feat(alerts): emit canonical node paths in describe

Every node in describe's tree now carries its path (the same canonical form
leaf_paths emits). A sustained node's path equals the key the engine stores its
timer under (condition_timers.path) - root is kind.wire(), the engine's own
timer-path root, and children use the shared core child_path - so a host joins
a duration node straight to its persisted first-true instant for a live
11-of-15-minute countdown without re-deriving paths itself.

Leaf-id assignment and the container-unwrap guards are unchanged. Adds a test
pinning the emitted paths against the timer-key form.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ryceg

crates/nocturne-alerts-ffi/README.md

@@ -299,18 +299,25 @@ Response — a recursive `tree`:
   "ok": true,
   "tree": {
     "type": "composite",
+    "path": "composite",
     "operator": "and",                       // and | or (null if unset)
     "conditions": [
-      { "leaf_id": 0, "type": "threshold", "kind": "threshold",
+      { "leaf_id": 0, "path": "composite[0].threshold",
+        "type": "threshold", "kind": "threshold",
         "params": { "direction": "below", "value": 80 } },
-      { "type": "sustained", "minutes": 15,  // container: no leaf_id, carries duration
-        "child": { "leaf_id": 1, "type": "iob", "kind": "iob",
+      { "type": "sustained", "path": "composite[1].sustained", "minutes": 15,
+        "child": { "leaf_id": 1, "path": "composite[1].sustained[0].iob",
+                   "type": "iob", "kind": "iob",
                    "params": { "operator": "<", "value": 1 } } }
     ]
   }
 }
 ```
 
+- Every node carries its canonical `path` (the same form `leaf_paths` emits). A
+  `sustained` node's `path` equals the key the engine stores its timer under
+  (`condition_timers.path`), so a host joins a duration node straight to its
+  persisted first-true instant for a "11 of 15 min" countdown.
 - **Containers** (`composite`, `not`, `sustained`) carry structure only —
   `operator` / `minutes` / nested `conditions`/`child` — and **no `leaf_id`**.
 - **Leaves** carry `leaf_id`, the verbatim `type`, the resolved canonical

crates/nocturne-alerts-ffi/src/envelope.rs

@@ -556,8 +556,12 @@ pub fn describe(request_json: &str) -> Result<Value, String> {
     };
     let full_node = Node::from_rule(kind, payload);
 
+    // Root path is the kind's wire name — the same root the engine keys timers
+    // and leaf paths under, so a host joins a sustained node's `path` straight
+    // to its persisted timer (`condition_timers.path`).
+    let root_path = kind.wire().to_string();
     let mut next_leaf_id = 0;
-    let tree = describe_node(Some(&full_node), &mut next_leaf_id);
+    let tree = describe_node(Some(&full_node), root_path, &mut next_leaf_id);
 
     Ok(json!({
         "schema_version": SCHEMA_VERSION,
@@ -572,11 +576,11 @@ pub fn describe(request_json: &str) -> Result<Value, String> {
 /// child/conditions list is missing — is a leaf and takes the next id. A
 /// JSON-null composite slot is a typeless leaf, exactly as the engine
 /// force-evaluates it to `false`.
-fn describe_node(node: Option<&Node>, next_leaf_id: &mut i32) -> Value {
+fn describe_node(node: Option<&Node>, path: String, next_leaf_id: &mut i32) -> Value {
     let Some(node) = node else {
         let id = *next_leaf_id;
         *next_leaf_id += 1;
-        return leaf_value(id, Value::Null, Value::Null, Value::Null);
+        return leaf_value(id, path, Value::Null, Value::Null, Value::Null);
     };
     let lower = node.type_str.as_deref().map(str::to_lowercase);
     match lower.as_deref() {
@@ -586,10 +590,16 @@ fn describe_node(node: Option<&Node>, next_leaf_id: &mut i32) -> Value {
             {
                 let conditions: Vec<Value> = children
                     .iter()
-                    .map(|c| describe_node(c.as_ref(), next_leaf_id))
+                    .enumerate()
+                    .map(|(i, c)| {
+                        let cp =
+                            child_path(&path, i, c.as_ref().and_then(|n| n.type_str.as_deref()));
+                        describe_node(c.as_ref(), cp, next_leaf_id)
+                    })
                     .collect();
                 return json!({
                     "type": "composite",
+                    "path": path,
                     "operator": opt_str(&p.operator),
                     "conditions": conditions,
                 });
@@ -599,20 +609,24 @@ fn describe_node(node: Option<&Node>, next_leaf_id: &mut i32) -> Value {
             if let Some(Payload::Not(p)) = node.payload("not")
                 && let Some(child) = &p.child
             {
+                let cp = child_path(&path, 0, child.type_str.as_deref());
                 return json!({
                     "type": "not",
-                    "child": describe_node(Some(child), next_leaf_id),
+                    "path": path,
+                    "child": describe_node(Some(child), cp, next_leaf_id),
                 });
             }
         }
         Some("sustained") => {
             if let Some(Payload::Sustained(p)) = node.payload("sustained")
                 && let Some(child) = &p.child
             {
+                let cp = child_path(&path, 0, child.type_str.as_deref());
                 return json!({
                     "type": "sustained",
+                    "path": path,
                     "minutes": p.minutes,
-                    "child": describe_node(Some(child), next_leaf_id),
+                    "child": describe_node(Some(child), cp, next_leaf_id),
                 });
             }
         }
@@ -643,14 +657,14 @@ fn describe_node(node: Option<&Node>, next_leaf_id: &mut i32) -> Value {
                 Some(p) => payload_json(p),
                 None => payload_json(&default_payload(k)),
             };
-            leaf_value(id, type_value, Value::String(k.wire().to_string()), params)
+            leaf_value(id, path, type_value, Value::String(k.wire().to_string()), params)
         }
-        None => leaf_value(id, type_value, Value::Null, Value::Null),
+        None => leaf_value(id, path, type_value, Value::Null, Value::Null),
     }
 }
 
-fn leaf_value(leaf_id: i32, type_value: Value, kind: Value, params: Value) -> Value {
-    json!({ "leaf_id": leaf_id, "type": type_value, "kind": kind, "params": params })
+fn leaf_value(leaf_id: i32, path: String, type_value: Value, kind: Value, params: Value) -> Value {
+    json!({ "leaf_id": leaf_id, "path": path, "type": type_value, "kind": kind, "params": params })
 }
 
 fn opt_str(s: &Option<String>) -> Value {

crates/nocturne-alerts-ffi/src/tests.rs

@@ -782,6 +782,32 @@ fn describe_composite_preserves_structure_and_sustained_minutes() {
     assert_eq!(conds[1]["child"]["kind"], json!("iob"));
 }
 
+#[test]
+fn describe_emits_paths_that_match_timer_keys() {
+    // Every node carries its canonical path; a sustained node's path equals the
+    // key the engine stores its timer under (`condition_timers.path`), so the
+    // host joins a duration node straight to its persisted first-true instant.
+    let params = json!({
+        "operator": "and",
+        "conditions": [
+            { "type": "threshold", "threshold": { "direction": "below", "value": 80 } },
+            {
+                "type": "sustained",
+                "sustained": {
+                    "minutes": 15,
+                    "child": { "type": "iob", "iob": { "operator": "<", "value": 1 } }
+                }
+            }
+        ]
+    });
+    let tree = describe_rule("composite", params);
+    assert_eq!(tree["path"], json!("composite"));
+    assert_eq!(tree["conditions"][0]["path"], json!("composite[0].threshold"));
+    let sustained = &tree["conditions"][1];
+    assert_eq!(sustained["path"], json!("composite[1].sustained"));
+    assert_eq!(sustained["child"]["path"], json!("composite[1].sustained[0].iob"));
+}
+
 #[test]
 fn describe_leaf_ids_align_with_evaluate_force_eval_log() {
     // The whole point of `describe`: its leaf ids must match `evaluate`'s