hecks 1.4.0 → 1.5.0

data/lib/hecks/runtime/identity.rb

@@ -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
       # `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
 
+      # 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,6 +64,9 @@ 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
@@ -59,23 +81,49 @@ module Hecks
       # 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
+        # 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.
+      #
+      # @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
 
@@ -127,12 +175,21 @@ module Hecks
         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
       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
@@ -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

@@ -31,20 +31,34 @@ module Hecks
       # 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
+      # `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-
+      # 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
@@ -68,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|
@@ -76,6 +96,13 @@ 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.
@@ -88,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
@@ -100,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
@@ -118,6 +169,8 @@ 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`
@@ -125,8 +178,13 @@ module Hecks
       # 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)
 
+      # 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`
@@ -139,6 +197,8 @@ module Hecks
       # 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
@@ -157,11 +217,11 @@ module Hecks
       # `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

data/lib/hecks/runtime/interpreting.rb

@@ -8,11 +8,19 @@ 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
@@ -32,9 +40,9 @@ module Hecks
       # 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
@@ -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

data/lib/hecks/runtime/invocation.rb

@@ -9,7 +9,8 @@ module Hecks
     # (`target`, a `Routing::Envelope` or nil), and every fact the caller did
     # or did not offer. Built once per dispatch by `Invocation.from_call`, the
     # only place the runtime interprets the shape of a call (`to:` vs `with:`
-    # vs loose keyword arguments, a port operation's reference attribute
+    # vs the flat facts hash `dispatch_flat` carries, a port operation's
+    # reference attribute
     # lifted into `to:`). `Runtime::Routing.envelope`/`.payload` delegate here
     # and no longer hold that logic themselves.
     #
@@ -21,12 +22,12 @@ module Hecks
     #   - `Invocation::Present` — the key was offered with a value
     #
     # Keys are kept exactly as offered: `with:` keys are symbolized (as they
-    # always were), loose keyword arguments keep whatever key the caller
-    # used. Undeclared keys a caller offered are kept too — refusing them is
+    # always were), a flat facts hash keeps whatever key the wire used. Undeclared keys a caller
+    # offered are kept too — refusing them is
     # still `refuse_unknown_arguments`' job, a dispatch step, not this one.
     #
-    # PR I1 changes no behavior: every interpreter still reads `ctx.args`,
-    # which is `#to_args` — the same Hash `Routing.payload` used to return.
+    # I1 changes no behavior: every interpreter still reads `ctx.args`,
+    # which is `#to_args` — the same Hash `Routing.payload` returns.
     # Roadmap I2 moves the Ruby `decode_arguments` step onto `facts` itself.
     Invocation = Data.define(:verb, :target, :facts)
 
@@ -41,6 +42,7 @@ module Hecks
       # The class of the two frozen marker singletons below — never
       # instantiated anywhere else.
       class Marker
+        # @param name [String] the marker's own label, used by #inspect/#to_s
         def initialize(name)
           @name = name
           freeze
@@ -54,22 +56,51 @@ module Hecks
       Absent = Marker.new("Absent")
       Null   = Marker.new("Null")
 
+      # @param verb [String] the fully qualified verb this invocation dispatches
+      # @param target [Routing::Envelope, nil] the resolved receiver, or nil when
+      #   the facts carry the identity themselves
+      # @param facts [Hash{String, Symbol => Object}] every candidate fact, keyed by
+      #   offered (or declared) name; frozen, deep-duped, before being stored
       def initialize(verb:, target:, facts:)
         super(verb: verb, target: target, facts: facts.dup.freeze)
       end
 
+      # Reads the fact recorded under `name`.
+      #
       # The fact recorded under `name` — `Absent` for a name never offered
       # and never declared either.
+      #
+      # @param name [String, Symbol] the fact name to look up
+      # @return [Invocation::Present, Invocation::Null, Invocation::Absent] the
+      #   recorded marker for `name`
       def fact(name) = facts.fetch(name, Absent)
 
