hecks 1.3.0 → 1.4.0

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

@@ -17,15 +17,27 @@ module Hecks
       # ReadModelBuilder so the two specification kinds parse the same
       # clauses identically rather than each carrying its own copy.
       module DSL
-        # RENAMED FROM `where`/`order_by`/`limit`/`offset`/`authorize`
-        # (all below) — item #13's full metaprogrammed dispatch (slice
-        # 4c). A SHARED mixin, same shape `attribute_impl` proved in
-        # slice 3: ONE renamed method each, both Query and ReadModel
-        # Keyword rows name it in `calls:`. `where`/`order_by` are
-        # bootstrap-reachable (every core chapter's own `read_model`
-        # filters its roster with them), so both are in
-        # BOOTSTRAP_CALLS_FALLBACK for the ReadModel context; `limit`/
-        # `offset`/`authorize` are not (checked directly).
+        # Records one `WhereClause` per `field => value` pair — what the
+        # `where` DSL word forwards to.
+        #
+        # `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.
+        #
+        # @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`
         def where_impl(clauses)
           @wheres ||= []
           clauses.each do |field, value|
@@ -34,15 +46,59 @@ module Hecks
           end
         end
 
+        # Records the query's single ordering, replacing any declared earlier.
+        #
+        # @param field [Symbol, String] the field to order by; a dotted path such as
+        #   `:"order.value"` reaches a value object's member
+        # @param direction [Symbol, String] `:asc` or `:desc`
+        # @return [OrderBy] the ordering just recorded
         def order_by_impl(field, direction = :asc)
           @order_by = OrderBy.new(field: field, direction: direction)
         end
 
+        # Records the most rows the query returns.
+        #
+        # @param value [Integer, Symbol] a literal row count, or a Symbol naming the query
+        #   argument that supplies it
+        # @return [LimitSpec] the limit just recorded
         def limit_impl(value) = @limit = LimitSpec.new(value: value)
+
+        # Records how many matched rows the query skips before the limit applies.
+        #
+        # @param value [Integer, Symbol] a literal row count, or a Symbol naming the query
+        #   argument that supplies it
+        # @return [OffsetSpec] the offset just recorded
         def offset_impl(value) = @offset = OffsetSpec.new(value: value)
+
+        # Records a cursor declaration. The word parses and round-trips, but both builders
+        # refuse it at `build` (`seal_cursor`) because no interpreter applies it.
+        #
+        # @param value [Symbol, Object] the query argument carrying the cursor, such as
+        #   `:after`, or a literal
+        # @return [CursorSpec] the cursor just recorded
         def cursor(value) = @cursor = CursorSpec.new(value: value)
+
+        # Records the authorization the query declares, and the argument that scopes it
+        # to one tenant.
+        #
+        # @param policy [Symbol, String] name of the access policy, such as `:vault_access`
+        # @param tenant [Symbol, String, nil] the field every ask must supply a value for
+        #   and is filtered by (`Runtime::TenantScope`); `nil` declares no tenant scoping
+        # @return [AuthorizationSpec] the authorization just recorded
         def authorize_impl(policy, tenant: nil) = @authorization = AuthorizationSpec.new(policy: policy, tenant: tenant)
+
+        # Records where a null sorts, overriding the `native` default.
+        #
+        # @param mode [Symbol, String] `:first` or `:last`; anything else orders as
+        #   `:native` does (see `NullPolicy.order`)
+        # @return [NullSemantics] the null policy just recorded
         def nulls(mode) = @null_semantics = NullSemantics.new(mode: mode)
+
+        # Records that the query asks its adapter to expose the query it generates.
+        #
+        # @param mode [Symbol, String] what to expose; `:sql` is the only mode
+        #   `Ports::Query.validate!` lets an adapter without `inspect_query` serve
+        # @return [InspectionSpec] the inspection request just recorded
         def inspect_query(mode = :sql) = @inspection = InspectionSpec.new(mode: mode)
 
         private

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

@@ -10,13 +10,27 @@ module Hecks
       module NullPolicy
         module_function
 
