hecks 3.10.0 → 3.12.0

data/lib/hecks/rust_build.rb

@@ -83,6 +83,17 @@ module Hecks
         raise Failure, "`#{command.join(" ")}` failed#{" in #{chdir}" if chdir}"
       end
 
+      # Asks rustup whether a compile target is installed for the active toolchain.
+      #
+      # @param target [String] the target triple, such as `wasm32-unknown-unknown`
+      # @return [Boolean] false when rustup is missing or does not list the target
+      def target_installed?(target)
+        listed = IO.popen(["rustup", "target", "list", "--installed", { err: File::NULL }], &:read)
+        listed.split("\n").include?(target)
+      rescue SystemCallError
+        false
+      end
+
       # Runs a tool and holds what it printed.
       #
       # @param tool [String] a key of `TOOLS`

data/lib/hecks/served_options.rb

@@ -0,0 +1,53 @@
+require "rack"
+
+module Hecks
+  # What a domain's world file says it is served by: each `served_by("Adapter") { ... }` line
+  # names an inbound adapter and the per-environment values it needs. The route is derived,
+  # never written: a driving adapter answers at `/webhooks/<adapter name, snake-cased>` unless
+  # its `path` says otherwise, so a world holds only what the domain cannot know (secret,
+  # path override) and the same domain can be served differently in each environment.
+  #
+  # A secret is named by the environment variable that holds it, never inline.
+  module ServedOptions
+    VERB = "served_by".freeze
+
+    module_function
+
+    # @param world [Bluebook::World, nil] a domain's judged world
+    # @return [Array<Hash>] one entry per `served_by` line: `adapter`, `path` and its settings
+    def entries(world)
+      return [] unless world
+
+      world.settings.filter_map do |key, values|
+        next unless key.to_s.start_with?("#{VERB}:")
+
+        adapter = values.fetch(:adapter)
+        values.merge(adapter: adapter, path: values.fetch(:path) { "/webhooks/#{snake(adapter)}" })
+      end
+    end
+
+    # A Rack app mounting every `served_by` adapter the world names at its derived path.
+    #
+    # @param world [Bluebook::World, nil]
+    # @param adapters [Hash{String => Class}] driving adapter classes by the name a world uses;
+    #   each is built with `secret:` read from the environment variable the line names
+    # @param env [#fetch] where secrets are read from (`ENV` in production)
+    # @return [Rack::URLMap]
+    # @raise [KeyError] when a line names an adapter no class answers for
+    # @raise [ArgumentError] when a line names a secret variable the environment does not hold
+    def rack_app(world, adapters:, env: ENV)
+      routes = entries(world).to_h do |entry|
+        klass = adapters.fetch(entry[:adapter])
+        [entry[:path], klass.new(secret: secret_for(entry, env))]
+      end
+      Rack::URLMap.new(routes)
+    end
+
+    def secret_for(entry, env)
+      name = entry.fetch(:secret) { raise ArgumentError, "#{entry[:adapter]} names no secret" }
+      env.fetch(name) { raise ArgumentError, "#{entry[:adapter]}: environment variable #{name} is not set" }
+    end
+
+    def snake(name) = name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+  end
+end

data/lib/hecks/site/bluebook/site.bluebook

@@ -167,6 +167,7 @@ Hecks.bluebook "Site" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Complete" => "projected", from: "requested"
       transition "Fault"    => "faulted",   from: "requested"
     end

data/lib/hecks/storehouse/audit.rb

@@ -33,7 +33,7 @@ module Hecks
       end
 
       # Tails this bus's own dispatch/query/state audit log — a pull-based
-      # substitute for a push subscription, since a stdio door answers one
+      # substitute for a push subscription, since a stdio server answers one
       # request at a time with no channel to push through.
       #
       # @param runtime [Runtime::Registry] the booted domain to tail

data/lib/hecks/storehouse/dispatching.rb

@@ -34,9 +34,9 @@ module Hecks
 
       # :nodoc:
       def command_envelope(args, spec)
-        Doors::CommandRequest.normalize(Doors::JsonDoor.deep_symbolize(args),
-                                        receiver:        spec[:receiver],
-                                        legacy_receiver: spec[:legacy_receiver])
+        Adapters::Driving::CommandRequest.normalize(Adapters::Driving::Json.deep_symbolize(args),
+                                                    receiver:        spec[:receiver],
+                                                    legacy_receiver: spec[:legacy_receiver])
       end
 
       # :nodoc:
