hecks 1.3.0 → 1.5.0

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

@@ -7,7 +7,7 @@ require_relative "../../ports/query/in_memory"
 module Hecks
   module Runtime
     class CommandRules
-      # A reference must point at something that EXISTS.
+      # 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 :
@@ -16,13 +16,22 @@ module Hecks
       # no corpus step ever passed a dangling reference.
       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
+        # 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.
         #
         # 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
         def resolve_references(domain, command, args)
           command.attributes.each do |attribute|
             next unless attribute.reference?
@@ -41,6 +50,20 @@ module Hecks
         # 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.
+        #
+        # @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
         def resolve_state_references(domain, construct, state)
           own_tenant_field = tenant_field_for(construct)
 
@@ -73,6 +96,14 @@ module Hecks
         # 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
         def validate_relationship_cardinality(construct, attribute, held)
           return if attribute.relationship.nil? || attribute.list?
           return unless held.nil? && !attribute.optional?
@@ -83,16 +114,32 @@ 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. This used to regex the target's
-        # name out of "Reference<Customer>" and then search
-        # `registry.bluebook(domain).aggregates` for it — and later reached the
-        # target through Ruby's constant tree, a class thrown away for its `.ir`
-        # the moment it was found.
+        # 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.
+        #
+        # @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
         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|
@@ -101,37 +148,53 @@ module Hecks
             next if @registry.repository(domain, target).find(key)
 
             raise NotFound,
-                  RefusalWording.render("NotFound", "reference_target_missing",
-                                        target: target.name, heads: target.identity_heads.join(", "),
-                                        key: key.inspect)
+                  RefusalWording.render_site("NotFound", "reference_target_missing",
+                                             target: target.name, heads: target.identity_heads.join(", "),
+                                             key: key)
           end
         end
 
-        # ANGLE-8's OWN WRITE-SIDE HALF of `TenantScope.apply` (runtime/
-        # tenant_scope.rb) — the QUERY-side mechanism this mirrors. That
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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,
+        # 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
+        # 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
         def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
           return unless own_tenant_field && state.key?(own_tenant_field)
 
@@ -152,50 +215,63 @@ module Hecks
             next if target_tenant == own_tenant
 
             raise Unauthorized,
-                  RefusalWording.render("Unauthorized", "cross_tenant_reference",
-                                        aggregate: construct.hecks_name, field: own_tenant_field,
-                                        tenant: Rendering.describe(state[own_tenant_field]),
-                                        attribute: attribute.name, target: target.name,
-                                        target_field: target_tenant_field,
-                                        other: Rendering.describe(record.state[target_tenant_field]))
+                  RefusalWording.render_site("Unauthorized", "cross_tenant_reference",
+                                             aggregate: construct.hecks_name, field: own_tenant_field,
+                                             tenant: Rendering.describe(state[own_tenant_field]),
+                                             attribute: attribute.name, target: target.name,
+                                             target_field: target_tenant_field,
+                                             other: Rendering.describe(record.state[target_tenant_field]))
           end
         end
 
-        # THE FIELD AN AGGREGATE'S OWN QUERY NAMES AS TENANT-SCOPING — the
+        # 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
+        # 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`
         def tenant_field_for(construct)
           authorization = construct.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
         end
 
-        # `value` is the referenced record's own id, EXACTLY as `Identity.of`
+        # 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). Before
-        # this, plain `value.to_s` on that compound case's own coerced
-        # Value 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`
+        # 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.
+        # same fields.
+        #
+        # @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
         def reference_key(value)
           unwrapped = Value.materialize_unwrapped(value)
           return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
@@ -203,35 +279,33 @@ module Hecks
           unwrapped.to_s
         end
 
-        # A COMMAND ARGUMENT's own related record, reachable by name from
-        # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
+        # 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;
+        # 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
+        # `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` used to
-        # be the other half of this method's job — a live query against
-        # another aggregate's own repository, every time a `given`/
-        # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
-        # fact a rule needs now has to be a `projects`-maintained LOCAL
-        # field (`AggregateBuilder#projects_impl`'s own comment), already
-        # present in `subject`'s own state, no hydration needed. 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`/
+        # 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 before this comment was written, not
-        # assumed.
+        # aggregate — verified by grep, not assumed.
         #
-        # RECURSES into what it finds, so a chain deeper than one hop
+        # 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
@@ -239,6 +313,22 @@ module Hecks
         DEREFERENCE_DEPTH = 4
         private_constant :DEREFERENCE_DEPTH
 
+        # Hydrates `owner`'s own reference-typed attributes into the records they name.
+        #
+        # @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
         def dereference(domain, owner, source, depth: DEREFERENCE_DEPTH)
           return {} if depth <= 0 || owner.nil?
 

data/lib/hecks/runtime/command_rules.rb

@@ -20,6 +20,9 @@ module Hecks
 
       attr_reader :registry
 
+      # @param registry [Runtime::Registry, nil] the booted registry the rules read bluebooks,
+      #   repositories and the event log from; nil serves only the rules that read no
+      #   registry, such as `sign_of`
       def initialize(registry)
         @registry = registry
       end

data/lib/hecks/runtime/dependency_planning.rb

@@ -17,12 +17,28 @@ module Hecks
         :unresolved_dependencies,
         keyword_init: true
       ) do
+        # Reports 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?`).
+        #
+        # @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.
+        #
+        # @param capabilities [Array<String, Symbol>] the repository's declared capabilities
+        # @return [Symbol] `DependencyPlanning::ATOMIC_PUT` when the plan is complete,
+        #   state-independent, and the adapter declares that capability;
+        #   `DependencyPlanning::TRANSACTIONAL_FALLBACK` otherwise
         def strategy_for(capabilities: [])
           return TRANSACTIONAL_FALLBACK unless complete_state? && state_independent?
           return TRANSACTIONAL_FALLBACK unless capabilities.map(&:to_sym).include?(ATOMIC_PUT)
@@ -38,13 +54,27 @@ module Hecks
       module ExpressionReads
         module_function
 
+        # Finds every dotted path a canonical expression reads, without evaluating it.
+        #
         # 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.
+        #
+        # @param canonical [String] the canonical expression text, such as a rule's `canonical`
+        # @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`
         def collect(node, bound_names)
           case node
           when Bluebook::Expression::Resolver::Lookup
@@ -74,12 +104,12 @@ module Hecks
         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,
+        # 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
+        # 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 —
+        # `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
@@ -87,8 +117,20 @@ module Hecks
         # unresolved regardless of correctness. Defaults to `aggregate`
         # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
         # own call site never needed to change.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against; an entity for an entity-owned command
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate a `parent.*` read
+        #   resolves against; defaults to `aggregate` for a plain-aggregate command
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
 
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate `parent.*` reads
+        #   resolve against; defaults to `aggregate`
         def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
@@ -96,10 +138,10 @@ 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
+          # `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
+          # 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
@@ -107,7 +149,7 @@ 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
+          # 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_
@@ -126,6 +168,9 @@ module Hecks
           @unresolved = Set.new
         end
 
+        # Runs the analysis and derives the command's dependency plan.
+        #
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def call
           analyze_initial_state
           analyze_mutations
@@ -237,7 +282,7 @@ module Hecks
           end
         end
 
-        # KNOWN, HARMLESS GAP: `corrects ..., as: :name`'s bound name
+        # 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
@@ -247,7 +292,7 @@ module Hecks
         # `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,
+        # 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
@@ -258,9 +303,9 @@ module Hecks
           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
+            # `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