hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -9,19 +9,19 @@ require_relative "../ports/persistence/remote_runtime"
 
 module Hecks
   module Runtime
-    # THE WRITE-SIDE HALF OF LAMBDA ROUTING — `Runtime::Loader.boot`
-    # constructs this INSTEAD OF `Dispatcher` when the booted domain's
+    # **The write-side half of lambda routing** — `Runtime::Loader.boot`
+    # constructs this instead of `Dispatcher` when the booted domain's
     # own `.world` declares Lambda routing (see loader.rb's own
     # `dispatcher_class_for`). Matches `Dispatcher`'s public shape
-    # closely enough that everything built ON TOP of a dispatcher —
+    # closely enough that everything built on top of a dispatcher —
     # `Handle`, `AggregateDoor`, `Facade::Surface` — needs no changes
     # at all: `Handle#run`'s entire contract is
-    # `@dispatcher.dispatch("#{fqn}.#{command}", **identity, **args).instance.state`,
+    # `@dispatcher.dispatch("#{fqn}.#{command}", to: @id, with: args).instance.state`,
     # and both classes answer that identically.
     #
-    # READS DELEGATE, WRITES DON'T. `query`/`reference_query` hand off
-    # to a REAL `Dispatcher` built over the SAME registry — since that
-    # registry's own repositories are ALREADY Lambda-backed
+    # **Reads delegate, writes don't**. `query`/`reference_query` hand off
+    # to a real `Dispatcher` built over the same registry — since that
+    # registry's own repositories are already Lambda-backed
     # (`Adapters::Lambda`, `persisted_by("Lambda")`, Phase 2's other
     # half), the inherited query machinery (`QueryInterpreter`,
     # `Ports::Query::InMemory.execute`) works completely unchanged, no
@@ -31,49 +31,120 @@ module Hecks
     # against incomplete local state and then merely persisted.
     class RemoteDispatcher
       Result = Struct.new(:verb, :instance, :events, keyword_init: true) do
+        # Reads the identity of the record the dispatch settled on.
+        #
+        # @return [String] the settled record's identity
         def id    = instance.id
+
+        # Reads the settled record's attributes as one Hash.
+        #
+        # @return [Hash{Symbol => Object}] the settled record's attributes, `:id` merged
+        #   in last
         def state = instance.to_h
       end
 
       attr_reader :registry
 
-      def initialize(registry, region: "us-east-1")
+      # @param registry [Runtime::Registry] the booted registry this dispatcher fronts;
+      #   read-side calls (`query`/`reference_query`) delegate to a local `Dispatcher`
+      #   built over the same registry
+      # @param region [String] the AWS region the routed Lambda function lives in
+      # @param function [String, nil] the `.world`'s own `dispatched_by("Lambda")`
+      #   function name, when the deployment stack is not named `hecks-<domain>`; nil
+      #   resolves the function name from `ENV["DOMAIN_NAME"]` or `registry.root`
+      def initialize(registry, region: "us-east-1", function: nil)
         @registry = registry
         # `File.basename(registry.root)`, not `bluebooks.keys.first` —
         # matches `Adapters::Lambda`'s own function-name resolution
         # exactly (see its own comment on why: one merged Lambda per
         # deploy, not one per attached chapter, and `root` is the one
         # signal every bluebook in this registry shares regardless of
-        # which one attached it) — INCLUDING that same adapter's own
+        # which one attached it) — including that same adapter's own
         # `ENV["DOMAIN_NAME"]`-first fix: `root` is always `/var/task`
         # inside a deployed Lambda, giving "task" instead of the real
         # domain name (a real, live AccessDeniedException on
         # "hecks-task" caught this).
-        @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root), region: region)
-        # READ-SIDE DELEGATE ONLY (see class comment) — never dispatched
+        # `function:` — the `.world`'s own `dispatched_by("Lambda")`
+        # naming of which function this is, for a deployment whose stack
+        # name isn't `hecks-<domain>` (Client's own comment has the real
+        # case). Absent, the resolution above is unchanged.
+        @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root),
+                                               region: region, function: function)
+        # Read-side delegate only (see class comment) — never dispatched
         # through; a real Dispatcher's own `query`/`reference_query`
         # already resolve generically via `registry.repository(...)`,
         # so building one here reuses that instead of duplicating it.
         @local = Dispatcher.new(registry)
       end
 