@@ -52,7 +52,9 @@ module Hecks
         ok(summary: summary,
            id:      result.id,
            state:   settled_state(runtime, spec, result),
-           events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
+           events:  result.events.map do |event|
+             { name: event.name, payload: Adapters::Driving::Json.materialize(event.payload) }
+           end)
       end
 
       # The record as its repository holds it once every reaction has run, which is the state the
@@ -65,7 +67,7 @@ module Hecks
       def settled_state(runtime, spec, result)
         return if result.state.nil?
 
-        Doors::JsonDoor.materialize(settled_record(runtime, spec, result) || result.state)
+        Adapters::Driving::Json.materialize(settled_record(runtime, spec, result) || result.state)
       end
 
       # :nodoc:
@@ -141,7 +143,7 @@ module Hecks
 
       # :nodoc:
       def batch_step(runtime, raw, summary, options)
-        step = Doors::JsonDoor.deep_symbolize(raw)
+        step = Adapters::Driving::Json.deep_symbolize(raw)
         dispatch(runtime: runtime, command: step[:command], args: step[:args] || {}, summary: summary, **options)
       end
     end

data/lib/hecks/storehouse/introspection.rb

@@ -68,7 +68,7 @@ module Hecks
       # @return [Hash] {ok: true, domain:, valid: true} plus :findings when deep;
       #   {ok: false, domain:, valid: false, error:} if the boot itself failed
       def validate(domain:, deep: false)
-        runtime = Hecks.boot(confine!(domain, "domain"), install_doors: false)
+        runtime = Hecks.boot(confine!(domain, "domain"), install_driving: false)
         result  = { ok: true, domain: domain, valid: true }
         result[:findings] = model_findings(runtime) if deep
         result
@@ -103,7 +103,7 @@ module Hecks
 
       # :nodoc:
       def journal_entries(repository)
-        repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Doors::JsonDoor.materialize(entry.state) } }
+        repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Adapters::Driving::Json.materialize(entry.state) } }
       end
 
       # Runs a domain's hand-curated .behaviors examples and reports the results.

data/lib/hecks/storehouse/querying.rb

@@ -27,12 +27,14 @@ module Hecks
         spec = resolve!(cli_for(request.bluebook), request.name, asking: true)
         rows = with_caller(request.role, request.actor_id) { answer(request, spec) }
 
-        ok(summary: request.summary, rows: rows.map { |row| Doors::JsonDoor.materialize(row) }).merge(verb: spec[:command])
+        ok(summary: request.summary, rows: rows.map do |row|
+          Adapters::Driving::Json.materialize(row)
+        end).merge(verb: spec[:command])
       end
 
       # :nodoc:
       def answer(request, spec)
-        request.runtime.query(spec[:command], **Doors::JsonDoor.deep_symbolize(request.args))
+        request.runtime.query(spec[:command], **Adapters::Driving::Json.deep_symbolize(request.args))
       end
 
       # Reads one aggregate's stored records directly, bypassing any declared
@@ -63,7 +65,7 @@ module Hecks
         repository = runtime.registry.repository(bluebook.name, ir)
         return ok(summary: summary, record: single_record(repository, ir, id)) if id
 
-        records = repository.all.map { |instance| Doors::JsonDoor.materialize(instance.to_h) }
+        records = repository.all.map { |instance| Adapters::Driving::Json.materialize(instance.to_h) }
         ok(summary: summary, count: records.length, records: records)
       end
 
@@ -71,7 +73,7 @@ module Hecks
       def single_record(repository, aggregate_ir, identity)
         instance = repository.find(identity) or
           raise Runtime::NotFound, "no #{aggregate_ir.hecks_name} found for id #{identity.inspect}"
-        Doors::JsonDoor.materialize(instance.to_h)
+        Adapters::Driving::Json.materialize(instance.to_h)
       end
     end
   end

data/lib/hecks/storehouse.rb

@@ -3,8 +3,8 @@ require "json"
 require "fileutils"
 require "time"
 require_relative "cache_dir"
-require_relative "doors/command_request"
-require_relative "doors/json_door"
+require_relative "adapters/driving/command_request"
+require_relative "adapters/driving/json"
 require_relative "naming"
 require_relative "projector"
 require_relative "runtime/errors"
@@ -55,7 +55,7 @@ module Hecks
             "own root (HECKS_STOREHOUSE_ROOT to widen it)"
     end
 
