hecks 5.0.0 → 6.0.0

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

@@ -1,4 +1,4 @@
-# Declares the PostgresEra adapter's port and fields; the class lives in the era plugin.
+# Declares the PostgresEra adapter's port and fields; the class is `postgres_era.rb` beside it.
 # This file is loaded on every boot, so it stays metadata only.
 Hecks.adapter "PostgresEra" do
   port  "persistence"
@@ -8,4 +8,10 @@ Hecks.adapter "PostgresEra" do
   # Opt-in to boot over a superuser or BYPASSRLS role, which the era write fence cannot
   # bite. Refused by default; see `Lineage#check_fence_applies!`.
   field :allow_superuser
+  # Whether this copy may migrate the database to a newer storage shape at boot, by minting the
+  # next era through a translation edge. `false` refuses; unset follows
+  # `LineageManager::EraResolver::MINT_BY_DEFAULT`; see `Refusals#refuse_unpermitted_mint!`.
+  field :mint_eras
+  # Rewrites every row of an aggregate in one statement, on the same SQL path as Postgres.
+  provides "set_transform"
 end

data/lib/hecks/{ports/persistence/plugins/era → adapters/driven}/postgres_era.rb

@@ -1,9 +1,10 @@
 require "json"
 
-require_relative "../../../../adapters/driven/sql_query_builder"
-require_relative "../../../../adapters/driven/postgres/outbox"
-require_relative "../../../../adapters/driven/postgres/reconnect"
-require_relative "../../../../adapters/driven/postgres/shared_connection"
+require_relative "../../ports/persistence/plugins/era"
+require_relative "sql_query_builder"
+require_relative "postgres/outbox"
+require_relative "postgres/reconnect"
+require_relative "postgres/shared_connection"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "postgres_era/events"
@@ -14,12 +15,12 @@ require_relative "postgres_era/journal"
 require_relative "postgres_era/dialect"
 require_relative "postgres_era/query_phases"
 require_relative "postgres_era/head_writes"
-require_relative "../../../../ports/persistence/append_only"
-require_relative "../../../../query_specification/common/order_by"
-require_relative "../../../../runtime/errors"
-require_relative "../../../../runtime/event"
-require_relative "../../../../runtime/instance"
-require_relative "../../../../runtime/registry"
+require_relative "../../ports/persistence/append_only"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/event"
+require_relative "../../runtime/instance"
+require_relative "../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -48,8 +49,8 @@ module Hecks
       # the same transaction as the journal row, so replaying the journal through `project` on
       # boot has nothing left to fix up.
       #
-      # @return [Array<Symbol>] always `[:atomic_put, :cross_process_lock, :atomic_append]`
-      def persistence_capabilities = %i[atomic_put cross_process_lock atomic_append]
+      # @return [Array<Symbol>] atomic_put, cross_process_lock, atomic_append, dispatch_claims
+      def persistence_capabilities = %i[atomic_put cross_process_lock atomic_append dispatch_claims]
 
       # Declares that this adapter can act on shape drift rather than only refuse.
       #
@@ -192,7 +193,7 @@ module Hecks
 
       def refuse_unknown_order_field!(order_by)
         name = order_by.to_s.split(".").first
-        return if @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+        return if @aggregate.lifecycle_field.to_s == name || @aggregate.attribute(name)
 
         raise Runtime::WiringError,
               "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"

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

@@ -45,8 +45,8 @@ module Hecks
         file, line = block.source_location
         return nil unless file && File.readable?(file)
 
-        node = block_node_at(file, line)
-        node&.body&.slice
+        body = block_node_at(file, line)&.body
+        body&.slice
       end
 
       # Finds the parsed block node starting on a given line of a file.
@@ -72,7 +72,8 @@ module Hecks
         walk(tree) do |node|
           next unless node.is_a?(::Prism::BlockNode)
 
-          index[node.location.start_line] ||= node
+          location = node.location
+          index[location.start_line] ||= node
         end
         index
       end

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

