hecks 3.5.0 → 3.6.0

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

@@ -1,4 +1,5 @@
 require_relative "../../../../../../runtime/registry"
+require_relative "merge_writes"
 
 module Hecks
   module Adapters
@@ -7,6 +8,12 @@ module Hecks
         # `merge_tail!` closes a fork: an old era's post-cut writes re-enter under named winners;
         # `diverged_count` measures the drift before that.
         module TailMerge
+          include MergeWrites
+
+          # What one merge works from: the aggregates and edge chain, the winners, and the era the
+          # tail folds into with its label, cut and the journal's tip when the merge began.
+          Merge = Data.define(:aggregates, :edges, :winners, :era, :label, :cut, :tip)
+
           # Counts the journal rows an old era wrote after the next era's cut.
           #
           # @return [Integer] 0 when the domain holds no newer era
@@ -23,9 +30,8 @@ module Hecks
           # Folds every old era's post-cut writes into the current era's heads, under winners.
           #
           # One transaction; any refusal rolls back. Records both worlds touched need a winner.
-          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-          # One transaction with a manual `ROLLBACK` at each refusal, and `new_states` must be
-          # captured before the head rebuild; splitting the steps would scatter both.
+          # One transaction with a manual `ROLLBACK` at each refusal, and the new world's head
+          # states must be captured before the head rebuild; splitting the steps would scatter both.
           #
           # @param aggregates [Array<Bluebook::Aggregate>] the current bluebook's aggregates
           # @param edges [Array<Hash>] the mint-order edge chain, from `LineageManager.edge_chain`
@@ -33,128 +39,81 @@ module Hecks
           # @param audit [#call, nil] returns violations (Array<String>); run before `COMMIT`
           # @raise [Runtime::WiringError] at era 1, an unresolved conflict, audit or lock failure
           def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
+            run_merge!(aggregates, edges, winners, audit)
+            true
+          rescue PG::LockNotAvailable
+            rollback_quietly
+            raise Runtime::WiringError, merge_lock_refusal
+          rescue PG::Error => e
+            rollback_quietly
+            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{e.message.strip}"
+          end
+
+          private
+
+          def run_merge!(aggregates, edges, winners, audit)
+            merge = begin_merge!(aggregates, edges, winners)
+            refuse_unresolved_conflicts!(merge)
+            new_states = pre_merge_states(merge)
+            recompile_heads!(merge)
+            reinsert_winners!(merge, new_states)
+            refuse_audit_violations!(audit)
+            @db.exec("COMMIT")
+          end
+
+          # Opens the transaction under the domain's era lock and reads where the merge stands.
+          def begin_merge!(aggregates, edges, winners)
+            lock_for_merge!
+            latest = eras.last
+            refuse_era_one!(latest[:ordinal])
+            Merge.new(aggregates: aggregates, edges: edges, winners: winners, era: latest[:ordinal],
+                      label: latest[:label], cut: latest[:watermark].to_i, tip: last_ordinal)
+          end
+
+          def lock_for_merge!
             @db.exec("BEGIN")
             @db.exec("SET LOCAL lock_timeout = '10s'")
             @db.exec("SELECT pg_advisory_xact_lock(hashtext('hecks_eras:' || #{text_literal(@domain)}))")
