hecks 3.5.0 → 3.6.0

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

@@ -1,5 +1,5 @@
-require_relative "../../../../../../naming"
-require_relative "../../translation/rule_compiler"
+require_relative "chain_sql"
+require_relative "sql_templates"
 
 module Hecks
   module Adapters
@@ -8,31 +8,14 @@ module Hecks
         # The read side of lineage: builds and maintains the head-snapshot
         # table and the compiled view/matview a query actually reads.
         module HeadCompiler
+          include ChainSql
+          include SqlTemplates
+
           # Backfill runs unconditionally after create: an existing journal
           # must never look empty just because its snapshot table is new.
           def ensure_head_snapshot!(storage_name, era)
             name = head_snapshot(storage_name, era)
-            unless table_exists?(name)
-              # Locked, not a bare CREATE, so two first-time boots can't race;
-              # nested_transaction lets this run standalone or inside mint's
-              # own already-open transaction without ending it early.
-              nested_transaction("hecks_head_snapshot") do
-                @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_head_snapshot:' || $1))", [name])
-                next if table_exists?(name)
-
-                # A delete upserts a tombstone (operation = 'delete', state
-                # NULL) instead of removing the row, so it still outranks a
-                # stale ancestor `save` row by ordinal under DISTINCT ON.
-                @db.exec(<<~SQL)
-                  CREATE TABLE #{quote(name)} (
-                    id        text PRIMARY KEY,
-                    ordinal   bigint NOT NULL,
-                    operation text NOT NULL DEFAULT 'save',
-                    state     jsonb
-                  )
-                SQL
-              end
-            end
+            create_head_snapshot_table!(name) unless table_exists?(name)
             # Self-healing for a table created before this column existed;
             # a no-op once it and the relaxed constraint are already there.
             @db.exec("ALTER TABLE #{quote(name)} ADD COLUMN IF NOT EXISTS operation text NOT NULL DEFAULT 'save'")
@@ -46,29 +29,8 @@ module Hecks
           def backfill_head_snapshot!(name, storage_name, era)
             chunked_backfill!(
               name,
-              source_sql: lambda do |cursor|
-                <<~SQL
-                  SELECT id, ordinal, state FROM (
-                    SELECT DISTINCT ON (aggregate_id) aggregate_id AS id, ordinal, operation, state
-                    FROM #{quoted_journal}
-                    WHERE era = #{era.to_i} AND aggregate = #{text_literal(storage_name)}
-                    #{"AND aggregate_id > #{text_literal(cursor)}" if cursor}
-                    ORDER BY aggregate_id, ordinal DESC
-                  ) latest WHERE operation = 'save' ORDER BY id LIMIT #{ResumableBackfill::CHUNK_SIZE}
-                SQL
-              end,
-              upsert:     lambda do |rows|
-                rows.each do |row|
-                  # Always 'save' — source_sql above already filtered to
-                  # operation = 'save' rows only.
-                  @db.exec_params(
-                    "INSERT INTO #{quote(name)} (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 #{quote(name)}.ordinal < EXCLUDED.ordinal",
-                    [row["id"], row["ordinal"], row["state"]]
-                  )
-                end
-              end
+              source_sql: ->(cursor) { head_backfill_page_sql(cursor, storage_name, era) },
+              upsert:     ->(rows) { upsert_head_snapshot_rows!(name, rows) }
             )
           end
 
@@ -100,136 +62,8 @@ module Hecks
           # tail to reduce.
           def ensure_first_head!(storage_name)
             ensure_head_snapshot!(storage_name, 1)
