hecks 3.5.0 → 3.6.0

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

@@ -2,6 +2,7 @@ require "objspace"
 require_relative "../../../freezer"
 require_relative "../../../ports/persistence/state_codec"
 require_relative "../../../runtime/value"
+require_relative "shared_elements/values"
 
 module Hecks
   module Adapters
@@ -16,6 +17,8 @@ module Hecks
       # returned instance. Everything else in the state goes through `StateCodec` whole. The
       # tables are weak and identity-keyed: a cache, never the only holder.
       class SharedElements
+        include Values
+
         # @param aggregate [Bluebook::Aggregate] the aggregate whose state this shares elements of
         def initialize(aggregate)
           @aggregate = aggregate
@@ -45,9 +48,7 @@ module Hecks
           return Ports::Persistence::StateCodec.copy(@aggregate, state) if lists.empty? && values.empty?
 
           copied = Ports::Persistence::StateCodec.copy(@aggregate, placeholders(state, lists, values))
-          lists.each { |name, (attribute, elements)| copied[name] = journal_list(attribute, elements) }
-          values.each { |name, (attribute, value)| copied[name] = journal_value(attribute, value) }
-          copied
+          share_journal(copied, lists, values)
         end
 
         # Hydrates journal-shaped state into the state a record holds.
@@ -67,6 +68,12 @@ module Hecks
 
         private
 
+        def share_journal(copied, lists, values)
+          lists.each { |name, (attribute, elements)| copied[name] = journal_list(attribute, elements) }
+          values.each { |name, (attribute, value)| copied[name] = journal_value(attribute, value) }
+          copied
+        end
+
         # The list attributes of `state` whose elements can be shared: composite, not a
         # reference, and actually held as an Array.
         def shareable_lists(state)
@@ -88,60 +95,6 @@ module Hecks
           end
         end
 
-        # The attributes of the aggregate that hold one value object able to hold a list, by
-        # name. A value object with no list in it is small and is left to the codec.
-        def growable_values
-          @growable_values ||= @aggregate.attributes.each_with_object({}) do |attribute, found|
-            next if attribute.list? || attribute.reference?
-
-            shape = value_object_of(attribute)
-            found[attribute.name.to_sym] = attribute if shape && growable?(shape, [])
-          end
-        end
-
-        def value_object_of(attribute)
-          return nil unless @aggregate.respond_to?(:value_object)
-
-          Runtime::Value.value_object_for(@aggregate, attribute.type.to_s)
-        end
-
-        def growable?(shape, seen)
-          return false if seen.include?(shape)
-
-          shape.attributes.any? do |attribute|
-            next false if attribute.reference?
-            next true if attribute.list?
-
-            nested = value_object_of(attribute)
-            nested ? growable?(nested, seen + [shape]) : false
-          end
-        end
-
-        # The growable value-object attributes of `state` holding a frozen value of their type.
-        def journal_values(state)
-          return {} unless state.is_a?(Hash)
-
-          growable_values.each_with_object({}) do |(name, attribute), found|
-            value = state[name]
-            found[name] = [attribute, value] if value.is_a?(Runtime::Value) && sharable_value?(attribute, value)
-          end
-        end
-
-        def sharable_value?(attribute, value)
-          value.frozen? && value.type_name == value_object_of(attribute).hecks_name
-        end
-
-        # The growable value-object attributes of `decoded` holding a frozen Hash: a copy this
-        # table made, or one a caller froze.
-        def live_values(decoded)
-          return {} unless decoded.is_a?(Hash)
-
-          growable_values.each_with_object({}) do |(name, attribute), found|
-            copy = decoded[name]
-            found[name] = [attribute, copy] if copy.is_a?(Hash) && copy.frozen?
-          end
-        end
-
         def composite?(attribute)
           type = attribute.type.to_s
           !Runtime::Value.find_entity(@aggregate, type).nil? ||
@@ -156,46 +109,6 @@ module Hecks
           state.merge(lists.merge(values).transform_values { nil })
         end
 
