hecks 3.2.0 → 3.3.0

data/rust/host/src/needs.rs

@@ -110,21 +110,34 @@ pub fn table(domain_ir: &Value) -> Value {
     Value::Object(verbs)
 }
 
+fn list<'a>(value: &'a Value, key: &str) -> &'a [Value] {
+    value.get(key).and_then(Value::as_array).map(Vec::as_slice).unwrap_or(&[])
+}
+
+fn named(value: &Value, name: &str) -> bool {
+    value.get("name").and_then(Value::as_str) == Some(name)
+}
+
+/// The command a verb names: `Domain::Aggregate.Command` on the aggregate itself, or
+/// `Domain::Aggregate.Entity[.Entity].Command` on an entity nested inside it.
+fn command_for<'a>(domain_ir: &'a Value, verb: &str) -> Option<&'a Value> {
+    let mut segments = verb.split('.');
+    let aggregate = segments.next()?.rsplit("::").next()?;
+    let mut path: Vec<&str> = segments.collect();
+    let command_name = path.pop()?;
+    let mut node = list(domain_ir, "aggregates").iter().find(|a| named(a, aggregate))?;
+    for entity in path {
+        node = list(node, "entities").iter().find(|e| named(e, entity))?;
+    }
+    list(node, "commands").iter().find(|c| named(c, command_name))
+}
+
 /// The command's attributes that declare a default (`attribute :runs, Count, default: 30`), each
 /// with the declared value. An attribute whose default is null declares none.
 fn declared_defaults<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, &'a Value)> {
-    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()
-    };
-    list(domain_ir, "aggregates")
-        .into_iter()
-        .filter(|a| named(a, aggregate))
-        .flat_map(|a| list(a, "commands"))
-        .filter(|c| named(c, command_name))
-        .flat_map(|c| list(c, "attributes"))
+    let Some(command) = command_for(domain_ir, verb) else { return Vec::new() };
+    list(command, "attributes")
+        .iter()
         .filter_map(|a| {
             let default = a.get("default").filter(|d| !d.is_null())?;
             Some((a.get("name").and_then(Value::as_str)?, default))
@@ -133,29 +146,35 @@ fn declared_defaults<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, &'a
 }
 
 /// Every command's declared defaults as the kernel's input `"defaults"` reads them:
-/// `{ verb: { attribute: value } }`. The kernel fills a reaction's command from this the same way
-/// the host fills the outermost one.
+/// `{ verb: { attribute: value } }`, entity commands included. The kernel fills a reaction's
+/// command from this the same way the host fills the outermost one.
 pub fn defaults_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 {
+    for aggregate in list(domain_ir, "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 defaults: serde_json::Map<String, Value> = declared_defaults(domain_ir, &verb)
-                .into_iter()
-                .map(|(name, value)| (name.to_string(), value.clone()))
-                .collect();
-            if !defaults.is_empty() {
-                verbs.insert(verb, Value::Object(defaults));
-            }
-        }
+        collect_defaults(domain_ir, aggregate, &format!("{domain}::{aggregate_name}"), &mut verbs);
     }
     Value::Object(verbs)
 }
 
+/// Adds the defaults of `node`'s commands, then of each entity nested in it, under `prefix`.
+fn collect_defaults(domain_ir: &Value, node: &Value, prefix: &str, verbs: &mut serde_json::Map<String, Value>) {
+    for command in list(node, "commands") {
+        let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+        let verb = format!("{prefix}.{command_name}");
+        let defaults: serde_json::Map<String, Value> =
+            declared_defaults(domain_ir, &verb).into_iter().map(|(name, value)| (name.to_string(), value.clone())).collect();
+        if !defaults.is_empty() {
+            verbs.insert(verb, Value::Object(defaults));
+        }
+    }
+    for entity in list(node, "entities") {
+        let entity_name = entity.get("name").and_then(Value::as_str).unwrap_or_default();
+        collect_defaults(domain_ir, entity, &format!("{prefix}.{entity_name}"), 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>> {
@@ -167,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,
     }
@@ -193,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.
@@ -351,4 +415,104 @@ mod tests {
         assert_eq!(defaults_table(&defaulted_ir()), json!({"Qc::Check.Start": {"runs": 30}}));
         assert_eq!(defaults_table(&integer_ir()), json!({}));
     }
+
+    // A board entity with a defaulted command, and a card nested inside it with another.
+    fn nested_ir() -> Value {
+        json!({"name": "Np", "aggregates": [{"name": "Workspace", "commands": [], "entities": [
+            {"name": "Board", "commands": [
+                {"name": "Retitle", "attributes": [
+                    {"name": "label", "type": "BoardLabel", "default": {"value": "untitled"}}], "needs": []}
+            ], "entities": [
+                {"name": "Card", "commands": [
+                    {"name": "Remark", "attributes": [
+                        {"name": "note", "type": "CardNote", "default": {"text": "none"}}], "needs": []}
+                ]}
+            ]}
+        ]}]})
+    }
+
+    #[test]
+    fn an_entity_command_is_filled_from_its_own_declared_default() {
+        let mut args = json!({"reference": {"value": "W1"}, "number": {"value": 1}});
+        fill_defaults(&nested_ir(), "Np::Workspace.Board.Retitle", &mut args);
+        assert_eq!(args["label"], json!({"value": "untitled"}));
+    }
+
+    #[test]
+    fn a_command_on_an_entity_nested_in_an_entity_is_filled_too() {
+        let mut args = json!({"with": {"reference": {"value": "W1"}}});
+        fill_defaults(&nested_ir(), "Np::Workspace.Board.Card.Remark", &mut args);
+        assert_eq!(args["with"]["note"], json!({"text": "none"}));
+    }
+
+    #[test]
+    fn an_entity_path_that_names_nothing_is_left_untouched() {
+        let mut args = json!({"number": 1});
+        fill_defaults(&nested_ir(), "Np::Workspace.Shelf.Retitle", &mut args);
+        fill_defaults(&nested_ir(), "Np::Workspace.Board.Remark", &mut args);
+        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!(
+            defaults_table(&nested_ir()),
+            json!({
+                "Np::Workspace.Board.Retitle": {"label": {"value": "untitled"}},
+                "Np::Workspace.Board.Card.Remark": {"note": {"text": "none"}}
+            })
+        );
+    }
 }

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(()),
+    }
+}

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

