hecks 3.2.0 → 3.3.0

data/lib/hecks/quality_control/quality_control.bluebook

@@ -1,7 +1,8 @@
 # Quality control: every check writes its expectation down before it looks at the answer.
 # A bug is logged with the failing test that proves it, or it is not logged.
 
-# Tunable dials for the QA loop: values in qa/settings.yml, reasoning here.
+# Tunable dials for the QA loop: values in qa/settings.yml, what each is in the `QaDial` rows of the
+# Vocabulary chapter.
 # `require`, not `require_relative`: isolated fuzz boots load a copy of this file from a tmpdir.
 require "hecks/fuzzing/qa_settings"
 
@@ -11,111 +12,15 @@ unless defined?(QualityControlDials)
     # boots. HECKS_QA_SETTINGS_PATH lets a subprocess test read a different settings file.
     settings = Hecks::Fuzzing::QaSettings.load(ENV.fetch("HECKS_QA_SETTINGS_PATH", Hecks::Fuzzing::QaSettings::DEFAULT_PATH))
 
-    # Minimum gap in seconds between one tick's report and the next dispatch; 0 is immediately.
-    # Read by the `/loop hecks_qa` caller, not by any script.
-    CADENCE_SECONDS = settings.cadence_seconds
-
-    # Most PRs (Patch plus Improvement) `hecks quality_control patch.open` opens per calendar day; 0 is uncapped.
-    PR_CAP_PER_DAY = settings.pr_cap_per_day
-
-    # Fuzz depth by `Target.clean_streak`, in three discrete tiers, read by
-    # `SweepDepth.for_streak`. The last row (`upto: Float::INFINITY`) is the ceiling.
-    WIDENING_TIERS = settings.widening_tiers
-
-    # How many `hecks quality_control query sweep.run <target>` children `--all` keeps running at once.
-    SWEEP_MAX_PARALLEL = settings.sweep_max_parallel
-
-    # How long the `/loop hecks_qa` caller waits for a tick's report before assuming it stalled.
-    LIVENESS_FALLBACK_SECONDS = settings.liveness_fallback_seconds
+    # Each dial of qa/settings.yml as a constant named for it: `PR_CAP_PER_DAY` is `pr_cap_per_day`.
+    # What each is and takes is declared once, as its `QaDial` row in the Vocabulary chapter.
+    Hecks::Vocabulary.rows("QaDial").each do |dial|
+      const_set(dial.fetch("name").upcase, settings.public_send(dial.fetch("name")))
+    end
 
     # The identity the loop runs as. `WaivedBy` repeats this literal (invariants read literals,
     # not constants); `spec/quality_control_spec.rb` pins the two equal.
     AUTOMATED_ENGINEER = "qa_sweep"
