hecks 2.8.0 → 3.0.0

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -1,15 +1,5 @@
-# ITS OWN BOUNDED CONTEXT, booted centrally like `Deploy` — never
-# attached via `uses_framework` (a framework member's aggregate folds
-# into the ATTACHING domain's own per-boot registry, framework.rb:43-66
-# — since hecks gives each tenant its own separate `Runtime.boot`, a
-# framework-attached Tenant would exist as a single-row copy inside
-# EVERY tenant's own boot, never as one cross-tenant list, defeating
-# this domain's whole point). `Deploy::Tenant` (deploy.bluebook) stays
-# a SEPARATE, validation-only aggregate — a shape check before
-# provisioning; this is the durable, reactable runtime fact that
-# aggregate's own comment named and deliberately deferred. Two
-# different meanings of "Tenant," on purpose, translated at the one
-# explicit seam `tenancy.hecksagon`'s own `translates` line names.
+# Its own bounded context, booted centrally like `Deploy` and never attached via `uses_framework`:
+# an attached Tenant would be a single-row copy in every tenant's boot, not one cross-tenant list.
 Hecks.bluebook "Tenancy" do
   vision "Which tenants exist, which realm and storage each one owns, and whether each is currently allowed to run, is one queryable, historical fact — not scattered across a world-file overlay and a validation-only command."
 
@@ -27,7 +17,7 @@ Hecks.bluebook "Tenancy" do
     attribute :status, Status, default: { value: "Active" }
 
     value_object "Slug" do
-      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
       invariant("a tenant slug is named") { !value.to_s.empty? }
     end
 
@@ -42,7 +32,7 @@ Hecks.bluebook "Tenancy" do
     end
 
     value_object "Schema" do
-      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
       invariant("a schema is named") { !value.to_s.empty? }
     end
 
@@ -50,14 +40,8 @@ Hecks.bluebook "Tenancy" do
       attribute :value, String, one_of: ["Active", "Suspended", "Retired"]
     end
 
-    # FIRES AFTER PROVISIONING, NEVER BEFORE — a pure record with no
-    # side effects, dispatched by `tenancy.hecksagon`'s own `translates`
-    # reaction once `Deploy::Tenant.Provision`'s adapter has already
-    # written the world overlay and proven the domain boots. Driving
-    # provisioning FROM this command's own emission would need a
-    # process manager reacting to it — the exact durable-saga cost
-    # `deploy.bluebook`'s own `Tenant` aggregate comment already argued
-    # three local, idempotent, single-process steps don't need.
+    # Fires after provisioning, never before: driving provisioning from this command's emission
+    # would need a process manager, the durable-saga cost `deploy.bluebook` argues against.
     command "Register" do
       goal "Record that a tenant now exists, after its shape has been validated and its schema provisioned"
 
@@ -74,13 +58,8 @@ Hecks.bluebook "Tenancy" do
       emits "TenantRegistered"
     end
 
-    # RECORD-ONLY — nothing today reads `status` before dispatch or
-    # boot, so suspending a tenant here does not yet stop anything from
-    # running. Spelled out in this command's own `goal`, not just a
-    # comment, so it survives into generated docs/corpus rather than
-    # quietly reading as enforced when it isn't — the exact "a dial
-    # says a check runs when nothing runs it" defect class this
-    # project has already been burned by once.
+    # Record-only: nothing reads `status` before dispatch or boot yet. Stated in the `goal` too,
+    # so generated docs do not read it as enforced.
     command "Suspend" do
       goal "Record that a tenant should no longer be treated as active — nothing yet enforces this at dispatch or boot time"
 
@@ -101,11 +80,8 @@ Hecks.bluebook "Tenancy" do
       emits "TenantReactivated"
     end
 
-    # RECORD-ONLY, DELIBERATELY — dropping a live Postgres schema as an
-    # automatic side effect of a command handler would break the pure,
-    # no-adapter-calls-from-a-handler shape every other command in this
-    # corpus holds to. Real teardown, if ever built, is its own
-    # separate, deliberately reviewed tool — never implicit here.
+    # Record-only: dropping a live schema from a command handler would break the pure, no-adapter
+    # handler shape. Teardown, if built, is a separate reviewed tool.
     command "Retire" do
       goal "Record that a tenant is permanently done — real schema teardown is a deliberately separate, manually-run tool, never automatic here"
 

data/lib/hecks/tenancy/bluebook/tenancy.hecksagon

@@ -1,30 +1,13 @@
 Hecks.hecksagon "Tenancy" do
   Tenancy::Tenant.persisted_by("LocalStorage")
 
