hecks 6.0.0 → 7.0.0

data/lib/hecks/bluebook/meta_validator/plan/category.rb

@@ -4,7 +4,6 @@ module Hecks
       class Plan
         # One append command: the verb, and the value-object-field -> argument map.
         # `:map` shadows Enumerable#map on purpose; spec/plan_spec.rb asserts on it.
-        # rubocop:disable-next Lint/StructNewOverride
         Append = Struct.new(:verb, :map, keyword_init: true)
 
         # One setting command. `targets` is target -> argument ; Lifecycle sets two
@@ -12,7 +11,7 @@ module Hecks
         Setter = Struct.new(:verb, :targets, keyword_init: true)
 
         Category = Struct.new(:name, :declare, :parent, :parent_key, :fields,
-                              :appends, :alternates, :setters, :sealers, :references,
+                              :appends, :alternates, :setters, :sealers, :references, :lists,
                               :identity_paths, :entity_owned,
                               keyword_init: true) do
           # Every verb this category declares, in declaration order; a verb missing
@@ -35,6 +34,15 @@ module Hecks
             Array(references[verb.to_s]).include?(argument.to_s)
           end
 
+          # Whether `argument` on `verb` is a list, so each of its items is one value.
+          #
+          # @param verb [String] the command name declaring `argument`
+          # @param argument [String] the argument name to check
+          # @return [Boolean] whether `argument` on `verb` is declared as a list
+          def list?(verb, argument)
+            Array(lists&.dig(verb.to_s)).include?(argument.to_s)
+          end
+
           # Whether this category has no parent — the root of the containment tree.
           def root? = parent.nil?
         end

data/lib/hecks/bluebook/meta_validator/plan/verbs.rb

@@ -15,6 +15,15 @@ module Hecks
             end
           end
 
+          # Which arguments of which verbs are lists, read straight off the IR, so a list
+          # argument's items are each wrapped as a value rather than the list as one.
+          def lists_in(commands)
+            commands.each_with_object({}) do |command, found|
+              named = command.attributes.select(&:list?).map { |attribute| attribute.name.to_s }
+              found[command.hecks_name] = named unless named.empty?
+            end
+          end
+
           # Every reference argument is dropped, not just the parent link:
           # a reference is not a field.
           def declared_fields(declare)

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -126,7 +126,8 @@ module Hecks
             sealers:    sealers_in(rest),
             # Every command, not `rest` — the creating command carries the parent
             # link, which is the most common reference of all.
-            references: references_in(aggregate.commands)
+            references: references_in(aggregate.commands),
+            lists:      lists_in(aggregate.commands)
           }
         end
 

data/lib/hecks/bluebook/meta_validator/reconstruction/heads.rb

@@ -26,7 +26,9 @@ module Hecks
               description:   text(row[:description]),
               identified_by: identity_paths(row),
               attributes:    Array(row[:attributes]).map { |field| attribute(field, id) }
-            }.merge(aggregate_rules(row)).merge(lifecycle: lifecycle(row), provenance: provenance(row))
+            }.merge(aggregate_rules(row)).merge(lifecycle: lifecycle(row), provenance: provenance(row),
+                                                formerly_known_as: row[:formerly_known_as],
+                                                created_by: row[:created_by])
           end
 
           # The rules and projected fields an aggregate row holds.

data/lib/hecks/bluebook/meta_validator/reconstruction/reading.rb

@@ -65,10 +65,17 @@ module Hecks
             end
           end
 
+          def memberships(row)
+            Array(row[:modules]).map do |part|
+              { name: text(part[:name]).to_s, vision: text(part[:vision]).to_s, aggregate: text(part[:aggregate]).to_s }
+            end
+          end
+
           # Every cell of the meta-domain is a single-field value object, so a row
           # arrives holding Values rather than Strings.
           def text(cell)
             return nil if cell.nil?
+            return cell.map { |held| text(held) } if cell.is_a?(Array)
             return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
 
             cell

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -66,11 +66,16 @@ module Hecks
             classification:    text(@declaration[:classification]),
             formerly_known_as: text(@declaration[:formerly_known_as]),
             namespace:         text(@declaration[:namespace]),
-            attaches_to:       attached_contexts(@declaration),
-            provides:          provisions(@declaration)
+            **row_fields(@declaration)
           }
         end
 