-    # The one bluebook this runtime booted; every whole-domain door assumes
+    # The one bluebook this runtime booted; every whole-domain entry point assumes
     # the same one-bluebook-per-boot shape.
     # :nodoc:
     def bluebook_for(runtime)
@@ -137,7 +137,7 @@ module Hecks
     def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id)
 
     # dry_run? (Runtime::Dispatcher) only understands the pre-envelope flat
-    # args shape; this is the one door back into it from dispatch's own envelope.
+    # args shape; this is the one entry point back into it from dispatch's own envelope.
     # :nodoc:
     def flatten_legacy(envelope, receiver, legacy_receiver)
       facts = envelope[:with] || {}

data/lib/hecks/tools/ci_gate_decision.rb

@@ -5,6 +5,7 @@ require "open3"
 require "hecks/vocabulary"
 require_relative "../tools"
 require_relative "ci_gates"
+require_relative "release_only"
 
 module Hecks
   module Tools
@@ -43,6 +44,8 @@ module Hecks
       # @param env [Hash{String => String}] the runner's environment
       # @return [Boolean] whether the gated job should run
       def touched?(gate, root:, env:)
+        return !inherits?(gate, root: root, env: env) if gate.fetch("mode") == "release_only"
+
         changed, reason = change_set(gate, root: root, env: env)
         if reason
           explain(gate, reason)
@@ -54,6 +57,38 @@ module Hecks
         gate.fetch("mode") == "touches" ? matches.any? : matches.any?(false)
       end
 
+      # Whether the change is only a release bump on a base whose required checks all passed, so
+      # the run may inherit the base's certification (`ReleaseOnly`). Anything unconfirmed answers
+      # false and the suite runs.
+      #
+      # @param gate [Hash{String => String}] the `CiGate` row
+      # @return [Boolean]
+      def inherits?(gate, root:, env:)
+        base = base_of(gate, root: root, env: env)
+        reason = inheritance_refusal(base, root: root, env: env)
+        warn "decide_ci_gate: #{reason}: running the suite rather than inheriting certification" if reason
+        reason.nil?
+      end
+
+      # @return [String, nil] why the change cannot inherit, nil when it can
+      def inheritance_refusal(base, root:, env:)
+        return "no usable base to diff against" if base.nil? || base.empty? || base == NO_COMMIT
+
+        changes = ReleaseOnly.changes(base, env.fetch("GITHUB_SHA", "HEAD"), root: root)
+        return "git diff itself failed" if changes.nil?
+        return "the change is not only release files and lines" unless ReleaseOnly.release_only?(changes)
+
+        base_refusal(base, env)
+      end
+
+      # @return [String, nil] why the base is not certified, nil when it is
+      def base_refusal(base, env)
+        runs = ReleaseOnly.check_runs(env.fetch("GITHUB_REPOSITORY", ""), base, env: env)
+        return "the base's check runs could not be read" if runs.nil?
+
+        "the base is not fully certified" unless ReleaseOnly.certified?(runs)
+      end
+
       # @return [Array(Array<String>, nil), Array(nil, String)] the changed paths, or the reason the
       #   change cannot be confirmed
       def change_set(gate, root:, env:)

data/lib/hecks/tools/ci_gates.rb

@@ -46,7 +46,7 @@ module Hecks
 
       # The values a row's `mode` and `push` may take: the language holds one closed set to a value
       # object, so the rest are held here.
-      MODES = %w[touches skips_unless].freeze
+      MODES = %w[touches skips_unless release_only].freeze
       PUSHES = %w[skip before_sha].freeze
 
       # @return [Array<Hash{String => String}>] the `CiGate` rows
@@ -111,16 +111,35 @@ module Hecks
          "  #{name}:",
          "    runs-on: ubuntu-latest",
          "    timeout-minutes: 10",
+         *job_permissions(gate),
          *job_condition(gate)]
       end
 
       # @return [Array<String>] the deciding step and the closing marker
       def job_footer(gate, name)
         ["        name: #{quoted(gate.fetch("label"))}",
+         *job_env(gate),
          "        run: bundle exec exe/hecks regeneration_run.decide_ci_gate gate=#{name} --wait",
          "  # END GENERATED ci_gate #{name}"]
       end
 
