hecks 3.5.0 → 3.6.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -1,5 +1,6 @@
 require_relative "../lineage"
 require_relative "../../storage_shape"
+require_relative "context"
 
 module Hecks
   module Adapters
@@ -8,7 +9,6 @@ module Hecks
         # Boot-time era resolution: first boot holds era 1, a quiet reboot changes nothing,
         # a superseded shape boots read-only, an unheld shape goes to the minter.
         module EraResolver
-          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           # Resolves which era this boot is and records it on the registry.
           #
           # @return [Integer, nil] the ordinal minted, or nil when this boot minted nothing
@@ -23,51 +23,75 @@ module Hecks
             lineage.ensure_base!
             # key? first, never `||`: a stored `false` must not read as an absent key.
             role = settings.key?(:role) ? settings[:role] : settings["role"]
+            resolve_era(Context.new(registry: registry, bluebook: bluebook, current_text: current_text,
+                                    lineage: lineage, role: role, directory: directory))
+          ensure
+            db&.close
+          end
 
-            held = lineage.eras
-            if held.empty?
-              lineage.hold_first!(current_text, projection: Runtime::StorageShape.project(bluebook))
-              bluebook.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) }
-              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: 1) if role
-              return
-            end
+          private
 
-            current_shape = Runtime::StorageShape.project(bluebook)
-            shapes = held.map { |era| [era, Runtime::StorageShape.project(shadow(era[:held_text]))] }
-            if bluebook.formerly_known_as
-              # Held text is frozen record and keeps the prior name; only the in-memory shape is
-              # normalized, and only on an exact match with the declared prior name.
-              shapes = shapes.map do |era, shape|
-                [era, shape["name"] == bluebook.formerly_known_as ? shape.merge("name" => bluebook.name) : shape]
-              end
-            end
+          def resolve_era(context)
+            held = context.lineage.eras
+            return hold_first_era(context) if held.empty?
 
+            shapes = held_shapes(context.bluebook, held)
             latest, latest_shape = shapes.last
-            if latest_shape == current_shape
-              bluebook.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) } if latest[:ordinal] == 1
-              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: latest[:ordinal]) if role
-              registry.resolved_eras[bluebook.name] = latest[:ordinal]
-              return
-            end
+            current_shape = context.current_shape
+            return resolve_latest(context, latest) if latest_shape == current_shape
 
             matched, = shapes.find { |_, shape| shape == current_shape }
-            if matched
-              # A superseded era (an old checkout) may read but not write: never advance_era!
-              # here, since the fence is already past this ordinal.
-              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
-              registry.resolved_eras[bluebook.name] = matched[:ordinal]
-              # The adapter refuses appends on this, even where the RLS fence cannot bind.
-              registry.superseded_eras[bluebook.name] = latest[:ordinal]
-              return
-            end
+            return resolve_superseded(context, matched, latest) if matched
 
-            registry.resolved_eras[bluebook.name] =
-              mint!(registry, bluebook, current_text, lineage, latest,
-                    role: role, directory: directory)
-          ensure
-            db&.close
+            context.record_resolved(mint!(context.with(latest: latest)))
+          end
+
+          def hold_first_era(context)
+            context.lineage.hold_first!(context.current_text, projection: context.current_shape)
+            ensure_first_heads!(context)
+            grant_role!(context, 1)
+            nil
+          end
+
+          # The latest held era is the current shape: nothing to mint.
+          def resolve_latest(context, latest)
+            ensure_first_heads!(context) if latest[:ordinal] == 1
+            grant_role!(context, latest[:ordinal])
+            context.record_resolved(latest[:ordinal])
+            nil
+          end
+
+          # A superseded era (an old checkout) may read but not write: never advance_era!
+          # here, since the fence is already past this ordinal.
+          def resolve_superseded(context, matched, latest)
+            grant_role!(context, matched[:ordinal])
+            context.record_resolved(matched[:ordinal])
+            # The adapter refuses appends on this, even where the RLS fence cannot bind.
+            context.record_superseded(latest[:ordinal])
+            nil
+          end
+
+          def ensure_first_heads!(context)
+            context.bluebook.aggregates.each { |aggregate| context.lineage.ensure_first_head!(aggregate.storage_name) }
+          end
+
+          def grant_role!(context, ordinal)
+            return unless context.role
+
+            context.lineage.grant_role!(context.role, aggregates: context.bluebook.aggregates, era: ordinal)
+          end
+
+          # Each held era with its storage shape. Held text is a frozen record and keeps the
+          # prior name; only the in-memory shape is normalized, and only on an exact match with
+          # the declared prior name.
+          def held_shapes(bluebook, held)
+            shapes = held.map { |era| [era, Runtime::StorageShape.project(shadow(era[:held_text]))] }
+            return shapes unless bluebook.formerly_known_as
+
+            shapes.map do |era, shape|
+              [era, shape["name"] == bluebook.formerly_known_as ? shape.merge("name" => bluebook.name) : shape]
+            end
           end
