behavior-contracts 0.7.2 → 0.7.3

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

@@ -242,6 +242,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 +456,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 +564,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;
@@ -773,6 +803,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 +896,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)`;
@@ -1112,6 +1204,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 +1252,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 +1271,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;
@@ -1601,6 +1705,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,7 +2033,9 @@ ${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).
@@ -1904,6 +2139,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) = 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;