hecks 1.2.0 → 1.4.0

data/lib/hecks/projector.rb

@@ -13,28 +13,28 @@ 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.
+  # 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
+  #   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,7 +42,7 @@ 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
+  # **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
@@ -68,7 +68,7 @@ module Hecks
     # `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.
     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,12 +77,12 @@ module Hecks
       projector.call(bluebook: bluebook, options: options)
     end
 
-    # A projection names the CAPABILITIES it needs; this refuses a
+    # A projection names the capabilities it needs; this refuses a
     # construct that lacks one, 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
@@ -107,7 +107,7 @@ module Hecks
 
     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.
     def emits_for(name)
       projector = registry.fetch(name.to_sym) { return :artifact }
@@ -132,7 +132,7 @@ module Hecks
       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.
@@ -178,7 +178,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
@@ -44,7 +44,7 @@ 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.
     def construct_diff(name)
@@ -54,8 +54,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) -
@@ -77,22 +77,22 @@ module Hecks
       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).
@@ -114,7 +114,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,14 +147,14 @@ 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.
@@ -167,23 +167,23 @@ 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
@@ -210,48 +210,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
@@ -278,10 +278,10 @@ 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).
     def format_constructs(diffs)
       diffs.map do |diff|
         lines = ["== #{diff[:name]} =="]
