hecks 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d13701a926b6be040b496d5e582a9d4fd99ad878372f5345636ef074aa6e4e8
-  data.tar.gz: 95fc7593502393bd0d698aeaac1b9419dc6e00b78e12f11ad6740a2008a0df0e
+  metadata.gz: 0d66cdbdb775a92f3cfcf3f626637cffd6fb81915d7edbcccfe21e1b7c980606
+  data.tar.gz: a43786075ea299d26d6d1f23075cf2176fdad15b7efa235234c4a6e321ec15f3
 SHA512:
-  metadata.gz: 9b65062cd42566cb0f2e4d5c45b12b1990133850964e117a6827b917d5b293245855a292ccd698c12d982de268a1554029a7a079a03c2cd7e99148eba1f7af47
-  data.tar.gz: 9b98481d47cfcbd09e72e5d53226287fbed298d2d1ae77ebbd48b133c7fb9100be1531daca0be92728976ef11eb87979e5847306b4eed628308dfebfdf83014f
+  metadata.gz: ac3883e9e6ebeef723718dfa39785d2dcdd0e57e613f6ca21a9519040eb11278f22eedbe597965d1b28e3dfa08b98ac2d0a989686cd7b8aec0d8d97dd476acec
+  data.tar.gz: f610074205ca1a39121169ef02109445b60ca66bf517c1a8351e8c761a1863fccfe0f9b41075fa00cc8225c017c82eefdb47c38566469fe378d0879aec115860

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

@@ -36,7 +36,7 @@ module Hecks
 
       SYSTEM_PREFIX = "You are assisting a domain-modeling interview for the hecks " \
                       "event-sourced framework. Reply with EXACTLY ONE JSON object, no prose " \
-                      "before or after it, no markdown code fence. "
+                      "before or after it, no markdown code fence. ".freeze
 
       module_function
 
@@ -97,13 +97,13 @@ module Hecks
       # ── transport ───────────────────────────────────────────────────
 
       def call(system:, payload:)
-        stdout, status = Timeout.timeout(TIMEOUT_SECONDS) {
+        stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
           Open3.capture2(
             "claude", "-p", "--output-format", "json",
             "--append-system-prompt", system, "--allowedTools", "",
             stdin_data: JSON.generate(payload)
           )
-        }
+        end
         raise Ports::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
 
         unwrap(stdout)

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

@@ -31,7 +31,7 @@ module Hecks
       # per execute, not a persistent connection — D1 has no connection to
       # hold open.
       class Connection
-        ENDPOINT = "https://api.cloudflare.com/client/v4"
+        ENDPOINT = "https://api.cloudflare.com/client/v4".freeze
 
         def initialize(account_id:, database_id:, api_token:)
           @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
@@ -65,36 +65,41 @@ module Hecks
           request.body = JSON.generate(payload)
 
           response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: true) { |http| http.request(request) }
-          body =
-            begin
-              JSON.parse(response.body)
-            rescue JSON::ParserError
-              raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
-            end
+          body = parse_d1_body(response)
+          messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
 
-          unless body["success"]
-            messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
-            raise Runtime::WiringError, "D1 query failed: #{messages.empty? ? response.body : messages}"
-          end
+          raise Runtime::WiringError, "D1 query failed: #{messages.empty? ? response.body : messages}" unless body["success"]
 
           results = body.fetch("result")
           failed = results.find { |result| result["success"] == false }
-          if failed
-            messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
-            detail =
-              if failed.key?("error")
-                failed["error"]
-              elsif failed.key?("message")
-                failed["message"]
-              else
-                messages
-              end
-            raise Runtime::WiringError, "D1 query failed: #{detail.to_s.empty? ? 'a batched statement failed' : detail}"
-          end
+          raise Runtime::WiringError, "D1 query failed: #{failed_statement_detail(failed, messages)}" if failed
 
           results
         end
 