-            held = eras
-            era = held.last[:ordinal]
-            label = held.last[:label]
-            if era == 1
-              @db.exec("ROLLBACK")
-              raise Runtime::WiringError, "nothing to merge — #{@domain} stands at era 1"
-            end
-            cut = held.last[:watermark].to_i
-            tip = last_ordinal
-
-            conflicts = aggregates.flat_map { |aggregate| conflict_ids(aggregate, edges, era, cut) }
-            unresolved = conflicts.reject { |_, id| winners.key?(id) }
-            unless unresolved.empty?
-              @db.exec("ROLLBACK")
-              raise Runtime::WiringError,
-                    "cannot merge the tail of #{@domain}: touched by both worlds since the cut — " \
-                    "#{unresolved.map { |storage, id| "#{storage}##{id}" }.sort.join(', ')}. " \
-                    "Name each winner (--winner <id>=old or --winner <id>=new), then run hecks merge_tail again. " \
-                    "A winner takes the WHOLE record — the aggregate is the consistency boundary, so the " \
-                    "loser's edits are discarded even where they touched different attributes"
-            end
-
-            # the new world's pre-merge head states, captured before the
-            # rebuild lets the tail interleave
-            new_states = {}
-            aggregates.each do |aggregate|
-              winners.select { |_, side| side == "new" }.each_key do |id|
-                row = @db.exec_params("SELECT state FROM #{quote(head_view(aggregate.storage_name))} WHERE id = $1", [id])
-                new_states[id] = [aggregate.storage_name, row[0]["state"]] if row.ntuples.positive?
-              end
-            end
-
-            @db.exec_params("UPDATE hecks_eras SET watermark = $2 WHERE domain = $1 AND ordinal > 1", [@domain, tip])
-            aggregates.each do |aggregate|
-              @db.exec("DROP VIEW IF EXISTS #{quote(head_view(aggregate.storage_name))}")
-              @db.exec("DROP MATERIALIZED VIEW IF EXISTS #{quote(matview(aggregate.storage_name, era, label))}")
-              # full: the watermarks just moved — every ancestor matview's
-              # cut is stale, so there is nothing safe to layer on.
-              compile_head!(aggregate, era, label, edges, full: true)
-            end
-
-            # rubocop:disable-next Metrics/BlockLength
-            winners.each do |id, side|
-              aggregates.each do |aggregate|
-                state =
-                  if side == "old"
-                    row = @db.exec_params(
-                      "SELECT state FROM #{quote(matview(aggregate.storage_name, era, label))} " \
-                      "WHERE aggregate_id = $1 AND operation = 'save' ORDER BY ordinal DESC LIMIT 1",
-                      [id]
-                    )
-                    row.ntuples.positive? ? row[0]["state"] : nil
-                  else
-                    new_states[id]&.first == aggregate.storage_name ? new_states[id][1] : nil
-                  end
-                next unless state
-
-                # Journal first, snapshot second, as a live write does: this INSERT bypasses
-                # PostgresEra#append, and head_view reads live rows from the snapshot table.
-                ordinal = @db.exec_params(
-                  "INSERT INTO #{quoted_journal} (era, aggregate, aggregate_id, operation, state) " \
-                  "VALUES ($1, $2, $3, 'save', $4) RETURNING ordinal",
-                  [era, aggregate.storage_name, id, state]
-                )[0]["ordinal"]
-                # Always 'save': winners come from save-only sources, never a delete.
-                @db.exec_params(
-                  "INSERT INTO #{quote(head_snapshot(aggregate.storage_name, era))} (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(head_snapshot(aggregate.storage_name, era))}.ordinal < EXCLUDED.ordinal",
-                  [id, ordinal, state]
-                )
-              end
-            end
-
-            if audit
-              violations = audit.call
-              unless violations.empty?
-                @db.exec("ROLLBACK")
-                raise Runtime::WiringError,
-                      "cannot merge the tail of #{@domain}: the audit refused —\n  - #{violations.join("\n  - ")}"
-              end
-            end
+          end
 
-            @db.exec("COMMIT")
-            true
-          rescue PG::LockNotAvailable
-            begin
-              @db.exec("ROLLBACK")
-            rescue StandardError
-              nil
-            end
+          def refuse_era_one!(era)
+            return unless era == 1
+
+            @db.exec("ROLLBACK")
+            raise Runtime::WiringError, "nothing to merge — #{@domain} stands at era 1"
+          end
+
+          def refuse_unresolved_conflicts!(merge)
+            conflicts = merge.aggregates.flat_map { |aggregate| conflict_ids(aggregate, merge.edges, merge.era, merge.cut) }
+            unresolved = conflicts.reject { |_, id| merge.winners.key?(id) }
+            return if unresolved.empty?
+
+            @db.exec("ROLLBACK")
+            raise Runtime::WiringError, conflict_refusal(unresolved)
+          end
+
+          def conflict_refusal(unresolved)
+            "cannot merge the tail of #{@domain}: touched by both worlds since the cut — " \
+              "#{unresolved.map { |storage, id| "#{storage}##{id}" }.sort.join(", ")}. " \
+              "Name each winner (--winner <id>=old or --winner <id>=new), then run hecks merge_tail again. " \
+              "A winner takes the WHOLE record — the aggregate is the consistency boundary, so the " \
+              "loser's edits are discarded even where they touched different attributes"
+          end
+
+          def refuse_audit_violations!(audit)
+            return unless audit
+
+            violations = audit.call
+            return if violations.empty?
+
+            @db.exec("ROLLBACK")
             raise Runtime::WiringError,
