hecks 1.0.0 → 1.0.2

data/lib/hecks/fuzzing/properties.rb

@@ -321,7 +321,8 @@ module Hecks
 
           domain, aggregate_name, = Naming.split_verb(asked[:query])
           args = asked[:args] || {}
-          rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args)
+          rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args,
+                                     bluebooks: bluebooks)
           ordered = Ports::Query::Ordering.apply(
             rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
           ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
@@ -361,21 +362,65 @@ module Hecks
       # same way #eligible_rows' own rows are, since a stable sort
       # (Ordering.apply's own `identity:`) and the real answer's own
       # `record.state.merge(id: record.id)` both need it.
-      def query_eligible_rows(instances, domain, aggregate_name, wheres, args)
+      # `bluebooks:` — needed ONLY to recognise and resolve a `/` HOP
+      # clause (`engagement/client/status`, hop_chain.bluebook's own
+      # PricedAboveViaEngagement): a hop's head names one of the OWNING
+      # aggregate's declared references, and only the declaration graph
+      # can say which attribute that is and which aggregate it targets.
+      # A local clause never consults it. Latent gap this closed, found
+      # by the fuzzer itself the first time a generated sequence ever
+      # built a full hop chain AND had its paged query answer a row
+      # (seed 1, the moment scalar_value_objects.bluebook joined the
+      # fixtures corpus and shifted every seeded draw): the recompute
+      # dug `engagement/client/status` as a LOCAL dotted path, found
+      # nil, and declared every genuinely-eligible row ineligible — a
+      # false property violation against a correct runtime answer,
+      # reproducible on an untouched main with this same 4-step script.
+      def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
+        aggregate = bluebooks[domain]&.aggregate(aggregate_name)
         prefix = "#{domain}::#{aggregate_name}#"
         instances.filter_map do |key, state|
           next unless key.start_with?(prefix)
 
           row = state.merge(id: key.split("#").last)
           next unless wheres.all? do |clause|
-            held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, clause.field))
-            Ports::Query::InMemory.holds?(clause, held, args)
+            resolved = resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+            held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
+            Ports::Query::InMemory.holds?(resolved, held, args)
           end
 
           row
         end
       end
 
+      # `Runtime::ReferenceHop#fold`, independently restated over the
+      # replay's own `:instances_at` snapshot instead of live
+      # repositories — the same shape every other recompute in this
+      # file takes (never the runtime's own code path, or the property
+      # would be checking the runtime against itself). One hop peels
+      # off the head (`HopPath.next_hop`, the identical one-step
+      # primitive the live fold uses), the inner clause recurses
+      # through `query_eligible_rows` against the TARGET's own
+      # snapshot rows (so a multi-hop tail resolves hop by hop, exactly
+      # as the live path's own recursion does), and the ids that
+      # answered fold back as the same local `in` membership clause the
+      # live fold builds. A clause with no `/`, or one whose head this
+      # aggregate's declarations cannot resolve, passes through
+      # untouched and evaluates locally as it always did.
+      def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+        return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
+
+        hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+        target = hop.target
+        return clause unless target
+
+        inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+        ids   = query_eligible_rows(instances, domain, target.hecks_name, [inner], args, bluebooks: bluebooks)
+                .map { |row| row[:id].to_s }.uniq
+
+        QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+      end
+
       # `QueryInterpreter#resolve_query_value`, reproduced: a declared
       # limit/offset is either a literal or a Symbol naming an argument
       # the caller supplied.

data/lib/hecks/language/bluebook/aggregate.bluebook

@@ -509,6 +509,15 @@ Hecks.bluebook "Bluebook" do
       member word: "query",           context: "Aggregate", body: "keywords", inner: "Query",         opens: "Query",          fills: "", calls: "query_impl"
       member word: "policy",          context: "Aggregate", body: "keywords", inner: "Policy",        opens: "Policy",         fills: "", calls: "policy_impl"
       member word: "value_object",    context: "Aggregate", body: "keywords", inner: "ValueObject",   opens: "ValueObject",    fills: "value_objects"
