hecks 3.14.0 → 5.0.0

data/rust/src/kernel/cli.rs

@@ -1,8 +1,17 @@
 //! The stdin/stdout JSON CLI shared by the native binary and the wasm32-wasip1 module.
-//! `run` reads `{"steps": [...]}` and hands each step to `kernel::orchestrate` (ADR 0012).
-
-use super::{named_query, orchestrate, query_comparators, read_model, repository, AggregateScan, CompletedCompensation, Event, Json, MutationRecord, PendingCrossDomainReaction, Refusal, SagaInstance, Tables};
-use crate::generated::active::{command_attributes_for_verb, command_creates, dispatch_by_name, entity_identity_head_for_path, identity_head_for_aggregate, reference_key_for_aggregate, Store, CROSS_DOMAIN_POLICIES, POLICIES, PROCESS_MANAGERS, QUERIES, READ_MODELS};
+//! `run` reads `{"steps": [...]}` and hands each step to `kernel::orchestrate` (ADR 0012), or
+//! `{"present": answer}` and answers that answer bare (`kernel::present`).
+
+use super::{
+    named_query, orchestrate, query_comparators, read_model, repository, AggregateScan,
+    CompletedCompensation, Event, Json, MutationRecord, PendingCrossDomainReaction, Refusal,
+    SagaInstance, Tables,
+};
+use crate::generated::active::{
+    command_attributes_for_verb, command_creates, dispatch_by_name, entity_identity_head_for_path,
+    identity_head_for_aggregate, reference_key_for_aggregate, Store, CROSS_DOMAIN_POLICIES,
+    POLICIES, PROCESS_MANAGERS, QUERIES, READ_MODELS,
+};
 use std::collections::HashMap;
 
 // Builds and invariant-checks a named query's value-object arguments (ADR 0037).
@@ -16,6 +25,18 @@ pub fn run(input: &str) -> String {
         Err(e) => return error_output(&format!("invalid JSON on stdin: {e}")),
     };
 
+    // `{"present": answer}`: a run's answer in the bare shape a caller reads (single-field value
+    // objects as their sole field); no step runs, and stored state stays wrapped.
+    // Parsed again keeping number text, so a Float the answer carries is written back unchanged.
+    if parsed.get("present").is_some() {
+        let answer = Json::parse_keeping_number_text(input)
+            .ok()
+            .and_then(|whole| whole.get("present").cloned())
+            .unwrap_or(Json::Null);
+        return super::present::present_answer(answer, crate::generated::active::present)
+            .to_json_string();
+    }
+
     // Optional `"needs"`: which commands need which outside facts (ADR 0081), passed by the host.
     super::needs::install(parsed.get("needs"));
     // Optional `"query_needs"`: which queries need which outside facts, filled the same way.