-  # THE TRANSLATION SEAM — the one explicit place Deploy's "Tenant"
-  # (a validated request) becomes Tenancy's "Tenant" (a durable fact).
-  # `on` deliberately omits the "Deploy::" prefix: PolicyInterpreter
-  # matches by event name plus the emitting aggregate's own demodulised
-  # name only, never the domain (confirmed live — a domain-qualified
-  # `on` silently never matches).
+  # The one seam where Deploy's "Tenant" (a validated request) becomes Tenancy's "Tenant" (a fact).
+  # `on` omits the "Deploy::" prefix: PolicyInterpreter matches event and aggregate name only.
+  # `with:` is required: the event payload also carries the port's dispatch-time args, which
+  # `Register` does not declare and would refuse.
   #
-  # `with:` IS REQUIRED, confirmed live — `TenantProvisioned`'s own
-  # payload is the ANSWER (slug/domain/realm/schema) merged with the
-  # port operation's OWN dispatch-time args (database/adapter,
-  # PortOperationInterpreter#ask's `ctx.args.merge(spread(answer))`),
-  # so the whole payload forwarded verbatim carries two fields
-  # `Register` never declares and gets refused outright.
-  # CHECKED TOGETHER, NOT IN ISOLATION — `bin/model_check`'s own
-  # `deaf_policy` check only sees ONE domain's own emitted events by
-  # default, which would flag this reaction as deaf (it reacts to a
-  # FOREIGN event, not one Tenancy itself emits). Fixed by
-  # `global_emitted_events:`, a cross-domain set `bin/model_check`
-  # builds across every target it boots in one run — run `bin/model_check
-  # lib/hecks/deploy lib/hecks/tenancy` (both targets, one invocation),
-  # not each directory separately, or this reads as a false positive
-  # again. Neither `deploy` nor `tenancy` is in
-  # `Hecks::Corpus::MODEL_CHECK_KINDS`, so the automatic sweep never
-  # reaches this at all, checked or not.
+  # Check with `hecks model_check lib/hecks/deploy lib/hecks/tenancy` in one run; alone, the
+  # reaction to a foreign event reads as a deaf policy.
   translates "RegisterProvisionedTenant" do
     on Tenant::TenantProvisioned
     trigger Tenant::Register, with: { slug: :slug, domain: :domain, realm: :realm, schema: :schema }

data/lib/hecks/three_zero/forms.yml

@@ -0,0 +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]
+  [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
+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
+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
+  <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]
+fuzz: hecks fuzz [domain] [seeds=20] [steps=30] [workers=] [adapter=memory]
+generate: hecks 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>
+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
+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
+project_cli: hecks project_cli [domain-path …]
+project_deploy: hecks deploy 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=
+  [adapter=PostgresEra]
+project_vocabulary: hecks project_vocabulary
+project_wasm: hecks build_wasm <domain>
+project_wasm_browser: hecks 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
+  ~/Projects --max-depth 3 --known-path PATH …"]
+qa_domain_novelty: hecks quality_control judge_novelty <domain> [arguments="--against
+  PATH …"]
+qa_generated_domains: hecks quality_control 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=
+  demonstration= symptom= expectation= submitter= [tags=a,b] [name=] [reproduced=yes|no]
+qa_mine_combinations: hecks quality_control 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>
+  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_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
+  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=]
+  [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
+  (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=]
+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]
+  [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]
+  [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=]
+  --confirm
+statements: hecks 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>
+  [snapshot=] [host_version=] [rehearsal=pass|fail] [rehearsed_at=] --confirm
+vendor_bluebook: hecks vendor <package[@version]> [from=path] [root=path]

data/lib/hecks/three_zero.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Hecks
+  # The table of what each retired `bin/` script became in hecks 3.0.0 (ADR 0080): a command on
+  # the Hecks domain, run through `exe/hecks`. `docs/tools.md` is pinned to it.
+  module ThreeZero
+    # Each retired script's name mapped to the 3.0 form that replaced it.
+    FORMS = YAML.safe_load_file(File.join(__dir__, "three_zero/forms.yml")).freeze
+  end
+end