+      # THE BARE SHORTHAND — `value_object "Price", Integer`, no block:
+      # a second row for the SAME word with `body: "none"`, the exact
+      # two-row move `identified_by` (above) already makes for its own
+      # block/blockless split — the body gate picks whichever row
+      # matches how the line was actually written. Declares a value
+      # object with exactly one attribute, named `value`, of the given
+      # type; sugar for the block form's own single `attribute :value,
+      # Type` line (`AggregateBuilder#value_object`'s own comment).
+      member word: "value_object",    context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "value_objects"
       member word: "command",         context: "Aggregate", body: "keywords", inner: "Command",       opens: "Command",        fills: "", calls: "command_impl"
       member word: "attribute",       context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "attribute_impl"
       member word: "invariant",       context: "Aggregate", body: "source",   inner: "",              opens: "",               fills: "invariants", calls: "invariant_impl"
@@ -558,6 +567,14 @@ Hecks.bluebook "Bluebook" do
       member keyword: "query",           context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "policy",          context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "value_object",    context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      # The bare shorthand's own TYPE argument — optional, because the
+      # block form gives no type at all (its attributes carry their own);
+      # `kind: "constant"` for the same reason `attribute`'s own type
+      # argument (below) is: a type is a bare constant, never quoted
+      # text. Type-AND-block is refused by the builder itself
+      # (`AggregateBuilder#value_object`), not here — an argument row
+      # cannot see the body, only the call.
+      member keyword: "value_object",    context: "Aggregate", at: "2", named: "",         kind: "constant", required: "false", fills: "type"
       member keyword: "command",         context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "command",         context: "Aggregate", at: "",  named: "from",     kind: "literal",  required: "false", fills: "from"
       member keyword: "attribute",       context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"

data/lib/hecks/language/hecksagon/domain_port.bluebook

@@ -4,7 +4,9 @@ Hecks.bluebook "Hecksagon" do
 
     identified_by PortName, as: :name
 
-    attribute :verb, PortVerb, optional: true
+    attribute :verb,    PortVerb, optional: true
+    attribute :signal,  PortSignal, optional: true
+    attribute :answers, list_of(PortAnswer)
 
     value_object "PortName" do
       attribute :value, String
@@ -16,6 +18,24 @@ Hecks.bluebook "Hecksagon" do
       invariant("a verb is named") { !value.to_s.empty? }
     end
 
+    # SAME CLOSED SET port.bluebook's own "Port" aggregate declares —
+    # kept as its own local value object rather than shared cross-
+    # chapter, the same way PortVerb already is here.
+    value_object "PortSignal" do
+      attribute :value, String, one_of: ["reply", "effect"]
+    end
+
+    # `answers` — DomainPortBuilder's own twin of PortBuilder#answers
+    # (port.bluebook's "Port" aggregate, same shape), added once a real
+    # `.port` file migrated to parse through this builder (the repoint
+    # `lib/hecks.rb#port`'s own comment describes) used the word
+    # (`extraction.port`'s own `answers :canonical`). Local, not shared
+    # cross-chapter, same reasoning as PortSignal just above.
+    value_object "PortAnswer" do
+      attribute :value, String
+      invariant("an answer names a real method") { !value.to_s.empty? }
+    end
+
     # HOW DOMAINPORT IS SPELLED. These rows live with the concept
     # they describe; SyntaxBoot discovers every aggregate-local seed table.
     # Contexts represented here: DomainPort.
@@ -35,6 +55,8 @@ Hecks.bluebook "Hecksagon" do
       member word: "tells",           context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "tells_impl"
       member word: "asks",            context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "asks_impl"
       member word: "verb",            context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "verb"
+      member word: "signal",          context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "signal"
+      member word: "answers",         context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "answers"
 
     end
 
@@ -59,6 +81,8 @@ Hecks.bluebook "Hecksagon" do
       member keyword: "tells",           context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "asks",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "verb",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "verb"
+      member keyword: "signal",          context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "signal"
+      member keyword: "answers",         context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "answers"
 
       # THE RECEIVING AGGREGATE — PortOperationBuilder's own `reference_to`
       # (inside the block) is refused (#335); this is the sanctioned

data/lib/hecks/runtime/command_interpreter.rb

@@ -48,7 +48,7 @@ module Hecks
       # that sets them runs, same as they were unset locals before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :delegated_events,
