hecks 1.0.2 → 1.2.0

data/lib/hecks/projector/docs_projector.rb

@@ -52,7 +52,7 @@ module Hecks
         out << chapter_header(bluebook, depth) unless only
         Array(aggregates(bluebook, only)).each { |aggregate| out << aggregate_section(aggregate, only ? depth : depth + 1) }
         out << closing(bluebook, depth + 1) unless only
-        out.compact.join("\n").rstrip + "\n"
+        "#{out.compact.join("\n").rstrip}\n"
       end
 
       # A NAME THAT NAMES NOTHING IS REFUSED, not answered with an empty
@@ -179,7 +179,7 @@ module Hecks
         value_object = value_object_for(attribute, holder)
         inner =
           if value_object
-            "{ " + value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(", ") + " }"
+            "{ #{value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(', ')} }"
           else
             attribute.type.to_s
           end
@@ -244,19 +244,13 @@ module Hecks
       end
 
       def command_entry(command, holder, depth)
-        out = [h(depth, "#{command.hecks_name}#{command.creates? ? ' *(creates)*' : ''}"), ""]
+        out = [h(depth, "#{command.hecks_name}#{' *(creates)*' if command.creates?}"), ""]
         out += [command.goal, ""] if command.goal
         out << "Issued by: **#{command.role}**." if command.role
         out << ""
 
         arguments = command.attributes
-        unless arguments.empty?
-          rows = arguments.map do |attribute|
-            shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
-            ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
-          end
-          out << table(%w[argument shape needed], rows)
-        end
+        out << table(%w[argument shape needed], command_argument_rows(arguments, holder)) unless arguments.empty?
 
         refusals = refusals_of(command, holder)
         unless refusals.empty?
@@ -272,6 +266,17 @@ module Hecks
         out.join("\n")
       end
 
+      # The argument table's own rows — a pure per-attribute mapping with
+      # nothing to share with `command_entry`'s other sections, extracted
+      # only to keep that method to the one shape every section there
+      # follows: build a chunk, append it if non-empty.
+      def command_argument_rows(arguments, holder)
+        arguments.map do |attribute|
+          shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
+          ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
+        end
+      end
+
       # EVERY WAY THIS VERB CAN SAY NO, gathered from the three places a
       # chapter states them — the lifecycle it is an edge of, its own
       # `given`s, and the fact that a reference has to resolve. A caller
@@ -284,7 +289,11 @@ module Hecks
         froms = lifecycle && lifecycle.transitions.filter_map do |name, transition|
           Array(transition.from) if name.to_s == command.hecks_name
         end.flatten.uniq
-        refusals << "`#{lifecycle.field}` is anything other than #{froms.map { |f| "`#{f}`" }.join(' or ')}" if froms && !froms.empty?
+        if froms && !froms.empty?
+          refusals << "`#{lifecycle.field}` is anything other than #{froms.map do |f|
+            "`#{f}`"
+          end.join(' or ')}"
+        end
 
         command.attributes.select(&:reference?).each do |reference|
           refusals << "no `#{reference.type.target_name}` exists for the id given as `#{reference.name}`"
@@ -302,7 +311,7 @@ module Hecks
         queries.each do |query|
           shape   = query.to_h
           takes   = Array(shape[:attributes]).map { |a| "`#{a[:name]}`" }.join(", ")