@@ -0,0 +1,126 @@
+require_relative "../../../runtime/instance"
+require_relative "../../../runtime/value"
+require_relative "../../../runtime/errors"
+require_relative "../../../runtime/refusal_wording"
+require_relative "../../../rendering"
+require_relative "../../../ports/query/in_memory"
+require_relative "row_decoding"
+
+module Hecks
+  module Adapters
+    # What a projection adapter shares, whatever its SQL dialect.
+    module Projection
+      # The read-model answer a projection gives from its own tables, the same walk
+      # `Runtime::ReadModelInterpreter` makes in process (ADR 0122 checks they agree).
+      #
+      # The including adapter supplies `projected_row(aggregate, id)`, the raw row for one id
+      # or nil, and `related_rows(aggregate, matches)`, the raw rows whose reference column
+      # holds any of the `[attribute, id]` pairs, ordered by id; `RowDecoding` turns each row
+      # into an instance through the adapter's own `decode_column`.
+      module ReadModelWalk
+        include RowDecoding
+
+        # The state of one `query_read_model` call, threaded through its per-head steps.
+        ReadModelRun = Struct.new(:model, :args, :bluebook, :reference_id, :eligible, :projected)
+
+        # Executes a declared read model against the projected read-store tables.
+        #
+        # A missing root raises, matching the in-process interpreter; a head
+        # matches against any already-projected source, not only the root.
+        #
+        # @param _domain [String, Symbol] domain name; not read
+        # @param model [Bluebook::ReadModel, Runtime::TenantScope::Scoped] read model to answer
+        # @param args [Hash] arguments; `model.reference_name` holds the root id
+        # @param bluebook [Bluebook::Declaration, nil] resolves each included aggregate; nil refused
+        # @return [Array<Hash>] one-element Array of the report, keyed by each head's `as`
+        # @raise [ArgumentError] if bluebook is nil
+        # @raise [Runtime::NotFound] if no projected row matches the referenced root id
+        def query_read_model(_domain, model, args, bluebook = nil)
+          raise ArgumentError, "projection query needs its domain bluebook" unless bluebook
+
+          # Read the same way ReadModelInterpreter reads it: an identity is a
+          # declared path, not unwrapped.
+          reference_id = args.fetch(model.reference_name).to_s
+          # 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.
+          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
+
+        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 }
+          root_heads + other_heads
+        end
+
+        # 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)
+          model = run.model
+          return select_related(aggregate, run.projected) unless head[:aggregate] == 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 select_projected(aggregate, id)
+          row = projected_row(aggregate, id.to_s)
+          row && projected_instance(aggregate, row)
+        end
+
+        # Matches every already-projected source, not just the root, so a head
+        # referencing another included head still matches. A head that names no aggregate of the
+        # bluebook (an entity, such as the language's `Handler`) has no rows, as the in-process loop
+        # reads it.
+        def select_related(aggregate, projected)
+          return [] unless aggregate
+
+          matches = projected.flat_map { |source| reference_matches(aggregate, source) }
+          return [] if matches.empty?
+
+          related_rows(aggregate, matches).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.target_name == source[:aggregate].to_s
+          end
+          return [] if references.empty?
+
+          ids = source[:rows].map { |row| row.id.to_s }
+          references.product(ids)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+require_relative "../../../runtime/instance"
+
+module Hecks
+  module Adapters
+    module Projection
+      # Reads a projected row of any aggregate back into an instance, so one adapter can answer
+      # every head of a read model and not only its own aggregate.
+      #
+      # The including adapter supplies `decode_column(aggregate, attribute, raw)`: how one
+      # declared column's stored text reads back in its dialect.
+      module RowDecoding
+        private
+
+        def projected_instance(aggregate, row)
+          Runtime::Instance.new(aggregate: aggregate, id: row["id"], state: decode_for(aggregate, row))
+        end
+
+        def decode_for(aggregate, row)
+          decode_fields(fields_for(aggregate), aggregate, row)
+        end
+
+        # Declared attributes plus the lifecycle field and any unlisted
+        # `projects` fields, all read back raw (see `decode_fields`).
+        def fields_for(aggregate)
+          fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
+          # `projects` fields (ADR 0025) read back raw too, as `persisted_fields` writes them.
+          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
+
+        # Decoded through the state codec against the row's own aggregate, so a NULL
+        # projected-only column reads back absent.
+        def decode_fields(fields, aggregate, row)
+          state = fields.each_with_object({}) do |(name, attribute), raw_state|
+            raw = row[name.to_s]
+            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
+
+        # Whether `attribute` is stored as JSON: a list, or a value object of `aggregate`.
+        def json_column?(aggregate, attribute)
+          attribute.list? || !aggregate.value_object(attribute.type).nil?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/set_transform/assignments.rb

