hecks 2.7.0 → 2.9.0

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

@@ -2,12 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `read_model "Name" do ... end` block into a `ReadModel` — a
-      # cross-aggregate projection built from an optional `reference_to`
-      # root (omitted, it's a rootless "bulk" read model) plus one or more
-      # `include`d aggregate heads, with `where`/`order_by`/`limit`/etc, and
-      # at most one of `group_by`, `count`, or `median` as its single
-      # reduction over the one eligible many-side collection.
+      # Parses a `read_model "Name" do ... end` block into a `ReadModel`: a cross-aggregate
+      # projection over an optional `reference_to` root and its `include`d aggregate heads.
       class ReadModelBuilder
         GRAMMAR_CONTEXT = "ReadModel".freeze
 
@@ -24,16 +20,10 @@ module Hecks
         # @param value [String] the description text
         # @return [String] the description as stored
         def description(value)
-          # moved to the language: ProjectionText / purpose, on Projection.Declare
           @description = value
         end
 
-        # Declares the read model's own "one" side — the aggregate head every row projects
-        # around, keyed by its identity.
-        #
-        # Reached through `calls: "reference_to_impl"`. Bootstrap-reachable — the self-hosted
-        # `Bluebook.WholeBluebook` read model declares one — so it's exercised while
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` is still in play, not only afterwards.
+        # Declares the read model's own "one" side, the aggregate head every row projects around.
         #
         # @param type [Module, Symbol, String] the referenced aggregate, written as a bare
         #   constant
@@ -50,21 +40,8 @@ module Hecks
 
         # Adds one aggregate head this read model projects.
         #
-        # Order-independent: `many:` is decided by comparing the included type
-        # against the reference target, resolved at build time (when the
-        # reference is known), not at the moment `include` itself runs — so
-        # an include declared before `reference_to` resolves exactly like one
-        # declared after it.
-        #
-        # Reached through `calls: "include_impl"`. Bootstrap-reachable —
-        # every core chapter's own `read_model` names which aggregates it
-        # includes with it — so it's exercised while
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` is still in play.
-        # `group_by_impl`, below, is table-routed the same way but is not
-        # bootstrap-reachable (no core read_model groups). The class-level
-        # `include WordGate` this file's own class body uses is
-        # `Module#include`, a different receiver, unrelated to this
-        # instance method sharing its name.
+        # `many:` is decided at build time against the reference target, so an include declared
+        # before `reference_to` resolves like one declared after it.
         #
         # @param type [Module, Symbol, String] the included aggregate, written as a bare constant
         # @param as [Symbol, nil] the field name to project this head's rows under; `nil` derives
@@ -75,64 +52,21 @@ module Hecks
           @includes << [Naming.demodulise(type), as]
         end
 
