hecks 2.8.0 → 3.0.0

data/lib/hecks/runtime.rb

@@ -1,33 +1,7 @@
 # Hecks::Runtime
 #
-# The runtime layer's face. `lib/hecks/runtime/` held thirteen files and
-# no parent, so the layer had no surface of its own : `lib/hecks.rb`
-# required each file by hand, and the runtime's own state — the registry a
-# declaration is being collected into — sat on the top-level Hecks module
-# beside the DSL words.
-#
-# What lives here is what runs a domain :
-#
-#   Runtime.boot(path)          load a directory and return its Dispatcher
-#   Runtime.with_registry(r)    bind the ambient registry for the duration of a load
-#   Runtime.current_registry    the registry a declaration is landing in, or nil
-#
-# What does not live here is what declares one — `Hecks.bluebook`,
-# `.hecksagon`, `.port`, `.adapter`, `.world` are loading words and stay on the
-# top-level module, which now reads as a facade over this.
-#
-#   runtime = Hecks::Runtime.boot("examples/pizzas/bluebook")
-#   runtime.dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
-#
-# Note, and it is the reason this file exists : `current_registry` is still
-# process-global. Each boot builds a fresh Registry, and `Loader.bind_runtime`
-# installs a fresh facade door whose modules close over that boot's dispatcher
-# — no class-level runtime binding remains, so two boots in one process no
-# longer share dispatch state, only the top-level name (the last-bound door
-# wins the constant, which is what per-boot install means). Owning the state
-# here was the first move ; the dispatcher reachable per-runtime rather than
-# through a constant was the second, and it is done — the door is the only
-# constant left, and it is a projection, not the runtime.
+# Boots a domain directory and holds the ambient registry and caller state a boot runs under.
+# `current_registry` is process-global; each boot's dispatcher is per-boot.
 
 require_relative "runtime/event"
 require_relative "runtime/value"
@@ -55,45 +29,51 @@ require_relative "runtime/tenant_check"
 require_relative "runtime/loader"
 
 module Hecks
-  # See the file header above for what this module is and owns; nested
-  # here (rather than documented in place) only because the
-  # `require_relative` calls above must run before Ruby reopens the
-  # module they populate.
+  # The runtime layer: boots a domain directory and holds the ambient registry a boot runs under.
   module Runtime
     class << self
-      # The registry declarations are currently landing in, or nil outside a
-      # boot. Read by the DSL collectors on the top-level module and by the
-      # extraction port.
+      # The registry declarations are currently landing in, or nil outside a boot.
       attr_reader :current_registry
 
-      # Load a bluebook directory and return the Dispatcher bound to it.
-      # `install_facade:`, `environment:` — see Loader.boot.
+      # Loads a bluebook directory and returns the Dispatcher bound to it. See Loader.boot.
+      #
+      #   Hecks::Runtime.boot("examples/pizzas/bluebook")
+      #     .dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
       #
       # @param path [String] path to a domain directory, or a file inside one
