hecks 4.0.0 → 6.0.0

data/lib/hecks/adapters/driven/postgres_dump/connection.rb

@@ -0,0 +1,57 @@
+require "uri"
+
+module Hecks
+  module Adapters
+    class PostgresDump
+      # A Postgres connection URL, split so a password reaches child-process tools
+      # through their environment, never on a command line the process list exposes.
+      class Connection
+        def initialize(url)
+          @uri = URI.parse(url)
+          raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
+        end
+
+        # Names the database the URL points at, empty when the URL names none.
+        def database
+          @uri.path.to_s.delete_prefix("/")
+        end
+
+        # Points the same server and credentials at another database; this one is unchanged.
+        def with_database(name)
+          copy = @uri.dup
+          copy.path = "/#{name}"
+          self.class.new(copy.to_s)
+        end
+
+        # Lists the connection settings the URL carries, in `PG.connect` keyword form; the
+        # user and password come back percent-decoded.
+        def settings
+          {
+            host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
+            user: decode(@uri.user), password: decode(@uri.password),
+            dbname: (database unless database.empty?), sslmode: query_params["sslmode"]
+          }.compact
+        end
+
+        # Builds the libpq environment variables for a child process.
+        def env
+          settings.to_h { |key, value| ["PG#{key.to_s.sub("dbname", "database").upcase}", value.to_s] }
+        end
+
+        # Opens a connection with the `pg` gem; the caller closes it.
+        def connect
+          require "pg"
+          PG.connect(**settings)
+        end
+
+        private
+
+        def query_params = URI.decode_www_form(@uri.query.to_s).to_h
+
+        def decode(value)
+          value && URI.decode_www_form_component(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+require "open3"
+require "securerandom"
+require_relative "postgres_dump/connection"
+require_relative "../../text"
+require_relative "../../ports/persistence"
+
+module Hecks
+  module Adapters
+    # Dumps one schema of a Postgres database and proves the dump restores, by
+    # restoring it into a scratch database and comparing every table's row count.
+    class PostgresDump
+      # Raised for a refusal or a failed tool.
+      class Error < StandardError; end
+
+      # What a verified dump holds: `tables` is each table's row count, by name.
+      Result = Struct.new(:tables, keyword_init: true)
+
+      # A schema name that needs no quoting: a letter or underscore, then word characters.
+      PLAIN_IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/i
+
+      # Splits `url` and `verify_url` into connections and validates `schema`.
+      def initialize(url:, schema:, verify_url: nil)
+        raise Error, "schema #{schema.inspect} is not a plain identifier" unless schema.to_s.match?(PLAIN_IDENTIFIER)
+
+        @schema = schema
+        @source = Connection.new(url)
+        @verify = Connection.new(verify_url || url)
+      end
+
+      # Writes a custom-format dump of the schema and proves it restores.
+      def call(dest)
+        require "pg"
+        raise Error, "schema #{@schema} has no tables in #{@source.database}" if source_counts.empty?
+
+        run("pg_dump", @source, "--format=custom", "--no-owner", "--no-privileges", "--schema=#{@schema}", "--file=#{dest}")
+        expected = source_counts
+        verify_restore(dest, expected)
+        Result.new(tables: expected)
+      rescue PG::Error => e
+        raise Error, "database error (#{e.class}): #{Text.first_line(e.message)}"
+      end
+
+      private
+
+      # The first few lines of a tool's stderr, enough to say why it failed.
+      def opening_lines(text)
+        head = text.lines.first(3)
+        head.join.strip
+      end
+
+      def source_counts = counting(@source) { |db| counts(db) }
+
+      def verify_restore(dump, expected)
+        scratch = "dump_verify_#{Process.pid}_#{SecureRandom.hex(3)}"
+        counting(@verify) do |admin|
+          admin.exec("CREATE DATABASE #{admin.quote_ident(scratch)}")
+          begin
+            restore_and_compare(dump, scratch, expected)
+          ensure
+            drop(admin, scratch)
+          end
+        end
+      end
+
+      def restore_and_compare(dump, scratch, expected)
+        target = @verify.with_database(scratch)
+        run("pg_restore", target, "--no-owner", "--no-privileges", "--exit-on-error", "--dbname=#{scratch}", dump)
+        actual = counting(target) { |db| counts(db) }
+        raise Error, mismatch(expected, actual) unless actual == expected
+      end
+
+      def counting(connection)
+        db = connection.connect
+        yield db
+      ensure
+        db&.close
+      end
+
+      def counts(db)
+        names = db.exec_params("SELECT table_name FROM information_schema.tables " \
+                               "WHERE table_schema = $1 AND table_type = 'BASE TABLE' ORDER BY 1", [@schema])
+                  .map { |row| row["table_name"] }
+        names.to_h do |name|
+          [name, db.exec("SELECT count(*) FROM #{db.quote_ident(@schema)}.#{db.quote_ident(name)}").getvalue(0, 0).to_i]
+        end
+      end
+
+      def mismatch(expected, actual)
+        differing = (expected.keys | actual.keys).reject { |name| expected[name] == actual[name] }
+        detail = differing.map { |name| "#{name} (source #{expected[name].inspect}, restored #{actual[name].inspect})" }
+        "the restored dump disagrees with the source for #{detail.join(", ")}; " \
+          "if the database took writes during the dump, dump it again"
+      end
+
+      def drop(admin, scratch)
+        admin.exec("DROP DATABASE IF EXISTS #{admin.quote_ident(scratch)} WITH (FORCE)")
+      rescue PG::Error => e
+        warn "could not drop scratch database #{scratch} (#{e.class}); drop it by hand"
+      end
+
+      def run(tool, connection, *)
+        _out, err, status = Open3.capture3(connection.env, tool, *)
+        raise Error, "#{tool} failed: #{opening_lines(err)}" unless status.success?
+      rescue Errno::ENOENT
+        raise Error, "#{tool} is not on PATH"
+      end
+    end
+  end
+
+  module Ports
+    # The persistence port, reopened only to keep the name below.
+    module Persistence
+      # The name embryonaut_platform's handoff tooling reaches it by.
+      PostgresDump = Adapters::PostgresDump
+    end
+  end
+end

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

@@ -1,4 +1,4 @@
-require_relative "../../../../../indifferent_key"
+require_relative "../../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -11,8 +11,9 @@ module Hecks
         # Journal name: the owning bluebook's declared name, matching the key rust/host derives its
         # advisory lock from (ADR 0036). A bare aggregate with no owner falls back to its own name.
         def journal_domain(aggregate, settings)
+          owner = aggregate.hecks_owner
           self.class.setting(
-            settings, :domain, default: aggregate.hecks_owner&.name || aggregate.storage_name
+            settings, :domain, default: owner&.name || aggregate.storage_name
           ).to_s
         end
 
@@ -29,7 +30,9 @@ module Hecks
         def provision!
           # Idempotent self-healing against any boot-ordering surprise.
           @lineage.ensure_head_snapshot!(table, @era)
-          @lineage.ensure_first_head!(table) if @era == 1
+          # A superseded boot reads and never reshapes: era 1's head view is not its to restore,
+          # because a mint has already pointed the view at a later era.
+          @lineage.ensure_first_head!(table) if @era == 1 && !@superseded_by
           # One row-cache table per where-field the aggregate's queries use; `query` consults it
           # to skip the head reduction.
           @field_caches = ensure_field_caches!

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

@@ -1,4 +1,4 @@
-require_relative "../../../../../runtime/errors"
+require_relative "../../../runtime/errors"
 
 module Hecks
   module Adapters

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

@@ -118,7 +118,7 @@ module Hecks
         # List fields are excluded: a one-value cache row cannot hold `contains` membership.
         def cacheable_field?(field)
           name = field.to_s.split(".").first
-          return true if @aggregate.lifecycle&.field.to_s == name
+          return true if @aggregate.lifecycle_field.to_s == name
 
           attribute = @aggregate.attribute(name)
           !attribute.nil? && !attribute.list?

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

@@ -1,5 +1,5 @@
-require_relative "../../../../../../naming"
-require_relative "../../translation/rule_compiler"
+require_relative "../../../../naming"
+require_relative "../../../../ports/persistence/plugins/era/translation/rule_compiler"
 require_relative "sql_templates"
 
 module Hecks
@@ -139,11 +139,15 @@ module Hecks
             " AND ordinal <= #{cut}" if cut
           end
 
-          # One link of the chain: its edge's rules over the previous link.
+          # One link of the chain: its edge's rules over the previous link. A link is `MATERIALIZED`
+          # because its `CASE` names `state` twice: left to Postgres to inline, each link doubles
+          # the
+          # expression of the one before, and a chain of eighteen links overflows the 65,535
+          # range-table entries one statement may hold.
           def edge_step_sql(edge, index, names)
             declared = edge[:translation].for_aggregate(names[:current][index + 1])
             guard = "era <= #{index + 1} AND operation = 'save'"
-            "edge_#{index + 1} AS (SELECT ordinal, era, #{id_column_for(declared, guard)}, operation, " \
+            "edge_#{index + 1} AS MATERIALIZED (SELECT ordinal, era, #{id_column_for(declared, guard)}, operation, " \
               "CASE WHEN #{guard} THEN #{rules_expression(declared)} ELSE state END AS state " \
               "FROM #{index.zero? ? "tail" : "edge_#{index}"})"
           end

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

@@ -1,5 +1,5 @@
-require_relative "../../../../../../naming"
-require_relative "../../../../../../runtime/errors"
+require_relative "../../../../naming"
+require_relative "../../../../runtime/errors"
 
 module Hecks
   module Adapters

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

@@ -1,5 +1,5 @@
-require_relative "../../era_tamper"
-require_relative "../../../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/era_tamper"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Adapters

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

@@ -1,6 +1,6 @@
-require_relative "../../era_tamper"
-require_relative "../../../../../../runtime/registry"
-require_relative "../../storage_shape"
+require_relative "../../../../ports/persistence/plugins/era/era_tamper"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
 
 module Hecks
   module Adapters

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

@@ -1,5 +1,5 @@
-require_relative "../../../../../../runtime/registry"
-require_relative "../../storage_shape"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
 
 module Hecks
   module Adapters

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

@@ -66,9 +66,13 @@ module Hecks
             FROM layered
           SQL
 
-          # Every edge chained over the reduced ancestor tail.
+          # Every edge chained over the reduced ancestor tail. Each link is MATERIALIZED: a rule
+          # reads
+          # `state` more than once, so Postgres inlining a link into the next copies its whole
+          # expression per read, and a long chain outgrows the planner ("too many range table
+          # entries").
           CHAIN_SQL = <<~SQL.freeze
-            WITH tail AS (%<tail>s),
+            WITH tail AS MATERIALIZED (%<tail>s),
             %<chain>s
             SELECT ordinal, aggregate_id, operation, state FROM edge_%<last>s
           SQL

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

@@ -1,4 +1,4 @@
-require_relative "../../../../../../runtime/registry"
+require_relative "../../../../runtime/registry"
 require_relative "merge_writes"
 
 module Hecks

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

@@ -10,7 +10,7 @@ require_relative "lineage/resumable_backfill"
 require_relative "lineage/head_compiler"
 require_relative "lineage/field_cache"
 require_relative "lineage/transform_installer"
-require_relative "../../../../../naming"
+require_relative "../../../naming"
 
 module Hecks
   module Adapters

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

@@ -4,9 +4,19 @@ module Hecks
       module LineageManager
         # Everything one era check carries from connecting to minting: the booting registry and
         # bluebook, its source text, the open lineage, the role to grant, the bluebook directory,
-        # and the latest held era once the held eras were read.
-        Context = Data.define(:registry, :bluebook, :current_text, :lineage, :role, :directory, :latest) do
-          def initialize(latest: nil, **rest) = super
+        # whether this copy may mint, and the latest held era once the held eras were read.
+        Context = Data.define(:registry, :bluebook, :current_text, :lineage, :role, :directory, :latest,
+                              :mint_permitted) do
+          def initialize(latest: nil, mint_permitted: false, **rest) = super
+
+          # @return [String] the name of the domain being checked
+          def domain_name = bluebook.name
+
+          # @return [Array<Bluebook::Aggregate>] the aggregates of the bluebook being checked
+          def aggregates = bluebook.aggregates
+
+          # @return [Array<Hash>] the eras the open lineage holds, oldest first
+          def held_eras = lineage.eras
 
           # @return [Integer] the ordinal of the era a mint would create
           def ordinal = latest[:ordinal] + 1
@@ -24,13 +34,13 @@ module Hecks
           #
           # @param ordinal [Integer] the resolved era
           # @return [Integer] `ordinal`
-          def record_resolved(ordinal) = registry.resolved_eras[bluebook.name] = ordinal
+          def record_resolved(ordinal) = registry.resolved_eras[domain_name] = ordinal
 
           # Records the era that superseded the one this boot resolved to.
           #
           # @param ordinal [Integer] the superseding era
           # @return [Integer] `ordinal`
-          def record_superseded(ordinal) = registry.superseded_eras[bluebook.name] = ordinal
+          def record_superseded(ordinal) = registry.superseded_eras[domain_name] = ordinal
         end
       end
     end

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

@@ -1,8 +1,8 @@
-require_relative "../../lineage"
-require_relative "../../era_guard"
-require_relative "../../../../../../runtime/identity"
-require_relative "../../../../../../runtime/registry"
-require_relative "../../translation/audit"
+require_relative "../../../../ports/persistence/plugins/era/lineage"
+require_relative "../../../../ports/persistence/plugins/era/era_guard"
+require_relative "../../../../runtime/identity"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/translation/audit"
 
 module Hecks
   module Adapters
@@ -17,8 +17,9 @@ module Hecks
           # held aggregate claimed; the refusal is EraGuard's own, byte for byte.
           #
           # @param registry [Runtime::Registry] where translations may claim a held aggregate
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era declares it
+          # @param bluebook [Bluebook::Declaration] the domain as currently declared
+          # @param held_bluebook [Bluebook::Declaration] the domain as the latest held era declares
+          #   it
           # @param edge [Bluebook::Translation] the one edge leaving the latest held era
           # @raise [Runtime::WiringError] on an unruled identity change or an uncovered path
           def check_coverage!(registry, bluebook, held_bluebook, edge)
@@ -30,9 +31,10 @@ module Hecks
 
           # Refuses an identity change, an uncovered path or an unsafe addition in one aggregate.
           #
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param bluebook [Bluebook::Declaration] the domain as currently declared
           # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
-          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era declares it
+          # @param held_bluebook [Bluebook::Declaration] the domain as the latest held era declares
+          #   it
           # @param edge [Bluebook::Translation] the one edge leaving the latest held era
           # @raise [Runtime::WiringError] on an unruled identity change or an uncovered path
           def check_aggregate_coverage!(bluebook, aggregate, held_bluebook, edge)
@@ -53,7 +55,7 @@ module Hecks
           # Stored ids were fixed under the prior key, so the edge must declare a `rekey` for it;
           # `rules.rekey?` is the one source of truth for that fact.
           #
-          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param bluebook [Bluebook::Declaration] the domain, named in the refusal
           # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
           # @param held_aggregate [Bluebook::Aggregate] the same aggregate in the held era
           # @param rules [Ports::Persistence::Lineage, nil] the edge's rules; nil excuses nothing
@@ -77,7 +79,7 @@ module Hecks
           # Previews each aggregate's translated head through the pending chain and audits it.
           # Runs before anything is minted, so a refusal leaves no half-born era.
           #
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param bluebook [Bluebook::Declaration] the domain as currently declared
           # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open db
           # @param chain [Array<Hash>] the full edge chain ending in `edge`, per `edge_chain`
           # @param ordinal [Integer] the ordinal of the era about to be minted

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

@@ -1,7 +1,7 @@
 require_relative "../lineage"
-require_relative "../../storage_shape"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
 require_relative "context"
-require_relative "../../../../../../indifferent_key"
+require_relative "../../../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -10,6 +10,10 @@ 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
+          # Whether this copy may mint when its world says nothing about it. False, so a copy that
+          # was not told refuses, and only the copy that owns a database moves it.
+          MINT_BY_DEFAULT = false
+
           # 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
@@ -25,17 +29,28 @@ module Hecks
             # key? first, never `||`: a stored `false` must not read as an absent key.
             role = IndifferentKey.read(settings, :role)
             resolve_era(Context.new(registry: registry, bluebook: bluebook, current_text: current_text,
-                                    lineage: lineage, role: role, directory: directory))
+                                    lineage: lineage, role: role, directory: directory,
+                                    mint_permitted: mint_permitted?(settings)))
           ensure
             db&.close
           end
 
           private
 
