hecks 1.3.0 → 1.4.0

data/lib/hecks/adapters/driven/memory.rb

@@ -13,17 +13,30 @@ module Hecks
     # instance really is a fresh store, with nothing shared across tests or
     # tenants.
     class Memory
-      # TENANT-CAPABLE TRIVIALLY — see Runtime::TenantCheck's own header
+      # Reports that two tenant boots of this adapter never share state.
+      #
+      # **Tenant-capable trivially** — see `Runtime::TenantCheck`'s own header
       # for the full reasoning. `@records` is a plain instance variable;
       # two `Runtime.boot` calls build two entirely separate Registry
       # objects and, through them, two entirely separate Memory
       # instances, so two tenant boots never share this adapter's state
       # by construction — nothing here needs to know "tenant" exists.
+      #
+      # @return [Boolean] always true
       def self.tenant_capable? = true
+
+      # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      #
+      # @return [Array<Symbol>] `[:atomic_put]`
       def persistence_capabilities = [:atomic_put]
 
       attr_reader :aggregate, :events
 
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records this store holds
+      # @param settings [Hash] world settings for the binding; accepted for the shared adapter
+      #   constructor shape and ignored
+      # @param root [String, nil] project root directory; accepted for the shared adapter
+      #   constructor shape and ignored
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @records   = {}
@@ -32,39 +45,90 @@ module Hecks
         @outbox    = []
       end
 
+      # Looks up the current record for one aggregate identity.
+      #
+      # @param id [String, Object] the aggregate identity, compared as `id.to_s`
+      # @return [Runtime::Instance, nil] the held record, or nil when no record has that id
       def find(id) = @records[id.to_s]
+
+      # Counts the records currently held, deleted ones excluded.
+      #
+      # @return [Integer] number of live records
       def count    = @records.size
 
+      # Lists every held record, in insertion order unless an ordering attribute is given.
+      #
+      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+      #   by; nil leaves the records in insertion order
+      # @param direction [Symbol, String] `:asc` or `:desc`
+      # @return [Array<Runtime::Instance>] the held records, `[]` when the store is empty
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
       def all(order_by: nil, direction: :asc)
         InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
       end
 
+      # Answers a declared query by filtering, ordering and paging the held records in Ruby.
+      #
+      # @param specification [QuerySpecification::Common::Options] the declared query
+      # @param args [Hash{Symbol => Object}] values for the specification's symbolic operands
+      # @param context [Hash] execution context; only `:registry` (a `Runtime::Registry` or
+      #   nil) is read, for comparators that look up another aggregate
+      # @return [Array<Runtime::Instance>] the matching records, `[]` when none match
+      # @raise [Runtime::WiringError] if a where clause uses an operation no comparator handles
       def query(specification, args = {}, context: {})
         Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
       end
 
+      # Records one journal entry, holding a codec copy of its state.
+      #
+      # Through the state codec, like every durable adapter (PR A3): the
+      # journal holds `StateCodec.copy` — exactly what an encode-to-JSON
+      # then decode would hand back — never the caller's own live state
+      # objects, so an entry read back here has the same deep-symbol,
+      # plain-Hash shape a Heki/Sqlite/Postgres entry has.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to journal
+      # @return [Ports::Persistence::Entry] the caller's own `entry`, not the journalled copy
       def append(entry)
-        @entries << entry
+        copied = Ports::Persistence::Entry.new(operation: entry.operation, id: entry.id,
+                                               state: copy(entry.state), mirrors: entry.mirrors)
+        @entries << copied
         entry
       end
 
+      # Applies one journal entry to the current-state Hash.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+      # @return [Runtime::Instance, nil] the new record for a save; for a delete, the record
+      #   removed, or nil when none was held
       def project(entry)
         if entry.save?
-          @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state.dup)
+          @records[entry.id] = build_instance(entry)
         else
           @records.delete(entry.id)
         end
       end
 
+      # Journals and materializes an instance's current state in one call.
+      #
+      # @param instance [Runtime::Instance] the instance to store
+      # @return [Runtime::Instance] the stored record, a fresh instance over a copy of the state
       def save(instance)
-        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: copy(instance.state))
         append(entry)
         project(entry)
       end
 
+      # Stores an entry and reports whether it inserted, replaced or conflicted.
+      #
       # One in-memory critical section in the only thread touching this plain
       # Hash: classify and replace without a preliminary repository lookup.
       # Durable append and projection remain ordered exactly as ordinary save.
+      #
+      # @param entry [Ports::Persistence::Entry] the save to store
+      # @param insert_only [Boolean] when true, an existing record is left untouched
+      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+      #   existing record and nothing was written
       def atomic_put(entry, insert_only: false)
         exists = @records.key?(entry.id.to_s)
         return :conflicted if insert_only && exists
@@ -75,29 +139,44 @@ module Hecks
         status
       end
 
+      # Journals a delete and removes the record, whether or not one is held.
+      #
+      # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+      # @return [Runtime::Instance, nil] the record removed, or nil when none was held
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
         project(entry)
       end
 
+      # Appends an emitted event to the in-process event log.
+      #
+      # @param event [Runtime::Event] the emitted event
+      # @return [Array<Runtime::Event>] the live event log, including `event`
       def record_event(event) = @events << event
 
+      # Lists the journal in append order, for `AppendOnly#recover!` to replay.
+      #
+      # @return [Array<Ports::Persistence::Entry>] a copy of the journal, `[]` when nothing
+      #   has been appended
       def entries = @entries.dup
 
+      # Empties the records, journal, event log and outbox, keeping the adapter itself.
+      #
       # Every other driven adapter (Postgres/PostgresEra/Sqlite/D1)
-      # already implements this — `Ports::Persistence::AppendOnly#reset!`
+      # implements this too — `Ports::Persistence::AppendOnly#reset!`
       # forwards to it and only raises when the wrapped adapter doesn't
-      # respond to `reset!` at all, which was always this adapter's own
-      # gap, not a deliberate omission (nothing about "in memory" implies
-      # "cannot be cleared"). Existing callers that fully re-`Hecks.boot`
+      # respond to `reset!` at all, and nothing about "in memory" implies
+      # "cannot be cleared". Existing callers that fully re-`Hecks.boot`
       # a domain per test case don't need this — they get a brand new
       # `Memory` instance, with brand new empty `@records`/`@events`/
       # `@entries`, for free. This is for the other case: a caller that
-      # deliberately keeps ONE booted runtime across many cases (to skip
+      # deliberately keeps one booted runtime across many cases (to skip
       # `load_domain`'s own per-boot parse/verify cost) and wants each
       # case to start from the same clean slate `Hecks.boot` would have
       # given it, without paying for a fresh boot to get there.
+      #
+      # @return [Adapters::Memory] self, now empty
       def reset!
         @records = {}
         @events  = []
@@ -106,13 +185,24 @@ module Hecks
         self
       end
 
+      # Runs the block directly, as the save + emit + outbox boundary other adapters commit.
+      #
       # No rollback here — a Hash has no transaction to join. Memory
       # implements `transaction` so `Interpreting#run_dispatch_order` has
       # one shape to call, and the outbox so a spec can watch rows move
       # pending → claimed → delivered without a database (the same
       # reason Memory records `events`). See `Runtime::Outbox`.
+      #
+      # @yield the writes to run together; an exception raised inside undoes nothing
+      # @return [Object] the block's own result
       def transaction = yield
 
+      # Holds new outbox rows, skipping any whose `delivery_id` is already held.
+      #
+      # @param rows [Array<Runtime::Outbox::Row>] pending rows to enqueue; each accepted row
+      #   has its `id` assigned in place
+      # @return [Array<Runtime::Outbox::Row>] the rows actually enqueued, `[]` when every one
+      #   was a duplicate
       def outbox_enqueue(rows)
         rows.filter_map do |row|
           next nil if @outbox.any? { |held| held.delivery_id == row.delivery_id }
@@ -123,6 +213,11 @@ module Hecks
         end
       end
 
+      # Marks a pending outbox row claimed and counts the delivery attempt.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @return [Boolean] true when the row was pending and is now claimed; false when it is
+      #   unknown or no longer pending
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
         row = @outbox.find { |held| held.id == id }
         return false unless row&.pending?
@@ -132,6 +227,13 @@ module Hecks
         true
       end
 
+      # Records a delivery outcome on an outbox row, whatever status it held.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @param status [String, Symbol] the new status, one of `Runtime::Outbox::STATUSES`;
+      #   not validated here
+      # @param error [String, nil] the failure description, or nil to clear it
+      # @return [Boolean] true when the row exists and was updated; false when no row has `id`
       def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
         row = @outbox.find { |held| held.id == id } or return false
         row.status = status.to_s
@@ -139,10 +241,104 @@ module Hecks
         true
       end
 
+      # Lists outbox rows in enqueue order, as copies a caller may mutate freely.
+      #
+      # @param status [String, Symbol, nil] only rows with this status; nil lists every row
+      # @return [Array<Runtime::Outbox::Row>] shallow copies of the matching rows, `[]` when
+      #   none match
       def outbox_rows(status: nil)
         rows = status ? @outbox.select { |row| row.status == status.to_s } : @outbox
         rows.map(&:dup)
       end
+
+      private
+
+      # THE LANGUAGE'S OWN BOOTSTRAP SAVES ITS SELF-DESCRIPTION QUADRATICALLY
+      # OTHERWISE. `MetaValidator::Judge` dispatches every declaration in the
+      # self-hosted grammar into a fresh, private, never-durable `Memory`
+      # store (meta_validator.rb's own header: "each bluebook is judged in a
+      # fresh in-memory store") — and every nested-entity dispatch (a
+      # `ValueObject::Member`, then one `ValueObject::Member::Pair` per
+      # key/value pair) re-saves the WHOLE parent aggregate, because entities
+      # have no storage of their own (S17, ADR 0026). A table of N member
+      # rows costs O(N) dispatches, each PAYING TWICE for the aggregate's own
+      # size-N state: once in `StateCodec.copy` (`append`/`project`'s own
+      # encode-then-decode round trip) and again in `Instance#initialize`'s
+      # `hydrate_with_defaults`, which re-walks and re-validates every
+      # element of an entity list on EVERY save regardless of how many of
+      # them were already valid as of the previous one
+      # (`Value::EntityListCoercion#hydrate_entity_list` has no "already
+      # hydrated" shortcut for entity elements — only a value-object list
+      # element gets one). Both are O(N) per save, so a table of N rows
+      # costs O(N^2) total — and it is paid by every rspec worker and every
+      # `bin/*` subprocess that boots the language at all (found live: PR
+      # #738's 128-row `RefusalSiteArgument` table alone tripled this one
+      # aggregate's own save time, 6.7s -> 18.2s).
+      #
+      # `Runtime::Value.judge_bootstrapping?` (judge.rb's own `send_to`,
+      # wrapping every dispatch the judge makes) is already the flag that
+      # marks exactly this window and NOTHING else — "never for a REAL
+      # domain's own declared value objects... which Judge never dispatches
+      # commands against" (coercion.rb's own comment on the same flag). It
+      # is reused here rather than a new toggle for the same reason: one
+      # flag, one meaning, checked by two unrelated callers for two
+      # unrelated purposes (loosening a scalar-shape check there, skipping
+      # both round trips here) is simpler to reason about than two flags
+      # that would always be true or false together.
+      #
+      # WHY SKIPPING BOTH IS SAFE HERE, AND ONLY HERE: `entry.state` a save
+      # ever hands this adapter is always `instance.state.dup`
+      # (`AppendOnly#save`) — a shallow copy of an ALREADY-hydrated,
+      # ALREADY-validated live `Instance`'s own state, built by the very
+      # same `Value.for_attribute`/`hydrate_with_defaults` machinery
+      # `StateCodec.copy` and `Instance.new`'s default (`hydrate: true`)
+      # path would otherwise redo. Every VALUE inside it — a `Runtime::
+      # Value` (frozen through, see value.rb's own header) or a `list_of`
+      # attribute's own array (`Freezer.deep`d the moment it was built,
+      # instance.rb's own header on `Instance#dup`) — is already immutable,
+      # so a bare top-level `.dup` is exactly as safe as `Instance#dup`
+      # already trusts it to be everywhere else in this codebase; nothing
+      # below the top level is ever mutated in place. Re-deriving the same
+      # answer through the codec and through re-hydration is therefore
+      # pure, avoidable cost for this one caller — never a correctness
+      # requirement.
+      #
+      # `bootstrap_fast_path?` is the guard, and it is deliberately CHEAP —
+      # O(this aggregate's own declared attribute count), never O(N) — so
+      # it cannot reintroduce the very cost it exists to avoid: `StateCodec.
+      # decoded?` (the obvious-looking alternative) recurses into every
+      # `list_of` element to check IT, which is exactly the O(N) walk this
+      # whole change removes. A `Hash` with every top-level key already a
+      # `Symbol` is what `Instance#state` ALWAYS looks like (`Value.hydrate`
+      # refuses anything else, coercion.rb's own header), so it is checked
+      # here instead — true for the actual shape every real save has,
+      # false (falling back to the always-correct slow path) for anything
+      # that somehow doesn't.
+      #
+      # Verified empirically before landing, not just argued: instrumenting
+      # every bootstrapping-time save across a full `grammar_registry` boot
+      # and comparing this fast path's own state, journal entry, and stored
+      # `Instance` against the unmodified `StateCodec.copy` + `Instance.new
+      # (hydrate: true)` pipeline's found them equal (`==`) for every one of
+      # 6,617 saves, zero mismatches.
+      def bootstrap_fast_path?(state)
+        Runtime::Value.judge_bootstrapping? && state.is_a?(Hash) && state.keys.all?(Symbol)
+      end
+
+      def copy(state)
+        return state.dup if bootstrap_fast_path?(state)
+
+        Ports::Persistence::StateCodec.copy(@aggregate, state)
+      end
+
+      def build_instance(entry)
+        if bootstrap_fast_path?(entry.state)
+          Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state.dup, hydrate: false)
+        else
+          decoded = Ports::Persistence::StateCodec.copy(@aggregate, entry.state)
+          Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: decoded)
+        end
+      end
     end
   end
 end

data/lib/hecks/adapters/driven/mock_stripe_adapter.rb

@@ -2,7 +2,7 @@
 
 module Hecks
   module Adapters
-    # A GENERIC STAND-IN for a real Checkout-Session-style adapter — no
+    # A generic stand-in for a real Checkout-Session-style adapter — no
     # network call, no real account, matching whatever real payment
     # adapter a project pairs it with by shape alone
     # (`create_session(event:, registration_id:, success_url:, cancel_url:)

data/lib/hecks/adapters/driven/postgres/codec.rb

@@ -5,12 +5,12 @@ module Hecks
     class Postgres
       # How a state crosses the column boundary: which fields persist, and
       # how each one encodes into (and decodes out of) its column. Same
-      # SHAPE as Sqlite::Codec (one column per attribute, JSON for
+      # shape as Sqlite::Codec (one column per attribute, JSON for
       # nested/list) — not its mechanics. Sqlite's own columns carry no
       # type affinity worth trusting on the way back out (SQLite gives it
       # back typed anyway via the driver), but `pg` hands every column
-      # back as TEXT unless a type map says otherwise, so a real `bigint`/
-      # `double precision` column needs its OWN coercion on decode that
+      # back as text unless a type map says otherwise, so a real `bigint`/
+      # `double precision` column needs its own coercion on decode that
       # Sqlite never had to write.
       module Codec
         private
@@ -23,7 +23,7 @@ module Hecks
           fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && fields.none? do |field|
             field[:name] == lifecycle.field
           end
-          # `projects` FIELDS (S12, ADR 0025) ARE A LOCAL COLUMN TOO — see
+          # `projects` fields (S12, ADR 0025) are a local column too — see
           # Sqlite::Codec#persisted_fields' own comment; identical reasoning,
           # `text` to match this file's own lowercase SQL type spelling.
           @aggregate.projected_fields.each do |field|
@@ -35,12 +35,12 @@ module Hecks
         end
 
         def encode(attr, value)
-          # NEVER SET IS NOT EMPTY — same reasoning as Sqlite::Codec's own
+          # **Never set is not empty** — same reasoning as Sqlite::Codec's own
           # comment: a list attribute nothing has ever appended to has to
           # stay NULL to answer the same as Memory does, not become `[]`
           # invented by this adapter's own storage.
-          return (value.nil? ? nil : JSON.generate(value)) if attr.list?
-          return JSON.generate(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
+          return (value.nil? ? nil : state_json(value)) if attr.list?
+          return state_json(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
 
           value
         end
@@ -51,21 +51,37 @@ module Hecks
           encode(field[:attribute], value)
         end
 
+        # Every jsonb column's text goes through the state codec's `encode`
+        # (PR A3) — see Sqlite::Codec#state_json.
+        def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
+
+        # Columns reassembled, then decoded once through the state codec
+        # (PR A3) — see Sqlite::Codec#decode, including why a NULL
+        # projected-only column reads back absent.
         def decode(row)
-          persisted_fields.each_with_object({}) do |field, state|
+          state = persisted_fields.each_with_object({}) do |field, raw_state|
             attr = field[:attribute]
             unless attr
-              state[field[:name]] = row[field[:name].to_s]
+              value = row[field[:name].to_s]
+              next if value.nil? && projected_only?(field)
+
+              raw_state[field[:name]] = value
               next
             end
             raw = row[attr.name.to_s]
-            state[attr.name] =
+            raw_state[attr.name] =
               if attr.list? || value_object?(attr)
-                raw ? JSON.parse(raw, symbolize_names: true) : nil
+                raw ? JSON.parse(raw) : nil
               else
                 coerce_scalar(attr, raw)
               end
           end
+          Ports::Persistence::StateCodec.decode(@aggregate, state)
+        end
+
+        def projected_only?(field)
+          @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
+            @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
 
         # `pg` returns every column as a Ruby String by default (no type

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -3,7 +3,7 @@ require_relative "../../../runtime/outbox"
 
 module Hecks
   module Adapters
-    # THE OUTBOX, POSTGRES-SHAPED — shared verbatim by `Postgres` and the
+    # **The outbox, Postgres-shaped** — shared verbatim by `Postgres` and the
     # era plugin's `PostgresEra`, the same way their `events` and
     # `hecks_saga_instances` DDL is copied between them: nothing here is
     # lineage-specific. Needs `@db` (a `PG::Connection`) and `table`
@@ -12,10 +12,19 @@ module Hecks
     # for the SQL idioms (`ON CONFLICT DO NOTHING` = idempotent enqueue,
     # `WHERE status = 'pending'` = the compare-and-set claim).
     module PostgresOutbox
-      # RE-ENTRANT — `Interpreting#run_dispatch_order` opens one
+      # Runs the block inside one Postgres transaction, joining an already-open one.
+      #
+      # **Re-entrant** — `Interpreting#run_dispatch_order` opens one
       # transaction around save+emit+outbox and the adapter's own
       # `append`/`atomic_put`/`delete` each open theirs; PG refuses
       # BEGIN inside BEGIN, so an inner call joins the open one.
+      #
+      # @yield the writes to commit together; an exception raised inside rolls the
+      #   outermost transaction back
+      # @return [Object] the block's own result
+      # @raise [PG::ConnectionBad] if the connection died; a reconnect is attempted for the
+      #   next caller before it is re-raised
+      # @raise [PG::Error] if a statement inside the block fails
       def transaction(&)
         return yield unless @db.transaction_status == PG::PQTRANS_IDLE
 
@@ -25,6 +34,13 @@ module Hecks
         raise
       end
 
+      # Inserts new outbox rows as pending, skipping any whose `delivery_id` already exists.
+      #
+      # @param rows [Array<Runtime::Outbox::Row>] rows to enqueue; each accepted row has its
+      #   `id` and `status` assigned in place. `row.aggregate` is stored as given
+      # @return [Array<Runtime::Outbox::Row>] the rows actually inserted, `[]` when every one
+      #   was a duplicate
+      # @raise [PG::Error] if an insert fails
       def outbox_enqueue(rows)
         rows.filter_map do |row|
           result = pg_exec_params(
@@ -40,6 +56,12 @@ module Hecks
         end
       end
 
+      # Claims a pending outbox row with a compare-and-set update, counting the attempt.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @return [Boolean] true when the row was pending and is now claimed; false when it is
+      #   unknown or another claimer got there first
+      # @raise [PG::Error] if the update fails
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
         pg_exec_params(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
@@ -48,6 +70,15 @@ module Hecks
         ).cmd_tuples == 1
       end
 
+      # Records a delivery outcome and its settle time on an outbox row, whatever status it
+      # held.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @param status [String, Symbol] the new status, one of `Runtime::Outbox::STATUSES`;
+      #   not validated here
+      # @param error [String, nil] the failure description, or nil to store NULL
+      # @return [Boolean] true when exactly one row was updated; false when no row has `id`
+      # @raise [PG::Error] if the update fails
       def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
         pg_exec_params(
           "UPDATE hecks_outbox SET status = $2, error = $3, settled_at = now() WHERE id = $1",
@@ -55,6 +86,13 @@ module Hecks
         ).cmd_tuples == 1
       end
 
+      # Lists the outbox rows whose `aggregate` column equals this adapter's `table`, in
+      # enqueue order.
+      #
+      # @param status [String, Symbol, nil] only rows with this status; nil lists every row
+      # @return [Array<Runtime::Outbox::Row>] the matching rows, `event` parsed with Symbol
+      #   keys; `[]` when none match
+      # @raise [PG::Error] if the statement fails
       def outbox_rows(status: nil)
         sql   = "SELECT * FROM hecks_outbox WHERE aggregate = $1"
         binds = [table]

data/lib/hecks/adapters/driven/postgres/reconnect.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Adapters
-    # SELF-HEALING CONNECTION — shared verbatim by `Postgres` and the era
+    # **Self-healing connection** — shared verbatim by `Postgres` and the era
     # plugin's `PostgresEra`, the same way `PostgresOutbox` (outbox.rb) is:
     # nothing here is lineage-specific, and `PostgresOutbox`'s own
     # `@db.exec*` calls route through this module's `pg_exec`/
@@ -12,18 +12,25 @@ module Hecks
     # A backend killed out from under an adapter (a DBA's own
     # `pg_terminate_backend`, a load balancer's failover, a restart) —
     # chaos-tested against the plain `Postgres` adapter: `PG::ConnectionBad`
-    # on the query that hit it, and PERMANENTLY on every query after,
+    # on the query that hit it, and permanently on every query after,
     # since nothing ever replaced `@db` with a live connection.
     # `pg_exec`/`pg_exec_params` are the two primitives every other method
     # in either class funnels through — wrapping them here, once,
-    # self-heals `@db` for the NEXT caller. THE CURRENT CALL STILL
-    # RAISES — reconnecting cannot tell a caller whether ITS OWN write
+    # self-heals `@db` for the next caller. The current call still
+    # raises — reconnecting cannot tell a caller whether its own write
     # reached the server before the connection died, so silently
     # retrying it here could silently double it; that ambiguity is
     # exactly why `Runtime::SagaInterpreter`'s own defect-retry exists
-    # ONE LAYER UP, where a dispatch is retried as a whole (fresh
+    # one layer up, where a dispatch is retried as a whole (fresh
     # hydrate, fresh `given`s), not as a lone SQL statement.
     module PostgresReconnect
+      # Runs one parameterless statement, replacing a dead connection before re-raising.
+      #
+      # @param sql [String] the statement to run
+      # @return [PG::Result] the statement's result
+      # @raise [PG::ConnectionBad] if the connection died; `@db` is reconnected for the next
+      #   caller, and this call is never retried
+      # @raise [PG::Error] if the server rejects the statement
       def pg_exec(sql)
         @db.exec(sql)
       rescue PG::ConnectionBad
@@ -31,6 +38,15 @@ module Hecks
         raise
       end
 
+      # Runs one statement with bind parameters, replacing a dead connection before
+      # re-raising.
+      #
+      # @param sql [String] the statement, with `$1`-style placeholders
+      # @param binds [Array<Object>] one value per placeholder, in order; nil binds NULL
+      # @return [PG::Result] the statement's result
+      # @raise [PG::ConnectionBad] if the connection died; `@db` is reconnected for the next
+      #   caller, and this call is never retried
+      # @raise [PG::Error] if the server rejects the statement
       def pg_exec_params(sql, binds)
         @db.exec_params(sql, binds)
       rescue PG::ConnectionBad
@@ -40,11 +56,11 @@ module Hecks
 
       private
 
-      # BEST-EFFORT — a reconnect attempt that itself fails (the server
+      # **Best-effort** — a reconnect attempt that itself fails (the server
       # is actually down, not just this one backend) leaves `@db`
       # unchanged; the `PG::ConnectionBad` already being re-raised by
       # `pg_exec`/`pg_exec_params` above still reaches the caller either
-      # way, so swallowing a failed RECONNECT attempt here loses no
+      # way, so swallowing a failed reconnect attempt here loses no
       # information — it only avoids masking the original error with a
       # second one.
       def reconnect!