hecks 1.4.0 → 1.5.1

data/lib/hecks/query_ir.rb

@@ -37,6 +37,11 @@ module Hecks
 
     module_function
 
+    # Reads the fields the language declares for one construct kind, from the grammar itself.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Array<Symbol>] the attribute names the self-hosted meta-domain
+    #   grammar declares for `name`
     def meta_declared(name)
       Hecks::Bluebook::MetaValidator.grammar_registry
                                     .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
@@ -47,6 +52,11 @@ module Hecks
     # for it — the same comparison spec/model_shape_conformance_spec.rb
     # makes, reusing its own Deviations data so this can never silently
     # drift from what that gate actually checks.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Hash{Symbol => Object}] `:name`, `:declared`, `:emitted`, plus
+    #   `:missing_from_ruby` and `:unaccounted_in_ruby` — each an `Array<Symbol>`
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def construct_diff(name)
       klass = CONSTRUCTS.fetch(name) do
         raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
@@ -72,6 +82,10 @@ module Hecks
         missing_from_ruby: accounted - emitted, unaccounted_in_ruby: unaccounted }
     end
 
+    # Diffs one or every construct kind at once.
+    #
+    # @param names [Array<String>] `CONSTRUCTS` keys to diff, every construct when empty
+    # @return [Array<Hash>] one `construct_diff` result per name
     def constructs(names = [])
       targets = names.empty? ? CONSTRUCTS.keys : names
       targets.map { |name| construct_diff(name) }
@@ -96,6 +110,10 @@ module Hecks
     # already a distinct object, whether it was block-declared or
     # bare-referenced — object identity carries no signal past that
     # point, for any construct, not just this one).
+    #
+    # @param registry [Runtime::Registry] the booted registry to walk
+    # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+    # @return [Array<Rule>]
     def collect_rules(registry, chapter_name = nil)
       rules = []
       chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
@@ -158,6 +176,10 @@ module Hecks
     # local_givens` reads it directly to group `collect_rules`' own
     # output by owner itself, the same reading `duplicates`' own
     # `declaration_count` makes.
+    #
+    # @param location [String] a `Rule#location`
+    # @return [String] the owning construct's path, with `" (declared)"` or a trailing
+    #   `.CommandName` segment stripped
     def owner_of(location)
       return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
 
@@ -188,6 +210,12 @@ module Hecks
     # `domains: []` means "the self-hosted meta-domain only" — pass real
     # domain directories explicitly to include them, or `nil` (the
     # default) for meta-domain plus every real example.
+    #
+    # @param domains [Array<String>, nil] domain root directories to scan; every real
+    #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
+    # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
+    # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
+    #   `:canonical`, and `:locations` (`Array<String>`)
     def duplicates(domains: nil, include_meta: true)
       domains ||= Codemod::EXAMPLE_ROOTS
       all_rules = []
@@ -260,6 +288,9 @@ module Hecks
     # case above, before assuming a group naming two pieces under
     # different aggregates is fresh duplication rather than an already-
     # resolved chapter-wide reference.
+    #
+    # @param rules [Array<Rule>] one duplicate-key group's own rules
+    # @return [Integer] how many of `rules` are real, independent declarations
     def declaration_count(rules)
       declared = rules.select { |r| r.location.end_with?(" (declared)") }
       declared_owners = declared.to_set { |r| owner_of(r.location) }
@@ -282,6 +313,8 @@ module Hecks
     # `bin/hecks_query_ir_mcp` (an MCP tool result, itself a text
     # block) want the identical human-readable rendering; only the
     # outer framing differs (plain stdout vs. a JSON-RPC content array).
+    # @param diffs [Array<Hash>] `constructs`' own output
+    # @return [String] the human-readable rendering
     def format_constructs(diffs)
       diffs.map do |diff|
         lines = ["== #{diff[:name]} =="]
