hecks 3.5.0 → 3.7.0

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

@@ -0,0 +1,98 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # The transactional outbox rows, keyed by this aggregate's storage name.
+      module Outbox
+        # Inserts new outbox rows as pending, skipping any whose `delivery_id` already exists.
+        #
+        # Rows share this aggregate's database so the enqueue joins the save's transaction, and
+        # are keyed by storage name so aggregates sharing a file read back only their own.
+        #
+        # @param rows [Array<Runtime::Outbox::Row>] rows to enqueue; each accepted row has its
+        #   `id` and `status` assigned in place. `row.aggregate` is stored as given
+        # @return [Array<Runtime::Outbox::Row>] the rows actually inserted, `[]` when every one
+        #   was a duplicate
+        # @raise [SQLite3::Exception] if an insert fails
+        def outbox_enqueue(rows)
+          rows.filter_map do |row|
+            insert_outbox_row(row)
+            next nil if @db.changes.zero?
+
+            row.id = @db.last_insert_row_id
+            row.status = "pending"
+            row
+          end
+        end
+
+        # Claims a pending outbox row with a compare-and-set update, counting the attempt.
+        #
+        # @param id [Integer] the row id `outbox_enqueue` assigned
+        # @return [Boolean] true when the row was pending and is now claimed; false when it is
+        #   unknown or another claimer got there first
+        # @raise [SQLite3::Exception] if the update fails
+        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+          @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
+
+        # Records a delivery outcome and its settle time on an outbox row, whatever status it
+        # held.
+        #
+        # @param id [Integer] the row id `outbox_enqueue` assigned
+        # @param status [String, Symbol] the new status, one of `Runtime::Outbox::STATUSES`;
+        #   not validated here
+        # @param error [String, nil] the failure description, or nil to store NULL
+        # @return [Boolean] true when exactly one row was updated; false when no row has `id`
+        # @raise [SQLite3::Exception] if the update fails
+        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+          @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
+
+        # Lists the outbox rows whose `aggregate` column equals this adapter's `table`, in
+        # enqueue order.
+        #
+        # @param status [String, Symbol, nil] only rows with this status; nil lists every row
+        # @return [Array<Runtime::Outbox::Row>] the matching rows, `event` parsed with Symbol
+        #   keys; `[]` when none match
+        # @raise [SQLite3::Exception] if the statement fails
+        def outbox_rows(status: nil)
+          sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
+          binds = [table]
+          if status
+            sql << " AND status = ?"
+            binds << status.to_s
+          end
+          @db.execute("#{sql} ORDER BY id", binds).map { |row| outbox_row(row) }
+        end
+
+        private
+
+        def insert_outbox_row(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]
+          )
+        end
+
+        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
+      end
+    end
+  end
+end

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

@@ -15,6 +15,9 @@ module Hecks
     # Rebuilds a read store from the authoritative journal, entry by entry.
     # Values are written as JSON, references as bare ids — the shapes the command path writes.
     class SqliteProjection < Sqlite
+      # The state of one `query_read_model` call, threaded through its per-head steps.
+      ReadModelRun = Struct.new(:model, :args, :bluebook, :reference_id, :eligible, :projected)
+
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.
       #
@@ -26,11 +29,7 @@ module Hecks
         return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
 
         columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
-        values  = [entry.id.to_s] + persisted_fields.map { |field| encode_field(field, entry.state[field[:name]]) }
-        @db.execute(
-          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{Array.new(columns.size,
-                                                                                              '?').join(', ')})", values
-        )
+        @db.execute(upsert_sql(columns), row_values(entry))
         entry
       end
 
@@ -55,36 +54,56 @@ module Hecks
         # Plural (ADR 0055) — `on:` lets `where`/`order_by`/`limit`/`offset`
         # each name a different many-side head, so more than one may be
         # eligible in the same read model.
-        eligible = model.filtered_head_names
+        run = ReadModelRun.new(model, args, bluebook, reference_id, model.filtered_head_names, [])
+        [ordered_heads(model).to_h { |head| [head[:as], resolve_head(run, head)] }]
+      end
 