+      # A `release_only` gate reads the base commit's check runs through the API, so its job may
+      # read checks and nothing more.
+      #
+      # @return [Array<String>] the job's `permissions:` lines, none for any other mode
+      def job_permissions(gate)
+        return [] unless gate.fetch("mode") == "release_only"
+
+        ["    permissions:", "      contents: read", "      checks: read"]
+      end
+
+      # @return [Array<String>] the deciding step's `env:` lines, none unless the gate calls the API
+      def job_env(gate)
+        return [] unless gate.fetch("mode") == "release_only"
+
+        ["        env:", "          GH_TOKEN: ${{ github.token }}"]
+      end
+
       # @param gate [Hash{String => String}] a `CiGate` row
       # @return [Array<String>] the job-level `if:` lines for a gate that skips push runs
       def job_condition(gate)

data/lib/hecks/tools/comment_style/source_file.rb

@@ -14,6 +14,9 @@ module Hecks
     module CommentStyle
       # One parsed source file and the violations found in it.
       class SourceFile
+        # Raised when an automatic fix would change code rather than comments.
+        class Error < RuntimeError; end
+
         include LongBlocks
         include Masking
         include CapsWords
@@ -51,7 +54,7 @@ module Hecks
           return @source if output == @source
 
           unchanged = CommentStyle.code_tokens(@source) == CommentStyle.code_tokens(output)
-          raise "#{path}: fix would change code, refusing" unless unchanged
+          raise Error, "#{path}: fix would change code, refusing" unless unchanged
 
           output
         end

data/lib/hecks/tools/deploy_recipe_lint/fixtures.rb

@@ -9,6 +9,9 @@ module Hecks
     module DeployRecipeLint
       # Generated fixture domains for the deploy generator, so the lint has real Makefiles to read.
       module Fixtures
+        # Raised when a deploy fixture cannot be generated.
+        class Error < RuntimeError; end
+
         # The fixture's bluebook, where `__NAME__` stands for the domain's name.
         FIXTURE_BLUEBOOK = <<~BLUEBOOK
           Hecks.bluebook "__NAME__" do
@@ -59,7 +62,7 @@ module Hecks
           Dir.mktmpdir do |dir|
             domain_dir = write_fixture(dir, basename, world_body, env_local: env_local)
             outcome = Hecks::Adapters::ConsoleCapture.capture { DeployRecipe.main([domain_dir], root: root) }
-            outcome.ok? or raise "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
+            outcome.ok? or raise Error, "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
           end
           File.join(root, "deploy", basename)
         end

data/lib/hecks/tools/lanes/files.rb

@@ -18,6 +18,7 @@ module Hecks
         def projection
           rulesets.merge(workflow(Lanes::WORKFLOW, "follows") { |lanes| Lanes.workflow(lanes) })
                   .merge(workflow(Lanes::WATCH_WORKFLOW, "alert_after") { |lanes| WatchWorkflow.text(lanes) })
+                  .merge(prebuilt)
         end
 
         # @param files [Hash{String => String}] the projection
@@ -44,6 +45,13 @@ module Hecks
           Lanes.rulesets.to_h { |name, ruleset| [ruleset_path(name), "#{JSON.pretty_generate(ruleset)}\n"] }
         end
 
+        # The workflow that publishes each `PrebuiltBinary` row.
+        def prebuilt
+          Hecks::Vocabulary.rows("PrebuiltBinary").to_h do |row|
+            [File.join(@root, PrebuiltWorkflow.path(row)), PrebuiltWorkflow.text(row)]
+          end
+        end
+
         # The workflow at `path` for the lanes whose `column` is set, or no file if none is.
         def workflow(path, column)
           lanes = Lanes.lanes.reject { |lane| lane[column].to_s.empty? }

