hecks 3.2.1 → 3.3.0

data/lib/hecks/fuzzing/qa_settings.rb

@@ -1,44 +1,26 @@
 require "yaml"
+require "hecks/vocabulary"
 
 module Hecks
   module Fuzzing
     # Loads and validates `qa/settings.yml`, the hecks_qa dials.
     #
     # Fails loud: a missing key, unknown key or wrong-typed value raises at load time.
-    # The meaning of each dial is documented on `QualityControlDials` in the bluebook.
+    # What each dial is and takes is declared as a `QaDial` row in the Vocabulary chapter.
     class QaSettings
-      # Accessor name to the class (or classes) a valid value must be an instance of.
-      # Booleans list both TrueClass and FalseClass; Numeric admits `0` as well as `0.0`.
-      EXPECTED_TYPES = {
-        cadence_seconds:              Integer,
-        pr_cap_per_day:               Integer,
-        widening_tiers:               Array,
-        sweep_max_parallel:           Integer,
-        liveness_fallback_seconds:    Integer,
-        draft_only:                   [TrueClass, FalseClass],
-        auto_merge:                   [TrueClass, FalseClass],
-        branch_prefix:                String,
-        adversarial_fraction:         Numeric,
-        guided_generation:            [TrueClass, FalseClass],
-        corpus_splice_probability:    Numeric,
-        favor_rare_verbs:             Integer,
-        self_consistency_checks:      [TrueClass, FalseClass],
-        shrink_budget:                Integer,
-        yield_weight_seconds:         Integer,
-        yield_decay_percent:          Integer,
-        rotation_stale_floor_seconds: Integer,
-        persistence_parity_seed_cap:  Integer,
-        concurrency_seed_cap:         Integer,
-        adapter_parity_pairs:         Hash,
-        modes:                        Hash,
-        role_draw_probability:        Numeric,
-        dry_run_fraction:             Numeric,
-        generated_domains_per_tick:   Integer,
-        generated_domains_rust:       [TrueClass, FalseClass],
-        generated_domain_seeds:       Integer,
-        structural_refusal_boundary:  Array
+      # The classes a value of each `type` of a `QaDial` row must be an instance of. Booleans list
+      # both TrueClass and FalseClass; Numeric admits `0` as well as `0.0`.
+      TYPE_CLASSES = {
+        "Integer" => [Integer], "Numeric" => [Numeric], "Boolean" => [TrueClass, FalseClass],
+        "String" => [String], "Array" => [Array], "Hash" => [Hash]
       }.freeze
 
+      # Accessor name to the classes a valid value must be an instance of, one entry per `QaDial`
+      # row of the Vocabulary chapter, where each dial is declared with its type and its meaning.
+      EXPECTED_TYPES = Hecks::Vocabulary.rows("QaDial").to_h do |dial|
+        [dial.fetch("name").to_sym, TYPE_CLASSES.fetch(dial.fetch("type"))]
+      end.freeze
+
       attr_reader(*EXPECTED_TYPES.keys)
 
       # The one real file, resolved from this file's `__dir__` rather than the bluebook's: the
@@ -68,8 +50,7 @@ module Hecks
         end
       end
 
-      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per dial in
-      #   `EXPECTED_TYPES`
+      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per `QaDial` row
       # @param path [String] path to the settings file, used only in error messages
       # @raise [ArgumentError] if `raw` is missing a required key, declares an unknown
       #   key, or gives a value the wrong type for its dial
@@ -81,7 +62,7 @@ module Hecks
         if extra.any?
           raise ArgumentError,
                 "#{path} declares unknown key(s) #{extra.sort.join(', ')} — " \
-                "Hecks::Fuzzing::QaSettings::EXPECTED_TYPES doesn't recognise them"
+                "no QaDial row of the Vocabulary chapter declares them"
         end
 
         EXPECTED_TYPES.each do |key, expected|

data/lib/hecks/gate/stages.yml

@@ -9,6 +9,16 @@
 #
 # `env` is set only where the caller has not set it: a push check has no use for the Hecks
 # domain's database, so it runs on Memory, as a pull-request run does in CI.
+#
+# A check a second stage repeats is written once, under an anchor (`&name`), and aliased
+# (`*name`) where the other stage takes it, so the two stages cannot drift apart.
+#
+# The `ci` stage is the checks the CI workflow `ci-checks.yml` holds. Each of its steps runs one
+# job's checks with `hecks gate_run.gate stage=ci only=<ids> --wait`, so the commands live here and
+# the workflow keeps only which job runs which ids and what each step is called;
+# spec/gate_ci_stage_spec.rb pins that every check is run by exactly one step. Select checks
+# with `only=`: several of them write generated files and compare, so the stage is not meant to
+# run whole in one checkout.
 pre_push:
   env:
     HECKS_ENVIRONMENT: memory
@@ -17,7 +27,8 @@ pre_push:
       title: rspec (parallel)
       run: [bundle, exec, parallel_rspec, spec, -n, "{workers}"]
       blocked: the suite is red.
-    - id: fuzzing
+    - &check_fuzzing
+      id: fuzzing
       title: spec/fuzzing, which the parallel run above excludes
       run: [bundle, exec, rspec, spec/fuzzing, --tag, fuzzing]
       blocked: spec/fuzzing is red.
@@ -25,31 +36,125 @@ pre_push:
       title: adapter agreement, one declared query and every engine giving the same answer
       run: [bundle, exec, rspec, spec/adapters/query_agreement_spec.rb, --tag, io]
       blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
-    - id: engine_agreement
+    - &check_engine_agreement
+      id: engine_agreement
       title: engine agreement, every declared comparator on both engines
       run: [bundle, exec, exe/hecks, conformance_run.check_engine_agreement, --wait]
       blocked: a comparator is missing a shared case or a cross-engine spec.
-    - id: model_check
+    - &check_model_check
+      id: model_check
       title: model check, unreachable states, dead transitions and orphaned handlers
       run: [bundle, exec, exe/hecks, model_check, --wait]
       blocked: the model checker found something.
-    - id: doc_coverage
+    - &check_doc_coverage
+      id: doc_coverage
       title: docs coverage, words with no running example
       run: [bundle, exec, exe/hecks, conformance_run.measure_doc_coverage, --wait]
       blocked: the language ships something undocumented; write the missing sections and examples.
-    - id: rubocop
+    - &check_rubocop
+      id: rubocop
       title: rubocop, the static style and correctness gate
       run: [bundle, exec, rubocop, -c, .rubocop.yml]
       blocked: rubocop found an offense.
-    - id: codegen_drift
+    - &check_codegen_drift
+      id: codegen_drift
       title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
       run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
       blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
-    - id: comment_style
+    - &check_comment_style
+      id: comment_style
       title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
       run: [bundle, exec, exe/hecks, style_run.check_comments, paths=lib/hecks, --wait]
       blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
-    - id: comment_blocks
+    - &check_comment_blocks
+      id: comment_blocks
       title: comment blocks, no run of comment lines past ADR 0075's cap
       run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
       blocked: a comment block ran past the cap; shorten it.
+
+# The checks `.githooks/post-commit` runs after each commit. A red one is reported and never
+# blocks the commit; pre_push runs it again as the backstop.
+post_commit:
+  env:
+    HECKS_ENVIRONMENT: memory
+  checks:
+    - *check_fuzzing
+
+# The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
+# (the `hecks-environment` action) reaches every check, as it reached each command before.
+ci:
+  checks:
+    - *check_model_check
+    - *check_engine_agreement
+    - *check_doc_coverage
+    - *check_rubocop
+    - *check_comment_style
+    - *check_comment_blocks
+    - *check_codegen_drift
+    - id: lint_deploy_recipes
+      title: generated deploy recipes, a command with no checked exit status or no echo
+      run: [bundle, exec, exe/hecks, deploy, makefile_check.lint, --wait]
+      blocked: a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen.
+    - id: fuzz
+      title: fuzz, every example domain on the Memory adapter
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, --wait]
+      blocked: a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output.
+    - id: fuzz_sqlite
+      title: fuzz on a real on-disk SQLite database
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
+      blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
+    - id: fuzz_postgres
+      title: fuzz on real Postgres, one worker (every ephemeral boot recreates the same scratch schema)
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
+      blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
+    - id: vocabulary_drift
+      title: vocabulary, the reserved-name tables regenerated must match the committed ones
+      run:
+        - sh
+        - -ec
+        - |
+          bundle exec exe/hecks language_run.project_vocabulary --confirm --wait
+          bundle exec exe/hecks language_run.project_reserved_names --confirm --wait
+          git diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs
+      blocked: a generated vocabulary file is stale; the check rewrote it, so commit the result.
+    - id: ci_gates
+      title: ci gates, the CiGate rows must match the marked regions of the workflows
+      run: [bundle, exec, exe/hecks, regeneration_run.project_ci_gates, --wait]
+      blocked: a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates --confirm`.
+    - id: tools_doc
+      title: tools doc, docs/tools.md must match the RetiredScript rows
+      run: [bundle, exec, exe/hecks, regeneration_run.project_tools_doc, --wait]
+      blocked: a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc --confirm`.
+    - id: rust_coverage
+      title: rust coverage, every generated module
+      run: [bundle, exec, exe/hecks, query, corpus_run.corpus_rust_coverage, --wait]
+      blocked: a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted.
+    - id: rust_coverage_codegen
+      title: rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta
+      run:
+        - sh
+        - -ec
+        - |
+          for module in pizzas governance identity banking meta; do
+            bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait
+          done
+      blocked: hecks-codegen generated nothing for a construct a domain declares.
+    - id: kernel_coverage
+      title: rust kernel coverage, every capability variant has a kernel file
+      run: [bundle, exec, exe/hecks, kernel_run.measure_kernel_coverage, --wait]
+      blocked: a capability's enum variant has no rust/src/kernel file behind it.
+    - id: rust_vocabulary_drift
+      title: rust vocabulary, the kernel vocab tables regenerated must match the committed ones
+      run:
+        - sh
+        - -ec
+        - |
+          bundle exec exe/hecks language_run.project_rust_vocabulary --confirm --wait
+          git diff --exit-code -- rust/src/kernel/vocab/
+          untracked="$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)"
+          if [ -n "$untracked" ]; then
+            echo "rust/src/kernel/vocab has uncommitted generated files:" >&2
+            echo "$untracked" >&2
+            exit 1
+          fi
+      blocked: the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result.

