hecks 1.3.0 → 1.5.0

data/lib/hecks/projector.rb

@@ -13,28 +13,31 @@ module Hecks
   # working, golden-tested example of the shape every future projector
   # (`:rust`, `:ul`, `:openid`, ...) is meant to follow.
   #
-  # The unit is ONE bluebook's IR, not a whole booted registry — matching
+  # The unit is one bluebook's IR, not a whole booted registry — matching
   # every real projection target (Rust/UL/OIDC all project one domain at
   # a time), and deliberately narrower than `Exporter.call`'s own
   # multi-domain shape.
-  # THREE KINDS OF "PROJECT", TOLD APART BY WHAT THEY NEED AS INPUT.
-  # Only the first belongs in this registry.
   #
-  #   A PROJECTION takes a chapter's DECLARATION and answers something
-  #   that DESCRIBES the domain: its IR, its storage shape, an OIDC scope
+  # ## Three kinds of "project"
+  #
+  # Told apart by what they need as input. Only the first belongs in this
+  # registry.
+  #
+  #   a projection takes a chapter's declaration and answers something
+  #   that describes the domain: its IR, its storage shape, an OIDC scope
   #   manifest, the parser's keyword table, the reference pages. Inert,
   #   derived, and runnable against any chapter that carries what it
   #   declares it needs. These are what `register` holds.
   #
-  #   AN EXPORT takes a declaration AND its BINDINGS and answers
-  #   something that IS the domain, running elsewhere — rust/project.rb's
+  #   an export takes a declaration and its bindings and answers
+  #   something that is the domain, running elsewhere — rust/project.rb's
   #   generated crate, the WASM artifact, the SAM template
   #   bin/project_deploy renders. It needs the `.world`/`.hecksagon` a
   #   projection never looks at, because a running system has to know how
   #   it is wired. That is the whole reason bin/project_deploy cannot use
   #   this protocol: `call(bluebook:, options:)` has no channel for it.
   #
-  #   A STATE PROJECTION takes RECORDS — a domain after dispatch — and is
+  #   a state projection takes records — a domain after dispatch — and is
   #   a read-model question wearing the same word.
   #   `bin/expression_projection` is the one of these: its operators are
   #   not declared anywhere, they are what exists after
@@ -42,8 +45,10 @@ module Hecks
   #   dispatches. Converting it into this registry would be a category
   #   error, however much its name suggests otherwise.
   #
-  # ONE WORD, THREE OTHER MEANINGS — worth naming too, because grepping
-  # "projection" turns all of these up and none is the above:
+  # ## One word, three other meanings
+  #
+  # Worth naming too, because grepping "projection" turns all of these up
+  # and none is the above:
   #
   #   Ports::Projection    read-model catch-up, events folded into state
   #   bin/project          forces that catch-up by hand
@@ -61,14 +66,33 @@ module Hecks
     # deliberately unguarded: a spec re-registering a stub under the same
     # name between examples is the ordinary case, not a footgun to fence
     # against.
+    # Adds `projector` to the registry under `name`, replacing anything
+    # already registered there.
+    #
+    # @param name [String, Symbol] the key `projector` is looked up by (converted to a symbol)
+    # @param projector [Module, Class, #call] anything answering `call(bluebook:, options:)`
+    # @return [void]
     def register(name, projector)
       registry[name.to_sym] = projector
     end
 
+    # Runs the projector registered under `name` against `bluebook`,
+    # after refusing a construct it does not admit.
+    #
     # `bluebook:` is kept as the keyword because it is the shipped
     # spelling and every existing caller uses it — but what it accepts is
     # any construct that emits IR, and `admits!` is what decides whether
-    # THIS target can actually take the one handed over.
+    # this target can actually take the one handed over.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct to project
+    # @param options [Hash] projector-specific options, passed through unchanged
+    # @return [Object] whatever the projector's own `call` returns: typically a
+    #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
+    # @raise [UnknownProjector] if no projector is registered under `name`
+    # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
+    #   projector requires
     def call(name, bluebook:, options: {})
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
@@ -77,16 +101,27 @@ module Hecks
       projector.call(bluebook: bluebook, options: options)
     end
 
-    # A projection names the CAPABILITIES it needs; this refuses a
-    # construct that lacks one, before the projector runs.
+    # Refuses `construct` if it lacks a capability or declared aggregate
+    # `projector` requires. A projection names the capabilities it needs;
+    # this is what enforces that, before the projector runs.
     #
-    # ONE CHECK COVERS BOTH SHAPES. An ordinary construct INCLUDES its
+    # One check covers both shapes. An ordinary construct includes its
     # capabilities and a class-shaped one — Command, Entity, ValueObject
-    # — EXTENDS them, and `is_a?` consults the singleton chain, so it
+    # — extends them, and `is_a?` consults the singleton chain, so it
     # answers for an extended module as readily as an included one. This
     # started as two checks on the assumption it would not; a spec
     # asserting the assumption failed, which is the only reason the
     # redundant half was noticed.
+    #
+    # @param name [String, Symbol] the projector's registered key, used in the message
+    #   when refusing
+    # @param projector [Module, Class, #call] the target being checked; consulted for
+    #   `projection_requires` and `projection_declares` when it answers them
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct offered to the projector
+    # @return [void]
+    # @raise [WrongConstruct] if `construct` lacks a required capability, or the
+    #   chapter it is declares no aggregate the projector needs
     def admits!(name, projector, construct)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
@@ -105,18 +140,38 @@ module Hecks
             "#{construct.name} declares no such aggregate."
     end
 
+    # Tells whether `construct` has the capability `admits!` requires of it.
+    #
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to check
+    # @param capability [Module] the capability module to check for
+    # @return [Boolean] true if `construct` is a `capability`
     def capable?(construct, capability) = construct.is_a?(capability)
 
-    # What KIND of artifact a registered target emits — asked of the
+    # What kind of artifact a registered target emits — asked of the
     # projection rather than inferred from what it returned.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @return [Symbol] `:files` for a path => contents tree, `:artifact` (the
+    #   default, including for an unregistered `name`) for a single Hash or String
     def emits_for(name)
       projector = registry.fetch(name.to_sym) { return :artifact }
       projector.respond_to?(:projection_emits) ? projector.projection_emits : :artifact
     end
 
+    # Tells whether a projector is registered under `name`.
+    #
+    # @param name [String, Symbol] the key to look up
+    # @return [Boolean] true if a projector is registered under `name`
     def registered?(name) = registry.key?(name.to_sym)
+
+    # Lists every key currently registered.
+    #
+    # @return [Array<Symbol>] every key currently registered
     def registered = registry.keys
 
+    # Gives the live registry, initializing it on first use.
+    #
+    # @return [Hash{Symbol => Module, Class, #call}] the live key => projector registry
     def registry
       @registry ||= {}
     end
@@ -126,13 +181,17 @@ module Hecks
     # (`:oidc`). Both resolve here, so the constant form is added
     # surface rather than a replacement — every `Projector.call(:ir, ...)`
     # written before this existed keeps working untouched.
+    #
+    # @param target [String, Symbol, #projection_key] a registered key, or a target
+    #   that declared its own key with `Target#projects_as`
+    # @return [String, Symbol] the key to call the target under
     def key_for(target)
       return target.projection_key if target.respond_to?(:projection_key) && target.projection_key
 
       target
     end
 
-    # WRITING IS THE CALLER'S CHOICE, NOT THE PROJECTOR'S. A projector
+    # Writing is the caller's choice, not the projector's. A projector
     # returns an artifact and never touches disk, which is what lets
     # spec/projector_spec.rb compare `:ir`'s output against a golden
     # fixture without a tmpdir. `out:` is the only thing that writes.
@@ -141,6 +200,11 @@ module Hecks
     # than from inspecting the artifact. A Hash of path => contents and a
     # Hash that simply happens to hold strings are the same object to
     # Ruby; only the projection knows which it meant.
+    #
+    # @param artifact [Hash, String] the projector's output; a file tree when `as: :files`
+    # @param out [String] the path to write to; a directory when `as: :files`
+    # @param as [Symbol] `:files` to write a tree, anything else to write one file
+    # @return [String, Array<String>] the path written, or every path written when `as: :files`
     def write(artifact, out, as: :artifact)
       return write_tree(artifact, out) if as == :files
 
@@ -150,6 +214,10 @@ module Hecks
 
     # Answers the paths written, in the order given — so a caller can
     # report what happened without re-deriving it from the tree.
+    #
+    # @param files [Hash{String => String}] relative path => contents
+    # @param directory [String] the directory to write the tree under
+    # @return [Array<String>] each file's full written path, in `files`' order
     def write_tree(files, directory)
       require "fileutils"
       files.map do |relative, contents|
@@ -178,7 +246,7 @@ Hecks::Projector.register(:docs, Hecks::Projector::DocsProjector)
 Hecks::Projector.register(:narrate, Hecks::Projector::NarrateProjector)
 Hecks::Projector.register(:cli, Hecks::Projector::CliProjector)
 
-# The TARGETS are required from lib/hecks.rb, immediately after this
+# The targets are required from lib/hecks.rb, immediately after this
 # file — deliberately not from here. A target requires this file (it
 # needs `Target` and the registry), so requiring them back from here
 # would close a genuine `circular require considered harmful` loop. Ruby

data/lib/hecks/query_ir.rb

@@ -4,7 +4,7 @@ require_relative "projections/model"
 require_relative "fuzzing/properties"
 
 module Hecks
-  # THE SHARED CORE behind `bin/query_ir` (a text CLI) and
+  # The shared core behind `bin/query_ir` (a text CLI) and
   # `bin/hecks_query_ir_mcp` (an MCP server exposing the same two
   # queries as tools) — one implementation, two front ends, the same
   # reason `Hecks::Codemod` exists once rather than per-script.
@@ -14,7 +14,7 @@ module Hecks
     Codemod    = Hecks::Codemod
     Deviations = Hecks::Projections::Model::Deviations
 
-    # THE SAME MAPPING spec/model_shape_conformance_spec.rb's own
+    # The same mapping spec/model_shape_conformance_spec.rb's own
     # MODEL_CONSTRUCTS holds — kept here rather than shared from the
     # spec (a spec file is not a library other code should require),
     # matching Deviations' own doc comment: "the generator and the gate
@@ -37,6 +37,11 @@ module Hecks
 
     module_function
 
+    # Reads the fields the language declares for one construct kind, from the grammar itself.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Array<Symbol>] the attribute names the self-hosted meta-domain
+    #   grammar declares for `name`
     def meta_declared(name)
       Hecks::Bluebook::MetaValidator.grammar_registry
                                     .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
@@ -44,9 +49,14 @@ module Hecks
 
     # The real structural diff between what a Ruby IR class emits
     # (Class.ir_spec.keys) and what the self-hosted meta-domain declares
-    # for it — the SAME comparison spec/model_shape_conformance_spec.rb
+    # for it — the same comparison spec/model_shape_conformance_spec.rb
     # makes, reusing its own Deviations data so this can never silently
     # drift from what that gate actually checks.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Hash{Symbol => Object}] `:name`, `:declared`, `:emitted`, plus
+    #   `:missing_from_ruby` and `:unaccounted_in_ruby` — each an `Array<Symbol>`
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def construct_diff(name)
       klass = CONSTRUCTS.fetch(name) do
         raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
@@ -54,8 +64,8 @@ module Hecks
       declared = meta_declared(name)
       emitted  = klass.ir_spec.keys
 
-      accounted = declared.reject { |field| Deviations::PARENT_REF.call(field) } -
-                  Deviations::JUDGE_ONLY -
+      accounted = declared.reject { |field| Deviations.parent_ref?(field) } -
+                  Deviations.judge_only(name) -
                   Deviations.folded(name).values.flatten -
                   Deviations.off_the_wire(name) -
                   Deviations.dynamic_tail(name) -
@@ -72,30 +82,38 @@ module Hecks
         missing_from_ruby: accounted - emitted, unaccounted_in_ruby: unaccounted }
     end
 
+    # Diffs one or every construct kind at once.
+    #
+    # @param names [Array<String>] `CONSTRUCTS` keys to diff, every construct when empty
+    # @return [Array<Hash>] one `construct_diff` result per name
     def constructs(names = [])
       targets = names.empty? ? CONSTRUCTS.keys : names
       targets.map { |name| construct_diff(name) }
     end
 
-    # Every given/ensures/invariant DECLARATION reachable from a booted
+    # Every given/ensures/invariant declaration reachable from a booted
     # registry, walked recursively — every owner's own `.preconditions`/
     # `.invariants` (block-declared rules), every value object's own
     # `.invariants`, and every command's own `.givens`/`.ensures`
-    # (`.givens` too, not just `.ensures` — a command's own LOCAL
+    # (`.givens` too, not just `.ensures` — a command's own local
     # `given("x") { block }` not yet hoisted to its owner, round 4's own
     # starting shape, would otherwise be invisible).
     #
-    # NOT keyed by object identity (a real, hard-won correction — see
+    # Not keyed by object identity (a real, hard-won correction — see
     # the comment on `duplicates`' own dedup below for why: a bare
     # `given("x")` reference and its owner's own block declaration are
-    # the SAME Ruby object at DSL build time, but `MetaValidator.call`
-    # (S14 — every bluebook is judged by dispatching its OWN IR into the
+    # the same Ruby object at DSL build time, but `MetaValidator.call`
+    # (S14 — every bluebook is judged by dispatching its own IR into the
     # self-hosted grammar, then reconstructed via `Assembly.call` from
     # flat rows) rebuilds the whole graph fresh from there. By the time
-    # any caller reads `chapter.aggregates`, EVERY given/invariant is
+    # any caller reads `chapter.aggregates`, every given/invariant is
     # already a distinct object, whether it was block-declared or
     # bare-referenced — object identity carries no signal past that
     # point, for any construct, not just this one).
+    #
+    # @param registry [Runtime::Registry] the booted registry to walk
+    # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+    # @return [Array<Rule>]
     def collect_rules(registry, chapter_name = nil)
       rules = []
       chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
@@ -114,7 +132,7 @@ module Hecks
       rules
     end
 
-    # THE RECURSIVE WALK `collect_rules` drives — pulled out of that method
+    # The recursive walk `collect_rules` drives — pulled out of that method
     # (pure extraction, identical traversal and Rule shapes) as its own
     # named, self-recursive method rather than a lambda closing over the
     # same locals. `rules` is the one piece of state every call shares —
@@ -147,17 +165,21 @@ module Hecks
     end
     private_class_method :walk_construct_rules
 
-    # A rule's OWNER — the construct path a "(declared)" location names
+    # A rule's owner — the construct path a "(declared)" location names
     # directly, or (for a command-level `.givens`/`.ensures` entry) the
     # path with its trailing `.CommandName` segment stripped. Two rules
-    # sharing an owner are the SAME declaration read twice (an owner's
+    # sharing an owner are the same declaration read twice (an owner's
     # own precondition, and a command under it referencing that
     # precondition by name) — not two independent ones.
     #
-    # PUBLIC, not a `duplicates`-only internal — `bin/codemod_hoist_
+    # Public, not a `duplicates`-only internal — `bin/codemod_hoist_
     # local_givens` reads it directly to group `collect_rules`' own
     # output by owner itself, the same reading `duplicates`' own
     # `declaration_count` makes.
+    #
+    # @param location [String] a `Rule#location`
+    # @return [String] the owning construct's path, with `" (declared)"` or a trailing
+    #   `.CommandName` segment stripped
     def owner_of(location)
       return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
 
@@ -167,27 +189,33 @@ module Hecks
     # Grouped by (kind, description, canonical), not canonical text
     # alone — a generic one-liner like `!value.to_s.empty?` legitimately
     # recurs dozens of times for unrelated fields; the real signal is
-    # the SAME RULE (same description, same predicate), which is also
+    # the same rule (same description, same predicate), which is also
     # exactly what the given/invariant reference mechanism itself
     # resolves on.
     #
-    # DEDUPED BY OWNER, not object identity (`collect_rules`' own
+    # Deduped by owner, not object identity (`collect_rules`' own
     # comment has the full story — identity is gone by the time this
     # reads the registry). Within a group, every command-level rule
-    # whose OWNER already has its own "(declared)" entry in the same
+    # whose owner already has its own "(declared)" entry in the same
     # group is just that declaration read again through a reference —
     # `Account.Open`/`Account.Credit`/etc. all naming `Account`'s own
-    # `given("customer is active")` count as Account's ONE declaration,
+    # `given("customer is active")` count as Account's one declaration,
     # not nine. A command-level rule with no matching owner declaration
-    # (a LOCAL, not-yet-hoisted `given("x") { block }`) counts as its
+    # (a local, not-yet-hoisted `given("x") { block }`) counts as its
     # own standalone declaration — two different commands independently
-    # writing the identical local predicate IS two declarations, a real
+    # writing the identical local predicate is two declarations, a real
     # hoisting opportunity. A group is reported only when it adds up to
-    # MORE than one real declaration this way.
+    # more than one real declaration this way.
     #
     # `domains: []` means "the self-hosted meta-domain only" — pass real
     # domain directories explicitly to include them, or `nil` (the
     # default) for meta-domain plus every real example.
+    #
+    # @param domains [Array<String>, nil] domain root directories to scan; every real
+    #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
+    # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
+    # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
+    #   `:canonical`, and `:locations` (`Array<String>`)
     def duplicates(domains: nil, include_meta: true)
       domains ||= Codemod::EXAMPLE_ROOTS
       all_rules = []
@@ -210,48 +238,48 @@ module Hecks
       end
     end
 
-    # `given` ONLY (not `invariant`/`ensures`) also covers CROSS-ENTITY
+    # `given` only (not `invariant`/`ensures`) also covers cross-entity
     # coverage — one piece's own entity-level declaration, shared with
-    # any OTHER piece nested under the SAME root aggregate (real corpus
+    # any other piece nested under the same root aggregate (real corpus
     # this closes: SafeDepositBox's own `Visit`/`KeyIssuance`, two
     # different pieces on one head). A rule owned by a nested entity
     # (its own owner path has more than one segment) is covered when
-    # SOME "(declared)" entry exists ANYWHERE under that SAME root
-    # aggregate — not just under its OWN exact owner — matching the
+    # some "(declared)" entry exists anywhere under that same root
+    # aggregate — not just under its own exact owner — matching the
     # DSL's own pool, threaded unchanged through an aggregate's whole
     # entity tree (`AggregateBuilder#entity`'s own comment).
     #
-    # A KNOWN, ACCEPTED GAP this does NOT (and structurally cannot)
-    # close: CHAPTER-WIDE given sharing (`AggregateBuilder#given`'s own
+    # A known, accepted gap this does not (and structurally cannot)
+    # close: chapter-wide given sharing (`AggregateBuilder#given`'s own
     # bare form, `docs/implemented/resolution-rules/chapter-given.md`) — `Account`,
     # `SafeDepositBox`, and `OnboardingCase` each still show as their
-    # own "(declared)" owner here even AFTER `SafeDepositBox`/
+    # own "(declared)" owner here even after `SafeDepositBox`/
     # `OnboardingCase` were converted to bare chapter-wide references,
-    # because a REFERENCED given still write-throughs into its own
-    # aggregate's `@named_givens` — the SAME reason `collect_rules`'
+    # because a referenced given still write-throughs into its own
+    # aggregate's `@named_givens` — the same reason `collect_rules`'
     # own top comment already gives for why object identity carries no
-    # signal past a bluebook's own build: the EXPORTED IR cannot tell
+    # signal past a bluebook's own build: the exported IR cannot tell
     # "I declared this myself" apart from "I referenced someone else's
     # declaration," because by the time anything reads `chapter.
     # aggregates`, both look identical. Closing this would mean reading
-    # SOURCE TEXT (bare `given(desc)` vs. block `given(desc) { ... }`),
+    # source text (bare `given(desc)` vs. block `given(desc) { ... }`),
     # not the built IR this query is deliberately built on — a
     # different, source-level tool, not a fix to this one. Treat a
     # still-flagged group naming multiple aggregates as "verify by
-    # hand whether this is ALREADY a chapter-wide reference before
+    # hand whether this is already a chapter-wide reference before
     # assuming it's fresh duplication," not as an automatic signal
     # either way.
     #
-    # THE IDENTICAL GAP, ONE LEVEL DOWN: chapter-wide ENTITY-scoped
+    # The identical gap, one level down: chapter-wide entity-scoped
     # sharing (`EntityBuilder#given`'s own bare form,
     # `docs/implemented/resolution-rules/chapter-entity-given.md`) hits this same wall for
     # the same structural reason — `SafeDepositBox.Visit` still shows
     # as its own "(declared)" owner here even after becoming a bare
     # reference to `Account.LedgerEntry`'s declaration, because a piece
     # resolving a chapter-wide reference still write-throughs the
-    # resolved `Given` into its own `@named_givens` (so ITS OWN
+    # resolved `Given` into its own `@named_givens` (so its own
     # commands can read it back locally without a second hop). This is
-    # not a NEW limitation this feature introduces — it is the exact
+    # not a new limitation this feature introduces — it is the exact
     # same IR-cannot-distinguish-declared-from-referenced fact, one
     # scope wider. `bin/query_ir duplicates` confirms this directly:
     # `Account.LedgerEntry (declared)` and `SafeDepositBox.Visit
@@ -260,6 +288,9 @@ module Hecks
     # case above, before assuming a group naming two pieces under
     # different aggregates is fresh duplication rather than an already-
     # resolved chapter-wide reference.
+    #
+    # @param rules [Array<Rule>] one duplicate-key group's own rules
+    # @return [Integer] how many of `rules` are real, independent declarations
     def declaration_count(rules)
       declared = rules.select { |r| r.location.end_with?(" (declared)") }
       declared_owners = declared.to_set { |r| owner_of(r.location) }
@@ -278,10 +309,12 @@ module Hecks
     end
     private_class_method :declaration_count
 
-    # SHARED TEXT FORMATTING — both `bin/query_ir` (a text CLI) and
+    # Shared text formatting — both `bin/query_ir` (a text CLI) and
     # `bin/hecks_query_ir_mcp` (an MCP tool result, itself a text
     # block) want the identical human-readable rendering; only the
-    # OUTER framing differs (plain stdout vs. a JSON-RPC content array).
+    # outer framing differs (plain stdout vs. a JSON-RPC content array).
+    # @param diffs [Array<Hash>] `constructs`' own output
+    # @return [String] the human-readable rendering
     def format_constructs(diffs)
       diffs.map do |diff|
         lines = ["== #{diff[:name]} =="]
@@ -303,31 +336,37 @@ module Hecks
       end.join("\n\n")
     end
 
-    # ONE HAND-TYPED CONSTRUCT-NAME PER RECONSTRUCTION METHOD — the only
-    # two `MetaValidator::Reconstruction` methods NOT driven generically
+    # **One hand-typed construct-name per reconstruction method** — the only
+    # two `MetaValidator::Reconstruction` methods not driven generically
     # through `Assembly::Contracts`' own table (its own header explains
     # why: `aggregate(row)`/`entity(row)` predate the table and were
     # never migrated). `impact_preview`'s own touchpoint 4 is checked
-    # ONLY for these two — every other construct is read generically, so
+    # only for these two — every other construct is read generically, so
     # asking "does Command's own reconstruction method mention this
     # field" is a question with no method to check.
     RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
 
-    # THE SIX TOUCHPOINTS `.claude/skills/bluebook-construct-creator/
+    # The six touchpoints `.claude/skills/bluebook-construct-creator/
     # SKILL.md` walks in prose, checked structurally instead of by hand
-    # — for a construct/field pair NOT yet fully propagated (typically
+    # — for a construct/field pair not yet fully propagated (typically
     # mid-round, deciding what's left), or as a sanity check before the
     # final gate sweep of a round already believed done. Every check
-    # here is BEST-EFFORT and ADVISORY, not a gate: a `false` does not
+    # here is best-effort and advisory, not a gate: a `false` does not
     # always mean "not yet done" (a field can be legitimately exempt —
     # `Deviations`' own named categories, `GUARANTEED_BY_CONSTRUCTION`,
     # or `META_DOMAIN_KNOWN_GAPS`, the last of which lives in
-    # spec/fuzzing/meta_domain_coverage_spec.rb, a SPEC file this
+    # spec/fuzzing/meta_domain_coverage_spec.rb, a spec file this
     # module deliberately never requires — see `CONSTRUCTS`' own
     # comment on the same principle). Read the touchpoint's own
     # existing gate (`model_shape_conformance_spec.rb`,
     # `assembly_spec.rb`, `meta_domain_coverage_spec.rb`) before trusting
     # a `false` here as a real gap.
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @param field [String, Symbol] the declared field to check propagation for
+    # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
+    #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
+    #   touchpoint does not apply to `name`)
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def impact_preview(name, field)
       CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}" }
       field = field.to_s
@@ -365,7 +404,7 @@ module Hecks
     # the method's own body ends at the next line indented no deeper
     # than its own `def` — the same boundary Ruby itself uses, read back
     # textually because there is no live AST here, only a file to grep a
-    # slice of. `nil` (not `false`) for every OTHER construct — this
+    # slice of. `nil` (not `false`) for every other construct — this
     # touchpoint genuinely does not apply to them (`RECONSTRUCTION_
     # METHODS` only names the two hand-typed methods), and collapsing
     # "does not apply" into "not done" would misreport a construct that
@@ -402,6 +441,10 @@ module Hecks
     end
     private_class_method :rust_mentions?
 
+    # Renders one field's touchpoint checklist as text.
+    #
+    # @param preview [Hash] `impact_preview`'s own output
+    # @return [String] the human-readable rendering
     def format_impact_preview(preview)
       lines = ["== #{preview[:name]}##{preview[:field]} =="]
       preview[:touchpoints].each do |t|
@@ -421,6 +464,10 @@ module Hecks
       lines.join("\n")
     end
 
+    # Renders the duplicate-rule groups as text.
+    #
+    # @param groups [Array<Hash>] `duplicates`' own output
+    # @return [String] the human-readable rendering
     def format_duplicates(groups)
       return "no duplicate given/invariant/ensures rule found" if groups.empty?
 

data/lib/hecks/query_specification/common/comparators.rb

@@ -7,10 +7,16 @@ module Hecks
   # vocabulary — and .render_value, the wire-rendering entry point
   # shared by every literal-bearing spec struct.
   module QuerySpecification
+    # The vocabulary every query-shaped construct shares — the clause structs
+    # (`WhereClause`, `OrderBy`, `LimitSpec`...), the `DSL` mixin that parses
+    # them, and the comparison and null rules every engine answers by. It is
+    # its own namespace so a plain `Bluebook::Query` and a
+    # `ReadModel::Specification` say one thing the same way rather than each
+    # carrying a copy.
     module Common
       # `none_in_state`, vendored addition not (yet) upstream hecks
-      # (migration plan task 4): a CROSS-AGGREGATE ANTI-JOIN comparator --
-      # `where ref: { none_in_state: "Claim:held" }` holds true when NO
+      # (migration plan task 4): a cross-aggregate anti-join comparator --
+      # `where ref: { none_in_state: "Claim:held" }` holds true when no
       # record in the named aggregate, keyed by this record's own field
       # value, is currently in the named state. plan.bluebook's own
       # description: "a keyed point lookup (HashMap hit), never a scan" --
@@ -20,10 +26,20 @@ module Hecks
       COMPARATORS = Hecks::Vocabulary.symbols("QueryComparator")
     end
 
+    # Renders a literal captured in a query clause as its self-describing
+    # wire spelling, for a spec struct's `to_h`.
+    #
     # The specification structs' own name for the one wire spelling — see
-    # Hecks::Literal, which every other `to_h`-bound literal field now
+    # `Hecks::Literal`, which every other `to_h`-bound literal field
     # shares. Kept as a word here because the structs below read better
     # saying what they are doing than naming the module that does it.
+    #
+    # @param value [nil, Symbol, String, StateRef, Boolean, Integer, Float, Hash, Array] the
+    #   literal as the bluebook author wrote it; Hash values and Array elements are
+    #   rendered recursively
+    # @return [String] the wire text: a Symbol keeps its colon, a String its double quotes,
+    #   and a number, a boolean and `nil` are bare
+    # @raise [ArgumentError] if `value`, or a value nested in it, is of any other class
     def self.render_value(value) = Literal.render(value)
   end
 end