hecks 1.3.0 → 1.4.0

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -3,41 +3,41 @@ require_relative "../saga_pending_dispatch"
 module Hecks
   module Runtime
     class Registry
-      # SAGA PERSISTENCE — no new DSL verb, no new world setting.
+      # **Saga persistence** — no new DSL verb, no new world setting.
       # Whatever adapter a domain's own aggregates already use for
       # durability, its sagas use the same one, automatically: three
-      # OPTIONAL adapter methods (`save_saga`/`delete_saga`/`each_saga`),
+      # optional adapter methods (`save_saga`/`delete_saga`/`each_saga`),
       # `respond_to?`-checked the same way `Ports::Persistence::AppendOnly`
       # already treats an adapter's own optional methods
       # (`find`/`all`/`count`/`reset!`/`events`/`record_event`).
       module SagaPersistence
-        # Resolved and memoized per domain — the FIRST real aggregate
+        # Resolved and memoized per domain — the first real aggregate
         # declared in the domain's own bluebook is the resolution
         # anchor. `Ports::Persistence::BindingPolicy.resolve` for that
         # aggregate already falls back to a domain-level default bind
         # (§0's `Hecksagon#bind_for`) before falling back to Memory, so
         # this needs no separate "was a default declared" branch of its
-        # own — whatever adapter that anchor resolves to already IS the
+        # own — whatever adapter that anchor resolves to already is the
         # domain's own default in the normal case (every aggregate
         # shares one adapter), and is the honest, documented fallback
         # for the rarer domain genuinely split across more than one
         # local adapter with no default declared.
         #
-        # GENUINELY LAZY, GENUINELY POST-BOOT — unlike `rehydrate_sagas!`
+        # Genuinely lazy, genuinely POST-boot — unlike `rehydrate_sagas!`
         # below (boot-only), this is called from live dispatch
         # (`SagaInterpreter#checkpoint`/`#end_saga`, on every saga
-        # transition), so the FIRST call for a given domain can come from
+        # transition), so the first call for a given domain can come from
         # any dispatching thread, not just the boot thread. `@saga_persistence`
         # itself is a plain Hash stood up once in `Registry#initialize` (no
         # race on the container), but `resolve_saga_persistence` is real work
         # (a `BindingPolicy.resolve` plus a lazy `repository` build) whose
-        # RESULT — the actual adapter instance a domain's sagas persist
-        # through — must be the SAME object for every caller: two threads
+        # result — the actual adapter instance a domain's sagas persist
+        # through — must be the same object for every caller: two threads
         # racing the first lookup and each building their own adapter would
         # silently split one domain's saga writes across two adapter
         # instances (worse than `Dispatcher#reaction_depth`'s M20 — that bug
-        # corrupted a counter; this one can corrupt WHICH STORE a saga's
-        # state lands in). Double-checked locking against a DEDICATED mutex
+        # corrupted a counter; this one can corrupt which store a saga's
+        # state lands in). Double-checked locking against a dedicated mutex
         # — never `@saga_mutex` — see `Registry#initialize`'s own comment for
         # why reusing that one would deadlock.
         def saga_persistence(domain)
@@ -47,23 +47,23 @@ module Hecks
           end
         end
 
-        # WALKS EVERY LOADED DOMAIN, repopulating `saga_instances` from
+        # Walks every loaded domain, repopulating `saga_instances` from
         # whatever `saga_persistence(domain)` resolves to — a real store
         # for a domain whose adapter answers the capability, `each_saga`
         # yielding real rows; `NULL_SAGA_STORE`'s own `each_saga` for
         # everything else, which never yields at all, so this needs no
-        # `respond_to?` branch of its own — the SAME reason every other
+        # `respond_to?` branch of its own — the same reason every other
         # call site in this capability never needs one. Called once at
         # boot (`Loader.boot`, between `verify!` and dispatcher
         # construction) — a process that's been running has no reason to
         # re-walk its own already-current `saga_instances`.
         #
-        # BOOT-TIME-ONLY (OR ITS TEST-RUNNER EQUIVALENT) — this method's
+        # Boot-time-only (or its test-runner equivalent) — this method's
         # only callers are `Loader.run_boot_gates!` (single-threaded, before
         # `dispatcher_for` ever exists) and `Registry#reset_runtime_state!`
         # (single-threaded test runner — see that method's own comment).
         # Never called from live dispatch, so `@saga_instances` mutation
