hecks 3.2.1 → 3.3.0

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

@@ -630,6 +630,219 @@ Hecks.bluebook "Bluebook" do
              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. ModelCheck reads this; hecks project_reserved_names
     # projects it into rust/codegen/src/reserved_names.rs, so Ruby and Rust

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.3.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/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

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

@@ -1,3 +1,5 @@
+require_relative "hosting_settings"
+
 module Hecks
   module Projections
     module Deploy
@@ -47,7 +49,9 @@ module Hecks
           # @!attribute [r] env [Hash{String => String}] plain environment variables
           # @!attribute [r] secrets [Hash{String => String}] environment variable => secret name,
           #   resolved on the box at deploy time and never written into a template
-          Container = Struct.new(:name, :repository, :port, :env, :secrets, keyword_init: true)
+          # @!attribute [r] tag_parameter [String] the stack parameter that holds this container's
+          #   image tag, which a hosting `deploy-service.sh` sets
+          Container = Struct.new(:name, :repository, :port, :env, :secrets, :tag_parameter, keyword_init: true)
 
           # A set of URL paths one container serves.
           #
@@ -82,7 +86,7 @@ module Hecks
             :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
             :containers, :routes, :default_container, :origin_header, :origin_secret,
             :secret_prefixes, :writable_secrets, :origin_env, :tunnel, :tunnel_service, :proxy_image, :task_definition,
-            :migration, :s3_buckets, keyword_init: true
+            :migration, :s3_buckets, :hosting, keyword_init: true
           ) do
             # @return [String] the CloudFormation stack that holds the database
             def rds_stack = "#{stack_prefix}-#{infra_name}-rds"
@@ -126,7 +130,8 @@ module Hecks
               tunnel: tunnel, tunnel_service: tunnel_service,
               proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
               task_definition: task_definition, migration: read_migration(s[:migration], database_name),
-              s3_buckets: read_s3_access(s.fetch(:s3_access, []))
+              s3_buckets: read_s3_access(s.fetch(:s3_access, [])),
+              hosting: HostingSettings.read(s, task_definition)
             )
           end
 
@@ -224,10 +229,18 @@ module Hecks
               name: name, repository: check(:repository, spec.fetch(:repository, "#{infra_name}-#{name}"), REPOSITORY),
               port: integer(:port, spec.fetch(:port) { raise ArgumentError, "containers: #{name} has no port" }, 1, 65_535),
               env: string_map(:env, spec.fetch(:env, {}), ENV_KEY, ENV_VALUE),
-              secrets: string_map(:secrets, spec.fetch(:secrets, {}), ENV_KEY, SECRET_NAME)
+              secrets: string_map(:secrets, spec.fetch(:secrets, {}), ENV_KEY, SECRET_NAME),
+              tag_parameter: check(:tag_parameter, spec.fetch(:tag_parameter, default_tag_parameter(name)),
+                                   HostingSettings::PARAMETER)
             )
           end
 
+          # @param name [String] a container name such as `web-app`
+          # @return [String] the image-tag parameter a stack names it by, such as `WebAppImageTag`
+          def default_tag_parameter(name)
+            "#{name.split('-').map(&:capitalize).join}ImageTag"
+          end
+
           def read_routes(list, containers)
             raise ArgumentError, "routes: expected a list" unless list.is_a?(Array)
 

data/lib/hecks/projections/deploy/box/templates/deploy-service.services-roll.part

@@ -0,0 +1,33 @@
+# deploy-box.sh renders every container the roll does not name at "latest". Name the tag each other
+# container runs now, read from the box's own Compose file, so rolling one service leaves the rest alone.
+BOX_ID="$(aws cloudformation describe-stacks --stack-name "$BOX_STACK" --region "$REGION" \
+  --query "Stacks[0].Outputs[?OutputKey=='InstanceId'].OutputValue" --output text)"
+[ -n "$BOX_ID" ] && [ "$BOX_ID" != None ] || { echo "no instance in stack ${BOX_STACK}" >&2; exit 1; }
+
+echo "==> reading the tags the box runs now"
+READ_JSON="$(jq -n --arg c "cat ${BOX_DIR}/compose.json 2>/dev/null || echo '{}'" '{commands: [$c]}')"
+COMMAND_ID="$(aws ssm send-command --instance-ids "$BOX_ID" --document-name AWS-RunShellScript --region "$REGION" \
+  --parameters "$READ_JSON" --query 'Command.CommandId' --output text)"
+for _ in $(seq 1 30); do
+  sleep 2
+  state="$(aws ssm get-command-invocation --command-id "$COMMAND_ID" --instance-id "$BOX_ID" --region "$REGION" \
+    --query Status --output text 2>/dev/null || echo Pending)"
+  [ "$state" != InProgress ] && [ "$state" != Pending ] && break
+done
+[ "$state" = Success ] || { echo "could not read the box's Compose file (${state}); nothing was rolled" >&2; exit 1; }
+aws ssm get-command-invocation --command-id "$COMMAND_ID" --instance-id "$BOX_ID" --region "$REGION" \
+  --query StandardOutputContent --output text > "${SCRATCH_DIR}/compose.json"
+
+TAGS=()
+for name in $SERVICES; do
+  if [ "$name" = "$SERVICE_NAME" ]; then
+    TAGS+=("${name}=${TAG}")
+    continue
+  fi
+  image="$(jq -r --arg n "$name" '.services[$n].image // empty' "${SCRATCH_DIR}/compose.json")"
+  # A container the box does not run yet starts at its "latest" image.
+  if [ -n "$image" ]; then TAGS+=("${name}=${image##*:}"); fi
+done
+echo "==> rolling ${TAGS[*]}"
+
+bash ./deploy-box.sh "${TAGS[@]}"