hecks 3.2.0 → 3.3.0

data/rust/codegen/src/main.rs

@@ -1,4 +1,4 @@
-//! `hecks-codegen` — Rust port of the IR-to-Rust-source codegen in `rust/project/*.rb`.
+//! `hecks-codegen` — the IR-to-Rust-source generator, the only one (ADR 0086).
 //! Usage: `hecks-codegen <prelude|domain|full> ...`, one subcommand per function below.
 // Some ported `naming.rs` helpers are not called yet.
 #![allow(dead_code)]
@@ -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(
@@ -110,7 +119,7 @@ fn write_domain(
     mod_name: &str,
     out_dir: &str,
 ) -> Result<domain_generator::GeneratedDomain, String> {
-    // Refuse before writing anything; same message as `RustProjection::DomainGenerator.call`.
+    // Refuse before writing anything, so a name collision is reported before any file exists.
     let aggregate_names: Vec<&str> = ir
         .get("aggregates")
         .map(Json::each)
@@ -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}");
@@ -257,8 +268,7 @@ fn run_full(args: &[String]) -> Result<(), String> {
     puts_blank(&mut merged_rs);
     puts_str(&mut merged_rs, &reactions::emit_identity_head_table(&ex, &merged_aggregates));
     puts_blank(&mut merged_rs);
-    // Section order must match `rust/project/domain_generator.rb`; the pipeline spec compares
-    // this file byte for byte.
+    // Section order is part of the output: `hecks regenerate_corpus --check` diffs this file byte for byte.
     puts_str(&mut merged_rs, &reactions::emit_entity_identity_head_table(&ex, &merged_aggregates));
     puts_blank(&mut merged_rs);
     puts_str(&mut merged_rs, &reactions::emit_command_attributes_table(&ex, &merged_aggregates));

data/rust/codegen/src/mutations.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/mutations.rb`, function for function.
+//! Port of the retired Ruby generator's `mutations.rb`, function for function.
 //! `mark_append_optional_fields!` is not ported: `Json` has no mutation API and the corpus
 //! already declares `optional: true` on every field that pass would touch.
 

data/rust/codegen/src/naming.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/naming.rb`, mirrored function for function.
+//! Port of the retired Ruby generator's `naming.rb`, mirrored function for function.
 
 use crate::json::Json;
 
@@ -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/codegen/src/ports.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/ports.rb` — read that file's own header comments
+//! Port of the retired Ruby generator's `ports.rb` — read that file's own header comments
 //! in full; this mirrors its algorithm directly, function for function.
 
 use crate::exemplar::Exemplar;

data/rust/codegen/src/queries.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/queries.rb`, mirrored function for function.
+//! Port of the retired Ruby generator's `queries.rb`, mirrored function for function.
 
 use crate::exemplar::Exemplar;
 use crate::json::Json;
@@ -302,7 +302,7 @@ pub fn query_skip_reason(query: &Json, aggregate: &Json, value_objects_by_name:
     let extra_keys = ["cursor", "consistency", "freshness", "inspection"];
     let extras: Vec<&str> = extra_keys.iter().filter(|k| query.get(k).is_some()).copied().collect();
     if !extras.is_empty() {
-        return Some(skip(extras[0], format!("declares {} — out of scope for this generator (rust/project/queries.rb's own header has the full argument)", extras.join(", "))));
+        return Some(skip(extras[0], format!("declares {} — out of scope for this generator (rust/codegen/src/queries.rs's own header has the full argument)", extras.join(", "))));
     }
     if query.get("index_hints").map(Json::each).unwrap_or(&[]).iter().any(|_| true) {
         return Some(skip("index_hints", "declares use_index, out of scope for the same reason the extras above are"));
@@ -780,7 +780,7 @@ pub fn emit_query_arg_check_table(query_defs: &[QueryDef]) -> String {
         })
         .collect();
     format!(
-        "/// C3.7 for a named query's own arguments — `query_arg_checks`\n/// (rust/project/queries.rb) has the full story.\npub fn check_query_args(verb: &str, args: &crate::kernel::Json) -> Result<(), crate::kernel::Refusal> {{\n    match verb {{\n{}\n        _ => Ok(()),\n    }}\n}}\n",
+        "/// C3.7 for a named query's own arguments — `query_arg_checks`\n/// (rust/codegen/src/queries.rs) has the full story.\npub fn check_query_args(verb: &str, args: &crate::kernel::Json) -> Result<(), crate::kernel::Refusal> {{\n    match verb {{\n{}\n        _ => Ok(()),\n    }}\n}}\n",
         arms.join("\n")
     )
 }

data/rust/codegen/src/reactions.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/reactions.rb`, mirrored function for function.
+//! Port of the retired Ruby generator's `reactions.rb`, mirrored function for function.
 
 use crate::exemplar::Exemplar;
 use crate::json::Json;

data/rust/codegen/src/read_models.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/read_models.rb`, mirrored function for function —
+//! Port of the retired Ruby generator's `read_models.rb`, mirrored function for function —
 //! read that file's own header for the full algorithm.
 
 use crate::exemplar::Exemplar;
@@ -267,7 +267,7 @@ fn aggregation_skip_reason(read_model: &Json, aggregates_by_name: &HashMap<Strin
     None
 }
 
-// Mirrors `rust/project/read_models.rb`'s `group_by_skip_reason`: the one
+// Mirrors the retired Ruby generator's `read_models.rb`'s `group_by_skip_reason`: the one
 // shape the corpus declares — a single rootless head, group_by alone.
 fn group_by_skip_reason(read_model: &Json, aggregates_by_name: &HashMap<String, &Json>, unsupported_names: &[String]) -> Option<SkipReason> {
     let heads = read_model.get("aggregate_heads").map(Json::each).unwrap_or(&[]);

data/rust/codegen/src/reference_specs.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/reference_specs.rb` — read that file's own
+//! Port of the retired Ruby generator's `reference_specs.rb` — read that file's own
 //! header comments in full; this mirrors its algorithm directly,
 //! function for function.
 

data/rust/codegen/src/registry.rs

@@ -1,4 +1,4 @@
-//! Command router emitter, ported from `rust/project/registry.rb`.
+//! Command router emitter, ported from the retired Ruby generator's `registry.rb`.
 //! The entry structs mirror the Hashes `domain_generator.rb` accumulates while walking the IR.
 
 use crate::exemplar::Exemplar;
@@ -144,7 +144,7 @@ pub fn emit_role_check(
     ))
 }
 
-/// Port of `rust/project/registry.rb#emit_tenant_boundary_check`.
+/// Port of the retired Ruby generator's `registry.rb#emit_tenant_boundary_check`.
 /// Hand-built: the target accessor differs for a single-attribute value object and a bare scalar.
 pub fn emit_tenant_boundary_check(check: &TenantBoundaryCheck) -> String {
     let ref_ident = naming::rust_ident_field(&check.reference_field);
@@ -740,7 +740,7 @@ pub fn emit_registry(exemplar: &Exemplar, aggregates: &[AggregateEntry]) -> Stri
     format!("{header}{body}")
 }
 
-/// Port of `rust/project/registry.rb#emit_reference_table`.
+/// Port of the retired Ruby generator's `registry.rb#emit_reference_table`.
 pub fn emit_reference_table(aggregates: &[AggregateEntry]) -> String {
     let rows: Vec<String> = aggregates
         .iter()
@@ -760,7 +760,7 @@ pub fn emit_reference_table(aggregates: &[AggregateEntry]) -> String {
     )
 }
 
-/// Port of `rust/project/registry.rb#emit_reference_lookup`.
+/// Port of the retired Ruby generator's `registry.rb#emit_reference_lookup`.
 pub fn emit_reference_lookup(aggregates: &[AggregateEntry]) -> String {
     let arms: Vec<String> = aggregates
         .iter()

data/rust/codegen/src/shared.rs

@@ -1,4 +1,4 @@
-//! Predicates ported from `rust/project/mutations.rb` that `types.rs` and `json_codec.rs` share.
+//! Predicates ported from the retired Ruby generator's `mutations.rb` that `types.rs` and `json_codec.rs` share.
 
 use crate::json::Json;
 use std::collections::HashMap;

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/codegen/src/skip_reason.rs

@@ -1,4 +1,4 @@
-//! A skip decision plus the construct family that forced it (`rust/project/skip_reason.rb`).
+//! A skip decision plus the construct family that forced it (the retired Ruby generator's `skip_reason.rb`).
 //! `construct` goes to `manifest.json` beside the reason so tools read the family, not the prose.
 
 use std::fmt;

data/rust/codegen/src/types.rs

@@ -1,4 +1,4 @@
-//! Type emitters ported from `rust/project/types.rb`: records, entities, value objects and
+//! Type emitters ported from the retired Ruby generator's `types.rb`: records, entities, value objects and
 //! closed-set tables.
 
 use crate::exemplar::Exemplar;
@@ -286,7 +286,7 @@ pub fn emit_record(exemplar: &Exemplar, aggregate: &Json, value_objects_by_name:
     format!("{struct_part}\n\n{fielded_part}")
 }
 
-/// Port of `rust/project/types.rb#projected_field_pseudo_attributes` (ADR 0025).
+/// Port of the retired Ruby generator's `types.rb#projected_field_pseudo_attributes` (ADR 0025).
 pub fn projected_field_pseudo_attributes(aggregate: &Json) -> Vec<Json> {
     aggregate
         .get("projected_fields")
@@ -318,7 +318,7 @@ pub fn with_projected_field_pseudo_attributes(aggregate: &Json) -> Json {
     Json::Object(pairs)
 }
 
-/// Port of `rust/project/types.rb#emit_set_projected_field`.
+/// Port of the retired Ruby generator's `types.rb#emit_set_projected_field`.
 pub fn emit_set_projected_field(aggregate: &Json) -> String {
     let name = naming::rust_ident(aggregate.get("name").and_then(Json::as_str).unwrap_or(""));
     let arms: Vec<String> = aggregate
@@ -338,7 +338,7 @@ pub fn emit_set_projected_field(aggregate: &Json) -> String {
     )
 }
 
-/// Port of `rust/project/types.rb#emit_projected_field_table`.
+/// Port of the retired Ruby generator's `types.rb#emit_projected_field_table`.
 pub fn emit_projected_field_table(aggregate: &Json) -> String {
     let name = naming::screaming_snake(aggregate.get("name").and_then(Json::as_str).unwrap_or(""));
     let rows: Vec<String> = aggregate

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.2.0
+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();