-          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         end
       end
     end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/merge_coordinator.rb

@@ -22,26 +22,31 @@ module Hecks
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
             lineage.ensure_base!
 
-            held = lineage.eras
+            chain = merge_chain(registry, bluebook, lineage.eras)
+            lineage.merge_tail!(aggregates: bluebook.aggregates, edges: chain, winners: winners,
+                                audit: head_audit(db, lineage, bluebook))
+          ensure
+            db&.close
+          end
+
+          private
+
+          # The edge chain from era 1 to the latest era.
+          def merge_chain(registry, bluebook, held)
             raise Runtime::WiringError, "nothing to merge — #{bluebook.name} stands at era 1" if held.size < 2
 
-            latest = held.last
-            chain = edge_chain(registry, bluebook, held[0..-2], latest[:label])
+            edge_chain(registry, bluebook, held[0..-2], held.last[:label])
+          end
 
-            audit = lambda do
-              violations = []
-              bluebook.aggregates.each do |aggregate|
-                rows = db.exec("SELECT id, state FROM #{PG::Connection.quote_ident(lineage.head_view(aggregate.storage_name))}")
-                         .to_h { |row| [row["id"], JSON.parse(row["state"])] }
-                verdict = Translation::Audit.check(aggregate: aggregate, declared: nil, before: rows, after: rows)
-                violations.concat(verdict.violations)
-              end
-              violations
-            end
+          # The audit the merge runs over the merged heads, answering every violation found.
+          def head_audit(db, lineage, bluebook)
+            -> { bluebook.aggregates.flat_map { |aggregate| head_violations(db, lineage, aggregate) } }
+          end
 
-            lineage.merge_tail!(aggregates: bluebook.aggregates, edges: chain, winners: winners, audit: audit)
-          ensure
-            db&.close
+          def head_violations(db, lineage, aggregate)
+            view = PG::Connection.quote_ident(lineage.head_view(aggregate.storage_name))
+            rows = db.exec("SELECT id, state FROM #{view}").to_h { |row| [row["id"], JSON.parse(row["state"])] }
+            Translation::Audit.check(aggregate: aggregate, declared: nil, before: rows, after: rows).violations
           end
         end
       end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -3,6 +3,8 @@ require_relative "../../storage_shape"
 require_relative "../../translation/audit"
 require_relative "../../translation/scaffold"
 require_relative "../../translation/approval_file"
+require_relative "context"
+require_relative "refusals"
 
 module Hecks
   module Adapters
@@ -11,48 +13,32 @@ module Hecks
         # Names the source era, resolves its one outgoing translation edge, and mints the
         # next era once approval, coverage and the audited chain all check out.
         module Minter
-          # Mints the next era for a drifted shape in one transaction.
-          def mint!(registry, bluebook, current_text, lineage, latest, role: nil, directory: nil)
-            ensure_named!(lineage, latest)
-            latest = lineage.eras.last
-
-            hash = Runtime::StorageShape.mint_hash(bluebook)
-            label = hash[0, Runtime::StorageShape::LABEL_LENGTH]
-            ordinal = latest[:ordinal] + 1
+          include Refusals
 
