hecks 3.0.3 → 3.0.4

data/lib/hecks/tools.rb

@@ -19,7 +19,10 @@ module Hecks
       "standardize_comments"           => ["tools/comment_style", "CommentStyle"],
       "standardize_comments_rust"      => ["tools/rust_comment_style", "RustCommentStyle"],
       "regen_codegen_domains"          => ["tools/regeneration_run", "RegenerationRun"],
+      "gate"                           => ["tools/gate", "Gate"],
       "argument_gate_matrix"           => ["tools/argument_gate_matrix", "ArgumentGateMatrix"],
+      "project_ci_gates"               => ["tools/ci_gates", "CiGates"],
+      "decide_ci_gate"                 => ["tools/ci_gate_decision", "CiGateDecision"],
       "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
       "lint_deploy_recipes"            => ["tools/deploy_recipe_lint", "DeployRecipeLint"],
       "project_oidc"                   => ["tools/oidc_manifests", "OidcManifests"],

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.0.3".freeze
+  VERSION = "3.0.4".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -49,6 +49,10 @@ module Hecks
         {"name"=>"build-dependencies"}.freeze,
         {"name"=>"workspace"}.freeze
       ].freeze,
+      "CiGate" => [
+        {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"skip", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
+        {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\\.rb$|rust/project_rust_pipeline\\.rb$|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
+      ].freeze,
       "Comparison" => [
         {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,
         {"symbol"=>"<=", "compares_less_than"=>"true", "compares_equal"=>"true", "negated"=>"false"}.freeze,
@@ -123,7 +127,8 @@ module Hecks
       ].freeze,
       "NormalisationStrategy" => [
         {"name"=>"collapse_whitespace"}.freeze,
-        {"name"=>"replace"}.freeze
+        {"name"=>"replace"}.freeze,
+        {"name"=>"scale_call"}.freeze
       ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,

data/lib/hecks.rb

@@ -27,8 +27,7 @@ require_relative "hecks/projector"
 # every target registers itself as it loads, so this require is the
 # installation of them.
 require_relative "hecks/projections"
-# After `Projector` (dispatches against the `:cli` projection) and
-# `Ports::Clock` (fills a staleness rule's `now` at the door) both exist.
+# After `Projector`, which dispatches against the `:cli` projection.
 require_relative "hecks/doors/cli_door"
 require_relative "hecks/doors/cli_runner"
 require_relative "hecks/storehouse"
@@ -76,6 +75,17 @@ module Hecks
       Runtime.describe(path, shared: shared, environment: environment)
     end
 
+    # Finishes a boot from declarations `describe` already loaded, so the domain's files are read
+    # once. See `Runtime::Loader.boot_described`.
+    #
+    # @param described [Runtime::Loader::Described] what `describe` answered
+    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
+    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
+    def boot_described(described, install_doors: true, install_facade: nil)
+      Runtime.boot_described(described, install_doors: install_doors, install_facade: install_facade)
+    end
+
     # Boots a domain from an explicit list of files (a `.bluebook`, its
     # `.hecksagon`, optionally a `.world`) instead of a whole directory —
     # see `Runtime::Loader.boot_files` for why this exists beside `boot`.

data/rust/codegen/src/naming.rs

@@ -125,13 +125,15 @@ fn plain_identifier(name: &str) -> bool {
 }
 
 /// Every declared `name` in the IR, in document order. The `fields` maps under `mutations` are
-/// skipped: their keys are attribute names and their values are source text, not declarations.
+/// skipped: their keys are attribute names and their values are source text, not declarations. So is
+/// `translations`: an era edge names data paths (`attendee.first_name`, a backfill into a nested
+/// value object), which the host applies to stored rows and which are never written into Rust.
 fn declared_names<'a>(ir: &'a Json, out: &mut Vec<&'a str>) {
     match ir {
         Json::Object(pairs) => {
             for (key, value) in pairs {
                 match (key.as_str(), value) {
-                    ("fields", _) => {}
+                    ("fields" | "translations", _) => {}
                     ("name", Json::String(name)) => out.push(name),
                     _ => declared_names(value, out),
                 }
@@ -335,6 +337,15 @@ mod tests {
         assert_eq!(unsafe_name_refusal("shop", &ir), None);
     }
 
+    #[test]
+    fn ignores_data_paths_named_by_a_translation_edge() {
+        let ir = Json::parse(
+            r#"{"name":"Shop","aggregates":[{"name":"Pizza"}],"translations":[{"aggregates":[{"name":"Pizza","backfills":[{"name":"attendee.first_name"}]}]}]}"#,
+        )
+        .unwrap();
+        assert_eq!(unsafe_name_refusal("shop", &ir), None);
+    }
+
     #[test]
     fn refuses_an_aggregate_name_that_is_not_a_plain_identifier() {
         assert!(reserved_name_refusal("shop", "shop", &["My-App"]).is_some());

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.0.3
+3.0.4

data/rust/host/src/dispatch.rs

@@ -14,6 +14,61 @@ pub struct Outcome {
     pub accepted: bool,
 }
 
+/// Who a command is dispatched for: the role they state and, when the host knows who they are, the
+/// actor Governance holds assignments for. Both absent is an unidentified caller.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct Caller<'a> {
+    pub role: Option<&'a str>,
+    pub actor_id: Option<&'a str>,
+}
+
+/// The role an unidentified caller is dispatched under when roles are enforced: no command declares
+/// it, so a command that declares any role refuses it.
+pub const ANONYMOUS_ROLE: &str = "Anonymous";
+
+/// What the host does about the role a command declares (`HECKS_ROLE_ENFORCEMENT`).
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Enforcement {
+    /// A caller with no role is unchecked, as before.
+    Off,
+    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`.
+    Shadow,
+    /// An unidentified or unassigned caller is refused.
+    Enforce,
+}
+
+impl Enforcement {
+    /// Reads `off` (the default), `shadow` or `enforce`; anything else is `Off`.
+    pub fn parse(value: Option<&str>) -> Self {
+        match value.map(|v| v.trim().to_ascii_lowercase()).as_deref() {
+            Some("shadow") => Self::Shadow,
+            Some("enforce") => Self::Enforce,
+            _ => Self::Off,
+        }
+    }
+
+    pub fn from_env() -> Self {
+        static MODE: std::sync::OnceLock<Enforcement> = std::sync::OnceLock::new();
+        *MODE.get_or_init(|| Self::parse(std::env::var("HECKS_ROLE_ENFORCEMENT").ok().as_deref()))
+    }
+
+    /// The caller the kernel is asked to check: an unidentified caller becomes the anonymous role
+    /// unless enforcement is off.
+    pub fn effective<'a>(self, caller: Caller<'a>) -> Caller<'a> {
+        if self != Self::Off && caller.role.is_none() && caller.actor_id.is_none() {
+            return Caller { role: Some(ANONYMOUS_ROLE), actor_id: None };
+        }
+        caller
+    }
+}
+
+/// Whether the kernel refused the command for the caller's role.
+fn refused_for_role(result: &serde_json::Value) -> bool {
+    result.get("refusals").and_then(|r| r.as_array()).is_some_and(|all| {
+        all.iter().any(|r| r.get("kind").and_then(|k| k.as_str()) == Some("Unauthorized"))
+    })
+}
+
 // Distinguishes a module refusal from a kernel failure to run at all.
 #[derive(Debug, PartialEq)]
 enum KernelAnswer {
@@ -80,6 +135,21 @@ pub async fn handle_routed(
     handle(client, wasm_path, verb, routed_invocation(to, facts)?, role, config, invoker).await
 }
 
+/// `handle_routed` for a caller the host can name.
+#[allow(clippy::too_many_arguments)]
+pub async fn handle_routed_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    to: serde_json::Value,
+    facts: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, routed_invocation(to, facts)?, caller, config, invoker).await
+}
+
 // Facts-only counterpart to `handle_routed`.
 #[allow(clippy::too_many_arguments)]
 pub async fn handle_facts(
@@ -94,6 +164,20 @@ pub async fn handle_facts(
     handle(client, wasm_path, verb, facts_invocation(facts)?, role, config, invoker).await
 }
 
+/// `handle_facts` for a caller the host can name.
+#[allow(clippy::too_many_arguments)]
+pub async fn handle_facts_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    facts: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, facts_invocation(facts)?, caller, config, invoker).await
+}
+
 // A Mutex, not a bare Arc<Client>: `handle` needs `Client::transaction`,
 // which takes `&mut Client`. Locking also means concurrent callers on
 // this connection can't interleave statements.
@@ -114,6 +198,57 @@ pub async fn handle(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
+}
+
+/// Dispatches for a caller, applying `HECKS_ROLE_ENFORCEMENT`: unidentified callers are refused (or,
+/// in shadow, logged as would-be refusals and let through).
+pub async fn handle_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_with(Enforcement::from_env(), client, wasm_path, verb, args, caller, config, invoker).await
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn handle_with(
+    mode: Enforcement,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    let checked = mode.effective(caller);
+    let outcome = run(client, wasm_path, verb, args.clone(), checked, config, invoker).await?;
+    if mode == Enforcement::Shadow && !outcome.accepted && refused_for_role(&outcome.result) {
+        crate::log::error("would_refuse_role", serde_json::json!({
+            "verb": verb, "role": checked.role, "actor_id": checked.actor_id,
+            "refusals": outcome.result.get("refusals"),
+        }));
+        return run(client, wasm_path, verb, args, Caller::default(), config, invoker).await;
+    }
+    Ok(outcome)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn run(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    let role = caller.role;
     let mut guard = client.lock().await;
     let txn = guard.transaction().await?;
 
@@ -147,10 +282,19 @@ pub async fn handle(
     // carries whatever role it was dispatched with. Built as a mutable
     // step, not inlined into the `json!` literal, so a roleless call
     // still omits the `"role"` key entirely rather than sending null.
+    // A fact the command `needs` is answered here, before the kernel's gates read the arguments and
+    // before the step is journaled, so a replay re-dispatches the recorded answer (ADR 0081).
+    let mut args = args;
+    if let Some(domain_ir) = crate::ir::ir() {
+        crate::needs::fill_needs(domain_ir, verb, &mut args, &crate::needs::ProcessClock);
+    }
     let mut step = serde_json::json!({ "verb": verb, "args": args.clone() });
     if let Some(role) = role {
         step["role"] = serde_json::Value::String(role.to_string());
     }
+    if let Some(actor_id) = caller.actor_id {
+        step["actor_id"] = serde_json::Value::String(actor_id.to_string());
+    }
     // Stamped only on this live step; replayed history already carries
     // its own real timestamp, and re-stamping today's time onto a
     // replay would be wrong, not just redundant.
@@ -179,7 +323,15 @@ pub async fn handle(
         }))
         .collect::<Vec<_>>());
 
-    let input = serde_json::json!({ "seed": seed, "steps": steps, "sagas": sagas_seed }).to_string();
+    let mut input = serde_json::json!({ "seed": seed, "steps": steps, "sagas": sagas_seed });
+    // Lets the kernel answer a reaction's command that needs a fact the same way (ADR 0081).
+    if let Some(domain_ir) = crate::ir::ir() {
+        let table = crate::needs::table(domain_ir);
+        if table.as_object().is_some_and(|t| !t.is_empty()) {
+            input["needs"] = table;
+        }
+    }
+    let input = input.to_string();
     // `wasm_runner::run` is sync, and wasmtime-wasi's sync bridge spins up
     // its own tokio runtime internally — fatal on a thread already
     // driving one. `spawn_blocking` moves it off this async runtime.
@@ -1169,6 +1321,60 @@ pub(crate) mod tests {
         assert_eq!(steps.len(), 1, "only the correctly-authorized registration should be persisted");
     }
 
+    #[test]
+    fn enforcement_reads_off_shadow_and_enforce_and_treats_anything_else_as_off() {
+        assert_eq!(Enforcement::parse(None), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("")), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("nonsense")), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("Shadow")), Enforcement::Shadow);
+        assert_eq!(Enforcement::parse(Some(" enforce ")), Enforcement::Enforce);
+    }
+
+    #[test]
+    fn only_an_unidentified_caller_becomes_anonymous_and_only_when_roles_are_checked() {
+        let nobody = Caller::default();
+        assert_eq!(Enforcement::Off.effective(nobody), nobody);
+        for mode in [Enforcement::Shadow, Enforcement::Enforce] {
+            assert_eq!(mode.effective(nobody).role, Some(ANONYMOUS_ROLE));
+            let stated = Caller { role: Some("Teller"), actor_id: None };
+            assert_eq!(mode.effective(stated), stated, "a stated role is kept");
+            let identified = Caller { role: None, actor_id: Some("u1") };
+            assert_eq!(mode.effective(identified), identified, "an identified caller is kept");
+        }
+    }
+
+    // The unidentified caller is the case the host never refused: no role at all.
+    #[tokio::test]
+    async fn an_unidentified_caller_is_refused_when_enforced_and_let_through_when_off_or_shadowed() {
+        let client = scratch_db("rust_host_dispatch_test_enforce").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                handle_with(mode, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+
+        let off = go(Enforcement::Off, "CUST-0021").await;
+        assert!(off.accepted, "off keeps the old behaviour: {:?}", off.result);
+
+        let enforced = go(Enforcement::Enforce, "CUST-0022").await;
+        assert!(!enforced.accepted, "an unidentified caller must be refused: {:?}", enforced.result);
+        assert!(refused_for_role(&enforced.result), "{:?}", enforced.result);
+        let error = enforced.result["refusals"][0]["error"].as_str().unwrap();
+        assert!(error.contains("Branch clerk") && error.contains(ANONYMOUS_ROLE), "{error}");
+
+        let shadowed = go(Enforcement::Shadow, "CUST-0023").await;
+        assert!(shadowed.accepted, "shadow lets the command through: {:?}", shadowed.result);
+
+        let steps = journal::load_steps(&*client.lock().await).await.unwrap();
+        assert_eq!(steps.len(), 2, "the enforced refusal was not persisted; off and shadow were");
+    }
+
     #[tokio::test]
     async fn a_mid_transaction_failure_rolls_back_any_saga_state_already_written() {
         // Deliberately doesn't provision "Transfer": its mutation fails

data/rust/host/src/main.rs

@@ -13,6 +13,7 @@ mod journal;
 mod lambda_client;
 mod log;
 mod mint;
+mod needs;
 mod payments;
 mod presentation;
 mod presentation_write;

data/rust/host/src/needs.rs

@@ -0,0 +1,243 @@
+// Facts a command `needs` (ADR 0081): the host answers them before the kernel reads the arguments,
+// the way the Ruby interpreter does in `decode_arguments`. The command's own IR carries
+// `"needs": [{"fact": "now"}]`; a needed fact the caller left out is filled with the clock's
+// answer, a supplied one is kept. The answer is written into the arguments before they are
+// journaled, so a replay re-dispatches the recorded value rather than asking the clock again.
+
+use serde_json::{json, Value};
+use std::sync::atomic::{AtomicI64, Ordering};
+
+/// What answers the `now` fact: epoch seconds, UTC.
+pub trait Clock {
+    fn now_secs(&self) -> i64;
+}
+
+/// The wall clock.
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_secs(&self) -> i64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs() as i64)
+            .unwrap_or_default()
+    }
+}
+
+/// A clock that always answers one moment, for tests.
+#[cfg(test)]
+pub struct FixedClock(pub i64);
+
+#[cfg(test)]
+impl Clock for FixedClock {
+    fn now_secs(&self) -> i64 {
+        self.0
+    }
+}
+
+const UNSET: i64 = i64::MIN;
+static OVERRIDE: AtomicI64 = AtomicI64::new(UNSET);
+
+/// Makes the process clock answer `secs` until `clear_fixed_clock`; for tests only.
+#[cfg(test)]
+pub fn set_fixed_clock(secs: i64) {
+    OVERRIDE.store(secs, Ordering::SeqCst);
+}
+
+#[cfg(test)]
+pub fn clear_fixed_clock() {
+    OVERRIDE.store(UNSET, Ordering::SeqCst);
+}
+
+/// The process clock the dispatcher uses: the wall clock unless a test has fixed it.
+pub struct ProcessClock;
+
+impl Clock for ProcessClock {
+    fn now_secs(&self) -> i64 {
+        match OVERRIDE.load(Ordering::SeqCst) {
+            UNSET => SystemClock.now_secs(),
+            fixed => fixed,
+        }
+    }
+}
+
+/// The command's declared needs, each with the type of the attribute of the same name.
+fn declared_needs<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, Option<&'a str>)> {
+    let Some((qualified_aggregate, command_name)) = verb.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let named = |value: &Value, name: &str| value.get("name").and_then(Value::as_str) == Some(name);
+    let list = |value: &'a Value, key: &str| -> Vec<&'a Value> {
+        value.get(key).and_then(Value::as_array).map(|a| a.iter().collect()).unwrap_or_default()
+    };
+    let mut needs = Vec::new();
+    for command in list(domain_ir, "aggregates")
+        .into_iter()
+        .filter(|a| named(a, aggregate))
+        .flat_map(|a| list(a, "commands"))
+        .filter(|c| named(c, command_name))
+    {
+        let attributes = list(command, "attributes");
+        for fact in list(command, "needs").into_iter().filter_map(|n| n.get("fact").and_then(Value::as_str)) {
+            let attribute_type =
+                attributes.iter().find(|a| named(a, fact)).and_then(|a| a.get("type")).and_then(Value::as_str);
+            needs.push((fact, attribute_type));
+        }
+    }
+    needs
+}
+
+/// Every command's needs as the kernel's input `"needs"` reads them: `{ verb: [{fact, type}] }`.
+/// The kernel answers a reaction's command from this (it has no IR of its own), and the same
+/// step's `occurred_at` keeps the answer the same on replay.
+pub fn table(domain_ir: &Value) -> Value {
+    let domain = domain_ir.get("name").and_then(Value::as_str).unwrap_or_default();
+    let mut verbs = serde_json::Map::new();
+    let aggregates = domain_ir.get("aggregates").and_then(Value::as_array).into_iter().flatten();
+    for aggregate in aggregates {
+        let aggregate_name = aggregate.get("name").and_then(Value::as_str).unwrap_or_default();
+        for command in aggregate.get("commands").and_then(Value::as_array).into_iter().flatten() {
+            let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+            let verb = format!("{domain}::{aggregate_name}.{command_name}");
+            let needs: Vec<Value> = declared_needs(domain_ir, &verb)
+                .into_iter()
+                .map(|(fact, attribute_type)| json!({"fact": fact, "type": attribute_type.unwrap_or("")}))
+                .collect();
+            if !needs.is_empty() {
+                verbs.insert(verb, Value::Array(needs));
+            }
+        }
+    }
+    Value::Object(verbs)
+}
+
+/// The facts of a command invocation: the `with` object when the call carries one, else the
+/// flat object itself (the kernel's `CommandInvocation` reads both shapes).
+fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
+    if args.get("with").is_some_and(Value::is_object) {
+        return args.get_mut("with").and_then(Value::as_object_mut);
+    }
+    args.as_object_mut()
+}
+
+fn answer(fact: &str, attribute_type: Option<&str>, clock: &dyn Clock) -> Option<Value> {
+    match fact {
+        "now" => {
+            let secs = clock.now_secs();
+            Some(if attribute_type == Some("Integer") { json!(secs) } else { json!({ "value": secs }) })
+        }
+        _ => None,
+    }
+}
+
+/// Fills each fact `verb` needs that `args` leaves out, before any gate reads the arguments. A key
+/// the caller supplied (even a null) is kept; a command that needs nothing is untouched.
+pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn Clock) {
+    let needs = declared_needs(domain_ir, verb);
+    if needs.is_empty() {
+        return;
+    }
+    let Some(facts) = facts_mut(args) else { return };
+    for (fact, attribute_type) in needs {
+        if facts.contains_key(fact) {
+            continue;
+        }
+        if let Some(value) = answer(fact, attribute_type, clock) {
+            facts.insert(fact.to_string(), value);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const LEASE_IR: &str = include_str!("../../src/generated/lease_clock/ir.json");
+
+    fn lease_ir() -> Value {
+        serde_json::from_str(LEASE_IR).unwrap()
+    }
+
+    // A command whose `now` is an Integer attribute, as QualityControl's are.
+    fn integer_ir() -> Value {
+        json!({"name": "Qc", "aggregates": [{"name": "Check", "commands": [
+            {"name": "Run", "attributes": [{"name": "now", "type": "Integer"}], "needs": [{"fact": "now"}]},
+            {"name": "Plain", "attributes": [{"name": "now", "type": "Integer"}], "needs": []}
+        ]}]})
+    }
+
+    fn first_needing(ir: &Value) -> String {
+        ir["aggregates"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .flat_map(|a| {
+                a["commands"].as_array().unwrap().iter().filter(|c| !c["needs"].as_array().unwrap().is_empty()).map(
+                    move |c| format!("{}::{}.{}", ir["name"].as_str().unwrap(), a["name"].as_str().unwrap(), c["name"].as_str().unwrap()),
+                )
+            })
+            .next()
+            .expect("the lease_clock domain declares a command that needs :now")
+    }
+
+    #[test]
+    fn a_needed_fact_the_caller_left_out_is_filled_from_the_clock() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"holder": "a"}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(1_700_000_000));
+        assert_eq!(args["with"]["now"], json!({"value": 1_700_000_000}));
+        assert_eq!(args["with"]["holder"], "a");
+    }
+
+    #[test]
+    fn a_flat_invocation_is_filled_at_its_top_level() {
+        let ir = lease_ir();
+        let mut args = json!({"holder": "a"});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(5));
+        assert_eq!(args["now"], json!({"value": 5}));
+    }
+
+    #[test]
+    fn a_value_the_caller_supplied_is_kept() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"now": {"value": 42}}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(7));
+        assert_eq!(args["with"]["now"], json!({"value": 42}));
+    }
+
+    #[test]
+    fn a_command_with_no_needs_is_untouched() {
+        let ir = integer_ir();
+        let mut args = json!({"with": {"x": 1}});
+        fill_needs(&ir, "Qc::Check.Plain", &mut args, &FixedClock(7));
+        assert_eq!(args, json!({"with": {"x": 1}}));
+        let mut unknown = json!({"with": {}});
+        fill_needs(&ir, "Qc::Check.Nope", &mut unknown, &FixedClock(7));
+        assert_eq!(unknown, json!({"with": {}}));
+    }
+
+    #[test]
+    fn an_integer_attribute_gets_a_bare_integer_and_an_instant_a_value_object() {
+        let mut integer = json!({"with": {}});
+        fill_needs(&integer_ir(), "Qc::Check.Run", &mut integer, &FixedClock(9));
+        assert_eq!(integer["with"]["now"], json!(9));
+        let ir = lease_ir();
+        let mut instant = json!({"with": {}});
+        fill_needs(&ir, &first_needing(&ir), &mut instant, &FixedClock(9));
+        assert_eq!(instant["with"]["now"], json!({"value": 9}));
+    }
+
+    #[test]
+    fn the_kernel_table_lists_only_commands_that_need_something() {
+        let table = table(&integer_ir());
+        assert_eq!(table, json!({"Qc::Check.Run": [{"fact": "now", "type": "Integer"}]}));
+        assert_eq!(super::table(&json!({"name": "D"})), json!({}));
+    }
+
+    #[test]
+    fn the_process_clock_answers_a_fixed_moment_and_otherwise_the_wall_clock() {
+        set_fixed_clock(123);
+        assert_eq!(ProcessClock.now_secs(), 123);
+        clear_fixed_clock();
+        assert!(ProcessClock.now_secs() > 1_700_000_000);
+    }
+}