@@ -23,9 +44,8 @@ pub fn run(input: &str) -> String {
     // Optional `"defaults"`: each command's declared argument defaults, filled the same way.
     super::needs::install_defaults(parsed.get("defaults"));
 
-    let steps = match parsed.get("steps").and_then(Json::as_array) {
-        Some(s) => s,
-        None => return error_output("expected a top-level {\"steps\": [...]} object"),
+    let Some(steps) = parsed.get("steps").and_then(Json::as_array) else {
+        return error_output("expected a top-level {\"steps\": [...]} object");
     };
 
     // Optional `"seed"`: prior state as `"instances"` emits it, so a host need not replay history.
@@ -40,34 +60,46 @@ pub fn run(input: &str) -> String {
     let mut refusals: Vec<(String, Refusal)> = Vec::new();
     // Process-manager instances are domain-level, so not a `Store` field.
     // Optional `"sagas"` seeds in-flight saga state the way `"seed"` seeds aggregates.
-    let mut sagas: HashMap<(String, String), SagaInstance> = match parsed.get("sagas").and_then(Json::as_array) {
-        Some(entries) => entries
-            .iter()
-            .filter_map(|entry| {
-                let process_manager = entry.get("process_manager")?.as_str()?.to_string();
-                let correlation = entry.get("correlation")?.as_str()?.to_string();
-                let state = entry.get("state")?.as_str()?.to_string();
-                let memory = entry.get("memory").cloned().unwrap_or_else(|| Json::Object(vec![]));
-                // Optional: an instance persisted without a ledger rehydrates with an empty one.
-                let completed_compensations = entry
-                    .get("completed_compensations")
-                    .and_then(Json::as_array)
-                    .map(|entries| {
-                        entries
-                            .iter()
-                            .filter_map(|e| {
-                                let command_name = e.get("command_name")?.as_str()?.to_string();
-                                let args = e.get("args").cloned().unwrap_or(Json::Null);
-                                Some(CompletedCompensation { command_name, args })
-                            })
-                            .collect()
-                    })
-                    .unwrap_or_default();
-                Some(((process_manager, correlation), SagaInstance { state, memory, completed_compensations }))
-            })
-            .collect(),
-        None => HashMap::new(),
-    };
+    let mut sagas: HashMap<(String, String), SagaInstance> = parsed
+        .get("sagas")
+        .and_then(Json::as_array)
+        .map_or_else(HashMap::new, |entries| {
+            entries
+                .iter()
+                .filter_map(|entry| {
+                    let process_manager = entry.get("process_manager")?.as_str()?.to_string();
+                    let correlation = entry.get("correlation")?.as_str()?.to_string();
+                    let state = entry.get("state")?.as_str()?.to_string();
+                    let memory = entry
+                        .get("memory")
+                        .cloned()
+                        .unwrap_or_else(|| Json::Object(vec![]));
+                    // Optional: an instance persisted without a ledger rehydrates with an empty one.
+                    let completed_compensations = entry
+                        .get("completed_compensations")
+                        .and_then(Json::as_array)
+                        .map(|entries| {
+                            entries
+                                .iter()
+                                .filter_map(|e| {
+                                    let command_name = e.get("command_name")?.as_str()?.to_string();
+                                    let args = e.get("args").cloned().unwrap_or(Json::Null);
+                                    Some(CompletedCompensation { command_name, args })
+                                })
+                                .collect()
+                        })
+                        .unwrap_or_default();
+                    Some((
+                        (process_manager, correlation),
+                        SagaInstance {
+                            state,
+                            memory,
+                            completed_compensations,
+                        },
+                    ))
+                })
+                .collect()
+        });
     // One entry per step, parallel to `steps`, so a host can read `.last()` for the newest step.
     let mut mutations_per_step: Vec<Vec<MutationRecord>> = Vec::new();
     // Parallel to `mutations_per_step`: policies that named a domain not compiled into this
@@ -92,7 +124,11 @@ pub fn run(input: &str) -> String {
         // for the run alone (ADR 0081), so the log holds no value that depends on the clock.
         let offered = args;
         let filled = match step.get("query") {
-            Some(Json::Str(question)) => super::needs::enrich_query(question, args, step.get("occurred_at").and_then(Json::as_str)),
+            Some(Json::Str(question)) => super::needs::enrich_query(
+                question,
+                args,
+                step.get("occurred_at").and_then(Json::as_str),
+            ),
             _ => None,
         };
         let args = filled.as_ref().unwrap_or(args);
@@ -110,27 +146,15 @@ pub fn run(input: &str) -> String {
                 // reference twin is the same engine.
                 // `reference_interpret` delegates to the same `entity_rows`).
                 Json::Str(question) if question.contains("::") && named_query::find_entity(ENTITY_QUERIES, question).is_some() => {
+                    // reason: the match guard above only admits a `question` that resolves.
+                    #[allow(clippy::expect_used)]
                     let def = named_query::find_entity(ENTITY_QUERIES, question).expect("matched by the guard above");
                     match named_query::run_entity(&store, def, args) {
                         Ok(rows) => {
-                            let rows = Json::Array(rows);
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", rows.clone()),
-                                ("reference_rows", rows),
-                            ]));
+                            query_results.push(answered_entry(question, offered, Json::Array(rows), true));
                         }
                         Err(refusal) => {
-                            let message = refusal.to_string();
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", Json::Null),
-                                ("error", Json::Str(message.clone())),
-                                ("reference_rows", Json::Null),
-                                ("reference_error", Json::Str(message)),
-                            ]));
+                            query_results.push(refused_entry(question, offered, &refusal, true));
                             refusals.push((question.clone(), refusal));
                         }
                     }