-
-    # How `hecks quality_control patch.open` opens a PR: not a draft, queued for auto-merge, on a branch that starts
-    # with BRANCH_PREFIX.
-    DRAFT_ONLY    = settings.draft_only
-    AUTO_MERGE    = settings.auto_merge
-    BRANCH_PREFIX = settings.branch_prefix
-
-    # Fraction (0.0..1.0) of generated command steps mutated adversarially; 0 turns the layer off.
-    # Higher finds refusal-ordering splits sooner but reaches deep state less often.
-    ADVERSARIAL_FRACTION = settings.adversarial_fraction
-
-    # Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`).
-    GUIDED_GENERATION = settings.guided_generation
-
-    # Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage.
-    # Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state
-    # tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost.
-    CORPUS_SPLICE_PROBABILITY = settings.corpus_splice_probability
-
-    # How many of the least-hit verbs the next seed weights up; 0 turns the lever off.
-    FAVOR_RARE_VERBS = settings.favor_rare_verbs
-
-    # Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay
-    # idempotency, value-object JSON round trip) on the same generated sequence.
-    SELF_CONSISTENCY_CHECKS = settings.self_consistency_checks
-
-    # Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking
-    # off. `concurrency` is never shrunk: a race does not reproduce on demand.
-    SHRINK_BUDGET = settings.shrink_budget
-
-    # Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`.
-    # Zero would make yield invisible, so pick a number that lets it matter.
-    YIELD_WEIGHT_SECONDS = settings.yield_weight_seconds
-
-    # Percent of the prior yield score kept at each release, so recent findings dominate.
-    # Applied by the caller: the mutation language cannot express "decay, then add" in `Release`.
-    YIELD_DECAY_PERCENT = settings.yield_decay_percent
-
-    # Once a waiting target is this stale, `RotationPriority.pick` takes it whatever its yield
-    # score, so a quiet target cannot starve.
-    ROTATION_STALE_FLOOR_SECONDS = settings.rotation_stale_floor_seconds
-
-    # Ceiling on `--seeds` for `--persistence-parity`, which pays for real Postgres per dispatch.
-    # `hecks quality_control query sweep.run` clamps down, never up, and prints a note.
-    PERSISTENCE_PARITY_SEED_CAP = settings.persistence_parity_seed_cap
-
-    # Ceiling on `--seeds` for the concurrency mode, which needs two disposable schemas per seed.
-    CONCURRENCY_SEED_CAP = settings.concurrency_seed_cap
-
-    # The two adapters each adapter-parity mode compares, by mode name; a new pairing is a new
-    # entry. `adapter_parity_sqlite` needs no `database:`/`schema:` because sqlite has no
-    # disposable database.
-    ADAPTER_PARITY_PAIRS = settings.adapter_parity_pairs
-
-    # Which comparison modes `hecks quality_control query sweep.run` may run: the enabled ones intersected with what
-    # `TargetCapabilities.infer(path)` finds in the target. `--modes a,b,c` overrides for one run.
-    #
-    # `wasm_front` and `adapter_parity_postgres` are off because nothing runs them; the others are
-    # built and off because their I/O cost across the rotation is unmeasured. `hecks quality_control query sweep.run`
-    # refuses to start when a mode outside `TargetCapabilities::RUNNABLE_MODES` is enabled.
-    MODES = settings.modes
-
-    # How often a generated role-gated command step carries a drawn caller (`role:`/`actor_id:`);
-    # 0 turns the draw off.
-    ROLE_DRAW_PROBABILITY = settings.role_draw_probability
-
-    # Fraction of generated command steps offered as a dry run instead of a real dispatch; 0 is
-    # off. Kept low: a dry run creates no state for later steps to act on.
-    DRY_RUN_FRACTION = settings.dry_run_fraction
-
-    # How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the
-    # step.
-    GENERATED_DOMAINS_PER_TICK = settings.generated_domains_per_tick
-
-    # Whether generated domains are also compared against a compiled Rust binary built in a scratch
-    # copy.
-    GENERATED_DOMAINS_RUST = settings.generated_domains_rust
-
-    # Generated sequences run per generated domain.
-    GENERATED_DOMAIN_SEEDS = settings.generated_domain_seeds
-
-    # 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.
-    STRUCTURAL_REFUSAL_BOUNDARY = settings.structural_refusal_boundary
   end
 end
 
@@ -1726,8 +1631,7 @@ Hecks.bluebook "QualityControl" do
     attribute :branch, PatchBranch
     attribute :commit, CommitRef
     attribute :title,  PatchTitle
-    # Makes `PR_CAP_PER_DAY` countable (`OpenedSince`). `default: 0` hydrates older rows at the
-    # epoch, which the cap never counts.
+    # When the PR was opened, in epoch seconds. `default: 0` hydrates older rows at the epoch.
     attribute :opened_at, Instant
 
     value_object "Instant" do
@@ -1775,8 +1679,7 @@ Hecks.bluebook "QualityControl" do
     # the record is written by the process that made it true. `now` is that script's clock read.
     # The script asks `dry_run?` of this command before it opens anything, so the two `given`s are
     # the rules for opening a PR at all: the branch is one this practice recognises as its own, and
-    # the bug it fixes is fixed. The prefix repeats `BRANCH_PREFIX` as a literal, as `WaivedBy`
-    # repeats `AUTOMATED_ENGINEER`; `spec/quality_control_spec.rb` pins the two equal.
+    # the bug it fixes is fixed. The prefix is declared here, once.
     command "Open" do
       role "QA engineer"
       goal "Record that a fix has been opened as a pull request, the moment its number, branch and commit are already known"