-        # here has no concurrent caller to race, unlike its OTHER two write
+        # here has no concurrent caller to race, unlike its other two write
         # points inside `@saga_mutex.synchronize` blocks (`saga_interpreter.
         # rb`), which genuinely do and are guarded accordingly.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation
@@ -81,28 +81,28 @@ module Hecks
 
         private
 
-        # THE OTHER HALF OF THE OUTBOX-SHAPED FIX (see saga_pending_
+        # The other half of the outbox-shaped fix (see saga_pending_
         # dispatch.rb) — `SAGA_PENDING_DISPATCH_KEY`, if the crashed
         # process left it standing, means the row's own `state` was
         # checkpointed but the dispatch cascade that justifies it may
         # never have run. Stripped out of `memory` before it becomes
-        # this instance's LIVE `:memory` (so nothing downstream — a
+        # this instance's live `:memory` (so nothing downstream — a
         # `given`, a `with:` mapping, the fuzzer — ever sees it), and
-        # surfaced loudly instead: a WARNING plus a `saga_log` entry,
+        # surfaced loudly instead: a warning plus a `saga_log` entry,
         # never an automatic redrive (see saga_pending_dispatch.rb for
         # why redriving without idempotent delivery would be worse than
-        # the stall). This is real, durable crash-recovery VISIBILITY —
+        # the stall). This is real, durable crash-recovery visibility —
         # still not the reconciliation itself, which stays a human's
         # call until hecks has idempotent redelivery to make it safe.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation -- same
         # justification as `rehydrate_sagas!`'s own disable comment
-        # above: this method's ONLY caller is that boot-time-only walk,
+        # above: this method's only caller is that boot-time-only walk,
         # never live dispatch, so `@saga_log` has no concurrent writer
         # to race here.
         def warn_stalled_saga(domain, process_manager, correlation, state, pending)
           # `.transform_keys(&:to_sym)` — Heki's own `each_saga` only
-          # symbolizes `memory`'s TOP-level keys (`SagaStore#each_saga`'s
-          # own `transform_keys`, one level deep); a value NESTED under
+          # symbolizes `memory`'s top-level keys (`SagaStore#each_saga`'s
+          # own `transform_keys`, one level deep); a value nested under
           # one of those keys, like this marker, comes back with plain
           # string keys from Heki specifically, symbol keys already from
           # Postgres/SQLite/D1's own `symbolize_names: true` parse. Normalizing

data/lib/hecks/runtime/registry/verification.rb

@@ -21,11 +21,11 @@ module Hecks
               # A domain-level default (§0) — `persisted_by "Heki"` bare,
               # applying to whichever aggregates don't override it — names
               # no aggregate of its own, so there's nothing to look up in
-              # the bluebook for THIS row specifically. Still validate its
+              # the bluebook for this row specifically. Still validate its
               # own adapter/verb shape (the same reason
               # `verify_default_adapter!` checks the framework-wide
               # default the same way, aggregate-less). Coverage of real
-              # aggregates that only resolve THROUGH this default comes
+              # aggregates that only resolve through this default comes
               # from their own dispatch-time `BindingPolicy.resolve` —
               # deliberately not required to be exhaustive here, the same
               # leniency this method already extended to any aggregate
@@ -78,8 +78,8 @@ module Hecks
                 "and cannot satisfy #{bind.verb}"
         end
 
-        # THE METHOD CONTRACT A `.port` FILE'S `verb`/`signal` NEVER
-        # CARRIED — an adapter can name the right port, satisfy the right
+        # The method contract a `.port` file's `verb`/`signal` never
+        # carried — an adapter can name the right port, satisfy the right
         # verb, and admit every `.world` setting `check_settings` checks,
         # and still be missing the one method a live dispatch will
         # actually call. `answers` is optional per port (an empty list is
@@ -99,7 +99,7 @@ module Hecks
                 "#{answers.map(&:inspect).join(', ')}"
         end
 
-        # THE NINE SINGLETON PORTS' OWN GAP — `persistence`, `projection`
+        # **The nine singleton ports' own gap** — `persistence`, `projection`
         # and `loading` are per-aggregate bindings, checked above through
         # every real `bind` a hexagon declares; a singleton port
         # (`clock`, `authorization`, …) is never bound to an aggregate at
@@ -108,9 +108,9 @@ module Hecks
         # already refuses zero or multiple implementations, live, at
         # first dispatch — that stays exactly as-is here (0 or 2+ is
         # ambiguity, not a method-contract question, and asserting every
