hecks 2.7.0 → 2.9.0

data/lib/hecks/runtime/invocation.rb

@@ -5,33 +5,11 @@ require_relative "../rendering"
 
 module Hecks
   module Runtime
-    # **One dispatch, as data** — the verb, the receiver it is addressed to
-    # (`target`, a `Routing::Envelope` or nil), and every fact the caller did
-    # or did not offer. Built once per dispatch by `Invocation.from_call`, the
-    # only place the runtime interprets the shape of a call (`to:` vs `with:`
-    # vs the flat facts hash `dispatch_flat` carries, a port operation's
-    # reference attribute
-    # lifted into `to:`). `Runtime::Routing.envelope`/`.payload` delegate here
-    # and no longer hold that logic themselves.
-    #
-    # `facts` maps a fact name to exactly one of:
-    #
-    #   - `Invocation::Absent`  — the key was never offered (every declared
-    #                             attribute the caller left out appears so)
-    #   - `Invocation::Null`    — the key was offered with an explicit nil
-    #   - `Invocation::Present` — the key was offered with a value
-    #
-    # Keys are kept exactly as offered: `with:` keys are symbolized (as they
-    # always were), a flat facts hash keeps whatever key the wire used. Undeclared keys a caller
-    # offered are kept too — refusing them is
-    # still `refuse_unknown_arguments`' job, a dispatch step, not this one.
-    #
-    # I1 changes no behavior: every interpreter still reads `ctx.args`,
-    # which is `#to_args` — the same Hash `Routing.payload` returns.
-    # Roadmap I2 moves the Ruby `decode_arguments` step onto `facts` itself.
+    # One dispatch, as data: the verb, the resolved receiver (`target`, a
+    # `Routing::Envelope` or nil), and every fact the caller offered or didn't.
     Invocation = Data.define(:verb, :target, :facts)
 
-    # The fact markers, the fact readers, and `from_call` — see above.
+    # Adds the fact wrappers and builders for an `Invocation`.
     class Invocation
       # A fact the caller offered with a real (non-nil) value.
       Present = Data.define(:value) do
@@ -42,7 +20,6 @@ module Hecks
       # The class of the two frozen marker singletons below — never
       # instantiated anywhere else.
       class Marker
-        # @param name [String] the marker's own label, used by #inspect/#to_s
         def initialize(name)
           @name = name
           freeze
@@ -56,51 +33,24 @@ module Hecks
       Absent = Marker.new("Absent")
       Null   = Marker.new("Null")
 
-      # @param verb [String] the fully qualified verb this invocation dispatches
-      # @param target [Routing::Envelope, nil] the resolved receiver, or nil when
-      #   the facts carry the identity themselves
-      # @param facts [Hash{String, Symbol => Object}] every candidate fact, keyed by
-      #   offered (or declared) name; frozen, deep-duped, before being stored
+      # Dupes and freezes `facts` so a caller can't mutate them after
+      # construction.
       def initialize(verb:, target:, facts:)
         super(verb: verb, target: target, facts: facts.dup.freeze)
       end
 
-      # Reads the fact recorded under `name`.
-      #
-      # The fact recorded under `name` — `Absent` for a name never offered
-      # and never declared either.
-      #
-      # @param name [String, Symbol] the fact name to look up
-      # @return [Invocation::Present, Invocation::Null, Invocation::Absent] the
-      #   recorded marker for `name`
+      # The fact recorded under `name`; `Absent` when never offered (and not
+      # declared either).
       def fact(name) = facts.fetch(name, Absent)
 
-      # Reports whether `name` was offered with a real, non-nil value.
-      #
-      # @param name [String, Symbol] the fact name to check
-      # @return [Boolean] true if `name` was offered with a non-nil value
       def present?(name) = fact(name).is_a?(Present)
 
-      # Reports whether `name` was offered with an explicit nil.
-      #
-      # @param name [String, Symbol] the fact name to check
-      # @return [Boolean] true if `name` was offered with an explicit nil
       def null?(name)    = fact(name).equal?(Null)
 
-      # Reports whether `name` was never offered.
-      #
-      # @param name [String, Symbol] the fact name to check
-      # @return [Boolean] true if `name` was never offered (and, if declared, left out)
       def absent?(name)  = fact(name).equal?(Absent)
 