+      # Dispatches a command by verb, routing to the local `Dispatcher` or the
+      # remote Lambda depending on the aggregate's bound adapter.
+      #
+      # Same shape as `Dispatcher#dispatch_flat` — everything but
+      # `saga_correlation:` is forwarded through unread, `to:`/`with:`
+      # included, and lifted out downstream by whichever path actually
+      # dispatches (`@local.dispatch_flat` locally, the flat wire form
+      # remotely). Not the strict `to:`/`with:`-only door `Dispatcher#
+      # dispatch` is — see that class's own comment for why this file
+      # never had one.
+      #
+      # @param verb [String] the fully qualified verb, `"Domain::Aggregate.Command"`
+      #   or `"Domain::Aggregate.Entity.Command"`
+      # @param saga_correlation [Hash, nil] correlation head => value, stamped on every
+      #   emitted event when a saga leg causes this dispatch; nil otherwise
+      # @param args [Hash] the facts, plus optional `:to`/`:with` keys, read the same
+      #   way `dispatch_flat` reads them
+      # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
+      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
+      #   domain or aggregate that is not declared
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
+      #   locally-routed aggregate refuses the call
+      # @raise [Runtime::StaleWrite] if concurrent local writers beat this one through
+      #   every retry, for a locally-routed aggregate
+      # @raise [Runtime::WiringError] if the aggregate's adapter or repository cannot be
+      #   resolved, or the remote call is accepted but reports no mutation for it
+      # @raise [Runtime::RemoteRefusal] if the routed Lambda refuses the call
       def dispatch(verb, saga_correlation: nil, **args)
+        dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
+      end
+
+      # Routes a dispatch to the local `Dispatcher` when the aggregate's bound
+      # adapter is not remote-backed (`Ports::Persistence::RemoteRuntime`),
+      # otherwise dispatches through the routed Lambda. Same flat-facts wire
+      # form as `Dispatcher#dispatch_flat`.
+      #
+      # @param verb [String] the fully qualified verb, in any shape `dispatch` accepts
+      # @param args [Hash] the facts, plus optional Symbol keys `:to`, `:with` and
+      #   `:saga_correlation`, read as `dispatch`'s keywords of the same names; not mutated
+      # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
+      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
+      #   domain or aggregate that is not declared
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
+      #   locally-routed aggregate refuses the call
+      # @raise [Runtime::StaleWrite] if concurrent local writers beat this one through
+      #   every retry, for a locally-routed aggregate
+      # @raise [Runtime::WiringError] if the aggregate's adapter or repository cannot be
+      #   resolved, or the remote call is accepted but reports no mutation for it
+      # @raise [Runtime::RemoteRefusal] if the routed Lambda refuses the call
+      def dispatch_flat(verb, args = {})
+        args = args.dup
+        saga_correlation = args.delete(:saga_correlation)
         domain, aggregate_name, = Naming.split_verb(verb) ||
                                   raise(UnknownVerb,
-                                        RefusalWording.render("UnknownVerb", "not_fully_qualified", verb: verb.inspect))
+                                        RefusalWording.render_site("UnknownVerb", "not_fully_qualified", verb: verb))
         aggregate = @registry.bluebook(domain)&.aggregate(aggregate_name) ||
                     raise(UnknownVerb,
-                          RefusalWording.render("UnknownVerb", "no_aggregate", domain: domain, aggregate: aggregate_name.inspect))
+                          RefusalWording.render_site("UnknownVerb", "no_aggregate", domain: domain, aggregate: aggregate_name))
 
-        # NOT EVERY AGGREGATE IN A LAMBDA-ROUTED DOMAIN IS ITSELF
-        # LAMBDA-BOUND — Member's real name->email rekey carries a
+        # Not every aggregate in a lambda-routed domain is itself
+        # lambda-bound — Member's real name->email rekey carries a
         # `compute` rule (era_check.rb's own `check_compute_rules!`),
         # which can only ever run against Postgres, permanently. Its
-        # OWN `.hecksagon` bind stays "Postgres" even when
+        # own `.hecksagon` bind stays "Postgres" even when
         # `dispatched_by("Lambda")` is on for everything else — checked
-        # here by real CAPABILITY (`Ports::Persistence::RemoteRuntime`,
+        # here by real capability (`Ports::Persistence::RemoteRuntime`,
         # §1), not by comparing the adapter's own name to the string
-        # "Lambda" — a bind resolves to whatever adapter CLASS actually
+        # "Lambda" — a bind resolves to whatever adapter class actually
         # backs it, and only a class shaped like "the real interpreter
         # lives behind a call boundary" forwards here; anything else
         # (Postgres, Memory, any future local adapter) falls through to
