hecks 2.8.0 → 3.0.0

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -6,23 +6,8 @@ require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
-    # The shape-drift coverage primitives — ADR 0032. Not a driver: nothing
-    # here walks a registry or reads/writes a held snapshot on its own.
-    # `PostgresEra::LineageManager::CoverageCheck` calls `uncovered_
-    # attributes`/`unsafe_additions`/`refuse_uncovered!`/`refuse_unsafe_
-    # addition!`/`check_vanished_aggregates!` directly, per translation
-    # edge, over its own DB-held shapes; `Translation::Reattest` and
-    # `PostgresEra::LineageManager` call `shadow_parse` directly, to read
-    # historical bluebook text under old grammar defaults. Both are real,
-    # independent, currently-shipped consumers.
-    #
-    # There is deliberately no top-level `check!`/`check_bluebook!` here
-    # walking a registry and reading/writing a held snapshot under
-    # `data/eras/*.bluebook`: it would duplicate, on its own, the same
-    # per-aggregate walk `CoverageCheck` already performs against
-    # `PostgresEra`'s own DB-held shapes, and nothing in production would
-    # call it — an unwired driver is not kept, per ADR 0032. If one is
-    # wanted, it is built informed by `CoverageCheck`'s real orchestration.
+    # Shape-drift coverage primitives (ADR 0032). Not a driver: callers own
+    # walking a registry and reading/writing held snapshots; nothing here does either.
     module EraGuard
       extend ShapeDiff
 
@@ -30,20 +15,16 @@ module Hecks
 
       # Refuses the boot when a held aggregate is gone and no translation says where it went.
       #
-      # An aggregate that existed in the held text and answers to no
-      # current name — renamed silently, with nothing declaring `was:` to
-      # explain where its data went — is exactly the disease this guards
-      # against, and a plain per-aggregate diff would never see it: the
-      # current aggregate simply has no held counterpart to compare to.
+      # A held aggregate matching no current name has no counterpart for a
+      # plain per-aggregate diff to compare against; only a `was:` or
+      # `retired` translation can explain it.
       #
-      # @param registry [Runtime::Registry] the registry whose declared translations are
-      #   searched for a `was:` or a `retired` entry naming the held aggregate
+      # @param registry [Runtime::Registry] the registry searched for a `was:`/`retired` entry
       # @param bluebook [Bluebook::Chapter] the bluebook booting now
       # @param held_bluebook [Bluebook::Chapter] the bluebook parsed from the held era's text
       # @return [void]
-      # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate by
-      #   name, no current aggregate's translation declares it as `was:`, and no translation
-      #   for this domain retires it
+      # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate, no
+      #   `was:` declares it, and no translation retires it
       def check_vanished_aggregates!(registry, bluebook, held_bluebook)
         held_bluebook.aggregates.each do |held_aggregate|
           claimed = bluebook.aggregates.any? do |aggregate|
@@ -125,65 +106,16 @@ module Hecks
         end
       end
 
-      # Parses held source into its own IR, in a scratch registry so a past
-      # era's text never touches the one actually booting.
+      # Parses held source into its own IR, in a throwaway registry.
       #