-                  "cannot merge the tail of #{@domain}: another mint or merge holds the domain lock — " \
-                  "waited 10s; try again shortly"
-          rescue PG::Error => e
-            begin
-              @db.exec("ROLLBACK")
-            rescue StandardError
-              nil
-            end
-            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{e.message.strip}"
+                  "cannot merge the tail of #{@domain}: the audit refused —\n  - #{violations.join("\n  - ")}"
           end
-          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-          # 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)
-            olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")
-            @db.exec(<<~SQL).map { |row| [aggregate.storage_name, row["aggregate_id"]] }
-              SELECT aggregate_id FROM #{quoted_journal}
-              WHERE era < #{era.to_i} AND aggregate IN (#{olds}) AND ordinal > #{cut.to_i}
-              INTERSECT
-              SELECT aggregate_id FROM #{quoted_journal}
-              WHERE era = #{era.to_i} AND aggregate = #{text_literal(names[:storage][era - 1])}
-            SQL
+          def merge_lock_refusal
+            "cannot merge the tail of #{@domain}: another mint or merge holds the domain lock — " \
+              "waited 10s; try again shortly"
           end
         end
       end

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

@@ -1,3 +1,5 @@
+require_relative "transform_sql"
+
 module Hecks
   module Adapters
     class PostgresEra
@@ -22,123 +24,7 @@ module Hecks
 
           # Runs the six definitions without a lock; `install_transforms!` is the locked entry.
           def install_transform_functions!
-            install_hecks_tr_extract!
-            install_hecks_tr_insert!
-            install_hecks_tr_rename!
-            install_hecks_tr_move!
-            install_hecks_tr_convert!
-            install_hecks_tr_drop!
-          end
-
-          private
-
-          def install_hecks_tr_extract!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_extract(state jsonb, path text[], OUT remaining jsonb, OUT value jsonb, OUT present boolean)
-              LANGUAGE plpgsql IMMUTABLE AS $fn$
-              DECLARE parent jsonb; leaf text;
-              BEGIN
-                remaining := state;
-                present := false;
-                leaf := path[array_upper(path, 1)];
-                IF array_length(path, 1) = 1 THEN
-                  IF state ? leaf THEN
-                    present := true;
-                    value := state -> leaf;
-                    remaining := state - leaf;
-                  END IF;
-                  RETURN;
-                END IF;
-                parent := state #> path[1:array_upper(path, 1) - 1];
-                IF jsonb_typeof(parent) = 'object' AND parent ? leaf THEN
-                  present := true;
-                  value := parent -> leaf;
-                  parent := parent - leaf;
-                  IF parent = '{}'::jsonb THEN
-                    remaining := state - path[1];
-                  ELSE
-                    remaining := jsonb_set(state, path[1:array_upper(path, 1) - 1], parent);
-                  END IF;
-                END IF;
-              END $fn$
-            SQL
-          end
-
-          # Refuses to nest under a non-object value (such as a reference id): overwriting it would
-          # be an undeclared drop. The Ruby reference transform's `insert` raises the same wording.
-          def install_hecks_tr_insert!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_insert(state jsonb, path text[], value jsonb, rule_label text) RETURNS jsonb
-              LANGUAGE plpgsql IMMUTABLE AS $fn$
-              BEGIN
-                IF array_length(path, 1) = 1 THEN
-                  RETURN state || jsonb_build_object(path[1], value);
-                END IF;
-                IF state ? path[1] AND jsonb_typeof(state -> path[1]) <> 'object' THEN
-                  RAISE EXCEPTION 'cannot %: % already holds %, not a value this can nest under — moving into it would discard that value silently. Rename or drop % first.',
-                    rule_label, path[1], state -> path[1], path[1];
-                END IF;
-                IF state -> path[1] IS NULL THEN
-                  state := state || jsonb_build_object(path[1], '{}'::jsonb);
-                END IF;
-                RETURN jsonb_set(state, path, value);
-              END $fn$
-            SQL
-          end
-
-          def install_hecks_tr_rename!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_rename(state jsonb, old_name text, new_name text) RETURNS jsonb
-              LANGUAGE sql IMMUTABLE AS $fn$
-                SELECT CASE WHEN state ? old_name
-                  THEN (state - old_name) || jsonb_build_object(new_name, state -> old_name)
-                  ELSE state END
-              $fn$
-            SQL
-          end
-
-          def install_hecks_tr_move!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
-              LANGUAGE plpgsql IMMUTABLE AS $fn$
-              DECLARE extracted record;
-              BEGIN
-                SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
-                IF NOT extracted.present THEN RETURN state; END IF;
-                RETURN hecks_tr_insert(extracted.remaining, to_path, extracted.value, rule_label);
-              END $fn$
-            SQL
-          end
-
-          def install_hecks_tr_convert!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
-              LANGUAGE plpgsql IMMUTABLE AS $fn$
-              DECLARE extracted record; pair jsonb;
-              BEGIN
-                SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
-                IF NOT extracted.present THEN RETURN state; END IF;
-                FOR pair IN SELECT * FROM jsonb_array_elements(pairs) LOOP
-                  IF pair -> 0 = extracted.value THEN
-                    RETURN hecks_tr_insert(extracted.remaining, to_path, pair -> 1, rule_label);
-                  END IF;
-                END LOOP;
-                RAISE EXCEPTION 'cannot translate %: % has no mapping in its convert''s values: table. Add % => ... to cover it.',
-                  from_label, extracted.value, extracted.value;
-              END $fn$
-            SQL
-          end
-
-          def install_hecks_tr_drop!
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
-              LANGUAGE plpgsql IMMUTABLE AS $fn$
-              DECLARE extracted record;
-              BEGIN
-                SELECT * INTO extracted FROM hecks_tr_extract(state, path);
-                RETURN extracted.remaining;
-              END $fn$
-            SQL
+            TransformSql::ALL.each { |sql| @db.exec(sql) }
           end
         end
       end

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

