hecks 2.9.0 → 3.0.0

data/lib/hecks/doors/launcher_options.rb

@@ -0,0 +1,129 @@
+require_relative "../ports/identity_generation"
+require_relative "../runtime/errors"
+require_relative "cli_door"
+
+module Hecks
+  module Doors
+    # What a domain's world file adds to its generated launcher, all of it opt-in.
+    #
+    # A `.world` that declares a `launcher` setting switches these on for that chapter; a
+    # domain without one keeps the launcher's plain forms exactly:
+    #
+    #     launcher "Launcher", run_keys: true, failure_states: %w[flagged failed],
+    #                          names: { "mcp" => "serve_mcp" }
+    #
+    # - **run_keys** mints the `run` key of a creating command that was given none.
+    # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
+    # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
+    module LauncherOptions
+      SETTING = "launcher".freeze
+      WAIT    = "--wait".freeze
+      RUN_KEY = "run.value".freeze
+
+      module_function
+
+      # Reads a chapter's `launcher` setting.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param chapter [String] the chapter the command line speaks to
+      # @return [Hash{Symbol => Object}, nil] the setting, or nil when the chapter did not opt in
+      def settings(runtime, chapter)
+        return unless runtime.respond_to?(:registry)
+
+        found = runtime.registry.world(chapter)&.for_verb(SETTING)
+        found.nil? || found.empty? ? nil : found
+      end
+
+      # The options the launcher's projection is asked for: the program's name, the chapter's
+      # launcher names, and whether run keys are minted (so help shows them optional).
+      #
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @param program [String] how the caller was invoked
+      # @return [Hash{Symbol => Object}] the options `Projector::CliProjector` reads
+      def projection(settings, program)
+        { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
+      end
+
+      # Takes `--wait` out of a verb's words, unless the verb declares a `wait` argument of its own.
+      #
+      # `--wait=false` (or `no`, `0`, `off`) is a `--wait` that was switched off; a bare `--wait`
+      # may be followed by its Boolean word.
+      #
+      # @param spec [Hash] the verb's projected spec
+      # @param words [Array<String>] the words after the verb
+      # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--wait` was given
+      # @raise [Runtime::TypeMismatch] if `--wait=` carries something that is not a Boolean word
+      def take_wait(spec, words)
+        return [words, false] unless words.any? { |word| wait_word?(word) }
+        return [words, false] if spec[:arguments].any? { |argument| argument[:path].split(".").first == "wait" }
+
+        wait  = false
+        rest  = []
+        queue = words.dup
+        until queue.empty?
+          word = queue.shift
+          wait_word?(word) ? wait ||= CliDoor.boolean(wait_value(word, queue)) : rest << word
+        end
+        [rest, wait]
+      end
+
+      # @api private
+      def wait_word?(word) = word == WAIT || word.start_with?("#{WAIT}=")
+
+      # The Boolean word a `--wait` carries: after `=`, or the next word when it is one.
+      # @api private
+      def wait_value(word, queue)
+        return word.split("=", 2).last if word.include?("=")
+
+        CliDoor::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+      end
+
+      # Whether a question's text answer reports a gap, which `--wait` turns into a failing exit.
+      #
+      # The coverage checks end their report with a `GAP (n)` heading; a non-zero count is a
+      # finding, and a CI stage that waits on the question fails on it.
+      #
+      # @param text [String, nil] the question's text answer
+      # @return [Boolean] whether a `GAP (n)` heading with n above zero is in the text
+      def gap_reported?(text)
+        text.is_a?(String) && text.match?(/^GAP \((?!0\))\d+\)/)
+      end
+
+      # Mints the `run` key a creating command was not given, when the domain opted in.
+      #
+      # An explicit key always wins. Nothing is minted for a command that acts on an existing
+      # record. When no identity adapter is bound the run is refused, saying to name a key,
+      # rather than sent on without one.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param spec [Hash] the verb's projected spec
+      # @param args [Hash] the parsed arguments
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)
+      # @raise [Runtime::NotFound] if a key is owed but no identity adapter is bound
+      def run_key(runtime, spec, args, settings)
+        return [args, nil] unless settings && settings[:run_keys] && spec[:creates]
+        return [args, nil] unless spec[:arguments].any? { |argument| argument[:path] == RUN_KEY }
+        return [args, nil] if args.key?(:run) || !runtime.respond_to?(:registry)
+
+        key = Ports::IdentityGeneration.uuid(runtime.registry)
+        [args.merge(run: { value: key }), key]
+      rescue Runtime::WiringError => e
+        raise Runtime::NotFound, "cannot mint a run key (#{e.message.lines.first.strip}); name one with run=<key>"
+      end
+
+      # Whether a settled record sits in one of the chapter's failure states.
+      #
+      # @param aggregate [Bluebook::Aggregate, nil] the record's aggregate
+      # @param state [Hash, nil] the record's state
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @return [Boolean] false when the aggregate has no lifecycle
+      def failed?(aggregate, state, settings)
+        field = aggregate&.lifecycle&.field
+        return false unless field && state
+
+        Array(settings && settings[:failure_states]).map(&:to_s).include?(state[field.to_sym].to_s)
+      end
+    end
+  end
+end

