hecks 5.0.0 → 7.0.0

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -3,6 +3,7 @@ Hecks.bluebook "Bluebook" do
     # Closed sets the language admits, projected into matching Ruby and Rust
     # tables (hecks project_vocabulary, hecks project_rust_vocabulary) so both runtimes agree.
     description "The closed sets the language admits — the whole of what any runtime may accept, declared once."
+    acknowledges :no_command_surface, "the closed sets are declared once and projected into both runtimes; nothing changes them at runtime"
 
     # Named only by itself; a vocabulary hangs under nothing else.
     identified_by VocabularyName, as: :name
@@ -112,10 +113,34 @@ Hecks.bluebook "Bluebook" do
       attribute :name, String, one_of: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "contains", "none_in_state"]
     end
 
+    # A read model's reducers as algebra (ADR 0126): `identity` is the answer over no rows
+    # (JSON text), `combine` folds two partial answers into one, `inverse` takes one partial
+    # answer back out ("" where none exists). `collect` means partial answers do not combine:
+    # the whole must be recomputed from the rows. Ruby's ReadModelInterpreter::Reductions and
+    # Rust's kernel::read_model answer an empty collection from `identity`; the fuzzer folds a
+    # grouped answer's leaves by `combine` and compares it with the ungrouped reduction.
+    value_object "Reducer" do
+      attribute :name,     String
+      attribute :identity, String
+      attribute :combine,  String
+      attribute :inverse,  String
+
+      member name: "count",      identity: "0",     combine: "add",     inverse: "subtract"
+      member name: "sum",        identity: "0",     combine: "add",     inverse: "subtract"
+      member name: "avg",        identity: "null",  combine: "collect", inverse: ""
+      member name: "min",        identity: "null",  combine: "min",     inverse: ""
+      member name: "max",        identity: "null",  combine: "max",     inverse: ""
+      member name: "median",     identity: "null",  combine: "collect", inverse: ""
+      member name: "percentile", identity: "null",  combine: "collect", inverse: ""
+      member name: "any",        identity: "false", combine: "or",      inverse: ""
+      member name: "all",        identity: "true",  combine: "and",     inverse: ""
+    end
+
     # Adapters::Driven::Folder::DOMAIN_ORDER — declarations load in this order
     value_object "LoadOrder" do
       attribute :glob, String,
-                one_of: ["*.port", "*.adapter", "*.bluebook", "translations/*.bluebook", "*.hecksagon", "*.world"]
+                one_of: ["*.port", "*.adapter", "*.bluebook", "translations/*.bluebook", "*.hecksagon", "*.world",
+                         "*.contextmap"]
     end
 
     # The order CommandInterpreter#call follows, ending at the events it
@@ -158,11 +183,79 @@ Hecks.bluebook "Bluebook" do
                          "RemoteRefusal", "TypeMismatch", "Unauthorized", "UnknownArgument", "UnknownVerb"]
     end
 
+    # The sorts of no an adapter answers differently.
+    value_object "RefusalKind" do
+      attribute :name, String, one_of: ["refused", "not_found", "unauthorized", "absent_argument"]
+    end
+
+    # The points of a command's dispatch a refusal can come from, in the order they run.
+    value_object "DispatchStage" do
+      attribute :name, String,
+                one_of: ["request", "arguments", "role", "references", "state", "givens", "ensures", "invariants",
+                         "remote"]
+    end
+
+    # Which stage each dispatch step belongs to, for the aggregate and entity orders alike. A
+    # validation runs the steps in order and, once a step of one stage has refused, finishes that
+    # stage and goes no further: a later stage reads what an earlier one settled, so its answer
+    # would mean nothing.
+    value_object "StepStage" do
+      attribute :step,  String
+      attribute :stage, String, admits: "Vocabulary::DispatchStage"
+
+      member step: "decode_arguments", stage: "arguments"
+      member step: "refuse_unknown_arguments", stage: "arguments"
+      member step: "refuse_absent_arguments", stage: "arguments"
+      member step: "normalize_args", stage: "arguments"
+      member step: "refuse_role_mismatch", stage: "role"
+      member step: "resolve_references", stage: "references"
+      member step: "hydrate", stage: "state"
+      member step: "hydrate_parent", stage: "state"
+      member step: "locate_element", stage: "state"
+      member step: "enforce_givens", stage: "givens"
+      member step: "admissible_transition", stage: "state"
+      member step: "assign_creation_attributes", stage: "state"
+      member step: "apply_mutations", stage: "state"
+      member step: "advance_lifecycle", stage: "state"
+      member step: "delegate_to_entity", stage: "state"
+      member step: "enforce_ensures", stage: "ensures"
+      member step: "enforce_invariants", stage: "invariants"
+      member step: "save", stage: "state"
+      member step: "emit", stage: "state"
+    end
+
+    # What sort of no each DomainRefusal is, and the dispatch stage it comes from. A driving
+    # adapter answers by `kind` (a missing record or a missing role differently from a rule that
+    # did not hold); a validation reports `stage` so a client knows how far the command got. A
+    # raise site may name a narrower stage (a reference that does not resolve is a NotFound
+    # in the `references` stage). Read through `Hecks::Refused#kind` and `#stage`.
+    value_object "RefusalClass" do
+      attribute :name,    String, admits: "Vocabulary::DomainRefusal"
+      attribute :kind,    String, admits: "Vocabulary::RefusalKind"
+      attribute :stage,   String, admits: "Vocabulary::DispatchStage"
+
+      member name: "AbsentArgument", kind: "absent_argument", stage: "arguments"
+      member name: "AlreadyExists", kind: "refused", stage: "state"
+      member name: "AttributeAbsent", kind: "refused", stage: "state"
+      member name: "EnsuresNotMet", kind: "refused", stage: "ensures"
+      member name: "GivenNotMet", kind: "refused", stage: "givens"
+      member name: "InvariantViolation", kind: "refused", stage: "invariants"
+      member name: "LifecycleRefused", kind: "refused", stage: "state"
+      member name: "NothingToCorrect", kind: "refused", stage: "state"
+      member name: "NotFound", kind: "not_found", stage: "state"
+      member name: "ProjectionAbsent", kind: "refused", stage: "state"
+      member name: "RemoteRefusal", kind: "refused", stage: "remote"
+      member name: "TypeMismatch", kind: "refused", stage: "arguments"
+      member name: "Unauthorized", kind: "unauthorized", stage: "role"
+      member name: "UnknownArgument", kind: "refused", stage: "arguments"
+      member name: "UnknownVerb", kind: "refused", stage: "request"
+    end
+
     # The wording for every DomainRefusal site not already carried by data
     # (given/ensures/invariant already describe themselves). Language-level
     # and the same for every domain, so it is declared here and projected
     # into Runtime::RefusalWording (Ruby) / kernel::vocab::RefusalSite (Rust)
-    # rather than read live off this chapter at every call.
+    # rather than read live off this bluebook at every call.
     #
     # `{name}` markers are plain text substitution, not expression syntax —
     # a template is read, never evaluated. Two call sites that raise the
@@ -253,7 +346,7 @@ Hecks.bluebook "Bluebook" do
       member refusal: "InvariantViolation", site: "admits_declared_set",
              template: "{name} admits {admits} — {admitted} — got {offered}"
       member refusal: "InvariantViolation", site: "undeclared_set",
-             template: "{name} admits {admits}, which this chapter does not declare — a closed set is named " \
+             template: "{name} admits {admits}, which this bluebook does not declare — a closed set is named " \
                        "Aggregate::SetName, and it must be one the bluebook actually holds"
       # ADR 0061 decision D1: a group_by leaf holds one row, so two rows
       # reaching the same full key path refuse at dispatch rather than one
@@ -606,7 +699,7 @@ Hecks.bluebook "Bluebook" do
     # per row, answering `touched` from the diff of the change against its base.
     # hecks project_ci_gates writes each row into the marked region of its
     # `workflow` (.github/workflows/<workflow>), and the job it writes runs
-    # `hecks decide_ci_gate gate=<name>`, which makes the decision from the row.
+    # `hecks RegenerationRun.decide_ci_gate! gate=<name>`, which makes the decision from the row.
     #
     # `mode` is how `pattern` (an extended regex over changed paths) decides:
     # `touches` runs the job when any changed path matches, `skips_unless` runs it
@@ -655,9 +748,291 @@ Hecks.bluebook "Bluebook" do
       member path: "packages/hecks-client/package-lock.json", lines: "^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"
     end
 