+          # Whether the world allows minting, spelled as a boolean or as the word.
+          def mint_permitted?(settings)
+            [true, "true"].include?(PostgresEra.setting(settings, :mint_eras, default: MINT_BY_DEFAULT))
+          end
+
           def resolve_era(context)
-            held = context.lineage.eras
+            held = context.held_eras
             return hold_first_era(context) if held.empty?
 
+            resolve_held(context, held)
+          end
+
+          # Some era is held: the latest, a superseded one, or none matches and a new one is minted.
+          def resolve_held(context, held)
             shapes = held_shapes(context.bluebook, held)
             latest, latest_shape = shapes.last
             current_shape = context.current_shape
@@ -73,13 +88,15 @@ module Hecks
           end
 
           def ensure_first_heads!(context)
-            context.bluebook.aggregates.each { |aggregate| context.lineage.ensure_first_head!(aggregate.storage_name) }
+            lineage = context.lineage
+            context.aggregates.each { |aggregate| 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)
+            lineage = context.lineage
+            lineage.grant_role!(context.role, aggregates: context.aggregates, era: ordinal)
           end
 
           # Each held era with its storage shape. Held text is a frozen record and keeps the

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

@@ -1,6 +1,6 @@
 require_relative "../lineage"
-require_relative "../../../../../../runtime/registry"
-require_relative "../../translation/audit"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/translation/audit"
 
 module Hecks
   module Adapters

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