data/lib/hecks/{cli → doors}/mcp_door.rb

@@ -1,9 +1,9 @@
 require "json"
 require_relative "../../hecks"
-require_relative "mcp"
+require_relative "../cli/mcp"
 
 module Hecks
-  module CLI
+  module Doors
     # The MCP door onto the storehouse bus: hand-rolled JSON-RPC over stdio, one
     # server per booted domain. All logic and the JSON shape answered with live in
     # `Storehouse`; this is plumbing only. A `role:`/`actor_id:` a caller sends is
@@ -235,7 +235,7 @@ module Hecks
       # Read once, so a bad setting refuses to start the door before anything is
       # written to stdout.
       def scope
-        @scope ||= McpDoorScope.start!(server: Mcp::SERVER)
+        @scope ||= McpDoorScope.start!(server: CLI::Mcp::SERVER)
       end
 
       # The standing notes, then what this door's scope says about `domain:`.
@@ -244,7 +244,7 @@ module Hecks
       end
 
       def serve
-        McpStdioGuard.warn!(server: Mcp::SERVER, notes: warning_notes)
+        McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
         $stdout.sync = true
 
         $stdin.each_line do |line|
@@ -269,7 +269,7 @@ module Hecks
       # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
       # door's `HECKS_DOOR_DOMAINS`, before anything boots.
       def boot(domain)
-        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_facade: false)
+        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_doors: false)
       end
 
       # One `when` per tool, so the shared `rescue` catches every branch's escape
@@ -315,7 +315,7 @@ module Hecks
         end
       rescue StandardError => e
         # A defect, not a refusal: reaching here means a bad domain path or an
-        # argument shape `Facade::JsonDoor` could not symbolize.
+        # argument shape `Doors::JsonDoor` could not symbolize.
         { ok: false, error: "#{e.class}: #{e.message}" }
       end
 
@@ -347,7 +347,7 @@ module Hecks
           send_response(id, {
                           protocolVersion: PROTOCOL_VERSION,
                           capabilities:    { tools: {} },
-                          serverInfo:      { name: Mcp::SERVER, version: "1.1.0" }
+                          serverInfo:      { name: CLI::Mcp::SERVER, version: "1.1.0" }
                         })
         when "notifications/initialized"
           nil # a notification — no id, no response

data/lib/hecks/doors/mcp_door_scope.rb

@@ -0,0 +1,97 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Doors
+    # What a spawned hecks mcp may do: every tool by default, or only
+    # reader tools against named domains in reader mode — reach, not identity (ADR 0072).
+    class McpDoorScope
+      ENV_PREFIX       = "HECKS_DOOR_".freeze
+      TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
+      DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
+      READERS          = "readers".freeze
+      EXIT_STATUS      = 2
+
+      # The tools a reader door serves — each reads a domain or the door's own
+      # audit log and writes no domain state. `validate` still boots its
+      # domain, so it stays bound to the allowed set like every other tool.
+      READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
+
+      # Unrestricted when no HECKS_DOOR_* variable is set.
+      def self.from_env(env = ENV)
+        problems = setting_problems(env)
+        raise ArgumentError, problems.join("\n") unless problems.empty?
+        return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
+
+        new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
+      end
+
+      # Refuses to stderr, not stdout, which carries the MCP protocol.
+      def self.start!(server:, env: ENV, stderr: $stderr)
+        from_env(env)
+      rescue ArgumentError, Runtime::TypeMismatch => e
+        e.message.each_line { |line| stderr.puts("#{server}: refusing to start: #{line.chomp}") }
+        exit(EXIT_STATUS)
+      end
+
+      def self.setting_problems(env)
+        unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
+        problems = unknown.map do |name|
+          "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
+        end
+        problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
+      end
+
+      def self.mode_problems(tools, domains)
+        if tools.nil?
+          domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
+        elsif tools != READERS
+          ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
+        elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
+          ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
+        else
+          []
+        end
+      end
+
+      # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
+      attr_reader :allowed_domains
+
+      def initialize(allowed_domains:)
+        @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
+      end
+
+      def restricted?
+        !@allowed_domains.nil?
+      end
+
+      def permits_tool?(name)
+        !restricted? || READER_TOOLS.include?(name)
+      end
+
+      def refusal(name)
+        { ok:    false,
+          error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
+                 "which serves only #{READER_TOOLS.join(', ')}" }
+      end
+
+      # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
+      def admit_domain!(domain)
+        return domain unless restricted?
+        return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
+
+        raise Runtime::TypeMismatch,
+              "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
+              "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
+      end
+
+      def notes
+        return [] unless restricted?
+
+        ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
+         "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+         "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
+         "Reader mode limits reach and identifies no one; it is not authentication."]
+      end
+    end
+  end
+end

