hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,64 @@
+require_relative "sql_templates"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The shortcut that builds an era from the matview of the era before it, rather than from
+        # the whole journal. A chain that cannot take it falls back to `ChainSql#chain_sql`.
+        module LayeredSql
+          include SqlTemplates
+
+          # 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
+
+          private
+
+          def layerable?(era, edges) = era >= 3 && edges.size >= 2 && edges.size == era - 1
+
+          # The previous era's matview, when it is labelled and already built.
+          def existing_prior_view(aggregate, era, held)
+            prior = held.find { |candidate| candidate[:ordinal] == era - 1 }
+            return nil unless prior && prior[:label]
+
+            view = matview(aggregate.storage_name, era - 1, prior[:label])
+            view if view_exists?(view)
+          end
+
+          def layered_sql(aggregate, era, edges, held, prior_view)
+            names = names_by_era(aggregate, edges)
+            declared = edges.last[:translation].for_aggregate(names[:current][edges.size])
+            tokens = layered_tokens(prior_view, names, era, declared)
+            format(LAYERED_SQL, tokens.merge(cut: cut_clause(held, era)))
+          end
+
+          def layered_tokens(prior_view, names, era, declared)
+            { prior_view: quote(prior_view), journal: quoted_journal, prior_era: era - 1,
+              aggregate: text_literal(names[:storage][era - 2]),
+              id_column: id_column_for(declared, "operation = 'save'"), expression: rules_expression(declared) }
+          end
+
+          # Cuts the previous era's rows at the watermark recorded when this era was minted.
+          def cut_clause(held, era)
+            cut = held.find { |candidate| candidate[:ordinal] == era }&.dig(:watermark)
+            " AND ordinal <= #{cut}" if cut
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+require "json"
+require "digest"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The writes a disposable ledger's boot makes in place of a mint: it re-holds the latest era
+        # at the booting shape, gives an aggregate a head that reads only its latest era, and moves
+        # an aggregate's rows into a dated archive table so it starts empty. Nothing is dropped:
+        # archived rows stay in their table, and each archive is listed in `hecks_ledger_archives`.
+        module LedgerReset
+          # The list of every archive a disposable ledger's boot made.
+          ARCHIVES_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_ledger_archives (
+              domain      text NOT NULL,
+              aggregate   text NOT NULL,
+              archive     text NOT NULL PRIMARY KEY,
+              row_count   bigint NOT NULL,
+              archived_at timestamptz NOT NULL DEFAULT now()
+            )
+          SQL
+
+          # The update that re-holds an era at a new shape.
+          REHOLD_SQL = "UPDATE hecks_eras SET held_text = $3, held_digest = $4, held_projection = $5::text::jsonb, " \
+                       "hash = $6, label = $7, canon_form = $8 WHERE domain = $1 AND ordinal = $2".freeze
+
+          # Moves every journal row of one aggregate, from every era, into a new table named for it
+          # and the time, then empties the aggregate's head snapshots, all in one transaction.
+          # The journal is locked against writers for the whole move, so no row can commit between
+          # the copy and the delete, and the delete must remove exactly the rows the copy holds or
+          # the transaction rolls back. A name already taken gets `_2`, `_3`, and so on; an archive
+          # is never overwritten.
+          #
+          # @param storage_name [String] the aggregate's snake-cased storage name
+          # @param stamp [String] the time the archive is named for, as `YYYYMMDDHHMMSS`
+          # @return [Array(String, Integer)] the archive table's name and how many rows it holds
+          # @raise [PG::Error] if Postgres refuses a statement; nothing is moved then
+          # @raise [Runtime::WiringError] if the delete removed other rows than the copy holds
+          def archive_aggregate!(storage_name, stamp)
+            archive = nil
+            nested_transaction("hecks_ledger_archive") do
+              lock_journal!
+              archive = unused_archive_name(storage_name, stamp)
+              move_rows!(storage_name, archive)
+            end
+            [archive, archived_count(archive)]
+          end
+
+          # Points an aggregate's head view at its snapshot in `era` alone, with no ancestor tail,
+          # creating the snapshot when it is missing. Used for an aggregate whose rows are all in
+          # that era: one just added, or one just archived.
+          #
+          # @param storage_name [String] the aggregate's snake-cased storage name
+          # @param era [Integer] the ordinal of the latest held era
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses a statement
+          def fresh_head!(storage_name, era)
+            ensure_head_snapshot!(storage_name, era)
+            tokens = { head_view: quote(head_view(storage_name)), snapshot: quote(head_snapshot(storage_name, era)) }
+            nested_transaction("hecks_fresh_head") do
+              @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
+              @db.exec(format(SqlTemplates::FIRST_HEAD_VIEW_SQL, tokens))
+            end
+          end
+
+          # Replaces the latest era's held text, digest, projection and name with the booting
+          # shape's, recording the old and new digests in `hecks_attestations`.
+          #
+          # @param ordinal [Integer] the latest held era
+          # @param text [String] the booting bluebook's source text
+          # @param projection [Hash] the booting bluebook's storage shape
+          # @param hash [String] the booting shape's mint hash
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses a statement
+          def rehold!(ordinal, text, projection, hash)
+            fresh = Digest::SHA256.hexdigest(text)
+            @db.exec(EraIntegrity::CREATE_ATTESTATIONS_SQL)
+            record_attestation!(ordinal, raw_era(ordinal)&.fetch(:held_digest), fresh)
+            @db.exec_params(REHOLD_SQL, [@domain, ordinal, text, fresh, JSON.generate(projection), hash,
+                                         hash[0, Runtime::StorageShape::LABEL_LENGTH],
+                                         Runtime::StorageShape::FORM_VERSION])
+            archive_text!(ordinal, text)
+          end
+
+          private
+
+          # Blocks every concurrent insert, update and delete on the journal until the transaction
+          # ends; reads go on. A writer that waits here lands its row in the journal after the move.
+          def lock_journal! = @db.exec("LOCK TABLE #{quoted_journal} IN SHARE ROW EXCLUSIVE MODE")
+
+          def move_rows!(storage_name, archive)
+            @db.exec("CREATE TABLE #{quote(archive)} AS SELECT * FROM #{quoted_journal} " \
+                     "WHERE aggregate = #{text_literal(storage_name)}")
+            record_archive!(storage_name, archive)
+            verify_moved!(archive, delete_journal_rows!(storage_name))
+            empty_head_snapshots!(storage_name)
+          end
+
+          # A delete of a row the archive does not hold would lose it; refuse and roll back.
+          def verify_moved!(archive, deleted)
+            return if deleted == archived_count(archive)
+
+            raise Runtime::WiringError, "the ledger archive #{archive} holds #{archived_count(archive)} rows but " \
+                                        "#{deleted} were deleted from the journal; nothing was moved"
+          end
+
+          def archived_count(archive) = @db.exec("SELECT count(*) FROM #{quote(archive)}")[0]["count"].to_i
+
+          # The archive's name, suffixed `_2`, `_3` and on while a table or listed archive has it.
+          def unused_archive_name(storage_name, stamp)
+            @db.exec(ARCHIVES_SQL)
+            base = "#{storage_name}_archived_#{stamp}"
+            (1..).lazy.map { |n| qualified_name(n == 1 ? base : "#{base}_#{n}") }.find { |name| archive_name_free?(name) }
+          end
+
+          def archive_name_free?(name)
+            return false if table_exists?(quote(name))
+
+            @db.exec_params("SELECT 1 FROM hecks_ledger_archives WHERE archive = $1", [name]).ntuples.zero?
+          end
+
+          def record_archive!(storage_name, archive)
+            @db.exec(ARCHIVES_SQL)
+            @db.exec_params("INSERT INTO hecks_ledger_archives (domain, aggregate, archive, row_count) " \
+                            "SELECT $1, $2, $3, count(*) FROM #{quote(archive)}", [@domain, storage_name, archive])
+          end
+
+          # The journal forces row-level security with no DELETE policy, so even its owner deletes
+          # nothing; a policy that admits this one aggregate's rows stands for the one statement.
+          def delete_journal_rows!(storage_name)
+            aggregate = text_literal(storage_name)
+            @db.exec("CREATE POLICY hecks_ledger_archive ON #{quoted_journal} FOR DELETE TO PUBLIC " \
+                     "USING (aggregate = #{aggregate})")
+            deleted = @db.exec("DELETE FROM #{quoted_journal} WHERE aggregate = #{aggregate}").cmd_tuples
+            @db.exec("DROP POLICY hecks_ledger_archive ON #{quoted_journal}")
+            deleted
+          end
+
+          def empty_head_snapshots!(storage_name)
+            eras.each do |era|
+              snapshot = head_snapshot(storage_name, era[:ordinal])
+              @db.exec("TRUNCATE #{quote(snapshot)}") if table_exists?(snapshot)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+require_relative "../field_cache_provisioner"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The read side of an era that the mint path provisions: each aggregate's head view and the
+        # field caches its queries narrow by. The mint that compiles an era and the first-era hold
+        # call these; nothing a boot reads does.
+        module MintProvisioning
+          # Creates and backfills one aggregate's field caches for an era, on this lineage's
+          # connection, so the caches commit with the era that owns them.
+          #
+          # @param aggregate [Bluebook::Aggregate] the aggregate whose where-fields are cached
+          # @param era [Integer] the ordinal of the era the caches belong to
+          # @return [Hash{String => String}] each cached field mapped to its cache table
+          # @raise [PG::Error] if Postgres refuses the DDL, a source read or an upsert
+          def provision_read_side!(aggregate, era)
+            FieldCacheProvisioner.new(self, aggregate, era).provision!
+          end
+
+          # Holds the read side of the first era: each aggregate's head view over the snapshot the
+          # first era holds, then its field caches, then the app role's privileges on them, as a
+          # mint grants them for a later era.
+          #
+          # @param aggregates [Array<Bluebook::Aggregate>] the domain's aggregates
+          # @param role [String, nil] the app role to grant; none when blank
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses a statement
+          def provision_first_era!(aggregates, role: nil)
+            aggregates.each do |aggregate|
+              ensure_first_head!(aggregate.storage_name)
+              provision_read_side!(aggregate, 1)
+            end
+            grant_role!(role, aggregates: aggregates, era: 1)
+          end
+
+          # Holds era 1 and provisions its read side in one transaction under the domain's era lock,
+          # so a crash leaves either all of it or none. A run that finds era 1 already held from the
+          # same text with some head view missing (a half-done run of an older version) completes
+          # it; any other held era is refused.
+          #
+          # @param text [String] the bluebook source the first era freezes
+          # @param projection [Hash, nil] the storage-shape projection of the text
+          # @param aggregates [Array<Bluebook::Aggregate>] the domain's aggregates
+          # @param role [String, nil] the app role to grant; nil or empty grants nothing
+          # @return [void]
+          # @raise [Runtime::WiringError] if another era is held, the lock is not granted in 10s,
+          #   or Postgres refuses a statement; the transaction rolls back first
+          def hold_first_era!(text, projection:, aggregates:, role: nil)
+            lock_era_table!
+            refuse_second_hold!(text, aggregates)
+            hold_first!(text, projection: projection)
+            provision_first_era!(aggregates, role: role)
+            @db.exec("COMMIT")
+          rescue StandardError
+            rollback_quietly
+            raise
+          end
+
+          private
+
+          def lock_era_table!
+            @db.exec("BEGIN")
+            @db.exec("SET LOCAL lock_timeout = '10s'")
+            @db.exec("SELECT pg_advisory_xact_lock(hashtext('hecks_eras:' || #{text_literal(@domain)}))")
+          end
+
+          # Refuses unless no era is held, or only era 1, from `text`, is held and unfinished.
+          def refuse_second_hold!(text, aggregates)
+            held = eras
+            return if held.empty?
+            return if held.size == 1 && held.first[:held_text] == text && unfinished?(aggregates)
+
+            raise Runtime::WiringError, "#{@domain} already holds an era"
+          end
+
+          def unfinished?(aggregates)
+            aggregates.any? { |aggregate| !table_exists?(head_view(aggregate.storage_name)) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -10,8 +10,9 @@ module Hecks
         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
+          Mint = Data.define(:ordinal, :shape_hash, :label, :held_text, :aggregates, :edges, :role, :projection,
+                             :edge) do
+            def initialize(role: nil, projection: nil, edge: nil, **rest) = super
           end
 
           # Makes a new era real in one locked transaction, or reports a concurrent minter won.
@@ -53,7 +54,7 @@ module Hecks
           # @return [void]
           # @raise [PG::Error] if Postgres refuses a grant
           def grant_role!(role, aggregates: [], era: nil)
-            return unless provisioner?
+            return if role.to_s.empty? || !provisioner?
 
             quoted_role = quote(role)
             @db.exec("GRANT INSERT, SELECT ON #{quoted_journal} TO #{quoted_role}")
@@ -112,11 +113,11 @@ module Hecks
           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)",