-        # declared port MUST have exactly one adapter would wrongly
+        # declared port must have exactly one adapter would wrongly
         # refuse a boot that simply never wires a port it doesn't use).
-        # This only ever tightens the ONE case those checks don't cover:
+        # This only ever tightens the one case those checks don't cover:
         # exactly one adapter, wired, missing a method `answers` names.
         PER_AGGREGATE_PORTS = %w[persistence projection loading].freeze
 
@@ -158,13 +158,13 @@ module Hecks
 
         private
 
-        # `role` IS REAL ACCESS CONTROL ONLY WHEN GOVERNANCE CAN CHECK IT
-        # AGAINST SOMETHING — a command that declares a role but whose
+        # `role` is real access control only when governance can check it
+        # against something — a command that declares a role but whose
         # domain never attaches Governance would leave that role forever
         # unchecked, exactly the defect ADR 0025 §9 names ("role gates
         # access control by exact string equality ... Governance ...
-        # connected to none of it"). Checked here, at `verify!` — RECOVERED
-        # and MOVED, not new: this used to run per-block, at HECKSAGON
+        # connected to none of it"). Checked here, at `verify!` — recovered
+        # and moved, not new: this used to run per-block, at hecksagon
         # build time (Bluebook::DSL::HecksagonBuilder#build), which broke
         # the moment a domain could be split across multiple hecksagon
         # blocks (base + an `environments/<name>.hecksagon` overlay,
@@ -172,20 +172,21 @@ module Hecks
         # the recovery provenance): every block but the one declaring
         # `uses_framework "Governance"` would be refused there, even
         # though `Registry#add_hecksagon` merges every block for a domain
-        # into ONE Hecksagon before anything ever dispatches against it.
-        # Checking the MERGED result once, here, after every file for
+        # into one Hecksagon before anything ever dispatches against it.
+        # Checking the merged result once, here, after every file for
         # this domain has loaded, is both more permissive (no need to
         # repeat `uses_framework` in every file) and strictly more
         # correct (a check against an incomplete, not-yet-merged
         # hecksagon can never see the real final shape).
         #
-        # GOVERNANCE ITSELF IS EXEMPT — it cannot `uses_framework` its own
-        # aggregates, and it IS the source of truth a role check runs
-        # against, the same self-reference `CommandRules::Authorization
-        # #governance_attached?` grants it at dispatch time.
+        # A provider is RECOGNISED by its declaration, not its name —
+        # `authorization_provider_for` answers for the domain's own
+        # chapter too, so Governance (which declares `provides
+        # "authorization"`) passes here because of what it declares, and
+        # the same rule `CommandRules::Authorization#governance_attached?`
+        # applies at dispatch time.
         def refuse_ungoverned_roles!(hexagon)
-          return if hexagon.domain == "Governance"
-          return if hexagon.framework_members.include?("Governance")
+          return if authorization_provider_for(hexagon.domain)
 
           bluebook_ir = bluebook(hexagon.domain)
           return unless bluebook_ir
@@ -195,12 +196,21 @@ module Hecks
 
           raise WiringError,
                 "#{offender.hecks_fqn} declares role #{offender.role.inspect}, but " \
-                "#{hexagon.domain}'s hecksagon never uses_framework \"Governance\" — role is only " \
-                "real access control once Governance is attached to check it against; without that " \
-                "it is silent decoration, the exact defect this refusal exists to catch"
+                "#{hexagon.domain}'s hecksagon never #{authorization_attachment_hint} — role is only " \
+                "real access control once an authorization provider is attached to check it against; " \
+                "without that it is silent decoration, the exact defect this refusal exists to catch"
         end
 
-        # Every command this domain declares, an aggregate's own AND every
+        # The suggestion, derived from whichever framework members actually
+        # declare `provides "authorization"` — never a hardcoded name.
+        def authorization_attachment_hint
+          providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
+          return "attaches a chapter that provides \"authorization\" (no framework member declares one)" if providers.empty?
+
+          providers.map { |name| "uses_framework #{name.inspect}" }.join(" or ")
+        end
+
+        # Every command this domain declares, an aggregate's own and every
         # entity nested inside one — the same reach `refuse_role_mismatch`
         # itself needs at dispatch time, just walked ahead of time here.
         def commands_in(bluebook_ir)