-            edge = resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
-            ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal, directory: directory)
-            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
-
-            chain = edge_chain(registry, bluebook, lineage.eras, label)
-            audit!(bluebook, lineage, chain, ordinal, edge)
-            lineage.mint_era!(
-              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
-              aggregates: bluebook.aggregates, edges: chain, role: role,
-              projection: Runtime::StorageShape.project(bluebook)
-            )
-            ordinal
+          # Mints the next era for a drifted shape in one transaction.
+          #
+          # @param context [Context] the era check so far; `latest` is the latest held era, named
+          #   here if it has no name yet
+          # @return [Integer] the ordinal of the era minted
+          # @raise [Runtime::WiringError] if the edge, its approval, its coverage or its audit
+          #   refuses
+          def mint!(context)
+            ensure_named!(context.lineage, context.latest)
+            context = context.with(latest: context.lineage.eras.last)
+            edge = verified_edge!(context)
+            chain = audited_chain!(context, edge)
+            commit_era!(context, chain)
           end
 
           # Finds the one translation edge leaving the held era and targeting the current
           # shape's label; a second edge from the same source is a wiring mistake, not a
           # merge to resolve automatically.
-          def resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
-            edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
-            refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory) if edges.empty?
-            if edges.size > 1
-              raise Runtime::WiringError,
-                    "cannot boot #{bluebook.name}: #{edges.size} translation edges leave era #{latest[:ordinal]} " \
-                    "(#{latest[:label]}) — eras fork mechanically; keep one edge per source shape"
-            end
-
-            edge = edges.first
-            unless edge.to == label
-              raise Runtime::WiringError,
-                    "cannot boot #{bluebook.name}: the translation edge from #{latest[:label]} targets " \
-                    "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run hecks scaffold_translation"
-            end
-            edge
+          def resolve_edge!(context)
+            edges = edges_leaving(context)
+            refuse_toward_the_scaffold!(context) if edges.empty?
+            refuse_forked_eras!(context, edges) if edges.size > 1
+            refuse_stale_edge!(context, edges.first)
+            edges.first
           end
 
           # Refuses a mint whose edge carries a compute or rekey rule without an approval.
@@ -62,52 +48,20 @@ module Hecks
           # tip, or a committed `translations/<edge>.approval` that matches the edge's digest and
           # records a passed rehearsal on a compatible host release. A committed approval that
           # applies is written into the journal, so the journal stays the single history.
-          def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal, directory: nil)
+          def ensure_compute_rekey_approved!(context, edge)
             return unless Translation::ApprovalFile.needs_rehearsal?(edge)
 
-            approval = lineage.approval_for(from: edge.from, to: edge.to)
+            approval = context.lineage.approval_for(from: edge.from, to: edge.to)
             digest = Translation::Audit.edge_digest(edge)
-            tip = lineage.last_ordinal
-            return if approval && approval[:edge_digest] == digest && approval[:reviewed_ordinal] == tip
+            tip = context.lineage.last_ordinal
+            return if approved_at_tip?(approval, digest, tip)
 
-            if Translation::ApprovalFile.applicable(directory, edge)
-              lineage.record_approval!(from: edge.from, to: edge.to, edge_digest: digest)
+            if Translation::ApprovalFile.applicable(context.directory, edge)
+              context.lineage.record_approval!(from: edge.from, to: edge.to, edge_digest: digest)
               return
             end
 
-            unless approval && approval[:edge_digest] == digest
-              if (mismatch = Translation::ApprovalFile.host_mismatch(directory, edge))
-                raise Runtime::WiringError,
-                      "cannot mint era #{ordinal} of #{bluebook.name}: the committed approval does not " \
-                      "apply — #{mismatch}"
-              end
-
-              raise Runtime::WiringError,
-                    "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
-                    "rule, and the audit's human-approved sample is its only verification — run " \
-                    "hecks audit_translation with --approve, then boot again"
-            end
-
-            raise Runtime::WiringError,
-                  "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
-                  "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
-                  "human approved no longer cover the data; re-run hecks audit_translation with --approve"
-          end
-
-          # Refuses toward the authoring loop, or, under HECKS_SCAFFOLD=1, scaffolds the
-          # missing edge first and names the file it wrote.
-          def refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
-            if ENV["HECKS_SCAFFOLD"] == "1" && directory
-              path = scaffold!(registry, bluebook, lineage, latest, directory)
-              raise Runtime::WiringError,
-                    "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) — wrote #{path}; " \
-                    "review it (resolve every unresolved), check it with hecks audit_translation, then boot again"
-            end
-
-            raise Runtime::WiringError,
-                  "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) and no translation edge " \
-                  "covers it — run hecks scaffold_translation to write the edge, " \
-                  "check it with hecks audit_translation, then boot again"
+            refuse_unapproved!(context, edge, approval, tip)
           end
 
           # Diffs the held era against the current shape and writes the edge file —
