hecks 2.7.0 → 2.9.0

data/lib/hecks/runtime/event.rb

@@ -2,32 +2,10 @@ require "time"
 
 module Hecks
   module Runtime
-    # `correlation` is not on the wire — `to_h` below deliberately omits it,
-    # the same as `bin/run`'s own event projection does. It is runtime
-    # bookkeeping stamped by `Dispatcher#dispatch` when a saga leg's own
-    # dispatch causes this event (see `SagaInterpreter#deliver_saga_dispatch`
-    # and `#saga_correlation`) : a Hash of `correlation_head` -> correlation
-    # value, so an event caused by one saga cannot be misread by an unrelated
-    # one correlating on a different field. Absent for any event no saga
-    # dispatch caused, which is most of them.
+    # An emitted domain event. `correlation` (saga head -> value) is runtime bookkeeping
+    # and deliberately absent from `to_h`.
     Event = Struct.new(:name, :aggregate, :id, :payload, :occurred_at, :correlation, keyword_init: true) do
-      # Freezes the event deep, so nothing about it can change after it happens.
-      #
-      # An emitted event is a record of something that happened, and a
-      # mutable audit trail is not one. The payload — the domain fact the
-      # event carries — is frozen through on emission: freezing the Hash
-      # alone would leave every value in it editable in place, which is
-      # the shape all four previous freezing bugs had.
-      #
-      # The whole event, not just its payload. Correlation is set at
-      # construction rather than merged in here by `Dispatcher#dispatch`
-      # after the event already exists, because it is part of the
-      # transaction and known from `dispatch`'s own argument before
-      # anything is emitted — that is what keeps an event immutable once
-      # it exists.
-      #
-      # The log stays appendable: new events are still recorded. It is
-      # each event that stops changing once it exists.
+      # Freezes the event deep, payload and correlation included.
       #
       # @return [void]
       def emit!

data/lib/hecks/runtime/identity.rb

@@ -3,58 +3,21 @@ require_relative "value"
 
 module Hecks
   module Runtime
-    # **The scalar an identity path names**.
-    #
-    # An identity is declared as a path — `identified_by :number` — and
-    # this is the one place that reads one. It follows the path and nothing else.
-    #
-    # What it replaced was `Value.identifier`, which opened a one-field value
-    # object and took whatever was inside : that let `identified_by :number` pass
-    # for an identity, with the runtime guessing which field had been meant. The
-    # guess is gone. A declaration that names no field is now refused when the
-    # bluebook loads (`an aggregate that is identified names a field`, `an entity
-    # is known by a field`), so by the time anything is dispatched there is
-    # always a path here to follow.
-    #
-    # Usage:
-    #
-    #   Identity.scalar("number.value", account_number_value_object)  # => "acct-1"
+    # Resolves an aggregate's or entity's identity string from a command payload.
     #
+    # Identity.scalar("number.value", account_number_value_object)  # => "acct-1"
     module Identity
       module_function
 
-      # Reads one key off `hash` by whichever of its Symbol/String spelling
-      # is actually present, favoring the Symbol spelling.
-      #
-      # A hash read that decides which spelling of a key answers by
-      # presence, never by `||` — a bare `||` treats a genuinely-held
-      # `false` the same as an absent key and falls through to the other
-      # spelling, landing on `nil` instead of the real, stored answer.
-      #
-      # @param hash [Hash] the hash to read, potentially keyed by either spelling
-      # @param key [String, Symbol] the key to look up
-      # @return [Object, nil] the value under `key.to_sym` if that key is present,
-      #   otherwise the value under `key` as given; nil if neither is a key of `hash`
+      # Reads `key` from `hash` by whichever Symbol/String spelling is present.
+      # Presence decides, not `||`, so a held `false` is not mistaken for absent.
       def hash_lookup(hash, key)
         sym = key.to_sym
         hash.key?(sym) ? hash[sym] : hash[key]
       end
 
