behavior-contracts 0.7.2 → 0.8.0

package/dist/generator/emit-typed-native-rust.js

@@ -178,13 +178,17 @@ function staticStringArrElems(node) {
  * Value-typed input) FAILS CLOSED — the covered read plane admits NO boxed escape (there is no `Value`
  * fallback on the native module). `where` names the emission site for the error.
  */
-function portFieldRustType(node, inputPorts, where = "port", asBinding, plan) {
+function portFieldRustType(node, inputPorts, where = "port", asBinding, plan, typedNodes) {
     if (staticStringArrElems(node) !== null)
         return "Vec<&'static str>";
     // #110: a componentRef port bound to a runtime array input port (with a resolvable elemType) → Vec<ElemT>.
     const arrElem = portArrayElemRef(node, inputPorts, plan);
     if (arrElem !== null)
         return `Vec<${renderTypeRef(arrElem)}>`;
+    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) → Vec<ElemT>.
+    const priorArr = priorNodeArrElemInfo(node, typedNodes, plan);
+    if (priorArr !== null)
+        return `Vec<${renderTypeRef(priorArr.elemRef)}>`;
     const num = numLiteralRustExpr(node);
     if (num !== null)
         return typeof node === "number" && Number.isInteger(node) ? "i64" : "f64";
@@ -201,13 +205,13 @@ function portFieldRustType(node, inputPorts, where = "port", asBinding, plan) {
  * reads `ports.f_<field>` DIRECTLY. The struct derives Clone (a bc#87 parallel stage clones it into the
  * per-worker dispatch). Every field is a NATIVE Rust type (bc#90 / runtime-free) — NO boxed `Value`.
  */
-function emitPortsStruct(comp, node, asBinding, plan) {
+function emitPortsStruct(comp, node, asBinding, plan, typedNodes) {
     const name = portsStructName(comp.name, node.id);
     const portNames = Object.keys(node.ports);
     if (portNames.length === 0) {
         return `// ${name} — native ports for node '${node.id}' (${node.component}); no ports.\n#[derive(Clone)]\npub struct ${name};`;
     }
-    const types = portNames.map((p) => portFieldRustType(node.ports[p], comp.inputPorts, `port '${p}' of node '${node.id}'`, asBinding, plan));
+    const types = portNames.map((p) => portFieldRustType(node.ports[p], comp.inputPorts, `port '${p}' of node '${node.id}'`, asBinding, plan, typedNodes));
     const fields = portNames
         .map((p, i) => `    pub ${portFieldName(p)}: ${types[i]}, // ${JSON.stringify(p)}`)
         .join("\n");
@@ -242,6 +246,22 @@ pub struct ${batch} {
     pub items: Vec<${name}>,
 }`;
 }
+/** emitFanoutPortsStructs (v3, rust twin) — per-id element ports struct + batch struct for a fanout node. */
+function emitFanoutPortsStructs(comp, node, typedNodes, plan) {
+    const f = node.fanout;
+    const name = portsStructName(comp.name, node.id);
+    const batch = `${name}Batch`;
+    const { elemRef } = fanoutOverElemInfo(comp, node, typedNodes, plan);
+    const asBinding = { name: f.as, ref: elemRef, plan };
+    const elemStruct = emitPortsStruct(comp, { id: node.id, component: f.component, ports: f.ports }, asBinding, plan);
+    return `${elemStruct}
+
+// ${batch} — CONCRETE batched ports for fanout '${node.id}': the Vec of per-id CONCRETE ports structs.
+#[derive(Clone)]
+pub struct ${batch} {
+    pub items: Vec<${name}>,
+}`;
+}
 // ── native expression compiler backend (#108) — cond `if` / map `when` / cond branches (Rust) ────────
 //
 // The runtime-free native expression compiler (native-expr.ts) mirrors run_behavior's cond/guard with
@@ -440,6 +460,13 @@ function emitRawRowStructs(comp, typedNodes, plan) {
         if ("cond" in n)
             continue; // #108: a cond node has no handler-result row (pure Expression).
         const ref = typedNodes.get(n.id);
+        if ("fanout" in n) {
+            const elemRowRef = fanoutItemsElemRef(n, ref, plan);
+            parts.push(emitOneRowStruct(rawElemStructName(comp.name, n.id), elemRowRef, plan));
+            parts.push(`// ${rawRowStructName(comp.name, n.id)} — the BATCH row for fanout '${n.id}': the aligned per-body rows.\n` +
+                `#[derive(Default)]\npub struct ${rawRowStructName(comp.name, n.id)} {\n    pub is_error: bool,\n    pub err: String,\n    pub rows: Vec<${rawElemStructName(comp.name, n.id)}>,\n}`);
+            continue;
+        }
         if ("map" in n) {
             const arrRef = ref;
             const elemRowRef = mapElemRowRef(n, arrRef, plan);
@@ -541,6 +568,13 @@ function emitHandlerTrait(comp, typedNodes, plan, ap) {
         const method = nodeMethodName(n.id);
         const fnKw = fnKwFor(n.id);
         const bt = boundRustType(n, typedNodes, plan);
+        if ("fanout" in n) {
+            // fanout (v3): one batched dispatch of the deduped id list — batch ports IN, aligned batch row OUT.
+            const portsT = `${portsStructName(comp.name, n.id)}Batch`;
+            const retT = rawRowStructName(comp.name, n.id);
+            lines.push(`    ${fnKw} ${method}(&self, ports: &${portsT}, bound: ${bt}) -> Option<${retT}>;`);
+            continue;
+        }
         if ("map" in n) {
             const m = n.map;
             const batched = m.batched === true;
@@ -651,6 +685,44 @@ function mapOverElemInfo(comp, node, typedNodes, plan) {
 function mapOverElemType(comp, node, typedNodes, plan) {
     return renderTypeRef(mapOverElemInfo(comp, node, typedNodes, plan).elemRef);
 }
+/**
+ * priorNodeArrElemInfo (#129, rust twin) — resolve a leaf port that is a `ref` into a PRIOR BODY NODE
+ * whose annotated `outType` is (or reaches, through a field path) a native array, to its element TypeRef
+ * + the OWNED Rust Vec expression that yields it. GENERALIZES the `map…over` prior-node-arr dataflow
+ * (mapOverElemInfo's first branch) to ANY leaf input port: a fold/dedup leaf whose `items` port is
+ * `{ref:["<priorNode>"]}` (or `.items` of a prior connection node) now lowers to `Vec<ElemT>` cloned
+ * out of the prior node's typed cell — ZERO boxed Value on the read hot path.
+ *
+ * The element type comes STRICTLY from the prior node's EXPLICIT `outType` annotation walked through
+ * typedFieldAccess (BC does NOT infer — consumer-interface C3 / [[graphddb-typed-native-static-link]]):
+ * if the head is not a prior body node, or its outType (through the field path) is not an `arr`, this
+ * returns null and the caller keeps its existing fail-closed behaviour (never a silent box). A
+ * single-segment INPUT-array port (elemType) is a DIFFERENT covered shape (portArrayElemRef) — handled
+ * ahead of this. Requires the typedNodes map (prior-node outType TypeRefs) and a TypePlan.
+ */
+function priorNodeArrElemInfo(node, typedNodes, plan) {
+    if (typedNodes === undefined || plan === undefined)
+        return null;
+    if (staticArrElems(node) !== null)
+        return null; // a static array literal — not a prior-node ref.
+    const e = classifyExpr(node);
+    if (e.kind !== "ref" || e.opt || e.path.length < 1)
+        return null;
+    if (!typedNodes.has(e.path[0]))
+        return null; // head is not a prior body node → not this shape.
+    const baseRef = typedNodes.get(e.path[0]);
+    let acc;
+    try {
+        acc = typedFieldAccess(`${typedCell(e.path[0])}.borrow()`, baseRef, e.path.slice(1), plan);
+    }
+    catch {
+        return null; // the field path does not resolve on the prior node's outType → fail-closed at caller.
+    }
+    if (acc.ref.kind !== "arr")
+        return null; // the prior-node result (through the path) is not an array.
+    // OWNED: clone the borrowed slice out of the RefCell so the ports struct owns its Vec<ElemT>.
+    return { elemRef: acc.ref.elem, overExpr: `${acc.expr}.clone()` };
+}
 // ── eligibility ─────────────────────────────────────────────────────────────────────
 function reconstructR(e) {
     switch (e.kind) {
@@ -773,6 +845,63 @@ function coveredMapNode(n, bodyIds, comp) {
             return false;
     return true;
 }
+/** coveredFanoutNode (v3, rust twin) — a first-class fanout node is covered when its over is a covered
+ * ref (prior-node arr / input array with elemType) and its element ports are static. See the go twin. */
+function coveredFanoutNode(n, bodyIds, comp) {
+    if (n === null || typeof n !== "object" || !("fanout" in n))
+        return false;
+    const f = n.fanout;
+    if (f.policy !== undefined && f.policy !== "fail")
+        return false;
+    if (f.relationKind !== "connection")
+        return false;
+    const overE = classifyExpr(f.over);
+    if (overE.kind !== "ref")
+        return false;
+    const head = overE.path[0];
+    if (!bodyIds.has(head)) {
+        if (overE.path.length !== 1)
+            return false;
+        const schema = comp.inputPorts?.[head];
+        if (schema === undefined || schema.elemType === undefined)
+            return false;
+    }
+    const ports = f.ports;
+    for (const p of Object.keys(ports))
+        if (!portIsStatic(ports[p]))
+            return false;
+    return true;
+}
+/** fanoutItemsElemRef (v3, rust twin) — the connection items element TypeRef for a covered fanout node. */
+function fanoutItemsElemRef(node, connRef, plan) {
+    if (connRef.kind !== "named")
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): node '${node.id}' outType must be a connection struct {items,cursor} (got ${JSON.stringify(connRef.kind)}).`);
+    const decl = findDecl(plan, connRef.name);
+    const itemsField = decl.fields.find((fd) => fd.name === "items");
+    if (!itemsField || itemsField.type.kind !== "arr")
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): node '${node.id}' connection struct '${connRef.name}' has no 'items' array field.`);
+    return itemsField.type.elem;
+}
+/** fanoutOverElemInfo (v3, rust twin) — the over id-list element TypeRef + the OWNED over-Vec expr. */
+function fanoutOverElemInfo(comp, node, typedNodes, plan) {
+    const f = node.fanout;
+    const e = classifyExpr(f.over);
+    if (e.kind === "ref" && e.path.length >= 1 && typedNodes.has(e.path[0])) {
+        const baseRef = typedNodes.get(e.path[0]);
+        const { ref } = typedFieldAccess(`${typedCell(e.path[0])}.borrow()`, baseRef, e.path.slice(1), plan);
+        if (ref.kind === "arr") {
+            const fieldPath = e.path.slice(1).map((p) => `.${rustFieldName(p)}`).join("");
+            return { elemRef: ref.elem, overExpr: `${typedCell(e.path[0])}.borrow()${fieldPath}.clone()` };
+        }
+    }
+    if (e.kind === "ref" && e.path.length === 1) {
+        const schema = comp.inputPorts?.[e.path[0]];
+        const et = schema?.elemType;
+        if (et !== undefined)
+            return { elemRef: deriveTypeRef(et, plan), overExpr: `in_.${rustFieldName(e.path[0])}.clone()` };
+    }
+    throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): fanout '${node.id}' 'over' must be a ref to a prior node's typed arr field OR an input array port with a declared elemType.`);
+}
 /** A covered read SHAPE with static ports + native-lowerable output (+ covered map...into), OR a
  * real-concurrency staged plan (bc#87) whose parallel-stage members are plain componentRef point reads. */
 function isSequentialComponentRefRead(comp) {
@@ -809,6 +938,11 @@ function coverageRejectReason(comp) {
                 return `node '${n.id}' cond has no outType (required to de-box the branch join)`;
             continue;
         }
+        if ("fanout" in n) {
+            if (!coveredFanoutNode(n, bodyIds, comp))
+                return `node '${n.id}' is a non-covered fanout shape (over an input array without elemType, or a dynamic element port)`;
+            continue;
+        }
         if ("map" in n) {
             if (!coveredMapNode(n, bodyIds, comp))
                 return `node '${n.id}' is a non-covered map shape (guard+into heterogeneous, or over an input array without elemType)`;
@@ -977,7 +1111,7 @@ function emitNativeScalar(node, want, resolveRef) {
  * a boxed escape would re-introduce the bc-runtime coupling this module removes). `fieldRustType` is the
  * ports-struct field type (from portFieldRustType); `resolveRef` resolves a ref head for the scalar path.
  */
-function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan) {
+function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan, typedNodes) {
     const field = portFieldName(pn);
     // #110: a componentRef port bound to a runtime array input port (with elemType) → the native Vec<ElemT>,
     // cloned out of the concrete input struct (`in_.<field>.clone()`) — ZERO boxed Value on the read hot path.
@@ -987,6 +1121,12 @@ function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan) {
             return `${field}: in_.${rustFieldName(e.path[0])}.clone()`;
         }
     }
+    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) →
+    // the native Vec<ElemT> cloned off the prior node's typed cell (`t_<node>.borrow().field….clone()`) —
+    // ZERO boxed Value on the read hot path (a fold/dedup leaf whose `items` = a prior node's array result).
+    const priorArr = priorNodeArrElemInfo(expr, typedNodes, plan);
+    if (priorArr !== null)
+        return `${field}: ${priorArr.overExpr}`;
     // change #2: a static string array (projection) → a native `vec![...]` of &'static str.
     const strArr = staticStringArrElems(expr);
     if (strArr !== null) {
@@ -1112,6 +1252,14 @@ function emitNativeRawRunner(comp, plan, ap) {
         };
         return [...order.keys()].some((k) => {
             const nd = comp.body[order[k]];
+            if ("fanout" in nd) {
+                const fo = nd.fanout;
+                const bound = new Set([fo.as]);
+                // the fanout's OVER is evaluated in the outer scope (may read input); ports in element scope.
+                if (walk(fo.over, k, new Set()))
+                    return true;
+                return Object.values(fo.ports).some((pn) => walk(pn, k, bound));
+            }
             if ("map" in nd) {
                 const m = nd.map;
                 const bound = new Set([m.as]);
@@ -1152,7 +1300,7 @@ function emitNativeRawRunner(comp, plan, ap) {
     // default emits `pub fn` exactly as before (byte-identical).
     const fnKw = isAsync ? "pub async fn" : "pub fn";
     // #108: a component whose body is ALL cond nodes dispatches NO handler — bind `_handlers` (clippy-clean).
-    const dispatchesHandler = comp.body.some((n) => "map" in n || "component" in n);
+    const dispatchesHandler = comp.body.some((n) => "map" in n || "fanout" in n || "component" in n);
     lines.push(`${fnKw} run_native_raw_struct_${fn}${bound}(`);
     lines.push(`    ${dispatchesHandler ? "handlers" : "_handlers"}: &H,`);
     lines.push(`    ${inParam}: ${inStructName(comp.name)},`);
@@ -1171,6 +1319,10 @@ function emitNativeRawRunner(comp, plan, ap) {
             k += stage.length - 1;
             continue;
         }
+        if ("fanout" in comp.body[i]) {
+            lines.push(emitFanoutArm(comp, comp.body[i], k, typedNodes, plan, priorNodeAt, ap.nodeIsAsync(comp.body[i].id)));
+            continue;
+        }
         if ("map" in comp.body[i]) {
             lines.push(emitMapArm(comp, comp.body[i], k, typedNodes, plan, priorNodeAt, ap.nodeIsAsync(comp.body[i].id)));
             continue;
@@ -1219,8 +1371,8 @@ function emitNativeRawRunner(comp, plan, ap) {
         const inits = [];
         for (const pn of portNames) {
             const expr = node.ports[pn];
-            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan);
-            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan));
+            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
+            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan, typedNodes));
         }
         const boundArg = node.bindField !== undefined ? `bound_${s}` : "None";
         // bc#97: derived per-node await — this point-read's future is awaited HERE (its result-consumption
@@ -1325,8 +1477,8 @@ function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes
         const inits = [];
         for (const pn of Object.keys(node.ports)) {
             const expr = node.ports[pn];
-            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan);
-            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan));
+            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
+            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan, typedNodes));
         }
         if (gated) {
             lines.push(`${ind}ports_${s} = Some(${structName} { ${inits.join(", ")} });`);
@@ -1601,6 +1753,135 @@ isAsync = false) {
         lines.push(c);
     return lines.join("\n");
 }
+/**
+ * emitFanoutArm (v3, rust twin) — the struct-native exec of a covered FANOUT node: build the per-id
+ * ports (all over ids), dispatch the batched handler ONCE (aligned per-body rows), then apply THE SAME
+ * dedupe/drop as run_behavior's fanoutDedupDrop — first-seen dedupe by the elem's dedupeKey field, drop
+ * dangling (empty dedupeKey ≡ the interpreter's null/absent-key body), implicitSource strip (STRUCTURAL:
+ * the elem type already omits it), wrap into the connection struct { items, cursor: None }.
+ */
+function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, isAsync = false) {
+    const f = node.fanout;
+    const awaitSfx = isAsync ? ".await" : "";
+    const s = sanitize(node.id);
+    const structName = portsStructName(comp.name, node.id);
+    const batch = `${structName}Batch`;
+    const connRef = typedNodes.get(node.id);
+    const elemRef = fanoutItemsElemRef(node, connRef, plan);
+    const elemName = renderTypeRef(elemRef);
+    const { elemRef: overElemRef, overExpr } = fanoutOverElemInfo(comp, node, typedNodes, plan);
+    const asName = f.as;
+    const priorHere = (head) => priorNodeAt(head, atPos);
+    const portNames = Object.keys(f.ports);
+    if (elemRef.kind !== "named")
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): node '${node.id}' connection items element must be a named struct (got ${JSON.stringify(elemRef.kind)}).`);
+    const elemDecl = findDecl(plan, elemRef.name);
+    const dkField = elemDecl.fields.find((fd) => fd.name === f.dedupeKey);
+    if (!dkField || dkField.type.kind !== "scalar" || dkField.type.scalar !== "string")
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): node '${node.id}' dedupeKey '${f.dedupeKey}' must be a string field of the connection items element type '${elemRef.name}'.`);
+    const dkRust = rustFieldName(f.dedupeKey);
+    const resolveRef = (head, restPath, opt) => {
+        if (opt)
+            return null;
+        let baseExpr;
+        let baseRef;
+        if (head === asName) {
+            baseExpr = `oel_${s}`;
+            baseRef = overElemRef;
+        }
+        else if (priorHere(head)) {
+            baseExpr = `${typedCell(head)}.borrow()`;
+            baseRef = typedNodes.get(head);
+        }
+        else {
+            if (restPath.length !== 0)
+                return null;
+            const scalar = inputScalarKind(comp.inputPorts?.[head]);
+            if (scalar === undefined)
+                return null;
+            const field = `in_.${rustFieldName(head)}`;
+            return { expr: scalar === "String" ? `${field}.clone()` : field, scalar };
+        }
+        let acc;
+        let expr;
+        try {
+            const r = typedFieldAccess(baseExpr, baseRef, restPath, plan);
+            expr = r.expr;
+            acc = r.ref;
+        }
+        catch {
+            return null;
+        }
+        if (acc.kind !== "scalar" || acc.scalar === "null")
+            return null;
+        const isBareRef = restPath.length === 0;
+        let owned;
+        if (acc.scalar === "string")
+            owned = isBareRef ? `(*${expr}).clone()` : `${expr}.clone()`;
+        else
+            owned = isBareRef ? `*${expr}` : expr;
+        return { expr: owned, scalar: rustScalar(acc.scalar) };
+    };
+    const buildPorts = (il) => {
+        const inits = [];
+        const asBinding = { name: asName, ref: overElemRef, plan };
+        for (const pn of portNames) {
+            const ty = portFieldRustType(f.ports[pn], comp.inputPorts, `fanout port '${pn}' of node '${node.id}'`, asBinding, plan);
+            inits.push(emitPortInit(pn, f.ports[pn], ty, resolveRef, comp.inputPorts, plan));
+        }
+        return [`${il}let ep_${s} = ${structName} { ${inits.join(", ")} };`];
+    };
+    const lines = [];
+    const closers = [];
+    lines.push(`    // ── fanout '${node.id}' (${f.component}, dedupeKey:${JSON.stringify(f.dedupeKey)}, drop:${JSON.stringify(f.drop)}${f.implicitSource ? ", implicitSource:" + JSON.stringify(f.implicitSource) : ""}${f.parent ? ", parent:" + f.parent : ""}) ──`);
+    let indent = "    ";
+    if (f.parent !== undefined && priorNodeAt(f.parent, atPos)) {
+        lines.push(`${indent}if produced_${sanitize(f.parent)}.get() {`);
+        closers.unshift(`${indent}}`);
+        indent += "    ";
+    }
+    lines.push(`${indent}let over_${s} = ${overExpr};`);
+    lines.push(`${indent}let mut built_${s}: Vec<${elemName}> = Vec::new();`);
+    lines.push(`${indent}let mut pi_${s}: Vec<${structName}> = Vec::with_capacity(over_${s}.len());`);
+    lines.push(`${indent}for oel_${s} in over_${s}.iter() {`);
+    for (const l of buildPorts(indent + "    "))
+        lines.push(l);
+    lines.push(`${indent}    pi_${s}.push(ep_${s});`);
+    lines.push(`${indent}}`);
+    lines.push(`${indent}if !pi_${s}.is_empty() {`);
+    lines.push(`${indent}    let want_${s} = pi_${s}.len();`);
+    lines.push(`${indent}    let bp_${s} = ${batch} { items: pi_${s} };`);
+    lines.push(`${indent}    let row_${s} = match handlers.${nodeMethodName(node.id)}(&bp_${s}, None)${awaitSfx} {`);
+    lines.push(`${indent}        Some(r) => r,`);
+    lines.push(`${indent}        None => return Err(unknown_component(${rustStrLit(f.component)})),`);
+    lines.push(`${indent}    };`);
+    lines.push(`${indent}    if row_${s}.is_error {`);
+    lines.push(`${indent}        return Err(BehaviorError::new("OP_FAILED", format!("operation '{}' failed under 'fail' policy: {}", ${rustStrLit(node.id)}, row_${s}.err)));`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    if row_${s}.rows.len() != want_${s} {`);
+    lines.push(`${indent}        return Err(BehaviorError::new("FANOUT_BATCH_RESULT_MISMATCH", format!("fanout '{}': batched handler must return a list aligned to the deduped id list (want {})", ${rustStrLit(node.id)}, want_${s})));`);
+    lines.push(`${indent}    }`);
+    // ── THE ONE dedupe/drop (mirrors fanoutDedupDrop verbatim): first-seen dedupe by dedupeKey field;
+    //    drop dangling (empty dedupeKey ≡ interpreter's null/absent-key body); implicitSource strip is
+    //    structural (the elem type already omits it). cursor is always None (connection wrap).
+    lines.push(`${indent}    let mut seen_${s}: std::collections::HashSet<String> = std::collections::HashSet::new();`);
+    lines.push(`${indent}    for er_${s} in row_${s}.rows.into_iter() {`);
+    lines.push(`${indent}        ${emitElemMove(`let el_${s}`, `er_${s}`, elemRef, plan)}`);
+    lines.push(`${indent}        let key_${s} = el_${s}.${dkRust}.clone();`);
+    if (f.drop === "dangling") {
+        lines.push(`${indent}        if key_${s}.is_empty() { continue; }`);
+    }
+    lines.push(`${indent}        if seen_${s}.contains(&key_${s}) { continue; }`);
+    lines.push(`${indent}        seen_${s}.insert(key_${s});`);
+    lines.push(`${indent}        built_${s}.push(el_${s});`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}}`);
+    lines.push(`${indent}*${typedCell(node.id)}.borrow_mut() = ${connRef.name} { ${rustFieldName("items")}: built_${s}, ..Default::default() };`);
+    lines.push(`${indent}produced_${sanitize(node.id)}.set(true);`);
+    for (const c of closers)
+        lines.push(c);
+    return lines.join("\n");
+}
 /** #108: resolve an INPUT port head for a native-expr ref (rust). Scalar → `in_.<field>` (owned: String
  * cloned, Copy as-is); array WITH elemType → `in_.<field>.clone()` of Vec<ElemT> (for `len`); else null. */
 function rustInputHeadRef(head, comp, plan) {
@@ -1800,13 +2081,15 @@ ${emitStructSurface([])}
         for (const n of c.body)
             typedNodes.set(n.id, deriveTypeRef(n.outType, plan));
         for (const n of c.body) {
-            if ("map" in n)
+            if ("fanout" in n)
+                structs.push(emitFanoutPortsStructs(c, n, typedNodes, plan));
+            else if ("map" in n)
                 structs.push(emitMapPortsStructs(c, n, typedNodes, plan));
             else if ("cond" in n) {
                 // #108: a cond node has NO ports struct (pure Expression — no handler dispatch).
             }
             else
-                structs.push(emitPortsStruct(c, n, undefined, plan));
+                structs.push(emitPortsStruct(c, n, undefined, plan, typedNodes)); // #129: typedNodes for prior-node arr leaf ports.
         }
         rowStructs.push(emitRawRowStructs(c, typedNodes, plan));
         handlerTraits.push(emitHandlerTrait(c, typedNodes, plan, asyncPlans.get(c.name)));
@@ -1904,6 +2187,34 @@ export function rustTypedNativeObserve(ir, ioModel = "sync") {
             // bc#90 / runtime-free: the scripted impl's `_bound` param mirrors the trait's typed produced-aware
             // Option<K> (NOT a boxed Value) — computed per node so the impl signature matches the trait.
             const bt = boundRustType(n, typedNodes, plan);
+            if ("fanout" in n) {
+                // v3: scripted fanout impl — drain one batched outcome, decode the aligned array into per-body
+                // elem rows (a null array element decodes to the zero elem row = dangling → dropped by the arm).
+                const f = n.fanout;
+                const elemRowRef = fanoutItemsElemRef(n, ref, plan);
+                const elemT = rawElemStructName(c.name, n.id);
+                const batchT = rawRowStructName(c.name, n.id);
+                const elemDecode = emitDecodeRow(c.name, n.id, elemT, elemRowRef, plan, emittedDecode, decodeFns, "Elem");
+                const portsT = `${portsStructName(c.name, n.id)}Batch`;
+                methods.push(`    ${fnKw} ${nodeMethodName(n.id)}(&self, _ports: &${portsT}, _bound: ${bt}) -> Option<${batchT}> {
+        let (is_err, err, ok, _echo) = self.next(${rustStrLit(f.component)})?;
+        if is_err {
+            return Some(${batchT} { is_error: true, err, ..Default::default() });
+        }
+        let arr = match ok { Some(Value::Arr(a)) => a, _ => Vec::new() };
+        // v3: a null aligned body is a DANGLING id — decode it to the zero elem row (whose dedupeKey
+        // field is empty), so the runner's dangling-drop excludes it (byte-equal to fanoutDedupDrop).
+        let rows = arr
+            .iter()
+            .map(|ev| match ev {
+                Value::Null => ${elemT}::default(),
+                _ => ${elemDecode}(ev),
+            })
+            .collect();
+        Some(${batchT} { rows, ..Default::default() })
+    }`);
+                continue;
+            }
             if ("map" in n) {
                 const m = n.map;
                 const batched = m.batched === true;
@@ -1916,7 +2227,7 @@ export function rustTypedNativeObserve(ir, ioModel = "sync") {
                 const retT = batched ? batchT : elemT;
                 if (batched) {
                     methods.push(`    ${fnKw} ${nodeMethodName(n.id)}(&self, _ports: &${portsT}, _bound: ${bt}) -> Option<${batchT}> {
-        let (is_err, err, ok) = self.next(${rustStrLit(m.component)})?;
+        let (is_err, err, ok, _echo) = self.next(${rustStrLit(m.component)})?;
         if is_err {
             return Some(${batchT} { is_error: true, err, ..Default::default() });
         }
@@ -1927,7 +2238,7 @@ export function rustTypedNativeObserve(ir, ioModel = "sync") {
                 }
                 else {
                     methods.push(`    ${fnKw} ${nodeMethodName(n.id)}(&self, _ports: &${portsT}, _bound: ${bt}) -> Option<${elemT}> {
-        let (is_err, err, ok) = self.next(${rustStrLit(m.component)})?;
+        let (is_err, err, ok, _echo) = self.next(${rustStrLit(m.component)})?;
         if is_err {
             return Some(${elemT} { is_error: true, err, ..Default::default() });
         }
@@ -1941,11 +2252,22 @@ export function rustTypedNativeObserve(ir, ioModel = "sync") {
             const node = n;
             const rowT = rawRowStructName(c.name, node.id);
             const decode = emitDecodeRow(c.name, node.id, rowT, ref, plan, emittedDecode, decodeFns, "");
-            methods.push(`    ${fnKw} ${nodeMethodName(node.id)}(&self, _ports: &${portsStructName(c.name, node.id)}, _bound: ${bt}) -> Option<${rowT}> {
-        let (is_err, err, ok) = self.next(${rustStrLit(node.component)})?;
+            // #129 (TEST glue): if this node has an `items` port and its outType is a bare arr, support the
+            // reference scriptedHandlers' `echo === "items"` — the scripted handler ECHOES the NATIVE `f_items`
+            // port back as its result. This makes the node→leaf array dataflow test non-vacuous: the leaf's
+            // observed result is exactly the native array that flowed into its ports struct, so a dropped or
+            // boxed native array would diverge from run_behavior. `ports` is bound only on the echo path.
+            const canEcho = ref.kind === "arr" && Object.prototype.hasOwnProperty.call(node.ports, "items");
+            const portsParam = canEcho ? "ports" : "_ports";
+            const echoBranch = canEcho
+                ? `\n        if echo == "items" {\n            return Some(${rowT} { val: ${portsParam}.${portFieldName("items")}.clone(), ..Default::default() });\n        }`
+                : "";
+            const okBind = canEcho ? "(is_err, err, ok, echo)" : "(is_err, err, ok, _echo)";
+            methods.push(`    ${fnKw} ${nodeMethodName(node.id)}(&self, ${portsParam}: &${portsStructName(c.name, node.id)}, _bound: ${bt}) -> Option<${rowT}> {
+        let ${okBind} = self.next(${rustStrLit(node.component)})?;
         if is_err {
             return Some(${rowT} { is_error: true, err, ..Default::default() });
-        }
+        }${echoBranch}
         let v = ok.unwrap_or(Value::Null);
         Some(${decode}(&v))
     }`);
@@ -2000,19 +2322,22 @@ impl ScriptedNativeRaw {
 
     // drain one scripted outcome for a component (last entry repeats — mirrors the reference scripted
     // handlers); None when the component has no scripted queue (fail-closed). Returns (is_error, err,
-    // ok_value). The bc#87 parallel-stage runner calls node_* from multiple threads, so the drain is
-    // Mutex-guarded.
-    fn next(&self, component: &str) -> Option<(bool, String, Option<Value>)> {
+    // ok_value, echo). The bc#87 parallel-stage runner calls node_* from multiple threads, so the drain
+    // is Mutex-guarded. #129: \`echo\` carries the reference scriptedHandlers' \`echo\` directive (e.g.
+    // "items") so a scripted node can ECHO a named input PORT back — used to make the node→leaf array
+    // dataflow test non-vacuous (the leaf returns its \`items\` port; a dropped/boxed array diverges).
+    fn next(&self, component: &str) -> Option<(bool, String, Option<Value>, String)> {
         self.seen.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
         let mut queues = self.queues.lock().unwrap();
         let (queue, single) = queues.get_mut(component)?;
         let raw = if *single || queue.len() <= 1 { queue[0].clone() } else { queue.remove(0) };
+        let echo = raw.get("echo").and_then(|e| e.as_str()).unwrap_or("").to_string();
         if let Some(okv) = raw.get("ok") {
             let v = behavior_contracts::decode_value(okv).expect("decode ok");
-            Some((false, String::new(), Some(v)))
+            Some((false, String::new(), Some(v), echo))
         } else {
             let e = raw.get("error").and_then(|e| e.as_str()).unwrap_or("").to_string();
-            Some((true, e, None))
+            Some((true, e, None, echo))
         }
     }
 }`;
@@ -2179,6 +2504,7 @@ function emitDecodeRow(compName, nodeId, rowT, ref, plan, emitted, out, suffix)
 }
 export const rustTypedNativeEmitter = {
     language: "rust-typed-native",
+    classification: "codegen", // native: 型付きフラットコード生成・IR/dict 非在（#128/A6）
     fileExtension: ".rs",
     defaultRuntimeImport: "behavior_contracts",
     filenameHint: "behaviors_typed_native_generated.rs",