-        # Root first, always (see this method's own header): a later head's
-        # join must match against a root or head already resolved.
+      private
+
+      # Root first, always (see `query_read_model`'s own header): a later head's
+      # join must match against a root or head already resolved.
+      def ordered_heads(model)
         root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
-        projected = []
-        reports = {}
-        (root_heads + other_heads).each do |head|
-          aggregate = bluebook.aggregate(head[:aggregate])
-          rows = if head[:aggregate] == model.reference_target
-                   [select_projected(aggregate, reference_id) ||
-                     raise(Runtime::NotFound,
-                           Runtime::RefusalWording.render_site("NotFound", "read_model_reference_missing",
-                                                               aggregate: head[:aggregate],
-                                                               offered:   Hecks::Rendering.describe(reference_id)))]
-                 else
-                   select_related(aggregate, projected)
-                 end
-          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) }
-                               else
-                                 rows.first && Runtime::Value.materialize(rows.first.to_h)
-                               end
-        end
-        [reports]
+        root_heads + other_heads
       end
 
-      private
+      # Reads one head's rows, records them as projected so later heads can join against them,
+      # and returns the head's report entry.
+      def resolve_head(run, head)
+        rows = head_rows(run, head, run.bluebook.aggregate(head[:aggregate]))
+        rows = filter_rows(run, head, rows)
+        run.projected << { aggregate: head[:aggregate], rows: rows }
+        head_report(head, rows)
+      end
+
+      # Applies the head's `where`/`order_by`/`limit`/`offset` when the read model names it.
+      def filter_rows(run, head, rows)
+        return rows unless run.eligible.include?(head[:as])
+
+        Ports::Query::InMemory.execute(rows, run.model.options_for(head[:as]), run.args)
+      end
+
+      def head_report(head, rows)
+        return rows.map { |row| Runtime::Value.materialize(row.to_h) } if head[:many]
+
+        rows.first && Runtime::Value.materialize(rows.first.to_h)
+      end
+
+      def head_rows(run, head, aggregate)
+        return select_related(aggregate, run.projected) unless head[:aggregate] == run.model.reference_target
+
+        [select_projected(aggregate, run.reference_id) || raise(Runtime::NotFound, missing_root_wording(run, head))]
+      end
+
+      def missing_root_wording(run, head)
+        Runtime::RefusalWording.render_site("NotFound", "read_model_reference_missing",
+                                            aggregate: head[:aggregate],
+                                            offered:   Hecks::Rendering.describe(run.reference_id))
+      end
+
+      def row_values(entry)
+        [entry.id.to_s] + persisted_fields.map { |field| encode_field(field, entry.state[field[:name]]) }
+      end
 
       def select_projected(aggregate, id)
         row = @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id.to_s])
@@ -94,26 +113,27 @@ module Hecks
       # Matches every already-projected source, not just the root, so a head
       # referencing another included head still matches.
       def select_related(aggregate, projected)
-        matches = projected.flat_map do |source|
-          references = aggregate.attributes.select do |attribute|
-            attribute.reference? && attribute.type.target_name == source[:aggregate].to_s
-          end
-          next [] if references.empty?
-
-          ids = source[:rows].map { |row| row.id.to_s }
-          next [] if ids.empty?
-
-          references.product(ids)
-        end
+        matches = projected.flat_map { |source| reference_matches(aggregate, source) }
         return [] if matches.empty?
 
         # A reference column holds the id, so it compares directly against itself.
         clauses = matches.map { |attribute, _id| "#{quote_ident(attribute.name)} = ?" }
         bind = matches.map { |_attribute, id| id }
-        @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(' OR ')} ORDER BY id", bind)
+        @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(" OR ")} ORDER BY id", bind)
            .map { |row| projected_instance(aggregate, row) }
       end
 
+      # Every (reference attribute, id) pair by which `aggregate` points at one projected source.
+      def reference_matches(aggregate, source)
+        references = aggregate.attributes.select do |attribute|
+          attribute.reference? && attribute.type.target_name == source[:aggregate].to_s
+        end
+        return [] if references.empty?
+
+        ids = source[:rows].map { |row| row.id.to_s }
+        references.product(ids)
+      end
+
       def projected_instance(aggregate, row)
         Runtime::Instance.new(aggregate: aggregate, id: row["id"], state: decode_for(aggregate, row))
       end
