hecks 0.2.0 → 0.3.0

data/lib/hecks/adapters/driven/postgres_era/lineage/tail_merge.rb

@@ -0,0 +1,163 @@
+require_relative "../../../../runtime/registry"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        module TailMerge
+          # ── fork observability ─────────────────────────────────────────
+
+          # Post-cut writes an old era made after the newer era was minted
+          # — the divergence between the worlds, observable at any time.
+          def diverged_count(old_era)
+            cut = eras.find { |era| era[:ordinal] == old_era + 1 }&.dig(:watermark)
+            return 0 unless cut
+
+            @db.exec(
+              "SELECT count(*) FROM #{quoted_journal} WHERE era = #{old_era.to_i} AND ordinal > #{cut.to_i}"
+            )[0]["count"].to_i
+          end
+
+          # ── tail-merge ─────────────────────────────────────────────────
+          #
+          # The one deliberate command — it marks a business event (an app
+          # retiring), never a shape change. One transaction: advance the
+          # watermarks, rebuild the head so the tail interleaves by its
+          # recorded global ordinal, append the declared winners, audit —
+          # and roll the whole thing back on any refusal. Records touched
+          # by both worlds since the cut refuse until each has an explicit
+          # winner; resolution itself is append-only (the winner's state
+          # re-enters as the newest row and wins structurally — originals
+          # stay immutable).
+          def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
+            @db.exec("BEGIN")
+            @db.exec("SET LOCAL lock_timeout = '10s'")
+            @db.exec("SELECT pg_advisory_xact_lock(hashtext('hecks_eras:' || #{text_literal(@domain)}))")
+            held = eras
+            era = held.last[:ordinal]
+            label = held.last[:label]
+            if era == 1
+              @db.exec("ROLLBACK")
+              raise Runtime::WiringError, "nothing to merge — #{@domain} stands at era 1"
+            end
+            cut = held.last[:watermark].to_i
+            tip = last_ordinal
+
+            conflicts = aggregates.flat_map { |aggregate| conflict_ids(aggregate, edges, era, cut) }
+            unresolved = conflicts.reject { |_, id| winners.key?(id) }
+            unless unresolved.empty?
+              @db.exec("ROLLBACK")
+              raise Runtime::WiringError,
+                    "cannot merge the tail of #{@domain}: touched by both worlds since the cut — " \
+                    "#{unresolved.map { |storage, id| "#{storage}##{id}" }.sort.join(', ')}. " \
+                    "Name each winner (--winner <id>=old or --winner <id>=new), then run bin/merge_tail again. " \
+                    "A winner takes the WHOLE record — the aggregate is the consistency boundary, so the " \
+                    "loser's edits are discarded even where they touched different attributes"
+            end
+
+            # the new world's pre-merge head states, captured before the
+            # rebuild lets the tail interleave
+            new_states = {}
+            aggregates.each do |aggregate|
+              winners.select { |_, side| side == "new" }.each_key do |id|
+                row = @db.exec_params("SELECT state FROM #{quote(head_view(aggregate.storage_name))} WHERE id = $1", [id])
+                new_states[id] = [aggregate.storage_name, row[0]["state"]] if row.ntuples.positive?
+              end
+            end
+
+            @db.exec_params("UPDATE hecks_eras SET watermark = $2 WHERE domain = $1 AND ordinal > 1", [@domain, tip])
+            aggregates.each do |aggregate|
+              @db.exec("DROP VIEW IF EXISTS #{quote(head_view(aggregate.storage_name))}")
+              @db.exec("DROP MATERIALIZED VIEW IF EXISTS #{quote(matview(aggregate.storage_name, era, label))}")
+              # full: the watermarks just moved — every ancestor matview's
+              # cut is stale, so there is nothing safe to layer on.
+              compile_head!(aggregate, era, label, edges, full: true)
+            end
+
+            winners.each do |id, side|
+              aggregates.each do |aggregate|
+                state =
+                  if side == "old"
+                    row = @db.exec_params(
+                      "SELECT state FROM #{quote(matview(aggregate.storage_name, era, label))} " \
+                      "WHERE aggregate_id = $1 AND operation = 'save' ORDER BY ordinal DESC LIMIT 1",
+                      [id]
+                    )
+                    row.ntuples.positive? ? row[0]["state"] : nil
+                  else
+                    new_states[id]&.first == aggregate.storage_name ? new_states[id][1] : nil
+                  end
+                next unless state
+
+                # Same two-step append does for a live write — journal
+                # first, snapshot second — because this INSERT bypasses
+                # PostgresEra#append entirely (it writes through Lineage
+                # directly). Skipping the snapshot half here would mean a
+                # merge winner lands in the journal but head_view — which
+                # reads this era's live rows from the snapshot table, not
+                # by re-scanning the journal — never shows it.
+                ordinal = @db.exec_params(
+                  "INSERT INTO #{quoted_journal} (era, aggregate, aggregate_id, operation, state) " \
+                  "VALUES ($1, $2, $3, 'save', $4) RETURNING ordinal",
+                  [era, aggregate.storage_name, id, state]
+                )[0]["ordinal"]
+                @db.exec_params(
+                  "INSERT INTO #{quote(head_snapshot(aggregate.storage_name, era))} (id, ordinal, state) VALUES ($1, $2, $3) " \
+                  "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, state = EXCLUDED.state " \
+                  "WHERE #{quote(head_snapshot(aggregate.storage_name, era))}.ordinal < EXCLUDED.ordinal",
+                  [id, ordinal, state]
+                )
+              end
+            end
+
+            if audit
+              violations = audit.call
+              unless violations.empty?
+                @db.exec("ROLLBACK")
+                raise Runtime::WiringError,
+                      "cannot merge the tail of #{@domain}: the audit refused —\n  - #{violations.join("\n  - ")}"
+              end
+            end
+
+            @db.exec("COMMIT")
+            true
+          rescue PG::LockNotAvailable
+            @db.exec("ROLLBACK") rescue nil
+            raise Runtime::WiringError,
+                  "cannot merge the tail of #{@domain}: another mint or merge holds the domain lock — " \
+                  "waited 10s; try again shortly"
+          rescue PG::Error => error
+            @db.exec("ROLLBACK") rescue nil
+            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{error.message.strip}"
+          end
+
+          # Ids touched by BOTH worlds since the cut — the old world's
+          # post-cut tail INTERSECTed with the new world's own writes.
+          #
+          # KNOWN GAP, not silently risked: this compares raw
+          # `aggregate_id` values, with no notion of "these two different
+          # ids are the same entity, rekeyed." If a domain's history
+          # includes a rekey (see TranslationRekey) and is LATER
+          # merged here, a record's pre-rekey and post-rekey rows will
+          # never intersect — they just silently survive as two separate,
+          # unrelated-looking heads (a duplicate, not corruption: nothing
+          # here deletes or clobbers either side). Resolve any such
+          # duplicate manually after a merge; teaching this INTERSECT
+          # about a rekey mapping is real, separate work, deliberately
+          # out of scope for rekey's first pass.
+          def conflict_ids(aggregate, edges, era, cut)
+            names = names_by_era(aggregate, edges)
+            olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")
+            @db.exec(<<~SQL).map { |row| [aggregate.storage_name, row["aggregate_id"]] }
+              SELECT aggregate_id FROM #{quoted_journal}
+              WHERE era < #{era.to_i} AND aggregate IN (#{olds}) AND ordinal > #{cut.to_i}
+              INTERSECT
+              SELECT aggregate_id FROM #{quoted_journal}
+              WHERE era = #{era.to_i} AND aggregate = #{text_literal(names[:storage][era - 1])}
+            SQL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/lineage/transform_installer.rb

@@ -0,0 +1,114 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        module TransformInstaller
+          # The jsonb rule transforms — installed once, idempotently. Kept
+          # equal to the port's reference entry-JSON transform by the
+          # cross-execution equivalence spec; the SQL here is a compilation
+          # target, not a second source of truth.
+          def install_transforms!
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_extract(state jsonb, path text[], OUT remaining jsonb, OUT value jsonb, OUT present boolean)
+              LANGUAGE plpgsql IMMUTABLE AS $fn$
+              DECLARE parent jsonb; leaf text;
+              BEGIN
+                remaining := state;
+                present := false;
+                leaf := path[array_upper(path, 1)];
+                IF array_length(path, 1) = 1 THEN
+                  IF state ? leaf THEN
+                    present := true;
+                    value := state -> leaf;
+                    remaining := state - leaf;
+                  END IF;
+                  RETURN;
+                END IF;
+                parent := state #> path[1:array_upper(path, 1) - 1];
+                IF jsonb_typeof(parent) = 'object' AND parent ? leaf THEN
+                  present := true;
+                  value := parent -> leaf;
+                  parent := parent - leaf;
+                  IF parent = '{}'::jsonb THEN
+                    remaining := state - path[1];
+                  ELSE
+                    remaining := jsonb_set(state, path[1:array_upper(path, 1) - 1], parent);
+                  END IF;
+                END IF;
+              END $fn$
+            SQL
+            # ADVERSARIAL FINDING: a destination whose top segment already
+            # holds a value — most commonly a reference, a bare scalar id
+            # — used to be silently overwritten with an empty object the
+            # moment a dotted destination needed to nest under it. That is
+            # a drop that never declared itself, the one thing this
+            # language exists to make explicit (see hecks_tr_convert's own
+            # refusal below, the same shape) — refused here instead, with
+            # the Ruby reference transform (ports/persistence/lineage.rb's
+            # `insert`) raising the identical wording.
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_insert(state jsonb, path text[], value jsonb, rule_label text) RETURNS jsonb
+              LANGUAGE plpgsql IMMUTABLE AS $fn$
+              BEGIN
+                IF array_length(path, 1) = 1 THEN
+                  RETURN state || jsonb_build_object(path[1], value);
+                END IF;
+                IF state ? path[1] AND jsonb_typeof(state -> path[1]) <> 'object' THEN
+                  RAISE EXCEPTION 'cannot %: % already holds %, not a value this can nest under — moving into it would discard that value silently. Rename or drop % first.',
+                    rule_label, path[1], state -> path[1], path[1];
+                END IF;
+                IF state -> path[1] IS NULL THEN
+                  state := state || jsonb_build_object(path[1], '{}'::jsonb);
+                END IF;
+                RETURN jsonb_set(state, path, value);
+              END $fn$
+            SQL
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_rename(state jsonb, old_name text, new_name text) RETURNS jsonb
+              LANGUAGE sql IMMUTABLE AS $fn$
+                SELECT CASE WHEN state ? old_name
+                  THEN (state - old_name) || jsonb_build_object(new_name, state -> old_name)
+                  ELSE state END
+              $fn$
+            SQL
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
+              LANGUAGE plpgsql IMMUTABLE AS $fn$
+              DECLARE extracted record;
+              BEGIN
+                SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
+                IF NOT extracted.present THEN RETURN state; END IF;
+                RETURN hecks_tr_insert(extracted.remaining, to_path, extracted.value, rule_label);
+              END $fn$
+            SQL
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
+              LANGUAGE plpgsql IMMUTABLE AS $fn$
+              DECLARE extracted record; pair jsonb;
+              BEGIN
+                SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
+                IF NOT extracted.present THEN RETURN state; END IF;
+                FOR pair IN SELECT * FROM jsonb_array_elements(pairs) LOOP
+                  IF pair -> 0 = extracted.value THEN
+                    RETURN hecks_tr_insert(extracted.remaining, to_path, pair -> 1, rule_label);
+                  END IF;
+                END LOOP;
+                RAISE EXCEPTION 'cannot translate %: % has no mapping in its convert''s values: table. Add % => ... to cover it.',
+                  from_label, extracted.value, extracted.value;
+              END $fn$
+            SQL
+            @db.exec(<<~SQL)
+              CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
+              LANGUAGE plpgsql IMMUTABLE AS $fn$
+              DECLARE extracted record;
+              BEGIN
+                SELECT * INTO extracted FROM hecks_tr_extract(state, path);
+                RETURN extracted.remaining;
+              END $fn$
+            SQL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/lineage.rb

@@ -0,0 +1,137 @@
+require "json"
+require "digest"
+
+require_relative "lineage/provisioning"
+require_relative "lineage/era_store"
+require_relative "lineage/mint_transaction"
+require_relative "lineage/tail_merge"
+require_relative "lineage/resumable_backfill"
+require_relative "lineage/head_compiler"
+require_relative "lineage/field_cache"
+require_relative "lineage/transform_installer"
+require_relative "../../../naming"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The lineage topology inside one Postgres database: one journal
+      # per domain, LIST-partitioned by era, with a single ordinal
+      # sequence spanning partitions (total order across eras is
+      # structural); a `hecks_eras` table holding each era's frozen
+      # source text, its once-minted hash/label, and the watermark cut
+      # into its ancestor; and, per aggregate, a HEAD derived from the
+      # journal — never a table anything rewrites.
+      #
+      # For era 1 the head is a plain view (latest save per id). From
+      # era 2 on, the ancestor tail is a MATERIALIZED view whose
+      # definition is the compiled, chained edge sequence — one CTE per
+      # original edge, in mint order, never a flattened merged rule set
+      # — with the watermark baked into the definition, so post-cut
+      # old-era writes cannot leak into the new head even on REFRESH.
+      # Live current-era writes overlay it through the head view.
+      #
+      # Writing to a superseded schema drops the instant the new one
+      # materializes: ONE shared row policy admits INSERTs to whichever
+      # era was just established (era 1 at first hold, era N at mint),
+      # and advancing it is part of the SAME transaction that builds the
+      # new era's matview. There is no persisted per-role fork — any
+      # granted role, app or the table's own OWNER (FORCE ROW LEVEL
+      # SECURITY applies this to the owner too, not only ordinary
+      # roles), writes the current era or nothing, from the moment that
+      # transaction commits. A stale-era write during the narrow window
+      # before that commit — RLS is checked once, when the statement
+      # EXECUTES, never re-checked at commit, so a transaction that
+      # inserted while the old era was still current can still land
+      # after a concurrent mint has already moved the fence on — is
+      # exactly what diverged_count/merge_tail exist to reconcile; it is
+      # the residual of an unavoidable race (ordinals are
+      # sequence-assigned, not transactional — see below), not a
+      # supported way to keep operating two schemas side by side. Only
+      # an actual Postgres superuser (or a role granted BYPASSRLS)
+      # sits above FORCE and keeps writing at will, forever.
+      #
+      # Lineage order is ordinal-assignment order: the ordinal comes from a
+      # sequence, and a sequence's `nextval()` is never rolled back with its
+      # transaction — accepted and documented rather than papered over.
+      #
+      # ONE PART OF THAT IS CLOSED. Two concurrent PLAIN writes could call
+      # `nextval()` in one order and COMMIT in the other — nothing about a
+      # single autocommit INSERT statement stops a slower one from finishing
+      # after a faster one that started later — so "ordinal order" and
+      # "commit order" were formally two different total orders even with no
+      # mint anywhere near either write. `PostgresEra#append` now holds
+      # `pg_advisory_xact_lock(hashtext('hecks_ordinal:' || domain))` for the
+      # length of its own transaction, a DIFFERENT key from `mint_era!` and
+      # `merge_tail!`'s `hecks_eras:domain` — so plain writes serialize
+      # against EACH OTHER only, never against a mint, and ordinal order
+      # equals commit order for them now.
+      #
+      # THE OTHER PART IS NOT, ON PURPOSE. A stale-era write during the
+      # narrow window before a mint's fence-move commits is the SAME race by
+      # a different name — and closing it would mean a plain write
+      # serializing against a mint, which is exactly the guarantee
+      # `postgres_lineage_spec.rb`'s "an old checkout keeps writing its own
+      # era THROUGH a mint" pins the ABSENCE of. That race stays the
+      # residual `diverged_count`/`merge_tail!` exist to reconcile, not
+      # something a plain write should ever block for.
+      #
+      # One concern per file under lineage/: provisioning (DDL and the
+      # RLS posture), era_store (the hecks_eras rows and their integrity),
+      # mint_transaction (the one transaction that makes an era real),
+      # tail_merge (the one deliberate merge command), resumable_backfill
+      # (the one chunked/lock-free/resumable scan loop, shared by
+      # head_compiler's own backfill and field_cache's), head_compiler
+      # (the chained-edge SQL a head derives through), field_cache (the
+      # per-where-field read cache that lets a query skip the reduction
+      # entirely), transform_installer (the hecks_tr_* jsonb helpers).
+      class Lineage
+        include Provisioning
+        include EraStore
+        include MintTransaction
+        include TailMerge
+        include ResumableBackfill
+        include HeadCompiler
+        include FieldCache
+        include TransformInstaller
+
+        JOURNAL_COLUMNS = "ordinal, era, aggregate, aggregate_id, operation, state, mirrors".freeze
+
+        attr_reader :db, :domain, :formerly_known_as
+
+        def initialize(db, domain, formerly_known_as: nil)
+          @db = db
+          @domain = domain.to_s
+          @formerly_known_as = formerly_known_as&.to_s
+        end
+
+        def journal = "hecks_journal_#{Naming.snake(@domain)}"
+        def quoted_journal = quote(journal)
+        def sequence = "#{journal}_ordinal"
+        def partition(era) = "#{journal}_era_#{era}"
+        def head_view(storage_name) = "#{storage_name}_head"
+        # The transactionally-upserted read cache behind head_view — one row
+        # per LIVE id, keyed by id, carrying the ordinal it was last written
+        # at. Scoped by ERA, not just storage_name — an aggregate that
+        # ISN'T renamed across a mint keeps the SAME storage_name in both
+        # eras, so storage_name alone would have era N+1 sharing one
+        # physical table with era N: a freshly-minted era would inherit
+        # every pre-mint (and, worse, pre-rekey/pre-translation) row
+        # instead of starting empty. era-qualified naming is what
+        # `partition`/`matview` already do for exactly this reason.
+        def head_snapshot(storage_name, era) = "#{storage_name}_head_snapshot_#{era}"
+        def matview(storage_name, era, label) = "#{storage_name}_lineage_#{era}_#{label}"
+
+        private
+
+        def quote(name) = PG::Connection.quote_ident(name.to_s)
+
+        def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
+
+        def path_literal(path)
+          segments = path.to_s.split(".").map { |segment| text_literal(segment) }
+          "ARRAY[#{segments.join(', ')}]::text[]"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+require_relative "../../../../ports/persistence/lineage"
+require_relative "../../../../runtime/era_guard"
+require_relative "../../../../runtime/identity"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../translation/audit"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # What a mint must prove before it may happen: the edge covers
+        # the whole diff, no identity path was re-keyed, and the audit's
+        # first two layers pass over the LIVE compiled chain.
+        module CoverageCheck
+          # Layer 1 against THIS edge specifically: every vanished or
+          # retyped path in the held→current diff must be explained, and
+          # every held aggregate must still be claimed. The refusal is
+          # EraGuard's own, byte for byte.
+          def check_coverage!(registry, bluebook, held_bluebook, edge)
+            bluebook.aggregates.each do |aggregate|
+              rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
+              held_aggregate = held_bluebook.aggregate(rules&.ancestor_name || aggregate.name)
+              next unless held_aggregate
+
+              check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
+              uncovered = Runtime::EraGuard.uncovered_attributes(aggregate, held_aggregate, rules)
+              Runtime::EraGuard.refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
+
+              unsafe = Runtime::EraGuard.unsafe_additions(aggregate, held_aggregate, rules)
+              Runtime::EraGuard.refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
+            end
+            Runtime::EraGuard.check_vanished_aggregates!(registry, bluebook, held_bluebook)
+          end
+
+          # An identity-path change is a RE-KEYING, not an ordinary
+          # translation — stored ids were fixed at write time under the old
+          # key, so this refuses UNLESS the edge declares a `rekey` for
+          # this aggregate covering exactly that. `rules.rekey?` (see
+          # `Ports::Persistence::Lineage`'s own comment) is the single
+          # source of truth every consumer of this fact asks — this is not
+          # a second, independent check of `declared.rekeys`.
+          def check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
+            # The FULL declared path lists, in declaration order — never the
+            # single-head shortcut, which is nil for every composite identity
+            # and so would let two different composites compare as unchanged.
+            return if held_aggregate.identity_paths == aggregate.identity_paths
+            return if rules&.rekey?
+
+            held_identity = Runtime::Identity.reading(held_aggregate)
+            current_identity = Runtime::Identity.reading(aggregate)
+            raise Runtime::WiringError,
+                  "cannot mint an era for #{bluebook.name}::#{aggregate.name}: its identity path changed " \
+                  "(#{held_identity} → #{current_identity}), and that is a re-keying, not a translation — " \
+                  "stored ids were minted under #{held_identity}, and no rule declares rows the same " \
+                  "entity under a new key. Keep the identity path, declare a rekey rule, or migrate the " \
+                  "data explicitly"
+          end
+
+          # Layers 1 and 2 of the audit, over the LIVE compiled chain —
+          # before anything is minted, so a refusal leaves no half-born
+          # era. (A convert meeting an unmapped value raises inside the
+          # preview query itself: same rollback-shaped outcome.)
+          def audit!(bluebook, lineage, chain, ordinal, edge)
+            violations = []
+            bluebook.aggregates.each do |aggregate|
+              declared = edge.for_aggregate(aggregate.name)
+              after = begin
+                lineage.translated_latest(aggregate, ordinal, chain)
+              rescue PG::Error => error
+                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{error.message.strip}"
+              end
+              before = if chain.size > 1
+                         lineage.translated_latest(aggregate, ordinal, chain[0..-2])
+                       else
+                         lineage.ancestor_latest(aggregate, ordinal, chain)
+                       end
+              verdict = Translation::Audit.check(aggregate: aggregate, declared: declared, before: before, after: after)
+              violations.concat(verdict.violations)
+            end
+            return if violations.empty?
+
+            raise Runtime::WiringError,
+                  "cannot mint era #{ordinal} of #{bluebook.name}: the audit refused —\n  - #{violations.join("\n  - ")}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+require_relative "../lineage"
+require_relative "../../../../runtime/storage_shape"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The boot-time resolution: which era IS this checkout? First
+        # boot holds era 1; a quiet reboot changes nothing; a
+        # held-but-superseded shape boots read-only-toward-the-fence; an
+        # unheld shape goes to the minter.
+        module EraResolver
+          def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
+            db = PostgresEra.connect_for(bluebook.name, settings)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            lineage.ensure_base!
+            role = settings[:role] || settings["role"]
+
+            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) }
+              # hold_first! already established era 1 as current for
+              # EVERY role; this one just needs its own privileges.
+              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: 1) if role
+              return
+            end
+
+            current_shape = Runtime::StorageShape.project(bluebook)
+            shapes = held.map { |era| [era, Runtime::StorageShape.project(shadow(era[:held_text]))] }
+            if bluebook.formerly_known_as
+              # A held era's shape is re-derived from its own frozen
+              # historical text (shadow(era[:held_text])), so its "name"
+              # is permanently the old one — the frozen text is authentic
+              # record ("this domain really was called that, at the
+              # time") and must never be rewritten. Only the in-memory
+              # shape used for THIS comparison is normalized, and only
+              # where it exactly matches the declared old name, so an
+              # unrelated domain that happens to shape-match some other
+              # domain's history still shows up as a real mismatch.
+              shapes = shapes.map do |era, shape|
+                [era, shape["name"] == bluebook.formerly_known_as ? shape.merge("name" => bluebook.name) : shape]
+              end
+            end
+
+            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
+              # A quiet reboot changes no era, so there is nothing to
+              # advance — only this role's own privileges, if it is new.
+              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: latest[:ordinal]) if role
+              registry.resolved_eras[bluebook.name] = latest[:ordinal]
+              return
+            end
+
+            matched, = shapes.find { |_, shape| shape == current_shape }
+            if matched
+              # A held-but-superseded era — an old checkout still running.
+              # It may keep BOOTING and READING (PostgresEra is the one
+              # adapter that recognizes this rather than refusing), but it
+              # may not keep WRITING: the shared era fence was already
+              # advanced past this ordinal by whichever mint superseded
+              # it, and nothing here may roll that back. Granting only
+              # this role's privileges, never advance_era!, is what keeps
+              # that true — see advance_era!'s own warning against being
+              # called with a superseded ordinal.
+              lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
+              registry.resolved_eras[bluebook.name] = matched[:ordinal]
+              return
+            end
+
+            registry.resolved_eras[bluebook.name] =
+              mint!(registry, bluebook, current_text, lineage, latest,
+                    role: role, directory: directory)
+          ensure
+            db&.close
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+require_relative "../lineage"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../translation/audit"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # Tail-merge, driven from bin/merge_tail: interleave the old
+        # world's post-cut writes into the head by their recorded global
+        # ordinals, under the full audit, in one transaction.
+        module MergeCoordinator
+          def merge!(registry:, bluebook:, settings:, winners: {})
+            db = PostgresEra.connect_for(bluebook.name, settings)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            lineage.ensure_base!
+
+            held = lineage.eras
+            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])
+
+            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
+
+            lineage.merge_tail!(aggregates: bluebook.aggregates, edges: chain, winners: winners, audit: audit)
+          ensure
+            db&.close
+          end
+        end
+      end
+    end
+  end
+end