hecks 1.3.0 → 1.4.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
@@ -24,7 +24,7 @@ module Hecks
       module_function
 
       # 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.
       def hash_lookup(hash, key)
@@ -32,7 +32,7 @@ module Hecks
         hash.key?(sym) ? hash[sym] : hash[key]
       end
 
-      # The head names the ATTRIBUTE and is consumed by whoever looked the value
+      # 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.
@@ -45,17 +45,17 @@ module Hecks
         end
       end
 
-      # THE IDENTITY IS THE JOIN OF ITS PARTS, in declaration order. Shared by
+      # 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.
@@ -64,10 +64,10 @@ module Hecks
         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
+        # 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
+        # source did not survive extraction) resolved 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?) }
 
@@ -75,7 +75,7 @@ module Hecks
       end
 
       # 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.
       def from(construct, args, key, value_owner: construct)
         return nil unless key
 
@@ -86,7 +86,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 +95,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 +118,23 @@ 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
+      # 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.
       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
+      # 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

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,40 @@ 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.
+      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
 
@@ -53,7 +78,7 @@ module Hecks
 
       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.
@@ -93,7 +118,7 @@ module Hecks
         @state.key?(name) || super
       end
 
-      # `id: @id` LAST, not first — see Facade::Handle#to_h's own comment
+      # `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
@@ -102,15 +127,15 @@ module Hecks
       # the correct bare identity. `@id` merged last always wins.
       def to_h = @state.merge(id: @id)
 
-      # A COPY A MUTATION MAY TOUCH. Every adapter but Memory hands `find`
+      # 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.
@@ -127,13 +152,13 @@ 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
+      # 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.
@@ -142,7 +167,7 @@ module Hecks
       # 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

@@ -19,7 +19,7 @@ module Hecks
 
       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 +28,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 —
+      # literal sequence of method calls is now data driving that sequence —
       # 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 +71,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

data/lib/hecks/runtime/invocation.rb

