hecks 2.8.0 → 2.9.0

data/lib/hecks/projector.rb

@@ -1,60 +1,13 @@
 module Hecks
-  # A named registry of "canonical IR in, external artifact out" tools —
-  # §30 of docs/HECKS_IMPLEMENTATION_PLAN.md. Before this existed, every
-  # such tool was its own thing with its own call shape: `Exporter`
-  # (registry-wide, consumed directly by bin/ir, bin/project_rust, and
-  # translation/audit's approval digest — untouched by this file, still
-  # exactly what those three read), and `RustProjection::Projector`
-  # (`rust/project.rb`, a whole separate Ruby program under a
-  # confusingly-identical module name) are the two that already exist.
-  # Neither is registered here — retrofitting either is real, separate
-  # work (Rust's generator is a whole second toolchain; a UL/OIDC
-  # projector doesn't exist yet at all) — but `:ir` is, as a genuine,
-  # working, golden-tested example of the shape every future projector
-  # (`:rust`, `:ul`, `:openid`, ...) is meant to follow.
+  # A named registry of "canonical IR in, external artifact out" tools, each
+  # taking one bluebook's IR and answering a derived artifact (`:ir`, `:docs`, ...).
   #
-  # 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.
+  #   Projector.call(:ir, bluebook: chapter)
   #
-  # ## 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
-  #   generated crate, the WASM artifact, the CloudFormation template
-  #   `lib/hecks/projections/deploy` renders. It needs the
-  #   `.world`/`.hecksagon` a projection never looks at, because a
-  #   running system has to know how it is wired. A target that needs
-  #   this declares `needs_world: true` (`Target#projects_as`) and reads
-  #   `options.fetch(:world)`; `Projector.call`'s own `world:` keyword is
-  #   what carries it, merged into `options` before the target ever runs.
-  #
-  #   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
-  #   `Grammar.expression` replays expression_operators.json's ledger of
-  #   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:
-  #
-  #   Ports::Projection    read-model catch-up, events folded into state
-  #   bin/project          forces that catch-up by hand
-  #   RustProjection       rust/project.rb's own separate toolchain
+  # A projection is inert and derived from a chapter's declaration. An export
+  # (rust crate, WASM, CloudFormation) also needs `.world` bindings and declares
+  # `needs_world: true`. State projections (`bin/expression_projection`) and
+  # `Ports::Projection` read-model catch-up are different things and not registered.
   module Projector
     class UnknownProjector < StandardError; end
     # A chapter-scoped projector was handed something that is not a chapter.
@@ -62,14 +15,8 @@ module Hecks
 
     module_function
 
-    # `projector` needs only to answer `call(bluebook:, options:)` — a
-    # module, a class with a class method, or any object responding to
-    # `call` all work. Re-registering a name replaces it outright,
-    # 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.
+    # already registered there (deliberately unguarded, so specs can stub).
     #
     # @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:)`
@@ -81,24 +28,14 @@ module Hecks
     # 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.
-    #
     # @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 bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to project
     # @param options [Hash] projector-specific options, passed through unchanged
-    # @param world [Bluebook::World, nil] the domain's `.world`/`.hecksagon` bindings,
-    #   required by an export (`needs_world: true`); nil for an ordinary projection.
-    #   Merged into `options[:world]` before the target runs — the target never
-    #   receives it as a separate argument.
-    # @return [Object] whatever the projector's own `call` returns: typically a
-    #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
+    # @param world [Bluebook::World, nil] bindings an export needs (`needs_world: true`);
+    #   merged into `options[:world]`
+    # @return [Object] whatever the projector's own `call` returns
     # @raise [UnknownProjector] if no projector is registered under `name`
-    # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
-    #   projector requires, or if the projector needs `world:` and none is given
+    # @raise [WrongConstruct] if `bluebook` lacks what the projector requires
     def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
@@ -107,31 +44,17 @@ module Hecks
       projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
     end
 
