hecks 2.8.0 → 3.0.0

data/lib/hecks/ports/identity_assignment.rb

@@ -2,21 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Which value a creating command's own identity field gets, when
-    # neither a slug-from-another-field nor a sequence-with-prefix
-    # mechanically answers it — a driving app's own console, say,
-    # falls back to this when a collection's identity strategy names
-    # "port" rather than "slug"/"sequence" (both of those stay pure
-    # config-driven mechanics, computed by whoever is dispatching,
-    # never by this port).
-    #
-    # Pure delegation, same as every sibling port (AccessControl,
-    # IdentityGeneration): an app's own domain declares what "port"
-    # actually means for it — mint a real UUID via
-    # Ports::IdentityGeneration, derive something else entirely — this
-    # port just resolves the one adapter that domain wired and calls
-    # it, the same "one adapter registry-wide, refuse if zero or many"
-    # resolution every other port here already uses.
+    # Which value a creating command's identity field gets when its strategy names "port".
+    # Delegates to the one adapter the domain wired.
     module IdentityAssignment
       NAME = "identity_assignment".freeze
 
@@ -24,29 +11,21 @@ module Hecks
 
       # Asks the domain's adapter which value a creating command's identity field gets.
       #
-      # No adapter, spec double or caller of this port ships in this repository, so every
-      # shape below other than `registry` is adapter-defined: the port forwards it untouched.
+      # Every argument other than `registry` is adapter-defined and forwarded untouched.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param agg_name [Object] adapter-defined, forwarded unchanged; names the aggregate
-      #   whose identity field is being assigned
-      # @param field_name [Object] adapter-defined, forwarded unchanged; names the identity
-      #   field
-      # @param args [Object] adapter-defined, forwarded unchanged; the creating command's own
-      #   arguments
+      # @param agg_name [Object] adapter-defined; names the aggregate being assigned
+      # @param field_name [Object] adapter-defined; names the identity field
+      # @param args [Object] adapter-defined; the creating command's own arguments
       # @return [Object] adapter-defined value to assign as the identity
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       def assign(registry, agg_name:, field_name:, args:)
         adapter(registry).assign(registry, agg_name: agg_name, field_name: field_name, args: args)
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/identity_generation.rb

@@ -2,27 +2,9 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # A creating command with no natural key needs a value from
-    # somewhere to be its identity — this is that somewhere. Resolved
-    # the same way `Ports::Extraction` resolves its own adapter (one
-    # adapter registry-wide implements this port, not a per-aggregate
-    # binding the way persistence needs — different aggregates have no
-    # real reason to want different id-generation strategies within
-    # one running app).
-    #
-    # Replay needs no suppression here, on purpose. A UUID minted for a
-    # creating command's identity gets baked into that step's own args
-    # — an ordinary string value — the moment it's generated, by
-    # whoever issues the first, live dispatch. A recorded corpus
-    # script or a captured fuzz-replay step already holds that
-    # concrete value; replaying it calls `dispatch` with the same
-    # args, and this module is never consulted again, for the same
-    # reason `SecureRandom.uuid` never runs twice for one
-    # already-recorded step today. `Event#occurred_at`
-    # (`command_rules/emission.rb`) is the one other "environmental
-    # fact, not caller-supplied" this codebase has, and it's handled
-    # the identical way: it fires on every dispatch, replay included,
-    # and comparison simply excludes it.
+    # Supplies the identity for a creating command with no natural key.
+    # One adapter registry-wide implements it. Replay never calls it: the minted value is
+    # already baked into the recorded step's args.
     module IdentityGeneration
       NAME = "identity_generation".freeze
 
@@ -32,18 +14,13 @@ module Hecks
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [String] a newly minted identity: a random UUID from `SecureRandomIdentity`,
-      #   or a decimal counter (`"1"`, `"2"`, …) from the deterministic `SequentialIdentity`
-      #   spec double — unique per adapter, not guaranteed UUID-shaped
+      #   or a decimal counter from the deterministic `SequentialIdentity` spec double
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       def uuid(registry) = adapter(registry).uuid
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/identity_resolution.rb

@@ -2,16 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # An authenticated (issuer, subject) pair, resolved to the id of a stable
-    # `Identity` — the other half of the same symmetry `Authorization`
-    # already has for Governance: one adapter registry-wide answers this
-    # port, resolved the same zero/one/many way, so an application never
-    # has to name `Identity` directly to ask "who is this."
-    #
-    # Answers `nil` for a pair nothing has linked — the caller decides
-    # what that means (refuse, prompt to register, whatever), the same
-    # way `Authorization#holds_role?` answering `false` decides nothing
-    # on its own.
+    # Resolves an authenticated (issuer, subject) pair to a stable identity id.
+    # One adapter registry-wide answers this port.
     module IdentityResolution
       NAME = "identity_resolution".freeze
 

data/lib/hecks/ports/key_vault.rb

@@ -2,55 +2,23 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # A subject's own encryption key lives here, one boundary removed from
-    # any event or bluebook attribute — cryptoshredding depends on the key
-    # material never being reachable except through this port's opaque
-    # reference (see `Privacy::SubjectKey`, `lib/hecks/framework/bluebook/
-    # privacy.bluebook`). Resolved the same way `Ports::IdentityGeneration`
-    # resolves its own adapter: one adapter registry-wide answers this
-    # port, not a per-aggregate binding.
+    # A subject's encryption key, one boundary removed from any event or
+    # bluebook attribute, so cryptoshredding never exposes key material.
     module KeyVault
       NAME = "key_vault".freeze
 
       module_function
 
-      # Mints a fresh per-subject encryption key and hands back an opaque reference to it.
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param subject_id [String] the data subject the key is being issued for
-      # @return [String] an opaque key reference; the key material itself never leaves the
-      #   bound adapter, and is never suitable to store on an event or a bluebook attribute
+      # Mints a per-subject key; the key material itself never leaves the bound adapter.
       def issue(registry, subject_id:) = adapter(registry).issue(subject_id: subject_id)
 
-      # Irrevocably destroys a key that {#issue} already returned a reference for.
-      #
-      # Ciphertext produced under `key_reference` becomes permanently unrecoverable the
-      # moment this returns — the mechanism a right-to-erasure request satisfies without
-      # rewriting or deleting any event.
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param key_reference [String] the opaque reference {#issue} returned
-      # @return [Boolean] true when a live key was destroyed; false when this reference was
-      #   already destroyed, or was never issued
+      # Irrevocably destroys a key; ciphertext under it becomes unrecoverable at once —
+      # how a right-to-erasure request is satisfied without rewriting or deleting events.
       def destroy(registry, key_reference:) = adapter(registry).destroy(key_reference: key_reference)
 
-      # Erases one subject: destroys their key in the vault, then durably records that it
-      # happened — in that fixed order, so a caller cannot dispatch `Shred` before the key
-      # is actually gone the way calling {#destroy} and `dispatch_flat` separately would
-      # allow. `Privacy::SubjectKey.Shred`'s own lifecycle guard (`from: "active"`) still
-      # refuses a raw double-dispatch; this is what closes the gap one level up, where the
-      # danger isn't a duplicate `Shred` but `Shred` running *before* {#destroy} does.
-      #
-      # Idempotent: a subject with no live `SubjectKey` record, or one already shredded,
-      # is left alone and answered `false` — a retried erasure request never re-destroys
-      # an already-gone key or double-dispatches `Shred`.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-      #   dispatcher both the lookup query and the `Shred` dispatch run through
-      # @param domain [String] the subject's own domain FQN, e.g. `"Site::Registration"`
-      # @param subject_id [String] the data subject to erase
-      # @return [Boolean] true when a live key was found and shredded by this call; false
-      #   when no `SubjectKey` record exists for this subject, or it was already shredded
+      # Destroys the subject's key, then dispatches Shred, in that fixed order — never the
+      # reverse, so Shred cannot be dispatched before the key is actually gone. Idempotent:
+      # a subject with no live key, or one already shredded, is left alone and returns false.
       def shred!(dispatcher, domain:, subject_id:) # rubocop:disable Naming/PredicateMethod
         record = dispatcher.query("Privacy::SubjectKey.ForSubject", domain: domain, subject_id: subject_id).first
         return false unless record
@@ -61,11 +29,7 @@ module Hecks
         true
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
-      #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port
+      # Refuses an ambiguous wiring rather than choosing an adapter arbitrarily.
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/persistence/append_only.rb

@@ -6,7 +6,12 @@ module Hecks
     module Persistence
       # `mirrors` is durable replication intent.  It is part of the same
       # append as the authoritative state, never a second outbox store.
-      Entry = Struct.new(:operation, :id, :state, :mirrors, keyword_init: true) do
+      #
+      # `sequence` is the journal position an adapter assigned this entry
+      # (set by `append` on a live write, or by `entries`/`entries_since` on
+      # a replayed one); nil for an adapter that assigns none. It rides
+      # along so `project` can advance a checkpoint without a second lookup.
+      Entry = Struct.new(:operation, :id, :state, :mirrors, :sequence, keyword_init: true) do
         # Tells a projecting adapter that this entry writes a record.
         #
         # @return [Boolean] true when `operation` is the String `"save"`
@@ -18,9 +23,8 @@ module Hecks
         def delete? = operation == "delete"
       end
 
-      # Makes append-before-projection a port invariant. Adapters retain
-      # control of their durable format, but every one must accept the same
-      # entry stream and materialize current state from it.
+      # Makes append-before-projection a port invariant: adapters keep their own durable
+      # format, but must accept the same entry stream and materialize state from it.
       class AppendOnly
         attr_reader :adapter
 
@@ -71,6 +75,17 @@ module Hecks
         #   undecoded (`CodecBoundary.check_entries!`)
         def entries = @adapter.entries
 
+        # Reads how far this repository's journal has been compacted, when the adapter tracks
+        # that (Postgres, Sqlite).
+        #
+        # @return [Integer] the highest journal `sequence` already deleted by compaction; 0 for
+        #   an adapter that tracks no such thing, or nothing compacted yet
+        def compacted_through
+          return 0 unless @adapter.respond_to?(:compacted_through)
+
+          @adapter.compacted_through
+        end
+
         # Lists the optional persistence behaviours the adapter advertises.
         #
         # @return [Array<Symbol>] frozen capability names such as `:atomic_put`,
@@ -96,12 +111,8 @@ module Hecks
 
         # Reads the events the adapter has durably recorded.
         #
-        # Not an endless `def events = ... if ...` — that modifier binds to
-        # the whole `def`, not just its body, so it evaluates against
-        # `@adapter` while `@adapter` is still nil (class-body time,
-        # before `initialize` ever runs) and silently skips defining the
-        # method at all. Found live: nothing in this codebase called
-        # `AppendOnly#events` before Memory got a `reset!` test that did.
+        # Written as an `if` guard, not a trailing modifier, which would evaluate against
+        # `@adapter` before `initialize` runs and silently skip defining the method.
         #
         # @return [Array<Runtime::Event>, nil] recorded events, oldest first; nil when the
         #   adapter keeps no event log
@@ -109,15 +120,39 @@ module Hecks
           @adapter.events if @adapter.respond_to?(:events)
         end
 
-        # Replays the whole journal through `project` to rebuild the projected records.
+        # Reads back one record's durably recorded events, oldest first, scoped by the
+        # adapter itself when it can (a SQL adapter pushes this down as a `WHERE` clause
+        # instead of `#events`'s whole-table read); falls back to filtering `#events` for
+        # an adapter with no scoped lookup of its own.
         #
-        # An append is durable before a projection is attempted. Replaying the
-        # log restores a snapshot/table after a crash in that small window.
+        # @param aggregate [String] the `"domain::AggregateName"` key events are stored under
+        # @param id [String, Object] the record's identity, matched as `id.to_s`
+        # @return [Array<Runtime::Event>, nil] the record's events; nil when the adapter
+        #   keeps no event log at all
+        def events_for(aggregate:, id:)
+          return @adapter.events_for(aggregate: aggregate, id: id) if @adapter.respond_to?(:events_for)
+
+          events&.select { |event| event.aggregate == aggregate && event.id.to_s == id.to_s }
+        end
+
+        # Replays unprojected journal entries through `project` to rebuild the projected records.
+        #
+        # An append is durable before a projection is attempted; replaying restores a
+        # snapshot/table after a crash in that small window. Postgres and Sqlite keep their
+        # projected table in the same transaction as the journal append, so they never fall
+        # behind it — each tracks how far it has replayed (`checkpoint`) and only re-walks
+        # entries past that point (`entries_since`), bounded by activity since the last boot,
+        # not total history. An adapter without that pair (Memory, Heki, D1, PostgresEra,
+        # RemoteRuntime) is unaffected: it still replays every entry.
         #
         # @return [Persistence::AppendOnly] self, so a factory can build and recover in one
         #   expression
         def recover!
-          entries.each { |entry| project(entry) }
+          if @adapter.respond_to?(:checkpoint) && @adapter.respond_to?(:entries_since)
+            @adapter.entries_since(@adapter.checkpoint).each { |entry| project(entry) }
+          else
+            entries.each { |entry| project(entry) }
+          end
           self
         end
 
@@ -142,29 +177,15 @@ module Hecks
 
         # Journals an instance's state, projects it, and reports how the write landed.
         #
-        # Returns an `Outcome`, not a bare `Instance` — every call site
-        # (`CommandInterpreter`/`EntityInterpreter`'s own `step_save`,
-        # `RebuildSweep#refresh`) reads it that way.
-        #
-        # `expected_version:` requests optimistic-concurrency CAS — commit
-        # only if the stored record's version still matches what this
-        # instance was read at. It is `nil` both when a caller explicitly
-        # doesn't want CAS (`RebuildSweep#refresh`'s own projection-field
-        # touch-up, which has no `given` to protect) and when the instance
-        # is brand new (never read from storage, so `instance.version` is
-        # nil) — both cases fall through to the plain, unconditional
-        # `project(entry)` below, byte-for-byte today's behavior. Only an
-        # adapter that both receives a non-nil `expected_version` and
-        # declares `:optimistic_concurrency` gets CAS treatment; every
-        # other adapter/call site is unaffected.
+        # Returns an Outcome, not a bare Instance, so callers can check `:saved` vs `:stale`;
+        # `expected_version:` only triggers CAS on an adapter declaring `:optimistic_concurrency`.
         #
         # @param instance [Runtime::Instance] the record to persist; its `state` is shallow
         #   copied into the entry
         # @param expected_version [Integer, nil] the version the instance was read at, or nil
         #   for an unconditional write
-        # @return [Persistence::Outcome] status `:saved` or `:stale`; on `:saved` its `instance`
-        #   is what the adapter's `project` answered, else the instance passed in; on `:stale`
-        #   it is the instance passed in. The entry is journaled even when the result is `:stale`
+        # @return [Persistence::Outcome] status `:saved` or `:stale`; `instance` is the
+        #   adapter's projected result on `:saved`, else the instance passed in
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
         def save(instance, expected_version: nil)
           entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
@@ -218,18 +239,7 @@ module Hecks
 
         # Records one emitted event durably, when the adapter keeps an event log.
         #
-        # Not an endless `def record_event = ... if ...` — same gotcha as
-        # `events` above, and it bit for real here: this guard evaluated
-        # against `@adapter` at class-body time (nil, always false), so
-        # `record_event` was never defined at all. `emission.rb`'s own
-        # `repository.record_event(event) if repository.respond_to?(:record_event)`
-        # therefore never fired for any adapter, ever — every declared
-        # `emits` was computed and reported in `registry.event_log` (an
-        # in-process array, gone at exit) but never durably recorded.
-        # Caught because a live tail of a domain's own persisted events
-        # found nothing to tail. `sqlite_spec.rb`/`postgres_spec.rb`/
-        # `postgres_era_spec.rb` all call `adapter.record_event` directly,
-        # bypassing this wrapper — which is exactly why no spec noticed.
+        # Written as an `if` guard, not a trailing modifier — same reason as `events` above.
         #
         # @param event [Runtime::Event] the event to record
         # @return [Object, nil] adapter-defined write result (an Array for Memory, a driver
@@ -240,17 +250,9 @@ module Hecks
 
         # Runs the block inside the adapter's transaction, or plainly when it has none.
         #
-        # One COMMIT boundary for save + emit + outbox — `Interpreting#
-        # run_dispatch_order` runs the `save` and `emit` steps inside
-        # this block, so an adapter that owns a real transaction
-        # (Sqlite, Postgres) commits the aggregate row, its journal
-        # entry, and the outbox rows together or not at all. An adapter
-        # without one just yields: Memory has nothing to roll back, and
-        # a file adapter's own `with_lock` already serialises its pair
-        # of writes. Nested calls are the adapter's problem to make
-        # re-entrant (both SQL adapters check for an open transaction
-        # first) — a reaction dispatched from inside a drain never nests
-        # here anyway, because draining happens after this block returns.
+        # One commit boundary for save + emit + outbox: an adapter with a real transaction
+        # (Sqlite, Postgres) commits the row, journal entry, and outbox rows together or
+        # not at all; Memory just yields, having nothing to roll back.
         #
         # @yield the writes to commit together; an exception raised inside rolls back an
         #   adapter-owned transaction and propagates
@@ -264,11 +266,9 @@ module Hecks
 
         # Runs the block while holding the adapter's cross-process write lock.
         #
-        # Only an adapter advertising `:cross_process_lock` (PostgresEra —
-        # see ADR 0036) implements this; `run_dispatch_order_with_isolation`
-        # (runtime/interpreting.rb) checks `capabilities` before ever
-        # calling it, so the plain `yield` fallback here only guards
-        # against a stray direct call, not the real dispatch path.
+        # Only PostgresEra advertises `:cross_process_lock` (ADR 0036); the real dispatch
+        # path checks `capabilities` first, so this `yield` fallback only guards a stray
+        # direct call.
         #
         # @yield the dispatch to run with writers serialised
         # @return [Object] adapter-defined; the block's own value when the adapter has no
@@ -279,10 +279,7 @@ module Hecks
           yield
         end
 
-        # **The outbox contract** — four optional adapter methods, probed
-        # together the way `save_saga`/`delete_saga`/`each_saga` are
-        # (`Registry::SagaPersistence`): an adapter either has an outbox
-        # or it doesn't, never half of one. See `Runtime::Outbox`.
+        # An adapter implements the whole outbox contract or none of it (see Runtime::Outbox).
         OUTBOX_METHODS = %i[outbox_enqueue outbox_claim outbox_settle outbox_rows].freeze
 
         # Reports whether the adapter implements the whole outbox contract; the answer is

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -4,23 +4,13 @@ require_relative "../../runtime/registry"
 module Hecks
   module Ports
     module Persistence
-      # Resolves one aggregate's persistence topology. An unmarked binding is
-      # authoritative; roles are deliberately opt-in so a second adapter can
-      # never silently become a read source.
+      # Resolves one aggregate's persistence topology; an unmarked binding is
+      # authoritative, and roles are opt-in so no adapter silently becomes a read source.
       module BindingPolicy
         module_function
 
-        # Picks the one bind that names an aggregate's authoritative store.
-        #
-        # A domain with no hecksagon gets the default in-memory bind. A domain that has one
-        # must bind the aggregate exactly once without a role.
-        #
-        # A `default_adapter` a world declares (`Registry#default_adapter_for` — the
-        # chapter's own world, else the project's) stands in wherever the hecksagon binds
-        # nothing for the aggregate, and replaces the in-memory fallback for a domain
-        # with no hecksagon. It is never consulted once the hecksagon binds the aggregate
-        # or declares a domain-level default of its own, so an explicit chapter decision
-        # always wins.
+        # Picks the one bind that names an aggregate's authoritative store. A world's
+        # `default_adapter` only fills a hecksagon's gap; an explicit bind always wins.
         #
         # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
         # @param domain [String, Symbol] name of the domain the aggregate belongs to

data/lib/hecks/ports/persistence/codec_boundary.rb

@@ -4,47 +4,15 @@ require_relative "../../runtime/errors"
 module Hecks
   module Ports
     module Persistence
-      # No adapter can build an `Instance` from undecoded state (Phase 2,
-      # Track A, PR A3). Routing every adapter through `StateCodec` is a
-      # convention until something refuses the bypass; this is that
-      # something, and it is installed by `RepositoryFactory.build` — the
-      # one place every runtime repository is made — so no adapter can opt
-      # out of it.
-      #
-      # ## The mechanism, two halves
-      #
-      # 1. `guard!(adapter)` extends the adapter object (not its class,
-      #    not a proxy — `is_a?`, `class`, and `===` stay the adapter's
-      #    own) with a module that wraps every public method the adapter's
-      #    class defines. Each call runs inside the boundary: a
-      #    thread-local flag, re-entrant, restored on the way out. A block
-      #    the caller passes (`transaction`, `with_write_lock`,
-      #    `each_saga`) runs outside it — that block is the dispatch
-      #    itself (hydrate, entity views, mutation), not adapter code.
-      #    Reaching the adapter through `repository.adapter` (the query
-      #    port, saga persistence, `bin/heki_compact`) is guarded all the
-      #    same: the wrapper is on the object.
-      #
-      # 2. `Runtime::Instance#initialize` asks `check_state!` whenever it
-      #    is handed `state:`. Outside the boundary that is a no-op; inside
-      #    it, state `StateCodec.decoded?` rejects refuses by name. An
-      #    `entries` answer is checked the same way on its way out, since a
-      #    journal `Entry` is not an `Instance`.
-      #
-      # ## Checked, not silently decoded
-      #
-      # An adapter that forgets the codec is a bug in that adapter, and
-      # decoding for it here would hide the forgetting. Hydration does not
-      # respell keys either (A4) — `Value.hydrate` refuses a non-Symbol
-      # top-level key everywhere — so this boundary's deep check and
-      # hydration's shallow one agree.
+      # Refuses to let a guarded adapter build an `Instance` from undecoded state.
+      # `RepositoryFactory.build` installs it, so no adapter can opt out.
       module CodecBoundary
         KEY = :hecks_persistence_codec_boundary
 
         module_function
 
-        # Extends an adapter object so every public method its class defines runs inside the
-        # boundary; guarding an adapter twice wraps it once.
+        # Extends the adapter object so every public method its class defines runs inside the
+        # boundary; guarding twice wraps once.
         #
         # @param adapter [Object] a driven persistence adapter instance
         # @return [Object] the same adapter object, now including `Guarded`
@@ -53,33 +21,22 @@ module Hecks
           adapter
         end
 
-        # Reports whether the current thread is executing inside a guarded adapter call.
+        # Whether this thread is currently inside a guarded adapter call.
         #
-        # @return [Boolean] true between entering a guarded adapter method and yielding to the
-        #   caller's block or returning
+        # @return [Boolean]
         def active? = Thread.current[KEY] == true
 
-        # Runs the block with the boundary switched on for this thread, restoring the earlier
-        # setting afterwards.
-        #
-        # @yield adapter code whose `Instance` construction is to be checked
-        # @return [Object] the block's value
+        # Runs the block with the boundary on for this thread; re-entrant.
         def within(&) = with_flag(true, &)
 
-        # Runs the block with the boundary switched off for this thread, restoring the earlier
-        # setting afterwards.
-        #
-        # @yield caller code, such as a dispatch running inside the adapter's transaction
-        # @return [Object] the block's value
+        # Runs the block with the boundary off for this thread; re-entrant.
         def outside(&) = with_flag(false, &)
 
-        # Refuses state an adapter is about to build an `Instance` from unless it is decoded;
-        # outside the boundary it checks nothing.
+        # Refuses undecoded state headed for `Runtime::Instance.new`; a no-op outside the boundary.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the state
         #   belongs to
         # @param state [Hash, Runtime::Value] the state handed to `Runtime::Instance.new`
-        # @return [nil] when the boundary is inactive or the state is decoded
         # @raise [Runtime::WiringError] if the boundary is active and
         #   `StateCodec.decoded?` rejects the state
         def check_state!(aggregate, state)
@@ -93,13 +50,12 @@ module Hecks
         end
 
         # Refuses a guarded adapter's `entries` answer if any entry's state is undecoded.
+        # A journal `Entry` is not an `Instance`, so `check_state!` never sees it.
         #
-        # @param adapter [Object] the guarded adapter, asked for its `aggregate` and class name
-        # @param entries [Array<Persistence::Entry>, Object] what the adapter's `entries`
-        #   returned; anything that is not an Array passes through unchecked
+        # @param adapter [Object] the guarded adapter
+        # @param entries [Array<Persistence::Entry>, Object] anything but an Array passes unchecked
         # @return [Array<Persistence::Entry>, Object] `entries` itself
-        # @raise [Runtime::WiringError] if an `Entry` in the Array carries state
-        #   `StateCodec.decoded?` rejects
+        # @raise [Runtime::WiringError] if an `Entry` carries state `StateCodec.decoded?` rejects
         def check_entries!(adapter, entries)
           return entries unless entries.is_a?(Array)
 
@@ -113,13 +69,7 @@ module Hecks
           entries
         end
 
-        # Sets the thread-local boundary flag for the length of the block, which is what makes
-        # the boundary re-entrant.
-        #
-        # @param value [Boolean] true to switch the boundary on, false to switch it off
-        # @yield the code to run under that setting
-        # @return [Object] the block's value; the earlier flag is restored even when the
-        #   block raises
+        # Sets the thread-local flag for the block and restores it after, even on a raise.
         def with_flag(value)
           previous = Thread.current[KEY]
           Thread.current[KEY] = value
@@ -128,24 +78,18 @@ module Hecks
           Thread.current[KEY] = previous
         end
 
-        # Marks a guarded adapter so a second `guard!` (a projection and an
-        # authoritative repository built over one object) never wraps twice.
+        # Marks a guarded adapter so a second `guard!` never wraps it twice.
         module Guarded; end
 
-        # Filled lazily under `WRAPPERS_LOCK`, one entry per adapter class —
-        # a cache, deliberately mutable.
+        # A per-adapter-class cache, filled lazily under `WRAPPERS_LOCK`; deliberately mutable.
         WRAPPERS = {} # rubocop:disable Style/MutableConstant
         WRAPPERS_LOCK = Mutex.new
 
         # Builds, or fetches from the cache, the module that guards one adapter class.
-        #
-        # One wrapper module per adapter class, built once: every public
-        # instance method the class (and its ancestors below Object)
-        # defines, each forwarding to `super` inside the boundary.
+        # Each public method forwards to `super` inside the boundary.
         #
         # @param klass [Class] the adapter's class
-        # @return [Module] an anonymous module including `Guarded`, meant to be `extend`ed onto
-        #   instances of `klass`
+        # @return [Module] an anonymous module including `Guarded`, to `extend` onto instances
         def wrapper_for(klass)
           WRAPPERS_LOCK.synchronize do
             WRAPPERS[klass] ||= Module.new do
@@ -161,12 +105,8 @@ module Hecks
           end
         end
 
-        # Wraps the caller's own block so it runs outside the boundary
-        # whenever the adapter yields to it.
-        #
-        # @param block [Proc, nil] the block the caller passed to the adapter method
-        # @return [Proc, nil] a proc forwarding its arguments to `block` under `outside`; nil
-        #   when no block was given
+        # Wraps the caller's block so it runs outside the boundary when the adapter yields to it;
+        # that block is the dispatch itself, not adapter code.
         def outside_block(block)
           return nil unless block