data/lib/hecks/hecks/adapters/codebase/regeneration.rb

@@ -16,7 +16,7 @@ module Hecks
       # files reports drift and writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus project_ci_gates decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_tools_doc decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -37,6 +37,7 @@ module Hecks
           check = flag.call(:check) || !flag.call(:confirm)
           child = RubyChild.new(tree)
           return project_ci_gates(child, check) if operation == "project_ci_gates"
+          return project_tools_doc(child, check) if operation == "project_tools_doc"
           return decide_ci_gate(child, held) if operation == "decide_ci_gate"
 
           result = child.capture("regen_codegen_domains", *("--check" if check))
@@ -53,6 +54,14 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale sections, when a check finds drift
+        def project_tools_doc(child, check)
+          child.answer("project_tools_doc", *("--check" if check))
+        end
+
         # @param child [RubyChild] the checkout's tool runner
         # @param held [Hash] the record's fields: `gate`, a `CiGate` row's name
         # @return [String] `touched=true` or `touched=false`

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../doors/json_door"
+
+module Hecks
+  module Adapters
+    # Gives a booted domain its first administrator through the chapter that provides
+    # `"membership"`, the way a project's hand-written bootstrap script does.
+    #
+    # The chapter names its own verbs (`provides "membership", admit:, grant:, people:`), so no
+    # aggregate is recognised by name. Both dispatches run as a caller that asserts the role the
+    # command is gated to and binds no `actor_id`: Governance checks an identified caller against
+    # its role assignments, which a domain with no administrator cannot have yet, and checks an
+    # unidentified one by comparing the role named (ADR 0025). That is the bootstrap step, and it is
+    # refused once anyone holds an administrator role, so it cannot add a second.
+    class FirstAdmin
+      # The roles that count as an administrator besides the one the grant command is gated to.
+      OWNER_ROLES = %w[Owner].freeze
+
+      # What a bootstrap did.
+      #
+      # @!attribute [r] email
+      #   @return [String] who was granted access
+      # @!attribute [r] role
+      #   @return [String] the role they now hold
+      # @!attribute [r] admitted
+      #   @return [Boolean] whether the person had to be admitted first
+      Result = Struct.new(:email, :role, :admitted, keyword_init: true) do
+        # @return [String] the sentence the verb answers with
+        def to_s = "Granted #{role} access to #{email}#{' (admitted first)' if admitted}"
+      end
+
+      # @param runtime [Hecks::Runtime] the booted domain
+      def initialize(runtime)
+        @runtime = runtime
+        @registry = runtime.registry
+      end
+
+      # Admits the person if they are not yet, then grants them a role.
+      #
+      # @param email [String] the person's email, the membership aggregate's identity
+      # @param name [String, nil] their name; the part of the email before the `@` when nil
+      # @param role [String, nil] the role to grant; the one the grant command is gated to when nil
+      # @return [Result] what was done
+      # @raise [Runtime::NotFound] when the domain has no membership chapter, the email is not an
+      #   email, or an administrator already exists
+      def call(email:, name: nil, role: nil)
+        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+        provider = membership_provider
+        verbs    = verbs_of(provider)
+        gate     = gated_role(provider, verbs.fetch(:grant))
+        people   = rows(verbs.fetch(:people))
+        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+
+        admitted = people.none? { |person| person.dig(:email, :value) == email }
+        admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
+        grant(provider, verbs.fetch(:grant), email, role || gate)
+        Result.new(email: email, role: role || gate, admitted: admitted)
+      end
+
+      private
+
+      def membership_provider
+        domain = @registry.bluebooks.values.first&.name
+        @registry.membership_provider_for(domain) or
+          raise Runtime::NotFound, "this domain attaches no chapter that provides \"membership\""
+      end
+
+      def verbs_of(provider)
+        %i[admit grant people].to_h { |key| [key, provider.provided_verb(Bluebook::Capabilities::MEMBERSHIP, key)] }
+      end
+
+      def rows(verb) = @runtime.query(verb).map { |row| Doors::JsonDoor.materialize(row) }
+
+      # The role a verb's command declares, which the dispatch must assert to be let through.
+      def gated_role(provider, verb)
+        aggregate, command = verb.split("::").last.split(".")
+        found = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
+                        &.commands&.find { |candidate| candidate.hecks_name == command }
+        found&.role&.to_s or raise Runtime::NotFound, "#{verb} declares no role to bootstrap as"
+      end
+
+      def refuse_if_administered!(people, roles)
+        held = people.select { |person| roles.map(&:downcase).include?(person.dig(:role, :value).to_s.downcase) }
+        return if held.empty?
+
+        who = held.map { |person| person.dig(:email, :value) }.join(", ")
+        raise Runtime::NotFound, "an administrator already exists (#{who}); grant roles through the " \
+                                 "domain's own #{roles.first} access instead"
+      end
+
+      def admit(provider, verb, email, name)
+        as(provider, verb) do
+          @runtime.dispatch(verb, with: { email: { value: email }, name: { value: name } })
+        end
+      end
+
+      def grant(provider, verb, email, role)
+        as(provider, verb) { @runtime.dispatch(verb, to: email, with: { role: { value: role } }) }
+      end
+
+      def as(provider, verb, &)
+        Hecks.as_caller(role: gated_role(provider, verb), &)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git.rb

