hecks 2.8.0 → 2.9.0

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

@@ -7,31 +7,12 @@ require_relative "../../ports/query/in_memory"
 module Hecks
   module Runtime
     class CommandRules
-      # A reference must point at something that exists.
-      #
-      # `reference_to Customer` is the one guarantee an aggregate reference is
-      # for, and it was declared 14 times across banking and enforced nowhere :
-      # an Account could belong to a customer who was never registered, and
-      # every gate stayed green because
-      # no corpus step ever passed a dangling reference.
+      # Refuses a `reference_to` whose target identity does not exist.
       module References
-        # Resolved here rather than in coercion because coercion is pure — it
-        # holds no repository. A reference into another domain is left alone : a
-        # cross-domain target may legitimately not be loaded, which is the same
-        # reading `across` policies already get.
+        # Checks reference-typed command arguments against their target repositories.
+        # Cross-domain targets are skipped: they may legitimately not be loaded.
         #
-        # Shared by CommandInterpreter and EntityInterpreter — an entity command
-        # can declare a reference-typed attribute the same way an aggregate
-        # command can, even though nothing in the real corpus does yet.
-        #
-        # @param domain [String, Symbol] the domain the referenced aggregate is
-        #   resolved in
-        # @param command [Class] the command or port-operation class (`Bluebook::Command`
-        #   or `PortOperation` subclass) whose reference-typed attributes are checked
-        # @param args [Hash{Symbol => Object}] the offered, already-coerced argument values
-        # @return [void]
-        # @raise [Runtime::NotFound] if a reference-typed argument names an identity that
-        #   does not exist in its target aggregate's repository
+        # @raise [Runtime::NotFound] if an argument names an identity that does not exist
         def resolve_references(domain, command, args)
           command.attributes.each do |attribute|
             next unless attribute.reference?
@@ -47,23 +28,11 @@ module Hecks
           end
         end
 
-        # Structural references are checked again against the settled state.
-        # This is what makes a `has_many` declared on an aggregate honest even
-        # when a command supplies its list through an ordinary typed argument.
+        # Re-checks references, cardinality and tenant agreement against settled state.
         #
-        # @param domain [String, Symbol] the domain the referenced aggregate is
-        #   resolved in
-        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
-        #   whose reference-typed attributes are checked against `state`
-        # @param state [Hash{Symbol => Object}] the settled, post-mutation state to
-        #   check every reference and relationship cardinality against
-        # @return [void]
-        # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to`
-        #   relationship holds nil
-        # @raise [Runtime::NotFound] if a reference-typed field names an identity
-        #   that does not exist in its target aggregate's repository
-        # @raise [Runtime::Unauthorized] if a referenced record belongs to a
-        #   different tenant than `construct`'s own record
+        # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to` holds nil
+        # @raise [Runtime::NotFound] if a reference names an identity that does not exist
+        # @raise [Runtime::Unauthorized] if a referenced record belongs to another tenant
         def resolve_state_references(domain, construct, state)
           own_tenant_field = tenant_field_for(construct)
 
@@ -90,20 +59,8 @@ module Hecks
           end
         end
 
-        # `has_one` and `belongs_to` mean exactly one target unless the
-        # declaration explicitly says optional. State validation owns this
-        # boundary because a command may leave an aggregate field untouched;
-        # checking only command arguments would let a required relationship be
-        # persisted as nil. `has_many` admits zero members, so its empty list is
-        # already a valid cardinality and needs no presence refusal.
-        #
-        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
-        #   `attribute` is declared on, named in a refusal
-        # @param attribute [Bluebook::Attribute] the reference-typed attribute to check
-        # @param held [Object, nil] the field's settled value
-        # @return [void]
-        # @raise [Runtime::TypeMismatch] if `attribute` declares a required (non-optional,
-        #   non-list) `has_one`/`belongs_to` relationship and `held` is nil
+        # `has_one` and `belongs_to` require a target unless optional. Checked on state,
+        # since a command may leave the field untouched.
         def validate_relationship_cardinality(construct, attribute, held)
           return if attribute.relationship.nil? || attribute.list?
           return unless held.nil? && !attribute.optional?
@@ -114,32 +71,14 @@ module Hecks
                 "#{attribute.type.target_name} identity, got nil"
         end
 
-        # The reference resolves itself — through the chapter's own IR, so the
-        # bluebook's declared heads are the index, rather than regexing the
-        # target's name out of "Reference<Customer>" and searching
-        # `registry.bluebook(domain).aggregates` for it, or reaching the
-        # target through Ruby's constant tree, a class thrown away for its
-        # `.ir` the moment it was found.
+        # Resolves the attribute's target through the chapter IR.
         #