-      # Digs `path`'s fields out of `held`, past the head a caller already
-      # consumed to look `held` up.
-      #
-      # The head names the attribute and is consumed by whoever looked the value
-      # up; what is left is the walk down into it. A path with no fields to walk
-      # — an aggregate that declares no identity and falls back to `id` — hands
-      # back what it was given, because there is nothing declared to dig for.
-      #
-      # @param path [String, Symbol] the dotted identity path (`"number.value"`) or a
-      #   bare head (`:id`); only the segments after the head are walked
-      # @param held [Object] the value already looked up for the path's head — a
-      #   `Runtime::Value`, a Hash, or a plain scalar
-      # @return [Object, nil] `held` unchanged when `path` has no fields past its head;
-      #   otherwise the value found by walking those fields, or nil when a segment
-      #   is missing or the value being dug into is not a Hash
+      # Digs the fields of `path` out of `held`, past the head the caller consumed.
+      # A path with no fields past the head returns `held` unchanged.
       def scalar(path, held)
         _head, *fields = path.to_s.split(".")
         return held if fields.empty?
@@ -64,66 +27,22 @@ module Hecks
         end
       end
 
-      # Derives `construct`'s identity string from `args`, joining every
-      # declared identity part in declaration order.
-      #
-      # The identity is the join of its parts, in declaration order. Shared by
-      # `CommandInterpreter` (an aggregate acting on itself) and
-      # `EntityInterpreter` (a piece addressed through its aggregate) — a piece
-      # declares an identity the same shape a head does, so it derives one the
-      # same way. `construct` answers `identity_paths` / `identity_heads` /
-      # `attribute` (an Aggregate or an Entity, either one) ; `value_owner`
-      # answers for coercion (`Value.for_attribute`'s first argument), which for
-      # an entity is its owning aggregate — an entity's value objects resolve
-      # through the aggregate's namespace, not its own.
-      #
-      # A part the payload does not carry makes the whole identity unresolvable,
-      # rather than half of one. Half an identity names nothing, and joining what
-      # did arrive would silently name a different record on every dispatch — the
-      # precise failure that minting an id caused, arrived at by another road.
-      #
-      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   `identity_paths` are resolved
-      # @param args [Hash{Symbol => Object}] the offered payload to resolve each
-      #   identity path against
-      # @param value_owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   namespace a value-object identity part is coerced against; `construct` itself
-      #   unless the caller passes the owning aggregate for an entity
-      # @return [String, nil] the joined identity string, or nil when `construct`
-      #   declares no identity path or any resolved part is nil or blank
+      # Joins every declared identity part of `construct` from `args`, in declaration order.
+      # `value_owner` is the aggregate that coerces value-object parts (an entity's owner).
+      # Returns nil unless every part resolves: half an identity would name a different record.
       def of(construct, args, value_owner: construct)
         paths = construct.identity_paths
         return nil if paths.empty?
 
         parts = paths.map { |path| from(construct, args, path, value_owner: value_owner) }
-        # A blank part names nothing, the same as an absent one — an ID is a
-        # scalar, and "" is not a fact about anything. Checking only `nil?`
-        # would let a canonical text extracted as "" (an expression whose
-        # source did not survive extraction) resolve to a real, empty-string
-        # identity — a record addressable by an id no caller could have meant.
+        # A blank part names nothing, the same as an absent one.
         return nil if parts.any? { |part| part.nil? || (part.respond_to?(:empty?) && part.empty?) }
 
         Naming.identity(parts)
       end
 
-      # Resolves one identity path (or a bare head such as `:id`) against `args`.
-      #
-      # A path digs into the value object that carries the identity, so what is
-      # stored is the scalar inside it rather than the object serialised whole.
-      #
-      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct `key` is
-      #   checked against when it is a bare head
-      # @param args [Hash{Symbol => Object}] the offered payload to resolve `key` against
-      # @param key [String, Symbol, nil] the identity path to resolve, dotted
-      #   (`"number.value"`) or bare (`:id`); nil resolves to nil
-      # @param value_owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   namespace a value-object head is coerced against; `construct` itself unless
-      #   the caller passes the owning aggregate for an entity
-      # @return [String, Object, nil] the resolved identity text — a String once dug
-      #   through a dotted path or coerced through a declared value-object attribute;
-      #   the raw `args[key]` value, unconverted, when the bare head names no declared
-      #   identity attribute of `construct`; nil when `key` is nil, absent from `args`,
-      #   or a dotted walk finds nothing
+      # Resolves one identity path, dotted or a bare head such as `:id`, against `args`.
+      # A dotted path yields the scalar inside the value object, never the object serialised.
       def from(construct, args, key, value_owner: construct)
         return nil unless key
 