+              "held_projection, canon_form, edge) " \
+              "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)",
               [@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]
+               Runtime::StorageShape::FORM_VERSION, mint.edge && JSON.generate(mint.edge)]
             )
           end
 
@@ -136,7 +137,10 @@ module Hecks
           # 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) }
+            mint.aggregates.each do |aggregate|
+              compile_head!(aggregate, mint.ordinal, mint.label, mint.edges)
+              provision_read_side!(aggregate, mint.ordinal)
+            end
             grant_role!(mint.role, aggregates: mint.aggregates, era: mint.ordinal) if mint.role
           end
 

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

@@ -1,5 +1,6 @@
 require_relative "base_sql"
 require_relative "domain_rename"
+require_relative "../shared_tables"
 
 module Hecks
   module Adapters
@@ -12,16 +13,17 @@ module Hecks
           include DomainRename
 
           # Builds or tops up this domain's lineage schema when the connected role owns the
-          # journal (or none exists yet); any other role only attempts the rename bridge.
+          # journal (or none exists yet); any other role skips it. Also
+          # creates the event, saga and outbox tables the database shares.
           #
-          # ALTER TABLE and REVOKE are owner-only, so a non-owner app role must skip them to boot.
+          # Only the mint path and the owner-only tools call it; a boot never does. ALTER TABLE and
+          # REVOKE are owner-only, so a non-owner app role must skip them.
           #
           # @return [void]
