hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -1,55 +1,77 @@
+require_relative "bootstrap_table"
+
 module Hecks
   module Bluebook
     module DSL
-      # THE THREE RESOLUTION PRIMITIVES the S10 given/invariant family's
+      # The three resolution primitives the S10 given/invariant family's
       # own "declared once, referenced by name" mechanism (ADR 0025)
       # reduces to, at every scope this language has grown one so far
       # (a command referencing its owner or a sibling piece's entity-wide
       # pool; an aggregate referencing another aggregate chapter-wide; a
       # value object referencing a sibling value object on the same
-      # aggregate) — extracted here, once, so the NEXT scope this family
+      # aggregate) — extracted here, once, so the next scope this family
       # widens to (there will be one — see docs/resolution-rules/
       # chapter-given.md's own "Known limitations" for two already named)
       # reuses one of these three shapes instead of a fourth hand-written
       # near-duplicate resolver.
       #
-      # NOT ONE UNIFIED ALGORITHM — a real design question this file
-      # answers directly: the THREE existing resolvers are not
-      # superficially different, they are STRUCTURALLY different (a
-      # multi-pool fallback CHAIN; ONE pool keyed by declaring OWNER,
-      # needing disambiguation; a LIVE SCAN over already-built sibling
+      # ## Not one unified algorithm
+      #
+      # A real design question this file answers directly: the three existing
+      # resolvers are not superficially different, they are structurally different (a
+      # multi-pool fallback chain; one pool keyed by declaring owner,
+      # needing disambiguation; a live scan over already-built sibling
       # objects with no separate pool at all) — forcing them into one
       # shape would be a real behavior change (see `#lookup`, below, for
       # which construct uses which), not the pure internal refactor this
-      # module is. `build_rule` is the one piece that WAS genuinely
+      # module is. `build_rule` is the one piece that was genuinely
       # identical across all 7 declaring methods (`given`×3,
       # `invariant`×3, `ensures`×1) before this file existed — extract
       # predicate source, refuse if extraction failed, build the struct.
       #
-      # `#lookup`/`#verify_resolves_via!` read WHICH construct uses which
+      # ## Resolution rules read off the grammar table, not a Ruby-only mirror
+      #
+      # `#lookup`/`#verify_resolves_via!` read which construct uses which
       # primitive off the self-hosted grammar table itself
-      # (`Keyword#resolves_via`, `syntax.bluebook`) — not a Ruby-only
-      # Hash cross-checked afterward (this file's OWN earlier shape, one
-      # round ago) — so a real domain's own boot, not just `bundle exec
-      # rspec`, fails loudly the moment the table and this file's own
+      # (`Keyword#resolves_via`, `syntax.bluebook`), so a real domain's own boot, not just
+      # `bundle exec rspec`, fails loudly the moment the table and this file's own
       # hand-written resolution methods disagree.
       module RuleReference
         module_function
 
+        # Extracts a predicate block's source and builds the rule struct that holds it,
+        # refusing when the source could not be read.
+        #
         # `struct_class` is `Given` or `Invariant` (both `Struct.new(
-        # :description, :canonical, :predicate, keyword_init: true)` —
+        # :description, :canonical, :predicate, :ast, keyword_init: true)` —
         # `Given` lives in command.rb, `Invariant` in value_object.rb).
-        # `owner_name`/`word` are ONLY for the refusal message's own
+        # `owner_name`/`word` are only for the refusal message's own
         # wording. `extraction_failure` is the tail of that same
-        # message, and stays a REQUIRED parameter rather than one
+        # message, and stays a required parameter rather than one
         # hardcoded string on purpose — `given` ("its source could not
         # be read, so no other runtime could ever evaluate it"),
         # `invariant` ("it would be a rule the IR cannot carry"), and
         # `ensures` ("a postcondition is carried as text, and this one
-        # has none") each already had their OWN exact wording before
+        # has none") each already had their own exact wording before
         # this method existed; unifying them into one generic sentence
         # would be a real (if small) behavior change this refactor is
         # not making.