+    # The checks a stage holds a change against before it is let through. `hecks gate_run.gate!`
+    # reads these rows, the git pre-push hook calls it, and the `ci` stage's checks are the ones
+    # `.github/workflows/ci-checks.yml` runs, so the list of checks lives here and nowhere else.
+
+    # A check is one command run from the repository root, all of a stage's checks at once:
+    # `name` is the row's key, which a `GateStage` lists; `id` is the name the check is reported and
+    # selected by (`only=a,b`), and the same `id` may name a different command in another stage;
+    # `title` is the heading its output is printed under; `argv` is the program and its arguments,
+    # separated by single spaces, with `{workers}` standing for half the machine's cores, at least
+    # one; `script` is a shell script run as `sh -ec` instead, when `argv` is empty; `blocked` is what
+    # a red check means and what to do about it.
+    #
+    # `runs_in` says where a check runs. `ci` marks a check that only CI runs: no local stage may
+    # list it, and the owner's decision is that the full spec suite runs in CI on production. Empty
+    # means a local stage may list the check.
+    value_object "GateCheck" do
+      attribute :name, String
+      attribute :id, String
+      attribute :title, String
+      attribute :argv, String
+      attribute :script, String
+      attribute :blocked, String
+      attribute :runs_in, String
+
+      member name: "rspec", id: "rspec",
+             title: "rspec (parallel)",
+             runs_in: "ci",
+             argv: "",
+             script: "# Workers are grouped by this machine's own last timings, kept under the git directory\n# (shared by every worktree, never committed). CI's committed baseline leaves out the io\n# specs this run includes, so it only seeds the first run; each run then rewrites the log.\nlog=\"$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log\"\n[ -f \"$log\" ] || cp .github/rspec_runtime_baseline.log \"$log\"\nbundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log \"$log\" --allowed-missing 100 \\\n  -o \"--format progress --format ParallelTests::RSpec::RuntimeLogger --out $log\"\n",
+             blocked: "the suite is red."
+      member name: "fuzzing", id: "fuzzing",
+             title: "spec/fuzzing, which the parallel run above excludes",
+             argv: "bundle exec rspec spec/fuzzing --tag fuzzing",
+             script: "",
+             blocked: "spec/fuzzing is red."
+      member name: "query_agreement", id: "query_agreement",
+             title: "adapter agreement, one declared query and every engine giving the same answer",
+             argv: "bundle exec rspec spec/adapters/query_agreement_spec.rb --tag io",
+             script: "",
+             blocked: "the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which."
+      member name: "engine_agreement", id: "engine_agreement",
+             title: "engine agreement, every declared comparator on both engines",
+             argv: "bundle exec exe/hecks conformance_run.check_engine_agreement! --wait",
+             script: "",
+             blocked: "a comparator is missing a shared case or a cross-engine spec."
+      member name: "shape_ledger", id: "shape_ledger",
+             title: "shape ledger, every bluebook's storage shape held by the ledger or reached by a translation edge",
+             argv: "bundle exec exe/hecks conformance_run.check_shape_ledger! --wait",
+             script: "",
+             blocked: "a bluebook's storage shape moved with no translation edge from the shape the ledger holds; the failure prints the edge to commit. A change that only adds is settled in one step with `hecks conformance_run.check_shape_ledger! --confirm --additive --wait`, which writes the empty edge and moves the ledger; a change that renames or reshapes data needs rules first."
+      member name: "model_check", id: "model_check",
+             title: "model check, unreachable states, dead transitions and orphaned handlers",
+             argv: "bundle exec exe/hecks ModelCheckRun.model_check! --wait",
+             script: "",
+             blocked: "the model checker found something."
+      member name: "doc_coverage", id: "doc_coverage",
+             title: "docs coverage, words with no running example",
+             argv: "bundle exec exe/hecks conformance_run.measure_doc_coverage! --wait",
+             script: "",
+             blocked: "the language ships something undocumented; write the missing sections and examples."
+      member name: "rubocop", id: "rubocop",
+             title: "rubocop, the static style and correctness gate",
+             argv: "bundle exec rubocop -c .rubocop.yml",
+             script: "",
+             blocked: "rubocop found an offense."
+      member name: "codegen_drift", id: "codegen_drift",
+             title: "codegen drift, rust/src/generated/ must match a fresh regeneration",
+             argv: "bundle exec exe/hecks regeneration_run.regenerate_corpus! --check --wait",
+             script: "",
+             blocked: "regenerating hits a diff. The whole generated tree is committed, so run `hecks regeneration_run.regenerate_corpus! --confirm` and commit what it changed."
+      member name: "comment_style", id: "comment_style",
+             title: "comment style, every comment under lib/hecks and spec against docs/COMMENT_STYLE_GUIDE.md",
+             argv: "bundle exec exe/hecks style_run.check_comments! paths=lib/hecks spec --wait",
+             script: "",
+             blocked: "a comment breaks the style guide, such as a line past 100 characters; `hecks StyleRun.fix_comments!` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check."
+      member name: "comment_blocks", id: "comment_blocks",
+             title: "comment blocks, no run of comment lines past ADR 0075's cap",
+             argv: "bundle exec exe/hecks style_run.check_comments! paths=lib,spec,examples only=long_block --wait",
+             script: "",
+             blocked: "a comment block ran past the cap; shorten it."
+      member name: "command_names", id: "command_names",
+             title: "command names, every launcher name a workflow, hook, gate row, spec or guide invokes still resolves",
+             argv: "bundle exec exe/hecks conformance_run.check_command_names! --wait",
+             script: "",
+             blocked: "a file invokes a launcher name the launcher no longer accepts (a renamed command, or a write without its !), so what runs it runs nothing. The failure names each file:line and the nearest valid name. Mark an invocation that is shown and not run with `dead-name-check: skip` on its line or the one before, a fence with `skip`, `historical` or `illustrative` after its language, or a whole page with `dead-name-check: skip-file` in its first lines."
+      member name: "workflow_pagination", id: "workflow_pagination",
+             title: "workflow pagination, no step counts or waits for GitHub list items from the first page alone",
+             argv: "bundle exec exe/hecks conformance_run.check_workflow_pagination! --wait",
+             script: "",
+             blocked: "a workflow step counts or waits for the items of a list call (artifacts, runs, jobs, issues, releases, pulls, commits) and reads only the first 30. Add --paginate and count the lines it prints, or filter the path with ?name=."
+      member name: "secret_output", id: "secret_output",
+             title: "secret output, no value a world hands an adapter as a secret reaches what a launcher prints",
+             argv: "bundle exec rspec spec/secret_output_spec.rb",
+             script: "",
+             blocked: "a declared secret, or a database URL's password, reached a refusal, a note or a result. Hold it through `Hecks::Secrets` where the world hands it over, and print through a guarded stream."
+      member name: "adapter_words", id: "adapter_words",
+             title: "adapter words, no domain name equal to a technology word the adapters are named for",
+             argv: "bundle exec rspec spec/adapter_words_spec.rb",
+             script: "",
+             blocked: "a domain name (a module, aggregate, command or query) equals a technology word listed in lib/hecks/hecks/adapter_words.json. The failure names each one; rename the domain name, not the adapter."
+      member name: "rust_fmt", id: "rust_fmt",
+             title: "rustfmt, every Rust crate laid out as `cargo fmt` would",
+             argv: "",
+             script: "# The main crate's generated modules are not committed, so cargo fmt would stop at a\n# missing file on a fresh checkout; its hand-written entry points are named instead.\nrustfmt --check --edition 2021 rust/src/main.rs rust/src/kernel/mod.rs rust/tests/*.rs\nfor crate in parser codegen lsp host web build; do\n  cargo fmt --check --manifest-path \"rust/$crate/Cargo.toml\"\ndone\n",
+             blocked: "a Rust file is not laid out as rustfmt has it; run `cargo fmt` in its crate (rust/src/exemplar is exempt, it is text templates). Generated Rust is laid out by its generators, so fix the generator, not the output."
+      member name: "rust_io", id: "rust_io",
+             title: "rust io specs, conformance, coercion, has_many, semantics corpus, corpus regeneration and feature exclusivity",
+             argv: "",
+             script: "# Building the banking crate makes banking the default feature and rewrites the module\n# list, both tracked. They are put back on the way out, and the check will not start over\n# a person's uncommitted edits to them.\nrewritten=\"rust/Cargo.toml rust/src/generated/mod.rs\"\nif [ -n \"$(git status --porcelain -- $rewritten)\" ]; then\n  echo \"uncommitted changes in $rewritten; commit or discard them first\" >&2\n  exit 1\nfi\ntrap 'git checkout -q -- $rewritten' EXIT\nenv -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus! --confirm --wait\nbundle exec exe/hecks build.project_rust! domain=examples/banking --wait\nbundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb\nbundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb\nbundle exec rspec --tag io --profile 8 spec/rust_build_regeneration_order_spec.rb spec/rust_build_regeneration_subset_spec.rb\n",
+             blocked: "a Rust io spec failed, or skipped; the crate it built is under rust/target."
+      member name: "ci_codegen_drift", id: "codegen_drift",
+             title: "codegen drift, the committed generated Rust must match the regeneration this job holds",
+             argv: "git diff --exit-code --stat -- rust/src/generated rust/Cargo.toml",
+             script: "",
+             blocked: "regenerating hits a diff. The whole generated tree is committed, so run `hecks regeneration_run.regenerate_corpus! --confirm` and commit what it changed."
+      # The rspec shards each hold only the domains they read, so the examples that read the whole
+      # generated tree are tagged `generated_all` and left out of them. This job holds every domain.
+      member name: "generated_tree", id: "generated_tree",
+             title: "whole-tree specs, the examples tagged generated_all against every domain's generated Rust",
+             argv: "bundle exec rspec --tag generated_all",
+             script: "",
+             blocked: "a spec that reads the whole generated tree failed; run `hecks regeneration_run.regenerate_corpus! --confirm` to materialize every domain, then `bundle exec rspec --tag generated_all`."
+      member name: "rust_clippy", id: "rust_clippy",
+             title: "clippy, every Rust crate with its warnings as errors",
+             argv: "",
+             script: "for crate in . parser codegen lsp host web build; do\n  cargo clippy --all-targets --manifest-path \"rust/$crate/Cargo.toml\" -- -D warnings\ndone\n",
+             blocked: "clippy found a warning in a Rust crate, under the strict `[lints.clippy]` table of its Cargo.toml. The main crate needs rust/src/generated, so run `hecks regeneration_run.regenerate_corpus! --confirm` first on a fresh checkout. Fix the code, or allow a lint at the one site with a line saying why; a warning in generated Rust is fixed in its generator."
+      member name: "lint_deploy_recipes", id: "lint_deploy_recipes",
+             title: "generated deploy recipes, a command with no checked exit status or no echo",
+             argv: "bundle exec exe/hecks deploy MakefileCheck.lint! --wait",
+             script: "",
+             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."
+      # The fuzz sweeps run as three shards each, one CI job leg apiece, so the corpus is swept in
+      # a third of the time. No unsharded row stays: no stage but `ci` ran the whole sweep, and a
+      # person who wants one run of it types `hecks fuzz_run.fuzz! --wait`. A shard is `shard=I/N`,
+      # and the matrix legs of `checks_fuzz` and `checks_fuzz_sqlite` in ci-checks.yml number 1 to
+      # N, which spec/ci_fuzz_shards_spec.rb holds to the N written here.
+      member name: "fuzz_1_of_3", id: "fuzz_1_of_3",
+             title: "fuzz, shard 1 of 3 of the example domains on the Memory adapter",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! shard=1/3 --wait",
+             script: "",
+             blocked: "a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."
+      member name: "fuzz_2_of_3", id: "fuzz_2_of_3",
+             title: "fuzz, shard 2 of 3 of the example domains on the Memory adapter",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! shard=2/3 --wait",
+             script: "",
+             blocked: "a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."
+      member name: "fuzz_3_of_3", id: "fuzz_3_of_3",
+             title: "fuzz, shard 3 of 3 of the example domains on the Memory adapter",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! shard=3/3 --wait",
+             script: "",
+             blocked: "a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."
+      member name: "fuzz_sqlite_1_of_3", id: "fuzz_sqlite_1_of_3",
+             title: "fuzz, shard 1 of 3 on a real on-disk SQLite database",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=1/3 --wait",
+             script: "",
+             blocked: "the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."
+      member name: "fuzz_sqlite_2_of_3", id: "fuzz_sqlite_2_of_3",
+             title: "fuzz, shard 2 of 3 on a real on-disk SQLite database",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=2/3 --wait",
+             script: "",
+             blocked: "the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."
+      member name: "fuzz_sqlite_3_of_3", id: "fuzz_sqlite_3_of_3",
+             title: "fuzz, shard 3 of 3 on a real on-disk SQLite database",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! adapter=sqlite seeds=6 shard=3/3 --wait",
+             script: "",
+             blocked: "the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."
+      member name: "fuzz_shards", id: "fuzz_shards",
+             title: "fuzz shards, the three shards together hold every domain of the sweep once",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! list_shards=3 --wait",
+             script: "",
+             blocked: "the split of the fuzz sweep into three shards drops or repeats a domain, or cannot be listed; a shard would then sweep less than the sweep it stands for. Read the refusal, and fix lib/hecks/tools/fuzz_sweep/shards.rb or the cost table spec/fuzzing/fuzz_runtime_baseline.log."
+      # The Postgres sweep is two legs of its own, a runner and a database apiece: it is the slowest
+      # sweep, since every dispatch is a real round trip.
+      member name: "fuzz_postgres_1_of_2", id: "fuzz_postgres_1_of_2",
+             title: "fuzz, shard 1 of 2 on real Postgres (each run in its own scratch schema)",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! adapter=postgres seeds=3 steps=20 shard=1/2 --wait",
+             script: "",
+             blocked: "the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD."
+      member name: "fuzz_postgres_2_of_2", id: "fuzz_postgres_2_of_2",
+             title: "fuzz, shard 2 of 2 on real Postgres (each run in its own scratch schema)",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz! adapter=postgres seeds=3 steps=20 shard=2/2 --wait",
+             script: "",
+             blocked: "the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD."
+      member name: "vocabulary_drift", id: "vocabulary_drift",
+             title: "vocabulary, the reserved-name tables regenerated must match the committed ones",
+             argv: "",
+             script: "bundle exec exe/hecks language_run.project_vocabulary! --confirm --wait\nbundle exec exe/hecks language_run.project_reserved_names! --confirm --wait\ngit diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs\n",
+             blocked: "a generated vocabulary file is stale; the check rewrote it, so commit the result."
+      member name: "ci_gates", id: "ci_gates",
+             title: "ci gates, the CiGate rows must match the marked regions of the workflows",
+             argv: "bundle exec exe/hecks regeneration_run.project_ci_gates! --wait",
+             script: "",
+             blocked: "a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates! --confirm`."
+      member name: "ci_pipeline", id: "ci_pipeline",
+             title: "ci pipeline, the workflow rows must match the files they project",
+             argv: "bundle exec exe/hecks regeneration_run.project_ci_pipeline! --wait",
+             script: "",
+             blocked: "a workflow row changed with no projection, or a projected workflow was edited by hand; run `hecks regeneration_run.project_ci_pipeline! --confirm`."
+      member name: "tools_doc", id: "tools_doc",
+             title: "tools doc, docs/tools.md must match the RetiredScript rows",
+             argv: "bundle exec exe/hecks regeneration_run.project_tools_doc! --wait",
+             script: "",
+             blocked: "a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc! --confirm`."
+      member name: "rust_coverage", id: "rust_coverage",
+             title: "rust coverage, every generated module",
+             argv: "bundle exec exe/hecks query corpus_run.corpus_rust_coverage --wait",
+             script: "",
+             blocked: "a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted."
+      member name: "rust_coverage_codegen", id: "rust_coverage_codegen",
+             title: "rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta",
+             argv: "",
+             script: "for module in pizzas governance identity banking meta; do\n  bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait\ndone\n",
+             blocked: "hecks-codegen generated nothing for a construct a domain declares."
+      member name: "kernel_coverage", id: "kernel_coverage",
+             title: "rust kernel coverage, every capability variant has a kernel file",
+             argv: "bundle exec exe/hecks kernel_run.measure_kernel_coverage! --wait",
+             script: "",
+             blocked: "a capability's enum variant has no rust/src/kernel file behind it."
+      member name: "rust_vocabulary_drift", id: "rust_vocabulary_drift",
+             title: "rust vocabulary, the kernel vocab tables regenerated must match the committed ones",
+             argv: "",
+             script: "bundle exec exe/hecks language_run.project_rust_vocabulary! --confirm --wait\ngit diff --exit-code -- rust/src/kernel/vocab/\nuntracked=\"$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)\"\nif [ -n \"$untracked\" ]; then\n  echo \"rust/src/kernel/vocab has uncommitted generated files:\" >&2\n  echo \"$untracked\" >&2\n  exit 1\nfi\n",
+             blocked: "the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result."
+    end
+
+    # The stages of the gate: the `checks` a stage runs, as a comma list of `GateCheck` names in
+    # the order they are reported. `env` is `NAME=value` words set only where the caller has not set
+    # the name: 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. `HECKS_PROCESS_SPECS` keeps the examples tagged `process` (they
+    # start child processes, so a plain `rspec` leaves them out) in the suite `ci_suite` runs.
+
+    # `ci_suite` is the full spec suite. It is a `runs_in: "ci"` check: CI runs it on production, and
+    # no local stage, hook or push lists it. Owner decision: nobody runs the full suite locally; a
+    # change is checked locally by the quick gate, RuboCop, the shape ledger and the specs named for
+    # that change. A person runs `ci_suite` by hand only by asking for it.
+    #
+    # `quick` is what every push of `main` runs, and what a commit should have passed: the checks
+    # that finish in seconds and that only the author can fix cheaply (a storage shape with no edge,
+    # a style offense, a comment past the guide, a leaked secret, a syntax error RuboCop reads).
+    # Everything slower runs after the push, in CI (`ci`, `ci_suite`) and the nightly run, and holds
+    # `stable`, not `main`. `pre_push` is the whole suite for a person who asks for it
+    # (`full_gate.value=true`). `rust_io` is the Rust io specs
+    # `ci-rust-io.yml` runs in its `rspec_rust_io` job, for a push that wants their answer first; no
+    # hook or workflow runs it. `ci` is the checks `ci-checks.yml` runs, each step with
+    # `hecks gate_run.gate! stage=ci only=<ids> --wait`; several of them write generated files and
+    # compare, so the stage is not meant to run whole in one checkout.
+    value_object "GateStage" do
+      attribute :name, String
+      attribute :env, String
+      attribute :checks, String
+
+      member name: "pre_push", env: "HECKS_ENVIRONMENT=memory HECKS_PROCESS_SPECS=1", checks: "fuzzing,query_agreement,engine_agreement,shape_ledger,model_check,doc_coverage,rubocop,codegen_drift,comment_style,comment_blocks,rust_fmt"
+      member name: "ci_suite", env: "HECKS_ENVIRONMENT=memory HECKS_PROCESS_SPECS=1", checks: "rspec"
+      member name: "quick", env: "HECKS_ENVIRONMENT=memory", checks: "shape_ledger,rubocop,comment_style,comment_blocks,secret_output,adapter_words"
+      member name: "rust_io", env: "CI=true HECKS_ENVIRONMENT=memory", checks: "rust_io"
+      member name: "ci", env: "", checks: "model_check,shape_ledger,engine_agreement,doc_coverage,rubocop,comment_style,comment_blocks,ci_codegen_drift,generated_tree,rust_fmt,rust_clippy,lint_deploy_recipes,command_names,workflow_pagination,fuzz_1_of_3,fuzz_2_of_3,fuzz_3_of_3,fuzz_sqlite_1_of_3,fuzz_sqlite_2_of_3,fuzz_sqlite_3_of_3,fuzz_postgres_1_of_2,fuzz_postgres_2_of_2,fuzz_shards,vocabulary_drift,ci_gates,ci_pipeline,tools_doc,rust_coverage,rust_coverage_codegen,kernel_coverage,rust_vocabulary_drift"
+    end
+
+    # What a push rehearsal runs, as data `GitRehearsal::Stages` reads. A `RehearsalStage` is one
+    # step: `kind` is `gate` (the `GateStage` named by `argument` runs) or `impacted` (the specs
+    # the push's changes touch, capped by the local spec limit). A `RehearsalScope` lists, in the order they run, the steps a rehearsal of
+    # that scope runs. `quick` is what a landing asks for and the train's push gate; `deep` adds the
+    # impacted specs and runs only when asked for (`scope.value=deep`). Owner decision: the full
+    # spec suite runs only in CI, so no scope runs it and only `deep` runs any impacted specs.
+    value_object "RehearsalStage" do
+      attribute :name, String
+      attribute :kind, String
+      attribute :argument, String
+
+      member name: "quick", kind: "gate", argument: "quick"
+      member name: "impacted", kind: "impacted", argument: ""
+    end
+
+    value_object "RehearsalScope" do
+      attribute :name, String
+      attribute :stages, String
+
+      member name: "quick", stages: "quick"
+      member name: "deep", stages: "quick,impacted"
+    end
+
     # The checks a commit must have passed before a `Promotion` moves it onto a guarded lane. Each
     # is the name of a job in .github/workflows that reports to a commit as a check run; a check
-    # that a path gate skipped reports `skipped`, which counts as passed. `hecks promote` reads
+    # that a path gate skipped reports `skipped`, which counts as passed. `hecks PromotionRun.promote!` reads
     # these rows, and hecks project_lanes writes them into the ruleset of any lane that requires
     # them, so the list lives here and nowhere else.
     #
@@ -682,7 +1057,7 @@ Hecks.bluebook "Bluebook" do
     # The branches a change travels along. `main` takes pushes with no gate; `stable` takes only
     # what a `Promotion` moves onto it once every `CiGate` check is green on that commit.
     # hecks project_lanes writes each row's ruleset into .github/rulesets/<name>.json, and
-    # `hecks promote` reads `follows` to know which lane a promotion fast-forwards.
+    # `hecks PromotionRun.promote!` reads `follows` to know which lane a promotion fast-forwards.
     #
     # `guarded` says whether a ruleset restricts the branch. `pushers` says what it takes: `anyone`
     # (any commit), or `green` (only a commit on which every `RequiredCheck` has already passed,
@@ -710,7 +1085,7 @@ Hecks.bluebook "Bluebook" do
     end
 
     # A binary hecks builds once per change to its crate and publishes, so a client that needs the
-    # same binary downloads it instead of compiling it (ADR 0110). `hecks regeneration_run.project_lanes`
+    # same binary downloads it instead of compiling it (ADR 0110). `hecks regeneration_run.project_lanes!`
     # writes .github/workflows/publish-<name>.yml from each row; `Hecks::RustBuild::PrebuiltBinary`
     # reads the same rows to name what to download.
     #
