hecks 5.0.0 → 7.0.0

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

@@ -15,10 +15,11 @@ module Hecks
         #
         # @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 [Runtime::WiringError] if this boot's shape is not minted yet, or its 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!
+          refuse_unwritable_boot!(entry)
           transaction do
             lock_writes!
             append_and_project!(entry)
@@ -26,19 +27,20 @@ module Hecks
           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.
+        # Refuses a write from a checkout whose shape no era holds yet, or whose era a later mint
+        # has superseded. Runs before the transaction so a stale checkout takes no lock; reads stay
+        # allowed. An unminted boot lets through the one entry whose command declared `mints_era
+        # true`; a superseded boot refuses that entry too.
         #
+        # @param entry [Ports::Persistence::Entry] the write about to be journaled
         # @return [nil] when this boot's era is current
-        # @raise [Runtime::WiringError] if the boot gate marked this era superseded
-        def refuse_superseded_write!
+        # @raise [Runtime::WiringError] if the boot gate left this shape unminted and the entry is
+        #   not a mint command's record, or marked its era superseded
+        def refuse_unwritable_boot!(entry)
+          raise Runtime::WiringError, unminted_refusal if @unminted && !entry.mints_era?
           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."
+          raise Runtime::WiringError, superseded_refusal
         end
 
         # Saves an entry and reports whether it inserted or replaced, decided under the same lock
@@ -48,10 +50,11 @@ module Hecks
         # @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 [Runtime::WiringError] if this boot's shape is not minted yet, or its 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!
+          refuse_unwritable_boot!(entry)
           status = nil
           transaction do
             lock_writes!
@@ -93,6 +96,42 @@ module Hecks
 
         private
 
+        def unminted_refusal
+          "cannot write #{table} for #{@domain}: the shape is not minted yet; run the mint entry point. " \
+            "This checkout's shape#{compared_labels} is held by no era, and a write here would land in era " \
+            "#{@era}, the latest held era, under a shape it does not hold. Reads still work."
+        end
+
+        # The two labels the boot compared, as far as each can be read: the held era's and this
+        # checkout's. Empty when neither can.
+        def compared_labels
+          held = held_label
+          current = current_label
+          return "" unless held || current
+
+          " (#{current || "unknown"}, against held era #{@era}'s #{held || "unknown"})"
+        end
+
+        # @return [String, nil] the label of the era this boot reads, or nil when it cannot be read
+        def held_label
+          @lineage.eras.find { |era| era[:ordinal] == @era }&.fetch(:label, nil)
+        rescue PG::Error, Runtime::WiringError
+          nil
+        end
+
+        # @return [String, nil] this checkout's shape label, or nil for an aggregate with no owner
+        def current_label
+          owner = @aggregate.hecks_owner
+          owner && Runtime::StorageShape.mint_label(owner)
+        end
+
+        def superseded_refusal
+          "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
+
         def head_row?(id)
           !@db.exec_params("SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1", [id.to_s]).ntuples.zero?
         end

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

@@ -1,6 +1,9 @@
-require_relative "../../../../../../naming"
-require_relative "../../translation/rule_compiler"
+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,41 +113,21 @@ 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.
+          # One link of the chain: its edge's rules over the previous link. A link is `MATERIALIZED`
+          # because its `CASE` names `state` twice: left to Postgres to inline, each link doubles
+          # the
+          # expression of the one before, and a chain of eighteen links overflows the 65,535
+          # range-table entries one statement may hold.
           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, " \
+            "edge_#{index + 1} AS MATERIALIZED (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

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

@@ -0,0 +1,143 @@
+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. 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
+          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.
+          #
+          # 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).
+          #
+          # @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!(storage_names: [], cache_fields: {})
+            rename_pending? ? rename_in_transaction!(storage_names, cache_fields) : 0
+          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
+
+          # 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
+
+          # 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]) }
+            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
+            [
+              "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
+
+          # 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
+          end
+
+          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
+    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