@@ -328,6 +361,12 @@ module Hecks
     # existing gate (`model_shape_conformance_spec.rb`,
     # `assembly_spec.rb`, `meta_domain_coverage_spec.rb`) before trusting
     # a `false` here as a real gap.
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @param field [String, Symbol] the declared field to check propagation for
+    # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
+    #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
+    #   touchpoint does not apply to `name`)
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def impact_preview(name, field)
       CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}" }
       field = field.to_s
@@ -402,6 +441,10 @@ module Hecks
     end
     private_class_method :rust_mentions?
 
+    # Renders one field's touchpoint checklist as text.
+    #
+    # @param preview [Hash] `impact_preview`'s own output
+    # @return [String] the human-readable rendering
     def format_impact_preview(preview)
       lines = ["== #{preview[:name]}##{preview[:field]} =="]
       preview[:touchpoints].each do |t|
@@ -421,6 +464,10 @@ module Hecks
       lines.join("\n")
     end
 
+    # Renders the duplicate-rule groups as text.
+    #
+    # @param groups [Array<Hash>] `duplicates`' own output
+    # @return [String] the human-readable rendering
     def format_duplicates(groups)
       return "no duplicate given/invariant/ensures rule found" if groups.empty?
 

data/lib/hecks/query_specification/common/null_policy.rb

@@ -22,7 +22,8 @@ module Hecks
         # `field DESC, id DESC`.
         #
         # @param records [Array<Object>] the rows to order, already in identity order
-        # @param direction [Symbol, String] `desc` sorts descending; anything else ascending
+        # @param direction [Symbol, String] `desc` in any letter case sorts descending;
+        #   anything else ascending
         # @param policy [NullSemantics, nil] where nulls go: mode `first` or `last`; `nil` or
         #   any other mode (`native`) puts nulls first ascending and last descending
         # @yield reads the sort key out of one record
@@ -32,16 +33,17 @@ module Hecks
         # @return [Array<Object>] a new Array holding every record in the requested order
         # @raise [ArgumentError] if two non-nil keys cannot be compared with each other
         def order(records, direction:, policy: nil, &key)
+          descending = direction.to_s.downcase == "desc"
           null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
           sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
-          if direction.to_s == "desc"
+          if descending
             sorted.reverse!
             null_rows.reverse!
           end
           case policy&.mode.to_s
           when "first" then null_rows + sorted
           when "last" then sorted + null_rows
-          else direction.to_s == "desc" ? sorted + null_rows : null_rows + sorted
+          else descending ? sorted + null_rows : null_rows + sorted
           end
         end
 

data/lib/hecks/rendering.rb

@@ -17,6 +17,12 @@ module Hecks
   module Rendering
     module_function
 
+    # Renders a value the way it should read inside a refusal message.
+    #
+    # @param value [Object] the value to render
+    # @return [String] `"nil"` for nil, JSON for a Hash/Array or a duck-typed value
+    #   object (unwrapped to its bare scalar when it has exactly one field), or
+    #   `value.inspect` for anything else
     def describe(value)
       case value
       when nil then "nil"

data/lib/hecks/router/namespace_installer.rb

@@ -12,6 +12,13 @@ module Hecks
       # to the router, pinned to this specific FQN version rather than
       # the router's default resolution.
       class OptionsProxy
+        # @param router [Router] router to dispatch resolved calls through
+        # @param realm [String, nil] realm segment of the FQN this proxy pins
+        # @param domain [String] domain segment of the FQN this proxy pins
+        # @param aggregate [String, nil] aggregate segment, or nil for a domain-level query
+        # @param options [Hash{Symbol => Object}] the `.options(...)` call's keywords; only
+        #   `:version` is accepted
+        # @raise [ArgumentError] if `options` has a key other than `:version`
         def initialize(router:, realm:, domain:, aggregate:, options:)
           unknown = options.keys - [:version]
           raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
@@ -45,10 +52,16 @@ module Hecks
         end
       end
 
+      # @param router [Router] router whose current routes get Ruby constants and methods
       def initialize(router)
         @router = router
       end
 
+      # Installs every current-version route as a namespace constant/method,
+      # plus the aggregate `find`/`all`/`count`/`events`/`repository` door and
+      # short `Aggregate.verb` shortcuts.
+      #
+      # @return [self]
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!