@@ -303,26 +303,26 @@ 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`,
@@ -365,7 +365,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

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

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

@@ -4,7 +4,7 @@ require_relative "../../runtime/value"
 module Hecks
   module QuerySpecification
     module Common
-      # THE ONE COMPARATOR TABLE. There were two, near-identical copies of
+      # **The one comparator table**. There were two, near-identical copies of
       # this — `Ports::Query::InMemory` (the path a Memory- or Heki-backed
       # aggregate query actually runs) and `Runtime::QueryInterpreter`
       # (entity/sub-list queries, and any adapter implementing no `:query`)
@@ -15,23 +15,25 @@ module Hecks
       # real bugs twice already, both recorded in the comments those files
       # carried. `none_in_state` was added to one copy only, so an ordinary
       # Memory query's `none_in_state` clause fell to the `else` branch and
-      # silently excluded every row. And `comparable` DIVERGED without
-      # anyone noticing: one copy took the FIRST numeric member of a value
-      # object, the other only unwrapped when there was EXACTLY ONE — so a
+      # silently excluded every row. And `comparable` diverged without
+      # anyone noticing: one copy took the first numeric member of a value
+      # object, the other only unwrapped when there was exactly one — so a
       # value object with two numeric members compared as a number on one
       # path and as a whole Hash on the other.
       #
-      # The callers still differ in how they REACH a value — one takes a
+      # The callers still differ in how they reach a value — one takes a
       # registry argument, the other closes over `@registry`; one digs the
       # field through `FieldPath`, the other is handed it — so they keep
       # their own resolution and share only the comparison itself.
       module Comparison
         module_function
 
+        # Unwraps a value object to the one scalar a comparison can mean.
+        #
         # A value object compared as a scalar, when which scalar is meant
         # is not in doubt. Exactly one numeric member is unambiguous; a
         # single-member value object is unambiguous whatever its type.
-        # Anything else is returned UNCHANGED rather than guessed at — two
+        # Anything else is returned unchanged rather than guessed at — two
         # numeric members give no reason to prefer either, and picking the
         # first silently compares a field the author never named.
         #
@@ -40,6 +42,11 @@ module Hecks
         # so this branch is a backstop rather than the primary guard: which
         # member is meant is knowable at declaration time, and a refusal
         # naming the candidates is worth more than any runtime reading.
+        #
+        # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
+        #   `Runtime::Value` is read through its `to_h`
+        # @return [Object, nil] the sole numeric member, or the sole member, of a Hash-shaped
+        #   value; otherwise `value` unchanged (a `Runtime::Value` comes back as its Hash)
         def comparable(value)
           value = value.to_h if value.is_a?(Runtime::Value)
           return value unless value.is_a?(Hash)
@@ -51,9 +58,15 @@ module Hecks
           value
         end
 
-        # Which members a value object offers a scalar comparison, for a
+        # Lists the members a value object offers a scalar comparison, for a
         # refusal that can name them. Empty when the value object is
         # unambiguous — nothing to report.
+        #
+        # @param value_object [Class<Bluebook::ValueObject>] the declared shape (a subclass
+        #   minted by `Bluebook::ValueObject.declare`, closed sets included) a query field names
+        # @return [Array<Symbol>] every attribute name when no single member can be meant;
+        #   `[]` when there is exactly one attribute, or exactly one typed `Integer`,
+        #   `Float` or `Numeric`
         def ambiguous_members(value_object)
           numerics = value_object.attributes.select { |a| NUMERIC_TYPES.include?(a.type.to_s) }
           return [] if numerics.size == 1 || value_object.attributes.size == 1
@@ -63,15 +76,32 @@ module Hecks
 
         NUMERIC_TYPES = %w[Integer Float Numeric].freeze
 
-        # A `case` over a closed, declared set (Vocabulary::QueryComparator,
+        # Decides whether one where-clause comparison holds between the value
+        # a record holds and the value the query wants.
+        #
+        # A `case` over a closed, declared set (`Vocabulary::QueryComparator`,
         # held equal to this list by spec/vocabulary_table_spec — see the
-        # `else` branch's own comment) is the whole point of THE ONE
-        # COMPARATOR TABLE this file's header describes: one place naming
+        # `else` branch's own comment) is the whole point of the one
+        # comparator table this file's header describes: one place naming
         # every comparator, not one method per comparator scattered across
         # a module.
+        #
+        # @param operation [Symbol, String] the comparator name: `eq`, `ne`, `lt`, `lte`,
+        #   `gt`, `gte`, `in`, `contains` or `none_in_state`
+        # @param held [Object, nil] the record's own value for the field; `nil` against a
+        #   non-nil `want` satisfies no comparator except `none_in_state` (see
+        #   `NullPolicy.unmatchable?`)
+        # @param want [Object, nil] the value compared against; for `in` an Array or a
+        #   comma-separated String, for `none_in_state` an `"Aggregate:state"` String
+        # @param registry [Runtime::Registry, nil] used only by `none_in_state` to look the
+        #   target aggregate up; `nil` makes that comparator hold
+        # @return [Boolean] whether the comparison holds; an ordered comparator over a
+        #   non-`Numeric` operand is `false`
+        # @raise [Runtime::WiringError] if `operation` names no comparator in this table, or
+        #   `none_in_state`'s target aggregate has no repository that can be wired
         # rubocop:disable-next Metrics/CyclomaticComplexity
         def holds?(operation, held, want, registry: nil)
-          # A NULL SATISFIES NO COMPARISON — NullPolicy.unmatchable? owns
+          # A NULL satisfies no comparison — NullPolicy.unmatchable? owns
           # the rule and the reasoning, including why `none_in_state` is
           # exempt from it.
           return false if NullPolicy.unmatchable?(operation, held, want)
@@ -100,28 +130,51 @@ module Hecks
           end
         end
 
+        # Checks that both operands of an ordered comparison are numbers.
+        #
         # gt/gte/lt/lte are numeric-only and silently false otherwise — a
         # where-clause never raises the way a given does, and that contract
         # predates the extraction (lt was already exactly this permissive).
+        #
+        # @param held [Object, nil] the record's own value for the field
+        # @param want [Object, nil] the value compared against
+        # @return [Boolean] `true` only when both are `Numeric`
         def ordered?(held, want) = held.is_a?(Numeric) && want.is_a?(Numeric)
 
+        # Reads a comparator's list operand as the Strings membership is tested against.
+        #
         # `in` reads a comma-separated list — a real Array survives
         # untouched (a bluebook's own in-process value, before any wire
         # serialisation), each element unwrapped the same way a scalar
-        # field is. This is `in`'s reading of ITS ARGUMENT (a caller may
+        # field is. This is `in`'s reading of its argument (a caller may
         # legitimately pass "a,b,c" meaning "any of these") — unrelated to
-        # `contains`, which reads the STORED field. See `contains?`.
+        # `contains`, which reads the stored field. See `contains?`.
+        #
+        # @param value [Array, String, Object, nil] an Array of elements, or anything whose
+        #   `to_s` is a comma-separated list such as `"a, b,c"`
+        # @return [Array<String>] one String per member: Array elements unwrapped through
+        #   `comparable` then `to_s`; split parts stripped of surrounding whitespace; `[]`
+        #   for `nil` or an empty String
         def members(value)
           return value.map { |element| comparable(element).to_s } if value.is_a?(Array)
 
           value.to_s.split(",").map(&:strip)
         end
 
+        # Answers `in`: whether the held value, or any element of a held Array,
+        # occurs in the wanted list.
+        #
         # A folded reference hop asks whether the locally-held identity is
         # among the matching target identities. A has_many relationship holds
         # several identities, so the same question becomes an intersection:
-        # does ANY held identity occur in the wanted set? Scalar `in` retains
+        # does any held identity occur in the wanted set? Scalar `in` retains
         # its existing one-candidate behavior.
+        #
+        # @param held [Array, Object] the record's own value; an Array contributes each
+        #   element as a candidate, anything else is the single candidate
+        # @param want [Array, String, Object] the wanted set, read through `members`
+        # @return [Boolean] whether any candidate, unwrapped through `comparable` and
+        #   compared as a String, is a wanted member
         def any_member_in?(held, want)
           wanted = members(want)
           candidates = held.is_a?(Array) ? held : [held]
@@ -129,24 +182,35 @@ module Hecks
           candidates.any? { |candidate| wanted.include?(comparable(candidate).to_s) }
         end
 
-        # `contains` means two different things depending on what is HELD —
-        # real ELEMENT membership for a `list_of` field (a genuine Array
+        # Answers `contains`: element membership for a held Array, substring
+        # for anything else.
+        #
+        # `contains` means two different things depending on what is held —
+        # real element membership for a `list_of` field (a genuine Array
         # arrives already, one element one member, nothing to split), and
-        # plain SUBSTRING for anything else. It used to fall through to
-        # `members`' comma-split for the scalar case too, silently reading
-        # a free-text field's own comma as a separator — which the SQL
-        # side's `instr`/`position` never did, so the two disagreed the
-        # moment a scalar's real content held a comma. Matching SQL's
+        # plain substring for anything else. The scalar case deliberately
+        # stays out of `members`' comma-split: that silently reads a
+        # free-text field's own comma as a separator — which the SQL
+        # side's `instr`/`position` never does, so the two disagree the
+        # moment a scalar's real content holds a comma. Matching SQL's
         # substring reading here keeps every engine answering `contains`
         # identically for the same declared field.
+        #
+        # @param held [Array, Object] the record's own value; anything but an Array is
+        #   read through `to_s`
+        # @param want [Object] the element or substring looked for, compared as its `to_s`
+        # @return [Boolean] whether `held` has `want` as a member (Array) or a substring
         def contains?(held, want)
           return members(held).include?(want.to_s) if held.is_a?(Array)
 
           held.to_s.include?(want.to_s)
         end
 
-        # A CROSS-AGGREGATE ANTI-JOIN — `where ref: { none_in_state:
-        # "Claim:held" }` holds when NO record in the named aggregate,
+        # Answers `none_in_state` by looking the held identity up in another
+        # aggregate's repository and reading that record's state.
+        #
+        # **A cross-aggregate anti-join** — `where ref: { none_in_state:
+        # "Claim:held" }` holds when no record in the named aggregate,
         # keyed by this record's own field value, is in the named state.
         # No registry — no way to look the target up — reads as "not
         # excluded", the same graceful default a missing record already
@@ -154,6 +218,17 @@ module Hecks
         # loaded domain; ambiguity (two domains declaring one name) picks
         # the first match rather than refusing, since a where-clause never
         # raises (see `ordered?`).
+        #
+        # @param held [Object, nil] this record's own field value, used as the target
+        #   record's identity
+        # @param want [String, Symbol] `"Aggregate:state"` — the target aggregate's bare
+        #   name and the excluded state, split on the first colon
+        # @param registry [Runtime::Registry, nil] the booted registry to find the target
+        #   aggregate and its repository in
+        # @return [Boolean] `false` only when the target record exists and its lifecycle
+        #   field (or `:state`, absent a lifecycle) equals the named state; `true` when
+        #   there is no registry, no such aggregate or no such record
+        # @raise [Runtime::WiringError] if the target aggregate's repository cannot be wired
         def none_in_state?(held, want, registry)
           return true unless registry
 
@@ -165,9 +240,42 @@ module Hecks
           record = registry.repository(target_domain, target_ir).find(held)
           return true unless record
 
-          comparable(record.state[:state]) != state
+          # The field a state lives on, read from the target's own
+          # declaration — not assumed to be literally named `state`. Every
+          # `none_in_state` fixture this comparator originally shipped
+          # with (spec/query_none_in_state_*_spec.rb) happens to declare a
+          # plain `attribute :state, ...` rather than a real `lifecycle`,
+          # which is how the previous hardcoded `record.state[:state]`
+          # passed every one of them while being wrong for the shape this
+          # whole comparator exists to answer about: a real state machine.
+          # `lifecycle :field, default: ... do ... end` stores its state
+          # under `field` (`Instance#assign_creation_attributes`'s own
+          # `state[aggregate.lifecycle.field.to_sym] = ...`), and this
+          # codebase's own convention overwhelmingly names that field
+          # `status`, not `state` (`QualityControl::Clearance`'s own
+          # `lifecycle :status` among many others) — so the hardcoded key
+          # silently read `nil` from every real lifecycle-backed target,
+          # comparable(nil) != state was true unconditionally, and
+          # `none_in_state` against any lifecycle aggregate answered
+          # "not excluded" for every row, always, no matter its actual
+          # state. Found chasing `QualityControl::Bug.AwaitingClearance`
+          # (qa/bluebook/quality_control.bluebook), which is exactly this
+          # shape: `Clearance:green`/`Clearance:red` against a `lifecycle
+          # :status` aggregate. Falls back to `:state` when the target
+          # declares no lifecycle at all, so every existing fixture (a
+          # plain attribute literally named `state`) keeps answering
+          # exactly as before.
+          field = target_ir.lifecycle&.field || :state
+          comparable(record.state[field]) != state
         end
 
+        # Searches every loaded domain for an aggregate by its bare name, taking
+        # the first match in the registry's load order.
+        #
+        # @param registry [Runtime::Registry] the booted registry whose bluebooks are searched
+        # @param name [String, nil] the aggregate's bare `hecks_name`, such as `"Claim"`
+        # @return [Array(String, Bluebook::Aggregate), nil] the owning domain's name and the
+        #   aggregate; `nil` when no loaded domain declares one by that name
         def find_aggregate_by_name(registry, name)
           registry.bluebooks.each do |domain, bluebook|
             aggregate = bluebook.aggregates.find { |a| a.hecks_name == name }