hecks 1.4.0 → 1.5.1

data/lib/hecks/runtime/registry.rb

@@ -16,12 +16,17 @@ module Hecks
 
       attr_reader :root, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :event_log,
                   :reaction_log, :saga_log, :saga_instances, :translations, :saga_mutex,
-                  :saga_dispatch_log, :policy_dispatch_log
+                  :saga_dispatch_log, :policy_dispatch_log, :bluebook_sources,
+                  :pending_privacy_markings
 
+      # @param root [String, nil] the booting project's root directory, the base
+      #   a shared ports/adapters root and a `.world`'s own relative paths resolve
+      #   against; nil for a registry with no such root
       def initialize(root: nil)
         @root         = root
         @bluebooks    = {}
-        @hecksagons   = {}
+        @bluebook_sources = {}
+        @hecksagons = {}
         @ports = {}
         @adapters     = {}
         @worlds       = {}
@@ -29,6 +34,14 @@ module Hecks
         @event_log    = []
         @reaction_log = []
         @saga_log = []
+        # A DECLARATIVE FACT, NOT YET A DISPATCHED ONE — `AggregateDoor#
+        # mark_sensitive` (called from a `.hecksagon` file, the same way
+        # `port`/`persisted_by` already are) appends here at
+        # hecksagon-build time; `Runtime::Loader.boot`'s own post-dispatcher
+        # step turns each entry into a real `Privacy::Marking.Mark`,
+        # idempotently, the same "declared here, taken effect once boot
+        # actually has a dispatcher" shape `redrive_outbox!` already has.
+        @pending_privacy_markings = []
         # **Additive, Ruby-only** — never merged into saga_log/reaction_log.
         # rust/src/kernel/orchestrate.rs ports those two arrays' exact
         # shape byte-for-byte (spec/rust_conformance_spec.rb's own
@@ -112,6 +125,14 @@ module Hecks
       # several files (`language/bluebook/*.bluebook`, all `Hecks.bluebook "Bluebook"`)
       # needs its declarations to accumulate into one builder rather than each
       # file minting its own and silently discarding the one before.
+      #
+      # @param name [String, Symbol] the chapter name the builder accumulates
+      #   declarations for
+      # @yield the block that mints a fresh builder, called only the first time
+      #   `name` is asked for
+      # @yieldreturn [Bluebook::DSL::BluebookBuilder] a fresh builder for `name`
+      # @return [Bluebook::DSL::BluebookBuilder] the builder already open for
+      #   `name`, or the block's freshly minted one on the first call
       def bluebook_builder(name)
         @bluebook_builders[name.to_s] ||= yield
       end
@@ -130,20 +151,53 @@ module Hecks
       # registry/saga_persistence.rb) there is no concurrent caller for
       # `Hecks/ThreadSharedIvarMutation` to actually be warning about here.
       # rubocop:disable Hecks/ThreadSharedIvarMutation
+      # Registers a loaded chapter, keyed by its own declared name.
+      #
+      # @param item [Bluebook::Chapter] the loaded, judged chapter
+      # @return [Bluebook::Chapter] `item`, unchanged
       def add_bluebook(item) = @bluebooks[item.name] = item
 
+      # PROVENANCE, SIDE-CHANNEL — which real `.bluebook` file(s)
+      # contributed to a chapter name, never part of the exported IR (a
+      # boot-time loading fact, not a domain fact) and never Rust-mirrored
+      # (the same "additive, Ruby-only" shape `@translations` above already
+      # is). Legitimate accumulation (several files declaring the SAME
+      # chapter name on purpose — `lib/hecks/language/bluebook/*.bluebook`
+      # all open `Hecks.bluebook "Bluebook"`) pushes more than one path
+      # here too; that alone is not a problem. What this exists to let
+      # `refuse_cross_package_bluebook_merge!` (registry/verification.rb)
+      # catch is TWO UNRELATED PACKAGES accumulating into the same name by
+      # coincidence — a stale vendored fork's own copy of a real gem's
+      # chapter, still reachable on the load path, silently merging its
+      # aggregates into the real one via this exact accumulation mechanism.
+      def record_bluebook_source(name, path)
+        (@bluebook_sources[name.to_s] ||= []) << path
+      end
+
       # Merged, not replaced — recovered, not new (see Runtime::Loader
       # .boot's own comment for the provenance). A domain's hecksagon can
       # now load in more than one block for the same domain (base file
       # plus an `environments/<name>.hecksagon` overlay), and the second
       # block should add to what the first declared, not silently
       # discard it.
