hecks 1.3.0 → 1.5.0

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

@@ -27,17 +27,31 @@ module Hecks
 
       attr_reader :aggregate, :path
 
+      # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      #
+      # @return [Array<Symbol>] `[:atomic_put]`
       def persistence_capabilities = [:atomic_put]
 
+      # Opens (creating if absent) the database file and its aggregate, journal, event, saga
+      # and outbox tables.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose table this adapter owns
+      # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
+      #   `database` (file path, default `data/<table>.db`) and `domain` (scopes saga rows,
+      #   default the aggregate's name), each read under a Symbol or a String key
+      # @param root [String, nil] directory a relative `database` path resolves against; nil
+      #   means the process working directory
+      # @raise [LoadError] if the `sqlite3` gem is not installed
+      # @raise [SQLite3::Exception] if the file cannot be opened or a table cannot be created
       def initialize(aggregate:, settings: {}, root: nil)
-        # LAZY, ON PURPOSE — a domain that never wires Sqlite should never
+        # **Lazy, on purpose** — a domain that never wires Sqlite should never
         # need the gem installed. `require "hecks"` alone must not
         # force a database client library nobody asked for.
         require "sqlite3"
 
         @aggregate = aggregate
         @path      = resolve_path(settings, root)
-        # THE OPTIONAL saga-persistence capability's own scoping column
+        # The optional saga-persistence capability's own scoping column
         # (§2/§4) — falls back to the aggregate's own name for a
         # directly-instantiated adapter (specs), same fallback shape
         # Postgres's own @domain already uses.
@@ -67,18 +81,33 @@ module Hecks
         create_outbox_table!
       end
 
-      # RE-ENTRANT ON PURPOSE — `atomic_put` opens its own transaction
+      # Runs the block inside one SQLite transaction, joining an already-open one.
+      #
+      # **Re-entrant on purpose** — `atomic_put` opens its own transaction
       # and `Interpreting#run_dispatch_order` opens one around the whole
       # save+emit pair; SQLite3 refuses a BEGIN inside a BEGIN, so the
       # inner call joins the outer one instead. Same shape Postgres uses.
+      #
+      # @yield the writes to commit together; an exception raised inside rolls the
+      #   outermost transaction back
+      # @return [Object] the block's own result
+      # @raise [SQLite3::Exception] if `BEGIN`, a statement inside the block, or `COMMIT` fails
       def transaction(&)
         return yield if @db.transaction_active?
 
         @db.transaction(&)
       end
 
+      # Names the aggregate's table; the journal table and outbox rows are 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 [SQLite3::Exception] if the statement fails
       def find(id)
         row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
         return nil unless row
@@ -86,9 +115,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 before it ever
       # reaches order_expression.
+      #
+      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+      #   by; 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
+      # @raise [SQLite3::Exception] if the statement fails
       def all(order_by: nil, direction: :asc)
         order_sql = "ORDER BY id"
         if order_by
@@ -107,21 +146,38 @@ module Hecks
         end
       end
 
+      # Counts the rows in the aggregate's table, deleted records excluded.
+      #
+      # @return [Integer] number of current records
+      # @raise [SQLite3::Exception] if the statement fails
       def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
 
+      # Inserts one journal row, outside any transaction of its own.
+      #
+      # @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 [SQLite3::Exception] if the insert fails
       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, JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, 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 [SQLite3::Exception] if the statement fails
       def project(entry)
         return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
 
@@ -137,24 +193,41 @@ 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 [SQLite3::Exception] if the statement fails
+      # @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, saga rows and
+      # outbox rows are left in place.
+      #
+      # @return [Adapters::Sqlite] self
+      # @raise [SQLite3::Exception] if a statement fails
       def reset!
         @db.execute("DELETE FROM #{quoted_table}")
         @db.execute("DELETE FROM #{quoted_entry_table}")
         self
       end
 
+      # Journals and replaces an instance's current state in one transaction.
+      #
+      # @param instance [Runtime::Instance] the instance to store
+      # @return [Runtime::Instance] a new instance over a shallow copy of the saved state
+      # @raise [SQLite3::Exception] if either statement fails; the transaction is rolled back
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
         transaction do
@@ -163,9 +236,17 @@ module Hecks
         end
       end
 
+      # Stores an entry and reports whether it inserted, replaced or conflicted.
+      #
       # The outcome lookup, journal append and snapshot replacement share one
       # SQLite transaction. The runtime performs no preliminary find; this
       # adapter-native operation owns both concurrency and outcome reporting.
