hecks 4.0.0 → 6.0.0

data/lib/hecks/bluebook/behaviour/{chapter.rb → declaration.rb}

@@ -3,15 +3,15 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # What a chapter does. The declared half is the roll-call of what a
+      # What a bluebook does. The declared half is the roll-call of what a
       # bluebook holds; these are the finders over it, plus `verbs`.
-      module Chapter
+      module Declaration
         include Owns
 
-        # Marks this chapter the root of the owner chain, attaches the ports
+        # Marks this bluebook the root of the owner chain, attaches the ports
         # table (filled later by a `.hecksagon`), and stamps ownership.
         #
-        # @return [Bluebook::Chapter] self
+        # @return [Bluebook::Declaration] self
         def settle
           @hecks_root    = true
           @ports         = []
@@ -33,43 +33,43 @@ module Hecks
         # @return [Bluebook::ReadModel, nil] the read model, or `nil` if none matches
         def read_model(named) = @read_models.find { |model| model.name == named.to_s || model.query_name == named.to_s }
 
-        # Finds a port declared at this chapter's root by name.
+        # Finds a port declared at this bluebook's root by name.
         #
         # @param named [String, Symbol] the port's declared name
         # @return [Bluebook::DomainPort, nil] the port, or `nil` if none is declared
         #   by that name
         def port(named)       = @ports_by_name[named.to_s]
 
-        # What this chapter declared it provides for one capability.
+        # What this bluebook declared it provides for one capability.
         #
         # @param capability [String, Symbol] the capability's name, such as
         #   `Bluebook::Capabilities::AUTHORIZATION`
         # @return [Hash{Symbol => String}, nil] each declared key mapped to its local verb,
-        #   or `nil` if this chapter declares no `provides` row for that capability
+        #   or `nil` if this bluebook declares no `provides` row for that capability
         def provision(capability)
           rows = @provides.select { |row| row.capability == capability.to_s }
           rows.empty? ? nil : rows.to_h { |row| [row.key.to_sym, row.verb] }
         end
 
-        # Says whether this chapter declares that it provides a capability.
+        # Says whether this bluebook declares that it provides a capability.
         #
         # @param capability [String, Symbol] the capability's name
-        # @return [Boolean] whether this chapter declares a `provides` row for that capability
+        # @return [Boolean] whether this bluebook declares a `provides` row for that capability
         def provides?(capability) = !provision(capability).nil?
 
-        # The declared verb for `key`, qualified with this chapter's own
+        # The declared verb for `key`, qualified with this bluebook's own
         # name — the spelling `Dispatcher#dispatch`/`#query` take.
         #
         # @param capability [String, Symbol] the capability's name
         # @param key [String, Symbol] the provided key to resolve
-        # @return [String, nil] the verb qualified as `"ChapterName::verb"`, or `nil` if this
-        #   chapter provides no such capability or key
+        # @return [String, nil] the verb qualified as `"BluebookName::verb"`, or `nil` if this
+        #   bluebook provides no such capability or key
         def provided_verb(capability, key)
           local = provision(capability)&.fetch(key.to_sym, nil)
           local && "#{name}::#{local}"
         end
 
-        # A port attaches after the chapter already exists, once its
+        # A port attaches after the bluebook already exists, once its
         # hecksagon is built — the same way an aggregate's own ports do.
         #
         # @param port [Bluebook::DomainPort] the operations-shaped port to attach
@@ -79,22 +79,22 @@ module Hecks
           @ports_by_name[port.name] = port
         end
 
-        # A translated reaction also attaches after the chapter already
+        # A translated reaction also attaches after the bluebook already
         # exists: which foreign domain's event it reacts to is a wiring
         # decision, not a fact the domain states about its own model.
         #
         # @param policy [Bluebook::Policy] the translated reaction to attach
-        # @return [Array<Bluebook::Policy>] this chapter's policies, with `policy` appended
+        # @return [Array<Bluebook::Policy>] this bluebook's policies, with `policy` appended
         def add_policy(policy)
           @policies << policy
         end
 