@@ -25,6 +25,8 @@ pub fn parse_body(
 
     loop {
         let Some(gated) = super::next_line(file, lines, pos, "Query")? else {
+            let end = lines.get(pos.saturating_sub(1)).map_or(0, |l| l.number);
+            super::needs::refuse_undeclared(file, end, name, &query.needs, &query.attributes)?;
             return Ok(query);
         };
         let line = gated.line.number;
@@ -83,6 +85,7 @@ pub fn parse_body(
                     type_name
                 });
             }
+            "needs" => super::needs::declare(file, line, name, &gated.args, &mut query.needs)?,
             word if OPTION_WORDS.contains(&word) => {
                 query_options::apply(file, line, word, &gated.args, &mut query.options)?
             }

data/rust/src/exemplar/commands.rs

@@ -1,4 +1,4 @@
-//! Exemplar shapes for rust/project/commands.rb (see mod.rs).
+//! Exemplar shapes for rust/codegen/src/commands.rs (see mod.rs).
 //!
 //! `dispatch_fn` proves the outer `pub fn .. -> DispatchResult { .. dispatch(..) .. }` wrapper.
 #![allow(dead_code, unused_variables)]

data/rust/src/exemplar/constraints.rs

@@ -1,4 +1,4 @@
-//! Exemplar shapes for rust/project/constraints.rb (see mod.rs).
+//! Exemplar shapes for rust/codegen/src/constraints.rs (see mod.rs).
 //!
 //! Both shapes are single-line refusal checks spliced into a `Result`-returning body.
 #![allow(dead_code, unused_variables)]

data/rust/src/exemplar/fielded.rs

@@ -1,4 +1,4 @@
-//! Exemplar shapes for rust/project/fielded.rb (see mod.rs).
+//! Exemplar shapes for rust/codegen/src/fielded.rs (see mod.rs).
 //!
 //! Each `Fielded::field` arm shape is a standalone leaf so both outer skeletons can reuse it.
 #![allow(dead_code, unused_variables)]

data/rust/src/exemplar/json.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes for rust/project/json_codec.rb; see mod.rs.
+// Exemplar shapes for rust/codegen/src/json_codec.rs; see mod.rs.
 // Kept out of the fenced region so its prose is not baked into every generated codec.
 #![allow(dead_code, unused_variables)]
 

data/rust/src/exemplar/mod.rs

@@ -1,4 +1,4 @@
-// Compile-checked Rust for every shape rust/project/*.rb emits; exemplar.rb slices the fenced
+// Compile-checked Rust for every shape rust/codegen/src/*.rs emits; exemplar.rs slices the fenced
 // `// TMPL:<id> BEGIN` / `END` regions and substitutes real names for the `tmpl_` vocabulary.
 //
 // `tmpl_*_host` functions only give fenced fragments real types and are never called, hence

data/rust/src/exemplar/mutations.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes for rust/project/mutations.rb; see mod.rs.
+// Exemplar shapes for rust/codegen/src/mutations.rs; see mod.rs.
 // Hosts take `record: &mut Tmpl...`, not `&mut self`, as the generated mutation closures do.
 #![allow(dead_code, unused_variables)]
 

data/rust/src/exemplar/queries.rs

@@ -1,4 +1,4 @@
-// Exemplar shape for rust/project/registry.rb's `emit_query_table`; see mod.rs.
+// Exemplar shape for rust/codegen/src/registry.rs's `emit_query_table`; see mod.rs.
 #![allow(dead_code, unused_variables)]
 
 // A `const` cannot call a function, so the row is a real literal substituted wholesale.

data/rust/src/exemplar/reactions.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes that rust/project/reactions.rb slices into generated tables;
+// Exemplar shapes that rust/codegen/src/reactions.rs slices into generated tables;
 // see mod.rs for how they are used.
 #![allow(dead_code, unused_variables)]
 

data/rust/src/exemplar/read_models.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes for rust/project/read_models.rb's `emit_read_model_table`
+// Exemplar shapes for rust/codegen/src/read_models.rs's `emit_read_model_table`
 // — see mod.rs's own header. `ReadModelDef`/`ReadModelHead`/`FilteredHead`/
 // `ReferenceField` are real kernel types (`rust/src/kernel/read_model.rs`).
 #![allow(dead_code, unused_variables)]

data/rust/src/exemplar/registry.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes for rust/project/registry.rb; see mod.rs.
+// Exemplar shapes for rust/codegen/src/registry.rs; see mod.rs.
 // `InMemoryRepository<T>` only needs `T: Clone`, so an `i64` record type suffices.
 #![allow(dead_code, unused_variables)]
 

data/rust/src/exemplar/types.rs

@@ -1,4 +1,4 @@
-// Exemplar shapes for rust/project/types.rb; see mod.rs.
+// Exemplar shapes for rust/codegen/src/types.rs; see mod.rs.
 // `closed_set_enum` is a one-field closed set (one variant per member); a multi-field closed
 // set is a fixed data table instead.
 #![allow(dead_code, unused_variables)]