hecks 2.8.0 → 3.0.0

data/lib/hecks/quality_control/quality_control.hecksagon

@@ -0,0 +1,13 @@
+# The QualityControl chapter, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). The QA ledger binds PostgresEra in qa/bluebook/quality_control.hecksagon, and the
+# Hecks chapter binds it through its world's `default_adapter`; the ports every one of them shares
+# are in quality_control.ports.hecksagon.
+Hecks.hecksagon "QualityControl" do
+  uses_framework "Governance"
+  persisted_by "Memory"
+end
+
+# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/quality_control/quality_control.ports.hecksagon

@@ -0,0 +1,54 @@
+# The ports QualityControl declares, for every hecksagon that attaches the chapter (`Chapters`
+# loads this file with it). Persistence is the attaching hecksagon's: the Hecks chapter binds
+# every aggregate through its world's `default_adapter`, and the QA ledger binds its own
+# (qa/bluebook/quality_control.hecksagon).
+Hecks.hecksagon "QualityControl" do
+  # Bound by adapters/github_issues. The port has to be declared even where no adapter binds it,
+  # so FileWhenSubmitted has a target and model_check's deaf-policy check can see it.
+  QualityControl::Ticket.port "IssueTracker" do
+    asks "File", to: Ticket do
+      answers "IssueFiled"
+      refuses "IssueFilingRefused"
+    end
+
+    tells "Closed", to: Ticket do
+      emits "IssueClosedUpstream"
+    end
+  end
+
+  # Bound by adapters/github_checks. ClearOnPass and RefuseOnFail turn its answer into
+  # Clearance::Passed/Failed.
+  QualityControl::Clearance.port "CI" do
+    asks "Run", to: Clearance do
+      answers "SuitePassed"
+      refuses "SuiteFailed"
+    end
+  end
+
+  # Queries answered from outside the domain. The bluebook declares each question and the value
+  # object its answer takes and never says who answers it; each `answers_query` binds it to the
+  # `*Tools` port's adapter, which runs the script's own command and answers what it printed.
+  QualityControl::Target.port "TargetTools" do
+    answers_query "Seed"
+    answers_query "CheckGeneratedDomains"
+    answers_query "MineCombinations"
+    answers_query "JudgeNovelty"
+    answers_query "DiscoverExternalDomains"
+  end
+
+  QualityControl::Sweep.port "SweepTools" do
+    answers_query "Tick"
+    answers_query "Run"
+    answers_query "MigrateLedgerFromHeki"
+    answers_query "CreateLedgerRole"
+    answers_query "Race"
+  end
+
+  QualityControl::Angle.port "AngleTools" do
+    answers_query "Seed"
+  end
+
+  QualityControl::Clearance.port "ClearanceTools" do
+    answers_query "CheckPullRequests"
+  end
+end

data/lib/hecks/query_ir.rb