@@ -0,0 +1,101 @@
+module Hecks
+  module Adapters
+    module SetTransform
+      # Compiles a statement's writes, its `SET` list, and the lifecycle conditions they bring:
+      # each assignment as its field is stored, and a lifecycle transition as a `CASE` over the
+      # states it moves from.
+      module Assignments
+        private
+
+        # @return [Array(Array<String>, Array<String>)] the assignments and the filter conditions
+        #   the lifecycle adds
+        def set_list(statement, build)
+          sets = statement.assignments.map { |assignment| assignment_sql(assignment, build) }
+          lifecycle_sets, conditions = lifecycle_moves(statement, build)
+          [sets + lifecycle_sets + version_bump, conditions]
+        end
+
+        # The lifecycle's assignment and the filter conditions its transition and `from:` guard add.
+        def lifecycle_moves(statement, build)
+          sets = []
+          conditions = []
+          if statement.transition
+            case_sql, condition = transition_sql(statement.transition, build)
+            sets << "#{quote_ident(@aggregate.lifecycle_field)} = #{case_sql}"
+            conditions << condition
+          end
+          conditions << state_in(statement.from_guard, build) if statement.from_guard
+          [sets, conditions]
+        end
+
+        def assignment_sql(assignment, build)
+          field = writable_field(assignment.target)
+          "#{quote_ident(field.name)} = #{assigned_value(field, assignment, build)}"
+        end
+
+        def assigned_value(field, assignment, build)
+          case assignment.kind
+          when :constant then constant_sql(field, assignment.value, build)
+          when :copy then copied_sql(field, assignment.value)
+          when :expression then expression_write(field, value_sql(assignment.value, build, strict: true), build)
+          when :step then stepped_sql(field, assignment.value, build)
+          else raise Uncompilable, "#{dialect_name} has no set-transform form for a #{assignment.kind} write"
+          end
+        end
+
+        # A constant is encoded once by this store's own codec, so every row holds what a save
+        # of that value would have written.
+        def constant_sql(field, value, build)
+          encoded = encode(@aggregate.attribute(field.name), value)
+          encoded.nil? ? "NULL" : typed_placeholder(build.binds, encoded, :json)
+        end
+
+        def copied_sql(field, source)
+          same_shape = @aggregate.attribute(source)&.type == @aggregate.attribute(field.name).type
+          raise Uncompilable, "#{dialect_name} copies a field only from one of the same type" unless same_shape
+
+          quote_ident(source)
+        end
+
+        def expression_write(field, operand, build)
+          raise Uncompilable, "#{field.name} holds #{field.type}, not #{operand.type}" unless operand.type == field.type
+
+          build.guards << "#{operand.sql} IS NOT NULL"
+          scalar_write(field.member, operand.sql)
+        end
+
+        def stepped_sql(field, amount, build)
+          raise Uncompilable, "#{dialect_name} steps only an Integer field" unless field.type == :integer
+
+          current = scalar_read(field.name, field.member, field.type)
+          build.guards << "#{current} IS NOT NULL"
+          sum = "(#{current} + #{typed_placeholder(build.binds, amount, :integer)})"
+          guard = integer_guard(sum)
+          build.guards << guard if guard
+          scalar_write(field.member, sum)
+        end
+
+        def writable_field(name)
+          field = Runtime::ScalarField.of(@aggregate, name)
+          return field if field&.writable?
+
+          raise Uncompilable, "#{dialect_name} writes #{name} only through a dispatch"
+        end
+
+        # Each case in order: the first whose states hold the current one, or that names none.
+        def transition_sql(cases, build)
+          conditions = cases.map { |from, _| from ? state_in(from, build) : "TRUE" }
+          whens = conditions.zip(cases).map do |condition, (_, target)|
+            "WHEN #{condition} THEN #{typed_placeholder(build.binds, target.to_s, :string)}"
+          end
+          ["CASE #{whens.join(" ")} END", "(#{conditions.join(" OR ")})"]
+        end
+
+        def state_in(states, build)
+          slots = Array(states).map { |state| typed_placeholder(build.binds, state.to_s, :string) }
+          "(COALESCE(#{quote_ident(@aggregate.lifecycle_field)}, '') IN (#{slots.join(", ")}))"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/set_transform/expressions.rb