-          # @raise [Runtime::WiringError] if the `formerly_known_as` rename cannot take
-          #   its locks within 10s or Postgres refuses one of its statements
+          # @raise [Runtime::WiringError] if the domain's `formerly_known_as` rename is still pending
           # @raise [PG::Error] if Postgres refuses a provisioning statement
           def ensure_base!
-            rename_domain! if @formerly_known_as
+            refuse_pending_rename!
             return unless provisioner?
 
             create_lineage_tables!
@@ -30,6 +32,7 @@ module Hecks
             revoke_journal_mutation!
             force_row_security!
             install_transforms!
+            SharedTables.new(@db).provision!
           end
 
           # Refuses to boot on a connection whose role Postgres exempts from row-level security
@@ -117,6 +120,9 @@ module Hecks
             # Canonical-form version that minted the name (Runtime::StorageShape::FORM_VERSION);
             # NULL reads as 1.
             @db.exec("ALTER TABLE hecks_eras ADD COLUMN IF NOT EXISTS canon_form int")
+            # The edge an era was minted under when no edge file wrote it, as `Translation::ImplicitEdge::RECORD`;
+            # NULL for every era a written edge reached.
+            @db.exec("ALTER TABLE hecks_eras ADD COLUMN IF NOT EXISTS edge jsonb")
             @db.exec(ERA_TEXTS_SQL)
           end
 

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