@@ -1828,21 +1731,78 @@ Hecks.bluebook "QualityControl" do
       order_by :number
     end
 
-    # `hecks quality_control patch.open` compares this and `Improvement.OpenedSince` counts, from local midnight,
-    # against `PR_CAP_PER_DAY`. `gte` on a bound argument, the `Account.AtOrAbove` shape.
-    query "OpenedSince" do
-      description "Every patch opened at or after one instant, in number order — what today's count against PR_CAP_PER_DAY is read from."
-      attribute :since, Instant
-      where(:"opened_at.value" => { gte: :since })
-      order_by :number
-    end
-
     query "All" do
       description "Every patch ever opened — what a runner reads back to reconcile against GitHub's own list."
       order_by :number
     end
   end
 
+  # How many pull requests the practice has opened on one UTC day, and the rule that the day's cap
+  # is not exceeded. A rule across many records belongs to an aggregate that owns it (ADR 0081): the
+  # cap is a `given` on one record, not a count over `Patch` and `Improvement`, and a record saves
+  # atomically, so two runs cannot both take the last slot. Identified by the day, so a new day is
+  # a new record. `hecks quality_control patch.open` asks `Today` for the day's record, opens it
+  # with `Open` when there is none, and takes a slot with `Take` once a PR is open.
+  aggregate "DailyQuota" do
+    description "One UTC day's count of the pull requests the practice has opened, and the rule that the day's cap is not exceeded."
+
+    identified_by :today
+
+    # Whole days since the epoch, the fact the runtime calls `today`.
+    attribute :today, Day
+    attribute :used,  SlotsUsed
+
+    value_object "Day" do
+      attribute :value, Integer, default: 0
+      invariant("a day is not before the epoch") { !value.negative? }
+    end
+
+    value_object "SlotsUsed" do
+      attribute :value, Integer, default: 0
+      invariant("a count of pull requests is not negative") { !value.negative? }
+    end
+
+    value_object "SlotCap" do
+      attribute :value, Integer
+      invariant("a cap is not negative") { !value.negative? }
+    end
+
+    command "Open" do
+      role "QA engineer"
+      goal "Open the day the clock reads, with no slot taken yet"
+
+      attribute :today, Day
+      needs :today
+
+      sets :today
+
+      emits "QuotaOpened"
+    end
+
+    # `cap` is the dial's value, `PR_CAP_PER_DAY`; 0 is uncapped. The script asks this as a dry
+    # run before it opens a PR, so a spent day refuses before anything is opened.
+    command "Take" do
+      role "QA engineer"
+      goal "Take one of the day's slots for a pull request, refused once the day's cap is spent"
+
+      reference_to DailyQuota
+      attribute :cap, SlotCap
+
+      given("the day's cap is not spent") { cap.value == 0 || used.value < cap.value }
+
+      sets :used, increment: { value: 1 }
+
+      emits "SlotTaken"
+    end
+
+    query "Today" do
+      description "The quota of the day the clock reads: nothing before the day's first pull request."
+      attribute :today, Day
+      needs :today
+      where(:"today.value" => :today)
+    end
+  end
+
   # A PR for deliberate, non-bugfix work: a sibling of `Patch`, because `Bug` means "proven wrong"
   # and `Patch.Open` keeps its required `reference_to Bug`.
   # Born `opened`, with no investigating state: the work was decided before any code moved.
@@ -1864,7 +1824,7 @@ Hecks.bluebook "QualityControl" do
     attribute :branch, ImprovementBranch
     attribute :commit, CommitRef
     attribute :title,  ImprovementTitle
-    # See `Patch.opened_at`: the same field, for the same cap.
+    # See `Patch.opened_at`.
     attribute :opened_at, Instant
 
     value_object "Instant" do
@@ -1997,14 +1957,6 @@ Hecks.bluebook "QualityControl" do
       order_by :number
     end
 
-    # `Patch.OpenedSince`'s twin: the cap counts both kinds of PR.
-    query "OpenedSince" do
-      description "Every improvement opened at or after one instant, in number order — the other half of today's count against PR_CAP_PER_DAY."
-      attribute :since, Instant
-      where(:"opened_at.value" => { gte: :since })
-      order_by :number
-    end
-
     query "All" do
       description "Every improvement ever landed — what a runner reads back to reconcile against GitHub's own list."
       order_by :number