@@ -720,6 +1095,8 @@ Hecks.bluebook "Bluebook" do
     # GitHub-hosted image it is built on, pinned (never `-latest`) because a binary links the
     # runner's glibc and must run on every host that runs that image or a newer one.
     # The release is tagged `<name>-<key>` and carries `<executable>-<target>` and its `.sha256`.
+    # A crate can have one row a target; a build takes the row for its crate and target. The arm64
+    # host builds on Ubuntu 22.04 (glibc 2.35) so it runs in a Debian bookworm (glibc 2.36) image.
     value_object "PrebuiltBinary" do
       attribute :name,   String
       attribute :crate,  String
@@ -729,12 +1106,14 @@ Hecks.bluebook "Bluebook" do
 
       member name: "host", crate: "rust/host", executable: "bootstrap", target: "x86_64-unknown-linux-gnu",
              runner: "ubuntu-24.04"
+      member name: "host-arm64", crate: "rust/host", executable: "bootstrap", target: "aarch64-unknown-linux-gnu",
+             runner: "ubuntu-22.04-arm"
     end
 
     # The dials of the hecks_qa loop: what each is called, the type of value it takes and what it
     # does. qa/settings.yml holds the values, which are edited and reviewed as a diff; this table
     # holds the rest, so the loader (`Hecks::Fuzzing::QaSettings`) checks the file against it and