+        def parse_d1_body(response)
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
+        end
+
+        # `messages` is the whole-response :errors fallback, tried LAST —
+        # a per-statement `failed["error"]`/`failed["message"]` (checked
+        # by key presence, not truthiness, so an explicit `nil` still
+        # counts as "the key was there") is always more specific to WHICH
+        # statement failed, when either is present.
+        def failed_statement_detail(failed, messages)
+          detail =
+            if failed.key?("error")
+              failed["error"]
+            elsif failed.key?("message")
+              failed["message"]
+            else
+              messages
+            end
+          detail.to_s.empty? ? "a batched statement failed" : detail
+        end
+
         public
 
         def get_first_row(sql, binds = [])
@@ -170,7 +175,10 @@ module Hecks
         order_sql = "ORDER BY id"
         if order_by
           name = order_by.to_s.split(".").first
-          raise Runtime::WiringError, "#{@aggregate.name} has no attribute #{order_by.inspect} to order by" unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+            raise Runtime::WiringError,
+                  "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
+          end
 
           spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
@@ -256,6 +264,16 @@ module Hecks
       # matching Sqlite#atomic_put's `next` (skip append AND project both,
       # together) with no second HTTP call and no gap for another writer to
       # land in between the check and the write.
+      # Three SQL statements, built here and batched together as ONE
+      # transaction below — see the comment above on the real TOCTOU gap
+      # this exact shape closes (the existence check moved INSIDE the
+      # batch, not run as a separate earlier round trip). Splitting the
+      # per-statement builders out would still need columns/values/slots/
+      # not_exists/quoted_table threaded into each, and would separate
+      # three pieces of ONE atomic batch across methods with no single
+      # place left to see that they are, together, the fix.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/MethodLength
       def atomic_put(entry, insert_only: false)
         instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
         columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
@@ -343,9 +361,10 @@ module Hecks
       # already uses through `Connection#execute`.
       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, completed_compensations) " \
-          "VALUES (?, ?, ?, ?, ?, ?)",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, " \
+          "completed_compensations) VALUES (?, ?, ?, ?, ?, ?)",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       end
 
@@ -360,7 +379,8 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.execute(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = ?",
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = ?",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],

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

@@ -2,10 +2,17 @@ require_relative "../../vocabulary"
 
 module Hecks
   module Adapters
+    # The filesystem-backed loader — glob-and-`Kernel.load` a domain's own
+    # `.port`/`.adapter`/`.bluebook`/`.hecksagon`/`.world`/environment-overlay
+    # files off disk, in the order `Vocabulary.fetch("LoadOrder")` requires,
+    # and locate a domain's own root directory by walking up from any file
+    # inside it looking for a `.hecksagon`. What `Hecks.boot(path)` uses when
+    # a caller names a directory rather than an explicit file list (see
+    # `Loader.boot_files` for that other path).
     class Folder
       DOMAIN_ORDER = Hecks::Vocabulary.fetch("LoadOrder")
-      PORTS        = "ports"
-      ADAPTERS     = "adapters"
+      PORTS        = "ports".freeze
+      ADAPTERS     = "adapters".freeze
 
       def initialize(settings: {}, root: nil)
         @settings = settings
@@ -117,7 +124,7 @@ module Hecks
         return unless File.directory?(directory)
 
         patterns.each do |pattern|
-          Dir[File.join(directory, pattern)].sort.each { |file| Kernel.load(file) }
+          Dir[File.join(directory, pattern)].each { |file| Kernel.load(file) }
         end
       end
 

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

@@ -30,7 +30,7 @@ module Hecks
     # no defaults, on purpose: a login mechanism silently
     # half-configured is worse than one that refuses to boot at all.
     module GoogleAuthentication
-      ISSUER = "https://accounts.google.com"
+      ISSUER = "https://accounts.google.com".freeze
 
       module_function
 
@@ -80,9 +80,7 @@ module Hecks
         require "oauth2"
         require "google-id-token"
 
-        unless state && expected_state && state == expected_state
-          raise Ports::Authentication::ValidationError, "state mismatch"
-        end
+        raise Ports::Authentication::ValidationError, "state mismatch" unless state && expected_state && state == expected_state
 
         token = client.auth_code.get_token(code, redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"))
         id_token = token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"

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

@@ -29,7 +29,7 @@ module Hecks
             case entry.fetch("operation")
             when "save"   then records[id] = entry.fetch("state")
             when "delete" then records.delete(id)
-            else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch("operation").inspect}"
+            else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch('operation').inspect}"
             end
           end
           records

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

@@ -18,12 +18,12 @@ module Hecks
       include Snapshot
       include Journal
 
-      MAGIC = "HEKI"
+      MAGIC = "HEKI".freeze
       HEADER_BYTES = 8
 
       class Malformed < StandardError; end
 
-      attr_reader :aggregate, :path
+      attr_reader :aggregate, :path, :events
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
@@ -114,8 +114,6 @@ module Hecks
 
       def record_event(event) = @events << event
 
-      def events = @events
-
       # ── the OPTIONAL saga-persistence capability (§2) — Heki's own
       # shape (a sibling snapshot+journal file pair, `SagaStore`,
       # heki/saga_store.rb) rather than a table in a store this adapter
@@ -128,7 +126,7 @@ module Hecks
         saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
       end
 
-      def each_saga(&block) = saga_store.each_saga(@domain, &block)
+      def each_saga(&) = saga_store.each_saga(@domain, &)
 
       private
 

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

@@ -24,7 +24,10 @@ module Hecks
         return records unless order_by
 
         name = order_by.to_s.split(".").first
-        raise Runtime::WiringError, "#{aggregate.name} has no attribute #{order_by.inspect} to order by" unless aggregate.lifecycle&.field.to_s == name || aggregate.attribute(name)
+        unless aggregate.lifecycle&.field.to_s == name || aggregate.attribute(name)
+          raise Runtime::WiringError,
+                "#{aggregate.name} has no attribute #{order_by.inspect} to order by"
+        end
 
         path = sortable_path(aggregate, order_by)
         spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)

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

@@ -123,11 +123,11 @@ module Hecks
       # full "Domain::Aggregate#id" string — callers already know which
       # aggregate they're asking this instance about.
       def instances
-        @client.read.fetch("instances", {}).filter_map { |key, state|
+        @client.read.fetch("instances", {}).filter_map do |key, state|
           next unless key.start_with?(@prefix)
 
           [key.delete_prefix(@prefix), build_instance(key.delete_prefix(@prefix), state)]
-        }.to_h
+        end.to_h
       end
 
       # Lambda's own JSON response is already Ruby-decoded with STRING

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

@@ -0,0 +1,3 @@
+Hecks.adapter "LocalStorage" do
+  port "persistence"
+end

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