-          out << "**#{query.hecks_name}**#{takes.empty? ? '' : " (#{takes})"}  "
+          out << "**#{query.hecks_name}**#{" (#{takes})" unless takes.empty?}  "
           out << (query.description ? "#{query.description}  " : "")
           filters = Array(shape[:wheres]).map { |w| "`#{w[:field]} #{w[:op]} #{w[:value].inspect}`" }
           out << "Filters: #{filters.join(', ')}." unless filters.empty?

data/lib/hecks/projector/exporter.rb

@@ -3,6 +3,13 @@ require_relative "../ports/persistence"
 
 module Hecks
   module Projector
+    # Registry-wide serialization to Hash/JSON: bluebook IR
+    # (`call`/`json`), era-adapter lineage-capability flags (`lineage`),
+    # and translation edges in both their DIGEST-relevant declared shape
+    # (`translation_hash`, what ApprovalDigest hashes) and their
+    # consumer-ready COMPILED shape with precompiled SQL attached
+    # (`translations`/`compiled_translation_aggregate`). Read directly by
+    # bin/ir, bin/project_rust, and the translation/audit approval digest.
     module Exporter
       module_function
 
@@ -47,6 +54,30 @@ module Hecks
         { capable_aggregates: capable.map { |aggregate| { name: aggregate.name, storage_name: aggregate.storage_name } } }
       end
 
+      # A BINDING fact, same shape/reasoning as `lineage` above: every
+      # aggregate's DECLARED persistence adapter name (`persisted_by`),
+      # not part of the canonical bluebook shape `call` exports (ADR
+      # 0001 — the IR describes what's declared, never which adapter a
+      # deployment binds it to). Unlike `lineage`, this needs no era
+      # plugin — `BindingPolicy` is core, always loaded — and covers
+      # EVERY aggregate, not just lineage-capable ones: `rust/host`
+      # (`ir.rs`'s own `refuse_unsupported_persistence_adapters`) reads
+      # this to refuse loudly, at boot, against a domain bound to an
+      # adapter it has no backend for (Heki, Memory, Sqlite, D1,
+      # LocalStorage — `rust/host` understands only Postgres/PostgresEra
+      # today), rather than silently building up a second, disjoint
+      # history nothing but Rust ever reads while the real state stays
+      # wherever its own adapter actually wrote it.
+      def persistence(registry, domain_name)
+        bluebook = registry.bluebooks.fetch(domain_name)
+        aggregates = bluebook.aggregates.map do |aggregate|
+          adapter = Ports::Persistence::BindingPolicy.resolve(registry, domain_name, aggregate).adapter
+          { name: aggregate.name, storage_name: aggregate.storage_name, adapter: adapter }
+        end
+
+        { aggregates: aggregates }
+      end
+
       # Translation IR, always as an array, WITH each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`
@@ -150,7 +181,9 @@ module Hecks
 
         translation_aggregate(aggregate).merge(
           compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
-          compiled_id_expression:    Translation::RuleCompiler.rekeyed?(aggregate) ? Translation::RuleCompiler.compile_id_expression(aggregate) : nil
+          compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
+                                        Translation::RuleCompiler.compile_id_expression(aggregate)
+                                      end)
         )
       end
     end

data/lib/hecks/projector/narrate_projector.rb

@@ -72,7 +72,11 @@ module Hecks
         parts << identity_sentence(aggregate)
 
         refs = aggregate.attributes.select(&:reference?)
-        parts << "Each one is linked to #{to_sentence_list(refs.map { |r| "#{a_or_an(r.type.target_name)} #{r.type.target_name}" })}." unless refs.empty?
+        unless refs.empty?
+          parts << "Each one is linked to #{to_sentence_list(refs.map do |r|
+            "#{a_or_an(r.type.target_name)} #{r.type.target_name}"
+          end)}."
+        end
 
         parts << lifecycle_narrative(aggregate)
         parts << verbs_narrative(aggregate, depth + 1)
@@ -124,35 +128,84 @@ module Hecks
         "#{header}\n\n#{body}"
       end
 
+      # ONE PARAGRAPH, BUILT FROM INDEPENDENT SENTENCES — each sentence
+      # below states one unrelated fact about `command` (its goal, who
+      # issues it, whether it creates the holder, what it takes, what it
+      # references, what gates it, what it guarantees, what it emits), in
+      # the fixed order a reader expects them; nothing after the first
+      # sentence depends on anything before it. Same nil-or-string +
+      # `compact.join` shape `aggregate_narrative`/`entity_narrative`
+      # already use above for the identical reason.
       def command_paragraph(command, holder)