-            # WHERE operation = 'save' excludes delete tombstones, whose
-            # state is NULL, so a deleted id falls out of the head instead
-            # of resolving to a nil state.
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE VIEW #{quote(head_view(storage_name))} AS
-              SELECT id, state FROM #{quote(head_snapshot(storage_name, 1))} WHERE operation = 'save'
-            SQL
-          end
-
-          # 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.
-          # rubocop:disable-next Metrics/CyclomaticComplexity
-          # rubocop:disable-next Metrics/PerceivedComplexity
-          def layered_chain_sql(aggregate, era, edges)
-            return nil if era < 3 || edges.size < 2 || edges.size != era - 1
-
-            held = eras
-            prior = held.find { |candidate| candidate[:ordinal] == era - 1 }
-            return nil unless prior && prior[:label]
-
-            prior_view = matview(aggregate.storage_name, era - 1, prior[:label])
-            return nil unless view_exists?(prior_view)
-
-            names = names_by_era(aggregate, edges)
-            cut = held.find { |candidate| candidate[:ordinal] == era }&.dig(:watermark)
-            declared = edges.last[:translation].for_aggregate(names[:current][edges.size])
-            expression = declared ? Translation::RuleCompiler.compile_rules(declared) : "state"
-            id_column = if Translation::RuleCompiler.rekeyed?(declared)
-                          Translation::RuleCompiler.id_case("operation = 'save'",
-                                                            declared)
-                        else
-                          "aggregate_id"
-                        end
-
-            <<~SQL
-              WITH layered AS (
-                SELECT DISTINCT ON (aggregate_id) ordinal, aggregate_id, operation, state FROM (
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quote(prior_view)}
-                  UNION ALL
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quoted_journal}
-                  WHERE era = #{era - 1} AND aggregate = #{text_literal(names[:storage][era - 2])}#{" AND ordinal <= #{cut}" if cut}
-                ) layers ORDER BY aggregate_id, ordinal DESC
-              )
-              SELECT ordinal, #{id_column}, operation,
-                     CASE WHEN operation = 'save' THEN #{expression} ELSE state END AS state
-              FROM layered
-            SQL
-          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 do |edge, index|
-              declared = edge[:translation].for_aggregate(names[:current][index + 1])
-              expression = declared ? Translation::RuleCompiler.compile_rules(declared) : "state"
-              guard = "era <= #{index + 1} AND operation = 'save'"
-              id_column = if Translation::RuleCompiler.rekeyed?(declared)
-                            Translation::RuleCompiler.id_case(guard,
-                                                              declared)
-                          else
-                            "aggregate_id"
-                          end
-              "edge_#{index + 1} AS (SELECT ordinal, era, #{id_column}, operation, " \
-                "CASE WHEN #{guard} THEN #{expression} ELSE state END AS state " \
-                "FROM #{index.zero? ? 'tail' : "edge_#{index}"})"
-            end
-
-            <<~SQL
-              WITH tail AS (#{tail}),
-              #{chain.join(",\n")}
-              SELECT ordinal, aggregate_id, operation, state FROM edge_#{edges.size}
-            SQL
-          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(<<~SQL)
-              SELECT aggregate_id, state FROM (
-                SELECT DISTINCT ON (aggregate_id) aggregate_id, operation, state
-                FROM (#{sql}) chained ORDER BY aggregate_id, ordinal DESC
-              ) latest WHERE operation = 'save'
-            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)
+            tokens = { head_view: quote(head_view(storage_name)), snapshot: quote(head_snapshot(storage_name, 1)) }
+            @db.exec(format(FIRST_HEAD_VIEW_SQL, tokens))
           end
 
           # The matview bakes each ancestor's watermark in as a literal;
@@ -240,55 +74,11 @@ module Hecks
             storage_name = aggregate.storage_name
             view = matview(storage_name, era, label)
             body = head_body_sql(aggregate, era, edges, full: full)
-            @db.exec(<<~SQL)
-              CREATE MATERIALIZED VIEW #{quote(view)} AS
-              #{body}
-            SQL
+            @db.exec("CREATE MATERIALIZED VIEW #{quote(view)} AS\n#{body}\n")
             @db.exec("CREATE INDEX IF NOT EXISTS #{quote("#{view}_reduce_idx")} ON #{quote(view)} (aggregate_id, ordinal DESC)")
 
             ensure_head_snapshot!(storage_name, era)
-            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
-            # Reads the snapshot's own operation column rather than hardcoding
-            # 'save', so a tombstone here outranks a stale ancestor save row
-            # by ordinal instead of letting it resurrect a deleted record.
-            @db.exec(<<~SQL)
-              CREATE VIEW #{quote(head_view(storage_name))} AS
-              SELECT id, state FROM (
-                SELECT DISTINCT ON (aggregate_id) aggregate_id AS id, operation, state FROM (
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quote(view)}
-                  UNION ALL
-                  SELECT ordinal, id AS aggregate_id, operation, state
-                  FROM #{quote(head_snapshot(storage_name, era))}
-                ) merged ORDER BY aggregate_id, ordinal DESC
-              ) latest WHERE operation = 'save'
-            SQL
-          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) do |index|
-              declared = edges[index][:translation].for_aggregate(current[index + 1])
-              current[index] = declared&.was || current[index + 1]
-            end
-            storage = current.map { |name| Naming.snake(name) }
-            { current: current, storage: storage }
-          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 ")
+            replace_head_view!(storage_name, era, view)
           end
 
           # The rule-compiling helpers live in Translation::RuleCompiler instead,
