hecks 3.2.1 → 3.4.0

data/rust/codegen/src/main.rs

@@ -19,6 +19,7 @@ mod literal;
 mod manifest;
 mod mutations;
 mod naming;
+mod optional_pass;
 mod ports;
 mod prelude;
 mod queries;
@@ -28,6 +29,7 @@ mod reference_specs;
 mod registry;
 mod reserved_names;
 mod shared;
+mod sidecars;
 mod skip_reason;
 mod types;
 
@@ -85,22 +87,29 @@ fn run_prelude(args: &[String]) -> Result<(), String> {
 }
 
 /// `hecks-codegen domain <ir.json> <source_label> <mod_name> <out_dir>` — writes one chapter's
-/// `<aggregate>.rs`, `registry.rs`, `mod.rs` and `manifest.json` into `out_dir`.
-///
-/// `metadata.rs` and `ir.json` are left to `hecks project_rust`.
+/// `<aggregate>.rs`, `registry.rs`, `mod.rs`, `manifest.json` and its `ir.json`/`metadata.rs`
+/// sidecars into `out_dir`.
 fn run_domain(args: &[String]) -> Result<(), String> {
     let [ir_path, source_label, mod_name, out_dir] = args else {
         return Err("usage: hecks-codegen domain <ir.json> <source_label> <mod_name> <out_dir>".to_string());
     };
 
-    let text = std::fs::read_to_string(ir_path).map_err(|e| format!("reading {ir_path}: {e}"))?;
-    let ir = Json::parse(&text).map_err(|e| format!("parsing {ir_path}: {e}"))?;
+    let ir = read_ir(ir_path)?;
 
     let ex = exemplar::Exemplar::load();
     write_domain(&ex, &ir, source_label, mod_name, out_dir)?;
     Ok(())
 }
 
+/// Reads one chapter's IR and prepares it for generation: marks the fields an `append` binds to an
+/// optional argument. What it generates from and what it writes to `ir.json` are this same IR.
+fn read_ir(path: &str) -> Result<Json, String> {
+    let text = std::fs::read_to_string(path).map_err(|e| format!("reading {path}: {e}"))?;
+    let mut ir = Json::parse(&text).map_err(|e| format!("parsing {path}: {e}"))?;
+    optional_pass::run(&mut ir);
+    Ok(ir)
+}
+
 /// Writes one chapter's files into `out_dir` and returns the `GeneratedDomain`, so `run_full`
 /// can union the registry, query and read-model definitions across chapters.
 fn write_domain(
@@ -147,6 +156,10 @@ fn write_domain(
     std::fs::write(&manifest_path, &generated.manifest_json).map_err(|e| format!("writing {manifest_path}: {e}"))?;
     println!("wrote {manifest_path}");
 
+    let (ir_json_path, metadata_path) = sidecars::write(std::path::Path::new(out_dir), ir, source_label)?;
+    println!("wrote {}", ir_json_path.display());
+    println!("wrote {}", metadata_path.display());
+
     Ok(generated)
 }
 
@@ -181,8 +194,7 @@ fn run_full(args: &[String]) -> Result<(), String> {
 
     let ex = exemplar::Exemplar::load();
 
-    let target_text = std::fs::read_to_string(target_ir_path).map_err(|e| format!("reading {target_ir_path}: {e}"))?;
-    let target_ir = Json::parse(&target_text).map_err(|e| format!("parsing {target_ir_path}: {e}"))?;
+    let target_ir = read_ir(target_ir_path)?;
     let target_domain_name = target_ir.get("name").and_then(Json::as_str).unwrap_or("").to_string();
 
     let target_out_dir = format!("{out_root}/{target_mod_name}");
@@ -209,8 +221,7 @@ fn run_full(args: &[String]) -> Result<(), String> {
         let chapter_ir_path = &args[i + 2];
         i += 3;
 
-        let text = std::fs::read_to_string(chapter_ir_path).map_err(|e| format!("reading {chapter_ir_path}: {e}"))?;
-        let chapter_ir = Json::parse(&text).map_err(|e| format!("parsing {chapter_ir_path}: {e}"))?;
+        let chapter_ir = read_ir(chapter_ir_path)?;
         let chapter_domain_name = chapter_ir.get("name").and_then(Json::as_str).unwrap_or("").to_string();
 
         let chapter_out_dir = format!("{out_root}/{chapter_mod_name}");

data/rust/codegen/src/naming.rs

@@ -285,8 +285,10 @@ pub fn literal_rhs(literal: &crate::json::Json) -> String {
     match literal {
         crate::json::Json::String(s) => format!("{}.to_string()", ruby_inspect_string(s)),
         // Separate arms so a whole-number Float renders as `0.0`, not an integer-typed `0`.
-        crate::json::Json::Int(n) => n.to_string(),
-        crate::json::Json::Float(_) => literal.to_s(),
+        crate::json::Json::Number(_) => match literal.number() {
+            Some(crate::json::Number::Int(n)) => n.to_string(),
+            _ => literal.to_s(),
+        },
         crate::json::Json::Bool(b) => b.to_string(),
         other => panic!("unsupported literal mutation source {other:?} — not one of String/Integer/Float/Boolean"),
     }

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.4.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: "" },
@@ -183,8 +184,6 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "hecksagon", context: "File", body: "keywords", inner: "Hecksagon", opens: "Hecksagon", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "subscribe", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "attaches", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_framework", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "port", context: "Hecksagon", body: "keywords", inner: "DomainPort", opens: "DomainPort", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "translates", context: "Hecksagon", body: "keywords", inner: "Policy", opens: "Policy", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "bounded", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
@@ -437,6 +436,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: "" },
@@ -468,8 +468,6 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "subscribe", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "", named: "from", kind: "symbol", required: "false", fills: "source", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_framework", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "port", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "translates", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "reference_to", context: "PortOperation", at: "1", named: "", kind: "constant", required: "true", fills: "type", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/lex.rs

@@ -567,7 +567,7 @@ mod tests {
     #[test]
     fn does_not_strip_a_bare_lowercase_call() {
         assert_eq!(
-            strip_aggregate_receiver("uses_framework \"Governance\""),
+            strip_aggregate_receiver("attaches \"Governance\""),
             None
         );
         assert_eq!(strip_aggregate_receiver("subscribe \"Deposited\""), None);

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"),