hecks 2.7.0 → 2.9.0

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

@@ -8,28 +8,19 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # What a mint must prove before it may happen: the edge covers
-        # the whole diff, no identity path was re-keyed, and the audit's
-        # first two layers pass over the live compiled chain.
+        # What a mint must prove first: the edge covers the whole diff, no identity path was
+        # re-keyed, and the audit's first two layers pass over the compiled chain.
         module CoverageCheck
-          # Refuses a mint whose translation edge leaves any part of the shape change
-          # unexplained.
+          # Refuses a mint whose translation edge leaves any part of the shape change unexplained.
           #
-          # Layer 1 against this edge specifically: every vanished or
-          # retyped path in the held→current diff must be explained, and
-          # every held aggregate must still be claimed. The refusal is
-          # EraGuard's own, byte for byte.
+          # Every vanished or retyped path in the held-to-current diff must be explained and every
+          # held aggregate claimed; the refusal is EraGuard's own, byte for byte.
           #
-          # @param registry [Runtime::Registry] the registry whose loaded translations may
-          #   claim a held aggregate through `was:` or `retired`
+          # @param registry [Runtime::Registry] where translations may claim a held aggregate
           # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era's
-          #   text declares it (a shadow parse)
+          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era declares it
           # @param edge [Bluebook::Translation] the one edge leaving the latest held era
-          # @return [void]
-          # @raise [Runtime::WiringError] if an identity path changed without a `rekey`
-          #   rule, a vanished or retyped path has no rule, a new required attribute has
-          #   nothing to fill it, or a held aggregate is neither renamed nor retired
+          # @raise [Runtime::WiringError] on an unruled identity change or an uncovered path
           def check_coverage!(registry, bluebook, held_bluebook, edge)
             bluebook.aggregates.each do |aggregate|
               rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
@@ -46,30 +37,19 @@ module Hecks
             Runtime::EraGuard.check_vanished_aggregates!(registry, bluebook, held_bluebook)
           end
 
-          # Refuses a mint that changes an aggregate's identity paths without declaring
-          # a `rekey`.
+          # Refuses a mint that changes an aggregate's identity paths without declaring a `rekey`.
           #
-          # An identity-path change is a re-keying, not an ordinary
-          # translation — stored ids were fixed at write time under the old
-          # key, so this refuses unless the edge declares a `rekey` for
-          # this aggregate covering exactly that. `rules.rekey?` (see
-          # `Ports::Persistence::Lineage`'s own comment) is the single
-          # source of truth every consumer of this fact asks — this is not
-          # a second, independent check of `declared.rekeys`.
+          # Stored ids were fixed under the prior key, so the edge must declare a `rekey` for it;
+          # `rules.rekey?` is the one source of truth for that fact.
           #
           # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
           # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
-          # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held
-          #   era's text declares it
-          # @param rules [Ports::Persistence::Lineage, nil] the edge's rules for this
-          #   aggregate; nil when the edge declares none, which cannot excuse a change
-          # @return [nil] when the identity paths are unchanged or a `rekey` covers them
-          # @raise [Runtime::WiringError] if the identity paths differ and no `rekey` rule
-          #   is declared
+          # @param held_aggregate [Bluebook::Aggregate] the same aggregate in the held era
+          # @param rules [Ports::Persistence::Lineage, nil] the edge's rules; nil excuses nothing
+          # @raise [Runtime::WiringError] if the identity paths differ and no `rekey` is declared
           def check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
-            # The full declared path lists, in declaration order — never the
-            # single-head shortcut, which is nil for every composite identity
-            # and so would let two different composites compare as unchanged.
+            # Full path lists, not the single-head shortcut: it is nil for every composite identity
+            # and would let two different composites compare equal.
             return if held_aggregate.identity_paths == aggregate.identity_paths
             return if rules&.rekey?
 
@@ -83,28 +63,16 @@ module Hecks
                   "data explicitly"
           end
 