@@ -1,7 +1,7 @@
-require_relative "../../../../../../runtime/registry"
-require_relative "../../storage_shape"
-require_relative "../../translation/audit"
-require_relative "../../translation/scaffold"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "../../../../ports/persistence/plugins/era/translation/audit"
+require_relative "../../../../ports/persistence/plugins/era/translation/scaffold"
 require_relative "context"
 require_relative "refusals"
 
@@ -22,8 +22,9 @@ module Hecks
           # @raise [Runtime::WiringError] if the edge, its coverage or its audit refuses
           def mint!(context)
             ensure_named!(context.lineage, context.latest)
-            context = context.with(latest: context.lineage.eras.last)
+            context = context.with(latest: context.held_eras.last)
             edge = verified_edge!(context)
+            refuse_unpermitted_mint!(context) unless context.mint_permitted
             chain = audited_chain!(context, edge)
             commit_era!(context, chain)
           end
@@ -67,14 +68,15 @@ module Hecks
           private
 
           def edges_leaving(context)
-            context.registry.translations.select do |t|
-              t.domain == context.bluebook.name && t.from == context.latest[:label]
+            registry = context.registry
+            registry.translations.select do |t|
+              t.domain == context.domain_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)
+            chain = edge_chain(context.registry, context.bluebook, context.held_eras, context.label)
             audit!(context.bluebook, context.lineage, chain, context.ordinal, edge)
             chain
           end