-        # STABLE on purpose : rows arrive already in identity order from
-        # Ports::Query::Ordering, and that base is what makes a tie deterministic
+        # Sorts records in memory by one key, placing the null-keyed ones where
+        # the policy says and keeping ties in their incoming order.
+        #
+        # Stable on purpose : rows arrive already in identity order from
+        # `Ports::Query::Ordering`, and that base is what makes a tie deterministic
         # rather than store-dependent. A plain sort_by is not stable in Ruby, so
         # equal keys would shuffle and the identity tier would be lost exactly
         # where it is needed. Descending reverses both partitions, so a tie reads
         # identity-descending too — the same total order sql_order renders as
         # `field DESC, id DESC`.
+        #
+        # @param records [Array<Object>] the rows to order, already in identity order
+        # @param direction [Symbol, String] `desc` sorts descending; anything else ascending
+        # @param policy [NullSemantics, nil] where nulls go: mode `first` or `last`; `nil` or
+        #   any other mode (`native`) puts nulls first ascending and last descending
+        # @yield reads the sort key out of one record
+        # @yieldparam record [Object] one element of `records`
+        # @yieldreturn [Comparable, nil] the key, mutually comparable across records; `nil`
+        #   marks the record as null-keyed
+        # @return [Array<Object>] a new Array holding every record in the requested order
+        # @raise [ArgumentError] if two non-nil keys cannot be compared with each other
         def order(records, direction:, policy: nil, &key)
           null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
           sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
@@ -31,18 +45,30 @@ module Hecks
           end
         end
 
-        # M3 — an UNDECLARED (`native`) null policy used to render no
-        # `NULLS ...` clause at all here, leaving each dialect's own
-        # default to decide: Postgres puts nulls LAST on ASC (and FIRST
+        # Renders the `ORDER BY` terms for one expression, with an explicit
+        # `NULLS FIRST`/`NULLS LAST` and an `id` tiebreak in the same direction.
+        #
+        # M3 — an undeclared (`native`) null policy still renders a
+        # `NULLS ...` clause. Rendering none leaves each dialect's own
+        # default to decide: Postgres puts nulls last on ASC (and first
         # on DESC), while `#order` above — this same "native" default,
-        # for Memory — puts nulls FIRST on ASC (and LAST on DESC), the
+        # for Memory — puts nulls first on ASC (and last on DESC), the
         # SQLite convention. Same query, same data, different row order
         # depending only on which adapter ran it. Rendered explicitly
-        # here instead, so an undeclared policy means the SAME total
+        # here instead, so an undeclared policy means the same total
         # order everywhere rather than "whatever this store already does"
         # — matching `#order`'s own default rather than the other way
         # round, since that default is unconditional (Memory/Heki have no
         # dialect to defer to) and SQLite already agrees with it natively.
+        #
+        # @param expression [String] the SQL expression to order by, already quoted or
+        #   built by the adapter; interpolated as is
+        # @param direction [Symbol, String] `desc` in any letter case renders `DESC`;
+        #   anything else `ASC`
+        # @param policy [NullSemantics, nil] mode `first` or `last` pins the nulls; `nil` or
+        #   any other mode renders `NULLS FIRST` ascending and `NULLS LAST` descending
+        # @return [String] the terms without the `ORDER BY` keyword, such as
+        #   `"price ASC NULLS FIRST, id ASC"`
         def sql_order(expression, direction, policy)
           direction = direction.to_s.downcase == "desc" ? "DESC" : "ASC"
           nulls = case policy&.mode.to_s
@@ -53,36 +79,54 @@ module Hecks
           "#{expression} #{direction}#{nulls}, id #{direction}"
         end
 
-        # THE COMPARATORS A NULL CANNOT SATISFY — the other half of
-        # `sql_predicate` below. That one answers "the value COMPARED TO is
+        # **The comparators a NULL cannot satisfy** — the other half of
+        # `sql_predicate` below. That one answers "the value compared to is
         # null" (`eq: nil` -> IS NULL, `ne: nil` -> IS NOT NULL, a real
         # convention both adapters already shared). This one answers the
-        # case nothing covered: the ROW'S OWN value is null and the value
+        # case nothing covered: the row's own value is null and the value
         # compared to is not.
         #
         # SQL says unknown. `NULL <> 'red'` is NULL, not true, so the row
         # is not returned. Ruby says `nil != "red"` is true, so it is. The
-        # two adapters therefore answered the SAME query on the SAME data
+        # two adapters therefore answered the same query on the same data
         # differently — Memory returning a row SQLite omitted — which is
         # not a difference of opinion a caller can plan around.
         #
         # Resolved toward SQL, and not because SQL is the store: an absent