+      # Reports whether `name` was offered with a real, non-nil value.
+      #
+      # @param name [String, Symbol] the fact name to check
+      # @return [Boolean] true if `name` was offered with a non-nil value
       def present?(name) = fact(name).is_a?(Present)
+
+      # Reports whether `name` was offered with an explicit nil.
+      #
+      # @param name [String, Symbol] the fact name to check
+      # @return [Boolean] true if `name` was offered with an explicit nil
       def null?(name)    = fact(name).equal?(Null)
+
+      # Reports whether `name` was never offered.
+      #
+      # @param name [String, Symbol] the fact name to check
+      # @return [Boolean] true if `name` was never offered (and, if declared, left out)
       def absent?(name)  = fact(name).equal?(Absent)
 
       # A Present fact's value; nil for an explicit Null. Raises KeyError for
       # an Absent fact — "never offered" has no value, and answering nil
       # would re-conflate it with an explicit null, the very ambiguity this
       # type exists to remove. Ask `absent?`/`present?` first.
+      #
+      # @param name [String, Symbol] the fact name to read
+      # @return [Object, nil] the offered value; nil for an explicit Null fact
+      # @raise [KeyError] if `name` names an Absent fact (never offered)
       def value(name)
         case (found = fact(name))
         when Present then found.value
@@ -78,9 +109,12 @@ module Hecks
         end
       end
 
-      # The legacy args hash, byte for byte what `Routing.payload` returned
+      # The flat args hash, byte for byte what `Routing.payload` returned
       # before this type existed: offered keys in offered order, Absent keys
       # omitted, Null keys mapped to nil. A fresh Hash every call.
+      #
+      # @return [Hash{String, Symbol => Object}] the offered facts by name; a fact
+      #   offered as nil is kept as nil
       def to_args
         facts.each_with_object({}) do |(name, found), args|
           next if found.equal?(Absent)
@@ -90,7 +124,7 @@ module Hecks
       end
 
       class << self
-        # **The one reading of a call's shape**. `receiver:` picks which of the
+        # The one reading of a call's shape. `receiver:` picks which of the
         # three dispatch shapes this is, because each has always checked its
         # parts in its own order and a malformed call's refusal depends on
         # that order:
@@ -107,24 +141,57 @@ module Hecks
         # the point in that order where the caller always resolved it.
         # `aggregate:` is the owning aggregate construct, read for `:port`
         # only.
-        def from_call(verb, to:, with:, legacy:, receiver: :aggregate, entity_depth: 0, aggregate: nil, &declaring)
+        #
+        # @param verb [String] the fully qualified verb being dispatched
+        # @param to [String, Hash, nil] a bare aggregate identity, or a Hash with
+        #   `aggregate:` and `entity:`/`entities:`; nil for no explicit receiver
+        # @param with [Hash, nil] the command's facts, keyed by attribute name; nil
+        #   when the caller offers `flat` instead
+        # @param flat [Hash] the command's facts as a flat args hash, used when `with`
+        #   is nil; for `:port`, may also carry the receiver identity under a
+        #   reference attribute's own name
+        # @param receiver [Symbol] which of the three dispatch shapes this is:
+        #   `:aggregate`, `:entity` or `:port`
+        # @param entity_depth [Integer] the number of entity-hop identities `to:`
+        #   must carry, for `:entity` only
+        # @param aggregate [Bluebook::Aggregate, nil] the owning aggregate construct,
+        #   read for `:port` only
+        # @yieldreturn [Class] the declaring command or port-operation class (anything
+        #   with `hecks_name` and `attributes`)
+        # @return [Runtime::Invocation] the built invocation
+        # @raise [Runtime::TypeMismatch] if `to:` is malformed, its entity count is
+        #   wrong, or (`:port` only) the operation resolves no receiving aggregate
+        # @raise [Runtime::UnknownArgument] if `with:` names an attribute the command
+        #   does not declare
+        # @raise [Runtime::AbsentArgument] if `with:` omits a required attribute
+        # @raise [ArgumentError] if `receiver` is none of `:aggregate`, `:entity` or `:port`
+        def from_call(verb, to:, with:, flat:, receiver: :aggregate, entity_depth: 0, aggregate: nil, &declaring)
           case receiver
           when :aggregate
             command = declaring.call