+      #
+      # @param item [Bluebook::Hecksagon] the declared wiring to register
+      # @return [void]
       def add_hecksagon(item)
         existing = @hecksagons[item.domain]
         @hecksagons[item.domain] = existing ? merge_hecksagons(existing, item) : item
       end
 
+      # Registers a loaded port, keyed by its own declared name.
+      #
+      # @param item [Bluebook::Port, Bluebook::DomainPort] the loaded port
+      # @return [Bluebook::Port, Bluebook::DomainPort] `item`, unchanged
       def add_port(item) = @ports[item.name] = item
+
+      # Registers a loaded adapter, keyed by its own declared name.
+      #
+      # @param item [Bluebook::Adapter] the loaded, judged adapter
+      # @return [Bluebook::Adapter] `item`, unchanged
       def add_adapter(item) = @adapters[item.name] = item
 
       # Merged, not replaced — the same generalization for `World` that
@@ -156,12 +210,40 @@ module Hecks
       # bare verb key and the `"verb:adapter"` qualified key point at the
       # same resolved hash) — an overlay's key wins over the base's same
       # key; a key only the base declares survives untouched.
+      #
+      # @param item [Bluebook::World] the declared world settings to register
+      # @return [void]
       def add_world(item)
         existing = @worlds[item.domain]
         @worlds[item.domain] = existing ? merge_worlds(existing, item) : item
       end
 
+      # Registers a loaded translation.
+      #
+      # @param item [Bluebook::Translation] the loaded, judged translation
+      # @return [Array<Bluebook::Translation>] every translation registered so far,
+      #   `item` last
       def add_translation(item) = @translations << item
+
+      # Declares one attribute of one domain's own aggregate sensitive — called from a
+      # terminal `has_<category>(readable_by:)` on a `Bluebook::DSL::AttributePath`
+      # (reached by chaining off a bare `Domain::Aggregate` inside a `.hecksagon` file
+      # being `Kernel.load`ed, or off an already-installed `AggregateDoor`), same timing
+      # (and same thread-safety argument, above) as `add_bluebook`/`add_port`. Recorded,
+      # not dispatched: `Runtime::Loader.boot`'s own `seed_privacy_markings!` turns each
+      # entry into a real `Privacy::Marking.Mark` once a dispatcher exists.
+      #
+      # @param domain [String] the marked attribute's own aggregate FQN, e.g.
+      #   `"Lifeadelics::Registration"`
+      # @param attribute_path [String] the dotted path within that aggregate, e.g.
+      #   `"attendee.medications"`
+      # @param category [String] the marking's own sensitivity category, e.g. `"phi"`
+      # @param readable_by [String] the Governance role a read must hold, unredacted
+      # @return [void]
+      def add_pending_privacy_marking(domain:, attribute_path:, category:, readable_by:)
+        @pending_privacy_markings << { domain: domain, attribute_path: attribute_path,
+                                        category: category, readable_by: readable_by }
+      end
       # rubocop:enable Hecks/ThreadSharedIvarMutation
 
       # {domain name => era ordinal} as resolved by the boot-time era
@@ -176,10 +258,30 @@ module Hecks
       # an old checkout only — see `initialize`'s own comment on it.
       attr_reader :superseded_eras
 
+      # Finds a loaded chapter by name.
+      #
+      # @param name [String, Symbol] the chapter's declared name
+      # @return [Bluebook::Chapter, nil] the chapter, or nil if none is registered
+      #   under `name`
       def bluebook(name)  = @bluebooks[name.to_s]
