hecks 1.3.0 → 1.5.0

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

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

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,39 +10,67 @@ 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` in any letter case 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)
+          descending = direction.to_s.downcase == "desc"
           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)
-          if direction.to_s == "desc"
+          if descending
             sorted.reverse!
             null_rows.reverse!
           end
           case policy&.mode.to_s
           when "first" then null_rows + sorted
           when "last" then sorted + null_rows
-          else direction.to_s == "desc" ? sorted + null_rows : null_rows + sorted
+          else descending ? sorted + null_rows : null_rows + sorted
           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 +81,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" })