hecks 1.3.0 → 1.5.0

data/lib/hecks/behaviors/runner.rb

@@ -35,16 +35,20 @@ module Hecks
       attr_accessor :last_suite
 
       # `Kernel.load`s one `.behaviors` file and returns its suite, with
-      # NO test actually executed yet — the cheap half, split out so a
+      # no test actually executed yet — the cheap half, split out so a
       # caller that only needs to know what tests exist (the rspec shim,
       # naming its `it`s at collection time) doesn't pay for running them
       # until it actually wants to. `Behaviors.loading_path` is bound only
       # for the duration of the load, and `last_suite` is reset to nil
-      # BEFORE it — a file that loads without ever calling
+      # before it — a file that loads without ever calling
       # `Hecks.behaviors` is unambiguously a parse error, never a stale
       # suite from whatever loaded before it in a sweep (a real bug in a
       # prior port of this idea: compared only against nil, so after the
       # first successful file in a sweep it stayed non-nil forever).
+      # @param path [String] the `.behaviors` file's path
+      # @return [Behaviors::ParseResult] `suite` holding the built `BehaviorsSuite` and
+      #   `parse_error` nil on success; `suite` nil and `parse_error` a String describing
+      #   a raised exception, or the file loading without calling `Hecks.behaviors`
       def parse(path)
         path = File.expand_path(path)
         previous_path = loading_path
@@ -66,6 +70,11 @@ module Hecks
       end
 
       # One `.behaviors` file → `FileResult`, every test actually run.
+      #
+      # @param path [String] the `.behaviors` file's path
+      # @return [Behaviors::FileResult] `parse_error` and empty `runs` on a parse
+      #   failure; otherwise `parse_error` nil and `runs` one `Expectations::Result`
+      #   per test
       def run(path)
         parsed = parse(path)
         return FileResult.new(path: parsed.path, parse_error: parsed.parse_error, runs: []) if parsed.parse_error
@@ -78,12 +87,22 @@ module Hecks
       # it actually found — a sweep that goes green without saying how
       # much it looked at is indistinguishable from one that found
       # nothing to look at.
+      #
+      # @param dir [String] the directory to search, recursively, for `.behaviors` files
+      # @return [Behaviors::SweepResult] `files_swept` the count found, `files` one
+      #   `FileResult` per file, and `summary` the aggregate counts `summarize` returns
       def run_all(dir)
         files = Dir.glob(File.join(dir, "**", "*.behaviors"))
         results = files.map { |path| run(path) }
         SweepResult.new(root: dir, files_swept: files.size, files: results, summary: summarize(results))
       end
 