@@ -115,18 +69,11 @@ module Hecks
           def scaffold!(_registry, bluebook, lineage, latest, directory)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
-
-            hash = Runtime::StorageShape.mint_hash(bluebook)
-            held_bluebook = shadow(latest[:held_text])
-            diffed = Translation::Scaffold.diff(held_bluebook, bluebook)
+            label = Runtime::StorageShape.mint_hash(bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+            diffed = Translation::Scaffold.diff(shadow(latest[:held_text]), bluebook)
             edge = Translation::Scaffold::Edge.new(
-              domain:     bluebook.name,
-              from:       latest[:label],
-              to:         hash[0, Runtime::StorageShape::LABEL_LENGTH],
-              ordinal:    latest[:ordinal] + 1,
-              label:      hash[0, Runtime::StorageShape::LABEL_LENGTH],
-              aggregates: diffed[:aggregates],
-              retired:    diffed[:retired]
+              domain: bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
+              label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
             )
             Translation::Scaffold.write!(directory, edge)
           end
@@ -141,6 +88,39 @@ module Hecks
             hash = Runtime::StorageShape.mint_hash(held_bluebook)
             lineage.mint_name!(era[:ordinal], hash, hash[0, Runtime::StorageShape::LABEL_LENGTH])
           end
+
+          private
+
+          def edges_leaving(context)
+            context.registry.translations.select do |t|
+              t.domain == context.bluebook.name && t.from == context.latest[:label]
+            end
+          end
+
+          # The edge chain to the current shape, after its audit passes.
+          def audited_chain!(context, edge)
+            chain = edge_chain(context.registry, context.bluebook, context.lineage.eras, context.label)
+            audit!(context.bluebook, context.lineage, chain, context.ordinal, edge)
+            chain
+          end
+
+          # The edge leaving the held era, once resolved, approved and found to cover the diff.
+          def verified_edge!(context)
+            edge = resolve_edge!(context)
+            ensure_compute_rekey_approved!(context, edge)
+            check_coverage!(context.registry, context.bluebook, shadow(context.latest[:held_text]), edge)
+            edge
+          end
+
+          def commit_era!(context, chain)
+            hash = context.shape_hash
+            context.lineage.mint_era!(
+              ordinal: context.ordinal, hash: hash, label: hash[0, Runtime::StorageShape::LABEL_LENGTH],
+              held_text: context.current_text, aggregates: context.bluebook.aggregates, edges: chain,
+              role: context.role, projection: Runtime::StorageShape.project(context.bluebook)
+            )
+            context.ordinal
+          end
         end
       end
     end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/refusals.rb

@@ -0,0 +1,75 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The refusals a mint raises: toward the scaffold when no edge exists, and for a forked,
+        # stale or unapproved edge. Each is built from the era check's `Context`.
+        module Refusals
+          # Refuses toward the authoring loop, or, under HECKS_SCAFFOLD=1, scaffolds the
+          # missing edge first and names the file it wrote.
+          def refuse_toward_the_scaffold!(context)
+            if ENV["HECKS_SCAFFOLD"] == "1" && context.directory
+              path = scaffold!(context.registry, context.bluebook, context.lineage, context.latest, context.directory)
+              raise era_refusal(context, "the shape changed (era #{context.ordinal}) — wrote #{path}; " \
+                                         "review it (resolve every unresolved), check it with hecks audit_translation, " \
+                                         "then boot again", minting: false)
+            end
+
+            raise era_refusal(context, "the shape changed (era #{context.ordinal}) and no translation edge " \
+                                       "covers it — run hecks scaffold_translation to write the edge, " \
+                                       "check it with hecks audit_translation, then boot again", minting: false)
+          end
+
+          private
+
+          def refuse_forked_eras!(context, edges)
+            latest = context.latest
+            raise era_refusal(context, "#{edges.size} translation edges leave era #{latest[:ordinal]} " \
+                                       "(#{latest[:label]}) — eras fork mechanically; keep one edge per source shape",
+                              minting: false)
+          end
+
+          def refuse_stale_edge!(context, edge)
+            return if edge.to == context.label
+
+            raise era_refusal(context, "the translation edge from #{context.latest[:label]} targets " \
+                                       "#{edge.to}, but the current shape is #{context.label} — the edge is stale; " \
+                                       "re-run hecks scaffold_translation", minting: false)
+          end
+
+          # Whether the journal already holds an approval of this edge at the journal's tip.
+          def approved_at_tip?(approval, digest, tip)
+            approval && approval[:edge_digest] == digest && approval[:reviewed_ordinal] == tip
+          end
+
+          def refuse_unapproved!(context, edge, approval, tip)
+            if approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
+              raise era_refusal(context, "the journal advanced past the approved " \
+                                         "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
+                                         "human approved no longer cover the data; re-run hecks audit_translation with --approve")
+            end
+
+            mismatch = Translation::ApprovalFile.host_mismatch(context.directory, edge)
+            raise era_refusal(context, unapproved_reason(mismatch))
+          end
+
+          def unapproved_reason(mismatch)
+            return "the committed approval does not apply — #{mismatch}" if mismatch
+
+            "this edge carries a compute or rekey " \
+              "rule, and the audit's human-approved sample is its only verification — run " \
+              "hecks audit_translation with --approve, then boot again"
+          end
+
+          # Builds the refusal; a mint's own refusals say "cannot mint era N of X", the
+          # edge-resolution ones say "cannot boot X".
+          def era_refusal(context, text, minting: true)
+            name = context.bluebook.name
+            lead = minting ? "cannot mint era #{context.ordinal} of #{name}" : "cannot boot #{name}"
+            Runtime::WiringError.new("#{lead}: #{text}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager.rb

@@ -31,19 +31,37 @@ module Hecks
         # @raise [Runtime::WiringError] if no loaded translation leads one label to the next
         def edge_chain(registry, bluebook, eras, current_label)
           labels = eras.map { |era| era[:label] } + [current_label]
-          (0...(labels.size - 1)).map do |index|
-            step = registry.translations.find do |t|
-              t.domain == bluebook.name && t.from == labels[index] && t.to == labels[index + 1]
-            end
-            unless step
-              raise Runtime::WiringError,
-                    "cannot boot #{bluebook.name}: the edge chain is broken at era #{index + 1} — no translation " \
-                    "leads #{labels[index]} to #{labels[index + 1]}; restore bluebook/translations/"
-            end
+          labels.each_cons(2).with_index.map do |(from, to), index|
+            step = edge_between(registry, bluebook, from, to)
+            refuse_broken_chain!(bluebook, index, from, to) unless step
             { translation: step }
           end
         end
 
+        # Finds the loaded translation that leads one shape label to the next.
+        #
+        # @param registry [Runtime::Registry] the registry whose `translations` are searched
+        # @param bluebook [Bluebook::Chapter] the domain; only edges for its name count
+        # @param from [String] the shape label the edge leaves
+        # @param to [String] the shape label the edge reaches
+        # @return [Bluebook::Translation, nil] the edge, or nil when none is loaded
+        def edge_between(registry, bluebook, from, to)
+          registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == to }
+        end
+
+        # Refuses a boot whose edge chain has a gap.
+        #
+        # @param bluebook [Bluebook::Chapter] the domain, named in the message
+        # @param index [Integer] the zero-based step with no translation
+        # @param from [String] the shape label the missing edge would leave
+        # @param to [String] the shape label the missing edge would reach
+        # @raise [Runtime::WiringError] always
+        def refuse_broken_chain!(bluebook, index, from, to)
+          raise Runtime::WiringError,
+                "cannot boot #{bluebook.name}: the edge chain is broken at era #{index + 1} — no translation " \
+                "leads #{from} to #{to}; restore bluebook/translations/"
+        end
+
         # Parses a held era's bluebook text into a throwaway registry, not the live one.
         #
         # The predicate extractor reads source from disk, so the text goes through a scratch file.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/query_phases.rb

@@ -0,0 +1,63 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The two-phase query path: candidate ids from the field caches, then the head view
+      # restricted to them. The cache only narrows; the head view stays authoritative.
+      module QueryPhases
+        private
+
+        # Phase one: candidate ids from the narrow cache tables, INTERSECTed. Reuses `where_clause`
+        # against each cache's `value` column, so every operator `super` supports works here.
+        def cache_phase(cached)
+          binds = []
+          clauses = cached.map do |clause, value|
+            cache_table = @lineage.field_cache(table, @era, clause.field.to_s)
+            "SELECT id FROM #{quote_ident(cache_table)} WHERE #{where_clause(clause.op.to_s, quote_ident("value"), value, binds,
+                                                                             field: clause.field)}"
+          end
+          @db.exec_params(clauses.join("\nINTERSECT\n"), binds).map { |row| row["id"] }
+        end
+
+        # Phase two: the head view restricted to phase one's ids plus the clauses it could not
+        # accelerate. Repeats the tail of `SqlQueryBuilder#query` so that module stays untouched.
+        def head_phase(declared, uncached, ids, args)
+          binds = []
+          clauses = ["id IN (#{ids.map { |id| placeholder(binds, id) }.join(", ")})"]
+          uncached.each { |clause, value| clauses << uncached_clause(clause, value, binds) }
+
+          sql = "SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(" AND ")}"
+          sql += order_suffix(declared)
+          sql += paging_suffix(declared, binds, args)
+          execute_query(sql, binds)
+        end
+
+        # A clause cache phase could not serve: a null comparison's own predicate, else the
+        # operator's `where_clause` against the head view.
+        def uncached_clause(clause, value, binds)
+          expression = query_expression(clause.field, value: value)
+          null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value)
+          return null_predicate.first if null_predicate
+
+          where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
+        end
+
+        def order_suffix(declared)
+          return " ORDER BY id" unless declared.order_by
+
+          " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
+        end
+
+        def paging_suffix(declared, binds, args)
+          limit = declared.limit && " LIMIT #{placeholder(binds, page_value(declared.limit, args))}"
+          offset = declared.offset && " OFFSET #{placeholder(binds, page_value(declared.offset, args))}"
+          unbounded = unbounded_limit if !declared.limit && declared.offset
+          "#{limit}#{unbounded}#{offset}"
+        end
+
+        def page_value(bound, args) = query_value(bound.value, args).to_i
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/sagas.rb