+        #
+        # @param struct_class [Class] the rule struct to build — `Bluebook::Given` or
+        #   `Bluebook::Invariant`
+        # @param description [String] the rule's own description, as declared by the caller's
+        #   own `given`/`invariant`/`ensures` word
+        # @param predicate [Proc] the rule's own body block, never called here — only its
+        #   extracted source is used
+        # @param owner_name [String] the declaring construct's own name, for the refusal message
+        # @param word [String] the declaring word (`"given"`, `"invariant"`, or `"ensures"`),
+        #   for the refusal message
+        # @param extraction_failure [String] the refusal message's own tail, naming what an
+        #   unreadable predicate would mean for this particular word
+        # @return [Bluebook::Given, Bluebook::Invariant] the built rule struct, an instance of
+        #   `struct_class`
+        # @raise [Bluebook::DSL::Malformed] if `predicate`'s source could not be extracted, or
+        #   it matches against a pattern construct `Expression::AstJson::PatternSubset` refuses
         def build_rule(struct_class, description, predicate, owner_name:, word:, extraction_failure:)
           canonical = Ports::Extraction.canonical(predicate)
 
@@ -64,35 +86,45 @@ module Hecks
           struct_class.new(description: description, canonical: canonical, predicate: predicate, ast: ast)
         end
 
-        # PRIMITIVE 1 — an ORDERED CHAIN of flat `Hash[description] =>
+        # Primitive 1 — an ordered chain of flat `Hash[description] =>
         # Rule` pools, first match wins. `CommandBuilder#given`'s own
-        # two-pool shape (its OWN owner's `named_givens`, then a sibling
+        # two-pool shape (its own owner's `named_givens`, then a sibling
         # piece's entity-wide pool) is this with a 2-element chain — a
         # future single-pool bare reference is the same primitive with a
         # 1-element chain, not a separate "just look in one hash" method.
+        # @param pools [Array<Hash{String => Bluebook::Given, Bluebook::Invariant}>] pools to
+        #   search in order; the first pool holding `description` wins
+        # @param description [String] the rule's own description to find
+        # @return [Bluebook::Given, Bluebook::Invariant, nil] the matching rule, or `nil` if no
+        #   pool has one
         def resolve_hash_chain(pools, description)
           pools.each { |pool| return pool[description] if pool.key?(description) }
           nil
         end
 
-        # PRIMITIVE 2 — ONE pool keyed BY DECLARING OWNER,
+        # Primitive 2 — one pool keyed by declaring owner,
         # `Hash[description][owner] => Rule` — `AggregateBuilder#given`'s
         # own chapter-wide shape, the only construct so far where the
-        # SAME description can mean two genuinely different predicates
+        # same description can mean two genuinely different predicates
         # (docs/implemented/resolution-rules/chapter-given.md). Returns the full
-        # candidates Hash (0, 1, or many entries) — deliberately NOT
+        # candidates Hash (0, 1, or many entries) — deliberately not
         # raising here, so each caller keeps its own exact refusal
         # wording for "none," "ambiguous," and "declared_by: named the
         # wrong owner" rather than one generic message papering over all
         # three.
+        # @param pool [Hash{String => Hash{String => Bluebook::Given, Bluebook::Invariant}}]
+        #   descriptions mapped to their own candidates, each keyed by declaring owner
+        # @param description [String] the rule's own description to find
+        # @return [Hash{String => Bluebook::Given, Bluebook::Invariant}] the candidates for
+        #   `description`, keyed by declaring owner; empty when none exist
         def resolve_owner_keyed(pool, description)
           pool[description] || {}
         end
 
-        # PRIMITIVE 3 — a LIVE SCAN over already-built SIBLING OBJECTS'
+        # Primitive 3 — a live scan over already-built sibling objects'
         # own collections, not a separately-maintained pool at all —
         # `ValueObjectBuilder#invariant`'s own shape: every sibling value
-        # object on the same aggregate has ALREADY been built by the time
+        # object on the same aggregate has already been built by the time
         # a later one references back (declaration order, the same
         # constraint every scope in this family carries), so there is
         # nothing to write through — just read their own already-declared
@@ -100,42 +132,57 @@ module Hecks
         # sibling (`:invariants` today; kept a parameter, not hardcoded,
         # since a future sibling-scan scope might reference a different
         # collection).