@@ -82,7 +153,7 @@ module Hecks
         # all.
         adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
         unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
-          return @local.dispatch(verb, saga_correlation: saga_correlation, **args)
+          return @local.dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
         end
 
         response = @client.dispatch(verb, args)
@@ -90,14 +161,14 @@ module Hecks
         refusal = response.fetch("refusals", []).find { |r| r["verb"] == verb }
         raise RemoteRefusal, "#{verb} refused: #{refusal['error']}" if refusal
 
-        # THIS STEP'S OWN mutations — `mutations` is one entry per
+        # This step's own mutations — `mutations` is one entry per
         # replayed step (rust/host's rehydrate-and-replay design,
         # Phase 1), so `.last` is exactly the step just dispatched.
         # Matched by fully-qualified aggregate name, not just "the
-        # first mutation" — a command whose reaction ALSO mutates a
+        # first mutation" — a command whose reaction also mutates a
         # different aggregate (a policy, a saga leg) puts more than
         # one mutation in the same step, and the direct effect of
-        # THIS verb is the one this dispatch's own caller expects
+        # this verb is the one this dispatch's own caller expects
         # `.instance` to be.
         fqn = "#{domain}::#{aggregate.hecks_name}"
         mutation = response.fetch("mutations", []).last&.find { |m| m["aggregate"] == fqn } ||
@@ -110,16 +181,46 @@ module Hecks
         Result.new(verb: verb, instance: instance, events: step_events(response))
       end
 
+      # Delegates to the local `Dispatcher` built over the same registry — see the
+      # class comment on why reads, unlike writes, need no remote-specific logic.
+      #
+      # @param verb [String, Symbol] the query's verb, in one of `Dispatcher#query`'s
+      #   three shapes
+      # @param args [Hash{Symbol => Object}] the query's declared arguments
+      # @return [Array<Hash>] see `Dispatcher#query`'s own return
+      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
+      #   domain, aggregate, entity, query or read model that is not declared
+      # @raise [Runtime::NotFound] if a read model's root reference names no record
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+      # @raise [KeyError] if a rooted read model is asked without its reference argument
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def query(verb, **args)           = @local.query(verb, **args)
+
+      # Delegates to the local `Dispatcher` built over the same registry — see the
+      # class comment on why reads, unlike writes, need no remote-specific logic.
+      #
+      # @param verb [String] the fully qualified query verb, `"Domain::Aggregate.Query"`
+      #   or `"Domain::Aggregate.Entity.Query"`
+      # @param args [Hash{Symbol => Object}] the query's declared arguments
+      # @return [Array<Hash>] one Hash per matching record, its state with `:id` merged
+      #   in last; for an entity query, one Hash per matching element
+      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
+      #   domain, aggregate, entity or query that is not declared
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def reference_query(verb, **args) = @local.reference_query(verb, **args)
 
-      # THE FULL DOMAIN'S EVENT HISTORY, on every call — `{"read":
+      # Fetches the full domain's event history, on every call — `{"read":
       # true}` replays the whole journal (Phase 1's `dispatch::read`),
-      # so its own `events` array already IS the complete log, the
+      # so its own `events` array already is the complete log, the
       # same thing `@registry.event_log` would answer for a local
       # dispatch. Not cached: `AggregateDoor.events`/`Handle#events`
       # are not called in this codebase's own hot paths today: if that
       # changes, caching belongs here, not in every caller.
+      #
+      # @return [Array<Runtime::Event>] every event in the routed Lambda's domain
+      #   journal, oldest first, with `occurred_at` always nil (the kernel is
+      #   timestamp-free by design)
       def events
         @client.read.fetch("events", []).map { |e| build_event(e) }
       end

data/lib/hecks/runtime/routing.rb

@@ -1,14 +1,18 @@
-require_relative "errors"
-require_relative "refusal_wording"
-require_relative "../rendering"
-
 module Hecks
   module Runtime
     # The invocation address is not part of a command's domain payload.
     # Aggregate commands carry one receiver identity; entity commands carry
     # the aggregate receiver followed by one identity for every entity hop.
+    #
+    # Reading a call's shape — what `to:` and `with:` mean, the BUG#7/#17/#18
+    # rules — lives in `Runtime::Invocation.from_call` now (invocation.rb).
+    # `envelope`/`payload` are kept as thin delegators for any caller still
+    # naming them; the dispatcher itself builds an Invocation instead.
     module Routing
       Envelope = Struct.new(:aggregate, :entities, keyword_init: true) do