-          # Previews every aggregate's translated head through the pending chain and
-          # refuses the mint if the audit finds a violation.
-          #
-          # Layers 1 and 2 of the audit, over the live compiled chain —
-          # before anything is minted, so a refusal leaves no half-born
-          # era. (A convert meeting an unmapped value raises inside the
-          # preview query itself: same rollback-shaped outcome.)
+          # Previews each aggregate's translated head through the pending chain and audits it.
+          # Runs before anything is minted, so a refusal leaves no half-born era.
           #
           # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open
-          #   connection
-          # @param chain [Array<Hash{Symbol => Bluebook::Translation}>] the full edge chain
-          #   ending in `edge`, as `edge_chain` returns it
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open db
+          # @param chain [Array<Hash>] the full edge chain ending in `edge`, per `edge_chain`
           # @param ordinal [Integer] the ordinal of the era about to be minted
-          # @param edge [Bluebook::Translation] the pending edge, whose per-aggregate rules
-          #   the audit checks
-          # @return [nil] when no aggregate reports a violation
-          # @raise [Runtime::WiringError] if Postgres refuses the translated preview query
-          #   (a `convert` meeting an unmapped value, for one), or the audit reports any
-          #   violation; the message lists them all
-          # @raise [PG::Error] if Postgres refuses the "before" query; only the translated
-          #   preview is rescued into a `Runtime::WiringError`
+          # @param edge [Bluebook::Translation] the pending edge
+          # @raise [Runtime::WiringError] if a preview query fails or the audit reports a violation
+          # @raise [PG::Error] if Postgres refuses the "before" query
           def audit!(bluebook, lineage, chain, ordinal, edge)
             violations = []
             bluebook.aggregates.each do |aggregate|

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

@@ -5,65 +5,29 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # The boot-time resolution: which era is this checkout? First
-        # boot holds era 1; a quiet reboot changes nothing; a
-        # held-but-superseded shape boots read-only-toward-the-fence; an
-        # unheld shape goes to the minter.
+        # 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.
         module EraResolver
           # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-          # Resolves which era this boot is and records it on the registry, holding era 1
-          # on a first boot and minting the next era when the shape is one no era holds.
+          # Resolves which era this boot is and records it on the registry.
           #
-          # A single order-dependent dispatch over a closed set of four
-          # boot scenarios (first boot / quiet reboot / held-but-superseded
-          # / unheld-shape-goes-to-minter), each already explained by its
-          # own comment above, all sharing one `db` connection closed in
-          # `ensure`. Splitting the branches into separate methods would
-          # turn each `return` (which exits `check!`, closing `db`) into a
-          # sentinel value threaded back up, obscuring the mutual
-          # exclusivity that is the method's whole point.
-          #
-          # @param registry [Runtime::Registry] the booting registry; `resolved_eras` gets
-          #   this domain's ordinal on every path but a first boot (where the adapter
-          #   self-resolves to era 1), and `superseded_eras` gets the newest ordinal when
-          #   this checkout's shape is held but superseded
-          # @param bluebook [Bluebook::Chapter] the domain being booted
-          # @param current_text [String] the domain's bluebook source as it stands on disk,
-          #   held verbatim as the new era's text on a first boot or a mint
-          # @param settings [Hash{Symbol, String => Object}] the world's persistence settings
-          #   for this binding; `database` is required, `schema`, `role` (a Postgres role to
-          #   grant this era's privileges to) and `allow_superuser` are honored
-          # @param directory [String, nil] the domain's bluebook directory, where
-          #   `HECKS_SCAFFOLD=1` writes a translation edge; nil disables scaffolding
-          # @return [Integer, nil] the ordinal of the era this boot minted, or nil when it
-          #   minted nothing (first boot, quiet reboot, or a held-but-superseded shape)
-          # @raise [Runtime::WiringError] if the database cannot be reached, the connection
-          #   is a superuser or has BYPASSRLS without `allow_superuser`, a declared
-          #   `formerly_known_as` rename cannot be applied, a held text fails its integrity
-          #   check, or the shape is unheld and `mint!` refuses
-          # @raise [Bluebook::DSL::Malformed] if a held era's text parses under neither the
-          #   current nor the legacy grammar
+          # @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
           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! provisions or verifies anything —
-            # the one point every PostgresEra boot passes through, and the
-            # earliest at which the connection's own role is known. See
-            # check_fence_applies!'s own header (BUG#24) for why a
-            # superuser connection refuses here by default.
+            # 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!
-            # Both spellings honored, key? first — never `||`, which cannot
-            # tell a genuinely stored `false` apart from an absent key (see
-            # PostgresEra.setting's own comment for the full reasoning).
+            # key? first, never `||`: a stored `false` must not read as an absent key.
             role = settings.key?(:role) ? settings[:role] : settings["role"]
 
             held = lineage.eras
             if held.empty?
               lineage.hold_first!(current_text, projection: Runtime::StorageShape.project(bluebook))
               bluebook.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) }
-              # hold_first! already established era 1 as current for
-              # every role; this one just needs its own privileges.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: 1) if role
               return
             end
@@ -71,15 +35,8 @@ module Hecks
             current_shape = Runtime::StorageShape.project(bluebook)
             shapes = held.map { |era| [era, Runtime::StorageShape.project(shadow(era[:held_text]))] }
             if bluebook.formerly_known_as
-              # A held era's shape is re-derived from its own frozen
-              # historical text (shadow(era[:held_text])), so its "name"
-              # is permanently the old one — the frozen text is authentic
-              # record ("this domain really was called that, at the
-              # time") and must never be rewritten. Only the in-memory
-              # shape used for this comparison is normalized, and only
-              # where it exactly matches the declared old name, so an
-              # unrelated domain that happens to shape-match some other
-              # domain's history still shows up as a real mismatch.
+              # Held text is 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.
               shapes = shapes.map do |era, shape|
                 [era, shape["name"] == bluebook.formerly_known_as ? shape.merge("name" => bluebook.name) : shape]
               end
@@ -88,8 +45,6 @@ module Hecks
             latest, latest_shape = shapes.last
             if latest_shape == current_shape
               bluebook.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) } if latest[:ordinal] == 1
-              # A quiet reboot changes no era, so there is nothing to
-              # advance — only this role's own privileges, if it is new.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: latest[:ordinal]) if role
               registry.resolved_eras[bluebook.name] = latest[:ordinal]
               return
@@ -97,24 +52,11 @@ module Hecks
 
             matched, = shapes.find { |_, shape| shape == current_shape }
             if matched
-              # A held-but-superseded era — an old checkout still running.
-              # It may keep booting and reading (PostgresEra is the one
-              # adapter that recognizes this rather than refusing), but it
-              # may not keep writing: the shared era fence was already
-              # advanced past this ordinal by whichever mint superseded
-              # it, and nothing here may roll that back. Granting only
-              # this role's privileges, never advance_era!, is what keeps
-              # that true — see advance_era!'s own warning against being
-              # called with a superseded ordinal.
+              # A superseded era (an old checkout) may read but not write: never advance_era!
+              # here, since the fence is already past this ordinal.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
               registry.resolved_eras[bluebook.name] = matched[:ordinal]
-              # ...and the boot remembers that it is superseded, not only
-              # which era it is: `RepositoryFactory.build` hands this to
-              # the adapter as `superseded_by:`, and `PostgresEra#append`
-              # refuses on it before issuing the INSERT. That is the
-              # in-process half of "may not keep writing" — the half that
-              # holds even for a connection the RLS fence cannot bite
-              # (a superuser under allow_superuser; BUG#24).
+              # The adapter refuses appends on this, even where the RLS fence cannot bind.
               registry.superseded_eras[bluebook.name] = latest[:ordinal]
               return
             end

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

@@ -6,26 +6,17 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # Tail-merge, driven from bin/merge_tail: interleave the old
-        # world's post-cut writes into the head by their recorded global
-        # ordinals, under the full audit, in one transaction.
+        # Tail-merge (bin/merge_tail): interleaves the stale world's post-cut writes into the
+        # head by global ordinal, audited, in one transaction.
         module MergeCoordinator
-          # Merges the writes old checkouts made after the last mint into the current
-          # era's head, on a connection of its own that it closes afterwards.
+          # Merges writes old checkouts made after the last mint into the current era's head.
           #
-          # @param registry [Runtime::Registry] the loaded registry; supplies the
-          #   translation edges the chain is built from
-          # @param bluebook [Bluebook::Chapter] the domain whose tail is merged
-          # @param settings [Hash{Symbol, String => Object}] the world's persistence
-          #   settings for this binding; `database` is required
           # @param winners [Hash{String => String}] record id to `"old"` or `"new"`, naming
-          #   which world's whole record wins for each id both worlds touched since the cut
+          #   which world's record wins for each id both worlds touched since the cut
           # @return [true] when the merge committed
-          # @raise [Runtime::WiringError] if the database cannot be reached, the domain
-          #   stands at era 1, the edge chain is broken, a record touched by both worlds
-          #   has no named winner, the post-merge audit reports violations, another mint
-          #   or merge holds the domain lock for 10 seconds, or Postgres refuses a
-          #   statement; every refusal rolls the merge back
+          # @raise [Runtime::WiringError] if the domain stands at era 1, the edge chain is
+          #   broken, a contested record has no winner, or the audit reports violations;
+          #   every refusal rolls the merge back
           def merge!(registry:, bluebook:, settings:, winners: {})
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)

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

@@ -7,34 +7,10 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # The mint path: name the source era, find the one edge that
-        # leaves it, hold the compute approval to what was actually
-        # reviewed, check coverage, audit the live chain, and mint — or
-        # refuse toward the authoring loop by name.
+        # Names the source era, resolves its one outgoing translation edge, and mints the
+        # next era once approval, coverage and the audited chain all check out.
         module Minter
-          # Mints the next era for a drifted shape in one transaction, after proving the
-          # edge is present, current, approved where it must be, covering, and audited.
-          #
-          # @param registry [Runtime::Registry] the booting registry; supplies the loaded
-          #   translation edges
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param current_text [String] the domain's bluebook source, held verbatim as the
-          #   new era's text
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open
-          #   connection
-          # @param latest [Hash{Symbol => Object}] the newest held era, as `Lineage#eras`
-          #   returns it (`:ordinal`, `:hash`, `:label`, `:held_text`, `:watermark`)
-          # @param role [String, nil] a Postgres role to grant the new era's privileges to;
-          #   nil grants nothing
-          # @param directory [String, nil] the domain's bluebook directory, where
-          #   `HECKS_SCAFFOLD=1` writes a missing edge; nil disables scaffolding
-          # @return [Integer] the ordinal of the era just minted
-          # @raise [Runtime::WiringError] if no edge leaves the latest era, more than one
-          #   does, the edge targets another shape, a compute or rekey edge lacks a current
-          #   approval, the edge leaves drift uncovered, the chain is broken, the audit
-          #   reports violations, or the mint transaction itself fails
-          # @raise [Bluebook::DSL::Malformed] if the latest held text parses under neither
-          #   the current nor the legacy grammar
+          # Mints the next era for a drifted shape in one transaction.
           def mint!(registry, bluebook, current_text, lineage, latest, role: nil, directory: nil)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
@@ -57,28 +33,9 @@ module Hecks
             ordinal
           end
 
-          # Finds the one translation edge that leaves the held era, and
-          # validates it: exactly one edge must leave (eras fork
-          # mechanically — a second edge from the same source is a wiring
-          # mistake, not a merge to resolve automatically), and it must
-          # target the current shape's label (otherwise the edge is stale
-          # and boot must not silently mint past it).
-          #
-          # @param registry [Runtime::Registry] the registry whose loaded `translations`
-          #   are searched
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, used only
-          #   when scaffolding a missing edge
-          # @param latest [Hash{Symbol => Object}] the newest held era, already named;
-          #   `:label` is the edge's required source and `:ordinal` appears in refusals
-          # @param label [String] the current shape's label, the edge's required target
-          # @param ordinal [Integer] the ordinal of the era about to be minted
-          # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a missing edge;
-          #   nil disables scaffolding
-          # @return [Bluebook::Translation] the single edge from `latest[:label]` to `label`
-          # @raise [Runtime::WiringError] if no edge leaves the latest era (naming the
-          #   scaffold it wrote, when it wrote one), more than one does, or the one edge
-          #   targets a label other than `label`
+          # Finds the one translation edge leaving the held era and targeting the current
+          # shape's label; a second edge from the same source is a wiring mistake, not a
+          # merge to resolve automatically.
           def resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
             edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
             refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory) if edges.empty?