@@ -0,0 +1,346 @@
+require_relative "bluebook"
+require_relative "codemod"
+require_relative "projections/model"
+require_relative "fuzzing/properties"
+
+module Hecks
+  # Shared core of `hecks ir_constructs` and `hecks serve_query_ir_mcp`.
+  # Returns structured data; formatting belongs to each front end.
+  module QueryIR
+    Codemod    = Hecks::Codemod
+    Deviations = Hecks::Projections::Model::Deviations
+
+    # Mirrors the conformance spec's MODEL_CONSTRUCTS; kept here because a spec is not a library.
+    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
+
+    # Reads the fields the language declares for one construct kind, from the grammar itself.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Array<Symbol>] the attribute names the self-hosted meta-domain
+    #   grammar declares for `name`
+    def meta_declared(name)
+      Hecks::Bluebook::MetaValidator.grammar_registry
+                                    .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
+    end
+
+    # The structural diff between what a Ruby IR class emits (`ir_spec.keys`) and what the
+    # self-hosted meta-domain declares, using the `Deviations` data the conformance spec reads.
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Hash{Symbol => Object}] `:name`, `:declared`, `:emitted`, plus
+    #   `:missing_from_ruby` and `:unaccounted_in_ruby` — each an `Array<Symbol>`
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
+    def construct_diff(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
+
+      accounted = declared.reject { |field| Deviations.parent_ref?(field) } -
+                  Deviations.judge_only(name) -
+                  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
+
+    # Diffs one or every construct kind at once.
+    #
+    # @param names [Array<String>] `CONSTRUCTS` keys to diff, every construct when empty
+    # @return [Array<Hash>] one `construct_diff` result per name
+    def constructs(names = [])
+      targets = names.empty? ? CONSTRUCTS.keys : names
+      targets.map { |name| construct_diff(name) }
+    end
+
+    # Every given/ensures/invariant reachable from a booted registry, walked recursively.
+    #
+    # Object identity carries no signal: `MetaValidator.call` rebuilds the graph from flat rows,
+    # so a bare `given("x")` reference and its block declaration are distinct objects by then.
+    # @param registry [Runtime::Registry] the booted registry to walk
+    # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+    # @return [Array<Rule>]
+    def collect_rules(registry, chapter_name = nil)
+      rules = []
+      chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
+
+      chapters.each do |chapter|
+        chapter.aggregates.each do |aggregate|
+          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,
+                                location: "#{aggregate.hecks_name}::#{vo.hecks_name} (declared)")
+            end
+          end
+        end
+      end
+      rules
+    end
+
+    # Recursive walk behind `collect_rules`; appends to `rules` in place.
+    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 path a "(declared)" location names, or a command-level location
+    # with its trailing `.CommandName` stripped.
+    #
+    # @param location [String] a `Rule#location`
+    # @return [String] the owning construct's path, with `" (declared)"` or a trailing
+    #   `.CommandName` segment stripped
+    def owner_of(location)
+      return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
+
+      location.rpartition(".").first
+    end
+
+    # Groups rules by (kind, description, canonical) and reports groups with more than one
+    # real declaration, counted by owner rather than object identity (see `collect_rules`).
+    #
+    # `domains: []` scans the self-hosted meta-domain only; `nil` adds every real example.
+    # @param domains [Array<String>, nil] domain root directories to scan; every real
+    #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
+    # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
+    # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
+    #   `:canonical`, and `:locations` (`Array<String>`)
+    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 do |(kind, description, canonical), rules, _|
+        { kind: kind, description: description, canonical: canonical,
+      locations: rules.map(&:location) }
+      end
+    end
+
+    # A rule owned by a nested entity is also covered by a "(declared)" entry anywhere under the
+    # same root aggregate, matching the DSL's shared given pool.
+    #
+    # Known gap: a bare chapter-wide `given(desc)` reference still shows as its own "(declared)"
+    # owner, because the built IR cannot tell a reference from a declaration. Verify a flagged
+    # group by hand before treating it as fresh duplication.
+    # @param rules [Array<Rule>] one duplicate-key group's own rules
+    # @return [Integer] how many of `rules` are real, independent declarations
+    def declaration_count(rules)
+      declared = rules.select { |r| r.location.end_with?(" (declared)") }
+      declared_owners = declared.to_set { |r| owner_of(r.location) }
+      declared_given_roots = declared.select { |r| r.kind == "given" }
+                                     .to_set { |r| owner_of(r.location).split(".").first }
+
+      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
+
+    # Renders `constructs` output as text, shared by `hecks ir_constructs` and `hecks
+    # serve_query_ir_mcp`.
+    #
+    # @param diffs [Array<Hash>] `constructs`' own output
+    # @return [String] the human-readable rendering
+    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
+          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")
+    end
+
+    # The two `MetaValidator::Reconstruction` methods written by hand rather than driven by
+    # `Assembly::Contracts`; `impact_preview` checks touchpoint 4 only for these.
+    RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
+
+    # Checks the six touchpoints of `.claude/skills/bluebook-construct-creator/SKILL.md` for a
+    # construct/field pair. Advisory, not a gate: a `false` can be a legitimate exemption
+    # (`Deviations`, `GUARANTEED_BY_CONSTRUCTION`, or the spec-only `META_DOMAIN_KNOWN_GAPS`).
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @param field [String, Symbol] the declared field to check propagation for
+    # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
+    #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
+    #   touchpoint does not apply to `name`)
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
+    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?
+
+    # nil, not false, for constructs without a hand-typed method: the touchpoint does not apply.
+    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
+      lines = File.readlines(file)
+      def_line = lines[start_line - 1]
+      indent = def_line[/\A\s*/]
+
+      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?
+
+    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?
+
+    # Renders one field's touchpoint checklist as text.
+    #
+    # @param preview [Hash] `impact_preview`'s own output
+    # @return [String] the human-readable rendering
+    def format_impact_preview(preview)
+      lines = ["== #{preview[:name]}##{preview[:field]} =="]
+      preview[:touchpoints].each do |t|
+        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 }
+      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
+
+    # Renders the duplicate-rule groups as text.
+    #
+    # @param groups [Array<Hash>] `duplicates`' own output
+    # @return [String] the human-readable rendering
+    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_ir_mcp.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "mcp_stdio_guard"
+require_relative "query_ir"
+
+module Hecks
+  # The MCP server that exposes `Hecks::QueryIR`'s queries as tools, over newline-delimited
+  # JSON-RPC.
+  #
+  # It is stdio only and unauthenticated (ADR 0062): {.start} refuses any other setup before it
+  # reads a request. The query logic lives in `Hecks::QueryIR`; this is only the protocol.
+  module QueryIrMcp
+    # The MCP protocol revision the server speaks.
+    PROTOCOL_VERSION = "2024-11-05"
+
+    # The three tools, as an MCP client lists them.
+    TOOLS = [
+      {
+        name:        "query_ir_constructs",
+        description: "For a bluebook IR construct (Aggregate, Entity, Command, Query, ValueObject, Policy, " \
+                     "ReadModel, ProcessManager, Bluebook) or all of them, the real structural diff between " \
+                     "what the Ruby class emits and what the self-hosted meta-domain declares for it. Use " \
+                     "this instead of reading entity.rb/entity.bluebook (or the equivalent pair for another " \
+                     "construct) by hand to check whether a new IR field has been fully propagated.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            names: {
+              type:        "array",
+              items:       { type: "string" },
+              description: "Construct names to check (e.g. [\"Entity\"]). Omit or leave empty for all constructs."
+            }
+          }
+        }
+      },
+      {
+        name:        "query_ir_duplicates",
+        description: "Every given/ensures/invariant DECLARATION across the real corpus " \
+                     "(banking/pizzas/compliance) and the self-hosted meta-domain, grouped by (kind, " \
+                     "description, canonical predicate), reporting every group with more than one " \
+                     "independently-declared rule (already-deduped references, which share the same " \
+                     "underlying rule object, are excluded). Use this to find real corpus duplication " \
+                     "before proposing a new 'declared once, referenced by name' resolution rule.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            domains:      {
+              type:        "array",
+              items:       { type: "string" },
+              description: "Real example domain directories to scan (e.g. [\"examples/banking\"]). Omit for " \
+                           "every real example domain."
+            },
+            include_meta: {
+              type:        "boolean",
+              description: "Include the self-hosted meta-domain (lib/hecks/language/bluebook). Defaults to true."
+            }
+          }
+        }
+      },
+      {
+        name:        "query_ir_impact",
+        description: "For one construct/field pair, which of the six propagation touchpoints " \
+                     ".claude/skills/bluebook-construct-creator/SKILL.md walks in prose already show signs " \
+                     "of it, and which don't: the meta-domain grammar, docs/resolution-rules/, " \
+                     "Assembly::Contracts, Reconstruction's hand-typed aggregate(row)/entity(row) (only " \
+                     "applicable to Aggregate/Entity), the fuzzer's FEATURE_COVERAGE/" \
+                     "GUARANTEED_BY_CONSTRUCTION, and the Rust mirror. Advisory, not a gate.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            name:  { type: "string", description: "Construct name (e.g. \"Aggregate\")." },
+            field: { type: "string", description: "The field name to check (e.g. \"preconditions\")." }
+          },
+          required:   %w[name field]
+        }
+      }
+    ].freeze
+
+    module_function
+
+    # Checks the process is set up for stdio, prints the startup warning to stderr, and serves
+    # requests until stdin closes.
+    #
+    # @param argv [Array<String>] the arguments the guard checks (only `--stdio` is accepted)
+    # @param input [IO] where requests arrive
+    # @param output [IO] where responses leave
+    # @return [void]
+    # @raise [SystemExit] when the setup is not stdio, with the guard's status
+    def start(argv: [], input: $stdin, output: $stdout)
+      McpStdioGuard.start!(server: "hecks-query-ir", notes: notes, argv: argv, stdin: input, stdout: output)
+      serve(input: input, output: output)
+    end
+
+    # @return [Array<String>] what the startup warning says beyond the guard's common lines
+    def notes
+      ["No identity is asked for or checked; every tool answers every caller.",
+       "query_ir_duplicates loads .bluebook files under #{Storehouse::BOOT_ROOT} as Ruby."]
+    end
+
+    # Answers each request line until the input ends.
+    #
+    # @param input [#each_line] newline-delimited JSON-RPC requests
+    # @param output [#puts] where each response is written, one JSON object a line
+    # @return [void]
+    def serve(input:, output:)
+      output.sync = true if output.respond_to?(:sync=)
+      input.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        request = parse(line, output)
+        respond(request, output) if request
+      end
+    end
+
+    # @param name [String] the tool
+    # @param arguments [Hash] its arguments as the client sent them
+    # @return [Hash] the MCP tool result
+    def call_tool(name, arguments)
+      case name
+      when "query_ir_constructs"
+        tool_result(QueryIR.format_constructs(QueryIR.constructs(Array(arguments["names"]))))
+      when "query_ir_duplicates" then tool_result(duplicates(arguments))
+      when "query_ir_impact"
+        tool_result(QueryIR.format_impact_preview(QueryIR.impact_preview(arguments["name"], arguments["field"])))
+      else
+        tool_result("no such tool: #{name.inspect} - known: #{TOOLS.map { |t| t[:name] }.join(', ')}", error: true)
+      end
+    rescue ArgumentError, Runtime::TypeMismatch => e
+      tool_result(e.message, error: true)
+    end
+
+    # @api private
+    def duplicates(arguments)
+      domains = confined_domains(arguments["domains"])
+      QueryIR.format_duplicates(QueryIR.duplicates(domains: domains, include_meta: arguments.fetch("include_meta", true)))
+    end
+
+    # `duplicates` loads every .bluebook under each directory as Ruby, so paths must stay in the
+    # storehouse boot root.
+    #
+    # @api private
+    def confined_domains(requested)
+      return nil if requested.nil? || requested.empty?
+
+      Array(requested).map { |dir| Storehouse.confine!(dir, "domains") }
+    end
+
+    # @api private
+    def tool_result(text, error: false)
+      { content: [{ type: "text", text: text }], isError: error }
+    end
+
+    # @api private
+    def parse(line, output)
+      JSON.parse(line)
+    rescue JSON::ParserError => e
+      error(output, nil, -32_700, "Parse error: #{e.message}")
+      nil
+    end
+
+    # @api private
+    def respond(request, output)
+      handle(request, output)
+    rescue StandardError => e
+      error(output, request["id"], -32_603, "Internal error: #{e.class}: #{e.message}")
+    end
+
+    # @api private
+    def handle(request, output)
+      id = request["id"]
+      params = request["params"] || {}
+      case request["method"]
+      when "initialize" then result(output, id, initialized)
+      when "notifications/initialized" then nil
+      when "tools/list" then result(output, id, { tools: TOOLS })
+      when "tools/call" then result(output, id, call_tool(params["name"], params["arguments"] || {}))
+      when "ping" then result(output, id, {})
+      else error(output, id, -32_601, "Method not found: #{request['method']}") unless id.nil?
+      end
+    end
+
+    # @api private
+    def initialized
+      { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },
+        serverInfo: { name: "hecks-query-ir", version: "1.0.0" } }
+    end
+
+    # @api private
+    def result(output, id, body) = output.puts(JSON.generate({ jsonrpc: "2.0", id: id, result: body }))
+
+    # @api private
+    def error(output, id, code, message)
+      output.puts(JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } }))
+    end
+  end
+end

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

@@ -2,37 +2,16 @@ 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.
+  # Adds `Common::COMPARATORS` and `.render_value`, the wire renderer shared by spec structs.
   module QuerySpecification
-    # The vocabulary every query-shaped construct shares — the clause structs
-    # (`WhereClause`, `OrderBy`, `LimitSpec`...), the `DSL` mixin that parses
-    # them, and the comparison and null rules every engine answers by. It is
-    # its own namespace so a plain `Bluebook::Query` and a
-    # `ReadModel::Specification` say one thing the same way rather than each
-    # carrying a copy.
+    # The clause structs, DSL mixin and comparison rules shared by every query-shaped construct.
     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.
+      # Includes `none_in_state`: `where ref: { none_in_state: "Claim:held" }` holds when no record
+      # in the named aggregate, keyed by this field's value, is in that state (a keyed lookup).
       COMPARATORS = Hecks::Vocabulary.symbols("QueryComparator")
     end
 
-    # Renders a literal captured in a query clause as its self-describing
-    # wire spelling, for a spec struct's `to_h`.
-    #
-    # The specification structs' own name for the one wire spelling — see
-    # `Hecks::Literal`, which every other `to_h`-bound literal field
-    # shares. Kept as a word here because the structs below read better
-    # saying what they are doing than naming the module that does it.
+    # Renders a query-clause literal as its wire spelling; delegates to `Hecks::Literal.render`.
     #
     # @param value [nil, Symbol, String, StateRef, Boolean, Integer, Float, Hash, Array] the
     #   literal as the bluebook author wrote it; Hash values and Array elements are