hecks 2.9.0 → 3.0.1

data/lib/hecks/cli/refresh_rspec_runtime_baseline.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "yaml"
+
+module Hecks
+  module CLI
+    # The command behind `hecks refresh_runtime_baseline`: regenerates the committed runtime
+    # baselines the sharded CI jobs group from. It prefers one CI run's timings; a local run is
+    # the fallback.
+    #
+    #   hecks refresh_runtime_baseline --from-run <run-id>   # preferred: one CI run's timings
+    #   hecks refresh_runtime_baseline [workers]             # fallback: this machine only
+    #
+    # `--from-run` reads the runtime-log artifacts of a successful run and writes a family only
+    # when every leg uploaded one; a partial set would skew the split. Runner seconds differ from a
+    # laptop's, so a local baseline misses subprocess-heavy specs. The local mode refuses a red run.
+    module RefreshRspecRuntimeBaseline
+      REPO = "heckslabs/hecks"
+      USAGE = "usage: hecks refresh_runtime_baseline --from-run <run-id> | [workers]"
+
+      # Only `spec/..._spec.rb:<seconds>` lines; RSpec's "Run options" line must not be copied
+      # into a committed file. Seconds can arrive in exponent form (`9.69e-05`).
+      RUNTIME_LINE = %r{\A(?<file>spec/\S+_spec\.rb):(?<seconds>\d+(?:\.\d+)?(?:e-?\d+)?)\z}
+
+      module_function
+
+      # Refreshes the baselines from a CI run or a local run.
+      #
+      # @param argv [Array<String>] `--from-run RUN_ID`, or optionally the local worker count
+      # @param root [String] the checkout whose `.github/` baselines are rewritten
+      # @param out [IO] where what was written goes
+      # @return [Integer] the exit status, 0 once written
+      # @raise [SystemExit] when the run is unreadable or unsuccessful, the local suite is red, or
+      #   no artifact family is complete
+      def call(argv, root:, out: $stdout)
+        if argv.first == "--from-run"
+          from_run(root, argv.fetch(1) { abort USAGE }, out)
+        else
+          from_local(root, argv.fetch(0, "6"), out)
+        end
+        0
+      end
+
+      # Reads the leg counts from the workflow matrix so a resize cannot leave a stale count here.
+      #
+      # @param root [String] the checkout
+      # @return [Hash{String => Hash}] each artifact family's leg count and baseline file
+      def families(root)
+        {
+          "rspec-runtime-group"       => { legs:     matrix_legs(root, "ci-rspec.yml", "rspec_shard"),
+                                           baseline: ".github/rspec_runtime_baseline.log" },
+          "postgres-io-runtime-group" => { legs:     matrix_legs(root, "ci-postgres-io-parallel.yml",
+                                                                 "rspec_postgres_io_parallel_shard"),
+                                           baseline: ".github/postgres_io_runtime_baseline.log" }
+        }
+      end
+
+      # @param root [String] the checkout
+      # @param workflow [String] the workflow file's name
+      # @param job [String] the job whose matrix is counted
+      # @return [Integer] how many groups the job's matrix has
+      def matrix_legs(root, workflow, job)
+        YAML.load_file(File.join(root, ".github/workflows", workflow)).dig("jobs", job, "strategy", "matrix", "group").size
+      end
+
+      # @param paths [Array<String>] runtime logs
+      # @return [Array<String>] one sorted `file:seconds` line per spec file
+      def baseline_lines(paths)
+        seconds_by_file = paths.flat_map { |path| File.readlines(path) }.filter_map do |line|
+          match = RUNTIME_LINE.match(line.strip) or next
+          [match[:file], Float(match[:seconds])]
+        end.to_h
+        seconds_by_file.map { |file, seconds| format("%<file>s:%<seconds>.2f", file: file, seconds: seconds) }.sort
+      end
+
+      # @param root [String] the checkout
+      # @param relative [String] the baseline's path under the checkout
+      # @param lines [Array<String>] the baseline's lines
+      # @param out [IO] where the note goes
+      # @return [void]
+      def write_baseline(root, relative, lines, out)
+        File.write(File.join(root, relative), "#{lines.join("\n")}\n")
+        out.puts "wrote #{relative}: #{lines.size} spec files"
+      end
+
+      # @param run_id [String] the CI run's id
+      # @return [void]
+      # @raise [SystemExit] when `gh` cannot read the run or it did not succeed
+      def refuse_unless_successful!(run_id)
+        out, status = Open3.capture2("gh", "run", "view", run_id, "-R", REPO, "--json", "conclusion")
+        abort "hecks refresh_runtime_baseline: could not read run #{run_id}" unless status.success?
+
+        conclusion = JSON.parse(out)["conclusion"]
+        return if conclusion == "success"
+
+        abort "hecks refresh_runtime_baseline: run #{run_id} concluded #{conclusion.inspect} — " \
+              "refusing to write a baseline from anything but a successful run"
+      end
+
+      # @param root [String] the checkout
+      # @param run_id [String] the CI run's id
+      # @param out [IO] where what was written goes
+      # @return [void]
+      # @raise [SystemExit] when no family of artifacts is complete
+      def from_run(root, run_id, out)
+        refuse_unless_successful!(run_id)
+        dir = File.join(root, "tmp/ci-runtime-#{run_id}")
+        FileUtils.rm_rf(dir)
+
+        written = families(root).count do |prefix, family|
+          system("gh", "run", "download", run_id, "-R", REPO, "-p", "#{prefix}-*", "-D", dir,
+                 out: File::NULL, err: File::NULL)
+          logs = Dir[File.join(dir, "#{prefix}-*", "*.log")]
+          legs = logs.map { |path| File.basename(File.dirname(path)) }.uniq.size
+          if legs == family[:legs]
+            write_baseline(root, family[:baseline], baseline_lines(logs), out)
+            true
+          else
+            warn "skipping #{family[:baseline]}: run #{run_id} has #{legs} of #{family[:legs]} #{prefix}-* artifacts"
+            false
+          end
+        end
+        return unless written.zero?
+
+        abort "hecks refresh_runtime_baseline: run #{run_id} had no complete artifact family — nothing written"
+      end
+
+      # @param root [String] the checkout
+      # @param workers [String] how many `parallel_rspec` workers to time with
+      # @param out [IO] where what was written goes
+      # @return [void]
+      # @raise [SystemExit] when the local suite is red
+      def from_local(root, workers, out)
+        raw = "tmp/rspec_runtime_baseline.raw.log"
+        FileUtils.mkdir_p(File.join(root, "tmp"))
+        FileUtils.rm_f(File.join(root, raw))
+
+        formatters = "--tag ~io --tag ~fuzzing --format progress --format ParallelTests::RSpec::RuntimeLogger --out #{raw}"
+        green = system("bundle", "exec", "parallel_rspec", "spec", "-n", workers, "-o", formatters, chdir: root)
+        abort "hecks refresh_runtime_baseline: the spec run failed — not writing a baseline from a red suite" unless green
+
+        write_baseline(root, families(root).fetch("rspec-runtime-group")[:baseline],
+                       baseline_lines([File.join(root, raw)]), out)
+      end
+    end
+  end
+end