@@ -88,9 +90,10 @@ module Hecks
 
           def commit_era!(context, chain)
             hash = context.shape_hash
+            bluebook = context.bluebook
             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,
+              held_text: context.current_text, aggregates: bluebook.aggregates, edges: chain,
               role: context.role, projection: Runtime::StorageShape.project(context.bluebook)
             )
             context.ordinal

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

@@ -20,6 +20,18 @@ module Hecks
                                        "check it with hecks audit_translation, then boot again", minting: false)
           end
 
+          # Refuses to move a database to a newer shape from a copy that may not mint: minting
+          # migrates what every other checkout of the domain reads, and an older checkout is then
+          # refused until it catches up.
+          def refuse_unpermitted_mint!(context)
+            latest = context.latest
+            raise era_refusal(context, "a translation edge covers the move from era #{latest[:ordinal]} " \
+                                       "(#{latest[:label]}) to #{context.label}, but this copy may not mint: " \
+                                       "it would migrate a database other checkouts read. Mint from the copy " \
+                                       "that owns the database, by declaring `mint_eras true` in the " \
+                                       "persisted_by block of its world", minting: false)
+          end
+
           private
 
           def refuse_forked_eras!(context, edges)
@@ -40,7 +52,7 @@ module Hecks
           # 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
+            name = context.domain_name
             lead = minting ? "cannot mint era #{context.ordinal} of #{name}" : "cannot boot #{name}"
             Runtime::WiringError.new("#{lead}: #{text}")
           end

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