-        # or null field is UNKNOWN, not a value, and a comparison against
+        # or null field is unknown, not a value, and a comparison against
         # unknown is unknown rather than true. Making SQL match Ruby
         # instead would mean compiling every `ne:` to
         # `(col <> $1 OR col IS NULL)` — more to get right in two
         # dialects, and a reliable way to lose an index — to make a real
         # query engine agree with an in-memory one.
         #
-        # `none_in_state` is deliberately NOT here: it is a 9th, vendored
+        # `none_in_state` is deliberately not here: it is a 9th, vendored
         # comparator whose `held` is a reference id, and a row holding no
         # reference is genuinely "not in that state" rather than unknown.
         NULL_UNMATCHABLE = %w[eq ne lt lte gt gte in contains].freeze
 
+        # Decides whether a comparison is lost before it starts because the row's
+        # own value is null — the rule `NULL_UNMATCHABLE`'s comment argues for.
+        #
+        # @param operation [Symbol, String] the comparator name, such as `:ne`
+        # @param held [Object, nil] the row's own value for the field
+        # @param want [Object, nil] the value compared against
+        # @return [Boolean] `true` when `held` is `nil`, `want` is not, and the comparator is
+        #   one of `NULL_UNMATCHABLE`; `none_in_state` is never unmatchable
         def unmatchable?(operation, held, want)
           held.nil? && !want.nil? && NULL_UNMATCHABLE.include?(operation.to_s)
         end
 
+        # Renders the SQL for a comparison against a null value — `eq: nil` as
+        # `IS NULL`, `ne: nil` as `IS NOT NULL` — so an adapter never binds a
+        # `NULL` parameter to `=` or `<>`.
+        #
+        # @param expression [String] the SQL expression for the field, interpolated as is
+        # @param operation [Symbol, String] the comparator name
+        # @param value [Object, nil] the resolved value compared against
+        # @return [Array(String, Array), nil] the predicate text and its (empty) bind
+        #   parameters; `nil` when `value` is not `nil` or the comparator is neither `eq`
+        #   nor `ne`, leaving the adapter to render the clause itself
         def sql_predicate(expression, operation, value)
           if value.nil? && operation.to_s == "eq"
             ["#{expression} IS NULL", []]

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

@@ -4,6 +4,10 @@ module Hecks
       NullSemantics = Struct.new(:mode, keyword_init: true) do
         def to_h = { mode: mode.to_s }
 
+        # Builds the policy a query has when it never writes `nulls`: each
+        # engine orders nulls first ascending and last descending (see `NullPolicy`).
+        #
+        # @return [NullSemantics] a new instance whose mode is `:native`
         def self.default = new(mode: :native)
       end
     end

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

@@ -13,6 +13,18 @@ module Hecks
         attr_reader :wheres, :order_by, :limit, :offset, :cursor,
                     :authorization, :null_semantics, :inspection
 
+        # @param wheres [Array<WhereClause>] the filter clauses, all of which must hold
+        # @param order_by [OrderBy, nil] the single ordering; `nil` leaves identity order
+        # @param limit [LimitSpec, nil] the most rows returned; `nil` is unbounded
+        # @param offset [OffsetSpec, nil] rows skipped before the limit; `nil` skips none
+        # @param cursor [CursorSpec, nil] the cursor declaration; `nil` when none is declared
+        # @param authorization [AuthorizationSpec, nil] the declared policy and tenant field;
+        #   `nil` when the query declares no `authorize`
+        # @param inspection [InspectionSpec, nil] the `inspect_query` request; `nil` when
+        #   the query asks for none
+        # @param null_semantics [NullSemantics, nil] where nulls sort; stored as given, so
+        #   an explicit `nil` (what `ReadModelBuilder` passes when `nulls` was never
+        #   written) stays `nil` rather than becoming the `native` default
         def initialize(wheres: [], order_by: nil, limit: nil, offset: nil, cursor: nil,
                        authorization: nil,
                        inspection: nil, null_semantics: NullSemantics.default)
@@ -26,12 +38,25 @@ module Hecks
           @inspection = inspection
         end
 
+        # Serializes every shared option, declared or not, so a subclass's `to_h`
+        # has one fixed set of keys to build on.
+        #
+        # @return [Hash{Symbol => Array<Hash>, Hash, nil}] keys `:wheres` (an Array of clause
+        #   Hashes, `[]` when none), `:order_by`, `:limit`, `:offset`, `:cursor`,
+        #   `:authorization`, `:null_semantics` and `:inspection`, each that spec's own
+        #   `to_h` or `nil` when undeclared
         def options_to_h
           { wheres: @wheres.map(&:to_h), order_by: @order_by&.to_h, limit: @limit&.to_h,
             offset: @offset&.to_h, cursor: @cursor&.to_h, authorization: @authorization&.to_h,
             null_semantics: @null_semantics&.to_h, inspection: @inspection&.to_h }
         end
 
+        # Serializes only the declared options beyond the settled three, so a
+        # construct that never wrote one keeps its wire shape unchanged.
+        #
+        # @return [Hash{Symbol => Hash}] the subset of `options_to_h` that is set, without
+        #   `:wheres`, `:order_by` and `:limit` (which the subclass emits itself) and
+        #   without a `:null_semantics` of `{ mode: "native" }`; `{}` when nothing is
         def extra_options_to_h
           options_to_h.reject do |key, value|
             value.nil? || value == [] || (key == :null_semantics && value == { mode: "native" })

data/lib/hecks/query_specification/field_path.rb

@@ -1,20 +1,21 @@
 module Hecks
   module QuerySpecification
-    # ONE reading of a dotted query-field path, shared by every place that
-    # used to invent its own. The reference interpreter did a bare
-    # `record[field]` lookup (a dotted path silently matched nothing), the
-    # SQL side split dots but judged numericness from the FIRST nested
-    # segment only (a two-level path quietly compared text), and the build
-    # seal walked the declaration graph a third way. Three
-    # implementations of "what does pizza.price_cents.cents mean" is two
-    # more than a language gets to have.
+    # One reading of a dotted query-field path, shared by every place that
+    # would otherwise invent its own. Left to themselves they disagree: a
+    # reference interpreter doing a bare `record[field]` lookup silently
+    # matches nothing for a dotted path, an SQL side that splits dots but
+    # judges numericness from the first nested segment only quietly
+    # compares a two-level path as text, and a build seal walks the
+    # declaration graph a third way. Three implementations of "what does
+    # pizza.price_cents.cents mean" is two more than a language gets to
+    # have.
     #
     # Two sides, deliberately in one file so they cannot drift:
     #
-    #   dig(holder, field)        — VALUE side: walk a record's held state,
+    #   dig(holder, field)        — value side: walk a record's held state,
     #                               segment by segment, through Value
     #                               objects and plain hashes alike.
-    #   leaf_attribute / numeric? — DECLARATION side: walk the declared
+    #   leaf_attribute / numeric? — declaration side: walk the declared
     #                               shape to the attribute a path lands on.
     #                               Callers supply value-object lookup as a
     #                               block, because an Aggregate and a
@@ -26,22 +27,39 @@ module Hecks
       NUMERIC_PRIMITIVES = %w[Integer Float].freeze
       SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
 
+      # Reads the value a dotted field path names out of a record's held state.
+      #
       # The held value a dotted field names, or nil — never a raise. The
       # first segment reads off the record (an Instance, a Value, or a
       # plain row hash); the rest read through whatever each step holds. A
       # stored nested value object is a plain hash by the time it is read
       # back, keyed by symbol in memory and by string off a wire decode,
       # so both spellings are tried — `key?` first, never `||`, because
-      # `||` falls through a genuinely-stored `false` to the OTHER
+      # `||` falls through a genuinely-stored `false` to the other
       # spelling (usually absent) and returns `nil` instead. The seal
       # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
       # here is a real, held answer, not a missing one.
+      #
+      # @param holder [Runtime::Instance, Runtime::Value, Hash, nil] the record, value
+      #   object or row Hash the first segment is read from
+      # @param field [String, Symbol, nil] the path, segments separated by `.`, such as
+      #   `"price.cents"`; a bare field name is a one-segment path
+      # @return [Object, nil] the value held at the end of the path; `nil` when `field` is
+      #   `nil`, a segment is absent, or a step lands on `nil` or an Array
       def dig(holder, field)
         return nil if field.nil?
 
         field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
       end
 
