hecks 4.0.0 → 6.0.0

data/lib/hecks/tools/translation_audit/domain_loading.rb

@@ -13,8 +13,8 @@ module Hecks
           loading = Hecks::Ports::Loading.bootstrap
           directory = loading.bluebook_directory(domain_path)
           registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-          load_chapters(registry, loading, directory)
-          bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+          load_declarations(registry, loading, directory)
+          bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
           [registry, bluebook, directory]
         end
 
@@ -35,7 +35,7 @@ module Hecks
 
         private
 
-        def load_chapters(registry, loading, directory)
+        def load_declarations(registry, loading, directory)
           Hecks.with_registry(registry) do
             loading.load_library
             loading.load_project(loading.shared_root(nil, directory))

data/lib/hecks/tools/translation_audit.rb

@@ -17,7 +17,18 @@ module Hecks
     #   hecks audit_translation <domain>
     module TranslationAudit
       # What one audit run works on: the loaded domain and its open journal.
-      Session = Struct.new(:registry, :bluebook, :directory, :db, :lineage)
+      Session = Struct.new(:registry, :bluebook, :directory, :db, :lineage) do
+        # @return [Boolean] whether the journal holds no era yet
+        def no_era? = lineage.eras.empty?
+
+        # @return [String] the name of the bluebook being audited
+        def bluebook_name = bluebook.name
+
+        # Closes the journal's database.
+        #
+        # @return [void]
+        def close = db.close
+      end
 
       extend DomainLoading
       extend Edges
@@ -43,7 +54,7 @@ module Hecks
       # @param session [Session] the loaded domain and its open journal
       # @return [Integer] the exit status
       def audit(session)
-        return hold_first_era(session) if session.lineage.eras.empty?
+        return hold_first_era(session) if session.no_era?
 
         audit_edge(session, edge_chain(session.registry, session.bluebook, session.lineage))
       end
@@ -66,8 +77,8 @@ module Hecks
       def hold_first_era(session)
         session.lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(session.bluebook, session.directory),
                                     projection: Hecks::Runtime::StorageShape.project(session.bluebook))
-        puts "#{session.bluebook.name} held era 1 just now — no edge to audit."
-        session.db.close
+        puts "#{session.bluebook_name} held era 1 just now — no edge to audit."
+        session.close
         0
       end
     end

data/lib/hecks/tools/translation_scaffold/reporting.rb

@@ -7,10 +7,13 @@ module Hecks
     module TranslationScaffold
       # Says what the written edge file leaves to decide.
       module Reporting
+        # An `unresolved` line the scaffold leaves for a person to decide.
+        UNRESOLVED_LINE = /^\s*unresolved /
+
         # @return [void]
         def report(path, diffed)
           text = File.read(path)
-          unresolved = text.scan(/^\s*unresolved /).size
+          unresolved = text.scan(UNRESOLVED_LINE).size
           unclaimed = diffed ? diffed[:unclaimed] : []
           puts "wrote #{path}"
           unclaimed.each { |name| puts unclaimed_message(name) }

data/lib/hecks/tools/translation_scaffold.rb

@@ -59,13 +59,13 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) { load_chapters(loading, directory) }
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        Hecks.with_registry(registry) { load_declarations(loading, directory) }
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook, directory]
       end
 
       # Loads the library, the project and the domain's files into the registry in scope.
-      def load_chapters(loading, directory)
+      def load_declarations(loading, directory)
         loading.load_library
         loading.load_project(loading.shared_root(nil, directory))
         # deliberately not translations/*.bluebook: an unresolved edge file refuses to load, and
@@ -73,17 +73,7 @@ module Hecks
         loading.load_each(directory, %w[*.port *.adapter])
         loading.load_bluebooks(directory)
         loading.load_each(directory, %w[*.hecksagon *.world])
-        load_environment_overlay(loading, directory)
-      end
-
-      # A domain that splits `persisted_by` per environment declares none in its base
-      # `.hecksagon`, so resolution fails without this overlay — opt-in via
-      # HECKS_PROJECT_ENVIRONMENT, a no-op otherwise.
-      def load_environment_overlay(loading, directory)
-        target_environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil) or return
-
-        loading.load_each(directory, [File.join("environments", "#{target_environment}.hecksagon")])
-        loading.load_each(directory, [File.join("environments", "#{target_environment}.world")])
+        loading.load_overlay(directory, ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
       end
 
       # @return [Integer] 0

data/lib/hecks/vendoring/git_source.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "tmpdir"
+require_relative "../text"
 require_relative "git_environment"
 
 module Hecks
@@ -56,14 +57,16 @@ module Hecks
       #
       # @param ref [String] the commit-ish to read from
       # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`
-      # @param glob [String] a `File.fnmatch` pattern the file's own name must match
+      # @param glob [String] a `File.fnmatch` pattern the file's own name must match; braces
+      #   (`"*.{bluebook,adapter}"`) name alternatives
       # @return [Array<String>] repository-relative paths, sorted
       def files(ref, subtree, glob = "*")
         out, _err, status = git("ls-tree", "-r", "--name-only", ref, "--", subtree)
         return [] unless status.success?
 
-        out.lines.map(&:chomp).select do |file|
-          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file))
+        listed = out.lines.map(&:chomp)
+        listed.select do |file|
+          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file), File::FNM_EXTGLOB)
         end.sort
       end
 
@@ -89,7 +92,7 @@ module Hecks
 
       def run!(label, *command)
         _out, err, status = Open3.capture3(GitEnvironment.clean, *command)
-        raise Error, "#{label} failed: #{err.lines.first.to_s.strip}" unless status.success?
+        raise Error, "#{label} failed: #{Text.first_line(err)}" unless status.success?
       end
     end
   end

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 = "4.0.0".freeze # rust/host/HECKS_RELEASE names the same release
+  VERSION = "6.0.0".freeze # rust/host/HECKS_RELEASE names the same release
 end

data/lib/hecks/vocabulary.rb

@@ -62,6 +62,17 @@ module Hecks
         {"symbol"=>"==", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"false"}.freeze,
         {"symbol"=>"!=", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"true"}.freeze
       ].freeze,
+      "DispatchStage" => [
+        {"name"=>"request"}.freeze,
+        {"name"=>"arguments"}.freeze,
+        {"name"=>"role"}.freeze,
+        {"name"=>"references"}.freeze,
+        {"name"=>"state"}.freeze,
+        {"name"=>"givens"}.freeze,
+        {"name"=>"ensures"}.freeze,
+        {"name"=>"invariants"}.freeze,
+        {"name"=>"remote"}.freeze
+      ].freeze,
       "DomainRefusal" => [
         {"name"=>"AbsentArgument"}.freeze,
         {"name"=>"AlreadyExists"}.freeze,
@@ -103,6 +114,41 @@ module Hecks
         {"name"=>"tel", "pattern"=>"phone|\\btel(ephone)?\\b", "resolves_to"=>"html_type"}.freeze,
         {"name"=>"textarea", "pattern"=>"\\b(text|body|note|notes|description|message|comment)\\b", "resolves_to"=>"kind"}.freeze
       ].freeze,