@@ -0,0 +1,116 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The six shared `hecks_tr_*` jsonb functions that compiled translation SQL calls.
+        module TransformSql
+          # Splits a path out of a state, answering what remains, the value and whether it was
+          # there.
+          TR_EXTRACT_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_extract(state jsonb, path text[], OUT remaining jsonb, OUT value jsonb, OUT present boolean)
+            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            DECLARE parent jsonb; leaf text;
+            BEGIN
+              remaining := state;
+              present := false;
+              leaf := path[array_upper(path, 1)];
+              IF array_length(path, 1) = 1 THEN
+                IF state ? leaf THEN
+                  present := true;
+                  value := state -> leaf;
+                  remaining := state - leaf;
+                END IF;
+                RETURN;
+              END IF;
+              parent := state #> path[1:array_upper(path, 1) - 1];
+              IF jsonb_typeof(parent) = 'object' AND parent ? leaf THEN
+                present := true;
+                value := parent -> leaf;
+                parent := parent - leaf;
+                IF parent = '{}'::jsonb THEN
+                  remaining := state - path[1];
+                ELSE
+                  remaining := jsonb_set(state, path[1:array_upper(path, 1) - 1], parent);
+                END IF;
+              END IF;
+            END $fn$
+          SQL
+
+          # Refuses to nest under a non-object value (such as a reference id): overwriting it would
+          # be an undeclared drop. The Ruby reference transform's `insert` raises the same wording.
+          TR_INSERT_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_insert(state jsonb, path text[], value jsonb, rule_label text) RETURNS jsonb
+            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            BEGIN
+              IF array_length(path, 1) = 1 THEN
+                RETURN state || jsonb_build_object(path[1], value);
+              END IF;
+              IF state ? path[1] AND jsonb_typeof(state -> path[1]) <> 'object' THEN
+                RAISE EXCEPTION 'cannot %: % already holds %, not a value this can nest under — moving into it would discard that value silently. Rename or drop % first.',
+                  rule_label, path[1], state -> path[1], path[1];
+              END IF;
+              IF state -> path[1] IS NULL THEN
+                state := state || jsonb_build_object(path[1], '{}'::jsonb);
+              END IF;
+              RETURN jsonb_set(state, path, value);
+            END $fn$
+          SQL
+
+          # Renames one top-level key.
+          TR_RENAME_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_rename(state jsonb, old_name text, new_name text) RETURNS jsonb
+            LANGUAGE sql IMMUTABLE AS $fn$
+              SELECT CASE WHEN state ? old_name
+                THEN (state - old_name) || jsonb_build_object(new_name, state -> old_name)
+                ELSE state END
+            $fn$
+          SQL
+
+          # Moves the value at one path to another.
+          TR_MOVE_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
+            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            DECLARE extracted record;
+            BEGIN
+              SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
+              IF NOT extracted.present THEN RETURN state; END IF;
+              RETURN hecks_tr_insert(extracted.remaining, to_path, extracted.value, rule_label);
+            END $fn$
+          SQL
+
+          # Moves a value to another path, mapping it through a lookup table.
+          TR_CONVERT_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
+            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            DECLARE extracted record; pair jsonb;
+            BEGIN
+              SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
+              IF NOT extracted.present THEN RETURN state; END IF;
+              FOR pair IN SELECT * FROM jsonb_array_elements(pairs) LOOP
+                IF pair -> 0 = extracted.value THEN
+                  RETURN hecks_tr_insert(extracted.remaining, to_path, pair -> 1, rule_label);
+                END IF;
+              END LOOP;
+              RAISE EXCEPTION 'cannot translate %: % has no mapping in its convert''s values: table. Add % => ... to cover it.',
+                from_label, extracted.value, extracted.value;
+            END $fn$
+          SQL
+
+          # Removes the value at a path.
+          TR_DROP_SQL = <<~SQL.freeze
+            CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
+            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            DECLARE extracted record;
+            BEGIN
+              SELECT * INTO extracted FROM hecks_tr_extract(state, path);
+              RETURN extracted.remaining;
+            END $fn$
+          SQL
+
+          # Every definition, in install order.
+          ALL = [TR_EXTRACT_SQL, TR_INSERT_SQL, TR_RENAME_SQL, TR_MOVE_SQL, TR_CONVERT_SQL, TR_DROP_SQL].freeze
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,7 @@ require "digest"
 
 require_relative "lineage/provisioning"
 require_relative "lineage/era_store"
