hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,68 @@
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "../../../../ports/persistence/plugins/era/projected_bluebook"
+require_relative "../../../../runtime/errors"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # What a held era is: the storage shape its mint recorded, and the hash of that shape.
+        #
+        # Held text is kept for audit and decides nothing. An era minted without a stored shape is
+        # read from its held text only when that text is the whole domain, which it is when it
+        # hashes to the era's stored hash; otherwise the era is refused by name. LineageManager
+        # extends it, so each method is called on LineageManager.
+        module HeldEra
+          # @param era [Hash] an era as `Lineage#eras` answers it: `projection` when its mint
+          #   recorded one, `hash` once it is named, and `held_text`
+          # @return [Hash] the storage shape the era holds
+          # @raise [Runtime::WiringError] naming the era, when it stores no shape and its held text
+          #   does not hash to its stored hash
+          def held_shape(era) = era[:projection] || verified_text_shape(era) || refuse_unshaped!(era)
+
+          # The held era as a bluebook view over its storage shape, for a diff, the additive rule or
+          # the coverage check.
+          #
+          # @param era [Hash] an era as `Lineage#eras` answers it
+          # @return [Runtime::ProjectedBluebook]
+          # @raise [Runtime::WiringError] as `held_shape`
+          def held_bluebook(era) = Runtime::ProjectedBluebook.new(held_shape(era))
+
+          # The era's hash: the one it stores once named, else the hash of the shape it holds.
+          #
+          # @param era [Hash] an era as `Lineage#eras` answers it
+          # @return [String] 64 lowercase hex characters
+          def held_hash(era) = era[:hash] || held_bluebook(era).mint_hash
+
+          # The shape an era's held text declares, when the text hashes to the era's stored hash and
+          # so is the whole domain the era was minted from; nil otherwise.
+          #
+          # @param era [Hash] an era with no stored shape
+          # @return [Hash, nil]
+          def verified_text_shape(era)
+            return unless era[:hash] && era[:held_text]
+
+            declared = shadow(era[:held_text])
+            Runtime::StorageShape.project(declared) if declared && Runtime::StorageShape.mint_hash(declared) == era[:hash]
+          rescue StandardError, SyntaxError
+            nil
+          end
+
+          # @raise [Runtime::WiringError] always, naming the era and why its shape is unknown
+          def refuse_unshaped!(era)
+            raise Runtime::WiringError,
+                  "era #{era[:ordinal]} (#{era[:label] || "unnamed"}) stores no storage shape, and its held " \
+                  "text #{unverified_reason(era)}, so it is not the whole domain the era was minted from"
+          end
+
+          # @return [String] why an era's held text cannot stand in for its missing shape
+          def unverified_reason(era)
+            return "has no stored hash to check it against" unless era[:hash]
+
+            "does not hash to its stored hash"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "../../../../naming"
+require_relative "../../../../ports/persistence/plugins/era/translation/additive_shape"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The change between the storage shape a disposable ledger holds and the shape it boots
+        # with, aggregate by aggregate. `added` names aggregates the held shape did not have,
+        # `widened` those that only gained optional attributes, and `replaced` those whose stored
+        # rows do not fit the booting shape: removed, or with an attribute renamed, dropped,
+        # retyped, switched between list and scalar, or a changed identity or lifecycle field. It
+        # reads and writes nothing.
+        LedgerChange = Data.define(:added, :widened, :replaced) do
+          # @param held_projection [Hash] the held era's storage shape, as `StorageShape.project`
+          #   answers it
+          # @param bluebook [Bluebook::Declaration] the bluebook booting now
+          # @return [LedgerChange]
+          def self.between(held_projection, bluebook)
+            held = by_name(held_projection)
+            current = by_name(Runtime::StorageShape.project(bluebook))
+            widened, broken = changed_in_both(held, current).partition do |name|
+              widened?(held[name], current[name], bluebook.aggregate(name))
+            end
+            new(added: missing(held, current), widened: widened, replaced: broken + missing(current, held))
+          end
+
+          # @return [Hash{String => Hash}] each projected aggregate by its name
+          def self.by_name(projection) = projection.fetch("aggregates", []).to_h { |aggregate| [aggregate["name"], aggregate] }
+
+          # @return [Array<String>] the aggregates `to` has and `from` does not
+          def self.missing(from, to) = to.keys - from.keys
+
+          # @return [Array<String>] the aggregates both shapes have, whose shapes differ
+          def self.changed_in_both(held, current) = (held.keys & current.keys).reject { |name| held[name] == current[name] }
+
+          # Whether an aggregate kept its identity, lifecycle field and every attribute as it was
+          # held, list or scalar included, and gained only attributes it declares optional
+          # (`Translation::AdditiveShape`). An attribute that became required is not seen: the
+          # held projection does not record `optional`.
+          #
+          # @return [Boolean]
+          def self.widened?(held, current, aggregate)
+            Translation::AdditiveShape.widened?(held, current, optional: Translation::AdditiveShape.optional_in(aggregate))
+          end
+          private_class_method :by_name, :changed_in_both, :widened?, :missing
+
+          # @return [Boolean] whether the held shape and the booting shape differ at all
+          def changed? = !(added.empty? && widened.empty? && replaced.empty?)
+
+          # The storage name of a replaced aggregate: the booting bluebook's own, else the name the
+          # held shape gave it, snake-cased the way an aggregate names its storage.
+          #
+          # @param bluebook [Bluebook::Declaration] the bluebook booting now
+          # @param name [String] a name from `replaced`
+          # @return [String]
+          def storage_name(bluebook, name) = bluebook.aggregate(name)&.storage_name || Naming.snake(name)
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,6 @@
 require_relative "../lineage"
-require_relative "../../../../../../runtime/registry"
-require_relative "../../translation/audit"
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/translation/audit"
 
 module Hecks
   module Adapters
@@ -35,7 +35,7 @@ module Hecks
           def merge_chain(registry, bluebook, held)
             raise Runtime::WiringError, "nothing to merge — #{bluebook.name} stands at era 1" if held.size < 2
 
-            edge_chain(registry, bluebook, held[0..-2], held.last[:label])
+            edge_chain(registry, bluebook, held[0..-2], held.last[:label], target: held.last)
           end
 
           # The audit the merge runs over the merged heads, answering every violation found.

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

@@ -0,0 +1,163 @@
+require_relative "../../../../ports/persistence/plugins/era/translation/implicit_edge"
+require_relative "../../../../ports/persistence/plugins/era/translation/scaffold"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "../../../../shape_ledger"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The decision a mint and a rehearsal both make: which translation edge leads the held era
+        # to the current shape, and whether a mint would go ahead on it. It reads only what its
+        # caller hands it and writes nothing, so the same inputs reach the same verdict on either
+        # path.
+        module MintDecision
+          # The implicit moves the framework keeps beside its shape ledger. A bluebook the framework
+          # holds, such as QualityControl, has its moves recorded here, not beside its own files.
+          FRAMEWORK_MOVES = File.join(File.expand_path("../../../../hecks", __dir__),
+                                      ShapeLedger::IMPLICIT_FILE).freeze
+
+          # What a decision concludes. `verdict` is `would_mint`, `needs_edge` (the change needs
+          # a rule) or `refused`; `reason` names why it is not `would_mint`; `edge` is the edge a
+          # mint would use and is nil unless `would_mint`; `source` is `file` or `implicit`; `edges`
+          # lists the edges that lead the held era to the current shape; `diff` is the shape diff;
+          # `watermark` is the one decided at.
+          Verdict = Data.define(:verdict, :reason, :edge, :edges, :source, :diff, :watermark)
+
+          module_function
+
+          # @param held [Array<Hash>] the held eras, oldest first; the last is the era a mint
+          #   leaves.
+          #   Each carries `label` and `declaration`, the storage shape it holds as a bluebook view
+          #   (see `held_for_decision`)
+          # @param bluebook [Bluebook::Declaration] the current bluebook
+          # @param edge_source [Hash] `translations`, the loaded edges, and `recorded`, the recorded
+          #   implicit moves as `[from, to]` pairs (see `recorded_moves`)
+          # @param watermark [Integer] the ledger watermark the decision reads
+          # @param rows [Array<String>] the refusals an audit ran over the decided edge; empty when
+          #   none, or when no audit has run yet
+          # @return [Verdict]
+          def decide(held:, bluebook:, edge_source:, watermark:, rows:)
+            latest = held.last
+            edges = leading(edge_source[:translations], bluebook, latest[:label])
+            found = if edges.empty?
+                      implicit(latest, bluebook, edge_source[:recorded], watermark)
+                    else
+                      written(edges, latest, bluebook, watermark)
+                    end
+            rows.empty? ? found : audit_refusal(found)
+          end
+
+          # The decision for the era a mint would leave, reading the held era's stored shape here,
+          # so a caller holding only the era's record reaches the same verdict as a mint does.
+          #
+          # @param latest [Hash] the held era, as `Lineage#eras` answers it
+          # @param bluebook [Bluebook::Declaration] the current bluebook
+          # @param translations [Array<Object>] the edges the registry loaded
+          # @param directory [String, nil] the domain's bluebook directory
+          # @param watermark [Integer] the ledger watermark the decision reads
+          # @return [Verdict]
+          def decide_latest(latest, bluebook:, translations:, directory:, watermark:)
+            decide(held: [held_for_decision(latest)], bluebook: bluebook, watermark: watermark, rows: [],
+                   edge_source: { translations: translations, recorded: recorded_moves(bluebook.name, directory) })
+          end
+
+          # A held era as the decision reads it: with `declaration`, the storage shape it holds as a
+          # bluebook view (LineageManager::HeldEra). Its held text is not read.
+          #
+          # @param era [Hash] an era as `Lineage#eras` answers it
+          # @return [Hash] the era with `declaration`, a `Runtime::ProjectedBluebook`
+          # @raise [Runtime::WiringError] naming the era, when its shape cannot be known
+          def held_for_decision(era) = era.merge(declaration: LineageManager.held_bluebook(era))
+
+          # The implicit moves a domain has recorded: beside its own bluebooks, when a directory is
+          # given, and in the framework's record. This is the only read the decision's inputs need.
+          #
+          # @param domain [String] the bluebook name the moves are recorded under
+          # @param directory [String, nil] the domain's bluebook directory
+          # @return [Array<Array(String, String)>] each recorded move as `[from, to]`
+          def recorded_moves(domain, directory)
+            paths = [directory && File.join(directory, ShapeLedger::IMPLICIT_FILE), FRAMEWORK_MOVES].compact
+            paths.flat_map { |path| ShapeLedger.pairs_of(ShapeLedger.implicit_moves(path).fetch(domain, [])) }
+          end
+
+          # Whether the move from the held era is breaking and nothing covers it: the decision needs
+          # an edge, and the change is not provably additive. A move a mint would go ahead on, or a
+          # decision already refused for another reason, is not this. An edge from the held shape
+          # covers it even when the held era has not been named yet.
+          #
+          # @return [Boolean]
+          def breaking?(latest, bluebook, verdict, translations)
+            return false unless verdict.verdict == "needs_edge"
+            return false unless leading(translations, bluebook, held_label_of(latest)).empty?
+
+            !additive?(verdict.diff, held_for_decision(latest), bluebook)
+          end
+
+          # @return [String] the stored label of a held era, or the one its shape would be named
+          def held_label_of(era)
+            era[:label] || LineageManager.held_hash(era)[0, Runtime::StorageShape::LABEL_LENGTH]
+          end
+
+          # The shape label a storage shape of this bluebook carries.
+          #
+          # @return [String]
+          def label_of(bluebook) = Runtime::StorageShape.mint_hash(bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+
+          # The edges the domain loads that lead the held era straight to the current shape. An edge
+          # from the held era to any other shape plays no part: the translation is from the held
+          # shape to the current one, so other edges neither fork the decision nor make it stale.
+          #
+          # @return [Array<Object>] the edges from `from` to the bluebook's current label
+          def leading(translations, bluebook, from)
+            to = label_of(bluebook)
+            translations.select { |edge| edge.domain == bluebook.name && edge.from == from && edge.to == to }
+          end
+
+          # The implicit empty edge: the recorded moves must reach the shape from the held label,
+          # and the change must qualify as additive by `Translation::ImplicitEdge.qualifies?`.
+          def implicit(latest, bluebook, recorded, watermark)
+            diff = diff_of(latest, bluebook)
+            to = label_of(bluebook)
+            return verdict_of("needs_edge", diff, watermark, reason: :unrecorded) unless reachable?(latest, to, recorded)
+            return verdict_of("needs_edge", diff, watermark, reason: :non_qualifying) unless additive?(diff, latest, bluebook)
+
+            edge = Translation::ImplicitEdge.new(domain: bluebook.name, from: latest[:label], to: to)
+            verdict_of("would_mint", diff, watermark, edge: edge, edges: [], source: "implicit")
+          end
+
+          # @return [Hash] the scaffold's diff of the held era against the current bluebook
+          def diff_of(latest, bluebook) = Translation::Scaffold.diff(latest[:declaration], bluebook)
+
+          # @return [Boolean] whether the recorded moves chain from the held label to `to`
+          def reachable?(latest, to, recorded) = ShapeLedger.reachable?(latest[:label], to, recorded)
+
+          # @return [Boolean] whether the change qualifies as additive by the implicit edge's rule
+          def additive?(diff, latest, bluebook) = Translation::ImplicitEdge.qualifies?(diff, latest[:declaration], bluebook)
+
+          # A written edge from the held shape to the current one leads on. Two files declaring that
+          # same pair disagree about one translation, so neither is taken.
+          def written(edges, latest, bluebook, watermark)
+            diff = diff_of(latest, bluebook)
+            return verdict_of("refused", diff, watermark, reason: :duplicate_edge, edges: edges) if edges.size > 1
+
+            verdict_of("would_mint", diff, watermark, edge: edges.first, edges: edges, source: "file")
+          end
+
+          # An audit's refusals turn a would_mint into a refusal that names the audit.
+          def audit_refusal(found)
+            return found unless found.verdict == "would_mint"
+
+            verdict_of("refused", found.diff, found.watermark, reason: :audit, edges: found.edges)
+          end
+
+          # @return [Verdict] a verdict of `kind`, with the fields it carries and none it does not
+          def verdict_of(kind, diff, watermark, **attributes)
+            Verdict.new(verdict: kind, reason: nil, edge: nil, edges: [], source: nil, diff: diff,
+                        watermark: watermark, **attributes)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The request a mint carries into the era check: whether the mint was confirmed, the verdict
+        # the rehearsal of that same era reached, and the ledger watermark the rehearsal read. Only the
+        # Maintenance mint path builds one; a boot has none, so a boot that would mint refuses.
+        MintRequest = Data.define(:confirm, :verdict, :watermark) do
+          # Reads the request out of a settings hash, spelled with symbol or string keys.
+          #
+          # @param settings [Hash] the settings the era check was booted with
+          # @return [MintRequest, nil] the request, or nil when the settings carry none
+          def self.from(settings)
+            raw = PostgresEra.setting(settings, :mint_request)
+            return nil if raw.nil?
+
+            raw = raw.transform_keys(&:to_sym)
+            new(confirm: raw[:confirm] == true, verdict: raw[:verdict].to_s, watermark: raw[:watermark].to_i)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+require_relative "../../../../runtime/registry"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "../../../../ports/persistence/plugins/era/translation/audit"
+require_relative "../../../../ports/persistence/plugins/era/translation/scaffold"
+require_relative "context"
+require_relative "refusals"
+require_relative "mint_decision"
+require_relative "era_resolution"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # Names the source era, resolves its one outgoing translation edge, and mints the
+        # next era once coverage and the audited chain check out.
+        module Minter
+          include Refusals
+
+          # Mints the next era for a drifted shape in one transaction.
+          #
+          # @param context [Context] the era check so far; `latest` is the latest held era, named
+          #   here if it has no name yet
+          # @return [Integer] the ordinal of the era minted
+          # @raise [Runtime::WiringError] if a held era already holds the shape, or the edge, its
+          #   coverage or its audit refuses
+          def mint!(context)
+            refuse_held_shape!(context)
+            refuse_unrehearsed_mint!(context)
+            ensure_named!(context.lineage, context.latest)
+            context = context.with(latest: context.held_eras.last)
+            decided_at = context.watermark
+            edge = verified_edge!(context)
+            refuse_unpermitted_mint!(context) unless context.mint_permitted
+            chain = audited_chain!(context, edge)
+            refuse_moved_watermark!(context, decided_at)
+            commit_era!(context, chain, edge)
+          end
+
+          # The edge a mint leaves the held era by, as `MintDecision` decides it. A refusal the
+          # decision names is raised by name; a change that needs a rule refuses toward the
+          # scaffold.
+          def resolve_edge!(context)
+            verdict = decide!(context)
+            return verdict.edge if verdict.verdict == "would_mint"
+            return refuse_toward_the_scaffold!(context) if verdict.verdict == "needs_edge"
+
+            refuse_refused_verdict!(context, verdict)
+          end
+
+          # Diffs the held era against the current shape and writes the edge file —
+          # confident rules inline, ambiguities as parse-refusing `unresolved` lines.
+          def scaffold!(_registry, bluebook, lineage, latest, directory)
+            ensure_named!(lineage, latest)
+            latest = lineage.eras.last
+            label = Runtime::StorageShape.mint_hash(bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+            diffed = Translation::Scaffold.diff(held_bluebook(latest), bluebook)
+            edge = Translation::Scaffold::Edge.new(
+              domain: bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
+              label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
+            )
+            Translation::Scaffold.write!(directory, edge)
+          end
+
+          # Mints a name for an era that has none yet, leaving an already-named era untouched.
+          #
+          # Era names are minted once, the moment an edge first needs to leave that era.
+          def ensure_named!(lineage, era)
+            return if era[:hash]
+
+            hash = held_hash(era)
+            lineage.mint_name!(era[:ordinal], hash, hash[0, Runtime::StorageShape::LABEL_LENGTH])
+          end
+
+          private
+
+          # Refuses a mint of a shape a held era already holds, by the match the boot resolves with.
+          def refuse_held_shape!(context)
+            held = EraResolution.matching_era(context.held_eras, context.bluebook) or return
+
+            raise Runtime::WiringError,
+                  "cannot mint #{context.domain_name}: era #{held[:ordinal]} already holds the current shape"
+          end
+
+          # The verdict `MintDecision` reaches for the held era the mint leaves, read at the
+          # watermark the context holds now.
+          def decide!(context)
+            MintDecision.decide(held: [MintDecision.held_for_decision(context.latest)], bluebook: context.bluebook,
+                                edge_source: edge_source_of(context), watermark: context.watermark, rows: [])
+          end
+
+          def edge_source_of(context)
+            registry = context.registry
+            { translations: registry.translations,
+              recorded:     MintDecision.recorded_moves(context.domain_name, context.directory) }
+          end
+
+          # The refusal a decided edge stands for: two files declaring the one translation.
+          def refuse_refused_verdict!(context, verdict) = refuse_duplicate_edges!(context, verdict.edges)
+
+          # The edge chain to the current shape, after its audit passes.
+          def audited_chain!(context, edge)
+            chain = edge_chain(context.registry, context.bluebook, context.held_eras, context.label,
+                               target: minted_record(edge))
+            audit!(context.bluebook, context.lineage, chain, context.ordinal, edge)
+            chain
+          end
+
+          # The edge leaving the held era, once resolved and found to cover the diff.
+          def verified_edge!(context)
+            edge = resolve_edge!(context)
+            check_coverage!(context.registry, context.bluebook, held_bluebook(context.latest), edge)
+            edge
+          end
+
+          # The journal record of the era a mint reaches, when the edge is implicit; nil when a
+          # written edge file leads there.
+          #
+          # @return [Hash, nil] the era record `edge_chain` reads as its last step
+          def minted_record(edge)
+            edge.is_a?(Translation::ImplicitEdge) ? edge.record : nil
+          end
+
+          # @return [Hash, nil] the `edge` column of the minted era: the implicit marker, or nil
+          def implicit_record(edge)
+            edge.is_a?(Translation::ImplicitEdge) ? Translation::ImplicitEdge::RECORD : nil
+          end
+
+          def commit_era!(context, chain, edge)
+            hash = context.shape_hash
+            bluebook = context.bluebook
+            context.lineage.mint_era!(
+              ordinal: context.ordinal, hash: hash, label: hash[0, Runtime::StorageShape::LABEL_LENGTH],
+              held_text: context.current_text, aggregates: bluebook.aggregates, edges: chain,
+              role: context.role, projection: Runtime::StorageShape.project(context.bluebook),
+              edge: implicit_record(edge)
+            )
+            context.ordinal
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The refusals a mint raises: toward the scaffold when no edge exists, and for a forked or
+        # stale edge. Each is built from the era check's `Context`.
+        module Refusals
+          # Refuses toward the authoring loop, or, under HECKS_SCAFFOLD=1, scaffolds the
+          # missing edge first and names the file it wrote.
+          def refuse_toward_the_scaffold!(context)
+            if ENV["HECKS_SCAFFOLD"] == "1" && context.directory
+              path = scaffold!(context.registry, context.bluebook, context.lineage, context.latest, context.directory)
+              raise era_refusal(context, "the shape changed (era #{context.ordinal}) — wrote #{path}; " \
+                                         "review it (resolve every unresolved), check it with hecks audit_translation, " \
+                                         "then boot again", minting: false)
+            end
+
+            raise era_refusal(context, "the shape changed (era #{context.ordinal}) and no translation edge " \
+                                       "covers it — run hecks scaffold_translation to write the edge, " \
+                                       "check it with hecks audit_translation, then boot again", minting: false)
+          end
+
+          # Refuses to move a database to a newer shape from a copy that may not mint: minting
+          # migrates what every other checkout of the domain reads, and an older checkout is then
+          # refused until it catches up.
+          def refuse_unpermitted_mint!(context)
+            latest = context.latest
+            raise era_refusal(context, "a translation edge covers the move from era #{latest[:ordinal]} " \
+                                       "(#{latest[:label]}) to #{context.label}, but this copy may not mint: " \
+                                       "it would migrate a database other checkouts read. Mint from the copy " \
+                                       "that owns the database, by declaring `mint_eras true` in the " \
+                                       "persisted_by block of its world", minting: false)
+          end
+
+          # Refuses a mint that the rehearsal does not back: not confirmed, not a would_mint verdict, or a
+          # ledger watermark that moved since the rehearsal read it.
+          def refuse_unrehearsed_mint!(context)
+            request = context.mint_request
+            raise era_refusal(context, "the mint was not confirmed") unless request.confirm
+            unless request.verdict == "would_mint"
+              raise era_refusal(context, "the rehearsal's verdict was #{request.verdict}, not would_mint; " \
+                                         "rehearse again")
+            end
+
+            refuse_moved_watermark!(context, request.watermark)
+          end
+
+          private
+
+          def refuse_moved_watermark!(context, watermark)
+            current = context.watermark
+            return if current == watermark
+
+            raise era_refusal(context, "the ledger watermark moved from #{watermark} to #{current} since the " \
+                                       "rehearsal; rehearse again")
+          end
+
+          def refuse_duplicate_edges!(context, edges)
+            latest = context.latest
+            raise era_refusal(context, "#{edges.size} translation edges lead era #{latest[:ordinal]} " \
+                                       "(#{latest[:label]}) to the current shape #{context.label}; keep one",
+                              minting: false)
+          end
+
+          # Builds the refusal; a mint's own refusals say "cannot mint era N of X", the
+          # edge-resolution ones say "cannot boot X".
+          def era_refusal(context, text, minting: true)
+            name = context.domain_name
+            lead = minting ? "cannot mint era #{context.ordinal} of #{name}" : "cannot boot #{name}"
+            Runtime::WiringError.new("#{lead}: #{text}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,8 +4,9 @@ require_relative "lineage_manager/era_resolver"
 require_relative "lineage_manager/minter"
 require_relative "lineage_manager/merge_coordinator"
 require_relative "lineage_manager/coverage_check"
-require_relative "../era_guard"
-require_relative "../../../../../runtime/registry"
+require_relative "lineage_manager/held_era"
+require_relative "../../../ports/persistence/plugins/era/era_guard"
+require_relative "../../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -17,6 +18,7 @@ module Hecks
         extend Minter
         extend MergeCoordinator
         extend CoverageCheck
+        extend HeldEra
 
         module_function
 
@@ -24,34 +26,66 @@ module Hecks
         # Each mint required its own edge, so a gap in the chain means a deleted file.
         #
         # @param registry [Runtime::Registry] the registry whose loaded `translations` are searched
-        # @param bluebook [Bluebook::Chapter] the domain; only edges for its name count
+        # @param bluebook [Bluebook::Declaration] the domain; only edges for its name count
         # @param eras [Array<Hash>] the ancestor eras in order, as `Lineage#eras` returns them
         # @param current_label [String] the shape label the last step must lead to
+        # @param target [Hash, nil] the era record the last step reaches when it is not in `eras`
+        #   (the held era of a settled chain, or the era a mint is about to write)
         # @return [Array<Hash>] one `{ translation: edge }` per step, in mint order
-        # @raise [Runtime::WiringError] if no loaded translation leads one label to the next
-        def edge_chain(registry, bluebook, eras, current_label)
+        # @raise [Runtime::WiringError] if no loaded translation or journal record leads a label
+        #   to the next one
+        def edge_chain(registry, bluebook, eras, current_label, target: nil)
           labels = eras.map { |era| era[:label] } + [current_label]
-          labels.each_cons(2).with_index.map do |(from, to), index|
-            step = edge_between(registry, bluebook, from, to)
+          labels.each_cons(2).with_index.filter_map do |(from, to), index|
+            next if same_shape?(from, to)
+
+            step = edge_between(registry, bluebook, from, to) ||
+                   recorded_edge(bluebook, from, to, eras[index + 1] || target)
             refuse_broken_chain!(bluebook, index, from, to) unless step
             { translation: step }
           end
         end
 
-        # Finds the loaded translation that leads one shape label to the next.
+        # Whether two shape labels name the same shape. A same-shape step is current, not a change,
+        # so it needs no edge and `edge_chain` skips it.
+        #
+        # @param from [String] the shape label the step leaves
+        # @param to [String] the shape label the step reaches
+        # @return [Boolean] true when both labels are the same shape
+        def same_shape?(from, to) = from == to
+
+        # The implicit edge a journal record names for the step that reached its era, or nil.
+        #
+        # @param bluebook [Bluebook::Declaration] the domain the edge belongs to
+        # @param from [String] the shape label the step leaves
+        # @param to [String] the shape label the step reaches
+        # @param record [Hash, nil] the era record the step reaches
+        # @return [Translation::ImplicitEdge, nil]
+        def recorded_edge(bluebook, from, to, record)
+          return unless record && record[:label] == to && record[:edge] == Translation::ImplicitEdge::RECORD
+
+          Translation::ImplicitEdge.new(domain: bluebook.name, from: from, to: to)
+        end
+
+        # Finds the loaded translation that leads one shape label to the next. A same-shape pair
+        # has no edge to find: it answers nil without searching, and `edge_chain` treats it as
+        # current.
         #
         # @param registry [Runtime::Registry] the registry whose `translations` are searched
-        # @param bluebook [Bluebook::Chapter] the domain; only edges for its name count
+        # @param bluebook [Bluebook::Declaration] the domain; only edges for its name count
         # @param from [String] the shape label the edge leaves
         # @param to [String] the shape label the edge reaches
-        # @return [Bluebook::Translation, nil] the edge, or nil when none is loaded
+        # @return [Bluebook::Translation, nil] the edge, or nil when none is loaded, or the shapes
+        #   match
         def edge_between(registry, bluebook, from, to)
+          return nil if same_shape?(from, to)
+
           registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == to }
         end
 
         # Refuses a boot whose edge chain has a gap.
         #
-        # @param bluebook [Bluebook::Chapter] the domain, named in the message
+        # @param bluebook [Bluebook::Declaration] the domain, named in the message
         # @param index [Integer] the zero-based step with no translation
         # @param from [String] the shape label the missing edge would leave
         # @param to [String] the shape label the missing edge would reach
@@ -67,7 +101,7 @@ module Hecks
         # The predicate extractor reads source from disk, so the text goes through a scratch file.
         #
         # @param source [String] bluebook source text from `hecks_eras.held_text`
-        # @return [Bluebook::Chapter, nil] the first bluebook the text declares
+        # @return [Bluebook::Declaration, nil] the first bluebook the text declares
         # @raise [Bluebook::DSL::Malformed] if the text parses under neither grammar
         def shadow(source)
           file = Tempfile.new(["hecks-era-", ".bluebook"])