-      # Normal parse first, shadow only as a fallback — never shadow-parsing
-      # unconditionally. A handful of DSL
-      # defaults fork on `MetaValidator.shadow_parsing?` for a reason
-      # that has nothing to do with syntax the live grammar cannot
-      # read at all (`identified_by { }`, `belongs_to`, `has_one`,
-      # `has_many` — genuinely removed spellings, exactly what shadow-
-      # parsing exists to keep readable): `reference_to`'s own default
-      # mint name (`default_reference_name`, attribute_collector.rb)
-      # is bare under ADR 0025 and `_id`-suffixed under shadow mode, and
-      # that fork applies even to text using nothing but current, live
-      # syntax. Held text minted under the current grammar — every real
-      # era in this corpus today, since nothing has ever minted a second
-      # one — parses fine normally; under unconditional shadow mode only
-      # the reference-naming default differs, so it silently
-      # reconstructs a different shape (and hash) than a fresh parse of
-      # the identical text — the same text hashing two different ways
-      # depending on which code path read it, breaking `ensure_named!`'s
-      # own from/to edge lookup with a spurious "no translation edge
-      # covers it" refusal that has nothing to do with any real
-      # translation gap.
-      #
-      # A normal parse can only ever succeed on text the live grammar
-      # fully understands — there is no way for it to silently produce a
-      # wrong-but-plausible answer for genuinely legacy text, since every
-      # removed spelling refuses loudly (`Malformed`) rather than
-      # degrading. So: try normal first — if the ordinary grammar reads
-      # this text without complaint, that is the canonical, unambiguous
-      # interpretation, the same one `label_of`/`mint_hash` on the same
-      # source text always computes, whoever's asking. Only on a
-      # `Malformed` refusal — the one signal that actually means "this
-      # spelling is not in the live grammar" — fall back to the legacy
-      # grammar. Any other exception (a
-      # genuine syntax error, an unrelated validation refusal) propagates
-      # unchanged; swallowing it here to retry under shadow mode would
-      # risk masking a real defect in the held text behind a confusing
-      # second failure instead of the original, more specific one.
-      #
-      # `MetaValidator.while_shadow_parsing` (ADR 0025, docs/dsl-work-
-      # slices.md's S0a) is what makes the fallback a legacy grammar
-      # rather than just a second copy of today's: it stops
-      # `BluebookBuilder.build` from judging this text against the
-      # grammar as it stands now, which is the one thing that would make
-      # a removed spelling refuse history the day it is removed from
-      # live source. The scratch registry is throwaway either way —
-      # nothing here is dispatched against or exposed to the real one —
-      # so skipping the judge/assemble round-trip changes nothing this
-      # method reads: `shape`, `uncovered_attributes`, and friends only
-      # ever ask the built IR for its own structure.
+      # Tries the live grammar first, falling back to the shadow one only
+      # on `Malformed` — the one signal meaning "not in the live grammar"
+      # (ADR 0025); any other exception propagates unchanged.
       #
       # @param source [String] the held bluebook text to evaluate
-      # @param path [String] the file path the text is evaluated as, which the predicate
-      #   extractor reads from disk; callers pass a tempfile holding the same text
-      # @return [Bluebook::Chapter, nil] the first bluebook the text declares; nil when it
-      #   declares none
-      # @raise [Bluebook::DSL::Malformed] if the text parses under neither the live grammar
-      #   nor the legacy one
+      # @param path [String] the file path reported as the text's origin
+      # @return [Bluebook::Chapter, nil] the first bluebook declared; nil when it declares none
+      # @raise [Bluebook::DSL::Malformed] if neither grammar accepts the text
       # @raise [SyntaxError] if the text is not valid Ruby
       def shadow_parse(source, path)
         parse_bluebook(source, path, shadow: false)
@@ -196,7 +128,7 @@ module Hecks
       # @param source [String] the bluebook text to evaluate
       # @param path [String] the file path reported to `Kernel.eval` as the text's origin
       # @param shadow [Boolean] true evaluates inside `MetaValidator.while_shadow_parsing`
-      #   (the legacy grammar); false evaluates under the live grammar
+      #   (the shadow grammar); false evaluates under the live grammar
       # @return [Bluebook::Chapter, nil] the first bluebook the text registered in the scratch
       #   registry; nil when it declares none
       # @raise [Bluebook::DSL::Malformed] if the chosen grammar refuses the text
@@ -207,7 +139,10 @@ module Hecks
         run = lambda do
           Hecks.with_registry(scratch) do
             loading.load_library
-            Kernel.eval(source, TOPLEVEL_BINDING, path, 1)
+            # Held text of a chapter spread over files is several blocks in one string, each
+            # opening the same chapter: judge once after all of them, as a directory load does.
+            Hecks::Bluebook::MetaValidator.defer { Kernel.eval(source, TOPLEVEL_BINDING, path, 1) }
+            Hecks::Bluebook::MetaValidator.judge_deferred!(scratch)
           end
         end
         shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call