+require_relative "lineage/era_integrity"
 require_relative "lineage/mint_transaction"
 require_relative "lineage/tail_merge"
 require_relative "lineage/resumable_backfill"
@@ -19,6 +20,7 @@ module Hecks
       class Lineage
         include Provisioning
         include EraStore
+        include EraIntegrity
         include MintTransaction
         include TailMerge
         include ResumableBackfill
@@ -107,7 +109,7 @@ module Hecks
 
         def path_literal(path)
           segments = path.to_s.split(".").map { |segment| text_literal(segment) }
-          "ARRAY[#{segments.join(', ')}]::text[]"
+          "ARRAY[#{segments.join(", ")}]::text[]"
         end
       end
     end

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

@@ -0,0 +1,38 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # Everything one era check carries from connecting to minting: the booting registry and
+        # bluebook, its source text, the open lineage, the role to grant, the bluebook directory,
+        # and the latest held era once the held eras were read.
+        Context = Data.define(:registry, :bluebook, :current_text, :lineage, :role, :directory, :latest) do
+          def initialize(latest: nil, **rest) = super
+
+          # @return [Integer] the ordinal of the era a mint would create
+          def ordinal = latest[:ordinal] + 1
+
+          # @return [String] the storage-shape hash of the current bluebook
+          def shape_hash = Runtime::StorageShape.mint_hash(bluebook)
+
+          # @return [String] the short label naming the current shape
+          def label = shape_hash[0, Runtime::StorageShape::LABEL_LENGTH]
+
+          # @return [Hash] the storage shape of the current bluebook
+          def current_shape = Runtime::StorageShape.project(bluebook)
+
+          # Records the era this boot resolved to on the registry.
+          #
+          # @param ordinal [Integer] the resolved era
+          # @return [Integer] `ordinal`
+          def record_resolved(ordinal) = registry.resolved_eras[bluebook.name] = ordinal
+
+          # Records the era that superseded the one this boot resolved to.
+          #
+          # @param ordinal [Integer] the superseding era
+          # @return [Integer] `ordinal`
+          def record_superseded(ordinal) = registry.superseded_eras[bluebook.name] = ordinal
+        end
+      end
+    end
+  end
+end

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