-                           :dry_run)
+                           :dry_run, :correction_bindings)
 
       def initialize(registry, rules:)
         @registry = registry
@@ -135,10 +135,13 @@ module Hecks
           # NotFound/AlreadyExists already get at hydration: "does the
           # fact this command's corrects names even exist" is not a
           # domain rule an author wrote, it is a precondition for the
-          # domain rules to mean anything at all.
-          @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
+          # domain rules to mean anything at all. Also locates the
+          # correction target itself, if `as:` named one — carried on
+          # `ctx` so `step_enforce_ensures` (the settled-record half)
+          # can bind the SAME name too, not just this pre-mutation half.
+          ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
           @rules.enforce_givens(ctx.instance, ctx.command, ctx.args, domain: ctx.domain,
-                                declaring: ctx.aggregate, parent: ctx.instance)
+                                declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
         }
       end
 
@@ -239,7 +242,7 @@ module Hecks
       def step_enforce_ensures(ctx)
         step(:enforce_ensures) {
           @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
-                                 domain: ctx.domain, parent: ctx.instance)
+                                 domain: ctx.domain, parent: ctx.instance, correction: ctx.correction_bindings || {})
         }
       end
 
@@ -260,7 +263,7 @@ module Hecks
           seed_projected_fields(ctx)
           ctx.persistence_outcome = if ctx.strategy == DependencyPlanning::ATOMIC_PUT
                                       # A SECOND CREATION IS NOT A FRESH ONE — see
-                                      # hydrate_legacy_creation's own comment; the
+                                      # hydrate_complete_state's own comment; the
                                       # same refusal, on the same terms, for the
                                       # complete-state path. `insert_only:` asks the
                                       # ADAPTER to decide and refuse ATOMICALLY
@@ -376,19 +379,61 @@ module Hecks
         found.dup
       end
 
-      # Transitional compatibility for live source that has not yet acquired
-      # explicit effects. It is deliberately isolated from the normal routing
-      # and planning path so `reference_to` no longer chooses how a migrated
-      # command hydrates or persists. Wave 8 removes this after the inventory is
-      # empty; frozen eras retain their own shadow parser.
+      # WAVE 8 (equivalence-gap plan, item 1.6) — NOT done, and this
+      # comment now says precisely how far it got, corrected from an
+      # EARLIER version of itself that briefly (same PR, never released)
+      # claimed the inventory was empty and deleted this method outright.
+      # A full corpus audit (`DependencyPlanning::Analyzer.call` against
+      # every `creates?`-true command in all 5 EXAMPLE domains — banking,
+      # pizzas, chess, compliance, roster) found and fixed 4 real
+      # authoring bugs (`Statement.Generate`, `CreatePizza`, `Chess::
+      # Game.Start`, `Roster.Open` — each declared an attribute and
+      # never `sets` it, so the field silently stayed nil on every
+      # created record regardless of what a caller sent), plus a real
+      # `DependencyPlanning::Analyzer` bug for ENTITY-owned commands
+      # (`root_aggregate:`, that class's own header) that surfaced one
+      # more live corpus bug of its own (`payment_cards.bluebook`'s own
+      # `Withdrawal.Dispute`, which never actually checked whether the
+      # card was retired) — all real, all kept.
       #