+        # @param aggregate [String, #to_s] the receiving aggregate's identity
+        # @param entities [Array<String, #to_s>, nil] the entity-hop identities after the
+        #   aggregate, in call order; empty for an aggregate-level command
         def initialize(aggregate:, entities: [])
           super(aggregate: aggregate.to_s, entities: Array(entities).map(&:to_s).freeze)
           freeze
@@ -17,158 +21,36 @@ module Hecks
 
       module_function
 
-      def envelope(to, entity_depth: 0)
-        return nil if to.nil?
-
-        aggregate, entities = to.is_a?(Hash) ? parse_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
-
-        Envelope.new(aggregate: aggregate, entities: entities)
-      end
-
-      # BUG#7 — the non-Hash half of `to:` used to accept ANY Ruby object
-      # (`[to, []]`, unconditionally) as though it were a ready-made
-      # aggregate identity scalar. That is looser than the JSON step
-      # boundary (`bin/run`/`Fuzzing::Replay`/`StepBuilder`) ever needs it
-      # to be — every legitimate caller already hands this a `String`
-      # (`Naming.identity` canonicalizes every identity to one before it
-      # ever reaches a `to:`/legacy-args door) — and looser than Rust's own
-      # hand-written mirror of this exact boundary
-      # (`rust/src/kernel/routing.rs#RoutingEnvelope::from_json`, its own
-      # header: "Generated routers accept this shape while retaining the
-      # legacy mixed-args object as a compatibility input during
-      # migration"), which refuses anything that is neither a JSON string
-      # nor object outright, TypeMismatch, before ever reaching a domain's
-      # own command payload.
+      # Resolves a `to:` argument into a routing envelope. A thin delegator to
+      # `Invocation.route`; the dispatcher itself builds an `Invocation` instead.
       #