data/lib/hecks/runtime/interpreting.rb

@@ -1,6 +1,6 @@
 require_relative "value"
 require_relative "aggregate_lock"
-require_relative "../ports/clock"
+require_relative "needs"
 
 module Hecks
   module Runtime
@@ -14,11 +14,6 @@ module Hecks
         interpreter.singleton_class.attr_accessor :trace
       end
 
-      # What answers each outside fact a command may `needs` (ADR 0081). A fact is answered once,
-      # before any given runs, and the answer rides in the command's own arguments, so the event
-      # records it and a replay re-dispatches the recorded value rather than asking again.
-      NEED_ANSWERS = { now: ->(registry) { Ports::Clock.now(registry) } }.freeze
-
       private
 
       # Fills each outside fact the command `needs` and the caller left out. A value the caller
@@ -32,13 +27,8 @@ module Hecks
         fill_defaults(command, fill_needs(command, args))
       end
 
-      # Answers each fact the command `needs` that the caller left out.
-      def fill_needs(command, args)
-        missing = command.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
-        return args if missing.empty?
-
-        args.merge(missing.to_h { |fact| [fact, need_value(command, fact)] })
-      end
+      # Answers each fact the command `needs` that the caller left out (see `Needs`).
+      def fill_needs(command, args) = Needs.fill(command, args, registry: @registry)
 
       # Gives each argument the caller left out the default its attribute declares
       # (`attribute :runs, Count, default: 30`), so a declared default holds on every way in and
@@ -56,15 +46,6 @@ module Hecks
         args.merge(absent.to_h { |attribute| [attribute.name.to_sym, attribute.default] })
       end
 
-      # The answer to one fact, in the shape the command's argument of that name takes: a bare
-      # Integer for an Integer attribute, else the one-field value object the language declares
-      # for an instant.
-      def need_value(command, fact)
-        answer    = NEED_ANSWERS.fetch(fact).call(@registry)
-        attribute = command.attributes.find { |held| held.name.to_s == fact.to_s }
-        attribute&.type.to_s == "Integer" ? answer : { value: answer }
-      end
-
       # Logged after the step's work, so trace order is completion order.
       def step(name)
         result = yield

data/lib/hecks/runtime/needs.rb

@@ -0,0 +1,48 @@
+require_relative "../ports/clock"
+
+module Hecks
+  module Runtime
+    # Answers the outside facts a command or a query `needs` (ADR 0081). A fact is answered once,
+    # before any given or filter reads the arguments, and the answer rides in the declaration's own
+    # arguments, so an event records it and a replay re-dispatches the recorded value rather than
+    # asking again.
+    module Needs
+      # What answers each fact a declaration may need: `now` is the clock port's reading in epoch
+      # seconds, `today` the day it falls in, whole days since the epoch in UTC.
+      ANSWERS = {
+        now:   ->(registry) { Ports::Clock.now(registry) },
+        today: ->(registry) { Ports::Clock.now(registry) / 86_400 }
+      }.freeze
+
+      module_function
+
+      # Fills each outside fact the declaration `needs` and the caller left out. A value the caller
+      # supplied is kept, so a test or a back-fill can name its own time.
+      #
+      # @param declaring [#needs, #attributes] the command or query being run
+      # @param args [Hash{Symbol => Object}] the arguments the caller passed
+      # @param registry [Runtime::Registry] where the clock port is bound
+      # @return [Hash{Symbol => Object}] `args`, with each missing needed fact answered
+      # @raise [Runtime::WiringError] when the port that answers a fact is not bound exactly once
+      def fill(declaring, args, registry:)
+        missing = declaring.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
+        return args if missing.empty?
+
+        args.merge(missing.to_h { |fact| [fact, value(declaring, fact, registry)] })
+      end
+
+      # The answer to one fact, in the shape the declaration's argument of that name takes: a bare
+      # Integer for an Integer attribute, else the one-field value object the language declares.
+      #
+      # @param declaring [#attributes] the command or query
+      # @param fact [Symbol] a key of `ANSWERS`
+      # @param registry [Runtime::Registry] where the clock port is bound
+      # @return [Integer, Hash{Symbol => Integer}] the answer, shaped for its argument
+      def value(declaring, fact, registry)
+        answer    = ANSWERS.fetch(fact).call(registry)
+        attribute = declaring.attributes.find { |held| held.name.to_s == fact.to_s }
+        attribute&.type.to_s == "Integer" ? answer : { value: answer }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter.rb