-      # `ctx.plan.complete_state?` already claimed every command whose plan is
-      # fully resolved in the two branches above `step_hydrate` tries first, so
-      # reaching this check already means the plan is incomplete — an
-      # un-migrated command still routes here on `creates?` alone, the same as
-      # the old `hydrate` did, regardless of whether it happens to have any
-      # mutations (`write_set`). Requiring an EMPTY write_set here refused
-      # every un-migrated creating command that sets even one field.
+      # DELETING THIS METHOD ON THAT BASIS TURNED OUT TO BE WRONG,
+      # caught by running the full suite rather than trusting the
+      # audit's own scope: the 5 example domains are nowhere near the
+      # WHOLE inventory of `creates?`-true commands this fallback
+      # actually carries. Dozens of separate, purpose-built spec
+      # fixtures across the suite (`spec/fixtures/*.bluebook`, and
+      # inline `Hecks.bluebook` blocks declared directly inside
+      # individual spec files — governance, mutation ops, ports,
+      # routing, tenant isolation, sagas, and more) declare their OWN
+      # small `creates?`-true commands the same incomplete way, and
+      # rely on this exact fallback to create anything at all. Deleting
+      # it produced 218 failures across specs with nothing to do with
+      # Wave 8's own subject — confirmed, not guessed, by actually
+      # running `bundle exec rspec` after the deletion, not merely by
+      # extrapolating from the one audited inventory. `spec/fixtures/
+      # till.bluebook`'s own `Till.OpenTill` (missing `sets :number`,
+      # the identical bug shape as the 4 fixed above) was fixed
+      # alongside the four real corpus ones as one instance of this — but
+      # it was one of many, not the last one, and finding the rest is
+      # real, separate, much larger follow-up work this pass does not
+      # attempt: a suite-wide audit of every declared bluebook fixture,
+      # not just the 5 example domains the plan's own text named.
+      #
+      # Transitional compatibility for live source that has not yet
+      # acquired explicit effects, same as it always was — deliberately
+      # isolated from the normal routing and planning path so
+      # `reference_to` no longer chooses how a migrated command hydrates
+      # or persists. A real, future Wave 8 removes this once THAT wider
+      # inventory is empty, not before.
+      #
+      # `ctx.plan.complete_state?` already claimed every command whose
+      # plan is fully resolved in the two branches above `step_hydrate`
+      # tries first, so reaching this check already means the plan is
+      # incomplete — an un-migrated command still routes here on
+      # `creates?` alone, the same as the old `hydrate` did, regardless
+      # of whether it happens to have any mutations (`write_set`).
+      # Requiring an EMPTY write_set here refused every un-migrated
+      # creating command that sets even one field.
       def legacy_implicit_creation?(ctx)
         ctx.route.nil? && ctx.command.creates?
       end
@@ -421,9 +466,11 @@ module Hecks
                                                    aggregate: aggregate.hecks_name,
                                                    identity:  identity_reading(aggregate)))
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_creation's
-        # own comment; the same refusal, on the same terms, for the
-        # complete-state path. ONLY when `strategy` will NOT be ATOMIC_PUT:
+        # A SECOND CREATION IS NOT A FRESH ONE — `creates?` on an identity
+        # a record already exists under refuses (`AlreadyExists`) rather
+        # than silently overwriting it, the same refusal `hydrate_prior_
+        # or_initial`'s own body gives for its own complete-but-state-
+        # dependent case, below. ONLY when `strategy` will NOT be ATOMIC_PUT:
         # an atomic-put-capable adapter enforces this itself, atomically,
         # via `insert_only:` in step_save (no read here, no race with the
         # write) — but `strategy_for` already fell back to a plain `save`
@@ -461,8 +508,8 @@ module Hecks
                                                    identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_
-        # creation's own comment; the same refusal, on the same terms, for
+        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_complete_
+        # state's own comment; the same refusal, on the same terms, for
         # a complete-but-state-dependent command (one with a `given`
         # reading its own prior state, which is what routes here instead
         # of hydrate_complete_state). Gated on `command.creates?`: a

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -116,7 +116,13 @@ module Hecks
         # parent aggregate reaching ITS OWN customer) resolves the same
         # way `account.customer.status` does for a command-level reference.
         # nil for an aggregate command — CommandInterpreter never passes it.
-        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil)
+        # `correction:` — the `{as_name => payload}` bindings
+        # `enforce_correction_target` (above) already located, merged in
+        # LAST so an `as:` name wins the same way `old:` always wins in
+        # `enforce_ensures`, below — it is a fresh local binding a
+        # `corrects` command introduces, not a real argument/state field
+        # a caller could collide with by accident.
+        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           state = GuardState.new(subject)
           # A RULE MAY ONLY READ WITHIN ITS OWN AGGREGATE BOUNDARY (S12,
           # ADR 0025) — `subject`'s own STORED references are no longer
@@ -135,6 +141,7 @@ module Hecks
           # forbids.
           attrs = args.merge(dereference(domain, command, args))
           attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           command.givens.each do |given|
             next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
 
