hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,80 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        # Groups a bluebook's aggregates in the modules it declares (ADR 0163). `domain_module
+        # "Deliver" do … end` opens a block whose `aggregate` words are recorded under the module;
+        # the module changes no aggregate, it names the task each one belongs to. Policies, read
+        # models and process managers inside the block are the bluebook's own, as they are outside it.
+        module Modules
+          # Opens the module `name` and evaluates its body; a module of that name that an earlier
+          # file opened gains the aggregates this body declares.
+          #
+          # @param name [String] the module's own name, such as `"Deliver"`
+          # @yield the module body: its vision, aggregates, policies, read models and process managers
+          # @return [Array<Bluebook::Declaration::ModuleRow>] every membership declared so far
+          # @raise [Bluebook::DSL::Malformed] if a module opens inside another, or holds no aggregate
+          def domain_module(name, &)
+            refuse_nested_module!(name)
+            @open_module = name.to_s
+            instance_eval(&) if block_given?
+            refuse_empty_module!(@open_module)
+            module_rows
+          ensure
+            @open_module = nil
+          end
+
+          private
+
+          # One row per aggregate a module groups, in declaration order, each carrying its module's
+          # vision (empty when the module names none).
+          def module_rows
+            module_members.map do |name, aggregate|
+              Declaration::ModuleRow.new(name: name, vision: module_visions[name].to_s, aggregate: aggregate)
+            end
+          end
+
+          # Each `[module, aggregate]` pair declared so far, in declaration order.
+          def module_members = @module_members ||= []
+
+          # Each module's vision by its name, for the modules that declared one.
+          def module_visions = @module_visions ||= {}
+
+          # Records an aggregate under the open module, if one is open.
+          def note_in_open_module(name)
+            module_members << [@open_module, name.to_s] if @open_module
+          end
+
+          # Records the open module's vision.
+          def module_vision(value)
+            held = module_visions[@open_module]
+            raise Malformed, "domain_module #{@open_module.inspect} declares two visions" if held && held != value
+
+            module_visions[@open_module] = value
+          end
+
+          # Refuses a bluebook-wide word written inside a module block.
+          def bluebook_wide!(word)
+            return unless @open_module
+
+            raise Malformed, "#{word} describes the whole bluebook, so it cannot sit inside " \
+                             "domain_module #{@open_module.inspect}"
+          end
+
+          def refuse_nested_module!(name)
+            return unless @open_module
+
+            raise Malformed, "domain_module #{name.inspect} sits inside domain_module " \
+                             "#{@open_module.inspect}; modules do not nest"
+          end
+
+          def refuse_empty_module!(name)
+            return if module_members.any? { |held, _| held == name }
+
+            raise Malformed, "domain_module #{name.inspect} holds no aggregate"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,57 @@ module Hecks
           module CorrelationKeys
             private
 
+            # A bare name (`correlates_by Message`) naming an aggregate of this bluebook means
+            # that aggregate's identity, `"Message.id"`. Any other bare name is refused here,
+            # with the message the builder used to give. Runs before the other correlation
+            # checks, so they only ever see the dotted form.
+            def resolve_bare_correlation_keys!(bluebook)
+              bluebook.process_managers.each do |process_manager|
+                key = process_manager.correlates_by.to_s
+                next if bare_correlation_key?(key)
+
+                resolve_bare_correlation_key!(bluebook, process_manager, key)
+              end
+            end
+
+            def bare_correlation_key?(key)
+              key.empty? || key.include?(".")
+            end
+
+            def resolve_bare_correlation_key!(bluebook, process_manager, key)
+              aggregate = find_correlated_aggregate(bluebook, key)
+              unless aggregate
+                raise ProcessManagerBuilder::InvalidProcessManager,
+                      bare_correlation_message(process_manager.name, key)
+              end
+
+              path = identity_path(process_manager, aggregate)
+              process_manager.correlate_by!("#{aggregate.name}.#{path}")
+            end
+
+            # The refusal for a bare name that does not name an aggregate of the bluebook.
+            def bare_correlation_message(name, key)
+              "#{name} correlates_by #{key}, which names a whole field rather than one of its scalars " \
+                "— say which one, e.g. #{key}.value (or name an aggregate of this bluebook, " \
+                "which correlates by its identity)"
+            end
+
+            def find_correlated_aggregate(bluebook, key)
+              bluebook.aggregates.find { |candidate| candidate.name.to_s == Naming.demodulise(key) }
+            end
+
+            # The one field an aggregate is correlated by: its identity, or `id` when it declares none.
+            # A value-object identity drops its trailing `.value`, so `Thing` reads as `Thing.id`.
+            def identity_path(process_manager, aggregate)
+              paths = aggregate.identity_paths.map(&:to_s)
+              return "id" if paths.empty?
+              return paths.first.delete_suffix(".value") if paths.one?
+
+              raise ProcessManagerBuilder::InvalidProcessManager,
+                    "#{process_manager.name} correlates_by #{aggregate.name}, but #{aggregate.name} has a " \
+                    "composite identity — name the one field, e.g. #{aggregate.name}.#{paths.first}"
+            end
+
             # `correlates_by` must land on a scalar: the dotted path is walked against each
             # command that emits an event the process manager reacts to. A command lacking the
             # first segment is skipped, since correlation has fallback tiers

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

