hecks 1.3.0 → 1.4.0

data/lib/hecks/ports/identity_generation.rb

@@ -3,19 +3,19 @@ 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
+    # 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
+    # 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
+    # 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`
@@ -28,8 +28,22 @@ module Hecks
 
       module_function
 
+      # Mints a fresh identity value from the bound adapter.
+      #
+      # @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
+      # @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.
+      #
+      # @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`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/identity_resolution.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # AN AUTHENTICATED (issuer, subject) PAIR, RESOLVED TO A STABLE
+    # 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
@@ -17,10 +17,27 @@ module Hecks
 
       module_function
 
+      # Looks up the id of the identity an authenticated (issuer, subject) pair is linked to.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @param issuer [String] the OIDC issuer that authenticated the caller
+      # @param subject [String] the OIDC subject the issuer vouches for
+      # @return [String, nil] the linked identity's id, usable as an `actor_id` for
+      #   `Ports::Authorization.holds_role?` — not an `Identity` record; nil if nothing has
+      #   linked this pair
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def resolve(registry, issuer:, subject:)
         adapter(registry).resolve(registry, issuer: issuer, subject: subject)
       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,
+      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/loading.rb

@@ -10,6 +10,10 @@ module Hecks
 
       module_function
 
+      # Builds the loader a boot starts from, before any registry exists to resolve one.
+      #
+      # @return [Adapters::Folder] a new `Folder` adapter with no settings and no root,
+      #   constructed directly rather than resolved through a registry
       def bootstrap = Adapters::Folder.new
     end
   end

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

@@ -7,7 +7,14 @@ module Hecks
       # `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
+        # Tells a projecting adapter that this entry writes a record.
+        #
+        # @return [Boolean] true when `operation` is the String `"save"`
         def save? = operation == "save"
+
+        # Tells a projecting adapter that this entry removes a record.
+        #
+        # @return [Boolean] true when `operation` is the String `"delete"`
         def delete? = operation == "delete"
       end
 
@@ -17,8 +24,14 @@ module Hecks
       class AppendOnly
         attr_reader :adapter
 
+        # Names the aggregate this repository stores, as the wrapped adapter holds it.
+        #
+        # @return [Bluebook::Aggregate] the aggregate the adapter was built for
         def aggregate = @adapter.aggregate
 
+        # @param adapter [Object] a driven persistence adapter; it must respond to `append`,
+        #   `project` and `entries`
+        # @raise [Runtime::WiringError] if the adapter lacks any of those three methods
         def initialize(adapter)
           @adapter = adapter
           required = %i[append project entries]
@@ -29,58 +42,130 @@ module Hecks
           end
         end
 
+        # Reads one record's current projected state from the adapter.
+        #
+        # @param id [String, Object] the record's identity; adapters compare it as `id.to_s`
+        # @return [Runtime::Instance, nil] the stored record, or nil when no record has that id
         def find(id) = @adapter.find(id)
+
+        # Lists every record the adapter currently projects, forwarding the keywords untouched.
+        #
+        # The shipped adapters accept `order_by:` (an attribute name, default nil for id or
+        # insertion order) and `direction:` (`:asc` or `:desc`).
+        #
+        # @return [Array<Runtime::Instance>] the stored records; `[]` when there are none
+        # @raise [Runtime::WiringError] from a SQL adapter when `order_by:` names no attribute
+        #   of the aggregate
         def all(**) = @adapter.all(**)
+
+        # Counts the records the adapter currently projects.
+        #
+        # @return [Integer] number of stored records, not of journal entries
         def count = @adapter.count
+
+        # Reads the adapter's whole journal, oldest entry first.
+        #
+        # @return [Array<Persistence::Entry>] every appended entry with decoded state; `[]` for
+        #   an empty journal or a `RemoteRuntime` adapter
+        # @raise [Runtime::WiringError] if a guarded adapter answers an entry whose state is
+        #   undecoded (`CodecBoundary.check_entries!`)
         def entries = @adapter.entries
 