@@ -0,0 +1,76 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # ADR 0166: a `split` writes rows into another aggregate from one aggregate's rows. The target's
+        # head is not stored: its tail is the source's held-era state, fanned out one row per target key,
+        # and read through the same chain every head reads.
+        module SplitSql
+          # The source's rows as they are in the era the split edge starts from, latest per id, with the
+          # era kept so later edges' guards still hold.
+          SPLIT_SOURCE_SQL = <<~SQL.freeze
+            WITH tail AS MATERIALIZED (%<tail>s),
+            %<chain>s
+            SELECT ordinal, era, aggregate_id, operation, state FROM edge_%<last>s
+          SQL
+
+          # The split edge that creates `names[:current][n]`, with the source aggregate and the split, or nil.
+          def split_into(names, edges)
+            edges.each_with_index do |edge, index|
+              target = names[:current][index + 1]
+              edge[:translation].aggregates.each do |source|
+                split = source.splits.find { |candidate| candidate.into == target }
+                return { index: index, source: source, split: split } if split
+              end
+            end
+            nil
+          end
+
+          # The target's tail from its source's held-era rows: the source is chained through the edges
+          # before the split edge, so the split reads the shape it declares its fields in.
+          def split_tail_sql(names, edges)
+            found = split_into(names, edges)
+            return nil unless found
+
+            source_sql = split_source_sql(found[:source], edges, found[:index])
+            split_fanout_sql(source_sql, found[:split], names[:storage][found[:index] + 1])
+          end
+
+          # A split target's records as its split fans them out of the source, latest per id, or nil when
+          # the aggregate is not a split target: the "before" side of the audit of a split edge.
+          def split_latest(aggregate, edges)
+            tail = split_tail_sql(names_by_era(aggregate, edges), edges)
+            tail && latest_of("SELECT ordinal, era, aggregate_id, operation, state FROM (#{tail}) split_rows")
+          end
+
+          private
+
+          def split_source_sql(source, edges, index)
+            through = edges.first(index + 1)
+            names = names_by_era(Struct.new(:name).new(source.name), through)
+            tail = latest_per_id(ancestor_tail_sql(names, index + 2))
+            index.zero? ? tail : split_chain_sql(tail, through.first(index), names)
+          end
+
+          def split_chain_sql(tail, edges, names)
+            chain = edges.each_with_index.map { |edge, i| edge_step_sql(edge, i, names) }
+            format(SPLIT_SOURCE_SQL, tail: tail, chain: chain.join(",\n"), last: edges.size)
+          end
+
+          # One row per source row that carries the key: the key becomes the target's id, and the named
+          # fields are copied under their own names. Deletes are kept, so a deleted source deletes its
+          # target row too.
+          def split_fanout_sql(source_sql, split, target_storage)
+            key = text_literal(split.keyed_by.to_s)
+            # A keyed_by field is often a value object, whose identity is its `value` member.
+            key_value = "COALESCE(state -> #{key} ->> 'value', state ->> #{key})"
+            fields = split.fields.map { |field| "#{text_literal(field.to_s)}, state -> #{text_literal(field.to_s)}" }
+            "SELECT ordinal, era, #{text_literal(target_storage)} AS aggregate, #{key_value} AS aggregate_id, " \
+              "operation, jsonb_build_object(#{fields.join(", ")}) AS state " \
+              "FROM (#{source_sql}) split_source WHERE state ? #{key}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -77,6 +77,15 @@ module Hecks
             SELECT ordinal, aggregate_id, operation, state FROM edge_%<last>s
           SQL
 
