hecks 4.0.0 → 6.0.0

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

@@ -112,10 +112,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 +182,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 +345,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
@@ -655,6 +747,185 @@ 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.
+    value_object "GateCheck" do
+      attribute :name, String
+      attribute :id, String
+      attribute :title, String
+      attribute :argv, String
+      attribute :script, String
+      attribute :blocked, String
+
+      member name: "rspec", id: "rspec",
+             title: "rspec (parallel)",
+             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 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. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) 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 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: "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 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\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. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed."
+      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 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 makefile_check.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."
+      member name: "fuzz", id: "fuzz",
+             title: "fuzz, every example domain on the Memory adapter",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz --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", id: "fuzz_sqlite",
+             title: "fuzz on a real on-disk SQLite database",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz adapter=sqlite seeds=6 --wait",
+             script: "",
+             blocked: "the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."
+      member name: "fuzz_postgres", id: "fuzz_postgres",
+             title: "fuzz on real Postgres, up to four workers (each in its own scratch schema)",
+             argv: "bundle exec exe/hecks fuzz_run.fuzz adapter=postgres seeds=3 steps=20 --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: "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 `pre_push` runs.
+
+    # `pre_push` is what a push of a guarded lane runs. `quick` is the checks that finish in seconds
+    # and catch the offenses people make most (a storage shape with no edge, a style offense, a comment
+    # past the guide): a push runs them first and stops on a red one, so the minutes of spec/fuzzing
+    # are not spent on a change that cannot pass. `unguarded_push` is what a push of only unguarded
+    # lanes (`main`) runs in place of `pre_push`: the slow suite is skipped, the style checks are not,
+    # since an offense that lands on `main` is a red CI run. `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: "rspec,fuzzing,query_agreement,engine_agreement,shape_ledger,model_check,doc_coverage,rubocop,codegen_drift,comment_style,comment_blocks,rust_fmt"
+      member name: "quick", env: "HECKS_ENVIRONMENT=memory", checks: "shape_ledger,rubocop,comment_style,comment_blocks"
+      member name: "unguarded_push", env: "HECKS_ENVIRONMENT=memory", checks: "shape_ledger,rubocop,comment_style,comment_blocks,fuzzing"
+      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,rust_fmt,rust_clippy,lint_deploy_recipes,fuzz,fuzz_sqlite,fuzz_postgres,vocabulary_drift,ci_gates,tools_doc,rust_coverage,rust_coverage_codegen,kernel_coverage,rust_vocabulary_drift"
+    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
@@ -720,6 +991,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 +1002,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.
@@ -795,6 +1070,10 @@ 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."
     end
