hecks 1.2.0 → 1.4.0

data/lib/hecks/behaviors/expectations.rb

@@ -14,20 +14,20 @@ require_relative "../ports/persistence/binding_policy"
 # runner.rb the same way the file-count/sweep concern is split from a
 # single test's own execution.
 #
-# TWO DELIBERATE DEVIATIONS from a prior port of this same idea (read
+# Two deliberate deviations from a prior port of this same idea (read
 # before writing this, not reinvented):
 #
 # 1. A `setup` refusal and a refusal from the command under test are
-#    caught in SEPARATE rescue scopes. The prior port wrapped the whole
+#    caught in separate rescue scopes. The prior port wrapped the whole
 #    test body — setups included — in one `rescue *REFUSAL_CLASSES`, so a
 #    broken setup could spuriously satisfy `expect refused: "..."` if its
 #    own refusal happened to match the expected substring. Here, any
-#    domain refusal during `setup` is unconditionally an ERROR — the
+#    domain refusal during `setup` is unconditionally an error — the
 #    example never got to the situation it claims to test.
 #
-# 2. `emits:` is read off a `registry.event_log` DIFF around the tested
+# 2. `emits:` is read off a `registry.event_log` diff around the tested
 #    dispatch, not off `Result#events` alone. `Result#events` only holds
-#    the events the OUTERMOST dispatch announced; a policy's own cascade
+#    the events the outermost dispatch announced; a policy's own cascade
 #    reenters through the same `Dispatcher#dispatch` (`PolicyInterpreter
 #    #deliver` → `door.reenter` → `dispatch`), and every dispatch's
 #    events — outer and reentrant alike — land in the one shared
@@ -66,18 +66,18 @@ module Hecks
         error_result(test, "#{e.class}: #{e.message}")
       end
 
-      # ONE BOOT PER SUITE, NOT PER TEST. The isolation a test needs is a
+      # One boot per suite, not per test. The isolation a test needs is a
       # runtime with nothing in it — and a boot of the same files gives
       # exactly that back for the price of `Registry#reset_runtime_state!`
       # instead of ~2s of loading, verifying and era-checking the same
       # bluebook again (chess: 76 behaviours, 155s of which was booting
-      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` AND
+      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` and
       # their mtimes, so an edited bluebook boots fresh on the next test
       # rather than running against a stale one — the property a watch
       # loop or a long rspec session actually relies on. `runtime:` lets
       # a caller that already holds a booted runtime (a spec, a REPL)
       # hand it in; it is reset the same way.
-      # NOT frozen — a real cache, mutated below (`RUNTIMES[key] ||=
+      # Not frozen — a real cache, mutated below (`RUNTIMES[key] ||=
       # boot_and_guard(files)`) and by #reset!. False positive for
       # Style/MutableConstant.
       # rubocop:disable-next Style/MutableConstant
@@ -94,12 +94,12 @@ module Hecks
         end
       end
 
-      # `reset_runtime_state!` only drops repository OBJECTS between
+      # `reset_runtime_state!` only drops repository objects between
       # tests (registry.rb) — sufficient isolation for `Memory`, whose
       # `@records` is a plain per-instance ivar, so a fresh object really
       # is a fresh store. Against anything else (Sqlite, Postgres) the
       # rows themselves stay put: tests leak into each other, and a
-      # suite booted against a domain's REAL hecksagon writes to a real
+      # suite booted against a domain's real hecksagon writes to a real
       # database. Refusing that wiring here, at boot, is the same shape
       # of guard `BindingPolicy` already applies to a missing bind — the
       # project's identity is refusing bad wiring up front, not
@@ -159,13 +159,13 @@ module Hecks
         check_ok(test) || check_fields(test, settled_state(runtime, verb, result)) || pass_result(test)
       end
 
-      # A field expectation reads the aggregate AS IT STANDS once the
+      # A field expectation reads the aggregate as it stands once the
       # dispatch and its whole cascade have run — the same "cascades are
       # always on" reading `emits:` already commits to. `Result#state` is
