behavior-contracts 0.7.2 → 0.8.0

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

@@ -119,13 +119,17 @@ function staticStringArrElems(node) {
  * Value-typed input) FAILS CLOSED — the covered read plane admits NO boxed escape (there is no
  * `dslcontracts.Value` fallback on the native module). `where` names the emission site for the error.
  */
-function portFieldGoType(node, inputPorts, where = "port", asBinding, plan) {
+function portFieldGoType(node, inputPorts, where = "port", asBinding, plan, typedNodes) {
     if (staticStringArrElems(node) !== null)
         return "[]string";
     // #110: a componentRef port bound to a runtime array input port (with a resolvable elemType) → []ElemT.
     const arrElem = portArrayElemRef(node, inputPorts, plan);
     if (arrElem !== null)
         return `[]${renderTypeRef(arrElem)}`;
+    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) → []ElemT.
+    const priorArr = priorNodeArrElemInfo(node, typedNodes, plan);
+    if (priorArr !== null)
+        return `[]${renderTypeRef(priorArr.elemRef)}`;
     const num = numLiteralGoExpr(node);
     if (num !== null)
         return Number.isInteger(node) ? "int64" : "float64";
@@ -322,6 +326,39 @@ function coveredMapNode(n, bodyIds, comp) {
             return false;
     return true;
 }
+/**
+ * coveredFanoutNode (v3) — a FANOUT node (first-class `@refs` id-list fan-out) is covered when:
+ *   - over is a static ref to a PRIOR BODY NODE's typed arr field OR an INPUT array port with elemType,
+ *   - every element port is static (literal / ref into the $as binding / concat / static arr),
+ *   - default 'fail' policy, relationKind connection (guard-checked by the guard/builder).
+ * The fanout de-boxes to: one deduped batched dispatch → first-seen dedupe (by the elem's dedupeKey
+ * field) + dangling drop + implicitSource strip + connection wrap {items, cursor:nil} — NO boxed Value.
+ */
+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;
+}
 /** A covered read SHAPE (typing-independent) — sequential componentRef reads + covered map...into,
  * OR a real-concurrency staged plan (bc#87) whose parallel-stage members are plain componentRef point
  * reads. A real-concurrency plan whose parallel members include a map / bindField-relation child is
@@ -366,6 +403,13 @@ function coverageRejectReason(comp) {
                 return `node '${n.id}' cond has no outType (required to de-box the branch join)`;
             continue;
         }
+        if ("fanout" in n) {
+            // v3: a first-class fanout node (deduped connection list-in fan-out) IS covered when its over is a
+            // covered ref (prior-node arr / input array with elemType) and its element ports are static.
+            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) {
             // #86 pt2 batched map...into / #93 shape 2/3 / #108 guarded map (no into) / map-over-input (with
             // elemType) ARE covered. A non-covered map shape (guard+into heterogeneous / over-input without
@@ -412,13 +456,13 @@ function assertTypedCoverage(comp) {
     throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#77): component '${comp.name}' is a sequential componentRef read but lacks outType/outputType on every node — the combined emitter de-boxes the RESULT into the node's outType struct, so a covered read MUST be fully typed (bc#45). Add outType annotations, or regenerate on go-straightline-native (boxed result).`);
 }
 // ── native ports struct + PortReader ──────────────────────────────────────────────────
-function emitPortsStruct(comp, node, asBinding, plan) {
+function emitPortsStruct(comp, node, asBinding, plan, typedNodes) {
     const structName = portsStructName(comp.name, node.id);
     const portNames = Object.keys(node.ports);
     if (portNames.length === 0) {
         return `// ${structName} — native ports for node '${node.id}' (${node.component}); no ports.\ntype ${structName} struct{}`;
     }
-    const fieldTypes = portNames.map((p) => portFieldGoType(node.ports[p], comp.inputPorts, `port '${p}' of node '${node.id}'`, asBinding, plan));
+    const fieldTypes = portNames.map((p) => portFieldGoType(node.ports[p], comp.inputPorts, `port '${p}' of node '${node.id}'`, asBinding, plan, typedNodes));
     const fieldNames = portNames.map(goPortFieldName);
     const fields = portNames
         .map((p, i) => `\t${fieldNames[i]} ${fieldTypes[i]} // ${JSON.stringify(p)}`)
@@ -486,6 +530,15 @@ function emitRawRowStructs(comp, typedNodes, plan) {
         if ("cond" in n)
             continue;
         const ref = typedNodes.get(n.id);
+        if ("fanout" in n) {
+            // a covered fanout node: RawElem_ is the connection items element (the per-body row the batched
+            // handler yields, aligned to the deduped id list); the batch RawRow_ carries the aligned []RawElem_.
+            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` +
+                `type ${rawRowStructName(comp.name, n.id)} struct {\n\tIsError bool\n\tErr     string\n\tRows    []${rawElemStructName(comp.name, n.id)}\n}`);
+            continue;
+        }
         if ("map" in n) {
             // a covered map node: RawElem_<comp>_<node> is the HANDLER'S per-element return shape:
             //   - into: the `into` field's type (the fetched item merged onto every over element);
@@ -583,6 +636,14 @@ function emitHandlerInterface(comp, typedNodes, plan) {
             continue; // #108: a cond node has no handler method (pure Expression).
         const method = nodeMethodName(comp.name, n.id);
         const bt = boundGoType(n, comp, typedNodes, plan);
+        if ("fanout" in n) {
+            // fanout (v3): one batched dispatch of the deduped id list. Ports = the batch struct; returns the
+            // aligned batch row (per-body rows) + resolved. The runner applies dedupe/drop/wrap after.
+            const portsT = `${portsStructName(comp.name, n.id)}_batch`;
+            const retT = rawRowStructName(comp.name, n.id);
+            lines.push(`\t${method}(ports ${portsT}, bound ${bt}) (${retT}, bool)`);
+            continue;
+        }
         if ("map" in n) {
             const m = n.map;
             const batched = m.batched === true;
@@ -626,6 +687,59 @@ type ${batchStruct} struct {
 	Items []${structName}
 }`;
 }
+/** emitFanoutPortsStructs (v3) — the per-body element ports struct + the batch struct for a covered
+ * fanout node (identical shape to a batched map's ports). The element ports read the `$as` id binding. */
+function emitFanoutPortsStructs(comp, node, typedNodes, plan) {
+    const f = node.fanout;
+    const structName = portsStructName(comp.name, node.id);
+    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);
+    const batchStruct = `${structName}_batch`;
+    return `${elemStruct}
+
+// ${batchStruct} — NATIVE batched ports for fanout '${node.id}': Items is a native slice of the concrete
+// per-id ports structs (${structName}). The consumer reads Items[i].<Field> DIRECTLY (bc#90 / runtime-free).
+type ${batchStruct} struct {
+	Items []${structName}
+}`;
+}
+/**
+ * fanoutItemsElemRef (v3) — the connection items ELEMENT TypeRef for a covered fanout node. The fanout
+ * outType is a connection struct `{items:[]Elem, cursor:*string}`; this returns Elem (the per-body row
+ * the batched handler yields, aligned to the deduped id list, before dedupe/drop). Fails closed if the
+ * outType is not that connection shape (named struct with an `items` arr field).
+ */
+function fanoutItemsElemRef(node, connRef, plan) {
+    if (connRef.kind !== "named") {
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go 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", `go fanout (v3): node '${node.id}' connection struct '${connRef.name}' has no 'items' array field.`);
+    }
+    return itemsField.type.elem;
+}
+/** fanoutOverElemInfo (v3) — the over id-list element TypeRef + the native Go over-slice expression.
+ * Mirrors mapOverElemInfo but reads the FanoutNode.fanout spec (prior-node arr OR input array w/ elemType). */
+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 { expr, ref } = goTypedInternals.typedFieldAccess(typedLocal(e.path[0]), baseRef, e.path.slice(1), plan);
+        if (ref.kind === "arr")
+            return { elemRef: ref.elem, overExpr: expr };
+    }
+    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.${goFieldName(e.path[0])}` };
+    }
+    throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go 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 (got ${JSON.stringify(f.over)}).`);
+}
 /** mapElemRowRef — the handler's per-element RETURN shape for a covered map node: the `into` field's
  * type (into) or the element outType directly (no-into). This is the type of RawElem_<comp>_<node>. */
 function mapElemRowRef(node, arrRef, plan) {
@@ -714,6 +828,43 @@ function mapOverElemInfo(comp, node, typedNodes, plan) {
 function mapOverElemType(comp, node, typedNodes, plan) {
     return renderTypeRef(mapOverElemInfo(comp, node, typedNodes, plan).elemRef);
 }
+/**
+ * priorNodeArrElemInfo (#129) — 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 native Go slice expression that yields it. This 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 `[]ElemT`
+ * fed straight from the prior node's typed local — 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 = goTypedInternals.typedFieldAccess(typedLocal(e.path[0]), 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.
+    return { elemRef: acc.ref.elem, overExpr: acc.expr };
+}
 function classifyPort(node) {
     if (staticArrElems(node) !== null)
         return "static";
@@ -945,7 +1096,7 @@ function emitNativeScalar(node, want, resolveRef) {
  * plane — a boxed escape would re-introduce the bc-runtime coupling this module removes). Returns the
  * struct field initializer (`Field: <expr>`). `resolveRef` resolves a ref head for the scalar path.
  */
-function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan) {
+function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan, typedNodes) {
     const fieldName = goPortFieldName(pn);
     // #110: a componentRef port bound to a runtime array input port (with elemType) → the native []ElemT,
     // read straight from the concrete input struct (`in.<Field>`) — ZERO boxed Value on the read hot path.
@@ -957,6 +1108,13 @@ function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan) {
             return `${fieldName}: in.${goFieldName(e.path[0])}`;
         }
     }
