hecks 1.3.0 → 1.5.0

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
 

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

@@ -11,12 +11,20 @@ module Hecks
         # version, recording a Layer-3 approval, and minting an era's name
         # once (never recomputed after).
         module EraStore
+          # Lists every era the domain holds, oldest first, refusing any whose text was edited.
+          #
           # Every held text is verified against its raw-byte digest on the
           # way out — an edited storage fact refuses rather than silently
-          # reporting "no drift". This is NOT the era name (which hashes
+          # reporting "no drift". This is not the era name (which hashes
           # the canonical projection, minted once, never recomputed): it
-          # is a plain integrity check over bytes, and a row from before
-          # the check existed is backfilled, not refused.
+          # is a plain integrity check over bytes, and a row that carries
+          # no digest yet is backfilled, not refused.
+          #
+          # @return [Array<Hash{Symbol => Object}>] one Hash per era in ordinal order, `[]` when
+          #   the domain holds none; keys are `:ordinal` (Integer), `:hash` and `:label` (String,
+          #   nil until `mint_name!` names the era), `:held_text` (String) and `:watermark`
+          #   (Integer journal ordinal the era was cut at, nil for era 1)
+          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
           def eras
             @db.exec_params(
               "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
@@ -29,8 +37,15 @@ module Hecks
             end
           end
 
+          # Reads one era's stored row without running the integrity check that `eras` applies.
+          #
           # The unverified row — what bin/reattest_era shows an operator
           # after the integrity check fires.
+          #
+          # @param ordinal [Integer] ordinal of the era to read
+          # @return [Hash{Symbol => String, nil}, nil] `:held_text`, `:held_digest` (SHA-256 hex,
+          #   nil if never stored), `:hash` (nil until minted) and `:held_projection` (JSON text,
+          #   nil if never stored); nil when the domain holds no such era
           def raw_era(ordinal)
             rows = @db.exec_params(
               "SELECT held_text, held_digest, hash, held_projection::text FROM hecks_eras WHERE domain = $1 AND ordinal = $2",
@@ -42,10 +57,17 @@ module Hecks
               held_projection: rows[0]["held_projection"] }
           end
 
-          # The recovery path: tamper-EVIDENCE (against accident and
+          # Accepts an era's held text as it now stands, replacing its stored digest.
+          #
+          # The recovery path: tamper-evidence (against accident and
           # drift, not adversaries) gets resolved by a human acknowledging
           # the text as it now stands — recorded in an append-only
-          # attestation table, never by a bare psql UPDATE.
+          # attestation table, never by a bare psql `UPDATE`.
+          #
+          # @param ordinal [Integer] ordinal of the era to re-attest
+          # @return [String] the new SHA-256 hex digest of the held text
+          # @raise [Runtime::WiringError] if the domain holds no era with that ordinal
+          # @raise [PG::Error] if Postgres refuses the attestation DDL or a write
           def reattest!(ordinal)
             era = raw_era(ordinal)
             raise Runtime::WiringError, "#{@domain} holds no era #{ordinal} to re-attest" unless era
@@ -72,6 +94,19 @@ module Hecks
             fresh
           end
 
+          # Checks one held text against its stored digest, storing the digest if the row has none.
+          #
+          # A text that passes (or that had no digest to fail against) also gets
+          # `backfill_frozen_facts!`; a text that fails gets nothing written.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the era's held bluebook source text
+          # @param stored_digest [String, nil] SHA-256 hex digest stored with the row; nil when
+          #   the row carries none yet
+          # @param stored_projection_json [String, nil] the row's stored projection as JSON text;
+          #   nil when the row carries none yet
+          # @return [void]
+          # @raise [Runtime::WiringError] if `stored_digest` is present and does not match `text`
           def verify_integrity!(ordinal, text, stored_digest, stored_projection_json)
             digest = Digest::SHA256.hexdigest(text)
             if stored_digest.nil?
@@ -90,9 +125,17 @@ module Hecks
             raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
           end
 
-          # A verified-authentic text backfills what older rows lack: its
+          # Fills in the archive copy and the stored projection an era row is missing.
+          #
+          # A verified-authentic text backfills what a row may lack: its
           # projection and its archive copy. Never run on a text that
           # failed verification — that would bless the edit.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the era's verified held source text
+          # @param stored_projection_json [String, nil] the row's stored projection as JSON text;
+          #   nil makes this derive one from `text` and store it, unless `text` does not load
+          # @return [void]
           def backfill_frozen_facts!(ordinal, text, stored_projection_json)
             archive_text!(ordinal, text)
             return if stored_projection_json
@@ -107,11 +150,27 @@ module Hecks
             )
           end
 
