hecks 5.0.0 → 7.0.0

data/lib/hecks/runtime/value/field_checks.rb

@@ -30,9 +30,9 @@ module Hecks
         # The refusal every wrong-typed or missing field shares: `type_name`'s `field_name` was
         # offered `offered` where `expected` was declared.
         def numeric_field_mismatch!(type_name, field_name, expected, offered)
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "numeric_field",
-                                           type: type_name, field: field_name, expected: expected, offered: offered)
+          message = RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                               type: type_name, field: field_name, expected: expected, offered: offered)
+          raise TypeMismatch.new(message, attribute: field_name)
         end
 
         # C3.8 boundary check — refuses a mistyped argument before it breaks a predicate.
@@ -52,15 +52,15 @@ module Hecks
 
         def check_numeric_bounds(type_name, field_name, given)
           if given.is_a?(Integer) && !INT64_RANGE.cover?(given)
-            raise TypeMismatch,
-                  RefusalWording.render_site("TypeMismatch", "integer_range",
-                                             type: type_name, field: field_name, offered: Rendering.describe(given))
+            raise TypeMismatch.new(RefusalWording.render_site("TypeMismatch", "integer_range", type: type_name,
+                                                              field: field_name, offered: Rendering.describe(given)),
+                                   attribute: field_name)
           end
           return unless given.is_a?(Float) && !given.finite?
 
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "non_finite_field",
-                                           type: type_name, field: field_name, offered: Rendering.describe(given))
+          raise TypeMismatch.new(RefusalWording.render_site("TypeMismatch", "non_finite_field", type: type_name,
+                                                            field: field_name, offered: Rendering.describe(given)),
+                                 attribute: field_name)
         end
 
         # A value object refuses an undeclared key the same way a command's own
@@ -71,10 +71,10 @@ module Hecks
           return if unknown.empty?
 
           declared = value_object.attributes.map(&:name)
-          raise UnknownArgument,
-                RefusalWording.render_site("UnknownArgument", "unknown_args",
-                                           command: value_object.hecks_name, unknown: unknown,
-                                           declared: declared)
+          raise UnknownArgument.new(RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                                               command: value_object.hecks_name, unknown: unknown,
+                                                               declared: declared),
+                                    attribute: unknown.first)
         end
 
         # C3.7 — every non-optional, non-list field must arrive (or construction

data/lib/hecks/runtime/value/invariant_violation.rb

@@ -1,5 +1,8 @@
+require_relative "../../refused"
+
 module Hecks
   module Runtime
-    class InvariantViolation < StandardError; end
+    # A value object's invariant refused the fields it was built from.
+    class InvariantViolation < Hecks::Refused; end
   end
 end

data/lib/hecks/runtime/value/references.rb

@@ -36,7 +36,9 @@ module Hecks
         # @return [Object, nil] the unwrapped scalar, or nil if it does not apply
         def sole_scalar_identity(value, paths)
           return nil unless value.is_a?(self) && paths.one?
-          return nil unless value.value_object.sole_attribute
+
+          shape = value.value_object
+          return nil unless shape.sole_attribute
 
           materialize_unwrapped(value)
         end
@@ -149,10 +151,11 @@ module Hecks
         # @return [String] `" (Target is known by head1, head2)"`, or `""` if the
         #   target or its identity heads cannot be resolved
         def known_by(attribute)
-          heads = Array(attribute.type.resolve&.identity_heads)
+          target = attribute.target_aggregate
+          heads = Array(target&.identity_heads)
           return "" if heads.empty?
 
-          " (#{attribute.type.target_name} is known by #{heads.join(", ")})"
+          " (#{attribute.target_name} is known by #{heads.join(", ")})"
         end
 
         private
@@ -161,7 +164,7 @@ module Hecks
         def reference_target(attribute, value)
           return nil unless value.is_a?(self) || value.is_a?(Hash)
 
-          target = attribute.type.resolve
+          target = attribute.target_aggregate
           target if target && !target.identity_paths.empty?
         end
 