@@ -154,20 +161,43 @@ module Hecks
         # event at all — is `AggregateBuilder#seal_correction_targets`;
         # this is the dispatch-time half — has THIS record actually done
         # so yet.
+        #
+        # ALSO LOCATES the matched event now, not just its existence, and
+        # returns a `{as_name => payload}` bindings hash — one entry per
+        # `:corrects` mutation that named an `as:` — so `given`/`ensures`
+        # on a corrects-bearing command can reference the located OLD
+        # event by that name, the same shape `enforce_ensures`'s own
+        # `old:` binding already has (CommandBuilder#corrects_impl's own
+        # comment: `as:` was stored, from the start, specifically to be
+        # wired into the evaluator once a real runtime consumer existed —
+        # this is that consumer). `.reverse.find` — the MOST RECENT
+        # matching event, if this record has somehow emitted the same
+        # correction target more than once; the prior existence-only
+        # check never had to make this choice, so it's a genuinely new
+        # one, made deliberately: `as:` reads as "the instance being
+        # corrected," which is naturally the latest fact on record, not
+        # an arbitrary one.
         def enforce_correction_target(instance, aggregate, command, domain:)
+          bindings = {}
           command.mutations.each do |mutation|
             next unless mutation.op == :corrects
 
             event_key  = "#{domain}::#{aggregate.hecks_name}"
             event_name = mutation.target.to_s
-            next if @registry.event_log.any? do |event|
+            corrected = @registry.event_log.reverse.find do |event|
               event.name == event_name && event.aggregate == event_key && event.id == instance.id
             end
 
-            raise NothingToCorrect,
-                  "#{command.hecks_name} refused — corrects #{event_name}, but " \
-                  "#{event_key} ##{instance.id} has never emitted it"
+            unless corrected
+              raise NothingToCorrect,
+                    "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                    "#{event_key} ##{instance.id} has never emitted it"
+            end
+
+            as = mutation.source[:as]
+            bindings[as.to_sym] = corrected.payload if as && !as.to_s.empty?
           end
+          bindings
         end
 
         # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — `command
@@ -215,16 +245,21 @@ module Hecks
         # Not new to ensures — `given` lives under the same rule — but an
         # ensures is more likely to collide, since it typically re-reads a
         # field the command just took in to mutate it.
-        def enforce_ensures(subject, command, args, old:, domain:, parent: nil)
+        def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # S12, ADR 0025 — same boundary reasoning as enforce_givens
           # above: `subject`'s own stored references are no longer
           # dereferenced here; a `projects`-maintained field is already
           # part of `state`. `command`/`args` still dereferences — a
           # fresh reference-typed ARGUMENT stays in bounds.
-          # `old` still wins over everything, unchanged.
+          # `old` still wins over everything, unchanged. `correction`
+          # (an `as:`-bound corrected event, if this command declares
+          # one) wins right alongside it — a settled-record ensures can
+          # reference the correction target exactly as freely as a
+          # pre-mutation given already can.
           attrs = args.merge(dereference(domain, command, args))
           attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           attrs = attrs.merge(old: old)
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)

data/lib/hecks/runtime/command_rules/arithmetic.rb

@@ -68,9 +68,39 @@ module Hecks
         # made. The real mistake, an absent argument, was never the one refused,
         # which is what fuzz surfaced.
         #