-      # @param shared [String, nil] a shared-root override; see `Loader.boot`
-      # @param install_facade [Boolean] whether to install the `Widget::Item.Add`-style
-      #   Ruby facade constants for this boot
-      # @param environment [String, nil] the environment name passed through to
-      #   `Adapters::Folder#load_domain`
+      # @param shared [String, nil] a shared-root override
+      # @param install_doors [Boolean] whether to install the Ruby facade constants
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
+      # @param environment [String, nil] the environment name for `Adapters::Folder#load_domain`
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot(path, shared: nil, install_facade: true, environment: nil)
-        Loader.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+      def boot(path, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.boot(path, shared: shared, install_doors: install_doors, environment: environment,
+          install_facade: install_facade)
       end
 
-      # `paths` form — see Loader.boot_files.
+      # Loads a domain's declarations without binding any adapter. See Loader.describe.
+      #
+      # @param path [String] path to a domain directory, or a file inside one
+      # @param shared [String, nil] a shared-root override
+      # @param environment [String, nil] the environment overlay; defaults to `HECKS_ENVIRONMENT`
+      # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
+      def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.describe(path, shared: shared, environment: environment)
+      end
+
+      # Loads only the given files of a domain; otherwise like `boot`. See Loader.boot_files.
       #
       # @param paths [String, Array<String>] one or more file paths within the domain
-      #   to load, instead of the whole directory
-      # @param shared [String, nil] a shared-root override; see `Loader.boot_files`
-      # @param install_facade [Boolean] whether to install the `Widget::Item.Add`-style
-      #   Ruby facade constants for this boot
-      # @param environment [String, nil] the environment name passed through to the
-      #   selected-file loader
+      # @param shared [String, nil] a shared-root override
+      # @param install_doors [Boolean] whether to install the Ruby facade constants
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
+      # @param environment [String, nil] the environment name for the selected-file loader
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot_files(paths, shared: nil, install_facade: true, environment: nil)
-        Loader.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+      def boot_files(paths, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.boot_files(paths, shared: shared, install_doors: install_doors, environment: environment,
+          install_facade: install_facade)
       end
 
       # Bind the ambient registry for the duration of the block, restoring
@@ -110,23 +90,9 @@ module Hecks
         @current_registry = previous
       end
 
-      # Bind the ambient caller (see Runtime::Caller) for the duration of
-      # the block — who a command's declared `role`, if any, is checked
-      # against.
-      #
-      # `as_of:` is optional, same opt-in shape as `actor_id:` — a caller
-      # that wants a Governance `RoleAssignment`'s `starts_at` enforced
-      # passes `as_of: Ports::Clock.now(registry)` here, at the door,
-      # exactly where `cli_runner.rb` already merges `Clock.now` into a
-      # command's own args. Nothing on the dispatch path calls the clock
-      # itself — see `Ports::Clock`'s own header for why — so an unbound
-      # `as_of` leaves `starts_at` unchecked, exactly as before.
+      # Binds the ambient caller (see Runtime::Caller) for the duration of the block.
+      # A command's declared `role` is checked against it.
       #
-      # `scope:` is optional too — a caller that states which scope it is
-      # acting in gets that scope checked against the matching
-      # `RoleAssignment`'s own `scope`, not just its `role_name`. See
-      # `Runtime::Caller::Current`'s own header for why this lives here
-      # rather than as a command-level DSL construct.
       # @param role [String, Symbol] the role to check the caller against
       # @param actor_id [String, nil] who is calling, checked against a real Governance
       #   `RoleAssignment` when given; string-equality only against `role` when nil

data/lib/hecks/rust_build/conformance.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require_relative "../rust_build"
+require_relative "native_build"
+
+module Hecks
+  module RustBuild
+    # The differential harness (ADR 0010): replays a corpus script through the Ruby interpreter
+    # (`Fuzzing::Replay`) and prints or diffs the JSON surface a Rust artifact must reproduce.
+    #
+    # With no artifact it prints Ruby's result as JSON, which saved to a file becomes a pinned
+    # expectation. The artifact is another artifact's JSON file, `native` (the workspace's
+    # `target/{release,debug}/rust`), a `.wasm` path (run under `wasmtime`), an executable path,
+    # or `build` (the domain's own Cargo feature, built and run); a live one gets the script on
+    # stdin. `HECKS_RUST_DIR` names the workspace and `CARGO_TARGET_DIR` where its output went.
+    module Conformance
+      USAGE = "usage: hecks check_conformance <domain> <script.json> " \
+              "[rust_output.json | native | build | path/to/binary | path/to/module.wasm]"
+
+      # The refusal kinds are not compared for ad-hoc filter steps: C8.3
+      # (docs/semantics/bluebook-semantics.md) is open (RuntimeError in Ruby, TypeMismatch in
+      # Rust), and only the message is byte-exact.
+      FILTER_VERB = "filter "
+
+      module_function
+
+      # @param argv [Array<String>] the domain, the script and optionally the artifact
+      # @return [Integer] 0 when the result is printed or matches, 1 on a mismatch
+      # @raise [Failure] when the artifact cannot be run
+      def call(argv)
+        require_relative "../../hecks"
+        require_relative "../fuzzing"
+        domain, script, other = argv
+        raise Failure, USAGE unless domain && script
+
+        ours = comparable(Hecks::Fuzzing::Replay.call(domain, JSON.parse(File.read(script)).fetch("steps")))
+        return print_result(ours) unless other
+
+        theirs = normalize(JSON.parse(artifact_output(domain, script, other)))
+        report(domain, script, ours, theirs)
+      end
+
+      def print_result(result)
+        puts JSON.pretty_generate(result)
+        0
+      end
+
+      # @param result [Hash] `Fuzzing::Replay`'s answer
+      # @return [Hash{String => Object}] the surface a Rust artifact must reproduce
+      def comparable(result)
+        surface = {
+          "instances" => result[:instances].transform_values { |state| JSON.parse(JSON.generate(state)) },
+          "events"    => result[:events].map { |event| event_surface(event) },
+          "refusals"  => result[:refusals].map do |refusal|
+            { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
+          end
+        }
+        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
+        dry_runs = result[:dry_runs].map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
+        surface["dry_runs"] = dry_runs unless dry_runs.empty?
+        surface
+      end
+
+      def event_surface(event)
+        { "name" => event[:name], "aggregate" => event[:aggregate], "id" => event[:id].to_s,
+          "payload" => JSON.parse(JSON.generate(event[:payload])) }
+      end
+
+      # The artifact's JSON for the script: live from a binary, or read from a file.
+      def artifact_output(domain, script, other)
+        case other
+        when "native" then run_binary(native_binary || missing_native!, script)
+        when "build" then run_binary(built_binary(domain), script)
+        when /\.wasm\z/
+          raise Failure, "#{other}: no such file — run hecks build_wasm #{domain} first" unless File.exist?(other)
+
+          run_process(["wasmtime", "run", other], File.read(script))
+        when ->(path) { !path.end_with?(".json") && File.file?(path) && File.executable?(path) }
+          # A pinned per-domain binary, as named by a sweep's `replay:` line.
+          run_binary(other, script)
+        else File.read(other)
+        end
+      end
+
+      def run_binary(binary, script) = run_process([binary], File.read(script))
+
+      def run_process(command, stdin_data)
+        stdout, status = Open3.capture2(*command, stdin_data: stdin_data)
+        raise Failure, "#{command.join(' ')} exited #{status.exitstatus}:\n#{stdout}" unless status.success?
+
+        stdout
+      end
+
+      def target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
+
+      def native_binary
+        %w[release debug].map { |profile| File.join(target_dir, profile, "rust") }.find { |path| File.executable?(path) }
+      end
+
+      def missing_native!
+        raise Failure, "no native rust binary found under rust/target/{release,debug}/rust — run " \
+                       "`cd rust && cargo build` first"
+      end
+
+      # Built on demand because `native` runs whichever domain the crate's default feature names.
+      def built_binary(domain)
+        feature = File.basename(domain.chomp("/"))
+        NativeBuild.build_rust_for(feature, RustBuild.rust_dir) or
+          raise Failure, "no `#{feature}` feature in rust/Cargo.toml — run hecks project_rust #{domain} first"
+      end
+
+      # Strips what a Rust run carries that Ruby has no analog for: `emitted_*` snapshot flags
+      # (ADR 0048) and the wall-clock `occurred_at` stamp two runs can never match.
+      def normalize(theirs)
+        if theirs["instances"].is_a?(Hash)
+          theirs["instances"].each_value do |record|
+            record.reject! { |key, _| key.start_with?("emitted_") } if record.is_a?(Hash)
+          end
+        end
+        theirs["events"].each { |event| event.delete("occurred_at") if event.is_a?(Hash) } if theirs["events"].is_a?(Array)
+        theirs
+      end
+
+      def report(domain, script, ours, theirs)
+        [ours, theirs].each { |side| drop_filter_kinds(side) }
+        mismatches = mismatches(ours, theirs)
+        if mismatches.empty?
+          puts "#{domain} / #{script}: matches."
+          return 0
+        end
+
+        warn "#{domain} / #{script}: #{mismatches.size} mismatch(es)\n\n#{mismatches.join("\n\n")}"
+        1
+      end
+
+      def drop_filter_kinds(side)
+        return unless side["refusals"].is_a?(Array)
+
+        side["refusals"].each { |r| r.delete("kind") if r.is_a?(Hash) && r["verb"].to_s.start_with?(FILTER_VERB) }
+      end
+
+      def mismatches(ours, theirs)
+        found = %w[instances events refusals].filter_map do |key|
+          next if ours[key] == theirs[key]
+
+          "#{key}:\n  ruby:  #{ours[key].inspect}\n  other: #{theirs[key].inspect}"
+        end
+        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
+        if (ours["dry_runs"] || []) != their_dry_runs
+          found << "dry_runs:\n  ruby:  #{ours['dry_runs'].inspect}\n  other: #{their_dry_runs.inspect}"
+        end
+        found
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/conformance_fuzz.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require_relative "../cache_dir"
+require_relative "../rust_build"
+require_relative "conformance"
+
+module Hecks
+  module RustBuild
+    # Runs generated fuzz sequences through `Conformance` against a native or `.wasm` artifact
+    # (ADR 0039), stopping at the first diverging seed with a reproduction command.
+    #
+    #   ConformanceFuzz.call([domain, "native" | "path/to/module.wasm", seeds, steps])
+    #
+    # `seeds` and `steps` default to `SEEDS` and `STEPS` in the environment, then to 10 and 25.
+    module ConformanceFuzz
+      USAGE = "usage: hecks fuzz_conformance <domain> <native|path/to/module.wasm> [seeds] [steps]"
+
+      # What a domain directory's basename may be: a plain identifier, never `.` or `..`.
+      DOMAIN_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
+
+      module_function
+
+      # @param argv [Array<String>] the domain, the artifact, and optionally seeds and steps
+      # @return [Integer] 0 when every sequence matched
+      # @raise [Failure] at the first seed that diverges, naming how to reproduce it
+      def call(argv)
+        require_relative "../../hecks"
+        require_relative "../fuzzing"
+        domain, artifact, seeds, steps = argv
+        raise Failure, USAGE unless domain && artifact
+
+        seeds = Integer(seeds || ENV["SEEDS"] || 10)
+        steps = Integer(steps || ENV["STEPS"] || 25)
+        scratch = scratch_dir(domain)
+        (1..seeds).each { |seed| replay(domain, artifact, seed, seeds, steps, scratch) }
+        FileUtils.rm_rf(scratch)
+        puts "#{domain}: #{seeds} generated sequence(s) x #{steps} step(s) each, all matched #{artifact}."
+        0
+      end
+
+      # A fresh directory per run, under the cache root outside the gem, so concurrent runs never
+      # share one; it is kept when a seed diverges, so the failing script outlives the run.
+      #
+      # @param domain [String] the domain's directory; its basename names the scratch directory
+      # @return [String] the new directory
+      # @raise [Failure] when the basename cannot safely name a directory
+      def scratch_dir(domain)
+        name = File.basename(domain.to_s.chomp("/"))
+        raise Failure, "#{USAGE}\n`#{domain}` is not a domain directory name" unless name.match?(DOMAIN_NAME)
+
+        parent = Hecks::CacheDir.path("rust_conformance_fuzz")
+        FileUtils.mkdir_p(parent)
+        Dir.mktmpdir("#{name}-", parent)
+      end
+
+      def replay(domain, artifact, seed, seeds, steps, scratch)
+        sequence = Hecks::Fuzzing::SequenceGenerator.generate(domain, seed: seed, steps: steps)
+        path = File.join(scratch, "seed-#{seed}.json")
+        File.write(path, JSON.generate({ "steps" => sequence }))
+        return if Conformance.call([domain, path, artifact]).zero?
+
+        raise Failure, "hecks fuzz_conformance: seed #{seed}/#{seeds} diverged against #{artifact} " \
+                       "(see the conformance output above) — " \
+                       "reproduce with: hecks check_conformance #{domain} #{path} #{artifact}"
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/coverage.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # Reports whether each construct in a domain's IR has a real, routed implementation under
+    # `<workspace>/src/generated/<domain>` (ADR 0054a).
+    #
+    #   Coverage.call([domain, "--codegen=ruby|rust"])
+    #   Coverage.call(["--check-allowlist"])
+    #
+    # Ground truth is the generated module's `ir.json` and its `manifest.json`; a construct in the
+    # IR that the manifest omits is a synthetic `unaccounted` finding. The exit status is 1 when a
+    # gap remains that the allowlist does not excuse.
+    module Coverage
+      USAGE = "usage: hecks rust_coverage <generated-module-name> [--codegen=ruby|rust]  " \
+              "(e.g. pizzas, banking, governance, identity)\n       hecks rust_coverage --check-allowlist"
+
+      # Deliberate, documented gaps only, matched by kind, gap class and construct (never a regex
+      # over `reason` prose). The list only shrinks: `--check-allowlist` fails once a rule excuses
+      # no gap anywhere.
+      ALLOWLIST = [].freeze
+
+      module_function
+
+      # @param argv [Array<String>] the generated module's name and optional `--codegen=` flag,
+      #   or `--check-allowlist`
+      # @return [Integer] 0 when nothing is a gap, 1 otherwise
+      # @raise [Failure] when the module, its `ir.json` or its manifest is missing
+      def call(argv)
+        flags, positional = argv.partition { |arg| arg.start_with?("--codegen") }
+        codegen = flags.empty? ? "ruby" : flags.last.delete_prefix("--codegen=")
+        raise Failure, "--codegen must be `ruby` or `rust` (got #{flags.last.inspect})" unless %w[ruby rust].include?(codegen)
+
+        target = positional.first or raise Failure, USAGE
+        return check_allowlist if target == "--check-allowlist"
+
+        report(target, codegen)
+      end
+
+      def rust_dir = RustBuild.rust_dir
+
+      def generated_root = File.join(rust_dir, "src/generated")
+
+      # Entity-scoped query ids at any depth (`Domain::Aggregate.Entity.Query`); mirrors the
+      # generator's own entity query entries.
+      def entity_query_ids(owner_id, entities)
+        entities.flat_map do |entity|
+          entity_id = "#{owner_id}.#{entity.fetch(:name)}"
+          entity.fetch(:queries, []).map { |q| "#{entity_id}.#{q.fetch(:name)}" } +
+            entity_query_ids(entity_id, entity.fetch(:entities, []))
+        end
+      end
+
+      # The [kind, id] pairs the IR implies, independent of the manifest.
+      def expected_from_ir(payload)
+        domain_name = payload.fetch(:name)
+        expected = payload.fetch(:aggregates).flat_map { |aggregate| aggregate_constructs(domain_name, aggregate) }
+        payload.fetch(:read_models).each { |rm| expected << [:read_model, "#{domain_name}::#{rm.fetch(:name)}"] }
+        payload.fetch(:policies).each { |p| expected << [:policy, "#{domain_name}::#{p.fetch(:name)}"] }
+        payload.fetch(:process_managers).each { |pm| expected << [:process_manager, "#{domain_name}::#{pm.fetch(:name)}"] }
+        # An `ir.json` from before the `lineage` key existed has none: nothing to expect.
+        payload.fetch(:lineage, {}).fetch(:capable_aggregates, []).each do |aggregate|
+          expected << [:lineage_aggregate, "#{domain_name}::#{aggregate.fetch(:name)}"]
+        end
+        expected
+      end
+
+      def aggregate_constructs(domain_name, aggregate)
+        id = "#{domain_name}::#{aggregate.fetch(:name)}"
+        found = [[:aggregate, id]]
+        aggregate.fetch(:commands).each { |c| found << [:command, "#{id}.#{c.fetch(:name)}"] }
+        aggregate.fetch(:queries).each { |q| found << [:query, "#{id}.#{q.fetch(:name)}"] }
+        entity_query_ids(id, aggregate.fetch(:entities)).each { |query_id| found << [:query, query_id] }
+        aggregate.fetch(:entities).each do |entity|
+          entity_id = "#{id}.#{entity.fetch(:name)}"
+          found << [:entity, entity_id]
+          entity.fetch(:commands).each { |c| found << [:entity_command, "#{entity_id}.#{c.fetch(:name)}"] }
+        end
+        aggregate.fetch(:ports).each do |port|
+          port.fetch(:operations).each { |op| found << [:port_operation, "#{id}.#{port.fetch(:name)}.#{op.fetch(:name)}"] }
+        end
+        found
+      end
+
+      # Parses a generated module's `ir.json` and `manifest.json`, adding a synthetic `unaccounted`
+      # finding for any IR construct the manifest omits.
+      def coverage_findings(mod_dir)
+        ir_path = File.join(mod_dir, "ir.json")
+        File.exist?(ir_path) or raise Failure, "#{ir_path}: missing — this generated tree predates ir.json " \
+                                               "(hecks project_rust writes it now); re-run hecks project_rust for this domain"
+        ir = JSON.parse(File.read(ir_path), symbolize_names: true)
+        manifest_path = File.join(mod_dir, "manifest.json")
+        File.exist?(manifest_path) or raise Failure, "#{manifest_path}: missing — re-run hecks project_rust for this " \
+                                                     "domain to write it"
+        manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)
+        [ir, manifest + unaccounted_findings(ir, manifest)]
+      end
+
+      def allowlist_rule_matches?(rule, finding)
+        rule[:kind] == finding[:kind].to_s &&
+          rule[:gap_class] == finding[:gap_class].to_s &&
+          rule[:construct] == finding[:construct].to_s
+      end
+
+      def allowlisted(finding) = ALLOWLIST.find { |rule| allowlist_rule_matches?(rule, finding) }
+
+      # A synthetic finding for each expected construct with no manifest entry at all: a gap in
+      # the manifest writer itself.
+      def unaccounted_findings(payload, manifest)
+        ids = Hash.new { |hash, kind| hash[kind] = Set.new }
+        manifest.each { |entry| ids[entry[:kind].to_sym] << entry[:id] }
+        expected_from_ir(payload).reject { |kind, id| ids[kind].include?(id) }.map do |kind, id|
+          { kind: kind.to_s, id: id, generated: false, gap_class: "unaccounted", construct: "unaccounted",
+            reason: "expected per ir.json, but manifest.json has NO entry for it at all — not even a " \
+                    "recorded skip; the generator's own accounting missed this construct entirely" }
+        end
+      end
+
+      # A real functional gap: not generated, or generated but unrouted.
+      def functional_gap?(finding) = finding[:generated] == false || finding[:routed] == false
+
+      # Every rule must still excuse a real gap somewhere under `src/generated/`.
+      def check_allowlist
+        gaps = Dir.glob(File.join(generated_root, "*/ir.json")).flat_map do |ir_path|
+          coverage_findings(File.dirname(ir_path))[1].select { |finding| functional_gap?(finding) }
+        end
+        stale = ALLOWLIST.reject { |rule| gaps.any? { |finding| allowlist_rule_matches?(rule, finding) } }
+        if stale.empty?
+          puts "hecks rust_coverage --check-allowlist: all #{ALLOWLIST.size} rules still excuse a real gap"
+          return 0
+        end
+        stale.each do |rule|
+          warn "STALE ALLOWLIST RULE: #{rule.slice(:kind, :gap_class, :construct)} matches no gap in any generated " \
+               "module — the gap it excused is gone; delete the rule"
+        end
+        1
+      end
+
+      def report(domain, codegen)
+        mod_dir = File.join(generated_root, domain)
+        Dir.exist?(mod_dir) or raise Failure, "#{mod_dir}: no such generated module — run hecks project_rust first, " \
+                                              "or check rust/src/generated/ for the actual directory name"
+        return print_report(domain, mod_dir) unless codegen == "rust"
+
+        Dir.mktmpdir("rust-coverage-codegen-") do |scratch|
+          print_report(domain, regenerated(mod_dir, domain, scratch))
+        end
+      end
+
+      # Regenerates the domain's manifest through `hecks-codegen` into a scratch directory. `cargo
+      # run` rather than a fixed target path, so `CARGO_TARGET_DIR` and rust-toolchain.toml apply.
+      def regenerated(mod_dir, domain, scratch)
+        ir_path = File.join(mod_dir, "ir.json")
+        File.exist?(File.join(mod_dir, "manifest.json")) or raise Failure, "#{mod_dir}: no committed manifest.json — " \
+                                                                           "re-run hecks project_rust for this domain to write it"
+        out_dir = File.join(scratch, domain)
+        output, status = Open3.capture2e("cargo", "run", "--quiet", "--", "domain", ir_path, domain, domain, out_dir,
+                                         chdir: File.join(rust_dir, "codegen"))
+        status.success? or raise Failure, "hecks-codegen domain failed for #{domain}:\n#{output}"
+        # `hecks-codegen domain` writes no ir.json sidecar; the cross-check reads the committed IR
+        # the generator was just handed.
+        FileUtils.cp(ir_path, File.join(out_dir, "ir.json"))
+        out_dir
+      end
+
+      def print_report(domain, mod_dir)
+        ir, findings = coverage_findings(mod_dir)
+        # A construct is implemented only when generated and routed (where routing applies): a
+        # `dispatch_*` that compiles but nothing can call is not working.
+        implemented, remainder = findings.partition { |f| f[:generated] && f[:routed] != false }
+        deferred, gap = remainder.partition { |f| allowlisted(f) }
+        puts "=" * 72
+        puts "hecks rust_coverage #{domain}  (source: manifest.json)"
+        puts "=" * 72
+        puts "#{ir.fetch(:name)} — #{findings.size} constructs accounted for " \
+             "(#{implemented.size} implemented, #{deferred.size} deferred, #{gap.size} GAP)"
+        print_bucket("IMPLEMENTED", implemented) unless implemented.empty?
+        print_deferred(deferred)
+        print_gaps(gap)
+        puts
+        gap.empty? ? 0 : 1
+      end
+
+      def print_bucket(label, entries)
+        puts "\n#{label} (#{entries.size})"
+        sorted(entries).each { |entry| print_entry(entry) }
+      end
+
+      def print_deferred(deferred)
+        puts "\nDEFERRED (#{deferred.size}) — on the allowlist, with its cited reason"
+        sorted(deferred).each do |entry|
+          puts "  [#{entry[:kind]}] #{entry[:id]}"
+          puts "      allowlist: #{allowlisted(entry)[:doc]}"
+        end
+      end
+
+      def print_gaps(gap)
+        puts "\nGAP (#{gap.size}) — missing, and NOT on the allowlist: a real, actionable finding"
+        sorted(gap).each { |entry| print_entry(entry) }
+      end
+
+      def print_entry(entry)
+        line = "  [#{entry[:kind]}] #{entry[:id]}"
+        line += " (#{entry[:gap_class]})" if entry[:gap_class]
+        puts line
+        puts "      #{entry[:reason]}" if entry[:reason]
+      end
+
+      def sorted(entries) = entries.sort_by { |entry| [entry[:kind].to_s, entry[:id]] }
+    end
+  end
+end