-            facts   = facts_for(command, with: with, legacy: legacy)
+            facts   = facts_for(command, with: with, flat: flat)
             new(verb: verb, target: route(to), facts: facts)
           when :entity
             target  = route(to, entity_depth: entity_depth)
             command = declaring.call
-            new(verb: verb, target: target, facts: facts_for(command, with: with, legacy: legacy))
+            new(verb: verb, target: target, facts: facts_for(command, with: with, flat: flat))
           when :port
-            port_call(verb, aggregate, declaring.call, to: to, with: with, legacy: legacy)
+            port_call(verb, aggregate, declaring.call, to: to, with: with, flat: flat)
           else
             raise ArgumentError, "unknown receiver #{receiver.inspect}"
           end
         end
 
         # `to:` as a `Routing::Envelope`, or nil when no `to:` was given.
+        #
+        # @param to [String, Hash, nil] a bare aggregate identity, or a Hash with
+        #   `aggregate:` and `entity:`/`entities:`; nil for no receiver
+        # @param entity_depth [Integer] the number of entity-hop identities `to`
+        #   must carry
+        # @return [Routing::Envelope, nil] the resolved envelope, or nil when `to`
+        #   is nil
+        # @raise [Runtime::TypeMismatch] if `to` is malformed, or its entity count
+        #   does not match `entity_depth`
         def route(to, entity_depth: 0)
           return nil if to.nil?
 
@@ -146,8 +213,23 @@ module Hecks
         # The offered facts for `declaring`, as Absent/Null/Present — offered
         # keys first, in offered order, then every declared attribute that was
         # not offered, as Absent.
-        def facts_for(declaring, with:, legacy:)
-          offered = offered_facts(declaring, with: with, legacy: legacy)
+        #
+        # @param declaring [Class] the command or port-operation class (anything
+        #   with `hecks_name` and `attributes`) whose declared attributes are read
+        # @param with [Hash, nil] the command's facts, keyed by attribute name; nil
+        #   when the caller offers `flat` instead
+        # @param flat [Hash] the command's facts as a flat args hash, used when `with`
+        #   is nil
+        # @return [Hash{String, Symbol => Invocation::Absent, Invocation::Null,
+        #   Invocation::Present}] each candidate fact keyed by its offered (or
+        #   declared) name
+        # @raise [Runtime::TypeMismatch] if both `with` and a non-empty `flat` are
+        #   given, or if `with` is not a Hash
+        # @raise [Runtime::UnknownArgument] if `with:` names an attribute `declaring`
+        #   does not declare
+        # @raise [Runtime::AbsentArgument] if `with:` omits a required attribute
+        def facts_for(declaring, with:, flat:)
+          offered = offered_facts(declaring, with: with, flat: flat)
           facts = offered.each_with_object({}) do |(name, value), found|
             found[name] = value.nil? ? Null : Present.new(value: value)
           end
@@ -160,10 +242,10 @@ module Hecks
 
         private
 
-        # **The port operation shape** — formerly `Dispatcher#port_invocation`.
+        # **The port operation shape** — moved from `Dispatcher#port_invocation`.
         #
         # A Reference-typed attribute naming the owning aggregate is routing,
-        # not a fact: lifted out of the loose kwargs into `to:` when no `to:`
+        # not a fact: lifted out of the flat facts into `to:` when no `to:`
         # was given. A `to:`-declared operation carries no Reference
         # attribute at all (PortOperationBuilder#initialize's own comment),
         # so its receiver is read — not removed — from the plain attribute
@@ -173,30 +255,30 @@ module Hecks
         # with attribute"; a real AbsentArgument confirmed this before `[]`
         # replaced `delete`). Composite identity is not attempted — `.first`
         # only, no domain in the corpus needs more for a port operation.
-        def port_call(verb, aggregate, operation, to:, with:, legacy:)
-          legacy = legacy.dup
+        def port_call(verb, aggregate, operation, to:, with:, flat:)
+          flat = flat.dup
           identity = operation.identity_attribute(aggregate.hecks_name)
