behavior-contracts 0.8.2 → 0.8.4

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

@@ -2,7 +2,7 @@ import { GeneratorFailure } from "./core.js";
 import { isControlGate } from "../behavior.js";
 import { goStraightlineInternals } from "./emit-shared-go.js";
 import { goTypedInternals } from "./emit-shared-go-typed.js";
-import { buildTypePlan, deriveTypeRef, findDecl } from "./typed.js";
+import { buildTypePlan, deriveTypeRef, findDecl, inputPortIsOptional, inputPortTypeRef } from "./typed.js";
 import { concurrencyPlan, execPlan, analyzeSequentialOps, classifyExpr, buildComponentPlan, } from "./straightline.js";
 import { NativeExprCompiler } from "./native-expr.js";
 const PKG = "dslcontracts";
@@ -72,18 +72,13 @@ function inferPortType(node, inputPorts, asBinding) {
                 }
                 return "Value";
             }
+            // a ref to a REQUIRED scalar input port → that scalar. An OPTIONAL port has no required-scalar
+            // kind (its native type is *T) and is lowered by the opt lane ahead of this — reaching here with
+            // one means the shape is uncovered, and "Value" routes it to the caller's loud fail-closed.
             if (e.path.length === 1) {
-                const s = inputPorts[e.path[0]];
-                if (s) {
-                    if (s.type === "string" || s.type === "literal")
-                        return "string"; // literal = constrained string.
-                    if (s.type === "int")
-                        return "int64";
-                    if (s.type === "float" || s.type === "number")
-                        return "float64"; // `"number"` = the float channel.
-                    if (s.type === "bool")
-                        return "bool";
-                }
+                const sc = inputScalarKind(inputPorts[e.path[0]]);
+                if (sc !== undefined)
+                    return sc;
             }
             return "Value";
         }
@@ -121,6 +116,12 @@ function staticStringArrElems(node) {
  * `dslcontracts.Value` fallback on the native module). `where` names the emission site for the error.
  */
 function portFieldGoType(node, inputPorts, where = "port", asBinding, plan, typedNodes) {
+    // A port reading an OPTIONAL input port lowers through the shared native-expr compiler (the *T
+    // pass-through / the coalesce default). It runs FIRST so an optional input can never fall into the
+    // required-scalar inference below (which has no way to say "absent").
+    const optPort = optPortCompileG(node, inputPorts, where, plan);
+    if (optPort !== null)
+        return renderTypeRef(optPort.ref);
     if (staticStringArrElems(node) !== null)
         return "[]string";
     // #110: a componentRef port bound to a runtime array input port (with a resolvable elemType) → []ElemT.
@@ -141,7 +142,7 @@ function portFieldGoType(node, inputPorts, where = "port", asBinding, plan, type
         return renderTypeRef(composite);
     const ft = inferPortType(node, inputPorts, asBinding);
     if (ft === "Value") {
-        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90 / runtime-free): ${where} '${JSON.stringify(node)}' does not lower to a native Go type (would need a boxed dslcontracts.Value). The covered read plane is runtime-free and admits NO boxed escape — the covered corpus ports are string / bool / static-string-array (projection) / bare-number (limit) only. Regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90 / runtime-free): ${where} '${JSON.stringify(node)}' does not lower to a native Go type (would need a boxed dslcontracts.Value). The covered read plane is runtime-free and admits NO boxed escape. ${GO_STATIC_PORT_FORMS} Regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
     }
     return ft;
 }
@@ -279,14 +280,20 @@ function numLiteralGoExpr(node) {
     // fractional / exponent literal → checked float64 (finite, already guaranteed above).
     return `${PKG}.Value(float64(${node}))`;
 }