@@ -0,0 +1,138 @@
+require_relative "../../../bluebook/expression"
+require_relative "../../../naming"
+require_relative "../../../runtime/scalar_field"
+
+module Hecks
+  module Adapters
+    module SetTransform
+      # Raised while compiling, before anything is written, when an expression or a write has no
+      # SQL form that means what Ruby means by it.
+      class Uncompilable < StandardError; end
+
+      # One compiled operand: its SQL text and the type Ruby would hold it as (`:integer`,
+      # `:float`, `:string`, or `:null` for a literal nil).
+      Operand = Struct.new(:sql, :type)
+
+      # What one statement collects while it compiles: the binds in placeholder order, the guards
+      # every updated row must also meet, and the command's arguments an expression reads.
+      Build = Struct.new(:binds, :guards, :arguments)
+
+      # Compiles a parsed bluebook expression to SQL in the including adapter's dialect. Every
+      # column an ordering comparison, an arithmetic operator or a sign test reads gets an
+      # `IS NOT NULL` guard, and every integer result the dialect's integer guard, so a row where
+      # Ruby would fault is never updated: the statement skips it and Ruby decides.
+      module Expressions
+        EVALUATOR = Bluebook::Expression::Evaluator
+        RESOLVER  = Bluebook::Expression::Resolver
+        ORDERING  = %w[< > <= >=].freeze
+        NUMERIC   = %i[integer float].freeze
+        SIGN_TESTS = { "positive?" => "> 0", "negative?" => "< 0", "zero?" => "= 0" }.freeze
+        ARITHMETIC = { RESOLVER::Addition => "+", RESOLVER::Subtraction => "-", RESOLVER::Multiplication => "*" }.freeze
+
+        private
+
+        def predicate_sql(node, build)
+          case node
+          when EVALUATOR::Or  then "(#{predicate_sql(node.left, build)} OR #{predicate_sql(node.right, build)})"
+          when EVALUATOR::And then "(#{predicate_sql(node.left, build)} AND #{predicate_sql(node.right, build)})"
+          when EVALUATOR::Not then "(NOT #{predicate_sql(node.node, build)})"
+          when EVALUATOR::Compare then compare_sql(node, build)
+          when EVALUATOR::Resolve then test_sql(node.expr, build)
+          else uncompilable(node)
+          end
+        end
+
+        def compare_sql(node, build)
+          symbol = node.operator_symbol
+          ordering = ORDERING.include?(symbol)
+          left, right = [node.left, node.right].map { |side| value_sql(side, build, strict: ordering) }
+          return equality_sql(left, right, symbol, node) unless ordering
+
+          uncompilable(node) unless ordered_pair?(left, right)
+          "(#{ordered_text(left)} #{symbol} #{ordered_text(right)})"
+        end
+
+        def equality_sql(left, right, symbol, node)
+          uncompilable(node) unless %w[== !=].include?(symbol) && comparable?(left, right)
+          null_safe_equality(left.sql, right.sql, negated: symbol == "!=")
+        end
+
+        def ordered_pair?(left, right)
+          (NUMERIC.include?(left.type) && NUMERIC.include?(right.type)) || [left.type, right.type] == %i[string string]
+        end
+
+        def comparable?(left, right)
+          left.type == :null || right.type == :null || ordered_pair?(left, right)
+        end
+
+        def ordered_text(operand) = operand.type == :string ? text_ordering(operand.sql) : operand.sql
+
+        def test_sql(node, build)
+          case node
+          when RESOLVER::SignTest then sign_test_sql(node, build)
+          when RESOLVER::Assignment
+            "(#{value_sql(node.receiver, build, strict: false).sql} IS #{"NOT " unless node.negated}NULL)"
+          else uncompilable(node)
+          end
+        end
+
+        def sign_test_sql(node, build)
+          receiver = value_sql(node.receiver, build, strict: true)
+          uncompilable(node) unless NUMERIC.include?(receiver.type) && SIGN_TESTS.key?(node.test)
+          "(#{receiver.sql} #{SIGN_TESTS.fetch(node.test)})"
+        end
+
+        def value_sql(node, build, strict:)
+          case node
+          when RESOLVER::IntegerLiteral, RESOLVER::FloatLiteral, RESOLVER::StringLiteral then scalar_bind(node.value, build)
+          when RESOLVER::NilLiteral then strict ? uncompilable(node) : Operand.new("NULL", :null)
+          when RESOLVER::Lookup then lookup_sql(node, build, strict)
+          when *ARITHMETIC.keys then arithmetic_sql(node, build)
+          else uncompilable(node)
+          end
+        end
+
+        # An argument is read before a field of the same name, as Ruby reads it.
+        def lookup_sql(node, build, strict)
+          name = node.path.to_sym
+          return argument_sql(build.arguments[name], build, strict, node) if build.arguments.key?(name)
+
+          field = Runtime::ScalarField.of(@aggregate, node.path) || uncompilable(node)
+          operand = Operand.new(field_read(field), field.type)
+          build.guards << "#{operand.sql} IS NOT NULL" if strict
+          operand
+        end
+
+        def argument_sql(value, build, strict, node)
+          return Operand.new("NULL", :null) if value.nil? && !strict
+
+          scalar_bind(value, build) || uncompilable(node)
+        end
+
+        def arithmetic_sql(node, build)
+          left, right = [node.left, node.right].map { |side| value_sql(side, build, strict: true) }
+          uncompilable(node) unless [left.type, right.type] == %i[integer integer]
+
+          sql = "(#{left.sql} #{ARITHMETIC.fetch(node.class)} #{right.sql})"
+          guard = integer_guard(sql)
+          build.guards << guard if guard
+          Operand.new(sql, :integer)
+        end
+
+        # A bound literal or argument, typed by the Ruby value it holds; nil for any other value.
+        def scalar_bind(value, build)
+          type = { Integer => :integer, Float => :float, String => :string }.find { |klass, _| value.is_a?(klass) }&.last
+          type && Operand.new(typed_placeholder(build.binds, value, type), type)
+        end
+
+        def field_read(field)
+          field.lifecycle? ? quote_ident(field.name) : scalar_read(field.name, field.member, field.type)
+        end
+
+        def uncompilable(node)
+          raise Uncompilable, "#{dialect_name} has no set-transform form for #{Naming.demodulise(node.class)}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+require_relative "set_transform/expressions"
+require_relative "set_transform/assignments"
+require_relative "../../ports/persistence/append_only"
+
+module Hecks
+  module Adapters
+    # A SQL store's `set_transform` (ADR 0129): one update statement, filtered by the query and the
+    # givens and returning every row it changed, for a {Ports::Persistence::SetStatement},
+    # journalled row by row in the same transaction. Mixed into an adapter that includes
+    # {SqlQueryBuilder}, whose filter clauses it reuses, and a
+    # set dialect that supplies the SQL spellings: `typed_placeholder`, `null_safe_equality`,
+    # `text_ordering`, `integer_guard`, `scalar_read`, `scalar_write`, `version_bump`,
+    # `run_set_transform` and `set_transform_dialect`.
+    module SetTransform
+      # Raised when the store refused the statement (an overflow, a lost connection) after it was
+      # sent; the transaction it ran in is rolled back.
+      class Declined < StandardError; end
+
+      include Expressions
+      include Assignments
+
+      # Compiles a statement to SQL without running it.
+      #
+      # @param statement [Ports::Persistence::SetStatement] the command over the query
+      # @return [Array(String, Array)] the update statement and its binds in placeholder order
+      # @raise [SetTransform::Uncompilable] if part of the statement has no form in this dialect
+      def compile_set_transform(statement)
+        build = Build.new([], [], statement.arguments || {})
+        sets, conditions = set_list(statement, build)
+        clauses = where_list(statement, build, conditions)
+        sql = "UPDATE #{quoted_table} SET #{sets.join(", ")}"
+        sql << " WHERE #{clauses.join(" AND ")}" unless clauses.empty?
+        ["#{sql} RETURNING *", build.binds]
+      end
+
+      # Runs a statement and journals every row it updated, inside one transaction (joining an
+      # open one).
+      #
+      # @param statement [Ports::Persistence::SetStatement] the command over the query
+      # @return [Array<Runtime::Instance>] each updated row as it now stands, in no set order
+      # @raise [SetTransform::Uncompilable] before anything is written
+      # @raise [SetTransform::Declined] if the store refused the statement
+      def apply_set_transform(statement)
+        sql, binds = compile_set_transform(statement)
+        transaction do
+          instances = run_set_transform(sql, binds)
+          journal_set(instances)
+          instances
+        end
+      end
+
+      private
+
+      # The query's clauses, the lifecycle's conditions, the givens, then every guard compiling
+      # them collected.
+      def where_list(statement, build, conditions)
+        wheres = query_conditions(statement, build) + conditions +
+                 statement.givens.map { |node| predicate_sql(node, build) }
+        wheres + build.guards.uniq
+      end
+
+      def query_conditions(statement, build)
+        query = statement.query
+        if query.wheres.any? { |clause| SqlQueryBuilder::IN_MEMORY_OPERATORS.include?(clause.op.to_s) } ||
+           query.limit || query.offset
+          raise Uncompilable, "#{dialect_name} cannot rewrite the rows of a paged or partly in-memory query"
+        end
+
+        where_clauses(query, statement.query_args || {}, build.binds)
+      end
+
+      # One journal entry per row, then the checkpoint once, as a row-by-row save would leave it.
+      def journal_set(instances)
+        entries = instances.map do |instance|
+          append(Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup))
+        end
+        advance_checkpoint!(entries.map(&:sequence).max) unless entries.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require_relative "../../ports/query/cursor"
+
+module Hecks
+  module Adapters
+    # The keyset predicate of a cursor query, compiled for the SQL dialects: the rows that follow
+    # a position `(value, id)` in the query's own `ORDER BY`.
+    #
+    # `Ports::Query::Cursor` states the same rule over Ruby rows, so the two answer alike. Mixed
+    # into {SqlQueryBuilder}; the dialect supplies `placeholder`, `query_expression`,
+    # `comparable_expression` and, when it orders through its own expression, `order_expression`.
+    module SqlKeyset
+      private
+
+      # The wheres, then the cursor's keyset when the ask carries a position.
+      def restricting_clauses(declared, args, binds)
+        where_clauses(declared, args, binds) + [keyset_clause(declared, args, binds)].compact
+      end
+
+      # @param declared [QuerySpecification::Common::Options] a query that may declare `cursor`
+      # @param args [Hash] the ask's arguments; `:after` carries the token
+      # @param binds [Array] filled in place, after the binds already there
+      # @return [String, nil] the predicate, nil when the query has no cursor or no token
+      def keyset_clause(declared, args, binds)
+        position = declared.cursor && Ports::Query::Cursor.decode(args[:after])
+        return unless position
+        return "id > #{placeholder(binds, position.id)}" unless declared.order_by
+
+        keyset_over_field(declared, position, binds)
+      end
+
+      def keyset_over_field(declared, position, binds)
+        order_by = declared.order_by
+        expression = keyset_expression(order_by.field, position.value)
+        beyond = order_by.direction.to_s.downcase == "desc" ? "<" : ">"
+        first = Ports::Query::Cursor.nulls_first?(order_by.direction, declared.null_semantics)
+        return keyset_after_null(expression, beyond, first, position, binds) if position.value.nil?
+
+        keyset_after_value(expression, beyond, first, position, binds)
+      end
+
+      # Rows that follow a null-keyed row: later nulls by id, and every valued row when nulls lead.
+      def keyset_after_null(expression, beyond, nulls_first, position, binds)
+        tied = "(#{expression} IS NULL AND id #{beyond} #{placeholder(binds, position.id)})"
+        nulls_first ? "(#{tied} OR #{expression} IS NOT NULL)" : tied
+      end
+
+      # Rows that follow a valued row: later values, equal values with a later id, and the nulls
+      # when they trail.
+      def keyset_after_value(expression, beyond, nulls_first, position, binds)
+        later = "#{expression} #{beyond} #{placeholder(binds, position.value)}"
+        tied = "(#{expression} = #{placeholder(binds, position.value)} AND id #{beyond} #{placeholder(binds, position.id)})"
+        nulls_first ? "(#{later} OR #{tied})" : "(#{later} OR #{tied} OR #{expression} IS NULL)"
+      end
+
+      def keyset_expression(field, value)
+        expression = respond_to?(:order_expression, true) ? order_expression(field) : query_expression(field, value: value)
+        comparable_expression(expression, value)
+      end
+    end
+  end
+end