-        # @param attribute [Bluebook::Attribute] the reference-typed attribute to resolve
-        # @return [Bluebook::Aggregate, nil] the target aggregate the reference names,
-        #   or nil if it cannot be resolved
-        # @raise [Bluebook::DSL::Malformed] if the reference does not know which
-        #   aggregate declares it
+        # @raise [Bluebook::DSL::Malformed] if the reference does not know its declaring aggregate
         def referenced_aggregate(attribute)
           attribute.type.resolve
         end
 
         # Refuses a reference-typed value whose target identity does not exist.
-        #
-        # @param domain [String, Symbol] the domain `target` is resolved in
-        # @param target [Bluebook::Aggregate] the referenced aggregate
-        # @param held [Object, Array<Object>] the offered value: a single reference,
-        #   or, when `list:` is true, an Array of them
-        # @param list [Boolean] whether `held` is list-shaped
-        # @return [void]
-        # @raise [Runtime::NotFound] if any referenced identity does not exist in
-        #   `target`'s repository
         def validate_reference_values(domain, target, held, list:)
           values = list ? Array(held) : [held]
           values.each do |value|
@@ -154,47 +93,8 @@ module Hecks
           end
         end
 
-        # Angle-8's own write-side half of `TenantScope.apply` (runtime/
-        # tenant_scope.rb) — the query-side mechanism this mirrors. That
-        # module turns a declared `authorize policy, tenant: :field` into a
-        # synthetic where-clause checked against the caller's own supplied
-        # tenant argument; there is no caller-identity/session system this
-        # runtime has to check a write's caller against (TenantScope's own
-        # header names that as a separate, still-open gap), so this checks
-        # the one thing that is available without one: whether the record
-        # being written and the record it references agree about which
-        # tenant they belong to. `lib/hecks/fuzzing/properties/guards.rb`'s
-        # `commands_respect_tenant_scope` states the identical claim,
-        # read off `history[:instances]` after the fact — this is what
-        # makes that claim hold by construction (a refused write is never
-        # stored) rather than merely checked for regression.
-        #
-        # Hooked into `resolve_state_references` rather than a new
-        # DISPATCH_ORDER step deliberately: that method already walks
-        # every `reference_to`-typed attribute against the settled,
-        # post-mutation state (the same moment `commands_respect_tenant_
-        # scope` itself inspects), already resolves the referenced record
-        # through the repository right above, and already runs from both
-        # `CommandInterpreter#step_save` and `EntityInterpreter#step_save`
-        # — one change, both interpreters covered, no new vocabulary step
-        # to keep in sync with `Vocabulary::AggregateDispatchOrder`/
-        # `EntityDispatchOrder`.
-        #
-        # @param domain [String, Symbol] the domain `target` is resolved in
-        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
-        #   `attribute` is declared on, named in a refusal
-        # @param attribute [Bluebook::Attribute] the reference-typed attribute being
-        #   checked
-        # @param target [Bluebook::Aggregate] the referenced aggregate
-        # @param held [Object, Array<Object>] the offered value: a single reference,
-        #   or, when `attribute.list?` is true, an Array of them
-        # @param state [Hash{Symbol => Object}] `construct`'s own settled state, read
-        #   for its own tenant field's value
-        # @param own_tenant_field [Symbol, nil] `construct`'s own declared tenant field;
-        #   a no-op if nil or absent from `state`
-        # @return [void]
-        # @raise [Runtime::Unauthorized] if a referenced record's own tenant field
-        #   disagrees with `construct`'s
+        # Refuses a write whose record and referenced record disagree about their tenant.
+        # Hooked into `resolve_state_references` so both interpreters are covered.
         def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
           return unless own_tenant_field && state.key?(own_tenant_field)
 
@@ -224,54 +124,16 @@ module Hecks
           end
         end
 
-        # The field an aggregate's own query names as tenant-scoping — the
-        # exact same lookup `Fuzzing::Properties::Guards#tenant_field_for`
-        # already established for the property that found this gap, reused
-        # here rather than reinvented: an aggregate's own declared tenant
-        # field is whichever field one of its own queries names in
-        # `authorize policy, tenant: :field`. `nil` for a construct that
-        # declares no such query — not every aggregate is tenant-scoped,
-        # and an entity never declares a query of its own at all today
-        # (`Entity.queries` is always empty in the real corpus), so this
-        # answers `nil` for every entity without needing to special-case
-        # one.
-        #
-        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
-        #   whose declared queries are searched
-        # @return [Symbol, nil] the tenant-scoping field name, or nil if `construct`
-        #   declares no query with `authorize policy, tenant: :field`
+        # The field a query names in `authorize policy, tenant: :field`, or nil.
         def tenant_field_for(construct)
           authorization = construct.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
         end
 