+        # @param siblings [Array<Object>] the already-built sibling objects to scan; each must
+        #   respond to `reader`
+        # @param description [String] the rule's own description to find
+        # @param reader [Symbol] the method to call on each sibling to read its own rule
+        #   collection, such as `:invariants`
+        # @return [Bluebook::Given, Bluebook::Invariant, nil] the matching rule, or `nil` if no
+        #   sibling declares one
         def resolve_sibling_scan(siblings, description, reader:)
           siblings.flat_map { |sibling| sibling.public_send(reader) }
                   .find { |rule| rule.description == description }
         end
 
-        # WHICH CONSTRUCT USES WHICH PRIMITIVE — no longer a Ruby-only
-        # Hash (that WAS this constant's own shape, one round ago): the
+        # **Which construct uses which primitive** — no longer a Ruby-only
+        # Hash (that was this constant's own shape, one round ago): the
         # user's own correction — "my goal is that if they read the same
         # table they behave identically" — means a table only Ruby ever
         # reads cannot deliver that, no matter how faithfully it is
         # cross-checked afterward. `Keyword#resolves_via`/`#disambiguator`
-        # (self-hosted, `syntax.bluebook`) is the REAL table now — the
-        # SAME generated data `rust/parser/src/keywords.rs` is generated
+        # (self-hosted, `syntax.bluebook`) is the real table now — the
+        # same generated data `rust/parser/src/keywords.rs` is generated
         # from (`bin/project_parser_table`). `#lookup` reads it live.
         #
-        # THE ONE UNAVOIDABLE EXCEPTION: the meta-domain's own bootstrap
+        # **The one unavoidable exception**: the meta-domain's own bootstrap
         # (`MetaValidator.load_grammar_into`) dispatches `given`/
-        # `invariant` on ITSELF 61 times while building the very grammar
+        # `invariant` on itself 61 times while building the very grammar
         # table that would answer "how does given/Aggregate resolve" —
         # `MetaValidator.grammar_registry`/`SyntaxBoot.call` are not
-        # ready yet, and cannot be made ready without ALREADY having
+        # ready yet, and cannot be made ready without already having
         # resolved a `given` somewhere upstream. `MetaValidator.
-        # bootstrapping?` is the SAME guard `MetaValidator.call` (the
+        # bootstrapping?` is the same guard `MetaValidator.call` (the
         # judge) already uses to skip self-judging during this exact
         # window — `#lookup` uses it too, falling back to
-        # `BOOTSTRAP_FALLBACK` (below) ONLY while it's true. Every REAL
+        # `BOOTSTRAP_FALLBACK` (below) only while it's true. Every real
         # domain (banking, pizzas, compliance, any future one) boots
-        # AFTER `grammar_registry` is fully built and memoized, so reads
+        # after `grammar_registry` is fully built and memoized, so reads
         # the real table, every time, no exception.
-        BOOTSTRAP_FALLBACK = {
-          %w[given Aggregate]       => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
-          %w[given Entity]          => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
-          %w[given Command]         => { resolves_via: "hash_chain" },
-          %w[invariant ValueObject] => { resolves_via: "sibling_scan" }
-        }.freeze
+        #
+        # No longer kept in sync by hand — the same `resolves_via`/
+        # `disambiguator` columns, projected ahead of time into the
+        # committed lib/hecks/bluebook/dsl/bootstrap_table.rb
+        # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).
+        BOOTSTRAP_FALLBACK = BootstrapTable::RESOLVES
 
+        # Reads how a (word, context) pair resolves its rule references, off the self-hosted
+        # grammar table itself (or, while that table is still booting, the projected fallback).
+        #
+        # @param word [String] the DSL word, such as `"given"` or `"invariant"`
+        # @param context [String] the grammar context, such as `"Aggregate"`
+        # @return [Hash{Symbol => String, nil}] `:resolves_via` and `:disambiguator` for this
+        #   (word, context) pair, `nil`-valued when the row leaves either blank, or `{}` if no row
+        #   matches at all
         def lookup(word, context)
           if MetaValidator.bootstrapping?
             BOOTSTRAP_FALLBACK[[word, context]] || {}
@@ -149,17 +196,24 @@ module Hecks
           end
         end
 
-        # A LIVE CROSS-CHECK, not a spec-only one — every REAL domain's
+        # A live cross-check, not a spec-only one — every real domain's
         # own boot (not just `bundle exec rspec`) now genuinely fails
         # loudly if a construct's own hand-written resolution method
         # ever disagrees with what the self-hosted grammar table claims
         # for it. Each of the three `reference_named_*` methods below
-        # calls this FIRST, naming the primitive it is ABOUT to use —
+        # calls this first, naming the primitive it is about to use —
         # if `syntax.bluebook`'s own `resolves_via` for this exact
         # (word, context) pair ever names something else, this is a
         # real drift between the language's own self-description and
-        # its own implementation, caught at the next boot of ANYTHING,
+        # its own implementation, caught at the next boot of anything,
         # not just the next `rspec` run.
+        # @param word [String] the DSL word, such as `"given"` or `"invariant"`
+        # @param context [String] the grammar context, such as `"Aggregate"`
+        # @param expected_primitive [String] the resolution primitive's own name the caller is
+        #   about to use, such as `"hash_chain"`, `"owner_keyed"`, or `"sibling_scan"`
+        # @return [void]
+        # @raise [RuntimeError] if `syntax.bluebook`'s own `resolves_via` for this (word, context)
+        #   pair names something other than `expected_primitive`
         def verify_resolves_via!(word, context, expected_primitive)
           actual = lookup(word, context)[:resolves_via]
           return if actual == expected_primitive

data/lib/hecks/bluebook/dsl/translation_builder.rb

@@ -13,6 +13,9 @@ module Hecks
 
         include WordGate
 
+        # @param name [String, Symbol] the aggregate's name in the destination era
+        # @param was [String, Symbol, nil] the aggregate's earlier name, when renamed
+        # @raise [Bluebook::DSL::Malformed] if `name` is empty
         def initialize(name, was: nil)
           raise Malformed, "an aggregate translation needs a name" if name.to_s.empty?
 
@@ -28,14 +31,23 @@ module Hecks
           @backfills = []
         end
 
-        # RENAMED FROM `rename`/`move`/`convert`/`retype`/`compute`/
-        # `rekey`/`backfill` (all seven below) — item #13's full
-        # metaprogrammed dispatch (slice 4c). Not bootstrap-reachable
-        # (translation.bluebook describes ITS OWN structure with
-        # aggregate/entity/attribute, never with these — they're
-        # words for real, user-authored `.translation` files only,
-        # loaded after the grammar table exists), so none need a
-        # BOOTSTRAP_CALLS_FALLBACK entry.
+        # Declares a field rename with no other change: same path, new name.
+        #
+        # Answers the `rename` word (and, via the same table rows, its
+        # siblings `move`/`convert`/`retype`/`compute`/`rekey`/`backfill`
+        # below) through the table's `calls:` column — item #13's full
+        # metaprogrammed dispatch (slice 4c). Each is carried in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` like every other
+        # `calls:`-routed word, but none of their rows are ever consulted
+        # during real bootstrap: `translation.bluebook` describes its own
+        # structure with aggregate/entity/attribute, never with these —
+        # they're words for real, user-authored `.translation` files
+        # only, loaded after the grammar table already exists.
+        #
+        # @param old_name [Symbol, String] the field's name in the held era
+        # @param to [Symbol, String] the field's name in the destination era
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if `old_name` or `to` is empty
         def rename_impl(old_name, to:)
           raise Malformed, "a rename needs a source name" if old_name.to_s.empty?
           raise Malformed, "a rename needs a destination name (to:)" if to.to_s.empty?
@@ -43,6 +55,13 @@ module Hecks
           @renames[old_name.to_sym] = to.to_sym
         end
 
+        # Declares a field moved to a different path, name unchanged.
+        #
+        # @param old_path [String, Symbol] the field's path in the held era; dotted reaches a
+        #   value-object member
+        # @param to [String, Symbol] the field's path in the destination era
+        # @return [Array<Bluebook::TranslationMove>] every move declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `old_path` or `to` is empty
         def move_impl(old_path, to:)
           raise Malformed, "a move needs a destination path (to:)" if to.to_s.empty?
           raise Malformed, "a move needs a source path" if old_path.to_s.empty?
@@ -50,10 +69,21 @@ module Hecks
           @moves << TranslationMove.new(old_path.to_s, to.to_s)
         end
 
+        # Declares an exhaustive value-to-value mapping for a field with nothing structural in
+        # common with its replacement.
+        #
         # A value with nothing structural in common with its replacement
         # — declared as an exhaustive table, not computed, so every value
         # that can appear in old data has a named destination. Paths
         # follow `move`'s convention: dotted reaches a value-object member.