-        # Every dispatchable name this chapter answers to, spelled exactly
+        # Every dispatchable name this bluebook answers to, spelled exactly
         # as `Dispatcher#dispatch` takes it. Derived from the aggregates,
         # never declared, and recurses into entities since a command can be
         # nested arbitrarily deep.
         #
-        # @return [Array<String>] every command verb reachable on this chapter, spelled
+        # @return [Array<String>] every command verb reachable on this bluebook, spelled
         #   `"Domain::Aggregate.command"` or, nested, `"Domain::Aggregate.Entity.command"`
         def verbs
           @aggregates.flat_map { |agg| aggregate_verbs(agg) }

data/lib/hecks/bluebook/behaviour/domain_port.rb

@@ -26,7 +26,7 @@ module Hecks
         # @return [Bluebook::Attribute, nil] the reference-typed attribute targeting
         #   `owner_name`, or `nil` if this operation declares none
         def identity_attribute(owner_name)
-          @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
+          @attributes.find { |attribute| attribute.reference? && attribute.target_name == owner_name.to_s }
         end
 
         # Like `Command#addressing_key_for` without the self-addressing branch: the

data/lib/hecks/bluebook/behaviour/entity.rb

@@ -12,6 +12,7 @@ module Hecks
         include Identified
         include Indexed
         include Owns
+        include Stateful
 
         # The hook `absorb` calls once every declared field is assigned.
         #

data/lib/hecks/bluebook/behaviour/hecksagon.rb

@@ -25,8 +25,15 @@ module Hecks
           specific = @binds.select { |b| b.aggregate_name == aggregate_name.to_s && b.verb.to_s == verb.to_s }
           return specific if specific.any?
 
-          @binds.select { |b| b.aggregate.nil? && b.verb.to_s == verb.to_s }
+          default_binds(verb)
         end
+
+        # The domain-level defaults for `verb`: the binds declared at the hecksagon's root, with no
+        # aggregate, which every aggregate inherits unless it declares its own.
+        #
+        # @param verb [String, Symbol]
+        # @return [Array<Bluebook::Bind>]
+        def default_binds(verb) = @binds.select { |b| b.aggregate.nil? && b.verb.to_s == verb.to_s }
       end
 
       # Settings lookup for a world, with adapter-specific entries falling back to the verb's own.

data/lib/hecks/bluebook/behaviour/process_manager.rb

@@ -43,7 +43,10 @@ module Hecks
         # The payload field a triggering event's instances are correlated by.
         #
         # @return [Symbol] the part of `correlates_by` before the first `.`
-        def correlation_head = @correlates_by.to_s.split(".").first.to_sym
+        def correlation_head
+          head, = @correlates_by.to_s.split(".")
+          head.to_sym
+        end
 
         # The compensation half, read off the handler that answers `REFUSED`.
         #

data/lib/hecks/bluebook/behaviour/query.rb

@@ -9,6 +9,11 @@ module Hecks
         # @return [Bluebook::Attribute, nil] the attribute, or `nil` if none is declared
         #   by that name
         def attribute(named) = @attributes.find { |a| a.name == named.to_sym }
+
+        # The field this query orders its answers by.
+        #
+        # @return [String, Symbol, nil] the `order_by` field, or `nil` when the query sets no order
+        def order_by_field = order_by&.field
       end
     end
   end

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -77,7 +77,10 @@ module Hecks
         end
 
         # Filtering options scoped to one included aggregate head (ADR 0055).
-        FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
+        FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics) do
+          # A read model's head does not page by cursor (ADR 0130), so a head never carries one.
+          def cursor = nil
+        end
 
         # Scopes this read model's filtering options down to one included head.
         #

data/lib/hecks/bluebook/behaviour/traits.rb