@@ -139,26 +163,13 @@ pub fn run(input: &str) -> String {
                     Some(def) => match check_query_args(question, args).and_then(|()| named_query::run(&store, def, args, caller_role)) {
                         Ok(entries) => {
                             let rows = Json::Array(entries.into_iter().map(|(id, record)| repository::row_json(id, record)).collect());
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", rows.clone()),
-                                // Same as `rows`: one compiled path (named_query.rs).
-                                ("reference_rows", rows),
-                            ]));
+                            // The reference twin is `rows`: one compiled path (named_query.rs).
+                            query_results.push(answered_entry(question, offered, rows, true));
                         }
                         // A refused query still gets an entry with `rows: null`, as in Ruby; one
                         // compiled path means `error` and `reference_error` are the same string.
                         Err(refusal) => {
-                            let message = refusal.to_string();
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", Json::Null),
-                                ("error", Json::Str(message.clone())),
-                                ("reference_rows", Json::Null),
-                                ("reference_error", Json::Str(message)),
-                            ]));
+                            query_results.push(refused_entry(question, offered, &refusal, true));
                             refusals.push((question.clone(), refusal));
                         }
                     },
@@ -179,24 +190,11 @@ pub fn run(input: &str) -> String {
                 },
                 Json::Str(question) => match read_model::find(READ_MODELS, question) {
                     Some(def) => match read_model::run(&store, def, args) {
-                        Ok(row) => {
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", Json::Array(vec![row])),
-                                // No `reference_rows` key: Ruby sets it only for questions with a
-                                // reference twin, and a read model has none.
-                            ]));
-                        }
-                        // As above, minus the reference keys.
+                        // No reference keys: Ruby sets them only for questions with a reference twin,
+                        // and a read model has none.
+                        Ok(row) => query_results.push(answered_entry(question, offered, Json::Array(vec![row]), false)),
                         Err(refusal) => {
-                            let message = refusal.to_string();
-                            query_results.push(Json::obj(vec![
-                                ("query", Json::Str(question.clone())),
-                                ("args", offered.clone()),
-                                ("rows", Json::Null),
-                                ("error", Json::Str(message)),
-                            ]));
+                            query_results.push(refused_entry(question, offered, &refusal, false));
                             refusals.push((question.clone(), refusal));
                         }
                     },
@@ -235,16 +233,21 @@ pub fn run(input: &str) -> String {
             // See `actor_id` on the command step below.
             let caller_actor_id = step.get("actor_id").and_then(Json::as_str);
             let command_input = dry_run_command_input(args);
-            dry_runs.push(dry_run(&store, verb, &command_input, caller_role, caller_actor_id));
+            dry_runs.push(dry_run(
+                &store,
+                verb,
+                &command_input,
+                caller_role,
+                caller_actor_id,
+            ));
             mutations_per_step.push(Vec::new());
             cross_domain_per_step.push(Vec::new());
             reactions_per_step.push(Json::Array(Vec::new()));
             continue;
         }
 