@@ -0,0 +1,120 @@
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/query/in_memory"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # A BROWSER-HOSTED DOMAIN'S OWN DECLARED INTENT — not a second Memory
+    # wearing a different name. Ruby has no way to reach a real browser's
+    # `window.localStorage` at all (it is per-tab, per-origin, JS-only,
+    # unreachable over any network the way D1's own REST API is) — so
+    # this Ruby-side adapter is honestly a stand-in: in-process, ephemeral,
+    # mechanically identical to Memory. What earns it a name of its own
+    # is what it DECLARES, not what it happens to do in Ruby: `persisted_by
+    # "LocalStorage"` says "this domain expects real, durable, single-
+    # device storage the moment it's actually running where it's meant to
+    # run" — the same distinction Heki (real local durability) already
+    # draws against Memory (deliberately ephemeral, test/example-only),
+    # one adapter over. `bin/console`, the fuzzer, `spec/`, `bin/
+    # model_check` all get a domain that boots and behaves correctly
+    # against this adapter; only a real browser gets the real durability.
+    #
+    # THE REAL BROWSER HALF lives outside this file entirely: `rust/web`'s
+    # `dispatch(json)` (docs/implemented/decisions/0015) takes an optional
+    # `"seed"` (the exact `"instances"` shape it also answers with) plus
+    # `"steps"` — a host rehydrates from a prior snapshot and replays only
+    # the new command(s), rather than the whole history every call. A
+    # page bound to this adapter is expected to hold that snapshot in
+    # `window.localStorage` itself (get on load, set after every
+    # `dispatch`) — the seed/instances round trip IS the adapter, once
+    # you're in the one runtime that can actually reach the storage this
+    # name promises.
+    class LocalStorage
+      # TENANT-CAPABLE TRIVIALLY, same reasoning as Memory's own — a
+      # browser tab is exactly one origin, exactly one user; there is no
+      # second tenant this in-process Hash could ever confuse a first
+      # one with.
+      def self.tenant_capable? = true
+      def persistence_capabilities = [:atomic_put]
+
+      attr_reader :aggregate, :events
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        @records   = {}
+        @events    = []
+        @entries   = []
+      end
+
+      def find(id) = @records[id.to_s]
+      def count    = @records.size
+
+      def all(order_by: nil, direction: :asc)
+        InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      # THE DECISION THE GUIDE ASKS FOR, MADE EXPLICITLY: no compiled
+      # dialect of its own, same as Heki/Memory — a personal-scale local
+      # store answering by walking `all` is correct on day one, and
+      # nothing about a browser tab's own data volume asks for pushdown.
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
+      end
+
+      def append(entry)
+        @entries << entry
+        entry
+      end
+
+      def project(entry)
+        if entry.save?
+          @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state.dup)
+        else
+          @records.delete(entry.id)
+        end
+      end
+
+      def save(instance)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        append(entry)
+        project(entry)
+      end
+
+      def atomic_put(entry, insert_only: false)
+        exists = @records.key?(entry.id.to_s)
+        return :conflicted if insert_only && exists
+
+        status = exists ? :replaced : :inserted
+        append(entry)
+        project(entry)
+        status
+      end
+
+      def delete(id)
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+      end
+
+      def record_event(event) = @events << event
+
+      def entries = @entries.dup
+
+      def reset!
+        @records = {}
+        @events  = []
+        @entries = []
+        self
+      end
+
+      # NOT lineage_capable? — deliberately absent, the same trade Heki
+      # makes and states plainly (writing-an-adapter.md's own section on
+      # it): a domain bound here has no edge for its own shape to travel
+      # across if it ever changes; that must be hand-migrated, or the
+      # shape must not change. A browser-local personal store is exactly
+      # the small-adapter case that guide names as a fine place to make
+      # that trade.
+    end
+  end
+end

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

@@ -5,6 +5,13 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
+    # The default, no-external-dependency persistence/query adapter — a
+    # plain in-process Hash of `Runtime::Instance` records per aggregate,
+    # with an append-only `@entries`/`@events` log alongside it. Every
+    # behaviors suite must resolve to this one (see
+    # Behaviors::Expectations#guard_memory_only!) precisely because a fresh
+    # instance really is a fresh store, with nothing shared across tests or
+    # tenants.
     class Memory
       # TENANT-CAPABLE TRIVIALLY — see Runtime::TenantCheck's own header
       # for the full reasoning. `@records` is a plain instance variable;
@@ -15,13 +22,14 @@ module Hecks
       def self.tenant_capable? = true
       def persistence_capabilities = [:atomic_put]
 
-      attr_reader :aggregate
+      attr_reader :aggregate, :events
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @records   = {}
         @events    = []
         @entries   = []
+        @outbox    = []
       end
 
       def find(id) = @records[id.to_s]
@@ -75,8 +83,6 @@ module Hecks
 
       def record_event(event) = @events << event
 
-      def events = @events
-
       def entries = @entries.dup
 
       # Every other driven adapter (Postgres/PostgresEra/Sqlite/D1)
@@ -96,8 +102,47 @@ module Hecks
         @records = {}
         @events  = []
         @entries = []
+        @outbox  = []
         self
       end
