hecks 3.2.0 → 3.3.0

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

@@ -625,16 +625,229 @@ Hecks.bluebook "Bluebook" do
              pattern: '^lib/hecks/runtime/', push: "skip",
              label: "does this change touch lib/hecks/runtime/**?"
       member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
-             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\.rb$|rust/project_rust_pipeline\.rb$|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
+             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
              push: "before_sha",
              label: "does this change touch anything rspec_postgres_io_parallel covers?"
     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`
+    # 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.
+    value_object "QaDial" do
+      attribute :name,    String
+      attribute :type,    String
+      attribute :meaning, String
+
+      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."
+      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",
+             meaning: "How many `hecks quality_control query sweep.run <target>` children `--all` keeps running at once."
+      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."
+      member name: "auto_merge", type: "Boolean",
+             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",
+             meaning: "Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`)."
+      member name: "corpus_splice_probability", type: "Numeric",
+             meaning: "Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."
+      member name: "favor_rare_verbs", type: "Integer",
+             meaning: "How many of the least-hit verbs the next seed weights up; 0 turns the lever off."
+      member name: "self_consistency_checks", type: "Boolean",
+             meaning: "Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay idempotency, value-object JSON round trip) on the same generated sequence."
+      member name: "shrink_budget", type: "Integer",
+             meaning: "Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking off. `concurrency` is never shrunk: a race does not reproduce on demand."
+      member name: "yield_weight_seconds", type: "Integer",
+             meaning: "Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`. Zero would make yield invisible, so pick a number that lets it matter."
+      member name: "yield_decay_percent", type: "Integer",
+             meaning: "Percent of the prior yield score kept at each release, so recent findings dominate. Applied by the caller: the mutation language cannot express \"decay, then add\" in `Release`."
+      member name: "rotation_stale_floor_seconds", type: "Integer",
+             meaning: "Once a waiting target is this stale, `RotationPriority.pick` takes it whatever its yield score, so a quiet target cannot starve."
+      member name: "persistence_parity_seed_cap", type: "Integer",
+             meaning: "Ceiling on `--seeds` for `--persistence-parity`, which pays for real Postgres per dispatch. `hecks quality_control query sweep.run` clamps down, never up, and prints a note."
+      member name: "concurrency_seed_cap", type: "Integer",
+             meaning: "Ceiling on `--seeds` for the concurrency mode, which needs two disposable schemas per seed."
+      member name: "adapter_parity_pairs", type: "Hash",
+             meaning: "The two adapters each adapter-parity mode compares, by mode name; a new pairing is a new entry. `adapter_parity_sqlite` needs no `database:`/`schema:` because sqlite has no disposable database."
+      member name: "modes", type: "Hash",
+             meaning: "Which comparison modes `hecks quality_control query sweep.run` may run: the enabled ones intersected with what `TargetCapabilities.infer(path)` finds in the target. `--modes a,b,c` overrides for one run. `wasm_front` and `adapter_parity_postgres` are off because nothing runs them; the others are built and off because their I/O cost across the rotation is unmeasured. `hecks quality_control query sweep.run` refuses to start when a mode outside `TargetCapabilities::RUNNABLE_MODES` is enabled."
+      member name: "role_draw_probability", type: "Numeric",
+             meaning: "How often a generated role-gated command step carries a drawn caller (`role:`/`actor_id:`); 0 turns the draw off."
+      member name: "dry_run_fraction", type: "Numeric",
+             meaning: "Fraction of generated command steps offered as a dry run instead of a real dispatch; 0 is off. Kept low: a dry run creates no state for later steps to act on."
+      member 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."
+      member name: "generated_domains_rust", type: "Boolean",
+             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: "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
+
+    # What each retired `bin/` script became in hecks 3.0.0 (ADR 0080, section 7): one row per
+    # command or query that answers it, so a script that became several verbs has several rows.
+    # hecks project_tools_doc writes the launcher forms into the marked tables of docs/tools.md,
+    # rendering each form from the command's own arguments, so a form can neither keep an argument
+    # 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
+    # preceded. `aggregate` and `verb` name the command (or, in QualityControl, the query) the way
+    # the launcher spells it, `aggregate.verb`.
+    #
+    # The rest is only what the arguments cannot say: `passes` documents the flags a command hands
+    # through to the tool it wraps (its `arguments=` word), `note` is a sentence kept beside the
+    # form, and `form` replaces the rendered form when a launcher route spells it its own way.
+    value_object "RetiredScript" do
+      attribute :script,    String
+      attribute :section,   String
+      attribute :aggregate, String
+      attribute :verb,      String
+      attribute :passes,    String, optional: true
+      attribute :note,      String, optional: true
+      attribute :form,      String, optional: true
+
+      member script: "ir", section: "Custodian", aggregate: "Introspection", verb: "ir"
+      member script: "shape", section: "Custodian", aggregate: "Introspection", verb: "shape"
+      member script: "stores", section: "Custodian", aggregate: "Introspection", verb: "stores"
+      member script: "history", section: "Custodian", aggregate: "Introspection", verb: "history"
+      member script: "statements", section: "Custodian", aggregate: "Introspection", verb: "statements"
+      member script: "narrate", section: "Custodian", aggregate: "Introspection", verb: "narrate"
+      member script: "docs", section: "Custodian", aggregate: "Introspection", verb: "docs"
+      member script: "project_diagrams", section: "Custodian", aggregate: "Introspection", verb: "project_diagrams"
+      member script: "project_glossary", section: "Custodian", aggregate: "Introspection", verb: "glossary"
+      member script: "model_check", section: "Custodian", aggregate: "ModelCheckRun", verb: "model_check"
+      member script: "run", section: "Custodian", aggregate: "Operation", verb: "run", form: "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+      member script: "project", section: "Custodian", aggregate: "Operation", verb: "refresh_projections"
+      member script: "behaviors", section: "Custodian", aggregate: "Operation", verb: "run_behaviors"
+      member script: "console", section: "Custodian", aggregate: "Operation", verb: "open_console"
+      member script: "follow", section: "Custodian", aggregate: "Operation", verb: "follow"
+      member script: "smoke_test", section: "Custodian", aggregate: "Operation", verb: "smoke_test"
+      member script: "smoke_http", section: "Custodian", aggregate: "Operation", verb: "smoke_http"
+      member script: "check_era", section: "Custodian", aggregate: "Host", verb: "check_era"
+      member script: "merge_tail", section: "Custodian", aggregate: "Era", verb: "merge_tail"
+      member script: "reattest_era", section: "Custodian", aggregate: "Era", verb: "reattest"
+      member script: "backfill_era_projections", section: "Custodian", aggregate: "Era", verb: "backfill_projections"
+      member script: "scaffold_translation", section: "Custodian", aggregate: "Era", verb: "scaffold_translation"
+      member script: "translation_audit", section: "Custodian", aggregate: "Era", verb: "audit_translation"
+      member script: "translation_audit", section: "Custodian", aggregate: "Era", verb: "approve_translation"
+      member script: "compact", section: "Custodian", aggregate: "Era", verb: "compact"
+      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: "Door", verb: "project_cli"
+      member script: "hecks_mcp_door", section: "Custodian", aggregate: "Door", 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"
+      member script: "project_wasm_browser", section: "Custodian", aggregate: "Build", verb: "build_browser_wasm"
+      member script: "rust_coverage", section: "Custodian", aggregate: "Build", verb: "rust_coverage"
+      member script: "rust_coverage", section: "Custodian", aggregate: "Build", verb: "check_coverage_allowlist"
+      member script: "rust_conformance", section: "Custodian", aggregate: "Build", verb: "check_conformance"
+      member script: "rust_conformance_fuzz", section: "Custodian", aggregate: "Build", verb: "fuzz_conformance"
+      member script: "fuzz", section: "Custodian", aggregate: "FuzzRun", verb: "fuzz"
+      member script: "generate", section: "Custodian", aggregate: "FuzzRun", verb: "generate_sequence"
+      member script: "bench", section: "Custodian", aggregate: "FuzzRun", verb: "bench"
+      member script: "(new)", section: "Custodian", aggregate: "Era", verb: "hold_first"
+      member script: "project_deploy", section: "Deploy", aggregate: "Recipe", verb: "project"
+      member script: "lint_deploy_recipes", section: "Deploy", aggregate: "MakefileCheck", verb: "lint"
+      member script: "deploy_template_diff", section: "Deploy", aggregate: "TemplateComparison", verb: "diff"
+      member script: "project_oidc", section: "Deploy", aggregate: "OidcManifest", verb: "project_oidc"
+      member script: "project_tenant", section: "Deploy", aggregate: "Tenant", verb: "provision"
+      member script: "project_tenant", section: "Deploy", aggregate: "Tenant", verb: "reprovision"
+      member script: "(new)", section: "Site", aggregate: "SiteProjection", verb: "project_site"
+      member script: "project_model", section: "Codebase", aggregate: "LanguageRun", verb: "project_model"
+      member script: "project_vocabulary", section: "Codebase", aggregate: "LanguageRun", verb: "project_vocabulary"
+      member script: "project_rust_vocabulary", section: "Codebase", aggregate: "LanguageRun", verb: "project_rust_vocabulary"
+      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_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"
+      member script: "reference", section: "Codebase", aggregate: "LanguageRun", verb: "project_reference"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "word_status"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "propose"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "admit"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "deprecate"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "retire"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "rename"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "propose_argument"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "admit_argument"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "deprecate_argument"
+      member script: "evolve", section: "Codebase", aggregate: "LanguageRun", verb: "retire_argument"
+      member script: "project_kernel_capabilities", section: "Codebase", aggregate: "KernelRun", verb: "project_kernel_capabilities"
+      member script: "rust_kernel_coverage", section: "Codebase", aggregate: "KernelRun", verb: "measure_kernel_coverage"
+      member script: "check_engine_agreement", section: "Codebase", aggregate: "ConformanceRun", verb: "check_engine_agreement"
+      member script: "doc_coverage", section: "Codebase", aggregate: "ConformanceRun", verb: "measure_doc_coverage"
+      member script: "argument_gate_matrix", section: "Codebase", aggregate: "ConformanceRun", verb: "argument_gate_matrix"
+      member script: "regen_codegen_domains", section: "Codebase", aggregate: "RegenerationRun", verb: "regenerate_corpus"
+      member script: "standardize_comments", section: "Codebase", aggregate: "StyleRun", verb: "report_comments"
+      member script: "standardize_comments", section: "Codebase", aggregate: "StyleRun", verb: "check_comments"
+      member script: "standardize_comments", section: "Codebase", aggregate: "StyleRun", verb: "fix_comments"
+      member script: "standardize_comments", section: "Codebase", aggregate: "StyleRun", verb: "write_comment_baseline"
+      member script: "standardize_comments", section: "Codebase", aggregate: "StyleRun", verb: "check_comments_unchanged"
+      member script: "standardize_comments_rust", section: "Codebase", aggregate: "StyleRun", verb: "report_rust_comments"
+      member script: "standardize_comments_rust", section: "Codebase", aggregate: "StyleRun", verb: "check_rust_comments"
+      member script: "standardize_comments_rust", section: "Codebase", aggregate: "StyleRun", verb: "fix_rust_comments"
+      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: "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"
+      member script: "refresh_rspec_runtime_baseline", section: "Codebase", aggregate: "TestSuiteRun", verb: "refresh_runtime_baseline"
+      member script: "spec_example", section: "Codebase", aggregate: "TestSuiteRun", verb: "run_spec_example"
+      member script: "stress_concurrency_specs", section: "Codebase", aggregate: "TestSuiteRun", verb: "stress_concurrency"
+      member script: "regenerate_persistence_legacy_fixtures", section: "Codebase", aggregate: "TestSuiteRun", verb: "regenerate_legacy_fixtures"
+      member script: "seed_semantics_corpus", section: "Codebase", aggregate: "TestSuiteRun", verb: "seed_semantics_corpus"
+      member script: "pattern-cases", section: "Codebase", aggregate: "TestSuiteRun", verb: "record_pattern_cases"
+      member script: "corpus", section: "Codebase", aggregate: "CorpusRun", verb: "rust_domains"
+      member script: "corpus", section: "Codebase", aggregate: "CorpusRun", verb: "regen_order"
+      member script: "corpus", section: "Codebase", aggregate: "CorpusRun", verb: "corpus_rust_coverage"
+      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: "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_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"
+      member script: "qa_open_pr", section: "QualityControl", aggregate: "Patch", verb: "open"
+      member script: "qa_open_pr", section: "QualityControl", aggregate: "Improvement", verb: "open"
+      member script: "qa_log_bug", section: "QualityControl", aggregate: "Bug", verb: "log"
+      member script: "qa_seed_angles", section: "QualityControl", aggregate: "Angle", verb: "seed"
+      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: "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_concurrency_racer", section: "QualityControl", aggregate: "Sweep", verb: "race", note: "not user-facing; ProcessPool starts it"
+    end
+
     # Rust keywords (strict + reserved) a generated identifier must not