@@ -60,6 +60,55 @@ module Hecks
         { report: { value: out.string } }
       end
 
+      # Checks a project's vendored packages against their `bluebook.lock` files and describes
+      # them as the manifest a client image carries, through `Hecks::EmbryonautBluebook::Manifest`.
+      #
+      # The manifest records the project's own commit and whether its tree has uncommitted changes,
+      # read from the repository the project stands in (`unknown` outside one).
+      #
+      # @param held [Hash] the `Package` query's arguments: `root` (the project; the current
+      #   directory when absent)
+      # @return [Hash{Symbol => String}] `text:` the manifest as JSON
+      # @raise [Runtime::NotFound] naming each package whose files disagree with its lock
+      def verify(**held)
+        root = File.expand_path(plain(held[:root]) || Dir.pwd)
+        raise Runtime::NotFound, "#{root} is not a directory" unless File.directory?(root)
+
+        { text: EmbryonautBluebook::Manifest.new(root, built_from: built_from(root)).to_json_text }
+      rescue EmbryonautBluebook::Manifest::Mismatch => e
+        raise Runtime::NotFound, e.message
+      end
+
+      # Judges every package of a bluebook registry against its latest release, through
+      # `Hecks::EmbryonautBluebook::Registry#check`.
+      #
+      # @param held [Hash] the `Registry` query's arguments: `root` (the registry; the current
+      #   directory when absent)
+      # @return [Hash{Symbol => String}] `text:` the notes and `versions ok`
+      # @raise [Runtime::NotFound] naming each package at fault, or when `root` is no repository
+      def check(**held)
+        report = registry(held).check
+        raise Runtime::NotFound, report.to_s unless report.ok?
+
+        { text: report.to_s }
+      rescue Vendoring::Error => e
+        raise Runtime::NotFound, e.message
+      end
+
+      # Tags a package of a bluebook registry at the version its `bluebook.yml` carries, through
+      # `Hecks::EmbryonautBluebook::Registry#release`. The tag is made in the local repository and
+      # never pushed.
+      #
+      # @param held [Hash] the `Registry` record: `package`, and `root` (the current directory when
+      #   absent)
+      # @return [Hash{Symbol => Hash}] `report:` the tag made and the command that publishes it
+      # @raise [ConsoleCapture::Failure] when the package breaks a release rule
+      def tag(**held)
+        { report: { value: registry(held).release(plain(held[:package])).to_s } }
+      rescue Vendoring::Error => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
       # Who the repository at a directory commits as: its configured name and email.
       #
       # @param chdir [String, nil] a directory inside the repository; the current one when nil