data/lib/hecks/ports/persistence/plugins/era/era_tamper.rb

@@ -5,26 +5,11 @@ require_relative "storage_shape"
 
 module Hecks
   module Runtime
-    # The refusal wording for a held era whose digest does not match its
-    # frozen text — the digest mismatch alone is what detects tampering (a
-    # plain SHA256 comparison over raw bytes, unrelated to any of this);
-    # this only supplies the wording once that's already fired.
+    # Wording for the boot refusal when a held era's frozen text was
+    # edited after freezing (detected elsewhere via a digest mismatch).
     #
-    # Lives here, not under `Ports::Persistence` — `project` below directly
-    # calls `Runtime::EraGuard.shadow_parse`/`Runtime::StorageShape.project`
-    # (DSL-execution machinery), the "an adapter/port reaches into the
-    # runtime instead of being handed already-computed data" shape that
-    # has caused trouble here before. A capability this dependent on the
-    # runtime is a runtime-owned one that the Postgres adapter calls, not
-    # a ports-level module that happens to reach sideways into it.
-    #
-    # Every tamper refusal reaches the same generic wording, cosmetic edit
-    # or real shape change alike: telling the two apart by re-parsing the
-    # edited text is a pure quality-of-message nicety, not a safety
-    # property, and an edit that cannot be classified has to fall to the
-    # generic wording anyway. An operator judges "did this matter"
-    # themselves, reading the still-archived original — an anomalous
-    # recovery moment already, not a normal boot path.
+    # Lives here, not under `Ports::Persistence`, because `project` below
+    # calls runtime DSL-execution machinery (`EraGuard`, `StorageShape`) directly.
     module EraTamper
       module_function
 
@@ -40,12 +25,8 @@ module Hecks
 
       # Parses a bluebook text and returns its storage-shape projection.
       #
-      # The projection is JSON-normalized for structural comparison
-      # against a stored projection; nil when the text does not load.
-      # Always parsed through a fresh tempfile, never the held file's own
-      # path: the predicate extractor caches source by path, and a held
-      # path whose content has changed (the very situation this module
-      # exists for) would hand it stale lines.
+      # Always parsed from a fresh tempfile, never the held file's own path,
+      # since the predicate extractor caches source by path and would see stale lines there.
       #
       # @param text [String] the bluebook source to parse
       # @param _source_path [String, nil] ignored; the text is always parsed from a tempfile

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -5,27 +5,8 @@ require "uri"
 module Hecks
   module Runtime
     module EraCheck
-      # The read side of the era gate, for a deploy operator rather than a boot:
-      # asks a running host which era it reports at `GET /version` and compares
-      # it with an allow-list file of the eras that should be running.
-      #
-      # `EraCheck.check!` decides at boot, against the store, whether a host may
-      # run on an era. This answers the question after a roll, from outside:
-      # did the host that came up report an era the operator expects? The two
-      # never share state. The host's own `GET /version` document
-      # (`rust/host/src/server.rs`, `version_body`) is the only input, so a
-      # rollback to an older image, or a fork of the journal back onto an older
-      # era, shows up here as an era missing from the list.
-      #
-      # ## The allow-list file
-      #
-      # One era id per line. Blank lines and lines starting with `#` are
-      # ignored, and so is a trailing ` # comment`. A file that lists no era
-      # means "only check that the host reports one", so a first roll can be
-      # checked before any era id is known. The generated `expected-era` file
-      # (`Deploy::Scripts`) has this shape.
-      #
-      # `bin/check_era` is the command-line wrapper.
+      # Compares a running host's reported era (`GET /version`) against an
+      # allow-list file of eras that should be running, for use after a roll.
       module ExpectedEra
         # The host could not be reached, or did not answer with a `200`.
         class Unreachable < StandardError; end
@@ -36,7 +17,7 @@ module Hecks
         # What a comparison concluded.
         #
         # @!attribute [r] status
