hecks 2.8.0 → 3.0.0

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

@@ -4,44 +4,16 @@ require_relative "../../runtime/value"
 module Hecks
   module QuerySpecification
     module Common
-      # **The one comparator table**. There were two, near-identical copies of
-      # this — `Ports::Query::InMemory` (the path a Memory- or Heki-backed
-      # aggregate query actually runs) and `Runtime::QueryInterpreter`
-      # (entity/sub-list queries, and any adapter implementing no `:query`)
-      # — plus a third partial reading of `comparable` inside
-      # `SqlQueryBuilder#query_value`.
-      #
-      # Two copies of one rule is not a style complaint here; it has cost
-      # real bugs twice already, both recorded in the comments those files
-      # carried. `none_in_state` was added to one copy only, so an ordinary
-      # Memory query's `none_in_state` clause fell to the `else` branch and
-      # silently excluded every row. And `comparable` diverged without
-      # anyone noticing: one copy took the first numeric member of a value
-      # object, the other only unwrapped when there was exactly one — so a
-      # value object with two numeric members compared as a number on one
-      # path and as a whole Hash on the other.
-      #
-      # The callers still differ in how they reach a value — one takes a
-      # registry argument, the other closes over `@registry`; one digs the
-      # field through `FieldPath`, the other is handed it — so they keep
-      # their own resolution and share only the comparison itself.
+      # The one comparator table shared by `Ports::Query::InMemory` and
+      # `Runtime::QueryInterpreter`, so every engine reads a where-clause identically.
       module Comparison
         module_function
 
         # Unwraps a value object to the one scalar a comparison can mean.
         #
-        # A value object compared as a scalar, when which scalar is meant
-        # is not in doubt. Exactly one numeric member is unambiguous; a
-        # single-member value object is unambiguous whatever its type.
-        # Anything else is returned unchanged rather than guessed at — two
-        # numeric members give no reason to prefer either, and picking the
-        # first silently compares a field the author never named.
-        #
-        # A declaration naming an ambiguous value object is refused when
-        # the bluebook loads (`AggregateBuilder`'s own query-field seal),
-        # so this branch is a backstop rather than the primary guard: which
-        # member is meant is knowable at declaration time, and a refusal
-        # naming the candidates is worth more than any runtime reading.
+        # Only a sole numeric member, or a sole member of any type, is unambiguous; anything
+        # else is returned unchanged rather than guessed at. Ambiguous declarations are refused
+        # at load, so this is a backstop.
         #
         # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
         #   `Runtime::Value` is read through its `to_h`
@@ -58,9 +30,8 @@ module Hecks
           value
         end
 
-        # Lists the members a value object offers a scalar comparison, for a
-        # refusal that can name them. Empty when the value object is
-        # unambiguous — nothing to report.
+        # Lists the members a value object offers a scalar comparison, for a refusal
+        # that can name them. Empty when the value object is unambiguous.
         #
         # @param value_object [Class<Bluebook::ValueObject>] the declared shape (a subclass
         #   minted by `Bluebook::ValueObject.declare`, closed sets included) a query field names
@@ -76,34 +47,19 @@ module Hecks
 
         NUMERIC_TYPES = %w[Integer Float Numeric].freeze
 
-        # Decides whether one where-clause comparison holds between the value
-        # a record holds and the value the query wants.
-        #
-        # A `case` over a closed, declared set (`Vocabulary::QueryComparator`,
-        # held equal to this list by spec/vocabulary_table_spec — see the
-        # `else` branch's own comment) is the whole point of the one
-        # comparator table this file's header describes: one place naming
-        # every comparator, not one method per comparator scattered across
-        # a module.
+        # Decides whether one where-clause comparison holds between the value a record
+        # holds and the value the query wants.
         #