-        # Renders a reference-typed value as the plain string key its target
-        # record is looked up by.
-        #
-        # `value` is the referenced record's own id, exactly as `Identity.of`
-        # would build it for that record — a bare scalar for a single-field
-        # identity (the overwhelming common case; Banking's own plain
-        # `reference_to Customer` holds one already, so `Value.
-        # materialize_unwrapped` is a no-op passthrough here), or a
-        # `Naming.identity`-joined string for a compound one
-        # (`belongs_to Translation, as: :translation_ref` — Translation's
-        # own `identified_by :domain, :from, :to`, three fields). Without
-        # `materialize_unwrapped`, plain `value.to_s` on that compound case's
-        # own coerced Value would hit Ruby's default `Object#to_s` (a raw,
-        # run-to-run-random memory address) instead of joining the record's
-        # real id — found live via bin/fuzz on the self-hosted "translation"
-        # domain (replay_is_deterministic), the same class of gap `Identity.from`
-        # already had for a compound `identified_by`'s own bare (undotted)
-        # attribute paths. `materialize_unwrapped` recurses a multi-
-        # attribute value object to a plain Hash keyed by attribute name,
-        # in declaration order — `Naming.identity` on `.values` reproduces
-        # the identical join `Identity.of` itself would produce for the
-        # same fields.
+        # Renders a reference value as the string key its target record is looked up by.
         #
-        # @param value [Object] the offered reference value: a `Runtime::Value`, a
-        #   scalar, or anything `Value.materialize_unwrapped` can open
-        # @return [String] the key to look the referenced record up by; empty when
-        #   `value` names no id
+        # A compound identity arrives as a Value; `materialize_unwrapped` is needed so it joins
+        # like `Identity.of` instead of rendering `Object#to_s`.
         def reference_key(value)
           unwrapped = Value.materialize_unwrapped(value)
           return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
@@ -279,56 +141,15 @@ module Hecks
           unwrapped.to_s
         end
 
-        # Hydrates a command argument's own related record, reachable by name
-        # from `given`/`ensures` — `disputed_by.status`, say, `CardPayment
-        # .Dispute`'s own fresh `Reference<Customer>` argument — without
-        # teaching the pure expression evaluator anything about
-        # repositories. The lookup happens here, once, before evaluation;
-        # `Resolver#lookup` just digs into a plain Hash exactly as it
-        # always has.
-        #
-        # `owner` narrowed to `command` only (S12, ADR 0025 — "rules
-        # confined to their own aggregate boundary"): dereferencing the
-        # declaring aggregate/entity's own stored `reference_to` is not part
-        # of this method's job — a cross-aggregate fact a rule needs has to
-        # be a `projects`-maintained local field (`AggregateBuilder#
-        # projects_impl`'s own comment), already present in `subject`'s own
-        # state, no hydration needed, rather than a live query against
-        # another aggregate's own repository on every `given`/`ensures`/
-        # `invariant` run. A reference-typed command argument stays in
-        # bounds, though — the ADR's own boundary list names "its command
-        # arguments" as readable, and nothing is stored yet for a fresh
-        # argument to project from; resolving it once here, synchronous
-        # with this command's own admission, is a different shape from a
-        # live query against an already-persisted reference. `enforce_givens`/
-        # `enforce_ensures` are this method's only two remaining callers,
-        # both passing `command`/`args`, never a `subject`'s own
-        # aggregate — verified by grep, not assumed.
-        #
-        # Recurses into what it finds, so a chain deeper than one hop
-        # still resolves in one pass. Depth-bounded rather than cycle-
-        # detected — nothing in this corpus dots more than two hops on a
-        # fresh argument, and a bound is simpler than tracking visited
-        # (type, id) pairs for a cycle nothing here declares.
+        # Recursion bound; simpler than cycle detection for a cycle no corpus rule declares.
         DEREFERENCE_DEPTH = 4
         private_constant :DEREFERENCE_DEPTH
 
-        # Hydrates `owner`'s own reference-typed attributes into the records they name.
+        # Hydrates reference-typed attributes into the records they name, so `given`/`ensures`
+        # can dot into them. Only command arguments are dereferenced (ADR 0025); a stored
+        # reference must be a `projects` field.
         #
