hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,119 @@
+require_relative "../lineage"
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "ledger_change"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The era check of a world that declares `disposable_ledger true` in its PostgresEra
+        # `persisted_by` block: a tooling ledger whose rows are worth keeping, not worth an era.
+        #
+        # Its boot never refuses as unminted or superseded and needs no edge, mint or rehearsal. It
+        # holds the first era itself, and on a shape change it re-holds the latest era at the
+        # booting shape: an added aggregate gets a head, a widened one keeps its rows as they are,
+        # and a replaced one has its rows moved to a dated archive table and starts empty. It names
+        # each archive on stderr. A world without the setting never reaches this module.
+        module DisposableLedger
+          module_function
+
+          # Whether a world's persistence settings declare the ledger disposable, spelled as a
+          # boolean or as the word. Unset is false, so every other world keeps its era guard.
+          #
+          # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+          # @return [Boolean]
+          def declared?(settings) = [true, "true"].include?(PostgresEra.setting(settings, :disposable_ledger, default: false))
+
+          # Brings the ledger to the booting shape and records the era the boot reads.
+          #
+          # @param registry [Runtime::Registry] the booting registry; `resolved_eras` is set
+          # @param bluebook [Bluebook::Declaration] the bluebook booting now
+          # @param current_text [String] its source text, held as the era's text
+          # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+          # @return [nil] a disposable ledger's boot mints no era
+          # @raise [Runtime::WiringError] if the connection is refused or its role is unfenced
+          #
+          # The world's `stored_as` names are applied first: the boot gates run before the wiring
+          # check that applies them, and a re-hold provisions heads under the storage names.
+          def check!(registry:, bluebook:, current_text:, settings:)
+            registry.apply_world_names!
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: true)
+            lineage = open_lineage(db, bluebook, settings)
+            registry.resolved_eras[bluebook.name] = locked(db, bluebook.name) { reconcile!(lineage, bluebook, current_text) }
+            grant!(lineage, bluebook, settings, registry.resolved_eras[bluebook.name])
+            nil
+          ensure
+            db&.close
+          end
+
+          # The ordinal the ledger holds once it is at the booting shape.
+          #
+          # @return [Integer]
+          def reconcile!(lineage, bluebook, text)
+            latest = lineage.eras.last
+            return hold_first!(lineage, bluebook, text) unless latest
+
+            change = LedgerChange.between(held_projection(latest), bluebook)
+            apply!(lineage, bluebook, text, change, latest[:ordinal]) if change.changed?
+            latest[:ordinal]
+          end
+
+          # Archives every replaced aggregate, gives each added or replaced one a head over the
+          # latest era alone, provisions the read side of every aggregate, and re-holds the era.
+          def apply!(lineage, bluebook, text, change, ordinal)
+            stamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+            change.replaced.each { |name| archive!(lineage, bluebook, change.storage_name(bluebook, name), stamp) }
+            fresh_heads!(lineage, bluebook, change, ordinal)
+            bluebook.aggregates.each { |aggregate| lineage.provision_read_side!(aggregate, ordinal) }
+            lineage.rehold!(ordinal, text, Runtime::StorageShape.project(bluebook), Runtime::StorageShape.mint_hash(bluebook))
+          end
+
+          # Gives every added or replaced aggregate the booting bluebook declares a head over the
+          # latest era alone: none of its rows are in an earlier era.
+          def fresh_heads!(lineage, bluebook, change, ordinal)
+            (change.added + change.replaced).filter_map { |name| bluebook.aggregate(name) }
+                                            .each { |aggregate| lineage.fresh_head!(aggregate.storage_name, ordinal) }
+          end
+
+          def archive!(lineage, bluebook, storage_name, stamp)
+            archive, count = lineage.archive_aggregate!(storage_name, stamp)
+            warn "[hecks] #{bluebook.name}: the shape of #{storage_name} changed in a way its rows do not fit; " \
+                 "archived #{count} journal row#{"s" unless count == 1} to #{archive} and started it empty " \
+                 "(disposable_ledger)"
+          end
+
+          def hold_first!(lineage, bluebook, text)
+            lineage.hold_first!(text, projection: Runtime::StorageShape.project(bluebook))
+            lineage.provision_first_era!(bluebook.aggregates)
+            1
+          end
+
+          # The storage shape the latest era holds: the projection its hold recorded, else the
+          # shape its held text declares.
+          def held_projection(era) = era[:projection] || Runtime::StorageShape.project(LineageManager.shadow(era[:held_text]))
+
+          def open_lineage(db, bluebook, settings)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
+            lineage.ensure_base!
+            lineage
+          end
+
+          # Holds the domain's era lock, the one a mint takes, for the whole reconcile, so two boots
+          # of a changed shape archive once.
+          def locked(db, domain)
+            db.exec_params("SELECT pg_advisory_lock(hashtext('hecks_eras:' || $1))", [domain])
+            yield
+          ensure
+            db.exec_params("SELECT pg_advisory_unlock(hashtext('hecks_eras:' || $1))", [domain])
+          end
+
+          def grant!(lineage, bluebook, settings, ordinal)
+            role = PostgresEra.setting(settings, :role)
+            lineage.grant_role!(role.to_s, aggregates: bluebook.aggregates, era: ordinal) unless role.to_s.empty?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+require_relative "../../../../ports/persistence/plugins/era/storage_shape"
+require_relative "mint_decision"
+require_relative "../lineage"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      module LineageManager
+        # The one answer to which era a bluebook's shape resolves to, given the eras its database
+        # holds: the boot records it, the boot status reports it, and the rehearsal and the mint
+        # read the held era and the match from it. It writes nothing. A status is one of:
+        #
+        # - `unheld`: the database holds no era for the bluebook.
+        # - `current`: the latest held era holds the current shape.
+        # - `superseded`: an older held era holds the current shape; a later one superseded it.
+        # - `behind`: no era holds the current shape, and a mint from the latest one would go ahead
+        #   on its translation edge or recorded implicit move.
+        # - `unminted`: no era holds the current shape, and no mint from the latest one would go
+        #   ahead.
+        module EraResolution
+          # What a resolution concludes. `resolved` is the era the boot reads (nil when `unheld`),
+          # `latest` the latest held era, `verdict` the mint decision from the latest era (nil
+          # unless the shape is `behind` or `unminted`), and `held_count` how many eras are held.
+          Answer = Data.define(:status, :resolved, :latest, :current_label, :verdict, :held_count,
+                               :breaking) do
+            # @return [Boolean] whether the shape is unminted because the move is breaking and no
+            #   translation edge covers it, so a boot reads nothing under it and refuses
+            def breaking? = breaking == true
+
+            # @return [Boolean] whether a held era holds the current shape
+            def matched? = %w[current superseded].include?(status)
+
+            # The label of the era the boot reads. An era no edge has left yet has no stored name,
+            # so its label is worked out in memory, as its mint would name it; naming is a write,
+            # so a resolution never stores it.
+            #
+            # @return [String, nil] the label; nil when no era is held
+            # @raise [Runtime::WiringError] when an unnamed era stores no shape (`refuse_unshaped!`)
+            def held_label
+              stored = resolved&.fetch(:label, nil)
+              return stored if stored || resolved.nil?
+
+              LineageManager.held_hash(resolved)[0, Runtime::StorageShape::LABEL_LENGTH]
+            end
+
+            # @return [Integer, nil] the ordinal of the era the boot reads
+            def ordinal = resolved&.fetch(:ordinal, nil)
+
+            # @return [String, nil] why the status is what it is; nil for `current`
+            def reason = Reasons.of(self)
+
+            # @return [Boolean] whether a mint from the latest era would go ahead on a recorded
+            #   implicit move rather than a written translation edge
+            def implicit? = verdict&.source == "implicit"
+
+            # @return [String] the mint decision from the latest era and why, as `verdict: reason`
+            def decision = "#{verdict.verdict}: #{verdict.reason}"
+
+            # @return [Hash, nil] the implicit move a `behind` shape would mint on, or nil
+            def move
+              return unless status == "behind" && implicit?
+
+              { "from" => held_label, "to" => current_label }
+            end
+
+            # @return [String, nil] a sentence when the read era's stored hash is not the hash
+            #   of its stored projection (a boot still reads it); nil when they agree or the era
+            #   stores only one of them
+            def warning
+              recomputed = projection_hash
+              return if recomputed.nil? || recomputed == resolved[:hash]
+
+              "era #{ordinal} stores hash #{resolved[:hash][0, 6]} but its stored projection hashes to #{recomputed[0, 6]}"
+            end
+
+            # @return [String, nil] the hash of the read era's stored projection; nil when it stores
+            #   no hash or no projection
+            def projection_hash
+              return unless resolved && resolved[:hash] && resolved[:projection]
+
+              Runtime::ProjectedBluebook.new(resolved[:projection]).mint_hash
+            end
+
+            # @return [Hash] the answer as a status row, string-keyed for a JSON document; `warning`
+            #   appears only when `warning` has something to say
+            def to_row
+              row = { "status" => status, "held" => held_label, "current" => current_label, "ordinal" => ordinal,
+                      "move" => move, "reason" => reason, "source" => "database" }
+              (note = warning) ? row.merge("warning" => note) : row
+            end
+          end
+
+          module_function
+
+          # Resolves the current shape of a bluebook against the eras its database holds.
+          #
+          # @param eras [Array<Hash>] the held eras, oldest first, as `Lineage#eras` answers them
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @param translations [Array<Object>] the translation edges the registry loaded
+          # @param directory [String, nil] the domain's bluebook directory, where moves are recorded
+          # @yieldreturn [Integer] the ledger watermark, read only when no held era matches
+          # @return [Answer]
+          def resolve(eras:, bluebook:, translations:, directory:)
+            facts = { latest: eras.last, current_label: MintDecision.label_of(bluebook), held_count: eras.size }
+            return answer("unheld", nil, facts) if eras.empty?
+
+            matched = matching_era(eras, bluebook)
+            return answer(matched.equal?(eras.last) ? "current" : "superseded", matched, facts) if matched
+
+            unmatched(facts, bluebook, translations, directory, yield)
+          end
+
+          # Resolves a bluebook against the eras its own database holds, over a connection that
+          # can only read: nothing is provisioned, and the session refuses any write.
+          #
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @param settings [Hash] the persistence settings its world declares; needs `database`
+          # @param translations [Array<Object>] the translation edges the registry loaded
+          # @param directory [String, nil] the domain's bluebook directory
+          # @return [Answer]
+          # @raise [Runtime::WiringError] if the connection is refused or a held text fails its
+          #   integrity check
+          def read(bluebook:, settings:, translations:, directory: nil)
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: false)
+            db.exec("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY")
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as, reading: true)
+            resolve(eras: lineage.eras, bluebook: bluebook, translations: translations, directory: directory) do
+              lineage.last_ordinal
+            end
+          ensure
+            db&.close
+          end
+
+          # The held era whose shape is the bluebook's: the latest when it holds it, else the
+          # oldest that does; nil when none holds it.
+          #
+          # @param eras [Array<Hash>] the held eras, oldest first
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @return [Hash, nil] the matching era
+          def matching_era(eras, bluebook)
+            current = Runtime::StorageShape.project(bluebook)
+            [eras.last, *eras].find { |era| held_shape_of(era, bluebook) == current }
+          end
+
+          # An era's storage shape, with a prior name normalized to the bluebook's. Held text is a
+          # frozen record and keeps the prior name; only the in-memory shape is renamed, and only on
+          # an exact match with the declared prior name.
+          #
+          # @param era [Hash] a held era
+          # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+          # @return [Hash] the storage shape the era holds
+          def held_shape_of(era, bluebook)
+            shape = LineageManager.held_shape(era)
+            prior = bluebook.formerly_known_as
+            prior && shape["name"] == prior ? shape.merge("name" => bluebook.name) : shape
+          end
+
+          # @return [Answer] a `behind` or `unminted` answer, by the latest era's mint decision
+          def unmatched(facts, bluebook, translations, directory, watermark)
+            verdict = MintDecision.decide_latest(facts[:latest], bluebook: bluebook, translations: translations,
+                                                                 directory: directory, watermark: watermark)
+            status = verdict.verdict == "would_mint" ? "behind" : "unminted"
+            breaking = MintDecision.breaking?(facts[:latest], bluebook, verdict, translations)
+            answer(status, facts[:latest], facts, verdict, breaking: breaking)
+          end
+
+          # @return [Answer]
+          def answer(status, resolved, facts, verdict = nil, breaking: false)
+            Answer.new(status: status, resolved: resolved, verdict: verdict, breaking: breaking, **facts)
+          end
+
+          # The sentence a status row gives for its status.
+          module Reasons
+            REMEDY = "write an edge (`era.scaffold_translation`) and mint it with the release mint".freeze
+
+            module_function
+
+            # @param answer [Answer] the resolution
+            # @return [String, nil] the reason; nil for `current`
+            def of(answer)
+              case answer.status
+              when "unheld" then "no era is held; the mint entry point holds the first"
+              when "superseded" then superseded(answer)
+              when "behind" then behind(answer)
+              when "unminted" then unminted(answer)
+              end
+            end
+
+            # @return [String]
+            def superseded(answer)
+              "era #{answer.ordinal} holds the current shape #{answer.current_label}; era " \
+                "#{answer.latest[:ordinal]} (#{answer.latest[:label]}) superseded it"
+            end
+
+            # @return [String]
+            def behind(answer)
+              "no era holds #{answer.current_label}; a mint from era #{answer.ordinal} (#{answer.held_label}) " \
+                "would go ahead on its #{answer.implicit? ? "recorded implicit move" : "translation edge"}"
+            end
+
+            # @return [String] the refusal a boot over a breaking move gives
+            def breaking(answer)
+              "no translation edge covers it: #{answer.current_label} is not an additive move from " \
+                "era #{answer.ordinal} (#{answer.held_label}); #{REMEDY}"
+            end
+
+            # @return [String]
+            def unminted(answer)
+              return breaking(answer) if answer.breaking?
+
+              "no era holds #{answer.current_label}; a mint from era #{answer.ordinal} (#{answer.held_label}) " \
+                "is #{answer.decision}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,114 +1,111 @@
 require_relative "../lineage"
 require_relative "../../../../ports/persistence/plugins/era/storage_shape"
 require_relative "context"
+require_relative "mint_request"
+require_relative "mint_decision"
+require_relative "era_resolution"
+require_relative "disposable_ledger"
 require_relative "../../../../indifferent_key"
 
 module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # Boot-time era resolution: first boot holds era 1, a quiet reboot changes nothing,
-        # a superseded shape boots read-only, an unheld shape goes to the minter.
+        # Boot-time era resolution. A boot reads: it reports the era its shape resolves to, and
+        # writes nothing. The mint entry point (a settings `mint_request`) is the only path that
+        # provisions the lineage or mints an era.
         module EraResolver
           # Whether this copy may mint when its world says nothing about it. False, so a copy that
-          # was not told refuses, and only the copy that owns a database moves it.
+          # was not told refuses, and only the copy that owns a database moves it. A mint also needs
+          # the mint entry point's request (`mint_request` in the settings): a boot never mints.
           MINT_BY_DEFAULT = false
 
           # Resolves which era this boot is and records it on the registry.
           #
+          # A boot with no mint request opens its lineage for reading and never provisions, holds,
+          # mints or grants. A boot with a request provisions the lineage first, then mints if the
+          # shape drifted.
+          #
           # @return [Integer, nil] the ordinal minted, or nil when this boot minted nothing
           # @raise [Runtime::WiringError] if the connection is refused, a held text fails its
-          #   integrity check, or the shape is unheld and `mint!` refuses
+          #   integrity check, no era is held, or the shape is unheld and `mint!` refuses
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
-            db = PostgresEra.connect_for(bluebook.name, settings)
-            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
-            # First, before ensure_base!: the earliest point the connection's role is known,
-            # so a superuser connection refuses here by default.
-            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
-            lineage.ensure_base!
-            # key? first, never `||`: a stored `false` must not read as an absent key.
-            role = IndifferentKey.read(settings, :role)
+            # A world that declares its ledger disposable has no era guard: see `DisposableLedger`.
+            return DisposableLedger.check!(registry:, bluebook:, current_text:, settings:) if DisposableLedger.declared?(settings)
+
+            request = MintRequest.from(settings)
+            db = PostgresEra.connect_for(bluebook.name, settings, provision: !request.nil?)
+            lineage = open_lineage(db, bluebook, settings, request)
             resolve_era(Context.new(registry: registry, bluebook: bluebook, current_text: current_text,
-                                    lineage: lineage, role: role, directory: directory,
-                                    mint_permitted: mint_permitted?(settings)))
+                                    lineage: lineage, role: IndifferentKey.read(settings, :role),
+                                    directory: directory, mint_permitted: mint_permitted?(settings),
+                                    mint_request: request))
           ensure
             db&.close
           end
 
           private
 