-        let verb = match step.get("verb").and_then(Json::as_str) {
-            Some(v) => v,
-            None => return error_output("step missing \"verb\", \"dry_run\", or \"query\""),
+        let Some(verb) = step.get("verb").and_then(Json::as_str) else {
+            return error_output("step missing \"verb\", \"dry_run\", or \"query\"");
         };
 
         // Per-step `role:` stands in for Ruby's ambient `Hecks.as_caller`; passed to the top-level
@@ -306,19 +309,34 @@ pub fn run(input: &str) -> String {
     let refusals_json = Json::Array(
         refusals
             .iter()
-            .map(|(verb, r)| Json::obj(vec![("verb", Json::str(verb.clone())), ("error", Json::str(r.to_string())), ("kind", Json::str(r.kind().to_string()))]))
+            .map(|(verb, r)| {
+                Json::obj(vec![
+                    ("verb", Json::str(verb.clone())),
+                    ("error", Json::str(r.to_string())),
+                    ("kind", Json::str(r.kind().to_string())),
+                ])
+            })
             .collect(),
     );
     let mutations_json = Json::Array(
         mutations_per_step
             .iter()
-            .map(|step_mutations| Json::Array(step_mutations.iter().map(mutation_to_json).collect()))
+            .map(|step_mutations| {
+                Json::Array(step_mutations.iter().map(mutation_to_json).collect())
+            })
             .collect(),
     );
     let cross_domain_json = Json::Array(
         cross_domain_per_step
             .iter()
-            .map(|step_reactions| Json::Array(step_reactions.iter().map(cross_domain_reaction_to_json).collect()))
+            .map(|step_reactions| {
+                Json::Array(
+                    step_reactions
+                        .iter()
+                        .map(cross_domain_reaction_to_json)
+                        .collect(),
+                )
+            })
             .collect(),
     );
 
@@ -332,7 +350,10 @@ pub fn run(input: &str) -> String {
         ("cross_domain_reactions".to_string(), cross_domain_json),
         // Whole-run logs, not per-step.
         ("reactions".to_string(), Json::Array(reaction_log)),
-        ("reactions_per_step".to_string(), Json::Array(reactions_per_step)),
+        (
+            "reactions_per_step".to_string(),
+            Json::Array(reactions_per_step),
+        ),
         ("sagas".to_string(), Json::Array(saga_log)),
         // State at the end of the run, fed back as `"sagas"` next time; the `"sagas"` key above
         // is the transition log, including refused transitions.
@@ -343,11 +364,31 @@ pub fn run(input: &str) -> String {
 
 /// Evaluates a command against a throwaway copy of the store; `"error"` carries the refusal
 /// a real dispatch would have raised.
-fn dry_run(store: &Store, verb: &str, command_input: &Json, caller_role: Option<&str>, caller_actor_id: Option<&str>) -> Json {
+fn dry_run(
+    store: &Store,
+    verb: &str,
+    command_input: &Json,
+    caller_role: Option<&str>,
+    caller_actor_id: Option<&str>,
+) -> Json {
     let mut scratch = store.clone();
-    match dispatch_by_name(&mut scratch, verb, command_input, caller_role, caller_actor_id, &mut Vec::new()) {
-        Ok(_) => Json::obj(vec![("verb", Json::str(verb.to_string())), ("ok", Json::Bool(true))]),
-        Err(refusal) => Json::obj(vec![("verb", Json::str(verb.to_string())), ("ok", Json::Bool(false)), ("error", Json::str(refusal.to_string()))]),
+    match dispatch_by_name(
+        &mut scratch,
+        verb,
+        command_input,
+        caller_role,
+        caller_actor_id,
+        &mut Vec::new(),
+    ) {
+        Ok(_) => Json::obj(vec![
+            ("verb", Json::str(verb.to_string())),
+            ("ok", Json::Bool(true)),
+        ]),
+        Err(refusal) => Json::obj(vec![
+            ("verb", Json::str(verb.to_string())),
+            ("ok", Json::Bool(false)),
+            ("error", Json::str(refusal.to_string())),
+        ]),
     }
 }
 
@@ -365,14 +406,17 @@ fn tables() -> Tables<'static> {
     }
 }
 
+/// Saga instances by (saga, correlation id), as `serve` keeps them across steps.
+type SagaMap = HashMap<(String, String), SagaInstance>;
+
 /// `--serve` mode: one JSON step per stdin line, one answer per stdout line, store kept across
 /// lines. Beyond `verb` it takes `dry_run`, `snapshot`, `restore` and `instances` steps.
 pub fn serve(input: impl std::io::BufRead, mut output: impl std::io::Write) {
     let mut store = Store::new();
-    let mut sagas: HashMap<(String, String), SagaInstance> = HashMap::new();
+    let mut sagas = SagaMap::new();
     let mut reaction_log: Vec<Json> = Vec::new();
     let mut saga_log: Vec<Json> = Vec::new();
-    let mut snapshot: Option<(Store, HashMap<(String, String), SagaInstance>)> = None;
+    let mut snapshot: Option<(Store, SagaMap)> = None;
     let ok = || Json::obj(vec![("ok", Json::Bool(true))]);
 
     for line in input.lines() {
@@ -381,7 +425,10 @@ pub fn serve(input: impl std::io::BufRead, mut output: impl std::io::Write) {
             continue;
         }
         let answer = match Json::parse(&line) {
-            Err(e) => Json::obj(vec![("ok", Json::Bool(false)), ("error", Json::str(format!("invalid JSON: {e}")))]),
+            Err(e) => Json::obj(vec![
+                ("ok", Json::Bool(false)),
+                ("error", Json::str(format!("invalid JSON: {e}"))),
+            ]),
             Ok(step) => {
                 let empty_args = Json::Object(vec![]);
                 let args = step.get("args").unwrap_or(&empty_args);
@@ -395,15 +442,27 @@ pub fn serve(input: impl std::io::BufRead, mut output: impl std::io::Write) {
                     match &snapshot {
                         Some((s, g)) => {
                             store = s.clone();
-                            sagas = g.clone();
+                            sagas.clone_from(g);
                             ok()
                         }
-                        None => Json::obj(vec![("ok", Json::Bool(false)), ("error", Json::str("no snapshot to restore"))]),
+                        None => Json::obj(vec![
+                            ("ok", Json::Bool(false)),
+                            ("error", Json::str("no snapshot to restore")),
+                        ]),
                     }
                 } else if step.get("instances").is_some() {
-                    Json::obj(vec![("ok", Json::Bool(true)), ("instances", Json::Object(store.instances()))])
+                    Json::obj(vec![
+                        ("ok", Json::Bool(true)),
+                        ("instances", Json::Object(store.instances())),
+                    ])
                 } else if let Some(verb) = step.get("dry_run").and_then(Json::as_str) {
-                    dry_run(&store, verb, &dry_run_command_input(args), caller_role, caller_actor_id)
+                    dry_run(
+                        &store,
+                        verb,
+                        &dry_run_command_input(args),
+                        caller_role,
+                        caller_actor_id,
+                    )
                 } else if let Some(verb) = step.get("verb").and_then(Json::as_str) {
                     let mut events: Vec<Event> = Vec::new();
                     let outcome = orchestrate(
@@ -425,11 +484,26 @@ pub fn serve(input: impl std::io::BufRead, mut output: impl std::io::Write) {
                         &mut saga_log,
                     );
                     match outcome {
-                        Ok(()) => Json::obj(vec![("ok", Json::Bool(true)), ("events", Json::Array(events.iter().map(event_to_json).collect()))]),
-                        Err(refusal) => Json::obj(vec![("ok", Json::Bool(false)), ("error", Json::str(refusal.to_string()))]),
+                        Ok(()) => Json::obj(vec![
+                            ("ok", Json::Bool(true)),
+                            (
+                                "events",
+                                Json::Array(events.iter().map(event_to_json).collect()),
+                            ),
+                        ]),
+                        Err(refusal) => Json::obj(vec![
+                            ("ok", Json::Bool(false)),
+                            ("error", Json::str(refusal.to_string())),
+                        ]),
                     }
                 } else {
-                    Json::obj(vec![("ok", Json::Bool(false)), ("error", Json::str("step needs verb, dry_run, snapshot, restore, or instances"))])
+                    Json::obj(vec![
+                        ("ok", Json::Bool(false)),
+                        (
+                            "error",
+                            Json::str("step needs verb, dry_run, snapshot, restore, or instances"),
+                        ),
+                    ])
                 }
             }
         };
@@ -452,7 +526,10 @@ fn run_filter(store: &Store, filter: &Json) -> Result<Vec<Json>, Refusal> {
         .ok_or_else(|| Refusal::Fault(format!("unknown aggregate {aggregate:?}")))?;
 
     let matched = repository::filter_entries(entries, field, comparator, value);
-    Ok(matched.into_iter().map(|(id, record)| repository::row_json(id, record)).collect())
+    Ok(matched
+        .into_iter()
+        .map(|(id, record)| repository::row_json(id, record))
+        .collect())
 }
 
 fn required_str<'a>(filter: &'a Json, key: &str) -> Result<&'a str, Refusal> {
@@ -464,9 +541,45 @@ fn required_str<'a>(filter: &'a Json, key: &str) -> Result<&'a str, Refusal> {
 
 /// The `refusals` verb column for a refused ad hoc filter, which has no verb; tolerates
 /// missing or mistyped fields.
+/// The log entry for an answered `query` step. A question with a reference twin also carries
+/// `reference_rows`, the same rows because both come from one compiled path.
+fn answered_entry(question: &str, offered: &Json, rows: Json, with_reference: bool) -> Json {
+    let mut fields = vec![
+        ("query", Json::Str(question.to_string())),
+        ("args", offered.clone()),
+        ("rows", rows.clone()),
+    ];
+    if with_reference {
+        fields.push(("reference_rows", rows));
+    }
+    Json::obj(fields)
+}
+
+/// The log entry for a refused `query` step: `rows: null` and the refusal's text, with the
+/// reference twin's null rows and identical error when the question has one.
+fn refused_entry(question: &str, offered: &Json, refusal: &Refusal, with_reference: bool) -> Json {
+    let message = refusal.to_string();
+    let mut fields = vec![
+        ("query", Json::Str(question.to_string())),
+        ("args", offered.clone()),
+        ("rows", Json::Null),
+        ("error", Json::Str(message.clone())),
+    ];
+    if with_reference {
+        fields.push(("reference_rows", Json::Null));
+        fields.push(("reference_error", Json::Str(message)));
+    }
+    Json::obj(fields)
+}
+
 fn filter_label(filter: &Json) -> String {
     let field = |key: &str| filter.get(key).and_then(Json::as_str).unwrap_or("");
-    format!("filter {}.{} {}", field("aggregate"), field("field"), field("op"))
+    format!(
+        "filter {}.{} {}",
+        field("aggregate"),
+        field("field"),
+        field("op")
+    )
 }
 
 fn command_input<'a>(step: &'a Json, legacy_args: &'a Json) -> &'a Json {
@@ -544,7 +657,10 @@ fn event_to_json(event: &Event) -> Json {
         ("id", Json::str(event.id.clone())),
         ("payload", event.payload.clone()),
         // Key order matches Ruby's `Event#to_h`; `None` serialises as null.
-        ("occurred_at", event.occurred_at.clone().map(Json::Str).unwrap_or(Json::Null)),
+        (
+            "occurred_at",
+            event.occurred_at.clone().map_or(Json::Null, Json::Str),
+        ),
     ])
 }
 
@@ -573,8 +689,14 @@ mod routing_tests {
         let selected = command_input(&step, &legacy_args);
         let invocation = crate::kernel::CommandInvocation::from_json(selected).unwrap();
         assert_eq!(invocation.route(), None);
-        assert_eq!(invocation.facts().get("branch_code").and_then(Json::as_str), Some("DOWNTOWN"));
-        assert_eq!(invocation.facts().get("box_number").and_then(Json::as_i64), Some(12));
+        assert_eq!(
+            invocation.facts().get("branch_code").and_then(Json::as_str),
+            Some("DOWNTOWN")
+        );
+        assert_eq!(
+            invocation.facts().get("box_number").and_then(Json::as_i64),
+            Some(12)
+        );
     }
 
     // A domain fact named `to` must dry-run as a plain fact, never a routing attempt
@@ -591,11 +713,19 @@ mod routing_tests {
 
         assert_eq!(invocation.route(), None);
         assert_eq!(
-            invocation.facts().get("to").and_then(|to| to.get("value")).and_then(Json::as_i64),
+            invocation
+                .facts()
+                .get("to")
+                .and_then(|to| to.get("value"))
+                .and_then(Json::as_i64),
             Some(570)
         );
         assert_eq!(
-            invocation.facts().get("name").and_then(|name| name.get("value")).and_then(Json::as_str),
+            invocation
+                .facts()
+                .get("name")
+                .and_then(|name| name.get("value"))
+                .and_then(Json::as_str),
             Some("crew-1")
         );
     }