-        #   @return [Symbol] `:match`, `:unlisted` (no era on the list, one reported) or `:mismatch`
+        #   @return [Symbol] `:match`, `:unlisted` (no era listed) or `:mismatch`
         # @!attribute [r] era
         #   @return [String] the era the host reported
         # @!attribute [r] allowed
@@ -78,13 +59,26 @@ module Hecks
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
         def fetch_era(url, timeout: 10)
+          fetch_version(url, timeout: timeout).fetch("era")
+        end
+
+        # Asks a host for its `/version` document.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [Hash{String => String}] `"era"` (never empty) and `"version"` (empty when the
+        #   host reports none)
+        # @raise [Unreachable] if the request fails or the status is not `200`
+        # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
+        def fetch_version(url, timeout: 10)
           response = get(version_url(url), timeout)
           raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
 
-          era = JSON.parse(response.body)["era"]
+          document = JSON.parse(response.body)
+          era = document["era"]
           raise BadResponse, "#{version_url(url)} carries no era" unless era.is_a?(String) && !era.empty?
 
-          era
+          { "era" => era, "version" => document["version"].to_s }
         rescue JSON::ParserError, TypeError
           raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
         end

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

@@ -6,11 +6,7 @@ module Hecks
   module Ports
     module Persistence
       # Translates a journal entry written under an old shape into the one
-      # the current bluebook declares — a renamed attribute, a renamed
-      # aggregate, or a field crossing a value-object boundary. Applied
-      # wherever entries are read, so replay derives the current head from
-      # history that was never rewritten — the port owns the meaning,
-      # adapters stay oblivious.
+      # the current bluebook declares; replay derives the head from unrewritten history.
       class Lineage
         # `ancestor_name` is the declared name a rename came from (matches
         # the held bluebook's own aggregate names); `ancestor_storage_name`
@@ -24,8 +20,8 @@ module Hecks
         #   searched, in declaration order
         # @param domain [String, Symbol] name of the domain the aggregate belongs to
         # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
-        # @return [Ports::Persistence::Lineage, nil] the rules of the first translation for `domain`
-        #   that names the aggregate; nil when none does
+        # @return [Ports::Persistence::Lineage, nil] the first translation for `domain` naming
+        #   the aggregate; nil when none does
         def self.for(registry, domain, aggregate)
           translation = registry.translations.find do |candidate|
             candidate.domain == domain.to_s && candidate.for_aggregate(aggregate.name)
@@ -37,9 +33,8 @@ module Hecks
 
         # Builds the rules one declared translation edge carries for one aggregate.
         #
-        # One specific edge's rules for one aggregate — what the mint
-        # path uses, where `for` would happily answer with whichever
-        # edge in the registry mentioned the aggregate first.
+        # Unlike `for`, this uses one specific edge, not whichever edge in
+        # the registry mentions the aggregate first — what the mint path needs.
         #
         # @param declared [Bluebook::TranslationAggregate, nil] the edge's entry for the
         #   aggregate, as `Bluebook::Translation#for_aggregate` returns it; nil when the edge
@@ -60,24 +55,16 @@ module Hecks
               ancestor_name: ancestor_name, ancestor_storage_name: ancestor_storage_name)
         end
 
