hecks 1.4.0 → 1.5.1

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

@@ -14,18 +14,33 @@ module Hecks
         include QuerySpecification::Common::DSL
         include WordGate
 
+        # @param name [String] the read model's own name, as written after `read_model`
         def initialize(name)
           @name = name
         end
 
+        # Sets the human-readable description shown for this read model.
+        #
+        # @param value [String] the description text
+        # @return [String] the description as stored
         def description(value)
           # moved to the language: ProjectionText / purpose, on Projection.Declare
           @description = value
         end
 
-        # Renamed from `reference_to` — item #13's full metaprogrammed
-        # dispatch (slice 4b). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Declares the read model's own "one" side — the aggregate head every row projects
+        # around, keyed by its identity.
+        #
+        # Reached through `calls: "reference_to_impl"`. Bootstrap-reachable — the self-hosted
+        # `Bluebook.WholeBluebook` read model declares one — so it's exercised while
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` is still in play, not only afterwards.
+        #
+        # @param type [Module, Symbol, String] the referenced aggregate, written as a bare
+        #   constant
+        # @param as [Symbol, nil] the field name to project the reference under; `nil` derives it
+        #   from the target's own name
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if `reference_to` was already declared
         def reference_to_impl(type, as: nil)
           raise Malformed, "#{@name} already has a projection reference" if @reference_target
 
@@ -33,22 +48,28 @@ module Hecks
           @reference_name   = (as || Naming.snake(@reference_target)).to_sym
         end
 
-        # Order-independent. `many:` is decided by comparing the included type
-        # against the reference target, so this used to refuse an include
-        # declared before the reference — a rule guarding an implementation
-        # limitation rather than a truth about read models. The includes are
-        # collected raw and resolved at build, when the reference is known, so
-        # there is no rule left to enforce.
-        # Renamed from `include`/`group_by` — item #13's full
-        # metaprogrammed dispatch (slice 4c). `include` is bootstrap-
-        # reachable (every core chapter's own `read_model` names which
-        # aggregates it includes with it — a first grep dismissed this
-        # as `Module#include` noise and was wrong; the cold-boot test
-        # after this rename caught it directly), so it's in
-        # BOOTSTRAP_CALLS_FALLBACK; `group_by` is not (no core read_model
-        # groups). The class-level `include WordGate` this file's own
-        # class body uses is `Module#include`, a different receiver,
-        # unaffected by renaming this instance method either way.
+        # Adds one aggregate head this read model projects.
+        #
+        # Order-independent: `many:` is decided by comparing the included type
+        # against the reference target, resolved at build time (when the
+        # reference is known), not at the moment `include` itself runs — so
+        # an include declared before `reference_to` resolves exactly like one
+        # declared after it.
+        #
+        # Reached through `calls: "include_impl"`. Bootstrap-reachable —
+        # every core chapter's own `read_model` names which aggregates it
+        # includes with it — so it's exercised while
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` is still in play.
+        # `group_by_impl`, below, is table-routed the same way but is not
+        # bootstrap-reachable (no core read_model groups). The class-level
+        # `include WordGate` this file's own class body uses is
+        # `Module#include`, a different receiver, unrelated to this
+        # instance method sharing its name.
+        #
+        # @param type [Module, Symbol, String] the included aggregate, written as a bare constant
+        # @param as [Symbol, nil] the field name to project this head's rows under; `nil` derives
+        #   it from the target's own name (pluralized for a many-side head)
+        # @return [void]
         def include_impl(type, as: nil)
           @includes ||= []
           @includes << [Naming.demodulise(type), as]
@@ -96,6 +117,21 @@ module Hecks
         # not this `Struct`) — found directly by reproducing "undefined
         # method `new' for module WhereClause" against a real corpus load,
         # not guessed.
+        #
+        # Records one `WhereClause` per `field => value` pair, targeted at a named many-side
+        # include when this read model has more than one.
+        #
+        # @param positional [Array<Hash{Symbol => Object}>] at most one bare Hash of where
+        #   clauses; in practice always empty, since Ruby routes an ordinary
+        #   `where(field: value)` call entirely into `rest` (see the comment above)
+        # @param on [Module, Symbol, String, nil] the many-side included aggregate these clauses
+        #   apply to; `nil` when this read model has at most one many-side head
+        # @param rest [Hash{Symbol => Object}] `field => value` where clauses; a value is either
+        #   a literal, a Symbol naming a query argument, or a one-pair Hash `{ comparator =>
+        #   operand }` such as `{ gte: :minimum }` — a bare value means `eq`
+        # @return [void]
+        # @raise [ArgumentError] if more than one positional argument is given, or a Hash value
+        #   does not have exactly one pair, or names a comparator outside `COMPARATORS`
         def where_impl(*positional, on: nil, **rest)
           raise ArgumentError, "wrong number of arguments (given #{positional.size}, expected 1)" if positional.size > 1
 
@@ -108,14 +144,36 @@ module Hecks
           end
         end
 
