hecks 3.5.0 → 3.7.0

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

@@ -0,0 +1,62 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The write path under the domain's lock: one journal row, then the head snapshot and every
+      # field cache brought to the same ordinal inside the same transaction.
+      module HeadWrites
+        private
+
+        def lock_writes!
+          @db.exec_params(
+            "SELECT pg_advisory_xact_lock(hashtext('hecks_ordinal:' || $1))",
+            [@lineage.domain]
+          )
+        end
+
+        def append_and_project!(entry)
+          state_json = entry.state && JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, entry.state))
+          ordinal = insert_journal_row(entry, state_json)
+          entry.save? ? snapshot_save!(entry, ordinal, state_json) : snapshot_delete!(entry, ordinal)
+          ordinal
+        end
+
+        def insert_journal_row(entry, state_json)
+          @db.exec_params(
+            "INSERT INTO #{@lineage.quoted_journal} (era, aggregate, aggregate_id, operation, state, mirrors) " \
+            "VALUES ($1, $2, $3, $4, $5, $6) RETURNING ordinal",
+            [@era, table, entry.id, entry.operation, state_json,
+             entry.mirrors && JSON.generate(entry.mirrors)]
+          )[0]["ordinal"]
+        end
+
+        def snapshot_save!(entry, ordinal, state_json)
+          @db.exec_params(
+            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'save', $3) " \
+            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+            "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            [entry.id, ordinal, state_json]
+          )
+          # Same transaction and ordinal, so every cache is exactly as current as the snapshot.
+          @field_caches.each do |field, cache_table|
+            @lineage.upsert_field_cache_row!(cache_table, entry.id, ordinal, state_json, query_expression(field))
+          end
+        end
+
+        # A tombstone row, not a bare DELETE: without one, an ancestor era's saved row would win
+        # the head's DISTINCT ON and the deleted record would read back. The ordinal guard keeps
+        # a stale replayed delete from clobbering a newer save.
+        def snapshot_delete!(entry, ordinal)
+          @db.exec_params(
+            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'delete', NULL) " \
+            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+            "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            [entry.id, ordinal]
+          )
+          @field_caches.each_value { |cache_table| @lineage.delete_field_cache_row!(cache_table, entry.id) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Writing and reading the journal: every append, with the head snapshot and field caches
+      # it keeps current in the same transaction, and the reads of the whole journal.
+      module Journal
+        # Appends one entry to the journal and updates the head snapshot and every field cache,
+        # all in one transaction under the domain's write lock.
+        #
+        # The lock precedes the INSERT because the ordinal comes from `nextval()` inside it. It is
+        # a different key from `mint_era!`'s, so it serializes writes, never a write against a mint.
+        # `project` stays out of it: AppendOnly#recover! already replays it on every boot.
+        #
+        # @param entry [Ports::Persistence::Entry] the save or delete to journal
+        # @return [Ports::Persistence::Entry] the same entry, unchanged
+        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [PG::Error] if Postgres refuses a statement, such as the era fence's RLS
+        def append(entry)
+          refuse_superseded_write!
+          transaction do
+            lock_writes!
+            append_and_project!(entry)
+          end
+          entry
+        end
+
+        # Refuses a write from a checkout whose era a later mint has superseded.
+        # Runs before the transaction so a stale checkout takes no lock; reads stay allowed.
+        #
+        # @return [nil] when this boot's era is current
+        # @raise [Runtime::WiringError] if the boot gate marked this era superseded
+        def refuse_superseded_write!
+          return unless @superseded_by
+
+          raise Runtime::WiringError,
+                "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
+                "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
+                "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
+                "reboot to write again."
+        end
+
+        # Saves an entry and reports whether it inserted or replaced, decided under the same lock
+        # that guards the write.
+        #
+        # @param entry [Ports::Persistence::Entry] the save to journal
+        # @param insert_only [Boolean] when true, an id already in the head is left untouched
+        # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` hit a
+        #   record
+        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [PG::Error] if Postgres refuses a statement
+        def atomic_put(entry, insert_only: false)
+          refuse_superseded_write!
+          status = nil
+          transaction do
+            lock_writes!
+            status = put_status(head_row?(entry.id), insert_only)
+            append_and_project!(entry) unless status == :conflicted
+          end
+          status
+        end
+
+        # Reads this aggregate's whole journal, every era, in write order. States are decoded but
+        # not translated: an ancestor era's row keeps the shape it was written in.
+        #
+        # @return [Array<Ports::Persistence::Entry>] entries by ascending ordinal
+        def entries
+          @db.exec_params(
+            "SELECT aggregate_id, operation, state, mirrors FROM #{@lineage.quoted_journal} " \
+            "WHERE aggregate = $1 ORDER BY ordinal",
+            [table]
+          ).map { |row| entry_from_row(row) }
+        end
+
+        # Deletes this aggregate's journal rows, refusing when row-level security turns the DELETE
+        # into a silent no-op.
+        #
+        # The journal forces RLS with no DELETE policy, so an ordinary connection matches zero rows
+        # without error; comparing the count before with the DELETE's own count exposes that.
+        # Head snapshots, field caches, `events` and saga rows are left as they are.
+        #
+        # @return [Adapters::PostgresEra] this adapter
+        # @raise [Runtime::WiringError] if the journal held rows and the DELETE removed none
+        def reset!
+          before = @db.exec_params(
+            "SELECT count(*) FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table]
+          )[0]["count"].to_i
+          result = @db.exec_params("DELETE FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table])
+          refuse_silent_delete!(before, result)
+          self
+        end
+
+        private
+
+        def head_row?(id)
+          !@db.exec_params("SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1", [id.to_s]).ntuples.zero?
+        end
+
+        def put_status(exists, insert_only)
+          return :conflicted if insert_only && exists
+
+          exists ? :replaced : :inserted
+        end
+
+        def entry_from_row(row)
+          state = row["state"] && JSON.parse(row["state"])
+          Ports::Persistence::Entry.new(
+            operation: row["operation"] || "save",
+            id:        row["aggregate_id"],
+            state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
+            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
+          )
+        end
+
+        def refuse_silent_delete!(before, result)
+          return unless before.positive? && result.cmd_tuples.zero?
+
+          raise Runtime::WiringError,
+                "reset! deleted 0 of #{before} row(s) for #{table} in #{@lineage.quoted_journal} — " \
+                "FORCE ROW LEVEL SECURITY admits no DELETE policy on the journal, so this connection's " \
+                "DELETE silently matched nothing. reset! only works connected as an actual Postgres " \
+                "superuser or a role granted BYPASSRLS, not as the provisioner or an app role."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The DDL of the lineage tables and the journal, run once per boot, owner only.
+        module BaseSql
+          # The held eras of every domain.
+          ERAS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_eras (
+              domain    text NOT NULL,
+              ordinal   int  NOT NULL,
+              hash      text,
+              label     text,
+              held_text text NOT NULL,
+              watermark bigint,
+              PRIMARY KEY (domain, ordinal)
+            )
+          SQL
+
+          # Every frozen text version, archived where an edit cannot reach it.
+          ERA_TEXTS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_era_texts (
+              domain      text NOT NULL,
+              ordinal     int  NOT NULL,
+              digest      text NOT NULL,
+              held_text   text NOT NULL,
+              archived_at timestamptz NOT NULL DEFAULT now(),
+              PRIMARY KEY (domain, ordinal, digest)
+            )
+          SQL
+
+          # The Layer-3 approvals of translation edges.
+          APPROVALS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_approvals (
+              domain           text NOT NULL,
+              from_label       text NOT NULL,
+              to_label         text NOT NULL,
+              edge_digest      text NOT NULL,
+              reviewed_ordinal bigint NOT NULL,
+              approved_at      timestamptz NOT NULL DEFAULT now()
+            )
+          SQL
+
+          # An owned sequence default, not generated always as identity, which
+          # partitioned tables only support from Postgres 17.
+          JOURNAL_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS %<journal>s (
+              ordinal      bigint NOT NULL DEFAULT nextval('%<sequence>s'),
+              era          int    NOT NULL,
+              aggregate    text   NOT NULL,
+              aggregate_id text   NOT NULL,
+              operation    text   NOT NULL DEFAULT 'save',
+              state        jsonb,
+              mirrors      jsonb
+            ) PARTITION BY LIST (era)
+          SQL
+
+          # One era's partition, built apart from the journal before it is attached.
+          PARTITION_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS %<partition>s (
+              LIKE %<journal>s INCLUDING DEFAULTS
+            )
+          SQL
+
+          # Attaches a built partition to the journal.
+          ATTACH_PARTITION_SQL = <<~SQL.freeze
+            ALTER TABLE %<journal>s
+              ATTACH PARTITION %<partition>s FOR VALUES IN (%<era>s)
+          SQL
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+require_relative "../../../../../../naming"
+require_relative "../../translation/rule_compiler"
+require_relative "sql_templates"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The SQL that derives an era's head from the journal: each ancestor era's rows, cut at
+        # the watermark recorded when its successor was minted, then every edge's rules chained
+        # over them in mint order.
+        module ChainSql
+          include SqlTemplates
+
+          # Reduces the tail before chaining edges over it, not after: every
+          # reader already reduces to latest-per-id, so translating a
+          # superseded entry would be wasted work. `era` survives the
+          # reduction because each edge's case still needs it.
+          def latest_per_id(tail)
+            return tail if tail.to_s.empty?
+
+            "SELECT DISTINCT ON (aggregate_id) ordinal, era, aggregate, aggregate_id, operation, state " \
+              "FROM (#{tail}) tail_entries ORDER BY aggregate_id, ordinal DESC"
+          end
+
+          # Builds era N by layering its own last edge onto era N-1's existing
+          # matview, instead of re-deriving from raw history; returns nil
+          # (falling back to chain_sql) whenever that shortcut can't honestly
+          # apply. `edges.size != era - 1` guards names_by_era's own
+          # assumption that `edges` is the full chain reaching `era` — a
+          # shorter chain here would index names[:storage] out of bounds
+          # rather than safely falling back.
+          def layered_chain_sql(aggregate, era, edges)
+            return nil unless layerable?(era, edges)
+
+            held = eras
+            prior_view = existing_prior_view(aggregate, era, held)
+            return nil unless prior_view
+
+            layered_sql(aggregate, era, edges, held, prior_view)
+          end
+
+          # Chains the original edges in mint order rather than flattening them
+          # into one rule set: edge 1 renaming A→B then edge 2 renaming C→A
+          # has no single phase order that applies both correctly.
+          def chain_sql(aggregate, era, edges)
+            names = names_by_era(aggregate, edges)
+            tail = latest_per_id(ancestor_tail_sql(names, era))
+            chain = edges.each_with_index.map { |edge, index| edge_step_sql(edge, index, names) }
+            format(CHAIN_SQL, tail: tail, chain: chain.join(",\n"), last: edges.size)
+          end
+
+          # Reads through head_body_sql — the same layered-or-full choice
+          # compile_head! makes at mint time — so a preview can't silently
+          # drift from what a real mint will materialize.
+          def translated_latest(aggregate, era, edges)
+            latest_of(head_body_sql(aggregate, era, edges))
+          end
+
+          # The untranslated ancestor tail, latest entry per id — the "before"
+          # side of a per-rule preservation check.
+          def ancestor_latest(aggregate, era, edges)
+            names = names_by_era(aggregate, edges)
+            tail = ancestor_tail_sql(names, era)
+            return {} if tail.empty?
+
+            latest_of("SELECT ordinal, era, aggregate_id, operation, state FROM (#{tail}) tail_rows")
+          end
+
+          # Reduces to newest entry per aggregate id, dropping any id whose
+          # newest entry is a delete rather than returning it with a nil state.
+          def latest_of(sql)
+            rows = @db.exec(format(LATEST_SQL, sql: sql))
+            rows.to_h { |row| [row["aggregate_id"], JSON.parse(row["state"])] }
+          end
+
+          # The one place that picks layered vs full, so a preview
+          # (translated_latest) can never approve a branch the real mint
+          # doesn't take. `full:` mirrors compile_head!'s own default;
+          # tail_merge is the one caller that forces it true.
+          def head_body_sql(aggregate, era, edges, full: false)
+            return chain_sql(aggregate, era, edges) if full
+
+            layered_chain_sql(aggregate, era, edges) || chain_sql(aggregate, era, edges)
+          end
+
+          # Walks `was:` chains backward from the current name, so each
+          # ancestor era's rows can be found under the name of their time.
+          # names[:storage][e - 1] is the storage name for era e (1-based).
+          def names_by_era(aggregate, edges)
+            current = Array.new(edges.size + 1)
+            current[edges.size] = aggregate.name
+            (edges.size - 1).downto(0) { |index| current[index] = name_before(edges, current, index) }
+            { current: current, storage: current.map { |name| Naming.snake(name) } }
+          end
+
+          # Cuts each ancestor era's rows at the watermark recorded when its
+          # successor was minted, so later writes to the old world don't leak in.
+          def ancestor_tail_sql(names, era)
+            watermarks = eras.to_h { |held| [held[:ordinal], held[:watermark]] }
+            selects = (1...era).map do |ancestor|
+              cut = watermarks[ancestor + 1]
+              "SELECT ordinal, era, aggregate, aggregate_id, operation, state FROM #{quoted_journal} " \
+                "WHERE era = #{ancestor} AND aggregate = #{text_literal(names[:storage][ancestor - 1])}" \
+                "#{" AND ordinal <= #{cut}" if cut}"
+            end
+            selects.join(" UNION ALL ")
+          end
+
+          private
+
+          def layerable?(era, edges) = era >= 3 && edges.size >= 2 && edges.size == era - 1
+
+          # The previous era's matview, when it is labelled and already built.
+          def existing_prior_view(aggregate, era, held)
+            prior = held.find { |candidate| candidate[:ordinal] == era - 1 }
+            return nil unless prior && prior[:label]
+
+            view = matview(aggregate.storage_name, era - 1, prior[:label])
+            view if view_exists?(view)
+          end
+
+          def layered_sql(aggregate, era, edges, held, prior_view)
+            names = names_by_era(aggregate, edges)
+            declared = edges.last[:translation].for_aggregate(names[:current][edges.size])
+            tokens = layered_tokens(prior_view, names, era, declared)
+            format(LAYERED_SQL, tokens.merge(cut: cut_clause(held, era)))
+          end
+
+          def layered_tokens(prior_view, names, era, declared)
+            { prior_view: quote(prior_view), journal: quoted_journal, prior_era: era - 1,
+              aggregate: text_literal(names[:storage][era - 2]),
+              id_column: id_column_for(declared, "operation = 'save'"), expression: rules_expression(declared) }
+          end
+
+          # Cuts the previous era's rows at the watermark recorded when this era was minted.
+          def cut_clause(held, era)
+            cut = held.find { |candidate| candidate[:ordinal] == era }&.dig(:watermark)
+            " AND ordinal <= #{cut}" if cut
+          end
+
+          # One link of the chain: its edge's rules over the previous link.
+          def edge_step_sql(edge, index, names)
+            declared = edge[:translation].for_aggregate(names[:current][index + 1])
+            guard = "era <= #{index + 1} AND operation = 'save'"
+            "edge_#{index + 1} AS (SELECT ordinal, era, #{id_column_for(declared, guard)}, operation, " \
+              "CASE WHEN #{guard} THEN #{rules_expression(declared)} ELSE state END AS state " \
+              "FROM #{index.zero? ? "tail" : "edge_#{index}"})"
+          end
+
+          def rules_expression(declared)
+            declared ? Translation::RuleCompiler.compile_rules(declared) : "state"
+          end
+
+          def id_column_for(declared, guard)
+            return "aggregate_id" unless Translation::RuleCompiler.rekeyed?(declared)
+
+            Translation::RuleCompiler.id_case(guard, declared)
+          end
+
+          def name_before(edges, current, index)
+            declared = edges[index][:translation].for_aggregate(current[index + 1])
+            declared&.was || current[index + 1]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+require_relative "../../../../../../naming"
+require_relative "../../../../../../runtime/errors"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The domain rename bridge: moves a domain's journal, sequence, partitions and lineage
+        # rows from its `formerly_known_as` name to the current one.
+        module DomainRename
+          # Moves a domain's journal, sequence, partitions and lineage rows from
+          # `formerly_known_as` to the current name, in one transaction.
+          #
+          # Runs before `provisioner?` and the CREATE TABLE calls in `ensure_base!`; a no-op when
+          # `hecks_eras` is missing, the new name has rows, or the former name has none.
+          # Locks go in a fixed order (old before new, eras before ordinal) so nothing deadlocks.
+          #
+          # @return [void]
+          # @raise [Runtime::WiringError] if the locks are not granted within 10s or Postgres
+          #   refuses a statement (prechecks included); both roll back first
+          def rename_domain!
+            rename_in_transaction! if rename_pending?
+          rescue PG::LockNotAvailable
+            rollback_quietly
+            raise Runtime::WiringError,
+                  "cannot rename #{@formerly_known_as} to #{@domain}: another rename, mint, or write holds " \
+                  "one of the domain locks — waited 10s; try again shortly"
+          rescue PG::Error => e
+            rollback_quietly
+            raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
+          end
+
+          private
+
+          def rename_pending?
+            return false unless @db.exec_params("SELECT to_regclass($1)", ["hecks_eras"])[0]["to_regclass"]
+            return false if domain_rows?(@domain)
+
+            domain_rows?(@formerly_known_as)
+          end
+
+          def domain_rows?(domain)
+            @db.exec_params("SELECT 1 FROM hecks_eras WHERE domain = $1 LIMIT 1", [domain]).ntuples.positive?
+          end
+
+          def rename_in_transaction!
+            old_journal = "hecks_journal_#{Naming.snake(@formerly_known_as)}"
+            ordinals = @db.exec_params(
+              "SELECT ordinal FROM hecks_eras WHERE domain = $1 ORDER BY ordinal", [@formerly_known_as]
+            ).map { |row| row["ordinal"].to_i }
+
+            @db.exec("BEGIN")
+            @db.exec("SET LOCAL lock_timeout = '10s'")
+            rename_lock_keys.each { |key| @db.exec_params("SELECT pg_advisory_xact_lock(hashtext($1))", [key]) }
+            rename_relations!(old_journal, ordinals)
+            rename_rows!
+            @db.exec("COMMIT")
+          end
+
+          def rename_lock_keys
+            [
+              "hecks_eras:#{@formerly_known_as}", "hecks_eras:#{@domain}",
+              "hecks_ordinal:#{@formerly_known_as}", "hecks_ordinal:#{@domain}"
+            ]
+          end
+
+          def rename_relations!(old_journal, ordinals)
+            @db.exec("ALTER TABLE #{quote(old_journal)} RENAME TO #{quote(journal)}")
+            # The sequence is a plain create sequence, not owned by the column, so it
+            # does not move with the table and needs its own rename.
+            @db.exec("ALTER SEQUENCE #{quote("#{old_journal}_ordinal")} RENAME TO #{quote(sequence)}")
+            # Renaming the parent does not rename its partitions.
+            ordinals.each do |ordinal|
+              @db.exec("ALTER TABLE #{quote("#{old_journal}_era_#{ordinal}")} RENAME TO #{quote(partition(ordinal))}")
+            end
+          end
+
+          def rename_rows!
+            %w[hecks_eras hecks_era_texts hecks_approvals].each do |table|
+              @db.exec_params("UPDATE #{table} SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as])
+            end
+            # hecks_attestations is created lazily on first reattest!, so it may not exist.
+            return unless @db.exec_params("SELECT to_regclass($1)", ["hecks_attestations"])[0]["to_regclass"]
+
+            @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+require_relative "../../era_tamper"
+require_relative "../../../../../../runtime/registry"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # Era text integrity: each held text is verified against its stored digest before use,
+        # and a drifted digest is resolved only by an append-only attestation.
+        module EraIntegrity
+          # The DDL for the append-only attestation record.
+          CREATE_ATTESTATIONS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_attestations (
+              domain      text NOT NULL,
+              ordinal     int  NOT NULL,
+              old_digest  text,
+              new_digest  text NOT NULL,
+              attested_at timestamptz NOT NULL DEFAULT now()
+            )
+          SQL
+
+          # Skips the integrity check `eras` runs, so hecks reattest can show the raw row first.
+          def raw_era(ordinal)
+            rows = @db.exec_params(
+              "SELECT held_text, held_digest, hash, held_projection::text FROM hecks_eras WHERE domain = $1 AND ordinal = $2",
+              [@domain, ordinal]
+            )
+            return nil if rows.ntuples.zero?
+
+            { held_text: rows[0]["held_text"], held_digest: rows[0]["held_digest"], hash: rows[0]["hash"],
+              held_projection: rows[0]["held_projection"] }
+          end
+
+          # Resolves drift via an append-only attestation record — never patch the digest.
+          def reattest!(ordinal)
+            era = raw_era(ordinal)
+            raise Runtime::WiringError, "#{@domain} holds no era #{ordinal} to re-attest" unless era
+
+            fresh = Digest::SHA256.hexdigest(era[:held_text])
+            @db.exec(CREATE_ATTESTATIONS_SQL)
+            record_attestation!(ordinal, era[:held_digest], fresh)
+            adopt_digest!(ordinal, fresh)
+            archive_text!(ordinal, era[:held_text])
+            fresh
+          end
+
+          # A row with no stored digest yet is backfilled, not refused; only a mismatch raises.
+          def verify_integrity!(ordinal, text, stored_digest, stored_projection_json)
+            digest = Digest::SHA256.hexdigest(text)
+            store_missing_digest!(ordinal, digest) if stored_digest.nil?
+            unless stored_digest.nil? || stored_digest == digest
+              raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
+            end
+
+            backfill_frozen_facts!(ordinal, text, stored_projection_json)
+          end
+
+          # Call only on already-verified text; this would bless an unverified edit.
+          def backfill_frozen_facts!(ordinal, text, stored_projection_json)
+            archive_text!(ordinal, text)
+            return if stored_projection_json
+
+            projection = Runtime::EraTamper.project(text)
+            return unless projection
+
+            @db.exec_params(
+              "UPDATE hecks_eras SET held_projection = $3::text::jsonb " \
+              "WHERE domain = $1 AND ordinal = $2 AND held_projection IS NULL",
+              [@domain, ordinal, JSON.generate(projection)]
+            )
+          end
+
+          private
+
+          def record_attestation!(ordinal, old_digest, new_digest)
+            @db.exec_params(
+              "INSERT INTO hecks_attestations (domain, ordinal, old_digest, new_digest) VALUES ($1, $2, $3, $4)",
+              [@domain, ordinal, old_digest, new_digest]
+            )
+          end
+
+          def adopt_digest!(ordinal, digest)
+            @db.exec_params(
+              "UPDATE hecks_eras SET held_digest = $3 WHERE domain = $1 AND ordinal = $2",
+              [@domain, ordinal, digest]
+            )
+          end
+
+          def store_missing_digest!(ordinal, digest)
+            @db.exec_params(
+              "UPDATE hecks_eras SET held_digest = $3 WHERE domain = $1 AND ordinal = $2 AND held_digest IS NULL",
+              [@domain, ordinal, digest]
+            )
+          end
+        end
+      end
+    end
+  end
+end