-        # The frozen codec copy of one value object. A list it holds is rebuilt from the copies
-        # of its elements, so a new version of the value costs the new elements, not all of them.
-        def journal_value(attribute, value)
-          known = @journal[value]
-          return known if known
-
-          fields = value.raw_fields
-          lists  = value_lists(attribute, fields)
-          held   = fields.merge(lists.transform_values { nil })
-          copy   = Ports::Persistence::StateCodec.copy_list_element(@aggregate, attribute, held)
-          copy.each_value { |inner| Freezer.deep(inner) }
-          lists.each { |name, (list_attribute, elements)| copy[name] = journal_list(list_attribute, elements) }
-          @copies[copy.freeze] = true
-          @journal[value] = copy
-        end
-
-        def value_lists(attribute, fields)
-          list_attributes(value_object_of(attribute)).each_with_object({}) do |(name, list_attribute), found|
-            elements = fields[name]
-            found[name] = [list_attribute, elements] if elements.is_a?(Array)
-          end
-        end
-
-        # The hydrated value for one frozen copy, its lists rebuilt from the hydrated elements
-        # already held.
-        def live_value(attribute, copy)
-          known = @live[copy]
-          return known if known
-
-          lists  = value_lists(attribute, copy)
-          fields = copy.merge(lists.to_h { |name, (list_attribute, elements)| [name, live_list(list_attribute, elements)] })
-          live   = Runtime::Value.trusting_stored_state do
-            Runtime::Value.for_attribute(@aggregate, attribute, fields)
-          end
-          return live unless @copies.key?(copy)
-
-          @journal[live] = copy
-          @live[copy] = live
-        end
-
         def journal_list(attribute, elements)
           elements.map { |element| journal_element(attribute, element) }.freeze
         end

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

@@ -3,12 +3,15 @@ require_relative "../../ports/query/in_memory"
 require_relative "in_memory_ordering"
 require_relative "../../runtime/instance"
 require_relative "memory/shared_elements"
+require_relative "memory/outbox_rows"
 
 module Hecks
   module Adapters
     # The default in-process adapter: a Hash of `Runtime::Instance` records
     # per aggregate, plus an append-only `@entries`/`@events` log.
     class Memory
+      include OutboxRows
+
       # Reports that two tenant boots of this adapter never share state.
       #
       # Trivially true: `@records` is a plain ivar, and each `Runtime.boot`
@@ -182,73 +185,8 @@ module Hecks
       # @return [Object] the block's own result
       def transaction = yield
 
-      # Holds new outbox rows, skipping any whose `delivery_id` is already held.
-      #
-      # @param rows [Array<Runtime::Outbox::Row>] pending rows to enqueue; each accepted row
-      #   has its `id` assigned in place
-      # @return [Array<Runtime::Outbox::Row>] the rows actually enqueued, `[]` when every one
-      #   was a duplicate
-      def outbox_enqueue(rows)
-        rows.filter_map do |row|
-          next nil if @outbox_deliveries.key?(row.delivery_id)
-
-          row.id = @outbox.size + 1
-          @outbox << row
-          @outbox_deliveries[row.delivery_id] = true
-          row
-        end
-      end
-
-      # Marks a pending outbox row claimed and counts the delivery 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 not pending
-      def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
-        row = outbox_row(id)
-        return false unless row&.pending?
-
-        row.status = "claimed"
-        row.attempts += 1
-        true
-      end
-
-      # Records a delivery outcome 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 clear it
-      # @return [Boolean] true when the row exists and was updated; false when no row has `id`
-      def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
-        row = outbox_row(id) or return false
-        row.status = status.to_s
-        row.error  = error
-        true
-      end
-
-      # Lists outbox rows in enqueue order, as copies a caller may mutate freely.
-      #
-      # @param status [String, Symbol, nil] only rows with this status; nil lists every row
-      # @return [Array<Runtime::Outbox::Row>] shallow copies of the matching rows, `[]` when
-      #   none match
-      def outbox_rows(status: nil)
-        rows = status ? @outbox.select { |row| row.status == status.to_s } : @outbox
-        rows.map(&:dup)
-      end
-
       private
 
-      # Finds a held outbox row by id in constant time.
-      #
-      # Ids are assigned as the 1-based position at enqueue and rows are never
-      # removed, so the id is the row's index plus one.
-      def outbox_row(id)
-        return nil unless id.is_a?(Integer) && id >= 1
-
-        @outbox[id - 1]
-      end
-
       # Skips the codec copy and rehydration round trip while judging the
       # self-hosted grammar (S17, ADR 0026), where re-validating already-valid
       # entity state costs O(N) per save and O(N^2) across an N-row table.

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

@@ -12,19 +12,18 @@ 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 local columns too (ADR 0025).
-          @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, which are local columns too (ADR 0025).
+        def raw_field_names
+          lifecycle = @aggregate.lifecycle
+          (lifecycle ? [lifecycle.field] : []) + @aggregate.projected_fields.map(&:name)
+        end
+
         def encode(attr, value)
           # A never-set list stays NULL rather than becoming `[]`, matching Memory.
           return (value.nil? ? nil : state_json(value)) if attr.list?
@@ -43,26 +42,30 @@ module Hecks
 
         # A NULL projected-only column reads back absent.
         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
-                coerce_scalar(attr, 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)
+
+          coerce_scalar(attr, raw)
+        end
+
         def projected_only?(field)
           @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }

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

@@ -0,0 +1,50 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # The CREATE TABLE statements `SchemaBuilder` runs, as text. `ENTRY_TABLE` takes the
+      # quoted table name as `%<table>s`.
+      module Ddl
+        ENTRY_TABLE = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS %<table>s (
+            sequence     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            aggregate_id text NOT NULL,
+            operation    text NOT NULL DEFAULT 'save',
+            state        jsonb NOT NULL,
+            mirrors      jsonb
+          )
+        SQL
+
+        EVENTS = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS events (
+            id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            name         text NOT NULL,
+            aggregate    text NOT NULL,
+            aggregate_id text NOT NULL,
+            payload      jsonb,
+            occurred_at  text
+          )
+        SQL
+
+        CHECKPOINTS = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS hecks_checkpoints (
+            aggregate_table text PRIMARY KEY,
+            last_sequence   bigint NOT NULL DEFAULT 0
+          )
+        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               jsonb NOT NULL,
+            completed_compensations  jsonb NOT NULL DEFAULT '[]'::jsonb,
+            updated_at           timestamptz NOT NULL DEFAULT now(),
+            PRIMARY KEY (domain, process_manager, correlation)
+          )
+        SQL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # Postgres's hooks into the shared SqlQueryBuilder, plus identifier quoting.
+      module Dialect
+        private
+
+        def select_list = "*"
+        def from_relation = quoted_table
+        def dialect_name = "Postgres"
+        def empty_in_clause = "FALSE"
+
+        def placeholder(binds, value)
+          binds << value
+          "$#{binds.size}"
+        end
+
+        def contains_clause(expression, placeholder)
+          "position(#{placeholder} in #{expression}) > 0"
+        end
+
+        # `column` is already a real jsonb column and already the array — no shared
+        # `state` blob to walk into first, unlike PostgresEra's own version.
+        def list_contains_clause(column, member, placeholder)
+          target = member.empty? ? "elem #>> '{}'" : "elem ->> #{text_literal(member)}"
+          elements = "jsonb_array_elements(#{quote_ident(column)}) AS elem"
+          "EXISTS (SELECT 1 FROM #{elements} WHERE #{target} = #{placeholder})"
+        end
+
+        def plain_column(name) = quote_ident(name)
+
+        # The attribute name is the column itself here, not part of the path (unlike
+        # PostgresEra's shared `state` blob) — the path is whatever follows the column.
+        def nested_expression(name, path, member)
+          segments = path.empty? ? [(member || "value").to_s] : path
+          jsonb_path(name, segments)
+        end
+
+        # A jsonb-extracted value still comes out as text; cast it to compare/sort
+        # numerically instead of lexicographically.
+        def comparable_expression(expression, value)
+          value.is_a?(Numeric) && jsonb_extraction?(expression) ? "(#{expression})::numeric" : expression
+        end
+
+        def execute_query(sql, binds)
+          pg_exec_params(sql, binds).map { |row| instance_from_row(row) }
+        end
+
+        def quote_ident(name) = PG::Connection.quote_ident(name.to_s)
+        def quoted_table = quote_ident(table)
+        def entry_table = "#{table}_entries"
+        def quoted_entry_table = quote_ident(entry_table)
+
+        def jsonb_extraction?(expression) = expression.include?("#>>")
+
+        def order_expression(field)
+          expression = query_expression(field)
+          jsonb_extraction?(expression) && numeric_field?(field) ? "(#{expression})::numeric" : expression
+        end
+
+        # Overrides Postgres's default NULLS LAST on ASC so every adapter answers
+        # a declared query's null ordering identically.
+        def order_clause(order_by, policy)
+          direction = order_by.direction.to_s.downcase == "desc" ? "DESC" : "ASC"
+          nulls = case policy&.mode.to_s
+                  when "first" then " NULLS FIRST"
+                  when "last" then " NULLS LAST"
+                  else direction == "DESC" ? " NULLS LAST" : " NULLS FIRST"
+                  end
+          "#{order_expression(order_by.field)} #{direction}#{nulls}, id #{direction}"
+        end
+
+        # Same walk PostgresEra's own numeric_field? uses — decides
+        # numericness at any depth from the declared shape itself, not a
+        # runtime value.
+        def numeric_field?(field)
+          name, *path = field.to_s.split(".")
+          QuerySpecification::FieldPath.numeric?(@aggregate.attribute(name), path) do |type|
+            Runtime::Value.value_object_for(@aggregate, type)
+          end
+        end
+
+        # Builds an escaped Array[...] literal rather than a hand-rolled '{a,b,c}'
+        # string, since a segment name isn't guaranteed schema-declared.
+        def jsonb_path(column, segments)
+          "#{quote_ident(column)} #>> ARRAY[#{segments.map { |segment| text_literal(segment) }.join(", ")}]::text[]"
+        end
+
+        def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # Event log: every emitted event lands in the database's shared `events` table.
+      module Events
+        # Inserts an emitted event into the shared `events` table.
+        #
+        # @param event [Runtime::Event] the emitted event; `payload` is stored as JSON
+        # @return [PG::Result] the insert's result; callers ignore it
+        # @raise [PG::Error] if the insert fails
+        def record_event(event)
+          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
+
+        # Reads back every recorded event in insertion order — the 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 the String Postgres returns; `[]` when none are recorded
+        # @raise [PG::Error] if the statement fails
+        def events
+          pg_exec("SELECT * FROM events ORDER BY id").map { |row| event_from(row) }
+        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 [PG::Error] if the statement fails
+        def events_for(aggregate:, id:)
+          pg_exec_params(
+            "SELECT * FROM events WHERE aggregate = $1 AND aggregate_id = $2 ORDER BY id",
+            [aggregate, id.to_s]
+          ).map { |row| event_from(row) }
+        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/postgres/journal.rb

@@ -0,0 +1,127 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # 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 [PG::Error] if the insert fails
+        def append(entry)
+          result = pg_exec_params(
+            "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES ($1, $2, $3, $4) " \
+            "RETURNING sequence",
+            # `mirrors` is nullable; an absent hash must bind SQL NULL, not the
+            # string "null", or a future IS NULL check would never match.
+            [entry.id, entry.operation, state_json(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+          )
+          entry.sequence = result[0]["sequence"].to_i
+          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); `[]` when nothing has been appended
+        # @raise [PG::Error] 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 [PG::Error] 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 > $1 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 [PG::Error] if the statement fails
+        def checkpoint
+          result = pg_exec_params("SELECT last_sequence FROM hecks_checkpoints WHERE aggregate_table = $1", [table])
+          result.ntuples.zero? ? 0 : result[0]["last_sequence"].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 [PG::Error] if the statement fails
+        def compacted_through
+          result = pg_exec_params("SELECT compacted_through FROM hecks_checkpoints WHERE aggregate_table = $1", [table])
+          result.ntuples.zero? ? 0 : result[0]["compacted_through"].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 [PG::Error] if a statement fails
+        def compact_entries!(through:)
+          removed = pg_exec_params("DELETE FROM #{quoted_entry_table} WHERE sequence <= $1", [through]).cmd_tuples
+          pg_exec_params(
+            "INSERT INTO hecks_checkpoints (aggregate_table, compacted_through) VALUES ($1, $2) " \
+            "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+            "compacted_through = GREATEST(hecks_checkpoints.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 = [])
+          pg_exec_params(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)
+          pg_exec_params(
+            "INSERT INTO hecks_checkpoints (aggregate_table, last_sequence) VALUES ($1, $2) " \
+            "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+            "last_sequence = GREATEST(hecks_checkpoints.last_sequence, EXCLUDED.last_sequence)",
+            [table, sequence]
+          )
+        end
+      end
+    end
+  end
+end