@@ -62,6 +62,19 @@ module Hecks
         def query(named)     = @queries_by_name[named.to_s]
       end
 
+      # A construct that may declare a lifecycle: an aggregate or an entity.
+      module Stateful
+        # The field the lifecycle keeps its state in.
+        #
+        # @return [Symbol, String, nil] the state field, or `nil` when no lifecycle is declared
+        def lifecycle_field = lifecycle&.field
+
+        # The names of the lifecycle's marks, the named groups of its states.
+        #
+        # @return [Array<String>] each mark's name, or `[]` when no lifecycle is declared
+        def mark_names = lifecycle ? lifecycle.marks.keys : []
+      end
+
       # A construct that owns what it declares.
       #
       # Owner links are read lazily (hecks_fqn, Reference#resolve), so stamping when the

data/lib/hecks/bluebook/capabilities/attribute_values.rb

@@ -15,24 +15,25 @@ module Hecks
           seconds if seconds.is_a?(Integer) && seconds.positive?
         end
 
-        # The seconds a `:duration` verb ("Aggregate.attribute") resolves to in `chapter`.
+        # The seconds a `:duration` verb ("Aggregate.attribute") resolves to in `bluebook`.
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
         # @param verb [String] the entry, spelled "Aggregate.attribute"
         # @return [Integer, nil] the positive whole seconds, or `nil` when the verb names no such
         #   attribute or its default is not whole seconds
-        def duration_of(chapter, verb)
-          duration_seconds(attribute_default(chapter, verb))
+        def duration_of(declaration, verb)
+          duration_seconds(attribute_default(declaration, verb))
         end
 
-        # The `default:` of the attribute a verb ("Aggregate.attribute") names in `chapter`.
+        # The `default:` of the attribute a verb ("Aggregate.attribute") names in `bluebook`.
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
         # @param verb [String] the entry, spelled "Aggregate.attribute"
         # @return [Object, nil] that attribute's `default:`, or `nil` when there is none
-        def attribute_default(chapter, verb)
+        def attribute_default(declaration, verb)
           aggregate_name, attribute_name = verb.split(".", 2)
-          chapter.aggregate(aggregate_name)&.attributes&.find { |a| a.name.to_s == attribute_name }&.default
+          aggregate = declaration.aggregate(aggregate_name)
+          aggregate&.attributes&.find { |a| a.name.to_s == attribute_name }&.default
         end
 
         # A default's value: the bare value, or the `{ value: x }` fill of a one-field value object.
@@ -43,27 +44,27 @@ module Hecks
           default.is_a?(Hash) ? default.fetch(:value) { default["value"] } : default
         end
 
-        # The string a `:text` verb ("Aggregate.attribute") resolves to in `chapter`: the
+        # The string a `:text` verb ("Aggregate.attribute") resolves to in `bluebook`: the
         # attribute's `default:`, bare or as the `{ value: "..." }` fill of a one-field value
         # object (ADR 0099).
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
         # @param verb [String] the entry, spelled "Aggregate.attribute"
         # @return [String, nil] the non-empty text, or `nil` when the verb names no such attribute
         #   or its default is not text
-        def text_of(chapter, verb)
-          text = filled_value(attribute_default(chapter, verb))
+        def text_of(declaration, verb)
+          text = filled_value(attribute_default(declaration, verb))
           text if text.is_a?(String) && !text.empty?
         end
 
-        # The attribute name an `:attribute` verb ("Aggregate.attribute") resolves to in `chapter`.
+        # The attribute name an `:attribute` verb ("Aggregate.attribute") resolves to in `bluebook`.
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
         # @param verb [String] the entry, spelled "Aggregate.attribute"
         # @return [String, nil] the attribute's name, or `nil` when the aggregate lacks it
-        def attribute_of(chapter, verb)
+        def attribute_of(declaration, verb)
           aggregate_name, attribute_name = verb.split(".", 2)