-    # 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
-    # capabilities and a class-shaped one — Command, Entity, ValueObject
-    # — 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.
+    # Refuses `construct` if it lacks a capability or declared aggregate `projector` requires.
+    # One `is_a?` check covers included and extended capabilities alike.
     #
     # @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`, `projection_declares`, and `projection_needs_world?` when
-    #   it answers them
-    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
-    #   IR-emitting construct offered to the projector
-    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`, checked
-    #   against the target's own `needs_world:` declaration
+    # @param projector [Module, Class, #call] the target; consulted for `projection_requires`,
+    #   `projection_declares` and `projection_needs_world?` when it answers them
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct offered
+    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`
     # @return [void]
-    # @raise [WrongConstruct] if `construct` lacks a required capability, the chapter it
-    #   is declares no aggregate the projector needs, or the projector needs `world:`
-    #   and `world` is nil
+    # @raise [WrongConstruct] if a required capability or aggregate is missing, or the
+    #   projector needs `world:` and `world` is nil
     def admits!(name, projector, construct, world = nil)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
@@ -190,11 +113,8 @@ module Hecks
       @registry ||= {}
     end
 
-    # A target may be addressed by the constant that implements it
-    # (`Projections::OIDC`) or by the bare key it registered under
-    # (`: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.
+    # Resolves a target given as a constant (`Projections::OIDC`) or a bare
+    # key (`:oidc`) to the key it is registered under.
     #
     # @param target [String, Symbol, #projection_key] a registered key, or a target
     #   that declared its own key with `Target#projects_as`
@@ -205,15 +125,10 @@ module Hecks
       target
     end
 
-    # 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.
+    # Writes `artifact` to `out`; a projector itself never touches disk.
     #
-    # `as:` comes from the projection's own `emits:` declaration rather
-    # 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.
+    # `as:` comes from the projection's `emits:` declaration, since a file tree
+    # and a Hash of strings are the same object to Ruby.
     #
     # @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`
@@ -226,8 +141,7 @@ module Hecks
       out
     end
 
-    # Answers the paths written, in the order given — so a caller can
-    # report what happened without re-deriving it from the tree.
+    # Writes each `files` entry under `directory`, answering the paths written.
     #
     # @param files [Hash{String => String}] relative path => contents
     # @param directory [String] the directory to write the tree under
@@ -249,8 +163,7 @@ require "json"
 require_relative "projector/exporter"
 require_relative "projector/ir_projector"
 require_relative "projector/target"
-# Neither of these requires this file back — they need `Naming` and nothing
-# else — so unlike a target they are safe to pull in from here.
+# These need only `Naming`, not this file, so they are safe to load from here.
 require_relative "projector/docs_projector"
 require_relative "projector/narrate_projector"
 require_relative "projector/cli_projector"
@@ -260,9 +173,5 @@ 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
-# 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
-# tolerates it; the warning is still right, and load order is the kind of
-# thing that only breaks once someone requires a target on its own.
+# Targets are required from lib/hecks.rb, not here: each requires this file, so
+# requiring them back would close a circular require.

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

@@ -2,37 +2,16 @@ require_relative "../../literal"
 require_relative "../../vocabulary"
 
 module Hecks
-  # Reopened (see query_specification.rb for the namespace's own
-  # summary) to add Common::COMPARATORS — the vendored comparator
-  # vocabulary — and .render_value, the wire-rendering entry point
-  # shared by every literal-bearing spec struct.
+  # Adds `Common::COMPARATORS` and `.render_value`, the wire renderer shared by spec structs.
   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.
+    # The clause structs, DSL mixin and comparison rules shared by every query-shaped construct.
     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
-      # 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" --
-      # a real, deliberate, pre-existing feature (WhereOp::NoneInState in
-      # the old Rust runtime), not invented here -- see Runtime::
-      # QueryInterpreter#holds?'s own comment for the evaluation side.
+      # Includes `none_in_state`: `where ref: { none_in_state: "Claim:held" }` holds when no record
+      # in the named aggregate, keyed by this field's value, is in that state (a keyed lookup).
       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
-    # shares. Kept as a word here because the structs below read better
-    # saying what they are doing than naming the module that does it.
+    # Renders a query-clause literal as its wire spelling; delegates to `Hecks::Literal.render`.
     #
     # @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

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

