hecks 2.9.0 → 3.0.0

data/lib/hecks/rust_build.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "tempfile"
+require_relative "hecks/adapters/console_capture"
+
+module Hecks
+  # The tools that generate a domain's Rust source, compile it and check the build against the Ruby
+  # engine, carried in the gem so a caller reaches them in this process.
+  #
+  # Each tool is a module with `call(argv) -> Integer`: it reads its arguments as a command line
+  # would give them, prints its report to `$stdout` and its complaints to `$stderr`, reads
+  # `ENV` for its settings, and answers an exit status. `run` and `capture` are the entry points:
+  # they hand a tool the streams and environment it is asked to use for the length of one call,
+  # and turn a refusal (`Failure`, `abort`, an unexpected error) into a status and a message. The
+  # `hecks project_rust` family of verbs runs them through `run`.
+  module RustBuild
+    # The gem's root directory, where `lib/` and `rust/` live.
+    ROOT = File.expand_path("../..", __dir__)
+
+    # Raised by a tool to refuse, with the reason as the message.
+    class Failure < StandardError; end
+
+    # What one captured call did: `out` and `err` (what the tool printed) and its exit `status`.
+    Result = Struct.new(:out, :err, :status) do
+      # @return [Boolean] whether the tool succeeded
+      def ok? = status.zero?
+    end
+
+    # Tool name to the file that defines it and the constant it defines.
+    TOOLS = {
+      "project_rust"          => ["rust_build/project_rust", :ProjectRust],
+      "project_wasm"          => ["rust_build/wasm", :Wasm],
+      "project_wasm_browser"  => ["rust_build/wasm_browser", :WasmBrowser],
+      "rust_conformance"      => ["rust_build/conformance", :Conformance],
+      "rust_conformance_fuzz" => ["rust_build/conformance_fuzz", :ConformanceFuzz],
+      "rust_coverage"         => ["rust_build/coverage", :Coverage]
+    }.freeze
+
+    # The process-wide lock a call holds while it swaps `ENV`, `$stdout` and `$stderr`; the same
+    # lock `ConsoleCapture` holds, so a build and a capture never interleave.
+    LOCK = Hecks::Adapters::ConsoleCapture::LOCK
+    private_constant :LOCK
+
+    class << self
+      # The workspace tools build in: `HECKS_RUST_DIR`, or the gem's own `rust/`.
+      #
+      # @return [String] the directory
+      def rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(ROOT, "rust"))
+
+      # Runs a tool with the given environment, writing to the given streams.
+      #
+      # The process's `ENV`, `$stdout` and `$stderr` are replaced for the length of the call, so
+      # calls are serialized.
+      #
+      # @param tool [String] a key of `TOOLS`
+      # @param argv [Array<String>] the tool's arguments
+      # @param env [Hash{String => String, nil}] variables to set for the call (nil removes one)
+      # @param out [IO] where the tool's stdout goes; must be a real IO (a file or the terminal)
+      # @param err [IO] where the tool's stderr goes
+      # @return [Integer] the exit status
+      def run(tool, argv, env: {}, out: $stdout, err: $stderr)
+        LOCK.synchronize do
+          with_env(env) do
+            with_streams(out, err) { finish(tool, argv) }
+          end
+        end
+      end
+
+      # Runs a program, its output going where the running tool's output goes.
+      #
+      # @param command [Array<String>] the program and its arguments
+      # @param chdir [String, nil] the directory to run it in
+      # @param env [Hash{String => String}] variables to set for it
+      # @return [void]
+      # @raise [Failure] when it cannot start or ends non-zero
+      def command!(*command, chdir: nil, env: {})
+        options = { out: $stdout, err: $stderr }
+        options[:chdir] = chdir if chdir
+        return if system(env, *command, **options)
+
+        raise Failure, "`#{command.join(' ')}` failed#{" in #{chdir}" if chdir}"
+      end
+
+      # Runs a tool and holds what it printed.
+      #
+      # @param tool [String] a key of `TOOLS`
+      # @param argv [Array<String>] the tool's arguments
+      # @param env [Hash{String => String, nil}] variables to set for the call
+      # @return [Result] what it printed, and how it ended
+      def capture(tool, argv, env: {})
+        Tempfile.create("rust_build_out") do |out|
+          Tempfile.create("rust_build_err") do |err|
+            status = run(tool, argv, env: env, out: out, err: err)
+            [out, err].each(&:flush)
+            Result.new(File.read(out.path), File.read(err.path), status)
+          end
+        end
+      end
+
+      # Sets variables for the block and puts them back after, for a nested tool call.
+      #
+      # @param env [Hash{String => String, nil}] variables to set (nil removes one)
+      # @yield the work to do under those variables
+      # @return [Object] the block's value
+      def with_env(env)
+        LOCK.synchronize do
+          saved = env.keys.to_h { |key| [key, ENV.fetch(key, nil)] }
+          begin
+            env.each { |key, value| ENV[key] = value }
+            yield
+          ensure
+            saved.each { |key, value| ENV[key] = value }
+          end
+        end
+      end
+
+      private
+
+      def with_streams(out, err)
+        saved = [$stdout, $stderr]
+        $stdout = out
+        $stderr = err
+        yield
+      ensure
+        $stdout, $stderr = saved
+      end
+
+      def finish(tool, argv)
+        file, constant = TOOLS.fetch(tool)
+        require_relative file
+        RustBuild.const_get(constant).call(argv)
+      rescue Failure => e
+        warn e.message
+        1
+      rescue SystemExit => e
+        e.status
+      rescue StandardError, ScriptError => e
+        warn "#{tool}: #{e.class}: #{e.message}"
+        1
+      end
+    end
+  end
+end