+        # Records the read model's single ordering, replacing any declared earlier.
+        #
+        # @param field [Symbol, String] the field to order by; a dotted path such as
+        #   `:"order.value"` reaches a value object's member
+        # @param direction [Symbol, String] `:asc` or `:desc`
+        # @param on [Module, Symbol, String, nil] the many-side included aggregate this ordering
+        #   applies to; `nil` when this read model has at most one many-side head
+        # @return [QuerySpecification::Common::OrderBy] the ordering just recorded
         def order_by_impl(field, direction = :asc, on: nil)
           @order_by = QuerySpecification::Common::OrderBy.new(field: field, direction: direction, target: resolve_target(on))
         end
 
+        # Records the most rows the targeted collection returns.
+        #
+        # @param value [Integer, Symbol] a literal row count, or a Symbol naming the query
+        #   argument that supplies it
+        # @param on [Module, Symbol, String, nil] the many-side included aggregate this limit
+        #   applies to; `nil` when this read model has at most one many-side head
+        # @return [QuerySpecification::Common::LimitSpec] the limit just recorded
         def limit_impl(value, on: nil)
           @limit = QuerySpecification::Common::LimitSpec.new(value: value, target: resolve_target(on))
         end
 
+        # Records how many matched rows the targeted collection skips before the limit applies.
+        #
+        # @param value [Integer, Symbol] a literal row count, or a Symbol naming the query
+        #   argument that supplies it
+        # @param on [Module, Symbol, String, nil] the many-side included aggregate this offset
+        #   applies to; `nil` when this read model has at most one many-side head
+        # @return [QuerySpecification::Common::OffsetSpec] the offset just recorded
         def offset_impl(value, on: nil)
           @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
         end
@@ -127,6 +185,9 @@ module Hecks
         # `seal_query_options` already enforces for where/order_by/etc
         # applies here too (`seal_group_by`) — grouping is a question
         # about one collection's own rows, same as those are.
+        # @param fields [Array<Symbol>] the eligible many-side head's own fields to nest its rows
+        #   under, one level per field
+        # @return [void]
         def group_by_impl(*fields)
           # Hash rows, `{field:}`, not bare symbols — same shape
           # `aggregate_heads` already uses for exactly the reason it
@@ -168,16 +229,24 @@ module Hecks
         # same shape as `count`, above (a bare, kind-driven coerce-and-
         # assign).
 
-        # `reference_to` is now optional — a read model with no root is a
+        # Assembles the declared references, includes and clauses into a `ReadModel`, after
+        # validating them.
+        #
+        # `reference_to` is optional — a read model with no root is a
         # bulk one: every `include`d head reads its own aggregate whole
         # (no FK match against a root that doesn't exist), and dispatch
-        # takes no id argument at all. This used to be required, on the
-        # assumption a read model was always "one root record's own
-        # cross-aggregate view" — true of every real corpus report so
-        # far, but not a truth about read models themselves: `group_by`'s
-        # own real use (nesting an aggregate's own whole table by its own
-        # field values) has no root to speak of. Still needs to describe
-        # something — zero includes and no reference is refused.
+        # takes no id argument at all. Requiring one would refuse a real,
+        # legitimate shape: `group_by`'s own real use (nesting an
+        # aggregate's own whole table by its own field values) has no root
+        # to speak of. Still needs to describe something — zero includes
+        # and no reference is refused.
+        #
+        # @return [Bluebook::ReadModel] the built read model
+        # @raise [Bluebook::DSL::Malformed] if neither `reference_to` nor any `include` is
+        #   declared, if `where`/`order_by`/`limit`/`offset`/`group_by`/`count`/`median` name an
+        #   `on:` that isn't a many-side include or are left untargeted with more than one
+        #   many-side head, if `count` and `median` are both declared or combined with
+        #   `group_by`, or if `cursor` is declared
         def build
           if !@reference_target && Array(@includes).empty?
             raise Malformed,
@@ -200,6 +269,12 @@ module Hecks
                         count: @count, median_field: @median_field)
         end
 
+        # Evaluates a `read_model` block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the read model's own name
+        # @yield the read model's body, `instance_eval`'d against a new builder
+        # @return [Bluebook::ReadModel] the built read model
+        # @raise [Bluebook::DSL::Malformed] see `#build`
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block

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

@@ -15,9 +15,10 @@ module Hecks
       # 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
+      # ## 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
@@ -28,18 +29,21 @@ module Hecks
       # `invariant`×3, `ensures`×1) before this file existed — extract
       # predicate source, refuse if extraction failed, build the struct.
       #
+      # ## 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
         # wording. `extraction_failure` is the tail of that same
@@ -52,6 +56,22 @@ module Hecks
         # 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)
 
@@ -72,6 +92,11 @@ module Hecks
         # 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
@@ -87,6 +112,11 @@ module Hecks
         # 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
@@ -102,6 +132,13 @@ 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 }
@@ -138,6 +175,14 @@ module Hecks
         # (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]] || {}
@@ -162,6 +207,13 @@ module Hecks
         # real drift between the language's own self-description and
         # 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,6 +140,9 @@ module Hecks
           @computes << TranslationCompute.new(old_path.to_s, to.to_s, sql.to_s)
         end
 
+        # 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,
@@ -101,12 +151,19 @@ 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
 
+        # 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
@@ -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,
@@ -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