hecks 5.0.0 → 6.0.0

data/lib/hecks/vocabulary.rb

@@ -62,6 +62,17 @@ module Hecks
         {"symbol"=>"==", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"false"}.freeze,
         {"symbol"=>"!=", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"true"}.freeze
       ].freeze,
+      "DispatchStage" => [
+        {"name"=>"request"}.freeze,
+        {"name"=>"arguments"}.freeze,
+        {"name"=>"role"}.freeze,
+        {"name"=>"references"}.freeze,
+        {"name"=>"state"}.freeze,
+        {"name"=>"givens"}.freeze,
+        {"name"=>"ensures"}.freeze,
+        {"name"=>"invariants"}.freeze,
+        {"name"=>"remote"}.freeze
+      ].freeze,
       "DomainRefusal" => [
         {"name"=>"AbsentArgument"}.freeze,
         {"name"=>"AlreadyExists"}.freeze,
@@ -103,6 +114,41 @@ module Hecks
         {"name"=>"tel", "pattern"=>"phone|\\btel(ephone)?\\b", "resolves_to"=>"html_type"}.freeze,
         {"name"=>"textarea", "pattern"=>"\\b(text|body|note|notes|description|message|comment)\\b", "resolves_to"=>"kind"}.freeze
       ].freeze,
+      "GateCheck" => [
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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`."}.freeze,
+        {"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`."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze
+      ].freeze,
+      "GateStage" => [
+        {"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"}.freeze,
+        {"name"=>"quick", "env"=>"HECKS_ENVIRONMENT=memory", "checks"=>"shape_ledger,rubocop,comment_style,comment_blocks"}.freeze,
+        {"name"=>"unguarded_push", "env"=>"HECKS_ENVIRONMENT=memory", "checks"=>"shape_ledger,rubocop,comment_style,comment_blocks,fuzzing"}.freeze,
+        {"name"=>"rust_io", "env"=>"CI=true HECKS_ENVIRONMENT=memory", "checks"=>"rust_io"}.freeze,
+        {"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"}.freeze
+      ].freeze,
       "IncludeHaystack" => [
         {"type"=>"Array", "strategy"=>"membership"}.freeze,
         {"type"=>"String", "strategy"=>"substring"}.freeze
@@ -117,7 +163,8 @@ module Hecks
         {"glob"=>"*.bluebook"}.freeze,
         {"glob"=>"translations/*.bluebook"}.freeze,
         {"glob"=>"*.hecksagon"}.freeze,
-        {"glob"=>"*.world"}.freeze
+        {"glob"=>"*.world"}.freeze,
+        {"glob"=>"*.contextmap"}.freeze
       ].freeze,
       "MutationOp" => [
         {"name"=>"set", "sign"=>""}.freeze,
@@ -136,7 +183,8 @@ module Hecks
         {"name"=>"scale_call"}.freeze
       ].freeze,
       "PrebuiltBinary" => [
-        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze,
+        {"name"=>"host-arm64", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"aarch64-unknown-linux-gnu", "runner"=>"ubuntu-22.04-arm"}.freeze
       ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
@@ -172,6 +220,8 @@ module Hecks
         {"name"=>"generated_domains_per_tick", "type"=>"Integer", "meaning"=>"How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the step."}.freeze,
         {"name"=>"generated_domains_rust", "type"=>"Boolean", "meaning"=>"Whether generated domains are also compared against a compiled Rust binary built in a scratch copy."}.freeze,
         {"name"=>"generated_domain_seeds", "type"=>"Integer", "meaning"=>"Generated sequences run per generated domain."}.freeze,
+        {"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."}.freeze,
+        {"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."}.freeze,
         {"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."}.freeze
       ].freeze,
       "QueryComparator" => [
@@ -185,6 +235,40 @@ module Hecks
         {"name"=>"contains"}.freeze,
         {"name"=>"none_in_state"}.freeze
       ].freeze,