-      # A Present fact's value; nil for an explicit Null. Raises KeyError for
-      # an Absent fact — "never offered" has no value, and answering nil
-      # would re-conflate it with an explicit null, the very ambiguity this
-      # type exists to remove. Ask `absent?`/`present?` first.
-      #
-      # @param name [String, Symbol] the fact name to read
-      # @return [Object, nil] the offered value; nil for an explicit Null fact
-      # @raise [KeyError] if `name` names an Absent fact (never offered)
+      # A Present fact's value (nil for Null). Raises for Absent rather than
+      # returning nil, so "never offered" isn't conflated with an explicit null.
       def value(name)
         case (found = fact(name))
         when Present then found.value
@@ -109,12 +59,8 @@ module Hecks
         end
       end
 
-      # The flat args hash, byte for byte what `Routing.payload` returned
-      # before this type existed: offered keys in offered order, Absent keys
-      # omitted, Null keys mapped to nil. A fresh Hash every call.
-      #
-      # @return [Hash{String, Symbol => Object}] the offered facts by name; a fact
-      #   offered as nil is kept as nil
+      # The offered facts as a plain Hash, in offered order: Absent keys
+      # omitted, Null mapped to nil. A fresh Hash every call.
       def to_args
         facts.each_with_object({}) do |(name, found), args|
           next if found.equal?(Absent)
@@ -124,47 +70,10 @@ module Hecks
       end
 
       class << self
-        # The one reading of a call's shape. `receiver:` picks which of the
-        # three dispatch shapes this is, because each has always checked its
-        # parts in its own order and a malformed call's refusal depends on
-        # that order:
-        #
-        #   :aggregate — facts first (`with:` checks), then `to:`
-        #   :entity    — `to:` first, then the block (which resolves the
-        #                entity chain, UnknownVerb), then facts
-        #   :port      — a reference attribute / identity field lifted into
-        #                `to:`, then `to:` (which a port operation requires),
-        #                then facts
-        #
-        # The block answers the declaring command or port operation (anything
-        # with `hecks_name` and `attributes`); it is called exactly once, at
-        # the point in that order where the caller always resolved it.
-        # `aggregate:` is the owning aggregate construct, read for `:port`
-        # only.
-        #
-        # @param verb [String] the fully qualified verb being dispatched
-        # @param to [String, Hash, nil] a bare aggregate identity, or a Hash with
-        #   `aggregate:` and `entity:`/`entities:`; nil for no explicit receiver
-        # @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; for `:port`, may also carry the receiver identity under a
-        #   reference attribute's own name
-        # @param receiver [Symbol] which of the three dispatch shapes this is:
-        #   `:aggregate`, `:entity` or `:port`
-        # @param entity_depth [Integer] the number of entity-hop identities `to:`
-        #   must carry, for `:entity` only
-        # @param aggregate [Bluebook::Aggregate, nil] the owning aggregate construct,
-        #   read for `:port` only
-        # @yieldreturn [Class] the declaring command or port-operation class (anything
-        #   with `hecks_name` and `attributes`)
-        # @return [Runtime::Invocation] the built invocation
-        # @raise [Runtime::TypeMismatch] if `to:` is malformed, its entity count is
-        #   wrong, or (`:port` only) the operation resolves no receiving aggregate
-        # @raise [Runtime::UnknownArgument] if `with:` names an attribute the command
-        #   does not declare
-        # @raise [Runtime::AbsentArgument] if `with:` omits a required attribute
-        # @raise [ArgumentError] if `receiver` is none of `:aggregate`, `:entity` or `:port`
+        # Builds an Invocation for one of three call shapes (:aggregate,
+        # :entity, :port). Each checks its own parts in a fixed order, because
+        # a malformed call's refusal depends on that order; `declaring` is
+        # called exactly once, at that shape's point in the order below.
         def from_call(verb, to:, with:, flat:, receiver: :aggregate, entity_depth: 0, aggregate: nil, &declaring)
           case receiver
           when :aggregate
@@ -182,16 +91,7 @@ module Hecks
           end
         end
 
-        # `to:` as a `Routing::Envelope`, or nil when no `to:` was given.
-        #
-        # @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 `to`
-        #   must carry
-        # @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`
+        # `to` as a `Routing::Envelope`, or nil when no `to:` was given.
         def route(to, entity_depth: 0)
           return nil if to.nil?
 