@@ -35,6 +35,7 @@ module Hecks
           # @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,6 +1,8 @@
 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
@@ -10,6 +12,8 @@ module Hecks
         GRAMMAR_CONTEXT = "Bluebook".freeze
 
         include WordGate
+        include Modules
+        include Metadata
         extend Validation
 
         attr_reader :classification
@@ -56,23 +60,11 @@ module Hecks
         # @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 bluebook's earlier name, so the storage layer recognizes its history
-        # under it instead of minting a new lineage — a bluebook's identity can change.
-        #
-        # @param value [String, Symbol] the bluebook'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 bluebook's constants install under instead of its own name,
-        # such as `namespace "Hecks::Domain"` for a bluebook 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 bluebook's sub-language extends (ADR 0026).
         # Variadic and accumulates across calls, like `identified_by`/`group_by`.
         #
@@ -82,7 +74,10 @@ module Hecks
         # @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 bluebook answers for other domains, one row per key —
         # checked once the bluebook is whole, since verbs may be declared later in the file.
@@ -94,6 +89,7 @@ module Hecks
         #   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 " \
                              "bluebook's commands and queries answer it"
@@ -103,22 +99,6 @@ module Hecks
           (@provides ||= []).concat(rows)
         end
 
-        # Classifies this bluebook as core to the framework, rather than a domain built on it.
-        #
-        # @return [Symbol] `:core`
-        def core       = @classification = :core
-
-        # Classifies this bluebook as a supporting piece of the framework, rather than a domain
-        # built on it.
-        #
-        # @return [Symbol] `:supporting`
-        def supporting = @classification = :supporting
-
-        # Classifies this bluebook as generic infrastructure, rather than a domain built on it.
-        #
-        # @return [Symbol] `:generic`
-        def generic    = @classification = :generic
-
         # Declares an aggregate belonging to this bluebook. `@bluebook_named_givens` is
         # threaded into it — see `AggregateBuilder#given` for the sharing this enables.
         #
@@ -126,15 +106,18 @@ module Hecks
         # 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, &)
+        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, &)
+                                                      bluebook_entity_pending_givens: @bluebook_entity_pending_givens,
+                                                &Kinds.wrap(name, kind, &body))
         end
 
         # Declares a read model belonging to this bluebook.
@@ -257,7 +240,7 @@ module Hecks
           { 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,
@@ -36,8 +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,
@@ -62,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,
@@ -98,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.rb

@@ -1,5 +1,6 @@
 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"
@@ -22,6 +23,7 @@ module Hecks
         include RuleReference
         include WordGate
         include NeedWord
+        include AudienceWord
         include ImplicitAttributes
         include Operands
         include FoldedSets
@@ -82,6 +84,14 @@ module Hecks
         # @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:`).
         #
@@ -203,13 +213,13 @@ module Hecks
         end
 
         def declared_rules
-          { name: @name, role: @role, roles: @roles || [], 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, idempotent: @idempotent || false }
+            provenance: @provenance, idempotent: @idempotent || false, mints_era: @mints_era || false }
         end
       end
     end

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

@@ -51,7 +51,6 @@ module Hecks
 
         # `has_many_impl`/`has_one_impl` are DSL keywords (`has_many`/`has_one` in a bluebook),
         # not real predicates, so Naming/PredicatePrefix does not apply here.
-        # rubocop:disable Naming/PredicatePrefix
         # Declares a list-typed relationship to another entity, referenced by its plural name.
         def has_many_impl(type, as: nil, **options)
           unless options.empty?
@@ -69,7 +68,6 @@ module Hecks
           target = Naming.demodulise(type)
           relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym, optional: optional)
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         # Declares a single-valued relationship to the entity that owns this one.
         def belongs_to_impl(type, as: nil, optional: false)

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

@@ -10,6 +10,9 @@ module Hecks
 
         COERCE_BY_KIND = { "text" => :to_s, "symbol" => :to_sym }.freeze
 
+        # The arguments of one word call: its positional arguments, its keyword arguments, and its block.
+        Invocation = Struct.new(:args, :kwargs, :block)
+
         # Not derivable from `fills:` (these rows all carry `fills: ""`) — the append target
         # for each opens-block word must be named here explicitly.
         SAFE_OPENS_BLOCK = {
@@ -31,13 +34,12 @@ module Hecks
 
         # Executes a table-admitted word via the shape `shape_for` found for it, or returns
         # NOT_HANDLED so the caller can fall back to its own "not yet implemented" refusal.
-        # The seven-argument form is the entry point `WordGate` and the dispatch specs call.
-        # rubocop:disable-next Metrics/ParameterLists
-        def try(builder, context, word, args, kwargs, block, rows)
+        # The call's arguments travel together as an `Invocation`, which keeps the signature short.
+        def try(builder, context, word, invocation, rows)
           shape = shape_for(context, word, rows)
           return NOT_HANDLED unless shape
 
-          run_shape(shape, builder, args, kwargs, block)
+          run_shape(shape, builder, invocation.args, invocation.kwargs, invocation.block)
         end
 
         # Runs the dispatcher the shape's kind names.

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

@@ -0,0 +1,53 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The aggregate kinds: `aggregate "GateRun", kind: "Run"` evaluates the kind's own text,
+      # written in the bluebook's words, around the aggregate's body. A kind is data, the file
+      # `lib/hecks/language/kinds/<kind>.kind`, not code: `{Name}` in it stands for the aggregate's
+      # name and `{Stem}` for that name without the kind, and a `# body` line marks where the
+      # aggregate's own body is evaluated.
+      module Kinds
+        DIRECTORY = File.expand_path("../../language/kinds", __dir__).freeze
+        BODY_MARK = /^# body\n/
+
+        module_function
+
+        # The block an aggregate is built from: its own body, or, for a kind, that body inside the
+        # kind's text.
+        #
+        # @param name [String] the aggregate's name
+        # @param kind [String, nil] the kind written after `kind:`, if any
+        # @yield the aggregate's own body; may be omitted
+        # @return [Proc, nil] the block to evaluate on the aggregate's builder
+        # @raise [Malformed] if the kind has no file
+        def wrap(name, kind, &body)
+          return body unless kind
+
+          before, after = halves(kind, name)
+          file = path(kind)
+          proc do
+            instance_eval(before, file, 1)
+            instance_eval(&body) if body
+            instance_eval(after, file, before.lines.size + 2)
+          end
+        end
+
+        # @return [Array(String, String)] the kind's text, names filled in, split at the body
+        def halves(kind, name)
+          before, after = File.read(path(kind)).split(BODY_MARK, 2)
+          [before, after].map { |text| fill(text, name, kind) }
+        rescue Errno::ENOENT
+          raise Malformed, "#{name} declares kind #{kind.inspect}, which has no file at #{path(kind)}"
+        end
+
+        # @return [String] the kind's text with `{Name}` and `{Stem}` replaced
+        def fill(text, name, kind)
+          text.gsub("{Name}", name.to_s).gsub("{Stem}", name.to_s.delete_suffix(kind.to_s))
+        end
+
+        # @return [String] the file that holds a kind
+        def path(kind) = File.join(DIRECTORY, "#{kind.to_s.downcase}.kind")
+      end
+    end
+  end
+end

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

@@ -25,6 +25,7 @@ module Hecks
           @owner     = owner
           @direction = direction
           @emits     = []
+          @handles   = []
         end
 
         # Refuses `reference_to` inside an operation body; a port operation has no self-reference
@@ -47,6 +48,12 @@ module Hecks
         # Names one event an inbound operation records once the external fact has arrived.
         def emits(event_name) = @emits << event_name.to_s
 
+        # Names one value of a command this operation handles, e.g. `handles "Build.build!",
+        # value: "wasm"`. Recorded in the IR only; nothing routes on it yet.
+        def handles_impl(command, value:)
+          @handles << { command: command.to_s, value: value.to_s }
+        end
+
         # `answers`/`refuses`, the two halves of an `asks` — separate words rather than two
         # `emits` so a reader can tell what came back from what the outside refused, without
         # reading the adapter.
@@ -64,7 +71,8 @@ module Hecks
 
           PortOperation.new(
             name: @name, attributes: attributes, emits: @emits,
-            direction: @direction, answers: @answers, refuses: @refuses, to: @to
+            direction: @direction, answers: @answers, refuses: @refuses, to: @to,
+            handles: @handles
           )
         end
 
@@ -116,7 +124,6 @@ module Hecks
 
         # Evaluates one operation block against a fresh builder and returns what it built;
         # `private` above doesn't reach this singleton method, since `.build` is the real entry.
-        # rubocop:disable-next Lint/IneffectiveAccessModifier
         def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
           builder = new(name, to: to, owner: owner, direction: direction)
           builder.instance_eval(&block) if block

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

@@ -17,6 +17,15 @@ module Hecks
           @handlers = []
         end
 
+        # Records the key that ties one instance's events together. A dotted path or symbol is
+        # kept as written; a bare aggregate name (`correlates_by Message`) is kept as its bare
+        # name, which `BluebookBuilder` resolves to `"Message.<identity>"` once every aggregate
+        # is known.
+        #
+        # @param key [Symbol, String, Module] the dotted path, or a bare aggregate name
+        # @return [void]
+        def correlates_by_impl(key) = @correlates_by = key
+
         # Records the event that begins a fresh instance of this process manager.
         #
         # `starts_on Transfer::TransferRequested`: a bare constant, stored as the bare event
@@ -35,9 +44,14 @@ module Hecks
         # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
         #   `ScopedConstant` module `ConstShim` resolves) or quoted text
         # @return [void]
-        def ends_on_impl(event_ref)
-          @ends_on = Naming.event_name_ref(event_ref)
-        end
+        def ends_on_impl(event_ref) = (@endings ||= []) << Naming.event_name_ref(event_ref)
+
+        # Records the command that resumes one stage, written `stage=command`, as the stage
+        # map a resume reads. The runtime does not read it yet.
+        #
+        # @param entry [String] one `stage=command` pair, for example `"gated=GateRun.Gate"`
+        # @return [void]
+        def resumes_impl(entry) = (@resumes ||= []) << entry.to_s
 
         # Records one leg of the state machine: the event that takes it, the state(s) it
         # applies from, and the dispatches (with optional compensations) it fires.
@@ -81,7 +95,8 @@ module Hecks
             name:          @name,
             correlates_by: @correlates_by,
             starts_on:     @starts_on,
-            ends_on:       @ends_on,
+            ends_on:       @endings&.first,
+            endings: @endings || [], resumes: @resumes || [],
             states:        derived_states,
             handlers:      @handlers
           )
@@ -148,19 +163,14 @@ module Hecks
           refuse_ambiguous_legs!
         end
 
+        # A bare name is not checked here: it may name an aggregate, which only the bluebook
+        # can see. `BluebookBuilder` resolves it to `"<Aggregate>.<identity>"`, or refuses it
+        # with `bare_correlation_message`. A dotted path is a scalar by its spelling.
         def refuse_bad_correlation!
-          unless @correlates_by
-            raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
-                                         "nothing would tie its events to one instance"
-          end
-
-          # Names a scalar (`:"end_to_end.value"`), never a whole field or value object.
-          # A syntactic check: the dotted spelling leaves no question about the key's type.
-          return if @correlates_by.to_s.include?(".")
+          return if @correlates_by
 
-          raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
-                                       "field rather than one of its scalars — say which one, e.g. " \
-                                       "#{@correlates_by}.value"
+          raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
+                                       "nothing would tie its events to one instance"
         end
 
         # A leg is selected by (event, current state), so two legs on the same pair would

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

@@ -121,6 +121,20 @@ module Hecks
         # `method_missing`/`respond_to_missing?` (via the included `WordGate`) give a
         # table-driven refusal naming the legal words, rather than a hand-typed list.
 
+        # ADR 0166: writes rows into `into` from this aggregate's rows, keyed by `keyed_by`.
+        #
+        # @param into [String, Symbol] the aggregate that receives the rows
+        # @param keyed_by [Symbol] the field both aggregates carry, which the target identifies by
+        # @param fields [Array<Symbol>] the fields copied into the target
+        # @raise [Bluebook::DSL::Malformed] if any of the three is missing or empty
+        def split_impl(into: nil, keyed_by: nil, fields: nil)
+          raise Malformed, "a split needs a target aggregate (into:)" if into.to_s.empty?
+          raise Malformed, "a split needs a key field (keyed_by:)" if keyed_by.to_s.empty?
+          raise Malformed, "a split needs at least one field (fields:)" if Array(fields).empty?
+
+          @splits << TranslationSplit.new(into.to_s, keyed_by.to_sym, Array(fields).map(&:to_sym))
+        end
+
         # Assembles the declared rules into a `TranslationAggregate`.
         #
         # @return [Bluebook::TranslationAggregate] the built per-aggregate translation
@@ -128,7 +142,7 @@ module Hecks
           TranslationAggregate.new(
             name: @name, was: @was, renames: @renames, moves: @moves, converts: @converts,
             drops: @drops, retypes: @retypes, derives: @derives, rekeys: @rekeys,
-            backfills: @backfills
+            backfills: @backfills, splits: @splits
           )
         end
 
@@ -142,6 +156,7 @@ module Hecks
           @retypes   = []
           @derives   = []
           @rekeys    = []
+          @splits    = []
           @backfills = []
         end
 

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

@@ -72,7 +72,7 @@ module Hecks
 
           refuse_unadmitted_word!(keywords, context, word) if admitted.empty?
 
-          dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
+          dispatched = GenericDispatch.try(self, context, word.to_s, GenericDispatch::Invocation.new(args, kwargs, block), rows)
           return dispatched unless dispatched.equal?(GenericDispatch::NOT_HANDLED)
 
           raise Malformed,

data/lib/hecks/bluebook/dsl.rb

@@ -25,6 +25,7 @@ require_relative "dsl/attribute_collector"
 require_relative "dsl/identity_declaration"
 require_relative "dsl/rule_reference"
 require_relative "dsl/word_gate"
+require_relative "dsl/kinds"
 require_relative "dsl/value_object_builder"
 require_relative "dsl/command_builder"
 require_relative "dsl/lifecycle_builder"

data/lib/hecks/bluebook/meta_validator/judge/identity.rb

@@ -17,14 +17,19 @@ module Hecks
             { value: text.to_s }
           end
 
-          # A reference argument is passed as the bare id it names; every
-          # other field is wrapped as a one-field value object instead.
+          # A reference argument is passed as the bare id it names; a list argument is passed
+          # as one value per item; every other field is wrapped as a one-field value object.
           def carried(plan, verb, argument, value)
-            return v(value) unless plan && verb && plan.references?(verb, argument)
+            return value if reference?(plan, verb, argument)
+            return value.map { |item| v(item) } if list?(plan, verb, argument, value)
 
-            value
+            v(value)
           end
 
+          def reference?(plan, verb, argument) = !!(plan && verb && plan.references?(verb, argument))
+
+          def list?(plan, verb, argument, value) = value.is_a?(Array) && !!(plan && verb && plan.list?(verb, argument))
+
           # A record's id is its declared identity, joined the same way the
           # runtime joins it, so there is exactly one way to name a thing.
           # Each part comes from the parent link, the walk index