+      # Reads one path segment off whatever the previous step held — a single
+      # step of `dig`.
+      #
+      # @param current [Runtime::Instance, Runtime::Value, Hash, Array, nil] the value the
+      #   walk has reached; a Hash is tried by Symbol key, then by String key
+      # @param segment [String] one segment of the dotted path
+      # @return [Object, nil] the member named `segment`; `nil` when `current` is `nil` or
+      #   an Array, or holds no such member
       def read(current, segment)
         return nil if current.nil?
 
@@ -54,7 +72,7 @@ module Hecks
         # an Array broke it: `Array#[]` demands an Integer index, so
         # `current[segment]` (a String) raised `TypeError` straight
         # through `dig` instead of answering nil. A dotted path stepping
-        # INTO a list_of attribute (`where "tags.name" == "x"` against a
+        # into a list_of attribute (`where "tags.name" == "x"` against a
         # bare list, rather than each element) has no single member a
         # bare index would name anyway — nil is the honest answer, the
         # same one a dangling reference or a missing key already gets.
@@ -63,11 +81,23 @@ module Hecks
         current[segment]
       end
 
+      # Walks the declared shape to the attribute a dotted path lands on.
+      #
       # The declared attribute a path lands on, or nil. `segments` is the
       # dotted tail — for a bare field it is empty and the root attribute
       # is its own leaf. The walk stops dead at a reference (an id is a
       # scalar; nothing nests under it) and at any member the declared
       # value object does not carry.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path's first
+      #   segment names; `nil` (no such attribute) answers `nil`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name in the caller's own declarations
+      # @yieldparam type [String] the type name of the attribute being stepped into
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil` when
+      #   the type is not a value object the caller knows
+      # @return [Bluebook::Attribute, nil] the attribute at the end of the path; `nil` when
+      #   a step crosses a reference, an undeclared type or a member that does not exist
       def leaf_attribute(attribute, segments)
         current = attribute
         segments.each do |segment|
@@ -79,12 +109,24 @@ module Hecks
         current
       end
 
+      # Decides from the declared shape whether a field path holds a number.
+      #
       # May an ordered comparator (lt/lte/gt/gte) land here, and may an
-      # ORDER BY cast here numerically? A bare field keeps the one-level
+      # `ORDER BY` cast here numerically? A bare field keeps the one-level
       # convention every adapter already implements: a numeric primitive,
       # or a value object carrying at least one numeric member. A dotted
       # path must land on a numeric primitive itself — the convention does
-      # not reach through a named path, it IS the absence of one.
+      # not reach through a named path, it is the absence of one.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
+      #   `nil` answers `false`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name, as for `leaf_attribute`
+      # @yieldparam type [String] the type name to look up
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Boolean] `true` when the leaf is an `Integer` or `Float`, or a bare field
+      #   naming a value object with at least one such member; `false` for a list, a
+      #   reference, or a path that lands nowhere
       def numeric?(attribute, segments, &)
         leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
@@ -95,9 +137,21 @@ module Hecks
         !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
       end
 
-      # A dotted path must end on a SCALAR member — landing on a value
+      # Decides whether a path ends on a scalar primitive that every engine
+      # compares the same way.
+      #
+      # A dotted path must end on a scalar member — landing on a value
       # object would hand SQL a JSON object where the reference
       # interpreter unwraps a hash, and the two would answer differently.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
+      #   `nil` answers `false`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name, as for `leaf_attribute`
+      # @yieldparam type [String] the type name to look up
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Boolean] `true` when the leaf is a non-list, non-reference attribute typed
+      #   `String`, `Integer`, `Float`, `TrueClass` or `FalseClass`
       def scalar_leaf?(attribute, segments, &)
         leaf = leaf_attribute(attribute, segments, &)
         !leaf.nil? && !leaf.list? && !leaf.reference? && SCALAR_PRIMITIVES.include?(leaf.type.to_s)

data/lib/hecks/query_specification/hop_path.rb

@@ -2,25 +2,25 @@ require_relative "../naming"
 
 module Hecks
   module QuerySpecification
-    # ONE reading of a dotted query-field path that hops THROUGH a
+    # One reading of a dotted query-field path that hops through a
     # reference into another aggregate's own shape — FieldPath's
-    # sibling, not its member. FieldPath walks a SHAPE, which cannot
+    # sibling, not its member. FieldPath walks a shape, which cannot
     # loop, and answers nil, never raising, because there is nothing
-    # left to say beyond "not found." HopPath walks the REFERENCE
-    # GRAPH instead — `BluebookBuilder#validate_no_bidirectional_references!`
-    # refuses any reference CYCLE at declaration time (ADR 0025,
+    # left to say beyond "not found." HopPath walks the reference
+    # graph instead — `BluebookBuilder#validate_no_bidirectional_references!`
+    # refuses any reference cycle at declaration time (ADR 0025,
     # "References" — widened from a direct pair to any ring, DFS over
     # the chapter's own reference graph), so what's left to guard here
     # is depth, not cycles: MAX_HOPS below, and this module's own
     # `refusal` states for a target the chapter doesn't resolve. A walk