@@ -5,6 +5,7 @@ require_relative "../ports/query/ordering"
 require_relative "../query_specification/field_path"
 require_relative "../query_specification/common/comparison"
 require_relative "errors"
+require_relative "needs"
 require_relative "reference_hop"
 require_relative "refusal_wording"
 require_relative "tenant_scope"
@@ -203,6 +204,7 @@ module Hecks
       def entity_rows(domain, aggregate, dotted, args)
         entity_name, query_name = Naming.split_dotted(dotted)
         entity, declared, list_attr = resolve_entity_query(aggregate, entity_name, query_name)
+        args = Needs.fill(declared, args, registry: @registry)
         declared = TenantScope.apply(declared, args)
 
         parent_key = Naming.reference_key(aggregate.hecks_name)
@@ -282,6 +284,7 @@ module Hecks
       # from field defaults and only refuses when a field has none. `null_vo_argument!`
       # refuses like any other wrong-shaped value. Command arguments are untouched.
       def normalize_args(aggregate, declared, args)
+        args = Needs.fill(declared, args, registry: @registry)
         declared.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
 

data/lib/hecks/runtime/registry/verification.rb

@@ -408,9 +408,9 @@ module Hecks
           File.expand_path(path.to_s).start_with?("#{GEM_CHAPTER_DIR}/")
         end
 
-        # Two packages can share a chapter name by coincidence (found live: a stale
-        # vendor/hecksagain fork of Governance/Identity/Deploy, still on 4 apps' load
-        # paths). Intentional accumulation (several files declaring the same chapter on
+        # Two packages can share a chapter name by coincidence (a stale vendored
+        # fork of Governance/Identity/Deploy still on an app's load paths).
+        # Intentional accumulation (several files declaring the same chapter on
         # purpose) is distinguished by package root, not file identity, and is left
         # untouched here — checked once, after every file has loaded.
         def refuse_cross_package_bluebook_merge!