data/lib/hecks/cli/release.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../release/runner"
+
+module Hecks
+  module CLI
+    # The command behind `hecks publish`: tags the merged release commit, publishes the gem, and
+    # gets `@hecks/client` published to npm. See "Releasing" in CONTRIBUTING.md for the release PR.
+    #
+    #   hecks publish --dry-run    # every check and build, nothing tagged or published
+    #   hecks publish              # tag, gem, then wait for CI to publish the client
+    module Release
+      # The flags a run starts with, before any is named.
+      DEFAULT_FLAGS = { dry_run: false, gem_only: false, npm_only: false, npm_local: false,
+                        no_wait: false, yes: false }.freeze
+
+      module_function
+
+      # Parses the flags and runs the release.
+      #
+      # @param argv [Array<String>] the command line's flags
+      # @param root [String] the repository root the release runs in
+      # @return [Integer] the release's exit status, or 2 for a flag it does not know
+      def call(argv, root:)
+        argv = argv.dup
+        flags = DEFAULT_FLAGS.dup
+        parser = parser_for(flags)
+        begin
+          parser.parse!(argv)
+          raise OptionParser::InvalidArgument, argv.join(" ") unless argv.empty?
+
+          return 0 if flags.delete(:help)
+
+          options = Hecks::Release::Runner::Options.new(**flags)
+        rescue OptionParser::ParseError, ArgumentError => e
+          warn "hecks publish: #{e.message}"
+          warn parser
+          return 2
+        end
+
+        Hecks::Release::Runner.new(root: root, options: options).call
+      end
+
+      # @param flags [Hash{Symbol => Boolean}] filled in as the parser reads each flag
+      # @return [OptionParser] the parser for `hecks publish`'s flags
+      def parser_for(flags)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: hecks publish [--dry-run] [--gem-only | --npm-only] [--npm-local | --no-wait] [--yes]"
+          opts.separator("Tags the merged release commit, publishes the gem, and gets @hecks/client published.")
+          opts.separator("By default CI publishes the client from the tag and this waits for it.")
+          opts.on("--dry-run", "run every check and build; tag, push and publish nothing") { flags[:dry_run] = true }
+          opts.on("--gem-only", "publish the gem only") { flags[:gem_only] = true }
+          opts.on("--npm-only", "skip the gem: wait for CI's publish, or with --npm-local publish from here") do
+            flags[:npm_only] = true
+          end
+          opts.on("--npm-local", "publish @hecks/client from this machine (first publish, or CI is down)") do
+            flags[:npm_local] = true
+          end
+          opts.on("--no-wait", "do not wait for CI's publish to reach npm") { flags[:no_wait] = true }
+          opts.on("--yes", "answer the confirmations yes") { flags[:yes] = true }
+          opts.on("--help", "print this usage") do
+            puts opts
+            flags[:help] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/release_gem.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../release/runner/commands"
+require_relative "../hecks/adapters/codebase/gem_registry"
+require_relative "../version"
+
+module Hecks
+  module CLI
+    # The command behind `hecks publish_gem` and the release runner's gem step: builds the hecks
+    # gem and pushes it to rubygems.org, using a push-scoped API key from 1Password instead of
+    # `~/.gem/credentials`. It pushes the version it is given, `Hecks::VERSION` by default.
+    module ReleaseGem
+      module_function
+
+      # Builds and pushes the gem, refusing unless `op` is installed and the JS client is at the
+      # same version (`spec/hecks_client_version_spec.rb` pins that rule too).
+      #
+      # @param root [String] the repository root the gem is built from
+      # @param commands [#run!, #capture, nil] runs the child commands; a real one when nil
+      # @param out [IO] where progress goes
+      # @param err [IO] where a refusal goes
+      # @param version [String] the version to build and push
+      # @return [Integer] 0 once pushed, 1 when refused
+      def call(root:, commands: nil, out: $stdout, err: $stderr, version: Hecks::VERSION)
+        Dir.chdir(root) do
+          commands ||= Hecks::Release::Runner::Commands.new
+          registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
+          refusal = refusal_for(root, commands, version)
+          if refusal
+            err.puts refusal
+            return 1
+          end
+
+          out.puts "Building and pushing hecks-#{version}.gem to rubygems.org " \
+                   "(1Password will prompt for Touch ID)..."
+          registry.push!(version)
+          out.puts "Released hecks #{version}."
+          0
+        end
+      end
+
+      # @param root [String] the repository root
+      # @param commands [#run!, #capture] runs the child commands
+      # @param version [String] the version being released
+      # @return [String, nil] why the release cannot start, or nil when it can
+      def refusal_for(root, commands, version = Hecks::VERSION)
+        unless Hecks::Adapters::Codebase::SecretVault.new(commands: commands).installed?
+          return "1Password CLI (op) not found. Install: brew install 1password-cli"
+        end
+
+        client_version = JSON.parse(File.read(File.join(root, "packages/hecks-client/package.json"))).fetch("version")
+        return nil if client_version == version
+
+        "packages/hecks-client is at #{client_version} but Hecks::VERSION is #{version}; bump the package first."
+      end
+    end
+  end
+end