data/lib/hecks/tools/lanes/prebuilt_workflow.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module Lanes
+      # The workflow that builds and publishes one `PrebuiltBinary` row (ADR 0110): after a push to
+      # `main` that touches the row's crate, it builds the binary on the row's runner and, unless
+      # a release for that key already exists, publishes it with its sha256. What the key is and
+      # where a client looks is `Hecks::RustBuild::PrebuiltBinary`, not anything written here.
+      module PrebuiltWorkflow
+        module_function
+
+        # @param row [Hash{String => String}] a `PrebuiltBinary` row
+        # @return [String] the path of the workflow, relative to the checkout
+        def path(row) = ".github/workflows/publish-#{row["name"]}.yml"
+
+        # @param row [Hash{String => String}] a `PrebuiltBinary` row
+        # @return [String] the workflow
+        def text(row)
+          [*header(row), *trigger(row), *job(row)].join("\n") << "\n"
+        end
+
+        def header(row)
+          name = row["name"]
+          ["name: Publish #{name}", "",
+           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary chapter. Do not hand-edit.",
+           "#",
+           "# Builds #{row["executable"]} from #{row["crate"]} for #{row["target"]} and publishes it as the release",
+           "# #{name}-<key>, where the key is a hash of the crate's build inputs. A client that needs the same",
+           "# bytes downloads it instead of compiling (Hecks::RustBuild::PrebuiltBinary); a key that already has a",
+           "# release is left alone, so a push that changed nothing the build reads publishes nothing."]
+        end
+
+        def trigger(row)
+          ["on:", "  push:", "    branches: [main]", "    paths:", "      - \"#{row["crate"]}/**\"",
+           "      - \".github/workflows/publish-#{row["name"]}.yml\"",
+           "      - \"lib/hecks/rust_build/prebuilt_binary.rb\"",
+           "  workflow_dispatch: {}", "",
+           "concurrency:", "  group: publish-#{row["name"]}", "  cancel-in-progress: false", "",
+           "permissions:", "  contents: write", ""]
+        end
+
+        def job(row)
+          ["jobs:", "  publish:", "    runs-on: #{row["runner"]}", "    timeout-minutes: 40", "    steps:",
+           "      - uses: actions/checkout@v4", "      - uses: ./.github/actions/setup-ruby", *key_step(row),
+           *build_steps(row), *release_step(row)]
+        end
+
+        def key_step(row)
+          ["      - name: Name the release", "        id: key", "        run: |",
+           "          key=$(bundle exec ruby -Ilib -rhecks/rust_build/prebuilt_binary -e \\",
+           "            'puts Hecks::RustBuild::PrebuiltBinary.key(ARGV.fetch(0))' #{row["crate"]})",
+           "          tag=#{row["name"]}-$key",
+           "          echo \"tag=$tag\" >> \"$GITHUB_OUTPUT\"",
+           "          if gh release view \"$tag\" > /dev/null 2>&1; then echo \"exists=true\" >> \"$GITHUB_OUTPUT\"; fi",
+           "        env:", "          GH_TOKEN: ${{ github.token }}"]
+        end
+
+        def build_steps(row)
+          ["      - name: Build #{row["executable"]}", "        if: steps.key.outputs.exists != 'true'",
+           "        working-directory: #{row["crate"]}", "        run: |",
+           "          rustup toolchain install stable --profile minimal",
+           "          rustup run stable cargo build --release --target #{row["target"]} --bin #{row["executable"]}"]
+        end
+
+        def release_step(row)
+          asset = "#{row["executable"]}-#{row["target"]}"
+          ["      - name: Publish the release", "        if: steps.key.outputs.exists != 'true'",
+           "        env:", "          GH_TOKEN: ${{ github.token }}", "          TAG: ${{ steps.key.outputs.tag }}",
+           "        run: |",
+           "          mkdir out",
+           "          cp #{row["crate"]}/target/#{row["target"]}/release/#{row["executable"]} out/#{asset}",
+           "          (cd out && sha256sum #{asset} > #{asset}.sha256)",
+           "          gh release create \"$TAG\" out/#{asset} out/#{asset}.sha256 --prerelease --target \"$GITHUB_SHA\" \\",
+           "            --title \"$TAG\" \\",
+           "            --notes \"#{row["executable"]} for #{row["target"]}, built from #{row["crate"]} at $GITHUB_SHA.\""]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/lanes/rows.rb

@@ -29,9 +29,15 @@ module Hecks
           return "#{name} has guarded #{lane["guarded"].inspect}" unless %w[yes no].include?(lane["guarded"])
           return "#{name} has alert_after #{lane["alert_after"].inspect}, not whole hours" unless hours?(lane)
 
+          return "#{name} has release_trailer #{lane["release_trailer"].inspect}, not a trailer word" unless trailer?(lane)
+
           follows_problem(lane, names)
         end
 
+        # @return [Boolean] whether `release_trailer` is empty (nothing is released from the lane)
+        #   or a git trailer key such as `Release-Approved-By`
+        def trailer?(lane) = lane["release_trailer"].to_s.match?(/\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/)
+
         # @return [Boolean] whether `alert_after` is empty (never late) or whole hours
         def hours?(lane) = lane["alert_after"].to_s.match?(/\A\d*\z/)
 

data/lib/hecks/tools/lanes.rb

@@ -78,5 +78,6 @@ require_relative "lanes/rows"
 require_relative "lanes/ruleset"
 require_relative "lanes/workflow"
 require_relative "lanes/watch_workflow"
+require_relative "lanes/prebuilt_workflow"
 require_relative "lanes/files"
 require_relative "lanes/live"

data/lib/hecks/tools/oidc_manifests.rb

@@ -10,9 +10,8 @@ module Hecks
     #
     # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
     # sweep over the whole checkout carries on past either. `hecks deploy
-    # oidc_manifest.project_oidc` loads
-    # `bundler/setup` first, which pins the `json` gem: newer releases pretty-print an empty array
-    # as `[\n\n]`, a diff spec/oidc_manifest_spec.rb would report as drift.
+    # oidc_manifest.project_oidc` writes through `Hecks::Projections::OIDC.render`, which spells an
+    # empty list `[]` whichever json release is loaded, so the text does not depend on the machine.
     module OidcManifests
       # Directories that hold a `.hecksagon` but are never domains.
       NOT_DOMAINS = %r{\A(rust|deploy|tmp|coverage)/}
@@ -50,7 +49,7 @@ module Hecks
       # @param path [String] a domain directory, relative to `root`
       # @return [void]
       def project(root, path)
-        runtime = Hecks.boot(File.join(root, path), install_doors: false)
+        runtime = Hecks.boot(File.join(root, path), install_driving: false)
         name    = runtime.registry.bluebooks.keys.first
         return warn("  #{path}: no bluebook found — skipped") unless name
 
@@ -65,7 +64,7 @@ module Hecks
       # @param out [String] where the manifest goes
       # @return [void]
       def write_manifest(registry, name, out)
-        Hecks::Projector.write(Hecks::Projector.call(:oidc, bluebook: registry.bluebook(name)), out)
+        File.write(out, Hecks::Projections::OIDC.render(Hecks::Projector.call(:oidc, bluebook: registry.bluebook(name))))
       end
     end
   end

data/lib/hecks/tools/regeneration_run.rb

@@ -8,13 +8,13 @@ require_relative "../corpus"
 
 module Hecks
   module Tools
-    # Regenerates every corpus domain's committed Rust output with `hecks project_rust`, or checks
-    # that the committed output is what a regeneration would write.
+    # Regenerates every corpus domain's Rust output with `hecks project_rust`, or checks that the
+    # output on disk is what that would write. Only pizzas, `mod.rs` and `Cargo.toml` are committed.
     #
     # The domain list comes from `Hecks::Corpus.rust_regen_order`, never a hand-kept list. The
     # order is fixed (sorted by relative path): domains that share governance/, identity/,
-    # Cargo.toml and generated/mod.rs stamp them with whichever ran last, so it must not flap. If
-    # the domain set or the sort rule changes, re-run and commit the output; never hand-edit stamps.
+    # Cargo.toml and generated/mod.rs stamp them with whichever ran last, so it must not flap.
+    # If the domain set or the sort rule changes, re-run and commit what changed.
     #
     #   hecks regenerate_corpus         # discover, regenerate, print the plan
     #   hecks regenerate_corpus --check # regenerate into a scratch crate; fail on any difference
@@ -27,6 +27,11 @@ module Hecks
                    "wrong directory, or something upstream deleted rust/src/generated/ entirely. Refusing " \
                    "to silently treat that as \"nothing to regenerate.\""
 
+      # The refusal when a check finds nothing generated to compare.
+      NOT_MATERIALIZED = "hecks regenerate_corpus --check: rust/src/generated has no generated output to compare. " \
+                         "Only pizzas, mod.rs and Cargo.toml are committed; run " \
+                         "`hecks regenerate_corpus --confirm` first, then the check."
+
       module_function
 
       # Regenerates the corpus, or checks it.
@@ -147,6 +152,8 @@ module Hecks
       # @param root [String] the checkout
       # @return [String] the scratch directory
       def scratch_crate(root)
+        abort NOT_MATERIALIZED unless File.directory?(File.join(root, "rust/src/generated/meta"))
+
         scratch = Dir.mktmpdir("regen-codegen-check")
         FileUtils.mkdir_p(File.join(scratch, "src"))
         FileUtils.cp_r(File.join(root, "rust/src/generated"), File.join(scratch, "src/generated"))