+        #
+        # @param old_path [String, Symbol] the field's path in the held era
+        # @param to [String, Symbol] the field's path in the destination era
+        # @param values [Hash] every old value mapped to its destination value
+        # @return [Array<Bluebook::TranslationConvert>] every convert declared so far, this one
+        #   last
+        # @raise [Bluebook::DSL::Malformed] if `old_path` or `to` is empty, or `values` is nil
+        #   or empty
         def convert_impl(old_path, to:, values:)
           raise Malformed, "a convert needs a destination path (to:)" if to.to_s.empty?
           raise Malformed, "a convert needs a source path" if old_path.to_s.empty?
@@ -70,10 +100,18 @@ module Hecks
         # coerce-and-append with nothing else, now executed by
         # `GenericDispatch`.
 
+        # Declares that a type's name changed while its member structure stayed the same.
+        #
         # A value object's or entity's own type name changed, member
         # structure unchanged. The stored data never carries the type
         # name, so nothing moves — this declares that the pair of names
         # means the same shape, which is what lets the era diff accept it.
+        #
+        # @param old_type [String, Symbol] the type's name in the held era
+        # @param to [String, Symbol] the type's name in the destination era
+        # @return [Array<Bluebook::TranslationRetype>] every retype declared so far, this one
+        #   last
+        # @raise [Bluebook::DSL::Malformed] if `old_type` or `to` is empty
         def retype_impl(old_type, to:)
           raise Malformed, "a retype needs a source type name" if old_type.to_s.empty?
           raise Malformed, "a retype needs a destination type name (to:)" if to.to_s.empty?
@@ -81,10 +119,19 @@ module Hecks
           @retypes << TranslationRetype.new(old_type.to_s, to.to_s)
         end
 
+        # Declares a field computed by a hand-written Postgres SQL expression.
+        #
         # A computed transform whose only implementation is the SQL
         # expression itself — Postgres-only by construction. The scaffold
         # never proposes one; a human writes it, and the audit's
         # human-sampled review is its only verification.
+        #
+        # @param old_path [String, Symbol] the source field's path in the held era
+        # @param to [String, Symbol] the field's path in the destination era
+        # @param sql [String] the Postgres SQL expression computing the destination value
+        # @return [Array<Bluebook::TranslationCompute>] every compute declared so far, this one
+        #   last
+        # @raise [Bluebook::DSL::Malformed] if `old_path`, `to`, or `sql` is empty
         def compute_impl(old_path, to:, sql:)
           raise Malformed, "a compute needs a destination path (to:)" if to.to_s.empty?
           raise Malformed, "a compute needs a source path" if old_path.to_s.empty?
@@ -93,7 +140,10 @@ module Hecks
           @computes << TranslationCompute.new(old_path.to_s, to.to_s, sql.to_s)
         end
 
-        # THE AGGREGATE'S OWN IDENTITY, changing what it's computed from —
+        # Declares a hand-written Postgres SQL expression that recomputes the aggregate's own
+        # identity.
+        #
+        # The aggregate's own identity, changing what it's computed from —
         # not a field crossing a boundary (`move`), not a value's own
         # transform (`compute`): the record's key. No path arguments,
         # unlike every rule above — nothing is consumed from or moved into
@@ -101,14 +151,21 @@ module Hecks
         # SQL-only, Postgres-only, human-reviewed-sample-is-the-only-
         # verification shape `compute` already has, and for the same
         # reason: there is nothing in-process to check this against.
+        #
+        # @param sql [String] the Postgres SQL expression computing the destination identity
+        # @return [Array<Bluebook::TranslationRekey>] every rekey declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `sql` is empty
         def rekey_impl(sql:)
           raise Malformed, "a rekey needs its sql: expression" if sql.to_s.empty?
 
           @rekeys << TranslationRekey.new(sql.to_s)
         end
 
-        # A NEWLY ADDED, required attribute — the addition-side sibling of
-        # `drop`. Nothing to rename, move, or convert FROM, since old data
+        # Declares a newly added, required attribute and the default existing records read
+        # until a real value is written.
+        #
+        # A newly added, required attribute — the addition-side sibling of
+        # `drop`. Nothing to rename, move, or convert from, since old data
         # never held this field at all; `default` is what an existing
         # record reads until the next command against it writes a real
         # value. Adapter-agnostic, unlike `compute` — applied the same