@@ -126,13 +146,10 @@ module Hecks
       # `projects` fields, all read back raw (see `decode_fields`).
       def fields_for(aggregate)
         fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
-        if (lifecycle = aggregate.lifecycle) && fields.none? { |name, _| name == lifecycle.field }
-          fields << [lifecycle.field, nil]
-        end
         # `projects` fields (ADR 0025) read back raw too — see `persisted_fields`.
-        aggregate.projected_fields.each do |field|
-          fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
-        end
+        lifecycle = aggregate.lifecycle
+        raw_names = (lifecycle ? [lifecycle.field] : []) + aggregate.projected_fields.map(&:name)
+        raw_names.each { |raw| fields << [raw, nil] unless fields.any? { |name, _| name == raw } }
         fields
       end
 
@@ -141,23 +158,25 @@ module Hecks
       def decode_fields(fields, aggregate, row)
         state = fields.each_with_object({}) do |(name, attribute), raw_state|
           raw = row[name.to_s]
-          # rubocop:disable Lint/DuplicateBranch -- the nil-attribute and
-          # reference-id branches both just answer `raw`, for unrelated reasons.
-          next if attribute.nil? && raw.nil? && aggregate.lifecycle&.field&.to_sym != name.to_sym
-
-          raw_state[name] =
-            if attribute.nil?
-              raw
-            elsif attribute.list? || !aggregate.value_object(attribute.type).nil?
-              raw ? JSON.parse(raw) : nil
-            else
-              # A reference is a scalar id — see Codec#decode.
-              raw
-            end
-          # rubocop:enable Lint/DuplicateBranch
+          next if unset_projected?(aggregate, name, attribute, raw)
+
+          raw_state[name] = decode_column(aggregate, attribute, raw)
         end
         Ports::Persistence::StateCodec.decode(aggregate, state)
       end
+
+      # A NULL column with no attribute reads back absent, except the lifecycle field.
+      def unset_projected?(aggregate, name, attribute, raw)
+        attribute.nil? && raw.nil? && aggregate.lifecycle&.field&.to_sym != name.to_sym
+      end
+
+      def decode_column(aggregate, attribute, raw)
+        return raw if attribute.nil?
+        # A reference is a scalar id — see Codec#decode.
+        return raw unless attribute.list? || !aggregate.value_object(attribute.type).nil?
+
+        raw ? JSON.parse(raw) : nil
+      end
     end
   end
 end

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