-      # the wrong source for that: it snapshots the instance the OUTER
+      # the wrong source for that: it snapshots the instance the outer
       # dispatch saved, and a policy's own reentrant dispatch (a ply
       # advancing off a Moved event, a move count bumping) hydrates and
-      # saves a FRESH record afterward — so a field the cascade wrote
+      # saves a fresh record afterward — so a field the cascade wrote
       # read back stale (found live: `expect move_count: 1` got 0 while
       # `emits:` saw MoveCountBumped in the same test). The repository
       # holds the settled record; read it back by the id the dispatch
@@ -185,7 +185,7 @@ module Hecks
       # A behaviors test writes a dispatch the way the guide's own chess
       # examples do — receiver identity and command facts side by side
       # (`label: "g", id: "wn", to: { file: 2, rank: 2 }`) — and since
-      # #335 the dispatcher's own `to:` keyword is the ROUTING envelope,
+      # #335 the dispatcher's own `to:` keyword is the routing envelope,
       # so forwarding those kwargs loose collides the moment a domain
       # declares a command fact named `to` (chess does: every Move's own
       # destination). Found live: every such test failed with "to: does
@@ -194,18 +194,31 @@ module Hecks
       # mixed facts into the strict envelope — identities lifted into
       # `to:`, declared facts into `with:` — so a behaviors dispatch now
       # goes through the exact same separation a policy's projection
-      # does. A verb that resolves to no command (a port operation —
-      # "Pizzas::Order.PaymentGateway.Receive") keeps the loose
-      # passthrough: its own input already spells the port form's
-      # `to:`/`with:`, which the dispatcher's port branch reads directly.
+      # does. A verb that names a port operation (checked explicitly,
+      # below — "Pizzas::Order.PaymentGateway.Receive") keeps the loose
+      # passthrough instead: its own input already spells the port
+      # form's `to:`/`with:`, which the dispatcher's port branch reads
+      # directly, and `ReactionInvocation.build`'s explicit envelope
+      # expects a command's own declared attributes at the top level,
+      # not a port operation's already-wrapped `to:`/`with:` shape.
+      #
+      # This used to rely on `resolve_target` raising `UnknownVerb` for
+      # any port-operation verb — true only so long as nothing else ever
+      # asked it to resolve one. Now that a `policy` can legitimately
+      # `trigger` a port operation (`ReactionInvocation#resolve_target`'s
+      # own port-operation branch), that raise is gone, so this checks
+      # for a port operation directly instead of leaning on a refusal
+      # that no longer happens.
       def dispatch_command(runtime, verb, args)
+        return runtime.dispatch_flat(verb, args) if port_operation?(runtime, verb)
+
         invocation = begin
           Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
                                             projected: args, explicit: true)
         rescue Runtime::UnknownVerb
           nil
         end
-        return runtime.dispatch(verb, **args) unless invocation
+        return runtime.dispatch_flat(verb, args) unless invocation
 
         if invocation.key?(:to)
           runtime.dispatch(verb, to: invocation[:to], with: invocation[:with])
@@ -214,6 +227,21 @@ module Hecks
         end
       end
 
+      # The same "Head.Rest" shape `Dispatcher#dispatch` and
+      # `ReactionInvocation#resolve_target` both already check — a bare
+      # domain/aggregate lookup plus a port-name lookup, no command
+      # resolution needed since all this asks is whether one exists.
+      def port_operation?(runtime, verb)
+        domain, aggregate_name, command_path = Naming.split_verb(verb)
+        return false unless command_path
+
+        aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        return false unless aggregate
+
+        head, rest = command_path.split(".", 2)
+        rest && !!aggregate.port(head)
+      end
+
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 
@@ -303,7 +331,7 @@ module Hecks
       # `expect` values both ways — bare (`expect kind: "bishop"`) and
       # wrapped (`expect kind: { value: "bishop" }`). A live record's
       # field always comes back as a `Hecks::Runtime::Value`;
-      # normalizing BOTH sides to the same bare-scalar-or-plain-hash
+      # normalizing both sides to the same bare-scalar-or-plain-hash
       # shape is the one comparison that accepts either spelling.
       def normalize(value)
         return Hecks::Runtime::Value.materialize_unwrapped(value) if value.is_a?(Hecks::Runtime::Value)