-        # @param renames [Hash{Symbol => Symbol}] old top-level attribute name to new name
-        # @param moves [Array<Bluebook::TranslationMove>] fields crossing a value-object
-        #   boundary, each a `from`/`to` pair of bare or dotted paths
-        # @param converts [Array<Bluebook::TranslationConvert>] moves whose value is replaced
-        #   through an exhaustive `values` lookup table
-        # @param drops [Array<Symbol>] bare or dotted paths whose data is deliberately discarded
-        # @param retypes [Array<Bluebook::TranslationRetype>] value-object or entity type names
-        #   declared to mean the same shape
-        # @param computes [Array<Bluebook::TranslationCompute>] SQL-only rules, never applied
-        #   in process
-        # @param rekeys [Array<Bluebook::TranslationRekey>] SQL-only identity rewrites; only
-        #   the first is read
-        # @param backfills [Array<Bluebook::TranslationBackfill>] defaults for new top-level
-        #   attributes an old entry lacks
-        # @param ancestor_name [String, nil] the aggregate's declared name before the edge;
-        #   nil unless the edge renames the aggregate itself
-        # @param ancestor_storage_name [String, nil] snake_case storage name of
-        #   `ancestor_name`; nil unless the edge renames the aggregate itself
+        # @param renames [Hash{Symbol => Symbol}] old attribute name to new name
+        # @param moves [Array<Bluebook::TranslationMove>] from/to paths across a value object
+        # @param converts [Array<Bluebook::TranslationConvert>] moves mapped through a values table
+        # @param drops [Array<Symbol>] bare or dotted paths whose data is discarded
+        # @param retypes [Array<Bluebook::TranslationRetype>] type names meaning the same shape
+        # @param computes [Array<Bluebook::TranslationCompute>] SQL-only rules, never applied here
+        # @param rekeys [Array<Bluebook::TranslationRekey>] SQL rewrites; only the first is read
+        # @param backfills [Array<Bluebook::TranslationBackfill>] defaults for a new attribute
+        # @param ancestor_name [String, nil] the aggregate's name before the edge, if renamed
+        # @param ancestor_storage_name [String, nil] snake_case storage name of ancestor_name
         def initialize(renames, moves = [], converts = [], drops = [], retypes: [], computes: [], rekeys: [],
                        backfills: [], ancestor_name: nil, ancestor_storage_name: nil)
           @renames = renames
@@ -94,54 +81,39 @@ module Hecks
 
         # Reports whether any rule in this edge is a compute.
         #
-        # Compute is the one rule kind with no in-process implementation at
-        # all. An aggregate carrying one refuses to boot anywhere but
-        # Postgres, per-rule and by name, before the general drift
-        # machinery says anything vaguer.
+        # Compute has no in-process implementation; an aggregate carrying
+        # one refuses to boot anywhere but Postgres.
         #
         # @return [Boolean] true when the edge declares at least one compute rule
         def computes? = !@computes.empty?
 
         # Reports whether this edge rewrites the aggregate's identity.
         #
-        # The single source of truth for "does this edge rekey this
-        # aggregate" — every consumer (coverage_check.rb's identity gate,
-        # minter.rb's approval gate, layer_two.rb's audit, head_compiler.rb's
-        # SQL compilation) asks this, never re-derives it from `declared`
-        # independently. One accessor to change if what a rekey rule means
-        # ever needs to change, not four call sites in four files.
+        # The single source of truth for this; other call sites ask here
+        # rather than re-deriving it from `declared` themselves.
         #
         # @return [Boolean] true when the edge declares at least one rekey rule
         def rekey? = !@rekeys.empty?
 
         # Returns the SQL expression the edge's first rekey rule declares.
         #
-        # The rekey's own SQL — first-and-only rule, same one-per-aggregate
-        # assumption `compute` makes about its own list where it matters
-        # (an edge with more than one is a DSL-level decision, not
-        # something this reader arbitrates).
+        # Only the first rule is read, the same one-per-aggregate assumption
+        # `compute` makes; more than one is a DSL-level decision to arbitrate elsewhere.
         #
         # @return [String, nil] the first rekey rule's SQL; nil when the edge declares no rekey
         def rekey_sql = @rekeys.first&.sql
 
         # Rewrites one journal entry's state from the held shape into the current one.
         #
-        # The reference semantics for the five portable rule kinds —
-        # rename, move, convert, drop, and the aggregate-level `was:`.
-        # `retype` moves nothing (stored state never carries a type name)
-        # and `compute` is deliberately not applied here: its SQL is its
-        # only implementation, so this transform neither imitates nor
-        # checks it — the source field passes through untouched, and the
-        # audit verifies compute output against the matview alone.
+        # The reference semantics for rename, move, convert, drop, and the aggregate-level `was:`.
+        # `compute` is not applied here — its SQL is the only implementation, audited separately.
         #
