hecks 1.2.0 → 1.4.0

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

@@ -16,24 +16,34 @@ module Hecks
     # historical bluebook text under old grammar defaults. Both are real,
     # independent, currently-shipped consumers.
     #
-    # A prior version of this module ALSO drove its own top-level check —
-    # `check!`/`check_bluebook!`, walking a registry and reading/writing a
-    # held snapshot under `data/eras/*.bluebook` — duplicating, on its own,
-    # the same per-aggregate walk `CoverageCheck` already performs against
-    # `PostgresEra`'s own DB-held shapes. Nothing in production ever called
-    # it (only a direct unit spec did); deleted rather than kept unwired,
-    # per ADR 0032. Wanted again, it's rebuilt informed by `CoverageCheck`'s
-    # real orchestration, not resurrected from here.
+    # 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.
     module EraGuard
       extend ShapeDiff
 
       module_function
 
+      # 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.
+      #
+      # @param registry [Runtime::Registry] the registry whose declared translations are
+      #   searched for a `was:` or a `retired` entry naming the held aggregate
+      # @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
       def check_vanished_aggregates!(registry, bluebook, held_bluebook)
         held_bluebook.aggregates.each do |held_aggregate|
           claimed = bluebook.aggregates.any? do |aggregate|
@@ -54,9 +64,18 @@ module Hecks
         end
       end
 
+      # Raises the refusal naming every changed path no translation rule explains.
+      #
       # The Layer-1 coverage refusal — one wording, shared with whoever
       # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
       # own mint-time coverage check).
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose shape changed
+      # @param uncovered [Array<String>] the unexplained paths, as `uncovered_attributes`
+      #   returns them; must not be empty, since the first one seeds the suggested rule
+      # @return [void] never returns; always raises
+      # @raise [Runtime::WiringError] always, carrying the refusal wording
       def refuse_uncovered!(bluebook, aggregate, uncovered)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \
@@ -65,9 +84,18 @@ module Hecks
               "#{suggestion(uncovered.first)}."
       end
 
+      # Raises the refusal naming every new required attribute an existing record cannot fill.
+      #
       # The addition-side sibling of refuse_uncovered! above — same
       # wording shape, different cause: nothing vanished or changed type,
       # something new arrived that an existing record has no way to hold.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param aggregate [Bluebook::Aggregate] the aggregate that gained the attributes
+      # @param unsafe [Array<Symbol>] the attribute names, as `unsafe_additions` returns them;
+      #   must not be empty, since the first one seeds the suggested `backfill`
+      # @return [void] never returns; always raises
+      # @raise [Runtime::WiringError] always, carrying the refusal wording
       def refuse_unsafe_addition!(bluebook, aggregate, unsafe)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(', ')} " \
@@ -77,8 +105,18 @@ module Hecks
               "`backfill :#{unsafe.first}, default: ...`."
       end
 
+      # Renders a path the way a translation file spells it.
+      #
+      # @param path [String] a bare attribute name or a dotted value-object member path
+      # @return [String] the path quoted (`"price.currency"`) when dotted, otherwise as a
+      #   Symbol literal (`:cost`)
       def render_path(path) = path.include?(".") ? path.inspect : ":#{path}"
 
+      # Proposes the translation rules that would explain one uncovered path.
+      #
+      # @param path [String] a bare attribute name or a dotted value-object member path
+      # @return [String] backticked example rules: `move`/`drop` for a dotted path,
+      #   `rename`/`drop` for a bare name
       def suggestion(path)
         if path.include?(".")
           "`move #{path.inspect}, to: #{path.inspect}` or `drop #{path.inspect}`"
@@ -90,60 +128,79 @@ module Hecks
       # Parses held source into its own IR, in a scratch registry so a past
       # era's text never touches the one actually booting.
       #
-      # NORMAL PARSE FIRST, shadow only as a FALLBACK — not shadow-parsing
-      # unconditionally, which is what this used to do. A handful of DSL
+      # 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 can no longer
+      # that has nothing to do with syntax the live grammar can no longer
       # 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)
-      # changed from `_id`-suffixed to bare under ADR 0025, 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; only the reference-naming DEFAULT differed
-      # once shadow mode engaged unconditionally, so it silently
-      # reconstructed a DIFFERENT shape (and hash) than a fresh parse of
+      # 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
+      # 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
+      # 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 doesn't exist anymore" — fall back to the legacy
-      # grammar, exactly as before this change. Any OTHER exception (a
+      # 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
+      # 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
+      # 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.
+      #
+      # @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
+      # @raise [SyntaxError] if the text is not valid Ruby
       def shadow_parse(source, path)
         parse_bluebook(source, path, shadow: false)
       rescue Hecks::Bluebook::DSL::Malformed
         parse_bluebook(source, path, shadow: true)
       end
 