data/lib/hecks/{facade/surface → doors/ruby_door}/aggregate_door.rb

@@ -1,4 +1,5 @@
 require_relative "../../bluebook/dsl/hecksagon_builder"
+require_relative "../../bluebook/dsl/world_builder"
 require_relative "../../bluebook/dsl/domain_port_builder"
 require_relative "../../bluebook/dsl/const_shim"
 require_relative "../../bluebook/dsl/binding_proxy"
@@ -7,8 +8,8 @@ require_relative "../handle"
 require_relative "../../naming"
 
 module Hecks
-  module Facade
-    module Surface
+  module Doors
+    module RubyDoor
       # One aggregate's door: creating verbs and queries as module methods, CRUD
       # delegation, and the `.hecksagon` binding/port hooks it lands on.
       module AggregateDoor
@@ -123,6 +124,9 @@ module Hecks
             return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
 
             collector = Bluebook::DSL::HecksagonBuilder.collector
+            world     = Bluebook::DSL::WorldBuilder.current
+            # Inside a `.world` block the same qualified spelling records a world setting.
+            return world.record_binding(verb, args, kwargs, block) if world && !collector
             return super(verb, *args, **kwargs, &block) unless collector
 
             collector << Bluebook::Bind.new(
@@ -136,7 +140,8 @@ module Hecks
           end
 
           door.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
-            !Bluebook::DSL::HecksagonBuilder.collector.nil? || super(name, include_private)
+            !Bluebook::DSL::HecksagonBuilder.collector.nil? || !Bluebook::DSL::WorldBuilder.current.nil? ||
+              super(name, include_private)
           end
 
           # Uses `aggregate.hecks_name`, not the qualified `fqn`: qualifying it here

data/lib/hecks/{facade/surface → doors/ruby_door}/chapter.rb

@@ -3,8 +3,8 @@ require_relative "../../bluebook/dsl/const_shim"
 require_relative "../../bluebook/dsl/hecksagon_builder"
 
 module Hecks
-  module Facade
-    module Surface
+  module Doors
+    module RubyDoor
       # One chapter's module: vision and aggregate list on the singleton, one
       # aggregate door per declared head, and a `const_missing` hook for undeclared names.
       module Chapter
@@ -15,7 +15,7 @@ module Hecks
         # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
         #   dispatcher each aggregate door closes over
         # @param bluebook [Bluebook::Chapter] the chapter to project into a module
-        # @return [Module] a fresh, unnamed module; `Surface.install` gives it its
+        # @return [Module] a fresh, unnamed module; `RubyDoor.install` gives it its
         #   top-level name
         # @raise [NameError] if an aggregate's name is not a valid constant name
         def chapter_module(dispatcher, bluebook)

data/lib/hecks/{facade/surface.rb → doors/ruby_door.rb}

@@ -1,14 +1,15 @@
-require_relative "surface/chapter"
-require_relative "surface/aggregate_door"
+require_relative "../chapters"
+require_relative "ruby_door/chapter"
+require_relative "ruby_door/aggregate_door"
 
 module Hecks
-  module Facade
+  module Doors
     # The door without classes: anonymous per-boot modules whose singleton methods
     # dispatch by FQN, installed by `Loader.bind_runtime` and replaced whole on the next boot.
     #
     # `persisted_by("Heki")` in a `.hecksagon` file lands on the module's `method_missing`,
     # which records a `Bind` into the open `HecksagonBuilder.collector`.
-    module Surface
+    module RubyDoor
       # Names that would shadow the machinery a Handle runs on; a field with one gets no reader.
       RESERVED = %i[id state events reload inspect to_h hash class].freeze
 
@@ -21,6 +22,7 @@ module Hecks
       # closing over `dispatcher`, so `Pizzas::Pizza` and the bare `Pizza` both open the
       # door of the boot that ran last.
       #
+      # A gem chapter a hecksagon `attaches` installs nothing (`Query`, `Port` stay free).
       # An aggregate sharing its chapter's name gets no second constant. A name that user
       # code or the stdlib already owns is left alone with a warning (see `Namespace.install`).
       #
@@ -30,8 +32,13 @@ module Hecks
       # @raise [NameError] if a chapter or aggregate name is not a valid constant name
       def install(dispatcher)
         dispatcher.registry.bluebooks.each_value do |bluebook|
+          next if attached_chapter?(dispatcher.registry, bluebook)
+
           chapter = chapter_module(dispatcher, bluebook)
-          Namespace.install(Object, bluebook.name, chapter)
+          Namespace.install(*placement(bluebook), chapter)
+          # A namespaced chapter keeps its aggregates inside its namespace: top-level
+          # shortcuts would bring back the collisions the namespace exists to avoid.
+          next if bluebook.namespace
 
           bluebook.aggregates.each do |aggregate|
             next if aggregate.hecks_name == bluebook.name
@@ -41,6 +48,30 @@ module Hecks
         end
         dispatcher
       end
+
+      # Whether `bluebook` is a gem chapter that a hecksagon attached rather than a domain's own.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param bluebook [Bluebook::Chapter] the chapter under test
+      # @return [Boolean]
+      def attached_chapter?(registry, bluebook)
+        registry.bounded?(bluebook.name) && Hecks::Chapters.index.key?(bluebook.name)
+      end
+
+      # Where a chapter's module installs: `Object::<name>`, or the constant path its
+      # `namespace` names, creating any missing parent modules along the way.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being installed
+      # @return [Array(Module, String)] the parent module and the constant name within it
+      def placement(bluebook)
+        return [Object, bluebook.name] unless bluebook.namespace
+
+        *parents, leaf = bluebook.namespace.split("::")
+        parent = parents.reduce(Object) do |outer, name|
+          outer.const_defined?(name, false) ? outer.const_get(name, false) : outer.const_set(name, Module.new)
+        end
+        [parent, leaf]
+      end
     end
   end
 end

data/lib/hecks/doors.rb

@@ -0,0 +1,61 @@
+module Hecks
+  # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
+  module Doors
+    # The removal release of the `Facade` and `install_facade:` spellings.
+    REMOVAL = "3.1.0".freeze
+
+    module_function
+
+    # Resolves the boot switch from the current keyword and its deprecated spelling.
+    #
+    # @param install_doors [Boolean] the `install_doors:` keyword
+    # @param install_facade [Boolean, nil] the deprecated `install_facade:` keyword; nil when
+    #   the caller did not pass it
+    # @return [Boolean] whether to install the Ruby door constants
+    def install?(install_doors, install_facade = nil)
+      return install_doors if install_facade.nil?
+
+      warn "[hecks] `install_facade:` is deprecated and is removed in #{REMOVAL}; use `install_doors:`"
+      install_facade
+    end
+  end
+
+  # Installs facade constants at top level, replacing only what it installed itself.
+  # A constant owned by user code or the stdlib is left alone with a warning.
+  module Namespace
+    # A live registry, mutated by `install`, so it cannot be frozen.
+    # rubocop:disable-next Style/MutableConstant
+    GENERATED = {}
+
+    module_function
+
+    # Sets `container::name` to `value`, replacing only a constant this module installed.
+    #
+    # @param container [Module] the namespace to define the constant in
+    # @param name [String, Symbol] the constant name
+    # @param value [Module] the facade module to install
+    # @return [Object] `value` when installed, else the foreign constant left in place
+    # @raise [NameError] if `name` is not a valid constant name
+    def install(container, name, value)
+      name = name.to_s
+
+      if container.const_defined?(name, false)
+        current = container.const_get(name)
+        unless GENERATED[[container, name]].equal?(current)
+          warn "[hecks] #{name} is already defined — leaving it alone"
+          return current
+        end
+        container.send(:remove_const, name)
+      end
+
+      container.const_set(name, value)
+      GENERATED[[container, name]] = value
+      value
+    end
+  end
+end
+
+require_relative "doors/handle"
+require_relative "doors/ruby_door"
+require_relative "doors/command_request"
+require_relative "doors/json_door"

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -3,7 +3,7 @@ require_relative "vendor"
 
 module Hecks
   module EmbryonautBluebook
-    # The command line behind `bin/vendor_bluebook`; lives in the gem so a
+    # The command line behind `hecks vendor`; lives in the gem so a
     # consuming project reaches it through its own bundle, no script to copy.
     #
     #     vendor_bluebook <package>[@<version-or-commit>] [--from path] [--root path]

data/lib/hecks/embryonaut_bluebook.rb

@@ -31,7 +31,7 @@ module Hecks
       if files.empty?
         raise Runtime::WiringError,
               "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "vendor it with bin/vendor_bluebook #{name}"
+              "vendor it with hecks vendor #{name}"
       end
 
       # Loaded in the glob's alphabetical order; a package with several

data/lib/hecks/engine_agreement.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Hecks
+  # The grep-based gate that keeps the query engines agreeing on what a comparator means.
+  #
+  # It fails when an engine re-grows its own comparator dispatch, or when a declared comparator
+  # lacks a shared `Comparison` case or a cross-engine agreement spec. Every declared comparator
+  # is read from `Hecks::Vocabulary`, as `Common::COMPARATORS` is: one live source, no copied list.
+  module EngineAgreement
+    # The engine files that must route every comparator through `Comparison.holds?`.
+    ENGINE_FILES = {
+      "in-memory port (Memory/Heki-backed aggregate queries)"                    => "lib/hecks/ports/query/in_memory.rb",
+      "reference interpreter (entity/sub-list queries, no-native-hook fallback)" => "lib/hecks/runtime/query_interpreter.rb"
+    }.freeze
+
+    # Where the shared comparison logic lives.
+    SHARED_COMPARISON_FILE = "lib/hecks/query_specification/common/comparison.rb"
+
+    # Specs that put each comparator in front of both engines. `none_in_state` needs a second
+    # aggregate and a registry, so the two dedicated growth specs cover it instead.
+    AGREEMENT_SPEC_FILES = %w[
+      spec/adapters/query_agreement_spec.rb
+      spec/query_none_in_state_aggregate_level_growth_spec.rb
+      spec/query_none_in_state_growth_spec.rb
+    ].freeze
+
+    # What a check found.
+    #
+    # @!attribute [r] declared
+    #   @return [Array<String>] the comparators the vocabulary declares
+    # @!attribute [r] problems
+    #   @return [Array<String>] each disagreement, in words; empty when the engines agree
+    Finding = Struct.new(:declared, :problems)
+
+    module_function
+
+    # Checks the engines against the vocabulary.
+    #
+    # @param root [String] the checkout whose files are read
+    # @return [Finding] the declared comparators and every problem found
+    def check(root:)
+      require "hecks"
+      declared = Hecks::Vocabulary.symbols("QueryComparator").map(&:to_s)
+      if declared.empty?
+        return Finding.new(declared, ["Vocabulary::QueryComparator declared no comparators at all — " \
+                                      "vocabulary.bluebook failed to register, or Hecks::Vocabulary changed " \
+                                      "shape. Refusing to report a clean pass."])
+      end
+
+      problems = vocabulary_problems(declared) + engine_problems(root, declared) + shared_problems(root, declared)
+      Finding.new(declared, problems)
+    end
+
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem when the language and the runtime table disagree
+    def vocabulary_problems(declared)
+      runtime = Hecks::QuerySpecification::Common::COMPARATORS.map(&:to_s)
+      differ = (declared - runtime) | (runtime - declared)
+      return [] if differ.empty?
+
+      ["Vocabulary::QueryComparator #{declared.sort.inspect} and " \
+       "QuerySpecification::Common::COMPARATORS #{runtime.sort.inspect} disagree " \
+       "(only in one: #{differ.sort.inspect}) — the language and the runtime table it drives " \
+       "have drifted apart."]
+    end
+
+    # @param root [String] the checkout
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem for each engine that lost `Comparison.holds?` or grew a case
+    def engine_problems(root, declared)
+      ENGINE_FILES.flat_map do |label, relative|
+        source = File.read(File.join(root, relative))
+        found = []
+        unless source =~ /Comparison\.holds\?/
+          found << "#{relative} (#{label}) no longer calls Comparison.holds? at all — " \
+                   "has it grown its own comparator dispatch again?"
+        end
+        declared.each do |comparator|
+          escaped = Regexp.escape(comparator)
+          next unless source =~ /when\s+"#{escaped}"/ || source =~ /when\s+:#{escaped}\b/
+
+          found << "#{relative} (#{label}) has its own `when #{comparator.inspect}` — comparator logic " \
+                   "belongs ONLY in #{SHARED_COMPARISON_FILE}, not re-implemented per engine."
+        end
+        found
+      end
+    end
+
+    # @param root [String] the checkout
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem for a comparator with no shared case, or no agreement spec
+    def shared_problems(root, declared)
+      comparison = File.read(File.join(root, SHARED_COMPARISON_FILE))
+      specs = AGREEMENT_SPEC_FILES.map { |path| File.read(File.join(root, path)) }
+      missing_case = declared.reject { |comparator| comparison =~ /when\s+"#{Regexp.escape(comparator)}"/ }
+      missing_spec = declared.reject { |comparator| specs.any? { |text| mentions_operator?(text, comparator) } }
+
+      [missing_case_problem(missing_case), missing_spec_problem(missing_spec)].compact
+    end
+
+    # @param missing [Array<String>] comparators with no `when` case in the shared file
+    # @return [String, nil] the problem, or nil when none is missing
+    def missing_case_problem(missing)
+      return nil if missing.empty?
+
+      "#{SHARED_COMPARISON_FILE} has no `when` case for: #{missing.sort.inspect} — " \
+        "a declared comparator with no shared implementation falls to Comparison.holds?'s own `else`, " \
+        "which RAISES (by design), but only the first time anything actually asks for it at runtime. " \
+        "Add a `when #{missing.first.inspect} then ...` case before shipping this comparator."
+    end
+
+    # @param missing [Array<String>] comparators no agreement spec exercises
+    # @return [String, nil] the problem, or nil when none is missing
+    def missing_spec_problem(missing)
+      return nil if missing.empty?
+
+      "no example in #{AGREEMENT_SPEC_FILES.inspect} exercises: #{missing.sort.inspect} — " \
+        "a comparator with a case but no cross-engine spec has never actually had both engines asked " \
+        "the same question. Add a declared query using it, with a hand-computed expected id list, to one " \
+        "of those files (see spec/adapters/query_agreement_spec.rb's own header for why a hand-computed " \
+        "oracle, not mere pairwise agreement, is the standard)."
+    end
+
+    # @param text [String] a spec's source
+    # @param comparator [String] the comparator name, such as `"eq"`
+    # @return [Boolean] whether the spec puts the comparator in front of an engine
+    def mentions_operator?(text, comparator)
+      # Explicit form: the comparator as a bare hash key, bounded so `in:` cannot match
+      # mid-identifier.
+      return true if text =~ /(?<![A-Za-z0-9_])#{Regexp.escape(comparator)}(?![A-Za-z0-9_])\s*:/
+
+      # `eq` is normally implicit (`where(status: "open")`), so an example description naming it
+      # counts; no other comparator gets that leniency.
+      return false unless comparator == "eq"
+
+      text =~ /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i ? true : false
+    end
+
+    # @param finding [Finding] what a check found
+    # @return [String] the clean-pass line
+    def clean_line(finding)
+      "check_engine_agreement: #{finding.declared.size} declared comparator(s) " \
+        "(#{finding.declared.sort.join(', ')}) — every one has a shared Comparison case, a cross-engine " \
+        "agreement spec, and both engine files still route through Comparison.holds? alone. 0 problems."
+    end
+
+    # @param finding [Finding] what a check found
+    # @return [String] every problem, numbered, with where the mechanism is explained
+    def problem_lines(finding)
+      numbered = finding.problems.each_with_index.map { |problem, index| "  #{index + 1}. #{problem}\n\n" }
+      ["check_engine_agreement: #{finding.problems.size} problem(s) found:\n\n", *numbered,
+       "See lib/hecks/query_specification/common/comparison.rb's own header for what this mechanism " \
+       "replaced and why a grep-based gate exists here at all."].join
+    end
+  end
+end