data/lib/hecks/storehouse.rb

@@ -2,8 +2,8 @@ require "json"
 require "fileutils"
 require "time"
 require_relative "cache_dir"
-require_relative "facade/command_request"
-require_relative "facade/json_door"
+require_relative "doors/command_request"
+require_relative "doors/json_door"
 require_relative "naming"
 require_relative "projector"
 require_relative "runtime/errors"
@@ -56,7 +56,7 @@ module Hecks
     end
 
     # The same alias table CliRunner resolves against, kept here so dispatch
-    # and query never drift from what a human typing bin/run sees.
+    # and query never drift from what a human typing hecks run sees.
     # :nodoc:
     def resolve!(cli, name, asking:)
       pool = asking ? cli[:questions] : cli[:verbs]
@@ -185,9 +185,9 @@ module Hecks
       cli      = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
       spec     = resolve!(cli, command, asking: false)
       require_caller_for_role_gated!(spec, role)
-      envelope = Facade::CommandRequest.normalize(Facade::JsonDoor.deep_symbolize(args),
-                                                  receiver:        spec[:receiver],
-                                                  legacy_receiver: spec[:legacy_receiver])
+      envelope = Doors::CommandRequest.normalize(Doors::JsonDoor.deep_symbolize(args),
+                                                 receiver:        spec[:receiver],
+                                                 legacy_receiver: spec[:legacy_receiver])
 
       result = with_caller(role, actor_id) do
         dry_run ? dry_run_outcome(runtime, spec, envelope, summary: summary) : real_dispatch(runtime, spec, envelope, summary)
@@ -200,8 +200,8 @@ module Hecks
       result = runtime.dispatch_flat(spec[:verb], envelope)
       ok(summary: summary,
          id:      result.id,
-         state:   result.state.nil? ? nil : Facade::JsonDoor.materialize(result.state),
-         events:  result.events.map { |event| { name: event.name, payload: Facade::JsonDoor.materialize(event.payload) } })
+         state:   result.state.nil? ? nil : Doors::JsonDoor.materialize(result.state),
+         events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
     end
 
     # :nodoc:
@@ -228,7 +228,7 @@ module Hecks
     def dispatch_batch(runtime:, steps:, summary:, source: nil, role: nil, actor_id: nil)
       require_summary!(summary)
       results = Array(steps).map do |raw|
-        step = Facade::JsonDoor.deep_symbolize(raw)
+        step = Doors::JsonDoor.deep_symbolize(raw)
         dispatch(runtime: runtime, command: step[:command], args: step[:args] || {},
                  summary: summary, source: source, role: role, actor_id: actor_id)
       end
@@ -268,9 +268,9 @@ module Hecks
       valid_caller!(role, actor_id)
       cli  = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
       spec = resolve!(cli, question, asking: true)
-      rows = with_caller(role, actor_id) { runtime.query(spec[:verb], **Facade::JsonDoor.deep_symbolize(args)) }
+      rows = with_caller(role, actor_id) { runtime.query(spec[:verb], **Doors::JsonDoor.deep_symbolize(args)) }
 
-      ok(summary: summary, rows: rows.map { |row| Facade::JsonDoor.materialize(row) }).merge(verb: spec[:verb])
+      ok(summary: summary, rows: rows.map { |row| Doors::JsonDoor.materialize(row) }).merge(verb: spec[:verb])
     end
 
     # Reads one aggregate's stored records directly, bypassing any declared
@@ -303,9 +303,9 @@ module Hecks
       if id
         instance = repository.find(id) or
           raise Runtime::NotFound, "no #{ir.hecks_name} found for id #{id.inspect}"
-        ok(summary: summary, record: Facade::JsonDoor.materialize(instance.to_h))
+        ok(summary: summary, record: Doors::JsonDoor.materialize(instance.to_h))
       else
-        records = repository.all.map { |instance| Facade::JsonDoor.materialize(instance.to_h) }
+        records = repository.all.map { |instance| Doors::JsonDoor.materialize(instance.to_h) }
         ok(summary: summary, count: records.length, records: records)
       end
     end
@@ -346,7 +346,7 @@ module Hecks
     end
 
     # One aggregate's (or the whole chapter's) full usage documentation — the
-    # same document bin/docs renders for a human.
+    # same document hecks docs renders for a human.
     #
     # @param runtime [Runtime::Registry] the booted domain to describe
     # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
@@ -373,7 +373,7 @@ module Hecks
     # @return [Hash] {ok: true, domain:, valid: true} plus :findings when deep;
     #   {ok: false, domain:, valid: false, error:} if the boot itself failed
     def validate(domain:, deep: false)
-      runtime = Hecks.boot(confine!(domain, "domain"), install_facade: false)
+      runtime = Hecks.boot(confine!(domain, "domain"), install_doors: false)
       result  = { ok: true, domain: domain, valid: true }
 
       if deep
@@ -407,7 +407,7 @@ module Hecks
 
     # :nodoc:
     def journal_entries(repository)
-      repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Facade::JsonDoor.materialize(entry.state) } }
+      repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Doors::JsonDoor.materialize(entry.state) } }
     end
 
     # Runs a domain's hand-curated .behaviors examples and reports the results.

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

@@ -17,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
 
@@ -32,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
 

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

@@ -6,7 +6,7 @@ Hecks.hecksagon "Tenancy" do
   # `with:` is required: the event payload also carries the port's dispatch-time args, which
   # `Register` does not declare and would refuse.
   #
-  # Check with `bin/model_check lib/hecks/deploy lib/hecks/tenancy` in one run; alone, the
+  # 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

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