-        # `on:` (ADR 0055) — overrides of `QuerySpecification::Common::DSL`'s
-        # shared `where_impl`/`order_by_impl`/`limit_impl`/`offset_impl`,
-        # scoped to `ReadModelBuilder` alone rather than added to the shared
-        # module `Query` also mixes in: a plain `query` has no
-        # `aggregate_heads` at all, so `on:` there would be a silently-
-        # ignored no-op rather than a real answer. Overriding only here
-        # means a `Query`'s own `where(..., on: X)` gets Ruby's own loud
-        # `unknown keyword: :on` instead of quietly doing nothing.
-        #
-        # `on:` names the target by type (`on: Character`), resolved the
-        # same way `reference_to`/`include` already resolve their own type
-        # argument (`Naming.demodulise`) — not by the include's own `as:`
-        # alias. A read model that `include`s the same type twice under two
-        # different `as:` has no way to say which one `on:` means today; no
-        # real corpus read model does this, so it's a real, deliberate scope
-        # limit (see ADR 0055), not an oversight.
-        #
-        # `*positional, on:, **rest` rather than a plain `(clauses, on: nil)`
-        # — found necessary, not stylistic, by reproducing the failure
-        # directly: `where(status: "disputed")` reaches here with its
-        # `status: "disputed"` captured as `**kwargs` (GenericDispatch's own
-        # `builder.send(calls, *args, **kwargs, &block)`), and Ruby stops
-        # auto-converting a bare `**hash` call into a plain positional Hash
-        # the moment a method declares any real keyword parameter — so a
-        # `(clauses, on: nil)` signature raised "wrong number of arguments
-        # (given 0, expected 1)" on every ordinary `where(field: value)`
-        # call, never reaching `on:` at all. `**rest` sidesteps this: Ruby
-        # still auto-splits `on:` into the declared keyword and gathers
-        # every other key into `rest` regardless of how the caller wrote it.
-        #
-        # `QuerySpecification::Common::WhereClause` etc — fully qualified,
-        # not the bare names `dsl.rb`'s own shared `where_impl` gets away
-        # with. That file is lexically nested inside `Common` itself, so
-        # `WhereClause` resolves directly; this class is nested inside
-        # `Bluebook::DSL`, which has no lexical or ancestor path to
-        # `QuerySpecification::Common` at all — a bare `WhereClause` here
-        # falls through to `const_missing` and, mid-bluebook-load, that's
-        # `ConstShim`, which resolves it against the self-hosted grammar
-        # domain's own unrelated `WhereClause` construct instead (a `Module`,
-        # not this `Struct`) — found directly by reproducing "undefined
-        # method `new' for module WhereClause" against a real corpus load,
-        # not guessed.
-        #
-        # Records one `WhereClause` per `field => value` pair, targeted at a named many-side
-        # include when this read model has more than one.
+        # The `on:` overrides of the shared where/order_by/limit/offset are kept off the shared
+        # module so a plain `query` still raises `unknown keyword: :on`. `on:` names its target
+        # by type, not by an include's `as:` alias (ADR 0055).
+
+        # Records one `WhereClause` per `field => value` pair, optionally targeted with `on:`.
         #
-        # @param positional [Array<Hash{Symbol => Object}>] at most one bare Hash of where
-        #   clauses; in practice always empty, since Ruby routes an ordinary
-        #   `where(field: value)` call entirely into `rest` (see the comment above)
-        # @param on [Module, Symbol, String, nil] the many-side included aggregate these clauses
-        #   apply to; `nil` when this read model has at most one many-side head
-        # @param rest [Hash{Symbol => Object}] `field => value` where clauses; a value is either
-        #   a literal, a Symbol naming a query argument, or a one-pair Hash `{ comparator =>
-        #   operand }` such as `{ gte: :minimum }` — a bare value means `eq`
+        # @param positional [Array<Hash>] at most one bare Hash of clauses; normally empty
+        # @param on [Module, Symbol, String, nil] the many-side include the clauses apply to
+        # @param rest [Hash{Symbol => Object}] `field => value`; a value is a literal, a Symbol
+        #   naming a query argument, or a one-pair `{ comparator => operand }` Hash
         # @return [void]
-        # @raise [ArgumentError] if more than one positional argument is given, or a Hash value
-        #   does not have exactly one pair, or names a comparator outside `COMPARATORS`
+        # @raise [ArgumentError] on more than one positional argument or a malformed comparator
         def where_impl(*positional, on: nil, **rest)
+          # `**rest` because a declared keyword stops Ruby turning a bare `where(status: "x")`
+          # into a positional Hash.
           raise ArgumentError, "wrong number of arguments (given #{positional.size}, expected 1)" if positional.size > 1
 
           @wheres ||= []
@@ -140,6 +74,8 @@ module Hecks
           clauses = (positional.first || {}).merge(rest)
           clauses.each do |field, value|
             op, operand = split_comparator(value)
+            # Fully qualified: a bare `WhereClause` reaches `ConstShim` and resolves to the
+            # grammar domain's unrelated module.
             @wheres << QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
           end
         end
@@ -178,74 +114,50 @@ module Hecks
           @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
         end
 