-    # here still needs to say WHY it stopped, not just that it did.
+    # here still needs to say why it stopped, not just that it did.
     #
-    # Every method below takes an ATTRIBUTE ARRAY, never a "shape"
+    # Every method below takes an attribute array, never a "shape"
     # object — deliberately, because the two real callers hold their
     # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
     # build) exposes `attributes` as a plain reader, but its own
     # `attribute(name, type = String, ...)` is the DSL's attribute-
-    # DECLARING method — calling it as a finder would silently mint a
+    # declaring method — calling it as a finder would silently mint a
     # new String attribute instead of looking one up. A sealed
     # `Aggregate` (tier-2 seal, and every runtime target) has a
     # real `attribute(name)` finder, but taking the array either way
@@ -37,37 +37,51 @@ module Hecks
       Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
 
       # A hop chain long enough to matter is long enough to be a
-      # mistake — NOT a guard against a walk that cannot terminate.
+      # mistake — not a guard against a walk that cannot terminate.
       # Nothing here loops forever regardless of how the reference
       # graph is shaped: a hop chain is a literal dotted string, fixed
       # at declaration time, and every step consumes exactly one of
-      # its own segments — the walk is bounded by what was TYPED, not
+      # its own segments — the walk is bounded by what was typed, not
       # by the graph. A self-referential aggregate hopping through
       # itself more than once (`"parent.parent.name"`, a grandparent
       # query) is real, common, and perfectly safe; this exists only
       # to refuse a chain nobody meant to write this long.
       MAX_HOPS = 8
 
+      # Names the path segment a reference attribute answers to.
+      #
       # The segment name a Reference answers to in a hop path — its own
       # declared attribute name, unchanged (ADR 0025, "References":
-      # `reference_to` mints that bare name now, no `_id`, so there is
+      # `reference_to` mints that bare name, no `_id`, so there is
       # no derivation left to apply). `proposal/client` (a query hop)
       # and `proposal.client` (the Ruby accessor,
       # `Facade::Handle#define_reference_accessors`) name the same
       # concept the same way.
+      #
+      # @param attribute [Bluebook::Attribute] a reference-typed attribute
+      # @return [String] the attribute's declared name
       def hop_name(attribute) = attribute.name.to_s
 
-      # Does this path's HEAD cross into another record via `/`? THE
-      # OPERATOR IS THE ANSWER NOW, not a name collision to arbitrate —
+      # Decides whether a field path starts by hopping through one of the given
+      # references, without resolving the reference's target.
+      #
+      # Does this path's head cross into another record via `/`? The
+      # operator is the answer now, not a name collision to arbitrate —
       # `.` walks fields inside this record, `/` crosses into another
       # one, so a path with no `/` is never a hop, full stop, and the
-      # OLD "a real local attribute wins first" rule (needed only
+      # old "a real local attribute wins first" rule (needed only
       # because `.` was overloaded for both meanings, and `client_id`
       # vs `client` was how the two were told apart) has nothing left
       # to arbitrate. Answerable from `attributes` alone — a Reference
       # knows its own `target_name` at declaration, before it can
-      # `resolve` it — which is what lets the AGGREGATE seal recognise
+      # `resolve` it — which is what lets the aggregate seal recognise
       # a hop it cannot yet check.
+      #
+      # @param field [String, Symbol] the query field path, such as `:"client/status"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Boolean] `true` when the path has a `/` and the segment before the first
+      #   one names a reference attribute
       def hop_head?(field, attributes)
         head, rest = field.to_s.split("/", 2)
         return false unless rest
@@ -75,16 +89,27 @@ module Hecks
         attributes.any? { |candidate| candidate.reference? && hop_name(candidate) == head }
       end
 