+      # Tallies a sweep's results into counts by outcome.
+      #
+      # @param results [Array<Behaviors::FileResult>] the swept files' results
+      # @return [Hash{Symbol => Integer}] `:files` the file count, `:parse_errors` files
+      #   that failed to parse, `:total` tests actually run across every file, `:passed`,
+      #   `:failed` and `:errored` counting each `Expectations::Result#status`
       def summarize(results)
         runs = results.flat_map(&:runs)
         {

data/lib/hecks/behaviors.rb

@@ -8,11 +8,19 @@ require_relative "behaviors/runner"
 # lib/hecks/fuzzing.rb, the shape this file mirrors) is opt-in too.
 module Hecks
   class << self
-    # `Hecks.behaviors "Name" do ... end` — deliberately NOT routed
+    # `Hecks.behaviors "Name" do ... end` — deliberately not routed
     # through `collect` the way `bluebook`/`hecksagon`/`world` are: a
     # behaviors suite is a test artifact a runner reads on demand, never
     # a thing a live domain boot needs, so it has no business landing in
     # `Runtime.current_registry`.
+    #
+    # @param name [String] the suite's declared name
+    # @yield the suite's body, evaluated against a `Behaviors::BehaviorsBuilder`
+    # @return [Behaviors::BehaviorsSuite] the built suite, also stashed as
+    #   `Behaviors.last_suite`
+    # @raise [Behaviors::LoadOutsideRunner] if called outside `Behaviors.run(path)`
+    # @raise [Behaviors::Malformed] if the suite declares no `vision` or `loads`, or
+    #   any of its `test` blocks is malformed
     def behaviors(name, &)
       path = Behaviors.loading_path or
         raise Behaviors::LoadOutsideRunner,

data/lib/hecks/bluebook/aggregate.rb

@@ -3,15 +3,15 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # A FIELD READ THROUGH A `reference_to`, HELD LOCALLY (S12, ADR 0025
+    # A field read through a `reference_to`, held locally (S12, ADR 0025
     # — "Consistency across aggregate boundaries") — `projects
     # :customer_status, from: :"customer.status"` declares that this
-    # aggregate's own `:customer_status` is a COPY of the target's own
+    # aggregate's own `:customer_status` is a copy of the target's own
     # `:status`, kept fresh by a rebuild sweep rather than read live at
-    # rule-evaluation time. `reference` names the LOCAL reference
+    # rule-evaluation time. `reference` names the local reference
     # attribute to walk through (`:customer`, minted by this
     # aggregate's own `reference_to Customer`); `remote_field` names
-    # the SCALAR on the target aggregate to copy.
+    # the scalar on the target aggregate to copy.
     ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
 
     # A construct like every other: the aggregate carries its own identity
@@ -19,14 +19,14 @@ module Hecks
     # everything declared on it. The chain is model objects end to end —
     # reference resolution and hecks_fqn both walk it.
     #
-    # THE HOLDING HALF, and nothing else. Every line below restates what
+    # The holding half, and nothing else. Every line below restates what
     # `language/bluebook/aggregate.bluebook` already declares — the field
     # list, said again as readers, again as constructor keywords, and
     # again as an emission. That triplication is what a generator removes;
-    # `Behaviour::Aggregate` carries everything that is NOT derivable from
+    # `Behaviour::Aggregate` carries everything that is not derivable from
     # the declaration, so regenerating this file can never be lossy.
     #
-    # PROTOTYPE: hand-written in the shape a generator would emit, to
+    # Prototype: hand-written in the shape a generator would emit, to
     # prove the seam before the generator exists. `bin/project_model`
     # would own this file; behaviour/aggregate.rb stays hand-written.
     class Aggregate
@@ -42,16 +42,16 @@ module Hecks
         value_objects:    many(:value_objects),
         commands:         many(:commands),
         invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
-        # 0025) — the aggregate's OWN named `given`s, the declaration a
+        # A precondition shared across commands, declared once (S10, ADR
+        # 0025) — the aggregate's own named `given`s, the declaration a
         # referencing command's own (already-resolved) `givens` entry
         # came from. Both sides of "declared once, referenced many"
-        # are real IR, the same shape a value object's TYPE and an
+        # are real IR, the same shape a value object's type and an
         # attribute's own reference to it both are.
         preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # S12, ADR 0025 — deliberately NOT folded into `attributes`:
+        # S12, ADR 0025 — deliberately not folded into `attributes`:
         # `EraGuard::ShapeDiff` only ever walks `attributes` to decide
-        # whether a NEW field leaves an existing record with something
+        # whether a new field leaves an existing record with something
         # genuinely absent, and a projected field's own absence story
         # is different — a record predating the `projects` declaration
         # is expected to be missing it until the rebuild sweep runs,
@@ -64,7 +64,7 @@ module Hecks
         lifecycle:        one(:lifecycle),
         entities:         many(:entities),
         queries:          many(:queries),
-        # ADDITIVE — every domain that declares no port emits `ports: []`,
+        # Additive — every domain that declares no port emits `ports: []`,
         # the same "regenerate deliberately" wire-format change
         # ir_golden_spec.rb's own header describes; no existing key
         # moves. See docs/decisions (rust/project/ports.rb) for the
@@ -80,6 +80,36 @@ module Hecks
       # Assigns what the language declares, then hands off to the
       # behaviour's own `settle` — derived identity, name indexes and
       # owner stamping, none of which the declaration states.
+      #
+      # @param name [String, Symbol] the aggregate's declared name
+      # @param description [String, nil] the aggregate's declared prose description
+      # @param attributes [Array<Bluebook::Attribute>] the aggregate's declared fields
+      # @param value_objects [Array<Class>] the value object classes (`Bluebook::ValueObject`
+      #   subclasses) declared on this aggregate
+      # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
+      #   declared on this aggregate
+      # @param invariants [Array<Bluebook::Invariant>] the aggregate-level rules that must
+      #   always hold
+      # @param preconditions [Array<Bluebook::Given>] the aggregate's own named `given`s, a
+      #   referencing command's own resolved `givens` entry can point back at
+      # @param projected_fields [Array<Bluebook::ProjectedField>] the declared `projects`
+      #   fields, copied from another aggregate's own state by the rebuild sweep
+      # @param identified_by [String, Symbol, Array<String, Symbol>] the identity path(s)
+      #   this aggregate is addressed by
+      # @param lifecycle [Bluebook::Lifecycle, nil] the aggregate's declared state machine,
+      #   or `nil` if it declares none
+      # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
+      #   nested directly under this aggregate
+      # @param queries [Array<Bluebook::Query>] the queries declared directly on this
+      #   aggregate
+      # @param policies [Array<Bluebook::Policy>] the reactions hoisted onto this aggregate
+      #   from the chapter that assembled it
+      # @param ports [Array<Bluebook::DomainPort>] the aggregate-scoped ports attached after
+      #   this aggregate was built
+      # @param reference_targets [Array<String>] the name of every aggregate this one points
+      #   at with an aggregate-level `reference_to`
+      # @param provenance [Object, nil] the aggregate's declared canonical source, captured
+      #   exactly as written, or `nil` if it declares none
       def initialize(name:, description: nil, attributes: [], value_objects: [],
                      commands: [], invariants: [], preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil,
                      entities: [], queries: [], policies: [], ports: [], reference_targets: [],

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -7,13 +7,20 @@ module Hecks
       # is the part no field table can say: which construct holds which, and how a
       # head's references become able to resolve.
       #
-      # It DECIDES NOTHING. Whether a declaration is admissible was settled on the
+      # It decides nothing. Whether a declaration is admissible was settled on the
       # way in, by the language.
       class AggregateAssembly
+        # @param row [Hash{Symbol => Object}] one declared aggregate's raw contract data,
+        #   as `@declaration[:aggregates]` carries it
         def initialize(row)
           @row = row
         end
 
+        # Builds the aggregate's whole owner-chain graph — its value objects, commands,
+        # entities, queries and lifecycle — from its raw declaration.
+        #
+        # @return [Bluebook::Aggregate] the built aggregate, with every reference stamped
+        #   to resolve against it
         def aggregate
           shapes   = Array(@row[:value_objects]).map { |shape| value_object(shape) }
           commands = Array(@row[:commands]).map { |verb| Build.call("Command", verb) }
@@ -29,7 +36,7 @@ module Hecks
             entities:          entities,
             queries:           asks,
             lifecycle:         lifecycle_of(@row),
-            # A policy declared inside a head is HOISTED onto the chapter by the
+            # A policy declared inside a head is hoisted onto the chapter by the
             # builder, and `Aggregate#to_h` never carried it — so the language does
             # not record which head a chapter-level policy was written in. The
             # chapter holds them all, which is what `PolicyInterpreter` reads.
@@ -43,11 +50,11 @@ module Hecks
 
         private
 
-        # What this head points at with an aggregate-level `reference_to`. NOT the
+        # What this head points at with an aggregate-level `reference_to`. Not the
         # self-references its verbs carry — the first version read
         # `commands.filter_map(&:references)` and gave Pizza two targets of "Pizza",
         # its own verbs pointing at itself, where the builder recorded none. An
-        # aggregate-level `reference_to X` leaves a reference ATTRIBUTE behind, so
+        # aggregate-level `reference_to X` leaves a reference attribute behind, so
         # the attributes are where the answer is.
         def reference_targets(fields)
           fields.select(&:reference?).map { |field| field.type.target_name }
@@ -57,7 +64,7 @@ module Hecks
           Build.call("ValueObject", row)
         end
 
-        # S17, ADR 0026 — RECURSES. "That is what `entity` is for, and
+        # S17, ADR 0026 — recurses. "That is what `entity` is for, and
         # `entity` is declared by the language and used zero times in it"
         # — Dispatch, inside Handler, is the first use, so `row[:entities]`
         # is built the same way `row` itself was reached: through this
@@ -75,7 +82,7 @@ module Hecks
 
         # Every reference learns which head declares it, so it can reach the chapter
         # and resolve. Deliberately across every list that can carry one — a
-        # reference the walk misses resolves to nil, and a nil target is SKIPPED
+        # reference the walk misses resolves to nil, and a nil target is skipped
         # rather than refused, so the guarantee would go quiet instead of red.
         def stamp_references(aggregate)
           lists = [aggregate.attributes, *aggregate.commands.map(&:attributes), *aggregate.queries.map(&:attributes)]
@@ -84,7 +91,7 @@ module Hecks
           lists.flatten.select(&:reference?).each { |field| field.type.declared_in = aggregate }
         end
 
-        # S17, ADR 0026 — walks NESTED entities too (Dispatch, inside
+        # S17, ADR 0026 — walks nested entities too (Dispatch, inside
         # Handler), not only an aggregate's own direct ones.
         def entity_reference_lists(entities, lists)
           entities.each do |piece|
@@ -95,7 +102,7 @@ module Hecks
           end
         end
 
-        # THREE LANGUAGE FIELDS, ONE IR OBJECT. `state_field`, `state_start` and
+        # Three language fields, one IR object. `state_field`, `state_start` and
         # `transitions` are separate declarations; the IR keeps one Lifecycle. The
         # contract names them derived, and this is what derives them.
         def lifecycle_of(row)
@@ -110,8 +117,8 @@ module Hecks
         end
 
         # A lifecycle holds [command, StateTransition] pairs and `to_h` expands one
-        # pair whose `from` is a list into several rows. Grouped back by command AND
-        # TARGET, because one declared pair has exactly one target and may have many
+        # pair whose `from` is a list into several rows. Grouped back by command and
+        # target, because one declared pair has exactly one target and may have many
         # froms — grouping by command alone would fuse two declarations that move the
         # same verb to different states.
         def transitions(rows)

data/lib/hecks/bluebook/assembly/build.rb

@@ -1,12 +1,12 @@
 module Hecks
   module Bluebook
     class Assembly
-      # ONE WAY TO BUILD A CONSTRUCT, for every construct.
+      # One way to build a construct, for every construct.
       #
-      # There used to be a method per category here — `value_object(row)`,
-      # `command(row)`, `policy(row)` — each one gathering the same keywords the
-      # contract already names. This reads the contract instead, so adding a field
-      # to the language and forgetting to assemble it is caught by the coverage gate
+      # Not a method per category — `value_object(row)`, `command(row)`,
+      # `policy(row)`, each gathering the same keywords the contract already
+      # names. This reads the contract instead, so adding a field to the
+      # language and forgetting to assemble it is caught by the coverage gate
       # rather than by nobody.
       #
       # `make` is the only branch, and it is a real one: a construct that became a
@@ -16,6 +16,16 @@ module Hecks
       module Build
         module_function
 
+        # Builds one construct from its declared row, reading which keywords it takes
+        # and how to read each one off `Assembly.contract(category)`.
+        #
+        # @param category [String] the contract's category name, such as `"Aggregate"`
+        #   or `"Command"`
+        # @param row [Hash{Symbol => Object}] the construct's own declared row
+        # @param extra [Hash{Symbol => Object}] keywords the caller supplies directly,
+        #   such as already-built children the contract itself cannot derive
+        # @return [Object] the built construct: an instance for a category whose
+        #   `make` is `:new`, or a class for one whose `make` is `:declare`
         def call(category, row, extra = {})
           contract = Assembly.contract(category)
           keywords = contract.fields.to_h { |keyword, (key, reader)| [keyword, read(reader, row[key])] }
@@ -23,12 +33,23 @@ module Hecks
           holder(contract).public_send(contract.make, **keywords, **extra)
         end
 
+        # Resolves the class or module a contract's construct is built through.
+        #
+        # @param contract [Bluebook::Assembly::Contract] the category's field contract
+        # @return [Module] the holder that answers `contract.make` (`.new` or `.declare`)
+        # @raise [ArgumentError] if the contract names no holder to build through
         def holder(contract)
           contract.holder or raise ArgumentError, "#{contract} holds nothing that can be built"
         end
 
         # A reader is a Marks method, a list of them, or one of three spellings that
         # need no decoding at all.
+        #
+        # @param reader [Symbol, Array, nil] the contract field's reader: `:plain`,
+        #   `:identity`, `:flag`, `[:each, marks_method]`, `[:option, name]`, or a bare
+        #   `Marks` method name
+        # @param value [Object] the raw declared value to read
+        # @return [Object] the value read through `reader`
         def read(reader, value)
           case reader
           when :plain    then value

data/lib/hecks/bluebook/assembly/contract.rb

@@ -5,14 +5,14 @@ module Hecks
     # struct format itself (this file) plus, reopened in contracts.rb, the
     # `CONTRACTS` table of one `Contract` per construct category.
     class Assembly
-      # WHAT A CONSTRUCT NEEDS THAT THE LANGUAGE CANNOT SAY, and how a claim that a
-      # field needs no assembling is CHECKED.
+      # What a construct needs that the language cannot say, and how a claim that a
+      # field needs no assembling is checked.
       #
-      # `derived:` used to be a list of names, and a list of names is a promise with
-      # nobody holding it. The coverage gate only asked whether a field was accounted
-      # for — so writing `derived: %i[version]` would have satisfied it while dropping
-      # a chapter's version in silence, which is the exact shape of every defect this
-      # arc has found. Naming a field derived is a CLAIM, and a claim needs a kind:
+      # Naming a field derived is a claim, and a claim needs a kind, not just a name
+      # in a list. A bare list of names is a promise with nobody holding it: the
+      # coverage gate only asks whether a field is accounted for, so `derived:
+      # %i[version]` would satisfy it while dropping a chapter's version in
+      # silence — the exact shape of every defect this arc has found.
       #
       #   :parent            the containment tree supplies it — a `*_id`, or one of
       #                      the named pointers below. Checked against the name.
@@ -25,38 +25,70 @@ module Hecks
       #   :elsewhere         not a fact about this construct at all. Allow-listed one
       #                      by one, because it is the kind with no other check.
       #
-      # Every one of those can FAIL. That is the whole difference.
+      # Every one of those can fail. That is the whole difference.
       Contract = Struct.new(:holder, :make, :fields, :derived, :rows, :reads, keyword_init: true) do
-        # How a declaration key is read back off a ROW. Absent means the default —
+        # How a declaration key is read back off a row. Absent means the default —
         # `text(row[key])`, a single cell — which is most of them ; present names the
         # shape, because a list needs a reader per element and a folded field is
         # gathered rather than fetched. Same pattern as `rows`, in the other
         # direction: declare the exceptions, default the rest.
+        #
+        # @param key [String, Symbol] the field's declaration key, as `fields` names it
+        # @return [Symbol, Array, nil] the reader named in `reads` for `key`, or `nil`
+        #   when the field reads through the default single-cell reader
         def reader(key) = Hash(reads)[key.to_sym]
 
-        # How an appendable LIST becomes rows the walk can offer. A list absent from
+        # How an appendable list becomes rows the walk can offer. A list absent from
         # here reads straight off the node ; one that is present names the shaper,
         # because the IR keeps a shape the language does not — a transition whose
         # `from` is a list is several rows, an append binds several fields at once,
         # an open map is one row per entry.
+        #
+        # @param list [String, Symbol] the appendable list's field name
+        # @return [Symbol, nil] the shaper method named in `rows` for `list`, or `nil`
+        #   when the list reads straight off the node instead
         def shaper(list) = Hash(rows)[list.to_sym]
 
+        # Whether `field` is one this contract accounts for, stored or derived.
+        #
+        # @param field [Symbol] the field name to check
+        # @return [Boolean] whether `field` is a key of `fields` or of `derived`
         def declares?(field) = fields.key?(field) || derived.key?(field)
 
+        # Names the kind of derived claim `field` makes, if any.
+        #
+        # @param field [Symbol] the derived field name to check
+        # @return [Symbol, Array, nil] the kind `derived` names for `field` — `:parent`,
+        #   `:children`, `:elsewhere`, `:walk`, an `[:computed, method]` or `[:folded,
+        #   object, member]` pair — or `nil` when `field` is not derived
         def kind_of(field) = derived[field]
 
-        # WHERE A FOLDED FIELD ACTUALLY LIVES, as [object, member].
+        # The fields the walk supplies — every `derived: { field => :walk }` claim.
+        # The language declares them (`attribute :position, Position`) so the
+        # judge can order siblings, but no constructor takes one. This is the one
+        # place that fact is stated ; `Specializer` and `Model::Deviations` read it
+        # here rather than each keeping their own `%i[position]`.
+        #
+        # @return [Array<Symbol>] every field name whose derived kind is `:walk`
+        def walked = derived.select { |_field, kind| kind == :walk }.keys
+
+        # Where a folded field actually lives, as [object, member].
         #
         # `[:folded, :lifecycle, :field]` says the language's `state_field` is the
-        # `field` of the IR's one Lifecycle. That is the same fact `Readings` used to
-        # state a second time as `node.lifecycle&.field` — so saying it once here
-        # drives BOTH directions: the walk reads the member on the way in, and the
-        # reconstruction gathers the members back into the object on the way out.
+        # `field` of the IR's one Lifecycle. `Readings` would otherwise have to state
+        # that fact a second time as `node.lifecycle&.field` — saying it once here
+        # drives both directions instead: the walk reads the member on the way in, and
+        # the reconstruction gathers the members back into the object on the way out.
         #
         # A nil member means the fold has no single member to name — `rows` is a
         # count of what `closed_set` and `members` hold between them, and `options`
         # spreads across eight keys. Those keep their own code, and the gate still
         # checks the object they name is real.
+        #
+        # @param field [Symbol] the derived field name to check
+        # @return [Array(Symbol, Symbol), Array(Array<Symbol>, nil), nil] the `[object,
+        #   member]` pair the field folds into — `member` is `nil` when the fold has
+        #   no single member to name — or `nil` when `field` does not fold at all
         def folded(field)
           kind = derived[field]
           return nil unless kind.is_a?(Array) && kind.first == :folded
@@ -64,16 +96,20 @@ module Hecks
           [kind[1], kind[2]]
         end
 
-        # COMPUTED means worked out, not merely answerable.
+        # Computed means worked out, not merely answerable.
         #
         # Asking only whether the holder responds was too weak, and measurably so:
         # `[:computed, :version]` passed, because `Bluebook` does answer to
         # `version` — it just answers with what the constructor was handed. A field
-        # the constructor TAKES is stored, and calling it computed is how a chapter's
+        # the constructor takes is stored, and calling it computed is how a chapter's
         # version would have gone missing while the gate said yes.
         #
-        # So a computed field is one the holder answers AND the constructor does not
+        # So a computed field is one the holder answers and the constructor does not
         # accept. `query_name` qualifies (`Naming.snake(name)`) ; `version` cannot.
+        #
+        # @param method [Symbol] the field name to check
+        # @return [Boolean] whether `holder` answers `method` but its constructor does
+        #   not accept it as a keyword
         def computes?(method)
           return false unless holder
           return false unless answers?(method)
@@ -81,10 +117,22 @@ module Hecks
           !accepts?(method)
         end
 
+        # Whether `holder` answers `method`, checked the way that fits how it is
+        # built: `respond_to?` for a `:declare` holder (a class, queried live) and
+        # `method_defined?` for a `:new` holder (an instance method, checked without
+        # building one).
+        #
+        # @param method [Symbol] the method name to check
+        # @return [Boolean] whether `holder` answers `method`
         def answers?(method)
           make == :declare ? holder.respond_to?(method) : holder.method_defined?(method)
         end
 
+        # Whether the holder's constructor takes `keyword` as a keyword argument.
+        #
+        # @param keyword [Symbol] the keyword to check
+        # @return [Boolean] whether the holder's constructor (`.declare` or
+        #   `#initialize`) accepts `keyword` as an optional or required keyword
         def accepts?(keyword)
           builder = make == :declare ? holder.method(:declare) : holder.instance_method(:initialize)
 
@@ -92,22 +140,49 @@ module Hecks
         end
       end
 
-      # The fields that hold a parent's id without being spelled `*_id`. An entity is
-      # declared in an aggregate, a member on a value object, a dispatch inside a
-      # handler, and each names its parent with a word rather than a suffix.
-      PARENT_POINTERS = %i[owner shape handler].freeze
+      # The fields that point at a parent without being spelled `*_id` — the one list,
+      # read by the assembly gate (a `:parent` claim), the model generator and
+      # QueryIR (a declared field the model composes instead of storing).
+      #
+      #   aggregate, bluebook   the bare parent link a creating command mints
+      #                         (ADR 0025) — exactly the `parent_key`s `Plan` reads
+      #                         off the language
+      #   owner                 Entity's own text twin of that link, which is why
+      #                         Entity's contract claims `owner: :parent`
+      #
+      # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
+      # Dispatch nested entities, so neither is a parent field any more the way
+      # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
+      # contracts directly and fails on any drift, rather than trusting this list to
+      # stay in sync with a second hand-written copy kept by the model generator.
+      PARENT_POINTERS = %i[aggregate bluebook owner].freeze
+
+      # Whether `field` is a parent pointer that does not end in `_id`.
+      #
+      # @param field [String, Symbol] the field name to check
+      # @return [Boolean] whether `field` ends with `_id`, or is one of
+      #   `PARENT_POINTERS`
+      def self.parent_pointer?(field)
+        field.to_s.end_with?("_id") || PARENT_POINTERS.include?(field.to_sym)
+      end
 
       # The only fields allowed to claim they describe something other than the
       # construct they hang off, each with the reason spelled out.
       #
       #   normalisations   the canonical-form table belongs to the expression grammar.
       #                    A chapter's rules are canonicalised on the way in, so the
-      #                    language models the table — but no chapter STORES one, and
+      #                    language models the table — but no chapter stores one, and
       #                    `Bluebook#to_h` splices it in from Expression.
       ELSEWHERE = {
         Bluebook: %i[normalisations]
       }.freeze
 
+      # Whether `field` is allow-listed as describing something other than
+      # `category`'s own construct — see `ELSEWHERE`.
+      #
+      # @param category [String, Symbol] the construct category name
+      # @param field [Symbol] the field name to check
+      # @return [Boolean] whether `field` is on `category`'s `ELSEWHERE` entry
       def self.elsewhere?(category, field)
         Array(ELSEWHERE[category.to_sym]).include?(field)
       end