-        # Names which of the eligible head's own fields to nest its rows
-        # under — one level per field, the leaf being that row with the
-        # named fields removed (they're already spent, as the keys that
-        # reached it). The same "exactly one many-side head" rule
-        # `seal_query_options` already enforces for where/order_by/etc
-        # applies here too (`seal_group_by`) — grouping is a question
-        # about one collection's own rows, same as those are.
+        # Names which of the eligible head's own fields to nest its rows under, one level per
+        # field; the leaf is the row with those fields removed.
+        #
         # @param fields [Array<Symbol>] the eligible many-side head's own fields to nest its rows
         #   under, one level per field
         # @return [void]
         def group_by_impl(*fields)
-          # Hash rows, `{field:}`, not bare symbols — same shape
-          # `aggregate_heads` already uses for exactly the reason it
-          # does: the language's own self-hosted grammar (`projection
-          # .bluebook`'s `GroupByField`) has to have something to read a
-          # `field:` off of when `Judge` walks this list generically: a
-          # bare `Symbol` has no attribute of its own to read.
+          # Hash rows rather than bare symbols: the self-hosted `GroupByField` grammar reads
+          # `field:` off each entry when `Judge` walks the list.
           @group_by = fields.map { |field| { field: field.to_sym } }
         end
 
-        # `count` -- a bare row count over the eligible many-side head's
-        # own rows (after `where`/`order_by`/`limit`/`offset` apply, the
-        # same rows `group_by` itself would nest) -- answers "how many
-        # match", not "which ones". A sibling reduction to `group_by`,
-        # not a filter: `seal_aggregation` refuses combining it with
-        # `group_by` or with `median`, the same "exactly one many-side
-        # head" rule `seal_group_by` already enforces for the same
-        # reason -- a bare marker, so `@count` is left unset (nil, not
-        # false) rather than defaulted, matching the "absent is not
-        # empty" reading `Lifecycle`'s own optional fields already rely
-        # on for the Judge's setter dispatch (Behaviour::ReadModel#
-        # count?, ReadModelInterpreter#aggregation_target).
-        # `count` — item #13's full metaprogrammed dispatch, slice 1
-        # (whole-project table-unification survey): the only Keyword row
-        # filling `count` — a bare marker, now stored as literal `true`
-        # by `GenericDispatch` off that same table fact.
-
-        # `median(field)` -- the median value of one numeric field
-        # across the eligible many-side head's own rows. Even count: the
-        # average of its two middle values (the standard definition,
-        # not "the lower of the two") -- see
-        # Runtime::ReadModelInterpreter#median for where that lands and
-        # is documented for a caller. `field` must name a numeric
-        # attribute (a bare numeric primitive, or a value object
-        # carrying one) -- checked once, at read time, by
-        # ReadModelInterpreter#aggregation_target, the same place
-        # `group_by`'s own field names are checked.
-        # `median` — item #13's full metaprogrammed dispatch, slice 1:
-        # same shape as `count`, above (a bare, kind-driven coerce-and-
-        # assign).
+        # `sum`/`avg`/`min`/`max`/`any`/`all` need no method of their own: each is one
+        # required positional symbol, the same shape as `median`, which `GenericDispatch`
+        # already handles generically off the grammar table (ADR 0078).
+
+        # The field's value at one interpolated rank (`0.0`..`1.0`) across the eligible
+        # many-side head's own rows; `median` is the fixed `at: 0.5` case (ADR 0078). Takes
+        # a named argument alongside its field, which is outside `GenericDispatch`'s
+        # one-positional-argument shape, so it needs a method of its own.
+        #
+        # @param field [Symbol] the eligible many-side head's own numeric field
+        # @param at [Float] the rank to interpolate, `0.0` (the minimum) through `1.0` (the maximum)
+        # @return [void]
+        # @raise [ArgumentError] if `at` is not a `Float` in `0.0..1.0`
+        def percentile_impl(field, at:)
+          unless at.is_a?(Float) && (0.0..1.0).cover?(at)
+            raise ArgumentError, "percentile's at: must be a Float between 0.0 and 1.0 (given #{at.inspect})"
+          end
+
+          @percentile_field = field.to_sym
+          @percentile_at = at
+        end
 
         # Assembles the declared references, includes and clauses into a `ReadModel`, after
         # validating them.
         #