-          found = chapter.aggregate(aggregate_name)&.attributes&.any? { |a| a.name.to_s == attribute_name }
+          found = declaration.aggregate(aggregate_name)&.attributes&.any? { |a| a.name.to_s == attribute_name }
           attribute_name if found
         end
       end

data/lib/hecks/bluebook/capabilities/package_declared.rb

@@ -0,0 +1,65 @@
+module Hecks
+  module Bluebook
+    module Capabilities
+      # A capability the language defines no contract for belongs to the package that provides it.
+      # Each of its `provides` keys names something the bluebook declares, and the kind of that
+      # target is read off what it names. Extended onto {Capabilities}, whose singleton methods
+      # these become.
+      module PackageDeclared
+        # Every kind a package-declared key may name: a command or query ("Aggregate.Name"), a
+        # port operation ("Aggregate.Port.Operation"), a lifecycle mark ("Aggregate.mark_name")
+        # or an attribute ("Aggregate.attribute").
+        KINDS = %i[command query port_operation mark attribute].freeze
+
+        # Every kind `verb` names in `bluebook`; more than one means the target is ambiguous.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
+        # @param verb [String] the key's target, spelled as one of `KINDS`
+        # @return [Array<Symbol>] the kinds it names, empty when it names nothing
+        def kinds_of(declaration, verb)
+          aggregate_name, member = verb.to_s.split(".", 2)
+          aggregate = declaration.aggregate(aggregate_name)
+          return [] unless aggregate && member
+          # The port is declared in the hecksagon, which attaches after the bluebook is built, so
+          # only the spelling is checkable here; `Registry#verify!` checks the operation.
+          return member.count(".") == 1 ? [:port_operation] : [] if member.include?(".")
+
+          member_kinds(aggregate, member)
+        end
+
+        # The value a package-declared key exports: the qualified verb of a command, query or port
+        # operation, the states of a lifecycle mark, or an attribute's name and `default:`.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the aggregate
+        # @param verb [String] the key's target
+        # @return [String, Array<String>, Hash{Symbol => Object}] what the reader is handed
+        # @raise [ArgumentError] when `verb` names nothing, or more than one kind, in `bluebook`
+        def resolved_value(declaration, verb)
+          kinds = kinds_of(declaration, verb)
+          raise ArgumentError, "#{declaration.name} declares no single target named #{verb.inspect}" unless kinds.one?
+
+          aggregate_name, member = verb.split(".", 2)
+          case kinds.first
+          when :mark then declaration.aggregate(aggregate_name).lifecycle.marked(member)
+          when :attribute then { attribute: member, default: filled_value(attribute_default(declaration, verb)) }
+          else "#{declaration.name}::#{verb}"
+          end
+        end
+
+        private
+
+        def member_kinds(aggregate, member)
+          member_names(aggregate).select { |_, names| names.include?(member) }.keys
+        end
+
+        # Every name an aggregate declares, by the kind of thing it names.
+        def member_names(aggregate)
+          { command:   aggregate.commands.map(&:hecks_name),
+            query:     aggregate.queries.map { |query| query.name.to_s },
+            mark:      aggregate.mark_names,
+            attribute: aggregate.attributes.map { |attribute| attribute.name.to_s } }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/capabilities.rb

@@ -1,11 +1,17 @@
 require_relative "capabilities/attribute_values"
+require_relative "capabilities/package_declared"
 
 module Hecks
   module Bluebook
-    # What a chapter may declare it provides — trusted in place of a literal
-    # chapter-name check by role checks, adapters and the fuzzer.
+    # What a bluebook may declare it provides — trusted in place of a literal
+    # bluebook-name check by role checks, adapters and the fuzzer.
+    #
+    # The language defines a contract only for the capabilities Hecks itself consumes. Any other
+    # `provides` name is the package's own: its keys are checked to name something the bluebook
+    # declares (`PackageDeclared`), and whoever reads the capability checks the keys it needs.
     module Capabilities
       extend AttributeValues
+      extend PackageDeclared
 
       AUTHORIZATION = "authorization".freeze
       # Who may sign in and with what role, resolved by declaration rather
@@ -14,61 +20,31 @@ module Hecks
       # A stable organizational identity, recognised by declaration rather
       # than the literal name "Identity".
       IDENTITY = "identity".freeze
-      # Guest newsletter signups, recognised by declaration rather than the
-      # literal chapter name "Newsletter".
-      NEWSLETTER = "newsletter".freeze
-      # Sending an issue to confirmed subscribers; kept separate from
-      # `NEWSLETTER` so a signup-only chapter declares nothing more.
-      NEWSLETTER_ISSUES = "newsletter_issues".freeze
-
-      # Taking a payment through an external processor, recognised by
-      # declaration rather than the literal name "Payments"; the two
-      # verdicts are port operations, not commands.
-      PAYMENTS = "payments".freeze
-
-      # Scheduling sessions and taking registrations, recognised by
-      # declaration rather than the literal aggregate names.
-      REGISTRATIONS = "registrations".freeze
-
-      # A business's connection to its payment processor, recognised by
-      # declaration rather than the literal name "PaymentConnection".
-      PAYMENT_CONNECTION = "payment_connection".freeze
-
-      # The checkout boundary in front of a payment processor: how long a
-      # signed webhook stays fresh and how long a session holds its seat,
-      # recognised by declaration rather than the literal chapter name.
-      CHECKOUT = "checkout".freeze
 
       # Marking a domain's attributes sensitive and reading the markings back, recognised by
-      # declaration rather than the literal chapter name "Privacy".
+      # declaration rather than the literal bluebook name "Privacy".
       PRIVACY = "privacy".freeze
 
       # A subject's key record, shredded to erase them, recognised by declaration rather than the
       # literal names "Privacy" and "SubjectKey".
       SUBJECT_KEYS = "subject_keys".freeze
 