+        # The row-valued fields of the bluebook: its attachments, provisions and module memberships.
+        def row_fields(declaration)
+          { attaches_to: attached_contexts(declaration), provides: provisions(declaration),
+            modules: memberships(declaration) }
+        end
+
         def policy(row) = declaration("Policy", row)
 
         # A process manager's handlers live inline on its own dispatched state,

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -60,6 +60,9 @@ module Hecks
         # `idempotent` is held as text like `expect_undelivered`, and emitted as a boolean.
         def idempotent?(row) = text(row[:idempotent]).to_s == "true"
 
+        # `mints_era` is held as text like `idempotent`, and emitted as a boolean.
+        def mints_era?(row) = text(row[:mints_era]).to_s == "true"
+
         # Kept as raw text, not decoded: this feeds `Assembly::Marks#where_clause`,
         # which decodes it via `read` — decoding here first would strip a kwarg
         # reference's colon, indistinguishable after from a same-named literal.

data/lib/hecks/bluebook/meta_validator/syntax_boot/disk_cache.rb

@@ -47,7 +47,7 @@ module Hecks
           # @param touch [Boolean] whether to mark it as used (a shipped file is read-only)
           # @return [Hash, nil] the table
           def load_table(path, touch: false)
-            table = Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own cache or the gem's own file, never external input
+            table = Marshal.load(File.binread(path))
             FileUtils.touch(path) if touch
             table
           end

data/lib/hecks/bluebook/model_check/aggregate_checks.rb

@@ -23,6 +23,33 @@ module Hecks
           bluebook.aggregates.filter_map { |aggregate| large_aggregate_finding(aggregate, limit) }
         end
 
+        # An aggregate with no commands has nothing that changes it and no command surface for a
+        # diagram to draw from. Reads are queries; a change needs a command.
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] one :no_command_surface error per aggregate with no commands
+        def no_command_surface_findings(bluebook)
+          unacknowledged_commandless(bluebook).map do |aggregate|
+            Finding.new(kind: :no_command_surface, severity: :error, subject: aggregate.hecks_name,
+                        message: "declares no commands, so nothing changes it and no command surface can " \
+                                 "be drawn — give it a command")
+          end
+        end
+
+        # @return [Array<Bluebook::Aggregate>] the aggregates with no commands that do not acknowledge it
+        def unacknowledged_commandless(bluebook)
+          commandless = bluebook.aggregates.select { |aggregate| aggregate.commands.empty? }
+          commandless.reject { |aggregate| Acknowledgements.held?(aggregate, :no_command_surface) }
+        end
+
+        # Every finding about an aggregate's size and its command surface.
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] the size and command-surface findings, in that order
+        def aggregate_findings(bluebook)
+          [*large_aggregate_findings(bluebook), *no_command_surface_findings(bluebook)]
+        end
+
         # @return [Finding, nil] the warning for an aggregate heavier than `limit`
         def large_aggregate_finding(aggregate, limit)
           weight = aggregate_weight(aggregate)

data/lib/hecks/bluebook/model_check/ask_checks.rb

@@ -36,6 +36,31 @@ module Hecks
           end
         end
 
+        # Flags a query the hecksagon binds to a port's adapter. Only the Ruby runtime asks an
+        # adapter for an answer; a Rust host would find nothing behind the query.
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon's ports
+        #   attached
+        # @param rust_target [Boolean] whether this domain has a real Rust target; a domain without
+        #   one is not checked, since nothing but the Ruby runtime serves it
+        # @return [Array<Finding>] one :external_query error per bound query, none off a Rust target
+        def external_query_findings(bluebook, rust_target: false)
+          return [] unless rust_target
+
+          bluebook.aggregates.flat_map do |aggregate|
+            aggregate.ports.flat_map do |port|
+              port.answered_queries.map { |answer| external_query_finding(aggregate, port, answer) }
+            end
+          end
+        end
+
+        def external_query_finding(aggregate, port, answer)
+          Finding.new(kind: :external_query, severity: :error,
+                      subject: "#{aggregate.hecks_name}.#{answer.name}",
+                      message: "the #{port.name} port's adapter answers this query, and only the Ruby " \
+                               "runtime asks an adapter — the Rust host cannot serve it")
+        end
+
         private
 
         def port_trigger_finding(bluebook, policy)

data/lib/hecks/bluebook/model_check/reaction_chains.rb

