hecks 0.2.0 → 1.0.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/transform_installer.rb

@@ -0,0 +1,134 @@
+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.
+          #
+          # LOCKED, unlike every other statement `ensure_base!` runs — those
+          # are all `CREATE ... IF NOT EXISTS`/`ADD COLUMN IF NOT EXISTS`,
+          # which Postgres itself resolves safely under concurrent boots.
+          # `CREATE OR REPLACE FUNCTION` is not: it always rewrites the
+          # `pg_proc` row, so two sessions racing to (re)install the SAME
+          # function — these six are shared/global, not per-domain, so any
+          # two domains' concurrent first-boots can collide here — hit a
+          # real `PG::InternalError: tuple concurrently updated`, not a
+          # graceful no-op. `nested_transaction` is the same
+          # already-open-transaction-safe wrapper `ensure_field_cache!`
+          # uses for its own advisory lock; a fixed, domain-independent key
+          # is correct since these functions have no domain of their own.
+          def install_transforms!
+            nested_transaction("hecks_tr_functions") do
+              @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_tr_functions'))", [])
+              install_transform_functions!
+            end
+          end
+
+          def install_transform_functions!
+            @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/ports/persistence/plugins/era/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/ports/persistence/plugins/era/postgres_era/lineage_manager/coverage_check.rb

@@ -0,0 +1,89 @@
+require_relative "../../lineage"
+require_relative "../../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/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -0,0 +1,85 @@
+require_relative "../lineage"
+require_relative "../../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!
+            # Both spellings honored, key? first — never `||`, which cannot
+            # tell a genuinely stored `false` apart from an absent key (see
+            # PostgresEra.setting's own comment for the full reasoning).
+            role = settings.key?(: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/ports/persistence/plugins/era/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

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

@@ -0,0 +1,132 @@
+require_relative "../../../../../../runtime/registry"
+require_relative "../../storage_shape"
+require_relative "../../translation/audit"
+require_relative "../../translation/scaffold"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The mint path: name the source era, find the one edge that
+        # leaves it, hold the compute approval to what was actually
+        # reviewed, check coverage, audit the live chain, and mint — or
+        # refuse toward the authoring loop by name.
+        module Minter
+          def mint!(registry, bluebook, current_text, lineage, latest, role: nil, directory: nil)
+            ensure_named!(lineage, latest)
+            latest = lineage.eras.last
+
+            hash = Runtime::StorageShape.mint_hash(bluebook)
+            label = hash[0, Runtime::StorageShape::LABEL_LENGTH]
+            ordinal = latest[:ordinal] + 1
+
+            edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
+            if edges.empty?
+              refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
+            end
+            if edges.size > 1
+              raise Runtime::WiringError,
+                    "cannot boot #{bluebook.name}: #{edges.size} translation edges leave era #{latest[:ordinal]} " \
+                    "(#{latest[:label]}) — eras fork mechanically; keep one edge per source shape"
+            end
+
+            edge = edges.first
+            unless edge.to == label
+              raise Runtime::WiringError,
+                    "cannot boot #{bluebook.name}: the translation edge from #{latest[:label]} targets " \
+                    "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run bin/scaffold_translation"
+            end
+
+            # A compute's (and, the same way, a rekey's) only verification
+            # is the audit's human-approved sample — mint stays
+            # non-interactive by requiring the approval to already exist,
+            # recorded IN THIS DATABASE by `bin/translation_audit …
+            # --approve` and bound to what was actually reviewed: this
+            # edge's parsed content, and the journal as it stood when the
+            # samples were read. A journal that has advanced past the
+            # review invalidates it — the approved samples no longer cover
+            # the data.
+            if edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+              approval = lineage.approval_for(from: edge.from, to: edge.to)
+              unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
+                raise Runtime::WiringError,
+                      "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
+                      "rule, and the audit's human-approved sample is its only verification — run " \
+                      "bin/translation_audit with --approve, then boot again"
+              end
+              tip = lineage.last_ordinal
+              if approval[:reviewed_ordinal] != tip
+                raise Runtime::WiringError,
+                      "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
+                      "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
+                      "human approved no longer cover the data; re-run bin/translation_audit with --approve"
+              end
+            end
+
+            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
+
+            chain = edge_chain(registry, bluebook, lineage.eras, label)
+            audit!(bluebook, lineage, chain, ordinal, edge)
+            lineage.mint_era!(
+              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
+              aggregates: bluebook.aggregates, edges: chain, role: role,
+              projection: Runtime::StorageShape.project(bluebook)
+            )
+            ordinal
+          end
+
+          # No edge yet: the boot refuses toward the authoring loop —
+          # naming both tools and the era ordinal. With HECKS_SCAFFOLD=1
+          # the boot RUNS the scaffold first (an explicit flag, never a
+          # silent side-effect) and the refusal names the file it wrote.
+          def refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
+            if ENV["HECKS_SCAFFOLD"] == "1" && directory
+              path = scaffold!(registry, bluebook, lineage, latest, directory)
+              raise Runtime::WiringError,
+                    "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) — wrote #{path}; " \
+                    "review it (resolve every unresolved), check it with bin/translation_audit, then boot again"
+            end
+
+            raise Runtime::WiringError,
+                  "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) and no translation edge " \
+                  "covers it — run bin/scaffold_translation to write the edge, " \
+                  "check it with bin/translation_audit, then boot again"
+          end
+
+          # Diff the held era against the current shape and write the edge
+          # file — confident rules inline, ambiguities as parse-refusing
+          # `unresolved` lines. Returns the file path.
+          def scaffold!(registry, bluebook, lineage, latest, directory)
+            ensure_named!(lineage, latest)
+            latest = lineage.eras.last
+
+            hash = Runtime::StorageShape.mint_hash(bluebook)
+            held_bluebook = shadow(latest[:held_text])
+            diffed = Translation::Scaffold.diff(held_bluebook, bluebook)
+            edge = Translation::Scaffold::Edge.new(
+              domain:     bluebook.name,
+              from:       latest[:label],
+              to:         hash[0, Runtime::StorageShape::LABEL_LENGTH],
+              ordinal:    latest[:ordinal] + 1,
+              label:      hash[0, Runtime::StorageShape::LABEL_LENGTH],
+              aggregates: diffed[:aggregates],
+              retired:    diffed[:retired]
+            )
+            Translation::Scaffold.write!(directory, edge)
+          end
+
+          # Era names are minted once. An era held before any drift was
+          # seen has no name yet; it gets one the moment an edge needs to
+          # leave it.
+          def ensure_named!(lineage, era)
+            return if era[:hash]
+
+            held_bluebook = shadow(era[:held_text])
+            hash = Runtime::StorageShape.mint_hash(held_bluebook)
+            lineage.mint_name!(era[:ordinal], hash, hash[0, Runtime::StorageShape::LABEL_LENGTH])
+          end
+        end
+      end
+    end
+  end
+end