hecks 1.0.2 → 1.2.0

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

@@ -17,7 +17,7 @@ module Hecks
         def create_aggregate_table!
           columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
           @db.exec(
-            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
           # SELF-HEALING, SAME IDIOM AS `ensure_indexes!` BELOW —
           # `CREATE TABLE IF NOT EXISTS` above does NOT retroactively add a
@@ -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
@@ -84,7 +103,8 @@ module Hecks
           # — the same idiom `rust/host/src/journal.rs`'s own
           # `sagas_backfilled` column addition already uses, for the
           # identical reason.
-          @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb NOT NULL DEFAULT '[]'::jsonb")
+          @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
+                   "NOT NULL DEFAULT '[]'::jsonb")
         end
 
         def sql_type(attr)

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

@@ -9,6 +9,8 @@ require_relative "../../query_specification/common/order_by"
 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
@@ -44,6 +46,8 @@ module Hecks
       include SqlQueryBuilder
       include SchemaBuilder
       include Codec
+      include PostgresOutbox
+      include PostgresReconnect
 
       SQL_TYPES = { "Integer" => "bigint", "Float" => "double precision" }.freeze
 
@@ -84,13 +88,14 @@ module Hecks
         # boot after the first, not news.
         connection.exec("SET client_min_messages = warning")
         connection
-      rescue PG::Error => error
+      rescue PG::Error => e
         raise Runtime::WiringError,
-              "cannot bind Postgres at #{declared} for #{name}: #{error.message.strip}"
+              "cannot bind Postgres at #{declared} for #{name}: #{e.message.strip}"
       end
 
       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
@@ -110,12 +115,13 @@ module Hecks
         create_entry_table!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
       end
 
       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])
@@ -128,19 +134,22 @@ 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)}"
         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
@@ -169,8 +178,10 @@ module Hecks
       # zero rows back means the conflict branch's WHERE excluded the row
       # entirely — the version had already moved — so `nil` is returned
       # for the caller (`AppendOnly#save`) to treat as "stale, no-op".
+      # 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"])
@@ -187,15 +198,16 @@ 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
         instance
       end
+      # 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",
@@ -207,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
 
@@ -221,24 +233,21 @@ module Hecks
       # transaction lives here, the one caller that runs both together.
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
-        @db.transaction { append(entry); project(entry) }
+        transaction do
+          append(entry)
+          project(entry)
+        end
       end
 
-      # Classification, journal append and snapshot replacement are one
-      # Postgres transaction. A row lock cannot serialize two first writers —
-      # there is no row to lock yet — so a transaction-scoped advisory lock on
-      # schema/table + aggregate id owns that missing-row race as well. Once a
-      # writer acquires it, the preceding writer has committed and status can
-      # be read from the materialized table without a runtime-side find.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
-          @db.exec_params(
+        transaction do
+          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?
@@ -255,19 +264,22 @@ module Hecks
 
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
-        @db.transaction { append(entry); project(entry) }
+        transaction do
+          append(entry)
+          project(entry)
+        end
         true
       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"],
@@ -282,18 +294,19 @@ 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 " \
           "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
           "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       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]
         )
@@ -302,8 +315,9 @@ module Hecks
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
-        @db.exec_params(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = $1",
+        pg_exec_params(
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
@@ -370,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/prism.rb

@@ -5,7 +5,18 @@ module Hecks
   module Adapters
     class NotExtractable < StandardError; end
 
+    # Extracts a `given`/`ensures`/invariant block's own source text back out
+    # of the `.rb` file it was defined in (via `block.source_location`),
+    # parses it with the `prism` gem, and canonicalises it — how a rule's
+    # predicate becomes readable, comparable text (era diffing, docs) rather
+    # than an opaque compiled Proc. Per-process `TREES` cache keyed by file
+    # path; `forget`/`forget_all` exist for a caller that reloads an edited
+    # file in-process (see their own comment).
     module Prism
+      # NOT frozen — a real cache, keyed by file path and mutated by
+      # #tree_for below (`TREES[file] ||= ...`) and #forget/#forget_all.
+      # False positive for Style/MutableConstant.
+      # rubocop:disable-next Style/MutableConstant
       TREES = {}
 
       module_function

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

@@ -34,24 +34,11 @@ module Hecks
       }.freeze
 
       def query(declared, args = {}, context: {})
-        sql = +"SELECT #{select_list} FROM #{from_relation}"
-        clauses = []
+        sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
-        declared.wheres.each do |clause|
-          value = query_value(clause.value, args)
-          expression = query_expression(clause.field, value: value)
-          if (null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value))
-            clauses << null_predicate.first
-            next
-          end
-          clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
-        end
+        clauses = where_clauses(declared, args, binds)
         sql << " WHERE #{clauses.join(' AND ')}" unless clauses.empty?