@@ -0,0 +1,146 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # The repository surface: find, list, count, and the journal-then-project writes.
+      module Repository
+        # Reads the current row for one aggregate identity.
+        #
+        # @param id [String, Object] the aggregate identity, bound as `id.to_s`
+        # @return [Runtime::Instance, nil] the decoded record, or nil when no row has that id
+        # @raise [SQLite3::Exception] if the statement fails
+        def find(id)
+          row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
+          return nil unless row
+
+          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+        end
+
+        # Lists every stored record, ordered by id unless an ordering attribute is given.
+        #
+        # order_by is a runtime value, so it is checked against the aggregate before use.
+        #
+        # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+        #   by; nil orders by id alone
+        # @param direction [Symbol, String] `:asc` or `:desc`, case-insensitive; anything else
+        #   sorts ascending
+        # @return [Array<Runtime::Instance>] the decoded records, `[]` when the table is empty
+        # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
+        # @raise [SQLite3::Exception] if the statement fails
+        def all(order_by: nil, direction: :asc)
+          rows = @db.execute("SELECT * FROM #{quoted_table} #{order_sql(order_by, direction)}")
+          rows.map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+        end
+
+        # Counts the rows in the aggregate's table, deleted records excluded.
+        #
+        # @return [Integer] number of current records
+        # @raise [SQLite3::Exception] if the statement fails
+        def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
+
+        # Replaces or deletes the aggregate's row for one journal entry.
+        #
+        # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+        # @return [Runtime::Instance, Array] for a save, a new instance over the entry's state;
+        #   for a delete, the `DELETE` statement's empty result rows
+        # @raise [SQLite3::Exception] if the statement fails
+        def project(entry)
+          advance_checkpoint!(entry.sequence) if entry.sequence
+          return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
+
+          instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+          @db.execute(upsert_sql(quoted_columns), instance_values(instance))
+          instance
+        end
+
+        # Deletes every row of the aggregate's table and its journal; events, saga rows and
+        # outbox rows are left in place.
+        #
+        # @return [Adapters::Sqlite] self
+        # @raise [SQLite3::Exception] if a statement fails
+        def reset!
+          @db.execute("DELETE FROM #{quoted_table}")
+          @db.execute("DELETE FROM #{quoted_entry_table}")
+          self
+        end
+
+        # Journals and replaces an instance's current state in one transaction.
+        #
+        # @param instance [Runtime::Instance] the instance to store
+        # @return [Runtime::Instance] a new instance over a shallow copy of the saved state
+        # @raise [SQLite3::Exception] if either statement fails; the transaction is rolled back
+        def save(instance)
+          entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          transaction do
+            append(entry)
+            project(entry)
+          end
+        end
+
+        # Stores an entry and reports whether it inserted, replaced or conflicted.
+        #
+        # The outcome lookup, journal append and snapshot replacement share one transaction.
+        #
+        # @param entry [Ports::Persistence::Entry] the save to store
+        # @param insert_only [Boolean] when true, an existing row is left untouched
+        # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+        #   existing row and nothing was written
+        # @raise [SQLite3::Exception] if a statement fails; the transaction is rolled back
+        def atomic_put(entry, insert_only: false)
+          status = nil
+          transaction { status = put_entry(entry, insert_only) }
+          status
+        end
+
+        # Journals a delete and removes the row, whether or not a row exists. The two
+        # statements share a transaction only when the caller has one open.
+        #
+        # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+        # @return [Boolean] always true
+        # @raise [SQLite3::Exception] if either statement fails
+        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, not a question
+          entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+          append(entry)
+          project(entry)
+          true
+        end
+
+        private
+
+        def order_sql(order_by, direction)
+          return "ORDER BY id" unless order_by
+
+          name = order_by.to_s.split(".").first
+          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 BY #{order_clause(spec, nil)}"
+        end
+
+        def quoted_columns
+          (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
+        end
+
+        def upsert_sql(columns)
+          slots = Array.new(columns.size, "?").join(", ")
+          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(", ")}) VALUES (#{slots})"
+        end
+
+        def instance_values(instance)
+          [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
+        end
+
+        def put_entry(entry, insert_only)
+          exists = !@db.get_first_value("SELECT 1 FROM #{quoted_table} WHERE id = ?", [entry.id.to_s]).nil?
+          return :conflicted if insert_only && exists
+
+          append(entry)
+          project(entry)
+          exists ? :replaced : :inserted
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # Saga checkpoints, scoped by the adapter's domain.
+      module Sagas
+        # Replaces one saga instance's checkpoint, keyed by domain, process manager and
+        # correlation.
+        #
+        # @param process_manager [String, Symbol] the process manager's name
+        # @param correlation [String, Object] the instance's correlation value, stored as
+        #   `correlation.to_s`
+        # @param state [String, Symbol] the saga's current state name
+        # @param memory [Hash] the saga's memory; must be JSON-serializable
+        # @param completed_compensations [Array] the ledger of completed compensable legs; must
+        #   be JSON-serializable
+        # @return [Array] the statement's empty result rows; callers ignore it
+        # @raise [SQLite3::Exception] if the statement fails
+        def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+          @db.execute(
+            "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, " \
+            "completed_compensations) VALUES (?, ?, ?, ?, ?, ?)",
+            [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+             JSON.generate(completed_compensations)]
+          )
+        end
+
+        # Removes a finished saga instance's checkpoint; a missing row is not an error.
+        #
+        # @param process_manager [String, Symbol] the process manager's name
+        # @param correlation [String, Object] the instance's correlation value, matched as
+        #   `correlation.to_s`
+        # @return [Array] the statement's empty result rows; callers ignore it
+        # @raise [SQLite3::Exception] if the statement fails
+        def delete_saga(process_manager:, correlation:)
+          @db.execute(
+            "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
+            [@domain, process_manager.to_s, correlation.to_s]
+          )
+        end
+
+        # Yields every checkpointed saga instance of this adapter's domain, for
+        # `Registry#rehydrate_sagas!` to restore at boot.
+        #
+        # @yieldparam process_manager [String] the process manager's name
+        # @yieldparam correlation [String] the instance's correlation value
+        # @yieldparam state [String] the saga's state name
+        # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every depth
+        # @yieldparam completed_compensations [Array] the completed-compensation ledger, `[]`
+        #   when the column is NULL
+        # @return [Enumerator, Array<Hash>] an enumerator over the same five values when no
+        #   block is given; otherwise the raw result rows
+        # @raise [SQLite3::Exception] if the statement fails
+        def each_saga
+          return enum_for(:each_saga) unless block_given?
+
+          @db.execute(
+            "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"],
+                  JSON.parse(row["memory"], symbolize_names: true),
+                  JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,3 +1,5 @@
+require_relative "ddl"
+
 module Hecks
   module Adapters
     class Sqlite
@@ -8,23 +10,14 @@ 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#{', ' unless columns.empty?}#{columns.join(', ')})"
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{", " unless columns.empty?}#{columns.join(", ")})"
           )
           # Called here so D1, which reuses this module, gets automatic indexing too.
           ensure_indexes!
         end
 
         def create_event_table!
-          @db.execute(<<~SQL)
-            CREATE TABLE IF NOT EXISTS events (
-              id           INTEGER PRIMARY KEY AUTOINCREMENT,
-              name         TEXT NOT NULL,
-              aggregate    TEXT NOT NULL,
-              aggregate_id TEXT NOT NULL,
-              payload      TEXT,
-              occurred_at  TEXT
-            )
-          SQL
+          @db.execute(Ddl::EVENTS)
           # Backs #events_for's per-record lookup (a `corrects` command's history read).
           @db.execute(
             "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"
@@ -32,15 +25,7 @@ module Hecks
         end
 
         def create_entry_table!
-          @db.execute(<<~SQL)
-            CREATE TABLE IF NOT EXISTS #{quoted_entry_table} (
-              sequence     INTEGER PRIMARY KEY AUTOINCREMENT,
-              aggregate_id TEXT NOT NULL,
-              operation    TEXT NOT NULL DEFAULT 'save',
-              state        TEXT NOT NULL,
-              mirrors      TEXT
-            )
-          SQL
+          @db.execute(format(Ddl::ENTRY_TABLE, table: quoted_entry_table))
         end
 
         def ensure_entry_operation_column!
@@ -60,17 +45,7 @@ module Hecks
         # Shared with D1, which includes this module. `domain` is an explicit column so
         # two domains can share one database file.
         def create_saga_table!
-          @db.execute(<<~SQL)
-            CREATE TABLE IF NOT EXISTS hecks_saga_instances (
-              domain               TEXT NOT NULL,
-              process_manager      TEXT NOT NULL,
-              correlation          TEXT NOT NULL,
-              state                TEXT NOT NULL,
-              memory               TEXT NOT NULL,
-              completed_compensations  TEXT NOT NULL DEFAULT '[]',
-              PRIMARY KEY (domain, process_manager, correlation)
-            )
-          SQL
+          @db.execute(Ddl::SAGA_INSTANCES)
           # The table may predate this column, and SQLite lacks ADD COLUMN IF NOT EXISTS,
           # so a duplicate-column error is treated as already applied.
           @db.execute("ALTER TABLE hecks_saga_instances ADD COLUMN completed_compensations TEXT NOT NULL DEFAULT '[]'")
@@ -79,24 +54,7 @@ module Hecks
         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(Ddl::OUTBOX)
           @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
         end
 
@@ -104,12 +62,7 @@ module Hecks
         # already had projected into it — shared across every aggregate in the database file,
         # since it is keyed by table name rather than declared per aggregate.
         def create_checkpoint_table!
-          @db.execute(<<~SQL)
-            CREATE TABLE IF NOT EXISTS hecks_checkpoints (
-              aggregate_table TEXT PRIMARY KEY,
-              last_sequence   INTEGER NOT NULL DEFAULT 0
-            )
-          SQL
+          @db.execute(Ddl::CHECKPOINTS)
           ensure_checkpoint_compacted_through_column!
         end