@@ -220,7 +230,7 @@ module Hecks
         # 0025 named for an unchecked `role`, here applied to saga
         # durability instead.
         #
-        # A WARNING, NOT A REFUSAL — unlike `refuse_ungoverned_roles!`,
+        # A warning, not a refusal — unlike `refuse_ungoverned_roles!`,
         # running sagas on a store with no `save_saga` is legitimate on
         # purpose in a fast in-memory test/dev boot (this project's own
         # `saga_durability_spec.rb` boots a process manager on `Memory`
@@ -228,13 +238,13 @@ module Hecks
         # refusing the boot outright would break a choice an author made
         # deliberately. What a deploy needs is for the gap to be loud and
         # undeniable, not for local dev/test to become impossible.
-        # THE OUTBOX'S TWIN OF `warn_undurable_sagas!` — a domain that
+        # The outbox's twin of `warn_undurable_sagas!` — a domain that
         # declares anything a commit could owe a reaction to (a policy
         # listening to one of its events, or a process manager) but is
         # bound to an adapter with no outbox (`AppendOnly#outbox?`) gets
         # reactions the pre-outbox way: run inline, lost on a crash
         # between commit and reaction. A warning, not a refusal, for the
-        # reason `warn_undurable_sagas!` gives — and Memory HAS an outbox
+        # reason `warn_undurable_sagas!` gives — and Memory has an outbox
         # (in-process, like everything else it holds), so a dev/test
         # boot stays quiet; this speaks up for the file/remote adapters
         # that persist state durably but hand reactions to nothing.

data/lib/hecks/runtime/registry.rb

@@ -29,8 +29,8 @@ module Hecks
         @event_log    = []
         @reaction_log = []
         @saga_log = []
-        # ADDITIVE, RUBY-ONLY — never merged into saga_log/reaction_log.
-        # rust/src/kernel/orchestrate.rs ports THOSE two arrays' exact
+        # **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
         # equality check) — a landmine found by reading that spec before
         # touching anything, not by hitting it. These carry the raw
@@ -43,7 +43,7 @@ module Hecks
         @saga_dispatch_log   = []
         @policy_dispatch_log = []
         @saga_instances = Hash.new { |h, k| h[k] = {} }
-        # GUARDS `saga_instances`' OWN mutation+checkpoint sequence
+        # Guards `saga_instances`' own mutation+checkpoint sequence
         # (`SagaInterpreter`'s 4 write points, §7) — the same shape of
         # hazard this codebase's own prior audit already flagged for
         # `Dispatcher#reenter`'s reaction-depth counter (M20: a
@@ -51,7 +51,7 @@ module Hecks
         # `Thread.current`, dispatcher.rb), made meaningfully easier to
         # hit here once a persistence write sits in the same critical
         # section. Held across the in-memory
-        # mutation AND the checkpoint write together, never across a
+        # mutation and the checkpoint write together, never across a
         # saga's own dispatch cascade — see `SagaInterpreter#advance_saga`'s
         # own comment for why that distinction matters (non-reentrant
         # Mutex, recursive re-entry is real).
@@ -59,18 +59,18 @@ module Hecks
         @repositories = {}
         @projection_repositories = {}
         @bluebook_builders = {}
-        # EAGER, NOT LAZY — see `#resolved_eras`'s own comment for why. Built
+        # **Eager, not lazy** — see `#resolved_eras`'s own comment for why. Built
         # here rather than `@resolved_eras ||= {}` on first access so there is
         # no window, post-boot, where two concurrently dispatching threads
         # could race creating this Hash (Hecks/ThreadSharedIvarMutation; the
         # same shape of hazard `Dispatcher#reenter`'s `@reaction_depth` was
-        # fixed for). Every WRITE into it still only ever happens at boot,
+        # fixed for). Every write into it still only ever happens at boot,
         # single-threaded (`EraResolver.check!`, a `:pre_verify` boot gate) —
         # this only removes the race on standing up the container itself for
         # a boot with no era-plugin domain at all, whose first touch would
         # otherwise be a live dispatch's own `RepositoryFactory.build` read.
         @resolved_eras = {}
-        # THE SIBLING FACT `EraResolver.check!` records for an OLD checkout:
+        # The sibling fact `EraResolver.check!` records for an old checkout:
         # domain name -> the newest held ordinal that superseded the era this
         # boot resolved to; absent for every domain booting the current era.
         # `RepositoryFactory.build` hands it to the adapter as