data/lib/hecks/cli/rspec_io_parallel_files.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module CLI
+    # The command behind `hecks list_io_parallel_specs`: prints, one per line, the spec files with
+    # at least one example matching an RSpec tag filter. ci.yml hands the list to `parallel_rspec`
+    # instead of the whole `spec` directory.
+    #
+    # Given every spec file, parallel_tests ignores the runtime log unless it covers about 67% of
+    # them, so a tag-filtered job silently groups by file size. A dry run, not grep, picks the
+    # files so inherited tags, `~fuzzing` and shared examples count.
+    #
+    # The list is committed (`.github/postgres_io_spec_files.txt`). `--write FILE` refreshes it;
+    # `--check FILE` (CI's postgres_io_file_list job) fails on a stale list.
+    #
+    #   hecks list_io_parallel_specs '<exclude-pattern regex>' -- --tag io --tag ~fuzzing
+    module RspecIoParallelFiles
+      module_function
+
+      # Lists the matching files, writes them, or checks a committed list.
+      #
+      # @param argv [Array<String>] `--check FILE` or `--write FILE` optionally, the exclude
+      #   pattern, `--`, then the RSpec tag arguments
+      # @param root [String] the checkout whose `spec/` is searched; the dry run runs there
+      # @param out [IO] where the list goes when neither flag is given
+      # @param err [IO] where the tally and any staleness go
+      # @return [Integer] the exit status, 0 once done
+      # @raise [SystemExit] on a bad command line, an empty candidate set, a failed dry run, or a
+      #   stale committed list
+      def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        argv = argv.dup
+        mode, list_path = argv.shift(2) if %w[--check --write].include?(argv.first)
+        abort "hecks list_io_parallel_specs: #{mode} needs a file path" if mode && list_path.nil?
+
+        exclude_arg, tag_args = parse(argv)
+        candidates = Dir.glob("spec/**/*_spec.rb", base: root).grep_v(Regexp.new(exclude_arg)).sort
+        refuse_empty_candidates(candidates)
+        files, example_count = matching_files(candidates, tag_args, root, err)
+        err.puts "hecks list_io_parallel_specs: #{files.size} of #{candidates.size} candidate files carry a " \
+                 "matching example (#{example_count} examples total) under `#{tag_args.join(' ')}`"
+
+        case mode
+        when "--write" then File.write(File.expand_path(list_path, root), "#{files.join("\n")}\n")
+        when "--check" then check(files, File.expand_path(list_path, root), list_path, exclude_arg, tag_args, err)
+        else out.puts files
+        end
+        0
+      end
+
+      # @param argv [Array<String>] the exclude pattern, `--`, and the tag arguments
+      # @return [Array(String, Array<String>)] the pattern and the tag arguments
+      # @raise [SystemExit] with the usage line when either is missing
+      def parse(argv)
+        exclude_arg, *rest = argv
+        separator = rest.index("--")
+        usage = "usage: hecks list_io_parallel_specs '<exclude-pattern regex>' -- <rspec tag args...>"
+        abort usage unless exclude_arg && separator
+        tag_args = rest[(separator + 1)..]
+        abort usage if tag_args.nil? || tag_args.empty?
+
+        [exclude_arg, tag_args]
+      end
+
+      # @param candidates [Array<String>] the spec files left after the exclude pattern
+      # @return [void]
+      # @raise [SystemExit] when there are none, which means a broken pattern or an empty checkout
+      def refuse_empty_candidates(candidates)
+        return unless candidates.empty?
+
+        abort "hecks list_io_parallel_specs: found ZERO candidate spec files after applying the exclude " \
+              "pattern — that's almost certainly a broken pattern or an empty checkout, not a real empty " \
+              "test suite. Refusing to silently hand parallel_rspec nothing to run."
+      end
+
+      # Asks RSpec for a dry run of the candidates under the tag filter.
+      #
+      # @param candidates [Array<String>] the spec files to ask about
+      # @param tag_args [Array<String>] the RSpec tag arguments
+      # @param root [String] the directory the dry run runs in
+      # @param err [IO] where a failed run's stderr goes
+      # @return [Array(Array<String>, Integer)] the files with a matching example, and how many
+      #   examples matched
+      # @raise [SystemExit] when the dry run fails, prints no JSON, or matches nothing
+      def matching_files(candidates, tag_args, root, err)
+        command = ["bundle", "exec", "rspec", "--dry-run", *tag_args, "--format", "json", *candidates]
+        stdout, stderr, status = Open3.capture3(*command, chdir: root)
+        unless status.success?
+          err.puts stderr
+          abort "hecks list_io_parallel_specs: `#{command.join(' ')}` exited #{status.exitstatus} — " \
+                "see stderr above. Refusing to guess a file list from a failed dry run."
+        end
+
+        start = stdout.index('{"version"')
+        abort "hecks list_io_parallel_specs: couldn't find RSpec's JSON output in the dry-run's stdout:\n#{stdout}" unless start
+
+        examples = JSON.parse(stdout[start..])["examples"] || []
+        files = examples.map { |e| e.fetch("file_path").sub(%r{\A\./}, "") }.uniq.sort
+        return [files, examples.size] unless files.empty?
+
+        abort "hecks list_io_parallel_specs: #{candidates.size} candidate files, but the dry run matched ZERO " \
+              "examples under `#{tag_args.join(' ')}` — that's almost certainly a broken tag filter, not a " \
+              "real empty set. Refusing to silently hand parallel_rspec nothing to run."
+      end
+
+      # @param files [Array<String>] the files that carry a matching example
+      # @param path [String] the committed list's absolute path
+      # @param shown [String] the path as the person typed it
+      # @param exclude_arg [String] the exclude pattern, for the refresh command
+      # @param tag_args [Array<String>] the tag arguments, for the refresh command
+      # @param err [IO] where the difference goes
+      # @return [void]
+      # @raise [SystemExit] when the committed list differs
+      def check(files, path, shown, exclude_arg, tag_args, err)
+        committed = File.exist?(path) ? File.readlines(path, chomp: true).reject(&:empty?) : []
+        missing = files - committed
+        stale = committed - files
+        return if missing.empty? && stale.empty?
+
+        err.puts "#{shown} is out of date."
+        err.puts named("carries a matching example but is not listed (would never run in the shards)", missing) if missing.any?
+        err.puts named("listed but carries no matching example any more", stale) if stale.any?
+        abort "Refresh it and commit the result:\n  " \
+              "hecks list_io_parallel_specs --write #{shown} '#{exclude_arg}' -- #{tag_args.join(' ')}"
+      end
+
+      # @param heading [String] what the paths have in common
+      # @param paths [Array<String>] the paths
+      # @return [String] the heading with the paths under it
+      def named(heading, paths)
+        "  #{heading}:\n    #{paths.join("\n    ")}"
+      end
+    end
+  end
+end