data/lib/hecks/runtime/value/validation.rb

@@ -121,15 +121,18 @@ module Hecks
         end
 
         # Runs each value-object member of an input list through the same entry point a nested
-        # single
-        # value goes through, so a member's own invariants and nested lists refuse on dispatch
-        # exactly as they do when the list sits directly on a command. The members stay as offered.
+        # single value goes through, so a member's own invariants and nested lists refuse on
+        # dispatch exactly as they do when the list sits directly on a command. The members stay
+        # as offered.
+        #
+        # A bare member is judged too: it wraps into a one-field value object and is refused for
+        # any other, here, before the save, not when the saved record is read back.
         def validate_input_list(aggregate, attribute, fields)
           nested = value_object_for(aggregate, attribute.type)
           return unless nested
 
           Array(fields[attribute.name]).each do |member|
-            next unless member.is_a?(Hash)
+            next if member.is_a?(self)
 
             member_fields = apply_defaults(nested, fields_for(nested, attribute.name, member))
             validate!(nested, normalize_composite_fields(aggregate, nested, member_fields))

data/lib/hecks/runtime/wasm_plugin.rb

@@ -0,0 +1,98 @@
+require "json"
+require_relative "errors"
+
+module Hecks
+  module Runtime
+    # Runs a plugin adapter's wasm module: one question in, one answer out.
+    #
+    # A plugin is a WASI command, the same contract the Rust host runs its kernel by. It reads
+    # `{"question": "Bluebook::Aggregate.Query", "args": {...}}` as JSON on stdin and writes
+    # `{"rows": [...]}` or `{"refused": "why"}` as JSON on stdout. It is given no files, network,
+    # environment or arguments, so it answers from its question alone; here its clock and
+    # randomness are fixed too. Both hosts run the same module, so there is one implementation to
+    # trust.
+    module WasmPlugin
+      # How much a plugin may write before it is cut off; the Rust host uses the same cap.
+      STDOUT_CAP = 64 * 1024 * 1024
+
+      @compiled = {}
+      @lock = Mutex.new
+
+      module_function
+
+      # Asks a plugin one question.
+      #
+      # @param adapter [Bluebook::Adapter] the plugin adapter whose module answers
+      # @param question [String] the qualified query, such as `"Calendar::Event.Occurrences"`
+      # @param args [Hash] the query's arguments as plain data, a referenced record as its state
+      # @return [Array<Hash>, Hash] the plugin's rows
+      # @raise [PluginRefusal] if the plugin refuses the question
+      # @raise [WiringError] if the module cannot run or answers something that is not the contract
+      def ask(adapter, question, args)
+        reply = run(adapter, JSON.generate(question: question, args: args))
+        return reply.fetch("rows") if reply.key?("rows")
+        raise PluginRefusal, "#{question}: #{reply["refused"]}" if reply.key?("refused")
+
+        raise WiringError, "#{adapter.name} answered #{question} with neither rows nor a refusal"
+      end
+
+      # Compiles a plugin's module once, so a missing or broken module stops the boot.
+      #
+      # @param adapter [Bluebook::Adapter] the plugin adapter to compile
+      # @return [void]
+      # @raise [WiringError] if the module is missing or is not wasm
+      def compile!(adapter) = compiled(adapter)
+
+      def run(adapter, input)
+        engine, wasm_module, linker = compiled(adapter)
+        output = +""
+        store  = Wasmtime::Store.new(engine, wasi_p1_config: wasi_config(input, output))
+        start(linker.instantiate(store, wasm_module), adapter)
+        JSON.parse(output)
+      rescue JSON::ParserError => e
+        raise WiringError, "#{adapter.name} answered with text that is not JSON: #{e.message}"
+      end
+
+      # The WASI setup a run gets: fixed clock and randomness, `input` on stdin, and stdout
+      # written into `output` up to the cap.
+      def wasi_config(input, output)
+        config = Wasmtime::WasiConfig.new.add_determinism
+        config.set_stdin_string(input).set_stdout_buffer(output, STDOUT_CAP)
+      end
+
+      # A command ends by returning from `_start` or by exiting; only exit code 0 is an answer.
+      def start(instance, adapter)
+        instance.invoke("_start")
+      rescue Wasmtime::WasiExit => e
+        raise WiringError, "#{adapter.name} exited with code #{e.code}" unless e.code.zero?
+      rescue Wasmtime::Trap, Wasmtime::Error => e
+        raise WiringError, "#{adapter.name} failed: #{e.message}"
+      end
+
+      def compiled(adapter)
+        path = adapter.plugin_path
+        @lock.synchronize { @compiled[path] ||= compile(adapter, path) }
+      end
+
+      def compile(adapter, path)
+        require_wasmtime!(adapter)
+        raise WiringError, "#{adapter.name} runs #{adapter.runs}, but there is no #{path}" unless File.file?(path)
+
+        engine = Wasmtime::Engine.new
+        linker = Wasmtime::Linker.new(engine)
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        [engine, Wasmtime::Module.from_file(engine, path), linker]
+      rescue Wasmtime::Error => e
+        raise WiringError, "#{adapter.name} runs #{adapter.runs}, which is not a wasm module: #{e.message}"
+      end
+
+      # Lazy, so a domain that answers no query with a plugin does not need the wasmtime gem.
+      def require_wasmtime!(adapter)
+        require "wasmtime"
+      rescue LoadError
+        raise WiringError, "#{adapter.name} is a wasm plugin, which needs the wasmtime gem: " \
+                           "add `gem \"wasmtime\"` to the Gemfile"
+      end
+    end
+  end
+end