@@ -307,6 +97,45 @@ module Hecks
               [name]
             ).ntuples.positive?
           end
+
+          private
+
+          # Locked, not a bare CREATE, so two first-time boots can't race;
+          # nested_transaction lets this run standalone or inside mint's
+          # own already-open transaction without ending it early.
+          def create_head_snapshot_table!(name)
+            nested_transaction("hecks_head_snapshot") do
+              @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_head_snapshot:' || $1))", [name])
+              next if table_exists?(name)
+
+              @db.exec(format(HEAD_SNAPSHOT_SQL, table: quote(name)))
+            end
+          end
+
+          def head_backfill_page_sql(cursor, storage_name, era)
+            after_cursor = ("AND aggregate_id > #{text_literal(cursor)}" if cursor)
+            format(HEAD_BACKFILL_SQL, journal: quoted_journal, era: era.to_i, aggregate: text_literal(storage_name),
+                                      after_cursor: after_cursor, chunk_size: ResumableBackfill::CHUNK_SIZE)
+          end
+
+          def upsert_head_snapshot_rows!(name, rows)
+            rows.each do |row|
+              # Always 'save' — the source SQL filtered to operation = 'save' rows only.
+              @db.exec_params(
+                "INSERT INTO #{quote(name)} (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 #{quote(name)}.ordinal < EXCLUDED.ordinal",
+                [row["id"], row["ordinal"], row["state"]]
+              )
+            end
+          end
+
+          def replace_head_view!(storage_name, era, view)
+            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
+            tokens = { head_view: quote(head_view(storage_name)), view: quote(view),
+                       snapshot: quote(head_snapshot(storage_name, era)) }
+            @db.exec(format(HEAD_VIEW_SQL, tokens))
+          end
         end
       end
     end

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