-        # @param domain [String, Symbol] the domain a referenced aggregate is
-        #   resolved in
-        # @param owner [Class, Bluebook::Aggregate, Bluebook::Entity, nil] the
-        #   construct whose reference-typed attributes are dereferenced; nil (or a
-        #   depth of zero) short-circuits to an empty Hash
-        # @param source [Hash{Symbol => Object}] the offered payload to read each
-        #   reference-typed attribute's raw id from
-        # @param depth [Integer] how many more hops to recurse into a resolved
-        #   reference's own reference-typed fields
-        # @return [Hash{Symbol => Object}] one entry per resolved reference-typed
-        #   attribute, keyed by the attribute name with a trailing `_id` stripped,
-        #   valued at the referenced record's state merged with its own dereferenced
-        #   references; an attribute with no id, an unresolvable target, or no
-        #   matching record contributes nothing
+        # @return [Hash{Symbol => Object}] keyed by attribute name with `_id` stripped
         def dereference(domain, owner, source, depth: DEREFERENCE_DEPTH)
           return {} if depth <= 0 || owner.nil?
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -2,8 +2,7 @@ require_relative "../bluebook/expression"
 
 module Hecks
   module Runtime
-    # Persistence-neutral facts derived from a command's existing semantic IR.
-    # This module deliberately does not execute a plan or choose a repository.
+    # Persistence-neutral facts derived from a command's semantic IR; it plans, never executes.
     module DependencyPlanning
       ATOMIC_PUT = :atomic_put
       TRANSACTIONAL_FALLBACK = :load_apply_validate_store
@@ -17,23 +16,18 @@ module Hecks
         :unresolved_dependencies,
         keyword_init: true
       ) do
-        # Reports whether every owner field this command could touch is a known,
-        # deterministic write.
+        # Whether every owner field this command could touch is a known, deterministic write.
         #
         # @return [Boolean] `complete_state`
         def complete_state? = complete_state
 
-        # Reports whether the command needs no prior state at all (implies `complete_state?`).
+        # Whether the command needs no prior state at all (implies `complete_state?`).
         #
         # @return [Boolean] `state_independent`
         def state_independent? = state_independent
 
-        # Chooses the dispatch strategy this plan's proof and the adapter's own
-        # capabilities together allow.
-        #
-        # Capability negotiation is correctness-first: an optimization is
-        # selected only when both the semantic proof and adapter capability
-        # are present. This is planning data only; no runtime path calls it yet.
+        # Chooses the dispatch strategy the plan's proof and the adapter's capabilities allow.
+        # An optimization is selected only when both are present.
         #
         # @param capabilities [Array<String, Symbol>] the repository's declared capabilities
         # @return [Symbol] `DependencyPlanning::ATOMIC_PUT` when the plan is complete,
@@ -47,34 +41,22 @@ module Hecks
         end
       end
 
-      # Walks a canonical expression's parsed nodes (the same AST
-      # Bluebook::Expression::Evaluator evaluates) and collects the
-      # dotted paths it reads — used by Analyzer to classify a
-      # given/ensures/invariant rule's dependencies without evaluating it.
+      # Collects the dotted paths a canonical expression reads, without evaluating it.
+      # Used by Analyzer to classify rule dependencies.
       module ExpressionReads
         module_function
 
-        # Finds every dotted path a canonical expression reads, without evaluating it.
+        # Finds every dotted path a canonical expression reads.
         #
-        # Read the same parsed canonical-expression nodes the evaluator uses.
-        # A generic Struct walk keeps this additive when the expression grammar
-        # gains a composed node; only Lookup nodes carry domain dependencies.
+        # Walks the parsed nodes the evaluator uses; only Lookup nodes carry dependencies.
         #
-        # @param canonical [String] the canonical expression text, such as a rule's `canonical`
+        # @param canonical [String] the canonical expression text
         # @return [Array<String>] the dotted paths the expression reads
         def paths(canonical)
           collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new)
         end
 
-        # Walks one parsed expression node, collecting the dotted paths it reads.
-        #
-        # @param node [Object] a node from `Bluebook::Expression::Evaluator.parse` — a
-        #   `Bluebook::Expression::Resolver::Lookup`, a `Bluebook::Expression::Resolver::
-        #   BlockPredicate`, a `Struct` composed of further nodes, an `Array` of them, or any
-        #   other value (a literal), which contributes no paths
-        # @param bound_names [Set<String>] names locally bound by an enclosing block
-        #   predicate's own parameter, excluded from the result rather than reported as reads
-        # @return [Array<String>] the dotted paths read under `node`, excluding `bound_names`
+        # Walks one parsed node, skipping names bound by an enclosing block predicate.
         def collect(node, bound_names)
           case node
           when Bluebook::Expression::Resolver::Lookup