data/lib/hecks/cli/rspec_shard_files.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "parallel_tests/test/runner"
+
+module Hecks
+  module CLI
+    # The command behind `hecks shard_specs`: prints the spec files assigned to one group
+    # (1-indexed) of a runtime-balanced N-way split. `rspec_shard` in ci-rspec.yml passes the
+    # committed runtime baseline so every leg agrees.
+    #
+    # It does not use `parallel_rspec --only-group`, which forces one process per leg; this suite
+    # is CPU-bound, so each leg would use one of four vCPUs. The group's list comes from
+    # `tests_in_groups`, leaving `parallel_rspec` its own workers.
+    module RspecShardFiles
+      USAGE = "usage: hecks shard_specs <group 1-indexed> <num_groups> [runtime_log_path]"
+
+      module_function
+
+      # Prints the files of one group.
+      #
+      # @param argv [Array<String>] the group, the number of groups, and optionally a runtime log
+      # @param root [String] the checkout whose `spec/` is split
+      # @param out [IO] where the files go, one per line
+      # @param err [IO] where the group's size goes
+      # @return [Integer] the exit status, 0 once printed
+      # @raise [SystemExit] on missing or out-of-range arguments, or when there are no spec files
+      def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        group_arg, num_groups_arg, runtime_log = argv
+        abort USAGE unless group_arg && num_groups_arg
+
+        group = Integer(group_arg)
+        num_groups = Integer(num_groups_arg)
+        abort "group must be between 1 and #{num_groups}, got #{group}" unless (1..num_groups).cover?(group)
+
+        files = Dir.glob("spec/**/*_spec.rb", base: root)
+        if files.empty?
+          abort "hecks shard_specs: found ZERO spec files under spec/ — " \
+                "refusing to hand parallel_rspec nothing to run"
+        end
+
+        groups = Dir.chdir(root) { groups_of(files, num_groups, runtime_log && File.expand_path(runtime_log, root)) }
+        selected = groups[group - 1] || []
+        err.puts "hecks shard_specs: group #{group}/#{num_groups} has #{selected.size} of #{files.size} files"
+        out.puts selected
+        0
+      end
+
+      # Splits the files by recorded runtime, falling back to file size on a cold cache.
+      #
+      # `allowed_missing_percent` covers gaps inside a log, not a missing file (`Runner.runtimes`
+      # raises `Errno::ENOENT`).
+      #
+      # @param files [Array<String>] the spec files, relative to the checkout
+      # @param num_groups [Integer] how many groups to split into
+      # @param runtime_log [String, nil] the runtime log's path, used when the file exists
+      # @return [Array<Array<String>>] the files of each group
+      def groups_of(files, num_groups, runtime_log)
+        options = { group_by: :runtime, allowed_missing_percent: 100 }
+        options[:runtime_log] = runtime_log if runtime_log && File.exist?(runtime_log)
+        ParallelTests::Test::Runner.tests_in_groups(files, num_groups, **options)
+      rescue Errno::ENOENT
+        ParallelTests::Test::Runner.tests_in_groups(files, num_groups, group_by: :filesize)
+      end
+    end
+  end
+end