@@ -806,8 +1085,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`.
     #
@@ -877,6 +1156,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"
@@ -939,6 +1219,7 @@ 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"

data/lib/hecks/language/context_map/context_map.bluebook

@@ -0,0 +1,90 @@
+Hecks.bluebook "ContextMap" do
+  aggregate "ContextMap" do
+    description "One .contextmap — the contexts a system holds and how pairs of them relate, declared before the wiring and held against it (ADR 0135). A sibling artifact to the bluebook, not part of it."
+
+    identified_by MapName, as: :system
+
+    # What the map's body fills: the contexts it names, the relationships between them and the
+    # pairs declared apart, each written as the builder reads it.
+    attribute :contexts,      ContextBody
+    attribute :relationships, RelationshipBody
+    attribute :separate_ways, SeparateWaysBody
+
+    value_object "MapName" do
+      attribute :value, String
+      invariant("a context map names its system") { !value.to_s.empty? }
+    end
+
+    value_object "ContextBody" do
+      attribute :value, String
+    end
+
+    value_object "RelationshipBody" do
+      attribute :value, String
+    end
+
+    value_object "SeparateWaysBody" do
+      attribute :value, String
+    end
+
+    command "Declare" do
+      role "Architect"
+      goal "Open a context map for a system"
+
+      attribute :system, MapName
+
+      sets :system
+
+      emits "ContextMapDeclared"
+    end
+
+    # Spelling rows for ContextMap keywords; SyntaxBoot discovers every
+    # aggregate-local seed table like this one.
+    value_object "KeywordSeed" do
+      attribute :word,          String
+      attribute :context,       String, admits: "Syntax::Context"
+      attribute :body,          String, admits: "Syntax::Body"
+      attribute :inner,         String
+      attribute :opens,         String
+      attribute :fills,         String
+      attribute :status,        String, default: "admitted", admits: "Syntax::Status"
+      attribute :was,           String
+      attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
+      attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
+
+      member word: "context_map",   context: "File",       body: "keywords", inner: "ContextMap", opens: "ContextMap", fills: ""
+      member word: "context",       context: "ContextMap", body: "none", inner: "", opens: "", fills: "contexts"
+      member word: "relate",        context: "ContextMap", body: "none", inner: "", opens: "", fills: "relationships"
+      member word: "separate_ways", context: "ContextMap", body: "none", inner: "", opens: "", fills: "separate_ways"
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,          String
+      attribute :context,          String, admits: "Syntax::Context"
+      attribute :at,               String
+      attribute :named,            String
+      attribute :kind,             String, admits: "Syntax::ArgumentKind"
+      attribute :required,         String
+      attribute :fills,            String
+      attribute :selects,          String
+      attribute :pair_key_fills,   String
+      attribute :pair_value_fills, String
+      attribute :pairs_shape,      String, admits: "Syntax::PairsShape"
+      attribute :status,           String, default: "admitted", admits: "Syntax::Status"
+      attribute :variadic,         String
+      attribute :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "context_map",   context: "File", at: "1", named: "", kind: "text", required: "true", fills: "system"
+      member keyword: "context",       context: "ContextMap", at: "1", named: "", kind: "text", required: "true", fills: "contexts"
+      member keyword: "context",       context: "ContextMap", at: "", named: "team", kind: "text", required: "false", fills: "contexts"
+      member keyword: "relate",        context: "ContextMap", at: "", named: "", kind: "pairs", required: "true", fills: "relationships", pairs_shape: "verbatim"
+      member keyword: "relate",        context: "ContextMap", at: "", named: "as", kind: "symbol", required: "true", fills: "relationships"
+      member keyword: "relate",        context: "ContextMap", at: "", named: "published", kind: "list", required: "false", fills: "relationships"
+      member keyword: "relate",        context: "ContextMap", at: "", named: "of", kind: "list", required: "false", fills: "relationships"
+      member keyword: "relate",        context: "ContextMap", at: "", named: "acknowledges", kind: "literal", required: "false", fills: "relationships"
+      member keyword: "separate_ways", context: "ContextMap", at: "1", named: "", kind: "text", required: "true", fills: "separate_ways"
+      member keyword: "separate_ways", context: "ContextMap", at: "2", named: "", kind: "text", required: "true", fills: "separate_ways"
+    end
+  end
+end

data/lib/hecks/language/hecksagon/domain_port.bluebook

@@ -1,6 +1,6 @@
 Hecks.bluebook "Hecksagon" do
   aggregate "DomainPort" do
-    description "A primary port — the boundary between a domain and its adapters, in hexagonal terms, is exactly what a hecksagon already IS for every other port. Root-level (belongs to the chapter) or aggregate-scoped (reached the same way persisted_by is, through the open Const.verb(...) entry point). One of two shapes, never both: a list of operations translating an inbound fact into this domain's own events, or a bare verb naming a swappable resource port (the same Hecks.port a project's own .port file declares, reached from inside the hecksagon instead)."
+    description "A primary port — the boundary between a domain and its adapters, in hexagonal terms, is exactly what a hecksagon already IS for every other port. Root-level (belongs to the bluebook) or aggregate-scoped (reached the same way persisted_by is, through the open Const.verb(...) entry point). One of two shapes, never both: a list of operations translating an inbound fact into this domain's own events, or a bare verb naming a swappable resource port (the same Hecks.port a project's own .port file declares, reached from inside the hecksagon instead)."
 
     identified_by PortName, as: :name
 
@@ -19,7 +19,7 @@ Hecks.bluebook "Hecksagon" do
       invariant("a verb is named") { !value.to_s.empty? }
     end
 
-    # Same closed set as port.bluebook's Port, kept local rather than shared across chapters.
+    # Same closed set as port.bluebook's Port, kept local rather than shared across bluebooks.
     value_object "PortSignal" do
       attribute :value, String, one_of: ["reply", "effect"]
     end

data/lib/hecks/language/hecksagon/hecksagon.bluebook

@@ -18,8 +18,8 @@ Hecks.bluebook "Hecksagon" do
       invariant("a subscription names an event") { !value.to_s.empty? }
     end
 
-    # A chapter this hecksagon attaches: `value` is its name, `source` is `gem` for a chapter the
-    # gem carries (a framework member such as Governance, or a language chapter such as Deploy)
+    # A bluebook this hecksagon attaches: `value` is its name, `source` is `gem` for a bluebook the
+    # gem carries (a framework member such as Governance, or a language bluebook such as Deploy)
     # or `vendor` for a package vendored into the consuming project, not shipped in hecks's lib/.
     value_object "Attachment" do
       attribute :value,  String
@@ -37,9 +37,9 @@ Hecks.bluebook "Hecksagon" do
     end
 
     # The name an attachment is asked for by, before its source is known.
-    value_object "ChapterName" do
+    value_object "AttachedBluebookName" do
       attribute :value, String
-      invariant("a chapter is named") { !value.to_s.empty? }
+      invariant("a bluebook is named") { !value.to_s.empty? }
     end
 
     command "Declare" do
@@ -66,14 +66,14 @@ Hecks.bluebook "Hecksagon" do
 
     command "Attaches" do
       role "Deployment"
-      goal "Attach a chapter to this hecksagon, from the gem or from vendor"
+      goal "Attach a bluebook to this hecksagon, from the gem or from vendor"
 
-      attribute :chapter, ChapterName
+      attribute :bluebook, AttachedBluebookName
       attribute :source,  String, default: "gem"
 
-      sets :attachments, append: { value: :chapter, source: :source }
+      sets :attachments, append: { value: :bluebook, source: :source }
 
-      emits "ChapterAttached"
+      emits "BluebookAttached"
     end
 
     command "DrivenBy" do

data/lib/hecks/language/oidc.json

@@ -1,6 +1,11 @@
 {
   "audience": "Bluebook",
   "scopes": [
+    {
+      "scope": "bluebook:aggregate.acknowledges",
+      "verb": "Bluebook::Aggregate.Acknowledges",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:aggregate.attribute",
       "verb": "Bluebook::Aggregate.Attribute",
@@ -91,6 +96,11 @@
       "verb": "Bluebook::Command.ActsOn",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:command.allow",
+      "verb": "Bluebook::Command.Allow",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.announce",
       "verb": "Bluebook::Command.Announce",

data/lib/hecks/language/port.bluebook

@@ -1,5 +1,5 @@
 Hecks.bluebook "Port" do
-  vision "The .port language, declared in itself. A port names one resource a domain's own aggregates call by verb — persisted_by, posted_by, whatever a chapter spells — bound to a real driven adapter at the world level. A sibling artifact to the bluebook, not part of one: the same port name is reused across every domain that needs the same kind of entry point."
+  vision "The .port language, declared in itself. A port names one resource a domain's own aggregates call by verb — persisted_by, posted_by, whatever a bluebook spells — bound to a real driven adapter at the world level. A sibling artifact to the bluebook, not part of one: the same port name is reused across every domain that needs the same kind of entry point."
   core
 
   aggregate "Port" do