@@ -134,83 +53,28 @@ module Hecks
         unless rest.empty?
           held = args[head]
           held = held.to_h if held.respond_to?(:to_h)
-          # **An ID is always a scalar**. The path says which field carries it, so a
-          # caller may hand that field's value straight over — a string or a
-          # number, never a serialised object. Only a value object that actually
-          # arrived whole has to be opened.
+          # An ID is always a scalar: a caller may pass the carrying field's value directly.
           return held.to_s unless held.is_a?(Hash)
 
           return rest.reduce(held) { |h, f| h.is_a?(Hash) ? hash_lookup(h, f) : nil }&.to_s
         end
 
-        # Coerced against the identity attribute only when the caller actually
-        # named it. A saga addresses an aggregate by its correlation key, and
-        # that key carries the id already resolved — coercing "w1" against a
-        # WireReference asked the caller to pass fields for a value object they
-        # never mentioned.
+        # Coerce only when the caller named the attribute; a saga's key is already resolved.
         attribute = construct.identity_heads.include?(head) ? construct.attribute(head) : nil
         raw       = args[head]
         return raw unless attribute
 
-        # **An ID is always a scalar** — same contract the dotted branch above
-        # already keeps, just reached a different way here: a bare
-        # (undotted) identity path names one of this construct's own
-        # declared attributes directly, and when that attribute's type is
-        # a value object (Translation's own compound `identified_by
-        # :domain, :from, :to`, each typed `TranslationDomainName`/
-        # `TranslationEraName`), `Value.for_attribute` coerces it into a
-        # real single-field Value wrapper — never unwrapped before this,
-        # so `Naming.identity`'s own plain `Array#join` (`Naming.identity`'s
-        # own header: parts must already be scalars) fell through to
-        # Ruby's default `Object#to_s`, leaking a raw, run-to-run-random
-        # memory address (`#<Hecks::Runtime::Value:0x...>`) into
-        # every refusal quoting this identity — found live via bin/fuzz on
-        # the self-hosted "translation" domain (replay_is_deterministic:
-        # the same address never repeats, so two replays of the
-        # identical steps produced different histories the moment a
-        # Translation went missing). `materialize_unwrapped` is the
-        # same single-field-VO-recurses-to-its-bare-scalar helper
-        # `read_model_interpreter.rb` already uses for exactly this
-        # unwrap; passthrough for anything that isn't a Value at all.
+        # Unwrap the coerced value object so `to_s` never leaks an object address into an id.
         Value.materialize_unwrapped(Value.for_attribute(value_owner, attribute, raw)).to_s
       end
 
-      # Renders `construct`'s identity paths for a refusal message.
-      #
-      # How an identity reads when the runtime has to name it in a refusal — the
-      # paths as they were declared, so the message quotes the bluebook back.
-      #
-      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   declared identity paths are rendered
-      # @return [String] `construct`'s identity paths, comma-separated, exactly as declared
+      # Renders the declared identity paths of `construct` for a refusal message.
       def reading(construct)
         construct.identity_paths.join(", ")
       end
 