data/lib/hecks/rust_build/host.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require_relative "../rust_build"
+require_relative "wasm"
+
+module Hecks
+  module RustBuild
+    # Builds the Rust host binary for a domain and stages it with the domain's module and IR, the
+    # three files a container image copies in.
+    #
+    #   Host.call(["path/to/domain", "--target=aarch64-unknown-linux-gnu", "--stage=build/host"])
+    #
+    # 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
+    # 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
+      # The host crate's binary.
+      BINARY = "bootstrap"
+
+      # The toolchain Cargo runs under, as `Wasm` builds with.
+      TOOLCHAIN = "stable"
+
+      # A Rust target triple: `<arch>-<vendor>-<os>`, with an optional `-<env>`.
+      TRIPLE = /\A[a-z0-9_]+(-[a-z0-9_.]+){2,3}\z/
+
+      module_function
+
+      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>` and
+      #   `--stage=<directory>`
+      # @return [Integer] the exit status
+      # @raise [Failure] when the toolchain, the target or a step is missing or fails
+      def call(argv)
+        domain = argv.find { |arg| !arg.start_with?("--") } or
+          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)
+
+        status = Wasm.call([domain])
+        raise Failure, "project_wasm failed for #{domain}" unless status.zero?
+
+        binary = compile(target)
+        publish(binary, File.basename(domain.chomp("/")), stage)
+        0
+      end
+
+      # @param argv [Array<String>] a tool's arguments
+      # @param name [String] a flag's name
+      # @return [String, nil] the value of `--<name>=<value>`, nil when absent
+      def flag(argv, name)
+        argv.filter_map { |arg| arg.delete_prefix("--#{name}=") if arg.start_with?("--#{name}=") }.last
+      end
+
+      # @return [String] the triple the Rust toolchain builds for by default
+      # @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
+          raise Failure, "rustup has no #{TOOLCHAIN} toolchain. Install it once with:\n\n    " \
+                         "rustup toolchain install #{TOOLCHAIN}\n\nthen re-run the build."
+      end
+
+      def require_buildable!(target)
+        raise Failure, "#{target} is not a Rust target triple (for example aarch64-unknown-linux-gnu)" unless
+          TRIPLE.match?(target)
+        if target.start_with?("wasm")
+          raise Failure, "the host is a server binary; #{target} is a wasm target. Build the module with " \
+                         "build.build_wasm, or name a native target"
+        end
+
+        require_rustup!
+        installed = query("rustup", "target", "list", "--installed", "--toolchain", TOOLCHAIN).to_s.split
+        return if installed.include?(target) || target == host_triple
+
+        raise Failure, <<~MSG
+          #{target} isn't installed for the #{TOOLCHAIN} toolchain. Install it once with:
+
+              rustup target add #{target} --toolchain #{TOOLCHAIN}
+
+          then re-run the build.
+        MSG
+      end
+
+      def require_rustup!
+        return if query("rustup", "--version")
+
+        raise Failure, "rustup isn't installed. Install the Rust toolchain from https://rustup.rs, " \
+                       "then re-run the build."
+      end
+
+      # `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)
+        host_dir = File.join(RustBuild.rust_dir, "host")
+        target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        puts "== cargo build --release --target #{target} --bin #{BINARY} (rust/host) =="
+        env = { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target))
+        RustBuild.command!("rustup", "run", TOOLCHAIN, "cargo", "build", "--release", "--target", target,
+                           "--bin", BINARY, chdir: host_dir, env: env)
+        File.join(target_dir, target, "release", BINARY)
+      rescue Failure => e
+        raise Failure, "#{e.message}#{cross_hint(target)}"
+      end
+
+      def linker_for(target)
+        variable = "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+        return {} if ENV.key?(variable) || target == host_triple
+
+        candidate = "#{target.split('-').first}-linux-gnu-gcc"
+        target.end_with?("linux-gnu") && query(candidate, "--version") ? { variable => candidate } : {}
+      end
+
+      def cross_hint(target)
+        return "" if target == host_triple
+
+        "\n#{target} differs from this machine's #{host_triple}, so linking needs a linker for it: " \
+          "put a cross compiler such as #{target.split('-').first}-linux-gnu-gcc on PATH, or set " \
+          "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+      end
+
+      def publish(binary, name, stage)
+        dist = File.join(RustBuild.rust_dir, "dist")
+        files = { binary => "#{name}-host", File.join(dist, "#{name}.wasm") => "#{name}.wasm",
+                  File.join(dist, "#{name}.ir.json") => "#{name}.ir.json" }
+        files.each_key do |path|
+          raise Failure, "the build left no #{path}" unless File.file?(path)
+        end
+        FileUtils.mkdir_p(stage)
+        files.each { |from, to| FileUtils.cp(from, File.join(stage, to)) }
+        File.chmod(0o755, File.join(stage, "#{name}-host"))
+        puts "staged in #{stage}: #{files.values.join(', ')}"
+      end
+
+      # @return [String, nil] a program's combined output, nil when it is missing or fails
+      def query(*command)
+        out, status = Open3.capture2e(*command)
+        status.success? ? out : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/kernel_input.rb

@@ -5,12 +5,14 @@ require_relative "../rust_build"
 
 module Hecks
   module RustBuild
-    # The stdin a compiled domain binary reads: the steps to run, plus the declared argument
-    # defaults the host would hand its kernel.
+    # The stdin a compiled domain binary reads: the steps to run, plus what the host would hand its
+    # kernel from the domain's IR.
     #
-    # The kernel has no IR of its own, so a command's declared defaults reach it as a top-level
-    # `"defaults"` table, `{ "Domain::Aggregate.Command" => { "attribute" => value } }`, the same
-    # one the Rust host builds from the domain's IR. A harness that sends only `"steps"` would
+    # The kernel has no IR of its own, so the facts a declaration reaches it with arrive as
+    # top-level tables the Rust host builds from the domain's IR: `"defaults"`, a command's declared
+    # argument defaults (`{ "Domain::Aggregate.Command" => { "attribute" => value } }`); `"needs"`,
+    # the outside facts a command needs; and `"query_needs"`, the same for a query (kept apart: a
+    # command and a query may share a qualified name). A harness that sends only `"steps"` would
     # leave the kernel refusing an argument Ruby fills, so every conformance caller builds its
     # input here.
     module KernelInput