@@ -23,20 +23,31 @@ module Hecks
           # @raise [Runtime::WiringError] on an unruled identity change or an uncovered path
           def check_coverage!(registry, bluebook, held_bluebook, edge)
             bluebook.aggregates.each do |aggregate|
-              rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
-              held_aggregate = held_bluebook.aggregate(rules&.ancestor_name || aggregate.name)
-              next unless held_aggregate
-
-              check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
-              uncovered = Runtime::EraGuard.uncovered_attributes(aggregate, held_aggregate, rules)
-              Runtime::EraGuard.refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
-
-              unsafe = Runtime::EraGuard.unsafe_additions(aggregate, held_aggregate, rules)
-              Runtime::EraGuard.refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
+              check_aggregate_coverage!(bluebook, aggregate, held_bluebook, edge)
             end
             Runtime::EraGuard.check_vanished_aggregates!(registry, bluebook, held_bluebook)
           end
 
+          # Refuses an identity change, an uncovered path or an unsafe addition in one aggregate.
+          #
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era declares it
+          # @param edge [Bluebook::Translation] the one edge leaving the latest held era
+          # @raise [Runtime::WiringError] on an unruled identity change or an uncovered path
+          def check_aggregate_coverage!(bluebook, aggregate, held_bluebook, edge)
+            rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
+            held_aggregate = held_bluebook.aggregate(rules&.ancestor_name || aggregate.name)
+            return unless held_aggregate
+
+            check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
+            uncovered = Runtime::EraGuard.uncovered_attributes(aggregate, held_aggregate, rules)
+            Runtime::EraGuard.refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
+
+            unsafe = Runtime::EraGuard.unsafe_additions(aggregate, held_aggregate, rules)
+            Runtime::EraGuard.refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
+          end
+
           # Refuses a mint that changes an aggregate's identity paths without declaring a `rekey`.
           #
           # Stored ids were fixed under the prior key, so the edge must declare a `rekey` for it;
@@ -74,27 +85,34 @@ module Hecks
           # @raise [Runtime::WiringError] if a preview query fails or the audit reports a violation
           # @raise [PG::Error] if Postgres refuses the "before" query
           def audit!(bluebook, lineage, chain, ordinal, edge)
-            violations = []
-            bluebook.aggregates.each do |aggregate|
-              declared = edge.for_aggregate(aggregate.name)
-              after = begin
-                lineage.translated_latest(aggregate, ordinal, chain)
-              rescue PG::Error => e
-                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{e.message.strip}"
-              end
-              before = if chain.size > 1
-                         lineage.translated_latest(aggregate, ordinal, chain[0..-2])
-                       else
-                         lineage.ancestor_latest(aggregate, ordinal, chain)
-                       end
-              verdict = Translation::Audit.check(aggregate: aggregate, declared: declared, before: before, after: after)
-              violations.concat(verdict.violations)
+            violations = bluebook.aggregates.flat_map do |aggregate|
+              after = translated_after(bluebook, lineage, aggregate, ordinal, chain)
+              before = translated_before(lineage, aggregate, ordinal, chain)
+              verdict = Translation::Audit.check(aggregate: aggregate, declared: edge.for_aggregate(aggregate.name),
+                                                 before: before, after: after)
+              verdict.violations
             end
             return if violations.empty?
 
             raise Runtime::WiringError,
                   "cannot mint era #{ordinal} of #{bluebook.name}: the audit refused —\n  - #{violations.join("\n  - ")}"
           end
+
+          private
+
+          # The aggregate's head translated through the whole chain, as the mint would write it.
+          def translated_after(bluebook, lineage, aggregate, ordinal, chain)
+            lineage.translated_latest(aggregate, ordinal, chain)
+          rescue PG::Error => e
+            raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{e.message.strip}"
+          end
+
+          # The aggregate's head as the chain's last step receives it.
+          def translated_before(lineage, aggregate, ordinal, chain)
+            return lineage.ancestor_latest(aggregate, ordinal, chain) unless chain.size > 1
+
+            lineage.translated_latest(aggregate, ordinal, chain[0..-2])
+          end
         end
       end
     end