-        # @param entry [Ports::Persistence::Entry] the entry as stored: `state` has Symbol
-        #   top-level keys and String keys inside a nested value-object Hash
-        # @return [Ports::Persistence::Entry] a new entry with a deep-copied, translated state
-        #   and the same `operation`, `id` and `mirrors`; `entry` itself, untouched, when it
-        #   is not a save or carries no state
-        # @raise [Runtime::WiringError] if a convert meets a value missing from its `values`
-        #   table, or a move or convert would nest under a destination already holding a
-        #   non-Hash value
+        # @param entry [Ports::Persistence::Entry] the entry as stored, with Symbol
+        #   top-level keys and String keys nested in a value-object Hash
+        # @return [Ports::Persistence::Entry] a new entry with translated state and the same
+        #   `operation`, `id` and `mirrors`; `entry` itself when it is not a save or has no state
+        # @raise [Runtime::WiringError] if a convert value is missing from its `values` table, or a
+        #   move/convert would nest under a destination already holding a non-Hash value
         def translate(entry)
           return entry unless entry.save? && entry.state
 
@@ -153,45 +125,18 @@ module Hecks
           @moves.each { |move| apply_move(state, move) }
           @converts.each { |convert| apply_convert(state, convert) }
           @drops.each { |name| apply_drop(state, name) }
-          # Last, and only where nothing already answered — a backfill
-          # fills the gap a rename/move/convert left untouched, never
-          # overwrites a value that already made it across. Dotted-path
-          # aware, same as `apply_drop` above (`apply_backfill`'s own
-          # header) — a bare name was the only shape this ever needed
-          # until a value object gained new required members with zero
-          # source data of their own (found live: a client site's Attendee
-          # redesign, commit 4326dcd).
+          # Only fills a gap nothing else already filled; dotted-path aware, like apply_drop.
           @backfills.each { |backfill| apply_backfill(state, backfill) }
           Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)
         end
 
         # Reports whether some rule accounts for a held path that vanished or changed type.
         #
-        # Whether this translation names `path` as an old key it accounts
-        # for — the rename, move, or convert it came from, or an explicit
-        # drop. `path` is a bare name ("cost") or a dotted value-object
-        # member ("price.currency"); a rule covering the whole top-level
-        # attribute (a rename, a top-level move/convert/drop) also covers
-        # anything nested under it, since the whole value travels or goes
-        # away together. This is what catches a field — or a value object's
-        # own member — that vanished (or silently changed type) without
-        # anything explaining it, even when some other field is covered.
+        # A rule covering a whole top-level attribute also covers anything nested
+        # under it; `backfills` only matches a whole name, since a backfill adds an
+        # attribute that is new outright, never a path that existed and moved.
         #
-        # `backfills` matches on the whole name only, never a dotted
-        # prefix — a backfill names a top-level attribute that is new
-        # outright (nothing to be a prefix of on the held side), unlike
-        # every rule above it, which explains a path that existed and
-        # moved, converted, or vanished.
-        #
-        # One `||` chain over a closed, fixed set of rule kinds (renames,
-        # moves, converts, drops, computes, backfills) — the same six this
-        # file's other methods enumerate. Splitting each disjunct into its
-        # own predicate would scatter one question ("does any rule explain
-        # this path") across six same-shaped methods with nothing else to
-        # do.
-        #
-        # @param path [String, Symbol] a bare attribute name or a dotted value-object member
-        #   path on the held side
+        # @param path [String, Symbol] a bare attribute name or a dotted value-object member path
         # @return [Boolean] true when a rename, move, convert, drop or compute names the path or
         #   its top-level attribute as its source, or a backfill names the top-level attribute
         # rubocop:disable-next Metrics/CyclomaticComplexity
@@ -210,32 +155,11 @@ module Hecks
 
         # Reports whether some rule gives an existing record a value at a new attribute.
         #