-        # @param operation [Symbol, String] the comparator name: `eq`, `ne`, `lt`, `lte`,
-        #   `gt`, `gte`, `in`, `contains` or `none_in_state`
-        # @param held [Object, nil] the record's own value for the field; `nil` against a
-        #   non-nil `want` satisfies no comparator except `none_in_state` (see
-        #   `NullPolicy.unmatchable?`)
-        # @param want [Object, nil] the value compared against; for `in` an Array or a
-        #   comma-separated String, for `none_in_state` an `"Aggregate:state"` String
-        # @param registry [Runtime::Registry, nil] used only by `none_in_state` to look the
-        #   target aggregate up; `nil` makes that comparator hold
-        # @return [Boolean] whether the comparison holds; an ordered comparator over a
-        #   non-`Numeric` operand is `false`
-        # @raise [Runtime::WiringError] if `operation` names no comparator in this table, or
-        #   `none_in_state`'s target aggregate has no repository that can be wired
+        # @param operation [Symbol, String] `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `in`,
+        #   `contains` or `none_in_state`
+        # @param held [Object, nil] the record's own value for the field
+        # @param want [Object, nil] the value compared against
+        # @param registry [Runtime::Registry, nil] used only by `none_in_state`
+        # @return [Boolean] whether the comparison holds
+        # @raise [Runtime::WiringError] if `operation` names no comparator in this table
         # rubocop:disable-next Metrics/CyclomaticComplexity
         def holds?(operation, held, want, registry: nil)
-          # A NULL satisfies no comparison — NullPolicy.unmatchable? owns
-          # the rule and the reasoning, including why `none_in_state` is
-          # exempt from it.
+          # A NULL satisfies no comparison (`none_in_state` is exempt); see NullPolicy.
           return false if NullPolicy.unmatchable?(operation, held, want)
 
           case operation.to_s
@@ -117,24 +73,15 @@ module Hecks
           when "contains" then contains?(held, want)
           when "none_in_state" then none_in_state?(held, want, registry)
           else
-            # Every declared comparator has a `when` above (Vocabulary::
-            # QueryComparator, held equal to this list by
-            # spec/vocabulary_table_spec) — this is not a real runtime
-            # path today, only a backstop against the day a tenth
-            # comparator reaches the grammar and this method doesn't
-            # grow to match. Silently reading an unrecognized comparator
-            # as `eq` is exactly the failure this table already shipped
-            # once (see this file's own header) — an operator this
-            # method can't evaluate must refuse, not guess.
+            # Backstop: an unrecognized comparator must refuse, never read as `eq`.
             raise Runtime::WiringError, "no comparator handles #{operation.to_s.inspect} — add one before declaring it"
           end
         end
 
         # Checks that both operands of an ordered comparison are numbers.
         #
-        # gt/gte/lt/lte are numeric-only and silently false otherwise — a
-        # where-clause never raises the way a given does, and that contract
-        # predates the extraction (lt was already exactly this permissive).
+        # Ordered comparators are numeric-only and silently false otherwise; a where-clause
+        # never raises.
         #
         # @param held [Object, nil] the record's own value for the field
         # @param want [Object, nil] the value compared against
@@ -143,12 +90,8 @@ module Hecks
 
         # Reads a comparator's list operand as the Strings membership is tested against.
         #
-        # `in` reads a comma-separated list — a real Array survives
-        # untouched (a bluebook's own in-process value, before any wire
-        # serialisation), each element unwrapped the same way a scalar
-        # field is. This is `in`'s reading of its argument (a caller may
-        # legitimately pass "a,b,c" meaning "any of these") — unrelated to
-        # `contains`, which reads the stored field. See `contains?`.
+        # `in` accepts an Array or a comma-separated String; `contains` reads the stored
+        # field instead (see `contains?`).
         #
         # @param value [Array, String, Object, nil] an Array of elements, or anything whose
         #   `to_s` is a comma-separated list such as `"a, b,c"`
@@ -164,12 +107,6 @@ module Hecks
         # Answers `in`: whether the held value, or any element of a held Array,
         # occurs in the wanted list.
         #
-        # A folded reference hop asks whether the locally-held identity is
-        # among the matching target identities. A has_many relationship holds
-        # several identities, so the same question becomes an intersection:
-        # does any held identity occur in the wanted set? Scalar `in` retains
-        # its existing one-candidate behavior.
-        #
         # @param held [Array, Object] the record's own value; an Array contributes each
         #   element as a candidate, anything else is the single candidate
         # @param want [Array, String, Object] the wanted set, read through `members`
@@ -182,19 +119,10 @@ module Hecks
           candidates.any? { |candidate| wanted.include?(comparable(candidate).to_s) }
         end
 
-        # Answers `contains`: element membership for a held Array, substring
-        # for anything else.
+        # Answers `contains`: element membership for a held Array, substring for anything else.
         #