data/lib/hecks/runtime.rb

@@ -35,7 +35,7 @@ module Hecks
       # The registry declarations are currently landing in, or nil outside a boot.
       attr_reader :current_registry
 
-      # Loads a bluebook directory and returns the Dispatcher bound to it. See Loader.boot.
+      # Loads a bluebook directory and returns the Dispatcher bound to it. See `Hecks.boot`.
       #
       #   Hecks::Runtime.boot("examples/pizzas/bluebook")
       #     .dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
@@ -44,42 +44,42 @@ module Hecks
       # @param shared [String, nil] a shared-root override
       # @param install_driving [Boolean] whether to install the Ruby facade constants
       # @param environment [String, nil] the environment name for `Adapters::Folder#load_domain`
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot(path, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-        Loader.boot(path, shared: shared, install_driving: install_driving, environment: environment)
+      def boot(path, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+        Hecks.boot(path, shared: shared, install_driving: install_driving, environment: environment)
       end
 
-      # Loads a domain's declarations without binding any adapter. See Loader.describe.
+      # Loads a domain's declarations without binding any adapter. See `Hecks.describe`.
       #
       # @param path [String] path to a domain directory, or a file inside one
       # @param shared [String, nil] a shared-root override
       # @param environment [String, nil] the environment overlay; defaults to `HECKS_ENVIRONMENT`
       # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
-      def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
-        Loader.describe(path, shared: shared, environment: environment)
+      def describe(path, shared: nil, environment: Assembly::FROM_ENV)
+        Hecks.describe(path, shared: shared, environment: environment)
       end
 
-      # Finishes a boot from declarations `describe` already loaded. See Loader.boot_described.
+      # Finishes a boot from declarations `describe` already loaded. See `Hecks.boot_described`.
       #
       # @param described [Runtime::Loader::Described] what `describe` answered
       # @param install_driving [Boolean] whether to install the Ruby facade constants
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
       def boot_described(described, install_driving: true)
-        Loader.boot_described(described, install_driving: install_driving)
+        Hecks.boot_described(described, install_driving: install_driving)
       end
 
-      # Loads only the given files of a domain; otherwise like `boot`. See Loader.boot_files.
+      # Loads only the given files of a domain; otherwise like `boot`. See `Hecks.boot_files`.
       #
       # @param paths [String, Array<String>] one or more file paths within the domain
       # @param shared [String, nil] a shared-root override
       # @param install_driving [Boolean] whether to install the Ruby facade constants
       # @param environment [String, nil] the environment name for the selected-file loader
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot_files(paths, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-        Loader.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
+      def boot_files(paths, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+        Hecks.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
       end
 
       # Bind the ambient registry for the duration of the block, restoring

data/lib/hecks/rust_build/command_schemas.rb

@@ -0,0 +1,27 @@
+require "fileutils"
+require "json"
+require_relative "../projections/command_schema"
+
+module Hecks
+  module RustBuild
+    # `schemas.json` beside a generated domain's `ir.json`: each command's JSON Schema by
+    # `Aggregate/Command`. The host has no Ruby, so it serves what the build projected here.
+    module CommandSchemas
+      FILE = "schemas.json".freeze
+
+      module_function
+
+      # @param bluebook [Bluebook::Declaration] the target domain's bluebook
+      # @param dir [String] the domain's generated directory
+      # @return [String] the path written
+      def write(bluebook, dir)
+        files = Projections::CommandSchema.call(bluebook: bluebook)
+        schemas = files.to_h do |path, text|
+          [path.delete_prefix("#{bluebook.name}/").delete_suffix(".schema.json"), JSON.parse(text)]
+        end
+        FileUtils.mkdir_p(dir)
+        File.join(dir, FILE).tap { |path| File.write(path, "#{JSON.pretty_generate(schemas)}\n") }
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/conformance/surface.rb

@@ -23,18 +23,55 @@ module Hecks
             "events"    => result[:events].map { |event| event_surface(event) },
             "refusals"  => result[:refusals].map { |refusal| refusal_surface(refusal) }
           }
-          dry_runs = dry_run_surface(result[:dry_runs])
-          surface["dry_runs"] = dry_runs unless dry_runs.empty?
-          surface
+          surface.merge(read_only_surface(result)).merge(cross_domain_surface(result[:cross_domain]))
+        end
+
+        # What each `across` policy delivered (policy, target verb, payload), omitted when none did.
+        def cross_domain_surface(deliveries)
+          rows = JSON.parse(JSON.generate(deliveries || []))
+          rows.empty? ? {} : { "cross_domain" => rows }
+        end
+
+        # The dry runs and validations, each omitted when the script has none.
+        def read_only_surface(result)
+          dry_runs = dry_run_surface(result[:dry_runs], result[:dry_run_traces])
+          validations = JSON.parse(JSON.generate(result[:validations] || []))
+          { "dry_runs" => dry_runs, "validations" => validations }.reject { |_, entries| entries.empty? }
         end
 
         def refusal_surface(refusal)
           { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
         end
 
-        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
-        def dry_run_surface(dry_runs)
-          dry_runs.map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
+        # The stages whose every refusal both engines list.
+        COLLECTED_STAGES = %w[givens ensures invariants].freeze
+
+        # In the arguments stage Rust lists the unknown and absent names, one refusal each; a
+        # coercion mismatch it raises alone, so a run with one is compared on `ok` alone.
+        LISTED_ARGUMENT_CLASSES = %w[AbsentArgument UnknownArgument].freeze
+
+        # `verb` and `ok`, as `Hecks::Fuzzing::Differential` compares, and for a run refused where
+        # both engines list every refusal, each one's kind, stage, attribute, path and rule.
+        def dry_run_surface(dry_runs, traces = [])
+          dry_runs.zip(traces).map do |dry, trace|
+            reasons = trace&.dig(:validation, :reasons) unless dry[:ok]
+            { "verb" => dry[:verb].to_s, "ok" => dry[:ok] }.merge(collected_refusals(reasons))
+          end
+        end
+
+        # @param reasons [Array<Array>, nil] each as `[kind, stage, attribute, path, rule, class]`
+        # @return [Hash] `{"refusals" => reasons}` without the class, if both engines list them all
+        def collected_refusals(reasons)
+          return {} unless reasons&.any? && listed_in_full?(reasons)
+
+          { "refusals" => reasons.map { |reason| reason.first(5) } }
+        end
+
+        def listed_in_full?(reasons)
+          stage = reasons.first[1]
+          return true if COLLECTED_STAGES.include?(stage)
+
+          stage == "arguments" && reasons.all? { |reason| LISTED_ARGUMENT_CLASSES.include?(reason.last) }
         end
 
         def event_surface(event)
@@ -47,7 +84,13 @@ module Hecks
         def normalize(theirs)
           strip_snapshot_flags(theirs["instances"])
           strip_timestamps(theirs["events"])
-          theirs
+          theirs.merge(cross_domain_surface(kernel_deliveries(theirs["cross_domain_reactions"])))
+        end
+
+        # The kernel's per-step cross-domain reactions as one list of policy, target verb and
+        # payload.
+        def kernel_deliveries(per_step)
+          Array(per_step).flatten.map { |row| row.slice("policy", "target_verb", "payload") }
         end
 
         def strip_snapshot_flags(instances)

data/lib/hecks/rust_build/conformance.rb

@@ -5,6 +5,7 @@ require "open3"
 require_relative "../rust_build"
 require_relative "native_build"
 require_relative "conformance/surface"
+require_relative "kernel_input"
 
 module Hecks
   module RustBuild
@@ -20,6 +21,9 @@ module Hecks
       USAGE = "usage: hecks check_conformance <domain> <script.json> " \
               "[rust_output.json | native | build | path/to/binary | path/to/module.wasm]"
 
+      # A compiled wasm module's path.
+      WASM_MODULE = /\.wasm\z/
+
       module_function
 
       # @param argv [Array<String>] the domain, the script and optionally the artifact
@@ -46,18 +50,28 @@ module Hecks
       # The artifact's JSON for the script: live from a binary, or read from a file.
       def artifact_output(domain, script, other)
         case other
-        when "native" then run_binary(native_binary || missing_native!, script)
-        when "build" then run_binary(built_binary(domain), script)
-        when /\.wasm\z/ then run_wasm(domain, script, other)
-        when method(:pinned_binary?) then run_binary(other, script)
+        when "native" then run_binary(native_binary || missing_native!, kernel_input(domain, script))
+        when "build" then run_binary(built_binary(domain), kernel_input(domain, script))
+        when WASM_MODULE then run_wasm(domain, script, other)
+        when method(:pinned_binary?) then run_binary(other, kernel_input(domain, script))
         else File.read(other)
         end
       end
 
+      # The stdin a compiled artifact reads: the script's steps with the domain's `defaults`,
+      # `needs` and `query_needs` tables beside them, as every other conformance caller sends
+      # them (`KernelInput`). Without the tables the kernel never answers a fact the declaration
+      # `needs`, and a Ruby-filled argument refuses on the Rust side.
+      def kernel_input(domain, script)
+        input = JSON.parse(File.read(script))
+        KernelInput.tables_for(domain).each { |name, table| input[name] = table unless table.empty? }
+        JSON.generate(input)
+      end
+
       def run_wasm(domain, script, wasm)
         raise Failure, "#{wasm}: no such file — run hecks build_wasm #{domain} first" unless File.exist?(wasm)
 
-        run_process(["wasmtime", "run", wasm], File.read(script))
+        run_process(["wasmtime", "run", wasm], kernel_input(domain, script))
       end
 
       # A pinned per-domain binary, as named by a sweep's `replay:` line.
@@ -65,7 +79,7 @@ module Hecks
         !path.end_with?(".json") && File.file?(path) && File.executable?(path)
       end
 
-      def run_binary(binary, script) = run_process([binary], File.read(script))
+      def run_binary(binary, stdin) = run_process([binary], stdin)
 
       def run_process(command, stdin_data)
         stdout, status = Open3.capture2(*command, stdin_data: stdin_data)
@@ -105,18 +119,37 @@ module Hecks
       end
 
       def mismatches(ours, theirs)
-        found = %w[instances events refusals].filter_map do |key|
+        found = %w[instances events refusals cross_domain].filter_map do |key|
           next if ours[key] == theirs[key]
 
           "#{key}:\n  ruby:  #{ours[key].inspect}\n  other: #{theirs[key].inspect}"
         end
         dry = dry_run_mismatch(ours, theirs)
         found << dry if dry
+        validated = validation_mismatch(ours, theirs)
+        found << validated if validated
         found
       end
 
+      # A Rust dry run on the same surface as Ruby's: `verb`, `ok`, and each refusal's kind, stage,
+      # attribute, path and rule where the stage is one both engines list in full.
+      def their_dry_run(dry)
+        reasons = Array(dry["refusals"]).map do |refusal|
+          refusal.values_at("kind", "stage", "attribute", "path", "rule", "refusal")
+        end
+        dry.slice("verb", "ok").merge(Surface.collected_refusals(reasons))
+      end
+
+      # A `validate` step's answer, whole: the same refusals in the same order from both engines.
+      def validation_mismatch(ours, theirs)
+        mine = ours["validations"] || []
+        return if mine == (theirs["validations"] || [])
+
+        "validations:\n  ruby:  #{mine.inspect}\n  other: #{theirs["validations"].inspect}"
+      end
+
       def dry_run_mismatch(ours, theirs)
-        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
+        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| their_dry_run(dry) }
         return if (ours["dry_runs"] || []) == their_dry_runs
 
         "dry_runs:\n  ruby:  #{ours["dry_runs"].inspect}\n  other: #{their_dry_runs.inspect}"

data/lib/hecks/rust_build/conformance_fuzz.rb

@@ -15,7 +15,7 @@ module Hecks
     #
     #   ConformanceFuzz.call([domain, "native" | "path/to/module.wasm", seeds, steps])
     #
-    # `seeds` and `steps` default to `SEEDS` and `STEPS` in the environment, then to 10 and 25.
+    # `seeds` and `steps` default to 10 and 25.
     module ConformanceFuzz
       USAGE = "usage: hecks fuzz_conformance <domain> <native|path/to/module.wasm> [seeds] [steps]"
 
@@ -45,7 +45,7 @@ module Hecks
         domain, artifact, seeds, steps = argv
         raise Failure, USAGE unless domain && artifact
 
-        Run.new(domain, artifact, Integer(seeds || ENV["SEEDS"] || 10), Integer(steps || ENV["STEPS"] || 25),
+        Run.new(domain, artifact, Integer(seeds || 10), Integer(steps || 25),
                 scratch_dir(domain))
       end
 

data/lib/hecks/rust_build/domain_name.rb

@@ -14,11 +14,14 @@ module Hecks
       # vocabulary.
       CARGO_RESERVED = Hecks::Vocabulary.fetch("CargoReservedName")
 
+      # A plain lowercase identifier: a letter or underscore, then letters, digits, underscores.
+      IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/
+
       # @param name [String] the domain's directory name
       # @return [Boolean] whether it is a plain lowercase identifier and no reserved word
       def self.valid?(name)
         text = name.to_s
-        text.match?(/\A[a-z_][a-z0-9_]*\z/) &&
+        text.match?(IDENTIFIER) &&
           Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(domain_name: text).empty?
       end
     end

data/lib/hecks/rust_build/host.rb

@@ -5,6 +5,7 @@ require "open3"
 require_relative "../rust_build"
 require_relative "wasm"
 require_relative "prebuilt_binary"
+require_relative "target_dir"
 
 module Hecks
   module RustBuild
@@ -15,7 +16,7 @@ module Hecks
     #
     # The host is compiled from the workspace this release carries (`rust/host`), so the binary is
     # the one the installed gem was released with; nothing is fetched. The module and IR come from
-    # `Wasm`. `CARGO_TARGET_DIR` names where Cargo writes (the copy's `target/` for a client), so
+    # `Wasm`. `TargetDir` names where Cargo writes (one shared cache for an installed copy), so
     # a second build recompiles only what changed. Stages `<domain>-host`, `<domain>.wasm` and
     # `<domain>.ir.json` in `--stage` (default `.hecks/host/<target>/` in the working directory).
     module Host
@@ -28,10 +29,13 @@ module Hecks
       # A Rust target triple: `<arch>-<vendor>-<os>`, with an optional `-<env>`.
       TRIPLE = /\A[a-z0-9_]+(-[a-z0-9_.]+){2,3}\z/
 
+      # The `host: <triple>` line of `rustc -vV`, capturing the triple.
+      HOST_LINE = /^host: (\S+)/
+
       module_function
 
-      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>` and
-      #   `--stage=<directory>`
+      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>`,
+      #   `--stage=<directory>` and `--no-prebuilt` (compile the host, download no published one)
       # @return [Integer] the exit status
       # @raise [Failure] when the toolchain, the target or a step is missing or fails
       def call(argv)
@@ -39,13 +43,15 @@ module Hecks
           raise Failure, "usage: hecks build_host <domain> [target=<triple>] [stage=<directory>]"
         target = flag(argv, "target") || host_triple
         require_buildable!(target)
-        stage = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+        stage = stage_for(argv, target)
 
         build_module(domain)
-        publish(compile(target), File.basename(domain.chomp("/")), stage)
+        publish(compile(target, prebuilt: !argv.include?("--no-prebuilt")), File.basename(domain.chomp("/")), stage)
         0
       end
 
+      def stage_for(argv, target) = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+
       def build_module(domain)
         raise Failure, "project_wasm failed for #{domain}" unless Wasm.call([domain]).zero?
       end
@@ -61,7 +67,7 @@ module Hecks
       # @raise [Failure] when there is no Rust toolchain
       def host_triple
         require_rustup!
-        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[/^host: (\S+)/, 1] or
+        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[HOST_LINE, 1] or
           raise Failure, "rustup has no #{TOOLCHAIN} toolchain. Install it once with:\n\n    " \
                          "rustup toolchain install #{TOOLCHAIN}\n\nthen re-run the build."
       end
@@ -100,11 +106,11 @@ module Hecks
 
       # `rustup run`, not bare `cargo`, as `Wasm` does. A cross target links with the
       # `<arch>-linux-gnu-gcc` on PATH unless `CARGO_TARGET_<TRIPLE>_LINKER` already names a linker.
-      def compile(target)
+      def compile(target, prebuilt: true)
         host_dir = File.join(RustBuild.rust_dir, "host")
-        target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        target_dir = TargetDir.for(host_dir)
         binary = File.join(target_dir, target, "release", BINARY)
-        return binary if PrebuiltBinary.fetch("host", host_dir, target: target, into: binary)
+        return binary if PrebuiltBinary.fetch_for("rust/host", host_dir, target: target, into: binary, allowed: prebuilt)
 
         cargo_build(target, host_dir, { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target)))
         binary

data/lib/hecks/rust_build/native_build.rb

@@ -80,7 +80,8 @@ module Hecks
         return if relative.start_with?("target/") || !File.file?(path)
 
         stat = File.stat(path)
-        digest << "#{relative}\0#{stat.size}\0#{stat.mtime.to_i}.#{stat.mtime.nsec}\n"
+        mtime = stat.mtime
+        digest << "#{relative}\0#{stat.size}\0#{mtime.to_i}.#{mtime.nsec}\n"
       end
 
       # Holds an exclusive flock from `cargo build` through the copy-out: parallel sweeps share

data/lib/hecks/rust_build/parser.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # Builds the `hecks-parse` binary from `rust/parser`, the one the bluebook parser specs run, so
+    # they need no hand build to reach it.
+    #
+    #   Parser.call([])
+    #
+    # Writes `rust/parser/target/debug/hecks-parse`, the path those specs look for.
+    module Parser
+      module_function
+
+      # @param _argv [Array<String>] unused: the crate has one build
+      # @return [Integer] 0 once the binary is built
+      # @raise [Failure] when cargo cannot build it
+      def call(_argv)
+        RustBuild.command!("cargo", "build", chdir: File.join(RustBuild.rust_dir, "parser"))
+        0
+      end
+    end
+  end
+end