@@ -93,30 +75,13 @@ module Hecks
         end
       end
 
-      # Static, correctness-first dependency analysis for one command:
-      # walks its mutations, lifecycle transitions, and given/ensures/
-      # invariant rules to derive a Plan (read_set/write_set/
-      # complete_state?/state_independent?) describing what the command
-      # touches without executing it. `Analyzer.call` is what
-      # CommandInterpreter and EntityInterpreter both consult before
-      # choosing a dispatch strategy.
+      # Static dependency analysis for one command: derives a Plan without executing it.
+      # CommandInterpreter and EntityInterpreter consult it before choosing a dispatch strategy.
       class Analyzer
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
-        # `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.
+        # `root_aggregate:` is the owner a `parent.*` read resolves against. An entity-owned
+        # command passes `aggregate:` as the entity, whose fields never include root-level ones.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
         #   is dispatched against; an entity for an entity-owned command
@@ -138,22 +103,9 @@ module Hecks
           @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
-          # as any attribute, even though nothing here writes it via a
-          # declared mutation (`CommandInterpreter#seed_projected_fields`
-          # populates it outside this analysis entirely). Left out of
-          # `known_writes` deliberately: `add_preservation_reads` then
-          # correctly treats it as a prior-state read that must survive
-          # 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).
+          # `projects` fields are owner state: a rule reading one reads this record's stored
+          # field. Left out of `known_writes` so `add_preservation_reads` keeps it as a read;
+          # the interpreter reseeds it on save. `parent.*` reads may name the root's too.
           aggregate.projected_fields.each { |field| @owner_fields << field.name } if aggregate.respond_to?(:projected_fields)
           if root_aggregate.respond_to?(:projected_fields)
             root_aggregate.projected_fields.each do |field|
@@ -198,10 +150,8 @@ module Hecks
         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
-        # record. Keep this aligned with Instance.defaults/default_for. They
-        # establish completeness but are not command mutations, so they do not
-        # appear in write_set.
+        # A fresh Instance supplies these values without a stored record; keep aligned with
+        # Instance.defaults/default_for. They are not command mutations, so not in write_set.
         def analyze_initial_state
           aggregate.attributes.each do |attribute|
             known_writes << attribute.name if deterministic_initial_value?(attribute)
@@ -239,8 +189,7 @@ module Hecks
           end
         end
 
-        # Returns true only when the source is known without prior aggregate
-        # state. Hash sources are the canonical append binding shape.
+        # True only when the source is known without prior state. Hash sources are append bindings.
         def analyze_source?(source)
           case source
           when Symbol
@@ -282,34 +231,16 @@ 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.
+        # Gap: the `as:` name bound by `corrects` is not special-cased like `:old`/`:parent`, so a
+        # rule reading it lands in `unresolved` and dispatch takes the safe `hydrate_existing`
+        # path. Runtime binding is unaffected.
         def classify_path(path, phase)
           head, nested = path.split(".", 2)
           name = head.to_sym
 
           if name == :parent
-            # `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.
+            # `parent.X` names the root aggregate's field, not the entity's `owner_fields`;
+            # the two sets are identical for a plain aggregate command.
             resolve_nested_state_read!(path, nested, root_owner_fields, "does not name parent aggregate state")
           elsif name == :old
             resolve_nested_state_read!(path, nested, owner_fields, "does not name prior aggregate state")
@@ -322,10 +253,8 @@ module Hecks
           end
         end
 
-        # Shared shape behind the `:parent`/`:old` branches above: read the
-        # nested field name, check it against the given owner field set
-        # (deliberately different sets for `parent`/`old` — see the caller),
-        # and either record it as a state read or refuse with `message`.
+        # Shared by the `:parent`/`:old` branches: checks the nested field against `field_set`
+        # and records a state read, or refuses with `message`.
         def resolve_nested_state_read!(path, nested, field_set, message)
           field = nested.to_s.split(".", 2).first
           if field.empty? || !field_set.include?(field.to_sym)
@@ -335,9 +264,8 @@ module Hecks
           end
         end
 
-        # A partial mutation must preserve every untouched field on the
-        # correctness path. Those prior values are real reads even when no rule
-        # names them. A deterministic write needs no preservation read.
+        # A partial mutation must preserve every untouched field, so those prior values are
+        # reads even when no rule names them.
         def add_preservation_reads
           state_reads.merge(owner_fields - known_writes)
         end