hecks 3.5.0 → 3.6.0

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

@@ -3,6 +3,7 @@ require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/value"
+require_relative "sql_value_members"
 
 module Hecks
   module Adapters
@@ -11,6 +12,8 @@ module Hecks
     # comparable_expression, plain_column, nested_expression, order_clause, execute_query
     # and dialect_name.
     module SqlQueryBuilder
+      include SqlValueMembers
+
       COMPARATORS = {
         "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
       }.freeze
@@ -31,17 +34,28 @@ module Hecks
         sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
         clauses = where_clauses(declared, args, binds)
-        sql << " WHERE #{clauses.join(' AND ')}" unless clauses.empty?
+        sql << " WHERE #{clauses.join(" AND ")}" unless clauses.empty?
         sql << order_by_sql(declared)
-        sql << " LIMIT #{placeholder(binds, query_value(declared.limit.value, args).to_i)}" if declared.limit
-        # SQLite refuses a bare OFFSET, so the dialect spells its own unbounded limit.
-        sql << unbounded_limit if !declared.limit && declared.offset
-        sql << " OFFSET #{placeholder(binds, query_value(declared.offset.value, args).to_i)}" if declared.offset
+        sql << paging_sql(declared, args, binds)
         execute_query(sql, binds)
       end
 
       private
 
+      # The LIMIT and OFFSET text, with their placeholders bound after the where binds.
+      def paging_sql(declared, args, binds)
+        sql = +""
+        sql << bound_paging(" LIMIT", declared.limit, args, binds) if declared.limit
+        # SQLite refuses a bare OFFSET, so the dialect spells its own unbounded limit.
+        sql << unbounded_limit if !declared.limit && declared.offset
+        sql << bound_paging(" OFFSET", declared.offset, args, binds) if declared.offset
+        sql
+      end
+
+      def bound_paging(keyword, clause, args, binds)
+        "#{keyword} #{placeholder(binds, query_value(clause.value, args).to_i)}"
+      end
+
       # `binds` is filled in place so LIMIT/OFFSET placeholders follow the where binds.
       def where_clauses(declared, args, binds)
         declared.wheres.each_with_object([]) do |clause, clauses|
@@ -65,25 +79,31 @@ module Hecks
         case oper
         when "eq", "ne", "gt", "gte", "lt", "lte"
           "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(oper)} #{placeholder(binds, value)}"
-        when "contains"
-          member = field && list_member(field)
-          if member
-            list_contains_clause(field.to_s, member, placeholder(binds, value.to_s))
-          else
-            contains_clause(expression, placeholder(binds, value.to_s))
-          end
-        when "in"
-          members = in_members(value)
-          return empty_in_clause if members.empty?
-
-          # `in` reads as text everywhere: casting the column keeps a numeric field
-          # matching the stringified members (SQLite's json_extract carries no affinity).
-          "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
+        when "contains" then contains_sql(expression, value, binds, field)
+        when "in" then in_sql(expression, value, binds)
         else
           raise ArgumentError, "#{dialect_name} query adapter does not support #{oper.inspect}"
         end
       end
 
+      def contains_sql(expression, value, binds, field)
+        member = field && list_member(field)
+        if member
+          list_contains_clause(field.to_s, member, placeholder(binds, value.to_s))
+        else
+          contains_clause(expression, placeholder(binds, value.to_s))
+        end
+      end
+
+      def in_sql(expression, value, binds)
+        members = in_members(value)
+        return empty_in_clause if members.empty?
+
+        # `in` reads as text everywhere: casting the column keeps a numeric field
+        # matching the stringified members (SQLite's json_extract carries no affinity).
+        "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(", ")})"
+      end
+
       # A real array is not re-split on commas: an id is a domain value and may hold one.
       # Unlike the other engines, a Hash or value-object element is not unwrapped.
       def in_members(value)
@@ -95,46 +115,18 @@ module Hecks
       # Compiles a declared field into an expression over the stored shape. A value-object
       # field compares through its numeric member, else its sole attribute, else `value`.
       # A reference is a bare id, so it takes the plain-column path.
-      # The two member fallbacks stay in one method so their order is visible.
-      # 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)
 
-        return plain_column(name) if path.empty? && @aggregate.lifecycle&.field.to_s == name
-        return plain_column(name) if path.empty? && attribute && !value_object?(attribute)
-
-        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) }
-                   # `numeric` can be false, which `&.` does not guard.
-                   # rubocop:disable-next Style/SafeNavigation
-                   numeric ? numeric.first : nil
-                 end
-        member ||= if path.empty? && attribute && value_object?(attribute)
-                     object = Runtime::Value.value_object_for(@aggregate, attribute.type)
-                     # A single-attribute value object is its one field, whatever it is named.
-                     (Forms::ValueObjectShape.numeric_member(object) || object.sole_attribute)&.name
-                   end
-        nested_expression(name, path, member)
-      end
+        return plain_column(name) if path.empty? && plain_field?(name, attribute)
 
-      # Picks the same member `query_expression` does, so both sides of a comparison
-      # agree on which field they mean.
-      def query_value(value, args)
-        value = args[value] if value.is_a?(Symbol)
-        hash = value.is_a?(Runtime::Value) ? value.to_h : value
-        if hash.is_a?(Hash)
-          numeric = hash.find { |_key, item| item.is_a?(Numeric) }
-          return numeric.last if numeric
-          return hash[:value] if hash.key?(:value)
-          return hash.values.first if hash.size == 1
-        end
+        nested_expression(name, path, path.empty? ? expression_member(attribute, value) : nil)
+      end
 
-        Runtime::Value.scalar(value)
-      rescue Runtime::TypeMismatch
-        value.is_a?(Hash) && value.size == 1 ? value.values.first : value
+      # Whether a bare field name reads as one plain column: the lifecycle field, or a scalar.
+      def plain_field?(name, attribute)
+        @aggregate.lifecycle&.field.to_s == name || (attribute && !value_object?(attribute))
       end
 
       def value_object?(attr)

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

@@ -0,0 +1,57 @@
+require_relative "../../forms/value_object_shape"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/value"
+
+module Hecks
+  module Adapters
+    # Which member of a value object a SQL comparison reads: its numeric member, else its sole
+    # attribute, else `value`. `SqlQueryBuilder` uses it so both sides of a comparison agree on
+    # which field they mean.
+    module SqlValueMembers
+      private
+
+      # The value's own numeric member when it has one, else the attribute's value-object member.
+      def expression_member(attribute, value)
+        member = (numeric_member_name(value) if value)
+        member ||= object_member_name(attribute) if attribute && value_object?(attribute)
+        member
+      end
+
+      def numeric_member_name(value)
+        hash = value.is_a?(Runtime::Value) ? value.to_h : value
+        pair = hash.find { |_key, item| item.is_a?(Numeric) } if hash.is_a?(Hash)
+        pair&.first
+      end
+
+      # A single-attribute value object is its one field, whatever it is named.
+      def object_member_name(attribute)
+        object = Runtime::Value.value_object_for(@aggregate, attribute.type)
+        (Forms::ValueObjectShape.numeric_member(object) || object.sole_attribute)&.name
+      end
+
+      # Picks the same member `query_expression` does, so both sides of a comparison
+      # agree on which field they mean.
+      def query_value(value, args)
+        value = args[value] if value.is_a?(Symbol)
+        picked = picked_member(value.is_a?(Runtime::Value) ? value.to_h : value)
+        return picked.first if picked
+
+        Runtime::Value.scalar(value)
+      rescue Runtime::TypeMismatch
+        value.is_a?(Hash) && value.size == 1 ? value.values.first : value
+      end
+
+      # The member of a Hash value a comparison reads, as a one-element Array so a nil member
+      # still counts as picked; nil when the value is no Hash or has no such member.
+      def picked_member(hash)
+        return nil unless hash.is_a?(Hash)
+
+        numeric = hash.find { |_key, item| item.is_a?(Numeric) }
+        return [numeric.last] if numeric
+        return [hash[:value]] if hash.key?(:value)
+
+        [hash.values.first] if hash.size == 1
+      end
+    end
+  end
+end

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