+      # Evaluates bluebook text once, in a throwaway registry, under one chosen grammar.
+      #
+      # @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
+      # @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
+      # @raise [SyntaxError] if the text is not valid Ruby
       def parse_bluebook(source, path, shadow:)
         scratch = Registry.new
         loading = Ports::Loading.bootstrap

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

@@ -6,41 +6,52 @@ require_relative "storage_shape"
 module Hecks
   module Runtime
     # The refusal wording for a held era whose digest no longer matches its
-    # frozen text — the digest mismatch alone is what DETECTS tampering (a
+    # 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.
     #
-    # LIVES HERE, NOT UNDER `Ports::Persistence` — `project` below directly
+    # 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
+    # runtime is a runtime-owned one that the Postgres adapter calls, not
     # a ports-level module that happens to reach sideways into it.
     #
-    # Used to also distinguish a cosmetic edit from a real shape change
-    # here, by re-parsing the edited text — a pure quality-of-message
-    # nicety, not a safety property, since dropped: every tamper refusal
-    # reaches the same generic wording now, the one this already fell to
-    # whenever it couldn't classify an edit anyway. An operator judges
-    # "did this matter" themselves,
-    # reading the still-archived original — an anomalous recovery moment
-    # already, not a normal boot path.
+    # 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.
     module EraTamper
       module_function
 
+      # Words the boot refusal for a held era text whose digest no longer matches.
+      #
+      # @param domain [String] name of the domain whose era was edited
+      # @param ordinal [Integer] the edited era's ordinal in `hecks_eras`
+      # @return [String] the refusal message, ready to raise as a `Runtime::WiringError`
       def refusal(domain:, ordinal:)
         "cannot boot #{domain}: the held text of era #{ordinal} was edited after it was frozen — " \
           "held era texts are storage facts; restore the original text, or reset the data"
       end
 
-      # The storage-shape projection of a bluebook text, 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.
+      # 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.
+      #
+      # @param text [String] the bluebook source to parse
+      # @param _source_path [String, nil] ignored; the text is always parsed from a tempfile
+      # @return [Hash{String => Object}, nil] `StorageShape.project`'s Hash after a JSON
+      #   round-trip; nil when the text declares no bluebook, or when parsing or projecting
+      #   raises any `StandardError` or `SyntaxError`
       def project(text, _source_path = nil)
         file = Tempfile.new(["hecks-tamper-", ".bluebook"])
         begin

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

@@ -15,9 +15,17 @@ module Hecks
         # `ancestor_name` is the declared name a rename came from (matches
         # the held bluebook's own aggregate names); `ancestor_storage_name`
         # is its derived, snake_case file/table name. Both are nil unless
-        # the aggregate itself was renamed.
+        # the edge declares a `was:` name that differs from the aggregate's own.
         attr_reader :ancestor_name, :ancestor_storage_name
 
+        # Builds the rules of the first declared translation that mentions an aggregate.
+        #
+        # @param registry [Runtime::Registry] the registry whose declared translations are
+        #   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
         def self.for(registry, domain, aggregate)
           translation = registry.translations.find do |candidate|
             candidate.domain == domain.to_s && candidate.for_aggregate(aggregate.name)
@@ -27,9 +35,18 @@ module Hecks
           from_declared(translation.for_aggregate(aggregate.name), aggregate.name)
         end
 
-        # One SPECIFIC edge's rules for one aggregate — what the mint
+        # 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.
+        #
+        # @param declared [Bluebook::TranslationAggregate, nil] the edge's entry for the
+        #   aggregate, as `Bluebook::Translation#for_aggregate` returns it; nil when the edge
+        #   does not mention the aggregate
+        # @param aggregate_name [String, Symbol] the aggregate's current name, compared with
+        #   `declared.was` to decide whether the edge renames the aggregate itself
+        # @return [Ports::Persistence::Lineage, nil] the edge's rules; nil when `declared` is nil
         def self.from_declared(declared, aggregate_name)
           return nil unless declared
 
@@ -43,6 +60,24 @@ 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
         def initialize(renames, moves = [], converts = [], drops = [], retypes: [], computes: [], rekeys: [],
                        backfills: [], ancestor_name: nil, ancestor_storage_name: nil)
           @renames = renames