data/lib/hecks/cli/run.rb

@@ -6,7 +6,7 @@ require_relative "../ports/persistence/plugins/era"
 
 module Hecks
   module CLI
-    # The command behind `bin/run` and `hecks run`: dispatches one verb from the
+    # The command behind `hecks run`: dispatches one verb from the
     # command line, or executes a JSON step list and reports instances, events,
     # refusals, reactions, sagas and query rows.
     #
@@ -55,8 +55,8 @@ module Hecks
       # near miss deserves the runner's "did you mean" rather than the step-list
       # form's "no such script".
       def cli_form(domain, argv, program)
-        runtime = Hecks.boot(domain, install_facade: false)
-        text, status = Facade::CliRunner.call(runtime: runtime, argv: argv, program: program)
+        runtime = Hecks.boot(domain, install_doors: false)
+        text, status = Doors::CliRunner.call(runtime: runtime, argv: argv, program: program)
         status.zero? ? puts(text) : abort(text)
         exit 0
       end

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../hecks"
+require_relative "../fuzzing"
+
+module Hecks
+  module CLI
+    # The command behind `hecks seed_semantics_corpus`: seeds (or deliberately re-seeds) the
+    # `expect` block of semantics-corpus fixtures from the Ruby runtime. Review the result
+    # against `docs/semantics/bluebook-semantics.md` before committing.
+    #
+    #   hecks seed_semantics_corpus                                # fill fixtures missing an expect
+    #   SEED=refusal_kind_lifecycle hecks seed_semantics_corpus    # re-seed one, deliberately
+    #
+    # The seeded expectation is the definition, not a recording: both runtimes are compared to it.
+    # `occurred_at` is stripped from events (C7.3/C9.1); refusals keep verb, error and kind (C8.2).
+    module SeedSemanticsCorpus
+      module_function
+
+      # Seeds the fixtures that need it and reports which.
+      #
+      # @param root [String] the checkout whose `spec/corpus/semantics/` is seeded
+      # @param env [Hash{String => String}] `SEED` names the one fixture to re-seed
+      # @param out [IO] where the report goes
+      # @return [Integer] the exit status, always 0
+      def call(root:, env: ENV, out: $stdout)
+        only = env.fetch("SEED", nil)
+        seeded = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).filter_map do |path|
+          fixture = JSON.parse(File.read(path))
+          name = File.basename(path, ".json")
+          next if only ? only != name : fixture.key?("expect")
+
+          fixture["expect"] = expectation_for(root, fixture)
+          File.write(path, "#{JSON.pretty_generate(fixture)}\n")
+          name
+        end
+        report(out, seeded)
+        0
+      end
+
+      # Replays the fixture's script against the Ruby runtime. Each refusal's `"kind"` is reduced
+      # to its class name; `occurred_at` is stripped from events.
+      #
+      # @param root [String] the checkout the fixture's domain path is relative to
+      # @param fixture [Hash] the parsed fixture: `domain` and `steps`
+      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events
+      def expectation_for(root, fixture)
+        result = Hecks::Fuzzing::Replay.call(File.join(root, fixture["domain"]), fixture["steps"])
+        {
+          "refusals"  => JSON.parse(JSON.generate(result[:refusals])).each { |r| r["kind"] = r["kind"]&.split("::")&.last },
+          "instances" => JSON.parse(JSON.generate(result[:instances])),
+          "events"    => JSON.parse(JSON.generate(result[:events])).each { |e| e.delete("occurred_at") }
+        }
+      end
+
+      # @param out [IO] where the report goes
+      # @param seeded [Array<String>] the fixtures written
+      # @return [void]
+      def report(out, seeded)
+        if seeded.empty?
+          out.puts "nothing to seed — every fixture carries its expect (pass SEED=<name> to re-seed one deliberately)"
+        else
+          out.puts "seeded: #{seeded.join(', ')}"
+          out.puts "review each expect against docs/semantics/bluebook-semantics.md before committing — " \
+                   "it is the definition now"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/serve_query_ir_mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../mcp_stdio_guard"
+
+module Hecks
+  module CLI
+    # The command behind `hecks serve_query_ir_mcp` and `hecks serve_query_ir_mcp`: an MCP server
+    # exposing `Hecks::QueryIR`'s queries as tools, over newline-delimited JSON-RPC on stdio.
+    #
+    # Stdio only and unauthenticated (ADR 0062); the protocol lives in `Hecks::QueryIrMcp` and the
+    # query logic in `Hecks::QueryIR`. The stdio guard runs before the runtime loads, so a refused
+    # transport never boots anything.
+    module ServeQueryIrMcp
+      module_function
+
+      # Enforces stdio, then serves until stdin closes.
+      #
+      # @param argv [Array<String>] the arguments the server was started with
+      # @return [void]
+      # @raise [SystemExit] when the guard refuses the transport
+      def call(argv)
+        Hecks::McpStdioGuard.enforce_stdio!(server: "hecks-query-ir")
+
+        require_relative "../../hecks"
+        require_relative "../query_ir_mcp"
+        Hecks::QueryIrMcp.start(argv: argv)
+      end
+    end
+  end
+end