hecks 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2957772a5d25ada566a632461d6aa1829b6fb8016d4b563377ba7c856c1ed7d
-  data.tar.gz: 0e92b2b30420c37c8b92c087e26873223e47cdadcf88d7cbed1583b4a39729ee
+  metadata.gz: b85a8382bb201f9ab54417b3535d8fe1ede57c842f627e32a2ff75d7f2dd6618
+  data.tar.gz: e4852fd6b22145bec8a215e4c46fc6347527f7bd05811ff7da780e74dc24fe1d
 SHA512:
-  metadata.gz: 7a9641aeac769fa7e43131942276f8d5acf121daa2adc5b9d9e1375d5f509588ed3a5bd09b6995bb4c1214dd074dfe27666e8490a44e53f7042131a22f3fd8cd
-  data.tar.gz: 6cfb8e4e7852d8cbeaf417cf20ae952a94df5d3c12acf79cb8f4c4a0e454ca01a1e04d17956fa2de4f359776f3b6c3b66b199a0fa6eb8fcf7b4389bcdfc834d8
+  metadata.gz: a538ddbe90fed2ccfa8c066f00777699b0eadade3c6523e6fbf5f62c19385ab7ace8e2c8de6fabafffce46abbefd36642401f6e5f23696127445378e95d98aad
+  data.tar.gz: e22574943d4246998ba9121c0c84d7b39ec944416066ad881f144f166a09deb5c1a1fbb8b6c8378084b89856ed9a4e5bfd9c66a3cd6d07fa9a9a21eee77d63fc

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -17,8 +17,65 @@ module Hecks
           end
         end
 
+        # An EXPLICIT, opt-in maintenance operation — never run
+        # automatically after an ordinary save/delete. Heki's journal is
+        # not a disposable write-ahead log: it is this adapter's own
+        # answer to `entries`, and `entries` is a real port contract
+        # (`Ports::Persistence::AppendOnly`'s own required-methods list)
+        # read in full, forever, by `Ports::Projection::Worker#catch_up!`
+        # and `Registry#projection_current?` to catch a projection up to
+        # its authoritative source, and by `bin/history` to show "every
+        # journal entry a domain's append-only adapters hold" — the same
+        # contract Postgres/Sqlite/D1 uphold by way of a journal TABLE
+        # that is never pruned. A real example (`examples/banking`,
+        # `persisted_by("Heki")` + `projected_by("SqliteProjection")`)
+        # depends on this today. Compacting throws that full history away
+        # for whatever happened before the call — correct only for an
+        # aggregate nothing ever projects from; callers (`bin/
+        # heki_compact`) are responsible for confirming that first.
+        #
+        # Crash-safety ordering: `write` below is the exact same
+        # temp-file, fsync, atomic-rename sequence `save`/`delete`
+        # already use — the snapshot it produces is confirmed durably on
+        # disk before this method ever touches the journal. Only once
+        # that succeeds does `truncate_journal!` run. A crash between the
+        # two leaves old (now fully redundant) journal lines in place;
+        # replaying them again over the fresh snapshot on the next boot
+        # is idempotent — the same value gets set again, never a wrong
+        # one — so nothing is lost, just a little wasted replay work
+        # once. A crash before `write` completes leaves the journal
+        # fully intact and the prior snapshot untouched, exactly today's
+        # existing crash-recovery guarantee.
+        def compact!
+          with_lock do
+            current = replay_journal(read_snapshot)
+            write(current)
+            truncate_journal!
+            @store = current
+          end
+        end
+
         private
 
+        def truncate_journal!
+          return unless File.exist?(@journal_path)
+
+          # A single `truncate(0)` syscall on an already-open file
+          # descriptor — the file's length changes atomically at the
+          # filesystem level, so there is no "half truncated" state to
+          # observe even under a crash mid-call. `fsync` below makes
+          # that change durable before this method returns; without it
+          # a crash could still leave the old (harmless-to-replay)
+          # content on disk after a normal return, which is fine per
+          # the crash-safety note above, but the durable case is the
+          # one actually worth returning success for.
+          File.open(@journal_path, "r+b") do |file|
+            file.truncate(0)
+            file.flush
+            file.fsync
+          end
+        end
+
         def replay_journal(records)
           return records unless File.exist?(@journal_path)
 

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -20,11 +20,14 @@ module Hecks
         return yield unless @db.transaction_status == PG::PQTRANS_IDLE
 
         @db.transaction(&)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
       end
 
       def outbox_enqueue(rows)
         rows.filter_map do |row|