-        # `reference_to` is optional — a read model with no root is a
-        # bulk one: every `include`d head reads its own aggregate whole
-        # (no FK match against a root that doesn't exist), and dispatch
-        # takes no id argument at all. Requiring one would refuse a real,
-        # legitimate shape: `group_by`'s own real use (nesting an
-        # aggregate's own whole table by its own field values) has no root
-        # to speak of. Still needs to describe something — zero includes
-        # and no reference is refused.
-        #
+        # `reference_to` is optional: a rootless read model is a bulk one and takes no id.
+        # Zero includes and no reference is refused.
         # @return [Bluebook::ReadModel] the built read model
         # @raise [Bluebook::DSL::Malformed] if neither `reference_to` nor any `include` is
-        #   declared, if `where`/`order_by`/`limit`/`offset`/`group_by`/`count`/`median` name an
+        #   declared, if `where`/`order_by`/`limit`/`offset`/`group_by` or a reduction name an
         #   `on:` that isn't a many-side include or are left untargeted with more than one
-        #   many-side head, if `count` and `median` are both declared or combined with
+        #   many-side head, if more than one reduction is declared or one is combined with
         #   `group_by`, or if `cursor` is declared
         def build
           if !@reference_target && Array(@includes).empty?
@@ -266,7 +178,10 @@ module Hecks
                         cursor: @cursor,
                         authorization: @authorization, null_semantics: @null_semantics,
                         inspection: @inspection, group_by: @group_by || [],
-                        count: @count, median_field: @median_field)
+                        count: @count, median_field: @median_field,
+                        sum_field: @sum_field, avg_field: @avg_field, min_field: @min_field,
+                        max_field: @max_field, percentile_field: @percentile_field,
+                        percentile_at: @percentile_at, any_field: @any_field, all_field: @all_field)
         end
 
         # Evaluates a `read_model` block against a fresh builder and returns what it built.
@@ -283,30 +198,9 @@ module Hecks
 
         private
 
-        # where/order_by/limit/offset/authorize's tenant all apply to
-        # collections — the `include`d aggregates whose heads are "many"
-        # (the "one" side, the reference target itself, is a single row;
-        # ordering, paging, or tenant-scoping one row means nothing). ADR
-        # 0055 gave `where`/`order_by`/`limit`/`offset` an `on:` to name
-        # which many-side collection they mean, so this asks two questions
-        # now instead of one:
-        #
-        #   1. Does every declared `on:` actually name a many-side included
-        #      aggregate? Checked regardless of how many many-side heads
-        #      exist — a typo refuses immediately, not only once ambiguity
-        #      would otherwise bite.
-        #   2. Is there still an untargeted option declared (including
-        #      `authorize`'s own `tenant:`, which has no `on:` of its own —
-        #      a real, deliberate scope limit, see ADR 0055)? An untargeted
-        #      option still needs exactly one many-side head to mean
-        #      anything unambiguous — the original rule, unchanged, and
-        #      still worded the same way (`spec/runtime/
-        #      read_model_interpreter_spec.rb`'s existing refusal regex
-        #      still matches).
-        #
-        # A read model with several many-side heads is legal precisely when
-        # every declared option names one; a read model with a single
-        # many-side head is unaffected either way, `on:` or not.
+        # where/order_by/limit/offset/authorize's tenant apply to the many-side collections;
+        # the reference target is a single row. Every `on:` must name a many-side include, and
+        # any untargeted option needs exactly one many-side head (ADR 0055).
         def seal_query_options
           many = Array(@aggregate_heads).select { |head| head[:many] }
 
@@ -320,10 +214,7 @@ module Hecks
                 "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
         end
 
-        # Question 1 of `seal_query_options`'s own two, split out to keep
-        # both under the same "one job per method" shape every other seal in
-        # this file already holds to (each raises its own one Malformed, for
-        # its own one reason).
+        # Refuses an `on:` that does not name one of the many-side includes.
         def validate_declared_targets!(many)
           many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
           declared_targets = Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
@@ -338,9 +229,7 @@ module Hecks
           end
         end
 