-        # Absent now resolves to nil. Whether it should be REFUSED instead
-        # is a separate question — the language cannot yet say which arguments are
-        # optional, and the meta-domain has plenty that are.
+        # STALE (as of the equivalence-gap plan's own audit): this used to
+        # say "the language cannot yet say which arguments are optional" —
+        # it already can, and always could once `attribute ..., optional:
+        # true` existed (`CommandBuilder#attribute_impl`,
+        # `attribute_collector.rb`): `sets` already sources correctly from
+        # an optional attribute, resolving absent to nil exactly as this
+        # method does, and REFUSING it here would be wrong, not merely
+        # undone work — `TillRoom::Till.TakeIn`'s own `note` (spec/
+        # fixtures/till.bluebook) and Banking's `CardPayment.Authorize`'s
+        # `tags` (payment_cards.bluebook) are real, live commands whose
+        # `sets` mutation is deliberately sourced from an optional
+        # attribute the caller may omit — `spec/runtime/command_rules_spec
+        # .rb`'s own "says an absent OPTIONAL argument is nil, not the
+        # name of the argument" pins exactly this as correct, not pending.
+        # The meta-domain's own self-hosted commands (Command.Declare's
+        # `role`/`goal`/`provenance`/`from`/`position`, and ~35 more sites
+        # across the language) all lean on the identical pattern — nil is
+        # the RIGHT answer for a `sets` sourced from a declared-optional
+        # attribute the caller left out, every time.
+        #
+        # The one thing that WAS still a real, narrow gap — a `sets`
+        # source Symbol naming NOTHING the command declares at all (a
+        # typo, not an optional argument) — silently resolved to nil
+        # forever the same way, indistinguishable at either build or run
+        # time from a legitimate optional absence. Closed at BUILD time
+        # instead of here: `CommandBuilder#refuse_unknown_argument_sources!`
+        # refuses it the moment the `.bluebook` file loads, mirroring
+        # `AggregateBuilder#seal_query_argument`'s identical check for a
+        # query's own where-clause argument. This function stays exactly
+        # what it always was — a pure, unconditional lookup — because by
+        # the time ANY mutation reaches it, the source has already been
+        # proven to name either a real, possibly-optional argument, or a
+        # StateRef/literal; there is nothing left here to refuse.
         def resolve_source(source, args)
           return args[source] if source.is_a?(Symbol)
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -62,13 +62,29 @@ module Hecks
       class Analyzer
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
-        def self.call(aggregate:, command:) = new(aggregate, command).call
-
-        def initialize(aggregate, command)
+        # `root_aggregate:` — Wave 8's own audit surfaced a real bug here,
+        # not merely a missing feature: for an ENTITY-owned command,
+        # `EntityInterpreter` calls this with `aggregate:` set to the
+        # ENTITY itself (`element_interpreter.rb`'s own `Analyzer.call
+        # (aggregate: entity, command:)`), so `owner_fields` was always
+        # the entity's own attribute set. A `given`/`ensures` reading
+        # `parent.X` legitimately means the ROOT aggregate's own field —
+        # a genuinely different owner — but `classify_path`'s `:parent`
+        # branch checked that read against `owner_fields` (the entity's),
+        # which can never contain a root-level field, so every entity
+        # command with a real, legitimate `parent.*` read was refused as
+        # unresolved regardless of correctness. Defaults to `aggregate`
+        # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
+        # own call site never needed to change.
+        def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
+
+        def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
           @owner_fields = aggregate.attributes.to_set(&:name)
           @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          @root_owner_fields = root_aggregate.attributes.to_set(&:name)
+          @root_owner_fields << root_aggregate.lifecycle.field.to_sym if root_aggregate.lifecycle
           # `projects` FIELDS (S12, ADR 0025) ARE OWNER STATE TOO — a
           # `given`/`ensures` reading one (e.g. `customer_status ==
           # "active"`) is reading this record's own stored field, same
@@ -80,9 +96,17 @@ module Hecks
           # a partial mutation, which is exactly right — a projected
           # field's freshness comes from the interpreter reseeding it on
           # save, not from anything a caller-supplied write set carries.
+          # Applies to BOTH `owner_fields` and `root_owner_fields` — an
+          # entity's own `parent.*` read can name the root aggregate's
+          # projected field just as easily as one of its real attributes
+          # (`Banking::Withdrawal.Dispute`'s own `parent.account_customer_
+          # status`, ATMCard's projected field, is a real, live example).
           if aggregate.respond_to?(:projected_fields)
             aggregate.projected_fields.each { |field| @owner_fields << field.name }
           end
+          if root_aggregate.respond_to?(:projected_fields)
+            root_aggregate.projected_fields.each { |field| @root_owner_fields << field.name }
+          end
           @payload_fields = command.attributes.to_set(&:name)
           @state_reads = Set.new
           @payload_reads = Set.new
@@ -115,7 +139,7 @@ module Hecks
 
         private
 
-        attr_reader :aggregate, :command, :owner_fields, :payload_fields,
+        attr_reader :aggregate, :command, :owner_fields, :root_owner_fields, :payload_fields,
                     :state_reads, :payload_reads, :writes, :known_writes, :unresolved
 
         # A fresh Instance supplies these values without reading a stored