+
+      # No rollback here — a Hash has no transaction to join. Memory
+      # implements `transaction` so `Interpreting#run_dispatch_order` has
+      # one shape to call, and the outbox so a spec can watch rows move
+      # pending → claimed → delivered without a database (the same
+      # reason Memory records `events`). See `Runtime::Outbox`.
+      def transaction = yield
+
+      def outbox_enqueue(rows)
+        rows.filter_map do |row|
+          next nil if @outbox.any? { |held| held.delivery_id == row.delivery_id }
+
+          row.id = @outbox.size + 1
+          @outbox << row
+          row
+        end
+      end
+
+      def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+        row = @outbox.find { |held| held.id == id }
+        return false unless row&.pending?
+
+        row.status = "claimed"
+        row.attempts += 1
+        true
+      end
+
+      def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+        row = @outbox.find { |held| held.id == id } or return false
+        row.status = status.to_s
+        row.error  = error
+        true
+      end
+
+      def outbox_rows(status: nil)
+        rows = status ? @outbox.select { |row| row.status == status.to_s } : @outbox
+        rows.map(&:dup)
+      end
     end
   end
 end

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

@@ -20,7 +20,9 @@ module Hecks
             { name: attribute.name, attribute: attribute, sql_type: sql_type(attribute) }
           end
           lifecycle = @aggregate.lifecycle
-          fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && !fields.any? { |field| field[:name] == lifecycle.field }
+          fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && fields.none? do |field|
+            field[:name] == lifecycle.field
+          end
           # `projects` FIELDS (S12, ADR 0025) ARE A LOCAL COLUMN TOO — see
           # Sqlite::Codec#persisted_fields' own comment; identical reasoning,
           # `text` to match this file's own lowercase SQL type spelling.

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

@@ -0,0 +1,100 @@
+require "json"
+require_relative "../../../runtime/outbox"
+
+module Hecks
+  module Adapters
+    # THE OUTBOX, POSTGRES-SHAPED — shared verbatim by `Postgres` and the
+    # era plugin's `PostgresEra`, the same way their `events` and
+    # `hecks_saga_instances` DDL is copied between them: nothing here is
+    # lineage-specific. Needs `@db` (a `PG::Connection`) and `table`
+    # (the aggregate's storage name) from the including class. See
+    # `Runtime::Outbox` for what the four verbs mean, and Sqlite's copy
+    # for the SQL idioms (`ON CONFLICT DO NOTHING` = idempotent enqueue,
+    # `WHERE status = 'pending'` = the compare-and-set claim).
+    module PostgresOutbox
+      # RE-ENTRANT — `Interpreting#run_dispatch_order` opens one
+      # transaction around save+emit+outbox and the adapter's own
+      # `append`/`atomic_put`/`delete` each open theirs; PG refuses
+      # BEGIN inside BEGIN, so an inner call joins the open one.
+      def transaction(&)
+        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 = 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)]
+          )
+          next nil if result.ntuples.zero?
+
+          row.id = result[0]["id"].to_i
+          row.status = "pending"
+          row
+        end
+      end
+
+      def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+        pg_exec_params(
+          "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
+          "WHERE id = $1 AND status = 'pending'",
+          [id]
+        ).cmd_tuples == 1
+      end
+
+      def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+        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
+      end
+
+      def outbox_rows(status: nil)
+        sql   = "SELECT * FROM hecks_outbox WHERE aggregate = $1"
+        binds = [table]
+        if status
+          sql << " AND status = $2"
+          binds << status.to_s
+        end
+        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"],
+            event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
+            attempts: row["attempts"].to_i, error: row["error"]
+          )
+        end
+      end
+
+      private
+
+      def create_outbox_table!
+        @db.exec(<<~SQL)
+          CREATE TABLE IF NOT EXISTS hecks_outbox (
+            id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            delivery_id  text NOT NULL UNIQUE,
+            event_uid    text NOT NULL,
+            aggregate    text NOT NULL,
+            domain       text NOT NULL,
+            kind         text NOT NULL,
+            consumer     text NOT NULL,
+            event        jsonb NOT NULL,
+            status       text NOT NULL DEFAULT 'pending',
+            attempts     integer NOT NULL DEFAULT 0,
+            error        text,
+            enqueued_at  timestamptz NOT NULL DEFAULT now(),
+            claimed_at   timestamptz,
+            settled_at   timestamptz
+          )
+        SQL
+        @db.exec("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
+      end
+    end
+  end
+end

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