data/lib/hecks/router.rb

@@ -9,31 +9,60 @@ module Hecks
 
     attr_reader :register
 
+    # Loads a project's bluebooks and builds a router over them, without
+    # installing any Ruby namespace shortcuts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the built router
     def self.load(root) = new(Bluebook::ProjectLoader.load(root))
 
     # Install one project router for ordinary application calls. The explicit
     # `Router.load` API remains useful for tests and embedded hosts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the booted router, also stored as `.default`
     def self.boot(root)
       router = load(root)
       router.install_namespace!
       @default = router
     end
 
+    # The process-wide router `.boot` installed.
+    #
+    # @return [Router] the router `.boot` installed
+    # @raise [NotBooted] if `.boot` has not been called yet
     def self.default
       @default || raise(NotBooted, "no project router is booted — call Hecks::Router.boot(root) first")
     end
 
+    # (see #dispatch)
     def self.dispatch(address, **args) = default.dispatch(address, **args)
+    # (see #query)
     def self.query(address, **args)    = default.query(address, **args)
 
+    # @param register [Bluebook::ProjectRegister, Bluebook::ProjectLoader] the FQN
+    #   catalogue to resolve addresses against
     def initialize(register)
       @register = register
     end
 
+    # Lists every routed FQN entry.
+    #
+    # @return [Array<Bluebook::ProjectRegister::Entry>] every routed FQN entry
     def available = register.entries.values
 
+    # Installs Ruby namespace constants and shortcut methods for every
+    # current-version route.
+    #
+    # @return [NamespaceInstaller] the installer that performed the install
     def install_namespace! = NamespaceInstaller.new(self).install!
 
+    # Resolves an address to its routed FQN entry.
+    #
+    # @param address [String] a fully-qualified command or query address, realm included
+    # @return [Bluebook::ProjectRegister::Entry] the routed entry
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [Fqn::Invalid] if `address` is not a well-formed FQN
     def resolve(address)
       fqn = Fqn.parse(address)
       raise UnknownAddress, "router addresses require a realm: #{address.inspect}" unless fqn.realm
@@ -43,6 +72,19 @@ module Hecks
       raise UnknownAddress, "no Bluebook route for #{address.inspect}"
     end
 
+    # Dispatches a command to its resolved aggregate.
+    #
+    # @param address [String] a fully-qualified command address, realm included
+    # @param args [Hash] command facts, plus the dispatcher's optional `:to`, `:with`,
+    #   and `:saga_correlation` keys
+    # @return [Runtime::Dispatcher::Result] the dispatch result
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a query
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
+    #   the call
+    # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def dispatch(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a query; use #query" unless entry.command?
@@ -50,6 +92,19 @@ module Hecks
       entry.dispatcher.dispatch_flat(local_verb(entry), args)
     end
 
+    # Queries a resolved aggregate, entity, or read model.
+    #
+    # @param address [String] a fully-qualified query address, realm included
+    # @param args [Hash{Symbol => Object}] the query's declared arguments
+    # @return [Array<Hash>] one row Hash per match; see `Runtime::Dispatcher#query`
+    #   for the exact shape per address kind
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a command
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [Runtime::NotFound] if a read model's root reference names no record
+    # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+    # @raise [KeyError] if a rooted read model is asked without its reference argument
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def query(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a command; use #dispatch" unless entry.query?

data/lib/hecks/runtime/aggregate_lock.rb

@@ -29,12 +29,21 @@ module Hecks
       @locks = {}
 
       class << self
+        # Returns the Mutex striped to one record, creating it on first use.
+        #
         # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
         # `id: nil` — identity could not be resolved yet (see
         # `Identity.best_effort`) — locks by aggregate type alone, coarser
         # (every record of this aggregate serializes against every other)
         # but still correct: it can only ever make dispatch more
         # conservative than a resolved id would.
+        #
+        # @param domain [String] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate being dispatched
+        # @param id [String, nil] the resolved record id, or nil to stripe by aggregate type
+        #   alone
+        # @return [Mutex] the mutex for this `[domain, aggregate, id]` key, held for the full
+        #   hydrate-through-save critical section
         def for(domain, aggregate, id = nil)
           key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
           @registry_lock.synchronize { @locks[key] ||= Mutex.new }

data/lib/hecks/runtime/boot_gates.rb

@@ -20,19 +20,37 @@ module Hecks
     # Sharing a primitive between them is deferred until a third consumer
     # actually wants it (0031's own Rejected Alternatives).
     class BootGates
+      # @return [void]
       def initialize
         @gates = Hash.new { |h, k| h[k] = [] }
       end
 
+      # Adds a gate to `phase`, run in registration order alongside any other gate there.
+      #
+      # @param name [Symbol] the gate's name, checked by `registered?`
+      # @param gate [Proc, Method] the gate; called as `gate.call(registry, directory)`
+      # @param phase [Symbol] the phase this gate runs under, such as `:pre_verify` or
+      #   `:post_verify`
+      # @return [Hecks::Runtime::BootGates] self, for chaining
       def register(name, gate, phase:)
         @gates[phase] << [name, gate]
         self
       end
 
+      # Reports whether a gate named `name` has been registered, under any phase.
+      #
+      # @param name [Symbol] the gate name to look for, across every phase
+      # @return [Boolean] true if a gate named `name` was registered under any phase
       def registered?(name)
         @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
       end
 
+      # Runs every gate registered under `phase`, in registration order.
+      #
+      # @param phase [Symbol] the phase to run, such as `:pre_verify` or `:post_verify`
+      # @param registry [Runtime::Registry] the booted registry, passed to each gate
+      # @param directory [String] the boot directory, passed to each gate
+      # @return [void]
       def run!(phase, registry, directory)
         @gates[phase].each { |pair| pair.last.call(registry, directory) }
       end

data/lib/hecks/runtime/caller.rb

@@ -37,8 +37,34 @@ module Hecks
 
       module_function
 
+      # The ambient caller bound by the innermost enclosing `as` block on this thread.
+      #
+      # @return [Runtime::Caller::Current, nil] the bound caller, or nil when no `as`
+      #   block is on the stack for this thread
       def current = Thread.current[:hecks_caller]
 
+      # Binds the ambient caller for the duration of the block, restoring whatever
+      # caller (if any) was bound before, even if the block raises.
+      #
+      # `actor_id`, `as_of` and `scope` are each optional, self-asserted facts about
+      # the caller rather than derived from the command — see `Current`'s own header
+      # above for why each stays here instead of becoming a command-level DSL
+      # construct.
+      #
+      # @param role [String] the role the caller states it holds, checked by string
+      #   equality against the command's declared `role`
+      # @param actor_id [String, nil] who the caller is; when given, lets
+      #   `CommandRules::Authorization` check a real Governance `RoleAssignment`
+      #   instead of the bare role-string comparison
+      # @param as_of [Integer, nil] Unix epoch seconds the caller asserts as "now",
+      #   filled at the door from `Ports::Clock.now`; nil leaves a `RoleAssignment`'s
+      #   `starts_at` unchecked
+      # @param scope [String, nil] the scope the caller states it is acting in,
+      #   checked against the matching `RoleAssignment`'s own `scope`; nil skips
+      #   that check
+      # @yield the code that should see `role`/`actor_id`/`as_of`/`scope` as the
+      #   ambient caller
+      # @return [Object] the block's result
       def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = Current.new(
@@ -49,11 +75,17 @@ module Hecks
         Thread.current[:hecks_caller] = previous
       end
 
+      # Clears the ambient caller for the duration of the block, restoring
+      # whatever caller (if any) was bound before, even if the block raises.
+      #
       # A reaction is the system acting, not the caller who happened to be
       # on the stack when the triggering command ran — `Dispatcher#reenter`
       # clears the ambient caller around a reaction's own dispatch so a
       # triggering caller's role can neither satisfy nor block a reaction
       # command it has nothing to do with.
+      #
+      # @yield the code that should see no ambient caller bound
+      # @return [Object] the block's result
       def without
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = nil

data/lib/hecks/runtime/capability_graph.rb

@@ -14,6 +14,8 @@ module Hecks
     # adapter names the port it implements, and neither can point at a third
     # port. There is no edge for a cycle to be made of.
     class CapabilityGraph
+      # @param registry [Runtime::Registry] the booted registry to read ports and adapters from
+      # @return [void]
       def initialize(registry)
         @registry = registry
       end
@@ -21,6 +23,9 @@ module Hecks
       # { port name => [adapter name, ...] }, for every port the registry
       # declares — including the ports nothing implements, so a caller can
       # tell "declared, unfulfilled" from "never declared at all".
+      #
+      # @return [Hash{String => Array<String>}] each declared port's name mapped to the names
+      #   of every adapter bound to it (empty when none are)
       def fulfillments
         @fulfillments ||= @registry.ports.each_key.to_h { |name| [name, adapters_for(name)] }
       end
@@ -28,10 +33,16 @@ module Hecks
       # The ports with zero adapters bound — the gap `Runtime::WiringError`
       # would otherwise only surface at the moment something tries to dispatch
       # through one.
+      #
+      # @return [Array<String>] the names of every declared port with no adapter bound to it
       def unfulfilled
         fulfillments.select { |_, adapters| adapters.empty? }.keys
       end
 
+      # Reports the port-dependency cycles this registry has — always none; see the module
+      # header for why no port model here can express one.
+      #
+      # @return [Array] always empty
       def cycles = []
 
       private

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -10,10 +10,10 @@ module Hecks
       module ArgumentGate
         private
 
-        # Anything else used to ride along in the payload untouched —
-        # normalize_args walks the declared attributes, so a name the command
-        # never had was simply never looked at. A misspelled argument did
-        # nothing, in silence.
+        # Without this check, anything else would ride along in the payload
+        # untouched — normalize_args walks only the declared attributes, so
+        # a name the command never had is simply never looked at, and a
+        # misspelled argument would do nothing, in silence.
         #
         # The keys that are legitimately not attributes are the ones that address
         # the aggregate rather than describe it : `id`, whatever the aggregate is
@@ -49,12 +49,13 @@ module Hecks
         # until fuzz went looking : a name the command never declared was refused,
         # while a name it did declare could simply be left out.
         #
-        # `Customer.Register` without its `name` used to be refused — but by
-        # accident, and with a lie for a message. `then_set :name, to: :name` found
-        # nothing to resolve, passed the literal symbol on, and coercion reported
-        # `name is a PersonName — pass its fields as an object`, which describes a
-        # mistake the caller did not make. The real mistake — an argument simply
-        # missing — was never the one named, and nothing refused it on purpose.
+        # Refusing `Customer.Register` for a missing `name` needs to be
+        # deliberate, not an accident with a lie for a message. Without this
+        # check, `then_set :name, to: :name` finds nothing to resolve, passes
+        # the literal symbol on, and coercion reports `name is a PersonName —
+        # pass its fields as an object`, which describes a mistake the caller
+        # did not make. The real mistake — an argument simply missing — is
+        # never the one named unless this refuses it on purpose.
         #
         # No command attribute anywhere in the corpus carries a default — checked,
         # all eight chapters, zero — so there is no optional argument for this to
@@ -65,16 +66,17 @@ module Hecks
         # (`CommandBuilder#reference_to`'s bare self-reference mints no
         # attribute to be absent) — but `PortOperationBuilder#reference_to`
         # always mints one (this file's own header on `PortOperation`: "no
-        # creates?/acts_on distinction to protect"), because an operation
-        # historically had no other way to say which record it addressed.
-        # `to:` is that other way now (`Dispatcher#port_invocation`
-        # promotes the identity attribute's own value out of the payload
-        # and into routing) — which left the attribute still declared,
-        # still non-optional, and now never present in `args` at all: every
-        # operation with an identity attribute refused its own well-formed
-        # calls, dispatched exactly the way `to:` intends. Exempted here on
-        # the same terms an aggregate command's self-address always was —
-        # an address, not a fact the operation still needs handed back.
+        # creates?/acts_on distinction to protect"), because an operation had
+        # no other way to say which record it addressed before `to:` existed.
+        # `to:` is that way now (`Dispatcher#port_invocation` promotes the
+        # identity attribute's own value out of the payload and into
+        # routing) — which leaves the attribute still declared, still
+        # non-optional, and never present in `args` at all: without this
+        # exemption, every operation with an identity attribute would refuse
+        # its own well-formed calls, dispatched exactly the way `to:`
+        # intends. Exempted here on the same terms an aggregate command's
+        # self-address always was — an address, not a fact the operation
+        # still needs handed back.
         def refuse_absent_arguments(command, args, aggregate: nil)
           given    = args.keys.map(&:to_sym)
           exempt   = aggregate && command.respond_to?(:identity_attribute) &&
@@ -92,7 +94,7 @@ module Hecks
                                            declared: declared_names(command))
         end
 
-        # **A command that declares nothing still has to say so**. `Account
+        # A command that declares nothing still has to say so. `Account
         # .Freeze` is `reference_to Account` and no attributes at all, so
         # `{declared}` rendered empty and the sentence trailed off mid-
         # clause : "Freeze does not declare standing — it takes ". Read

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -165,9 +165,9 @@ module Hecks
                                      fields)
                     end
 