@@ -0,0 +1,276 @@
+require_relative "errors"
+require_relative "refusal_wording"
+require_relative "routing"
+require_relative "../rendering"
+
+module Hecks
+  module Runtime
+    # **One dispatch, as data** — the verb, the receiver it is addressed to
+    # (`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
+    # lifted into `to:`). `Runtime::Routing.envelope`/`.payload` delegate here
+    # and no longer hold that logic themselves.
+    #
+    # `facts` maps a fact name to exactly one of:
+    #
+    #   - `Invocation::Absent`  — the key was never offered (every declared
+    #                             attribute the caller left out appears so)
+    #   - `Invocation::Null`    — the key was offered with an explicit nil
+    #   - `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
+    # 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.
+    # Roadmap I2 moves the Ruby `decode_arguments` step onto `facts` itself.
+    Invocation = Data.define(:verb, :target, :facts)
+
+    # The fact markers, the fact readers, and `from_call` — see above.
+    class Invocation
+      # A fact the caller offered with a real (non-nil) value.
+      Present = Data.define(:value) do
+        def inspect = "#<Invocation::Present #{value.inspect}>"
+        alias_method :to_s, :inspect
+      end
+
+      # The class of the two frozen marker singletons below — never
+      # instantiated anywhere else.
+      class Marker
+        def initialize(name)
+          @name = name
+          freeze
+        end
+
+        def inspect = "Invocation::#{@name}"
+        alias to_s inspect
+      end
+      private_constant :Marker
+
+      Absent = Marker.new("Absent")
+      Null   = Marker.new("Null")
+
+      def initialize(verb:, target:, facts:)
+        super(verb: verb, target: target, facts: facts.dup.freeze)
+      end
+
+      # The fact recorded under `name` — `Absent` for a name never offered
+      # and never declared either.
+      def fact(name) = facts.fetch(name, Absent)
+
+      def present?(name) = fact(name).is_a?(Present)
+      def null?(name)    = fact(name).equal?(Null)
+      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.
+      def value(name)
+        case (found = fact(name))
+        when Present then found.value
+        when Null then nil
+        else raise KeyError, "#{verb} was not given #{name.inspect}"
+        end
+      end
+
+      # The legacy 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.
+      def to_args
+        facts.each_with_object({}) do |(name, found), args|
+          next if found.equal?(Absent)
+
+          args[name] = found.equal?(Null) ? nil : found.value
+        end
+      end
+
+      class << self
+        # **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:
+        #
+        #   :aggregate — facts first (`with:` checks), then `to:`
+        #   :entity    — `to:` first, then the block (which resolves the
+        #                entity chain, UnknownVerb), then facts
+        #   :port      — a reference attribute / identity field lifted into
+        #                `to:`, then `to:` (which a port operation requires),
+        #                then facts
+        #
+        # The block answers the declaring command or port operation (anything
+        # with `hecks_name` and `attributes`); it is called exactly once, at
+        # 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)
+          case receiver
+          when :aggregate
+            command = declaring.call
+            facts   = facts_for(command, with: with, legacy: legacy)
+            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))
+          when :port
+            port_call(verb, aggregate, declaring.call, to: to, with: with, legacy: legacy)
+          else
+            raise ArgumentError, "unknown receiver #{receiver.inspect}"
+          end
+        end
+
+        # `to:` as a `Routing::Envelope`, or nil when no `to:` was given.
+        def route(to, entity_depth: 0)
+          return nil if to.nil?
+
+          aggregate, entities = to.is_a?(Hash) ? envelope_hash(to) : scalar_envelope(to)
+
+          raise TypeMismatch, "to: must name the receiving aggregate identity" if aggregate.nil? || aggregate.to_s.empty?
+          if entities.size != entity_depth
+            raise TypeMismatch,
+                  "to: for an entity command needs #{entity_depth} entity " \
+                  "#{entity_depth == 1 ? 'identity' : 'identities'} after the aggregate — got #{entities.size}"
+          end
+          raise TypeMismatch, "to: contains a blank entity identity" if entities.any? do |identity|
+            identity.nil? || identity.to_s.empty?
+          end
+
+          Routing::Envelope.new(aggregate: aggregate, entities: entities)
+        end
+
+        # 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)
+          facts = offered.each_with_object({}) do |(name, value), found|
+            found[name] = value.nil? ? Null : Present.new(value: value)
+          end
+          declaring.attributes.each do |attribute|
+            name = attribute.name.to_sym
+            facts[name] = Absent unless facts.key?(name)
+          end
+          facts
+        end
+
+        private
+
+        # **The port operation shape** — formerly `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:`
+        # 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
+        # named for the owner's first `identified_by` field: that attribute
+        # is still a declared external fact `refuse_absent_arguments`
+        # expects to find (Rust's own comment: "declare only external facts
+        # 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
+          identity = operation.identity_attribute(aggregate.hecks_name)
+          if to.nil? && identity && legacy.key?(identity.name)
+            to = legacy.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)
+          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))
+        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
+        # spec/runtime/routing_envelope_shape_spec.rb.
+        def scalar_envelope(to)
+          return [to, []] if to.is_a?(String)
+
+          raise TypeMismatch, "to: must be a string aggregate identity or an entity route, got #{Rendering.describe(to)}"
+        end
+
+        def envelope_hash(to)
+          hash = to.transform_keys(&:to_sym)
+          unknown = hash.keys - %i[aggregate entity entities]
+          raise TypeMismatch, "to: does not recognize #{unknown.sort.join(', ')}" unless unknown.empty?
+
+          [hash[:aggregate], entity_identities(hash)]
+        end
+
+        # 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.
+        def entity_identities(hash)
+          raise TypeMismatch, "to: takes entity: or entities:, not both" if hash.key?(:entities) && hash.key?(:entity)
+
+          identities = hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
+          raise TypeMismatch, "to: entity route requires at least one entity identity" if identities.empty?
+
+          identities
+        end
+
+        # `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 —
+        # whether `to:` was given never enters this decision (BUG#17).
+        def offered_facts(declaring, with:, legacy:)
+          if with && !legacy.empty?
+            raise TypeMismatch,
+                  "dispatch takes command facts in with:, not both with: and loose keyword arguments"
+          end
+
+          return legacy unless with
+          raise TypeMismatch, "with: must be a hash of command facts" unless with.is_a?(Hash)
+
+          offered = with.transform_keys(&:to_sym)
+          declared = declaring.attributes.map { |attribute| attribute.name.to_sym }
+          refuse_unknown_facts!(declaring, offered, declared)
+          refuse_absent_facts!(declaring, offered, declared)
+          offered
+        end
+
+        # Unknown before absent — a `with:` that is both still refuses
+        # UnknownArgument first.
+        def refuse_unknown_facts!(declaring, offered, declared)
+          unknown = (offered.keys - declared).sort
+          return if unknown.empty?
+
+          raise UnknownArgument,
+                RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                           command: declaring.hecks_name, unknown: unknown,
+                                           declared: declared)
+        end
+
+        def refuse_absent_facts!(declaring, offered, declared)
+          absent = declaring.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
+          return if absent.empty?
+
+          raise AbsentArgument,
+                RefusalWording.render_site("AbsentArgument", "absent_args",
+                                           command: declaring.hecks_name, absent: absent,
+                                           declared: declared)
+        end
+      end
+    end
+  end
+end