+          # Opens the lineage: for reading on a boot, and provisioned first on a mint request. Either
+          # refuses, by name, while the domain's history still sits under its former name.
+          def open_lineage(db, bluebook, settings, request)
+            lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as,
+                                                     reading:           request.nil?)
+            # First, before anything else: the earliest point the connection's role is known,
+            # so a superuser connection refuses here by default.
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
+            request ? lineage.ensure_base! : lineage.refuse_pending_rename!
+            lineage
+          end
+
           # Whether the world allows minting, spelled as a boolean or as the word.
           def mint_permitted?(settings)
             [true, "true"].include?(PostgresEra.setting(settings, :mint_eras, default: MINT_BY_DEFAULT))
           end
 
+          # Resolves the boot's shape through `EraResolution`, the answer every era tool reads, and
+          # records it on the registry; a mint request on a shape no era holds mints instead.
           def resolve_era(context)
-            held = context.held_eras
-            return hold_first_era(context) if held.empty?
-
-            resolve_held(context, held)
-          end
-
-          # Some era is held: the latest, a superseded one, or none matches and a new one is minted.
-          def resolve_held(context, held)
-            shapes = held_shapes(context.bluebook, held)
-            latest, latest_shape = shapes.last
-            current_shape = context.current_shape
-            return resolve_latest(context, latest) if latest_shape == current_shape
-
-            matched, = shapes.find { |_, shape| shape == current_shape }
-            return resolve_superseded(context, matched, latest) if matched
-
-            context.record_resolved(mint!(context.with(latest: latest)))
-          end
-
-          def hold_first_era(context)
-            context.lineage.hold_first!(context.current_text, projection: context.current_shape)
-            ensure_first_heads!(context)
-            grant_role!(context, 1)
-            nil
-          end
+            answer = EraResolution.resolve(eras: context.held_eras, bluebook: context.bluebook,
+                                           translations: context.translations, directory: context.directory) do
+              context.watermark
+            end
+            return refuse_unheld!(context) if answer.status == "unheld"
+            return context.record_resolved(mint!(context.with(latest: answer.latest))) if minting?(answer, context)
 
-          # The latest held era is the current shape: nothing to mint.
-          def resolve_latest(context, latest)
-            ensure_first_heads!(context) if latest[:ordinal] == 1
-            grant_role!(context, latest[:ordinal])
-            context.record_resolved(latest[:ordinal])
-            nil
-          end
+            return refuse_breaking!(context, answer) if answer.breaking?
 
-          # A superseded era (an old checkout) may read but not write: never advance_era!
-          # here, since the fence is already past this ordinal.
-          def resolve_superseded(context, matched, latest)
-            grant_role!(context, matched[:ordinal])
-            context.record_resolved(matched[:ordinal])
-            # The adapter refuses appends on this, even where the RLS fence cannot bind.
-            context.record_superseded(latest[:ordinal])
-            nil
+            record(context, answer)
           end
 
-          def ensure_first_heads!(context)
-            lineage = context.lineage
-            context.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) }
+          # A breaking move no edge covers: the boot reads nothing and writes nothing. This stands
+          # in until the commit-time gate (ADR 0168) keeps such a move off main.
+          def refuse_breaking!(context, answer)
+            raise Runtime::WiringError, "cannot boot #{context.domain_name}: #{answer.reason}"
           end
 
-          def grant_role!(context, ordinal)
-            return unless context.role
+          # Whether this check mints: a mint request, on a shape no held era holds.
+          def minting?(answer, context) = context.mint_request && !answer.matched?
 
-            lineage = context.lineage
-            lineage.grant_role!(context.role, aggregates: context.aggregates, era: ordinal)
+          # No era is held: the first era is held by the mint entry point, never by a boot.
+          def refuse_unheld!(context)
+            raise Runtime::WiringError,
+                  "cannot boot #{context.domain_name}: no era held; run the mint entry point " \
+                  "(`hecks era.hold_first! <domain directory> --confirm`) to hold the first era"
           end
 
-          # Each held era with its storage shape. Held text is a frozen record and keeps the
-          # prior name; only the in-memory shape is normalized, and only on an exact match with
-          # the declared prior name.
-          def held_shapes(bluebook, held)
-            shapes = held.map { |era| [era, Runtime::StorageShape.project(shadow(era[:held_text]))] }
-            return shapes unless bluebook.formerly_known_as
-
-            shapes.map do |era, shape|
-              [era, shape["name"] == bluebook.formerly_known_as ? shape.merge("name" => bluebook.name) : shape]
-            end
+          # Records what the resolution answered and writes nothing. A superseded era (an old
+          # checkout) reads and never writes: the adapter refuses appends on it, even where the RLS
+          # fence cannot bind. A shape no era holds reads the latest held era, and is behind when a
+          # mint from it would go ahead; the mint entry point runs that mint.
+          def record(context, answer)
+            context.record_resolved(answer.ordinal)
+            latest = answer.latest[:ordinal]
+            status = answer.status
+            context.record_superseded(latest) if status == "superseded"
+            context.record_unminted(latest) if %w[unminted behind].include?(status)
+            context.record_behind(latest) if status == "behind"
+            nil
           end
         end
       end

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