-      # Resolves the best identity string available for `construct` from `args`,
-      # without raising, for use as a lock key only.
-      #
-      # Best-effort, for a lock key only — `Runtime::AggregateLock`'s own
-      # per-record striping needs some id to key on before dispatch has run
-      # far enough to hydrate for real, so this walks the identical chain
-      # `CommandInterpreter#hydrate_existing`/`#hydrate_prior_or_initial`
-      # and `EntityInterpreter#parent` already use to locate the real
-      # record — but wrapped to never raise. Choosing which Mutex to hold
-      # must never itself become a crash. `nil` means "could not resolve
-      # from the raw, pre-normalized payload this runs against" — the
-      # caller locks by aggregate type alone in that case (coarser, still
-      # correct, just less concurrent).
-      #
-      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct being
-      #   located for the lock key
-      # @param args [Hash{Symbol => Object}] the raw, pre-normalized payload to resolve
-      #   an identity from
-      # @param route [Runtime::Routing::Envelope, nil] the call's resolved routing
-      #   envelope, if any; its own `aggregate` identity is tried first
-      # @param reference_key [Symbol, nil] the command's reference-key fallback,
-      #   tried last if given
-      # @return [String, Object, nil] the best-effort identity to lock by, or nil
-      #   when nothing resolves (the caller then locks by aggregate type alone)
+      # Resolves a best-effort identity for `construct` to use as a lock key; never raises.
+      # Returns nil when nothing resolves, and the caller then locks by aggregate type alone.
       def best_effort(construct, args, route = nil, reference_key: nil)
         route&.aggregate ||
           of(construct, args) ||

data/lib/hecks/runtime/instance.rb

@@ -4,66 +4,22 @@ require_relative "../ports/persistence/codec_boundary"
 
 module Hecks
   module Runtime
-    # One aggregate (or entity) record's runtime state: the declared
-    # attributes hydrated with defaults, plus the identity (`id`) and,
-    # for a CAS-capable adapter, the optimistic-concurrency `version`
-    # stamped on it. `[]`/`[]=`/method_missing give state-field access;
-    # `to_h` is the wire/storage shape with `id` merged in last so a
-    # same-named declared attribute can never clobber it.
+    # One aggregate or entity record's runtime state: declared attributes plus `id` and `version`.
+    # `to_h` is the wire/storage shape, with `id` merged last so an attribute named `id` loses.
     class Instance
       attr_reader :aggregate, :id
       attr_accessor :state
-      # **Out-of-band adapter bookkeeping, not domain state** — the optimistic-
-      # concurrency version a CAS-capable adapter (Postgres today) stamps
-      # on a record it reads/writes, so a later `save` can assert "commit
-      # only if nobody has written since". Deliberately absent from
-      # `to_h`/`[]`/`[]=`/`method_missing` : a domain author never declares
-      # this, a `given`/`ensures`/`invariant` can never read it, and no
-      # adapter that doesn't understand it (Memory, Heki) ever sets it —
-      # `nil` there just means "no CAS attempted", which is exactly what a
-      # plain `save` already does. See docs/decisions/ (concurrency-control
-      # ADR) for the full mechanism.
+      # Optimistic-concurrency version stamped by a CAS-capable adapter; not domain state.
+      # Left out of `to_h` and `[]` on purpose; nil means no CAS was attempted.
       attr_accessor :version
 
