hecks 3.11.0 → 3.13.0

data/lib/hecks/projections/site/edge.rb

@@ -7,6 +7,7 @@ require_relative "edge/row_reader"
 require_relative "edge/checks"
 require_relative "edge/behaviours"
 require_relative "edge/rules"
+require_relative "edge/function_code"
 
 module Hecks
   module Projections
@@ -16,17 +17,33 @@ module Hecks
       #
       # The routes are the table's own `Route` rows. What a table cannot know, the names a template
       # gives its policies, origins, target groups and listener, a project declares as `member`
-      # rows of four more value objects of the same chapter: `Edge` (the template and listener),
-      # `EdgePolicy`, `EdgeOrigin` and `EdgeRule`. `docs/site-routes.md` lists their fields. A
-      # project that declares none of the four has no edge to project.
+      # rows of five more value objects of the same chapter: `Edge` (the template and listener),
+      # `EdgePolicy`, `EdgeOrigin`, `EdgeRule` and `EdgeFunction` (a viewer-request function a route
+      # names with `edge:`). `docs/site-routes.md` lists their fields. A project that declares none
+      # of the five has no edge to project.
       class Edge
         Setting  = Struct.new(:template, :listener, :secret_header, :secret_value, :alb, keyword_init: true)
         Policy   = Struct.new(:cache_class, :origin, :cache, :origin_request, :response_headers, keyword_init: true)
         Upstream = Struct.new(:origin, :id, :target_group, keyword_init: true)
         Rule     = Struct.new(:rule, :priority, :origin, keyword_init: true)
 
+        # A function the generator writes: `kind` says which, and the rest are its settings, the
+        # lists as comma-separated text.
+        Function = Struct.new(:name, :kind, :host, :aliases, :paths, keyword_init: true) do
+          # @return [Array<String>] the alias hosts that are redirected
+          def alias_list = split(aliases)
+
+          # @return [Array<String>] the exact paths the function watches
+          def path_list = split(paths)
+
+          private
+
+          def split(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+        end
+
         # The value objects a project declares its edge rows in, by the kind of record each holds.
-        OBJECTS = { setting: "Edge", policy: "EdgePolicy", upstream: "EdgeOrigin", rule: "EdgeRule" }.freeze
+        OBJECTS = { setting: "Edge", policy: "EdgePolicy", upstream: "EdgeOrigin", rule: "EdgeRule",
+                    function: "EdgeFunction" }.freeze
 
         # The fields each kind of row may carry, with the Ruby class each takes.
         FIELDS = {
@@ -34,14 +51,15 @@ module Hecks
           policy:   { cache_class: String, origin: String, cache: String, origin_request: String,
                     response_headers: String },
           upstream: { origin: String, id: String, target_group: String },
-          rule:     { rule: String, priority: Integer, origin: String }
+          rule:     { rule: String, priority: Integer, origin: String },
+          function: { name: String, kind: String, host: String, aliases: String, paths: String }
         }.freeze
 
         # The fields a row of each kind must carry. The template may instead be named to the tool.
         REQUIRED = { setting: [], policy: %i[cache_class cache], upstream: %i[origin id],
-                     rule: %i[rule priority origin] }.freeze
+                     rule: %i[rule priority origin], function: %i[name kind host aliases paths] }.freeze
 
-        STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule }.freeze
+        STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule, function: Function }.freeze
 
         # @return [Setting] the template and the listener
         attr_reader :setting
@@ -51,6 +69,8 @@ module Hecks
         attr_reader :upstreams
         # @return [Array<Rule>] the listener rules
         attr_reader :rules
+        # @return [Array<Function>] the edge functions the generator writes
+        attr_reader :functions
         # @return [Hash{Symbol => Object}] the default behaviour as `Cdn.behavior_lines` takes it
         attr_reader :default_behaviour
         # @return [Array<Hash{Symbol => Object}>] the other behaviours, in matching order
@@ -65,11 +85,12 @@ module Hecks
         # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
         # @param template [String, nil] the template the caller names, which stands in for the
         #   `Edge` row's own `template:`
-        # @return [Edge, nil] the checked edge, or nil when the chapter declares none
+        # @return [Edge, nil] the checked edge, or nil when the chapter declares none and no route
+        #   names an edge function
         # @raise [Table::Invalid] when a row is refused or the edge contradicts the routes
         def self.read(chapter, table:, vocabulary:, template: nil)
           declared = OBJECTS.transform_values { |name| Table.rows_of(chapter, name) }