-        # The destination-side twin of `explains?` above, which only ever
-        # asks about a rule's source. `unsafe_additions` asks a different
-        # question — not "was this vanished path accounted for" but "does
-        # an existing record end up with a value here" — and a move or
-        # convert whose `to:` lands a old field inside a brand-new
-        # top-level attribute (`weight` becoming `contents.weight` when
-        # `Contents` did not exist before) fills that attribute for an
-        # existing record exactly as a `backfill` would, even though
-        # nothing named `contents` explains any vanished path. `compute`
-        # counts on the same terms `explains?` already grants it
-        # elsewhere in this file — Postgres-only and audited, not
-        # actually applied by this method, the same gap the vanish side
-        # already lives with.
+        # The destination-side twin of `explains?`, which checks a rule's source; this checks
+        # `@renames.value?` too, since a bare rename fills the destination unconditionally,
+        # the same way a backfill would.
         #
-        # `@renames.value?` belongs here too: a bare
-        # `rename :cost, to: :amount` is the plainest possible covering
-        # rule there is (`translate` above applies it unconditionally, no
-        # lookup table, no per-record ambiguity — simpler than a move or
-        # convert), and without it `unsafe_additions` reports the new name
-        # as an unexplained required addition on every rename-only edge,
-        # the single most common translation shape there is. `explains?`
-        # checks the source side (`@renames.key?`); this is the symmetric
-        # destination-side check.
-        #
-        # @param path [String, Symbol] the name of a top-level attribute new in the current
-        #   shape
+        # @param path [String, Symbol] the name of a top-level attribute new in the current shape
         # @return [Boolean] true when a rename, move, convert or compute lands a value in that
         #   attribute, or a backfill names it
         def fills?(path)
@@ -250,15 +174,11 @@ module Hecks
 
         # Reports whether a declared retype pairs two type names as the same shape.
         #
-        # A retype covers a value object or entity whose own name changed
-        # with its members intact. Nothing in the stored data carries the
-        # type name, so this never moves a value; it only satisfies the
-        # era diff's literal type-name comparison.
+        # Nothing in the stored data carries a type name, so this never moves a value;
+        # it only satisfies the era diff's literal type-name comparison.
         #
-        # @param held_type [String, Bluebook::Reference] the type the held era declares,
-        #   compared by its `to_s`
-        # @param current_type [String, Bluebook::Reference] the type declared now, compared by
-        #   its `to_s`
+        # @param held_type [String, Bluebook::Reference] the type the held era declares
+        # @param current_type [String, Bluebook::Reference] the type declared now
         # @return [Boolean] true when some retype rule runs from `held_type` to `current_type`
         def retype?(held_type, current_type)
           @retypes.any? { |retype| retype.from == held_type.to_s && retype.to == current_type.to_s }
@@ -274,30 +194,14 @@ module Hecks
           end
         end
 
-        # M27 (docs/audits/2026-08-10-main-bug-audit.md,
-        # docs/audits/2026-08-11-bug-triage.md) — simultaneous, not
-        # sequential: `state[new] = state.delete(old)` per rename, run
-        # one rule at a time against the same hash it was reading from,
-        # loses data the instant one rule's destination is another
-        # rule's source. Applied sequentially, a swap (`rename :a, to: :b`
-        # alongside `rename :b, to: :a`) on `{a: 1, b: 2}` produces
-        # `{a: 1}` — the first rule writes `b: 1` over the real `b: 2`
-        # before the second rule ever gets a chance to read it, and the
-        # value the whole edge is supposed to preserve (2, moved to
-        # `:a`) is gone. The standard fix: snapshot every rule's old
-        # key and value from `state` first, then remove every old key
-        # and only then write every new key — a rename never reads a
-        # key this same pass has already written to, so a swap or a
-        # longer chain applies as one permutation, not a sequence of
-        # edits each stepping on the last.
+        # Snapshots every rename's old key/value before writing any new key, so a
+        # swap (:a<->:b) applies as one permutation instead of losing data when one
+        # rule's destination is another's source.
         def apply_renames(state, renames)
           snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]] if state.key?(old_name) }
           snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
