behavior-contracts 0.7.1 → 0.7.3

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

@@ -322,6 +322,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 +399,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
@@ -486,6 +526,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 +632,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 +683,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) {
@@ -1220,6 +1330,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));
@@ -1536,6 +1652,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 +2216,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));
@@ -2002,7 +2248,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 +2360,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;