@@ -87,6 +136,16 @@ module Hecks
 
       private
 
+      def registry(held)
+        EmbryonautBluebook::Registry.new(File.expand_path(plain(held[:root]) || Dir.pwd))
+      end
+
+      def built_from(root)
+        head = capture("rev-parse", "HEAD", chdir: root)
+        status = capture("status", "--porcelain", "--", ".", chdir: root)
+        { "commit" => head.ok? ? head.out.strip : "unknown", "dirty" => status.ok? && !status.out.strip.empty? }
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
 
       # A source that is not a repository is worded here; the vendoring's own refusal for it is a

data/lib/hecks/hecks/adapters/in_process_access.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "first_admin"
+
+module Hecks
+  module Adapters
+    # What the `DomainRuntime` port's adapter does when an `Operation` asks it to give a domain its
+    # first administrator.
+    module InProcessAccess
+      # Boots the domain and grants the first administrator through its membership chapter.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the domain), `email`, and optionally
+      #   `name` and `role`
+      # @return [Hash{Symbol => Hash}] `output:` the sentence saying who now holds which role
+      # @raise [Runtime::NotFound] if the domain cannot be found or has no membership chapter, or an
+      #   administrator already exists
+      def bootstrap(**held)
+        result = FirstAdmin.new(boot(held[:subject])).call(
+          email: plain(held[:email]), name: plain(held[:name]), role: plain(held[:role])
+        )
+        output(result.to_s)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/in_process_boot.rb