@@ -4,44 +4,16 @@ require_relative "../../runtime/value"
 module Hecks
   module QuerySpecification
     module Common
-      # **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`)
-      # — plus a third partial reading of `comparable` inside
-      # `SqlQueryBuilder#query_value`.
-      #
-      # Two copies of one rule is not a style complaint here; it has cost
-      # 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
-      # 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
-      # 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.
+      # The one comparator table shared by `Ports::Query::InMemory` and
+      # `Runtime::QueryInterpreter`, so every engine reads a where-clause identically.
       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
-        # numeric members give no reason to prefer either, and picking the
-        # first silently compares a field the author never named.
-        #
-        # A declaration naming an ambiguous value object is refused when
-        # the bluebook loads (`AggregateBuilder`'s own query-field seal),
-        # 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.
+        # Only a sole numeric member, or a sole member of any type, is unambiguous; anything
+        # else is returned unchanged rather than guessed at. Ambiguous declarations are refused
+        # at load, so this is a backstop.
         #
         # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
         #   `Runtime::Value` is read through its `to_h`
@@ -58,9 +30,8 @@ module Hecks
           value
         end
 
-        # 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.
+        # Lists the members a value object offers a scalar comparison, for a refusal
+        # that can name them. Empty when the value object is unambiguous.
         #
         # @param value_object [Class<Bluebook::ValueObject>] the declared shape (a subclass
         #   minted by `Bluebook::ValueObject.declare`, closed sets included) a query field names
@@ -76,34 +47,19 @@ module Hecks
 
         NUMERIC_TYPES = %w[Integer Float Numeric].freeze
 
-        # 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
-        # every comparator, not one method per comparator scattered across
-        # a module.
+        # Decides whether one where-clause comparison holds between the value a record
+        # holds and the value the query wants.
         #
-        # @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
+        # @param operation [Symbol, String] `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `in`,
+        #   `contains` or `none_in_state`
+        # @param held [Object, nil] the record's own value for the field
+        # @param want [Object, nil] the value compared against
+        # @param registry [Runtime::Registry, nil] used only by `none_in_state`
+        # @return [Boolean] whether the comparison holds
+        # @raise [Runtime::WiringError] if `operation` names no comparator in this table
         # rubocop:disable-next Metrics/CyclomaticComplexity
         def holds?(operation, held, want, registry: nil)
-          # A NULL satisfies no comparison — NullPolicy.unmatchable? owns
-          # the rule and the reasoning, including why `none_in_state` is
-          # exempt from it.
+          # A NULL satisfies no comparison (`none_in_state` is exempt); see NullPolicy.
           return false if NullPolicy.unmatchable?(operation, held, want)
 
           case operation.to_s
@@ -117,24 +73,15 @@ module Hecks
           when "contains" then contains?(held, want)
           when "none_in_state" then none_in_state?(held, want, registry)
           else
-            # Every declared comparator has a `when` above (Vocabulary::
-            # QueryComparator, held equal to this list by
-            # spec/vocabulary_table_spec) — this is not a real runtime
-            # path today, only a backstop against the day a tenth
-            # comparator reaches the grammar and this method doesn't
-            # grow to match. Silently reading an unrecognized comparator
-            # as `eq` is exactly the failure this table already shipped
-            # once (see this file's own header) — an operator this
-            # method can't evaluate must refuse, not guess.
+            # Backstop: an unrecognized comparator must refuse, never read as `eq`.
             raise Runtime::WiringError, "no comparator handles #{operation.to_s.inspect} — add one before declaring it"
           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).
+        # Ordered comparators are numeric-only and silently false otherwise; a where-clause
+        # never raises.
         #
         # @param held [Object, nil] the record's own value for the field
         # @param want [Object, nil] the value compared against
@@ -143,12 +90,8 @@ module Hecks
 
         # 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
-        # legitimately pass "a,b,c" meaning "any of these") — unrelated to
-        # `contains`, which reads the stored field. See `contains?`.
+        # `in` accepts an Array or a comma-separated String; `contains` reads the stored
+        # field instead (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"`
@@ -164,12 +107,6 @@ module Hecks
         # 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