+          # The chain in one step: each held era's rows take the one composed translation from
+          # that era to the current shape.
+          DIRECT_SQL = <<~SQL.freeze
+            WITH tail AS MATERIALIZED (%<tail>s),
+            direct AS MATERIALIZED (SELECT ordinal, era, aggregate_id, operation,
+              %<state>s AS state FROM tail)
+            SELECT ordinal, aggregate_id, operation, state FROM direct
+          SQL
+
           # Reduces to newest entry per aggregate id, dropping any id whose newest entry is a
           # delete.
           LATEST_SQL = <<~SQL.freeze

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

@@ -10,6 +10,8 @@ require_relative "lineage/resumable_backfill"
 require_relative "lineage/head_compiler"
 require_relative "lineage/field_cache"
 require_relative "lineage/transform_installer"
+require_relative "lineage/mint_provisioning"
+require_relative "lineage/ledger_reset"
 require_relative "../../../naming"
 
 module Hecks
@@ -27,6 +29,8 @@ module Hecks
         include HeadCompiler
         include FieldCache
         include TransformInstaller
+        include MintProvisioning
+        include LedgerReset
 
         # Longer identifiers are silently truncated by Postgres, so `qualified_name` hashes them.
         POSTGRES_IDENTIFIER_LIMIT = 63