-          if to.nil? && identity && legacy.key?(identity.name)
-            to = legacy.delete(identity.name)
+          if to.nil? && identity && flat.key?(identity.name)
+            to = flat.delete(identity.name)
           elsif to.nil? && operation.to == aggregate.hecks_name
             identity_name = Array(aggregate.identified_by).first
-            to = legacy[identity_name] if identity_name && legacy.key?(identity_name)
+            to = flat[identity_name] if identity_name && flat.key?(identity_name)
           end
 
           target = route(to)
           raise TypeMismatch, "#{operation.hecks_name} requires its receiving aggregate in to:" unless target
 
-          new(verb: verb, target: target, facts: facts_for(operation, with: with, legacy: legacy))
+          new(verb: verb, target: target, facts: facts_for(operation, with: with, flat: flat))
         end
 
         # BUG#7 — a non-Hash `to:` must be a String, matching Rust's
         # `RoutingEnvelope::from_json` (kernel/routing.rs), which refuses
         # anything neither a JSON string nor object before the domain payload
         # is examined. Surfaced on `examples/roster`'s `Mark`, whose own
-        # attribute is literally named `to`: a flat-kwargs dispatch steals
-        # that key into this parameter, and an out-of-range Integer used to be
-        # accepted as the aggregate identity, leaving Mark's `to` fact absent
-        # (AbsentArgument in Ruby, TypeMismatch in Rust). See
+        # attribute is literally named `to`: a flat-facts dispatch steals
+        # that key into this parameter, and without this check an out-of-range
+        # Integer would be accepted as the aggregate identity, leaving Mark's
+        # `to` fact absent (AbsentArgument in Ruby, TypeMismatch in Rust). See
         # spec/runtime/routing_envelope_shape_spec.rb.
         def scalar_envelope(to)
           return [to, []] if to.is_a?(String)
@@ -214,11 +296,11 @@ module Hecks
 
         # BUG#18 — an entity route naming no entity (`entities: []`, or
         # neither key) refuses here, unconditionally, before entity_depth is
-        # consulted: for an aggregate-level command (depth 0) `[].size == 0`
-        # used to satisfy the depth check and let the degenerate Hash reach
-        # the command's own validation. Rust's `RoutingEnvelope::from_json`
-        # always refused it at this point. A bare aggregate identity String
-        # remains the ordinary aggregate-command shape.
+        # consulted: for an aggregate-level command (depth 0), without this,
+        # `[].size == 0` would satisfy the depth check and let the degenerate
+        # Hash reach the command's own validation. Rust's `RoutingEnvelope::
+        # from_json` always refused it at this point. A bare aggregate identity
+        # String remains the ordinary aggregate-command shape.
         def entity_identities(hash)
           raise TypeMismatch, "to: takes entity: or entities:, not both" if hash.key?(:entities) && hash.key?(:entity)
 
@@ -230,16 +312,16 @@ module Hecks
 
         # `with:` is deliberately strict: a caller choosing the explicit
         # envelope cannot smuggle receiver identity back into the payload,
-        # and may not mix it with loose keyword arguments. Without `with:`
-        # (nil or false) the loose keyword arguments are the facts, unread —
+        # and may not mix it with a flat facts hash. Without `with:`
+        # (nil or false) the flat facts are the facts, unread —
         # whether `to:` was given never enters this decision (BUG#17).
-        def offered_facts(declaring, with:, legacy:)
-          if with && !legacy.empty?
+        def offered_facts(declaring, with:, flat:)
+          if with && !flat.empty?
             raise TypeMismatch,
-                  "dispatch takes command facts in with:, not both with: and loose keyword arguments"
+                  "dispatch takes command facts in with:, not both with: and a flat facts hash"
           end
 
-          return legacy unless with
+          return flat unless with
           raise TypeMismatch, "with: must be a hash of command facts" unless with.is_a?(Hash)
 
           offered = with.transform_keys(&:to_sym)