@@ -316,7 +344,7 @@ module Hecks
       # can name more than one bluebook, so resolution searches every
       # aggregate across every bluebook the suite booted for the one that
       # actually declares the command. `on:` (when given, only ever on
-      # the TESTED command — `setup` never receives it, see the DSL
+      # the tested command — `setup` never receives it, see the DSL
       # contract) narrows the search to one aggregate by name instead of
       # searching all of them.
       def qualify(command, on_aggregate, bluebooks, kind:)
@@ -326,7 +354,7 @@ module Hecks
         disambiguate_qualified_name(candidates, command, kind, bluebooks)
       end
 
-      # THE SEARCH — every (bluebook, aggregate) pair that declares a
+      # **The search** — every (bluebook, aggregate) pair that declares a
       # command/query named `command`, narrowed to `on_aggregate` by name
       # when given.
       def qualify_candidates(command, on_aggregate, bluebooks, kind)
@@ -340,7 +368,7 @@ module Hecks
         pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
       end
 
-      # THE REPORT — zero candidates and more-than-one candidates both
+      # **The report** — zero candidates and more-than-one candidates both
       # refuse (with a different message); exactly one resolves to its
       # dotted FQN.
       def disambiguate_qualified_name(candidates, command, kind, bluebooks)

data/lib/hecks/behaviors/ir.rb

@@ -2,7 +2,7 @@
 #
 # The `.behaviors` authoring surface's own IR — plain Structs, holding
 # exactly what `Hecks.behaviors "Name" do ... end` collected. Deliberately
-# NOT part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
+# not part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
 # collected into a domain Registry (see `Hecks.behaviors`), never
 # dispatched through MetaValidator, and carries none of the self-hosted
 # round-trip machinery a real bluebook construct does. It is a test

data/lib/hecks/behaviors/rspec.rb

@@ -4,7 +4,7 @@ require_relative "../behaviors"
 # `bundle exec rspec` uses to run `.behaviors` files as ordinary examples,
 # one `it` per test, named by the test's own description string. Same
 # shape `spec/guides_spec.rb` uses for doctested guides: the file is
-# PARSED at collection time (cheap — `Behaviors.parse`, no test actually
+# parsed at collection time (cheap — `Behaviors.parse`, no test actually
 # run yet, just enough to know the `it` names), and each test's own
 # `Expectations.run_one` runs lazily inside its own `it`, exactly when
 # rspec actually executes it.

data/lib/hecks/behaviors/runner.rb

@@ -35,12 +35,12 @@ 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

data/lib/hecks/behaviors.rb

@@ -8,7 +8,7 @@ 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

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

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

@@ -7,7 +7,7 @@ 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
         def initialize(row)
@@ -29,7 +29,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 +43,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 +57,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 +75,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 +84,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 +95,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 +110,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,7 +1,7 @@
 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

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:
+      # arc has found. Naming a field derived is a claim, and a claim needs a kind:
       #
       #   :parent            the containment tree supplies it — a `*_id`, or one of
       #                      the named pointers below. Checked against the name.
@@ -25,16 +25,16 @@ 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.
         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,
@@ -45,12 +45,19 @@ module Hecks
 
         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]`.
+        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
+        # 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.
         #
         # A nil member means the fold has no single member to name — `rows` is a
@@ -64,15 +71,15 @@ 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.
         def computes?(method)
           return false unless holder
@@ -92,17 +99,33 @@ 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`
+      #
+      # It used to read `%i[owner shape handler]` here while the model's copy read
+      # `owner aggregate bluebook`: `shape` and `handler` were Member's and
+      # Dispatch's parent fields before S17 (ADR 0026) made both nested entities,
+      # and nothing noticed the two lists had stopped agreeing. spec/assembly_spec
+      # now derives this set from `Plan` and the contracts and fails on any drift.
+      PARENT_POINTERS = %i[aggregate bluebook owner].freeze
+
+      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]