@@ -9,6 +9,7 @@ require_relative "../../cli/stores"
 require_relative "../../cli/shape"
 require_relative "../../cli/history"
 require_relative "in_process_operations"
+require_relative "in_process_access"
 
 module Hecks
   module Adapters
@@ -25,6 +26,7 @@ module Hecks
     # a projection refresh, a behaviors run, a smoke test and a bounded follow.
     class InProcessBoot
       include InProcessOperations
+      include InProcessAccess
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -19,9 +19,9 @@ module Hecks
     # minutes, so it starts as a child through `ProcessPool`.
     class RustToolchain
       # The `Hecks::RustBuild` tool each ask runs.
-      TOOLS = { generate: "project_rust", wasm: "project_wasm", browser_wasm: "project_wasm_browser",
-                conform: "rust_conformance", replay: "rust_conformance_fuzz",
-                coverage: "rust_coverage" }.freeze
+      TOOLS = { generate: "project_rust", wasm: "project_wasm", host: "project_host",
+                browser_wasm: "project_wasm_browser", conform: "rust_conformance",
+                replay: "rust_conformance_fuzz", coverage: "rust_coverage" }.freeze
 
       # The load path the benchmark child runs with: this checkout's or gem's `lib/`.
       LIB = File.expand_path("../../..", __dir__)
@@ -73,6 +73,21 @@ module Hecks
         child(:wasm, [plain(held[:domain])])
       end
 
+      # Generates the domain, compiles it to a `wasm32-wasip1` module, builds the host binary from
+      # the workspace and stages the three files in a directory an image copies from.
+      #
+      # @param held [Hash] the `Build` record: `domain`, `target` (the machine's own when absent)
+      #   and `stage_dir` (`.hecks/host/<target>/` when absent)
+      # @return [Hash{Symbol => Hash}] `output:` where the files were staged
+      # @raise [ConsoleCapture::Failure] when the toolchain or the target is missing, or a step
+      #   fails
+      def host(**held)
+        argv = [plain(held[:domain])]
+        argv << "--target=#{plain(held[:target])}" if plain(held[:target])
+        argv << "--stage=#{plain(held[:stage_dir])}" if plain(held[:stage_dir])
+        child(:host, argv)
+      end
+
       # Generates the domain, then compiles it to an ES module for a browser through wasm-bindgen.
       #
       # @param held [Hash] the `Build` record: `domain`

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "console_capture"
+require_relative "shell"
 require_relative "codebase/tree"
 require_relative "codebase/ruby_child"