@@ -4,8 +4,8 @@ require_relative "lineage_manager/era_resolver"
 require_relative "lineage_manager/minter"
 require_relative "lineage_manager/merge_coordinator"
 require_relative "lineage_manager/coverage_check"
-require_relative "../era_guard"
-require_relative "../../../../../runtime/registry"
+require_relative "../../../ports/persistence/plugins/era/era_guard"
+require_relative "../../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -24,7 +24,7 @@ module Hecks
         # Each mint required its own edge, so a gap in the chain means a deleted file.
         #
         # @param registry [Runtime::Registry] the registry whose loaded `translations` are searched
-        # @param bluebook [Bluebook::Chapter] the domain; only edges for its name count
+        # @param bluebook [Bluebook::Declaration] the domain; only edges for its name count
         # @param eras [Array<Hash>] the ancestor eras in order, as `Lineage#eras` returns them
         # @param current_label [String] the shape label the last step must lead to
         # @return [Array<Hash>] one `{ translation: edge }` per step, in mint order
@@ -41,7 +41,7 @@ module Hecks
         # 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 bluebook [Bluebook::Declaration] 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
@@ -51,7 +51,7 @@ module Hecks
 
         # Refuses a boot whose edge chain has a gap.
         #
-        # @param bluebook [Bluebook::Chapter] the domain, named in the message
+        # @param bluebook [Bluebook::Declaration] 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
@@ -67,7 +67,7 @@ module Hecks
         # The predicate extractor reads source from disk, so the text goes through a scratch file.
         #
         # @param source [String] bluebook source text from `hecks_eras.held_text`
-        # @return [Bluebook::Chapter, nil] the first bluebook the text declares
+        # @return [Bluebook::Declaration, nil] the first bluebook the text declares
         # @raise [Bluebook::DSL::Malformed] if the text parses under neither grammar
         def shadow(source)
           file = Tempfile.new(["hecks-era-", ".bluebook"])

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

@@ -24,8 +24,7 @@ module Hecks
         # 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) }
+          clauses = head_clauses(declared, uncached, ids, args, binds)
 
           sql = "SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(" AND ")}"
           sql += order_suffix(declared)
@@ -33,6 +32,13 @@ module Hecks
           execute_query(sql, binds)
         end
 
+        # The candidate ids, the clauses the cache could not serve, then the cursor's keyset.
+        def head_clauses(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) }
+          clauses.push(*keyset_clause(declared, args, 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)