+
+      # Finds a domain's registered wiring by name.
+      #
+      # @param name [String, Symbol] the domain name
+      # @return [Bluebook::Hecksagon, nil] the domain's wiring, or nil if none is
+      #   registered under `name`
       def hecksagon(name) = @hecksagons[name.to_s]
+
+      # Finds a domain's registered world settings by name.
+      #
+      # @param name [String, Symbol] the domain name
+      # @return [Bluebook::World, nil] the domain's world, or nil if none is
+      #   registered under `name`
       def world(name)     = @worlds[name.to_s]
 
+      # Every verb every loaded chapter declares, sorted.
+      #
+      # @return [Array<String>] every declared verb, across every loaded chapter
       def verbs = @bluebooks.values.flat_map(&:verbs).sort
 
       # The chapter that answers a role check for `domain` — the domain's
@@ -188,6 +290,10 @@ module Hecks
       # every check for the literal name "Governance": Governance is
       # recognised by what it declares, and a chapter that declares the
       # same thing is recognised the same way.
+      #
+      # @param domain [String, Symbol] the domain whose role checks are being resolved
+      # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s role
+      #   checks, or nil if none does
       def authorization_provider_for(domain)
         names = [domain.to_s, *Array(hecksagon(domain)&.framework_members)]
         names.filter_map { |name| bluebook(name) }
@@ -195,10 +301,24 @@ module Hecks
       end
 
       # Every loaded chapter declaring `provides "authorization"`.