@@ -12,21 +12,20 @@ module Hecks
           fields = @aggregate.attributes.reject { |attribute| attribute.name == :id }.map do |attribute|
             { 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.none? do |field|
-            field[:name] == lifecycle.field
-          end
-          # `projects` fields are written straight into `Instance#state`, so they need a column
-          # or `project` drops them. They carry no attribute and are stored as raw scalars,
-          # like the lifecycle field.
-          @aggregate.projected_fields.each do |field|
-            next if fields.any? { |f| f[:name] == field.name }
-
-            fields << { name: field.name, attribute: nil, sql_type: "TEXT" }
+          raw_field_names.each do |name|
+            fields << { name: name, attribute: nil, sql_type: "TEXT" } unless fields.any? { |f| f[:name] == name }
           end
           fields
         end
 
+        # The lifecycle field and the `projects` fields. `projects` fields are written straight
+        # into `Instance#state`, so they need a column or `project` drops them. They carry no
+        # attribute and are stored as raw scalars, like the lifecycle field.
+        def raw_field_names
+          lifecycle = @aggregate.lifecycle
+          (lifecycle ? [lifecycle.field] : []) + @aggregate.projected_fields.map(&:name)
+        end
+
         def encode(attr, value)
           # A list nothing has appended to stays NULL, as under Memory; forcing `[]` would
           # invent data no dispatch wrote.
@@ -45,27 +44,31 @@ module Hecks
         def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
 
         def decode(row)
-          state = persisted_fields.each_with_object({}) do |field, raw_state|
-            attr = field[:attribute]
-            unless attr
-              value = row[field[:name].to_s]
-              next if value.nil? && projected_only?(field)
-
-              raw_state[field[:name]] = value
-              next
-            end
-            raw = row[attr.name.to_s]
-            raw_state[attr.name] =
-              if attr.list? || value_object?(attr)
-                raw ? JSON.parse(raw) : nil
-              else
-                # A reference holds a head's id, which is text and would fail JSON.parse.
-                raw
-              end
-          end
+          state = persisted_fields.each_with_object({}) { |field, raw_state| decode_field(row, field, raw_state) }
           Ports::Persistence::StateCodec.decode(@aggregate, state)
         end
 
+        def decode_field(row, field, raw_state)
+          attr = field[:attribute]
+          return decode_raw_field(row, field, raw_state) unless attr
+
+          raw_state[attr.name] = decode_stored(attr, row[attr.name.to_s])
+        end
+
+        def decode_raw_field(row, field, raw_state)
+          value = row[field[:name].to_s]
+          return if value.nil? && projected_only?(field)
+
+          raw_state[field[:name]] = value
+        end
+
+        def decode_stored(attr, raw)
+          return raw ? JSON.parse(raw) : nil if attr.list? || value_object?(attr)
+
+          # A reference holds a head's id, which is text and would fail JSON.parse.
+          raw
+        end
+
         # A NULL `projects` column means never seeded, so it reads back absent as under Heki and
         # PostgresEra; nothing stores a nil projected value. The lifecycle field keeps its NULL.
         def projected_only?(field)

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

@@ -0,0 +1,68 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # The CREATE TABLE statements `SchemaBuilder` runs, as text. `ENTRY_TABLE` takes the
+      # quoted table name as `%<table>s`.
+      module Ddl
+        EVENTS = <<~SQL.freeze
+          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
+
+        ENTRY_TABLE = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS %<table>s (
+            sequence     INTEGER PRIMARY KEY AUTOINCREMENT,
+            aggregate_id TEXT NOT NULL,
+            operation    TEXT NOT NULL DEFAULT 'save',
+            state        TEXT NOT NULL,
+            mirrors      TEXT
+          )
+        SQL
+
+        SAGA_INSTANCES = <<~SQL.freeze
+          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
+
+        OUTBOX = <<~SQL.freeze
+          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
+
+        CHECKPOINTS = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS hecks_checkpoints (
+            aggregate_table TEXT PRIMARY KEY,
+            last_sequence   INTEGER NOT NULL DEFAULT 0
+          )
+        SQL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # SQLite's hooks into the shared SqlQueryBuilder, plus identifier quoting.
+      module Dialect
+        private
+
+        def select_list = "*"
+        def from_relation = quoted_table
+        def dialect_name = "SQLite"
+        def empty_in_clause = "0"
+
+        def placeholder(binds, value)
+          binds << value
+          "?"
+        end
+
+        def contains_clause(expression, placeholder)
+          "instr(#{expression}, #{placeholder}) > 0"
+        end
+
+        def list_contains_clause(column, member, placeholder)
+          target = member.empty? ? "json_each.value" : "json_extract(json_each.value, '$.#{member}')"
+          "EXISTS (SELECT 1 FROM json_each(#{quote_ident(column)}) WHERE #{target} = #{placeholder})"
+        end
+
+        def plain_column(name) = quote_ident(name)
+
+        def nested_expression(name, path, member)
+          json_path = path.empty? ? "$.#{member || "value"}" : "$.#{path.join(".")}"
+          "json_extract(#{quote_ident(name)}, '#{json_path}')"
+        end
+
+        # SQLite has no bare OFFSET; LIMIT -1 is its unbounded spelling.
+        def unbounded_limit = " LIMIT -1"
+
+        def order_clause(order_by, policy)
+          QuerySpecification::Common::NullPolicy.sql_order(query_expression(order_by.field), order_by.direction, policy)
+        end
+
+        def execute_query(sql, binds)
+          @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+        end
+
+        def quote_ident(name)
+          %("#{name.to_s.gsub('"', '""')}")
+        end
+
+        def quoted_table = quote_ident(table)
+        def entry_table = "#{table}_entries"
+        def quoted_entry_table = quote_ident(entry_table)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # Event log: every emitted event lands in the database's shared `events` table.
+      module Events
+        # Inserts an emitted event into the database's shared `events` table.
+        #
+        # @param event [Runtime::Event] the emitted event; `payload` is stored as JSON
+        # @return [Array] the insert's empty result rows; callers ignore it
+        # @raise [SQLite3::Exception] if the insert fails
+        def record_event(event)
+          @db.execute(
+            "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
+            [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
+          )
+        end
+
+        # Reads back every recorded event in insertion order — the database file's whole
+        # `events` table, not only this aggregate's rows.
+        #
+        # @return [Array<Runtime::Event>] the stored events, `payload` parsed with Symbol keys
+        #   and `occurred_at` as stored; `[]` when none are recorded
+        # @raise [SQLite3::Exception] if the statement fails
+        def events
+          @db.execute("SELECT * FROM events ORDER BY id").map do |row|
+            event_from(row)
+          end
+        end
+
+        # Reads back one record's recorded events, oldest first — pushed down as a `WHERE`
+        # clause (`hecks_events_aggregate_id_idx`) instead of filtering `#events`'s whole-table
+        # read, since a `corrects` command's history lookup only ever needs this one record.
+        #
+        # @param aggregate [String] the `"domain::AggregateName"` key events are stored under
+        # @param id [String, Object] the record's identity, matched as `id.to_s`
+        # @return [Array<Runtime::Event>] the record's stored events; `[]` when it has none
+        # @raise [SQLite3::Exception] if the statement fails
+        def events_for(aggregate:, id:)
+          @db.execute(
+            "SELECT * FROM events WHERE aggregate = ? AND aggregate_id = ? ORDER BY id",
+            [aggregate, id.to_s]
+          ).map do |row|
+            event_from(row)
+          end
+        end
+
+        private
+
+        def event_from(row)
+          Runtime::Event.new(
+            name:        row["name"],
+            aggregate:   row["aggregate"],
+            id:          row["aggregate_id"],
+            payload:     JSON.parse(row["payload"], symbolize_names: true),
+            occurred_at: row["occurred_at"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # The append-only entry table and its checkpoint bookkeeping.
+      module Journal
+        # Inserts one journal row, outside any transaction of its own.
+        #
+        # Stamps the row's assigned `sequence` onto `entry` in place, so a `project` call right
+        # after (same object, same transaction) can advance the checkpoint with no extra query.
+        #
+        # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state` is
+        #   encoded through the state codec and `mirrors` stored as JSON, or NULL when nil
+        # @return [Ports::Persistence::Entry] the same `entry`, `sequence` now set
+        # @raise [SQLite3::Exception] if the insert fails
+        def append(entry)
+          @db.execute(
+            "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
+            # `mirrors` is nullable: an absent hash must bind SQL NULL, not the JSON text "null".
+            [entry.id, entry.operation, JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, entry.state)),
+             entry.mirrors && JSON.generate(entry.mirrors)]
+          )
+          entry.sequence = @db.last_insert_row_id
+          entry
+        end
+
+        # Reads the whole journal back in append order, for `AppendOnly#recover!` to replay.
+        #
+        # @return [Array<Ports::Persistence::Entry>] every journalled entry, state decoded
+        #   through the state codec and `mirrors` parsed with String keys (nil when none were
+        #   stored); a NULL `operation` reads as `"save"`; `[]` when nothing has been appended
+        # @raise [SQLite3::Exception] if the statement fails
+        # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
+        def entries
+          entries_matching(
+            "SELECT aggregate_id, operation, state, mirrors, sequence FROM #{quoted_entry_table} ORDER BY sequence"
+          )
+        end
+
+        # Reads only the journal rows past a given `sequence`, for `AppendOnly#recover!` to replay
+        # after a checkpoint instead of the whole journal.
+        #
+        # @param sequence [Integer] the highest `sequence` already projected; rows at or below it
+        #   are skipped
+        # @return [Array<Ports::Persistence::Entry>] the journalled entries past `sequence`, in
+        #   append order, decoded exactly as `entries` decodes them; `[]` when none are newer
+        # @raise [SQLite3::Exception] if the statement fails
+        # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
+        def entries_since(sequence)
+          entries_matching(
+            "SELECT aggregate_id, operation, state, mirrors, sequence FROM #{quoted_entry_table} " \
+            "WHERE sequence > ? ORDER BY sequence",
+            [sequence]
+          )
+        end
+
+        # Reads the highest journal `sequence` this table has already had projected into it.
+        #
+        # @return [Integer] `0` when the table has never been checkpointed (a fresh table, or one
+        #   from before this bookkeeping existed) — `entries_since(0)` then reads the whole journal,
+        #   matching `entries`' own full replay
+        # @raise [SQLite3::Exception] if the statement fails
+        def checkpoint
+          @db.get_first_value("SELECT last_sequence FROM hecks_checkpoints WHERE aggregate_table = ?", [table]).to_i
+        end
+
+        # Reads the highest journal `sequence` compaction has already deleted from this table.
+        #
+        # @return [Integer] `0` when nothing has ever been compacted
+        # @raise [SQLite3::Exception] if the statement fails
+        def compacted_through
+          @db.get_first_value("SELECT compacted_through FROM hecks_checkpoints WHERE aggregate_table = ?", [table]).to_i
+        end
+
+        # Deletes every journal row at or before `through` and records it, so a `:strict`
+        # projection catch-up can tell whether it still has the history it needs.
+        #
+        # Never moves `compacted_through` backwards, and never touches the aggregate's own
+        # table — only the journal, which a `:refresh` projection rebuild never needs.
+        #
+        # @param through [Integer] the highest `sequence` to delete
+        # @return [Integer] the number of journal rows deleted
+        # @raise [SQLite3::Exception] if a statement fails
+        def compact_entries!(through:)
+          @db.execute("DELETE FROM #{quoted_entry_table} WHERE sequence <= ?", [through])
+          removed = @db.changes
+          @db.execute(
+            "INSERT INTO hecks_checkpoints (aggregate_table, compacted_through) VALUES (?, ?) " \
+            "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+            "compacted_through = MAX(compacted_through, excluded.compacted_through)",
+            [table, through]
+          )
+          removed
+        end
+
+        private
+
+        # Shared decode step for `entries`/`entries_since` — runs a query already selecting
+        # `aggregate_id, operation, state, mirrors, sequence` and builds one Entry per row.
+        def entries_matching(sql, binds = [])
+          @db.execute(sql, binds).map do |row|
+            state = JSON.parse(row["state"])
+            Ports::Persistence::Entry.new(
+              operation: row["operation"] || "save",
+              id:        row["aggregate_id"],
+              state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
+              mirrors:   row["mirrors"] && JSON.parse(row["mirrors"]),
+              sequence:  row["sequence"].to_i
+            )
+          end
+        end
+
+        # Advances this table's checkpoint to `sequence`, never backwards — two overlapping
+        # `project` calls for out-of-order entries must not let an older sequence win.
+        def advance_checkpoint!(sequence)
+          @db.execute(
+            "INSERT INTO hecks_checkpoints (aggregate_table, last_sequence) VALUES (?, ?) " \
+            "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+            "last_sequence = MAX(last_sequence, excluded.last_sequence)",
+            [table, sequence]
+          )
+        end
+      end
+    end
+  end
+end