hecks 6.0.0 → 7.0.0

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

@@ -1,6 +1,9 @@
 require_relative "../../../../naming"
 require_relative "../../../../ports/persistence/plugins/era/translation/rule_compiler"
 require_relative "sql_templates"
+require_relative "split_sql"
+require_relative "layered_sql"
+require_relative "direct_sql"
 
 module Hecks
   module Adapters
@@ -11,6 +14,9 @@ module Hecks
         # over them in mint order.
         module ChainSql
           include SqlTemplates
+          include SplitSql
+          include LayeredSql
+          include DirectSql
 
           # Reduces the tail before chaining edges over it, not after: every
           # reader already reduces to latest-per-id, so translating a
@@ -23,29 +29,12 @@ module Hecks
               "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))
+            tail = latest_per_id(target_tail_sql(names, era, edges))
             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
@@ -67,6 +56,15 @@ module Hecks
             latest_of("SELECT ordinal, era, aggregate_id, operation, state FROM (#{tail}) tail_rows")
           end
 
+          # The aggregate's head as the chain's last edge receives it: every edge but the last,
+          # read under the name the held era gives the aggregate. The last edge's `was` is that
+          # name, so a renamed aggregate's held rows are found, as `ancestor_latest` finds them.
+          # Needs at least two edges; with one, `ancestor_latest` is the whole answer.
+          def received_latest(aggregate, era, edges)
+            held_name = edges.last[:translation].for_aggregate(aggregate.name)&.was || aggregate.name
+            latest_of(chain_sql(Struct.new(:name).new(held_name), era, edges[0..-2]))
+          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)
@@ -78,10 +76,16 @@ module Hecks
           # (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
+          def head_body_sql(aggregate, era, edges, full: false, direct: direct_translation?(edges))
+            return walked_sql(aggregate, era, edges, direct) if full
 
-            layered_chain_sql(aggregate, era, edges) || chain_sql(aggregate, era, edges)
+            layered_chain_sql(aggregate, era, edges) || walked_sql(aggregate, era, edges, direct)
+          end
+
+          # The whole chain from the journal: one composed step when `direct` and the chain composes,
+          # otherwise one link per era.
+          def walked_sql(aggregate, era, edges, direct)
+            (direct && direct_chain_sql(aggregate, era, edges)) || chain_sql(aggregate, era, edges)
           end
 
           # Walks `was:` chains backward from the current name, so each
@@ -109,34 +113,10 @@ module Hecks
 
           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
+          # A split target's tail is its own journal rows plus the rows its split fans out of the
+          # source.
+          def target_tail_sql(names, era, edges)
+            [ancestor_tail_sql(names, era), split_tail_sql(names, edges)].compact.reject(&:empty?).join(" UNION ALL ")
           end
 
           # One link of the chain: its edge's rules over the previous link. A link is `MATERIALIZED`

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

