hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/identity.rb

@@ -3,9 +3,9 @@ require_relative "value"
 
 module Hecks
   module Runtime
-    # THE SCALAR AN IDENTITY PATH NAMES.
+    # **The scalar an identity path names**.
     #
-    # An identity is DECLARED as a path — `identified_by :number` — and
+    # 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
@@ -23,19 +23,38 @@ module Hecks
     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
+      # 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`
       def hash_lookup(hash, key)
         sym = key.to_sym
         hash.key?(sym) ? hash[sym] : hash[key]
       end
 
-      # The head names the ATTRIBUTE and is consumed by whoever looked the value
+      # 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
       def scalar(path, held)
         _head, *fields = path.to_s.split(".")
         return held if fields.empty?
@@ -45,37 +64,66 @@ module Hecks
         end
       end
 
-      # THE IDENTITY IS THE JOIN OF ITS PARTS, in declaration order. Shared by
+      # 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
+      # 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,
+      # 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
       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. This used to check only
-        # `nil?`, so a canonical text extracted as "" (an expression whose
-        # source did not survive extraction) resolved to a REAL, empty-string
+        # 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.
         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.
+      # 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
       def from(construct, args, key, value_owner: construct)
         return nil unless key
 
@@ -86,7 +134,7 @@ 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
+          # **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.
@@ -95,18 +143,18 @@ module Hecks
           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
+        # 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
+        # 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.
         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
+        # **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`/
@@ -118,23 +166,32 @@ module Hecks
         # 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
+        # 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
+        # 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.
         Value.materialize_unwrapped(Value.for_attribute(value_owner, attribute, raw)).to_s
       end
 
-      # How an identity READS when the runtime has to name it in a refusal — the
+      # 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
       def reading(construct)
         construct.identity_paths.join(", ")
       end
 
-      # BEST-EFFORT, FOR A LOCK KEY ONLY — `Runtime::AggregateLock`'s own
-      # per-record striping needs SOME id to key on before dispatch has run
+      # 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
@@ -143,6 +200,17 @@ module Hecks
       # 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)
       def best_effort(construct, args, route = nil, reference_key: nil)
         route&.aggregate ||
           of(construct, args) ||

data/lib/hecks/runtime/instance.rb

@@ -1,5 +1,6 @@
 require_relative "value"
 require_relative "identity"
+require_relative "../ports/persistence/codec_boundary"
 
 module Hecks
   module Runtime
@@ -12,7 +13,7 @@ module Hecks
     class Instance
       attr_reader :aggregate, :id
       attr_accessor :state
-      # OUT-OF-BAND ADAPTER BOOKKEEPING, NOT DOMAIN STATE — the optimistic-
+      # **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
@@ -24,16 +25,54 @@ module Hecks
       # ADR) for the full mechanism.
       attr_accessor :version
 
-      # `args:` — THE ORIGINAL COMMAND PAYLOAD, offered only by a fresh
+      # `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.
-      def initialize(aggregate:, id:, state: nil, args: nil)
+      #
+      # `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
+      def initialize(aggregate:, id:, state: nil, args: nil, hydrate: true)
         @aggregate = aggregate
         @id        = id
-        @state     = state ? self.class.hydrate_with_defaults(aggregate, state) : self.class.defaults(aggregate)
-        @version   = nil
+        # Inside a persistence adapter call this refuses undecoded stored
+        # state (Ports::Persistence::CodecBoundary); everywhere else, no-op.
+        Ports::Persistence::CodecBoundary.check_state!(aggregate, state) if state
+        @state = if !hydrate
+                   state || self.class.defaults(aggregate)
+                 elsif state
+                   self.class.hydrate_with_defaults(aggregate, state)
+                 else
+                   self.class.defaults(aggregate)
+                 end
+        @version = nil
         materialize_identity!(args)
       end
 
@@ -43,6 +82,12 @@ module Hecks
       # 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
       def self.hydrate_with_defaults(aggregate, state)
         hydrated = Value.hydrate(aggregate, state)
         defaults(aggregate).each do |name, value|
@@ -51,9 +96,16 @@ 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
       def self.defaults(aggregate)
         state = aggregate.attributes.to_h do |attr|
-          # FROZEN, like a list that has had something appended to it.
+          # 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.
@@ -63,6 +115,16 @@ module Hecks
         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
       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
@@ -75,10 +137,24 @@ module Hecks
         Value.build(value_object, {}, aggregate)
       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
@@ -93,27 +169,36 @@ module Hecks
         @state.key?(name) || super
       end
 
-      # `id: @id` LAST, not first — see Facade::Handle#to_h's own comment
+      # 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
       def to_h = @state.merge(id: @id)
 
-      # A COPY A MUTATION MAY TOUCH. Every adapter but Memory hands `find`
+      # 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`
+      # 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
+      # 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
+      # `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
       def dup
         copy = super
         copy.state = @state.dup
@@ -127,22 +212,22 @@ module Hecks
 
       private
 
-      # M17 — a COMPOSITE identity (`identity_heads.size > 1`, e.g.
+      # 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. 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) used to persist every head as
-      # nil — the id correctly named the record, but the record's own
-      # attributes forgot what named it.
+      # 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
+      # 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

data/lib/hecks/runtime/interpreting.rb

@@ -8,18 +8,26 @@ module Hecks
     # in CommandInterpreter and EntityInterpreter, where they could only
     # ever drift.
     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.
+      #
+      # @param interpreter [Class] the class (`CommandInterpreter`, `EntityInterpreter`)
+      #   including this module
+      # @return [void]
       def self.included(interpreter)
         interpreter.singleton_class.attr_accessor :trace
       end
 
       private
 
-      # Logged AFTER the step's own work, so a step that wraps sub-steps logs
+      # 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.
       def step(name)
@@ -28,21 +36,21 @@ module Hecks
         result
       end
 
-      # DRIVES `DISPATCH_ORDER` (CommandInterpreter/EntityInterpreter, each
-      # mirroring its own Vocabulary::*DispatchOrder — vocabulary.bluebook,
-      # held equal to it by spec/vocabulary_conformance_spec.rb) by `send`ing
+      # 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. What used to be `call`'s own
-      # literal sequence of method calls is now DATA driving that sequence —
-      # tracing a real dispatch and comparing it to the declaration is
+      # `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
+      # 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;
+      # 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
+      # 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
@@ -71,20 +79,20 @@ module Hecks
         ctx.outbox_rows = @registry.outbox.enqueue(ctx.repository, Array(ctx.result), ctx.domain)
       end
 
-      # THE CONCURRENCY-CONTROL SPLIT — see docs/decisions/ (concurrency
+      # 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
+      # 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
+      # `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
@@ -116,8 +124,8 @@ module Hecks
       # 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 copy,
-      # shared, rather than the two identical ones that used to drift.
+      # at all (an entity inherits its aggregate's own gate). One shared
+      # copy, rather than two identical ones that can only ever drift apart.
       def normalize_args(aggregate, command, args)
         coerce_declared_arguments(aggregate, command, args)
       end