hecks 0.2.0 → 1.0.0

data/lib/hecks/query_ir.rb

@@ -0,0 +1,411 @@
+require "set"
+require_relative "bluebook"
+require_relative "codemod"
+require_relative "projections/model"
+require_relative "fuzzing/properties"
+
+module Hecks
+  # THE SHARED CORE behind `bin/query_ir` (a text CLI) and
+  # `bin/hecks_query_ir_mcp` (an MCP server exposing the same two
+  # queries as tools) — one implementation, two front ends, the same
+  # reason `Hecks::Codemod` exists once rather than per-script.
+  # Every method here returns structured data (Hashes/Arrays/Structs),
+  # never formatted text — formatting is each front end's own job.
+  module QueryIR
+    Codemod    = Hecks::Codemod
+    Deviations = Hecks::Projections::Model::Deviations
+
+    # THE SAME MAPPING spec/model_shape_conformance_spec.rb's own
+    # MODEL_CONSTRUCTS holds — kept here rather than shared from the
+    # spec (a spec file is not a library other code should require),
+    # matching Deviations' own doc comment: "the generator and the gate
+    # read one source" — Deviations is that one source; this table is
+    # small and genuinely construct-list bookkeeping, not a rule that
+    # can drift silently the way a Deviations entry could.
+    CONSTRUCTS = {
+      "Bluebook"       => Hecks::Bluebook::Chapter,
+      "Aggregate"      => Hecks::Bluebook::Aggregate,
+      "Command"        => Hecks::Bluebook::Command,
+      "Entity"         => Hecks::Bluebook::Entity,
+      "ValueObject"    => Hecks::Bluebook::ValueObject,
+      "Policy"         => Hecks::Bluebook::Policy,
+      "Query"          => Hecks::Bluebook::Query,
+      "ReadModel"      => Hecks::Bluebook::ReadModel,
+      "ProcessManager" => Hecks::Bluebook::ProcessManager
+    }.freeze
+
+    Rule = Struct.new(:kind, :description, :canonical, :location, keyword_init: true)
+
+    module_function
+
+    def meta_declared(name)
+      Hecks::Bluebook::MetaValidator.grammar_registry
+                                    .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
+    end
+
+    # The real structural diff between what a Ruby IR class emits
+    # (Class.ir_spec.keys) and what the self-hosted meta-domain declares
+    # for it — the SAME comparison spec/model_shape_conformance_spec.rb
+    # makes, reusing its own Deviations data so this can never silently
+    # drift from what that gate actually checks.
+    def construct_diff(name)
+      klass = CONSTRUCTS.fetch(name) {
+        raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
+      }
+      declared = meta_declared(name)
+      emitted  = klass.ir_spec.keys
+
+      accounted = declared.reject { |field| Deviations::PARENT_REF.call(field) } -
+                  Deviations::JUDGE_ONLY -
+                  Deviations.folded(name).values.flatten -
+                  Deviations.off_the_wire(name) -
+                  Deviations.dynamic_tail(name) -
+                  Deviations.unpacked(name).keys
+
+      unaccounted = emitted -
+                    declared -
+                    Deviations.contained(name) -
+                    Deviations.folded(name).keys -
+                    Deviations.computed(name) -
+                    Deviations.unpacked(name).values.flatten
+
+      { name: name, declared: declared, emitted: emitted,
+        missing_from_ruby: accounted - emitted, unaccounted_in_ruby: unaccounted }
+    end
+
+    def constructs(names = [])
+      targets = names.empty? ? CONSTRUCTS.keys : names
+      targets.map { |name| construct_diff(name) }
+    end
+
+    # Every given/ensures/invariant DECLARATION reachable from a booted
+    # registry, walked recursively — every owner's own `.preconditions`/
+    # `.invariants` (block-declared rules), every value object's own
+    # `.invariants`, and every command's own `.givens`/`.ensures`
+    # (`.givens` too, not just `.ensures` — a command's own LOCAL
+    # `given("x") { block }` not yet hoisted to its owner, round 4's own
+    # starting shape, would otherwise be invisible).
+    #
+    # NOT keyed by object identity (a real, hard-won correction — see
+    # the comment on `duplicates`' own dedup below for why: a bare
+    # `given("x")` reference and its owner's own block declaration are
+    # the SAME Ruby object at DSL build time, but `MetaValidator.call`
+    # (S14 — every bluebook is judged by dispatching its OWN IR into the
+    # self-hosted grammar, then reconstructed via `Assembly.call` from
+    # flat rows) rebuilds the whole graph fresh from there. By the time
+    # any caller reads `chapter.aggregates`, EVERY given/invariant is
+    # already a distinct object, whether it was block-declared or
+    # bare-referenced — object identity carries no signal past that
+    # point, for any construct, not just this one).
+    def collect_rules(registry, chapter_name = nil)
+      rules = []
+      chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
+
+      walk_construct = lambda do |construct, path|
+        (construct.respond_to?(:preconditions) ? construct.preconditions : []).each do |rule|
+          rules << Rule.new(kind: "given", description: rule.description, canonical: rule.canonical,
+                            location: "#{path} (declared)")
+        end
+        (construct.respond_to?(:invariants) ? construct.invariants : []).each do |rule|
+          rules << Rule.new(kind: "invariant", description: rule.description, canonical: rule.canonical,
+                            location: "#{path} (declared)")
+        end
+        construct.commands.each do |command|
+          command.givens.each do |rule|
+            rules << Rule.new(kind: "given", description: rule.description, canonical: rule.canonical,
+                              location: "#{path}.#{command.hecks_name}")
+          end
+          command.ensures.each do |rule|
+            rules << Rule.new(kind: "ensures", description: rule.description, canonical: rule.canonical,
+                              location: "#{path}.#{command.hecks_name}")
+          end
+        end
+        construct.entities.each { |piece|
+          walk_construct.call(piece, "#{path}.#{piece.hecks_name}")
+        } if construct.respond_to?(:entities)
+      end
+
+      chapters.each do |chapter|
+        chapter.aggregates.each do |aggregate|
+          walk_construct.call(aggregate, aggregate.hecks_name)
+          aggregate.value_objects.each do |vo|
+            vo.invariants.each do |rule|
+              rules << Rule.new(kind: "invariant", description: rule.description, canonical: rule.canonical,
+                                location: "#{aggregate.hecks_name}::#{vo.hecks_name} (declared)")
+            end
+          end
+        end
+      end
+      rules
+    end
+
+    # A rule's OWNER — the construct path a "(declared)" location names
+    # directly, or (for a command-level `.givens`/`.ensures` entry) the
+    # path with its trailing `.CommandName` segment stripped. Two rules
+    # sharing an owner are the SAME declaration read twice (an owner's
+    # own precondition, and a command under it referencing that
+    # precondition by name) — not two independent ones.
+    #
+    # PUBLIC, not a `duplicates`-only internal — `bin/codemod_hoist_
+    # local_givens` reads it directly to group `collect_rules`' own
+    # output by owner itself, the same reading `duplicates`' own
+    # `declaration_count` makes.
+    def owner_of(location)
+      return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
+
+      location.rpartition(".").first
+    end
+
+    # Grouped by (kind, description, canonical), not canonical text
+    # alone — a generic one-liner like `!value.to_s.empty?` legitimately
+    # recurs dozens of times for unrelated fields; the real signal is
+    # the SAME RULE (same description, same predicate), which is also
+    # exactly what the given/invariant reference mechanism itself
+    # resolves on.
+    #
+    # DEDUPED BY OWNER, not object identity (`collect_rules`' own
+    # comment has the full story — identity is gone by the time this
+    # reads the registry). Within a group, every command-level rule
+    # whose OWNER already has its own "(declared)" entry in the same
+    # group is just that declaration read again through a reference —
+    # `Account.Open`/`Account.Credit`/etc. all naming `Account`'s own
+    # `given("customer is active")` count as Account's ONE declaration,
+    # not nine. A command-level rule with no matching owner declaration
+    # (a LOCAL, not-yet-hoisted `given("x") { block }`) counts as its
+    # own standalone declaration — two different commands independently
+    # writing the identical local predicate IS two declarations, a real
+    # hoisting opportunity. A group is reported only when it adds up to
+    # MORE than one real declaration this way.
+    #
+    # `domains: []` means "the self-hosted meta-domain only" — pass real
+    # domain directories explicitly to include them, or `nil` (the
+    # default) for meta-domain plus every real example.
+    def duplicates(domains: nil, include_meta: true)
+      domains ||= Codemod::EXAMPLE_ROOTS
+      all_rules = []
+      all_rules.concat(collect_rules(Codemod.meta_registry)) if include_meta
+
+      domains.each do |domain_dir|
+        bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+        next if bluebook_files.empty?
+
+        registry = Codemod.load_bluebook(bluebook_files)
+        all_rules.concat(collect_rules(registry))
+      end
+
+      all_rules.group_by { |r| [r.kind, r.description, r.canonical] }
+               .map { |key, rules| [key, rules, declaration_count(rules)] }
+               .select { |_, _, count| count > 1 }
+               .map { |(kind, description, canonical), rules, _|
+        { kind: kind, description: description, canonical: canonical,
+      locations: rules.map(&:location) }
+      }
+    end
+
+    # `given` ONLY (not `invariant`/`ensures`) also covers CROSS-ENTITY
+    # coverage — one piece's own entity-level declaration, shared with
+    # any OTHER piece nested under the SAME root aggregate (real corpus
+    # this closes: SafeDepositBox's own `Visit`/`KeyIssuance`, two
+    # different pieces on one head). A rule owned by a nested entity
+    # (its own owner path has more than one segment) is covered when
+    # SOME "(declared)" entry exists ANYWHERE under that SAME root
+    # aggregate — not just under its OWN exact owner — matching the
+    # DSL's own pool, threaded unchanged through an aggregate's whole
+    # entity tree (`AggregateBuilder#entity`'s own comment).
+    #
+    # A KNOWN, ACCEPTED GAP this does NOT (and structurally cannot)
+    # close: CHAPTER-WIDE given sharing (`AggregateBuilder#given`'s own
+    # bare form, `docs/implemented/resolution-rules/chapter-given.md`) — `Account`,
+    # `SafeDepositBox`, and `OnboardingCase` each still show as their
+    # own "(declared)" owner here even AFTER `SafeDepositBox`/
+    # `OnboardingCase` were converted to bare chapter-wide references,
+    # because a REFERENCED given still write-throughs into its own
+    # aggregate's `@named_givens` — the SAME reason `collect_rules`'
+    # own top comment already gives for why object identity carries no
+    # signal past a bluebook's own build: the EXPORTED IR cannot tell
+    # "I declared this myself" apart from "I referenced someone else's
+    # declaration," because by the time anything reads `chapter.
+    # aggregates`, both look identical. Closing this would mean reading
+    # SOURCE TEXT (bare `given(desc)` vs. block `given(desc) { ... }`),
+    # not the built IR this query is deliberately built on — a
+    # different, source-level tool, not a fix to this one. Treat a
+    # still-flagged group naming multiple aggregates as "verify by
+    # hand whether this is ALREADY a chapter-wide reference before
+    # assuming it's fresh duplication," not as an automatic signal
+    # either way.
+    #
+    # THE IDENTICAL GAP, ONE LEVEL DOWN: chapter-wide ENTITY-scoped
+    # sharing (`EntityBuilder#given`'s own bare form,
+    # `docs/implemented/resolution-rules/chapter-entity-given.md`) hits this same wall for
+    # the same structural reason — `SafeDepositBox.Visit` still shows
+    # as its own "(declared)" owner here even after becoming a bare
+    # reference to `Account.LedgerEntry`'s declaration, because a piece
+    # resolving a chapter-wide reference still write-throughs the
+    # resolved `Given` into its own `@named_givens` (so ITS OWN
+    # commands can read it back locally without a second hop). This is
+    # not a NEW limitation this feature introduces — it is the exact
+    # same IR-cannot-distinguish-declared-from-referenced fact, one
+    # scope wider. `bin/query_ir duplicates` confirms this directly:
+    # `Account.LedgerEntry (declared)` and `SafeDepositBox.Visit
+    # (declared)` both appear under the same `given: "customer is
+    # active"` group — verify by hand, same as the aggregate-level
+    # case above, before assuming a group naming two pieces under
+    # different aggregates is fresh duplication rather than an already-
+    # resolved chapter-wide reference.
+    def declaration_count(rules)
+      declared = rules.select { |r| r.location.end_with?(" (declared)") }
+      declared_owners = declared.map { |r| owner_of(r.location) }.to_set
+      declared_given_roots = declared.select { |r| r.kind == "given" }
+                                     .map { |r| owner_of(r.location).split(".").first }.to_set
+
+      standalone = rules.reject do |r|
+        owner = owner_of(r.location)
+        next true if declared_owners.include?(owner)
+        next true if r.kind == "given" && owner.include?(".") && declared_given_roots.include?(owner.split(".").first)
+
+        false
+      end
+
+      declared_owners.size + standalone.size
+    end
+    private_class_method :declaration_count
+
+    # SHARED TEXT FORMATTING — both `bin/query_ir` (a text CLI) and
+    # `bin/hecks_query_ir_mcp` (an MCP tool result, itself a text
+    # block) want the identical human-readable rendering; only the
+    # OUTER framing differs (plain stdout vs. a JSON-RPC content array).
+    def format_constructs(diffs)
+      diffs.map do |diff|
+        lines = ["== #{diff[:name]} =="]
+        lines << "  emits:    #{diff[:emitted].join(', ')}"
+        lines << "  declares: #{diff[:declared].join(', ')}"
+        if diff[:missing_from_ruby].empty? && diff[:unaccounted_in_ruby].empty?
+          lines << "  clean — every declared field is emitted (or a named deviation), nothing emitted is undeclared"
+        else
+          lines << "  MISSING FROM RUBY (declared, not emitted, not a named deviation): #{diff[:missing_from_ruby].join(', ')}" unless diff[:missing_from_ruby].empty?
+          lines << "  UNACCOUNTED IN RUBY (emitted, not declared, not a named deviation): #{diff[:unaccounted_in_ruby].join(', ')}" unless diff[:unaccounted_in_ruby].empty?
+        end
+        lines.join("\n")
+      end.join("\n\n")
+    end
+
+    # ONE HAND-TYPED CONSTRUCT-NAME PER RECONSTRUCTION METHOD — the only
+    # two `MetaValidator::Reconstruction` methods NOT driven generically
+    # through `Assembly::Contracts`' own table (its own header explains
+    # why: `aggregate(row)`/`entity(row)` predate the table and were
+    # never migrated). `impact_preview`'s own touchpoint 4 is checked
+    # ONLY for these two — every other construct is read generically, so
+    # asking "does Command's own reconstruction method mention this
+    # field" is a question with no method to check.
+    RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
+
+    # THE SIX TOUCHPOINTS `.claude/skills/bluebook-construct-creator/
+    # SKILL.md` walks in prose, checked structurally instead of by hand
+    # — for a construct/field pair NOT yet fully propagated (typically
+    # mid-round, deciding what's left), or as a sanity check before the
+    # final gate sweep of a round already believed done. Every check
+    # here is BEST-EFFORT and ADVISORY, not a gate: a `false` does not
+    # always mean "not yet done" (a field can be legitimately exempt —
+    # `Deviations`' own named categories, `GUARANTEED_BY_CONSTRUCTION`,
+    # or `META_DOMAIN_KNOWN_GAPS`, the last of which lives in
+    # spec/fuzzing/meta_domain_coverage_spec.rb, a SPEC file this
+    # module deliberately never requires — see `CONSTRUCTS`' own
+    # comment on the same principle). Read the touchpoint's own
+    # existing gate (`model_shape_conformance_spec.rb`,
+    # `assembly_spec.rb`, `meta_domain_coverage_spec.rb`) before trusting
+    # a `false` here as a real gap.
+    def impact_preview(name, field)
+      CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}" }
+      field = field.to_s
+
+      {
+        name:        name,
+        field:       field,
+        touchpoints: [
+          { touchpoint: "meta-domain grammar declares it", present: meta_declared(name).map(&:to_s).include?(field) },
+          { touchpoint: "docs/resolution-rules/ names it", present: resolution_rule_mentions?(field) },
+          { touchpoint: "Assembly::Contracts consumes it", present: contract_consumes?(name, field) },
+          { touchpoint: "Reconstruction's hand-typed method reads it", present: reconstruction_reads?(name, field) },
+          { touchpoint: "fuzzer FEATURE_COVERAGE/GUARANTEED_BY_CONSTRUCTION claims it", present: fuzzer_claims?(name, field) },
+          { touchpoint: "Rust mirror (rust/parser/src/parse/*.rs) mentions it", present: rust_mentions?(field) }
+        ]
+      }
+    end
+
+    def resolution_rule_mentions?(field)
+      paths = Dir.glob(File.join(Codemod::ROOT, "docs/resolution-rules/*.md")) +
+              Dir.glob(File.join(Codemod::ROOT, "docs/implemented/resolution-rules/*.md"))
+      paths.any? { |path| File.read(path).include?(field) }
+    end
+    private_class_method :resolution_rule_mentions?
+
+    def contract_consumes?(name, field)
+      contract = Hecks::Bluebook::Assembly.contract(name)
+      contract.fields.key?(field.to_sym) || contract.derived.key?(field.to_sym)
+    rescue KeyError
+      false
+    end
+    private_class_method :contract_consumes?
+
+    # `Method#source_location` finds where the hand-typed method starts;
+    # the method's own body ends at the next line indented no deeper
+    # than its own `def` — the same boundary Ruby itself uses, read back
+    # textually because there is no live AST here, only a file to grep a
+    # slice of. `nil` (not `false`) for every OTHER construct — this
+    # touchpoint genuinely does not apply to them (`RECONSTRUCTION_
+    # METHODS` only names the two hand-typed methods), and collapsing
+    # "does not apply" into "not done" would misreport a construct that
+    # was never supposed to have this touchpoint at all.
+    def reconstruction_reads?(name, field)
+      method_name = RECONSTRUCTION_METHODS[name]
+      return nil unless method_name
+
+      file, start_line = Hecks::Bluebook::MetaValidator::Reconstruction.instance_method(method_name).source_location
+      lines = File.readlines(file)
+      def_line = lines[start_line - 1]
+      indent = def_line[/\A\s*/]
+
+      body = lines[start_line..].take_while { |line| line.strip.empty? || line[/\A\s*/].size > indent.size || !line.lstrip.start_with?("def ") }
+      body.join.include?("#{field}:")
+    end
+    private_class_method :reconstruction_reads?
+
+    def fuzzer_claims?(name, field)
+      key = "#{name}##{field}"
+      Hecks::Fuzzing::Properties::FEATURE_COVERAGE.values.flatten.include?(key) ||
+        Hecks::Fuzzing::Properties::GUARANTEED_BY_CONSTRUCTION.key?(key)
+    end
+    private_class_method :fuzzer_claims?
+
+    def rust_mentions?(field)
+      Dir.glob(File.join(Codemod::ROOT, "rust/parser/src/parse/*.rs")).any? { |path| File.read(path).include?(field) }
+    end
+    private_class_method :rust_mentions?
+
+    def format_impact_preview(preview)
+      lines = ["== #{preview[:name]}##{preview[:field]} =="]
+      preview[:touchpoints].each do |t|
+        mark = t[:present].nil? ? "n/a" : (t[:present] ? "yes" : "NOT YET")
+        lines << "  [#{mark.rjust(7)}] #{t[:touchpoint]}"
+      end
+      done = preview[:touchpoints].count { |t| t[:present] == true }
+      total = preview[:touchpoints].count { |t| !t[:present].nil? }
+      lines << ""
+      lines << "#{done}/#{total} applicable touchpoint(s) show signs of this field — advisory, not a gate; " \
+               "a NOT YET can be a legitimate exemption (Deviations, GUARANTEED_BY_CONSTRUCTION, or a spec-only " \
+               "META_DOMAIN_KNOWN_GAPS entry this module deliberately never reads)."
+      lines.join("\n")
+    end
+
+    def format_duplicates(groups)
+      return "no duplicate given/invariant/ensures rule found" if groups.empty?
+
+      body = groups.map do |group|
+        ["== #{group[:kind]}: #{group[:description].inspect} — #{group[:canonical]} ==",
+         *group[:locations].map { |loc| "  #{loc}" }].join("\n")
+      end.join("\n\n")
+
+      "#{body}\n\n#{groups.size} duplicate group(s), #{groups.sum { |g| g[:locations].size }} declarations total"
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      AuthorizationSpec = Struct.new(:policy, :tenant, keyword_init: true) do
+        def to_h = { policy: policy.to_s, tenant: tenant && tenant.to_s }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+require_relative "../../literal"
+require_relative "../../vocabulary"
+
+module Hecks
+  module QuerySpecification
+    module Common
+      # `none_in_state`, vendored addition not (yet) upstream hecks
+      # (migration plan task 4): a CROSS-AGGREGATE ANTI-JOIN comparator --
+      # `where ref: { none_in_state: "Claim:held" }` holds true when NO
+      # record in the named aggregate, keyed by this record's own field
+      # value, is currently in the named state. plan.bluebook's own
+      # description: "a keyed point lookup (HashMap hit), never a scan" --
+      # a real, deliberate, pre-existing feature (WhereOp::NoneInState in
+      # the old Rust runtime), not invented here -- see Runtime::
+      # QueryInterpreter#holds?'s own comment for the evaluation side.
+      COMPARATORS = Hecks::Vocabulary.symbols("QueryComparator")
+    end
+
+    # The specification structs' own name for the one wire spelling — see
+    # Hecks::Literal, which every other `to_h`-bound literal field now
+    # shares. Kept as a word here because the structs below read better
+    # saying what they are doing than naming the module that does it.
+    def self.render_value(value) = Literal.render(value)
+  end
+end

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