@@ -204,13 +228,36 @@ module Hecks
           end
         end
 
+        # KNOWN, HARMLESS GAP: `corrects ..., as: :name`'s bound name
+        # (admissibility.rb's `enforce_correction_target`/`enforce_givens`/
+        # `enforce_ensures`) isn't special-cased here the way `:old`/
+        # `:parent` are — a given/ensures referencing it falls through to
+        # `unresolved` below (its own field lookup finds no owner/payload
+        # match), same net effect as any other not-yet-optimized command:
+        # `complete_state?` comes back false, so dispatch takes the safe
+        # `hydrate_existing` path instead of the `ATOMIC_PUT` fast path.
+        # Not a correctness bug — `as:`'s runtime binding (a plain `attrs`
+        # merge, exactly like `old:`'s) resolves and evaluates correctly
+        # regardless of what this STATIC analysis concludes — just a real,
+        # deliberately-left optimization gap: closing it would mean
+        # threading "which names this command declares as correction
+        # bindings" into the Analyzer, which doesn't have that per-command
+        # context today. Worth doing alongside `:old`/`:parent`'s own
+        # handling someday, not attempted here.
         def classify_path(path, phase)
           head, nested = path.split(".", 2)
           name = head.to_sym
 
           if name == :parent
             parent_field = nested.to_s.split(".", 2).first
-            if parent_field.empty? || !owner_fields.include?(parent_field.to_sym)
+            # `root_owner_fields` — NOT `owner_fields`. For an entity-owned
+            # command `owner_fields` is the ENTITY's own attribute set;
+            # `parent.X` always means the ROOT aggregate's own field, a
+            # genuinely different owner (`root_aggregate:`'s own header,
+            # above, has the full bug this fixes). Identical for a plain
+            # aggregate command, where root_aggregate defaults to aggregate
+            # itself and the two sets are the same set.
+            if parent_field.empty? || !root_owner_fields.include?(parent_field.to_sym)
               unresolved << "#{path} does not name parent aggregate state"
             else
               state_reads << parent_field.to_sym

data/lib/hecks/runtime/entity_interpreter.rb

@@ -98,7 +98,14 @@ module Hecks
           ctx.chain = chain
           ctx.route = route
           ctx.dry_run = dry_run
-          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
+          # `root_aggregate:` — `entity` is the immediate owner (what
+          # `owner_fields` inside the Analyzer means), but a `parent.X`
+          # read inside this command's own given/ensures means the ROOT
+          # aggregate's own field, not the entity's — `aggregate` here IS
+          # that root (this method's own first parameter, never the
+          # entity). See DependencyPlanning::Analyzer.call's own header
+          # for the bug this closes.
+          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command, root_aggregate: aggregate)
           # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
           # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
           ctx.repository = @registry.repository(domain, aggregate)

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -73,10 +73,19 @@ module Hecks
                    [fetch(bluebook, domain, head[:aggregate], reference_id)]
                  elsif rootless
                    # No root to FK-match against — a rootless model reads
-                   # each of its own heads WHOLE, independently. (Multiple
-                   # heads on one rootless model aren't cross-joined
-                   # against each other either — each is its own bulk
-                   # read. A real, deliberate scope limit for now.)
+                   # each of its own heads WHOLE, independently. Multiple
+                   # heads on one rootless model are NEVER cross-joined
+                   # against each other, and there is no DSL to declare
+                   # one if you wanted to — `ReadModelBuilder#include_impl`
+                   # takes only `type`/`as:` (checked directly, not
+                   # assumed), and `group_by` groups this bulk read's own
+                   # output, it names no predicate between two heads.
+                   # Building a cross-join here would mean CHOOSING a join
+                   # semantics (equality on which fields?) nobody has
+                   # declared — a real, deliberate scope limit pending a
+                   # future `include ..., joins: ...`-shaped grammar
+                   # addition (with its own Rust mirror), not a gap this
+                   # interpreter can quietly grow into on its own.
                    records(bluebook, domain, head[:aggregate])
                  else
                    matching(records(bluebook, domain, head[:aggregate])) do |record|