@@ -118,6 +175,12 @@ module Hecks
         # `EraGuard.refuse_unsafe_addition!` asks for when a non-optional
         # attribute with no default: could leave an existing record with
         # the field genuinely absent.
+        #
+        # @param name [String, Symbol] the new attribute's name
+        # @param default [Object] the value an existing record reads until it is written for real
+        # @return [Array<Bluebook::TranslationBackfill>] every backfill declared so far, this
+        #   one last
+        # @raise [Bluebook::DSL::Malformed] if `name` is empty or `default` is nil
         def backfill_impl(name, default:)
           raise Malformed, "a backfill needs a name" if name.to_s.empty?
           raise Malformed, "a backfill needs a default: value" if default.nil?
@@ -125,33 +188,46 @@ module Hecks
           @backfills << TranslationBackfill.new(name.to_sym, default)
         end
 
+        # Always refuses to boot: marks a field the scaffold could not decide a rule for.
+        #
         # The scaffold writes this where it cannot decide; a file carrying
         # one can only boot into this refusal — never a guess.
         #
-        # RENAMED FROM `unresolved` — item #13's full metaprogrammed
+        # Answers the `unresolved` word through the table's `calls:`
+        # column — item #13's full metaprogrammed
         # dispatch (slice 4). Builds its own message with real branching
         # (empty vs. named candidates, a special :identity case), not a
-        # fixed string a boolean `refuses:` flag could express — reached
-        # through `calls:` instead, like `attribute`/`role`. NOT
-        # bootstrap-reachable: translation.bluebook (loaded during
-        # bootstrap, to describe the translation DSL itself) never
-        # writes `unresolved` — that word is only ever used by real,
-        # user-authored `.translation` files, loaded well after the
-        # grammar table exists — so no BOOTSTRAP_CALLS_FALLBACK entry is
-        # needed here (checked directly, not assumed).
+        # fixed string a boolean `refuses:` flag could express. Carried in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` like every other
+        # `calls:`-routed word, but that row is never consulted during
+        # real bootstrap (checked directly, not assumed):
+        # translation.bluebook (loaded during bootstrap, to describe the
+        # translation DSL itself) never writes `unresolved` — that word is
+        # only ever used by real, user-authored `.translation` files,
+        # loaded well after the grammar table already exists.
+        #
+        # @param name [String, Symbol] the unresolved field's name, or `:identity` for an
+        #   unresolved identity change
+        # @param candidates [Array<String, Symbol>] paths the scaffold considered but could not
+        #   choose between; empty when it found none
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] always
         def unresolved_impl(name, candidates: [])
           raise Malformed, unresolved_message(name, candidates)
         end
 
-        # `method_missing`/`respond_to_missing?` used to be hand-written
-        # here, giving a hand-typed "must be rename, move, convert, ..."
-        # list on every genuinely undefined call — WordGate (`include`d
-        # above) now answers the same question off the self-hosted
-        # grammar table instead, the exact "hardcoded legal-word list"
-        # this whole arc's item #13 exists to close. A word admitted
-        # elsewhere in the grammar but not in this context still gets a
-        # richer, table-driven refusal than the old generic one did.
+        # `method_missing`/`respond_to_missing?` answer off the self-hosted
+        # grammar table (via the `include`d `WordGate`, above), giving a
+        # richer, table-driven "must be rename, move, convert, ..." refusal
+        # on a genuinely undefined call than a hand-typed list could —
+        # the exact "hardcoded legal-word list" this whole arc's item #13
+        # exists to close. A word admitted
+        # elsewhere in the grammar but not in this context still gets that
+        # richer refusal.
 