+          # Reports the ordinal of the newest era the domain holds.
+          #
+          # @return [Integer] the highest held ordinal, or 1 when no era is held yet
+          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]
           end
 
+          # Holds a domain's first source text as era 1 and makes era 1 the writable era.
+          #
+          # Call only while the domain holds no era — every caller checks `eras.empty?` first.
+          # An existing era 1 row is kept (`ON CONFLICT DO NOTHING`), but `advance_era!(1)` runs
+          # regardless, so calling this on a domain past era 1 would roll the write fence back.
+          #
+          # @param text [String] the bluebook source text to freeze as era 1
+          # @param projection [Hash{String => Object}, nil] the storage-shape projection of the
+          #   bluebook, as `Runtime::StorageShape.project` returns it; nil stores none
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert or the policy change, as it does
+          #   for a role that does not own the journal
           def hold_first!(text, projection: nil)
             @db.exec_params(
               "INSERT INTO hecks_eras (domain, ordinal, held_text, held_digest, held_projection) " \
@@ -124,6 +183,15 @@ module Hecks
             advance_era!(1)
           end
 
+          # Copies one version of an era's text into `hecks_era_texts`, keyed by its digest.
+          #
+          # A version already archived is left alone (`ON CONFLICT DO NOTHING`), so every
+          # distinct text an era ever held survives a re-attestation.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the source text to archive
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert
           def archive_text!(ordinal, text)
             @db.exec_params(
               "INSERT INTO hecks_era_texts (domain, ordinal, digest, held_text) VALUES ($1, $2, $3, $4) " \
@@ -132,10 +200,19 @@ module Hecks
             )
           end
 
-          # A Layer-3 approval, recorded IN the database it was reviewed
+          # Records that a human approved a translation edge's audit samples.
+          #
+          # A Layer-3 approval, recorded in the database it was reviewed
           # against — bound to the edge's parsed content and the journal's
           # high-water ordinal at review time. The latest row for a shape
           # pair wins (re-approval supersedes).
+          #
+          # @param from [String] label of the era shape the edge leaves
+          # @param to [String] label of the era shape the edge leads to
+          # @param edge_digest [String] SHA-256 hex digest of the edge's parsed content, as
+          #   `Translation::Audit.edge_digest` computes it
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert
           def record_approval!(from:, to:, edge_digest:)
             @db.exec_params(
               "INSERT INTO hecks_approvals (domain, from_label, to_label, edge_digest, reviewed_ordinal) " \
@@ -144,6 +221,13 @@ module Hecks
             )
           end
 
+          # Finds the most recent approval recorded for the edge between two era shapes.
+          #
+          # @param from [String] label of the era shape the edge leaves
+          # @param to [String] label of the era shape the edge leads to
+          # @return [Hash{Symbol => Object}, nil] `:edge_digest` (String, SHA-256 hex of the edge
+          #   that was reviewed) and `:reviewed_ordinal` (Integer, the journal's highest ordinal at
+          #   review time); nil when no approval is recorded for the pair
           def approval_for(from:, to:)
             rows = @db.exec_params(
               "SELECT edge_digest, reviewed_ordinal FROM hecks_approvals " \
@@ -155,8 +239,16 @@ module Hecks
             { edge_digest: rows[0]["edge_digest"], reviewed_ordinal: rows[0]["reviewed_ordinal"].to_i }
           end
 
-          # Era identity is minted ONCE and stored; nothing ever recomputes
+          # Stores an era's hash and label, only if the era has no hash yet.
+          #
+          # Era identity is minted once and stored; nothing ever recomputes
           # a stored name to verify it.
+          #
+          # @param ordinal [Integer] ordinal of the era to name
+          # @param hash [String] the era's shape hash, SHA-256 hex
+          # @param label [String] the short label edges and refusals use, a prefix of `hash`
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the update
           def mint_name!(ordinal, hash, label)
             @db.exec_params(
               "UPDATE hecks_eras SET hash = $3, label = $4, canon_form = $5 " \
@@ -165,6 +257,9 @@ module Hecks
             )
           end
 
+          # Reads the journal's high-water mark across every era's partition.
+          #
+          # @return [Integer] the highest ordinal in the journal, or 0 when the journal is empty
           def last_ordinal
             @db.exec("SELECT COALESCE(max(ordinal), 0) AS o FROM #{quoted_journal}")[0]["o"].to_i
           end