hecks 1.4.0 → 1.5.0

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

@@ -10,9 +10,19 @@ module Hecks
       # loading, and the smaller checks are also called piecemeal by the
       # repository factory.
       module Verification
+        # Runs the whole wiring gate against this registry's loaded bluebooks,
+        # hexagons, ports and adapters.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
+        #   adapter cannot satisfy its port's verb or declared `answers`, a world
+        #   setting names a field its adapter does not declare, the default adapter
+        #   is unusable, or a command declares a role with no authorization provider
+        #   attached
         def verify!
           verify_default_adapter!
           verify_singleton_port_answers!
+          refuse_cross_package_bluebook_merge!
 
           @hecksagons.each_value do |hexagon|
             refuse_ungoverned_roles!(hexagon)
@@ -50,6 +60,13 @@ module Hecks
           self
         end
 
+        # Checks that the framework-wide default persistence adapter (used by any
+        # aggregate left out of an explicit bind list) is itself wired correctly.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if the default adapter cannot satisfy the
+        #   persistence port's verb, is missing a declared `answers` method, or has
+        #   no Ruby implementation
         def verify_default_adapter!
           name = Ports::Persistence::DEFAULT_ADAPTER
 
@@ -68,6 +85,14 @@ module Hecks
                 "aggregate with no bind could not be given one: #{e.message}"
         end
 
+        # Checks that `bind`'s adapter implements the port it names and satisfies
+        # the verb the bind declares.
+        #
+        # @param bind [Bluebook::Bind] the bind to check
+        # @return [void]
+        # @raise [Runtime::WiringError] if `bind`'s adapter is unknown, declares an
+        #   unknown port, is missing a declared `answers` method, or cannot satisfy
+        #   `bind`'s own verb
         def check_verb(bind)
           port = port_for(bind)
           check_answers(port, bind.adapter)
@@ -85,6 +110,13 @@ module Hecks
         # actually call. `answers` is optional per port (an empty list is
         # today's pre-existing behavior, unchecked), so this only ever
         # tightens a port that opted in.
+        #
+        # @param port [Bluebook::Port] the port whose declared `answers` methods
+        #   `adapter_name` must respond to
+        # @param adapter_name [String] the adapter's declared name to check
+        # @return [void]
+        # @raise [Runtime::WiringError] if `adapter_name` has no Ruby implementation,
+        #   or its implementation does not respond to one of `port.answers`
         def check_answers(port, adapter_name)
           answers = Array(port.answers)
           return if answers.empty?
@@ -114,6 +146,12 @@ module Hecks
         # exactly one adapter, wired, missing a method `answers` names.
         PER_AGGREGATE_PORTS = %w[persistence projection loading].freeze
 
+        # Checks every singleton port (not per-aggregate-bound) with exactly one
+        # wired adapter against its own declared `answers` methods.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a singleton port's one wired adapter is
+        #   missing one of its declared `answers` methods
         def verify_singleton_port_answers!
           @ports.each_value do |port|
             next if PER_AGGREGATE_PORTS.include?(port.name)
@@ -127,6 +165,16 @@ module Hecks
           self
         end
 
+        # Checks that every setting `settings` declares (besides `:adapter`) is a
+        # field `bind`'s adapter actually admits.
+        #
+        # @param bind [Bluebook::Bind] the bind naming the adapter to check against;
+        #   a no-op if its adapter is unknown
+        # @param settings [Hash{Symbol => Object}] the world's declared settings for
+        #   this bind
+        # @return [void]
+        # @raise [Runtime::WiringError] if `settings` declares a field `bind`'s
+        #   adapter does not declare
         def check_settings(bind, settings)
           adapter = @adapters[bind.adapter]
           return unless adapter
@@ -141,6 +189,12 @@ module Hecks
                 "Add the field to the adapter, or remove it from the world."
         end
 
+        # Finds the port `bind`'s adapter declares.
+        #
+        # @param bind [Bluebook::Bind] the bind naming the adapter to look up
+        # @return [Bluebook::Port] the port `bind`'s adapter declares
+        # @raise [Runtime::WiringError] if `bind` names an unknown adapter, or one
+        #   declaring an unknown port
         def port_for(bind)
           adapter = @adapters[bind.adapter]
           raise WiringError, "unknown adapter #{bind.adapter.inspect}" unless adapter
@@ -149,6 +203,12 @@ module Hecks
             raise(WiringError, "adapter #{bind.adapter} declares unknown port #{adapter.port.inspect}")
         end
 
+        # Finds the Ruby module implementing the adapter declared `name`.
+        #
+        # @param name [String] the adapter's declared name, such as `"PostgresEra"`
+        # @return [Module] the adapter module or class under `Hecks::Adapters`
+        # @raise [Runtime::WiringError] if no Ruby implementation named `name` exists
+        #   under `Hecks::Adapters`
         def adapter_class(name)
           Adapters.const_get(name)
         rescue NameError
@@ -164,9 +224,9 @@ module Hecks
         # 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
-        # build time (Bluebook::DSL::HecksagonBuilder#build), which broke
-        # the moment a domain could be split across multiple hecksagon
+        # and moved, not new: running this per-block, at hecksagon
+        # build time (Bluebook::DSL::HecksagonBuilder#build), breaks
+        # the moment a domain is split across multiple hecksagon
         # blocks (base + an `environments/<name>.hecksagon` overlay,
         # Runtime::Loader.boot's `environment:` — see its own comment for
         # the recovery provenance): every block but the one declaring
@@ -179,7 +239,7 @@ module Hecks
         # correct (a check against an incomplete, not-yet-merged
         # hecksagon can never see the real final shape).
         #
-        # A provider is RECOGNISED by its declaration, not its name —
+        # 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
@@ -217,6 +277,61 @@ module Hecks
           bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
         end
 
+        # TWO UNRELATED PACKAGES, ONE CHAPTER NAME BY COINCIDENCE — the
+        # real risk `Registry#bluebook_sources` exists to catch (found
+        # live: a stale `vendor/hecksagain` fork's own copy of Governance/
+        # Identity/Deploy, still reachable on 4 consuming apps' own load
+        # paths alongside the real gem). `BluebookBuilder.build`'s own
+        # accumulation (several files declaring the SAME chapter name ON
+        # PURPOSE — `lib/hecks/language/bluebook/*.bluebook` all open
+        # `Hecks.bluebook "Bluebook"`) is never touched here — that merge
+        # stays unconditional, checked only AFTER every file has loaded,
+        # the same "check the merged final result once" timing
+        # `refuse_ungoverned_roles!` already uses and for the same reason
+        # (a check against an incomplete load can never see the real
+        # shape). What distinguishes intentional accumulation from
+        # coincidence is PACKAGE ROOT, not file identity: files a real
+        # gemspec or a `vendor/` boundary already treats as one unit are
+        # expected to share a name; files from two DIFFERENT roots never
+        # legitimately do.
+        def refuse_cross_package_bluebook_merge!
+          @bluebook_sources.each do |name, paths|
+            roots = paths.map { |path| package_root_for(path) }.uniq
+            next if roots.size <= 1
+
+            raise WiringError,
+                  "#{name.inspect} is declared by more than one package: #{roots.join(' and ')} — " \
+                  "these are two unrelated sources sharing a chapter name by coincidence, not one " \
+                  "domain split across files, and merging their declarations into one chapter is " \
+                  "almost certainly a stale/vendored copy left on the load path (paths: " \
+                  "#{paths.join(', ')})"
+          end
+        end
+
+        # THE NEAREST BOUNDARY A PATH ALREADY BELONGS TO — a real
+        # gemspec (this IS a package, whatever depends on it or vendors
+        # it), or a bare `vendor/` path component, treated as its OWN
+        # root regardless of what gemspec might sit above it: vendored
+        # code should never be considered "the same package" as whatever
+        # it's vendored into, even when nothing else marks the boundary.
+        # Neither found, the path's own directory is the root — two
+        # files with no closer marker only "belong together" if they are
+        # literally the same file.
+        def package_root_for(path)
+          return path.to_s if path.nil?
+
+          dir = File.dirname(File.expand_path(path))
+          loop do
+            return "vendor:#{dir}" if File.basename(dir) == "vendor"
+            return dir if Dir.glob(File.join(dir, "*.gemspec")).any?
+
+            parent = File.dirname(dir)
+            return dir if parent == dir
+
+            dir = parent
+          end
+        end
+
         # A domain that declares a `process_manager` but whose
         # `saga_persistence` resolves to `NULL_SAGA_STORE` (no anchor
         # aggregate, a RemoteRuntime-shaped adapter, an adapter that

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