+    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) →
+    // the native []ElemT read straight off the prior node's typed local (`t_<node>.Field…`) — ZERO boxed
+    // Value on the read hot path. The over-source case (map…over) resolves via mapOverElemInfo; this is
+    // the plain leaf array input port (a fold/dedup leaf whose `items` = a prior node's array result).
+    const priorArr = priorNodeArrElemInfo(expr, typedNodes, plan);
+    if (priorArr !== null)
+        return `${fieldName}: ${priorArr.overExpr}`;
     // change #2: a static string array (projection) → a native `[]string{...}` literal.
     const strArr = staticStringArrElems(expr);
     if (strArr !== null) {
@@ -1066,8 +1224,8 @@ function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes
         const resolveRef = resolveRefAt(atPos);
         for (const pn of Object.keys(node.ports)) {
             const expr = node.ports[pn];
-            const fieldGoType = portFieldGoType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan);
-            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan));
+            const fieldGoType = portFieldGoType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
+            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan, typedNodes));
         }
         lines.push(`${ind}ps_${s} = ${structName}{${inits.join(", ")}}`);
         lines.push(`${ind}run_${s} = true`);
@@ -1220,6 +1378,12 @@ function emitNativeRawRunner(comp, plan, flags) {
             k += stage.length - 1;
             continue;
         }