@@ -0,0 +1,114 @@
+require_relative "../ask_resolution"
+require_relative "reaction_cycles"
+require_relative "reaction_walk"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The reaction graph of one bluebook: which verb emits which event, which policy reacts to
+      # it, and which verb that policy dispatches in turn, an `ask` resolved through the
+      # hecksagon to its port operation. `from` walks it to the longest chain a verb's events start.
+      #
+      # A policy already on the path is not followed again: a loop is cut where it closes, so a
+      # chain counts each policy once; `cycles` reports the loops themselves. A cross-domain
+      # (`across`) policy ends a chain, since the other domain's policies are not in this
+      # bluebook. A `where` is not evaluated, so a chain is the deepest one the declarations
+      # allow, not one a run is certain to take.
+      class ReactionChains
+        # One reaction step: the policy that fires and the verb it dispatches.
+        Step = Struct.new(:policy, :verb) do
+          # @return [String] the policy's name
+          def policy_name = policy.name
+        end
+
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon attached
+        def initialize(bluebook)
+          @bluebook  = bluebook
+          @emitted   = emitted_by_verb
+          @policies  = bluebook.policies.reject(&:target_domain)
+          @dispatch  = @policies.to_h { |policy| [policy, dispatched_by(policy)] }
+          @successors = @policies.to_h { |policy| [policy, @dispatch[policy] ? reacting_to(@dispatch[policy]) : []] }
+        end
+
+        # @return [Array<Array<String>>] each verb that emits an event, as split_verb parses it
+        def verbs = @emitted.keys
+
+        # @return [Set<Array>] the verbs some policy dispatches, which a longer chain already covers
+        def reaction_targets = @dispatch.values.compact.to_set
+
+        # @param verb [Array<String>] a verb, as `Naming.split_verb` parses it
+        # @return [Array<Step>] the longest chain of reactions the verb's events start, in order
+        def from(verb) = walk.longest(reacting_to(verb))
+
+        # @return [Boolean] whether the last `from` stopped searching, so its chain is a lower bound
+        def capped? = walk.capped?
+
+        # @return [Array<Array>] each loop in the graph, as the policies that reach one another
+        def cycles = @cycles ||= ReactionCycles.new(@policies, @successors).groups
+
+        # @param policy [Object] a policy of this bluebook
+        # @return [Step] the policy with the verb it dispatches
+        def step(policy) = Step.new(policy, @dispatch[policy])
+
+        # @param policy [Object] a policy of this bluebook
+        # @return [Array] the policies the verb it dispatches starts
+        def successors(policy) = @successors.fetch(policy)
+
+        private
+
+        def walk = @walk ||= ReactionWalk.new(self, cycles.flatten)
+
+        # Policies that react to an event the verb emits.
+        def reacting_to(verb)
+          events = @emitted.fetch(verb, [])
+          @policies.select { |policy| events.any? { |aggregate, event| hears?(policy, aggregate, event) } }
+        end
+
+        def hears?(policy, aggregate, event)
+          return false unless policy.event_name == event
+
+          qualifier = policy.event_qualifier
+          qualifier.nil? || Naming.demodulise(qualifier) == aggregate
+        end
+
+        def dispatched_by(policy)
+          verb = policy.asks? ? asked_verb(policy) : "#{@bluebook.name}::#{policy.trigger_command}"
+          Naming.split_verb(verb) if verb
+        end
+
+        # The port operation an `ask` resolves to, spelled as a trigger names it, or nil.
+        def asked_verb(policy)
+          outcome = AskResolution.call(@bluebook, policy)
+          "#{@bluebook.name}::#{outcome.verb}" if outcome.resolved?
+        end
+
+        # Each verb the bluebook declares to the `[aggregate, event]` pairs it announces.
+        def emitted_by_verb
+          @bluebook.aggregates.each_with_object({}) do |aggregate, held|
+            commands_of(aggregate).each { |verb, events| held[verb] = events.map { |event| [aggregate.hecks_name, event] } }
+          end
+        end
+
+        def commands_of(aggregate)
+          prefix = "#{@bluebook.name}::#{aggregate.hecks_name}"
+          [*aggregate.commands.map { |command| ["#{prefix}.#{command.hecks_name}", command.emits] },
+           *aggregate.entities.flat_map { |entity| entity_commands(prefix, entity) },
+           *aggregate.ports.flat_map { |port| operations(prefix, port) }]
+            .to_h { |verb, events| [Naming.split_verb(verb), bare_names(events)] }
+        end
+
+        def bare_names(events) = Array(events).map { |event| event.to_s.split("::").last }
+
+        def entity_commands(prefix, entity)
+          entity.commands.map { |command| ["#{prefix}.#{entity.hecks_name}.#{command.hecks_name}", command.emits] }
+        end
+
+        def operations(prefix, port)
+          port.operations.map do |operation|
+            ["#{prefix}.#{port.name}.#{operation.hecks_name}", [*operation.emits, operation.answers, operation.refuses].compact]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_cycles.rb

@@ -0,0 +1,53 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The loops of a reaction graph: groups of policies that can each reach the others through
+      # the commands they dispatch (the strongly connected components with a cycle in them, found
+      # with Tarjan's algorithm), whether or not any command outside the group starts them.
+      class ReactionCycles
+        # @param policies [Array] the graph's nodes, in declaration order
+        # @param successors [Hash{Object => Array}] the policies each policy's dispatch can start
+        def initialize(policies, successors)
+          @policies   = policies
+          @successors = successors
+        end
+
+        # @return [Array<Array>] each loop's policies, in declaration order
+        def groups
+          @index = {}
+          @low = {}
+          @stack = []
+          @found = []
+          @policies.each { |policy| connect(policy) unless @index.key?(policy) }
+          @found.select { |group| loop?(group) }.map { |group| group.sort_by { |policy| @policies.index(policy) } }
+        end
+
+        private
+
+        def loop?(group) = group.size > 1 || @successors.fetch(group.first).include?(group.first)
+
+        def connect(node)
+          @index[node] = @low[node] = @index.size
+          @stack.push(node)
+          @successors.fetch(node).each { |next_node| visit(node, next_node) }
+          @found << pop_group(node) if @low[node] == @index[node]
+        end
+
+        def visit(node, next_node)
+          if @index.key?(next_node)
+            @low[node] = [@low[node], @index[next_node]].min if @stack.include?(next_node)
+          else
+            connect(next_node)
+            @low[node] = [@low[node], @low[next_node]].min
+          end
+        end
+
+        def pop_group(root)
+          group = []
+          group << @stack.pop until group.last.equal?(root)
+          group
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_depth_checks.rb

@@ -0,0 +1,58 @@
+require_relative "reaction_chains"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over reaction chains. A command whose events start a chain of policies longer
+      # than the dispatcher's reaction limit has the reactions past it refused without anyone
+      # being told; a chain of exactly the limit runs whole, in both runtimes. A loop of
+      # policies, which no limit on the chain's length can describe, is reported as a loop.
+      module ReactionDepthChecks
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon attached
+        # @param limit [Integer] the reaction depth limit; the dispatcher's own when not given
+        # @return [Array<Finding>] a warning for each entry command whose longest chain exceeds
+        #   `limit`, for each loop of policies, and for each chain search that gave up
+        def reaction_depth_findings(bluebook, limit: Hecks::Runtime::Dispatcher::MAX_REACTION_DEPTH)
+          chains = ReactionChains.new(bluebook)
+          [*(chains.verbs - chains.reaction_targets.to_a).flat_map { |verb| chain_findings(chains, verb, limit) },
+           *chains.cycles.map { |policies| loop_finding(policies, limit) }]
+        end
+
+        # @return [Array<Finding>] the deep-chain warning for the verb, and the search warning if
+        #   the walk gave up
+        def chain_findings(chains, verb, limit)
+          chain = chains.from(verb)
+          [(deep_chain_finding(verb, chain, limit) if chain.size > limit),
+           (capped_search_finding(verb, chain) if chains.capped?)].compact
+        end
+
+        # @return [Finding] the warning naming every policy of a loop
+        def loop_finding(policies, limit)
+          names = policies.map(&:name)
+          Finding.new(kind: :unbounded_reaction_loop, severity: :warning, subject: names.join(", "),
+                      message: "policies #{names.join(", ")} reach one another, so a command that starts " \
+                               "them reacts until the reaction depth limit of #{limit}, and the " \
+                               "#{limit + 1}th reaction is refused without anyone being told")
+        end
+
+        # @return [Finding] the warning that the chain found for the verb is a lower bound
+        def capped_search_finding(verb, chain)
+          Finding.new(kind: :reaction_chain_search_capped, severity: :warning, subject: verb_text(verb),
+                      message: "the search for the longest chain stopped after " \
+                               "#{ReactionWalk::WORK_LIMIT} steps; the chain of #{chain.size} reactions is a lower bound")
+        end
+
+        # @return [Finding] the warning naming the entry verb and each policy and verb of its chain
+        def deep_chain_finding(verb, chain, limit)
+          path = chain.map { |step| "#{step.policy_name} -> #{verb_text(step.verb)}" }.join(" -> ")
+          Finding.new(kind: :deep_reaction_chain, severity: :warning, subject: verb_text(verb),
+                      message: "starts a chain of #{chain.size} reactions, past the reaction depth " \
+                               "limit of #{limit}: the #{limit + 1}th and any after it are refused: " \
+                               "#{verb_text(verb)} -> #{path}")
+        end
+
+        def verb_text(verb) = "#{verb[0]}::#{verb[1]}.#{verb[2]}"
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_walk.rb

@@ -0,0 +1,62 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The longest chain of reactions a policy starts, counting each policy once per chain. A
+      # policy that reaches no loop has one longest chain whatever path led to it, so those are
+      # remembered; the rest are searched path by path, and the search stops after `WORK_LIMIT`
+      # steps per chain, which `capped?` reports.
+      class ReactionWalk
+        # Policies visited by one search before it gives up and answers the best chain so far.
+        WORK_LIMIT = 10_000
+
+        # @param graph [ReactionChains] answers `step(policy)` and `successors(policy)`
+        # @param looping [Array] the policies that lie on a loop
+        def initialize(graph, looping)
+          @graph   = graph
+          @looping = looping.to_set
+          @settled = {}
+          @reaches = {}
+          @work    = 0
+        end
+
+        # @param starts [Array] the policies the first event reaches
+        # @return [Array<ReactionChains::Step>] the longest chain, in order
+        def longest(starts)
+          @work = 0
+          @capped = false
+          starts.map { |policy| search(policy, []) }.max_by(&:size) || []
+        end
+
+        # @return [Boolean] whether the last `longest` gave up, so its chain is a lower bound
+        def capped? = @capped
+
+        private
+
+        def search(policy, path)
+          return settled(policy) unless reaches_loop?(policy)
+          return give_up if (@work += 1) > WORK_LIMIT
+
+          open = @graph.successors(policy) - path - [policy]
+          [@graph.step(policy)] + (open.map { |next_policy| search(next_policy, [*path, policy]) }.max_by(&:size) || [])
+        end
+
+        def give_up
+          @capped = true
+          []
+        end
+
+        def settled(policy)
+          @settled[policy] ||= [@graph.step(policy)] +
+                               (@graph.successors(policy).map { |next_policy| settled(next_policy) }.max_by(&:size) || [])
+        end
+
+        def reaches_loop?(policy)
+          @reaches.fetch(policy) do
+            onward = @graph.successors(policy)
+            @reaches[policy] = @looping.include?(policy) || onward.any? { |next_policy| reaches_loop?(next_policy) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check.rb

@@ -7,6 +7,7 @@ require_relative "model_check/policy_checks"
 require_relative "model_check/context_checks"
 require_relative "model_check/context_map_checks"
 require_relative "model_check/ask_checks"
+require_relative "model_check/reaction_depth_checks"
 require_relative "model_check/reference_checks"
 require_relative "model_check/orphan_checks"
 require_relative "model_check/one_of_checks"
@@ -41,6 +42,7 @@ module Hecks
       extend PolicyChecks
       extend ContextChecks
       extend AskChecks
+      extend ReactionDepthChecks
       extend ReferenceChecks
       extend OrphanChecks
       extend OneOfChecks
@@ -78,10 +80,11 @@ module Hecks
         [
           *bluebook.aggregates.flat_map { |aggregate| aggregate_lifecycle_findings(aggregate) },
           *reference_findings(bluebook),
-          *large_aggregate_findings(bluebook),
+          *aggregate_findings(bluebook),
           *bluebook.process_managers.flat_map { |process_manager| saga_findings(bluebook, process_manager) },
           *reaction_findings(bluebook, options),
-          *unused_ask_findings(bluebook)
+          *unused_ask_findings(bluebook),
+          *reaction_depth_findings(bluebook)
         ]
       end
 
@@ -112,31 +115,6 @@ module Hecks
           aggregate.entities.flat_map { |entity| lifecycle_findings(aggregate, entity) }
       end
 
-      # Flags a query the hecksagon binds to a port's adapter. Only the Ruby runtime asks an
-      # adapter for an answer; a Rust host would find nothing behind the query.
-      #
-      # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon's ports
-      #   attached
-      # @param rust_target [Boolean] whether this domain has a real Rust target; a domain without
-      #   one is not checked, since nothing but the Ruby runtime serves it
-      # @return [Array<Finding>] one :external_query error per bound query, none off a Rust target
-      def external_query_findings(bluebook, rust_target: false)
-        return [] unless rust_target
-
-        bluebook.aggregates.flat_map do |aggregate|
-          aggregate.ports.flat_map do |port|
-            port.answered_queries.map { |answer| external_query_finding(aggregate, port, answer) }
-          end
-        end
-      end
-
-      def external_query_finding(aggregate, port, answer)
-        Finding.new(kind: :external_query, severity: :error,
-                    subject: "#{aggregate.hecks_name}.#{answer.name}",
-                    message: "the #{port.name} port's adapter answers this query, and only the Ruby " \
-                             "runtime asks an adapter — the Rust host cannot serve it")
-      end
-
       # Flags an aggregate or domain name that collides with a Rust keyword or reserved
       # Cargo key — both become bare module identifiers with no `r#` escape hatch.
       #

data/lib/hecks/bluebook/process_manager.rb

@@ -54,25 +54,42 @@ module Hecks
         correlates_by: -> { correlates_by&.to_s },
         starts_on:     :starts_on,
         ends_on:       :ends_on,
+        endings:       :endings,
+        resumes:       :resumes,
         states:        :states,
         handlers:      many(:handlers)
       )
 
