hecks 2.7.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91dfe0fb86ceb9bb96ecc6b08da680213fed526f49f922f1a2f66d9cb89c80e
-  data.tar.gz: 22fc90a2e361f45e27796248c22391997281e62fbfeec01b25ba35378e6e5681
+  metadata.gz: 6f6baf48801bf4f341c3a39a05215c2a0ce3f345b22068f84d0e04c91c3c76f6
+  data.tar.gz: 6eda1623f06f2607400ff7a2b13c10775ed60416c91f36f7d4a36bdb9d6adf39
 SHA512:
-  metadata.gz: 824fd1d23971f6dacfd3c3ea18a35f5d0d61e7f07e2056b789d7be7d105a7bc47d13a61e0391d7aeb46d20bcfe8400e307bf05728ed10f9e4c69b46ac7d0df45
-  data.tar.gz: 3f6e4679c8187f212f913de1d17944c3bac2ed0e4385bcff3bcd259e1b6ccb49d6c8270c7f84885fcc3f308e9ca7def653341050c649d1a048b8a91228ee65e7
+  metadata.gz: c8d8670a30de7d7318a84cf6a25f78b394c6974fb42f61697fbe20d0bc5642455740c644fd055cfe7f347d0bed254ab93fd42ce596fc444af6de8bcde86e7291
+  data.tar.gz: dc3b18d73758d235d369c0158729b8186e8d6a6d8c2c5040d26f772876b43d8ff8eb29a784e166585af1d890bf5620de0fa456934bf6568ba96d1318858e9079

data/exe/hecks

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+# The `hecks` command the gem installs: run, read, check and serve a domain.
+# Routes to `Hecks::CLI` (lib/hecks/cli.rb); run with no arguments to list subcommands.
+
+# The gem's own `lib` goes first, as for every `bin/` script, so this also
+# runs straight from a checkout.
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "hecks/cli"
+
+exit Hecks::CLI.start(ARGV)

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

@@ -6,31 +6,8 @@ require_relative "../../ports/agent"
 
 module Hecks
   module Adapters
-    # **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
-    # the CLI's own JSON envelope (`{"result": "..."}`) down to the
-    # 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
-    # `Ports::Agent::Answers`' job, not this file's — see `ports/agent.rb`'s
-    # own header for why that split is load-bearing.
-    #
-    # `Open3.capture2` with an explicit argv array, never a shell string
-    # — the same shape every other subprocess call in this repo already
-    # uses (`bin/rust_conformance`), and the reason `claude` being
-    # shell-aliased to `claude --dangerously-skip-permissions` in a
-    # human's own terminal never reaches this code at all: an argv spawn
-    # invokes the real binary directly, no shell, no alias.
-    #
-    # `--allowedTools ""` — this adapter asks a question and reads back
-    # text; it never wants the model reaching for a tool mid-answer.
+    # Real `agent` fulfillment: one `claude -p --output-format json` process per call.
+    # Transport only; shape and vocabulary checks belong to `Ports::Agent::Answers`.
     module ClaudeCode
       TIMEOUT_SECONDS = 120
 
@@ -40,22 +17,6 @@ module Hecks
 
       module_function
 
-      # 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 " \
@@ -65,18 +26,6 @@ module Hecks
         )
       end
 
-      # 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, " \
@@ -89,22 +38,6 @@ module Hecks
         )
       end
 
-      # 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(
@@ -117,22 +50,7 @@ module Hecks
         )
       end
 
-      # 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
+      # Named `suggest_name`, not `name`: `name` is never a safe module-function name here.
       def suggest_name(meaning:, kind:, near:)
         call(
           system:  SYSTEM_PREFIX + "Suggest a name for a #{kind} meaning \"#{meaning}\", distinct from " \
@@ -142,18 +60,7 @@ module Hecks
         )
       end
 
-      # ── 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`)
+      # Argv spawn, never a shell, so a `claude` shell alias cannot apply; no tools are allowed.
       def call(system:, payload:)
         stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
           Open3.capture2(
@@ -171,13 +78,6 @@ 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

@@ -5,7 +5,7 @@ require "uri"
 require_relative "sql_query_builder"
 require_relative "sqlite/schema_builder"
 require_relative "sqlite/codec"
-require_relative "sqlite" # for Sqlite::SchemaBuilder/Sqlite::Codec — see the reuse note below
+require_relative "sqlite"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -15,59 +15,23 @@ 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
-    # 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.
+    # Cloudflare D1 (managed SQLite over REST): reuses Sqlite's schema and codec unchanged.
+    # Only the transport differs, one HTTP call per query.
     class D1
-      # **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
-      # per execute, not a persistent connection — D1 has no connection to
-      # hold open.
+      # HTTP transport exposing the slice of `SQLite3::Database` the shared SQLite code uses.
       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
+        # D1 batches are transactions: statements run in order and a failure rolls all back.
         def batch(statements)
           payload = {
             batch: statements.map do |sql, binds|
@@ -104,11 +68,7 @@ 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 —
-        # 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
-        # statement failed, when either is present.
+        # Prefers the statement's own error/message (by key presence) over the whole-response one.
         def failed_statement_detail(failed, messages)
           detail =
             if failed.key?("error")
@@ -123,26 +83,10 @@ 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
@@ -156,22 +100,11 @@ 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
+      # Creates the aggregate, journal, event and saga tables if absent.
+      # Settings: `account_id`, `database_id`, `api_token` (required) and `domain` (saga scope).
+      # @raise [Runtime::WiringError] if a required setting is missing or empty
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
 
@@ -183,12 +116,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
-        # (§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
-        # this end up in" ambiguity here: every aggregate on D1 within a
-        # domain already shares one database.
+        # Saga rows are scoped by domain; one D1 database per domain, so aggregates share it.
         @domain = (
           if settings.key?(:domain)
             settings[:domain]
@@ -199,9 +127,7 @@ module Hecks
           end
         ).to_s
 
-        # No PRAGMA synchronous here, unlike Sqlite — D1 is a managed
-        # durable service; there is no local fsync policy for a caller to
-        # tune, and the query endpoint has no PRAGMA write-access to it.
+        # No PRAGMA synchronous: D1 is managed and its query endpoint disallows PRAGMA writes.
         create_aggregate_table!
         create_entry_table!
         ensure_entry_operation_column!
@@ -210,16 +136,8 @@ 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
@@ -227,19 +145,8 @@ module Hecks
         Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
       end
 
-      # 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
+      # Lists every record, ordered by id or by `order_by` when it names an attribute.
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
       def all(order_by: nil, direction: :asc)
         order_sql = "ORDER BY id"
         if order_by
@@ -258,37 +165,17 @@ 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 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.
+          # Absent mirrors bind SQL NULL, not the JSON text "null" (the column is nullable).
           [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?
 
@@ -304,13 +191,7 @@ 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
+      # The whole journal in append order, for `AppendOnly#recover!` to replay.
       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"])
@@ -323,70 +204,25 @@ module Hecks
         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
+      # Clears the aggregate table and its journal; events and saga rows stay.
       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
+      # Journals then projects as two HTTP requests; the journal row stays if projecting fails.
       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.
+      # Stores an entry in one D1 batch; returns `:inserted`, `:replaced` or `:conflicted`.
       #
-      # 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
-      # 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 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,
-      # 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 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
-      # 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
+      # The existence check is the batch's first statement and both writes are gated by
+      # WHERE NOT EXISTS, so `insert_only` has no gap between check and write.
+      # @return [Symbol] `:conflicted` only when `insert_only` met an existing row
       # rubocop:disable-next Metrics/AbcSize
       # rubocop:disable-next Metrics/MethodLength
       def atomic_put(entry, insert_only: false)
@@ -405,7 +241,7 @@ module Hecks
               "THEN 'replaced' ELSE 'inserted' END AS status"
           end
 
-        # `mirrors` is nullable (unlike `state`) — see `append`'s own comment.
+        # `mirrors` is nullable; see `append`.
         encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
 
         entry_sql, entry_binds =
@@ -444,12 +280,6 @@ 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)
@@ -457,11 +287,6 @@ 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 (?, ?, ?, ?, ?)",
@@ -469,12 +294,7 @@ 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
+      # Every recorded event in the shared `events` table, not only this aggregate's.
       def events
         @db.execute("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
@@ -487,13 +307,24 @@ module Hecks
         end
       end
 
-      # 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`.
+      # One record's recorded events, oldest first — pushed down as a `WHERE` clause
+      # (`hecks_events_aggregate_id_idx`) instead of filtering `#events`'s whole-table read.
+      def events_for(aggregate:, id:)
+        @db.execute(
+          "SELECT * FROM events WHERE aggregate = ? AND aggregate_id = ? ORDER BY id",
+          [aggregate, id.to_s]
+        ).map do |row|
+          Runtime::Event.new(
+            name:        row["name"],
+            aggregate:   row["aggregate"],
+            id:          row["aggregate_id"],
+            payload:     JSON.parse(row["payload"], symbolize_names: true),
+            occurred_at: row["occurred_at"]
+          )
+        end
+      end
+
+      # Persists a saga's checkpointed state as one D1 statement.
       #
       # @param process_manager [String, Symbol] the process manager's name
       # @param correlation [String, Object] the instance's correlation value, stored as
@@ -513,13 +344,6 @@ 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 = ?",
@@ -527,18 +351,7 @@ 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
+      # Yields each checkpointed saga of this domain, for `Registry#rehydrate_sagas!`.
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
@@ -555,10 +368,7 @@ module Hecks
 
       private
 
-      # ── SqlQueryBuilder's dialect hooks — identical to Sqlite's, since
-      # D1 speaks the same dialect (copied, not shared by module include,
-      # because Sqlite's own copies are private instance methods on a
-      # different class — see the file header) ───────────────────────
+      # SqlQueryBuilder dialect hooks, copied from Sqlite's private methods.
       def select_list = "*"
       def from_relation = quoted_table
       def dialect_name = "D1"
@@ -585,8 +395,7 @@ module Hecks
         "json_extract(#{quote_ident(name)}, '#{json_path}')"
       end
 
-      # SQLite (and D1, the same engine) has no bare OFFSET — LIMIT -1 is
-      # its own documented unbounded spelling, exactly for this case.
+      # SQLite has no bare OFFSET; LIMIT -1 is its unbounded spelling.
       def unbounded_limit = " LIMIT -1"
 
       def order_clause(order_by, policy)
@@ -597,8 +406,6 @@ module Hecks
         @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
       end
 
-      # ── the rest of the dialect ─────────────────────────────────────
-
       def quote_ident(name)
         %("#{name.to_s.gsub('"', '""')}")
       end