@@ -210,24 +110,8 @@ module Hecks
           Routing::Envelope.new(aggregate: aggregate, entities: entities)
         end
 
-        # The offered facts for `declaring`, as Absent/Null/Present — offered
-        # keys first, in offered order, then every declared attribute that was
-        # not offered, as Absent.
-        #
-        # @param declaring [Class] the command or port-operation class (anything
-        #   with `hecks_name` and `attributes`) whose declared attributes are read
-        # @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 => Invocation::Absent, Invocation::Null,
-        #   Invocation::Present}] each candidate fact keyed by its offered (or
-        #   declared) name
-        # @raise [Runtime::TypeMismatch] if both `with` and a non-empty `flat` are
-        #   given, or if `with` is not a Hash
-        # @raise [Runtime::UnknownArgument] if `with:` names an attribute `declaring`
-        #   does not declare
-        # @raise [Runtime::AbsentArgument] if `with:` omits a required attribute
+        # Every candidate fact for `declaring`, as Absent/Null/Present: offered
+        # keys first in offered order, then remaining declared attributes as Absent.
         def facts_for(declaring, with:, flat:)
           offered = offered_facts(declaring, with: with, flat: flat)
           facts = offered.each_with_object({}) do |(name, value), found|
@@ -242,19 +126,10 @@ module Hecks
 
         private
 
-        # **The port operation shape** — moved from `Dispatcher#port_invocation`.
-        #
         # A Reference-typed attribute naming the owning aggregate is routing,
         # not a fact: lifted out of the flat facts into `to:` when no `to:`
-        # was given. A `to:`-declared operation carries no Reference
-        # attribute at all (PortOperationBuilder#initialize's own comment),
-        # so its receiver is read — not removed — from the plain attribute
-        # named for the owner's first `identified_by` field: that attribute
-        # is still a declared external fact `refuse_absent_arguments`
-        # expects to find (Rust's own comment: "declare only external facts
-        # with attribute"; a real AbsentArgument confirmed this before `[]`
-        # replaced `delete`). Composite identity is not attempted — `.first`
-        # only, no domain in the corpus needs more for a port operation.
+        # was given. Only `.first` of a composite identity is used — no
+        # domain in the corpus needs more for a port operation.
         def port_call(verb, aggregate, operation, to:, with:, flat:)
           flat = flat.dup
           identity = operation.identity_attribute(aggregate.hecks_name)
@@ -271,15 +146,9 @@ module Hecks
           new(verb: verb, target: target, facts: facts_for(operation, with: with, flat: flat))
         end
 
-        # BUG#7 — a non-Hash `to:` must be a String, matching Rust's
-        # `RoutingEnvelope::from_json` (kernel/routing.rs), which refuses
-        # anything neither a JSON string nor object before the domain payload
-        # is examined. Surfaced on `examples/roster`'s `Mark`, whose own
-        # attribute is literally named `to`: a flat-facts dispatch steals
-        # that key into this parameter, and without this check an out-of-range
-        # Integer would be accepted as the aggregate identity, leaving Mark's
-        # `to` fact absent (AbsentArgument in Ruby, TypeMismatch in Rust). See
-        # spec/runtime/routing_envelope_shape_spec.rb.
+        # Must be a String, matching Rust's own parity check for `to:` — this
+        # keeps a same-named `to` attribute from being stolen as the
+        # aggregate identity by a flat-facts dispatch.
         def scalar_envelope(to)
           return [to, []] if to.is_a?(String)
 
@@ -294,13 +163,9 @@ module Hecks
           [hash[:aggregate], entity_identities(hash)]
         end
 
-        # BUG#18 — an entity route naming no entity (`entities: []`, or
-        # neither key) refuses here, unconditionally, before entity_depth is
-        # consulted: for an aggregate-level command (depth 0), without this,
-        # `[].size == 0` would satisfy the depth check and let the degenerate
-        # Hash reach the command's own validation. Rust's `RoutingEnvelope::
-        # from_json` always refused it at this point. A bare aggregate identity
-        # String remains the ordinary aggregate-command shape.
+        # An entity route naming no entity is refused here, unconditionally,
+        # before entity_depth is checked — otherwise a depth-0 (aggregate)
+        # command would let the degenerate `entities: []` Hash slip through.
         def entity_identities(hash)
           raise TypeMismatch, "to: takes entity: or entities:, not both" if hash.key?(:entities) && hash.key?(:entity)
 
@@ -312,9 +177,8 @@ module Hecks
 
         # `with:` is deliberately strict: a caller choosing the explicit
         # envelope cannot smuggle receiver identity back into the payload,
-        # and may not mix it with a flat facts hash. Without `with:`
-        # (nil or false) the flat facts are the facts, unread —
-        # whether `to:` was given never enters this decision (BUG#17).
+        # and may not mix it with a flat facts hash. Without `with:`, the
+        # flat facts are taken as-is, unread.
         def offered_facts(declaring, with:, flat:)
           if with && !flat.empty?
             raise TypeMismatch,

data/lib/hecks/runtime/loader.rb

@@ -8,49 +8,20 @@ require_relative "registry"
 
 module Hecks
   module Runtime
-    # The boot entry point: loads a bluebook directory (or an explicit
-    # file list) into a fresh Registry, runs every registered boot gate
-    # (era checks, saga rehydration, …), and hands back the Dispatcher
-    # (or RemoteDispatcher, for a domain declaring `dispatched_by
-    # ("Lambda")`) bound to it — installing the `Widget::Item.Add(...)`
-    # facade sugar unless the caller opts out.
+    # Boots a domain: loads its bluebook directory into a fresh Registry, runs
+    # every boot gate, and hands back the bound Dispatcher (or RemoteDispatcher).
     class Loader
-      # `install_facade:` defaults on — every ordinary caller wants
-      # `Widget::Item.Add(...)` sugar. A caller that only ever dispatches
-      # by FQN string (`SmokeTest`, the one caller so far) can pass
-      # `false` to skip it: `Facade::Surface.install` puts a bare global
-      # Ruby constant on `Object` per domain and per aggregate name, with
-      # no scoping and no cleanup hook, so a tool booting arbitrary
-      # throwaway domains under generic names ("Widget", "Item", "Tag")
-      # would otherwise leak those names into the rest of the process —
-      # measured, not hypothetical: this exact leak once made an
-      # unrelated `dsl_spec.rb` example resolve a bare `Widget` constant
-      # to a stale smoke-test facade from a deleted temp directory instead
-      # of raising, corrupting that spec's own unrelated build. Skipping
-      # the install is safe because nothing downstream of a raw
-      # `Dispatcher` needs the sugar — `Dispatcher#dispatch`/`#query` work
-      # identically either way.
-      # `environment:` — see Adapters::Folder#load_domain's own comment
-      # for the mechanism. hecks never reads ENV itself (every other
-      # env-var lookup in this codebase lives in app-owned .world/
-      # .hecksagon files, never library internals) — a caller resolves
-      # its own env var name and passes the resulting string straight
-      # through, e.g. `Hecks.boot(path, environment:
-      # ENV.fetch("MYAPP_ENV", "development"))`.
+      # Boots `path`: loads its bluebook directory into a fresh Registry, runs
+      # every registered boot gate, and returns the bound dispatcher. Pass
+      # `install_facade: false` to skip the `Widget::Item.Add(...)` global
+      # facade sugar (only a caller dispatching by FQN string needs to).
       #
-      # @param path [String] a domain directory to boot, resolved through
-      #   `Ports::Loading#bluebook_directory`
-      # @param shared [String, nil] an explicit shared ports/adapters root override; nil
-      #   resolves it by walking up from the domain directory
-      # @param install_facade [Boolean] whether to install the `Widget::Item.Add(...)`
-      #   facade sugar
-      # @param environment [String, nil] the environment overlay to load after the
-      #   domain's own files (e.g. `"production"`); nil loads none
+      # @param path [String] a domain directory to boot
+      # @param shared [String, nil] shared ports/adapters root; nil walks up from `path`
+      # @param environment [String, nil] environment overlay loaded after the domain; nil for none
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
-      # @raise [Errno::ENOENT] if `path` names neither a domain directory nor one holding
-      #   a `bluebook/` subdirectory
-      # @raise [Runtime::WiringError] if a boot gate finds a wiring problem (an undeclared
-      #   bind, a compute/rekey rule with no persistence plugin loaded, …)
+      # @raise [Errno::ENOENT] if `path` names no domain directory
+      # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
       def self.boot(path, shared: nil, install_facade: true, environment: nil)
         loading   = Ports::Loading.bootstrap
         directory = loading.bluebook_directory(path)
@@ -70,36 +41,20 @@ module Hecks
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
 
-      # The outbox's boot-time reconciliation — after the dispatcher
-      # exists (a row's consumer runs through its interpreters, so this
-      # cannot be a plain registry gate the way saga rehydration is) and
-      # after saga rehydration (a redriven row may advance a saga, which
-      # must already be in memory). `pending` rows are redriven —
-      # provably never started; `claimed` rows are surfaced, never
-      # auto-redriven — see `Runtime::Outbox`. A remote dispatcher has
-      # no local stores to scan.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
-      #   just-booted dispatcher; a no-op unless it exposes an `outbox`
-      # @return [void]
+      # Redrives pending outbox rows after the dispatcher and saga
+      # rehydration both exist (a redriven row may advance a saga, which
+      # must already be in memory). Claimed rows are surfaced, never
+      # auto-redriven — see `Runtime::Outbox`. A no-op for a remote dispatcher.
       def self.redrive_outbox!(dispatcher)
         return unless dispatcher.respond_to?(:outbox)
 
         dispatcher.outbox.redrive!
       end
 
-      # Turns every `.hecksagon`-declared `AggregateDoor#mark_sensitive` fact into a real
-      # `Privacy::Marking.Mark` — after the dispatcher exists (dispatch needs a bound
-      # repository), idempotent across reboots (a marking already present is never
-      # re-dispatched, the same "provably never started" restraint `redrive_outbox!`
-      # holds itself to above). A no-op when nothing declared one, or when the domain
-      # never attached Privacy at all.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the just-booted
-      #   dispatcher `Privacy::Marking.Mark` dispatches through
-      # @param registry [Runtime::Registry] the just-booted registry `pending_privacy_markings`
-      #   was recorded on
-      # @return [void]
+      # Turns every `.hecksagon`-declared `mark_sensitive` fact into a real
+      # `Privacy::Marking.Mark`. Idempotent across reboots — a marking already
+      # present is never re-dispatched. A no-op when nothing declared one, or
+      # the domain never attached Privacy at all.
       def self.seed_privacy_markings!(dispatcher, registry)
         return if registry.pending_privacy_markings.empty?
         return unless registry.bluebook("Privacy")
@@ -115,40 +70,16 @@ module Hecks
         end
       end
 
-      # The explicit-file form — `paths` names the exact bluebook/hecksagon/
-      # world files to boot, in place, wherever they actually live. `boot`
-      # above only ever takes a directory and globs it; that is the right
-      # shape for a real deployment (`examples/banking`, a domain someone
-      # `cd`s into), and the wrong one for a caller that wants to declare a
-      # narrow, explicit scope and have it booted exactly as declared — a
-      # `.behaviors` file's own `loads` line is the motivating caller
-      # (`Hecks::Behaviors`), but this carries no behaviors-specific
-      # logic and is not gated behind requiring that module.
+      # Boots the exact bluebook/hecksagon/world files in `paths`, in place —
+      # unlike `boot`, no directory globbing and no copying into a temp dir
+      # (a `persisted_by` path must resolve against the real project root,
+      # not a copy's).
       #
-      # No copying, no temp directory. A prior port of this same idea
-      # (vendored into a downstream consumer, read before writing this)
-      # scoped a per-test boot by copying files into `Dir.mktmpdir` — which
-      # destroys real relative paths, and worse, makes a `persisted_by`
-      # path resolve against the temp copy's root instead of the project's
-      # own (confirmed there: a file adapter kept reading and writing the
-      # same deterministic tmp copy across an entire session, because
-      # `Hecks.boot`'s own `root` is always `File.dirname` of whatever
-      # directory it was handed). `directory` here is `File.dirname` of the
-      # first real path in `paths` — genuinely on disk, not a copy — so
-      # every downstream path (`EraCheck`, `persisted_by`, `shared_root`)
-      # resolves exactly as an ordinary directory boot's would.
-      #
-      # @param paths [Array<String>, String] the exact bluebook/hecksagon/world file paths
-      #   to boot, in the order they should load
-      # @param shared [String, nil] an explicit shared ports/adapters root override; nil
-      #   resolves it by walking up from `File.dirname` of the first path
-      # @param install_facade [Boolean] whether to install the `Widget::Item.Add(...)`
-      #   facade sugar
-      # @param environment [String, nil] the environment overlay to load after the
-      #   named files (e.g. `"production"`); nil loads none
+      # @param paths [Array<String>, String] the exact file paths to boot, in load order
+      # @param shared [String, nil] shared ports/adapters root; nil walks up from the first path
+      # @param environment [String, nil] environment overlay loaded after the named files
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
-      # @raise [Runtime::WiringError] if a boot gate finds a wiring problem (an undeclared
-      #   bind, a compute/rekey rule with no persistence plugin loaded, …)
+      # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
       def self.boot_files(paths, shared: nil, install_facade: true, environment: nil)
         loading   = Ports::Loading.bootstrap
         files     = Array(paths).map { |path| File.expand_path(path) }
@@ -167,31 +98,10 @@ module Hecks
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
 
-      # Runs every registered boot gate against `registry`, in order.
-      #
-      # ADR 0031 — a per-boot `BootGates` instance holds exactly the gates this
-      # registry's own bound adapters have a capability for, rather than two
-      # hardcoded, unconditional calls. Ordering is
-      # preserved: era-checking (when a persistence plugin contributes one)
-      # still runs before `verify!`, saga rehydration still runs after
-      # (conservative — see `SagaPersistence#rehydrate_sagas!`'s own
-      # comment).
-      #
-      # ADR 0033 — this loader no longer names `EraCheck`, or any other
-      # era-specific class, at all. Every loaded persistence plugin
-      # (`Ports::Persistence.each_plugin` — nothing here if nothing was
-      # ever `require`d, or brought in by a bound adapter, see
-      # `load_bound_adapters!`) is asked to contribute its own `:pre_verify`/
-      # `:post_verify` gates generically; `:saga_rehydration` is the one
-      # gate core still registers directly, because ADR 0031 already
-      # proved it's not era-specific.
-      #
-      # @param registry [Runtime::Registry] the registry mid-boot, with its bluebooks,
-      #   hecksagons, ports, adapters and worlds already loaded
-      # @param directory [String] the domain directory the gates report against in a refusal
-      # @return [Runtime::BootGates] the gates instance built and run for this boot
-      # @raise [Runtime::WiringError] if `registry.verify!` or any contributed gate finds
-      #   a wiring problem
+      # Runs every registered boot gate against `registry`, in order:
+      # era-checking (if a plugin contributes one) before `verify!`, saga
+      # rehydration after. No era-specific class is named here — each loaded
+      # persistence plugin contributes its own gates generically (ADR 0031).
       def self.run_boot_gates!(registry, directory)
         gates = BootGates.new
         load_bound_adapters!(registry)
@@ -208,17 +118,11 @@ module Hecks
       end
 
       # Resolves the Ruby implementation of every adapter a hecksagon binds.
-      #
-      # An adapter whose implementation loads on first mention (`PostgresEra`,
-      # through the era plugin) registers its persistence plugin as a side effect
-      # of that load. Resolving here, before the gates are collected, is what makes
-      # a domain that declares `persisted_by "PostgresEra"` boot with the plugin
-      # loaded and its era gates registered, without the app requiring the plugin
-      # itself. An adapter with no Ruby implementation is left for `verify!`, which
-      # refuses it with the bind it came from.
-      #
-      # @param registry [Runtime::Registry] the registry mid-boot, whose hecksagons name the binds
-      # @return [void]
+      # An adapter's implementation can register its own persistence plugin as
+      # a side effect of loading (e.g. `PostgresEra`) — resolving here, before
+      # gates are collected, is what registers those plugins' gates without
+      # the app requiring them itself. A bind with no implementation is left
+      # for `verify!` to refuse.
       def self.load_bound_adapters!(registry)
         registry.hecksagons.each_value do |hexagon|
           hexagon.binds.each do |bind|
@@ -229,23 +133,10 @@ module Hecks
         end
       end
 