+        # Lists the optional persistence behaviours the adapter advertises.
+        #
+        # @return [Array<Symbol>] frozen capability names such as `:atomic_put`,
+        #   `:optimistic_concurrency` or `:cross_process_lock`; `[]` when the adapter declares
+        #   no `persistence_capabilities`
         def capabilities
           return [] unless @adapter.respond_to?(:persistence_capabilities)
 
           Array(@adapter.persistence_capabilities).map(&:to_sym).freeze
         end
 
+        # Clears the adapter's stored records and journal so a kept runtime starts clean.
+        #
+        # @return [Object] whatever the adapter's `reset!` returns; every shipped adapter
+        #   returns itself
+        # @raise [Runtime::WiringError] if the adapter has no `reset!`, or (PostgresEra) if row
+        #   level security silently matched none of the journal rows
         def reset!
           raise Runtime::WiringError, "append-only adapter cannot reset" unless @adapter.respond_to?(:reset!)
 
           @adapter.reset!
         end
 
-        # NOT an endless `def events = ... if ...` — that modifier binds to
-        # the WHOLE `def`, not just its body, so it evaluates against
+        # 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.
+        #
+        # @return [Array<Runtime::Event>, nil] recorded events, oldest first; nil when the
+        #   adapter keeps no event log
         def events
           @adapter.events if @adapter.respond_to?(:events)
         end
 
+        # Replays the whole journal through `project` to rebuild the projected records.
+        #
         # An append is durable before a projection is attempted. Replaying the
         # log restores a snapshot/table after a crash in that small window.
+        #
+        # @return [Persistence::AppendOnly] self, so a factory can build and recover in one
+        #   expression
         def recover!
           entries.each { |entry| project(entry) }
           self
         end
 
+        # Writes one entry to the adapter's durable journal, before any projection of it.
+        #
+        # @param entry [Persistence::Entry] the save or delete to journal
+        # @return [Persistence::Entry] the entry as the adapter returns it; every shipped
+        #   adapter returns the entry it was given
+        # @raise [Runtime::WiringError] from a `RemoteRuntime` adapter, which has no local
+        #   journal, and from PostgresEra when its era is superseded
         def append(entry) = @adapter.append(entry)
+
+        # Applies one journaled entry to the adapter's current-state store.
+        #
+        # @param entry [Persistence::Entry] the save or delete to materialize
+        # @return [Object, nil] adapter-defined: Memory, Sqlite, Postgres and PostgresEra answer
+        #   the saved `Runtime::Instance`; Heki and `SqliteProjection` answer the entry;
+        #   a delete answers a driver result, the removed record, or nil
+        # @raise [Runtime::WiringError] from a `RemoteRuntime` adapter, which projects nothing
+        #   locally
         def project(entry) = @adapter.project(entry)
 
+        # 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
+        # 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
+        # adapter that both receives a non-nil `expected_version` and
         # declares `:optimistic_concurrency` gets CAS treatment; every
         # other adapter/call site is unaffected.
+        #
+        # @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`
+        # @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)
           append(entry)
@@ -94,6 +179,17 @@ module Hecks
           Outcome.new(status: :saved, instance: saved || instance)
         end
 
+        # Writes an instance through the adapter's own existence-check-and-write critical
+        # section, so a create cannot race another writer.
+        #
+        # @param instance [Runtime::Instance] the record to persist
+        # @param insert_only [Boolean] true to refuse replacing a record that already exists
+        # @return [Persistence::Outcome] status `:inserted`, `:replaced`, or `:conflicted` when
+        #   `insert_only` met an existing record and nothing was written; `instance` is always
+        #   the instance passed in
+        # @raise [Runtime::WiringError] if the adapter does not both advertise `:atomic_put`
+        #   and implement it
+        # @raise [ArgumentError] if the adapter answers a status outside `Outcome::STATUSES`
         def atomic_put(instance, insert_only: false)
           unless capabilities.include?(:atomic_put) && @adapter.respond_to?(:atomic_put)
             raise Runtime::WiringError,
@@ -105,6 +201,12 @@ module Hecks
           Outcome.new(status: status, instance: instance)
         end
 
+        # Journals and projects the removal of one record, if it exists.
+        #
+        # @param id [String, Object] the record's identity; journaled as `id.to_s`
+        # @return [Boolean] true when a record was found and deleted, false when there was
+        #   none and nothing was journaled
+        # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
         def delete(id)
           return false unless find(id)
 
@@ -114,7 +216,9 @@ module Hecks
           true
         end
 
-        # NOT an endless `def record_event = ... if ...` — same gotcha as
+        # 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
@@ -126,11 +230,17 @@ module Hecks
         # 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.
+        #
+        # @param event [Runtime::Event] the event to record
+        # @return [Object, nil] adapter-defined write result (an Array for Memory, a driver
+        #   result for the SQL adapters); nil when the adapter has no `record_event`
         def record_event(event)
           @adapter.record_event(event) if @adapter.respond_to?(:record_event)
         end
 
-        # ONE COMMIT BOUNDARY FOR SAVE + EMIT + OUTBOX — `Interpreting#
+        # 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
@@ -141,39 +251,93 @@ module Hecks
         # 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.
+        #
+        # @yield the writes to commit together; an exception raised inside rolls back an
+        #   adapter-owned transaction and propagates
+        # @return [Object] adapter-defined; the block's own value for every adapter without a
+        #   `transaction` and for Memory
         def transaction(&)
           return @adapter.transaction(&) if @adapter.respond_to?(:transaction)
 
           yield
         end
 
-        # ONLY an adapter advertising `:cross_process_lock` (PostgresEra —
+        # 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.
+        #
+        # @yield the dispatch to run with writers serialised
+        # @return [Object] adapter-defined; the block's own value when the adapter has no
+        #   `with_write_lock`
         def with_write_lock(&)
           return @adapter.with_write_lock(&) if @adapter.respond_to?(:with_write_lock)
 
           yield
         end
 
-        # THE OUTBOX CONTRACT — four optional adapter methods, probed
+        # **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`.
         OUTBOX_METHODS = %i[outbox_enqueue outbox_claim outbox_settle outbox_rows].freeze
 
+        # Reports whether the adapter implements the whole outbox contract; the answer is
+        # memoized per repository.
+        #
+        # @return [Boolean] true only when the adapter responds to all four `OUTBOX_METHODS`
         def outbox?
           @outbox = OUTBOX_METHODS.all? { |method| @adapter.respond_to?(method) } if @outbox.nil?
           @outbox
         end
 
+        # Stores pending outbox rows, skipping any whose `delivery_id` is already held.
+        #
+        # Call only after `outbox?` answers true; the other three outbox methods share that
+        # precondition.
+        #
+        # @param rows [Array<Runtime::Outbox::Row>] the rows to enqueue, one per event and consumer
+        # @return [Array<Runtime::Outbox::Row>] the rows actually stored, with `id` assigned;
+        #   duplicates are dropped
         def outbox_enqueue(rows) = @adapter.outbox_enqueue(rows)
+
+        # Moves one pending outbox row to `claimed` and counts the attempt.
+        #
+        # @param id [Integer] the row id assigned by `outbox_enqueue`
+        # @return [Boolean] true when this call claimed the row; false when it is missing or
+        #   no longer pending
         def outbox_claim(id) = @adapter.outbox_claim(id)
+
+        # Records the final status of a claimed outbox row.
+        #
+        # @param id [Integer] the row id assigned by `outbox_enqueue`
+        # @param status [String, Symbol] the settled status; `Runtime::Outbox` passes
+        #   `"delivered"` or `"failed"`
+        # @param error [String, nil] failure text, `"ErrorClass: message"`; nil on success
+        # @return [Boolean] true when a row with that id was updated
         def outbox_settle(id, status:, error: nil) = @adapter.outbox_settle(id, status: status, error: error)
+
+        # Lists this aggregate's outbox rows, oldest first.
+        #
+        # @param status [String, Symbol, nil] keep only rows with this status; nil for all rows
+        # @return [Array<Runtime::Outbox::Row>] copies of the stored rows; `[]` when none match
         def outbox_rows(status: nil) = @adapter.outbox_rows(status: status)
 
+        # Answers a read model from the adapter's own projected tables, when it can.
+        #
+        # @param domain [String, Symbol] name of the domain declaring the read model
+        # @param model [Bluebook::ReadModel] the read model to answer
+        # @param args [Hash{Symbol => Object}] the read model's arguments, including its
+        #   reference argument
+        # @param bluebook [Bluebook::Chapter, nil] the domain's bluebook, which the SQLite
+        #   projection needs to find the included aggregates
+        # @return [Array<Hash>, nil] a one-element Array holding the report Hash keyed by head
+        #   name; nil when the adapter has no `query_read_model`
+        # @raise [ArgumentError] if the adapter answers natively and `bluebook` is nil
+        # @raise [Runtime::NotFound] if the referenced root record is not in the projection
         def query_read_model(domain, model, args, bluebook = nil)
           return unless @adapter.respond_to?(:query_read_model)
 

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

@@ -10,6 +10,18 @@ module Hecks
       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.
+        #
+        # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
+        # @param domain [String, Symbol] name of the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
+        # @return [Bluebook::Bind] the authoritative `persisted_by` bind, or the default
+        #   `Memory` bind when the domain declares no hecksagon
+        # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
+        #   aggregate, more or fewer than one bind without a role, or any bind with a role
         def resolve(registry, domain, aggregate)
           hexagon = registry.hecksagon(domain)
           return default_binding(aggregate) unless hexagon
@@ -24,10 +36,19 @@ module Hecks
           authoritative.first
         end
 
+        # Builds the bind an aggregate gets when its domain declares no hecksagon.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to bind
+        # @return [Bluebook::Bind] a roleless `persisted_by` bind to `DEFAULT_ADAPTER`
         def default_binding(aggregate)
           Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: DEFAULT_ADAPTER)
         end
 
+        # Builds, without raising, the error for an aggregate a hecksagon leaves unbound.
+        #
+        # @param domain [String, Symbol] name of the domain, used in the message
+        # @param aggregate [Bluebook::Aggregate] the aggregate with no bind
+        # @return [Runtime::WiringError] an error whose message says how to bind the aggregate
         def missing_binding(domain, aggregate)
           Runtime::WiringError.new(
             "#{domain}::#{aggregate.hecks_name} has no #{VERB} bind. #{domain} declares a " \
@@ -37,6 +58,13 @@ module Hecks
           )
         end
 
+        # Builds, without raising, the error for an aggregate whose count of roleless binds
+        # is not one.
+        #
+        # @param domain [String, Symbol] name of the domain, used in the message
+        # @param aggregate [Bluebook::Aggregate] the aggregate with the wrong bind count
+        # @param authoritative [Array<Bluebook::Bind>] the roleless binds found; may be empty
+        # @return [Runtime::WiringError] an error whose message reports the count
         def ambiguous_binding(domain, aggregate, authoritative)
           Runtime::WiringError.new(
             "#{domain}::#{aggregate.hecks_name} has #{authoritative.size} authoritative #{VERB} bindings. " \
@@ -44,6 +72,12 @@ module Hecks
           )
         end
 