-/** A port node is static (literal / ref / concat of those / static arr / bare number literal) —
- * resolvable to a native Go Value with no NewObj / no evaluate interpreter. */
-function portIsStatic(node) {
+/** A port node is static (literal / ref / concat of those / static arr / bare number literal / an
+ * optional-input read) — resolvable to a native Go value with no NewObj / no evaluate interpreter. This
+ * is the SHAPE gate that decides native ELIGIBILITY; the lowering itself (portFieldGoType / emitPortInit)
+ * is what proves each shape, and fails closed loudly on one it cannot lower. */
+function portIsStatic(node, inputPorts) {
     const arr = staticArrElems(node);
     if (arr !== null)
-        return arr.every(portIsStatic);
+        return arr.every((el) => portIsStatic(el, inputPorts));
     if (numLiteralGoExpr(node) !== null)
         return true; // bare number literal (e.g. Query `limit`)
+    // An optional-input read (`opt($.x)` / `coalesce(opt($.x), 20)` / `ne(opt($.x), null)`) is a
+    // statically-resolvable port — the opt lane lowers it (or fails closed with the specific reason).
+    if (inputPorts !== undefined && exprReadsOptionalInput(node, inputPorts))
+        return true;
     const e = classifyExpr(node);
     switch (e.kind) {
         case "str":
@@ -295,7 +302,7 @@ function portIsStatic(node) {
         case "ref":
             return true;
         case "concat":
-            return e.parts.every((p) => portIsStatic(reconstructG(p)));
+            return e.parts.every((p) => portIsStatic(reconstructG(p), inputPorts));
         default:
             return false;
     }
@@ -399,7 +406,7 @@ function coveredMapNode(n, bodyIds, comp) {
     }
     const ports = m.ports;
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp.inputPorts))
             return false;
     return true;
 }
@@ -432,7 +439,7 @@ function coveredFanoutNode(n, bodyIds, comp) {
     }
     const ports = f.ports;
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp.inputPorts))
             return false;
     return true;
 }
@@ -539,7 +546,7 @@ function coverageRejectReason(comp) {
         if (cr.relationKind !== undefined && cr.relationKind !== "single" && cr.relationKind !== "connection")
             return `relationKind '${cr.relationKind}' not native-covered (node '${n.id}')`;
         for (const p of Object.keys(cr.ports))
-            if (portIsStatic(cr.ports[p]) === false)
+            if (portIsStatic(cr.ports[p], comp.inputPorts) === false)
                 return `node '${n.id}' port '${p}' is not statically resolvable`;
     }
     if (!outputIsNativeLowerable(comp))