@@ -79,7 +79,7 @@ module Hecks
         # half that holds even for a connection row-level security cannot
         # bite (BUG#24). Eager for exactly the reason `@resolved_eras` is.
         @superseded_eras = {}
-        # EAGER, NOT LAZY — see `#capability_graph`'s own comment for why.
+        # **Eager, not lazy** — see `#capability_graph`'s own comment for why.
         # `CapabilityGraph.new` only stores the registry reference; there is
         # no reason to defer it, and doing so removes the exact same
         # first-access race `#resolved_eras` above does, while preserving the
@@ -87,10 +87,10 @@ module Hecks
         # spec.rb` already requires.
         @capability_graph = CapabilityGraph.new(self)
         # `@saga_persistence` itself is eager (see `#saga_persistence`'s own
-        # comment) — only the PER-DOMAIN resolution inside it is genuinely
-        # expensive and lazy, guarded by this dedicated mutex. NOT the same
+        # comment) — only the per-domain resolution inside it is genuinely
+        # expensive and lazy, guarded by this dedicated mutex. Not the same
         # mutex as `@saga_mutex`: `checkpoint` (saga_interpreter.rb) calls
-        # `saga_persistence(domain)` from INSIDE an `@saga_mutex.synchronize`
+        # `saga_persistence(domain)` from inside an `@saga_mutex.synchronize`
         # block, so reusing `@saga_mutex` here would deadlock the very first
         # time a saga advanced (a `Mutex` is not reentrant — the exact
         # warning `@saga_mutex`'s own comment already gives for a different
@@ -100,23 +100,23 @@ module Hecks
         @outbox = Outbox::Relay.new(self)
       end
 
-      # THE OUTBOX RELAY — one per registry, for its whole life (built
+      # **The outbox relay** — one per registry, for its whole life (built
       # here, never swapped, so no thread ever sees a different one).
       # It can enqueue from the moment the registry exists; a Dispatcher
       # attaches the interpreters that let it deliver. See
       # `Runtime::Outbox`.
       attr_reader :outbox
 
-      # THE BUILDER STAYS OPEN FOR THE LIFE OF THIS REGISTRY, keyed by chapter
+      # The builder stays open for the life of this registry, keyed by chapter
       # name — see the comment on `BluebookBuilder.build`. A chapter split across
       # several files (`language/bluebook/*.bluebook`, all `Hecks.bluebook "Bluebook"`)
-      # needs its declarations to accumulate into ONE builder rather than each
+      # needs its declarations to accumulate into one builder rather than each
       # file minting its own and silently discarding the one before.
       def bluebook_builder(name)
         @bluebook_builders[name.to_s] ||= yield
       end
 
-      # BOOT-TIME-ONLY, SINGLE-THREADED — every `add_*` below (through
+      # Boot-time-only, single-threaded — every `add_*` below (through
       # `add_translation`) is called exclusively from `Hecks.collect`
       # (hecks.rb), which is what `Hecks.bluebook`/`.hecksagon`/`.port`/
       # `.adapter`/`.world`/`.translation` run inside while a `.bluebook`/
@@ -132,11 +132,11 @@ module Hecks
       # rubocop:disable Hecks/ThreadSharedIvarMutation
       def add_bluebook(item) = @bluebooks[item.name] = item
 
-      # MERGED, NOT REPLACED — RECOVERED, not new (see Runtime::Loader
+      # 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
+      # block should add to what the first declared, not silently
       # discard it.
       def add_hecksagon(item)
         existing = @hecksagons[item.domain]
@@ -146,7 +146,7 @@ module Hecks
       def add_port(item) = @ports[item.name] = item
       def add_adapter(item) = @adapters[item.name] = item
 
-      # MERGED, NOT REPLACED — the same generalization for `World` that
+      # Merged, not replaced — the same generalization for `World` that
       # `add_hecksagon` above recovers for `Hecksagon`: an
       # `environments/<name>.world` overlay (or a host-owned tenancy
       # overlay world, same mechanism) can now add or override settings
@@ -165,7 +165,7 @@ module Hecks
       # rubocop:enable Hecks/ThreadSharedIvarMutation
 
       # {domain name => era ordinal} as resolved by the boot-time era
-      # gate. A lineage adapter writes into ITS OWN era's partition —
+      # gate. A lineage adapter writes into its own era's partition —
       # which, for an old checkout booting a held-but-superseded shape,
       # is not the newest one. The Hash itself is stood up in `initialize`
       # (see that comment) — this is a plain reader, not a memoizer;