data/lib/hecks/tools/argument_gate_matrix.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "hecks/fuzzing"
+require "json"
+require "fileutils"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Generates the argument-gate ordering matrix: for each adjacent pair of gates a command
+    # can violate, one input violating both, with Ruby's refusal recorded as the expected answer.
+    # A row is kept only when Ruby's dispatch trace shows the earlier gate refused (ADR 0010).
+    #
+    #   hecks argument_gate_matrix            # report only
+    #   hecks argument_gate_matrix --write    # rewrite the matrix + fixtures
+    module ArgumentGateMatrix
+      # Domains chosen for the argument shapes they carry: value objects, references, roles,
+      # entity commands, closed sets, and an identity key colliding with an argument.
+      DOMAINS = %w[
+        examples/banking
+        examples/pizzas
+        examples/roster
+        examples/chess
+        qa/stress_domains/nested_pieces
+        qa/stress_domains/ledger_ordering
+      ].freeze
+
+      MATRIX_FILE = "spec/corpus/argument_gate_order/matrix.json"
+
+      FIXTURE_NOTE = "GENERATED by hecks argument_gate_matrix (roadmap D2) — one step per adjacent pair of " \
+                     "argument-gate steps this domain's own commands can violate, each input violating BOTH, so " \
+                     "the refusal that wins is the EARLIER declared step's. Ruby's own answers are pinned in " \
+                     "spec/corpus/argument_gate_order/matrix.json; this file holds the Rust port to the same rows " \
+                     "through the ordinary conformance harness. Do not hand-edit — re-run " \
+                     "hecks argument_gate_matrix --confirm."
+
+      # Gate order comes from the vocabulary table, so reordering it reorders the pairs.
+      AGGREGATE_ORDER = Hecks::Vocabulary.symbols("AggregateDispatchOrder").map(&:to_s)
+      ENTITY_ORDER    = Hecks::Vocabulary.symbols("EntityDispatchOrder").map(&:to_s)
+      # `decode_arguments` is a no-op in Ruby, so no input can violate it.
+      GATES = %w[refuse_unknown_arguments refuse_absent_arguments normalize_args refuse_role_mismatch resolve_references].freeze
+      # The identity-resolution step that follows the gates in both orders.
+      SETTLES = { "aggregate" => "hydrate", "entity" => "hydrate_parent" }.freeze
+
+      # A `Random` whose no-argument `rand` is a constant above every "generate something invalid"
+      # probability in `ValueGenerator`, so generated payloads are always valid.
+      class SteadyRandom
+        def initialize(seed) = @random = Random.new(seed)
+
+        def rand(limit = nil) = limit.nil? ? 0.99 : @random.rand(limit)
+
+        def bytes(count) = @random.bytes(count)
+      end
+
+      module_function
+
+      def order_for(kind) = kind == "entity" ? ENTITY_ORDER : AGGREGATE_ORDER
+
+      def base_args(command, aggregate, random)
+        command.attributes.to_h do |attribute|
+          [attribute.name.to_s, Hecks::Fuzzing::ValueGenerator.value_for(attribute, aggregate, random: random, known_ids: {})]
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def identity_args(construct, aggregate, random)
+        Array(construct.identified_by).to_h do |path|
+          head = path.to_s.split(".").first
+          attribute = construct.attributes.find { |a| a.name.to_s == head }
+          value = attribute && Hecks::Fuzzing::ValueGenerator.value_for(attribute, aggregate, random: random, known_ids: {})
+          [head, value || "no-such-#{head}"]
+        end
+      rescue ArgumentError
+        {}
+      end
+
+      # `to:`/`with:` are dispatch envelope keywords, so an attribute with either name is read as
+      # a route; corrupting it would exercise envelope parsing, not an argument gate.
+      ENVELOPE_KEYS = %w[to with].freeze
+
+      def corruptible(command)
+        command.attributes.reject { |a| a.list? || a.reference? || ENVELOPE_KEYS.include?(a.name.to_s) }
+      end
+
+      def droppable(command)
+        command.attributes.reject { |a| a.optional? || a.list? || ENVELOPE_KEYS.include?(a.name.to_s) }
+      end
+
+      def live_gates(command, kind)
+        gates = ["refuse_unknown_arguments"]
+        gates << "refuse_absent_arguments" if droppable(command).any?
+        gates << "normalize_args" if corruptible(command).any?
+        gates << "refuse_role_mismatch" unless command.role.to_s.empty?
+        gates << "resolve_references" if command.attributes.any?(&:reference?)
+        gates << SETTLES.fetch(kind) unless kind == "aggregate" && command.creates?
+        gates
+      end
+
+      MISMATCHED_ROLE = "a role this caller does not hold"
+
+      # Mutates `args` to violate `step`; returns a description of the violation, or nil if the
+      # command cannot violate it.
+      def violate!(step, args, command, aggregate, random)
+        case step
+        when "refuse_unknown_arguments" then violate_unknown!(args, random)
+        when "refuse_absent_arguments"  then violate_absent!(args, command)
+        when "normalize_args"           then violate_normalize!(args, command, aggregate, random)
+        when "refuse_role_mismatch"     then MISMATCHED_ROLE
+        when "resolve_references"       then violate_reference!(args, command)
+        # The world is empty, so every acting command addresses a missing record.
+        when "hydrate", "hydrate_parent" then "no record exists"
+        end
+      end
+
+      def violate_unknown!(args, random)
+        name, value = Hecks::Fuzzing::InvalidValueGenerator.undeclared_argument(random: random)
+        args[name.to_s] = value
+        name.to_s
+      end
+
+      def violate_absent!(args, command)
+        dropped = droppable(command).first or return nil
+
+        args.delete(dropped.name.to_s)
+        dropped.name.to_s
+      end
+
+      # Corrupts one attribute with a wrong value both engines word identically. It avoids
+      # `InvalidValueGenerator.corrupt`, whose composite-value-object and Array shapes render
+      # differently in Ruby and Rust, and corrupts a declared value-object field instead.
+      def violate_normalize!(args, command, aggregate, _random)
+        attribute = corruptible(command).find { |a| args.key?(a.name.to_s) } || corruptible(command).first
+        return nil unless attribute
+
+        value_object = Hecks::Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
+        current = args[attribute.name.to_s]
+        wrong =
+          if value_object.nil?
+            mistyped_scalar(attribute.type)
+          elsif current.is_a?(Hash)
+            field = value_object.attributes.find { |f| current.key?(f.name.to_s) } or return nil
+
+            current.merge(field.name.to_s => value_object.closed_set? ? NON_MEMBER : mistyped_scalar(field.type))
+          end
+        return nil if wrong.nil?
+
+        args[attribute.name.to_s] = wrong
+        attribute.name.to_s
+      end
+
+      # A well-typed string no `one_of` admits, so a closed set refuses on membership.
+      NON_MEMBER = "not a declared member"
+
+      # For a String field a plain scalar is worded differently by Ruby and Rust, so an empty
+      # Hash (the branch they share) stands in as the wrong value.
+      def mistyped_scalar(type_name)
+        type_name.to_s == "String" ? {} : "not a #{type_name.to_s.downcase}"
+      end
+
+      def violate_reference!(args, command)
+        reference = command.attributes.find(&:reference?) or return nil
+
+        args[reference.name.to_s] = "no-such-#{reference.type.target_name.to_s.downcase}"
+        reference.name.to_s
+      end
+
+      # The first declared step missing from the dispatch trace is the one that refused.
+      def refused_step(kind)
+        interpreter = kind == "entity" ? Hecks::Runtime::EntityInterpreter : Hecks::Runtime::CommandInterpreter
+        ran = interpreter.trace || []
+        # `decode_arguments` never traces, so it must not be read as the refusing step.
+        order_for(kind).reject { |step| step == "decode_arguments" }.find { |step| !ran.include?(step.to_sym) }
+      end
+
+      # Dispatches one row; returns [refusal class, message, refused step], or nils if it succeeded.
+      def run_row(runtime, row, kind)
+        Hecks::Runtime::CommandInterpreter.trace = []
+        Hecks::Runtime::EntityInterpreter.trace = []
+        args = JSON.parse(JSON.generate(row[:args])).transform_keys(&:to_sym)
+        begin
+          if row[:role]
+            Hecks.as_caller(role: row[:role]) { runtime.dispatch_flat(row[:verb], args) }
+          else
+            runtime.dispatch_flat(row[:verb], args)
+          end
+          [nil, nil, nil]
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          [e.class.name.split("::").last, e.message, refused_step(kind)]
+        end
+      ensure
+        Hecks::Runtime::CommandInterpreter.trace = nil
+        Hecks::Runtime::EntityInterpreter.trace = nil
+      end
+
+      # One row per adjacent live-gate pair the command can violate on both steps. Commands with an
+      # envelope-keyword attribute never reach an argument gate, so they yield none.
+      def rows_for(command, aggregate, verb, kind, random)
+        return [] if command.attributes.any? { |a| ENVELOPE_KEYS.include?(a.name.to_s) }
+
+        base = base_args(command, aggregate, random)
+        return [] if base.nil?
+
+        gates = live_gates(command, kind)
+        gates.each_cons(2).filter_map do |earlier, later|
+          args = JSON.parse(JSON.generate(base))
+          args.merge!(identity_args(aggregate, aggregate, random)) unless kind == "aggregate" && command.creates?
+          role = nil
+          earlier_detail = violate!(earlier, args, command, aggregate, random)
+          later_detail   = violate!(later, args, command, aggregate, random)
+          next if earlier_detail.nil? || later_detail.nil?
+
+          role = MISMATCHED_ROLE if [earlier, later].include?("refuse_role_mismatch")
+
+          { verb: verb, kind: kind, role: role, pair: [earlier, later],
+            violates: { earlier => earlier_detail, later => later_detail }, args: args }
+        end
+      end
+
+      def candidates(runtime, chapter)
+        bluebook = runtime.registry.bluebook(chapter)
+        random = SteadyRandom.new(20_260_918)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate_rows = aggregate.commands.flat_map do |command|
+            rows_for(command, aggregate, "#{chapter}::#{aggregate.hecks_name}.#{command.hecks_name}", "aggregate", random)
+          end
+          entity_rows = aggregate.entities.flat_map do |entity|
+            entity.commands.flat_map do |command|
+              verb = "#{chapter}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
+              rows = rows_for(command, aggregate, verb, "entity", random)
+              rows.each { |row| row[:args] = identity_args(entity, aggregate, random).merge(row[:args]) }
+            end
+          end
+          aggregate_rows + entity_rows
+        end
+      end
+
+      # Dispatches every candidate row of each domain, keeps the ones Ruby's dispatch trace
+      # confirms, and prints how many; with `--write` it rewrites the matrix and the Rust
+      # conformance fixtures.
+      def main(argv, root: Tools::ROOT)
+        kept, dropped = sweep(root)
+        report(kept, dropped)
+        write(root, kept) if argv.include?("--write")
+        0
+      end
+
+      def sweep(root)
+        kept = []
+        dropped = []
+        DOMAINS.each do |domain|
+          Hecks::Fuzzing::IsolatedBoot.call(File.join(root, domain)) do |copy|
+            runtime = Hecks.boot(copy, environment: nil)
+            chapters = runtime.registry.bluebooks.keys
+            chapter = chapters.find { |name| candidates(runtime, name).any? } || chapters.first
+            candidates(runtime, chapter).each do |row|
+              kind, error, refused = run_row(runtime, row, row[:kind])
+              if kind.nil?
+                dropped << row.merge(reason: "Ruby accepted it — neither gate refused")
+              elsif refused.to_s != row[:pair].first
+                dropped << row.merge(reason: "Ruby refused at #{refused.inspect} (#{kind}), not the earlier declared step")
+              else
+                kept << row.merge(domain: domain, expected: { "kind" => kind, "error" => error, "refused_at" => refused.to_s })
+              end
+            end
+          end
+        end
+        [kept, dropped]
+      end
+
+      def report(kept, dropped)
+        pairs = kept.group_by { |row| row[:pair].join(" before ") }.transform_values(&:size)
+        puts "kept #{kept.size} rows over #{DOMAINS.size} domains; dropped #{dropped.size}"
+        pairs.sort.each { |pair, count| puts "  #{pair}: #{count}" }
+        dropped.group_by { |row| row[:reason] }.sort_by { |_, rows| -rows.size }.each do |reason, rows|
+          puts "  dropped #{rows.size}: #{reason}"
+        end
+      end
+
+      def write(root, kept)
+        path = File.join(root, MATRIX_FILE)
+        FileUtils.mkdir_p(File.dirname(path))
+        matrix = {
+          "generated_by"    => "hecks argument_gate_matrix",
+          "aggregate_order" => AGGREGATE_ORDER,
+          "entity_order"    => ENTITY_ORDER,
+          "rows"            => kept.map do |row|
+            { "domain" => row[:domain], "verb" => row[:verb], "kind" => row[:kind], "pair" => row[:pair],
+              "violates" => row[:violates], "role" => row[:role], "args" => row[:args], "expected" => row[:expected] }
+          end
+        }
+        File.write(path, "#{JSON.pretty_generate(matrix)}\n")
+        puts "wrote #{path}"
+
+        kept.group_by { |row| row[:domain] }.each { |domain, rows| write_fixture(root, domain, rows) }
+      end
+
+      def write_fixture(root, domain, rows)
+        path = File.join(root, "spec/corpus/rust_conformance/argument_gate_order_#{File.basename(domain)}.json")
+        fixture = {
+          "domain" => domain,
+          "note"   => FIXTURE_NOTE,
+          "steps"  => rows.map do |row|
+            step = { "verb" => row[:verb] }
+            step["role"] = row[:role] if row[:role]
+            step["args"] = row[:args]
+            step
+          end
+        }
+        File.write(path, "#{JSON.pretty_generate(fixture)}\n")
+        puts "wrote #{path}"
+      end
+    end
+  end
+end