-          return nil if declared.values.all?(&:empty?)
+          return nil if declared.values.all?(&:empty?) && table.rows.none?(&:edge)
 
           problems = []
           records = declared.to_h { |kind, members| [kind, build(kind, members, problems)] }
@@ -104,6 +125,7 @@ module Hecks
           @policies = records.fetch(:policy)
           @upstreams = records.fetch(:upstream)
           @rules = records.fetch(:rule)
+          @functions = records.fetch(:function)
         end
         private :assign
 
@@ -119,6 +141,10 @@ module Hecks
         #   unless the `Edge` row says `alb: false`
         def alb? = setting.nil? || setting.alb != false
 
+        # @param name [String] a logical id
+        # @return [Function, nil] the function row of that name
+        def function(name) = functions.find { |candidate| candidate.name == name }
+
         # @param origin [String] an origin of the Origin set
         # @return [Upstream, nil] its CloudFront origin and target group
         def upstream(origin) = upstreams.find { |candidate| candidate.origin == origin }

data/lib/hecks/projections/site/site_cdn.rb

@@ -7,12 +7,14 @@ require_relative "edge"
 module Hecks
   module Projections
     module Site
-      # The edge of a site's route table as the two blocks of a CloudFormation template that depend
-      # on it: the distribution's cache behaviours and the load balancer's listener rules.
+      # The edge of a site's route table as the blocks of a CloudFormation template that depend on
+      # it: the distribution's cache behaviours, the load balancer's listener rules and the
+      # functions the behaviours attach.
       #
-      # The blocks are returned by name, `"behaviors"` and `"listener_rules"`, as text from the
-      # left margin; a project whose `Edge` row says `alb: false` has no load balancer and gets
-      # `"behaviors"` alone. `Regions` puts each between the markers of the same name in the
+      # The blocks are returned by name, `"behaviors"`, `"listener_rules"` and `"edge_functions"`,
+      # as text from the left margin; a project whose `Edge` row says `alb: false` has no load
+      # balancer and gets no `"listener_rules"`, and one with no `EdgeFunction` row gets no
+      # `"edge_functions"`. `Regions` puts each between the markers of the same name in the
       # project's template, at the markers' indentation. The text is a pure function of the table
       # and the edge rows.
       module SiteCdn
@@ -34,9 +36,21 @@ module Hecks
           edge = options[:edge] || Edge.read(bluebook, table: table, vocabulary: Table.vocabulary(registry))
           return {} unless edge
 
-          return { "behaviors" => behaviors(edge) } unless edge.alb?
+          regions(edge)
+        end
 
-          { "behaviors" => behaviors(edge), "listener_rules" => listener_rules(edge) }
+        # @param edge [Edge] a checked edge
+        # @return [Hash{String => String}] the regions the edge needs
+        def regions(edge)
+          { "behaviors" => behaviors(edge) }
+            .merge(edge.alb? ? { "listener_rules" => listener_rules(edge) } : {})
+            .merge(edge.functions.any? ? { "edge_functions" => edge_functions(edge) } : {})
+        end
+
+        # @param edge [Edge] a checked edge
+        # @return [String] one function resource per `EdgeFunction` row, ending in a newline
+        def edge_functions(edge)
+          edge.functions.map { |function| Edge::FunctionCode.resource(function) }.join("\n")
         end
 
         # @param edge [Edge] a checked edge

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/projections/site/table/row_builder.rb

@@ -11,7 +11,7 @@ module Hecks
                          :indexable, :switch, :off, :preview, :label, :seo, :redirect_to, :aliases,
                          :nav_group, :nav_order, :mobile_order, :footer_column, :footer_order,
                          :admin_key, :admin_order, :compress, :alb_rule, :cdn,
-                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, keyword_init: true)
+                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, :edge, keyword_init: true)
 
         # Turns a declared member into a `Row`: checks its fields and their types, fills the
         # defaults, and checks each closed-set value against the Site chapter's vocabulary.
@@ -23,7 +23,10 @@ module Hecks
                      aliases: String, nav_group: String, nav_order: Integer, mobile_order: Integer,
                      footer_column: String, footer_order: Integer, admin_key: String,
                      admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool,