@@ -57,37 +92,60 @@ module Hecks
           @ancestor_storage_name = ancestor_storage_name
         end
 
-        # Whether any rule in this edge is a compute — 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.
+        # 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.
+        #
+        # @return [Boolean] true when the edge declares at least one compute rule
         def computes? = !@computes.empty?
 
-        # THE SINGLE SOURCE OF TRUTH for "does this edge rekey this
+        # 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`
+        # 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.
+        #
+        # @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).
+        #
+        # @return [String, nil] the first rekey rule's SQL; nil when the edge declares no rekey
         def rekey_sql = @rekeys.first&.sql
 
-        # The reference semantics for the five PORTABLE rule kinds —
+        # 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.
+        #
+        # @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
         def translate(entry)
           return entry unless entry.save? && entry.state
 
-          # Deep, not shallow: a move or convert reaches INTO a nested
+          # Deep, not shallow: a move or convert reaches into a nested
           # value-object hash, and a shallow dup would quietly mutate
           # the caller's copy of the original entry.
           state = deep_dup(entry.state)
@@ -95,24 +153,26 @@ 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
+          # 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.
           @backfills.each { |backfill| state[backfill.name] = backfill.default unless state.key?(backfill.name) }
           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
+        # 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. Used to catch 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.
+        # 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.
         #
-        # `backfills` matches on the WHOLE name only, never a dotted
+        # `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
@@ -121,9 +181,14 @@ module Hecks
         # 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
+        # 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
+        # @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
         # rubocop:disable-next Metrics/PerceivedComplexity
         def explains?(path)
@@ -138,31 +203,36 @@ module Hecks
             @backfills.any? { |backfill| backfill.name.to_s == top }
         end
 
-        # THE DESTINATION-SIDE TWIN of `explains?` above, which only ever
-        # asks about a rule's SOURCE. `unsafe_additions` asks a different
+        # 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
+        # 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
+        # actually applied by this method, the same gap the vanish side
         # already lives with.
         #
-        # `@renames.value?` belongs here too, and used to be missing: 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, which both got their `fills?`
-        # entry from the start), and its absence meant `unsafe_additions`
-        # reported the new name as an unexplained required addition on
-        # EVERY rename-only edge, the single most common translation
-        # shape there is. `explains?` already checked the source side
-        # (`@renames.key?`); `fills?` is the symmetric destination-side
-        # check that was never added alongside it.
+        # `@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
+        # @return [Boolean] true when a rename, move, convert or compute lands a value in that
+        #   attribute, or a backfill names it
         def fills?(path)
           path = path.to_s
 
@@ -173,11 +243,18 @@ module Hecks
             @backfills.any? { |backfill| backfill.name.to_s == path }
         end
 
-        # Whether a declared retype says the pair of TYPE names means the
-        # same shape — a value object or entity whose own name changed
+        # 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.
+        #
+        # @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`
+        # @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 }
         end
@@ -193,25 +270,25 @@ module Hecks
         end
 
         # M27 (docs/audits/2026-08-10-main-bug-audit.md,
-        # docs/audits/2026-08-11-bug-triage.md) — SIMULTANEOUS, not
+        # 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,
+        # 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. A swap (`rename :a, to: :b` alongside
-        # `rename :b, to: :a`) on `{a: 1, b: 2}` used to produce
-        # `{a: 1}` — the first rule wrote `b: 1` over the real `b: 2`
-        # before the second rule ever got a chance to read it, and the
-        # value the whole edge was supposed to preserve (2, moved to
-        # `:a`) was 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
+        # 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.
         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
+          # 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
@@ -236,8 +313,16 @@ module Hecks
         end
 
         # A dotted path's first segment is a top-level (symbol) key; a
-        # second segment reaches into a value-object member, stored with a
-        # string key exactly as the adapter's own journal reader loaded it.
+        # 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.
         def apply_move(state, move)
           old_top, old_member = move.from.split(".", 2)
           new_top, new_member = move.to.split(".", 2)
@@ -282,19 +367,18 @@ 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 — used to be silently clobbered with
-        # an empty hash the moment a dotted destination needed to nest
-        # under it (`state[top] ||= {}` only guards nil/false, so a
-        # truthy non-Hash sailed straight through to `state[top][member] =`,
-        # i.e. `"team-1"["detail"] =`, which is String#[]=  and raised an
-        # unrelated-looking IndexError). Whether it crashed or silently
-        # replaced the value, this 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.
+        # 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.
         def insert(state, top, member, value, rule:)
           return state[top] = value unless member