-        # `contains` means two different things depending on what is held —
-        # real element membership for a `list_of` field (a genuine Array
-        # arrives already, one element one member, nothing to split), and
-        # plain substring for anything else. The scalar case deliberately
-        # stays out of `members`' comma-split: that silently reads a
-        # free-text field's own comma as a separator — which the SQL
-        # side's `instr`/`position` never does, so the two disagree the
-        # moment a scalar's real content holds a comma. Matching SQL's
-        # substring reading here keeps every engine answering `contains`
-        # identically for the same declared field.
+        # A scalar is not comma-split, so free text containing a comma matches the way
+        # SQL's `instr`/`position` does.
         #
         # @param held [Array, Object] the record's own value; anything but an Array is
         #   read through `to_s`
@@ -206,29 +134,17 @@ module Hecks
           held.to_s.include?(want.to_s)
         end
 
-        # Answers `none_in_state` by looking the held identity up in another
-        # aggregate's repository and reading that record's state.
+        # Answers `none_in_state` by looking the held identity up in another aggregate's
+        # repository and reading that record's state.
         #
-        # **A cross-aggregate anti-join** — `where ref: { none_in_state:
-        # "Claim:held" }` holds when no record in the named aggregate,
-        # keyed by this record's own field value, is in the named state.
-        # No registry — no way to look the target up — reads as "not
-        # excluded", the same graceful default a missing record already
-        # falls back to. The target is searched by bare name across every
-        # loaded domain; ambiguity (two domains declaring one name) picks
-        # the first match rather than refusing, since a where-clause never
-        # raises (see `ordered?`).
+        # Holds when no such record is in the named state. No registry, aggregate or record
+        # reads as "not excluded". The target is found by bare name; the first match wins.
         #
-        # @param held [Object, nil] this record's own field value, used as the target
-        #   record's identity
-        # @param want [String, Symbol] `"Aggregate:state"` — the target aggregate's bare
-        #   name and the excluded state, split on the first colon
-        # @param registry [Runtime::Registry, nil] the booted registry to find the target
-        #   aggregate and its repository in
-        # @return [Boolean] `false` only when the target record exists and its lifecycle
-        #   field (or `:state`, absent a lifecycle) equals the named state; `true` when
-        #   there is no registry, no such aggregate or no such record
-        # @raise [Runtime::WiringError] if the target aggregate's repository cannot be wired
+        # @param held [Object, nil] this record's own field value, the target record's identity
+        # @param want [String, Symbol] `"Aggregate:state"`, split on the first colon
+        # @param registry [Runtime::Registry, nil] the booted registry
+        # @return [Boolean] `false` only when the target record is in the named state
+        # @raise [Runtime::WiringError] if the target's repository cannot be wired
         def none_in_state?(held, want, registry)
           return true unless registry
 
@@ -240,31 +156,7 @@ module Hecks
           record = registry.repository(target_domain, target_ir).find(held)
           return true unless record
 
-          # The field a state lives on, read from the target's own
-          # declaration — not assumed to be literally named `state`. Every
-          # `none_in_state` fixture this comparator originally shipped
-          # with (spec/query_none_in_state_*_spec.rb) happens to declare a
-          # plain `attribute :state, ...` rather than a real `lifecycle`,
-          # which is how the previous hardcoded `record.state[:state]`
-          # passed every one of them while being wrong for the shape this
-          # whole comparator exists to answer about: a real state machine.
-          # `lifecycle :field, default: ... do ... end` stores its state
-          # under `field` (`Instance#assign_creation_attributes`'s own
-          # `state[aggregate.lifecycle.field.to_sym] = ...`), and this
-          # codebase's own convention overwhelmingly names that field
-          # `status`, not `state` (`QualityControl::Clearance`'s own
-          # `lifecycle :status` among many others) — so the hardcoded key
-          # silently read `nil` from every real lifecycle-backed target,
-          # comparable(nil) != state was true unconditionally, and
-          # `none_in_state` against any lifecycle aggregate answered
-          # "not excluded" for every row, always, no matter its actual
-          # state. Found chasing `QualityControl::Bug.AwaitingClearance`
-          # (qa/bluebook/quality_control.bluebook), which is exactly this
-          # shape: `Clearance:green`/`Clearance:red` against a `lifecycle
-          # :status` aggregate. Falls back to `:state` when the target
-          # declares no lifecycle at all, so every existing fixture (a
-          # plain attribute literally named `state`) keeps answering
-          # exactly as before.
+          # The state lives on the target's lifecycle field, else on `:state`.
           field = target_ir.lifecycle&.field || :state
           comparable(record.state[field]) != state
         end

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

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

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

@@ -1,37 +1,23 @@
 module Hecks
   module QuerySpecification
     module Common