-      # The gap surfaced live on `examples/roster` — the first domain in
-      # this corpus to declare a command attribute literally named `to`
-      # (`Roster::Roster.Mark`, deliberately, per that bluebook's own
-      # header comment). `bin/qa_sweep`'s legacy-args dispatch convention
-      # (`runtime.dispatch(verb, **symbolize(args))`, `step_builder.rb`)
-      # flattens a command's own declared fact and its routing target into
-      # ONE Ruby kwargs hash — completely ordinary for every other domain,
-      # since Ruby's keyword-argument binding only steals a key that
-      # collides with `dispatch`'s own `to:`/`with:`/`saga_correlation:`
-      # parameter names. `Mark`'s `to` does collide, so a fuzzer-corrupted
-      # scalar offered for it (an out-of-range Integer, from
-      # `InvalidValueGenerator.corrupt`) was routed here as the AGGREGATE
-      # IDENTITY instead of the domain's own required argument — accepted
-      # unconditionally, leaving `Mark`'s own `to` fact absent from the
-      # payload entirely. Ruby refused `AbsentArgument` ("Mark was not
-      # given to — it takes to"); Rust's stricter `RoutingEnvelope::
-      # from_json` refuses the malformed scalar itself, TypeMismatch,
-      # before the domain payload is ever examined — the observed
-      # divergence. Tightening this branch to Rust's own contract (a
-      # scalar `to:` must be a `String`) makes both refuse the same way,
-      # for the same reason, at the same step.
-      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
-      private_class_method :scalar_envelope
-
-      # The Hash-shaped half of `to:` — pulled out of `envelope` because
-      # it is a self-contained parse (raises on an unrecognized key, then
-      # returns the pair) with no dependency on anything `envelope` does
-      # afterward; the validations that follow apply the same way
-      # whichever branch produced `aggregate`/`entities`.
-      def parse_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
-      private_class_method :parse_envelope_hash
-
-      # `with:` is deliberately strict. Compatibility-only calls still pass
-      # loose keyword arguments through the old addressing gate, but a caller
-      # choosing the explicit envelope cannot smuggle receiver identity back
-      # into the payload.
-      def payload(command, 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 = command.attributes.map { |attribute| attribute.name.to_sym }
-        refuse_unknown_facts!(command, offered, declared)
-        refuse_absent_facts!(command, offered, declared)
-        offered
-      end
-
-      # The two `with:` shape checks `payload` runs in sequence — pulled
-      # out because each is a self-contained "compute a difference, raise
-      # if non-empty" rule with no dependency on the other. Order stays
-      # unknown-before-absent, exactly as inline: `payload` calls them in
-      # that order, so a fact that is both unknown AND leaves something
-      # else absent still raises UnknownArgument first, same as before.
-      def refuse_unknown_facts!(command, offered, declared)
-        unknown = (offered.keys - declared).sort
-        return if unknown.empty?
-
-        reading = declared.empty? ? "none" : declared.join(", ")
-        raise UnknownArgument,
-              RefusalWording.render("UnknownArgument", "unknown_args",
-                                    command: command.hecks_name, unknown: unknown.join(", "),
-                                    declared: reading)
-      end
-      private_class_method :refuse_unknown_facts!
-
-      def refuse_absent_facts!(command, offered, declared)
-        absent = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
-        return if absent.empty?
-
-        reading = declared.empty? ? "none" : declared.join(", ")
-        raise AbsentArgument,
-              RefusalWording.render("AbsentArgument", "absent_args",
-                                    command: command.hecks_name, absent: absent.sort.join(", "),
-                                    declared: reading)
-      end
-      private_class_method :refuse_absent_facts!
-
-      # BUG#18 — an entity route naming NO entity at all (`entities: []`,
-      # or neither `entity:` nor `entities:` present) used to come back
-      # `[]` here unremarked, which only ever refused downstream for an
-      # ENTITY command (`envelope`'s own `entities.size != entity_depth`
-      # check, entity_depth >= 1) — for an AGGREGATE-level command
-      # (entity_depth 0), `[].size == 0` trivially satisfied that check,
-      # so the degenerate Hash `{aggregate:, entities: []}` reached the
-      # command's own validation instead of being refused as malformed
-      # routing. Rust's `RoutingEnvelope::from_json` never let it get
-      # that far: the Hash branch refuses "entity route requires at
-      # least one entity identity" unconditionally, before any
-      # entity_depth is known. Refusing it here too, at the same point,
-      # closes the gap without touching the scalar branch (a bare
-      # aggregate identity, no Hash at all) that every ordinary aggregate
-      # dispatch already uses instead of this shape (`Facade::Handle#
-      # dispatch`'s own `to: @id`, `CommandRequest`'s own header —
-      # "aggregate command: { to: "record-id", ... }" — and, now,
-      # `Judge#address`).
-      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
+      # @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 the call expects
+      # @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 envelope(to, entity_depth: 0) = Invocation.route(to, entity_depth: entity_depth)
+
+      # Resolves a command's offered facts into its flat args hash. A thin
+      # delegator to `Invocation.facts_for` for any caller still naming it.
+      #
+      # Loaded by invocation.rb (which requires this file), so `Invocation`
+      # is always defined by the time either method runs.
+      #
+      # @param command [Class] a `Bluebook::Command` subclass (or port-operation class)
+      #   responding to `hecks_name` and `attributes`
+      # @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 => Object}] the offered facts by attribute name; an
+      #   attribute offered as nil is kept as nil
+      # @raise [Runtime::TypeMismatch] if both `with` and a non-empty `flat` are given, if
+      #   `with` is not a Hash, or if `with` names an unknown or omits a required attribute
+      def payload(command, with:, flat:)
+        facts = Invocation.facts_for(command, with: with, flat: flat)
+        Invocation.new(verb: nil, target: nil, facts: facts).to_args
       end
-      private_class_method :entity_identities
     end
   end
 end

data/lib/hecks/runtime/saga_interpreter/correlation.rb

@@ -3,27 +3,27 @@ require_relative "../value"
 module Hecks
   module Runtime
     class SagaInterpreter
-      # How a saga decides WHICH CONVERSATION an event belongs to — three
+      # How a saga decides which conversation an event belongs to — three
       # tiers, each one a lesson.
       module Correlation
         private
 
-        # A DOTTED PATH NAMES THE SCALAR FIELD, rather than asking a value object
+        # A dotted path names the scalar field, rather than asking a value object
         # to stand in for one. `correlates_by :end_to_end` would key a saga on
         # the whole ExternalTransfer::EndToEndReference — and what a non-scalar
-        # correlation key even IS is representation-dependent (the object
+        # correlation key even is is representation-dependent (the object
         # itself? its serialised text?). `:"end_to_end.value"` reads the one
         # field with a single unambiguous rendering.
         def saga_correlation(process_manager, event)
           path  = process_manager.correlates_by.to_s.split(".")
-          # A LATER EVENT MAY ALREADY HOLD THE SCALAR. `reference.value` digs a
-          # value object's field out of a FRESH declaration (TransferRequested's
-          # `reference` IS a TransferReference) — but a downstream event this
+          # A later event may already hold the scalar. `reference.value` digs a
+          # value object's field out of a fresh declaration (TransferRequested's
+          # `reference` is a TransferReference) — but a downstream event this
           # same value was smuggled through as a passthrough argument
           # (AccountDebited's `reference:`, resolved by `dispatch_args` to the
           # bare correlation string) carries it as a scalar already, with
           # nothing left to dig. `"xfer-1".respond_to?(:[])` is true — String
-          # has its OWN `[]` (substring indexing) — so checking for keyed
+          # has its own `[]` (substring indexing) — so checking for keyed
           # lookup explicitly, rather than "responds to `[]` at all", is what
           # stops the second segment from being read as a symbol index into a
           # string that has already arrived.
@@ -32,9 +32,9 @@ module Hecks
           end
           return value unless value.to_s.empty?
 
-          # THE STAMP — `deliver_saga_dispatch` marks its own event before this
+          # **The stamp** — `deliver_saga_dispatch` marks its own event before this
           # saga's next step ever asks, for a leg whose command declares
-          # NEITHER the correlation field itself nor the emitting aggregate's
+          # neither the correlation field itself nor the emitting aggregate's
           # own reference key (the two tiers above). command_interpreter/
           # argument_gate.rb names the old payload-only lookup "the weakest
           # part of the gate" : a correlation key arriving on a command only
@@ -48,34 +48,32 @@ module Hecks
           stamped = event.correlation && event.correlation[process_manager.correlation_head.to_s]
           return stamped unless stamped.nil? || stamped.to_s.empty?
 
-          # A SELF-REFERENCING LEG carries the correlation forward under its
+          # A self-referencing leg carries the correlation forward under its
           # own emitting record's identity — `event.id`, not a field dug back
-          # out of the payload. This used to read `event.payload[own_key]`
-          # (`own_key` the aggregate's own reference-key convention, "wire",
-          # "transfer"), which only ever held a value because LEGACY dispatch
-          # left the self-addressing key riding along in the payload
-          # unfiltered. Routing separated from payload (`to:`/`with:`, the
-          # facade's own `Handle#run` always uses it) closed exactly that
-          # leak — correctly, since an addressing key is not a fact the
-          # payload should carry — which left this tier reading an empty
-          # Hash for any self-referencing leg with no OTHER declared
-          # attributes (`OnboardingCase.Clear`, `.Decline` — no `attribute`
-          # lines at all): the saga silently stopped advancing, forever, for
-          # exactly the leg this tier exists to correlate.
+          # out of the payload, because an addressing key is not a fact the
+          # payload should carry: routing is kept separate from payload
+          # (`to:`/`with:`, the facade's own `Handle#run` always uses it), so
+          # `own_key` (the aggregate's own reference-key convention, "wire",
+          # "transfer") never rides along in the payload unfiltered. Digging
+          # for it there would read an empty Hash for any self-referencing
+          # leg with no other declared attributes (`OnboardingCase.Clear`,
+          # `.Decline` — no `attribute` lines at all), silently stopping the
+          # saga from advancing, forever, for exactly the leg this tier
+          # exists to correlate.
           #
           # `event.id` says the identical thing this tier always meant —
           # "the record that just emitted this event, by its own identity" —
           # and unlike a payload dig it is populated by the record itself,
           # not by which dispatch convention the caller happened to use.
           #
-          # GATED, still — a manually-dispatched command on a wholly
-          # UNRELATED aggregate can share an event NAME this process_manager happens to
+          # Gated, still — a manually-dispatched command on a wholly
+          # unrelated aggregate can share an event name this process_manager happens to
           # handle (`Drawer.Take` also emits "Taken", the same name a
-          # SAGA-DISPATCHED leg uses) with nothing this saga should read as
+          # saga-dispatched leg uses) with nothing this saga should read as
           # its own conversation. What makes a leg genuinely
           # self-referencing — the one fact worth trusting `event.id`
-          # for — is that `correlates_by`'s own head field IS this event's
-          # OWN aggregate's declared identity, not merely a same-shaped
+          # for — is that `correlates_by`'s own head field is this event's
+          # own aggregate's declared identity, not merely a same-shaped
           # name: `OnboardingCase.identity_heads` really does include
           # `:reference`, `correlates_by :"reference.value"`'s own head ;
           # `Drawer.identity_heads` is `[:number]`, nowhere close.