+      "GateCheck" => [
+        {"name"=>"rspec", "id"=>"rspec", "title"=>"rspec (parallel)", "argv"=>"", "script"=>"# Workers are grouped by this machine's own last timings, kept under the git directory\n# (shared by every worktree, never committed). CI's committed baseline leaves out the io\n# specs this run includes, so it only seeds the first run; each run then rewrites the log.\nlog=\"$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log\"\n[ -f \"$log\" ] || cp .github/rspec_runtime_baseline.log \"$log\"\nbundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log \"$log\" --allowed-missing 100 \\\n  -o \"--format progress --format ParallelTests::RSpec::RuntimeLogger --out $log\"\n", "blocked"=>"the suite is red."}.freeze,
+        {"name"=>"fuzzing", "id"=>"fuzzing", "title"=>"spec/fuzzing, which the parallel run above excludes", "argv"=>"bundle exec rspec spec/fuzzing --tag fuzzing", "script"=>"", "blocked"=>"spec/fuzzing is red."}.freeze,
+        {"name"=>"query_agreement", "id"=>"query_agreement", "title"=>"adapter agreement, one declared query and every engine giving the same answer", "argv"=>"bundle exec rspec spec/adapters/query_agreement_spec.rb --tag io", "script"=>"", "blocked"=>"the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which."}.freeze,
+        {"name"=>"engine_agreement", "id"=>"engine_agreement", "title"=>"engine agreement, every declared comparator on both engines", "argv"=>"bundle exec exe/hecks conformance_run.check_engine_agreement --wait", "script"=>"", "blocked"=>"a comparator is missing a shared case or a cross-engine spec."}.freeze,
+        {"name"=>"shape_ledger", "id"=>"shape_ledger", "title"=>"shape ledger, every bluebook's storage shape held by the ledger or reached by a translation edge", "argv"=>"bundle exec exe/hecks conformance_run.check_shape_ledger --wait", "script"=>"", "blocked"=>"a bluebook's storage shape moved with no translation edge from the shape the ledger holds; the failure prints the edge to commit. A change that only adds is settled in one step with `hecks conformance_run.check_shape_ledger --confirm --additive --wait`, which writes the empty edge and moves the ledger; a change that renames or reshapes data needs rules first."}.freeze,
+        {"name"=>"model_check", "id"=>"model_check", "title"=>"model check, unreachable states, dead transitions and orphaned handlers", "argv"=>"bundle exec exe/hecks model_check --wait", "script"=>"", "blocked"=>"the model checker found something."}.freeze,
+        {"name"=>"doc_coverage", "id"=>"doc_coverage", "title"=>"docs coverage, words with no running example", "argv"=>"bundle exec exe/hecks conformance_run.measure_doc_coverage --wait", "script"=>"", "blocked"=>"the language ships something undocumented; write the missing sections and examples."}.freeze,
+        {"name"=>"rubocop", "id"=>"rubocop", "title"=>"rubocop, the static style and correctness gate", "argv"=>"bundle exec rubocop -c .rubocop.yml", "script"=>"", "blocked"=>"rubocop found an offense."}.freeze,
+        {"name"=>"codegen_drift", "id"=>"codegen_drift", "title"=>"codegen drift, rust/src/generated/ must match a fresh regeneration", "argv"=>"bundle exec exe/hecks regeneration_run.regenerate_corpus --check --wait", "script"=>"", "blocked"=>"regenerating hits a diff. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed."}.freeze,
+        {"name"=>"comment_style", "id"=>"comment_style", "title"=>"comment style, every comment under lib/hecks and spec against docs/COMMENT_STYLE_GUIDE.md", "argv"=>"bundle exec exe/hecks style_run.check_comments paths=lib/hecks spec --wait", "script"=>"", "blocked"=>"a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check."}.freeze,
+        {"name"=>"comment_blocks", "id"=>"comment_blocks", "title"=>"comment blocks, no run of comment lines past ADR 0075's cap", "argv"=>"bundle exec exe/hecks style_run.check_comments paths=lib,spec,examples only=long_block --wait", "script"=>"", "blocked"=>"a comment block ran past the cap; shorten it."}.freeze,
+        {"name"=>"rust_fmt", "id"=>"rust_fmt", "title"=>"rustfmt, every Rust crate laid out as `cargo fmt` would", "argv"=>"", "script"=>"# The main crate's generated modules are not committed, so cargo fmt would stop at a\n# missing file on a fresh checkout; its hand-written entry points are named instead.\nrustfmt --check --edition 2021 rust/src/main.rs rust/src/kernel/mod.rs rust/tests/*.rs\nfor crate in parser codegen lsp host web build; do\n  cargo fmt --check --manifest-path \"rust/$crate/Cargo.toml\"\ndone\n", "blocked"=>"a Rust file is not laid out as rustfmt has it; run `cargo fmt` in its crate (rust/src/exemplar is exempt, it is text templates). Generated Rust is laid out by its generators, so fix the generator, not the output."}.freeze,
+        {"name"=>"rust_io", "id"=>"rust_io", "title"=>"rust io specs, conformance, coercion, has_many, semantics corpus and feature exclusivity", "argv"=>"", "script"=>"# Building the banking crate makes banking the default feature and rewrites the module\n# list, both tracked. They are put back on the way out, and the check will not start over\n# a person's uncommitted edits to them.\nrewritten=\"rust/Cargo.toml rust/src/generated/mod.rs\"\nif [ -n \"$(git status --porcelain -- $rewritten)\" ]; then\n  echo \"uncommitted changes in $rewritten; commit or discard them first\" >&2\n  exit 1\nfi\ntrap 'git checkout -q -- $rewritten' EXIT\nenv -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus --confirm --wait\nbundle exec exe/hecks build.project_rust domain=examples/banking --wait\nbundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb\nbundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb\n", "blocked"=>"a Rust io spec failed, or skipped; the crate it built is under rust/target."}.freeze,
+        {"name"=>"ci_codegen_drift", "id"=>"codegen_drift", "title"=>"codegen drift, the committed generated Rust must match the regeneration this job holds", "argv"=>"git diff --exit-code --stat -- rust/src/generated rust/Cargo.toml", "script"=>"", "blocked"=>"regenerating hits a diff. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed."}.freeze,
+        {"name"=>"rust_clippy", "id"=>"rust_clippy", "title"=>"clippy, every Rust crate with its warnings as errors", "argv"=>"", "script"=>"for crate in . parser codegen lsp host web build; do\n  cargo clippy --all-targets --manifest-path \"rust/$crate/Cargo.toml\" -- -D warnings\ndone\n", "blocked"=>"clippy found a warning in a Rust crate, under the strict `[lints.clippy]` table of its Cargo.toml. The main crate needs rust/src/generated, so run `hecks regenerate_corpus --confirm` first on a fresh checkout. Fix the code, or allow a lint at the one site with a line saying why; a warning in generated Rust is fixed in its generator."}.freeze,
+        {"name"=>"lint_deploy_recipes", "id"=>"lint_deploy_recipes", "title"=>"generated deploy recipes, a command with no checked exit status or no echo", "argv"=>"bundle exec exe/hecks deploy makefile_check.lint --wait", "script"=>"", "blocked"=>"a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen."}.freeze,
+        {"name"=>"fuzz", "id"=>"fuzz", "title"=>"fuzz, every example domain on the Memory adapter", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz --wait", "script"=>"", "blocked"=>"a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output."}.freeze,
+        {"name"=>"fuzz_sqlite", "id"=>"fuzz_sqlite", "title"=>"fuzz on a real on-disk SQLite database", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz adapter=sqlite seeds=6 --wait", "script"=>"", "blocked"=>"the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats."}.freeze,
+        {"name"=>"fuzz_postgres", "id"=>"fuzz_postgres", "title"=>"fuzz on real Postgres, up to four workers (each in its own scratch schema)", "argv"=>"bundle exec exe/hecks fuzz_run.fuzz adapter=postgres seeds=3 steps=20 --wait", "script"=>"", "blocked"=>"the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD."}.freeze,
+        {"name"=>"vocabulary_drift", "id"=>"vocabulary_drift", "title"=>"vocabulary, the reserved-name tables regenerated must match the committed ones", "argv"=>"", "script"=>"bundle exec exe/hecks language_run.project_vocabulary --confirm --wait\nbundle exec exe/hecks language_run.project_reserved_names --confirm --wait\ngit diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs\n", "blocked"=>"a generated vocabulary file is stale; the check rewrote it, so commit the result."}.freeze,
+        {"name"=>"ci_gates", "id"=>"ci_gates", "title"=>"ci gates, the CiGate rows must match the marked regions of the workflows", "argv"=>"bundle exec exe/hecks regeneration_run.project_ci_gates --wait", "script"=>"", "blocked"=>"a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates --confirm`."}.freeze,
+        {"name"=>"tools_doc", "id"=>"tools_doc", "title"=>"tools doc, docs/tools.md must match the RetiredScript rows", "argv"=>"bundle exec exe/hecks regeneration_run.project_tools_doc --wait", "script"=>"", "blocked"=>"a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc --confirm`."}.freeze,
+        {"name"=>"rust_coverage", "id"=>"rust_coverage", "title"=>"rust coverage, every generated module", "argv"=>"bundle exec exe/hecks query corpus_run.corpus_rust_coverage --wait", "script"=>"", "blocked"=>"a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted."}.freeze,
+        {"name"=>"rust_coverage_codegen", "id"=>"rust_coverage_codegen", "title"=>"rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta", "argv"=>"", "script"=>"for module in pizzas governance identity banking meta; do\n  bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait\ndone\n", "blocked"=>"hecks-codegen generated nothing for a construct a domain declares."}.freeze,
+        {"name"=>"kernel_coverage", "id"=>"kernel_coverage", "title"=>"rust kernel coverage, every capability variant has a kernel file", "argv"=>"bundle exec exe/hecks kernel_run.measure_kernel_coverage --wait", "script"=>"", "blocked"=>"a capability's enum variant has no rust/src/kernel file behind it."}.freeze,
+        {"name"=>"rust_vocabulary_drift", "id"=>"rust_vocabulary_drift", "title"=>"rust vocabulary, the kernel vocab tables regenerated must match the committed ones", "argv"=>"", "script"=>"bundle exec exe/hecks language_run.project_rust_vocabulary --confirm --wait\ngit diff --exit-code -- rust/src/kernel/vocab/\nuntracked=\"$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)\"\nif [ -n \"$untracked\" ]; then\n  echo \"rust/src/kernel/vocab has uncommitted generated files:\" >&2\n  echo \"$untracked\" >&2\n  exit 1\nfi\n", "blocked"=>"the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result."}.freeze
+      ].freeze,
+      "GateStage" => [
+        {"name"=>"pre_push", "env"=>"HECKS_ENVIRONMENT=memory HECKS_PROCESS_SPECS=1", "checks"=>"rspec,fuzzing,query_agreement,engine_agreement,shape_ledger,model_check,doc_coverage,rubocop,codegen_drift,comment_style,comment_blocks,rust_fmt"}.freeze,
+        {"name"=>"quick", "env"=>"HECKS_ENVIRONMENT=memory", "checks"=>"shape_ledger,rubocop,comment_style,comment_blocks"}.freeze,
+        {"name"=>"unguarded_push", "env"=>"HECKS_ENVIRONMENT=memory", "checks"=>"shape_ledger,rubocop,comment_style,comment_blocks,fuzzing"}.freeze,
+        {"name"=>"rust_io", "env"=>"CI=true HECKS_ENVIRONMENT=memory", "checks"=>"rust_io"}.freeze,
+        {"name"=>"ci", "env"=>"", "checks"=>"model_check,shape_ledger,engine_agreement,doc_coverage,rubocop,comment_style,comment_blocks,ci_codegen_drift,rust_fmt,rust_clippy,lint_deploy_recipes,fuzz,fuzz_sqlite,fuzz_postgres,vocabulary_drift,ci_gates,tools_doc,rust_coverage,rust_coverage_codegen,kernel_coverage,rust_vocabulary_drift"}.freeze
+      ].freeze,
       "IncludeHaystack" => [
         {"type"=>"Array", "strategy"=>"membership"}.freeze,
         {"type"=>"String", "strategy"=>"substring"}.freeze
@@ -117,7 +163,8 @@ module Hecks
         {"glob"=>"*.bluebook"}.freeze,
         {"glob"=>"translations/*.bluebook"}.freeze,
         {"glob"=>"*.hecksagon"}.freeze,
-        {"glob"=>"*.world"}.freeze
+        {"glob"=>"*.world"}.freeze,
+        {"glob"=>"*.contextmap"}.freeze
       ].freeze,
       "MutationOp" => [
         {"name"=>"set", "sign"=>""}.freeze,
@@ -136,7 +183,8 @@ module Hecks
         {"name"=>"scale_call"}.freeze
       ].freeze,
       "PrebuiltBinary" => [
-        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze,
+        {"name"=>"host-arm64", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"aarch64-unknown-linux-gnu", "runner"=>"ubuntu-22.04-arm"}.freeze
       ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
@@ -172,6 +220,8 @@ module Hecks
         {"name"=>"generated_domains_per_tick", "type"=>"Integer", "meaning"=>"How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the step."}.freeze,
         {"name"=>"generated_domains_rust", "type"=>"Boolean", "meaning"=>"Whether generated domains are also compared against a compiled Rust binary built in a scratch copy."}.freeze,
         {"name"=>"generated_domain_seeds", "type"=>"Integer", "meaning"=>"Generated sequences run per generated domain."}.freeze,
+        {"name"=>"mutation_files", "type"=>"Array", "meaning"=>"Rust files `hecks quality_control target.mutate --from-dials` mutates, and so the files one `hecks quality_control sweep.tick` mutation-tests after the generated domains; empty skips the step."}.freeze,
+        {"name"=>"mutation_equivalent", "type"=>"Array", "meaning"=>"Mutants that behave the same as the original code, by the name `cargo mutants --list` gives them without the file and line; never run, so they cannot be reported as survivors."}.freeze,
         {"name"=>"structural_refusal_boundary", "type"=>"Array", "meaning"=>"Construct families a skipped query verb may belong to. A skip inside the list is logged Held, one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a family here is declared by no committed manifest."}.freeze
       ].freeze,
       "QueryComparator" => [
@@ -185,6 +235,40 @@ module Hecks
         {"name"=>"contains"}.freeze,
         {"name"=>"none_in_state"}.freeze
       ].freeze,
+      "Reducer" => [
+        {"name"=>"count", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"sum", "identity"=>"0", "combine"=>"add", "inverse"=>"subtract"}.freeze,
+        {"name"=>"avg", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"min", "identity"=>"null", "combine"=>"min", "inverse"=>""}.freeze,
+        {"name"=>"max", "identity"=>"null", "combine"=>"max", "inverse"=>""}.freeze,
+        {"name"=>"median", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"percentile", "identity"=>"null", "combine"=>"collect", "inverse"=>""}.freeze,
+        {"name"=>"any", "identity"=>"false", "combine"=>"or", "inverse"=>""}.freeze,
+        {"name"=>"all", "identity"=>"true", "combine"=>"and", "inverse"=>""}.freeze
+      ].freeze,
+      "RefusalClass" => [
+        {"name"=>"AbsentArgument", "kind"=>"absent_argument", "stage"=>"arguments"}.freeze,
+        {"name"=>"AlreadyExists", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"AttributeAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"EnsuresNotMet", "kind"=>"refused", "stage"=>"ensures"}.freeze,
+        {"name"=>"GivenNotMet", "kind"=>"refused", "stage"=>"givens"}.freeze,
+        {"name"=>"InvariantViolation", "kind"=>"refused", "stage"=>"invariants"}.freeze,
+        {"name"=>"LifecycleRefused", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NothingToCorrect", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"NotFound", "kind"=>"not_found", "stage"=>"state"}.freeze,
+        {"name"=>"ProjectionAbsent", "kind"=>"refused", "stage"=>"state"}.freeze,
+        {"name"=>"RemoteRefusal", "kind"=>"refused", "stage"=>"remote"}.freeze,
+        {"name"=>"TypeMismatch", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"Unauthorized", "kind"=>"unauthorized", "stage"=>"role"}.freeze,
+        {"name"=>"UnknownArgument", "kind"=>"refused", "stage"=>"arguments"}.freeze,
+        {"name"=>"UnknownVerb", "kind"=>"refused", "stage"=>"request"}.freeze
+      ].freeze,
+      "RefusalKind" => [
+        {"name"=>"refused"}.freeze,
+        {"name"=>"not_found"}.freeze,
+        {"name"=>"unauthorized"}.freeze,
+        {"name"=>"absent_argument"}.freeze
+      ].freeze,
       "RefusalSiteArgument" => [
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"command", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
         {"refusal"=>"NotFound", "site"=>"creating_no_identity", "argument"=>"aggregate", "shape"=>"scalar", "quoting"=>"none", "separator"=>"", "sorted"=>"false", "when_empty"=>""}.freeze,
@@ -359,7 +443,7 @@ module Hecks
         {"refusal"=>"InvariantViolation", "site"=>"closed_set_member", "template"=>"{type} admits {admitted} — got {offered}"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"value_object_invariant", "template"=>"{name} invariant violated — {description} (given {offered})"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"admits_declared_set", "template"=>"{name} admits {admits} — {admitted} — got {offered}"}.freeze,
-        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this bluebook does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
         {"refusal"=>"InvariantViolation", "site"=>"group_by_collision", "template"=>"{read_model} groups by {fields}, but rows {ids} share {key} — a group_by leaf holds one row; add a field that tells them apart"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"tenant_required", "template"=>"{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to"}.freeze,
         {"refusal"=>"Unauthorized", "site"=>"role_mismatch", "template"=>"{command} refused — role: {role}, and the caller stated {caller_role}"}.freeze,
@@ -443,6 +527,7 @@ module Hecks
         {"script"=>"project_refusal_wording", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_refusal_wording"}.freeze,
         {"script"=>"project_reserved_names", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_reserved_names"}.freeze,
         {"script"=>"project_parser_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_parser_table"}.freeze,
+        {"script"=>"project_phrase_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_phrase_table"}.freeze,
         {"script"=>"project_bootstrap_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_bootstrap_table"}.freeze,
         {"script"=>"project_field_hints", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_field_hints"}.freeze,
         {"script"=>"expression_projection", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_expression_tables"}.freeze,
@@ -505,6 +590,7 @@ module Hecks
         {"script"=>"qa_seed_targets", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"seed"}.freeze,
         {"script"=>"qa_generated_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"check_generated_domains", "passes"=>"--domains 3 --start N --forms a,b --seeds 5 --steps 25 --adversarial 0.3 --rust --shrink-budget 200 --domain-shrink-budget 40 --promote dir --name N --from-dials --blueprint F --source F"}.freeze,
         {"script"=>"qa_mine_combinations", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mine_combinations", "passes"=>"--candidates 3 --rust --seeds 5 --steps 25 --adversarial 0.3 --repair-rounds 1 --agent CMD --from DIR --against PATH --brief"}.freeze,
+        {"script"=>"(new)", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mutate", "passes"=>"--file rust/src/… --from-dials"}.freeze,
         {"script"=>"qa_domain_novelty", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"judge_novelty", "passes"=>"--against PATH …"}.freeze,
         {"script"=>"qa_discover_external_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"discover_external_domains", "passes"=>"--projects-dir ~/Projects --max-depth 3 --known-path PATH …"}.freeze,
         {"script"=>"qa_postgres_migrate", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"migrate_ledger_from_heki", "passes"=>"[aggregate …] --force", "note"=>"a dry run without --force"}.freeze,
@@ -574,6 +660,27 @@ module Hecks
         {"type"=>"String"}.freeze,
         {"type"=>"Hash"}.freeze
       ].freeze,
+      "StepStage" => [
+        {"step"=>"decode_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_unknown_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments", "stage"=>"arguments"}.freeze,
+        {"step"=>"normalize_args", "stage"=>"arguments"}.freeze,
+        {"step"=>"refuse_role_mismatch", "stage"=>"role"}.freeze,
+        {"step"=>"resolve_references", "stage"=>"references"}.freeze,
+        {"step"=>"hydrate", "stage"=>"state"}.freeze,
+        {"step"=>"hydrate_parent", "stage"=>"state"}.freeze,
+        {"step"=>"locate_element", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_givens", "stage"=>"givens"}.freeze,
+        {"step"=>"admissible_transition", "stage"=>"state"}.freeze,
+        {"step"=>"assign_creation_attributes", "stage"=>"state"}.freeze,
+        {"step"=>"apply_mutations", "stage"=>"state"}.freeze,
+        {"step"=>"advance_lifecycle", "stage"=>"state"}.freeze,
+        {"step"=>"delegate_to_entity", "stage"=>"state"}.freeze,
+        {"step"=>"enforce_ensures", "stage"=>"ensures"}.freeze,
+        {"step"=>"enforce_invariants", "stage"=>"invariants"}.freeze,
+        {"step"=>"save", "stage"=>"state"}.freeze,
+        {"step"=>"emit", "stage"=>"state"}.freeze
+      ].freeze,
       "ToStringType" => [
         {"type"=>"String"}.freeze,
         {"type"=>"Integer"}.freeze,

data/lib/hecks.rb

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

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

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

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

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