+        // v3: a covered fanout node — deduped batched dispatch + first-seen dedupe + dangling drop +
+        // connection wrap (the SAME definition as run_behavior's fanoutDedupDrop).
+        if ("fanout" in comp.body[i]) {
+            lines.push(emitFanoutArm(comp, comp.body[i], k, typedNodes, plan, priorNodeAt, zeroOut));
+            continue;
+        }
         // #86 pt2: a covered batched map...into node — struct-native element collection + into enrichment.
         if ("map" in comp.body[i]) {
             lines.push(emitMapArm(comp, comp.body[i], k, typedNodes, plan, priorNodeAt, zeroOut, flags));
@@ -1276,8 +1440,8 @@ function emitNativeRawRunner(comp, plan, flags) {
         const resolveRef = resolveRefAt(k);
         for (const pn of portNames) {
             const expr = node.ports[pn];
-            const fieldGoType = portFieldGoType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan);
-            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan));
+            const fieldGoType = portFieldGoType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
+            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan, typedNodes));
         }
         lines.push(`${indent}ports_${s} := ${structName}{${inits.join(", ")}}`);
         const oc = `row_${s}`;
@@ -1536,6 +1700,132 @@ function emitMapArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut, f
 function elemLocal(s) {
     return `oel_${s}`;
 }