-      # `args:` — the original command payload, offered only by a fresh
-      # creation (`CommandInterpreter#hydrate_legacy_creation`/
-      # `#hydrate_complete_state`/`#hydrate_prior_or_initial`, each already
-      # holding it when they mint a brand-new record). See
-      # `materialize_identity!` for why a composite identity needs it.
-      #
-      # `hydrate:` — on by default, and every existing caller keeps getting
-      # exactly what it always got: `state` re-walked through
-      # `hydrate_with_defaults` (declared defaults filled, every attribute
-      # re-coerced through `Value.for_attribute`, an entity list's every
-      # element rebuilt and re-validated). `false` is for exactly one
-      # caller (`Adapters::Memory#build_instance`, judge-bootstrapping
-      # only — see its own header) that already knows `state` needs none
-      # of that: it is a shallow dup of an already-hydrated, already-
-      # validated live `Instance`'s own state, not a raw value pulled off
-      # a wire. Skipping the re-walk is what turns a `list_of` entity's Nth
-      # save from O(N) (re-hydrating every element saved so far, for every
-      # save) into O(1) — the quadratic cost `Adapters::Memory`'s own
-      # header traces start to finish. `CodecBoundary.check_state!` still
-      # runs either way ; only the re-hydration is skipped.
-      #
-      # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct this
-      #   record's state is declared by
-      # @param id [String, nil] this record's identity; nil for a record whose identity
-      #   is not yet resolvable (e.g. an entity element hydrated before its own view exists)
-      # @param state [Hash{Symbol => Object}, nil] the record's stored (or partial)
-      #   attribute values; nil for a brand-new record, hydrated entirely from declared
-      #   defaults
-      # @param args [Hash{Symbol => Object}, nil] the original command payload, offered
-      #   only by a fresh creation; materializes a composite identity's own head
-      #   attributes
-      # @param hydrate [Boolean] whether `state` is re-walked through
-      #   `hydrate_with_defaults`; false only for a caller that already knows `state` is
-      #   already hydrated and validated
+      # `args` is the creation payload, used only to fill a composite identity's heads.
+      # `hydrate: false` skips the default re-walk for an already-hydrated, validated state,
+      # keeping a `list_of` entity's Nth save O(1) rather than O(N).
       def initialize(aggregate:, id:, state: nil, args: nil, hydrate: true)
         @aggregate = aggregate
         @id        = id
-        # Inside a persistence adapter call this refuses undecoded stored
-        # state (Ports::Persistence::CodecBoundary); everywhere else, no-op.
+        # Inside a persistence adapter call this refuses undecoded stored state.
         Ports::Persistence::CodecBoundary.check_state!(aggregate, state) if state
         @state = if !hydrate
                    state || self.class.defaults(aggregate)
@@ -76,18 +32,7 @@ module Hecks
         materialize_identity!(args)
       end
 
-      # Loading existing state runs the same default-fill a fresh instance
-      # gets: an attribute the record predates — a newly-required field
-      # with a declared default:, a list added since the record was
-      # written — arrives filled instead of nil. Only declared defaults
-      # fill in; an attribute with no default stays absent, exactly as
-      # stored.
-      #
-      # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   declared attributes and defaults `state` is hydrated against
-      # @param state [Hash{Symbol => Object}] the raw stored (or partial) attribute values
-      # @return [Hash{Symbol => Object}] `state` coerced through every declared attribute,
-      #   with any missing declared-default attribute filled in
+      # Hydrates `state` and fills declared defaults for attributes the record predates.
       def self.hydrate_with_defaults(aggregate, state)
         hydrated = Value.hydrate(aggregate, state)
         defaults(aggregate).each do |name, value|
@@ -96,39 +41,20 @@ module Hecks
         hydrated
       end
 
-      # Builds a fresh record's starting state: every declared attribute's
-      # default value, an empty frozen Array for a `list_of` attribute, and
-      # the lifecycle field's declared starting value when `aggregate` has one.
-      #
-      # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   declared attributes and lifecycle are read
-      # @return [Hash{Symbol => Object}] the default state, keyed by attribute name
+      # Builds a fresh record's starting state: declared defaults, empty lists, lifecycle start.
       def self.defaults(aggregate)
         state = aggregate.attributes.to_h do |attr|
-          # Frozen, like a list that has had something appended to it.
-          # An untouched list is the easiest one to miss and the easiest
-          # to mutate: nothing has replaced it yet, so a caller pushing
-          # into it writes straight into the aggregate's own state.
+          # Frozen so pushing into an untouched list cannot write into the aggregate's state.
           [attr.name, attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)]
         end
         state[aggregate.lifecycle.field.to_sym] = aggregate.lifecycle.default if aggregate.lifecycle
         state
       end
 
-      # Resolves one attribute's default value: its own declared `default:`
-      # if it has one, otherwise a value object built entirely from its own
-      # members' defaults, when every member declares one.
-      #
-      # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct
-      #   `attribute` belongs to
-      # @param attribute [Bluebook::Attribute] the attribute to resolve a default for
-      # @return [Runtime::Value, Object, nil] the coerced default value; nil when
-      #   `attribute` declares no default and either names no value object or names
-      #   one with a member that itself declares no default
+      # Resolves an attribute's default, building a value object from its members' defaults.
       def self.default_for(aggregate, attribute)
         return Value.for_attribute(aggregate, attribute, attribute.default) unless attribute.default.nil?