@@ -182,12 +182,29 @@ module Hecks
 
       def verbs = @bluebooks.values.flat_map(&:verbs).sort
 
+      # The chapter that answers a role check for `domain` — the domain's
+      # own chapter, or any framework member its hecksagon attaches, that
+      # declares `provides "authorization"`. Nil when none does. Replaces
+      # 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.
+      def authorization_provider_for(domain)
+        names = [domain.to_s, *Array(hecksagon(domain)&.framework_members)]
+        names.filter_map { |name| bluebook(name) }
+             .find { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
+      end
+
+      # Every loaded chapter declaring `provides "authorization"`.
+      def authorization_providers
+        @bluebooks.values.select { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
+      end
+
       def repository(domain, aggregate)
         @repositories[[domain.to_s, aggregate.hecks_name]] ||= Ports::Persistence.repository(self, domain, aggregate)
       end
 
-      # EVERYTHING A DISPATCH WROTE, CLEARED; NOTHING A BOOT DECLARED,
-      # TOUCHED. Bluebooks, hecksagons, ports, adapters, worlds and the
+      # Everything a dispatch wrote, cleared; nothing a boot declared,
+      # touched. Bluebooks, hecksagons, ports, adapters, worlds and the
       # resolved eras are what loading the files produced and stay as
       # they are; the logs, the saga instances and the repositories are
       # what running commands against them produced, and go back to
@@ -204,8 +221,8 @@ module Hecks
       # boot, 76 chess behaviours = two and a half minutes of booting the
       # same two files — can now boot once and reset between tests.
       #
-      # SINGLE-THREADED CALLER, THE SAME REASON THE `add_*` CLUSTER ABOVE
-      # IS EXEMPT — `Behaviors::Expectations.run_one` is this method's ONLY
+      # Single-threaded caller, the same reason the `add_*` cluster above
+      # is exempt — `Behaviors::Expectations.run_one` is this method's only
       # caller (verified by grep before writing this), and it runs one
       # test at a time: `Runner#run` maps over tests sequentially, and
       # `Behaviors.rspec`'s generated examples run under RSpec's own
@@ -229,7 +246,7 @@ module Hecks
 
       # Built eagerly in `initialize` (see that comment) — this is a plain
       # reader, not a memoizer; `spec/runtime/capability_graph_spec.rb`
-      # asserts the SAME instance comes back every call, which this still
+      # asserts the same instance comes back every call, which this still
       # gives, just without a lazy `||=` race on standing it up.
       attr_reader :capability_graph
 
@@ -262,9 +279,9 @@ module Hecks
         false
       end
 
-      # RECOVERED — see `add_hecksagon`'s own comment for provenance.
+      # Recovered — see `add_hecksagon`'s own comment for provenance.
       # Concatenates every list-shaped fact; `binds` in particular is
-      # additive because an overlay REBINDING an aggregate (a new
+      # additive because an overlay rebinding an aggregate (a new
       # `persisted_by` for the same aggregate/verb) is meant to shadow
       # the base's own bind at resolution time, not erase it outright —
       # `Ports::Persistence::BindingPolicy.resolve`'s own "exactly one
@@ -281,11 +298,11 @@ module Hecks
         )
       end
 
-      # RECOVERED AND GENERALIZED — see `add_world`'s own comment. `realm`/
+      # Recovered and generalized — see `add_world`'s own comment. `realm`/
       # `latest` are scalars, so the overlay's value wins when present,
       # else the base's survives; `settings` is a shallow merge keyed by
       # verb (and `"verb:adapter"`) — an overlay entry for a key the base
-      # also declares REPLACES that key's whole resolved hash (the same
+      # 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.
       def merge_worlds(base, overlay)

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`,
     # 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
@@ -37,43 +37,58 @@ module Hecks
 
       attr_reader :registry
 
-      def initialize(registry, region: "us-east-1")
+      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
 
+      # Same deprecation as `Dispatcher#dispatch` — loose keyword facts warn;
+      # `to:`/`with:` do not.
       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`.
+      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 +97,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 +105,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 } ||
@@ -113,9 +128,9 @@ module Hecks
       def query(verb, **args)           = @local.query(verb, **args)
       def reference_query(verb, **args) = @local.reference_query(verb, **args)
 
-      # THE FULL DOMAIN'S EVENT HISTORY, on every call — `{"read":
+      # 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