-          # Frozen, like every other value the domain hands back. An
-          # appended list used to come back mutable, so a caller could
-          # push straight into an aggregate's own state after the
+          # Frozen, like every other value the domain hands back — without
+          # this, an appended list would come back mutable, letting a
+          # caller push straight into an aggregate's own state after the
           # dispatch had finished.
           Freezer.deep(Array(instance[mutation.target]) + [element])
         end
@@ -197,11 +197,11 @@ module Hecks
 
         # Vendored fix, not (yet) upstream hecks (migration plan
         # task 9): #apply's `:increment`/`:decrement`/`:multiply`
-        # branches used to wrap `amount` into a `Value` unconditionally
+        # branches wrapping `amount` into a `Value` unconditionally
         # whenever the target attribute existed, never checking whether
         # `current` (the field's own existing value, read straight off
-        # `instance[mutation.target]`) was also wrapped -- the two sides
-        # of the same arithmetic call could disagree on Value-ness. On a
+        # `instance[mutation.target]`) was also wrapped, would let the two
+        # sides of the same arithmetic call disagree on Value-ness. On a
         # phantom-created field this is the common case, not an edge
         # one: `Instance.defaults`/`#default_for` leaves a VO-typed
         # attribute with no declared `default:` genuinely absent (nil),
@@ -276,16 +276,15 @@ module Hecks
           held.max.to_i + 1
         end
 
-        # Moved to `EntityElement.check_entity_collision` (entity_element.rb)
-        # — BUG#145. Used to live here, called only from `#entity_element`
-        # above (an aggregate's own entity list, e.g. `Workspace.boards`).
+        # The entity-collision check lives in `EntityElement.check_entity_collision`
+        # (entity_element.rb) — BUG#145 — shared by both `#entity_element` above
+        # (an aggregate's own entity list, e.g. `Workspace.boards`) and
         # `EntityElement#appended_to_element`'s own nested-entity branch (an
-        # entity's own entity list one hop further in, e.g. `Board.cards`)
-        # needs the exact same guard — see that method's own call site and
-        # comment for why a caller-supplied nested identity was silently
-        # duplicating before this moved. Pure relocation, not a behavior
-        # change here: the check's own doc comment (heads/composite/
-        # auto-mint reasoning) now lives with the code, in entity_element.rb.
+        # entity's own entity list one hop further in, e.g. `Board.cards`),
+        # which needs the exact same guard against a caller-supplied nested
+        # identity silently duplicating. See that method's own call site and
+        # comment; the check's own doc comment (heads/composite/auto-mint
+        # reasoning) lives with the code, in entity_element.rb.
       end
     end
   end