-        # An entity's members hydrate through the same path but an entity
-        # declares no value objects of its own — nothing to default-build.
+        # An entity declares no value objects of its own.
         return nil unless aggregate.respond_to?(:value_object)
 
         value_object = aggregate.value_object(attribute.type)
@@ -138,23 +64,12 @@ module Hecks
       end
 
       # Reads one state field by name.
-      #
-      # @param name [String, Symbol] the declared attribute name to read
-      # @return [Object, nil] the field's current value; nil if `name` is not a key
-      #   of `state`
       def [](name) = @state[name.to_sym]
 
       # Reports whether `state` holds a value for `name`.
-      #
-      # @param name [String, Symbol] the declared attribute name to check
-      # @return [Boolean] true if `state` has a key for `name`
       def key?(name) = @state.key?(name.to_sym)
 
       # Writes one state field by name.
-      #
-      # @param name [String, Symbol] the declared attribute name to write
-      # @param value [Object] the value to store
-      # @return [Object] `value`, unchanged
       def []=(name, value)
         @state[name.to_sym] = value
       end
@@ -169,36 +84,10 @@ module Hecks
         @state.key?(name) || super
       end
 
-      # Renders this record's wire/storage shape, state plus its identity.
-      #
-      # `id: @id` last, not first — see Facade::Handle#to_h's own comment
-      # for the full story (the same fix, landed there first): an
-      # aggregate free to declare its own attribute literally named `id`
-      # (BurningManPrep's `Item`, `attribute :id, ItemId`) has that
-      # attribute's own wrapped value object sitting in `@state[:id]` —
-      # merging `@state` on top of `{ id: @id }` let it silently clobber
-      # the correct bare identity. `@id` merged last always wins.
-      #
-      # @return [Hash{Symbol => Object}] `state`, with `id` merged in last
+      # State plus identity, `id` merged last so a declared attribute named `id` cannot clobber it.
       def to_h = @state.merge(id: @id)
 
-      # Copies this record, deep enough that a mutation on the copy cannot
-      # reach the original's own state.
-      #
-      # A copy a mutation may touch. Every adapter but Memory hands `find`
-      # a freshly-decoded Instance already; Memory's holds the record it
-      # eventually saves — the same state Hash, aliased. Before `ensures`
-      # existed, nothing could refuse between apply_mutations and save, so
-      # that aliasing was invisible: a dispatch either ran to completion or
-      # raised before touching state at all. `ensures` is the first refusal
-      # to sit after mutation, and it found the bug the moment it did — an
-      # in-memory record left half-mutated by a dispatch that then refused.
-      # `command_interpreter`/`entity_interpreter` hydrate an existing
-      # record through this, never through the adapter's own return value
-      # directly, so a refused ensures leaves the stored record untouched
-      # regardless of which adapter is holding it.
-      #
-      # @return [Runtime::Instance] a copy of this record, with its own state Hash
+      # Copies this record with its own state Hash, so a refused dispatch spares the original.
       def dup
         copy = super
         copy.state = @state.dup
@@ -212,36 +101,15 @@ module Hecks
 
       private
 
-      # M17 — a composite identity (`identity_heads.size > 1`, e.g.
-      # `identified_by :branch_code, :box_number`) has no single
-      # `identified_by` to fall back to `:id` for — `@aggregate.identified_by`
-      # is nil the moment there is more than one head (`Behaviour::Identified
-      # #derive_identity`), so the single-head branch below never runs for
-      # it at all. Without this, a creating command that declares those heads
-      # as ordinary attributes but doesn't also `sets` them (redundant with
-      # the identity the command's own args already named) would persist
-      # every head as nil — the id correctly naming the record, but the
-      # record's own attributes forgetting what named it.
-      #
-      # Filled from `args`, never from splitting `@id` back apart — the
-      # same reason the single-head branch below won't guess a multi-path
-      # identifier from its joined string: `@id` is a display key, not a
-      # reversible serialization, and a composite's own separator can
-      # collide with a part's own text. `args` is only offered by a fresh
-      # creation (`Instance.new`'s own `args:` comment); an existing record
-      # read back from storage has no args to lean on, and doesn't need
-      # one since a correctly-persisted record already carries its own
-      # heads.
+      # A composite identity has no single head, so each head is filled from `args`.
+      # Never split `@id`: it is a display key and a part's text can contain the separator.
       def materialize_identity!(args = nil)
         return materialize_composite_identity!(args) if @aggregate.identity_heads.size > 1
 
         identity  = @aggregate.identified_by || :id
         attribute = @aggregate.attribute(identity)
         return unless attribute && @state[identity].nil?
-        # Several paths under one head mean the identifier is a display key,
-        # not a reversible serialization of the structured value object. A
-        # creating command supplies that object explicitly; persisted state
-        # hydrates it from storage. Never guess by splitting the joined id.
+        # Several paths under one head make the id a display key, not reversible; never split it.
         return if @aggregate.identity_heads.one? && @aggregate.identity_paths.size > 1
 
         @state[identity] = Value.from_identifier(@aggregate, attribute, @id)

data/lib/hecks/runtime/interpreting.rb

@@ -3,21 +3,9 @@ require_relative "aggregate_lock"
 
 module Hecks
   module Runtime
-    # What every stepwise interpreter shares: the traced step, and the
-    # coercion of a command's declared arguments. Two copies of each lived
-    # in CommandInterpreter and EntityInterpreter, where they could only
-    # ever drift.
+    # Shared by the stepwise interpreters: the traced step and coercion of declared arguments.
     module Interpreting
-      # Ruby's module-inclusion hook. Gives `interpreter` its own `trace`
-      # accessor, since a class including this module needs its own copy
-      # rather than one shared across every interpreter.
-      #
-      # Each including interpreter gets its own `trace` — set by a spec to
-      # observe dispatch order (Vocabulary::AggregateDispatchOrder and
-      # Vocabulary::EntityDispatchOrder in language/bluebook/vocabulary.bluebook);
-      # nil in production, always — one array push and a nil check per step
-      # is the entire cost of leaving this in.
-      #
+      # Gives each including interpreter its own `trace`, set by specs to observe dispatch order.
       # @param interpreter [Class] the class (`CommandInterpreter`, `EntityInterpreter`)
       #   including this module
       # @return [void]
@@ -27,37 +15,15 @@ module Hecks
 
       private
 
-      # Logged after the step's own work, so a step that wraps sub-steps logs
-      # itself once everything inside it has already logged — trace order is
-      # completion order, which is dispatch order.
+      # Logged after the step's work, so trace order is completion order.
       def step(name)
         result = yield
         self.class.trace << name if self.class.trace
         result
       end
 
-      # Drives `DISPATCH_ORDER` (CommandInterpreter/EntityInterpreter, each
-      # read off its own generated Vocabulary::*DispatchOrder table —
-      # vocabulary.bluebook, via lib/hecks/vocabulary.rb) by `send`ing
-      # each declared step name against the including interpreter's own
-      # `step_<name>` handler, in declared order. Data drives that sequence,
-      # rather than `call` spelling it out as a literal sequence of method
-      # calls — tracing a real dispatch and comparing it to the declaration is
-      # tautological once `call` mechanically follows the declaration; a
-      # conditional step (assign_creation_attributes, advance_lifecycle) still
-      # has to guard itself at the top of its own handler and skip tracing
-      # when it does not fire, rather than the caller branching around it —
-      # see CommandInterpreter#step_assign_creation_attributes.
-      # The commit boundary. Every step up to `save` runs as before;
-      # `save`, `emit`, and the outbox enqueue that follows them run
-      # inside one `repository.transaction` — so the aggregate row, its
-      # journal entry, the recorded event, and the outbox rows naming
-      # who is owed a reaction commit together or not at all. No new
-      # step is added to the vocabulary's dispatch order (the step list
-      # is a pinned contract, `spec/vocabulary_conformance_spec.rb`);
-      # the enqueue is a consequence of `emit`, not a step of its own.
-      # A context without a repository (port operations — nothing to
-      # save) or with no `:save` in its order runs plainly.
+      # Runs `order` by sending each `step_<name>` handler; `save` onward shares one transaction.
+      # The outbox enqueue rides on `emit`; the vocabulary's step list is a pinned contract.
       def run_dispatch_order(order, ctx)
         split = order.index(:save)
         return order.each { |name| send(:"step_#{name}", ctx) } unless split && ctx.respond_to?(:repository) && ctx.repository