-        sql << if declared.order_by
-                 " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
-               else
-                 " ORDER BY id"
-               end
+        sql << order_by_sql(declared)
         sql << " LIMIT #{placeholder(binds, query_value(declared.limit.value, args).to_i)}" if declared.limit
         # An offset with no declared limit — SQLite refuses a bare OFFSET
         # outright (LIMIT -1 is its unbounded idiom) while Postgres accepts
@@ -65,10 +52,34 @@ module Hecks
 
       private
 
-      def where_clause(op, expression, value, binds, field: nil)
-        case op
+      # Every declared `where` clause, compiled in declaration order — a
+      # null-policy predicate short-circuits the ordinary comparator path
+      # per clause, same as it did inline. `binds` is populated in place
+      # (the same array `query` goes on to push LIMIT/OFFSET placeholders
+      # into afterward), so pulling this loop out changes nothing about
+      # bind-parameter order.
+      def where_clauses(declared, args, binds)
+        declared.wheres.each_with_object([]) do |clause, clauses|
+          value = query_value(clause.value, args)
+          expression = query_expression(clause.field, value: value)
+          if (null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value))
+            clauses << null_predicate.first
+            next
+          end
+          clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
+        end
+      end
+
+      def order_by_sql(declared)
+        return " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}" if declared.order_by
+
+        " ORDER BY id"
+      end
+
+      def where_clause(oper, expression, value, binds, field: nil)
+        case oper
         when "eq", "ne", "gt", "gte", "lt", "lte"
-          "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(op)} #{placeholder(binds, value)}"
+          "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(oper)} #{placeholder(binds, value)}"
         when "contains"
           member = field && list_member(field)
           if member
@@ -97,7 +108,7 @@ module Hecks
           # which Postgres overrides to cast numerics.
           "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
         else
-          raise ArgumentError, "#{dialect_name} query adapter does not support #{op.inspect}"
+          raise ArgumentError, "#{dialect_name} query adapter does not support #{oper.inspect}"
         end
       end
 
@@ -137,6 +148,16 @@ module Hecks
       # path that can never match. Measured, not assumed: a `where` on a
       # has_one/belongs_to/reference_to field returned zero rows against
       # real data until that exclusion was removed.
+      # `member` resolves through two ORDERED fallback tiers — the bound
+      # value's own numeric field first, then the declared value object's
+      # numeric-or-sole attribute — each documented above as fixing a
+      # real, measured bug (a reference field matching nothing, a
+      # single-attribute VO silently falling to the wrong convention).
+      # Splitting the tiers apart would separate two writes to the same
+      # `member` local across method boundaries, hiding the fallback
+      # order that makes them correct together.
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def query_expression(field, value: nil)
         name, *path = field.to_s.split(".")
         attribute = @aggregate.attribute(name)
@@ -147,6 +168,10 @@ module Hecks
         member = if path.empty? && value
                    hash = value.is_a?(Runtime::Value) ? value.to_h : value
                    numeric = hash.is_a?(Hash) && hash.find { |_key, item| item.is_a?(Numeric) }
+                   # NOT &.-able: `numeric` can be `false` (hash.is_a?(Hash) came
+                   # back false) as well as nil (.find came back empty) — `&.`
+                   # only guards nil, so `false.first` raises. False positive.
+                   # rubocop:disable-next Style/SafeNavigation
                    numeric ? numeric.first : nil
                  end
         member ||= if path.empty? && attribute && value_object?(attribute)

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

@@ -13,7 +13,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 —
           # `CommandInterpreter#seed_projected_fields`/`RebuildSweep`
           # both write one straight into `Instance#state` the same as

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) }
@@ -140,8 +143,15 @@ module Hecks
       end
 
       def decode_for(aggregate, row)
+        decode_fields(fields_for(aggregate), aggregate, row)
+      end
+
+      # The field list a row decodes against: every declared attribute,
+      # plus the lifecycle field and any `projects` fields not already
+      # among them (both read back raw — see `decode_fields`).
+      def fields_for(aggregate)
         fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
-        if (lifecycle = aggregate.lifecycle) && !fields.any? { |name, _| name == lifecycle.field }
+        if (lifecycle = aggregate.lifecycle) && fields.none? { |name, _| name == lifecycle.field }
           fields << [lifecycle.field, nil]
         end
         # `projects` FIELDS (S12, ADR 0025) NEED READING BACK TOO — `project`
@@ -154,8 +164,16 @@ module Hecks
         aggregate.projected_fields.each do |field|
           fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
         end
+        fields
+      end
+
+      def decode_fields(fields, aggregate, row)
         fields.each_with_object({}) do |(name, attribute), state|
           raw = row[name.to_s]
+          # rubocop:disable Lint/DuplicateBranch -- the nil-attribute and
+          # reference-id branches both just answer `raw`, coincidentally, for
+          # two unrelated reasons (see each branch's own comment); merging
+          # them would blur that distinction.
           state[name] =
             if attribute.nil?
               raw