-                     seo_title: String, edge_methods: String, mobile_heading: String }.freeze
+                     seo_title: String, edge_methods: String, mobile_heading: String, edge: String }.freeze
+
+          # What an `edge:` names: the logical id of an `EdgeFunction` row.
+          EDGE_NAME = /\A[A-Za-z][A-Za-z0-9]*\z/
 
           # The value objects of the Site chapter's `Route` aggregate whose members are the closed
           # sets, by the row field each constrains.
@@ -103,6 +106,13 @@ module Hecks
               problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(", ")}")
             end
             check_verbs(row, label)
+            check_edge(row, label)
+          end
+
+          def check_edge(row, label)
+            return unless row.edge.is_a?(String) && !EDGE_NAME.match?(row.edge)
+
+            problem(label, "has edge #{row.edge.inspect}; an edge is the logical id of an EdgeFunction row")
           end
 
           def check_verbs(row, label)

data/lib/hecks/projections/site/table.rb

@@ -60,7 +60,8 @@ module Hecks
 
         # @param registry [Runtime::Registry] a registry holding the Site chapter
         # @return [Hash{Symbol => Array<String>}] each constrained field to its allowed values, and
-        #   `:http_method` to the verbs a route may answer
+        #   `:http_method` to the verbs a route may answer and `:edge_function_kind` to the kinds of
+        #   `EdgeFunction` row
         # @raise [Invalid] when the registry does not hold the Site chapter
         def self.vocabulary(registry)
           site = registry.bluebook("Site") or
@@ -69,7 +70,8 @@ module Hecks
           members = lambda do |name|
             route.value_objects.find { |object| object.hecks_name == name }.members.map { |member| member.fetch(:value) }
           end
-          RowBuilder::VOCABULARY.transform_values(&members).merge(http_method: members.call("HttpMethod"))
+          closed = RowBuilder::VOCABULARY.transform_values(&members)
+          closed.merge(http_method: members.call("HttpMethod"), edge_function_kind: members.call("EdgeFunctionKind"))
         end
 
         # @param chapter [Bluebook::Chapter] a chapter to search

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/site/bluebook/site.bluebook

@@ -12,7 +12,9 @@
 # The same command projects the CDN: a project that adds Edge, EdgePolicy, EdgeOrigin and EdgeRule rows
 # to its chapter has the CloudFront behaviours and the listener rules written into the marked regions
 # of the template it owns (the `:site_cdn` projection). Those rows are the template's facts, so only the
-# closed sets they draw on, cache class and origin, are named here.
+# closed sets they draw on, cache class, origin and the kind of an EdgeFunction row, are named here. A
+# route's `edge:` names an EdgeFunction row, a viewer-request function the projection writes into the
+# template's `edge_functions` region and attaches to that route's behaviour.
 #
 # Each run records that it was requested before the SiteToolchain port is asked, and what came of
 # it after. No command declares a role: the chapter boots standing alone.
@@ -33,6 +35,7 @@ Hecks.bluebook "Site" do
     attribute :source, Source,  optional: true
     attribute :http_method, HttpMethod, optional: true
     attribute :preview, Preview, optional: true
+    attribute :edge, EdgeName, optional: true
 
     # `/blog/:slug.html` names a parameter; a trailing `/*` matches everything beneath a prefix. A
     # row with a `command:` or `query:` source may leave its path out, and the projection derives it
@@ -78,6 +81,18 @@ Hecks.bluebook "Site" do
       attribute :value, String, one_of: ["public", "draft"]
     end
 
+    # The logical id of an `EdgeFunction` row: the viewer-request function the route's behaviour runs.
+    value_object "EdgeName" do
+      attribute :value, String, pattern: '\A[A-Za-z][A-Za-z0-9]*\z'
+    end
+
+    # What an `EdgeFunction` row asks the projection to write: `redirect_host` answers a request for
+    # a watched path on an alias host with a redirect to the canonical host and leaves every other
+    # request alone.
+    value_object "EdgeFunctionKind" do
+      attribute :value, String, one_of: ["redirect_host"]
+    end
+
     # The HTTP verbs a route answers.
     value_object "HttpMethod" do
       attribute :value, String, one_of: ["GET", "POST", "PUT", "PATCH", "DELETE"]

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? }