+      "Reducer" => [
+        {"name"=>"count", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"sum", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"avg", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"min", "identity"=>"null", "combine"=>"min", "inverse"=>""}.freeze,
+        {"name"=>"max", "identity"=>"null", "combine"=>"max", "inverse"=>""}.freeze,
+        {"name"=>"median", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"percentile", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"any", "identity"=>"false", "combine"=>"or", "inverse"=>""}.freeze,
+        {"name"=>"all", "identity"=>"true", "combine"=>"and", "inverse"=>""}.freeze
+      ].freeze,
+      "RefusalClass" => [
+        {"name"=>"AbsentArgument", "kind"=>"absent_argument", "stage"=>"arguments"}.freeze,
+        {"name"=>"AlreadyExists", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"AttributeAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"EnsuresNotMet", "kind"=>"refused", "stage"=>"ensures"}.freeze,
+        {"name"=>"GivenNotMet", "kind"=>"refused", "stage"=>"givens"}.freeze,
+        {"name"=>"InvariantViolation", "kind"=>"refused", "stage"=>"invariants"}.freeze,
+        {"name"=>"LifecycleRefused", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NothingToCorrect", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NotFound", "kind"=>"not_found", "stage"=>"state"}.freeze,
+        {"name"=>"ProjectionAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"RemoteRefusal", "kind"=>"refused", "stage"=>"remote"}.freeze,
+        {"name"=>"TypeMismatch", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"Unauthorized", "kind"=>"unauthorized", "stage"=>"role"}.freeze,
+        {"name"=>"UnknownArgument", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"UnknownVerb", "kind"=>"refused", "stage"=>"request"}.freeze
+      ].freeze,
+      "RefusalKind" => [
+        {"name"=>"refused"}.freeze,
+        {"name"=>"not_found"}.freeze,
+        {"name"=>"unauthorized"}.freeze,
+        {"name"=>"absent_argument"}.freeze
+      ].freeze,
       "RefusalSiteArgument" => [
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"command", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"aggregate", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
@@ -359,7 +443,7 @@ module Hecks
         {"refusal"=>"InvariantViolation", "site"=>"closed_set_member", "template"=>"{type} admits {admitted} — got {offered}"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"value_object_invariant", "template"=>"{name} invariant violated — {description} (given {offered})"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"admits_declared_set", "template"=>"{name} admits {admits} — {admitted} — got {offered}"}.freeze,
-        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "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"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"group_by_collision", "template"=>"{read_model} groups by {fields}, but rows {ids} share {key} — a group_by leaf holds one row; add a field that tells them apart"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"tenant_required", "template"=>"{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"role_mismatch", "template"=>"{command} refused — role: {role}, and the caller stated {caller_role}"}.freeze,
@@ -443,6 +527,7 @@ module Hecks
         {"script"=>"project_refusal_wording", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_refusal_wording"}.freeze,
         {"script"=>"project_reserved_names", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_reserved_names"}.freeze,
         {"script"=>"project_parser_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_parser_table"}.freeze,
+        {"script"=>"project_phrase_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_phrase_table"}.freeze,
         {"script"=>"project_bootstrap_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_bootstrap_table"}.freeze,
         {"script"=>"project_field_hints", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_field_hints"}.freeze,
         {"script"=>"expression_projection", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_expression_tables"}.freeze,
@@ -505,6 +590,7 @@ module Hecks
         {"script"=>"qa_seed_targets", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"seed"}.freeze,
         {"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"}.freeze,
         {"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"}.freeze,
+        {"script"=>"(new)", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mutate", "passes"=>"--file rust/src/… --from-dials"}.freeze,
         {"script"=>"qa_domain_novelty", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"judge_novelty", "passes"=>"--against PATH …"}.freeze,
         {"script"=>"qa_discover_external_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"discover_external_domains", "passes"=>"--projects-dir ~/Projects --max-depth 3 --known-path PATH …"}.freeze,
         {"script"=>"qa_postgres_migrate", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"migrate_ledger_from_heki", "passes"=>"[aggregate …] --force", "note"=>"a dry run without --force"}.freeze,
@@ -574,6 +660,27 @@ module Hecks
         {"type"=>"String"}.freeze,
         {"type"=>"Hash"}.freeze
       ].freeze,
+      "StepStage" => [
+        {"step"=>"decode_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_unknown_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"normalize_args", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_role_mismatch", "stage"=>"role"}.freeze,
+        {"step"=>"resolve_references", "stage"=>"references"}.freeze,
+        {"step"=>"hydrate", "stage"=>"state"}.freeze,
+        {"step"=>"hydrate_parent", "stage"=>"state"}.freeze,
+        {"step"=>"locate_element", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_givens", "stage"=>"givens"}.freeze,
+        {"step"=>"admissible_transition", "stage"=>"state"}.freeze,
+        {"step"=>"assign_creation_attributes", "stage"=>"state"}.freeze,
+        {"step"=>"apply_mutations", "stage"=>"state"}.freeze,
+        {"step"=>"advance_lifecycle", "stage"=>"state"}.freeze,
+        {"step"=>"delegate_to_entity", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_ensures", "stage"=>"ensures"}.freeze,
+        {"step"=>"enforce_invariants", "stage"=>"invariants"}.freeze,
+        {"step"=>"save", "stage"=>"state"}.freeze,
+        {"step"=>"emit", "stage"=>"state"}.freeze
+      ].freeze,
       "ToStringType" => [
         {"type"=>"String"}.freeze,
         {"type"=>"Integer"}.freeze,

data/lib/hecks.rb

@@ -5,6 +5,7 @@ require_relative "hecks/version"
 require_relative "hecks/vocabulary"
 require_relative "hecks/rendering"
 require_relative "hecks/naming"
+require_relative "hecks/text"
 require_relative "hecks/fqn"
 require_relative "hecks/freezer"
 require_relative "hecks/construct"
@@ -21,6 +22,7 @@ require_relative "hecks/router"
 
 require_relative "hecks/runtime"
 require_relative "hecks/adapters"
+require_relative "hecks/assembly"
 require_relative "hecks/projector"
 # After the projector registry and its `Target` mixin are both real —
 # every target registers itself as it loads, so this require is the
@@ -42,8 +44,8 @@ require_relative "hecks/embryonaut_bluebook"
 # has, so it loads on first use.
 Hecks.autoload(:Corpus, File.expand_path("hecks/corpus", __dir__))
 
-# The chapters a hecksagon can `attaches` by name (ADR 0080); loads on first use.
-Hecks.autoload(:Chapters, File.expand_path("hecks/chapters", __dir__))
+# The bluebooks a hecksagon can `attaches` by name (ADR 0080); loads on first use.
+Hecks.autoload(:FrameworkBluebooks, File.expand_path("hecks/framework_bluebooks", __dir__))
 
 # The Composer's staging, parse stage and check; loads on first use.
 Hecks.autoload(:Composer, File.expand_path("hecks/composer", __dir__))
@@ -62,9 +64,9 @@ module Hecks
     # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @param environment [String, nil] env name; its `.hecksagon`/`.world` overlay,
     #   if present, loads after the domain's own. Defaults to `HECKS_ENVIRONMENT`; nil loads none
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot(path, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot(path, shared: shared, install_driving: install_driving, environment: environment)
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the domain's dispatcher
+    def boot(path, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+      Assembly.boot(path, shared: shared, install_driving: install_driving, environment: environment)
     end
 
     # Loads a domain's declarations without binding any adapter or opening any store.
@@ -73,8 +75,8 @@ module Hecks
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.describe`
     # @param environment [String, nil] env overlay; defaults to `HECKS_ENVIRONMENT`
     # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
-    def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
-      Runtime.describe(path, shared: shared, environment: environment)
+    def describe(path, shared: nil, environment: Assembly::FROM_ENV)
+      Assembly.describe(path, shared: shared, environment: environment)
     end
 
     # Finishes a boot from declarations `describe` already loaded, so the domain's files are read
@@ -82,9 +84,9 @@ module Hecks
     #
     # @param described [Runtime::Loader::Described] what `describe` answered
     # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the domain's dispatcher
     def boot_described(described, install_driving: true)
-      Runtime.boot_described(described, install_driving: install_driving)
+      Assembly.boot_described(described, install_driving: install_driving)
     end
 
     # Boots a domain from an explicit list of files (a `.bluebook`, its
@@ -94,11 +96,17 @@ module Hecks
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot_files`
     # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @param environment [String, nil] environment name passed to the selected-file loader
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot_files(paths, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the domain's dispatcher
+    def boot_files(paths, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+      Assembly.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
     end
 
+    # Installs the Ruby driving adapter (`Widget::Item.Add(...)`) over a dispatcher built by hand.
+    #
+    # @param dispatcher [Runtime::Dispatcher] a dispatcher over a verified registry
+    # @return [Runtime::Dispatcher] the same dispatcher
+    def bind_runtime(dispatcher) = Assembly.bind_runtime(dispatcher)
+
     # Binds the ambient registry for the duration of the block.
     #
     # @param registry [Runtime::Registry] the registry to make current for the block
@@ -126,14 +134,14 @@ module Hecks
       Runtime.as_caller(role: role, actor_id: actor_id, as_of: as_of, scope: scope, &)
     end
 
-    # Declares a chapter — a `.bluebook` file's top-level word.
+    # Declares a bluebook — a `.bluebook` file's top-level word.
     #
-    # @param name [String] the chapter's declared name
-    # @param version [String, nil] the chapter's pinned version, or nil for unversioned
-    # @yield the chapter's body, evaluated against a `Bluebook::DSL::BluebookBuilder`
-    # @return [Bluebook::Chapter] the built, judged chapter
+    # @param name [String] the bluebook's declared name
+    # @param version [String, nil] the bluebook's pinned version, or nil for unversioned
+    # @yield the bluebook's body, evaluated against a `Bluebook::DSL::BluebookBuilder`
+    # @return [Bluebook::Declaration] the built, judged bluebook
     # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
-    # @raise [Bluebook::DSL::Malformed] if the chapter fails the language's own judgment
+    # @raise [Bluebook::DSL::Malformed] if the bluebook fails the language's own judgment
     def bluebook(name, version: nil, &)
       collect(:add_bluebook, Bluebook::DSL::BluebookBuilder.build(name, version: version, &))
     end
@@ -175,6 +183,17 @@ module Hecks
     # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
     def world(name, &)     = collect(:add_world, Bluebook::DSL::WorldBuilder.build(name, &))
 
+    # Declares a context map — a `.contextmap` file's top-level word, naming the contexts a system
+    # holds and how pairs of them relate (ADR 0135).
+    #
+    # @param name [String, Symbol] the system the map covers
+    # @yield the map's body, evaluated against a `Bluebook::DSL::ContextMapBuilder`
+    # @return [Bluebook::ContextMap] the built map
+    # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
+    # @raise [ArgumentError] on an unknown relationship kind, or a relationship naming an
+    #   undeclared context
+    def context_map(name, &) = collect(:add_context_map, Bluebook::DSL::ContextMapBuilder.build(name, &))
+
     # Declares a data translation — a `.translation` file's top-level word,
     # migrating one domain's stored shape from one era to the next.
     #

data/lib/rubocop/cop/hecks/inline_regexp.rb

@@ -0,0 +1,29 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a regular expression written inline instead of held by a named constant.
+      #
+      # An inline pattern says how it matches but not what it is for, and the same pattern gets
+      # retyped wherever it is needed. Name it once (`IDENTIFIER = /\A[a-z][a-z0-9_]*\z/`) beside
+      # the code that uses it, or in `Hecks::Naming` when several places share it. A pattern built
+      # by interpolating a runtime value cannot be a constant, so it is left alone.
+      #
+      # @example
+      #   name.match?(/\A[a-z][a-z0-9_]*\z/)        # bad
+      class InlineRegexp < Base
+        MSG = "Name this pattern: assign it to a constant that says what it matches, " \
+              "and use the constant here.".freeze
+
+        # Flags a regexp literal outside a constant assignment.
+        #
+        # @param node [RuboCop::AST::RegexpNode] the regexp being visited
+        # @return [void]
+        def on_regexp(node)
+          return if node.interpolation? || node.each_ancestor(:casgn).any?
+
+          add_offense(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/no_transport_in_runtime.rb

@@ -0,0 +1,78 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a transport detail inside the runtime: a network or process library, a reach into
+      # `Hecks::Adapters`, or a read of the process's environment, arguments or standard input.
+      #
+      # The runtime runs the domain and nothing else; HTTP, Lambda, the shell and the environment
+      # belong to the adapters behind a hecksagon's ports, which call into the runtime and never
+      # the other way round. An adapter registers itself with the runtime when it loads.
+      #
+      # @example
+      #   require "net/http"                       # bad
+      #   Adapters::Folder.new                     # bad
+      #   ENV["HECKS_ENVIRONMENT"]                 # bad
+      #   Ports::Loading.bootstrap                 # good
+      class NoTransportInRuntime < Base
+        MSG = "`%<code>s` puts a transport detail inside the runtime. Move it into an adapter " \
+              "under `lib/hecks/adapters/` and let the adapter call in, or pass the value in at boot.".freeze
+
+        # Libraries that speak to the network, the shell or another process.
+        TRANSPORT_LIBRARIES = %r{\A(net/|uri\z|open-uri\z|socket\z|rack|webrick\z|open3\z|aws-sdk|faraday\z)}
+
+        # Paths a runtime file must not load: adapters and the command line live outside it.
+        OUTSIDE_PATHS = %r{(\A|/)(adapters|cli)(/|\z)}
+
+        # @!method library_require(node)
+        def_node_matcher :library_require, <<~PATTERN
+          (send nil? :require (str $_))
+        PATTERN
+
+        # @!method relative_require(node)
+        def_node_matcher :relative_require, <<~PATTERN
+          (send nil? :require_relative (str $_))
+        PATTERN
+
+        # @!method process_input?(node)
+        def_node_matcher :process_input?, <<~PATTERN
+          (const {nil? cbase} {:ENV :ARGV :STDIN})
+        PATTERN
+
+        # @!method adapters_namespace?(node)
+        def_node_matcher :adapters_namespace?, <<~PATTERN
+          (const {nil? cbase (const {nil? cbase} :Hecks)} :Adapters)
+        PATTERN
+
+        # Flags a require of a transport library, or of a file under adapters or the command line.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          flagged = library_require(node)&.match?(TRANSPORT_LIBRARIES) ||
+                    relative_require(node)&.match?(OUTSIDE_PATHS)
+          add_offense(node, message: format(MSG, code: node.source)) if flagged
+        end
+
+        # Flags `ENV`, `ARGV`, `STDIN` and any `Hecks::Adapters` reference.
+        #
+        # @param node [RuboCop::AST::ConstNode] the constant being visited
+        # @return [void]
+        def on_const(node)
+          return unless process_input?(node) || adapters_namespace?(node)
+
+          add_offense(node, message: format(MSG, code: node.source))
+        end
+
+        # Flags `$stdin`.
+        #
+        # @param node [RuboCop::AST::Node] the global variable being visited
+        # @return [void]
+        def on_gvar(node)
+          return unless node.children.first == :$stdin
+
+          add_offense(node, message: format(MSG, code: node.source))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/rails_model_rules.rb

@@ -0,0 +1,46 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a validation, callback or association declared in a `Hecks::Rails::Model` or in a
+      # model inheriting the `ApplicationRecord` the railtie generates.
+      #
+      # Every rule of a Hecks domain is declared in its bluebook. A `validates` or `before_save`
+      # in the Rails model would be a second author for a rule the domain already states, and the
+      # two drift; an association would load records the domain keeps as plain identity values.
+      #
+      # @example
+      #   class Account < ApplicationRecord
+      #     validates :owner, presence: true  # bad
+      #     has_many :entries                 # bad
+      #   end
+      class RailsModelRules < Base
+        MSG = "`%<call>s` declares a rule or an association in a model. State the rule in the " \
+              "bluebook instead; the model is a skin over the aggregate.".freeze
+
+        FORBIDDEN = /\A(validates?(_\w+)?|(before|after|around)_\w+|has_(many|one|and_belongs_to_many)|belongs_to)\z/
+
+        # @!method model_parent?(node)
+        def_node_matcher :model_parent?, <<~PATTERN
+          (class _ {(const (const (const {nil? cbase} :Hecks) :Rails) :Model) (const {nil? cbase} :ApplicationRecord)} ...)
+        PATTERN
+
+        # Flags a forbidden declaration written directly in a model's body.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless node.receiver.nil? && FORBIDDEN.match?(node.method_name.to_s)
+          return unless inside_model?(node)
+
+          add_offense(node, message: format(MSG, call: node.method_name))
+        end
+
+        private
+
+        def inside_model?(node)
+          node.each_ancestor(:class).any? { |klass| model_parent?(klass) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/thread_shared_ivar_mutation.rb

@@ -81,7 +81,7 @@ module RuboCop
           return nil unless klass
 
           const_node = klass.identifier
-          const_node.const_name.to_s.split("::").last
+          const_node.short_name.to_s
         end
 
         # An ivar set in `initialize` cannot yet be shared with another thread.

data/lib/rubocop/cop/hecks/train_wreck.rb

@@ -0,0 +1,69 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a call that reaches through one object into another: `runtime.registry.bluebooks`.
+      #
+      # Each bare reader in the chain steps into an object the caller was not handed, so the caller
+      # now knows how that object is built. Ask the first object instead, with a method that answers
+      # the question (`runtime.bluebooks`). Conversions and collection calls (`to_s`, `map`)
+      # are not steps, so a chain of them is left to Hecks/UnnamedPipeline.
+      #
+      # @example
+      #   runtime.registry.bluebooks          # bad
+      #   runtime.bluebooks                   # good
+      #   error.class.name                    # good: `class` is not a step into a collaborator
+      class TrainWreck < Base
+        MSG = "`%<chain>s` reaches through `%<through>s` into an object it was not handed. Ask `%<root>s` " \
+              "for it with a method named for what you want.".freeze
+
+        # Calls that convert, query or iterate a value rather than step into a collaborator.
+        PIPELINE_METHODS = %i[
+          to_s to_sym to_str to_a to_h to_i to_f to_r to_proc to_json inspect freeze dup class
+          first last keys values size count length strip chomp lstrip rstrip downcase upcase capitalize
+          lines chars bytes sort uniq compact flatten reverse each each_value each_key each_line lazy
+          with_index each_with_index reverse_each tally sum min max now utc iso8601 source value new
+        ].freeze
+
+        # Flags the outermost call of a chain whose leading readers step past the first object.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return if chained_further?(node)
+
+          root, reaches = leading_reaches(node)
+          return if reaches.size <= max_reaches
+
+          add_offense(reaches.last, message: message_for(root, reaches))
+        end
+        alias on_csend on_send
+
+        private
+
+        def max_reaches = cop_config.fetch("MaxReaches", 1)
+
+        def chained_further?(node)
+          node.parent&.call_type? && node.parent.receiver.equal?(node)
+        end
+
+        def leading_reaches(node)
+          calls = []
+          calls.unshift(node) && (node = node.receiver) while node&.call_type? && node.receiver
+          [node, calls.take_while { |call| reach?(call) }]
+        end
+
+        def reach?(call)
+          return false if call.arguments? || call.block_literal? || call.operator_method?
+
+          name = call.method_name
+          !(PIPELINE_METHODS.include?(name) || name.end_with?("?", "!", "="))
+        end
+
+        def message_for(root, reaches)
+          format(MSG, chain: reaches.last.source, through: reaches[0..-2].map(&:method_name).join("."),
+                      root: root&.source || "self")
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/unnamed_pipeline.rb

@@ -0,0 +1,51 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a chain of more than three calls: `text.to_s.strip.downcase.gsub(SEPARATORS, "_")`.
+      #
+      # A long pipeline makes the reader replay every step to learn what comes out. Extract it into
+      # a method named for the result (`slug(text)`, `first_line(error)`), and reuse that method
+      # where the same pipeline appears again. The receiver does not count toward the limit.
+      #
+      # @example
+      #   error.message.lines.first.to_s.strip      # bad
+      #   first_line(error.message)                 # good
+      class UnnamedPipeline < Base
+        MSG = "This chain runs %<count>d calls; a reader has to replay each one to learn what it makes. " \
+              "Extract it into a method named for the result.".freeze
+
+        # Flags the outermost call of a chain longer than `MaxCalls`.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return if chained_further?(node)
+
+          count = chain_length(node)
+          add_offense(node, message: format(MSG, count: count)) if count > cop_config.fetch("MaxCalls", 3)
+        end
+        alias on_csend on_send
+
+        private
+
+        def chained_further?(node)
+          outer = node.block_literal? ? node.parent : node
+          outer.parent&.call_type? && outer.parent.receiver.equal?(outer)
+        end
+
+        def chain_length(node)
+          count = 0
+          while (node = link(node))&.call_type? && node.receiver && !node.operator_method?
+            count += 1
+            node = node.receiver
+          end
+          count
+        end
+
+        def link(node)
+          node&.any_block_type? ? node.send_node : node
+        end
+      end
+    end
+  end
+end