-        # 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`
@@ -182,19 +119,10 @@ module Hecks
           candidates.any? { |candidate| wanted.include?(comparable(candidate).to_s) }
         end
 
-        # Answers `contains`: element membership for a held Array, substring
-        # for anything else.
+        # 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. 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.
+        # A scalar is not comma-split, so free text containing a comma matches the way
+        # SQL's `instr`/`position` does.
         #
         # @param held [Array, Object] the record's own value; anything but an Array is
         #   read through `to_s`
@@ -206,29 +134,17 @@ module Hecks
           held.to_s.include?(want.to_s)
         end
 
-        # Answers `none_in_state` by looking the held identity up in another
-        # aggregate's repository and reading that record's state.
+        # 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
-        # falls back to. The target is searched by bare name across every
-        # loaded domain; ambiguity (two domains declaring one name) picks
-        # the first match rather than refusing, since a where-clause never
-        # raises (see `ordered?`).
+        # Holds when no such record is in the named state. No registry, aggregate or record
+        # reads as "not excluded". The target is found by bare name; the first match wins.
         #
-        # @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
+        # @param held [Object, nil] this record's own field value, the target record's identity
+        # @param want [String, Symbol] `"Aggregate:state"`, split on the first colon
+        # @param registry [Runtime::Registry, nil] the booted registry
+        # @return [Boolean] `false` only when the target record is in the named state
+        # @raise [Runtime::WiringError] if the target's repository cannot be wired
         def none_in_state?(held, want, registry)
           return true unless registry
 
@@ -240,31 +156,7 @@ module Hecks
           record = registry.repository(target_domain, target_ir).find(held)
           return true unless record
 
-          # 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.
+          # The state lives on the target's lifecycle field, else on `:state`.
           field = target_ir.lifecycle&.field || :state
           comparable(record.state[field]) != state
         end

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

@@ -11,33 +11,17 @@ require_relative "where_clause"
 module Hecks
   module QuerySpecification
     module Common
-      # Shared builder-instance methods for the `where`/`order_by`/
-      # `limit`/`offset`/`cursor`/`authorize`/`nulls`/`inspect_query`
-      # bluebook DSL words, mixed into both QueryBuilder and
-      # ReadModelBuilder so the two specification kinds parse the same
-      # clauses identically rather than each carrying its own copy.
+      # Builder methods for the `where`/`order_by`/`limit`/`offset`/`cursor`/`authorize`/
+      # `nulls`/`inspect_query` DSL words, shared by QueryBuilder and ReadModelBuilder.
       module DSL
-        # Records one `WhereClause` per `field => value` pair — what the
-        # `where` DSL word forwards to.
+        # Records one `WhereClause` per `field => value` pair (the `where` DSL word).
         #
-        # `where`/`order_by`/`limit`/`offset`/`authorize` (all below) carry
-        # an `_impl` name because the words themselves are dispatched by
-        # the grammar table rather than defined as methods: both the Query
-        # and the ReadModel Keyword rows name the `_impl` method in
-        # `calls:`, the same shape `attribute_impl` has, and a shared mixin
-        # means one method each. `where`/`order_by` are bootstrap-reachable
-        # (every core chapter's own `read_model` filters its roster with
-        # them), so they must resolve through
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` while the grammar
-        # table is still being built.
+        # `where`/`order_by` resolve through `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`
+        # while the grammar table is being built.
         #
-        # @param clauses [Hash{Symbol => Object}] field name (a dotted or slashed path is
-        #   one Symbol) to 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 a Hash value does not have exactly one pair, or names a
-        #   comparator outside `COMPARATORS`
+        # @param clauses [Hash{Symbol => Object}] field name to a literal, a query argument
+        #   Symbol, or a one-pair Hash such as `{ gte: :minimum }`; a bare value means `eq`
+        # @raise [ArgumentError] if a Hash value is not one known `COMPARATORS` pair
         def where_impl(clauses)
           @wheres ||= []
           clauses.each do |field, value|