+require "hecks/tools"
+require "hecks/tools/site_routes"
+require "hecks/projections/site/live_edge"
 
 module Hecks
   module Adapters
@@ -44,8 +49,70 @@ module Hecks
         { output: { value: result.out } }
       end
 
+      # Compares the CloudFront behaviours a project's edge generates with a live distribution's.
+      # The live configuration is read from a saved `get-distribution-config` answer (`live`) or
+      # fetched with that one read-only call (`distribution`, the distribution's id); nothing is
+      # changed on either side.
+      #
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `live` or `distribution`,
+      #   with `expect_new` (path patterns, comma separated) and `refs` (`!Ref Name=id` words,
+      #   comma separated) when set
+      # @return [Hash{Symbol => Hash}] `output:` the report of a distribution that matches
+      # @raise [ConsoleCapture::Failure] when the project has no edge, the live configuration
+      #   cannot be read, or the two differ; the message is the report
+      def compare(**held)
+        edge = edge_of(located(:domain, held[:domain]))
+        live = live_configuration(held)
+        live_edge = Projections::Site::LiveEdge
+        comparison = live_edge.new(edge, live, expect_new: words(held[:expect_new]),
+                                               refs:       live_edge.refs_from(plain(held[:refs]))).call
+        raise ConsoleCapture::Failure, comparison.to_s unless comparison.clean?
+
+        { output: { value: comparison.to_s } }
+      end
+
       private
 
+      # The project's checked edge, read the way `project_site` reads it.
+      def edge_of(root)
+        registry = nil
+        outcome = ConsoleCapture.capture { registry = Tools::SiteRoutes.registry_for(root) }
+        raise ConsoleCapture::Failure, outcome.output.strip unless outcome.ok?
+
+        site = Projections::Site
+        chapter = site::Table.chapter(registry)
+        table = site::Table.read(chapter, registry: registry)
+        site::Edge.read(chapter, table: table, vocabulary: site::Table.vocabulary(registry)) ||
+          raise(ConsoleCapture::Failure, "#{root} declares no Edge rows")
+      rescue Projections::Site::Table::Invalid => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      def live_configuration(held)
+        file = plain(held[:live])
+        id = plain(held[:distribution])
+        text = file ? read_saved(file) : fetch(id)
+        JSON.parse(text)
+      rescue JSON::ParserError => e
+        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{e.message.lines.first.strip}"
+      end
+
+      def read_saved(path)
+        File.read(File.expand_path(path))
+      rescue SystemCallError => e
+        raise ConsoleCapture::Failure, "cannot read the live configuration: #{e.message}"
+      end
+
+      # The one AWS call: reading a distribution's configuration.
+      def fetch(id)
+        result = Shell.new.capture("aws", "cloudfront", "get-distribution-config", "--id", id.to_s)
+        return result.out if result.ok?
+
+        raise ConsoleCapture::Failure, "aws cloudfront get-distribution-config failed: #{message_of(result)}"
+      end
+
+      def words(argument) = plain(argument).to_s.split(",").map(&:strip).reject(&:empty?)
+
       def message_of(result)
         text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
         text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text

data/lib/hecks/hecks/codebase.behaviors

@@ -85,6 +85,12 @@ Hecks.behaviors "Codebase" do
     expect refused: "must match"
   end
 
+  test "ProjectToolsDoc refuses a run that is not named" do
+    tests "ProjectToolsDoc", on: "RegenerationRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
   test "DecideCiGate refuses a run that is not named" do
     tests "DecideCiGate", on: "RegenerationRun"
     input run: { value: "" }, gate: { value: "runtime_changed" }

data/lib/hecks/hecks/codebase.bluebook

@@ -1027,6 +1027,22 @@ Hecks.bluebook "Hecks" do
       emits ProjectCiGatesRequested
     end
 
+    command "ProjectToolsDoc" do
+      role "Maintainer"
+      goal "Write the launcher forms of docs/tools.md from the RetiredScript rows, or with check only compare them"
+
+      attribute :check,   Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_tools_doc"
+
+      emits ProjectToolsDocRequested
+    end
+
     command "DecideCiGate" do
       role "Maintainer"
       goal "Say whether this run's change touches what a CiGate row guards, as the gated job's detector"
@@ -1105,6 +1121,11 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectToolsDocRequested" do
+    on      "RegenerationRun.ProjectToolsDocRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "ExamineWhenDecideCiGateRequested" do
     on      "RegenerationRun.DecideCiGateRequested"
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }