hecks 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b85a8382bb201f9ab54417b3535d8fe1ede57c842f627e32a2ff75d7f2dd6618
-  data.tar.gz: e4852fd6b22145bec8a215e4c46fc6347527f7bd05811ff7da780e74dc24fe1d
+  metadata.gz: badbf552a5137cc39f791c4a398fe7d33423ff6d15c82cb018d1ef7c464af754
+  data.tar.gz: 5bf8d933f52178d2870d19dd0e33b03cacd060b848b54340c4940edbe94e008e
 SHA512:
-  metadata.gz: a538ddbe90fed2ccfa8c066f00777699b0eadade3c6523e6fbf5f62c19385ab7ace8e2c8de6fabafffce46abbefd36642401f6e5f23696127445378e95d98aad
-  data.tar.gz: e22574943d4246998ba9121c0c84d7b39ec944416066ad881f144f166a09deb5c1a1fbb8b6c8378084b89856ed9a4e5bfd9c66a3cd6d07fa9a9a21eee77d63fc
+  metadata.gz: 9327ee7366dacb9dcc90fc155999e5ff055efefc8e840ff4ddb08a7042adfcedbe5396c7547713562bebe1db618017b6851421f48d0ac300ab4339cf674a4cca
+  data.tar.gz: 97e1aa8115377269a23b29609e88370f86cfaec8dee9f79889232755dea7a55921d7e3db2fa6c3af26ca4f2afaca56a034fd7a6b5b8413ad00e45aef9c24c0d9

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,7 +40,7 @@ module Hecks
 
       module_function
 
-      # THE NEXT BEST QUESTION. `state` is whatever
+      # **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.
@@ -53,7 +53,7 @@ module Hecks
         )
       end
 
-      # PROSE -> PROPOSED DECLARATIONS.
+      # Prose -> proposed declarations.
       def interpret(prose:, state:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
@@ -66,7 +66,7 @@ module Hecks
         )
       end
 
-      # WHAT IS WRONG WITH THIS AS A MODEL — closed to the same kind
+      # 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.
@@ -82,7 +82,7 @@ module Hecks
         )
       end
 
-      # VOCABULARY HELP. Named `suggest_name`, not `name` — see
+      # **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.
       def suggest_name(meaning:, kind:, near:)

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?
 

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

@@ -31,7 +31,7 @@ module Hecks
         load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
       end
 
-      # CHAPTERS FIRST, JUDGED ONCE, THEN EVERYTHING THAT READS THEM.
+      # Chapters first, judged once, then everything that reads them.
       # A chapter may be split across files (the language's own grammar is
       # nine), and judging file one before files two-through-nine exist
       # refuses references that are perfectly well declared a file later —
@@ -39,8 +39,8 @@ module Hecks
       # already places every `*.bluebook` ahead of hecksagons and worlds,
       # so the window ends at the last chapter pattern rather than at a
       # hand-written list this would otherwise have to keep in step.
-      # `environment:` — ONE MORE PAIR OF FILES, LOADED LAST, NOT A GLOB.
-      # RECOVERED, not new — see Runtime::Loader.boot's own comment for
+      # `environment:` — one more pair of files, loaded last, not a glob.
+      # Recovered, not new — see Runtime::Loader.boot's own comment for
       # the provenance. A caller passing `Hecks.boot(path, environment:
       # "production")` gets exactly `environments/production.hecksagon`
       # and `environments/production.world` loaded, whichever exist (a
@@ -53,7 +53,7 @@ module Hecks
       # globs (all non-recursive, none named `environments/*`), so this
       # is the only thing that ever reaches them. Loaded as genuine
       # `Hecks.hecksagon "SameDomain" do ... end` / `Hecks.world
-      # "SameDomain" do ... end` blocks — MERGED into the base file's
+      # "SameDomain" do ... end` blocks — merged into the base file's
       # own hecksagon/world (Registry#add_hecksagon / #add_world,
       # concatenate/override rather than replace), so an overlay can
       # rebind or add settings for anything the base file declared
@@ -73,7 +73,7 @@ module Hecks
         load_each(directory, [File.join("environments", "#{environment}.world")])
       end
 
-      # EVERY BLUEBOOK IN A FOLDER IS ONE DECLARATION SET. Individual files
+      # Every bluebook in a folder is one declaration set. Individual files
       # remain organized in the domain expert's language; the folder is the
       # unit callers load. Builders group declarations by the chapter name in
       # each file, so a folder may hold more than one chapter without a catalog.
@@ -84,7 +84,7 @@ module Hecks
         Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
       end
 
-      # THE EXPLICIT-FILE SIBLING OF `load_domain` — for a caller that names
+      # The explicit-file sibling of `load_domain` — for a caller that names
       # its own exact files rather than a directory to glob (`Loader.boot_files`,
       # behind `Hecks.boot_files`). No `Dir.glob`, no copying: every path here
       # is a real file on disk, wherever it actually lives, loaded in place —
@@ -93,7 +93,7 @@ module Hecks
       # tmpdir (see Loader.boot_files's own header for why that pattern is a
       # hazard, not a convenience).
       #
-      # ORDERED BY CATEGORY, NOT BY THE CALLER'S OWN LIST ORDER — same four
+      # Ordered by category, not by the caller's own list order — same four
       # groups `Vocabulary.fetch("LoadOrder")` walks a directory in
       # (bluebook chapters, translations, hecksagons, worlds), because a
       # hecksagon can reference a bluebook's own constants and must not load
@@ -138,11 +138,11 @@ module Hecks
         raise Errno::ENOENT, "no such domain directory: #{path}"
       end
 
-      # THE DOMAIN YOU ARE STANDING IN. Walks up from `from` — the way git
+      # **The domain you are standing in**. Walks up from `from` — the way git
       # finds `.git` — and answers the nearest directory a boot would accept,
       # or nil if there is not one above you.
       #
-      # MARKED BY A `.hecksagon`, NOT BY A `.bluebook`. Chapters are
+      # Marked by a `.hecksagon`, not by a `.bluebook`. Chapters are
       # everywhere: era translations, the language's own self-hosted grammar,
       # and `spec/fixtures`, which holds a dozen unrelated ones in a single
       # directory. A `.hecksagon` is the file that says "this is a domain, and
@@ -152,7 +152,7 @@ module Hecks
       # Both layouts, because `bluebook_directory` above accepts both: a
       # domain directory holding a `bluebook/` subdirectory (every example in
       # this corpus), or one holding the files directly.
-      # NORMALISED TO THE OUTER DIRECTORY. Standing in `examples/banking/bluebook`,
+      # Normalised to the outer directory. Standing in `examples/banking/bluebook`,
       # the `.hecksagon` is right there, so a plain walk stops on the
       # `bluebook/` directory itself. Both boot identically — `bluebook_directory`
       # accepts either and `Loader.boot` takes `File.dirname` of what it gets,

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

@@ -4,26 +4,26 @@ require_relative "../../ports/authentication"
 
 module Hecks
   module Adapters
-    # GOOGLE'S OWN OIDC HANDSHAKE — the `authentication` port's one real
+    # **Google's own OIDC handshake** — the `authentication` port's one real
     # implementation today, moved here from being hand-rolled per-app
     # (an embryonaut_console `google_auth.rb` used to do exactly this;
     # any hecks-based app gets Google sign-in for free now, the
     # same "one adapter, reusable everywhere" value every other adapter
     # in this directory already has).
     #
-    # `oauth2` does ONLY the authorization-code exchange (no Rack
+    # `oauth2` does only the authorization-code exchange (no Rack
     # middleware, no Omniauth strategy indirection) ; `google-id-token`
-    # does ONLY ID-token verification (signature checked against
+    # does only ID-token verification (signature checked against
     # Google's real, rotating JWKS — real, maintained code, never
     # hand-rolled here). Neither library decides what a verified
-    # (issuer, subject) MEANS — that's `Ports::IdentityResolution`'s
+    # (issuer, subject) means — that's `Ports::IdentityResolution`'s
     # job, called by whoever consumes this port's `verify`.
     #
-    # LAZY REQUIRES, same reasoning `Postgres.connect_for` already
+    # Lazy requires, same reasoning `Postgres.connect_for` already
     # holds itself to for `pg`: a domain that never binds
     # `authentication` to this adapter should never need these gems
-    # installed. This FILE loads in every boot (driven.rb's own
-    # unconditional require_relative list) ; the GEMS load only where
+    # installed. This file loads in every boot (driven.rb's own
+    # unconditional require_relative list) ; the gems load only where
     # a real handshake actually happens.
     #
     # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` —
@@ -68,7 +68,7 @@ module Hecks
       # itself. `email_verified` rides along because a caller granting
       # access off this email needs to know Google actually checked it.
       def verify(code:, state:, expected_state:)
-        # BOTH GEMS, BEFORE ANYTHING ELSE — not staggered further down
+        # **Both gems, before anything else** — not staggered further down
         # this method: the rescue clause below names GoogleIDToken
         # ::ValidationError, and Ruby resolves that constant reference
         # at the moment an exception is being matched, not at parse