-      # Null-handling shared between the in-memory and SQL query
-      # engines: stable null-aware ordering (#order, #sql_order) and
-      # which comparators a null value can never satisfy (#unmatchable?,
-      # #sql_predicate) — kept in one place because Memory, Postgres and
-      # SQLite each default nulls differently and must be made to agree
-      # explicitly rather than leaking their own native behavior.
+      # Null handling shared by the in-memory and SQL query engines: null-aware ordering
+      # and the comparators a null can never satisfy, so every adapter agrees.
       module NullPolicy
         module_function
 
         # 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`.
+        # Stable on purpose: rows arrive in identity order, which makes ties deterministic.
+        # Descending reverses both partitions, matching `sql_order`'s `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
+        # @param direction [Symbol, String] `desc` sorts descending; anything else ascending
+        # @param policy [NullSemantics, nil] mode `first` or `last`; otherwise `native`
         # @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
+        # @yieldreturn [Comparable, nil] the sort key; `nil` marks the record null-keyed
+        # @return [Array<Object>] a new Array in the requested order
         def order(records, direction:, policy: nil, &key)
           descending = direction.to_s.downcase == "desc"
           null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
@@ -50,27 +36,13 @@ module Hecks
         # 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
-        # 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
-        # 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.
+        # An undeclared (`native`) policy still renders `NULLS ...`, because dialects
+        # differ (Postgres puts nulls last on ASC); this matches `#order`'s default.
         #
-        # @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"`
+        # @param expression [String] the SQL expression, interpolated as is
+        # @param direction [Symbol, String] `desc` renders `DESC`; anything else `ASC`
+        # @param policy [NullSemantics, nil] mode `first` or `last` pins the nulls
+        # @return [String] the terms without `ORDER BY`, 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
@@ -81,34 +53,13 @@ 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
-        # 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
-        # compared to is not.
+        # Comparators a NULL row value can never satisfy.
         #
-        # 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
-        # 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
-        # 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
-        # comparator whose `held` is a reference id, and a row holding no
-        # reference is genuinely "not in that state" rather than unknown.
+        # SQL treats `NULL <> 'red'` as unknown, so the row is dropped; Memory follows SQL.
+        # `none_in_state` is excluded: a row with no reference is not in that state.
         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.
+        # Decides whether a comparison is lost because the row's own value is null.
         #
         # @param operation [Symbol, String] the comparator name, such as `:ne`
         # @param held [Object, nil] the row's own value for the field
@@ -119,9 +70,8 @@ module Hecks
           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 `<>`.
+        # Renders the SQL for a comparison against a null value (`IS NULL`/`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

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

@@ -3,12 +3,8 @@ require_relative "null_semantics"
 module Hecks
   module QuerySpecification
     module Common
-      # The attribute set every query-shaped construct shares — wheres,
-      # ordering, paging, cursor, authorization, null semantics,
-      # inspection mode — plus `options_to_h`/`extra_options_to_h` for
-      # serializing it. Both Bluebook::Query and
-      # QuerySpecification::ReadModel::Specification subclass this
-      # rather than each declaring the same fields twice.
+      # The attribute set every query-shaped construct shares, plus `options_to_h` and
+      # `extra_options_to_h` for serializing it.
       class Options
         attr_reader :wheres, :order_by, :limit, :offset, :cursor,
                     :authorization, :null_semantics, :inspection

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

@@ -1,16 +1,8 @@
 module Hecks
   module QuerySpecification
     module Common
-      # `target` — which many-side `include`d aggregate this clause applies
-      # to on a `read_model` with more than one (ADR 0055's own `on:`,
-      # `ReadModelBuilder#where_impl`). Always `nil` for a plain `Query`'s
-      # own `where` (that builder never overrides `where_impl` to accept
-      # `on:`), and `nil` for a `read_model` with a single many-side head,
-      # where naming one is unnecessary. `to_h` omits the key entirely
-      # rather than emitting `target: nil` — the same "absent, not null"
-      # convention `count`/`median_field` already established
-      # (`lib/hecks/bluebook/read_model.rb`), so every read model that
-      # never uses `on:` keeps its existing wire shape byte-identical.
+      # One filter clause. `target` names the many-side `include`d aggregate on a
+      # `read_model` with several (ADR 0055); `to_h` omits it when `nil`.
       WhereClause = Struct.new(:field, :op, :value, :target, keyword_init: true) do
         def to_h
           base = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }