hecks 3.0.4 → 3.1.0

data/lib/hecks/three_zero/forms.yml

@@ -1,127 +1,127 @@
 # Each bin/ script and exe/hecks route, and the hecks 3.0 form that replaces it: the verb spelling the
 # 3.0 launcher answers to (ADR 0080, section 7), with QualityControl verbs after `hecks quality_control`.
 ---
-argument_gate_matrix: hecks argument_gate_matrix [--confirm] (writes only with --confirm)
-backfill_era_projections: hecks backfill_projections <domain>
-behaviors: hecks run_behaviors subject=<path>
-bench: hecks bench [domains=pizzas,banking] [targets=] [iterations=1000] [warmup=200]
+argument_gate_matrix: hecks conformance_run.argument_gate_matrix [--confirm] (writes only with --confirm)
+backfill_era_projections: hecks era.backfill_projections <domain>
+behaviors: hecks operation.run_behaviors subject=<path>
+bench: hecks fuzz_run.bench [domains=pizzas,banking] [targets=] [iterations=1000] [warmup=200]
   [runs=3] [rust_binary=] [format=markdown] [output=]
-canonicalise: hecks canonicalise <file.json>
-check_engine_agreement: hecks check_engine_agreement
-check_era: hecks check_era <url> expected=era-file [timeout=10]
-codemod_hoist_local_givens: hecks hoist_local_givens --confirm
-codemod_implicit_append_fields: hecks drop_implicit_append_fields --confirm
-compact: hecks compact <domain> [aggregates=A,B] --confirm
+canonicalise: hecks style_run.canonicalise <file.json>
+check_engine_agreement: hecks conformance_run.check_engine_agreement
+check_era: hecks host.check_era <url> expected=era-file [timeout=]
+codemod_hoist_local_givens: hecks codemod_run.hoist_local_givens --confirm
+codemod_implicit_append_fields: hecks codemod_run.drop_implicit_append_fields --confirm
+compact: hecks era.compact <domain> [aggregates=A,B] --confirm
 console: hecks console [subject=<domain>]
-corpus: hecks rust_domains; hecks regen_order; hecks corpus_rust_coverage
-deploy_template_diff: hecks deploy diff before=a.yaml after=b.yaml [--json] [--strict]
-doc_coverage: hecks measure_doc_coverage
+corpus: hecks corpus_run.rust_domains; hecks corpus_run.regen_order; hecks corpus_run.corpus_rust_coverage
+deploy_template_diff: hecks deploy template_comparison.diff before=a.yaml after=b.yaml [--json] [--strict]
+doc_coverage: hecks conformance_run.measure_doc_coverage
 docs: hecks docs [domain-path] [aggregate]
-evolve: hecks word_status; hecks propose <word> context=X [body=none] [inner=] [opens=]
-  [fills=]; hecks admit|deprecate|retire <word> context=X; hecks rename <word> context=X
-  new_name=Y; hecks propose_argument <word> context=X kind=K [required=false] [at=N]
-  [named=] [fills=] [pairs_shape=]; hecks admit_argument|deprecate_argument|retire_argument
+evolve: hecks language_run.word_status; hecks language_run.propose <word> context=X [body=none] [inner=] [opens=]
+  [fills=]; hecks language_run.admit|deprecate|retire <word> context=X; hecks language_run.rename <word> context=X
+  new_name=Y; hecks language_run.propose_argument <word> context=X kind=K [required=false] [at=N]
+  [named=] [fills=] [pairs_shape=]; hecks language_run.admit_argument|deprecate_argument|retire_argument
   <word> context=X [at=N] [named=]
-expression_projection: hecks project_expression_tables [--stdout]
-follow: hecks follow <domain> [aggregate=Name] [since=N] [interval=0.5] [wait=N] [--from-now] [--stream]
-fuzz: hecks fuzz [domain] [seeds=20] [steps=30] [workers=] [adapter=memory]
-generate: hecks generate_sequence <domain> [seed=1] [steps=30] [adversarial=0.0]
+expression_projection: hecks language_run.project_expression_tables [--stdout]
+follow: hecks operation.follow <domain> [aggregate=Name] [since=N] [interval=0.5] [wait=N] [--from-now] [--stream]
+fuzz: hecks fuzz_run.fuzz [domain] [seeds=20] [steps=30] [workers=] [adapter=memory]
+generate: hecks fuzz_run.generate_sequence <domain> [seed=1] [steps=30] [adversarial=0.0]
 hecks_mcp_door: hecks mcp [--stdio]
-hecks_query_ir_mcp: hecks serve_query_ir_mcp
-heki_compact: hecks compact_heki <domain> [aggregates=A,B] --confirm
-history: hecks history <domain>
+hecks_query_ir_mcp: hecks corpus_run.serve_query_ir_mcp
+heki_compact: hecks era.compact_heki <domain> [aggregates=A,B] --confirm
+history: hecks introspection.history <domain>
 ir: hecks ir <domain> [--translations] | hecks ir --meta
-lint_deploy_recipes: hecks deploy lint [makefiles=a,b]
-merge_tail: hecks merge_tail <domain> winners=id:old,id:new --confirm
+lint_deploy_recipes: hecks deploy makefile_check.lint [makefiles=a,b]
+merge_tail: hecks era.merge_tail <domain> winners=id:old,id:new --confirm
 model_check: hecks model_check [--strict] [--profile client] [<domain> …]
 narrate: hecks narrate [domain-path] [aggregate]
-pattern-cases: hecks record_pattern_cases
-present: hecks present [port=4567]
-project: hecks refresh_projections subject=<domain>
-project_bootstrap_table: hecks project_bootstrap_table
+pattern-cases: hecks test_suite_run.record_pattern_cases
+present: hecks corpus_run.present [port=4567]
+project: hecks operation.refresh_projections subject=<domain>
+project_bootstrap_table: hecks language_run.project_bootstrap_table
 project_cli: hecks project_cli [domain-path …]
-project_deploy: hecks deploy project <domain> [tenant=] [schema=] [out=] [environment=]
+project_deploy: hecks deploy recipe.project <domain> [tenant=] [schema=] [out=] [environment=]
 project_diagrams: hecks project_diagrams <domain-path> <ChapterName>
-project_field_hints: hecks project_field_hints
-project_glossary: hecks glossary <domain> chapter=Name
-project_kernel_capabilities: hecks project_kernel_capabilities
-project_model: hecks project_model
-project_oidc: hecks deploy project_oidc [domains=a,b]
-project_parser_table: hecks project_parser_table
-project_refusal_wording: hecks project_refusal_wording
-project_reserved_names: hecks project_reserved_names
-project_rust: hecks project_rust <domain>
-project_rust_vocabulary: hecks project_rust_vocabulary
-project_tenant: hecks deploy provision <domain_dir> slug=s domain= realm= schema=
-  database= [adapter=PostgresEra]; hecks deploy reprovision <tenant> directory= database=
+project_field_hints: hecks language_run.project_field_hints
+project_glossary: hecks introspection.glossary <domain> chapter=Name
+project_kernel_capabilities: hecks kernel_run.project_kernel_capabilities
+project_model: hecks language_run.project_model
+project_oidc: hecks deploy oidc_manifest.project_oidc [domains=a,b]
+project_parser_table: hecks language_run.project_parser_table
+project_refusal_wording: hecks language_run.project_refusal_wording
+project_reserved_names: hecks language_run.project_reserved_names
+project_rust: hecks build.project_rust <domain>
+project_rust_vocabulary: hecks language_run.project_rust_vocabulary
+project_tenant: hecks deploy tenant.provision <domain_dir> slug=s domain= realm= schema=
+  database= [adapter=PostgresEra]; hecks deploy tenant.reprovision <tenant> directory= database=
   [adapter=PostgresEra]
-project_vocabulary: hecks project_vocabulary
-project_wasm: hecks build_wasm <domain>
-project_wasm_browser: hecks build_browser_wasm <domain>
+project_vocabulary: hecks language_run.project_vocabulary
+project_wasm: hecks build.build_wasm <domain>
+project_wasm_browser: hecks build.build_browser_wasm <domain>
 qa_concurrency_racer: not user-facing; ProcessPool starts it as hecks quality_control
-  race domain= database= schema= verb= step_arguments=
-qa_discover_external_domains: hecks quality_control discover_external_domains [arguments="--projects-dir
+  sweep.race domain= database= schema= verb= step_arguments=
+qa_discover_external_domains: hecks quality_control target.discover_external_domains [arguments="--projects-dir
   ~/Projects --max-depth 3 --known-path PATH …"]
-qa_domain_novelty: hecks quality_control judge_novelty <domain> [arguments="--against
+qa_domain_novelty: hecks quality_control target.judge_novelty <domain> [arguments="--against
   PATH …"]
-qa_generated_domains: hecks quality_control check_generated_domains [arguments="--domains
+qa_generated_domains: hecks quality_control target.check_generated_domains [arguments="--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"]
-qa_log_bug: hecks quality_control log sweep=<sweep id> reference= sequence=N title=
+qa_log_bug: hecks quality_control bug.log sweep=<sweep id> reference= sequence=N title=
   demonstration= symptom= expectation= submitter= [tags=a,b] [name=] [reproduced=yes|no]
-qa_mine_combinations: hecks quality_control mine_combinations [arguments="--candidates
+qa_mine_combinations: hecks quality_control target.mine_combinations [arguments="--candidates
   3 --rust --seeds 5 --steps 25 --adversarial 0.3 --repair-rounds 1 --agent CMD --from
   DIR --against PATH --brief"]
 qa_open_pr: hecks quality_control patch.open bug=BUG#n number=N url=… branch=… commit=SHA
   title=… [now=]; hecks quality_control improvement.open [angle=ANGLE-n] number=N
   url=… branch=… title=… [now=]
-qa_postgres_migrate: hecks quality_control migrate_ledger_from_heki domain=<domain_dir>
+qa_postgres_migrate: hecks quality_control sweep.migrate_ledger_from_heki domain=<domain_dir>
   data=<heki_dir> [arguments="[aggregate …] --force"] (a dry run without --force)
-qa_postgres_role: hecks quality_control create_ledger_role <database> [role=hecks_qa]
-qa_pr_check: hecks quality_control check_pull_requests
+qa_postgres_role: hecks quality_control sweep.create_ledger_role <database> [role=hecks_qa]
+qa_pr_check: hecks quality_control clearance.check_pull_requests
 qa_seed_angles: hecks quality_control angle.seed
 qa_seed_targets: hecks quality_control target.seed
-qa_sweep: hecks quality_control ask run [target=] [arguments="--all --seeds N --steps
+qa_sweep: hecks quality_control query sweep.run [target=] [arguments="--all --seeds N --steps
   N --adversarial F --role-draw F --dry-run F --self-consistency BOOL --modes a,b
-  --persistence-parity --no-parity"]; hecks quality_control release <target> [now=]
+  --persistence-parity --no-parity"]; hecks quality_control target.release <target> [now=]
   [next_streak=] [capabilities=] [yield_score=]
-qa_tick: hecks quality_control tick
-query_ir: hecks ir_constructs [names=a,b]; hecks ir_duplicates [domains=a,b] [--meta];
-  hecks ir_impact name=N field=F
-reattest_era: hecks reattest <domain> era=N --confirm
-reference: hecks project_reference
-refresh_rspec_runtime_baseline: hecks refresh_runtime_baseline [workers=6] [from_run=ID]
-regen_codegen_domains: hecks regenerate_corpus [--check]
-regenerate_persistence_legacy_fixtures: hecks regenerate_legacy_fixtures --confirm
-release: hecks publish [--gem-only] [--npm-only] [--npm-local] [--no-wait] --confirm
+qa_tick: hecks quality_control sweep.tick
+query_ir: hecks corpus_run.ir_constructs [names=a,b]; hecks corpus_run.ir_duplicates [domains=a,b] [--meta];
+  hecks corpus_run.ir_impact name=N field=F
+reattest_era: hecks era.reattest <domain> era=N --confirm
+reference: hecks language_run.project_reference
+refresh_rspec_runtime_baseline: hecks test_suite_run.refresh_runtime_baseline [workers=] [from_run=ID]
+regen_codegen_domains: hecks regeneration_run.regenerate_corpus [--check]
+regenerate_persistence_legacy_fixtures: hecks test_suite_run.regenerate_legacy_fixtures --confirm
+release: hecks publishing_run.publish [--gem-only] [--npm-only] [--npm-local] [--no-wait] --confirm
   (without --confirm, the old --dry-run)
-release_gem: hecks publish_gem --confirm
-rspec_io_parallel_files: hecks list_io_parallel_specs exclude=REGEX [tags=] [check=file];
-  hecks write_io_parallel_spec_list exclude=REGEX [tags=] write=file --confirm
-rspec_shard_files: hecks shard_specs group=1 groups=N [runtime_log=]
+release_gem: hecks publishing_run.publish_gem --confirm
+rspec_io_parallel_files: hecks test_suite_run.list_io_parallel_specs exclude=REGEX [tags=] [check=file];
+  hecks test_suite_run.write_io_parallel_spec_list exclude=REGEX [tags=] write=file --confirm
+rspec_shard_files: hecks test_suite_run.shard_specs group=1 groups=N [runtime_log=]
 run: hecks run [domain] <verb [name=value …] | script.json | - | '{"steps":[…]}'>
-rust_conformance: hecks check_conformance <domain> script=steps.json [artifact=native]
-rust_conformance_fuzz: hecks fuzz_conformance <domain> artifact=native [seeds=10]
+rust_conformance: hecks build.check_conformance <domain> script=steps.json [artifact=native]
+rust_conformance_fuzz: hecks build.fuzz_conformance <domain> artifact=native [seeds=10]
   [steps=25]
-rust_coverage: hecks rust_coverage <module> [codegen=ruby]; hecks check_coverage_allowlist
-rust_kernel_coverage: hecks measure_kernel_coverage
-scaffold_translation: hecks scaffold_translation <domain>
-seed_semantics_corpus: hecks seed_semantics_corpus [fixture=name]
-shape: hecks shape <domain>
-smoke_http: hecks smoke_http path=/p [url=] [header=] [scheme=timestamped]
+rust_coverage: hecks build.rust_coverage <module> [codegen=ruby]; hecks build.check_coverage_allowlist
+rust_kernel_coverage: hecks kernel_run.measure_kernel_coverage
+scaffold_translation: hecks era.scaffold_translation <domain>
+seed_semantics_corpus: hecks test_suite_run.seed_semantics_corpus [fixture=name]
+shape: hecks introspection.shape <domain>
+smoke_http: hecks operation.smoke_http path=/p [url=] [header=] [scheme=timestamped]
   [payload=] [payload_file=] [health_path=] [state_path=]
 smoke_test: hecks smoke_test [domain]
-spec_example: hecks run_spec_example file=path example=text
-standardize_comments: hecks report_comments paths=a,b [only=] [--json] [top=20]; hecks
-  check_comments paths=…; hecks fix_comments paths=… --confirm; hecks write_comment_baseline
-  --confirm; hecks check_comments_unchanged ref=REF
-standardize_comments_rust: hecks report_rust_comments paths=a,b [only=] [--json] [top=N];
-  hecks check_rust_comments paths=… [only=]; hecks fix_rust_comments paths=… [only=]
+spec_example: hecks test_suite_run.run_spec_example file=path example=text
+standardize_comments: hecks style_run.report_comments paths=a,b [only=] [--json] [top=20]; hecks
+  style_run.check_comments paths=…; hecks style_run.fix_comments paths=… --confirm; hecks style_run.write_comment_baseline
+  --confirm; hecks style_run.check_comments_unchanged ref=REF
+standardize_comments_rust: hecks style_run.report_rust_comments paths=a,b [only=] [--json] [top=N];
+  hecks style_run.check_rust_comments paths=… [only=]; hecks style_run.fix_rust_comments paths=… [only=]
   --confirm
-statements: hecks statements <domain> chapter=Name
+statements: hecks introspection.statements <domain> chapter=Name
 stores: hecks stores <domain>
-stress_concurrency_specs: hecks stress_concurrency [runs=30] [parallel=] [seed_start=1]
-translation_audit: hecks audit_translation <domain>; hecks approve_translation <domain>
+stress_concurrency_specs: hecks test_suite_run.stress_concurrency [runs=] [parallel=] [seed_start=]
+translation_audit: hecks era.audit_translation <domain>; hecks era.approve_translation <domain>
   [snapshot=] [host_version=] [rehearsal=pass|fail] [rehearsed_at=] --confirm
-vendor_bluebook: hecks vendor <package[@version]> [from=path] [root=path]
+vendor_bluebook: hecks package.vendor <package[@version]> [from=path] [root=path]

data/lib/hecks/tools/ci_gates.rb

@@ -102,7 +102,7 @@ module Hecks
           "      - uses: ./.github/actions/hecks-environment",
           "      - id: diff",
           "        name: #{quoted(gate.fetch('label'))}",
-          "        run: bundle exec exe/hecks decide_ci_gate gate=#{name} --wait",
+          "        run: bundle exec exe/hecks regeneration_run.decide_ci_gate gate=#{name} --wait",
           "  # END GENERATED ci_gate #{name}"
         ].join("\n")
       end

data/lib/hecks/tools/deploy_recipe.rb

@@ -11,7 +11,7 @@ module Hecks
     # target and dispatches to the matching `Projector` export, writing the recipe (template,
     # scripts and Makefile) under `deploy/<stack>/` of the checkout.
     #
-    #   hecks deploy project <domain> [--tenant=<slug>] [--schema=<name>]
+    #   hecks deploy recipe.project <domain> [--tenant=<slug>] [--schema=<name>]
     #       [--out=<dir>] [--environment=<name>]
     #
     # `--environment` layers an overlay `.world` file over the base one; a missing overlay is an
@@ -96,7 +96,7 @@ module Hecks
 
         File.exist?(world_file) or
           abort "#{world_file} does not exist — a domain needs a .world file to declare " \
-                "deployed_to(\"AwsLambda\") or deployed_to(\"AwsFargate\")"
+                "deployed_to(\"AwsLambda\"), deployed_to(\"AwsFargate\") or deployed_to(\"AwsBox\")"
         world_file
       end
 
@@ -150,7 +150,7 @@ module Hecks
       # Loads the whole registry a domain boots with, not just its own `.bluebook`, because a
       # cross-domain invoke grant can live in any attached chapter. A domain with no bluebook of
       # its own (the QA ledger) gets its chapter from the hecksagon's `Chapters.load!`. `root:` is
-      # required or `uses_embryonaut_bluebook` refuses with "needs a registry with a root to
+      # required or `attaches ... from: :vendor` refuses with "needs a registry with a root to
       # vendor from".
       #
       # @param domain [String] the domain directory
@@ -176,15 +176,16 @@ module Hecks
       # @param deploy_settings [Hash] the world's `deployed_to` settings
       # @param world_file [String] the `.world` file, named in the refusal
       # @param domain [String] the domain directory, named in the refusal
-      # @return [Symbol] `:aws_lambda` or `:aws_fargate`
-      # @raise [SystemExit] with an example block when the world declares neither
+      # @return [Symbol] `:aws_lambda`, `:aws_fargate` or `:aws_box`
+      # @raise [SystemExit] with an example block when the world declares none of them
       def target_key(deploy_settings, world_file, domain)
         case deploy_settings[:adapter]
         when "AwsLambda" then :aws_lambda
         when "AwsFargate" then :aws_fargate
+        when "AwsBox" then :aws_box
         else
           abort <<~MSG
-            #{world_file} declares no deployed_to("AwsLambda") or deployed_to("AwsFargate") block. Add one, e.g.:
+            #{world_file} declares no deployed_to("AwsLambda"), deployed_to("AwsFargate") or deployed_to("AwsBox") block. Add one, e.g.:
 
                 deployed_to("AwsLambda") do
                   region "us-east-1"
@@ -201,6 +202,13 @@ module Hecks
                   port 8080
                 end
 
+            or:
+
+                deployed_to("AwsBox") do
+                  region "us-east-1"
+                  containers [{ name: "web", port: 8080 }]
+                end
+
             then re-run hecks deploy project #{domain}.
           MSG
         end

data/lib/hecks/tools/oidc_manifests.rb

@@ -9,7 +9,8 @@ module Hecks
     # `oidc.json` beside the domain.
     #
     # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
-    # sweep over the whole checkout carries on past either. `hecks deploy project_oidc` loads
+    # sweep over the whole checkout carries on past either. `hecks deploy
+    # oidc_manifest.project_oidc` loads
     # `bundler/setup` first, which pins the `json` gem: newer releases pretty-print an empty array
     # as `[\n\n]`, a diff spec/oidc_manifest_spec.rb would report as drift.
     module OidcManifests

data/lib/hecks/tools/sequence_script.rb

@@ -10,8 +10,8 @@ module Hecks
     #
     #   hecks generate_sequence <domain> [--seed N] [--steps N] [--adversarial fraction]
     #
-    # `--adversarial` mutates the sequence as `hecks quality_control ask run` does; 0 (off) by
-    # default.
+    # `--adversarial` mutates the sequence as `hecks quality_control query sweep.run` does; 0 (off)
+    # by default.
     module SequenceScript
       USAGE = "usage: hecks generate_sequence <domain> [--seed N] [--steps N] [--adversarial FRACTION]"
 

data/lib/hecks/tools/site_routes.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "fileutils"
+require "optparse"
+require_relative "../tools"
+require_relative "../projections/site/routes_ts"
+require_relative "../projections/site/site_cdn"
+require_relative "../projections/site/regions"
+
+module Hecks
+  module Tools
+    # Projects a project's route table into `routes.ts` (`Projections::Site::RoutesTs`) and, when
+    # it declares an edge, into the behaviours and listener rules of its template
+    # (`Projections::Site::SiteCdn`).
+    #
+    #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]
+    #
+    # `<project>` is the directory whose `bluebook/` holds the chapter that declares the rows and a
+    # hecksagon that attaches Site; it defaults to the checkout. `routes.ts` is written to
+    # `<project>/generated` unless `--out` names another directory. The template is rewritten in
+    # place between its `BEGIN`/`END GENERATED site_cdn` markers, or under `--out` a copy of it is
+    # written at the same relative path. With `--check` nothing is written: the tool answers 1 and
+    # names each file that differs from the table.
+    module SiteRoutes
+      # Where the files go, relative to the project, when `--out` names no directory.
+      DEFAULT_OUT = "generated"
+
+      USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]"
+
+      module_function
+
+      # Projects the route table, writes what differs and prints a line for each file written.
+      #
+      # @param argv [Array<String>] the project directory, then the flags
+      # @param root [String] the checkout, used as the project when `argv` names none
+      # @return [Integer] 0, or 1 when `--check` finds a file out of date
+      # @raise [SystemExit] with the reason on stderr when the project declares no route table or
+      #   the table is refused
+      def main(argv, root: Tools::ROOT)
+        argv = argv.dup
+        out = nil
+        check = false
+        OptionParser.new do |parser|
+          parser.on("--out=DIR") { |value| out = value }
+          parser.on("--check") { check = true }
+        end.parse!(argv)
+        project = argv.empty? ? root : File.expand_path(argv.shift)
+        abort USAGE unless argv.empty?
+
+        files = projection(project, out: out)
+        stale = files.reject { |path, text| File.file?(path) && File.read(path) == text }.keys
+        return report(stale, project, check) if check
+
+        stale.each do |path|
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, files.fetch(path))
+          puts "wrote #{display(path, project)}"
+        end
+        puts "project_site: #{files.size} #{files.size == 1 ? 'file' : 'files'}, current" if stale.empty?
+        0
+      end
+
+      # @param root [String] the project directory
+      # @param out [String, nil] the directory to write to; `generated/` of the project when nil
+      # @return [Hash{String => String}] each file's absolute path to the text it should hold
+      # @raise [SystemExit] when the project declares no route table or the table is refused
+      def projection(root, out: nil)
+        registry = registry_for(root)
+        chapter = Projections::Site::Table.chapter(registry)
+        table = Projections::Site::Table.read(chapter, registry: registry)
+        files = Projector.call(:site_routes_ts, bluebook: chapter, options: { table: table })
+        dir = out ? File.expand_path(out) : File.join(root, DEFAULT_OUT)
+        written = files.to_h { |name, text| [File.join(dir, name), text] }
+        written.merge(template_files(root, out, chapter, table, registry))
+      rescue Projections::Site::Table::Invalid => e
+        abort "project_site: #{e.message}"
+      end
+
+      # The template with the edge's regions rewritten, when the project declares an edge.
+      #
+      # @param root [String] the project directory
+      # @param out [String, nil] the directory to write to, or nil to rewrite the template in place
+      # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+      # @param table [Projections::Site::Table] the checked table
+      # @param registry [Hecks::Runtime::Registry] the registry the project booted into
+      # @return [Hash{String => String}] the template's path to its text; empty with no edge
+      # @raise [SystemExit] when the template is missing or lacks a region
+      def template_files(root, out, chapter, table, registry)
+        edge = Projections::Site::Edge.read(chapter, table: table, vocabulary: Projections::Site::Table.vocabulary(registry))
+        return {} unless edge
+
+        regions = Projector.call(:site_cdn, bluebook: chapter, options: { table: table, edge: edge })
+        relative = edge.setting.template
+        source = File.join(root, relative)
+        abort "project_site: the template #{relative} does not exist in #{root}" unless File.file?(source)
+
+        text = regions.reduce(File.read(source)) do |current, (name, block)|
+          unless Projections::Site::Regions.region?(current, name)
+            abort "project_site: #{relative} has no BEGIN/END GENERATED site_cdn #{name} region"
+          end
+
+          Projections::Site::Regions.replace(current, name, block)
+        end
+        { (out ? File.join(File.expand_path(out), relative) : source) => text }
+      end
+
+      # Loads the project's chapters the way a deploy does: the bluebooks, then the hecksagons that
+      # attach the chapters they need.
+      #
+      # @param root [String] the project directory
+      # @return [Hecks::Runtime::Registry] the registry
+      # @raise [SystemExit] when the project has no `bluebook/` directory
+      def registry_for(root)
+        dir = File.join(root, "bluebook")
+        unless Dir.exist?(dir)
+          abort "project_site: #{dir} does not exist; a project declares its route table in a bluebook/ directory"
+        end
+
+        registry = Hecks::Runtime::Registry.new(root: root)
+        lib_hecks = File.expand_path("..", __dir__)
+        Hecks.with_registry(registry) do
+          %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
+             adapters/driven/prism.adapter].each { |file| Kernel.load(File.join(lib_hecks, file)) }
+          Dir.glob(File.join(dir, "*.bluebook")).each { |file| Kernel.load(file) }
+          Dir.glob(File.join(dir, "*.hecksagon")).each { |file| Kernel.load(file) }
+        end
+        registry
+      end
+
+      # @param stale [Array<String>] absolute paths whose text differs from the table
+      # @param project [String] the project directory
+      # @param check [Boolean] whether this is a `--check` run
+      # @return [Integer] 0 when current, else 1 with the stale files on stderr
+      def report(stale, project, _check)
+        if stale.empty?
+          puts "project_site: every file current"
+          return 0
+        end
+
+        warn "project_site: out of date: #{stale.map { |path| display(path, project) }.join(', ')} " \
+             "(run hecks site site_projection.project_site)"
+        1
+      end
+
+      # @param path [String] an absolute path
+      # @param project [String] the project directory
+      # @return [String] the path relative to the project when it lies beneath it
+      def display(path, project) = path.delete_prefix("#{project}/")
+    end
+  end
+end

data/lib/hecks/tools/tenant_provisioning.rb

@@ -16,7 +16,7 @@ module Hecks
     # merge) the base `persisted_by` settings, so `--database` is required. A policy's refusal is
     # swallowed by `PolicyInterpreter#deliver`, so success is confirmed by query.
     #
-    #   hecks deploy provision <domain-directory> <slug> --domain=name --realm=name \
+    #   hecks deploy tenant.provision <domain-directory> <slug> --domain=name --realm=name \
     #     --schema=name --database=name [--adapter=PostgresEra]
     module TenantProvisioning
       USAGE = "usage: hecks deploy provision <domain-directory> <slug> --domain=NAME --realm=NAME " \

data/lib/hecks/tools.rb

@@ -24,6 +24,7 @@ module Hecks
       "project_ci_gates"               => ["tools/ci_gates", "CiGates"],
       "decide_ci_gate"                 => ["tools/ci_gate_decision", "CiGateDecision"],
       "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
+      "project_site"                   => ["tools/site_routes", "SiteRoutes"],
       "lint_deploy_recipes"            => ["tools/deploy_recipe_lint", "DeployRecipeLint"],
       "project_oidc"                   => ["tools/oidc_manifests", "OidcManifests"],
       "project_tenant"                 => ["tools/tenant_provisioning", "TenantProvisioning"],

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.0.4".freeze
+  VERSION = "3.1.0".freeze
 end

data/rust/build/src/cargo_sync.rs

@@ -50,7 +50,7 @@ fn write_root_mod(out_root: &Path, all_dirs: &[String], domains: &[String], targ
     out.push_str("// chapter (governance/identity — no merged.rs of its own, so absent\n");
     out.push_str("// from `domains`) stays unconditional: it has no single feature of its\n");
     out.push_str("// own to gate behind, and is compiled in by whichever domain(s) attach\n");
-    out.push_str("// it via `uses_framework`.\n");
+    out.push_str("// it via `attaches`.\n");
     for name in all_dirs {
         if domains.iter().any(|d| d == name) {
             out.push_str(&format!("#[cfg(feature = {name:?})]\n"));

data/rust/build/src/pipeline.rs

@@ -66,10 +66,10 @@ pub fn run(root: &Path, domain: &str, opts: &Options) -> Result<(), String> {
         }
     }
 
-    let (uses_framework_names, uses_embryonaut_bluebook_names) = match &hecksagon_path {
+    let (gem_chapter_names, vendored_package_names) = match &hecksagon_path {
         Some(p) => (
-            resolve::resolve_uses_framework(&parser_bin, &target_chapter_name, p)?,
-            resolve::resolve_uses_embryonaut_bluebook(&parser_bin, &target_chapter_name, p)?,
+            resolve::resolve_gem_chapters(&parser_bin, &target_chapter_name, p)?,
+            resolve::resolve_vendored_packages(&parser_bin, &target_chapter_name, p)?,
         ),
         None => (Vec::new(), Vec::new()),
     };
@@ -85,45 +85,52 @@ pub fn run(root: &Path, domain: &str, opts: &Options) -> Result<(), String> {
     lineage_pass::run(&mut target_ir, hecksagon_path.as_deref(), world_path.as_deref(), root)?;
     let target_ir_text = crate::json::write(&target_ir);
 
-    // Every other chapter's `uses_framework` names, resolved through the
+    // Every other chapter the gem supplies by `attaches "Name"`, resolved through the
     // same directory listing (`resolve::framework_members`) the Ruby
-    // pipeline itself calls.
+    // pipeline itself calls. A gem chapter that is not a framework member (the language,
+    // Tenancy, Deploy) is loaded by the Ruby runtime alone, so it is checked and skipped.
     let framework_members = resolve::framework_members(root)?;
+    let other_gem_chapters = resolve::other_gem_chapter_names(root)?;
     let mut chapters: Vec<Chapter> = Vec::new();
-    for fw_name in &uses_framework_names {
+    for fw_name in &gem_chapter_names {
+        if other_gem_chapters.contains(fw_name) && !framework_members.iter().any(|(name, _)| name == fw_name) {
+            continue;
+        }
         let fw_path = framework_members
             .iter()
             .find(|(name, _)| name == fw_name)
             .map(|(_, path)| path.clone())
             .ok_or_else(|| {
-                let known: Vec<&str> = framework_members.iter().map(|(n, _)| n.as_str()).collect();
-                format!("hecks-build: uses_framework {fw_name:?} names no known framework member — known: {}", known.join(", "))
+                let mut known: Vec<&str> = framework_members.iter().map(|(n, _)| n.as_str()).collect();
+                known.extend(other_gem_chapters.iter().map(String::as_str));
+                known.sort();
+                format!("hecks-build: attaches {fw_name:?} names no chapter the gem carries — known: {}", known.join(", "))
             })?;
         let fw_chapter_name = resolve::header_chapter_name(&fw_path)?;
         if &fw_chapter_name != fw_name {
             return Err(format!(
-                "hecks-build: {} declares chapter {fw_chapter_name:?}, but uses_framework named {fw_name:?}",
+                "hecks-build: {} declares chapter {fw_chapter_name:?}, but attaches named {fw_name:?}",
                 fw_path.display()
             ));
         }
         let fw_ir_text = parse_chapter_with_optionals(&parser_bin, &fw_chapter_name, std::slice::from_ref(&fw_path))?;
         chapters.push(Chapter {
             mod_name: fw_name.to_lowercase(),
-            source_label: format!("{domain} (uses_framework {fw_name:?})"),
+            source_label: format!("{domain} (attaches {fw_name:?})"),
             ir_text: fw_ir_text,
         });
     }
 
-    // Every vendored package's `uses_embryonaut_bluebook` names, resolved the
+    // Every vendored package's `attaches ... from: :vendor` names, resolved the
     // same way `EmbryonautBluebook.load!` (Ruby) resolves them — without this,
     // a vendored chapter would silently drop from the output.
-    for pkg_name in &uses_embryonaut_bluebook_names {
+    for pkg_name in &vendored_package_names {
         let pkg_files = resolve::vendored_bluebook_files(&domain_path, pkg_name)?;
         let pkg_chapter_name = resolve::header_chapter_name(&pkg_files[0])?;
         let expected_chapter_name = resolve::pascal(pkg_name);
         if pkg_chapter_name != expected_chapter_name {
             return Err(format!(
-                "hecks-build: {} declares chapter {pkg_chapter_name:?}, but uses_embryonaut_bluebook {pkg_name:?} \
+                "hecks-build: {} declares chapter {pkg_chapter_name:?}, but attaches {pkg_name:?}, from: :vendor \
                  expects {expected_chapter_name:?}",
                 pkg_files[0].display()
             ));
@@ -140,13 +147,13 @@ pub fn run(root: &Path, domain: &str, opts: &Options) -> Result<(), String> {
             // `expected_chapter_name` above), not the raw `pkg_name` — that
             // would diverge the moment a package name has an underscore.
             mod_name: expected_chapter_name.to_lowercase(),
-            source_label: format!("{domain} (uses_embryonaut_bluebook {pkg_name:?})"),
+            source_label: format!("{domain} (attaches {pkg_name:?}, from: :vendor)"),
             ir_text: pkg_ir_text,
         });
     }
 
-    // Guards against a `uses_framework`- and a `uses_embryonaut_bluebook`-
-    // derived entry sharing a `mod_name`, which would silently overwrite one
+    // Guards against a gem-chapter and a vendored-package
+    // entry sharing a `mod_name`, which would silently overwrite one
     // chapter's sidecars with another's.
     {
         let mut seen: Vec<&str> = Vec::new();