+      #
+      # @param entry [Ports::Persistence::Entry] the save to store
+      # @param insert_only [Boolean] when true, an existing row is left untouched
+      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+      #   existing row and nothing was written
+      # @raise [SQLite3::Exception] if a statement fails; the transaction is rolled back
       def atomic_put(entry, insert_only: false)
         status = nil
         transaction do
@@ -181,6 +262,12 @@ module Hecks
         status
       end
 
+      # Journals a delete and removes the row, whether or not a row exists. The two
+      # statements share a transaction only when the caller has one open.
+      #
+      # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+      # @return [Boolean] always true
+      # @raise [SQLite3::Exception] if either statement fails
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
@@ -188,6 +275,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 [SQLite3::Exception] if the insert fails
       def record_event(event)
         @db.execute(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
@@ -195,6 +287,12 @@ module Hecks
         )
       end
 
+      # Reads back every recorded event in insertion order — the database file'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 [SQLite3::Exception] if the statement fails
       def events
         @db.execute("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
@@ -207,26 +305,22 @@ module Hecks
         end
       end
 
-      # ── the OPTIONAL saga-persistence capability (§2) — reuses the
-      # DDL every SQLite-backed aggregate table already lives beside
-      # (`create_saga_table!`, `Sqlite::SchemaBuilder`, shared with D1).
-      # SQLite's `resolve_path` defaults to one `.db` file PER
-      # AGGREGATE unless a domain shares one `database` setting across
-      # its aggregates — since saga persistence resolves through
-      # whichever adapter instance backs the domain's FIRST aggregate
-      # (`Registry#saga_persistence`), this table ends up living inside
-      # THAT one aggregate's own file by default. Correct and durable
-      # either way; a domain that wants an obviously-named saga store
-      # already gets one by sharing `database` across its aggregates,
-      # the recommended, common case.
-      # THE OUTBOX — see `Runtime::Outbox`. Rows land in the SAME
+      # Inserts new outbox rows as pending, skipping any whose `delivery_id` already exists.
+      #
+      # The outbox — see `Runtime::Outbox`. Rows land in the same
       # database as this aggregate (the only way the enqueue shares the
       # save's transaction), keyed by the aggregate's storage name so an
       # adapter instance only ever reads back its own rows even when
       # several aggregates share one file. `INSERT OR IGNORE` on the
-      # UNIQUE delivery_id makes a re-enqueue of the same (event,
+      # unique delivery_id makes a re-enqueue of the same (event,
       # consumer) a no-op; `outbox_claim`'s `WHERE status = 'pending'`
       # is the compare-and-set that lets exactly one relay win a row.
+      #
+      # @param rows [Array<Runtime::Outbox::Row>] rows to enqueue; each accepted row has its
+      #   `id` and `status` assigned in place. `row.aggregate` is stored as given
+      # @return [Array<Runtime::Outbox::Row>] the rows actually inserted, `[]` when every one
+      #   was a duplicate
+      # @raise [SQLite3::Exception] if an insert fails
       def outbox_enqueue(rows)
         rows.filter_map do |row|
           @db.execute(
@@ -243,6 +337,12 @@ module Hecks
         end
       end
 
+      # Claims a pending outbox row with a compare-and-set update, counting the attempt.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @return [Boolean] true when the row was pending and is now claimed; false when it is
+      #   unknown or another claimer got there first
+      # @raise [SQLite3::Exception] if the update fails
       def outbox_claim(id)
         @db.execute(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = ? " \
@@ -252,6 +352,15 @@ module Hecks
         @db.changes == 1
       end
 
+      # Records a delivery outcome and its settle time on an outbox row, whatever status it
+      # held.
+      #
+      # @param id [Integer] the row id `outbox_enqueue` assigned
+      # @param status [String, Symbol] the new status, one of `Runtime::Outbox::STATUSES`;
+      #   not validated here
+      # @param error [String, nil] the failure description, or nil to store NULL
+      # @return [Boolean] true when exactly one row was updated; false when no row has `id`
+      # @raise [SQLite3::Exception] if the update fails
       def outbox_settle(id, status:, error: nil)
         @db.execute(
           "UPDATE hecks_outbox SET status = ?, error = ?, settled_at = ? WHERE id = ?",
@@ -260,6 +369,13 @@ module Hecks
         @db.changes == 1
       end
 
+      # Lists the outbox rows whose `aggregate` column equals this adapter's `table`, in
+      # enqueue order.
+      #
+      # @param status [String, Symbol, nil] only rows with this status; nil lists every row
+      # @return [Array<Runtime::Outbox::Row>] the matching rows, `event` parsed with Symbol
+      #   keys; `[]` when none match
+      # @raise [SQLite3::Exception] if the statement fails
       def outbox_rows(status: nil)
         sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
         binds = [table]
@@ -270,6 +386,31 @@ module Hecks
         @db.execute("#{sql} ORDER BY id", binds).map { |row| outbox_row(row) }
       end
 
+      # Replaces one saga instance's checkpoint, keyed by domain, process manager and
+      # correlation.
+      #
+      # ── the optional saga-persistence capability (§2) — reuses the
+      # DDL every SQLite-backed aggregate table already lives beside
+      # (`create_saga_table!`, `Sqlite::SchemaBuilder`, shared with D1).
+      # SQLite's `resolve_path` defaults to one `.db` file per
+      # aggregate unless a domain shares one `database` setting across
+      # its aggregates — since saga persistence resolves through
+      # whichever adapter instance backs the domain's first aggregate
+      # (`Registry#saga_persistence`), this table ends up living inside
+      # that one aggregate's own file by default. Correct and durable
+      # either way; a domain that wants an obviously-named saga store
+      # already gets one by sharing `database` across its aggregates,
+      # the recommended, common case.
+      #
+      # @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 [SQLite3::Exception] if the statement fails
       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, " \
@@ -279,6 +420,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 [SQLite3::Exception] if the statement fails
       def delete_saga(process_manager:, correlation:)
         @db.execute(
           "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
@@ -286,6 +434,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 [SQLite3::Exception] if the statement fails
       def each_saga
         return enum_for(:each_saga) unless block_given?
 

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

@@ -8,6 +8,9 @@ module Hecks
     module SystemClock
       module_function
 
+      # Reads the machine's own current time.
+      #
+      # @return [Integer] the current time, in Unix epoch seconds
       def now = Time.now.to_i
     end
   end

data/lib/hecks/adapters/driven/tenant_provisioner.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "TenantProvisioner" do
+  port "TenantProvisioning"
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module Adapters
+    # THE IMPERATIVE HALF of provisioning a tenant, pulled out of
+    # `bin/project_tenant` and behind a real driven port
+    # (`Deploy::Tenant.port "TenantProvisioning"`) instead — the same
+    # hexagonal reasoning `GithubChecks` already gives for its own
+    # port: real, impure, side-effecting work (writing the overlay
+    # file) belongs in an adapter, not in a bare script or a command
+    # handler. `Deploy::Tenant`'s own `asks "Provision"` operation calls
+    # `#provision` and turns whatever it returns into `TenantProvisioned`,
+    # or whatever it raises into `ProvisioningRefused` — see
+    # `PortOperationInterpreter#ask`'s own "every failure is an answer"
+    # comment for why nothing here needs its own rescue.
+    #
+    # DELIBERATELY DOES NOT BOOT THE TARGET DOMAIN — that step (proving
+    # it boots for real, running the tenant_capable? gate) stays in
+    # `bin/project_tenant` itself, called AFTER this operation answers,
+    # not nested inside it. Booting a whole domain from inside an
+    # adapter method that is itself running mid-dispatch (this port
+    # operation) is a real, separate concern from writing one file, and
+    # keeping the two apart avoids a nested `Hecks.boot` call ever
+    # running inside another boot's own dispatch call stack.
+    #
+    # RETURNS A HASH SHAPED LIKE `Tenancy::Tenant.Register`'S OWN
+    # ARGUMENTS, on purpose — `tenancy.hecksagon`'s own `translates`
+    # reaction forwards an answered event's payload verbatim, so this
+    # adapter's own return value IS the translation from Deploy's
+    # vocabulary into Tenancy's, decided here rather than in a mapping
+    # layer neither side could see into.
+    class TenantProvisioner
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # `directory:` IS REQUIRED, NOT DERIVED FROM `domain` — a real,
+      # confirmed bug found only under CI's own real-Postgres suite: a
+      # domain's own DECLARED NAME (`domain`, e.g. "Scratch") is not a
+      # filesystem path, and File.expand_path(domain, Dir.pwd) silently
+      # resolved to the wrong directory (relative to whatever the
+      # RUNNING PROCESS' own cwd happened to be) whenever the CLI's own
+      # `--domain=` value didn't happen to equal its own directory
+      # argument by coincidence. `bin/project_tenant` passes its own
+      # real `domain_directory` local straight through.
+
+      def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)
+        domain_directory = File.expand_path(directory[:value] || directory)
+
+        overlay_path = File.join(domain_directory, "environments", "#{slug[:value] || slug}.world")
+        FileUtils.mkdir_p(File.dirname(overlay_path))
+        File.write(overlay_path, <<~WORLD)
+          Hecks.world "#{domain[:value] || domain}" do
+            realm "#{realm[:value] || realm}"
+            persisted_by("#{adapter[:value] || adapter}") do
+              database "#{database[:value] || database}"
+              schema   "#{schema[:value] || schema}"
+            end
+          end
+        WORLD
+
+        { slug: slug, domain: domain, realm: realm, schema: schema }
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -14,7 +14,7 @@ end
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-# `PostgresEra` is NOT `require_relative`d here — ADR 0033 moved it, and
+# `PostgresEra` is not `require_relative`d here — ADR 0033 moved it, and
 # the rest of the era/lineage/translation subsystem, behind a loadable
 # persistence plugin (`hecks/ports/persistence/plugins/era`) rather than
 # requiring every app to carry it whether or not anything ever binds
@@ -22,10 +22,10 @@ require_relative "driven/postgres"
 # that makes that genuinely load-nothing-until-asked instead of pushing
 # an explicit `require` onto every one of the ~15 generic `bin/*` tools
 # that boot an arbitrary checked-in domain (several of which — pizzas,
-# compliance, chess, roster — bind PostgresEra): the FIRST real
+# compliance, chess, roster — bind PostgresEra): the first real
 # `Adapters.const_get("PostgresEra")` (`registry/verification.rb`'s own
 # adapter resolution, unchanged) transparently `require`s the plugin
-# entry point, which defines the constant AND calls `register_plugin`
+# entry point, which defines the constant and calls `register_plugin`
 # as its own side effect (`plugins/era.rb`'s last line) — the exact
 # same effect an explicit `require "hecks/ports/persistence/plugins/
 # era"` has, just deferred to the moment something is actually asked
@@ -40,10 +40,12 @@ require_relative "driven/prism"
 require_relative "driven/folder"
 require_relative "driven/d1"
 require_relative "driven/mock_stripe_adapter"
+require_relative "driven/tenant_provisioner"
 require_relative "driven/secure_random_identity"
+require_relative "driven/in_process_key_vault"
 require_relative "driven/system_clock"
 # `SequentialIdentity` — the deterministic identity_generation test
-# double — is NOT required here on purpose. It lives at
+# double — is not required here on purpose. It lives at
 # spec/fixtures/sequential_identity.{adapter,rb}, loaded explicitly by
 # whichever spec wants it: this file's `require_relative` list is what
 # `Folder#load_library`'s `.adapter` glob backs, and `.adapter` DSL

data/lib/hecks/adapters/driving/github_webhook.rb

@@ -4,19 +4,19 @@ require "rack"
 
 module Hecks
   module Adapters
-    # THE DRIVING SIDE — code an OUTSIDE caller reaches IN through,
-    # rather than code the domain reaches OUT through. Every existing
+    # **The driving side** — code an outside caller reaches in through,
+    # rather than code the domain reaches out through. Every existing
     # file under `adapters/driven/` is the latter: a store or reader a
-    # `persisted_by`/`port` binding resolves TO, called BY this
+    # `persisted_by`/`port` binding resolves to, called by this
     # framework's own runtime. Nothing under this repository has ever
-    # been the mirror image before — code that receives a request FROM
+    # been the mirror image before — code that receives a request from
     # the outside world and turns it into a dispatch — so this is the
     # first entry, and the directory itself is new.
     module Driving
-      # A GITHUB WEBHOOK RECEIVER, TRANSPORT ONLY — the same split
+      # **A GitHub webhook receiver, transport only** — the same split
       # `Hecks::Adapters::GithubChecks` (qa/adapters/github_checks.rb,
-      # this class's own PULL-side sibling) already draws for itself:
-      # THIS file owns proving a request really came from GitHub and
+      # this class's own pull-side sibling) already draws for itself:
+      # this file owns proving a request really came from GitHub and
       # unwrapping GitHub's own webhook envelope (`X-GitHub-Event`, the
       # JSON body, GitHub's own automatic `ping` check) — never which
       # commands to dispatch about what it finds inside. That is exactly
@@ -26,10 +26,12 @@ module Hecks
       # in `qa/adapters/github_ci_webhook.rb`, the subclass of this file
       # that actually knows what a `QualityControl::Clearance` is.
       #
-      # A PLAIN RACK APP (`#call(env)`) — no Sinatra, no Rails — the same
+      # ## A plain rack app
+      #
+      # A plain rack app (`#call(env)`) — no Sinatra, no Rails — the same
       # shape `Hecks::Forms::App` (lib/hecks/forms/app.rb) already
       # established for the one other HTTP-facing surface this library
-      # ships. `rack` is a LAZY Gemfile dependency for exactly the reason
+      # ships. `rack` is a lazy Gemfile dependency for exactly the reason
       # that file's own header gives: this file is never required by
       # `require "hecks"` (nothing under `adapters.rb`'s own eager
       # `adapters/driven` load names it — see that file's own header),
@@ -37,9 +39,11 @@ module Hecks
       # `rack` installed, the same "opt in by requiring the file at all"
       # contract `hecks/forms.rb` already has for `Forms::App`.
       #
-      # SUBCLASS RESPONSIBILITY: implement `#handle_event(event, action,
+      # ## Subclass responsibility
+      #
+      # Implement `#handle_event(event, action,
       # payload)`, returning `[http_status, response_body_hash]`. Called
-      # ONLY after the signature has verified and the body has parsed as
+      # only after the signature has verified and the body has parsed as
       # JSON — a subclass never has to re-check either. `event` is
       # GitHub's own `X-GitHub-Event` header value ("check_suite",
       # "check_run", "pull_request", ...); `action` is the payload's own
@@ -51,7 +55,7 @@ module Hecks
       # subclass at all; there is nothing domain-specific to decide
       # about it.
       class GithubWebhook
-        # REFUSED, LOUDLY — the same shape a domain refusal already takes
+        # **Refused, loudly** — the same shape a domain refusal already takes
         # everywhere else in this codebase (`Runtime::DOMAIN_REFUSALS`,
         # `Forms::App`'s own `{error:, message:}` JSON body for a bad
         # command). A request that cannot prove it came from GitHub gets
@@ -60,31 +64,40 @@ module Hecks
         # exactly like success in a log nobody re-reads.
         class InvalidSignature < StandardError; end
 
-        # THE BODY DID NOT EVEN PARSE — distinct from a signature refusal:
+        # **The body did not even parse** — distinct from a signature refusal:
         # this body genuinely came from whoever signed it (checked
-        # FIRST, before parsing ever runs — see `#call`), and simply
+        # first, before parsing ever runs — see `#call`), and simply
         # is not JSON. Still refused, never guessed at.
         class MalformedPayload < StandardError; end
 
         SIGNATURE_HEADER = "HTTP_X_HUB_SIGNATURE_256".freeze
         EVENT_HEADER     = "HTTP_X_GITHUB_EVENT".freeze
 
-        # `secret:` HAS NO DEFAULT, ON PURPOSE — the same rule
+        # `secret:` has no default, on purpose — the same rule
         # `GoogleAuthentication`'s own header states for its own
         # `ENV.fetch`, restated here because the consequence is worse for
         # a webhook: an unverified signature check is not "half
-        # configured", it is NO verification at all, silently accepting
+        # configured", it is no verification at all, silently accepting
         # anything claiming to be GitHub. A caller passes the real
         # secret explicitly — from `ENV.fetch("GITHUB_WEBHOOK_SECRET")`
         # or wherever it keeps one — rather than this class reaching into
         # the environment itself and hiding that requirement inside a
         # default.
+        # @param secret [String] the shared webhook secret (e.g. `ENV.fetch
+        #   ("GITHUB_WEBHOOK_SECRET")`), checked against each request's `X-Hub-Signature-256`
+        # @raise [ArgumentError] if `secret` is nil or empty
         def initialize(secret:)
           raise ArgumentError, "no webhook secret configured" if secret.to_s.empty?
 
           @secret = secret
         end
 
+        # The rack entry point: verifies, parses, and routes one webhook request.
+        #
+        # @param env [Hash] the rack environment
+        # @return [Array(Integer, Hash, Array<String>)] the rack response triple — status,
+        #   headers, and a one-element body Array holding the JSON-encoded response
+        # @raise [NotImplementedError] if the subclass has not implemented `#handle_event`
         def call(env)
           request = Rack::Request.new(env)
           return respond(405, error: "MethodNotAllowed", message: "POST only") unless request.post?
@@ -107,8 +120,8 @@ module Hecks
 
         private
 
-        # CONSTANT-TIME COMPARE, NOT `==`. A byte-by-byte `==` returns
-        # the moment it finds the first mismatching byte, so how LONG
+        # Constant-time compare, not `==`. A byte-by-byte `==` returns
+        # the moment it finds the first mismatching byte, so how long
         # that took leaks how many leading bytes of a forged signature
         # were already right to anyone timing the response — GitHub's
         # own webhook documentation calls this out by name and recommends