@@ -18,11 +20,10 @@ module Hecks
 
       # @param domain_path [String] the domain's directory; its basename names the generated module
       # @param steps [Array<Hash>] the steps to run
-      # @return [Hash{String => Object}] the input; `"defaults"` is there only when one is declared
+      # @return [Hash{String => Object}] the input; each table is there only when it has an entry
       def build(domain_path, steps)
         input = { "steps" => steps }
-        defaults = defaults_for(domain_path)
-        input["defaults"] = defaults unless defaults.empty?
+        tables_for(domain_path).each { |name, table| input[name] = table unless table.empty? }
         input
       end
 
@@ -30,19 +31,52 @@ module Hecks
       # @return [String] the input as JSON, ready for the binary's stdin
       def json(domain_path, steps) = JSON.generate(build(domain_path, steps))
 
-      # Each command's declared defaults, read from the domain's generated IR.
+      # Each command's declared defaults, entity commands included, read from the domain's
+      # generated IR. An entity's commands sit under `Domain::Aggregate.Entity[.Entity].Command`.
       #
       # @param domain_path [String] the domain's directory
       # @return [Hash{String => Hash{String => Object}}] empty when the IR is absent or has none
-      def defaults_for(domain_path)
-        ir = generated_ir(domain_path) or return {}
+      def defaults_for(domain_path) = tables_for(domain_path).fetch("defaults")
+
+      # The three tables of one domain: `"defaults"`, `"needs"` and `"query_needs"`.
+      #
+      # @param domain_path [String] the domain's directory
+      # @return [Hash{String => Hash}] each table, empty when the IR is absent or declares none
+      def tables_for(domain_path)
+        tables = { "defaults" => {}, "needs" => {}, "query_needs" => {} }
+        ir = generated_ir(domain_path) or return tables
         domain = ir["name"].to_s
-        Array(ir["aggregates"]).each_with_object({}) do |aggregate, table|
-          Array(aggregate["commands"]).each do |command|
-            held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
-                                               .to_h { |attribute| [attribute["name"], attribute["default"]] }
-            table["#{domain}::#{aggregate['name']}.#{command['name']}"] = held unless held.empty?
-          end
+        Array(ir["aggregates"]).each { |aggregate| collect(aggregate, "#{domain}::#{aggregate['name']}", tables) }
+        tables
+      end
+
+      # Adds what `node`'s commands and queries declare, then what each entity nested in it does,
+      # under `prefix`.
+      #
+      # @param node [Hash] an aggregate or entity of the IR
+      # @param prefix [String] the verb path down to `node`
+      # @param tables [Hash] filled in place
+      # @return [void]
+      def collect(node, prefix, tables)
+        Array(node["commands"]).each do |command|
+          verb = "#{prefix}.#{command['name']}"
+          held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
+                                             .to_h { |attribute| [attribute["name"], attribute["default"]] }
+          tables["defaults"][verb] = held unless held.empty?
+          tables["needs"][verb] = needs_of(command) unless Array(command["needs"]).empty?
+        end
+        Array(node["queries"]).each do |query|
+          tables["query_needs"]["#{prefix}.#{query['name']}"] = needs_of(query) unless Array(query["needs"]).empty?
+        end
+        Array(node["entities"]).each { |entity| collect(entity, "#{prefix}.#{entity['name']}", tables) }
+      end
+
+      # @param declaration [Hash] a command or query of the IR that declares `needs`
+      # @return [Array<Hash>] each needed fact with the type of the argument of the same name
+      def needs_of(declaration)
+        Array(declaration["needs"]).map do |need|
+          argument = Array(declaration["attributes"]).find { |attribute| attribute["name"] == need["fact"] }
+          { "fact" => need["fact"], "type" => argument ? argument["type"].to_s : "" }
         end
       end