@@ -0,0 +1,174 @@
+require_relative "null_policy"
+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.
+      module Comparison
+        module_function
+
+        # 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.
+        def comparable(value)
+          value = value.to_h if value.is_a?(Runtime::Value)
+          return value unless value.is_a?(Hash)
+
+          numerics = value.values.select { |field| field.is_a?(Numeric) }
+          return numerics.first if numerics.size == 1
+          return value.values.first if value.size == 1
+
+          value
+        end
+
+        # Which 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.
+        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
+
+          value_object.attributes.map(&:name)
+        end
+
+        NUMERIC_TYPES = %w[Integer Float Numeric].freeze
+
+        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.
+          return false if NullPolicy.unmatchable?(operation, held, want)
+
+          case operation.to_s
+          when "eq"       then held == want
+          when "ne"       then held != want
+          when "lt"       then ordered?(held, want) && held < want
+          when "lte"      then ordered?(held, want) && held <= want
+          when "gt"       then ordered?(held, want) && held > want
+          when "gte"      then ordered?(held, want) && held >= want
+          when "in"       then any_member_in?(held, want)
+          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.
+            raise Runtime::WiringError, "no comparator handles #{operation.to_s.inspect} — add one before declaring it"
+          end
+        end
+
+        # 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).
+        def ordered?(held, want) = held.is_a?(Numeric) && want.is_a?(Numeric)
+
+        # `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?`.
+        def members(value)
+          return value.map { |element| comparable(element).to_s } if value.is_a?(Array)
+
+          value.to_s.split(",").map(&:strip)
+        end
+
+        # 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.
+        def any_member_in?(held, want)
+          wanted = members(want)
+          candidates = held.is_a?(Array) ? held : [held]
+
+          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
+        # 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
+        # substring reading here keeps every engine answering `contains`
+        # identically for the same declared field.
+        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,
+        # 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?`).
+        def none_in_state?(held, want, registry)
+          return true unless registry
+
+          aggregate_name, state = want.to_s.split(":", 2)
+          target = find_aggregate_by_name(registry, aggregate_name)
+          return true unless target
+
+          target_domain, target_ir = target
+          record = registry.repository(target_domain, target_ir).find(held)
+          return true unless record
+
+          comparable(record.state[:state]) != state
+        end
+
+        def find_aggregate_by_name(registry, name)
+          registry.bluebooks.each do |domain, bluebook|
+            aggregate = bluebook.aggregates.find { |a| a.hecks_name == name }
+            return [domain, aggregate] if aggregate
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      CursorSpec = Struct.new(:value, keyword_init: true) do
+        def to_h = { value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end