@@ -0,0 +1,73 @@
+require_relative "../../../../ports/persistence/plugins/era/translation/compose"
+require_relative "sql_templates"
+require_relative "direct_verified"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The head read in one step. Each held era's rows take the translation composed from that
+        # era's edge to the last, instead of one link per later era. A chain that does not compose
+        # exactly (two steps ruling one aggregate, a rekey or a split) has no direct form and
+        # reads through `ChainSql#chain_sql` instead.
+        module DirectSql
+          include SqlTemplates
+
+          # Overrides the default of reading directly where the chain is verified.
+          #
+          # @return [Boolean, nil] true or false to force a path; nil to follow `DirectVerified`
+          attr_writer :direct_translation
+
+          # @param edges [Array<Hash>] the chain, one `{ translation: edge }` per era
+          # @return [Boolean] whether the head should read through the composed step
+          def direct_translation?(edges)
+            return @direct_translation unless @direct_translation.nil?
+
+            DirectVerified.proven?(edges.map { |edge| edge[:translation] })
+          end
+
+          # The head SQL as one step, or nil when the chain cannot be composed exactly.
+          #
+          # @param aggregate [#name, #storage_name] the aggregate whose head is read
+          # @param era [Integer] the era the head is read for
+          # @param edges [Array<Hash>] the chain reaching `era`
+          # @return [String, nil] the SQL; nil when a link needs the chain
+          def direct_chain_sql(aggregate, era, edges)
+            names = names_by_era(aggregate, edges)
+            composed = composed_by_era(aggregate, edges)
+            return unless composed
+
+            tail = latest_per_id(target_tail_sql(names, era, edges))
+            format(DIRECT_SQL, tail: tail, state: direct_state_sql(composed))
+          end
+
+          private
+
+          # The aggregate's rules from each held era to the last, keyed by that era; nil when any
+          # suffix of the chain refuses to compose.
+          def composed_by_era(aggregate, edges)
+            translations = edges.map { |edge| edge[:translation] }
+            (1..translations.size).to_h do |held|
+              composed = Translation::Compose.compose(**compose_arguments(translations.drop(held - 1)))
+              [held, composed.for_aggregate(aggregate.name)]
+            end
+          rescue Runtime::WiringError
+            nil
+          end
+
+          def compose_arguments(chain)
+            { domain: chain.first.domain, from: chain.first.from, to: chain.last.to, chain: chain }
+          end
+
+          # `state` itself when no era's rows change, else one case per era that does.
+          def direct_state_sql(composed)
+            cases = composed.filter_map do |held, declared|
+              "WHEN era = #{held} AND operation = 'save' THEN #{rules_expression(declared)}" if declared
+            end
+            cases.empty? ? "state" : "CASE #{cases.join(" ")} ELSE state END"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/lineage/direct_verified.json

@@ -0,0 +1,10 @@
+{
+  "chains": [
+    {
+      "domain": "Pizzas",
+      "from": "e3f3d7",
+      "to": "77625c",
+      "fingerprint": "cddf5d0e5867f849eff61a9cce6751bbfd221f173a9573673fac3963fb21af26"
+    }
+  ]
+}

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

@@ -0,0 +1,65 @@
+require "json"
+require "digest"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The edge chains whose composed (direct) translation `direct_translation_spec` proves
+        # equal to their one-link-per-era chain, kept as fingerprints in `direct_verified.json`.
+        #
+        # A fingerprint is the bluebook name and, for each edge in order, its origin, its target
+        # and a digest of its rules. A client chain that shares a name with a proven one but
+        # differs in any edge reads through the chain. A stale file only costs the direct path.
+        #
+        # Rewrite the file after a committed edge changes by running the generator spec:
+        #
+        #     HECKS_WRITE_DIRECT_VERIFIED=1 exe/hecks test_suite_run.run_spec_example! \
+        #       file.value=spec/adapters/driven/postgres_era/direct_verified_spec.rb \
+        #       "example.value= " --wait
+        module DirectVerified
+          PATH = File.join(__dir__, "direct_verified.json").freeze
+
+          module_function
+
+          # @param translations [Array<Bluebook::Translation>] a chain of edges, oldest first
+          # @return [String] the chain's fingerprint, SHA-256 hex
+          def fingerprint(translations)
+            edges = translations.map { |edge| [edge.from.to_s, edge.to.to_s, rules_digest(edge)] }
+            Digest::SHA256.hexdigest(JSON.generate([translations.first&.domain.to_s, edges]))
+          end
+
+          # @param translations [Array<Bluebook::Translation>] a chain of edges, oldest first
+          # @return [Boolean] whether this exact chain is one the spec proved
+          def proven?(translations)
+            return false if translations.empty? || translations.any?(&:nil?)
+
+            proven.include?(fingerprint(translations))
+          rescue StandardError
+            false
+          end
+
+          # @return [Array<String>] the proven fingerprints in the committed file; empty if it is
+          #   missing or unreadable
+          def proven
+            JSON.parse(File.read(PATH)).fetch("chains", []).map { |chain| chain["fingerprint"] }
+          rescue SystemCallError, JSON::ParserError
+            []
+          end
+
+          # @param chains [Array<Array>] each `[domain, start label, final label, edges]` proved
+          # @return [String] the file's JSON text for those chains
+          def render(chains)
+            rows = chains.map do |domain, start, final, edges|
+              { "domain" => domain, "from" => start.to_s, "to" => final.to_s, "fingerprint" => fingerprint(edges) }
+            end
+            ordered = rows.uniq.sort_by { |row| row.values_at("domain", "from", "to", "fingerprint") }
+            "#{JSON.pretty_generate("chains" => ordered)}\n"
+          end
+
+          def rules_digest(edge) = Digest::SHA256.hexdigest(JSON.generate(edge.to_plan))
+        end
+      end
+    end
+  end
+end

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

@@ -1,25 +1,32 @@
 require_relative "../../../../naming"
 require_relative "../../../../runtime/errors"
+require_relative "domain_rename_state"
 
 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.
+        # rows from its `formerly_known_as` name to the current one. Only the rename entry point
+        # (`Era.RenameDomain`) moves them; a boot or a provisioning that finds the move pending
+        # refuses by name (`refuse_pending_rename!`), so no history starts fresh beside the old.
         module DomainRename
-          # Moves a domain's journal, sequence, partitions and lineage rows from
-          # `formerly_known_as` to the current name, in one transaction.
+          include DomainRenameState
+
+          # Moves a domain's journal, sequence, partitions, lineage rows, heads and field caches
+          # 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.
+          # 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).
           #
-          # @return [void]
+          # @param storage_names [Array<String>] the storage names of the domain's aggregates
+          # @param cache_fields [Hash{String => Array<String>}] each aggregate's storage name mapped
+          #   to the where-fields its queries cache, whose tables hash the domain
+          # @return [Integer] how many eras moved; 0 when nothing was pending
           # @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?
+          def rename_domain!(storage_names: [], cache_fields: {})
+            rename_pending? ? rename_in_transaction!(storage_names, cache_fields) : 0
           rescue PG::LockNotAvailable
             rollback_quietly
             raise Runtime::WiringError,
@@ -30,31 +37,71 @@ module Hecks
             raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
           end
 
-          private
-
+          # Tells whether the history sits under the former name while the current name holds none.
+          #
+          # @return [Boolean] false with no prior name, no eras table, eras under the current name,
+          #   or none under the former name
+          # @raise [PG::Error] if the lookup fails
           def rename_pending?
+            return false unless @formerly_known_as
             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
 
+          # Refuses, by name, to go on while the rename is pending.
+          #
+          # @return [void]
+          # @raise [Runtime::WiringError] if `rename_pending?`
+          def refuse_pending_rename!
+            return unless rename_pending?
+
+            raise Runtime::WiringError,
+                  "cannot boot #{@domain}: its history is held under the former name #{@formerly_known_as} " \
+                  "and #{@domain} holds none; rename the domain with era.rename_domain first " \
+                  "(`hecks era.rename_domain! domain=<domain directory> --confirm`)"
+          end
+
+          private
+
           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 }
-
+          # The locks come first and the eras are read after them, so a mint that lands before the
+          # locks are granted has its partition renamed with the rest; the pending check is made
+          # again under the locks for a rename that finished while this one waited.
+          def rename_in_transaction!(storage_names, cache_fields)
             @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!
+            return finish_without_moving unless rename_pending?
+
+            eras = former_eras
+            move_everything!(eras, storage_names, cache_fields)
             @db.exec("COMMIT")
+            eras.size
+          end
+
+          def finish_without_moving
+            @db.exec("ROLLBACK")
+            0
+          end
+
+          def move_everything!(eras, storage_names, cache_fields)
+            rename_relations!("hecks_journal_#{Naming.snake(@formerly_known_as)}", eras.map(&:first))
+            rename_heads!(storage_names, eras)
+            rename_catalogue_relations!
+            rename_field_caches!(cache_fields, eras.map(&:first))
+            rename_rows!
+          end
+
+          # The former name's eras as [ordinal, label] pairs, oldest first.
+          def former_eras
+            @db.exec_params(
+              "SELECT ordinal, label FROM hecks_eras WHERE domain = $1 ORDER BY ordinal", [@formerly_known_as]
+            ).map { |row| [row["ordinal"].to_i, row["label"]] }
           end
 
           def rename_lock_keys
@@ -75,14 +122,19 @@ module Hecks
             end
           end
 
-          def rename_rows!
-            %w[hecks_eras hecks_era_texts].each do |table|
-              @db.exec_params("UPDATE #{table} SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as])
+          # Renames each aggregate's head view, per-era snapshot tables and translated-tail views;
+          # ALTER TABLE renames a view as it does a table, and the view keeps its snapshot by oid.
+          def rename_heads!(storage_names, eras)
+            former = self.class.new(@db, @formerly_known_as)
+            storage_names.each do |name|
+              rename_relation!(former.head_view(name), head_view(name))
+              eras.each { |ordinal, label| rename_era_heads!(former, name, ordinal, label) }
             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"]
+          end
 
-            @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as])
+          def rename_era_heads!(former, name, ordinal, label)
+            rename_relation!(former.head_snapshot(name, ordinal), head_snapshot(name, ordinal))
+            rename_relation!(former.matview(name, ordinal, label), matview(name, ordinal, label)) if label
           end
         end
       end

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

@@ -0,0 +1,108 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # What a domain rename moves besides the journal: every table keyed by the domain's name,
+        # the head objects found in the catalogue (not by the aggregates the bluebook lists now, so
+        # an aggregate since removed moves too), the field caches whose names hash the domain, and
+        # the backfill cursors that name the renamed relations.
+        module DomainRenameState
+          # Tables with a `domain` column, moved by name when they exist.
+          DOMAIN_TABLES = %w[hecks_eras hecks_era_texts hecks_attestations hecks_ledger_archives
+                             hecks_saga_instances].freeze
+
+          # The suffixes of the relations a domain's heads and archives are named with.
+          HEAD_SUFFIX = /\A(?<storage>.+?)_(?<kind>head|head_snapshot_\d+|lineage_\d+_[^_]+|archived_\d+)\z/
+
+          private
+
+          def rename_rows!
+            DOMAIN_TABLES.each do |table|
+              next unless relation?(table)
+
+              @db.exec_params("UPDATE #{table} SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as])
+            end
+            rename_archive_names!
+          end
+
+          # An archive table moved with its domain prefix, so its list says where it is now.
+          def rename_archive_names!
+            return unless relation?("hecks_ledger_archives")
+
+            @db.exec_params(
+              "UPDATE hecks_ledger_archives SET archive = $3 || substr(archive, $4) " \
+              "WHERE domain = $1 AND left(archive, $4 - 1) = $2",
+              [@domain, "#{former_prefix}_", "#{current_prefix}_", former_prefix.length + 2]
+            )
+          end
+
+          def relation?(name) = !@db.exec_params("SELECT to_regclass($1)", [quote(name)])[0]["to_regclass"].nil?
+
+          def former_prefix = Naming.snake(@formerly_known_as)
+
+          def current_prefix = Naming.snake(@domain)
+
+          # Renames each head, snapshot, matview and archive the catalogue holds under the former
+          # prefix, leaving alone those that belong to another domain whose name extends it.
+          def rename_catalogue_relations!
+            catalogue_relations.each do |name|
+              rename_relation!(name, name.sub(/\A#{Regexp.escape(former_prefix)}_/, "#{current_prefix}_"))
+            end
+          end
+
+          def catalogue_relations
+            others = other_prefixes
+            names = @db.exec_params(
+              "SELECT relname FROM pg_class WHERE relkind IN ('r', 'v', 'm') AND relname LIKE $1 " \
+              "AND pg_table_is_visible(oid) ORDER BY relname", ["#{former_prefix.gsub("_", "\\_")}\\_%"]
+            ).map { |row| row["relname"] }
+            names.select { |name| head_name?(name) && others.none? { |other| name.start_with?("#{other}_") } }
+          end
+
+          def head_name?(name) = name.delete_prefix("#{former_prefix}_").match?(HEAD_SUFFIX)
+
+          # Prefixes of other held domains that extend the former name and so would match it.
+          def other_prefixes
+            held = @db.exec_params("SELECT DISTINCT domain FROM hecks_eras WHERE domain NOT IN ($1, $2)",
+                                   [@formerly_known_as, @domain]).map { |row| Naming.snake(row["domain"]) }
+            held.select { |other| other.start_with?("#{former_prefix}_") }
+          end
+
+          # The field caches for each cached field of each aggregate, under every held era.
+          def rename_field_caches!(cache_fields, ordinals)
+            former = self.class.new(@db, @formerly_known_as)
+            cache_fields.each do |storage, fields|
+              ordinals.product(fields) do |ordinal, field|
+                rename_cache!(former.field_cache(storage, ordinal, field), field_cache(storage, ordinal, field))
+              end
+            end
+          end
+
+          def rename_cache!(from, to)
+            rename_relation!(from, to)
+          end
+
+          # Renames a table, view or materialized view, the indexes named after it and its cursor.
+          def rename_relation!(from, to)
+            return unless relation?(from)
+
+            @db.exec("ALTER TABLE #{quote(from)} RENAME TO #{quote(to)}")
+            rename_progress!(from, to)
+            %w[_value_idx _reduce_idx _pkey].each { |suffix| rename_index!("#{from}#{suffix}", "#{to}#{suffix}") }
+          end
+
+          def rename_index!(from, to)
+            @db.exec("ALTER INDEX #{quote(from)} RENAME TO #{quote(to)}") if relation?(from)
+          end
+
+          # The backfill cursor follows its relation, so a renamed snapshot is not filled afresh.
+          def rename_progress!(from, to)
+            return unless relation?("hecks_backfill_progress")
+
+            @db.exec_params("UPDATE hecks_backfill_progress SET target = $2 WHERE target = $1", [from, to])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 require_relative "../../../../ports/persistence/plugins/era/era_tamper"
+require_relative "../../../../ports/persistence/plugins/era/projected_bluebook"
 require_relative "../../../../runtime/registry"
 
 module Hecks
@@ -45,23 +46,27 @@ module Hecks
           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)
+          # `stored_hash` is the era's name, which a missing projection is backfilled against.
+          def verify_integrity!(ordinal, text, stored_digest, stored_projection_json, stored_hash = nil)
             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)
+            backfill_frozen_facts!(ordinal, text, stored_projection_json, stored_hash)
           end
 
-          # Call only on already-verified text; this would bless an unverified edit.
-          def backfill_frozen_facts!(ordinal, text, stored_projection_json)
+          # Call only on already-verified text; this would bless an unverified edit. A missing
+          # projection is filled from the text only when the text hashes to the era's stored hash,
+          # so it is the whole domain the era was minted from; a domain split across files whose
+          # top-level file alone was held stays without one, and reading its shape refuses by name.
+          def backfill_frozen_facts!(ordinal, text, stored_projection_json, stored_hash = nil)
             archive_text!(ordinal, text)
-            return if stored_projection_json
+            return if stored_projection_json || stored_hash.nil?
 
             projection = Runtime::EraTamper.project(text)
-            return unless projection
+            return unless projection && Runtime::ProjectedBluebook.new(projection).mint_hash == stored_hash
 
             @db.exec_params(
               "UPDATE hecks_eras SET held_projection = $3::text::jsonb " \

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

@@ -9,19 +9,66 @@ module Hecks
         # CRUD over `hecks_eras`/`hecks_era_texts`: era text
         # integrity, archiving, and once-only era naming.
         module EraStore
-          # Verifies each held text's digest before returning it; a missing digest is backfilled.
+          # Verifies each held text's digest before returning it; a missing digest is backfilled. A
+          # reading lineage verifies without writing.
           def eras
+            return eras_unrecorded if @reading
+
             @db.exec_params(
-              "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
+              "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text, edge::text " \
               "FROM hecks_eras WHERE domain = $1 ORDER BY ordinal",
               [@domain]
             ).map do |row|
-              verify_integrity!(row["ordinal"].to_i, row["held_text"], row["held_digest"], row["held_projection"])
-              { ordinal: row["ordinal"].to_i, hash: row["hash"], label: row["label"],
-                held_text: row["held_text"], watermark: row["watermark"]&.to_i }
+              verify_integrity!(row["ordinal"].to_i, row["held_text"], row["held_digest"], row["held_projection"],
+                                row["hash"])
+              era_from(row)
             end
           end
 
+          # The held eras as stored, each text checked against its digest in memory. Unlike `eras`,
+          # nothing is archived or backfilled, so a reading works under a role that may only select.
+          #
+          # @return [Array<Hash>] the eras, as `eras` answers them
+          # @raise [Runtime::WiringError] when a held text does not match its digest
+          def eras_unrecorded
+            return [] unless table_exists?("hecks_eras")
+
+            @db.exec_params(
+              "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text, edge::text " \
+              "FROM hecks_eras WHERE domain = $1 ORDER BY ordinal",
+              [@domain]
+            ).map { |row| unrecorded_era(row) }
+          end
+
+          def unrecorded_era(row)
+            ordinal = row["ordinal"].to_i
+            stored = row["held_digest"]
+            if stored && stored != Digest::SHA256.hexdigest(row["held_text"])
+              raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
+            end
+
+            era_from(row)
+          end
+
+          # @return [Hash] the era a row holds, as `eras` answers it
+          def era_from(row)
+            { ordinal: row["ordinal"].to_i, hash: row["hash"], label: row["label"], held_text: row["held_text"],
+              watermark: row["watermark"]&.to_i, edge: parsed_edge(row["edge"]),
+              projection: parsed_projection(row["held_projection"]) }
+          end
+
+          # @return [Hash, nil] the storage-shape projection the era's mint recorded, string-keyed
+          #   as `StorageShape.project` answers it, or nil for an era minted without one
+          def parsed_projection(text)
+            text && JSON.parse(text)
+          end
+
+          # @return [Hash, nil] the edge column as symbol-keyed JSON, or nil for an era a written
+          #   edge reached
+          def parsed_edge(text)
+            text && JSON.parse(text, symbolize_names: true)
+          end
+
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]
@@ -60,6 +107,17 @@ module Hecks
           def last_ordinal
             @db.exec("SELECT COALESCE(max(ordinal), 0) AS o FROM #{quoted_journal}")[0]["o"].to_i
           end
+
+          # How many journal rows above an ordinal belong to one record of one aggregate.
+          #
+          # @param ordinal [Integer] the ordinal the rows must exceed
+          # @param aggregate [String] the aggregate's storage name
+          # @param id [String] the record's id
+          # @return [Integer]
+          def rows_of_after(ordinal, aggregate, id)
+            sql = "SELECT count(*) AS n FROM #{quoted_journal} WHERE ordinal > $1 AND aggregate = $2 AND aggregate_id = $3"
+            @db.exec_params(sql, [ordinal, aggregate, id])[0]["n"].to_i
+          end
         end
       end
     end