@@ -165,6 +183,7 @@ module Hecks
               # A reference is a scalar id — see Codec#decode.
               raw
             end
+          # rubocop:enable Lint/DuplicateBranch
         end
       end
     end

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

@@ -10,7 +10,7 @@ module Hecks
         def create_aggregate_table!
           columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
           @db.execute(
-            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
           # RIGHT HERE, NOT AS A SEPARATE STEP IN `Sqlite#initialize` —
           # `create_aggregate_table!` is the one piece of DDL `D1`
@@ -96,6 +96,28 @@ module Hecks
           raise unless e.message.include?("duplicate column name")
         end
 
+        def create_outbox_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_outbox (
+              id           INTEGER PRIMARY KEY AUTOINCREMENT,
+              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        TEXT NOT NULL,
+              status       TEXT NOT NULL DEFAULT 'pending',
+              attempts     INTEGER NOT NULL DEFAULT 0,
+              error        TEXT,
+              enqueued_at  TEXT NOT NULL,
+              claimed_at   TEXT,
+              settled_at   TEXT
+            )
+          SQL
+          @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
+        end
+
         def sql_type(attr)
           return "TEXT" if attr.list?
 

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

@@ -9,6 +9,7 @@ require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
+require_relative "../../runtime/outbox"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -63,6 +64,17 @@ module Hecks
         ensure_entry_mirrors_column!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
+      end
+
+      # 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.
+      def transaction(&)
+        return yield if @db.transaction_active?
+
+        @db.transaction(&)
       end
 
       def table = @aggregate.storage_name
@@ -81,7 +93,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)}"
@@ -142,8 +157,10 @@ module Hecks
 
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
-        append(entry)
-        project(entry)
+        transaction do
+          append(entry)
+          project(entry)
+        end
       end
 
       # The outcome lookup, journal append and snapshot replacement share one
@@ -151,7 +168,7 @@ module Hecks
       # adapter-native operation owns both concurrency and outcome reporting.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
+        transaction do
           exists = !@db.get_first_value("SELECT 1 FROM #{quoted_table} WHERE id = ?", [entry.id.to_s]).nil?
           if insert_only && exists
             status = :conflicted
@@ -202,11 +219,63 @@ module Hecks
       # 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
+      # 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,
+      # consumer) a no-op; `outbox_claim`'s `WHERE status = 'pending'`
+      # is the compare-and-set that lets exactly one relay win a row.
+      def outbox_enqueue(rows)
+        rows.filter_map do |row|
+          @db.execute(
+            "INSERT OR IGNORE INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, " \
+            "status, attempts, enqueued_at) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?)",
+            [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer,
+             JSON.generate(row.event), Time.now.utc.iso8601]
+          )
+          next nil if @db.changes.zero?
+
+          row.id = @db.last_insert_row_id
+          row.status = "pending"
+          row
+        end
+      end
+
+      def outbox_claim(id)
+        @db.execute(
+          "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = ? " \
+          "WHERE id = ? AND status = 'pending'",
+          [Time.now.utc.iso8601, id]
+        )
+        @db.changes == 1
+      end
+
+      def outbox_settle(id, status:, error: nil)
+        @db.execute(
+          "UPDATE hecks_outbox SET status = ?, error = ?, settled_at = ? WHERE id = ?",
+          [status.to_s, error, Time.now.utc.iso8601, id]
+        )
+        @db.changes == 1
+      end
+
+      def outbox_rows(status: nil)
+        sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
+        binds = [table]
+        if status
+          sql << " AND status = ?"
+          binds << status.to_s
+        end
+        @db.execute("#{sql} ORDER BY id", binds).map { |row| outbox_row(row) }
+      end
+
       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
 
@@ -221,7 +290,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"],
@@ -234,6 +304,15 @@ module Hecks
 
       # ── SqlQueryBuilder's dialect hooks ─────────────────────────────
 
+      def outbox_row(row)
+        Runtime::Outbox::Row.new(
+          id: row["id"], 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
+
       def select_list = "*"
       def from_relation = quoted_table
       def dialect_name = "SQLite"

data/lib/hecks/adapters/driven.rb

@@ -1,4 +1,7 @@
 module Hecks
+  # Reopened here purely to require in every driven adapter under
+  # adapters/driven/ below (see the comment inside for what "driven side"
+  # means) — the actual namespace is declared in adapters.rb.
   module Adapters
     # The driven side — every store or reader an adapter declaration can
     # bind. A small adapter is one file beside this one; sqlite, postgres
@@ -32,6 +35,7 @@ require_relative "driven/postgres"
 Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
 require_relative "driven/lambda"
 require_relative "driven/heki"
+require_relative "driven/local_storage"
 require_relative "driven/prism"
 require_relative "driven/folder"
 require_relative "driven/d1"