hecks 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b85a8382bb201f9ab54417b3535d8fe1ede57c842f627e32a2ff75d7f2dd6618
-  data.tar.gz: e4852fd6b22145bec8a215e4c46fc6347527f7bd05811ff7da780e74dc24fe1d
+  metadata.gz: 830e92d9660dc86cc7de1af49d85fd7ce5ab611e07341dd11f4633274b920fda
+  data.tar.gz: 1c70b3c2994fd520a604ebd8c8cc8a53e7531e3cb5ba1dd59c6fd751b9b9dd99
 SHA512:
-  metadata.gz: a538ddbe90fed2ccfa8c066f00777699b0eadade3c6523e6fbf5f62c19385ab7ace8e2c8de6fabafffce46abbefd36642401f6e5f23696127445378e95d98aad
-  data.tar.gz: e22574943d4246998ba9121c0c84d7b39ec944416066ad881f144f166a09deb5c1a1fbb8b6c8378084b89856ed9a4e5bfd9c66a3cd6d07fa9a9a21eee77d63fc
+  metadata.gz: 3aeb0240903bed58fbd5684c23ee2069e9b3021aef07082d11e26ffa5052cebccf42d78e3aff243ba192183460056113e0510c7667306d1ed2cde3048ad118c0
+  data.tar.gz: e104c2252f0dbbb1ba5ea97a0f6f56f890cab76e12ff86f246605003738228b94062e317f16db1ebfb376753536d8309cedff86e00275781497232de67b17e1e

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

@@ -6,16 +6,16 @@ require_relative "../../ports/agent"
 
 module Hecks
   module Adapters
-    # THE REAL `agent` FULFILLMENT — shells out to the `claude` CLI
+    # **The real `agent` fulfillment** — shells out to the `claude` CLI
     # itself, `claude -p --output-format json`, one process per call.
     # `Ports::Agent`'s own scripted double (`spec/fixtures/scripted_
     # agent.{adapter,rb}`) is the deterministic sibling every spec binds
     # instead, the same relationship `SecureRandomIdentity` already has
     # to `SequentialIdentity`.
     #
-    # THIS FILE OWNS TRANSPORT ONLY — spawning the process, unwrapping
+    # **This file owns transport only** — spawning the process, unwrapping
     # the CLI's own JSON envelope (`{"result": "..."}`) down to the
-    # model's raw text, and parsing THAT text as JSON. It hands back a
+    # model's raw text, and parsing that text as JSON. It hands back a
     # plain Hash. Whether that Hash has the keys a caller asked for, and
     # whether its values are within the closed vocabularies this port
     # recognizes (a critique's `kind`, a proposal's `verb` pattern) is
@@ -40,10 +40,22 @@ module Hecks
 
       module_function
 
-      # THE NEXT BEST QUESTION. `state` is whatever
+      # Asks the model for the next best interview question, as a raw parsed-JSON reply.
+      #
+      # **The next best question**. `state` is whatever
       # `Interview::Session#declaration`/`#gaps` produced — passed
       # through as JSON, not reformatted, so this adapter never
       # re-derives what the session already knows.
+      #
+      # @param state [Hash] the interview's whole current picture (declaration plus gaps),
+      #   JSON-able
+      # @param asked [Array<Object>] JSON-able record of the questions already asked
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"questions"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.questions`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def ask(state:, asked:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far, ask the single best next " \
@@ -53,7 +65,18 @@ module Hecks
         )
       end
 
-      # PROSE -> PROPOSED DECLARATIONS.
+      # Turns a human's sentence into proposed declarations, as a raw parsed-JSON reply.
+      #
+      # Prose -> proposed declarations.
+      #
+      # @param prose [String] a human's plain-English sentence
+      # @param state [Hash] the interview's whole current picture, JSON-able
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"proposals"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.proposals`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def interpret(prose:, state:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
@@ -66,10 +89,22 @@ module Hecks
         )
       end
 
-      # WHAT IS WRONG WITH THIS AS A MODEL — closed to the same kind
+      # Asks the model to judge a declared model on taste, as a raw parsed-JSON reply.
+      #
+      # What is wrong with this as a model — closed to the same kind
       # vocabulary `Ports::Agent::CRITIQUE_KINDS` declares, spelled out
       # here too since the system prompt is the only place the model
       # itself ever sees that list.
+      #
+      # @param declared [Hash] the chapter as declared so far, JSON-able
+      # @param refusals [Array<Object>] JSON-able refusals the language itself already raised
+      # @param findings [Array<Object>] JSON-able mechanical findings already found
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"findings"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.findings`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def critique(declared:, refusals:, findings:)
         kinds = Ports::Agent::CRITIQUE_KINDS.join(", ")
         call(
@@ -82,9 +117,22 @@ module Hecks
         )
       end
 
-      # VOCABULARY HELP. Named `suggest_name`, not `name` — see
+      # Suggests a name for a construct, as a raw parsed-JSON reply.
+      #
+      # **Vocabulary help**. Named `suggest_name`, not `name` — see
       # `Ports::Agent#suggest_name`'s own comment for why `name` is
       # never a safe module-function name here.
+      #
+      # @param meaning [String] what the new name needs to mean
+      # @param kind [String] the kind of construct being named, such as `"event"`
+      # @param near [Array<String>] names already in use nearby, which a suggestion must not
+      #   collide with
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"names"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.suggestions`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def suggest_name(meaning:, kind:, near:)
         call(
           system:  SYSTEM_PREFIX + "Suggest a name for a #{kind} meaning \"#{meaning}\", distinct from " \
@@ -96,6 +144,16 @@ module Hecks
 
       # ── transport ───────────────────────────────────────────────────
 
+      # Runs `claude` as a subprocess with `payload` on stdin and returns its parsed JSON reply.
+      #
+      # @param system [String] the system-prompt text appended via `--append-system-prompt`
+      # @param payload [Hash] the JSON-able payload written to the subprocess's stdin
+      # @return [Object] the parsed JSON value nested under the CLI envelope's `"result"` key
+      #   (see `unwrap`)
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   exits non-zero, or the call does not finish within `TIMEOUT_SECONDS`
+      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"`, or the
+      #   result text is not valid JSON (see `unwrap`)
       def call(system:, payload:)
         stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
           Open3.capture2(
@@ -113,6 +171,13 @@ module Hecks
         raise Ports::Agent::Unavailable, "claude is not on PATH: #{e.message}"
       end
 
+      # Unwraps the CLI's own JSON envelope down to the model's parsed reply.
+      #
+      # @param stdout [String] the raw stdout of the `claude` CLI invocation, the outer
+      #   `{"result": "..."}` envelope
+      # @return [Object] the JSON value parsed out of the envelope's `"result"` string
+      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"` key, or
+      #   `result` is not valid JSON
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
         result = envelope["result"]

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

@@ -16,15 +16,15 @@ require_relative "../../runtime/instance"
 module Hecks
   module Adapters
     # Cloudflare D1 — SQLite, managed, reached over its REST API rather
-    # than a local file. D1 IS SQLite, dialect and all, so this file
-    # reuses Sqlite::SchemaBuilder and Sqlite::Codec UNCHANGED (the DDL
+    # than a local file. D1 is SQLite, dialect and all, so this file
+    # reuses Sqlite::SchemaBuilder and Sqlite::Codec unchanged (the DDL
     # and the column encode/decode) and SqlQueryBuilder's dialect hooks
     # are copied near-verbatim from sqlite.rb — the only real difference
     # is the transport (D1::Connection, an HTTP call per query, vs a
     # persistent local sqlite3 handle). See sqlite.rb's own header
     # comment: "this file supplies only SQLite's dialect" — true here too.
     class D1
-      # THE TRANSPORT — mirrors just the slice of SQLite3::Database's own
+      # **The transport** — mirrors just the slice of SQLite3::Database's own
       # interface (execute/get_first_row/get_first_value, rows as
       # column-name-keyed hashes) that Sqlite::SchemaBuilder, Sqlite::Codec,
       # and this file's own methods already assume. One stateless HTTP call
@@ -33,20 +33,41 @@ module Hecks
       class Connection
         ENDPOINT = "https://api.cloudflare.com/client/v4".freeze
 
+        # @param account_id [String] the Cloudflare account that owns the database
+        # @param database_id [String] the D1 database's id
+        # @param api_token [String] a Cloudflare API token, sent as a bearer token on every
+        #   request
         def initialize(account_id:, database_id:, api_token:)
           @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
           @api_token = api_token
         end
 
+        # Runs one statement in its own HTTP request and returns its rows.
+        #
+        # @param sql [String] the statement, with `?` placeholders
+        # @param binds [Array<Object>] one value per placeholder, in order
+        # @return [Array<Hash{String => Object}>] the result rows keyed by column name; `[]`
+        #   for a statement that returns none
+        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
+        #   that is not JSON
         def execute(sql, binds = [])
           response_results({ sql: sql, params: binds }).first.fetch("results", [])
         end
 
+        # Runs several statements as one transaction in a single HTTP request.
+        #
         # D1 batches are SQL transactions: statements execute in order and a
         # failure rolls the entire sequence back. Keep the tuple-shaped local
         # seam small so adapter code and focused fakes do not need to know the
         # REST request envelope.
         # https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
+        #
+        # @param statements [Array<Array(String, Array)>] `[sql, binds]` pairs in execution
+        #   order; nil binds mean none
+        # @return [Array<Array<Hash{String => Object}>>] each statement's result rows, in
+        #   the order given
+        # @raise [Runtime::WiringError] if D1 reports the request or any one statement failed,
+        #   or answers with a body that is not JSON
         def batch(statements)
           payload = {
             batch: statements.map do |sql, binds|
@@ -83,10 +104,10 @@ module Hecks
           raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
         end
 
-        # `messages` is the whole-response :errors fallback, tried LAST —
+        # `messages` is the whole-response :errors fallback, tried last —
         # a per-statement `failed["error"]`/`failed["message"]` (checked
         # by key presence, not truthiness, so an explicit `nil` still
-        # counts as "the key was there") is always more specific to WHICH
+        # counts as "the key was there") is always more specific to which
         # statement failed, when either is present.
         def failed_statement_detail(failed, messages)
           detail =
@@ -102,10 +123,26 @@ module Hecks
 
         public
 
+        # Runs one statement and keeps only its first row, as `SQLite3::Database` does.
+        #
+        # @param sql [String] the statement, with `?` placeholders
+        # @param binds [Array<Object>] one value per placeholder, in order
+        # @return [Hash{String => Object}, nil] the first row keyed by column name, or nil when
+        #   the statement returned none
+        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
+        #   that is not JSON
         def get_first_row(sql, binds = [])
           execute(sql, binds).first
         end
 
+        # Runs one statement and keeps only the first column of its first row.
+        #
+        # @param sql [String] the statement, with `?` placeholders
+        # @param binds [Array<Object>] one value per placeholder, in order
+        # @return [Object, nil] the value as D1's JSON carries it, or nil when the statement
+        #   returned no row
+        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
+        #   that is not JSON
         def get_first_value(sql, binds = [])
           get_first_row(sql, binds)&.values&.first
         end
@@ -119,8 +156,22 @@ module Hecks
 
       attr_reader :aggregate
 
+      # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      #
+      # @return [Array<Symbol>] `[:atomic_put]`
       def persistence_capabilities = [:atomic_put]
 
+      # Checks the credentials are declared and creates the aggregate, journal, event and
+      # saga tables if absent, one HTTP request per statement.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose table this adapter owns
+      # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
+      #   `account_id`, `database_id` and `api_token` (all required) and `domain` (scopes saga
+      #   rows, default the aggregate's name), each read under a Symbol or a String key
+      # @param root [String, nil] project root directory; accepted for the shared adapter
+      #   constructor shape and ignored
+      # @raise [Runtime::WiringError] if a required setting is missing or empty, or D1 rejects
+      #   a table-creation statement
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
 
@@ -132,7 +183,7 @@ module Hecks
         end
 
         @db = Connection.new(account_id: account_id, database_id: database_id, api_token: api_token)
-        # THE OPTIONAL saga-persistence capability's own scoping column
+        # The optional saga-persistence capability's own scoping column
         # (§2/§4) — D1's domain isolation is by whole-database identity
         # (one D1 database per domain in practice), so unlike Sqlite's
         # own per-aggregate-file default, there's no "which file does
@@ -159,8 +210,16 @@ module Hecks
         create_saga_table!
       end
 
+      # Names the aggregate's table; the journal table is keyed off it.
+      #
+      # @return [String] the aggregate's snake_case storage name, unquoted
       def table = @aggregate.storage_name
 
+      # Reads the current row for one aggregate identity.
+      #
+      # @param id [String, Object] the aggregate identity, bound as `id.to_s`
+      # @return [Runtime::Instance, nil] the decoded record, or nil when no row has that id
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def find(id)
         row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
         return nil unless row
@@ -168,9 +227,19 @@ module Hecks
         Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
       end
 
-      # order_by IS A RUNTIME VALUE — see postgres.rb's own all for the
+      # Lists every stored record, ordered by id unless an ordering attribute is given.
+      #
+      # order_by is a runtime value — see postgres.rb's own all for the
       # full reasoning; whitelisted the identical way, same order_clause
       # Sqlite's own all reuses (D1 speaks the identical dialect).
+      #
+      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+      #   by, with id as the tie-break; nil orders by id alone
+      # @param direction [Symbol, String] `:asc` or `:desc`, case-insensitive; anything else
+      #   sorts ascending
+      # @return [Array<Runtime::Instance>] the decoded records, `[]` when the table is empty
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate, or D1
+      #   rejects the statement
       def all(order_by: nil, direction: :asc)
         order_sql = "ORDER BY id"
         if order_by
@@ -189,21 +258,37 @@ module Hecks
         end
       end
 
+      # Counts the rows in the aggregate's table, deleted records excluded.
+      #
+      # @return [Integer] number of current records
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
 
+      # Inserts one journal row in its own HTTP request.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state` is
+      #   encoded through the state codec and `mirrors` stored as JSON, or NULL when nil
+      # @return [Ports::Persistence::Entry] the same `entry`
+      # @raise [Runtime::WiringError] if D1 rejects the insert
       def append(entry)
         @db.execute(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # `mirrors` (unlike `state`) is a nullable column — an absent
           # mirrors hash must bind a real SQL NULL, not the four-character
           # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
           # check against it would never match. Same guard `postgres_era.rb`
           # already uses for its own journal's `mirrors` column.
-          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+          [entry.id, entry.operation, state_json(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
 
+      # Replaces or deletes the aggregate's row for one journal entry.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+      # @return [Runtime::Instance, Array] for a save, a new instance over the entry's state;
+      #   for a delete, the `DELETE` statement's empty result rows
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def project(entry)
         return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
 
@@ -219,59 +304,89 @@ module Hecks
         instance
       end
 
+      # Reads the whole journal back in append order, for `AppendOnly#recover!` to replay.
+      #
+      # @return [Array<Ports::Persistence::Entry>] every journalled entry, state decoded
+      #   through the state codec and `mirrors` parsed with String keys (nil when none were
+      #   stored); a NULL `operation` reads as `"save"`; `[]` when nothing has been appended
+      # @raise [Runtime::WiringError] if D1 rejects the statement
+      # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
       def entries
         @db.execute("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
           state = JSON.parse(row["state"])
           Ports::Persistence::Entry.new(
             operation: row["operation"] || "save",
             id:        row["aggregate_id"],
-            state:     state&.transform_keys(&:to_sym),
+            state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
             mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
           )
         end
       end
 
+      # Deletes every row of the aggregate's table and its journal; events and saga rows
+      # are left in place.
+      #
+      # @return [Adapters::D1] self
+      # @raise [Runtime::WiringError] if D1 rejects a statement
       def reset!
         @db.execute("DELETE FROM #{quoted_table}")
         @db.execute("DELETE FROM #{quoted_entry_table}")
         self
       end
 
+      # Journals and then replaces an instance's current state, as two separate HTTP
+      # requests rather than one batch.
+      #
+      # @param instance [Runtime::Instance] the instance to store
+      # @return [Runtime::Instance] a new instance over a shallow copy of the saved state
+      # @raise [Runtime::WiringError] if D1 rejects either statement; a journal row already
+      #   inserted stays
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
         append(entry)
         project(entry)
       end
 
+      # Stores an entry and reports whether it inserted, replaced or conflicted, all in one
+      # batched HTTP request.
+      #
       # Classification, durable journal append and current-state projection
       # are one D1 batch transaction and therefore one HTTP request. The first
       # statement supplies the outcome from database state inside that same
       # transaction; the runtime performs no preliminary find.
       #
-      # `insert_only:` used to spend a SEPARATE, EARLIER round trip finding
-      # out whether the row existed before ever building the batch — a real
+      # Under `insert_only:`, spending a separate, earlier round trip finding
+      # out whether the row exists before building the batch would be a real
       # TOCTOU gap (two concurrent creates at the same identity could both
       # pass that check before either wrote). D1's batch has no conditional
-      # BRANCH of its own, true, but it does not need one: a batch's own
+      # branch of its own, true, but it does not need one: a batch's own
       # statements already execute in order, atomically, as one transaction
       # (Connection#batch's own comment) — the exact guarantee the single-
       # connection adapters' own `@db.transaction do ... end` gets locally.
-      # So the existence check moves INSIDE the batch as its own first
+      # So the existence check sits inside the batch as its own first
       # statement, and the two writes are individually gated with `WHERE NOT
       # EXISTS (...)` against that same table, evaluated in the same
       # transaction — a row that already existed makes both writes into
       # real, zero-row no-ops rather than skipping them from the Ruby side,
-      # matching Sqlite#atomic_put's `next` (skip append AND project both,
+      # matching Sqlite#atomic_put's `next` (skip append and project both,
       # together) with no second HTTP call and no gap for another writer to
       # land in between the check and the write.
-      # Three SQL statements, built here and batched together as ONE
-      # transaction below — see the comment above on the real TOCTOU gap
-      # this exact shape closes (the existence check moved INSIDE the
+      #
+      # Three SQL statements, built here and batched together as one
+      # transaction below — see the paragraph above on the real TOCTOU gap
+      # this exact shape closes (the existence check inside the
       # batch, not run as a separate earlier round trip). Splitting the
       # per-statement builders out would still need columns/values/slots/
       # not_exists/quoted_table threaded into each, and would separate
-      # three pieces of ONE atomic batch across methods with no single
+      # three pieces of one atomic batch across methods with no single
       # place left to see that they are, together, the fix.
+      #
+      # @param entry [Ports::Persistence::Entry] the save to store
+      # @param insert_only [Boolean] when true, an existing row turns both writes into
+      #   zero-row no-ops
+      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+      #   existing row and nothing was written
+      # @raise [Runtime::WiringError] if D1 rejects the batch; the whole batch is rolled back
       # rubocop:disable-next Metrics/AbcSize
       # rubocop:disable-next Metrics/MethodLength
       def atomic_put(entry, insert_only: false)
@@ -290,7 +405,7 @@ module Hecks
               "THEN 'replaced' ELSE 'inserted' END AS status"
           end
 
-        # `mirrors` is NULLABLE (unlike `state`) — see `append`'s own comment.
+        # `mirrors` is nullable (unlike `state`) — see `append`'s own comment.
         encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
 
         entry_sql, entry_binds =
@@ -298,12 +413,12 @@ module Hecks
             [
               "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) " \
               "SELECT ?, ?, ?, ? #{not_exists}",
-              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors, entry.id.to_s]
+              [entry.id, entry.operation, state_json(entry.state), encoded_mirrors, entry.id.to_s]
             ]
           else
             [
               "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors]
+              [entry.id, entry.operation, state_json(entry.state), encoded_mirrors]
             ]
           end
 
@@ -329,6 +444,12 @@ module Hecks
         results.fetch(0).fetch(0).fetch("status").to_sym
       end
 
+      # Journals a delete and then removes the row, whether or not a row exists, as two
+      # separate HTTP requests.
+      #
+      # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+      # @return [Boolean] always true
+      # @raise [Runtime::WiringError] if D1 rejects either statement
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
@@ -336,6 +457,11 @@ module Hecks
         true
       end
 
+      # Inserts an emitted event into the database's shared `events` table.
+      #
+      # @param event [Runtime::Event] the emitted event; `payload` is stored as JSON
+      # @return [Array] the insert's empty result rows; callers ignore it
+      # @raise [Runtime::WiringError] if D1 rejects the insert
       def record_event(event)
         @db.execute(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
@@ -343,6 +469,12 @@ module Hecks
         )
       end
 
+      # Reads back every recorded event in insertion order — the database's whole `events`
+      # table, not only this aggregate's rows.
+      #
+      # @return [Array<Runtime::Event>] the stored events, `payload` parsed with Symbol keys
+      #   and `occurred_at` as stored; `[]` when none are recorded
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def events
         @db.execute("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
@@ -355,10 +487,23 @@ module Hecks
         end
       end
 
-      # ── the OPTIONAL saga-persistence capability (§2) — reuses the DDL
+      # Replaces one saga instance's checkpoint, keyed by domain, process manager and
+      # correlation.
+      #
+      # ── the optional saga-persistence capability (§2) — reuses the DDL
       # `Sqlite::SchemaBuilder` already shares with Sqlite (`d1.rb`'s own
       # file header). Same `?`-placeholder shape every other write here
       # already uses through `Connection#execute`.
+      #
+      # @param process_manager [String, Symbol] the process manager's name
+      # @param correlation [String, Object] the instance's correlation value, stored as
+      #   `correlation.to_s`
+      # @param state [String, Symbol] the saga's current state name
+      # @param memory [Hash] the saga's memory; must be JSON-serializable
+      # @param completed_compensations [Array] the ledger of completed compensable legs; must
+      #   be JSON-serializable
+      # @return [Array] the statement's empty result rows; callers ignore it
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.execute(
           "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, " \
@@ -368,6 +513,13 @@ module Hecks
         )
       end
 
+      # Removes a finished saga instance's checkpoint; a missing row is not an error.
+      #
+      # @param process_manager [String, Symbol] the process manager's name
+      # @param correlation [String, Object] the instance's correlation value, matched as
+      #   `correlation.to_s`
+      # @return [Array] the statement's empty result rows; callers ignore it
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def delete_saga(process_manager:, correlation:)
         @db.execute(
           "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
@@ -375,6 +527,18 @@ module Hecks
         )
       end
 
+      # Yields every checkpointed saga instance of this adapter's domain, for
+      # `Registry#rehydrate_sagas!` to restore at boot.
+      #
+      # @yieldparam process_manager [String] the process manager's name
+      # @yieldparam correlation [String] the instance's correlation value
+      # @yieldparam state [String] the saga's state name
+      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every depth
+      # @yieldparam completed_compensations [Array] the completed-compensation ledger, `[]`
+      #   when the column is NULL
+      # @return [Enumerator, Array<Hash>] an enumerator over the same five values when no
+      #   block is given; otherwise the raw result rows
+      # @raise [Runtime::WiringError] if D1 rejects the statement
       def each_saga
         return enum_for(:each_saga) unless block_given?