-      # ONE STEP: does `field`'s head hop through one of `attributes`'
+      # Resolves the first hop of a field path and hands back what is left to walk.
+      #
+      # **One step**: does `field`'s head hop through one of `attributes`'
       # own references? Answers the resolved `Hop` plus the string
       # still left to walk (itself possibly another `/`-hop, against
-      # the TARGET's own attributes, or a plain `.`-dotted field walk
+      # the target's own attributes, or a plain `.`-dotted field walk
       # once the hops run out) — or nil, when the head names nothing or
       # the path has no `/` at all. This is the one primitive
       # Runtime::ReferenceHop needs: it recurses hop by hop through its
       # own `apply`, one ordinary same-aggregate query at a time, and
       # never needs the whole chain resolved up front the way a seal
       # does.
+      #
+      # @param field [String, Symbol] the query field path, such as `"client/region/name"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Array(Hop, String), nil] the hop and the rest of the path after the first
+      #   `/`; the hop's `target` is `nil` when the referenced aggregate is not in the
+      #   declaring chapter. `nil` when the path has no `/` or its head names no reference
+      # @raise [Bluebook::DSL::Malformed] if the reference has no `declared_in` aggregate
+      #   to resolve its target through
       def next_hop(field, attributes)
         head, rest = field.to_s.split("/", 2)
         return nil unless rest
@@ -96,10 +121,22 @@ module Hecks
         [hop, rest]
       end
 
-      # The WHOLE chain, resolved — every hop's target found, in
+      # Resolves every hop of a field path in order, stopping with a reason at
+      # the first one it cannot follow.
+      #
+      # The whole chain, resolved — every hop's target found, in
       # order — for the one caller that needs it all at once:
-      # BluebookBuilder#validate_query_hops!, checking a hop chain
+      # `BluebookBuilder#validate_query_hops!`, checking a hop chain
       # before anything ever dispatches it.
+      #
+      # @param field [String, Symbol] the query field path, such as `"client/region/name"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Plan] `hops` walked so far; `tail` the remaining `.`-dotted field (`nil`
+      #   on refusal); `refusal` `nil` when clean, `:unresolvable` when the last hop's
+      #   target is not found, `:too_deep` when the chain exceeds `MAX_HOPS`
+      # @raise [Bluebook::DSL::Malformed] if a reference on the path has no `declared_in`
+      #   aggregate to resolve its target through
       def plan(field, attributes)
         hops = []
         remaining = field.to_s
@@ -113,7 +150,7 @@ module Hecks
           return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
 
           # Pushed even unresolved — a caller reporting :unresolvable
-          # needs THIS hop's own target_name (real, known at
+          # needs this hop's own target_name (real, known at
           # declaration, regardless of whether resolve succeeded), not
           # whatever hop came before it. `.target` is nil on this one
           # entry; every caller checking `hops.last.target` already has

data/lib/hecks/query_specification/read_model/specification.rb

@@ -9,6 +9,10 @@ module Hecks
       class Specification < Common::Options
         attr_reader :joins
 
+        # @param joins [Array<Hash{Symbol => Object}>] one row per projected aggregate head,
+        #   keyed `:aggregate` (String target name), `:as` (Symbol output name) and `:many`
+        #   (Boolean), as `ReadModelBuilder` builds them
+        # @param ** [Hash] the shared query options, passed to `Common::Options#initialize`
         def initialize(joins: [], **)
           super(**)
           @joins = joins

data/lib/hecks/rendering.rb

@@ -1,8 +1,8 @@
 require "json"
 
 module Hecks
-  # HOW A VALUE READS INSIDE A REFUSAL, in one place, because a refusal is an
-  # ANSWER and its wording is contract — pinned byte-for-byte by the corpus.
+  # How a value reads inside a refusal, in one place, because a refusal is an
+  # answer and its wording is contract — pinned byte-for-byte by the corpus.
   #
   # `inspect` and JSON agree on scalars and disagree on everything composite :
   # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
@@ -29,7 +29,7 @@ module Hecks
         # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
         # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
         # rather than naming `Runtime::Value` directly — `Runtime::Value`
-        # itself requires THIS file (`runtime/value.rb`'s own
+        # itself requires this file (`runtime/value.rb`'s own
         # `require_relative "../rendering"`), so naming it here would be
         # circular. A single-field wrapper (the overwhelming common case
         # — an amount, an id, a lifecycle field) unwraps to its bare