+/**
+ * emitFanoutArm (v3) — the struct-native exec of a covered FANOUT node. This is the genuinely new
+ * native list-in fan-out handler: build the per-id native 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 (a body whose
+ * dedupeKey field is the zero value ≡ the interpreter's null/absent-key body), implicitSource strip
+ * (STRUCTURAL — the connection items elem type already omits the implicitSource field), and wrap into
+ * the connection struct {items, cursor:nil}. NO boxed Value on any plane. Byte-equal to run_behavior.
+ */
+function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut) {
+    const f = node.fanout;
+    const s = sanitize(node.id);
+    const structName = portsStructName(comp.name, node.id);
+    const batchStruct = `${structName}_batch`;
+    const connRef = typedNodes.get(node.id);
+    const elemRef = fanoutItemsElemRef(node, connRef, plan);
+    const elemGo = 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);
+    // the dedupeKey Go field on the connection items elem (must be a string scalar for the seen-set key).
+    if (elemRef.kind !== "named")
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go 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", `go fanout (v3): node '${node.id}' dedupeKey '${f.dedupeKey}' must be a string field of the connection items element type '${elemRef.name}'.`);
+    const dkGo = goFieldName(f.dedupeKey);
+    // per-id native ports build (same as a batched map's per-element ports). $as → the over id value.
+    const buildPorts = (il, elemVar) => {
+        const inits = [];
+        const resolveRef = (head, restPath, opt) => {
+            if (opt)
+                return null;
+            let baseExpr;
+            let baseRef;
+            if (head === asName) {
+                baseExpr = elemVar;
+                baseRef = overElemRef;
+            }
+            else if (priorHere(head)) {
+                baseExpr = typedLocal(head);
+                baseRef = typedNodes.get(head);
+            }
+            else {
+                if (restPath.length !== 0)
+                    return null;
+                const scalar = inputScalarKind(comp.inputPorts?.[head]);
+                if (scalar === undefined)
+                    return null;
+                return { expr: `in.${goFieldName(head)}`, scalar };
+            }
+            let acc;
+            let expr;
+            try {
+                const r = goTypedInternals.typedFieldAccess(baseExpr, baseRef, restPath, plan);
+                expr = r.expr;
+                acc = r.ref;
+            }
+            catch {
+                return null;
+            }
+            if (acc.kind !== "scalar" || acc.scalar === "null")
+                return null;
+            return { expr, scalar: goScalar(acc.scalar) };
+        };
+        const asBinding = { name: asName, ref: overElemRef, plan };
+        for (const pn of portNames) {
+            const fieldGoType = portFieldGoType(f.ports[pn], comp.inputPorts, `fanout port '${pn}' of node '${node.id}'`, asBinding, plan);
+            inits.push(emitPortInit(pn, f.ports[pn], fieldGoType, resolveRef, comp.inputPorts, plan));
+        }
+        return [`${il}ep_${s} := ${structName}{${inits.join(", ")}}`];
+    };
+    const lines = [];
+    const closers = [];
+    lines.push(`\t// ── 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 = "\t";
+    if (f.parent !== undefined && priorNodeAt(f.parent, atPos)) {
+        lines.push(`${indent}if produced_${sanitize(f.parent)} {`);
+        closers.unshift(`${indent}}`);
+        indent += "\t";
+    }
+    // over id-list (typed field access — no serialize) → per-id ports (all ids; dedupe is on the result).
+    lines.push(`${indent}over_${s} := ${overExpr}`);
+    lines.push(`${indent}var items_${s} []${elemGo}`);
+    lines.push(`${indent}pi_${s} := make([]${structName}, 0, len(over_${s}))`);
+    lines.push(`${indent}for _, ${elemLocal(s)} := range over_${s} {`);
+    for (const l of buildPorts(indent + "\t", elemLocal(s)))
+        lines.push(l);
+    lines.push(`${indent}\tpi_${s} = append(pi_${s}, ep_${s})`);
+    lines.push(`${indent}}`);
+    // empty id-list => empty connection (handler not called), matching run_behavior.
+    lines.push(`${indent}if len(pi_${s}) > 0 {`);
+    lines.push(`${indent}\tbp_${s} := ${batchStruct}{Items: pi_${s}}`);
+    lines.push(`${indent}\tfo_${s}, fo_${s}Resolved := handlers.${nodeMethodName(comp.name, node.id)}(bp_${s}, nil)`);
+    lines.push(`${indent}\tif !fo_${s}Resolved {`, `${indent}\t\treturn ${zeroOut}, ${goErr("UNKNOWN_COMPONENT", `"component '${f.component}' has no handler (fail-closed)"`)}`, `${indent}\t}`);
+    lines.push(`${indent}\tif fo_${s}.IsError {`, `${indent}\t\treturn ${zeroOut}, ${goErr("OP_FAILED", `"operation '${node.id}' failed under 'fail' policy: "+fo_${s}.Err`)}`, `${indent}\t}`);
+    lines.push(`${indent}\tif len(fo_${s}.Rows) != len(pi_${s}) {`, `${indent}\t\treturn ${zeroOut}, ${goErr("FANOUT_BATCH_RESULT_MISMATCH", `fmt.Sprintf("fanout '${node.id}': batched handler must return a list aligned to the deduped id list (want %d)", len(pi_${s}))`)}`, `${indent}\t}`);
+    // ── THE ONE dedupe/drop (mirrors fanoutDedupDrop verbatim): first-seen dedupe by dedupeKey field;
+    //    drop dangling (zero dedupeKey ≡ interpreter's null/absent-key body); implicitSource strip is
+    //    structural (the elem type already omits it). cursor is always nil (connection wrap).
+    lines.push(`${indent}\tseen_${s} := make(map[string]struct{}, len(fo_${s}.Rows))`);
+    lines.push(`${indent}\titems_${s} = make([]${elemGo}, 0, len(fo_${s}.Rows))`);
+    lines.push(`${indent}\tfor fi_${s} := range fo_${s}.Rows {`);
+    lines.push(`${indent}\t\tbody_${s} := fo_${s}.Rows[fi_${s}]`);
+    lines.push(`${indent}\t\tvar el_${s} ${elemGo}`);
+    lines.push(emitRowCopy(`el_${s}`, `body_${s}`, elemRef, plan, indent.length + 2));
+    lines.push(`${indent}\t\tkey_${s} := el_${s}.${dkGo}`);
+    if (f.drop === "dangling") {
+        // dangling: a body whose dedupeKey is the zero value (empty string) is dropped.
+        lines.push(`${indent}\t\tif key_${s} == "" {`, `${indent}\t\t\tcontinue`, `${indent}\t\t}`);
+    }
+    lines.push(`${indent}\t\tif _, dup_${s} := seen_${s}[key_${s}]; dup_${s} {`, `${indent}\t\t\tcontinue`, `${indent}\t\t}`);
+    lines.push(`${indent}\t\tseen_${s}[key_${s}] = struct{}{}`);
+    lines.push(`${indent}\t\titems_${s} = append(items_${s}, el_${s})`);
+    lines.push(`${indent}\t}`);
+    lines.push(`${indent}}`);
+    // wrap into the connection struct {Items, Cursor:nil}. A nil items slice serializes to [] (the
+    // connection serializer normalizes it) — matching {items:[],cursor:null} for an empty fan-out.
+    lines.push(`${indent}${typedLocal(node.id)} = ${connRef.name}{${goFieldName("items")}: items_${s}}`);
+    lines.push(`${indent}produced_${s} = true`);
+    for (const c of closers)
+        lines.push(c);
+    return lines.join("\n");
+}
 /** #108: resolve an INPUT port head for a native-expr ref (cond `if` / map `when` / branches). A scalar
  * port → `in.<Field>` of the scalar type; an array port WITH elemType → `in.<Field>` of `[]ElemT` (so
  * `len(in.<Field>)` works); anything else → null (fail-closed). */
@@ -1974,7 +2264,11 @@ function emit(ctx) {
         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) {
+                // v3: a fanout node emits a per-id element ports struct + a batch struct (like a batched map).
+                structs.push(emitFanoutPortsStructs(c, n, typedNodes, plan));
+            }
+            else if ("map" in n) {
                 // #86 pt2 / #108: a map node emits an element ports struct + a batch struct. The element ports
                 // may read the `$as` binding — resolved via the over-element type (prior node / input array).
                 structs.push(emitMapPortsStructs(c, n, typedNodes, plan));
@@ -1983,7 +2277,8 @@ function emit(ctx) {
                 // #108: a cond node has NO ports struct (it is a pure Expression — no handler dispatch).
             }
             else {
-                structs.push(emitPortsStruct(c, n, undefined, plan));
+                // #129: pass typedNodes so a leaf array port fed by a prior node's arr outType types as []ElemT.
+                structs.push(emitPortsStruct(c, n, undefined, plan, typedNodes));
             }
         }
         // CONCRETE per-node row structs + the per-component handler interface (the fully-concrete seam).
@@ -2002,7 +2297,7 @@ function emit(ctx) {
     const needSync = native.some((c) => concurrencyPlan(c) !== null);
     // bc#90: the ONLY std-lib `fmt.Sprintf` site on the covered plane is the batched-map result-count
     // mismatch error — so `fmt` is imported iff a covered component has a batched map node.
-    const needFmt = native.some((c) => c.body.some((n) => "map" in n && n.map.batched === true));
+    const needFmt = native.some((c) => c.body.some((n) => ("map" in n && n.map.batched === true) || "fanout" in n));
     // The FULLY-covered module (no non-native components) gets a MINIMAL, RUNTIME-FREE header — NO
     // bc-runtime import at all (bc#90).
     // FAIL CLOSED (bc#86/#89): the --typed-native (native codegen) surface is native-only. If ANY
@@ -2114,6 +2409,39 @@ ${native.map((c) => `\t${handlerIfaceName(c.name)}`).join("\n")}
             if ("cond" in n)
                 continue; // #108: cond has no handler method (pure Expression) — no scripted impl.
             const ref = typedNodes.get(n.id);
+            if ("fanout" in n) {
+                // v3: scripted fanout impl — drain one batched outcome and decode the aligned []Value into the
+                // per-body elem rows (a null array element materializes to the zero elem row = dangling).
+                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`;
+                const foBoundT = boundGoType(n, c, typedNodes, plan);
+                methodImpls.push(`func (s *ScriptedNativeRaw) ${nodeMethodName(c.name, n.id)}(_ ${portsT}, _ ${foBoundT}) (${batchT}, bool) {
+	src, ok := s.next(${JSON.stringify(f.component)})
+	if !ok {
+		return ${batchT}{}, false
+	}
+	if src.isErr {
+		return ${batchT}{IsError: true, Err: src.err}, true
+	}
+	arr, _ := src.ok.([]${PKG}.Value)
+	rows := make([]${elemT}, 0, len(arr))
+	for _, ev := range arr {
+		// v3: a null aligned body is a DANGLING id — decode it to the zero elem row (empty dedupeKey
+		// field), so the runner's dangling-drop excludes it (byte-equal to fanoutDedupDrop).
+		if ev == nil {
+			rows = append(rows, ${elemT}{})
+			continue
+		}
+		rows = append(rows, ${elemDecode}(ev))
+	}
+	return ${batchT}{Rows: rows}, true
+}`);
+                continue;
+            }
             if ("map" in n) {
                 const m = n.map;
                 const batched = m.batched === true;
@@ -2161,7 +2489,18 @@ ${native.map((c) => `\t${handlerIfaceName(c.name)}`).join("\n")}
             const rowT = rawRowStructName(c.name, node.id);
             const decode = emitDecodeRow(c.name, node.id, rowT, ref, plan, emittedDecode, decodeFns, "");
             const nodeBoundT = boundGoType(node, c, typedNodes, plan);
-            methodImpls.push(`func (s *ScriptedNativeRaw) ${nodeMethodName(c.name, node.id)}(_ ${portsStructName(c.name, node.id)}, _ ${nodeBoundT}) (${rowT}, bool) {
+            // #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 `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 named only when the echo path
+            // uses it (else the param stays `_` so a non-echo node compiles clean / unused-param-free).
+            const canEcho = ref.kind === "arr" && Object.prototype.hasOwnProperty.call(node.ports, "items");
+            const portsParam = canEcho ? "ports" : "_";
+            const echoBranch = canEcho
+                ? `\tif src.echo == "items" {\n\t\treturn ${rowT}{Val: ports.${goPortFieldName("items")}}, true\n\t}\n`
+                : "";
+            methodImpls.push(`func (s *ScriptedNativeRaw) ${nodeMethodName(c.name, node.id)}(${portsParam} ${portsStructName(c.name, node.id)}, _ ${nodeBoundT}) (${rowT}, bool) {
 	src, ok := s.next(${JSON.stringify(node.component)})
 	if !ok {
 		return ${rowT}{}, false
@@ -2169,14 +2508,18 @@ ${native.map((c) => `\t${handlerIfaceName(c.name)}`).join("\n")}
 	if src.isErr {
 		return ${rowT}{IsError: true, Err: src.err}, true
 	}
-	return ${decode}(src.ok), true
+${echoBranch}	return ${decode}(src.ok), true
 }`);
         }
     }
     const adapter = `// scriptSrc — a scripted per-component outcome (an ok Value or an error), drained in order.
+// #129: \`echo\` carries the reference scriptedHandlers' \`echo\` directive (e.g. "items") so a scripted
+// node can ECHO a named input PORT back as its result — used to make the node→leaf array dataflow test
+// non-vacuous (the leaf handler returns its \`items\` port, so a dropped/boxed native array diverges).
 type scriptSrc struct {
 	isErr bool
 	err   string
+	echo  string
 	ok    ${PKG}.Value
 }
 
@@ -2207,12 +2550,18 @@ func NewScriptedNativeRaw(spec *${PKG}.JObj) (*ScriptedNativeRaw, error) {
 			}
 			for _, e := range entries {
 				eo, _ := e.(*${PKG}.JObj)
+				// #129: an \`echo\` directive names an input port to echo back (mirrors the reference
+				// scriptedHandlers' \`echo === "items"\`). It is drained together with the ok payload.
+				echo := ""
+				if echoNode, has := eo.Get("echo"); has {
+					echo, _ = echoNode.(string)
+				}
 				if okNode, has := eo.Get("ok"); has {
 					val, derr := ${PKG}.DecodeValue(okNode)
 					if derr != nil {
 						return nil, derr
 					}
-					queues[comp] = append(queues[comp], scriptSrc{ok: val})
+					queues[comp] = append(queues[comp], scriptSrc{ok: val, echo: echo})
 					continue
 				}
 				ev, _ := eo.Get("error")
@@ -2324,6 +2673,7 @@ function emitDecodeRow(compName, nodeId, rowT, ref, plan, emitted, out, suffix)
  */
 export const goTypedNativeEmitter = {
     language: "go-typed-native",
+    classification: "codegen", // native: 型付きフラットコード生成・IR/dict 非在（#128/A6）
     fileExtension: ".go",
     defaultRuntimeImport: "github.com/foo-ogawa/behavior-contracts/go/coderuntime",
     filenameHint: "behaviors.typed.native.generated.go",