-          result = @db.exec_params(
+          result = pg_exec_params(
             "INSERT INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, status, attempts) " \
             "VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', 0) ON CONFLICT (delivery_id) DO NOTHING RETURNING id",
             [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer, JSON.generate(row.event)]
@@ -38,7 +41,7 @@ module Hecks
       end
 
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
-        @db.exec_params(
+        pg_exec_params(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
           "WHERE id = $1 AND status = 'pending'",
           [id]
@@ -46,7 +49,7 @@ module Hecks
       end
 
       def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
-        @db.exec_params(
+        pg_exec_params(
           "UPDATE hecks_outbox SET status = $2, error = $3, settled_at = now() WHERE id = $1",
           [id, status.to_s, error]
         ).cmd_tuples == 1
@@ -59,7 +62,7 @@ module Hecks
           sql << " AND status = $2"
           binds << status.to_s
         end
-        @db.exec_params("#{sql} ORDER BY id", binds).map do |row|
+        pg_exec_params("#{sql} ORDER BY id", binds).map do |row|
           Runtime::Outbox::Row.new(
             id: row["id"].to_i, delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
             domain: row["domain"], kind: row["kind"], consumer: row["consumer"],

data/lib/hecks/adapters/driven/postgres/reconnect.rb

@@ -0,0 +1,57 @@
+module Hecks
+  module Adapters
+    # SELF-HEALING CONNECTION — shared verbatim by `Postgres` and the era
+    # plugin's `PostgresEra`, the same way `PostgresOutbox` (outbox.rb) is:
+    # nothing here is lineage-specific, and `PostgresOutbox`'s own
+    # `@db.exec*` calls route through this module's `pg_exec`/
+    # `pg_exec_params` too, since both classes mix it in. Needs `@db` (a
+    # `PG::Connection`), `@aggregate`, and `@settings` from the including
+    # class — the same three `self.class.connect_for(@aggregate.name,
+    # @settings)` already needs to build one in the first place.
+    #
+    # A backend killed out from under an adapter (a DBA's own
+    # `pg_terminate_backend`, a load balancer's failover, a restart) —
+    # chaos-tested against the plain `Postgres` adapter: `PG::ConnectionBad`
+    # on the query that hit it, and PERMANENTLY on every query after,
+    # since nothing ever replaced `@db` with a live connection.
+    # `pg_exec`/`pg_exec_params` are the two primitives every other method
+    # in either class funnels through — wrapping them here, once,
+    # self-heals `@db` for the NEXT caller. THE CURRENT CALL STILL
+    # RAISES — reconnecting cannot tell a caller whether ITS OWN write
+    # reached the server before the connection died, so silently
+    # retrying it here could silently double it; that ambiguity is
+    # exactly why `Runtime::SagaInterpreter`'s own defect-retry exists
+    # ONE LAYER UP, where a dispatch is retried as a whole (fresh
+    # hydrate, fresh `given`s), not as a lone SQL statement.
+    module PostgresReconnect
+      def pg_exec(sql)
+        @db.exec(sql)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
+      end
+
+      def pg_exec_params(sql, binds)
+        @db.exec_params(sql, binds)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
+      end
+
+      private
+
+      # BEST-EFFORT — a reconnect attempt that itself fails (the server
+      # is actually down, not just this one backend) leaves `@db`
+      # unchanged; the `PG::ConnectionBad` already being re-raised by
+      # `pg_exec`/`pg_exec_params` above still reaches the caller either
+      # way, so swallowing a failed RECONNECT attempt here loses no
+      # information — it only avoids masking the original error with a
+      # second one.
+      def reconnect!
+        @db = self.class.connect_for(@aggregate.name, @settings)
+      rescue PG::Error
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -28,6 +28,25 @@ module Hecks
           # `persisted_fields` (Codec), so it never appears in `decode`'s
           # domain-state hash or `Instance#to_h`.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
+          # SAME SELF-HEALING SHAPE, FOR DOMAIN ATTRIBUTES THEMSELVES —
+          # `hecks_version` above only heals the adapter's own bookkeeping
+          # column; a bluebook attribute added (or, via `translations/`,
+          # renamed) after this table already exists is not bookkeeping,
+          # but the identical gap applies: `CREATE TABLE IF NOT EXISTS`
+          # is a no-op against the existing table, so without this a new
+          # attribute boots clean and then dies `PG::UndefinedColumn` on
+          # the first `project` — discovered chaos-testing a live rename
+          # against this adapter (no era, no translation prompt; those
+          # live in `PostgresEra` — this is the plain adapter's own,
+          # simpler contract: "the table always has every column the
+          # bluebook currently declares"). No `NOT NULL`, no `DEFAULT` —
+          # existing rows get SQL NULL for a column they never had a
+          # value for, exactly what a fresh row would get for an unset
+          # optional attribute (`encode_field`'s own nil handling).
+          persisted_fields.each do |field|
+            @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
+                     "#{quote_ident(field[:name])} #{field[:sql_type]}")
+          end
           # RIGHT HERE, NOT A SEPARATE STEP IN `Postgres#initialize` —
           # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
           # uses: index creation runs unconditionally, right after the

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

@@ -10,6 +10,7 @@ require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
 require_relative "postgres/outbox"
+require_relative "postgres/reconnect"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -46,6 +47,7 @@ module Hecks
       include SchemaBuilder
       include Codec
       include PostgresOutbox
+      include PostgresReconnect
 
       SQL_TYPES = { "Integer" => "bigint", "Float" => "double precision" }.freeze
 
@@ -93,6 +95,7 @@ module Hecks
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
+        @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
         # THE OPTIONAL saga-persistence capability's own scoping column
         # (§2/§4) — falls back to the aggregate's own storage name for a
@@ -118,7 +121,7 @@ module Hecks
       def table = @aggregate.storage_name
 
       def find(id)
-        result = @db.exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
+        result = pg_exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
         return nil if result.ntuples.zero?
 
         instance_from_row(result[0])
@@ -140,13 +143,13 @@ module Hecks
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
         end
 
-        @db.exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
+        pg_exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
       end
 
-      def count = @db.exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
+      def count = pg_exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
 
       def append(entry)
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES ($1, $2, $3, $4)",
           # `mirrors` (unlike `state`) is a NULLABLE column — an absent
           # mirrors hash must bind a real SQL NULL, not the four-character
@@ -178,7 +181,7 @@ module Hecks
       # rubocop:disable Metrics/AbcSize -- the CAS/plain upsert split is one
       # protocol; splitting it would hide the version handshake.
       def project(entry, expected_version: nil)
-        return @db.exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
+        return pg_exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
 
         instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
         columns  = (["id"] + persisted_fields.map { |field| field[:name].to_s } + ["hecks_version"])
@@ -195,7 +198,7 @@ module Hecks
         end
         sql += " RETURNING hecks_version"
 
-        result = @db.exec_params(sql, values)
+        result = pg_exec_params(sql, values)
         return nil if result.ntuples.zero?
 
         instance.version = result[0]["hecks_version"].to_i
@@ -204,7 +207,7 @@ module Hecks
       # rubocop:enable Metrics/AbcSize
 
       def entries
-        @db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
+        pg_exec("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",
@@ -216,8 +219,8 @@ module Hecks
       end
 
       def reset!
-        @db.exec("DELETE FROM #{quoted_table}")
-        @db.exec("DELETE FROM #{quoted_entry_table}")
+        pg_exec("DELETE FROM #{quoted_table}")
+        pg_exec("DELETE FROM #{quoted_entry_table}")
         self
       end
 
@@ -239,12 +242,12 @@ module Hecks
       def atomic_put(entry, insert_only: false)
         status = nil
         transaction do
-          @db.exec_params(
+          pg_exec_params(
             "SELECT pg_advisory_xact_lock(" \
             "hashtext(current_schema() || ':' || $1), hashtext($2))",
             [table, entry.id.to_s]
           )
-          exists = !@db.exec_params(
+          exists = !pg_exec_params(
             "SELECT 1 FROM #{quoted_table} WHERE id = $1",
             [entry.id.to_s]
           ).ntuples.zero?
@@ -269,14 +272,14 @@ module Hecks
       end
 
       def record_event(event)
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES ($1, $2, $3, $4, $5)",
           [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
         )
       end
 
       def events
-        @db.exec("SELECT * FROM events ORDER BY id").map do |row|
+        pg_exec("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
             name:        row["name"],
             aggregate:   row["aggregate"],
@@ -291,7 +294,7 @@ module Hecks
       # shape as PostgresEra's own (postgres_era.rb), not lineage-
       # specific, copied verbatim.
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
           "VALUES ($1, $2, $3, $4, $5, $6) " \
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
@@ -303,7 +306,7 @@ module Hecks
       end
 
       def delete_saga(process_manager:, correlation:)
-        @db.exec_params(
+        pg_exec_params(
           "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
           [@domain, process_manager.to_s, correlation.to_s]
         )
@@ -312,7 +315,7 @@ module Hecks
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
-        @db.exec_params(
+        pg_exec_params(
           "SELECT process_manager, correlation, state, memory, completed_compensations " \
           "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
@@ -381,7 +384,7 @@ module Hecks
       end
 
       def execute_query(sql, binds)
-        @db.exec_params(sql, binds).map { |row| instance_from_row(row) }
+        pg_exec_params(sql, binds).map { |row| instance_from_row(row) }
       end
 
       # Stamps `.version` (adapter bookkeeping, never domain state — see

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

@@ -14,4 +14,9 @@ Hecks.adapter "PostgresEra" do
   field :database
   field :role
   field :schema
+  # `allow_superuser true` — the explicit, on-the-record opt-in to boot
+  # over a connection whose role is a Postgres superuser or carries
+  # BYPASSRLS, which the era write-fence (row-level security) cannot
+  # bite. Refused by default; see `Lineage#check_fence_applies!` (BUG#24).
+  field :allow_superuser
 end

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

@@ -67,7 +67,10 @@ module Hecks
         # reads it — not the identity unwrap, which is gone : an identity is
         # declared as a path and followed.
         reference_id = args.fetch(model.reference_name).to_s
-        eligible = model.filtered_head_name
+        # Plural (ADR 0055) — `on:` lets `where`/`order_by`/`limit`/`offset`
+        # each name a different many-side head, so more than one can be
+        # eligible in the same read model now.
+        eligible = model.filtered_head_names
 
         # ROOT FIRST, ALWAYS — see this method's own header. Mirrors
         # `ReadModelInterpreter#project`'s identical partition, for the
@@ -87,7 +90,7 @@ module Hecks
                  else
                    select_related(aggregate, projected)
                  end
-          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          rows = Ports::Query::InMemory.execute(rows, model.options_for(head[:as]), args) if eligible.include?(head[:as])
           projected << { aggregate: head[:aggregate], rows: rows }
           reports[head[:as]] = if head[:many]
                                  rows.map { |row| Runtime::Value.materialize(row.to_h) }

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/expectations.rb

@@ -194,11 +194,24 @@ module Hecks
       # mixed facts into the strict envelope — identities lifted into
       # `to:`, declared facts into `with:` — so a behaviors dispatch now
       # goes through the exact same separation a policy's projection
-      # does. A verb that resolves to no command (a port operation —
-      # "Pizzas::Order.PaymentGateway.Receive") keeps the loose
-      # passthrough: its own input already spells the port form's
-      # `to:`/`with:`, which the dispatcher's port branch reads directly.
+      # does. A verb that names a port operation (checked explicitly,
+      # below — "Pizzas::Order.PaymentGateway.Receive") keeps the loose
+      # passthrough instead: its own input already spells the port
+      # form's `to:`/`with:`, which the dispatcher's port branch reads
+      # directly, and `ReactionInvocation.build`'s explicit envelope
+      # expects a command's own declared attributes at the top level,
+      # not a port operation's already-wrapped `to:`/`with:` shape.
+      #
+      # THIS USED TO RELY ON `resolve_target` RAISING `UnknownVerb` for
+      # any port-operation verb — true only so long as nothing else ever
+      # asked it to resolve one. Now that a `policy` can legitimately
+      # `trigger` a port operation (`ReactionInvocation#resolve_target`'s
+      # own port-operation branch), that raise is gone, so this checks
+      # for a port operation directly instead of leaning on a refusal
+      # that no longer happens.
       def dispatch_command(runtime, verb, args)
+        return runtime.dispatch(verb, **args) if port_operation?(runtime, verb)
+
         invocation = begin
           Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
                                             projected: args, explicit: true)
@@ -214,6 +227,21 @@ module Hecks
         end
       end
 
+      # THE SAME "Head.Rest" SHAPE `Dispatcher#dispatch` AND
+      # `ReactionInvocation#resolve_target` BOTH ALREADY CHECK — a bare
+      # domain/aggregate lookup plus a port-name lookup, no command
+      # resolution needed since all this asks is whether one exists.
+      def port_operation?(runtime, verb)
+        domain, aggregate_name, command_path = Naming.split_verb(verb)
+        return false unless command_path
+
+        aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        return false unless aggregate
+
+        head, rest = command_path.split(".", 2)
+        rest && !!aggregate.port(head)
+      end
+
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 

data/lib/hecks/bluebook/assembly/marks.rb

@@ -170,9 +170,19 @@ module Hecks
         # a saga with nothing to do.
         def read(value) = Literal.read(value)
 
+        # `target:` (ADR 0055) — read straight off the wire, unconverted:
+        # it's already the bare aggregate-name STRING `WhereClause#to_h`/
+        # `OrderBy#to_h`/`LimitSpec#to_h` wrote (`resolve_target`'s own
+        # `Naming.demodulise` already ran once, at DSL-build time; this is
+        # the REPLAY path every real boot actually goes through, reading
+        # that same wire shape back — see this class's own header). Absent
+        # from `clause`/`declared` entirely on older wire data that never
+        # declared `on:` — `clause[:target]`/`declared[:target]` reads
+        # `nil` for a missing key exactly like an explicit `nil` would,
+        # so this is additive, not a migration.
         def where_clause(clause)
           QuerySpecification::Common::WhereClause.new(
-            field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value])
+            field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value]), target: clause[:target]
           )
         end
 
@@ -180,14 +190,14 @@ module Hecks
           return nil unless declared
 
           QuerySpecification::Common::OrderBy.new(
-            field: declared[:field], direction: declared[:direction].to_sym
+            field: declared[:field], direction: declared[:direction].to_sym, target: declared[:target]
           )
         end
 
         def limit(declared)
           return nil unless declared
 
-          QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]))
+          QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]), target: declared[:target])
         end
 
         # EVERY OTHER SPECIFICATION OPTION, from one table.

data/lib/hecks/bluebook/behaviour/domain_port.rb

@@ -11,9 +11,33 @@ module Hecks
         # what it acts for, and `identity_attribute` is how that is found.
         def references = nil
 
+        # NEVER a creating command — a port operation always acts on an
+        # aggregate that already exists (`operation.to`/`identity_attribute`
+        # both name where its RECEIVER comes from, never a birth). Answered
+        # explicitly, not derived from `references` the way `Command
+        # #creates?` is (`references.nil?` would read every operation as
+        # creating, since `references` above is unconditionally nil) —
+        # needed so `ReactionInvocation#source_receiver_for` can call
+        # `target.command.creates?` on a port operation the same way it
+        # already does on an ordinary command, and correctly lift a
+        # same-aggregate policy's own Event.id as the operation's receiver.
+        def creates? = false
+
         def identity_attribute(owner_name)
           @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
         end
+
+        # THE SAME READING `Command#addressing_key_for` gives, minus its
+        # self-addressing branch — a port operation's `references` is
+        # unconditionally nil (above), so it never means "this verb is
+        # declared ON the very aggregate it acts on" the way a command's
+        # does; a port operation's only path back to its owner is a real,
+        # declared reference-typed attribute, which is exactly what
+        # `identity_attribute` already finds. Needed for the identical
+        # reason `Command#addressing_key_for` is: `ReactionInvocation
+        # #aggregate_aliases` calls it on whatever `target.command` holds,
+        # a `PortOperation` now included since a policy can trigger one.
+        def addressing_key_for(aggregate_name) = identity_attribute(aggregate_name)&.name
       end
 
       # WHAT A PORT DOES — one finder over its declared operations.