+      #
+      # @return [Array<Bluebook::Chapter>] every loaded chapter that provides
+      #   authorization
       def authorization_providers
         @bluebooks.values.select { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
       end
 
+      # Resolves and memoizes `aggregate`'s authoritative repository.
+      #
+      # @param domain [String, Symbol] name of the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate to resolve a repository for
+      # @return [Persistence::AppendOnly] repository over the aggregate's authoritative
+      #   adapter, or over a `Memory` adapter when the domain declares no hecksagon
+      # @raise [Runtime::WiringError] if the aggregate has no authoritative bind, more than
+      #   one, or a bind with a role this port does not support; or if the bound adapter is
+      #   unknown, answers a different verb, is given a setting it does not declare, has no
+      #   Ruby implementation, or lacks a method its port's `answers` list or the
+      #   append-only contract (`append`, `project`, `entries`) requires
       def repository(domain, aggregate)
         @repositories[[domain.to_s, aggregate.hecks_name]] ||= Ports::Persistence.repository(self, domain, aggregate)
       end
@@ -216,8 +336,8 @@ module Hecks
       # that store again, the way `Loader.boot_files` does after
       # `verify!`.
       #
-      # What this is for: a test runner that used to boot a runtime per
-      # test to get isolation (`Behaviors::Expectations.run_one`) — ~2s a
+      # What this is for: a test runner that would otherwise boot a runtime
+      # per test to get isolation (`Behaviors::Expectations.run_one`) — ~2s a
       # boot, 76 chess behaviours = two and a half minutes of booting the
       # same two files — can now boot once and reset between tests.
       #
@@ -229,6 +349,8 @@ module Hecks
       # single-threaded example loop. No production dispatch path calls
       # this at all — a live Puma worker pool never resets a registry out
       # from under itself mid-flight.
+      #
+      # @return [Runtime::Registry] self
       # rubocop:disable-next Hecks/ThreadSharedIvarMutation
       def reset_runtime_state!
         @event_log.clear
@@ -250,6 +372,17 @@ module Hecks
       # gives, just without a lazy `||=` race on standing it up.
       attr_reader :capability_graph
 
+      # Resolves and memoizes the repository to read `aggregate` from — a caught-up
+      # projection when one is bound and current, otherwise the authoritative repository.
+      #
+      # @param domain [String, Symbol] name of the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate to resolve a read
+      #   repository for
+      # @return [Persistence::AppendOnly] the projection repository when one is bound
+      #   and caught up with the authoritative store; the authoritative repository
+      #   otherwise
+      # @raise [Runtime::WiringError] if the authoritative or projection bind cannot
+      #   be resolved
       def read_repository(domain, aggregate)
         key = [domain.to_s, aggregate.hecks_name]
         binding = Ports::Projection.binds_for(self, domain, aggregate).first
@@ -264,6 +397,15 @@ module Hecks
         projection_current?(projection, authoritative) ? projection : authoritative
       end
 
+      # Reports whether `projection`'s own journal entries and rows agree with
+      # `authoritative`'s, entry-for-entry.
+      #
+      # @param projection [Persistence::AppendOnly] the projection repository to check
+      # @param authoritative [Persistence::AppendOnly] the authoritative repository to
+      #   check `projection` against
+      # @return [Boolean] true when `projection` holds the same entries and rows as
+      #   `authoritative`, in the same order; false on any mismatch, or if comparing
+      #   them raises
       def projection_current?(projection, authoritative)
         projected_entries = projection.entries
         source_entries = authoritative.entries
@@ -288,6 +430,12 @@ module Hecks
       # authoritative bind" check is what actually catches a genuine
       # double-bind; this merge only concatenates, it does not itself
       # decide which of two binds for the same aggregate wins.
+      #
+      # @param base [Bluebook::Hecksagon] the domain's already-registered wiring
+      # @param overlay [Bluebook::Hecksagon] the newly loaded block's own wiring to
+      #   fold in
+      # @return [Bluebook::Hecksagon] a new wiring with every list-shaped fact
+      #   concatenated, `base` then `overlay`
       def merge_hecksagons(base, overlay)
         Bluebook::Hecksagon.new(
           domain:             base.domain,
@@ -305,6 +453,11 @@ module Hecks
       # also declares replaces that key's whole resolved hash (the same
       # all-or-nothing shape `WorldBuilder#method_missing` already builds
       # each entry as), it does not deep-merge field by field within it.
+      #
+      # @param base [Bluebook::World] the domain's already-registered world
+      # @param overlay [Bluebook::World] the newly loaded block's own world to fold in
+      # @return [Bluebook::World] a new world with `overlay`'s scalars winning when
+      #   present, and `settings` shallow-merged, `overlay`'s keys winning
       def merge_worlds(base, overlay)
         Bluebook::World.new(
           domain:   base.domain,

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -16,7 +16,7 @@ module Hecks
     # 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
@@ -31,12 +31,27 @@ 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
 
+      # @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` —
@@ -62,14 +77,55 @@ module Hecks
         @local = Dispatcher.new(registry)
       end
 
-      # Same deprecation as `Dispatcher#dispatch` — loose keyword facts warn;
-      # `to:`/`with:` do not.
+      # 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)
-        Dispatcher.deprecate_loose_facts(args.except(:to, :with))
         dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
       end
 
-      # Same flat-facts wire form as `Dispatcher#dispatch_flat`.
+      # 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)
@@ -125,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
       # 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

@@ -10,6 +10,9 @@ module Hecks
     # 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
@@ -18,12 +21,34 @@ module Hecks
 
       module_function
 
+      # Resolves a `to:` argument into a routing envelope. A thin delegator to
+      # `Invocation.route`; the dispatcher itself builds an `Invocation` instead.
+      #
+      # @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.
-      def payload(command, with:, legacy:)
-        facts = Invocation.facts_for(command, with: with, legacy: legacy)
+      #
+      # @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
     end

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

@@ -50,18 +50,16 @@ module Hecks
 
           # 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" —

data/lib/hecks/runtime/saga_interpreter.rb

@@ -28,14 +28,29 @@ module Hecks
 
       attr_reader :registry
 
+      # @param registry [Runtime::Registry] the booted registry whose declared
+      #   process managers and saga persistence this interpreter runs against
+      # @param door [Runtime::Dispatcher] the dispatcher a saga leg's own dispatch
+      #   re-enters through
       def initialize(registry, door:)
         @registry = registry
         @door     = door
       end
 
+      # Runs `domain`'s declared process managers against `event`: begins,
+      # advances or ends each matching saga instance, checkpointing durably
+      # before its own dispatches run.
+      #
       # `only:` — one process manager, the outbox relay's way of running
       # exactly the consumer a row names (`Runtime::Outbox::Relay#
       # run_consumer`); nil advances every manager the domain declares.
+      #
+      # @param event [Runtime::Event] the just-emitted event to react to
+      # @param domain [String, Symbol] the domain whose declared process managers
+      #   are checked
+      # @param only [Bluebook::ProcessManager, nil] one process manager to run
+      #   exactly, instead of every manager `domain` declares
+      # @return [void]
       def advance(event, domain, only: nil)
         bluebook = @registry.bluebook(domain)
         return unless bluebook
@@ -56,12 +71,11 @@ module Hecks
       # could otherwise interleave their writes out of order, silently
       # reordering a saga's own transition history — worse for the
       # adapters with no locking of their own (Heki) than for Postgres.
-      # `deep_copy` guards against the exact shape of bug PR #175 itself
-      # already found once (over-freezing a live, still-mutated Hash) —
-      # never hand a persistence adapter the same object `advance_saga`/
-      # `unwind` go on to mutate in place; round-tripping through JSON
-      # is also what guarantees the value is safe for every adapter that
-      # itself calls `JSON.generate` on it.
+      # `deep_copy` guards against a real bug shape (over-freezing a live,
+      # still-mutated Hash) — never hand a persistence adapter the same
+      # object `advance_saga`/`unwind` go on to mutate in place;
+      # round-tripping through JSON is also what guarantees the value is
+      # safe for every adapter that itself calls `JSON.generate` on it.
       # `pending:` — see saga_pending_dispatch.rb. Injected into the
       # written copy of memory only, never into `instance[:memory]`
       # itself: every other reader of a live instance's memory
@@ -423,7 +437,7 @@ module Hecks
         # Same non-reentrancy reasoning as `advance_saga`'s own comment —
         # the mutex covers only the check-and-mutate-and-checkpoint step.
         advanced = @registry.saga_mutex.synchronize do
-          # The compensating leg is selected by (REFUSED, current state)
+          # The compensating leg is selected by (`REFUSED`, current state)
           # too — C10.3, one rule for every leg.
           handler = process_manager.handler_for(REFUSED, instance[:state])
           unless handler
@@ -507,9 +521,9 @@ module Hecks
       end
 
       # BUG#6 — unconditionally the saga's own home domain, never inferred
-      # from `command_name`'s own shape. This used to guess: a leftover
-      # `::` after `Naming.command_ref`'s own rewrite was read as "already
-      # domain-qualified" and left alone. That heuristic cannot actually
+      # from `command_name`'s own shape. Guessing from a leftover
+      # `::` after `Naming.command_ref`'s own rewrite (read as "already
+      # domain-qualified" and left alone) cannot actually
       # tell a genuinely cross-domain reference (`Banking::Account::
       # Debit` -> one `::` survives) apart from a same-domain entity
       # command reference (`Manifest::Slot::Fill` -> one `::` survives
@@ -519,11 +533,11 @@ module Hecks
       # (confirmed against `Naming.command_ref`'s own rewrite: it only
       # ever strips the last `::`, so the count of what remains is blind
       # to why it's there). Picking the cross-domain reading unconditionally
-      # left `qa/stress_domains/waybill`'s own `Packing` saga dispatching
+      # would leave `qa/stress_domains/waybill`'s own `Packing` saga dispatching
       # `Manifest::Slot::Fill` — an entity command in its own domain —
-      # unprefixed, so `Naming.split_verb` read "Manifest" as a domain
+      # unprefixed, so `Naming.split_verb` would read "Manifest" as a domain
       # name instead of this chapter's own aggregate, and the dispatch
-      # failed with `UnknownVerb`, silently recorded as an ordinary
+      # would fail with `UnknownVerb`, silently recorded as an ordinary
       # domain refusal rather than surfacing as the real bug it is.
       #
       # The fix mirrors `PolicyInterpreter#deliver`'s own mechanism,