-        # THE GOAL, VERBATIM — same rule `DocsProjector` holds to: quoted
-        # exactly as declared, not recased to fit mid-sentence, because the
-        # promise this whole projector makes is that a sentence here is a
-        # sentence the chapter actually wrote.
-        sentences = ["**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"]
-        sentences << "Issued by #{a_or_an(command.role)} #{command.role}." if command.role
-        # `acts_on.nil?`, NOT `creates?` — `creates?` answers true for every
-        # verb an ENTITY declares (it never references itself; see
-        # `Command#acts_on`'s own comment), so reading it directly here would
-        # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
-        # being, which is exactly backwards.
-        sentences << "This is how a new #{holder.hecks_name} comes into being." if command.acts_on.nil?
+        [
+          command_headline_sentence(command),
+          command_role_sentence(command),
+          command_creation_sentence(command, holder),
+          command_arguments_sentence(command),
+          command_references_sentence(command),
+          command_conditions_sentence(command, holder),
+          command_guarantees_sentence(command),
+          command_emits_sentence(command)
+        ].compact.join(" ")
+      end
+
+      # THE GOAL, VERBATIM — same rule `DocsProjector` holds to: quoted
+      # exactly as declared, not recased to fit mid-sentence, because the
+      # promise this whole projector makes is that a sentence here is a
+      # sentence the chapter actually wrote.
+      def command_headline_sentence(command)
+        "**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"
+      end
+
+      def command_role_sentence(command)
+        return nil unless command.role
+
+        "Issued by #{a_or_an(command.role)} #{command.role}."
+      end
+
+      # `acts_on.nil?`, NOT `creates?` — `creates?` answers true for every
+      # verb an ENTITY declares (it never references itself; see
+      # `Command#acts_on`'s own comment), so reading it directly here would
+      # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
+      # being, which is exactly backwards.
+      def command_creation_sentence(command, holder)
+        return nil unless command.acts_on.nil?
+
+        "This is how a new #{holder.hecks_name} comes into being."
+      end
 
+      def command_arguments_sentence(command)
         arguments = command.attributes.reject(&:reference?)
-        sentences << "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}." unless arguments.empty?
+        return nil if arguments.empty?
 
+        "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}."
+      end
+
+      def command_references_sentence(command)
         refs = command.attributes.select(&:reference?)
-        sentences << "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id." unless refs.empty?
+        return nil if refs.empty?
 
+        "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
+      end
+
+      def command_conditions_sentence(command, holder)
         conditions = conditions_of(command, holder)
-        sentences << "It only goes through if #{conditions.join('; ')}." unless conditions.empty?
+        return nil if conditions.empty?
 
+        "It only goes through if #{conditions.join('; ')}."
+      end
+
+      def command_guarantees_sentence(command)
         guarantees = command.ensures.map(&:description)
-        sentences << "When it succeeds: #{guarantees.join('; ')}." unless guarantees.empty?
+        return nil if guarantees.empty?
+
+        "When it succeeds: #{guarantees.join('; ')}."
+      end
 
-        sentences << "It records `#{command.emits.join('`, `')}` as a fact." unless command.emits.empty?
+      def command_emits_sentence(command)
+        return nil if command.emits.empty?
 
-        sentences.join(" ")
+        "It records `#{command.emits.join('`, `')}` as a fact."
       end
 
       # EVERY REQUIRED CONDITION, STATED AS SOMETHING THAT MUST BE TRUE —
@@ -166,10 +219,14 @@ module Hecks
 
         lifecycle = holder.lifecycle
         if lifecycle
-          froms = lifecycle.transitions.filter_map { |name, transition|
+          froms = lifecycle.transitions.filter_map do |name, transition|
             Array(transition.from) if name.to_s == command.hecks_name
-          }.flatten.uniq
-          conditions << "its `#{lifecycle.field}` is currently #{to_sentence_list(froms.map { |f| "`#{f}`" }, conj: 'or')}" unless froms.empty?
+          end.flatten.uniq
+          unless froms.empty?
+            conditions << "its `#{lifecycle.field}` is currently #{to_sentence_list(froms.map do |f|
+              "`#{f}`"
+            end, conj: 'or')}"
+          end
         end
 
         conditions + command.givens.map(&:description)
@@ -200,8 +257,8 @@ module Hecks
         "#{header}\n\n#{lines.join("\n")}"
       end
 