+        # Builds, without raising, the error for binds that carry a role this port ignores.
+        #
+        # @param domain [String, Symbol] name of the domain, used in the message
+        # @param aggregate [Bluebook::Aggregate] the aggregate carrying the binds
+        # @param bindings [Array<Bluebook::Bind>] the binds that declare a role
+        # @return [Runtime::WiringError] an error whose message lists each role
         def unsupported_roles(domain, aggregate, bindings)
           Runtime::WiringError.new(
             "#{domain}::#{aggregate.hecks_name} uses persistence role#{'s' unless bindings.size == 1} " \

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

@@ -0,0 +1,178 @@
+require_relative "state_codec"
+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.
+      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.
+        #
+        # @param adapter [Object] a driven persistence adapter instance
+        # @return [Object] the same adapter object, now including `Guarded`
+        def guard!(adapter)
+          adapter.extend(wrapper_for(adapter.class)) unless adapter.singleton_class.include?(Guarded)
+          adapter
+        end
+
+        # Reports whether the current thread is executing inside a guarded adapter call.
+        #
+        # @return [Boolean] true between entering a guarded adapter method and yielding to the
+        #   caller's block or returning
+        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
+        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
+        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.
+        #
+        # @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)
+          return unless active?
+          return if StateCodec.decoded?(aggregate, state)
+
+          raise Runtime::WiringError,
+                "a persistence adapter built a #{aggregate.name} record from undecoded state " \
+                "(#{state.keys.inspect}) — decode stored state through " \
+                "Hecks::Ports::Persistence::StateCodec.decode before handing it to Runtime::Instance"
+        end
+
+        # Refuses a guarded adapter's `entries` answer if any entry's state is undecoded.
+        #
+        # @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
+        # @return [Array<Persistence::Entry>, Object] `entries` itself
+        # @raise [Runtime::WiringError] if an `Entry` in the Array carries state
+        #   `StateCodec.decoded?` rejects
+        def check_entries!(adapter, entries)
+          return entries unless entries.is_a?(Array)
+
+          entries.each do |entry|
+            next unless entry.is_a?(Entry) && !StateCodec.decoded?(adapter.aggregate, entry.state)
+
+            raise Runtime::WiringError,
+                  "#{adapter.class} answered a #{adapter.aggregate.name} journal entry #{entry.id.inspect} with " \
+                  "undecoded state — decode it through Hecks::Ports::Persistence::StateCodec.decode"
+          end
+          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
+        def with_flag(value)
+          previous = Thread.current[KEY]
+          Thread.current[KEY] = value
+          yield
+        ensure
+          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.
+        module Guarded; end
+
+        # Filled lazily under `WRAPPERS_LOCK`, one entry per adapter class —
+        # a cache, 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.
+        #
+        # @param klass [Class] the adapter's class
+        # @return [Module] an anonymous module including `Guarded`, meant to be `extend`ed onto
+        #   instances of `klass`
+        def wrapper_for(klass)
+          WRAPPERS_LOCK.synchronize do
+            WRAPPERS[klass] ||= Module.new do
+              include Guarded
+
+              (klass.public_instance_methods - Object.public_instance_methods).each do |name|
+                define_method(name) do |*args, **kwargs, &block|
+                  result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
+                  name == :entries ? CodecBoundary.check_entries!(self, result) : result
+                end
+              end
+            end
+          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
+        def outside_block(block)
+          return nil unless block
+
+          proc { |*yielded, **yielded_kwargs, &inner| outside { block.call(*yielded, **yielded_kwargs, &inner) } }
+        end
+      end
+    end
+  end
+end

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

@@ -10,6 +10,10 @@ module Hecks
         # `Runtime::StaleWrite` (runtime/errors.rb) and `AppendOnly#save`.
         STATUSES = %i[inserted replaced updated conflicted missing saved stale].freeze
 
+        # @param status [Symbol, String] one of `STATUSES`; stored as a Symbol
+        # @param instance [Runtime::Instance, Object, nil] the record the write concerned, as
+        #   the repository reports it; nil when there is none
+        # @raise [ArgumentError] if `status` is not one of `STATUSES`
         def initialize(status:, instance: nil)
           normalized = status.to_sym
           raise ArgumentError, "unknown persistence outcome #{status.inspect}" unless STATUSES.include?(normalized)