-        # Question 2 of `seal_query_options`'s own two — see that method's
-        # header. `authorize`'s own `tenant:` has no `on:` at all (ADR 0055's
-        # own documented scope limit), so it always counts as untargeted.
+        # `authorize`'s `tenant:` has no `on:`, so it always counts as untargeted.
         def untargeted_option_declared?
           Array(@wheres).any? { |where| where.target.nil? } ||
             (@order_by && @order_by.target.nil?) ||
@@ -349,9 +238,7 @@ module Hecks
             @authorization&.tenant
         end
 
-        # Same shape as `seal_query_options`, same reason — `group_by`
-        # answers a question about one collection's own rows, so zero or
-        # several many-side heads leaves it with no unambiguous target.
+        # Same rule as `seal_query_options`: `group_by` needs exactly one many-side head.
         def seal_group_by
           return unless @group_by&.any?
 
@@ -364,45 +251,35 @@ module Hecks
                 "own rows; name which one by including only it"
         end
 
-        # `count`/`median` are the other two reductions a read model may
-        # declare over its one eligible collection — same "exactly one
-        # many-side head" rule as `seal_group_by`, plus a rule
-        # `seal_group_by` doesn't need: a read model reports one shape,
-        # so `count` and `median` cannot both be declared, and neither
-        # may combine with `group_by` (nesting rows and reducing them to
-        # a scalar are answers to different questions ; a caller asking
-        # "how many, nested by state" is not a shape this read model
-        # produces today — a real, deliberate scope limit, not an
-        # oversight, the same discipline the rootless model's own
-        # "each head reads independently" limit already documents).
+        # Every reduction (`Behaviour::ReadModel::REDUCTION_FIELDS`) needs exactly one
+        # many-side head, cannot be declared alongside another, and cannot combine with
+        # `group_by`: a read model reports one shape.
         def seal_aggregation
-          return unless @count || @median_field
+          declared = Behaviour::ReadModel::REDUCTION_FIELDS
+                     .select { |ivar, _| instance_variable_get(:"@#{ivar}") }.values
+          return if declared.empty?
 
-          if @count && @median_field
-            raise Malformed,
-                  "#{@name} declares both count and median — a read model reports " \
-                  "one shape; choose one"
-          end
           if @group_by&.any?
             raise Malformed,
-                  "#{@name} declares count/median together with group_by — a read " \
+                  "#{@name} declares #{declared.join('/')} together with group_by — a read " \
                   "model reports one shape; choose one"
           end
+          if declared.size > 1
+            joiner = declared.size == 2 ? "both #{declared.join(' and ')}" : declared.join(", ")
+            raise Malformed, "#{@name} declares #{joiner} — a read model reports one shape; choose one"
+          end
 
           many = Array(@aggregate_heads).count { |head| head[:many] }
           return if many == 1
 
           raise Malformed,
-                "#{@name} declares count/median but includes #{many} many-side " \
-                "aggregates, not exactly one — count/median reduce a single " \
+                "#{@name} declares #{declared.first} but includes #{many} many-side " \
+                "aggregates, not exactly one — #{declared.first} reduces a single " \
                 "collection's own rows; name which one by including only it"
         end
 
-        # `cursor` parses, round-trips through the IR, and is read by nothing —
-        # no interpreter (Memory, Sqlite, Postgres) ever applies it. Refusing
-        # it here, rather than deleting the word, keeps the declared syntax
-        # honest (the language still knows the shape) while refusing to let a
-        # bluebook author believe cursor-based pagination actually happens.
+        # `cursor` is parsed but no interpreter applies it, so it is refused rather than
+        # letting an author believe cursor pagination happens.
         def seal_cursor
           return unless @cursor
 
@@ -411,10 +288,7 @@ module Hecks
                 "pagination — use limit/offset instead"
         end
 
-        # `on:`'s own resolution (ADR 0055) — same demodulise `reference_to`/
-        # `include` already use for their own type argument. `nil` when `on:`
-        # is omitted, matching every other optional field's "absent, not
-        # false" reading in this file.
+        # Resolves `on:` to a type name; `nil` when omitted.
         def resolve_target(on) = on && Naming.demodulise(on)
 
         def add_aggregate_head(type, name, many:)

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

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