hecks 3.11.0 → 3.12.0

data/lib/hecks/projections/deploy/box.rb

@@ -5,10 +5,12 @@ require_relative "box/hosting"
 require_relative "box/roll_recipe"
 require_relative "box/caddy"
 require_relative "box/access"
+require_relative "box/logging"
 require_relative "box/stack_yaml"
 require_relative "box/compose"
 require_relative "box/shared_database"
 require_relative "box/roll_scripts"
+require_relative "box/edge"
 
 module Hecks
   module Projections
@@ -21,10 +23,12 @@ module Hecks
         extend Projector::Target
         extend Caddy
         extend Access
+        extend Logging
         extend StackYaml
         extend Compose
         extend SharedDatabase
         extend RollScripts
+        extend Edge
 
         projects_as :aws_box, needs_world: true, emits: :files
 
@@ -123,7 +127,15 @@ module Hecks
             volume_gb: { value: settings.fetch(:volume_gb, 30) },
             database_class: { value: settings.fetch(:database_class, "db.t4g.small") },
             storage_gb: { value: settings.fetch(:storage_gb, 20) }
-          }
+          }.merge(cdn_arguments(settings[:cdn]))
+        end
+
+        # @param cdn [Hash{Symbol => Object}, nil] the world's `cdn` setting
+        # @return [Hash{Symbol => Array}] the `cdn_aliases` argument, or nothing without a `cdn`
+        def cdn_arguments(cdn)
+          return {} unless cdn.is_a?(Hash) && cdn[:aliases].is_a?(Array)
+
+          { cdn_aliases: cdn[:aliases].map { |name| { value: name } } }
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -136,8 +148,8 @@ module Hecks
             "render-compose.sh" => render_compose_sh(plan, region),
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
             "deploy-box.sh" => deploy_box_sh(plan, region),
-            "Makefile" => makefile(plan)
-          }.merge(database_files(plan)).merge(migration_files(plan))
+            "Makefile" => makefile(plan, region)
+          }.merge(database_files(plan)).merge(migration_files(plan)).merge(edge_files(plan, region))
             .then { |files| Hosting.extend_files(files, plan: plan, region: region) }
         end
 

data/lib/hecks/projections/site/site_root/workflow.rb

@@ -32,6 +32,11 @@ module Hecks
             permissions:
               contents: read
 
+            # A newer push to the same PR supersedes the run in flight; pushes to main each keep their own run.
+            concurrency:
+              group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+              cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
             jobs:
               routes-current-and-parity:
                 runs-on: ubuntu-24.04

data/lib/hecks/projector/cli_audience.rb

@@ -13,6 +13,26 @@ module Hecks
         hidden.empty? ? specs : specs.reject { |_, spec| hidden.include?(spec[:group]) }
       end
 
+      # The specs the options' audience is shown: those not hidden, and only those listed, if any
+      # are.
+      def audience_specs(specs, options)
+        only_listed(without_hidden(specs, options[:hide]), options[:only])
+      end
+
+      # The specs a newcomer is shown: only those named, or all of them when none are.
+      def only_listed(specs, only)
+        listed = Array(only)
+        listed.empty? ? specs : specs.slice(*listed)
+      end
+
+      # The line saying the help lists only the first steps and how to list the rest, or no line
+      # when it lists everything.
+      def newcomer_hint(program, only)
+        return [] if Array(only).empty?
+
+        ["  #{program} --all                  also list every command (no bluebook is in this folder yet)"]
+      end
+
       # The attached chapters the help points at, one line each, under the call that opens them.
       #
       # @param chapters [Array<Array(String, String)>, nil] each chapter's word and its summary

data/lib/hecks/projector/cli_projector/usage.rb

@@ -34,8 +34,7 @@ module Hecks
 
         # The whole help: the two tables, the chapters, then the hints.
         def full_usage(bluebook, commands, questions, options, program)
-          shown = [CliAudience.without_hidden(commands, options[:hide]),
-                   CliAudience.without_hidden(questions, options[:hide])]
+          shown = [commands, questions].map { |specs| CliAudience.audience_specs(specs, options) }
           [usage_header(bluebook, program),
            tables(*shown, all: options[:all], notes: aggregate_notes(bluebook)),
            CliAudience.chapter_lines(program, options[:chapters]),
@@ -57,6 +56,11 @@ module Hecks
         # The pointers after the tables: `--help`, `--all`, `--maintainer` and an example call.
         def usage_footer(program, shown, options, hidden_count)
           out = ["", "  #{program} <command> --help       what one command wants, and every way it refuses"]
+          if Array(options[:only]).any?
+            out.concat(CliAudience.newcomer_hint(program, options[:only]))
+            return out << "  start with #{program} init! — it writes the stub files of a new domain"
+          end
+
           out.concat(all_hint(program, *shown)) unless options[:all]
           out.concat(CliAudience.maintainer_hint(program, hidden_count))
           out << "  a command is called with its aggregate — #{example_qualified(shown.first)}"
@@ -64,8 +68,15 @@ module Hecks
 
         # The commands table then the queries table.
         def tables(commands, questions, all:, notes:)
-          ["commands:", *listing(commands, all: all, notes: notes) { |spec| spec[:summary] }, "",
-           "queries (nothing here changes anything):",
+          ["commands:", *listing(commands, all: all, notes: notes) { |spec| spec[:summary] },
+           *queries_table(questions, all: all, notes: notes)]
+        end
+
+        # The queries table, or nothing when the audience is shown no query.
+        def queries_table(questions, all:, notes:)
+          return [] if questions.empty?
+
+          ["", "queries (nothing here changes anything):",
            *listing(questions, all: all, notes: notes) { |spec| first_sentence(spec[:summary]) }]
         end
 

data/lib/hecks/rust_build/host.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "open3"
 require_relative "../rust_build"
 require_relative "wasm"
+require_relative "prebuilt_binary"
 
 module Hecks
   module RustBuild
@@ -102,13 +103,19 @@ module Hecks
       def compile(target)
         host_dir = File.join(RustBuild.rust_dir, "host")
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        binary = File.join(target_dir, target, "release", BINARY)
+        return binary if PrebuiltBinary.fetch("host", host_dir, target: target, into: binary)
+
+        cargo_build(target, host_dir, { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target)))
+        binary
+      rescue Failure => e
+        raise Failure, "#{e.message}#{cross_hint(target)}"
+      end
+
+      def cargo_build(target, host_dir, env)
         puts "== cargo build --release --target #{target} --bin #{BINARY} (rust/host) =="
-        env = { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target))
         RustBuild.command!("rustup", "run", TOOLCHAIN, "cargo", "build", "--release", "--target", target,
                            "--bin", BINARY, chdir: host_dir, env: env)
-        File.join(target_dir, target, "release", BINARY)
-      rescue Failure => e
-        raise Failure, "#{e.message}#{cross_hint(target)}"
       end
 
       def linker_for(target)

data/lib/hecks/rust_build/prebuilt_binary.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "net/http"
+require "uri"
+require "hecks/vocabulary"
+
+module Hecks
+  module RustBuild
+    # A binary hecks has already compiled and published, named by what went into it (ADR 0110).
+    #
+    # The `PrebuiltBinary` rows of the Vocabulary chapter say which binaries are published: the
+    # crate to key, the Cargo binary, the target it is built for. A release tagged `<name>-<key>`
+    # holds the binary and its `.sha256`; the key is a hash of the crate's build inputs, so the
+    # same bytes are the same release, whichever commit they come from. `fetch` downloads it and
+    # checks its hash, and answers nil on any miss (not published yet, no network, a hash that
+    # does not match) so a caller compiles as it always did. `HECKS_PREBUILT=off` turns the
+    # download off.
+    module PrebuiltBinary
+      # Where releases are published.
+      REPOSITORY = "heckslabs/hecks"
+
+      # Left out of the key: Cargo's own output, and files that are never part of the binary.
+      EXCLUDED = %w[target tests .gitignore].freeze
+
+      MAX_REDIRECTS = 5
+
+      module_function
+
+      # @param name [String] a `PrebuiltBinary` row's name
+      # @return [Hash{String => String}] the row
+      # @raise [KeyError] when no row has the name
+      def row(name)
+        Hecks::Vocabulary.rows("PrebuiltBinary").find { |found| found["name"] == name } or
+          raise KeyError, "no PrebuiltBinary row named #{name.inspect}"
+      end
+
+      # @param crate_dir [String] the crate's directory
+      # @return [String] a hash of every file that goes into the build: each path and its bytes, in
+      #   path order, so it does not depend on the checkout it is read from
+      def key(crate_dir)
+        files = Dir.glob("**/*", File::FNM_DOTMATCH, base: crate_dir).sort.select do |path|
+          File.file?(File.join(crate_dir, path)) && !EXCLUDED.include?(path.split("/").first)
+        end
+        digest = Digest::SHA256.new
+        files.each { |path| digest << "#{path}\0#{File.binread(File.join(crate_dir, path))}\0" }
+        digest.hexdigest[0, 24]
+      end
+
+      # @param name [String] a row's name
+      # @param key [String] the crate's key
+      # @return [String] the release tag
+      def tag(name, key) = "#{name}-#{key}"
+
+      # @param name [String] a row's name
+      # @return [String] the file the release holds the binary as
+      def asset(name)
+        found = row(name)
+        "#{found["executable"]}-#{found["target"]}"
+      end
+
+      # @param name [String] a row's name
+      # @param crate_dir [String] the crate's directory
+      # @param target [String] the triple the caller builds for
+      # @param into [String] the file to write the binary to
+      # @return [String, nil] `into`, or nil when the binary is not published for this target or
+      #   could not be fetched and verified
+      def fetch(name, crate_dir, target:, into:)
+        return if ENV["HECKS_PREBUILT"] == "off" || row(name)["target"] != target
+
+        body = verified(name, crate_dir) or return
+        FileUtils.mkdir_p(File.dirname(into))
+        File.binwrite(into, body)
+        File.chmod(0o755, into)
+        puts "== downloaded the prebuilt #{asset(name)} (#{tag(name, key(crate_dir))}); nothing compiled =="
+        into
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError
+        nil
+      end
+
+      # @return [String, nil] the published binary, nil unless its bytes hash to the published
+      #   sha256
+      def verified(name, crate_dir)
+        base = "https://github.com/#{REPOSITORY}/releases/download/#{tag(name, key(crate_dir))}/#{asset(name)}"
+        expected = get("#{base}.sha256")&.split&.first
+        body = expected && get(base)
+        body if body && Digest::SHA256.hexdigest(body) == expected
+      end
+
+      # @return [String, nil] the body at the URL, following redirects, nil unless it answers 200
+      def get(url, redirects = MAX_REDIRECTS)
+        response = Net::HTTP.get_response(URI(url))
+        return response.body if response.is_a?(Net::HTTPSuccess)
+        return get(response["location"], redirects - 1) if response.is_a?(Net::HTTPRedirection) && redirects.positive?
+
+        nil
+      end
+    end
+  end
+end

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/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.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/release_only.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/vocabulary"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Decides whether a commit is only a release bump on a base that is fully certified, so CI may
+    # inherit the base's certification instead of running the suite again.
+    #
+    # The files a bump edits, and which of their lines it may change, are the `ReleaseFile` rows of
+    # the Vocabulary chapter. A change is a release bump when it touches at least one file, every
+    # file it touches is a row, and every line it adds or removes in a file matches that row's
+    # `lines` pattern (an empty pattern admits any line). Whether the base is certified is read
+    # from the base commit's own check runs: every `RequiredCheck` row that is not marked
+    # `runs: always` must have its latest run on the base succeed or be skipped.
+    #
+    # Every case that cannot be confirmed answers "not a release bump", so the suite runs.
+    module ReleaseOnly
+      GREEN = %w[success skipped].freeze
+
+      module_function
+
+      # @param changes [Hash{String => Array<String>}] each changed path to the lines it adds or
+      #   removes
+      # @param files [Array<Hash{String => String}>] the `ReleaseFile` rows
+      # @return [Boolean] whether the change touches only release files, and only their release
+      #   lines
+      def release_only?(changes, files: Hecks::Vocabulary.rows("ReleaseFile"))
+        return false if changes.empty?
+
+        by_path = files.to_h { |row| [row.fetch("path"), row.fetch("lines", "")] }
+        changes.all? { |path, lines| by_path.key?(path) && lines_allowed?(lines, by_path.fetch(path)) }
+      end
+
+      # @param lines [Array<String>] the changed lines of one file
+      # @param pattern [String] the row's `lines` regex, empty for any line
+      # @return [Boolean] whether every changed line matches
+      def lines_allowed?(lines, pattern)
+        return true if pattern.to_s.empty?
+
+        regex = Regexp.new(pattern)
+        lines.all? { |line| line.match?(regex) }
+      end
+
+      # @param runs [Array<Hash{String => String}>] the base commit's check runs: `name`,
+      #   `conclusion` and `started_at`
+      # @param required [Array<Hash{String => String}>] the `RequiredCheck` rows
+      # @return [Boolean] whether every check that must be inherited has a green latest run
+      def certified?(runs, required: Hecks::Vocabulary.rows("RequiredCheck"))
+        latest = latest_runs(runs)
+        inherited = required.reject { |row| row["runs"] == "always" }.map { |row| row.fetch("name") }
+        inherited.all? { |name| GREEN.include?(latest[name].to_h["conclusion"]) }
+      end
+
+      # @return [Hash{String => Hash}] each check's most recently started run
+      def latest_runs(runs)
+        runs.group_by { |run| run["name"] }.transform_values { |group| group.max_by { |run| run["started_at"].to_s } }
+      end
+
+      # @param base [String] the commit the change is measured against
+      # @param head [String] the commit under test
+      # @param root [String] the checkout
+      # @return [Hash{String => Array<String>}, nil] each changed path to its changed lines, or nil
+      #   when git could not say
+      def changes(base, head, root:)
+        out, _err, status = Open3.capture3("git", "-C", root, "diff", "-U0", "--no-color", base, head)
+        status.success? ? parse(out) : nil
+      end
+
+      # @param diff [String] `git diff -U0` output
+      # @return [Hash{String => Array<String>}] each changed path to the lines it adds or removes
+      def parse(diff)
+        found = Hash.new { |hash, key| hash[key] = [] }
+        path = nil
+        diff.each_line do |line|
+          path = file_of(line.chomp) || path
+          found[path] << line[1..].chomp if path && content_line?(line)
+        end
+        found.to_h
+      end
+
+      # @return [String, nil] the path a `+++` or `---` header names, nil for any other line
+      def file_of(line)
+        return line.delete_prefix("+++ b/") if line.start_with?("+++ b/")
+
+        line.delete_prefix("--- a/") if line.start_with?("--- a/")
+      end
+
+      # @return [Boolean] whether the line is an added or removed line, not a header
+      def content_line?(line)
+        line.match?(/\A[+-]/) && !line.start_with?("+++ ", "--- ")
+      end
+
+      # @param repository [String] `owner/name`
+      # @param sha [String] the commit whose check runs are read
+      # @param env [Hash{String => String}] carries `GH_TOKEN` for the API call
+      # @return [Array<Hash{String => String}>, nil] the check runs, or nil when the API failed
+      def check_runs(repository, sha, env: ENV)
+        path = "repos/#{repository}/commits/#{sha}/check-runs?per_page=100"
+        jq = ".check_runs[] | {name, conclusion, started_at}"
+        out, _err, status = Open3.capture3(env.to_h.slice("GH_TOKEN"), "gh", "api", path, "--paginate", "--jq", jq)
+        status.success? ? out.lines.map { |line| JSON.parse(line) } : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.11.0".freeze
+  VERSION = "3.12.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,6 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"before_sha", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
+        {"name"=>"release_only", "workflow"=>"ci.yml", "mode"=>"release_only", "pattern"=>"", "push"=>"before_sha", "label"=>"is this change only a release bump on a certified base?"}.freeze,
         {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"skip", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
@@ -134,6 +135,9 @@ module Hecks
         {"name"=>"replace"}.freeze,
         {"name"=>"scale_call"}.freeze
       ].freeze,
+      "PrebuiltBinary" => [
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+      ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
         {"name"=>"Integer"}.freeze,
@@ -363,6 +367,15 @@ module Hecks
         {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
         {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
       ].freeze,
+      "ReleaseFile" => [
+        {"path"=>"lib/hecks/version.rb", "lines"=>"^\\s*VERSION = \"[0-9]+\\.[0-9]+\\.[0-9]+\"\\.freeze$"}.freeze,
+        {"path"=>"CHANGELOG.md", "lines"=>""}.freeze,
+        {"path"=>"README.md", "lines"=>"^(\\*\\*Status:\\*\\* )?Current release: `[0-9]+\\.[0-9]+\\.[0-9]+`"}.freeze,
+        {"path"=>"Gemfile.lock", "lines"=>"^    hecks \\([0-9]+\\.[0-9]+\\.[0-9]+\\)$"}.freeze,
+        {"path"=>"rust/host/HECKS_RELEASE", "lines"=>"^[0-9]+\\.[0-9]+\\.[0-9]+$"}.freeze,
+        {"path"=>"packages/hecks-client/package.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze,
+        {"path"=>"packages/hecks-client/package-lock.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze
+      ].freeze,
       "RequiredCheck" => [
         {"name"=>"rspec"}.freeze,
         {"name"=>"checks"}.freeze,
@@ -372,7 +385,8 @@ module Hecks
         {"name"=>"rspec_rust_parser"}.freeze,
         {"name"=>"rspec_rust_codegen"}.freeze,
         {"name"=>"rspec_rust_host"}.freeze,
-        {"name"=>"rspec_fuzzing"}.freeze
+        {"name"=>"rspec_fuzzing"}.freeze,
+        {"name"=>"release_consistency", "runs"=>"always"}.freeze
       ].freeze,
       "RetiredScript" => [
         {"script"=>"ir", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"ir"}.freeze,