@@ -1030,43 +1037,31 @@ function reconstructG(e) {
 function inStructName(compName) {
     return `In_${sanitize(compName)}`;
 }
-/** Go type for an input port's declared type (scalar → concrete; array+elemType → []ElemT; else Value). */
-function inputPortGoType(schema, plan) {
-    switch (schema?.type) {
-        case "string":
-        // a `"literal"` port is a constrained STRING union (`param.literal(…)`, stored 'S') → native string.
-        case "literal":
-            return "string";
-        case "int":
-            return "int64";
-        case "float":
-        // a `"number"` port is the FLOAT channel (run_behavior: number → float / f64 / float64).
-        case "number":
-            return "float64";
-        case "bool":
-            return "bool";
-        case "array":
-        case "arr": {
-            // #108: an input ARRAY port with a declared elemType lowers to a native []ElemT (the map-over-input
-            // $as element type source). Without elemType or a plan, it stays a boxed Value (uncovered / fail-closed).
-            const et = schema.elemType;
-            if (et !== undefined && plan !== undefined)
-                return `[]${renderTypeRef(deriveTypeRef(et, plan))}`;
-            return `${PKG}.Value`;
-        }
-        case "map": {
-            // an input MAP port (dynamic string keys, declared value elemType) lowers to a native map[string]ElemT.
-            const et = schema.elemType;
-            if (et !== undefined && plan !== undefined)
-                return `map[string]${renderTypeRef(deriveTypeRef(et, plan))}`;
-            return `${PKG}.Value`;
-        }
-        default:
-            return `${PKG}.Value`;
-    }
-}
-/** The scalar kind an input port declares, or undefined if it is not a native scalar. */
+/**
+ * inputPortGoType — the native Go type for an input port's declared type. Scalars lower to the concrete
+ * scalar; `array`/`map` with a declared elemType to `[]ElemT` / `map[string]ElemT`; an OPTIONAL port
+ * (`{opt:T}` → `required:false`) to `*T` — the native representation of "the value is absent" (nil).
+ * A declared type with no native lowering stays the boxed Value.
+ *
+ * An OPTIONAL port whose inner type has no native lowering FAILS CLOSED: a boxed `Value` cannot carry
+ * the presence distinction on the covered plane, and emitting the bare inner type would silently turn
+ * "absent" into a zero value. A port whose optionality cannot be represented is never silently coerced.
+ */
+function inputPortGoType(schema, plan, where = "input port") {
+    const ref = inputPortTypeRef(schema, plan);
+    if (ref !== undefined)
+        return renderTypeRef(ref);
+    if (inputPortIsOptional(schema))
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (runtime-free): ${where} is OPTIONAL (declared {opt:…}) but its inner type ${JSON.stringify(schema?.type)} has no native Go lowering, so "absent" has no native representation (a boxed Value would be an escape, and the bare inner type would silently read absent as a zero value). Declare an elemType for an array/map, or use a natively-lowerable scalar.`);
+    return `${PKG}.Value`;
+}
+/** The scalar kind a REQUIRED input port declares, or undefined when it is not a required native scalar.
+ * An OPTIONAL port is deliberately NOT a scalar kind here: its native type is `*T`, and the callers of
+ * this function build REQUIRED scalar slots (`in.<Field>` read straight into a non-opt port field).
+ * Answering "int64" for an `{opt:"int"}` port is exactly how "absent" would silently become `0`. */
 function inputScalarKind(schema) {
+    if (inputPortIsOptional(schema))
+        return undefined;
     switch (schema?.type) {
         case "string":
         case "literal": // a `"literal"` union is a constrained string (see inputPortGoType).
@@ -1091,7 +1086,7 @@ function emitInStruct(comp, plan) {
         return `// ${name} — the CONCRETE input for '${comp.name}' (no input ports).\ntype ${name} struct{}`;
     }
     const names = ports.map((p) => goFieldName(p));
-    const types = ports.map((p) => inputPortGoType(comp.inputPorts[p], plan));
+    const types = ports.map((p) => inputPortGoType(comp.inputPorts[p], plan, `input port '${p}' of component '${comp.name}'`));
     const nameW = Math.max(0, ...names.map((n) => n.length));
     const typeW = Math.max(0, ...types.map((t) => t.length));
     const fields = ports
@@ -1132,6 +1127,15 @@ function emitInDecoder(comp, plan) {
         const scalar = inputScalarKind(schema);
         const et = schema.elemType;
         lines.push(`\tif v, ok := input.Get(${JSON.stringify(p)}); ok {`);
+        if (inputPortIsOptional(schema)) {
+            // An OPTIONAL port decodes into its native *T. materializeExpr's opt de-box IS the wire rule:
+            // a nil Value (null) → nil (absent), any other value → a pointer to the materialized inner. A key
+            // that never appears leaves the struct's zero value (nil) — the same absent value. Checked FIRST:
+            // optionality wraps every inner type (an optional array is *[]T, not []T).
+            lines.push(`\t\tin.${field} = ${goTypedInternals.materializeExpr("v", inputPortTypeRef(schema, plan), plan)}`);
+            lines.push(`\t}`);
+            continue;
+        }
         if ((schema?.type === "array" || schema?.type === "arr") && et !== undefined) {
             // #108: decode the boxed Value array into the native []ElemT (test glue — materialize each element
             // via the typed materializer; a non-array or non-conforming element is a fail-closed decode error).
@@ -1174,6 +1178,9 @@ function emitInDecoder(comp, plan) {
     lines.push(`}`);
     return lines.join("\n");
 }
+/** The port forms the STATIC (non-optional) lane lowers — named in its reject message so the message
+ * describes what is actually covered rather than a stale corpus list. */
+const GO_STATIC_PORT_FORMS = "This port does not read an optional input, so it lowers through the STATIC port forms: a string / bool / number literal, a static string-array (projection), a ref to a REQUIRED scalar input port, a ref to an input array/map port or a prior node's array (declared elemType), a ref to a `$as` element field, or a concat of native strings. A dynamic operator at port position is not covered on this lane. (A port that DOES read an optional input lowers through the full native expression compiler, which admits the whole closed operator set — so the covered operator set at port position currently depends on the lane, not on the operator.)";
 /**
  * emitNativeScalar — lower a static port expr to a NATIVE Go expression of the concrete `want` scalar
  * type, or null if it cannot be statically proven that type. Literals: a string literal is native for
@@ -1231,6 +1238,11 @@ function emitNativeScalar(node, want, resolveRef) {
  */
 function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan, typedNodes, asBinding, elemBaseExpr) {
     const fieldName = goPortFieldName(pn);
+    // The OPTIONAL-input lane (*T pass-through / coalesce default) — same shared compile as
+    // portFieldGoType, so the field type and its initializer are derived from ONE lowering.
+    const optPort = optPortCompileG(expr, inputPorts ?? {}, `port '${pn}'`, plan);
+    if (optPort !== null)
+        return `${fieldName}: ${optPort.expr}`;
     // #108-map: a port that is a ref to a `$as` element MAP/NAMED field (or an input map port) → the typed
     // composite value directly off the element/input (native map[string]V / struct — ZERO boxed Value).
     if (plan !== undefined) {
@@ -1283,7 +1295,7 @@ function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan, typed
     // FAIL CLOSED: the covered read plane is runtime-free — no boxed Value fallback (that would
     // re-couple the covered module to bc-runtime). If a genuinely-dynamic port reaches here, the
     // component is not native-eligible and must regenerate on the boxed straight-line path.
-    throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90 / runtime-free): port '${pn}' (${JSON.stringify(expr)}) does not lower to a native Go value of type '${fieldGoType}'. The covered read plane admits NO boxed dslcontracts.Value escape — regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
+    throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90 / runtime-free): port '${pn}' (${JSON.stringify(expr)}) does not lower to a native Go value of type '${fieldGoType}'. The covered read plane admits NO boxed dslcontracts.Value escape. ${GO_STATIC_PORT_FORMS} Regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
 }
 /**
  * emitParallelStageArm (bc#87) — EXPLICIT static parallel orchestration for a real-concurrency stage.
@@ -2019,23 +2031,72 @@ function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut
         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). */
+/**
+ * goInputHeadRef (#108) — resolve an INPUT port head for a native-expr ref (cond `if` / map `when` /
+ * branches / an opt-lane port). The port's declared type comes from the shared `inputPortTypeRef` SSoT,
+ * so an OPTIONAL port resolves as `{opt:…}` (native `*T`) and the compiler can see its optionality: a
+ * null-compare becomes a real presence test and a coalesce a real deref-or-default, while a
+ * REQUIRED-scalar slot fed by an opt fails closed. Go values are read directly off the input struct (no
+ * ownership ceremony); a type with no native lowering → null (fail-closed).
+ */
 function goInputHeadRef(head, comp, plan) {
-    const schema = comp.inputPorts?.[head];
-    if (schema === undefined)
+    const ref = inputPortTypeRef(comp.inputPorts?.[head], plan);
+    if (ref === undefined)
         return null;
-    const sc = inputScalarKind(schema);
-    if (sc !== undefined) {
-        const scalarRef = { kind: "scalar", scalar: sc === "int64" ? "int" : sc === "float64" ? "float" : sc };
-        return { expr: `in.${goFieldName(head)}`, ref: scalarRef };
-    }
-    const et = schema.elemType;
-    if ((schema.type === "array" || schema.type === "arr") && et !== undefined) {
-        return { expr: `in.${goFieldName(head)}`, ref: { kind: "arr", elem: deriveTypeRef(et, plan) } };
+    return { expr: `in.${goFieldName(head)}`, ref };
+}
+/**
+ * optPortCompileG — the OPTIONAL-input port lane (go). The rust twin's mirror: a component may
+ * declare an input port `{opt:T}` (PortSchema `required:false`), and the only native representation of
+ * "the value is absent" is `*T`, so such a port never lowers through the required-scalar inference. The
+ * port expression compiles with the SHARED runtime-free native-expr compiler (native-expr.ts — the same
+ * traversal, type-inference and fail-closed discipline rust uses, so the two agree by construction):
+ *
+ *   - `opt($.x)` / `$.x` at port position  → `*T` (the leaf receives the absent value as null, exactly
+ *     as run_behavior's `evalPorts` passes it).
+ *   - `coalesce(opt($.x), <literal>)`      → the native deref-or-default — a native `T`, no boxed Value.
+ *   - `ne(opt($.x), null)` / `eq(…, null)` → the native presence test (`!= nil` / `== nil`).
+ *
+ * Returns null when the port expression reads NO optional input (the caller keeps its existing lowering).
+ * A port that DOES read one but does not compile — or that compiles to a fallible expression, which this
+ * position cannot hoist — FAILS CLOSED loudly rather than degrade to a required type or a zero value.
+ */
+function optPortCompileG(node, inputPorts, where, plan) {
+    if (plan === undefined)
+        return null;
+    if (!exprReadsOptionalInput(node, inputPorts))
+        return null;
+    const resolveHead = (head) => goInputHeadRef(head, { inputPorts }, plan);
+    let c;
+    try {
+        // zeroOut is unreachable here: a port expression that needs an error return is rejected below
+        // (stmts.length > 0), so the backend never renders an early-return with it.
+        c = new NativeExprCompiler(makeGoExprBackend("", resolveHead, plan)).compilePort(node);
+    }
+    catch (e) {
+        if (!(e instanceof GeneratorFailure))
+            throw e;
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (runtime-free): ${where} ${JSON.stringify(node)} reads an OPTIONAL input port but does not lower to a native Go value: ${e.message}`);
+    }
+    if (c.stmts.length > 0)
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (runtime-free): ${where} ${JSON.stringify(node)} reads an OPTIONAL input port through a FALLIBLE expression (one that can raise INT_OVERFLOW / NAN_OR_INF / MOD_ZERO / PRECISION_LOSS). Such an expression lowers to STATEMENTS carrying an early error-return, and a port is built inline in the ports-struct literal — a position that cannot host them. (A cond/guard position CAN host them, so the same expression is covered there — the boundary is the POSITION, not the operator.) Use a non-fallible port expression.`);
+    return c;
+}
+/** exprReadsOptionalInput — does this port expression reference an OPTIONAL (`required:false`) input
+ * port? Language-neutral scan for `ref`/`refOpt` heads bound to an optional port. Decides ONLY which
+ * lane a port takes; the lane itself then proves the lowering (or fails closed). */
+function exprReadsOptionalInput(node, inputPorts) {
+    if (node === null || typeof node !== "object")
+        return false;
+    if (Array.isArray(node))
+        return node.some((el) => exprReadsOptionalInput(el, inputPorts));
+    const rec = node;
+    const keys = Object.keys(rec);
+    if (keys.length === 1 && (keys[0] === "ref" || keys[0] === "refOpt")) {
+        const path = rec[keys[0]];
+        return Array.isArray(path) && typeof path[0] === "string" && inputPortIsOptional(inputPorts?.[path[0]]);
     }
-    return null;
+    return keys.some((k) => exprReadsOptionalInput(rec[k], inputPorts));
 }
 /**
  * emitCondArm — the struct-native exec of a covered cond node (#108). Mirrors run_behavior's cond
@@ -2281,6 +2342,23 @@ function makeGoExprBackend(zeroOut, resolveHead, plan) {
         // opt (`*T`) null-presence test: present = `(expr != nil)`, absent = `(expr == nil)`.
         optIsSome: (expr) => `(${expr} != nil)`,
         optIsNone: (expr) => `(${expr} == nil)`,
+        // opt (`*T`) defaulted to a PURE default. Go has no `unwrap_or`, so this is the same immediately-
+        // invoked func literal the `ternary` rendering uses (the established shape in this emitter): bind the
+        // pointer ONCE, deref it when present, else yield the default. The default sits in the else branch,
+        // so it is evaluated only when absent — run_behavior's lazy right side exactly.
+        optUnwrapOr: (optExpr, defaultExpr, innerTy) => `func() ${innerTy} { if v := ${optExpr}; v != nil { return *v }; return ${defaultExpr} }()`,
+        // opt defaulted to a FALLIBLE default — a statement if/else, NOT a func literal: the default's
+        // hoisted `return zeroOut, err` early returns must leave the ENCLOSING fn, which a func literal
+        // would swallow (it would return from the literal). Only the nil branch evaluates the default.
+        optCoalesceGuard: (temp, ty, optExpr, bindTemp, dStmts, dExpr) => [
+            `var ${temp} ${ty}`,
+            `if ${bindTemp} := ${optExpr}; ${bindTemp} != nil {`,
+            `	${temp} = *${bindTemp}`,
+            `} else {`,
+            ...dStmts.map((x) => `	${x}`),
+            `	${temp} = ${dExpr}`,
+            `}`,
+        ],
         ternary: (cond, t, e, ty) => `func() ${ty} { if ${cond} { return ${t} }; return ${e} }()`,
         shortCircuitBool: (op, temp, left, rStmts, rExpr) => {
             // and: temp=false; if left { <rStmts>; temp=rExpr }.  or: temp=true; if !left { <rStmts>; temp=rExpr }.
@@ -2713,17 +2791,20 @@ ${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);
-            // #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`
-                : "";
+            // #129 (TEST glue): support the reference scriptedHandlers' echo forms (PROTOCOL.md §3.5) — the
+            // adapter normalizes `{"echo":"port","port":"X"}` / `{"echo":"items"}` to the port NAME, and the
+            // scripted handler
+            // ECHOES a NATIVE port back as its result. This makes a port-plane pin non-vacuous: the node's
+            // observed result IS the native value that flowed into its ports struct, so a dropped / re-boxed /
+            // zero-defaulted port diverges from run_behavior instead of passing. A port is echoable when its
+            // native type IS the node's outType (that is exactly when the row's Val can hold it); `ports` is
+            // named only when at least one port qualifies (else the param stays `_` so a non-echo node
+            // compiles clean / unused-param-free).
+            const echoable = echoablePorts(c, node, ref, plan, typedNodes);
+            const portsParam = echoable.length > 0 ? "ports" : "_";
+            const echoBranch = echoable
+                .map((ep) => `\tif src.echo == ${JSON.stringify(ep)} {\n\t\treturn ${rowT}{Val: ports.${goPortFieldName(ep)}}, true\n\t}\n`)
+                .join("");
             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 {
@@ -2775,10 +2856,19 @@ 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.
+				// scriptedHandlers' PROTOCOL.md §3.5 echo forms). It is drained together with the ok
+				// payload. \`{"echo":"port","port":"X"}\` is normalized to the port NAME here, so the
+				// generated node method just compares \`src.echo\` against its echoable port names —
+				// \`{"echo":"items"}\` is already that shape.
 				echo := ""
 				if echoNode, has := eo.Get("echo"); has {
 					echo, _ = echoNode.(string)
+					if echo == "port" {
+						echo = ""
+						if portNode, hasPort := eo.Get("port"); hasPort {
+							echo, _ = portNode.(string)
+						}
+					}
 				}
 				if okNode, has := eo.Get("ok"); has {
 					val, derr := ${PKG}.DecodeValue(okNode)
@@ -2862,6 +2952,16 @@ ${arms}
 }
 `;
 }
+/** echoablePorts (TEST glue) — the node's ports whose NATIVE type is exactly the node's outType, in
+ * declaration order. Those are the ports a scripted `echo: "<port>"` can return as the row's Val. A port
+ * with a different type is not echoable (the row could not hold it), and a NAMED outType has no Val at
+ * all (its row carries the struct's fields flattened — see emitDecodeRow). */
+function echoablePorts(comp, node, ref, plan, typedNodes) {
+    if (ref.kind === "named")
+        return [];
+    const want = renderTypeRef(ref);
+    return Object.keys(node.ports).filter((p) => portFieldGoType(node.ports[p], comp.inputPorts, `port '${p}'`, undefined, plan, typedNodes) === want);
+}
 /** emitDecodeRow — emit (once, deduped) a decoder `decodeRow_<comp>_<node><suffix>(v Value) <rowT>`
  * that materializes the scripted ok Value into the concrete row struct (typed fields = the outType /
  * elem-row type). Named: reuse the Value->struct marshaller + copy fields; scalar/arr/opt: materialize