hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/references.rb

@@ -3,18 +3,18 @@ module Hecks
     module DSL
       class BluebookBuilder
         module Validation
-          # Checks of how a chapter's aggregates point at each other: the chapter's own namespace,
+          # Checks of how a bluebook's aggregates point at each other: the bluebook's own namespace,
           # entity commands that root on themselves, and reference rings.
           module References
             private
 
-            # A chapter's constants install under its name, or its `namespace`; landing in the
+            # A bluebook's constants install under its name, or its `namespace`; landing in the
             # gem's own `Hecks` module would shadow the gem's modules (ADR 0080), so it refuses.
             def validate_not_the_gem_module!(bluebook)
               return unless (bluebook.namespace || bluebook.name) == "Hecks"
 
               raise Malformed, "#{bluebook.name}'s constants would install in the gem's own Hecks module — " \
-                               "declare a namespace, such as namespace \"Hecks::Domain\", or rename the chapter"
+                               "declare a namespace, such as namespace \"Hecks::Domain\", or rename the bluebook"
             end
 
             # Refuses an entity command that names its own entity as its root.
@@ -41,8 +41,8 @@ module Hecks
             end
 
             # A reference ring means no aggregate in it is a consistency boundary. Checked at
-            # chapter level because seeing a cycle needs every end declared (ADR 0025). Catches
-            # any ring length; self-reference stays legal, and a cross-chapter target is a
+            # bluebook level because seeing a cycle needs every end declared (ADR 0025). Catches
+            # any ring length; self-reference stays legal, and a cross-bluebook target is a
             # dangling name, not an edge.
             def validate_no_bidirectional_references!(aggregates)
               cycle = find_reference_cycle(reference_edges(aggregates))
@@ -95,7 +95,7 @@ module Hecks
 
             def first_cycle_through(targets, edges, state, path)
               targets.each do |target|
-                # a name this chapter never declares is dangling, not an edge
+                # a name this bluebook never declares is dangling, not an edge
                 next unless edges.key?(target)
 
                 found = reference_cycle_from(target, edges, state, path)

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/with_projections.rb

@@ -6,7 +6,7 @@ module Hecks
           # Checks `with:` projections of policies and saga legs against the source event's shape
           # and the target command's fields.
           module WithProjections
-            # What every `with:` check shares: the chapter's commands by "Owner.Command", its
+            # What every `with:` check shares: the bluebook's commands by "Owner.Command", its
             # aggregates, and the sagas' correlation heads.
             WithContext = Struct.new(:lookup, :aggregates, :correlation_heads)
             # One `with:` to check: the command it targets, the event it reads from, the spec
@@ -21,9 +21,9 @@ module Hecks
             private
 
             # Checks `with:` projections against the source event's shape and the target's fields.
-            # Same-chapter only: an unresolvable cross-chapter source or target is skipped.
+            # Same-bluebook only: an unresolvable cross-bluebook source or target is skipped.
             # A for_each policy's source is the event plus a query row; the row's names are known
-            # only when the query's aggregate is in this chapter, otherwise only the target is
+            # only when the query's aggregate is in this bluebook, otherwise only the target is
             # checked.
             def validate_with_projections!(policies, process_managers, aggregates)
               context = WithContext.new(command_lookup(aggregates), aggregates, correlation_heads(process_managers))
@@ -73,10 +73,10 @@ module Hecks
             def readable_sources(spec, aggregates)
               pm = spec.process_manager
               event_name = spec.event_name
-              # A policy's source also carries the emitter's identity
-              # (`PolicyInterpreter#emitter_identity`); a saga leg's source
+              # A policy's source also carries the emitter's identity, under each head and as `:id`
+              # (`PolicyInterpreter#emitter_identity`, `#emitter_id`); a saga leg's source
               # (`SagaInterpreter#dispatch_args`) merges no such thing.
-              identity = pm.nil? && event_name ? event_identity_heads_for(event_name, aggregates) : []
+              identity = pm.nil? && event_name ? [*event_identity_heads_for(event_name, aggregates), :id] : []
               shapes = [event_name && event_shape_for(event_name, aggregates),
                         pm && event_shape_for(pm.starts_on, aggregates)].compact
               Readable.new(pm&.correlates_by && pm.correlation_head, identity, shapes, spec.row_names.to_a)

data/lib/hecks/bluebook/dsl/bluebook_builder/validation.rb

@@ -12,7 +12,7 @@ module Hecks
   module Bluebook
     module DSL
       class BluebookBuilder
-        # Whole-chapter, cross-aggregate checks that `#build` runs once a chapter is assembled.
+        # Whole-bluebook, cross-aggregate checks that `#build` runs once a bluebook is assembled.
         # Extended onto BluebookBuilder: pure functions of their arguments, no builder state.
         # Each family of checks lives in its own module under `validation/`.
         module Validation
@@ -26,15 +26,16 @@ module Hecks
           include ComputedSources
           include CorrelationKeys
 
-          # Runs every whole-chapter check against one assembled chapter.
+          # Runs every whole-bluebook check against one assembled bluebook.
           # Public so `MetaValidator.judge_deferred!` can call it with no builder instance.
           #
-          # @param bluebook [Bluebook::Chapter] the assembled chapter to validate
+          # @param bluebook [Bluebook::Declaration] the assembled bluebook to validate
           # @return [void]
           # @raise [Bluebook::DSL::Malformed] if any check finds a violation
           # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a
           #   `correlates_by` resolves to something other than a scalar field
           def validate_assembled!(bluebook)
+            resolve_bare_correlation_keys!(bluebook)
             validate_not_the_gem_module!(bluebook)
             validate_declarations!(bluebook)
             validate_owner_stamped!(bluebook)

data/lib/hecks/bluebook/dsl/bluebook_builder.rb

@@ -1,21 +1,25 @@
 require_relative "word_gate"
 require_relative "bluebook_builder/validation"
 require_relative "bluebook_builder/pending_givens"
+require_relative "bluebook_builder/modules"
+require_relative "bluebook_builder/metadata"
 module Hecks
   module Bluebook
     module DSL
       # The `Hecks.bluebook "Name" do ... end` receiver, collecting every aggregate,
-      # read model, policy and process manager a chapter declares.
+      # read model, policy and process manager a bluebook declares.
       class BluebookBuilder
         GRAMMAR_CONTEXT = "Bluebook".freeze
 
         include WordGate
+        include Modules
+        include Metadata
         extend Validation
 
         attr_reader :classification
 
-        # @param name [String] the chapter's declared name
-        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
+        # @param name [String] the bluebook's declared name
+        # @param version [String, nil] the bluebook's pinned version, or nil for unversioned
         def initialize(name, version: nil)
           @name       = name
           @version    = version
@@ -23,23 +27,23 @@ module Hecks
           @read_models      = []
           @policies         = []
           @process_managers = []
-          # The root of the chapter-wide given pool, one level wider than
+          # The root of the bluebook-wide given pool, one level wider than
           # `AggregateBuilder`'s `@entity_named_givens` (S10). See `#given` for
           # what this closes.
-          @chapter_named_givens = {}
-          # Every bare chapter-given reference left unresolved so far, threaded into
-          # every aggregate like `@chapter_named_givens`. See
-          # `AggregateBuilder#pending_chapter_given` for what queues here.
-          @chapter_pending_givens = []
-          # One level wider still — the chapter-wide, entity-scoped pool, the piece
-          # analogue of `@chapter_named_givens`. See `EntityBuilder#given_impl` and
-          # docs/implemented/resolution-rules/chapter-entity-given.md for the algorithm.
-          @chapter_entity_named_givens   = {}
-          @chapter_entity_pending_givens = []
+          @bluebook_named_givens = {}
+          # Every bare bluebook-given reference left unresolved so far, threaded into
+          # every aggregate like `@bluebook_named_givens`. See
+          # `AggregateBuilder#pending_bluebook_given` for what queues here.
+          @bluebook_pending_givens = []
+          # One level wider still — the bluebook-wide, entity-scoped pool, the piece
+          # analogue of `@bluebook_named_givens`. See `EntityBuilder#given_impl` and
+          # docs/implemented/resolution-rules/bluebook-entity-given.md for the algorithm.
+          @bluebook_entity_named_givens   = {}
+          @bluebook_entity_pending_givens = []
         end
 
-        # Chapter metadata belongs to the composed builder, not whichever file sorts
-        # first; two different versions for one chapter is a real contradiction.
+        # Bluebook metadata belongs to the composed builder, not whichever file sorts
+        # first; two different versions for one bluebook is a real contradiction.
         def adopt_version(version)
           return if version.nil?
           if @version && @version.to_s != version.to_s
@@ -51,93 +55,72 @@ module Hecks
         end
         private :adopt_version
 
-        # Records the chapter's vision statement.
+        # Records the bluebook's vision statement.
         #
         # @param value [String] the vision text, as given to `vision "..."`
         # @return [void]
         def vision(value)
+          return module_vision(value) if @open_module
+
           @vision = value
         end
 
-        # Records the chapter's earlier name, so the storage layer recognizes its history
-        # under it instead of minting a new lineage — a chapter's identity can change.
-        #
-        # @param value [String, Symbol] the chapter's earlier name
-        # @return [String] `value`, stringified, as stored
-        def formerly_known_as(value) = @formerly_known_as = value.to_s
-
-        # Names the Ruby module the chapter's constants install under instead of its own name,
-        # such as `namespace "Hecks::Domain"` for a chapter that would otherwise collide.
-        #
-        # @param value [String] a constant path, such as `"Hecks::Domain"`
-        # @return [String] `value`, stringified, as stored
-        def namespace(value) = @namespace = value.to_s
-
-        # Names a core grammar context this chapter's sub-language extends (ADR 0026).
+        # Names a core grammar context this bluebook's sub-language extends (ADR 0026).
         # Variadic and accumulates across calls, like `identified_by`/`group_by`.
         #
         # Reached through `calls: "attaches_to_impl"`, not bootstrap-reachable — only
-        # sub-language chapters like Paging call it, never a core chapter.
+        # sub-language bluebooks like Paging call it, never a core bluebook.
         #
         # @param contexts [Array<String>] one or more core grammar context names, such as
         #   `"Query"`/`"ReadModel"`
         # @return [Array<String>] every context named so far, this call's included
-        def attaches_to_impl(*contexts) = (@attaches_to ||= []).concat(contexts.map(&:to_s))
+        def attaches_to_impl(*contexts)
+          bluebook_wide!(:attaches_to)
+          (@attaches_to ||= []).concat(contexts.map(&:to_s))
+        end
 
-        # Records a capability this chapter answers for other domains, one row per key —
-        # checked once the chapter is whole, since verbs may be declared later in the file.
+        # Records a capability this bluebook answers for other domains, one row per key —
+        # checked once the bluebook is whole, since verbs may be declared later in the file.
         #
         # @param capability [String] the capability's own name, such as `"authorization"`
         # @param verbs [Hash{Symbol => String}] one command/query reference per capability
         #   key, e.g. `grant: "RoleAssignment.Assign"`
-        # @return [Array<Bluebook::Chapter::Provision>] every provision row declared so far,
+        # @return [Array<Bluebook::Declaration::Provision>] every provision row declared so far,
         #   this capability's included
         # @raise [Bluebook::DSL::Malformed] if `verbs` is empty
         def provides_impl(capability, **verbs)
+          bluebook_wide!(:provides)
           if verbs.empty?
             raise Malformed, "#{@name}'s provides #{capability.inspect} names no verb — say which of this " \
-                             "chapter's commands and queries answer it"
+                             "bluebook's commands and queries answer it"
           end
 
-          rows = verbs.map { |key, verb| Chapter::Provision.new(capability: capability.to_s, key: key.to_s, verb: verb.to_s) }
+          rows = verbs.map { |key, verb| Declaration::Provision.new(capability: capability.to_s, key: key.to_s, verb: verb.to_s) }
           (@provides ||= []).concat(rows)
         end
 
-        # Classifies this chapter as core to the framework, rather than a domain built on it.
-        #
-        # @return [Symbol] `:core`
-        def core       = @classification = :core
-
-        # Classifies this chapter as a supporting piece of the framework, rather than a domain
-        # built on it.
-        #
-        # @return [Symbol] `:supporting`
-        def supporting = @classification = :supporting
-
-        # Classifies this chapter as generic infrastructure, rather than a domain built on it.
-        #
-        # @return [Symbol] `:generic`
-        def generic    = @classification = :generic
-
-        # Declares an aggregate belonging to this chapter. `@chapter_named_givens` is
+        # Declares an aggregate belonging to this bluebook. `@bluebook_named_givens` is
         # threaded into it — see `AggregateBuilder#given` for the sharing this enables.
         #
-        # Bootstrap-reachable (every core chapter's top-level shape uses it), so also
+        # Bootstrap-reachable (every core bluebook's top-level shape uses it), so also
         # named in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
         #
         # @param name [String] the aggregate's own name
+        # @param kind [String, nil] the kind whose text the aggregate's body is evaluated within
         # @yield the aggregate body, evaluated against a new `AggregateBuilder`; may be omitted
         # @return [Array<Bluebook::Aggregate>] every aggregate declared so far, this one last
         # @raise [Bluebook::DSL::Malformed] if the aggregate's own body fails any check
         #   `AggregateBuilder#build` raises
-        def aggregate_impl(name, &)
-          @aggregates << AggregateBuilder.build(name, chapter_named_givens:          @chapter_named_givens,
-                                                      chapter_pending_givens:        @chapter_pending_givens,
-                                                      chapter_entity_named_givens:   @chapter_entity_named_givens,
-                                                      chapter_entity_pending_givens: @chapter_entity_pending_givens, &)
+        def aggregate_impl(name, kind: nil, &body)
+          note_in_open_module(name)
+          @aggregates << AggregateBuilder.build(name, bluebook_named_givens:          @bluebook_named_givens,
+                                                      bluebook_pending_givens:        @bluebook_pending_givens,
+                                                      bluebook_entity_named_givens:   @bluebook_entity_named_givens,
+                                                      bluebook_entity_pending_givens: @bluebook_entity_pending_givens,
+                                                &Kinds.wrap(name, kind, &body))
         end
 
-        # Declares a read model belonging to this chapter.
+        # Declares a read model belonging to this bluebook.
         #
         # @param name [String] the read model's own name
         # @yield the read model body, evaluated against a new `ReadModelBuilder`
@@ -146,8 +129,8 @@ module Hecks
         #   raises
         def read_model(name, &)
           # A read model gathers heads from several aggregates, so no single head
-          # declares it — the chapter does. Its owner is stamped in `build`, where
-          # the chapter namespace exists.
+          # declares it — the bluebook does. Its owner is stamped in `build`, where
+          # the bluebook namespace exists.
           @read_models << ReadModelBuilder.build(name, &)
         end
 
@@ -165,17 +148,17 @@ module Hecks
           raise Malformed, "report is gone — read_model is the word now"
         end
 
-        # Declares a policy belonging to this chapter.
+        # Declares a policy belonging to this bluebook.
         #
         # @param name [String] the policy's own name
         # @yield the policy body, evaluated against a new `PolicyBuilder`
-        # @return [Array<Bluebook::Policy>] every chapter-level policy declared so far,
+        # @return [Array<Bluebook::Policy>] every bluebook-level policy declared so far,
         #   this one last
         def policy(name, &)
           @policies << PolicyBuilder.build(name, &)
         end
 
-        # Declares a process manager (saga) belonging to this chapter.
+        # Declares a process manager (saga) belonging to this bluebook.
         #
         # @param name [String] the process manager's own name
         # @yield the process manager body, evaluated against a new `ProcessManagerBuilder`
@@ -185,30 +168,30 @@ module Hecks
           @process_managers << ProcessManagerBuilder.build(name, &)
         end
 
-        # Assembles this builder's accumulated declarations into a judged `Chapter`.
+        # Assembles this builder's accumulated declarations into a judged `Bluebook`.
         #
-        # @return [Bluebook::Chapter] the built chapter, judged by the language when not
-        #   deferring across a multi-file chapter
-        # @raise [Bluebook::DSL::Malformed] if a chapter-wide given reference cannot be
+        # @return [Bluebook::Declaration] the built bluebook, judged by the language when not
+        #   deferring across a multi-file bluebook
+        # @raise [Bluebook::DSL::Malformed] if a bluebook-wide given reference cannot be
         #   resolved, if cross-construct validation fails, or if the language's own
-        #   whole-document judgment refuses the chapter
+        #   whole-document judgment refuses the bluebook
         # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
         #   manager's own structural check fails
         def build
-          # The chapter is the top of the construct chain — its constructor stamps every
+          # The bluebook is the top of the construct chain — its constructor stamps every
           # aggregate and read model with itself as owner, so `hecks_fqn` resolves by
           # walking up to it.
-          bluebook = Bluebook::Chapter.new(**chapter_identity, **chapter_constructs)
+          bluebook = Bluebook::Declaration.new(**bluebook_identity, **bluebook_constructs)
 
-          # A bare chapter-given may still be pending if a file that would resolve it
+          # A bare bluebook-given may still be pending if a file that would resolve it
           # hasn't loaded yet; deferred to `MetaValidator.judge_deferred!`, before
           # `validate_assembled!`, so nothing downstream reads an unresolved placeholder.
-          resolve_pending_chapter_givens! unless MetaValidator.deferring?
-          resolve_pending_chapter_entity_givens! unless MetaValidator.deferring?
+          resolve_pending_bluebook_givens! unless MetaValidator.deferring?
+          resolve_pending_bluebook_entity_givens! unless MetaValidator.deferring?
 
-          # A chapter may span several files; a hop/projection/event can name a construct
+          # A bluebook may span several files; a hop/projection/event can name a construct
           # not yet loaded, so this is skipped while `MetaValidator.defer` loads the
-          # chapter's files and run once by `judge_deferred!` against the whole chapter.
+          # bluebook's files and run once by `judge_deferred!` against the whole bluebook.
           self.class.validate_assembled!(bluebook) unless MetaValidator.deferring?
 
           # The language judges the bluebook last, so the meta-domain sees a fully built
@@ -217,15 +200,15 @@ module Hecks
           MetaValidator.call(bluebook)
         end
 
-        # Builds a `Chapter` from a `Hecks.bluebook "Name" do ... end` block, reusing one open
-        # builder per chapter name so several files accumulate into it rather than replacing it.
+        # Builds a `Bluebook` from a `Hecks.bluebook "Name" do ... end` block, reusing one open
+        # builder per bluebook name so several files accumulate into it rather than replacing it.
         #
-        # @param name [String] the chapter's declared name
-        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
-        # @yield the chapter body; a bare constant resolves to a `ConstShim::ScopedConstant`
-        # @return [Bluebook::Chapter] the built, judged chapter
+        # @param name [String] the bluebook's declared name
+        # @param version [String, nil] the bluebook's pinned version, or nil for unversioned
+        # @yield the bluebook body; a bare constant resolves to a `ConstShim::ScopedConstant`
+        # @return [Bluebook::Declaration] the built, judged bluebook
         # @raise [Bluebook::DSL::Malformed] if `version` conflicts with an already-adopted
-        #   version, or the built chapter fails validation
+        #   version, or the built bluebook fails validation
         # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
         #   manager's structural check fails
         def self.build(name, version: nil, &block)
@@ -246,18 +229,18 @@ module Hecks
 
         private
 
-        # The chapter's own metadata.
-        def chapter_identity
+        # The bluebook's own metadata.
+        def bluebook_identity
           { name: @name, version: @version, vision: @vision, classification: @classification,
             formerly_known_as: @formerly_known_as, namespace: @namespace }
         end
 
-        # What the chapter declares: its constructs and the contexts and capabilities it names.
-        def chapter_constructs
+        # What the bluebook declares: its constructs and the contexts and capabilities it names.
+        def bluebook_constructs
           { aggregates: @aggregates, read_models: @read_models,
             policies: @aggregates.flat_map(&:policies) + @policies,
             process_managers: @process_managers,
-            attaches_to: @attaches_to || [], provides: @provides || [] }
+            attaches_to: @attaches_to || [], provides: @provides || [], modules: module_rows }
         end
       end
     end

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -15,6 +15,8 @@ module Hecks
         # [context, word] => the method a word's whole call forwards to.
         CALLS = {
           ["Aggregate", "provenance"] => :provenance_impl,
+          ["Aggregate", "formerly_known_as"] => :formerly_known_as_impl,
+          ["Aggregate", "created_by"] => :created_by_impl,
           ["Aggregate", "identified_by"] => :identified_by_impl,
           ["Aggregate", "reference_to"] => :reference_to_impl,
           ["Aggregate", "has_many"] => :has_many_impl,
@@ -28,6 +30,7 @@ module Hecks
           ["Aggregate", "attribute"] => :attribute_impl,
           ["Aggregate", "invariant"] => :invariant_impl,
           ["Aggregate", "given"] => :given_impl,
+          ["Aggregate", "acknowledges"] => :acknowledges_impl,
           ["Aggregate", "projects"] => :projects_impl,
           ["Lifecycle", "transition"] => :transition_impl,
           ["Lifecycle", "mark"] => :mark_impl,
@@ -35,7 +38,10 @@ module Hecks
           ["Bluebook", "provides"] => :provides_impl,
           ["Bluebook", "aggregate"] => :aggregate_impl,
           ["Command", "role"] => :role_impl,
+          ["Command", "audience"] => :audience_impl,
           ["Command", "provenance"] => :provenance_impl,
+          ["Command", "idempotent"] => :idempotent_impl,
+          ["Command", "mints_era"] => :mints_era_impl,
           ["Command", "reference_to"] => :reference_to_impl,
           ["Command", "given"] => :given_impl,
           ["Command", "sets"] => :sets_impl,
@@ -60,8 +66,10 @@ module Hecks
           ["Policy", "trigger"] => :trigger_impl,
           ["Policy", "ask"] => :ask_impl,
           ["Policy", "across"] => :across_impl,
+          ["ProcessManager", "correlates_by"] => :correlates_by_impl,
           ["ProcessManager", "starts_on"] => :starts_on_impl,
           ["ProcessManager", "ends_on"] => :ends_on_impl,
+          ["ProcessManager", "resumes"] => :resumes_impl,
           ["ProcessManager", "transition"] => :transition_impl,
           ["Handler", "dispatch"] => :dispatch_impl,
           ["Dispatch", "compensates"] => :compensates_impl,
@@ -96,8 +104,10 @@ module Hecks
           ["Hecksagon", "port"] => :port_impl,
           ["PortOperation", "reference_to"] => :reference_to_impl,
           ["PortOperation", "attribute"] => :attribute_impl,
+          ["PortOperation", "handles"] => :handles_impl,
           ["Translation", "aggregate"] => :aggregate_impl,
           ["TranslationAggregate", "rename"] => :rename_impl,
+          ["TranslationAggregate", "split"] => :split_impl,
           ["TranslationAggregate", "move"] => :move_impl,
           ["TranslationAggregate", "convert"] => :convert_impl,
           ["TranslationAggregate", "retype"] => :retype_impl,

data/lib/hecks/bluebook/dsl/command_builder/folded_sets.rb

@@ -0,0 +1,48 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class CommandBuilder
+        # `attribute :name, Type, sets: true`: the argument and the plain `sets :name` that a following
+        # line would record, at the same position among the command's mutations.
+        module FoldedSets
+          # Declares one argument and, with `sets: true`, the plain `sets` of the owner's field of the
+          # same name.
+          #
+          # @param name [Symbol] the argument's name
+          # @param type [Array] the type, as `attribute` takes it
+          # @param sets [Boolean] true to also record `sets name`
+          # @param options [Hash] the keywords `attribute` takes
+          # @return [void]
+          # @raise [Bluebook::DSL::Malformed] if `sets:` is anything but true
+          def attribute_impl(name, *type, sets: false, **)
+            super(name, *type, **)
+            return if sets == false
+
+            refuse_unreadable_sets_flag!(name, sets)
+            (@folded_sets ||= []) << name.to_sym
+            sets_impl(name)
+          end
+
+          private
+
+          def refuse_unreadable_sets_flag!(name, flag)
+            return if flag == true
+
+            raise Malformed, "#{@name}'s attribute :#{name} takes sets: true or no sets: at all, not #{flag.inspect}"
+          end
+
+          # Refuses an attribute that says `sets: true` where the owner has no field of that name.
+          def refuse_unowned_folded_sets!
+            missing = (@folded_sets || []).reject { |name| @owner_attributes.any? { |attr| attr.name == name } }
+            return if missing.empty?
+
+            raise Malformed,
+                  "#{@name}'s attribute#{"s" if missing.size > 1} #{missing.map { |name| ":#{name}" }.join(", ")} " \
+                  "say sets: true, but the owner declares no field of that name to set — " \
+                  "declare it on the owner, or drop sets: true"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -1,8 +1,10 @@
 require_relative "word_gate"
 require_relative "need_word"
+require_relative "audience_word"
 require_relative "command_builder/owner"
 require_relative "command_builder/rules"
 require_relative "command_builder/mutations"
+require_relative "command_builder/folded_sets"
 require_relative "command_builder/implicit_attributes"
 require_relative "command_builder/operands"
 module Hecks
@@ -13,12 +15,18 @@ module Hecks
       class CommandBuilder
         GRAMMAR_CONTEXT = "Command".freeze
 
+        # What a second `role` declaration is refused with; `%<name>s` is the command.
+        ROLE_TWICE = "%<name>s declares role twice — a command carries one responsibility; the second would " \
+                     "silently win and the first would still look declared. Name every role in one: role \"A\", \"B\"".freeze
+
         include AttributeCollector
         include RuleReference
         include WordGate
         include NeedWord
+        include AudienceWord
         include ImplicitAttributes
         include Operands
+        include FoldedSets
 
         # Sentinel for "this keyword was never passed" — distinct from Ruby's own
         # nil/false, so `to: false` doesn't get treated as absent.
@@ -42,20 +50,20 @@ module Hecks
           @from = normalize_from(from)
         end
 
-        # Sets the command's one responsibility role, refusing a second declaration.
+        # Sets the role that runs the command, or the several roles any one of which may,
+        # refusing a second declaration.
         #
-        # @param value [String, Symbol] the role's name
-        # @return [Object] `value` as stored
-        # @raise [Bluebook::DSL::Malformed] if a role is already declared
-        def role_impl(value)
-          if @role
-            raise Malformed,
-                  "#{@name} declares role twice — a command carries ONE " \
-                  "responsibility; the second would silently win and the " \
-                  "first would still look declared"
-          end
-
-          @role = value
+        # With several, `role` is the first and `roles` holds them all.
+        #
+        # @param values [Array<String, Symbol>] the role names
+        # @return [Object] the first role as stored
+        # @raise [Bluebook::DSL::Malformed] if a role is already declared, or one is named twice
+        def role_impl(*values)
+          raise Malformed, format(ROLE_TWICE, name: @name) if @role
+          raise Malformed, "#{@name} names a role twice in one role declaration" if values.map(&:to_s).uniq.size != values.size
+
+          @roles = values.map(&:to_s) if values.size > 1
+          @role = values.first
         end
 
         # Sets the human-readable description shown for this command.
@@ -70,6 +78,20 @@ module Hecks
         # @return [Object] `from` as stored
         def provenance_impl(from:) = @provenance = from
 
+        # Declares the command safe to deliver twice: it leaves the same state delivered once or
+        # many times, so a saga redrive may run it again when a crash left its outcome unknown.
+        #
+        # @return [true]
+        def idempotent_impl = @idempotent = true
+
+        # Declares that this command's own record may be written through a boot whose shape no era
+        # holds yet, so the command that mints the held era can persist its request. Every other
+        # write from such a boot stays refused.
+        #
+        # @param value [Boolean] `true` to allow the write; any other value declares nothing
+        # @return [Boolean] the flag as stored
+        def mints_era_impl(value) = @mints_era = value == true
+
         # Declares the aggregate this command acts on (with no `as:`), or a cross-reference to
         # another aggregate (with `as:`).
         #
@@ -125,6 +147,7 @@ module Hecks
         #   state source names an undeclared field, or a delegating command also declares its
         #   own mutations or events
         def build
+          refuse_unowned_folded_sets!
           resolve_implicit_attributes!
           refuse_duplicate_targets!
           refuse_undeclared_needs!
@@ -190,13 +213,13 @@ module Hecks
         end
 
         def declared_rules
-          { name: @name, role: @role, goal: @goal, attributes: attributes, givens: @givens,
-            ensures: @ensures, needs: @needs }
+          { name: @name, role: @role, roles: @roles || [], audience: @audience || [], goal: @goal,
+            attributes: attributes, givens: @givens, ensures: @ensures, needs: @needs }
         end
 
         def declared_effects
           { mutations: @mutations, emits: @emits, references: @references, from: @from,
-            provenance: @provenance }
+            provenance: @provenance, idempotent: @idempotent || false, mints_era: @mints_era || false }
         end
       end
     end