-      def op_words(op)
-        { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[op.to_s.to_sym] || op.to_s
+      def op_words(comparator)
+        { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[comparator.to_s.to_sym] || comparator.to_s
       end
 
       # ── what happens on its own ───────────────────────────────────────
@@ -212,7 +269,8 @@ module Hecks
         parts = [DocsProjector.h(depth, "Reactions")]
         bluebook.policies.each do |policy|
           elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
-          parts << "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — nobody has to ask for it."
+          parts << "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — " \
+                   "nobody has to ask for it."
         end
 
         bluebook.process_managers.each do |saga|

data/lib/hecks/projector.rb

@@ -70,9 +70,9 @@ module Hecks
     # any construct that emits IR, and `admits!` is what decides whether
     # THIS target can actually take the one handed over.
     def call(name, bluebook:, options: {})
-      projector = registry.fetch(name.to_sym) {
+      projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
-      }
+      end
       admits!(name, projector, bluebook)
       projector.call(bluebook: bluebook, options: options)
     end

data/lib/hecks/query_ir.rb

@@ -1,4 +1,3 @@
-require "set"
 require_relative "bluebook"
 require_relative "codemod"
 require_relative "projections/model"
@@ -49,9 +48,9 @@ module Hecks
     # 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) {
+      klass = CONSTRUCTS.fetch(name) do
         raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
-      }
+      end
       declared = meta_declared(name)
       emitted  = klass.ir_spec.keys
 
@@ -101,33 +100,9 @@ module Hecks
       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)
+          walk_construct_rules(aggregate, aggregate.hecks_name, rules)
           aggregate.value_objects.each do |vo|
             vo.invariants.each do |rule|
               rules << Rule.new(kind: "invariant", description: rule.description, canonical: rule.canonical,
@@ -139,6 +114,39 @@ module Hecks
       rules
     end
 
+    # THE RECURSIVE WALK `collect_rules` drives — pulled out of that method
+    # (pure extraction, identical traversal and Rule shapes) as its own
+    # named, self-recursive method rather than a lambda closing over the
+    # same locals. `rules` is the one piece of state every call shares —
+    # threaded as a parameter and mutated in place, the same accumulator
+    # role the lambda's own closure played.
+    def walk_construct_rules(construct, path, rules)
+      (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
+      return unless construct.respond_to?(:entities)
+
+      construct.entities.each do |piece|
+        walk_construct_rules(piece, "#{path}.#{piece.hecks_name}", rules)
+      end
+    end
+    private_class_method :walk_construct_rules
+
     # 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
@@ -196,10 +204,10 @@ module Hecks
       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, _|
+               .map do |(kind, description, canonical), rules, _|
         { kind: kind, description: description, canonical: canonical,
       locations: rules.map(&:location) }
-      }
+      end
     end
 
     # `given` ONLY (not `invariant`/`ensures`) also covers CROSS-ENTITY
@@ -254,9 +262,9 @@ module Hecks
     # 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_owners = declared.to_set { |r| owner_of(r.location) }
       declared_given_roots = declared.select { |r| r.kind == "given" }
-                                     .map { |r| owner_of(r.location).split(".").first }.to_set
+                                     .to_set { |r| owner_of(r.location).split(".").first }
 
       standalone = rules.reject do |r|
         owner = owner_of(r.location)
@@ -282,8 +290,14 @@ module Hecks
         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?
+          unless diff[:missing_from_ruby].empty?
+            lines << "  MISSING FROM RUBY (declared, not emitted, not a named deviation): " \
+                     "#{diff[:missing_from_ruby].join(', ')}"
+          end
+          unless diff[:unaccounted_in_ruby].empty?
+            lines << "  UNACCOUNTED IN RUBY (emitted, not declared, not a named deviation): " \
+                     "#{diff[:unaccounted_in_ruby].join(', ')}"
+          end
         end
         lines.join("\n")
       end.join("\n\n")
@@ -358,6 +372,10 @@ module Hecks
     # was never supposed to have this touchpoint at all.
     def reconstruction_reads?(name, field)
       method_name = RECONSTRUCTION_METHODS[name]
+      # rubocop:disable-next Style/ReturnNilInPredicateMethodDefinition -- nil vs
+      # false is a deliberate distinction here: nil means "not applicable" (no
+      # hand-typed method to check), false means "applicable, and it fails" —
+      # see the spec's own "not-applicable (nil), not false" example.
       return nil unless method_name
 
       file, start_line = Hecks::Bluebook::MetaValidator::Reconstruction.instance_method(method_name).source_location
@@ -365,7 +383,9 @@ module Hecks
       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 = lines[start_line..].take_while do |line|
+        line.strip.empty? || line[/\A\s*/].size > indent.size || !line.lstrip.start_with?("def ")
+      end
       body.join.include?("#{field}:")
     end
     private_class_method :reconstruction_reads?
@@ -385,7 +405,11 @@ module Hecks
     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")
+        mark = if t[:present].nil?
+                 "n/a"
+               else
+                 (t[:present] ? "yes" : "NOT YET")
+               end
         lines << "  [#{mark.rjust(7)}] #{t[:touchpoint]}"
       end
       done = preview[:touchpoints].count { |t| t[:present] == true }

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

@@ -2,7 +2,7 @@ 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 }
+        def to_h = { policy: policy.to_s, tenant: tenant&.to_s }
       end
     end
   end

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

