hecks 5.0.0 → 7.0.0

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

@@ -66,13 +66,26 @@ 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
 
+          # The chain in one step: each held era's rows take the one composed translation from
+          # that era to the current shape.
+          DIRECT_SQL = <<~SQL.freeze
+            WITH tail AS MATERIALIZED (%<tail>s),
+            direct AS MATERIALIZED (SELECT ordinal, era, aggregate_id, operation,
+              %<state>s AS state FROM tail)
+            SELECT ordinal, aggregate_id, operation, state FROM direct
+          SQL
+
           # Reduces to newest entry per aggregate id, dropping any id whose newest entry is a
           # delete.
           LATEST_SQL = <<~SQL.freeze

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,9 @@ 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 "lineage/mint_provisioning"
+require_relative "lineage/ledger_reset"
+require_relative "../../../naming"
 
 module Hecks
   module Adapters
@@ -27,6 +29,8 @@ module Hecks
         include HeadCompiler
         include FieldCache
         include TransformInstaller
+        include MintProvisioning
+        include LedgerReset
 
         # Longer identifiers are silently truncated by Postgres, so `qualified_name` hashes them.
         POSTGRES_IDENTIFIER_LIMIT = 63
@@ -37,11 +41,15 @@ module Hecks
         # @param domain [String, Symbol] the domain's declared name; every relation name and
         #   advisory-lock key derives from it
         # @param formerly_known_as [String, Symbol, nil] the domain's prior name, which makes
-        #   `ensure_base!` rename its relations and rows first; nil when there is no prior name
-        def initialize(db, domain, formerly_known_as: nil)
+        #   `ensure_base!` and a read refuse while the history sits under it; `rename_domain!` moves
+        #   the history; nil when there is no prior name
+        # @param reading [Boolean] true for a read: the held eras are verified in memory and never
+        #   archived or backfilled, so the connection needs only SELECT
+        def initialize(db, domain, formerly_known_as: nil, reading: false)
           @db = db
           @domain = domain.to_s
           @formerly_known_as = formerly_known_as&.to_s
+          @reading = reading
         end
 
         # Names the domain's one journal table, the partitioned parent of every era's rows.

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/context.rb

@@ -0,0 +1,68 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      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,
+        # whether this copy may mint, the mint request the Maintenance mint command made (nil on
+        # a boot), and the latest held era once the held eras were read.
+        Context = Data.define(:registry, :bluebook, :current_text, :lineage, :role, :directory, :latest,
+                              :mint_permitted, :mint_request) do
+          def initialize(latest: nil, mint_permitted: false, mint_request: nil, **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<Object>] the translation edges the registry loaded
+          def translations = registry.translations
+
+          # @return [Array<Hash>] the eras the open lineage holds, oldest first
+          def held_eras = lineage.eras
+
+          # @return [Integer] the ledger watermark now: the journal's highest ordinal
+          def watermark = lineage.last_ordinal
+
+          # @return [Integer] the ordinal of the era a mint would create
+          def ordinal = latest[:ordinal] + 1
+
+          # @return [String] the storage-shape hash of the current bluebook
+          def shape_hash = Runtime::StorageShape.mint_hash(bluebook)
+
+          # @return [String] the short label naming the current shape
+          def label = shape_hash[0, Runtime::StorageShape::LABEL_LENGTH]
+
+          # @return [Hash] the storage shape of the current bluebook
+          def current_shape = Runtime::StorageShape.project(bluebook)
+
+          # Records the era this boot resolved to on the registry.
+          #
+          # @param ordinal [Integer] the resolved era
+          # @return [Integer] `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[domain_name] = ordinal
+
+          # Records that this boot's shape is held by no era, with the latest held era it reads.
+          #
+          # @param ordinal [Integer] the latest held era
+          # @return [Integer] `ordinal`
+          def record_unminted(ordinal) = registry.unminted_eras[domain_name] = ordinal
+
+          # Records that this boot's shape is one recorded move or edge ahead of the latest
+          # held era.
+          #
+          # @param ordinal [Integer] the latest held era the move leaves
+          # @return [Integer] `ordinal`
+          def record_behind(ordinal) = registry.behind_eras[domain_name] = ordinal
+        end
+      end
+    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
@@ -109,9 +111,11 @@ module Hecks
 
           # The aggregate's head as the chain's last step receives it.
           def translated_before(lineage, aggregate, ordinal, chain)
+            split = lineage.split_latest(aggregate, chain)
+            return split if split
             return lineage.ancestor_latest(aggregate, ordinal, chain) unless chain.size > 1
 
-            lineage.translated_latest(aggregate, ordinal, chain[0..-2])
+            lineage.received_latest(aggregate, ordinal, chain)
           end
         end
       end

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/disposable_ledger.rb

@@ -0,0 +1,119 @@
+require_relative "../lineage"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "ledger_change"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The era check of a world that declares `disposable_ledger true` in its PostgresEra
+        # `persisted_by` block: a tooling ledger whose rows are worth keeping, not worth an era.
+        #
+        # Its boot never refuses as unminted or superseded and needs no edge, mint or rehearsal. It
+        # holds the first era itself, and on a shape change it re-holds the latest era at the
+        # booting shape: an added aggregate gets a head, a widened one keeps its rows as they are,
+        # and a replaced one has its rows moved to a dated archive table and starts empty. It names
+        # each archive on stderr. A world without the setting never reaches this module.
+        module DisposableLedger
+          module_function
+
+          # Whether a world's persistence settings declare the ledger disposable, spelled as a
+          # boolean or as the word. Unset is false, so every other world keeps its era guard.
+          #
+          # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+          # @return [Boolean]
+          def declared?(settings) = [true, "true"].include?(PostgresEra.setting(settings, :disposable_ledger, default: false))
+
+          # Brings the ledger to the booting shape and records the era the boot reads.
+          #
+          # @param registry [Runtime::Registry] the booting registry; `resolved_eras` is set
+          # @param bluebook [Bluebook::Declaration] the bluebook booting now
+          # @param current_text [String] its source text, held as the era's text
+          # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+          # @return [nil] a disposable ledger's boot mints no era
+          # @raise [Runtime::WiringError] if the connection is refused or its role is unfenced
+          #
+          # The world's `stored_as` names are applied first: the boot gates run before the wiring
+          # check that applies them, and a re-hold provisions heads under the storage names.
+          def check!(registry:, bluebook:, current_text:, settings:)
+            registry.apply_world_names!
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: true)
+            lineage = open_lineage(db, bluebook, settings)
+            registry.resolved_eras[bluebook.name] = locked(db, bluebook.name) { reconcile!(lineage, bluebook, current_text) }
+            grant!(lineage, bluebook, settings, registry.resolved_eras[bluebook.name])
+            nil
+          ensure
+            db&.close
+          end
+
+          # The ordinal the ledger holds once it is at the booting shape.
+          #
+          # @return [Integer]
+          def reconcile!(lineage, bluebook, text)
+            latest = lineage.eras.last
+            return hold_first!(lineage, bluebook, text) unless latest
+
+            change = LedgerChange.between(held_projection(latest), bluebook)
+            apply!(lineage, bluebook, text, change, latest[:ordinal]) if change.changed?
+            latest[:ordinal]
+          end
+
+          # Archives every replaced aggregate, gives each added or replaced one a head over the
+          # latest era alone, provisions the read side of every aggregate, and re-holds the era.
+          def apply!(lineage, bluebook, text, change, ordinal)
+            stamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+            change.replaced.each { |name| archive!(lineage, bluebook, change.storage_name(bluebook, name), stamp) }
+            fresh_heads!(lineage, bluebook, change, ordinal)
+            bluebook.aggregates.each { |aggregate| lineage.provision_read_side!(aggregate, ordinal) }
+            lineage.rehold!(ordinal, text, Runtime::StorageShape.project(bluebook), Runtime::StorageShape.mint_hash(bluebook))
+          end
+
+          # Gives every added or replaced aggregate the booting bluebook declares a head over the
+          # latest era alone: none of its rows are in an earlier era.
+          def fresh_heads!(lineage, bluebook, change, ordinal)
+            (change.added + change.replaced).filter_map { |name| bluebook.aggregate(name) }
+                                            .each { |aggregate| lineage.fresh_head!(aggregate.storage_name, ordinal) }
+          end
+
+          def archive!(lineage, bluebook, storage_name, stamp)
+            archive, count = lineage.archive_aggregate!(storage_name, stamp)
+            warn "[hecks] #{bluebook.name}: the shape of #{storage_name} changed in a way its rows do not fit; " \
+                 "archived #{count} journal row#{"s" unless count == 1} to #{archive} and started it empty " \
+                 "(disposable_ledger)"
+          end
+
+          def hold_first!(lineage, bluebook, text)
+            lineage.hold_first!(text, projection: Runtime::StorageShape.project(bluebook))
+            lineage.provision_first_era!(bluebook.aggregates)
+            1
+          end
+
+          # The storage shape the latest era holds: the projection its hold recorded, else the
+          # shape its held text declares.
+          def held_projection(era) = era[:projection] || Runtime::StorageShape.project(LineageManager.shadow(era[:held_text]))
+
+          def open_lineage(db, bluebook, settings)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
+            lineage.ensure_base!
+            lineage
+          end
+
+          # Holds the domain's era lock, the one a mint takes, for the whole reconcile, so two boots
+          # of a changed shape archive once.
+          def locked(db, domain)
+            db.exec_params("SELECT pg_advisory_lock(hashtext('hecks_eras:' || $1))", [domain])
+            yield
+          ensure
+            db.exec_params("SELECT pg_advisory_unlock(hashtext('hecks_eras:' || $1))", [domain])
+          end
+
+          def grant!(lineage, bluebook, settings, ordinal)
+            role = PostgresEra.setting(settings, :role)
+            lineage.grant_role!(role.to_s, aggregates: bluebook.aggregates, era: ordinal) unless role.to_s.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/era_resolution.rb

@@ -0,0 +1,219 @@
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "mint_decision"
+require_relative "../lineage"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The one answer to which era a bluebook's shape resolves to, given the eras its database
+        # holds: the boot records it, the boot status reports it, and the rehearsal and the mint
+        # read the held era and the match from it. It writes nothing. A status is one of:
+        #
+        # - `unheld`: the database holds no era for the bluebook.
+        # - `current`: the latest held era holds the current shape.
+        # - `superseded`: an older held era holds the current shape; a later one superseded it.
+        # - `behind`: no era holds the current shape, and a mint from the latest one would go ahead
+        #   on its translation edge or recorded implicit move.
+        # - `unminted`: no era holds the current shape, and no mint from the latest one would go
+        #   ahead.
+        module EraResolution
+          # What a resolution concludes. `resolved` is the era the boot reads (nil when `unheld`),
+          # `latest` the latest held era, `verdict` the mint decision from the latest era (nil
+          # unless the shape is `behind` or `unminted`), and `held_count` how many eras are held.
+          Answer = Data.define(:status, :resolved, :latest, :current_label, :verdict, :held_count,
+                               :breaking) do
+            # @return [Boolean] whether the shape is unminted because the move is breaking and no
+            #   translation edge covers it, so a boot reads nothing under it and refuses
+            def breaking? = breaking == true
+
+            # @return [Boolean] whether a held era holds the current shape
+            def matched? = %w[current superseded].include?(status)
+
+            # The label of the era the boot reads. An era no edge has left yet has no stored name,
+            # so its label is worked out in memory, as its mint would name it; naming is a write,
+            # so a resolution never stores it.
+            #
+            # @return [String, nil] the label; nil when no era is held
+            # @raise [Runtime::WiringError] when an unnamed era stores no shape (`refuse_unshaped!`)
+            def held_label
+              stored = resolved&.fetch(:label, nil)
+              return stored if stored || resolved.nil?
+
+              LineageManager.held_hash(resolved)[0, Runtime::StorageShape::LABEL_LENGTH]
+            end
+
+            # @return [Integer, nil] the ordinal of the era the boot reads
+            def ordinal = resolved&.fetch(:ordinal, nil)
+
+            # @return [String, nil] why the status is what it is; nil for `current`
+            def reason = Reasons.of(self)
+
+            # @return [Boolean] whether a mint from the latest era would go ahead on a recorded
+            #   implicit move rather than a written translation edge
+            def implicit? = verdict&.source == "implicit"
+
+            # @return [String] the mint decision from the latest era and why, as `verdict: reason`
+            def decision = "#{verdict.verdict}: #{verdict.reason}"
+
+            # @return [Hash, nil] the implicit move a `behind` shape would mint on, or nil
+            def move
+              return unless status == "behind" && implicit?
+
+              { "from" => held_label, "to" => current_label }
+            end
+
+            # @return [String, nil] a sentence when the read era's stored hash is not the hash
+            #   of its stored projection (a boot still reads it); nil when they agree or the era
+            #   stores only one of them
+            def warning
+              recomputed = projection_hash
+              return if recomputed.nil? || recomputed == resolved[:hash]
+
+              "era #{ordinal} stores hash #{resolved[:hash][0, 6]} but its stored projection hashes to #{recomputed[0, 6]}"
+            end
+
+            # @return [String, nil] the hash of the read era's stored projection; nil when it stores
+            #   no hash or no projection
+            def projection_hash
+              return unless resolved && resolved[:hash] && resolved[:projection]
+
+              Runtime::ProjectedBluebook.new(resolved[:projection]).mint_hash
+            end
+
+            # @return [Hash] the answer as a status row, string-keyed for a JSON document; `warning`
+            #   appears only when `warning` has something to say
+            def to_row
+              row = { "status" => status, "held" => held_label, "current" => current_label, "ordinal" => ordinal,
+                      "move" => move, "reason" => reason, "source" => "database" }
+              (note = warning) ? row.merge("warning" => note) : row
+            end
+          end
+
+          module_function
+
+          # Resolves the current shape of a bluebook against the eras its database holds.
+          #
+          # @param eras [Array<Hash>] the held eras, oldest first, as `Lineage#eras` answers them
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @param translations [Array<Object>] the translation edges the registry loaded
+          # @param directory [String, nil] the domain's bluebook directory, where moves are recorded
+          # @yieldreturn [Integer] the ledger watermark, read only when no held era matches
+          # @return [Answer]
+          def resolve(eras:, bluebook:, translations:, directory:)
+            facts = { latest: eras.last, current_label: MintDecision.label_of(bluebook), held_count: eras.size }
+            return answer("unheld", nil, facts) if eras.empty?
+
+            matched = matching_era(eras, bluebook)
+            return answer(matched.equal?(eras.last) ? "current" : "superseded", matched, facts) if matched
+
+            unmatched(facts, bluebook, translations, directory, yield)
+          end
+
+          # Resolves a bluebook against the eras its own database holds, over a connection that
+          # can only read: nothing is provisioned, and the session refuses any write.
+          #
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @param settings [Hash] the persistence settings its world declares; needs `database`
+          # @param translations [Array<Object>] the translation edges the registry loaded
+          # @param directory [String, nil] the domain's bluebook directory
+          # @return [Answer]
+          # @raise [Runtime::WiringError] if the connection is refused or a held text fails its
+          #   integrity check
+          def read(bluebook:, settings:, translations:, directory: nil)
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: false)
+            db.exec("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY")
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as, reading: true)
+            resolve(eras: lineage.eras, bluebook: bluebook, translations: translations, directory: directory) do
+              lineage.last_ordinal
+            end
+          ensure
+            db&.close
+          end
+
+          # The held era whose shape is the bluebook's: the latest when it holds it, else the
+          # oldest that does; nil when none holds it.
+          #
+          # @param eras [Array<Hash>] the held eras, oldest first
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @return [Hash, nil] the matching era
+          def matching_era(eras, bluebook)
+            current = Runtime::StorageShape.project(bluebook)
+            [eras.last, *eras].find { |era| held_shape_of(era, bluebook) == current }
+          end
+
+          # An era's storage shape, with a prior name normalized to the bluebook's. Held text is a
+          # frozen record and keeps the prior name; only the in-memory shape is renamed, and only on
+          # an exact match with the declared prior name.
+          #
+          # @param era [Hash] a held era
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @return [Hash] the storage shape the era holds
+          def held_shape_of(era, bluebook)
+            shape = LineageManager.held_shape(era)
+            prior = bluebook.formerly_known_as
+            prior && shape["name"] == prior ? shape.merge("name" => bluebook.name) : shape
+          end
+
+          # @return [Answer] a `behind` or `unminted` answer, by the latest era's mint decision
+          def unmatched(facts, bluebook, translations, directory, watermark)
+            verdict = MintDecision.decide_latest(facts[:latest], bluebook: bluebook, translations: translations,
+                                                                 directory: directory, watermark: watermark)
+            status = verdict.verdict == "would_mint" ? "behind" : "unminted"
+            breaking = MintDecision.breaking?(facts[:latest], bluebook, verdict, translations)
+            answer(status, facts[:latest], facts, verdict, breaking: breaking)
+          end
+
+          # @return [Answer]
+          def answer(status, resolved, facts, verdict = nil, breaking: false)
+            Answer.new(status: status, resolved: resolved, verdict: verdict, breaking: breaking, **facts)
+          end
+
+          # The sentence a status row gives for its status.
+          module Reasons
+            REMEDY = "write an edge (`era.scaffold_translation`) and mint it with the release mint".freeze
+
+            module_function
+
+            # @param answer [Answer] the resolution
+            # @return [String, nil] the reason; nil for `current`
+            def of(answer)
+              case answer.status
+              when "unheld" then "no era is held; the mint entry point holds the first"
+              when "superseded" then superseded(answer)
+              when "behind" then behind(answer)
+              when "unminted" then unminted(answer)
+              end
+            end
+
+            # @return [String]
+            def superseded(answer)
+              "era #{answer.ordinal} holds the current shape #{answer.current_label}; era " \
+                "#{answer.latest[:ordinal]} (#{answer.latest[:label]}) superseded it"
+            end
+
+            # @return [String]
+            def behind(answer)
+              "no era holds #{answer.current_label}; a mint from era #{answer.ordinal} (#{answer.held_label}) " \
+                "would go ahead on its #{answer.implicit? ? "recorded implicit move" : "translation edge"}"
+            end
+
+            # @return [String] the refusal a boot over a breaking move gives
+            def breaking(answer)
+              "no translation edge covers it: #{answer.current_label} is not an additive move from " \
+                "era #{answer.ordinal} (#{answer.held_label}); #{REMEDY}"
+            end
+
+            # @return [String]
+            def unminted(answer)
+              return breaking(answer) if answer.breaking?
+
+              "no era holds #{answer.current_label}; a mint from era #{answer.ordinal} (#{answer.held_label}) " \
+                "is #{answer.decision}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/era_resolver.rb

@@ -0,0 +1,114 @@
+require_relative "../lineage"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "context"
+require_relative "mint_request"
+require_relative "mint_decision"
+require_relative "era_resolution"
+require_relative "disposable_ledger"
+require_relative "../../../../indifferent_key"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # Boot-time era resolution. A boot reads: it reports the era its shape resolves to, and
+        # writes nothing. The mint entry point (a settings `mint_request`) is the only path that
+        # provisions the lineage or mints an era.
+        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. A mint also needs
+          # the mint entry point's request (`mint_request` in the settings): a boot never mints.
+          MINT_BY_DEFAULT = false
+
+          # Resolves which era this boot is and records it on the registry.
+          #
+          # A boot with no mint request opens its lineage for reading and never provisions, holds,
+          # mints or grants. A boot with a request provisions the lineage first, then mints if the
+          # shape drifted.
+          #
+          # @return [Integer, nil] the ordinal minted, or nil when this boot minted nothing
+          # @raise [Runtime::WiringError] if the connection is refused, a held text fails its
+          #   integrity check, no era is held, or the shape is unheld and `mint!` refuses
+          def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
+            # A world that declares its ledger disposable has no era guard: see `DisposableLedger`.
+            return DisposableLedger.check!(registry:, bluebook:, current_text:, settings:) if DisposableLedger.declared?(settings)
+
+            request = MintRequest.from(settings)
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: !request.nil?)
+            lineage = open_lineage(db, bluebook, settings, request)
+            resolve_era(Context.new(registry: registry, bluebook: bluebook, current_text: current_text,
+                                    lineage: lineage, role: IndifferentKey.read(settings, :role),
+                                    directory: directory, mint_permitted: mint_permitted?(settings),
+                                    mint_request: request))
+          ensure
+            db&.close
+          end
+
+          private
+
+          # Opens the lineage: for reading on a boot, and provisioned first on a mint request. Either
+          # refuses, by name, while the domain's history still sits under its former name.
+          def open_lineage(db, bluebook, settings, request)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as,
+                                                     reading:           request.nil?)
+            # First, before anything else: the earliest point the connection's role is known,
+            # so a superuser connection refuses here by default.
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
+            request ? lineage.ensure_base! : lineage.refuse_pending_rename!
+            lineage
+          end
+
+          # 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
+
+          # Resolves the boot's shape through `EraResolution`, the answer every era tool reads, and
+          # records it on the registry; a mint request on a shape no era holds mints instead.
+          def resolve_era(context)
+            answer = EraResolution.resolve(eras: context.held_eras, bluebook: context.bluebook,
+                                           translations: context.translations, directory: context.directory) do
+              context.watermark
+            end
+            return refuse_unheld!(context) if answer.status == "unheld"
+            return context.record_resolved(mint!(context.with(latest: answer.latest))) if minting?(answer, context)
+
+            return refuse_breaking!(context, answer) if answer.breaking?
+
+            record(context, answer)
+          end
+
+          # A breaking move no edge covers: the boot reads nothing and writes nothing. This stands
+          # in until the commit-time gate (ADR 0168) keeps such a move off main.
+          def refuse_breaking!(context, answer)
+            raise Runtime::WiringError, "cannot boot #{context.domain_name}: #{answer.reason}"
+          end
+
+          # Whether this check mints: a mint request, on a shape no held era holds.
+          def minting?(answer, context) = context.mint_request && !answer.matched?
+
+          # No era is held: the first era is held by the mint entry point, never by a boot.
+          def refuse_unheld!(context)
+            raise Runtime::WiringError,
+                  "cannot boot #{context.domain_name}: no era held; run the mint entry point " \
+                  "(`hecks era.hold_first! <domain directory> --confirm`) to hold the first era"
+          end
+
+          # Records what the resolution answered and writes nothing. A superseded era (an old
+          # checkout) reads and never writes: the adapter refuses appends on it, even where the RLS
+          # fence cannot bind. A shape no era holds reads the latest held era, and is behind when a
+          # mint from it would go ahead; the mint entry point runs that mint.
+          def record(context, answer)
+            context.record_resolved(answer.ordinal)
+            latest = answer.latest[:ordinal]
+            status = answer.status
+            context.record_superseded(latest) if status == "superseded"
+            context.record_unminted(latest) if %w[unminted behind].include?(status)
+            context.record_behind(latest) if status == "behind"
+            nil
+          end
+        end
+      end
+    end
+  end
+end