-      # The kinds of contract entry a capability may name: `:command` and
-      # `:query` ("Aggregate.Name"), `:port_operation` ("Aggregate.Port.Operation")
-      # and `:mark` ("Aggregate.mark_name", the states of that aggregate's
-      # lifecycle mark) and `:duration` ("Aggregate.attribute", the whole-seconds
-      # `default:` of that attribute, ADR 0098). `:mark` and `:duration` entries are
-      # optional; every other entry is required.
-      #
-      # ADR 0099 adds two more optional kinds: `:text` ("Aggregate.attribute", the string
-      # `default:` of that attribute, a word the domain owns) and `:attribute`
-      # ("Aggregate.attribute", the attribute's own name, for the host to read a field by).
-      OPTIONAL_KINDS = %i[mark duration text attribute].freeze
-
+      # The contract of each capability the language defines: every key a `provides` row must
+      # name, and whether it names a command or a query ("Aggregate.Name").
       CONTRACTS = {
-        AUTHORIZATION      => {
+        AUTHORIZATION => {
           # every assignment an actor holds, current or historical
-          assignments: :query,
+          assignments:      :query,
+          # the assignments an actor holds right now: those that have not ended
+          live_assignments: :query,
           # the command that grants an actor a role
-          grant:       :command,
-          # every grant of one role acting as another
-          transitions: :query
+          grant:            :command,
+          # every grant of one role acting as another, current or historical
+          transitions:      :query,
+          # the grants of one role acting as another that have not ended
+          live_transitions: :query
         }.freeze,
-        MEMBERSHIP         => {
+        MEMBERSHIP    => {
           # recognize a person who may eventually sign in
           admit:  :command,
           # grant an admitted person a role (the access-grant half)
@@ -76,7 +52,7 @@ module Hecks
           # every admitted person, for the admin listing
           people: :query
         }.freeze,
-        IDENTITY           => {
+        IDENTITY      => {
           # mint a stable identity, independent of how it authenticated
           register: :command,
           # associate an (issuer, subject) pair with that identity
@@ -84,107 +60,31 @@ module Hecks
           # look up the identity an authenticated pair resolves to
           resolve:  :query
         }.freeze,
-        NEWSLETTER         => {
-          # a guest signs up; the aggregate it names is the subscriber
-          subscribe:             :command,
-          # attach a display name to an existing subscriber
-          add_name:              :command,
-          # a subscriber confirms their address from the emailed link
-          confirm:               :command,
-          # a subscriber leaves from the emailed link
-          unsubscribe:           :command,
-          # Optional: the subscriber states that await the emailed confirm
-          # link, spelled "Subscriber.awaiting_confirmation"
-          awaiting_confirmation: :mark,
-          # Optional: the subscriber states that receive each issue sent
-          receives_issues:       :mark,
-          # Optional: the subscriber states of someone who has left
-          left:                  :mark,
-          # Optional: how many seconds the emailed confirm link stays valid,
-          # spelled "Subscriber.confirm_window"
-          confirm_window:        :duration,
-          # Optional: how many seconds an emailed unsubscribe link stays valid
-          unsubscribe_window:    :duration
-        }.freeze,
-        NEWSLETTER_ISSUES  => {
-          # mark an issue sent; the issue aggregate is the one it names
-          send_issue:      :command,
-          # record one email handed to the mail provider; the delivery
-          # aggregate is the one it names
-          record_delivery: :command
-        }.freeze,
-        PAYMENTS           => {
-          # start a payment; the aggregate it names is the payment
-          initiate:     :command,
-          # the processor reports the money arrived
-          succeeded:    :port_operation,
-          # the processor reports the payment failed or expired
-          failed:       :port_operation,
-          # Optional: the lifecycle states of the payment that hold a seat,
-          # spelled "Payment.holds_seat" (Aggregate.mark_name); resolves to the
-          # states of that aggregate's lifecycle `mark :holds_seat`
-          holds_seat:   :mark,
-          # Optional: the failure reason a lapsed checkout hold records, spelled
-          # "Payment.lapse_reason" (the string `default:` of that attribute)
-          lapse_reason: :text
-        }.freeze,
-        REGISTRATIONS      => {
-          # schedule a session; the aggregate it names is the event
-          schedule:      :command,
-          # a guest asks for a place; the aggregate it names is the registration
-          request:       :command,
-          # Optional: the registration attribute that stamps when it was asked for,
-          # spelled "Registration.requested_at"
-          registered_at: :attribute,
-          # Optional: the registration states that give a seat back, spelled
-          # "Registration.frees_seat" (Aggregate.mark_name); resolves to the
-          # states of that aggregate's lifecycle `mark :frees_seat`
-          frees_seat:    :mark
-        }.freeze,
-        PAYMENT_CONNECTION => {
-          # link the processor account; the aggregate it names is the connection
-          connect:    :command,
-          # link a different processor account after a disconnect
-          reconnect:  :command,
-          # drop the link
-          disconnect: :command,
-          # pause the connection without dropping it
-          suspend:    :command,
-          # lift a pause
-          resume:     :command,
-          # switch taking payments on
-          enable:     :command,
-          # switch taking payments off
-          disable:    :command
-        }.freeze,
-        PRIVACY            => {
+        PRIVACY       => {
           # flag one attribute of a domain sensitive
           mark_sensitive: :command,
           # every marking of one domain, for masking a read
           markings_for:   :query
         }.freeze,
-        SUBJECT_KEYS       => {
+        SUBJECT_KEYS  => {
           # the key record of one subject, if any
           key_for: :query,
           # record the subject's key as destroyed
           shred:   :command
-        }.freeze,
-        CHECKOUT           => {
-          # Optional: how many seconds either side of now a signed webhook's
-          # timestamp may sit, spelled "WebhookReceipt.tolerance"
-          webhook_tolerance: :duration,
-          # Optional: how many seconds a session holds its seat
-          session_hold:      :duration
         }.freeze
       }.freeze
 
       # The keys a capability's `provides` must name.
       #
       # @param capability [String] a `CONTRACTS` key
-      # @return [Array<Symbol>] the keys whose kind is not optional
-      def self.required_keys(capability)
-        CONTRACTS.fetch(capability).reject { |_, kind| OPTIONAL_KINDS.include?(kind) }.keys
-      end
+      # @return [Array<Symbol>] every key of its contract
+      def self.required_keys(capability) = CONTRACTS.fetch(capability).keys
+
+      # Whether the language defines `capability`'s contract, rather than the package providing it.
+      #
+      # @param capability [String, Symbol] a capability's name
+      # @return [Boolean] whether `CONTRACTS` holds it
+      def self.language_defined?(capability) = CONTRACTS.key?(capability.to_s)
     end
   end
 end

data/lib/hecks/bluebook/command.rb

@@ -50,6 +50,8 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         role:       :role,
+        # Every role that may run the command, when more than one may; `role` is then the first.
+        roles:      -> { roles.size > 1 ? roles : Hecks::IR::OMIT },
         goal:       :goal,
         references: :references,
         attributes: many(:attributes),
@@ -60,31 +62,39 @@ module Hecks
         emits:      :emits,
         # The lifecycle state this command is admissible from: a guard, not a transition.
         from:       -> { from },
-        provenance: :provenance
+        provenance: :provenance,
+        # Safe to deliver twice; the saga redrive reads it for a dispatch left unsettled.
+        idempotent: -> { idempotent? }
       )
 
       # Every optional declared field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        role: nil, goal: nil, attributes: [], givens: [], ensures: [], needs: [],
-        mutations: [], emits: [], references: nil, from: nil, provenance: nil
+        role: nil, roles: [], goal: nil, attributes: [], givens: [], ensures: [], needs: [],
+        mutations: [], emits: [], references: nil, from: nil, provenance: nil, idempotent: false
       }.freeze
 
       class << self
         attr_reader :role, :goal, :attributes, :givens, :ensures, :needs, :mutations, :emits, :references,
-                    :from, :provenance
+                    :from, :provenance, :idempotent
+
+        # @return [Boolean] whether a second delivery leaves the state a first one did
+        def idempotent? = @idempotent ? true : false
+
+        # @return [Array<String>] every role that may run it when more than one may, else empty
+        def roles = @roles || []
 
         # Mints one command as its own anonymous subclass of the class `declare` is called on.
         #
         # @param name [String, Symbol] the command's declared name
-        # @param role [String, nil] the declared role text; `goal` is the goal text
+        # @param role [String, nil] the declared role; `roles` all of them when several may run it
         # @param attributes [Array<Bluebook::Attribute>] the declared arguments
         # @param givens [Array<Bluebook::Given>] the declared preconditions
         # @param ensures [Array<Bluebook::Given>] the postconditions; `needs` the facts it supplies
-        # @param mutations [Array<Bluebook::Mutation>] the state changes it applies
-        # @param emits [Array<String>] the event names it may emit
+        # @param mutations [Array<Bluebook::Mutation>] its state changes; `emits` the event names
         # @param references [String, Symbol, nil] the aggregate its `reference_to` addresses
         # @param from [String, Array<String>, nil] the lifecycle states it is admissible from
         # @param provenance [Object, nil] the declared canonical source, as written
+        # @param idempotent [Boolean] whether a second delivery changes nothing
         def declare(name:, **given)
           fields = KeywordFields.fill(given, FIELD_DEFAULTS)
           verb = Class.new(self)
@@ -104,6 +114,11 @@ module Hecks
           end
           settle
         end
+
+        # Every role that may run the command: its `roles` when several may, else its one `role`.
+        #
+        # @return [Array<String>] empty when the command declares no role
+        def role_set = roles.size > 1 ? roles : [role].compact.map(&:to_s)
       end
     end
   end