-    # collide with. RustProjection::Projector::RUST_KEYWORDS reads this;
-    # hecks project_reserved_names projects it into
-    # rust/codegen/src/reserved_names.rs, so Ruby and Rust escape or refuse
-    # the same words from one declaration instead of two hand-typed copies.
+    # collide with. ModelCheck reads this; hecks project_reserved_names
+    # projects it into rust/codegen/src/reserved_names.rs, so Ruby and Rust
+    # escape or refuse the same words from one declaration instead of two
+    # hand-typed copies.
     value_object "RustReservedWord" do
       attribute :word, String,
                 one_of: ["as", "break", "const", "continue", "crate", "dyn", "else", "enum", "extern", "false",
@@ -648,8 +861,8 @@ Hecks.bluebook "Bluebook" do
     # as a Cargo `[features]` key: every key rust/Cargo.toml already uses
     # outside `[features]` (`[package]`, `[lib]`, `[[bin]]`) plus `default`,
     # which Cargo reserves for the auto-enabled feature set. Read by
-    # RustProjection::Projector::CARGO_RESERVED_DOMAIN_NAMES and projected by
-    # hecks project_reserved_names, same as RustReservedWord above.
+    # Hecks::RustBuild::DomainName and projected by hecks
+    # project_reserved_names, same as RustReservedWord above.
     value_object "CargoReservedName" do
       attribute :name, String,
                 one_of: ["name", "version", "edition", "path", "authors", "license", "description", "default",

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

@@ -83,7 +83,7 @@ Hecks.bluebook "Hecksagon" do
       member word: "hecksagon",       context: "File",     body: "keywords", inner: "Hecksagon",      opens: "Hecksagon",      fills: ""
       member word: "subscribe",       context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions"
       member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments"
-      # Deprecated spellings of `attaches`; they warn and are removed in 3.2.0.
+      # Deprecated spellings of `attaches`; they warn and are removed in 3.4.0.
       member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
       member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
       member word: "port",            context: "Hecksagon",     body: "keywords", inner: "DomainPort",    opens: "DomainPort",    fills: "", calls: "port_impl"

data/lib/hecks/language/oidc.json

@@ -236,6 +236,11 @@
       "verb": "Bluebook::Query.Filter",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:query.need",
+      "verb": "Bluebook::Query.Need",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:query.option",
       "verb": "Bluebook::Query.Option",

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -58,7 +58,7 @@ module Hecks
         # @return [String] the `era` the host's `/version` document carries
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_era(url, timeout: 10)
+        def fetch_era(url, timeout:)
           fetch_version(url, timeout: timeout).fetch("era")
         end
 
@@ -70,7 +70,7 @@ module Hecks
         #   host reports none)
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_version(url, timeout: 10)
+        def fetch_version(url, timeout:)
           response = get(version_url(url), timeout)
           raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
 
@@ -105,7 +105,7 @@ module Hecks
         # @raise [Errno::ENOENT] if the allow-list file does not exist
         # @raise [Unreachable] see `fetch_era`
         # @raise [BadResponse] see `fetch_era`
-        def check(url, file, timeout: 10)
+        def check(url, file, timeout:)
           allowed = parse(File.read(file))
           verdict(fetch_era(url, timeout: timeout), allowed)
         end

data/lib/hecks/projections/deploy/box/hosting.rb

@@ -0,0 +1,170 @@
+require "shellwords"
+require_relative "../scripts"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The hosting scripts an AWS box deploy ships beside its stacks when the world sets
+        # `hosting_scripts true`: the steps an operator runs once `make stacks` has created the box.
+        # Container names, repositories, parameters and stacks come from the resolved plan, never
+        # from this file.
+        module Hosting
+          module_function
+
+          # Adds the hosting scripts to a box file map when the world opts in.
+          #
+          # @param files [Hash{String => String}] the box target's own files, keyed by path
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated AWS region
+          # @return [Hash{String => String}] `files` itself without the opt-in, else a copy with
+          #   `hosting.mk`, `deploy-service.sh`, `smoke-after-deploy.sh` and `expected-era`
+          def extend_files(files, plan:, region:)
+            return files unless plan.hosting
+
+            files.merge(
+              "hosting.mk"            => hosting_mk(plan),
+              "deploy-service.sh"     => deploy_service_sh(plan, region),
+              "smoke-after-deploy.sh" => smoke_after_deploy_sh(plan, region),
+              "expected-era"          => Scripts.expected_era(plan.hosting)
+            )
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the Makefile fragment the box `Makefile` includes
+          def hosting_mk(plan)
+            Box.template("hosting.mk.tmpl", "SERVICE" => plan.containers.first.name,
+                                            "URL"     => plan.hosting.public_url.to_s)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated AWS region
+          # @return [String] `deploy-service.sh`
+          def deploy_service_sh(plan, region)
+            roll = plan.task_definition ? "deploy-service.taskdef-roll.part" : "deploy-service.services-roll.part"
+            Box.template("deploy-service.sh.tmpl",
+                         "STACK" => plan.infra_name, "MODE_SUMMARY" => mode_summary(plan),
+                         "SETTINGS" => deploy_constants(plan, region), "SERVICES" => services_block(plan),
+                         "REPOSITORY_STEP" => repository_step(plan),
+                         "ROLL_STEPS" => part(roll))
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated AWS region
+          # @return [String] `smoke-after-deploy.sh`
+          def smoke_after_deploy_sh(plan, region)
+            hosting = plan.hosting
+            image_stack = hosting.stack
+            Box.template("smoke-after-deploy.sh.tmpl",
+                         "STACK" => plan.infra_name, "SETTINGS" => smoke_constants(plan, region),
+                         "SETTLE_CHECKS" => settle_checks(plan),
+                         "IMAGE_STACK_WAIT" => image_stack ? ", stack #{image_stack}" : "")
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the sentence that says what the roll puts on the box
+          def mode_summary(plan)
+            if plan.task_definition
+              <<~TEXT.gsub(/^/, "# ").chomp
+                It then sets the stack's matching image-tag parameter (UsePreviousValue for every other
+                one, and it checks that only that one changed), reads the task definition the stack
+                registers, refuses to roll it unless it carries the pushed image, and rolls it with
+                deploy-box.sh.
+              TEXT
+            else
+              <<~TEXT.gsub(/^/, "# ").chomp
+                It then rolls the box with deploy-box.sh, naming the new tag for this container and the
+                tag the box runs now for every other one.
+              TEXT
+            end
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the comment lines that list what "settled" means
+          def settle_checks(plan)
+            stacks = plan.hosting.stack ? "the box stack and the #{plan.hosting.stack} stack are" : "the box stack is"
+            checks = ["#{stacks} CREATE_COMPLETE or UPDATE_COMPLETE, never rolled back or failed;",
+                      "every container and the proxy of the box's Compose project is up and has stayed up;"]
+            if plan.task_definition
+              checks << "each container runs the image of the task definition it was rolled from (the latest " \
+                        "#{plan.task_definition} unless TASKDEF says otherwise)."
+            end
+            checks.map { |line| "#      - #{line}" }.join("\n")
+          end
+
+          def deploy_constants(plan, region)
+            lines = { "REGION" => region }
+            if plan.task_definition
+              lines["FAMILY"] = plan.task_definition
+              lines["IMAGE_STACK"] = plan.hosting.stack
+            else
+              lines["BOX_STACK"] = plan.box_stack
+              lines["BOX_DIR"] = "/opt/#{plan.infra_name}"
+            end
+            constants(lines)
+          end
+
+          def smoke_constants(plan, region)
+            hosting = plan.hosting
+            watched = [plan.box_stack, hosting.stack].compact
+            constants(
+              "REGION" => region, "BOX_STACK" => plan.box_stack, "BOX_DIR" => "/opt/#{plan.infra_name}",
+              "WATCHED_STACKS" => watched.join(" "),
+              "EXPECTED_SERVICES" => (plan.containers.map(&:name) + ["caddy"]).join(" ")
+            ).concat("\n#{smoke_defaults(plan)}")
+          end
+
+          def smoke_defaults(plan)
+            hosting = plan.hosting
+            [
+              "TASK_DEFINITION=\"${TASKDEF:-#{plan.task_definition}}\"",
+              "REPO=\"${REPO:-#{hosting.smoke_repo}}\"",
+              "WORKFLOW=\"${WORKFLOW:-#{hosting.smoke_workflow}}\"",
+              "SMOKE_REF=\"${SMOKE_REF:-#{hosting.smoke_ref}}\""
+            ].join("\n")
+          end
+
+          def constants(values)
+            values.map { |name, value| "#{name}=#{Shellwords.escape(value)}" }.join("\n")
+          end
+
+          # One case arm per container that sets the repository and image-tag parameter to use, and
+          # the list of names the script accepts.
+          def services_block(plan)
+            arms = plan.containers.map do |container|
+              setting =
+                if plan.task_definition
+                  "CFN_PARAM_KEY=#{Shellwords.escape(container.tag_parameter)}"
+                else
+                  "ECR_REPOSITORY=#{Shellwords.escape(container.repository)}"
+                end
+              "    #{Shellwords.escape(container.name)}) #{setting} ;;"
+            end
+            <<~BASH.chomp
+              SERVICES='#{plan.containers.map(&:name).join(' ')}'
+
+              # Sets the container's settings for one service, or exits.
+              resolve_service() {
+                case "$1" in
+              #{arms.join("\n")}
+                  *) echo "unknown service '$1', must be one of: ${SERVICES}" >&2; exit 1 ;;
+                esac
+              }
+            BASH
+          end
+
+          def repository_step(plan)
+            plan.task_definition ? "#{part('deploy-service.taskdef.part')}\n\n" : ""
+          end
+
+          def part(file)
+            file ? File.read(File.join(Box::TEMPLATE_DIR, file)).chomp : ""
+          end
+
+          private_class_method :deploy_constants, :smoke_constants, :smoke_defaults, :constants,
+                               :services_block, :part, :repository_step, :settle_checks
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/hosting_settings.rb