-    # the QualityControl chapter reads each value as a constant (`QualityControlDials::PR_CAP_PER_DAY`
+    # the QualityControl bluebook reads each value as a constant (`QualityControlDials::PR_CAP_PER_DAY`
     # for `pr_cap_per_day`) without a second list of the names or their types. `type` is Integer,
     # Numeric (an Integer or a Float), Boolean, String, Array or Hash. A dial's nested shape, where it
     # has one, is checked by the loader.
@@ -746,7 +1125,7 @@ Hecks.bluebook "Bluebook" do
       member name: "cadence_seconds", type: "Integer",
              meaning: "Minimum gap in seconds between one tick's report and the next dispatch; 0 is immediately. Read by the `/loop hecks_qa` caller, not by any script."
       member name: "pr_cap_per_day", type: "Integer",
-             meaning: "Most PRs (Patch plus Improvement) `hecks quality_control patch.open` opens per calendar day; 0 is uncapped."
+             meaning: "Most PRs (Patch plus Improvement) `hecks quality_control Patch.open!` opens per calendar day; 0 is uncapped."
       member name: "widening_tiers", type: "Array",
              meaning: "Fuzz depth by `Target.clean_streak`, in three discrete tiers, read by `SweepDepth.for_streak`. The last row (`upto: Float::INFINITY`) is the ceiling."
       member name: "sweep_max_parallel", type: "Integer",
@@ -754,9 +1133,9 @@ Hecks.bluebook "Bluebook" do
       member name: "liveness_fallback_seconds", type: "Integer",
              meaning: "How long the `/loop hecks_qa` caller waits for a tick's report before assuming it stalled."
       member name: "draft_only", type: "Boolean",
-             meaning: "Whether `hecks quality_control patch.open` opens its PR as a draft; false opens it ready for review."
+             meaning: "Whether `hecks quality_control Patch.open!` opens its PR as a draft; false opens it ready for review."
       member name: "auto_merge", type: "Boolean",
-             meaning: "Whether `hecks quality_control patch.open` queues the PR for auto-merge once it is open."
+             meaning: "Whether `hecks quality_control Patch.open!` queues the PR for auto-merge once it is open."
       member name: "adversarial_fraction", type: "Numeric",
              meaning: "Fraction (0.0..1.0) of generated command steps mutated adversarially; 0 turns the layer off. Higher finds refusal-ordering splits sooner but reaches deep state less often."
       member name: "guided_generation", type: "Boolean",
@@ -795,8 +1174,24 @@ Hecks.bluebook "Bluebook" do
              meaning: "Whether generated domains are also compared against a compiled Rust binary built in a scratch copy."
       member name: "generated_domain_seeds", type: "Integer",
              meaning: "Generated sequences run per generated domain."
+      member name: "mutation_files", type: "Array",
+             meaning: "Rust files `hecks quality_control target.mutate --from-dials` mutates, and so the files one `hecks quality_control sweep.tick` mutation-tests after the generated domains; empty skips the step."
+      member name: "mutation_equivalent", type: "Array",
+             meaning: "Mutants that behave the same as the original code, by the name `cargo mutants --list` gives them without the file and line; never run, so they cannot be reported as survivors."
       member name: "structural_refusal_boundary", type: "Array",
              meaning: "Construct families a skipped query verb may belong to. A skip inside the list is logged Held, one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a family here is declared by no committed manifest."
+      member name: "red_main_check", type: "Boolean",
+             meaning: "Whether each `hecks quality_control sweep.tick` runs the quick gate on local main as its last finding step, logging each red check as a bug and fixing the self-contained ones; false skips the step."
+      member name: "event_pump", type: "Boolean",
+             meaning: "Whether each `hecks quality_control sweep.tick` runs the event pump as its last step: each attached domain's policies react to the events past their cursors, and every refusal is named. false skips the step; `hecks quality_control event_pump.pump!` runs it regardless."
+      member name: "push_nudge", type: "Boolean",
+             meaning: "Whether each `hecks quality_control sweep.tick` checks once whether a push of local main is due and files, revises or finishes the one `push-due` Work row; false skips the check. The thresholds are the QualityControl world's `push_nudge` setting."
+      member name: "quiesced", type: "Boolean",
+             meaning: "Whether each `hecks quality_control sweep.tick` runs no step at all: every step prints `quiesced: skipped <step>` and the tick exits 0, so a mint window sees a quiet ledger. The setting is read once at the start of a tick; `hecks qa_quiesce.hold!` writes a marker file every step checks as well, which a tick already running notices before its next step."
+      member name: "main_maintenance", type: "Boolean",
+             meaning: "Whether each `hecks quality_control sweep.tick` runs the main-maintenance chain after the main-check step: the quick gate on main, the reconcile plan, and the push through the train when origin is behind. false skips the chain."
+      member name: "maintenance_confirm", type: "Boolean",
+             meaning: "Whether the main-maintenance chain's reconcile writes after its plan (`Era.Reconcile` with confirm); false leaves the reconcile a dry run that writes nothing."
     end
 
     # What each retired `bin/` script became in hecks 3.0.0 (ADR 0080, section 7): one row per
@@ -806,8 +1201,8 @@ Hecks.bluebook "Bluebook" do
     # the command dropped nor miss one it gained; the table specs read the same rows.
     #
     # `section` is the part of docs/tools.md the row is listed under (Custodian, Deploy, Site,
-    # Codebase or QualityControl); Custodian and Codebase commands live in the Hecks chapter, the
-    # others in the chapter of their own name. `script` is `(new)` for a command no `bin/` script
+    # Codebase or QualityControl); Custodian and Codebase commands live in the Hecks bluebook, the
+    # others in the bluebook of their own name. `script` is `(new)` for a command no `bin/` script
     # preceded. `aggregate` and `verb` name the command (or, in QualityControl, the query) the way
     # the launcher spells it, `aggregate.verb`.
     #
@@ -850,7 +1245,7 @@ Hecks.bluebook "Bluebook" do
       member script: "heki_compact", section: "Custodian", aggregate: "Era", verb: "compact_heki"
       member script: "vendor_bluebook", section: "Custodian", aggregate: "Package", verb: "vendor", note: "waits: a refusal exits 1 with its reason on stderr"
       member script: "project_cli", section: "Custodian", aggregate: "Launch", verb: "project_cli"
-      member script: "hecks_mcp_door", section: "Custodian", aggregate: "Launch", verb: "serve_mcp"
+      member script: "hecks_mcp_door", section: "Custodian", aggregate: "Server", verb: "serve_mcp"
       member script: "project_rust", section: "Custodian", aggregate: "Build", verb: "project_rust"
       member script: "project_wasm", section: "Custodian", aggregate: "Build", verb: "build_wasm"
       member script: "project_host", section: "Custodian", aggregate: "Build", verb: "build_host"
@@ -877,6 +1272,7 @@ Hecks.bluebook "Bluebook" do
       member script: "project_refusal_wording", section: "Codebase", aggregate: "LanguageRun", verb: "project_refusal_wording"
       member script: "project_reserved_names", section: "Codebase", aggregate: "LanguageRun", verb: "project_reserved_names"
       member script: "project_parser_table", section: "Codebase", aggregate: "LanguageRun", verb: "project_parser_table"
+      member script: "project_phrase_table", section: "Codebase", aggregate: "LanguageRun", verb: "project_phrase_table"
       member script: "project_bootstrap_table", section: "Codebase", aggregate: "LanguageRun", verb: "project_bootstrap_table"
       member script: "project_field_hints", section: "Codebase", aggregate: "LanguageRun", verb: "project_field_hints"
       member script: "expression_projection", section: "Codebase", aggregate: "LanguageRun", verb: "project_expression_tables"
@@ -908,6 +1304,7 @@ Hecks.bluebook "Bluebook" do
       member script: "canonicalise", section: "Codebase", aggregate: "StyleRun", verb: "canonicalise"
       member script: "codemod_hoist_local_givens", section: "Codebase", aggregate: "CodemodRun", verb: "hoist_local_givens"
       member script: "codemod_implicit_append_fields", section: "Codebase", aggregate: "CodemodRun", verb: "drop_implicit_append_fields"
+      member script: "codemod_move_former_name", section: "Codebase", aggregate: "CodemodRun", verb: "move_former_name"
       member script: "rspec_shard_files", section: "Codebase", aggregate: "TestSuiteRun", verb: "shard_specs"
       member script: "rspec_io_parallel_files", section: "Codebase", aggregate: "TestSuiteRun", verb: "list_io_parallel_specs"
       member script: "rspec_io_parallel_files", section: "Codebase", aggregate: "TestSuiteRun", verb: "write_io_parallel_spec_list"
@@ -923,12 +1320,13 @@ Hecks.bluebook "Bluebook" do
       member script: "query_ir", section: "Codebase", aggregate: "CorpusRun", verb: "ir_constructs"
       member script: "query_ir", section: "Codebase", aggregate: "CorpusRun", verb: "ir_duplicates"
       member script: "query_ir", section: "Codebase", aggregate: "CorpusRun", verb: "ir_impact"
-      member script: "hecks_query_ir_mcp", section: "Codebase", aggregate: "CorpusRun", verb: "serve_query_ir_mcp"
-      member script: "present", section: "Codebase", aggregate: "CorpusRun", verb: "present"
+      member script: "hecks_query_ir_mcp", section: "Codebase", aggregate: "Server", verb: "serve_query_ir_mcp"
+      member script: "present", section: "Codebase", aggregate: "Server", verb: "present"
       member script: "release", section: "Codebase", aggregate: "PublishingRun", verb: "publish", note: "without --confirm, the old --dry-run"
       member script: "release_gem", section: "Codebase", aggregate: "PublishingRun", verb: "publish_gem"
       member script: "(new)", section: "Codebase", aggregate: "GateRun", verb: "gate"
       member script: "qa_tick", section: "QualityControl", aggregate: "Sweep", verb: "tick"
+      member script: "qa_event_pump", section: "QualityControl", aggregate: "EventPump", verb: "pump"
       member script: "qa_sweep", section: "QualityControl", aggregate: "Sweep", verb: "run", passes: "--all --seeds N --steps N --adversarial F --role-draw F --dry-run F --self-consistency BOOL --modes a,b --persistence-parity --no-parity"
       member script: "qa_sweep", section: "QualityControl", aggregate: "Target", verb: "release"
       member script: "qa_pr_check", section: "QualityControl", aggregate: "Clearance", verb: "check_pull_requests"
@@ -939,10 +1337,13 @@ Hecks.bluebook "Bluebook" do
       member script: "qa_seed_targets", section: "QualityControl", aggregate: "Target", verb: "seed"
       member script: "qa_generated_domains", section: "QualityControl", aggregate: "Target", verb: "check_generated_domains", passes: "--domains 3 --start N --forms a,b --seeds 5 --steps 25 --adversarial 0.3 --rust --shrink-budget 200 --domain-shrink-budget 40 --promote dir --name N --from-dials --blueprint F --source F"
       member script: "qa_mine_combinations", section: "QualityControl", aggregate: "Target", verb: "mine_combinations", passes: "--candidates 3 --rust --seeds 5 --steps 25 --adversarial 0.3 --repair-rounds 1 --agent CMD --from DIR --against PATH --brief"
+      member script: "(new)", section: "QualityControl", aggregate: "Target", verb: "mutate", passes: "--file rust/src/… --from-dials"
       member script: "qa_domain_novelty", section: "QualityControl", aggregate: "Target", verb: "judge_novelty", passes: "--against PATH …"
       member script: "qa_discover_external_domains", section: "QualityControl", aggregate: "Target", verb: "discover_external_domains", passes: "--projects-dir ~/Projects --max-depth 3 --known-path PATH …"
       member script: "qa_postgres_migrate", section: "QualityControl", aggregate: "Sweep", verb: "migrate_ledger_from_heki", passes: "[aggregate …] --force", note: "a dry run without --force"
       member script: "qa_postgres_role", section: "QualityControl", aggregate: "Sweep", verb: "create_ledger_role"
+      member script: "qa_main_gate", section: "QualityControl", aggregate: "MainCheck", verb: "check_main"
+      member script: "qa_fix_main_bug", section: "QualityControl", aggregate: "Bug", verb: "fix_and_land", passes: "--bug BUG#n"
       member script: "qa_concurrency_racer", section: "QualityControl", aggregate: "Sweep", verb: "race", note: "not user-facing; ProcessPool starts it"
     end