hecks 3.2.1 → 3.3.0

data/rust/codegen/src/optional_pass.rs

@@ -0,0 +1,226 @@
+//! Marks value-object and entity fields `optional` when an `append` mutation binds them to an
+//! optional command argument, so the generated struct field is an `Option`.
+//!
+//! Resolves the appended element as `Hecks::RustBuild::AppendOptionals` does in Ruby: a local
+//! entity wins over any value object of the same name, a local value object over a domain-wide one,
+//! and an `append` into another aggregate's value object marks that value object.
+
+use std::collections::HashMap;
+
+use crate::json::Json;
+
+/// Where an appended element lives: its aggregate's index, then its own index in that aggregate.
+#[derive(Clone, Copy)]
+enum Element {
+    ValueObject(usize, usize),
+    Entity(usize, usize),
+}
+
+struct Mark {
+    element: Element,
+    field: String,
+}
+
+pub fn run(ir: &mut Json) {
+    let marks = collect_marks(ir);
+    apply_marks(ir, &marks);
+}
+
+fn list<'a>(node: &'a Json, key: &str) -> &'a [Json] {
+    node.get(key).map(Json::each).unwrap_or(&[])
+}
+
+fn name_of(node: &Json) -> Option<&str> {
+    node.get("name").and_then(Json::as_str)
+}
+
+// Every value object in the domain by name; the last one declared wins, as a Ruby `to_h` does.
+fn domain_wide_value_objects(aggregates: &[Json]) -> HashMap<&str, (usize, usize)> {
+    let mut by_name = HashMap::new();
+    for (a, aggregate) in aggregates.iter().enumerate() {
+        for (v, value_object) in list(aggregate, "value_objects").iter().enumerate() {
+            if let Some(name) = name_of(value_object) {
+                by_name.insert(name, (a, v));
+            }
+        }
+    }
+    by_name
+}
+
+fn find_element(aggregates: &[Json], a: usize, domain_wide: &HashMap<&str, (usize, usize)>, type_name: &str) -> Option<Element> {
+    let aggregate = &aggregates[a];
+    if let Some(e) = list(aggregate, "entities").iter().position(|entity| name_of(entity) == Some(type_name)) {
+        return Some(Element::Entity(a, e));
+    }
+    if let Some(v) = list(aggregate, "value_objects").iter().rposition(|value_object| name_of(value_object) == Some(type_name)) {
+        return Some(Element::ValueObject(a, v));
+    }
+    domain_wide.get(type_name).map(|&(owner, v)| Element::ValueObject(owner, v))
+}
+
+// Read first, write after: the commands are read while the elements they mark are mutated.
+fn collect_marks(ir: &Json) -> Vec<Mark> {
+    let aggregates = list(ir, "aggregates");
+    let domain_wide = domain_wide_value_objects(aggregates);
+    let mut marks = Vec::new();
+
+    for (a, aggregate) in aggregates.iter().enumerate() {
+        for attribute in list(aggregate, "attributes") {
+            let (Some(attr_name), Some(type_name)) = (name_of(attribute), attribute.get("type").and_then(Json::as_str)) else { continue };
+            let Some(element) = find_element(aggregates, a, &domain_wide, type_name) else { continue };
+
+            for field in collect_fields_to_mark(aggregate, attr_name) {
+                marks.push(Mark { element, field });
+            }
+        }
+    }
+    marks
+}
+
+fn collect_fields_to_mark(aggregate: &Json, target_attr_name: &str) -> Vec<String> {
+    let mut out = Vec::new();
+
+    for command in list(aggregate, "commands") {
+        let command_attrs = list(command, "attributes");
+
+        for mutation in list(command, "mutations") {
+            let op = mutation.get("op").and_then(Json::as_str).unwrap_or("");
+            let target = mutation.get("target").and_then(Json::as_str).unwrap_or("");
+            if op != "append" || target != target_attr_name {
+                continue;
+            }
+
+            let Some(fields) = mutation.get("fields").and_then(Json::as_object) else { continue };
+            for (field_name, source) in fields {
+                // Only a Symbol (an argument name) renders with a leading `:` in `Literal.render`.
+                let Some(source_text) = source.as_str() else { continue };
+                let Some(arg_name) = source_text.strip_prefix(':') else { continue };
+
+                let source_is_optional = command_attrs
+                    .iter()
+                    .any(|a| name_of(a) == Some(arg_name) && a.get("optional").map(Json::as_bool).unwrap_or(false));
+                if source_is_optional {
+                    out.push(field_name.clone());
+                }
+            }
+        }
+    }
+
+    out
+}
+
+fn apply_marks(ir: &mut Json, marks: &[Mark]) {
+    let Some(aggregates) = ir.get_mut("aggregates").and_then(Json::as_array_mut) else { return };
+
+    for mark in marks {
+        let (a, key, index) = match mark.element {
+            Element::ValueObject(a, v) => (a, "value_objects", v),
+            Element::Entity(a, e) => (a, "entities", e),
+        };
+        let element = aggregates.get_mut(a).and_then(|aggregate| aggregate.get_mut(key)).and_then(Json::as_array_mut).and_then(|elements| elements.get_mut(index));
+        let Some(attrs) = element.and_then(|element| element.get_mut("attributes")).and_then(Json::as_array_mut) else { continue };
+
+        if let Some(field_attr) = attrs.iter_mut().find(|a| name_of(a) == Some(mark.field.as_str())) {
+            field_attr.set_bool("optional", true);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn aggregate_with(entities: &str, value_objects: &str, attribute_type: &str) -> String {
+        format!(
+            r#"{{
+  "attributes": [
+    {{"name": "ledger", "type": "{attribute_type}", "list": true, "default": null, "optional": false, "pattern": null, "admits": null}}
+  ],
+  "value_objects": [{value_objects}],
+  "entities": [{entities}],
+  "commands": [
+    {{
+      "name": "Credit",
+      "attributes": [
+        {{"name": "amount", "type": "PositiveMoney", "list": false, "default": null, "optional": true, "pattern": null, "admits": null}}
+      ],
+      "mutations": [
+        {{"target": "ledger", "op": "append", "fields": {{"amount": ":amount", "direction": "{{value: \"credit\"}}"}}}}
+      ]
+    }}
+  ]
+}}"#
+        )
+    }
+
+    fn element(amount_optional: bool) -> String {
+        format!(
+            r#"{{"name": "LedgerEntry", "attributes": [
+        {{"name": "amount", "type": "Money", "list": false, "default": null, "optional": {amount_optional}, "pattern": null, "admits": null}},
+        {{"name": "direction", "type": "Direction", "list": false, "default": null, "optional": false, "pattern": null, "admits": null}}
+      ]}}"#
+        )
+    }
+
+    fn domain(aggregates: &[String]) -> Json {
+        Json::parse(&format!(r#"{{"aggregates": [{}]}}"#, aggregates.join(","))).expect("fixture parses")
+    }
+
+    fn amount_optional(ir: &Json, aggregate: usize, key: &str) -> bool {
+        let element = &list(&list(ir, "aggregates")[aggregate], key)[0];
+        let amount = list(element, "attributes").iter().find(|a| name_of(a) == Some("amount")).unwrap();
+        amount.get("optional").unwrap().as_bool()
+    }
+
+    // The input and expectation `spec/rust_build_generation_helpers_spec.rb` holds the Ruby pass to,
+    // recorded from it. Read at test time, not compiled in: an installed gem has no `spec/`.
+    #[test]
+    fn marks_what_the_ruby_pass_marks_on_the_shared_fixture() {
+        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../spec/fixtures/append_optionals");
+        let read = |name: &str| Json::parse(&std::fs::read_to_string(dir.join(name)).expect("reads the fixture")).expect("parses");
+
+        let mut ir = read("input.json");
+        run(&mut ir);
+
+        assert_eq!(ir, read("expected.json"));
+    }
+
+    // Banking's `Account.Credit` shape: entity list `ledger`, one `append` binding `amount` from
+    // an optional argument and `direction` from a literal Hash.
+    #[test]
+    fn marks_the_argument_sourced_field_optional() {
+        let mut ir = domain(&[aggregate_with(&element(false), "", "LedgerEntry")]);
+        run(&mut ir);
+
+        assert!(amount_optional(&ir, 0, "entities"));
+    }
+
+    #[test]
+    fn marks_a_value_object_another_aggregate_declares() {
+        let owner = r#"{"attributes": [], "value_objects": [LEDGER], "entities": [], "commands": []}"#.replace("LEDGER", &element(false));
+        let appender = aggregate_with("", "", "LedgerEntry");
+        let mut ir = domain(&[appender, owner]);
+        run(&mut ir);
+
+        assert!(amount_optional(&ir, 1, "value_objects"), "the value object lives in the second aggregate");
+    }
+
+    #[test]
+    fn prefers_a_local_entity_over_a_value_object_of_the_same_name() {
+        let local = aggregate_with(&element(false), "", "LedgerEntry");
+        let owner = r#"{"attributes": [], "value_objects": [LEDGER], "entities": [], "commands": []}"#.replace("LEDGER", &element(false));
+        let mut ir = domain(&[local, owner]);
+        run(&mut ir);
+
+        assert!(amount_optional(&ir, 0, "entities"), "the local entity is the one marked");
+        assert!(!amount_optional(&ir, 1, "value_objects"), "the domain-wide value object is left alone");
+    }
+
+    #[test]
+    fn leaves_a_field_alone_when_its_argument_is_required() {
+        let mut ir = domain(&[aggregate_with(&element(false), "", "LedgerEntry").replace("\"optional\": true", "\"optional\": false")]);
+        run(&mut ir);
+
+        assert!(!amount_optional(&ir, 0, "entities"));
+    }
+}

data/rust/{build → codegen}/src/sidecars.rs

@@ -1,4 +1,6 @@
-//! Writes each chapter's `ir.json` and `metadata.rs` sidecars.
+//! Writes each chapter's `ir.json` and `metadata.rs` sidecars, from the IR as generated (marked).
+
+use crate::json::{self, Json};
 
 /// Renders `text` as a Rust string literal. Not Ruby's `String#inspect`, whose `\#{` and bare
 /// `\uXXXX` escapes are not valid Rust.
@@ -22,22 +24,24 @@ pub fn rust_string_literal(text: &str) -> String {
     out
 }
 
-pub fn write(mod_dir: &std::path::Path, ir_text: &str, source_label: &str) -> Result<(std::path::PathBuf, std::path::PathBuf), String> {
+/// `ir.json` is what `rust/host` reads at runtime, and `metadata.rs` embeds the same text.
+pub fn write(mod_dir: &std::path::Path, ir: &Json, source_label: &str) -> Result<(std::path::PathBuf, std::path::PathBuf), String> {
     std::fs::create_dir_all(mod_dir).map_err(|e| format!("creating {}: {e}", mod_dir.display()))?;
 
+    let ir_text = json::write(ir);
     let ir_json_path = mod_dir.join("ir.json");
-    std::fs::write(&ir_json_path, ir_text).map_err(|e| format!("writing {}: {e}", ir_json_path.display()))?;
+    std::fs::write(&ir_json_path, &ir_text).map_err(|e| format!("writing {}: {e}", ir_json_path.display()))?;
 
     let metadata_path = mod_dir.join("metadata.rs");
     let mut contents = String::new();
-    // Attribution text matches both Ruby pipelines so generated trees diff clean.
+    // The header every generated `metadata.rs` carries; `regenerate_corpus --check` diffs it.
     contents.push_str("// GENERATED by hecks project_rust — ");
     contents.push_str(source_label);
     contents.push_str("'s own canonical IR,\n");
     contents.push_str("// embedded for runtime self-description. Not read by any dispatch\n");
     contents.push_str("// function in this module — introspection only.\n");
     contents.push_str("pub const IR_JSON: &str = ");
-    contents.push_str(&rust_string_literal(ir_text));
+    contents.push_str(&rust_string_literal(&ir_text));
     contents.push_str(";\n");
     std::fs::write(&metadata_path, contents).map_err(|e| format!("writing {}: {e}", metadata_path.display()))?;
 

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.2.1
+3.3.0

data/rust/host/src/api.rs

@@ -823,7 +823,7 @@ mod tests {
     }
 
     // app.rb: `get "/api/me" { json(session[:member] || {}) }`, where
-    // session[:member] is embryonaut_access_control.rb's own
+    // session[:member] is the access-control module's own
     // `{ "email" =>, "name" =>, "identity_id" =>, "role" => }`.
     #[test]
     fn me_is_the_ruby_engines_own_member_hash() {

data/rust/host/src/dispatch.rs

@@ -611,6 +611,11 @@ pub async fn query(
     question: &str,
     args: serde_json::Value,
 ) -> anyhow::Result<serde_json::Value> {
+    // A fact the query `needs` is answered before the kernel checks its arguments (ADR 0081).
+    let mut args = args;
+    if let Some(domain_ir) = crate::ir::ir() {
+        crate::needs::fill_query_needs(domain_ir, question, &mut args, &crate::needs::ProcessClock);
+    }
     let state = read(client, wasm_path).await?;
     let seed = state.get("instances").cloned().unwrap_or_else(|| serde_json::json!({}));
     let input = serde_json::json!({ "seed": seed, "steps": [{ "query": question, "args": args }] }).to_string();

data/rust/host/src/needs.rs

@@ -186,9 +186,11 @@ fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
 
 fn answer(fact: &str, attribute_type: Option<&str>, clock: &dyn Clock) -> Option<Value> {
     match fact {
-        "now" => {
+        // `now` is epoch seconds; `today` the day those fall in, whole days since the epoch (UTC).
+        "now" | "today" => {
             let secs = clock.now_secs();
-            Some(if attribute_type == Some("Integer") { json!(secs) } else { json!({ "value": secs }) })
+            let answer = if fact == "today" { secs.div_euclid(86_400) } else { secs };
+            Some(if attribute_type == Some("Integer") { json!(answer) } else { json!({ "value": answer }) })
         }
         _ => None,
     }
@@ -212,6 +214,49 @@ pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn C
     }
 }
 
+/// The facts the query `question` (`Domain::Aggregate.Query`) needs, each with the type of the
+/// argument of the same name. An entity's query is not looked up here.
+fn declared_query_needs<'a>(domain_ir: &'a Value, question: &str) -> Vec<(&'a str, Option<&'a str>)> {
+    let Some((qualified_aggregate, query_name)) = question.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let Some(query) = list(domain_ir, "aggregates")
+        .iter()
+        .find(|a| named(a, aggregate))
+        .and_then(|a| list(a, "queries").iter().find(|q| named(q, query_name)))
+    else {
+        return Vec::new();
+    };
+    let attributes = list(query, "attributes");
+    list(query, "needs")
+        .iter()
+        .filter_map(|n| n.get("fact").and_then(Value::as_str))
+        .map(|fact| {
+            let attribute_type =
+                attributes.iter().find(|a| named(a, fact)).and_then(|a| a.get("type")).and_then(Value::as_str);
+            (fact, attribute_type)
+        })
+        .collect()
+}
+
+/// Fills each fact the query `question` needs that `args` leaves out, before the kernel checks the
+/// arguments. A key the caller supplied (even a null) is kept; a query that needs nothing, or whose
+/// arguments are not an object, is untouched.
+pub fn fill_query_needs(domain_ir: &Value, question: &str, args: &mut Value, clock: &dyn Clock) {
+    let needs = declared_query_needs(domain_ir, question);
+    if needs.is_empty() {
+        return;
+    }
+    let Some(facts) = args.as_object_mut() 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);
+        }
+    }
+}
+
 /// Gives each argument `verb` declares a default for, and `args` leaves out, that default, after
 /// `fill_needs` and before any gate reads the arguments. A key the caller supplied (even a null)
 /// is kept, as is a fact `fill_needs` already answered.
@@ -408,6 +453,58 @@ mod tests {
         assert_eq!(args, json!({"number": 1}));
     }
 
+    // An aggregate with a query that needs `now` and one that needs `today`.
+    fn query_ir() -> Value {
+        json!({"name": "Lease", "aggregates": [{"name": "Slot", "commands": [], "queries": [
+            {"name": "Expired", "attributes": [{"name": "now", "type": "LeaseInstant"}],
+             "needs": [{"fact": "now"}]},
+            {"name": "IssuedToday", "attributes": [{"name": "today", "type": "Integer"}],
+             "needs": [{"fact": "today"}]},
+            {"name": "Plain", "attributes": [{"name": "now", "type": "LeaseInstant"}]}
+        ]}]})
+    }
+
+    #[test]
+    fn a_needed_query_fact_the_caller_left_out_is_filled_from_the_clock() {
+        let mut args = json!({});
+        fill_query_needs(&query_ir(), "Lease::Slot.Expired", &mut args, &FixedClock(1_700_000_000));
+        assert_eq!(args["now"], json!({"value": 1_700_000_000}));
+    }
+
+    #[test]
+    fn a_query_value_the_caller_supplied_is_kept_even_when_null() {
+        let mut args = json!({"now": null});
+        fill_query_needs(&query_ir(), "Lease::Slot.Expired", &mut args, &FixedClock(5));
+        assert!(args["now"].is_null());
+        let mut named = json!({"now": {"value": 9}});
+        fill_query_needs(&query_ir(), "Lease::Slot.Expired", &mut named, &FixedClock(5));
+        assert_eq!(named["now"], json!({"value": 9}));
+    }
+
+    #[test]
+    fn a_query_that_needs_nothing_or_names_nothing_is_untouched() {
+        let mut args = json!({});
+        fill_query_needs(&query_ir(), "Lease::Slot.Plain", &mut args, &FixedClock(5));
+        fill_query_needs(&query_ir(), "Lease::Slot.Missing", &mut args, &FixedClock(5));
+        fill_query_needs(&query_ir(), "Lease::Shelf.Expired", &mut args, &FixedClock(5));
+        assert_eq!(args, json!({}));
+    }
+
+    #[test]
+    fn today_is_whole_days_since_the_epoch_shaped_for_its_argument() {
+        let mut args = json!({});
+        fill_query_needs(&query_ir(), "Lease::Slot.IssuedToday", &mut args, &FixedClock((19_000 * 86_400) + 86_399));
+        assert_eq!(args["today"], json!(19_000));
+
+        let mut command = json!({"with": {}});
+        let ir = json!({"name": "D", "aggregates": [{"name": "A", "commands": [
+            {"name": "Open", "attributes": [{"name": "day", "type": "Day"}], "needs": [{"fact": "day"}]},
+            {"name": "Take", "attributes": [{"name": "today", "type": "Day"}], "needs": [{"fact": "today"}]}
+        ]}]});
+        fill_needs(&ir, "D::A.Take", &mut command, &FixedClock(19_001 * 86_400));
+        assert_eq!(command["with"]["today"], json!({"value": 19_001}));
+    }
+
     #[test]
     fn the_kernel_table_lists_entity_commands_under_their_full_path() {
         assert_eq!(

data/rust/host/src/resend.rs

@@ -256,8 +256,8 @@ mod tests {
 
     #[test]
     fn a_reply_to_address_rides_in_the_payload_and_is_absent_without_one() {
-        let with = payload("f", Some("lifeadelics@gmail.com"), &email("a@b.com", "x"));
-        assert_eq!(with["reply_to"], "lifeadelics@gmail.com");
+        let with = payload("f", Some("replies@example.com"), &email("a@b.com", "x"));
+        assert_eq!(with["reply_to"], "replies@example.com");
         assert!(payload("f", None, &email("a@b.com", "x")).get("reply_to").is_none());
     }
 
@@ -273,11 +273,11 @@ mod tests {
     #[tokio::test]
     async fn a_live_send_carries_the_reply_to_address_to_resend() {
         let fake = FakeResend::start(vec![("200 OK", "", r#"{"id":"em_9"}"#)]);
-        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base).replying_to("lifeadelics@gmail.com");
+        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base).replying_to("replies@example.com");
 
         mailer.deliver(&email("a@b.com", "x")).await;
 
-        assert!(fake.requests()[0].contains(r#""reply_to":"lifeadelics@gmail.com""#), "{}", fake.requests()[0]);
+        assert!(fake.requests()[0].contains(r#""reply_to":"replies@example.com""#), "{}", fake.requests()[0]);
     }
 
     #[test]

data/rust/host/src/ui_schema.rs

@@ -860,7 +860,7 @@ fn humanize(key: &str) -> String {
 mod tests {
     use super::*;
 
-    // Embryonaut-shaped, because that's the domain the Ruby engine
+    // Shaped like a real member-gated app, the kind the Ruby engine
     // actually serves. Each test below pins one rule of ui_schema.rb.
 
     fn domain() -> Value {

data/rust/parser/src/emit.rs

@@ -463,6 +463,18 @@ fn query_json(q: &ir::Query) -> JsonValue {
     if let Some(returns) = &q.returns {
         pairs.push(("returns".to_string(), JsonValue::str(returns.clone())));
     }
+    // `needs` follows `returns`, only when declared, so a query that needs nothing keeps its shape.
+    if !q.needs.is_empty() {
+        pairs.push((
+            "needs".to_string(),
+            JsonValue::Array(
+                q.needs
+                    .iter()
+                    .map(|fact| JsonValue::Object(vec![("fact".to_string(), JsonValue::str(fact.clone()))]))
+                    .collect(),
+            ),
+        ));
+    }
     JsonValue::Object(pairs)
 }
 

data/rust/parser/src/ir.rs

@@ -133,6 +133,8 @@ pub struct Query {
     pub options: QueryOptions,
     /// `returns Name` or `returns list_of(Name)`, spelled as `Query#returns` holds it.
     pub returns: Option<String>,
+    /// Outside facts the runtime supplies before the filter reads the arguments (`needs :now`).
+    pub needs: Vec<String>,
 }
 
 /// `AuthorizationSpec#to_h`: both fields are bare `.to_s`, never Literal-rendered.

data/rust/parser/src/keywords.rs

@@ -161,6 +161,7 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "authorize", context: "Query", body: "none", inner: "", opens: "", fills: "options", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "inspect_query", context: "Query", body: "none", inner: "", opens: "", fills: "options", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "returns", context: "Query", body: "none", inner: "", opens: "", fills: "returns", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "needs", context: "Query", body: "none", inner: "", opens: "", fills: "needs", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "attribute", context: "ValueObject", body: "none", inner: "", opens: "", fills: "attributes", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "one_of", context: "ValueObject", body: "rows", inner: "OneOf", opens: "", fills: "rows", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "invariant", context: "ValueObject", body: "source", inner: "", opens: "", fills: "invariants", status: "admitted", was: "", resolves_via: "sibling_scan", disambiguator: "" },
@@ -437,6 +438,7 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "authorize", context: "Query", at: "", named: "tenant", kind: "symbol", required: "false", fills: "tenant", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "inspect_query", context: "Query", at: "1", named: "", kind: "symbol", required: "false", fills: "mode", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "returns", context: "Query", at: "1", named: "", kind: "constant", required: "true", fills: "type", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "needs", context: "Query", at: "1", named: "", kind: "symbol", required: "true", fills: "fact", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "attribute", context: "ValueObject", at: "1", named: "", kind: "symbol", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "attribute", context: "ValueObject", at: "2", named: "", kind: "constant", required: "true", fills: "type", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "attribute", context: "ValueObject", at: "", named: "default", kind: "literal", required: "false", fills: "default", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/main.rs

@@ -205,6 +205,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("limit", "Query"),
     ("authorize", "Query"),
     ("returns", "Query"),
+    ("needs", "Query"),
     ("on", "Policy"),
     ("trigger", "Policy"),
     ("across", "Policy"),

data/rust/parser/src/parse/command.rs

@@ -164,7 +164,7 @@ pub fn parse_body(
                 owner_entities,
             );
             refuse_duplicate_targets(file, *pos, &command)?;
-            refuse_undeclared_needs(file, *pos, &command)?;
+            super::needs::refuse_undeclared(file, *pos, &command.name, &command.needs, &command.attributes)?;
             return Ok((command, pending));
         };
         let line = gated.line.number;
@@ -206,27 +206,7 @@ pub fn parse_body(
                     canonical: canonical::apply(&raw),
                 });
             }
-            "needs" => {
-                let fact = super::positional_symbol(file, line, "needs", &gated.args, 1)?;
-                if !NEEDABLE_FACTS.contains(&fact.as_str()) {
-                    return Err(Diagnostic::new(
-                        file,
-                        line,
-                        format!(
-                            "{} needs :{fact}, which the runtime cannot supply — it supplies :now",
-                            command.name
-                        ),
-                    ));
-                }
-                if command.needs.contains(&fact) {
-                    return Err(Diagnostic::new(
-                        file,
-                        line,
-                        format!("{} declares needs :{fact} twice", command.name),
-                    ));
-                }
-                command.needs.push(fact);
-            }
+            "needs" => super::needs::declare(file, line, &command.name, &gated.args, &mut command.needs)?,
             "provenance" => {
                 let raw = super::named_raw(&gated.args, "from")
                     .ok_or_else(|| Diagnostic::new(file, line, "'provenance' requires a from:"))?;
@@ -319,28 +299,6 @@ fn state_ref(raw: &str) -> Option<String> {
     Some(inner.to_string())
 }
 
-/// The outside facts a command may declare it needs; mirrors `CommandBuilder::NEEDABLE_FACTS`.
-const NEEDABLE_FACTS: &[&str] = &["now"];
-
-/// A need names the attribute the runtime fills, so the command must declare it.
-fn refuse_undeclared_needs(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {
-    match command
-        .needs
-        .iter()
-        .find(|fact| !command.attributes.iter().any(|a| &a.name == *fact))
-    {
-        Some(fact) => Err(Diagnostic::new(
-            file,
-            line,
-            format!(
-                "{} needs :{fact} but declares no attribute :{fact} for the runtime to fill — add `attribute :{fact}, <type>`",
-                command.name
-            ),
-        )),
-        None => Ok(()),
-    }
-}
-
 /// Refuses a field written twice: a command's effects are one update set (C4.2).
 /// `delegates_to`/`corrects` name no field and are not counted.
 fn refuse_duplicate_targets(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {

data/rust/parser/src/parse/mod.rs

@@ -9,6 +9,7 @@ pub mod entity;
 pub mod file;
 pub mod hecksagon;
 pub mod lifecycle;
+pub mod needs;
 pub mod policy;
 pub mod process_manager;
 pub mod query;

data/rust/parser/src/parse/needs.rs

@@ -0,0 +1,60 @@
+//! The `needs` word, shared by the two declarations that may use it: a command and a query
+//! (ADR 0081). Mirrors `Hecks::Bluebook::DSL::NeedWord`.
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+use crate::parse::ArgumentGateResult;
+
+/// The outside facts a declaration may need, each the name of the attribute the runtime fills;
+/// mirrors `NeedWord::NEEDABLE_FACTS`. `now` is the clock port's reading in epoch seconds and
+/// `today` the day it falls in, whole days since the epoch in UTC.
+const NEEDABLE_FACTS: &[&str] = &["now", "today"];
+
+/// Reads one `needs :fact` line into `needs`.
+///
+/// Refuses a fact the runtime cannot supply and a fact declared twice, as the Ruby builder does.
+pub fn declare(
+    file: &str,
+    line: usize,
+    owner: &str,
+    args: &ArgumentGateResult,
+    needs: &mut Vec<String>,
+) -> ParseResult<()> {
+    let fact = super::positional_symbol(file, line, "needs", args, 1)?;
+    if !NEEDABLE_FACTS.contains(&fact.as_str()) {
+        let supplied: Vec<String> = NEEDABLE_FACTS.iter().map(|known| format!(":{known}")).collect();
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{owner} needs :{fact}, which the runtime cannot supply — it supplies {}",
+                supplied.join(", ")
+            ),
+        ));
+    }
+    if needs.contains(&fact) {
+        return Err(Diagnostic::new(file, line, format!("{owner} declares needs :{fact} twice")));
+    }
+    needs.push(fact);
+    Ok(())
+}
+
+/// A need names the attribute the runtime fills, so the declaration must have one.
+pub fn refuse_undeclared(
+    file: &str,
+    line: usize,
+    owner: &str,
+    needs: &[String],
+    attributes: &[ir::Attribute],
+) -> ParseResult<()> {
+    match needs.iter().find(|fact| !attributes.iter().any(|a| &a.name == *fact)) {
+        Some(fact) => Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{owner} needs :{fact} but declares no attribute :{fact} for the runtime to fill — add `attribute :{fact}, <type>`"
+            ),
+        )),
+        None => Ok(()),
+    }
+}