-      attr_reader :name, :correlates_by, :starts_on, :ends_on, :states, :handlers
+      attr_reader :name, :correlates_by, :starts_on, :ends_on, :endings, :resumes, :states, :handlers
 
       # Every optional keyword and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        correlates_by: nil, starts_on: nil, ends_on: nil, states: [], handlers: []
+        correlates_by: nil, starts_on: nil, ends_on: nil, endings: [], resumes: [],
+        states: [], handlers: []
       }.freeze
 
       # @param correlates_by [Symbol, nil] the payload field that correlates a triggering
       #   event to an instance
       # @param starts_on [String, nil] the event that starts a new instance
-      # @param ends_on [String, nil] the event that ends an instance
+      # @param ends_on [String, nil] the first event that ends an instance
+      # @param endings [Array<String>] every event that ends an instance, in declaration order;
+      #   empty when the declaration names only `ends_on`
       def initialize(name:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @name = name.to_s
       end
+
+      # Every event that ends an instance. A process manager that declares one `ends_on` has
+      # that event alone; one that declares several ends on any of them.
+      #
+      # @return [Array<String>] the ending events, never empty when `ends_on` is set
+      def ending_events = endings.empty? ? [ends_on].compact : endings
+
+      # Replaces a bare aggregate name with the dotted path the bluebook resolved it to.
+      #
+      # @param key [String] the `"<Aggregate>.<identity>"` path
+      # @return [String] the path now held
+      def correlate_by!(key) = @correlates_by = key
     end
   end
 end

data/lib/hecks/bluebook/translation.rb

@@ -9,7 +9,6 @@ module Hecks
     # One field whose value changed, bridged by an exhaustive lookup table.
     # Paths follow `TranslationMove`; `values` maps each old-era value to its new-era one.
     # `:values` shadows Struct#values on purpose; no caller reads the built-in.
-    # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
     # A value object's or entity's type name changed with its members unchanged.
@@ -27,6 +26,9 @@ module Hecks
     # derive has a value; a record where it has none keeps its id.
     TranslationRekey = Struct.new(:to)
 
+    # ADR 0166: one aggregate's rows fan out into another, keyed by a field both share.
+    TranslationSplit = Struct.new(:into, :keyed_by, :fields)
+
     # A newly added, required attribute with no source in old data.
     # `default` is what an existing record reads until a command writes a real value;
     # applied in-process by `Lineage#translate` on every adapter.
@@ -35,12 +37,12 @@ module Hecks
     # One aggregate's part of a translation between eras.
     # `drops` makes data loss a declared decision.
     class TranslationAggregate
-      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :derives, :rekeys, :backfills
+      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :derives, :rekeys, :backfills, :splits
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
-        derives: [], rekeys: [], backfills: []
+        derives: [], rekeys: [], backfills: [], splits: []
       }.freeze
 
       # @param name [String, Symbol] the aggregate's name in the destination era