@@ -69,34 +35,16 @@ module Hecks
         end
       end
 
-      # Rows for the events this dispatch just emitted, written while
-      # the save's transaction is still open. `nil` (no outbox on this
-      # repository) tells the dispatcher to react directly, the
-      # pre-outbox path; a dry run emits nothing and enqueues nothing.
+      # Enqueues outbox rows for the just-emitted events inside the save's transaction.
       def enqueue_outbox(ctx)
         return if ctx.dry_run || !ctx.respond_to?(:outbox_rows=)
 
         ctx.outbox_rows = @registry.outbox.enqueue(ctx.repository, Array(ctx.result), ctx.domain)
       end
 
-      # The concurrency-control split — see docs/decisions/ (concurrency
-      # control ADR) for the full mechanism. A repository that declares
-      # `:optimistic_concurrency` (Postgres today) already closes the
-      # lost-update gap itself, via `step_save`'s CAS + `#call`'s own
-      # `StaleWrite` retry loop — an extra in-process lock here would be
-      # pointless overhead, not incorrect, so it's skipped for clarity.
-      # A repository that declares `:cross_process_lock` (PostgresEra —
-      # ADR 0036) holds a real Postgres advisory lock for the whole
-      # dispatch order instead: unlike Heki/Memory (confirmed
-      # process-local, never a second process writing the same store),
-      # PostgresEra's own tables can be dispatched against concurrently
-      # by `rust/host` from a separate OS process, and an in-process
-      # `Mutex` is invisible to that. Every other repository gets the
-      # striped `Mutex` below, held for the whole dispatch-order run, so
-      # a second thread's own hydrate can't start until the first
-      # thread's save has landed. `lock_key_id` is best-effort
-      # (`Identity.best_effort`) — `nil` still locks correctly, just
-      # coarser (by aggregate type).
+      # Picks the isolation by capability: CAS needs none, a cross-process lock uses the
+      # repository's write lock, and the rest get a striped in-process Mutex (ADR 0036).
+      # A nil `lock_key_id` still locks correctly, just by aggregate type.
       def run_dispatch_order_with_isolation(order, ctx, lock_key_id:)
         capabilities = ctx.repository.capabilities
         if capabilities.include?(:optimistic_concurrency)
@@ -108,9 +56,7 @@ module Hecks
         end
       end
 
-      # Every declared attribute present in the payload passes the reference
-      # gate, then coercion — the same walk whether the command acts on an
-      # aggregate or on one of its entity's elements.
+      # Passes each declared payload attribute through the reference gate, then coercion.
       def coerce_declared_arguments(aggregate, command, args)
         command.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
@@ -120,12 +66,7 @@ module Hecks
         end
       end
 
-      # Coercion only — CommandInterpreter's own refuse_unknown_arguments/
-      # refuse_absent_arguments are separate DISPATCH_ORDER steps now (the
-      # declared vocabulary lists all three as flat, sequential members, not
-      # one nesting the other two), and EntityInterpreter never had them here
-      # at all (an entity inherits its aggregate's own gate). One shared
-      # copy, rather than two identical ones that can only ever drift apart.
+      # Coercion only; the unknown/absent-argument refusals are separate dispatch steps.
       def normalize_args(aggregate, command, args)
         coerce_declared_arguments(aggregate, command, args)
       end