@@ -37,11 +41,15 @@ module Hecks
         # @param domain [String, Symbol] the domain's declared name; every relation name and
         #   advisory-lock key derives from it
         # @param formerly_known_as [String, Symbol, nil] the domain's prior name, which makes
-        #   `ensure_base!` rename its relations and rows first; nil when there is no prior name
-        def initialize(db, domain, formerly_known_as: nil)
+        #   `ensure_base!` and a read refuse while the history sits under it; `rename_domain!` moves
+        #   the history; nil when there is no prior name
+        # @param reading [Boolean] true for a read: the held eras are verified in memory and never
+        #   archived or backfilled, so the connection needs only SELECT
+        def initialize(db, domain, formerly_known_as: nil, reading: false)
           @db = db
           @domain = domain.to_s
           @formerly_known_as = formerly_known_as&.to_s
+          @reading = reading
         end
 
         # Names the domain's one journal table, the partitioned parent of every era's rows.

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/context.rb

@@ -4,10 +4,11 @@ module Hecks
       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,
-        # whether this copy may mint, and the latest held era once the held eras were read.
+        # whether this copy may mint, the mint request the Maintenance mint command made (nil on
+        # a boot), and the latest held era once the held eras were read.
         Context = Data.define(:registry, :bluebook, :current_text, :lineage, :role, :directory, :latest,
-                              :mint_permitted) do
-          def initialize(latest: nil, mint_permitted: false, **rest) = super
+                              :mint_permitted, :mint_request) do
+          def initialize(latest: nil, mint_permitted: false, mint_request: nil, **rest) = super
 
           # @return [String] the name of the domain being checked
           def domain_name = bluebook.name
@@ -15,9 +16,15 @@ module Hecks
           # @return [Array<Bluebook::Aggregate>] the aggregates of the bluebook being checked
           def aggregates = bluebook.aggregates
 
+          # @return [Array<Object>] the translation edges the registry loaded
+          def translations = registry.translations
+
           # @return [Array<Hash>] the eras the open lineage holds, oldest first
           def held_eras = lineage.eras
 
+          # @return [Integer] the ledger watermark now: the journal's highest ordinal
+          def watermark = lineage.last_ordinal
+
           # @return [Integer] the ordinal of the era a mint would create
           def ordinal = latest[:ordinal] + 1
 
@@ -41,6 +48,19 @@ module Hecks
           # @param ordinal [Integer] the superseding era
           # @return [Integer] `ordinal`
           def record_superseded(ordinal) = registry.superseded_eras[domain_name] = ordinal
+
+          # Records that this boot's shape is held by no era, with the latest held era it reads.
+          #
+          # @param ordinal [Integer] the latest held era
+          # @return [Integer] `ordinal`
+          def record_unminted(ordinal) = registry.unminted_eras[domain_name] = ordinal
+
+          # Records that this boot's shape is one recorded move or edge ahead of the latest
+          # held era.
+          #
+          # @param ordinal [Integer] the latest held era the move leaves
+          # @return [Integer] `ordinal`
+          def record_behind(ordinal) = registry.behind_eras[domain_name] = ordinal
         end
       end
     end

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/coverage_check.rb

@@ -111,9 +111,11 @@ module Hecks
 
           # The aggregate's head as the chain's last step receives it.
           def translated_before(lineage, aggregate, ordinal, chain)
+            split = lineage.split_latest(aggregate, chain)
+            return split if split
             return lineage.ancestor_latest(aggregate, ordinal, chain) unless chain.size > 1
 
-            lineage.translated_latest(aggregate, ordinal, chain[0..-2])
+            lineage.received_latest(aggregate, ordinal, chain)
           end
         end
       end