@@ -0,0 +1,123 @@
+require_relative "../scripts/settings"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The hosting words of a `deployed_to("AwsBox")` block: `hosting_scripts true` and the
+        # settings the generated `deploy-service.sh`, `smoke-after-deploy.sh` and `expected-era`
+        # read. Every value is matched against a conservative pattern before a script splices it in.
+        module HostingSettings
+          PARAMETER = /\A[A-Za-z][A-Za-z0-9]{0,254}\z/
+          STACK     = /\A[a-zA-Z][a-zA-Z0-9-]{0,127}\z/
+          PUBLIC_URL = %r{\Ahttps?://[^\s'"$`\\]+\z}
+          # The words that only mean something to the hosting scripts.
+          WORDS = %i[hosting_stack smoke_repo smoke_workflow smoke_ref expected_eras public_url].freeze
+
+          # The checked hosting settings.
+          #
+          # @!attribute [r] stack [String, nil] the CloudFormation stack whose image-tag parameters
+          #   feed the task definition; nil without a `task_definition`
+          # @!attribute [r] smoke_repo [String, nil] the GitHub repository holding the workflow
+          # @!attribute [r] smoke_workflow [String] the smoke workflow's file name
+          # @!attribute [r] smoke_ref [String] the ref the smoke workflow is dispatched on
+          # @!attribute [r] expected_eras [Array<String>] the eras `expected-era` lists
+          # @!attribute [r] public_url [String, nil] the live site, for `make check-era`
+          Hosting = Struct.new(:stack, :smoke_repo, :smoke_workflow, :smoke_ref, :expected_eras,
+                               :public_url, keyword_init: true)
+
+          module_function
+
+          # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+          # @param task_definition [String, nil] the declared task definition family
+          # @return [Hosting, nil] the checked settings, or nil when the world has not opted in
+          # @raise [ArgumentError] when a hosting word is invalid, missing or has nothing to act on
+          def read(settings, task_definition)
+            flag = settings.fetch(:hosting_scripts, false)
+            raise ArgumentError, "hosting_scripts: #{flag.inspect} must be true or false" unless [true, false].include?(flag)
+
+            unless flag
+              stray = WORDS.select { |word| settings.key?(word) }
+              raise ArgumentError, "#{stray.join(', ')} only apply with hosting_scripts true" unless stray.empty?
+
+              return nil
+            end
+
+            Hosting.new(stack: read_stack(settings, task_definition), **read_smoke(settings),
+                        expected_eras: eras(settings), public_url: optional(settings, :public_url, PUBLIC_URL))
+          end
+
+          # With a task definition, the stack that registers its revisions is where a new image tag
+          # goes, so it has to be named. Without one the box is rolled from `services.json` and no
+          # stack holds a tag.
+          def read_stack(settings, task_definition)
+            stack = settings[:hosting_stack]
+            if task_definition.nil?
+              raise ArgumentError, "hosting_stack names the stack behind a task_definition; this world has none" if stack
+
+              return nil
+            end
+            raise ArgumentError, missing_stack(task_definition) if stack.nil?
+
+            check(:hosting_stack, stack, STACK)
+          end
+
+          def read_smoke(settings)
+            workflow = settings[:smoke_workflow]
+            raise ArgumentError, missing_workflow if workflow.nil?
+
+            {
+              smoke_workflow: check(:smoke_workflow, workflow, Scripts::Settings::WORKFLOW),
+              smoke_repo:     optional(settings, :smoke_repo, Scripts::Settings::GITHUB_REPO),
+              smoke_ref:      check(:smoke_ref, settings.fetch(:smoke_ref, "main"), Scripts::Settings::REF)
+            }
+          end
+
+          def eras(settings)
+            Array(settings.fetch(:expected_eras, [])).map { |era| check(:expected_eras, era.to_s, Scripts::Settings::ERA) }
+          end
+
+          def optional(settings, key, pattern)
+            value = settings[key]
+            value.nil? ? nil : check(key, value, pattern)
+          end
+
+          def check(key, value, pattern)
+            return value if value.is_a?(String) && value.match?(pattern)
+
+            raise ArgumentError, "#{key}: #{value.inspect} does not match #{pattern.inspect}"
+          end
+
+          def missing_workflow
+            <<~MSG
+              deployed_to("AwsBox") enables hosting_scripts but names no smoke_workflow. Name the GitHub
+              workflow file the post-deploy smoke dispatches, e.g.:
+
+                  deployed_to("AwsBox") do
+                    ...
+                    hosting_scripts true
+                    smoke_workflow "smoke-prod.yml"
+                  end
+
+              A deploy that ends without a smoke of the live site cannot tell a roll that took from one
+              that only looked live.
+            MSG
+          end
+
+          def missing_stack(family)
+            <<~MSG
+              deployed_to("AwsBox") enables hosting_scripts with task_definition #{family.inspect} but names no
+              hosting_stack. Name the CloudFormation stack whose TaskDefinition resource reads an image-tag
+              parameter per container (`<Name>ImageTag` unless a container sets `tag_parameter`), e.g.:
+
+                  hosting_stack "my-platform"
+
+              deploy-service.sh sets that parameter to the tag it pushed, so the stack, not a hand-registered
+              revision, is the source of truth for what runs.
+            MSG
+          end
+        end
+      end
+    end
+  end
+end