-          # Not combinable (Style/CombinableLoops is disabled repo-wide, see
-          # .rubocop.yml, for exactly this reason): a swap (:a<->:b) needs
-          # every delete done before any write, or the first rename's write
-          # becomes the second rename's delete target — see this method's
-          # own comment above.
+          # Not combinable: every delete must finish before any write, or a swap's
+          # first write becomes its second delete target.
           snapshot.each { |_old_name, new_name, value| state[new_name] = value }
         end
 
@@ -317,18 +221,7 @@ module Hecks
           end
         end
 
-        # Applies one backfill, dotted-path aware — `apply_drop`'s own
-        # mirror on the addition side. A bare name sets a plain top-level
-        # key, unchanged from before; a dotted name (`"attendee.
-        # first_name"`) reaches into an existing value-object member the
-        # same way `apply_drop`/`hecks_tr_insert` (rule_compiler.rb's own
-        # SQL-compiled twin, kept in step with this) already do — creating
-        # the container Hash if an old record somehow lacks it entirely,
-        # never overwriting a value already there at either level.
-        #
-        # @param state [Hash] the entry's own state Hash, mutated in place
-        # @param backfill [Bluebook::TranslationBackfill] the backfill rule to apply
-        # @return [void]
+        # Dotted-path aware; must stay in step with `hecks_tr_insert` in rule_compiler.rb.
         def apply_backfill(state, backfill)
           name = backfill.name.to_s
           top, member = name.split(".", 2)
@@ -342,17 +235,8 @@ module Hecks
           end
         end
 
-        # A dotted path's first segment is a top-level (symbol) key; a
-        # second segment reaches into a value-object member by its string
-        # key — the spelling a raw stored row carries. Translation runs on
-        # raw rows, before the state codec decodes anything (PR A3): its
-        # only caller (`Translation::Audit::LayerTwo`) feeds it
-        # head-snapshot rows straight out of `JSON.parse`, and the
-        # PostgresEra head applies the same rules in SQL before
-        # `PostgresEra#decode` ever sees the jsonb. Decode is always the
-        # last step, so an undeclared (retired) member this rule has to
-        # read is still exactly as it was written, and never something an
-        # adapter's `entries` — decoded, deep-symbol — would be fed here.
+        # Runs on raw rows, before the state codec decodes anything — decode is
+        # always the last step, so this never sees an adapter's deep-symbolized entry.
         def apply_move(state, move)
           old_top, old_member = move.from.split(".", 2)
           new_top, new_member = move.to.split(".", 2)
@@ -364,9 +248,8 @@ module Hecks
           insert(state, new_top.to_sym, new_member, value, rule: "move #{move.from} to: #{move.to}")
         end
 
-        # A convert is a move whose value has nothing in common with its
-        # replacement — the same path machinery, plus a lookup. A value
-        # with no entry in the table refuses loudly rather than carry an
+        # A convert is a move whose value has nothing in common with its replacement.
+        # A value missing from the lookup table refuses loudly rather than carry an
         # unrecognized value silently into the new era.
         def apply_convert(state, convert)
           old_top, old_member = convert.from.split(".", 2)
@@ -397,18 +280,9 @@ module Hecks
           [value, true]
         end
 
-        # Adversarial finding, not a hypothetical: a destination whose
-        # top segment already holds a value — most commonly a reference,
-        # stored as a bare scalar id — must not be nested under when a
-        # dotted destination needs it (`state[top] ||= {}` alone only
-        # guards nil/false, so a truthy non-Hash sails straight through
-        # to `state[top][member] =`, i.e. `"team-1"["detail"] =`, which
-        # is String#[]=  and raises an unrelated-looking IndexError).
-        # Whether it crashes or silently replaces the value, that is a
-        # `drop` that never declared itself — the one thing this language
-        # exists to make explicit (see apply_convert's own refusal above,
-        # the same shape). Refuse by name instead, on both sides: the SQL
-        # half (hecks_tr_insert) raises the identical wording.
+        # A destination already holding a non-Hash value (e.g. a bare reference id)
+        # must not be silently nested under — that would be an undeclared drop. The
+        # SQL half (`hecks_tr_insert`) refuses with identical wording.
         def insert(state, top, member, value, rule:)
           return state[top] = value unless member