@@ -2,6 +2,10 @@ require_relative "../../literal"
 require_relative "../../vocabulary"
 
 module Hecks
+  # Reopened (see query_specification.rb for the namespace's own
+  # summary) to add Common::COMPARATORS — the vendored comparator
+  # vocabulary — and .render_value, the wire-rendering entry point
+  # shared by every literal-bearing spec struct.
   module QuerySpecification
     module Common
       # `none_in_state`, vendored addition not (yet) upstream hecks

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

@@ -44,7 +44,7 @@ module Hecks
           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) }
+          numerics = value.values.grep(Numeric)
           return numerics.first if numerics.size == 1
           return value.values.first if value.size == 1
 
@@ -63,6 +63,13 @@ module Hecks
 
         NUMERIC_TYPES = %w[Integer Float Numeric].freeze
 
+        # 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.
+        # 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

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

@@ -11,6 +11,11 @@ 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.
       module DSL
         # RENAMED FROM `where`/`order_by`/`limit`/`offset`/`authorize`
         # (all below) — item #13's full metaprogrammed dispatch (slice

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

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      LimitSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `limit` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      LimitSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

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

@@ -1,6 +1,12 @@
 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.
       module NullPolicy
         module_function
 
@@ -82,8 +88,6 @@ module Hecks
             ["#{expression} IS NULL", []]
           elsif value.nil? && operation.to_s == "ne"
             ["#{expression} IS NOT NULL", []]
-          else
-            nil
           end
         end
       end

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

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OffsetSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `offset` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OffsetSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

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

@@ -3,6 +3,12 @@ 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.
       class Options
         attr_reader :wheres, :order_by, :limit, :offset, :cursor,
                     :authorization, :null_semantics, :inspection
@@ -10,8 +16,14 @@ module Hecks
         def initialize(wheres: [], order_by: nil, limit: nil, offset: nil, cursor: nil,
                        authorization: nil,
                        inspection: nil, null_semantics: NullSemantics.default)
-          @wheres, @order_by, @limit, @offset, @cursor = wheres, order_by, limit, offset, cursor
-          @authorization, @null_semantics, @inspection = authorization, null_semantics, inspection
+          @wheres = wheres
+          @order_by = order_by
+          @limit = limit
+          @offset = offset
+          @cursor = cursor
+          @authorization = authorization
+          @null_semantics = null_semantics
+          @inspection = inspection
         end
 
         def options_to_h
@@ -21,10 +33,10 @@ module Hecks
         end
 
         def extra_options_to_h
-          options_to_h.reject { |key, value|
+          options_to_h.reject do |key, value|
             value.nil? || value == [] || (key == :null_semantics && value == { mode: "native" })
-          }
-                      .reject { |key, _| %i[wheres order_by limit].include?(key) }
+          end
+                      .except(:wheres, :order_by, :limit)
         end
       end
     end

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

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OrderBy = Struct.new(:field, :direction, keyword_init: true) do
-        def to_h = { field: field.to_s, direction: direction.to_s }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `order_by` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OrderBy = Struct.new(:field, :direction, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, direction: direction.to_s }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end