hecks 1.2.0 → 1.4.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.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
@@ -43,7 +43,7 @@ require_relative "driven/mock_stripe_adapter"
 require_relative "driven/secure_random_identity"
 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

@@ -0,0 +1,145 @@
+require "openssl"
+require "json"
+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
+    # file under `adapters/driven/` is the latter: a store or reader a
+    # `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
+    # 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
+      # `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
+      # 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
+      # as domain-specific as `GithubChecks#run` turning `check-runs`
+      # JSON into green-or-raise, and lives exactly where that class's
+      # own header explains such logic belongs: outside this library,
+      # 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
+      # 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
+      # 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),
+      # so a project that never mounts a driving adapter never needs
+      # `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,
+      # payload)`, returning `[http_status, response_body_hash]`. Called
+      # 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
+      # top-level `"action"` field when it has one (GitHub's webhooks
+      # nearly all carry one — "completed", "requested", "opened", ...)
+      # and nil when it does not. `ping` — GitHub's own automatic
+      # connectivity check, sent once when a webhook is first saved in
+      # repository settings — is answered here and never reaches a
+      # subclass at all; there is nothing domain-specific to decide
+      # about it.
+      class GithubWebhook
+        # **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
+        # a real 401 and a named reason, never a silent 200 that would
+        # let a forged "CI passed" payload regress nothing while looking
+        # exactly like success in a log nobody re-reads.
+        class InvalidSignature < StandardError; end
+
+        # **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
+        # 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
+        # `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
+        # 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.
+        def initialize(secret:)
+          raise ArgumentError, "no webhook secret configured" if secret.to_s.empty?
+
+          @secret = secret
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          return respond(405, error: "MethodNotAllowed", message: "POST only") unless request.post?
+
+          body = request.body.read
+          verify_signature!(request, body)
+
+          event = request.get_header(EVENT_HEADER)
+          return respond(200, ok: true, event: "ping") if event == "ping"
+          return respond(400, error: "MissingEvent", message: "no #{EVENT_HEADER} header") if event.to_s.empty?
+
+          payload = parse_json(body)
+          status, result = handle_event(event, payload["action"], payload)
+          respond(status, result)
+        rescue InvalidSignature => e
+          respond(401, error: "InvalidSignature", message: e.message)
+        rescue MalformedPayload => e
+          respond(400, error: "MalformedPayload", message: e.message)
+        end
+
+        private
+
+        # 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
+        # exactly the constant-time compare `Rack::Utils.secure_compare`
+        # already gives for free, reused rather than hand-rolled.
+        def verify_signature!(request, body)
+          header = request.get_header(SIGNATURE_HEADER)
+          raise InvalidSignature, "missing #{SIGNATURE_HEADER.sub('HTTP_', '').tr('_', '-')} header" if header.to_s.empty?
+
+          digest   = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @secret, body)
+          expected = "sha256=#{digest}"
+          return if Rack::Utils.secure_compare(expected, header)
+
+          raise InvalidSignature,
+                "signature does not match — refusing a payload that cannot be proven to be GitHub's own"
+        end
+
+        def parse_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise MalformedPayload, e.message
+        end
+
+        def handle_event(event, action, payload)
+          raise NotImplementedError, "#{self.class} must implement #handle_event(event, action, payload)"
+        end
+
+        def respond(status, body)
+          [status, { "content-type" => "application/json" }, [JSON.generate(body)]]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/dsl.rb

@@ -59,7 +59,7 @@ module Hecks
       # nothing and passes whenever dispatch doesn't raise; `count:` on a
       # command and `emits:` on a query are each read by neither runner
       # (Expectations#run_command/#run_query), so they're accepted here
-      # and then silently ignored at run time. Checking both at BUILD
+      # and then silently ignored at run time. Checking both at build
       # time, not in the runners, makes them errors on the file that
       # wrote them rather than green checks nobody questions.
       def validate_expect!
@@ -95,7 +95,7 @@ module Hecks
 
       def vision(text) = @vision = text
 
-      # Relative to THIS `.behaviors` file, never to the filesystem's cwd
+      # Relative to this `.behaviors` file, never to the filesystem's cwd
       # or a same-stem convention — scope is a fact this file declares,
       # not one a runner infers.
       def loads(*paths)