-      # The one piece of the old, era-owned `check_compute_rules!` core
-      # still carries — deliberately thinner. `registry.translations` is
-      # plain `Bluebook::Translation`/`TranslationAggregate`/
-      # `TranslationCompute`/`TranslationRekey` data (`bluebook/
-      # translation.rb`, core, no era-specific class involved), so this
-      # needs nothing plugin-specific to ask "does anything declare a
-      # compute/rekey rule at all." A loaded persistence plugin (e.g. the
-      # era plugin's own `:era_compute_rules` gate, registered above) runs
-      # the real, adapter-aware version of this check and refuses by name
-      # ("...is bound to Memory") long before this ever would; this only
-      # fires when nothing did, because nothing was loaded to.
-      #
-      # @param registry [Runtime::Registry] the registry mid-boot, whose declared
-      #   `translations` are checked
-      # @return [void]
-      # @raise [Runtime::WiringError] if any translation declares a `computes`/`rekeys`
-      #   rule while no persistence plugin is loaded to interpret it
+      # A backstop only: fires when a translation declares a `computes`/
+      # `rekeys` rule but no persistence plugin is loaded to interpret it.
+      # Any loaded plugin's own compute-rules gate refuses earlier, by name,
+      # whenever one is loaded — this only runs when nothing was.
       def self.check_compute_rules_backstop!(registry)
         return if Ports::Persistence.plugins_loaded?
 
@@ -261,31 +152,11 @@ module Hecks
         end
       end
 
-      # `RemoteDispatcher` for a domain routed through Lambda,
-      # `Dispatcher` otherwise — the one place this decision gets
-      # made, so everything built on top (`Handle`, `AggregateDoor`,
-      # `Facade::Surface`) never has to know which class it's holding.
-      # `registry.bluebooks.keys.first` is the just-booted domain's own
-      # name (insertion order — the target's own bluebook loads before
-      # any `uses_framework` chapter, `bin/project_rust`'s own header
-      # draws the identical distinction), not a directory basename.
-      #
-      # `dispatched_by("Lambda")` is its own, explicit verb — not
-      # inferred from `deployed_to("AwsLambda")`'s mere presence. Both
-      # Banking's and Embryonaut's `.world` files already declare
-      # `deployed_to("AwsLambda")` (it only means "a deploy target
-      # exists"), so treating that alone as "boot this domain against
-      # Lambda" would have silently rerouted Banking's every local
-      # boot — every spec, every `bin/console` session — the moment
-      # this landed. A domain opts in explicitly, the same way
-      # `persisted_by("PostgresEra")` is never inferred from anything
-      # else either.
-      #
-      # @param registry [Runtime::Registry] the just-booted registry, whose just-booted
-      #   domain's `.world` is checked for `dispatched_by("Lambda")`
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] a `RemoteDispatcher`
-      #   bound to `registry` if the domain declares `dispatched_by("Lambda")`, a plain
-      #   `Dispatcher` otherwise
+      # `RemoteDispatcher` for a domain declaring `dispatched_by("Lambda")`,
+      # `Dispatcher` otherwise. That's an explicit opt-in, never inferred from
+      # `deployed_to("AwsLambda")` alone — that verb only means a deploy
+      # target exists, and treating it as "dispatch via Lambda" would reroute
+      # every local boot of a domain that merely declares one.
       def self.dispatcher_for(registry)
         domain = registry.bluebooks.keys.first
         settings = registry.world(domain)&.for_verb("dispatched_by") || {}
@@ -294,18 +165,9 @@ module Hecks
         RemoteDispatcher.new(registry, region: settings.fetch(:region, "us-east-1"), function: settings[:function])
       end
 
-      # Installs the facade sugar (`Widget::Item.Add(...)`), closed over
-      # `dispatcher`, and hands `dispatcher` back.
-      #
-      # The door is installed here, not stamped: the facade's modules close
-      # over this dispatcher, so the binding lives in the surface a boot
-      # installs rather than in a class-level global (`ruby_class.runtime =`
-      # on every aggregate's class) that would make two boots in one process
-      # share one name.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
-      #   just-booted dispatcher the facade should call into
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] `dispatcher`, unchanged
+      # Installs the facade sugar (`Widget::Item.Add(...)`) closed over
+      # `dispatcher`. The binding lives in the facade's own modules, not a
+      # class-level global, so two boots in one process don't share one name.
       def self.bind_runtime(dispatcher)
         Facade::Surface.install(dispatcher)
         dispatcher