@@ -97,29 +54,10 @@ module Hecks
             edge
           end
 
-          # Refuses a mint whose edge carries a compute or rekey rule without a recorded
-          # approval that still matches the edge and the journal.
+          # Refuses a mint whose edge carries a compute or rekey rule without a recorded,
+          # edge-matching, journal-current approval.
           #
-          # A compute's (and, the same way, a rekey's) only verification
-          # is the audit's human-approved sample — mint stays
-          # non-interactive by requiring the approval to already exist,
-          # recorded in this database by `bin/translation_audit …
-          # --approve` and bound to what was actually reviewed: this
-          # edge's parsed content, and the journal as it stood when the
-          # samples were read. A journal that has advanced past the
-          # review invalidates it — the approved samples no longer cover
-          # the data.
-          #
-          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, which holds
-          #   the recorded approvals and the journal's last ordinal
-          # @param edge [Bluebook::Translation] the edge about to be minted through
-          # @param ordinal [Integer] the ordinal of the era about to be minted
-          # @return [nil] when the edge has no compute or rekey rule, or its approval is
-          #   current
-          # @raise [Runtime::WiringError] if no approval is recorded for this shape pair, the
-          #   approval's edge digest differs from this edge's, or the journal has advanced
-          #   past the reviewed ordinal
+          # A compute or rekey's only verification is a human-approved audit sample.
           def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
             return unless edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
 
@@ -139,28 +77,8 @@ module Hecks
                   "human approved no longer cover the data; re-run bin/translation_audit with --approve"
           end
 
-          # Refuses a mint that found no translation edge, naming the authoring tools —
-          # or, with scaffolding on, the file it just wrote.
-          #
-          # No edge yet: the boot refuses toward the authoring loop —
-          # naming both tools and the era ordinal. With HECKS_SCAFFOLD=1
-          # the boot runs the scaffold first (an explicit flag, never a
-          # silent side-effect) and the refusal names the file it wrote.
-          #
-          # @param registry [Runtime::Registry] the registry, forwarded to `scaffold!` when
-          #   scaffolding is on
-          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, forwarded
-          #   to `scaffold!` when scaffolding is on
-          # @param latest [Hash{Symbol => Object}] the newest held era, forwarded to
-          #   `scaffold!` when scaffolding is on
-          # @param ordinal [Integer] the ordinal of the era about to be minted, named in
-          #   the refusal
-          # @param directory [String, nil] the domain's bluebook directory; scaffolding
-          #   requires this to be present as well as `HECKS_SCAFFOLD=1`
-          # @return [void] never returns
-          # @raise [Runtime::WiringError] always; the message names the scaffolded file
-          #   when `HECKS_SCAFFOLD=1` and `directory` wrote one
+          # 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!(registry, bluebook, lineage, latest, ordinal, directory)
             if ENV["HECKS_SCAFFOLD"] == "1" && directory
               path = scaffold!(registry, bluebook, lineage, latest, directory)
@@ -175,19 +93,8 @@ module Hecks
                   "check it with bin/translation_audit, then boot again"
           end
 
-          # Diffs the held era against the current shape and writes the edge
-          # file — confident rules inline, ambiguities as parse-refusing
-          # `unresolved` lines.
-          #
-          # @param _registry [Runtime::Registry] unused; kept so the signature matches its
-          #   caller's own arguments
-          # @param bluebook [Bluebook::Chapter] the domain as currently declared
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage; named so
-          #   `ensure_named!` can mint a name for `latest` first if it has none
-          # @param latest [Hash{Symbol => Object}] the newest held era, as `Lineage#eras`
-          #   returns it
-          # @param directory [String] the domain's bluebook directory to write the edge under
-          # @return [String] the path `Translation::Scaffold::Writer#write!` wrote
+          # 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
@@ -209,15 +116,7 @@ module Hecks
 
           # Mints a name for an era that has none yet, leaving an already-named era untouched.
           #
-          # Era names are minted once. An era held before any drift was
-          # seen has no name yet; it gets one the moment an edge needs to
-          # leave it.
-          #
-          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, which
-          #   records the minted name
-          # @param era [Hash{Symbol => Object}] the era to name, as `Lineage#eras` returns it;
-          #   `:hash` present means it is already named
-          # @return [void]
+          # Era names are minted once, the moment an edge first needs to leave that era.
           def ensure_named!(lineage, era)
             return if era[:hash]
 

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

@@ -10,26 +10,8 @@ require_relative "../../../../../runtime/registry"
 module Hecks
   module Adapters
     class PostgresEra
-      # The PostgresEra side of the boot-time era gate. Where every other
-      # adapter's era check can only hold texts and refuse, this one
-      # acts: a drifted shape whose translation edge exists, matches by
-      # shape label, covers the whole diff, and passes the audit mints
-      # the next era — one transaction — and boots into it. Everything
-      # else refuses, as loudly and as specifically as the situation
-      # allows, naming both authoring tools.
-      #
-      # Minting happens here, once: era identity (SHA-256 of the canonical
-      # storage-shape serialization; the short prefix is the label edges
-      # and refusals use) is computed at mint time and stored in
-      # hecks_eras. Everything else reads stored names and never hashes
-      # anything — an era name is a storage fact, minted on this path or
-      # absent, never reconstructed.
-      #
-      # One concern per file under lineage_manager/: era_resolver (which
-      # era is this boot?), minter (the mint path and its refusals),
-      # merge_coordinator (bin/merge_tail's driver), coverage_check
-      # (what a mint must prove first). What stays here is what they
-      # share: the edge chain, and the shadow parse.
+      # PostgresEra's era gate: mints the next era when an edge covers the drift, else refuses.
+      # Era names are hashed once at mint time and stored in hecks_eras, never reconstructed.
       module LineageManager
         extend EraResolver
         extend Minter
@@ -39,23 +21,14 @@ module Hecks
         module_function
 
         # Collects the translation edge for every step from era 1 to the current shape.
+        # Each mint required its own edge, so a gap in the chain means a deleted file.
         #
-        # The full chain, one edge per step in original mint order —
-        # never flattened. Each step is found by its stored labels;
-        # every mint required its own edge, so a break in the chain is a
-        # deleted file, and deserves its own refusal.
-        #
-        # @param registry [Runtime::Registry] the registry whose loaded `translations`
-        #   are searched
-        # @param bluebook [Bluebook::Chapter] the domain; only edges declared for its
-        #   name are considered
-        # @param eras [Array<Hash{Symbol => Object}>] the ancestor eras in ordinal order,
-        #   as `Lineage#eras` returns them; only `:label` is read
+        # @param registry [Runtime::Registry] the registry whose loaded `translations` are searched
+        # @param bluebook [Bluebook::Chapter] 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
-        # @return [Array<Hash{Symbol => Bluebook::Translation}>] one `{ translation: edge }`
-        #   per step, in mint order; `[]` when `eras` is empty
-        # @raise [Runtime::WiringError] if no loaded translation leads one label to the
-        #   next
+        # @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)
           labels = eras.map { |era| era[:label] } + [current_label]
           (0...(labels.size - 1)).map do |index|
@@ -71,18 +44,13 @@ module Hecks
           end
         end
 
-        # Parses a held era's bluebook text into a throwaway registry, leaving the live
-        # one untouched.
+        # Parses a held era's bluebook text into a throwaway registry, not the live one.
         #
-        # Held texts live in rows, not files, but the predicate
-        # extractor reads source from disk at the eval path — so a
-        # shadow parse writes the text to a scratch file first.
+        # The predicate extractor reads source from disk, so the text goes through a scratch file.
         #
-        # @param source [String] bluebook source text, as held in `hecks_eras.held_text`
-        # @return [Bluebook::Chapter, nil] the first bluebook the text declares, or nil
-        #   when it declares none
-        # @raise [Bluebook::DSL::Malformed] if the text parses under neither the current
-        #   grammar nor the legacy shadow-parse fallback
+        # @param source [String] bluebook source text from `hecks_eras.held_text`
+        # @return [Bluebook::Chapter, 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"])
           file.write(source)