@@ -0,0 +1,120 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The row-level steps of a tail merge: finding the ids both worlds touched, capturing the
+        # new world's head states, rebuilding the heads, and writing each winner back.
+        module MergeWrites
+          # The ids written by both worlds since the cut.
+          CONFLICT_SQL = <<~SQL.freeze
+            SELECT aggregate_id FROM %<journal>s
+            WHERE era < %<era>s AND aggregate IN (%<olds>s) AND ordinal > %<cut>s
+            INTERSECT
+            SELECT aggregate_id FROM %<journal>s
+            WHERE era = %<era>s AND aggregate = %<current>s
+          SQL
+
+          # Ids written by both worlds since the cut, as `[storage_name, aggregate_id]` pairs.
+          #
+          # Compares raw ids: a rekeyed record's pre- and post-rekey rows never intersect and
+          # survive as two separate heads (a duplicate, not corruption); resolve by hand.
+          def conflict_ids(aggregate, edges, era, cut)
+            names = names_by_era(aggregate, edges)
+            rows = @db.exec(conflict_sql(names, era, cut))
+            rows.map { |row| [aggregate.storage_name, row["aggregate_id"]] }
+          end
+
+          private
+
+          def conflict_sql(names, era, cut)
+            olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")
+            format(CONFLICT_SQL, journal: quoted_journal, era: era.to_i, olds: olds, cut: cut.to_i,
+                                 current: text_literal(names[:storage][era - 1]))
+          end
+
+          # The new world's pre-merge head states, captured before the
+          # rebuild lets the tail interleave.
+          def pre_merge_states(merge)
+            new_ids = merge.winners.select { |_, side| side == "new" }.keys
+            merge.aggregates.each_with_object({}) do |aggregate, states|
+              new_ids.each do |id|
+                state = head_state(aggregate, id)
+                states[id] = [aggregate.storage_name, state] if state
+              end
+            end
+          end
+
+          # The record's state in the aggregate's current head, or nil when it is not there.
+          def head_state(aggregate, id)
+            row = @db.exec_params("SELECT state FROM #{quote(head_view(aggregate.storage_name))} WHERE id = $1", [id])
+            row[0]["state"] if row.ntuples.positive?
+          end
+
+          def recompile_heads!(merge)
+            @db.exec_params("UPDATE hecks_eras SET watermark = $2 WHERE domain = $1 AND ordinal > 1", [@domain, merge.tip])
+            merge.aggregates.each do |aggregate|
+              drop_head!(aggregate, merge)
+              # full: the watermarks just moved — every ancestor matview's
+              # cut is stale, so there is nothing safe to layer on.
+              compile_head!(aggregate, merge.era, merge.label, merge.edges, full: true)
+            end
+          end
+
+          def drop_head!(aggregate, merge)
+            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(aggregate.storage_name))}")
+            @db.exec("DROP MATERIALIZED VIEW IF EXISTS #{quote(matview(aggregate.storage_name, merge.era, merge.label))}")
+          end
+
+          def reinsert_winners!(merge, new_states)
+            merge.winners.each do |id, side|
+              merge.aggregates.each do |aggregate|
+                state = winner_state(merge, aggregate, id, side, new_states)
+                write_winner!(merge, aggregate, id, state) if state
+              end
+            end
+          end
+
+          # The winning state of one record: the old world's from the rebuilt matview, the new
+          # world's from the states captured before the rebuild; nil when this aggregate has none.
+          def winner_state(merge, aggregate, id, side, new_states)
+            return new_winner_state(aggregate, id, new_states) unless side == "old"
+
+            row = @db.exec_params(
+              "SELECT state FROM #{quote(matview(aggregate.storage_name, merge.era, merge.label))} " \
+              "WHERE aggregate_id = $1 AND operation = 'save' ORDER BY ordinal DESC LIMIT 1",
+              [id]
+            )
+            row.ntuples.positive? ? row[0]["state"] : nil
+          end
+
+          def new_winner_state(aggregate, id, new_states)
+            new_states[id]&.first == aggregate.storage_name ? new_states[id][1] : nil
+          end
+
+          # Journal first, snapshot second, as a live write does: this INSERT bypasses
+          # PostgresEra#append, and head_view reads live rows from the snapshot table.
+          def write_winner!(merge, aggregate, id, state)
+            ordinal = @db.exec_params(
+              "INSERT INTO #{quoted_journal} (era, aggregate, aggregate_id, operation, state) " \
+              "VALUES ($1, $2, $3, 'save', $4) RETURNING ordinal",
+              [merge.era, aggregate.storage_name, id, state]
+            )[0]["ordinal"]
+            upsert_winner_snapshot!(snapshot: quote(head_snapshot(aggregate.storage_name, merge.era)),
+                                    id: id, ordinal: ordinal, state: state)
+          end
+
+          # Always 'save': winners come from save-only sources, never a delete.
+          def upsert_winner_snapshot!(snapshot:, id:, ordinal:, state:)
+            @db.exec_params(
+              "INSERT INTO #{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 #{snapshot}.ordinal < EXCLUDED.ordinal",
+              [id, ordinal, state]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,67 +8,36 @@ module Hecks
         # `mint_era!`: writes a new era in one transaction and advances the current-era
         # RLS fence (`advance_era!`) just before commit.
         module MintTransaction
+          # The era a mint writes: its name, frozen text, the aggregates to recompile and the
+          # edge chain that derives their heads.
+          Mint = Data.define(:ordinal, :shape_hash, :label, :held_text, :aggregates, :edges, :role, :projection) do
+            def initialize(role: nil, projection: nil, **rest) = super
+          end
+
           # Makes a new era real in one locked transaction, or reports a concurrent minter won.
           #
-          # @param ordinal [Integer] ordinal of the era to mint, one past the newest held era
           # @param hash [String] the era's shape hash, SHA-256 hex
-          # @param label [String] the era's short label, a prefix of `hash`
-          # @param held_text [String] the bluebook source text to freeze as this era
-          # @param aggregates [Array<Bluebook::Aggregate>] aggregates whose heads are recompiled
-          # @param edges [Array<Hash>] the full edge chain in mint order, one per step
-          # @param role [String, nil] app role to grant privileges to; nil grants nothing
-          # @param projection [Hash{String => Object}, nil] storage-shape projection, or nil
+          # @param fields [Hash] the keywords of `Mint`: `ordinal:` (one past the newest held era),
+          #   `label:` (a prefix of `hash`),
+          #   `held_text:` (the bluebook source to freeze as this era), `aggregates:` (whose heads
+          #   are recompiled), `edges:` (the full edge chain in mint order, one per step), and
+          #   optionally `role:` (app role to grant privileges to; nil grants nothing) and
+          #   `projection:` (the storage-shape projection, or nil)
           # @return [Boolean] true once committed; false, rolled back, if `ordinal` is held
           # @raise [Runtime::WiringError] on a lock wait over 10s or a Postgres error
-          def mint_era!(ordinal:, hash:, label:, held_text:, aggregates:, edges:, role: nil, projection: nil)
-            @db.exec("BEGIN")
-            # Mint is non-interactive, so a concurrent minter fails fast with a name, not a hang.
-            @db.exec("SET LOCAL lock_timeout = '10s'")
-            @db.exec("SELECT pg_advisory_xact_lock(hashtext('hecks_eras:' || #{text_literal(@domain)}))")
-            if eras.any? { |era| era[:ordinal] == ordinal }
-              @db.exec("ROLLBACK")
-              return false
-            end
+          # @raise [ArgumentError] on a missing or unknown keyword
+          def mint_era!(hash:, **fields)
+            mint = Mint.new(shape_hash: hash, **fields)
+            return false if stand_down?(mint)
 
-            watermark = last_ordinal
-            @db.exec_params(
-              "INSERT INTO hecks_eras (domain, ordinal, hash, label, held_text, watermark, held_digest, " \
-              "held_projection, canon_form) " \
-              "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)",
-              [@domain, ordinal, hash, label, held_text, watermark, Digest::SHA256.hexdigest(held_text),
-               projection && JSON.generate(projection), Runtime::StorageShape::FORM_VERSION]
-            )
-            archive_text!(ordinal, held_text)
-            ensure_partition!(ordinal)
-            # grant_role! must follow compile_head!, which creates the per-era snapshot
-            # tables that it grants on.
-            aggregates.each { |aggregate| compile_head!(aggregate, ordinal, label, edges) }
-            grant_role!(role, aggregates: aggregates, era: ordinal) if role
-            # Must stay last, right before `COMMIT`: DROP/CREATE POLICY takes an
-            # AccessExclusiveLock held to commit, so placing it before compile_head!
-            # would block every writer for the whole matview build.
-            #
-            # Unconditional, even with no role configured: the cutoff is a fact about the
-            # era, and a role granted by an earlier boot must lose old-era writes on commit.
-            advance_era!(ordinal)
-            @db.exec("COMMIT")
+            write_era!(mint)
             true
           rescue PG::LockNotAvailable
-            begin
-              @db.exec("ROLLBACK")
-            rescue StandardError
-              nil
-            end
-            raise Runtime::WiringError,
-                  "cannot mint era #{ordinal} of #{@domain}: another mint holds the domain lock — " \
-                  "waited 10s; try again shortly"
+            rollback_quietly
+            raise Runtime::WiringError, lock_refusal(mint)
           rescue PG::Error => e
-            begin
-              @db.exec("ROLLBACK")
-            rescue StandardError
-              nil
-            end
-            raise Runtime::WiringError, "cannot mint era #{ordinal} of #{@domain}: #{e.message.strip}"
+            rollback_quietly
+            raise Runtime::WiringError, "cannot mint era #{mint.ordinal} of #{@domain}: #{e.message.strip}"
           end
 
           # Grants an app role what it needs to append to the journal and read and write heads.
@@ -91,14 +60,7 @@ module Hecks
             @db.exec("GRANT USAGE ON SEQUENCE #{quote(sequence)} TO #{quoted_role}")
             return unless era
 
-            aggregates.each do |aggregate|
-              storage_name = aggregate.storage_name
-              @db.exec("GRANT SELECT, INSERT, UPDATE, DELETE ON #{quote(head_snapshot(storage_name, era))} TO #{quoted_role}")
-              if view_exists?(head_view(storage_name))
-                @db.exec("GRANT SELECT ON #{quote(head_view(storage_name))} " \
-                         "TO #{quoted_role}")
-              end
-            end
+            aggregates.each { |aggregate| grant_head!(aggregate.storage_name, era, quoted_role) }
           end
 
           # Replaces the journal's row policies: one era accepts INSERTs, every row stays readable.
@@ -121,6 +83,69 @@ module Hecks
             @db.exec("DROP POLICY IF EXISTS hecks_read_all ON #{quoted_journal}")
             @db.exec("CREATE POLICY hecks_read_all ON #{quoted_journal} FOR SELECT TO PUBLIC USING (true)")
           end
+
+          private
+
+          # Opens the mint transaction and takes the domain's mint lock. When a concurrent minter
+          # already holds this ordinal, rolls back and answers true.
+          def stand_down?(mint)
+            @db.exec("BEGIN")
+            # Mint is non-interactive, so a concurrent minter fails fast with a name, not a hang.
+            @db.exec("SET LOCAL lock_timeout = '10s'")
+            @db.exec("SELECT pg_advisory_xact_lock(hashtext('hecks_eras:' || #{text_literal(@domain)}))")
+            held = eras.any? { |era| era[:ordinal] == mint.ordinal }
+            @db.exec("ROLLBACK") if held
+            held
+          end
+
+          def write_era!(mint)
+            insert_era!(mint)
+            materialize_era!(mint)
+            @db.exec("COMMIT")
+          end
+
+          def lock_refusal(mint)
+            "cannot mint era #{mint.ordinal} of #{@domain}: another mint holds the domain lock — " \
+              "waited 10s; try again shortly"
+          end
+
+          def insert_era!(mint)
+            @db.exec_params(
+              "INSERT INTO hecks_eras (domain, ordinal, hash, label, held_text, watermark, held_digest, " \
+              "held_projection, canon_form) " \
+              "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)",
+              [@domain, mint.ordinal, mint.shape_hash, mint.label, mint.held_text, last_ordinal,
+               Digest::SHA256.hexdigest(mint.held_text), mint.projection && JSON.generate(mint.projection),
+               Runtime::StorageShape::FORM_VERSION]
+            )
+          end
+
+          def materialize_era!(mint)
+            archive_text!(mint.ordinal, mint.held_text)
+            ensure_partition!(mint.ordinal)
+            compile_and_grant!(mint)
+            # Must stay last, right before `COMMIT`: DROP/CREATE POLICY takes an
+            # AccessExclusiveLock held to commit, so placing it before compile_head!
+            # would block every writer for the whole matview build.
+            #
+            # Unconditional, even with no role configured: the cutoff is a fact about the
+            # era, and a role granted by an earlier boot must lose old-era writes on commit.
+            advance_era!(mint.ordinal)
+          end
+
+          # grant_role! must follow compile_head!, which creates the per-era snapshot
+          # tables that it grants on.
+          def compile_and_grant!(mint)
+            mint.aggregates.each { |aggregate| compile_head!(aggregate, mint.ordinal, mint.label, mint.edges) }
+            grant_role!(mint.role, aggregates: mint.aggregates, era: mint.ordinal) if mint.role
+          end
+
+          def grant_head!(storage_name, era, quoted_role)
+            @db.exec("GRANT SELECT, INSERT, UPDATE, DELETE ON #{quote(head_snapshot(storage_name, era))} TO #{quoted_role}")
+            return unless view_exists?(head_view(storage_name))
+
+            @db.exec("GRANT SELECT ON #{quote(head_view(storage_name))} TO #{quoted_role}")
+          end
         end
       end
     end