+        # Assembles the declared rules into a `TranslationAggregate`.
+        #
+        # @return [Bluebook::TranslationAggregate] the built per-aggregate translation
         def build
           TranslationAggregate.new(
             name: @name, was: @was, renames: @renames, moves: @moves, converts: @converts,
@@ -178,7 +254,7 @@ module Hecks
           path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
         end
 
-        # THE SCAFFOLD'S OWN HINT for the one drift it can detect but never
+        # The scaffold's own hint for the one drift it can detect but never
         # resolve on its own — an aggregate's `identified_by` changed. Not
         # a field to rename/move/drop, so none of the ordinary hints fit;
         # `coverage_check.rb#check_identity_unchanged!` is the real gate,
@@ -199,6 +275,10 @@ module Hecks
 
         include WordGate
 
+        # @param domain [String, Symbol] the domain this translation carries forward
+        # @param from [String, Symbol] the origin era
+        # @param to [String, Symbol] the destination era
+        # @raise [Bluebook::DSL::Malformed] if `domain`, `from`, or `to` is empty
         def initialize(domain, from:, to:)
           raise Malformed, "a translation names no domain" if domain.to_s.empty?
           raise Malformed, "#{domain}'s translation says nothing about its origin era (from:)" if from.to_s.empty?
@@ -211,38 +291,64 @@ module Hecks
           @retired    = []
         end
 
-        # RENAMED FROM `aggregate` — item #13's full metaprogrammed
+        # Declares one aggregate's own translation rules.
+        #
+        # Answers the `aggregate` word through the table's `calls:`
+        # column — item #13's full metaprogrammed
         # dispatch (slice 4c). Not bootstrap-reachable — this "Translation"
         # -context `aggregate` (opens a TranslationAggregateBuilder) is a
         # different (context, word) pair than "Bluebook"-context
         # `aggregate` (the one translation.bluebook itself is described
-        # with), so it's never used to describe the language's own
+        # with), so it never describes the language's own
         # translation chapter.
+        #
+        # @param name [String, Symbol] the aggregate's name in the destination era
+        # @param was [String, Symbol, nil] the aggregate's earlier name, when renamed
+        # @yield the aggregate's own translation body, evaluated against a
+        #   `TranslationAggregateBuilder`
+        # @return [Array<Bluebook::TranslationAggregate>] every aggregate translation declared
+        #   so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `name` is empty, or any rule in the body fails
+        #   its own checks
         def aggregate_impl(name, was: nil, &block)
           builder = TranslationAggregateBuilder.new(name, was: was)
           builder.instance_eval(&block) if block
           @aggregates << builder.build
         end
 
-        # `retired` — item #13's full metaprogrammed dispatch, slice 2
-        # (whole-project table-unification survey): an aggregate that is
-        # gone outright — not renamed. The deliberate alternative to a
-        # bogus `was:` claim on an unrelated aggregate. Same shape
-        # `TranslationAggregateBuilder#drop` is, now executed by
-        # `GenericDispatch`.
-
-        # `method_missing`/`respond_to_missing?` — same removal as
-        # TranslationAggregateBuilder's own, one level up: WordGate
-        # (`include`d above) answers off the self-hosted grammar table
-        # now instead of a hand-typed "it declares aggregate blocks and
-        # retired aggregates" message.
-
+        # `retired` (an aggregate that is gone outright, not renamed — the
+        # deliberate alternative to a bogus `was:` claim on an unrelated
+        # aggregate, the same shape `TranslationAggregateBuilder#drop` is)
+        # is executed straight off the grammar table by `GenericDispatch` —
+        # item #13's full metaprogrammed dispatch, slice 2 (whole-project
+        # table-unification survey) — so no hand-written method answers it here.
+
+        # `method_missing`/`respond_to_missing?` answer off the self-hosted
+        # grammar table (via the `include`d `WordGate`, above, the same
+        # mechanism `TranslationAggregateBuilder`'s own comment describes
+        # one level up) instead of a hand-typed "it declares aggregate
+        # blocks and retired aggregates" message.
+
+        # Assembles the declared era pair, aggregates and retirements, judged by the translation
+        # language.
+        #
+        # @return [Bluebook::Translation] the translation, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the translation language refuses the declaration
         def build
           MetaValidator.call_translation(
             Translation.new(domain: @domain, from: @from, to: @to, aggregates: @aggregates, retired: @retired)
           )
         end
 
+        # Evaluates a `.translation` file's top-level block against a fresh builder.
+        #
+        # @param domain [String, Symbol] the domain this translation carries forward
+        # @param from [String, Symbol] the origin era
+        # @param to [String, Symbol] the destination era
+        # @yield the translation body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Translation] the judged translation
+        # @raise [Bluebook::DSL::Malformed] if the body fails any check, or the translation
+        #   language refuses the declaration
         def self.build(domain, from:, to:, &block)
           builder = new(domain, from: from, to: to)
           builder.instance_eval(&block) if block