@@ -0,0 +1,78 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Saga checkpoints. Rows keep `domain` as a column so domains sharing one schema stay
+      # isolated. No lock here: `SagaInterpreter`'s own mutex already serializes in-process writers.
+      module Sagas
+        # The DDL for the checkpoint table.
+        CREATE_SAGAS_SQL = <<~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
+
+        # Checkpoints one saga instance, replacing the row for the same (domain, process manager,
+        # correlation) if one exists.
+        #
+        # @param memory [Hash] the saga's memory, stored as JSON
+        # @param completed_compensations [Array] compensable legs already completed, stored as JSON
+        # @return [PG::Result] the upsert's result
+        def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+          @db.exec_params(
+            "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+            "VALUES ($1, $2, $3, $4, $5, $6) " \
+            "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
+            "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
+            "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
+            [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+             JSON.generate(completed_compensations)]
+          )
+        end
+
+        # Removes a finished saga instance's checkpoint; a no-op when no such row exists.
+        #
+        # @return [PG::Result] the DELETE's result
+        def delete_saga(process_manager:, correlation:)
+          @db.exec_params(
+            "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
+            [@domain, process_manager.to_s, correlation.to_s]
+          )
+        end
+
+        # Yields every saga checkpoint stored for this domain, so a booting registry can rehydrate.
+        #
+        # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, keys symbolized
+        # @return [Enumerator, PG::Result] an enumerator when no block is given
+        def each_saga
+          return enum_for(:each_saga) unless block_given?
+
+          @db.exec_params(
+            "SELECT process_manager, correlation, state, memory, completed_compensations " \
+            "FROM hecks_saga_instances WHERE domain = $1",
+            [@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
+
+        private
+
+        def create_saga_table!
+          @db.exec(CREATE_SAGAS_SQL)
+          # Covers a table created before this column existed, where IF NOT EXISTS is a no-op.
+          @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
+                   "NOT NULL DEFAULT '[]'::jsonb")
+        end
+      end
+    end
+  end
+end