behavior-contracts 0.8.3 → 0.8.5

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";
@@ -49,161 +49,70 @@ function portsStructName(compName, nodeId) {
     // type to implement the per-component Handler_<comp> interface's concrete Node_* method signatures.
     return `PortsNR_${sanitize(compName)}_${nodeId.replace(/[^A-Za-z0-9_]/g, "_")}`;
 }
-function inferPortType(node, inputPorts, asBinding) {
-    if (staticArrElems(node) !== null)
-        return "Value";
-    const e = classifyExpr(node);
-    switch (e.kind) {
-        case "str":
-        case "concat":
-            return "string";
-        case "bool":
-            return "bool";
-        case "ref": {
-            // #108: a `$as`-headed ref (map element binding) — resolve the element field's scalar type.
-            if (asBinding !== undefined && e.path[0] === asBinding.name) {
-                try {
-                    const { ref } = goTypedInternals.typedFieldAccess(asBinding.name, asBinding.ref, e.path.slice(1), asBinding.plan);
-                    if (ref.kind === "scalar" && ref.scalar !== "null")
-                        return goScalarPortField(ref.scalar);
-                }
-                catch {
-                    return "Value";
-                }
-                return "Value";
-            }
-            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";
-                }
-            }
-            return "Value";
-        }
-        default:
-            return "Value";
-    }
-}
-/** scalar TypeRef → PortFieldType (native go scalar kind). */
-function goScalarPortField(scalar) {
-    return scalar === "string" ? "string" : scalar === "int" ? "int64" : scalar === "float" ? "float64" : "bool";
-}
-/** A static string-array port (every element a static string literal) — the graphddb `projection`
- * shape. Returns the list of literal strings, or null when the node is not that shape. */
-function staticStringArrElems(node) {
-    const arr = staticArrElems(node);
-    if (arr === null)
-        return null;
-    const out = [];
-    for (const el of arr) {
-        const e = classifyExpr(el);
-        if (e.kind !== "str")
-            return null;
-        out.push(e.value);
-    }
-    return out;
-}
 /**
- * portFieldGoType — the NATIVE Go type for a covered port field (bc#90 / runtime-free). The covered
- * ports struct carries NO `dslcontracts.Value` field: every port lowers to a concrete Go type.
- *   - a static string-array (projection) → `[]string` (change #2);
- *   - a bare int/float number literal (e.g. Query `limit: 20`) → `int64`/`float64`;
- *   - a string/bool/scalar-input port → the scalar Go type (inferPortType).
- * A port that would otherwise infer to the boxed `Value` (a dynamic operator, a non-static array, a
- * 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.
+ * portFieldGoType — the NATIVE Go type for a covered port field (bc#90 / runtime-free), read off the ONE
+ * port lowering (compilePortNode / native-expr). The covered ports struct carries NO `dslcontracts.Value`
+ * field: every port lowers to a concrete Go type, and a port that cannot lower FAILS CLOSED. The field
+ * type is the compiled expression's TypeRef, so it can never disagree with the initializer (emitPortInit),
+ * which is the SAME lowering read for its value. `where` names the emission site for the error.
  */
-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";
-    // a ref to a `$as` element field (or an input map port) whose type is a MAP or NAMED struct (NOT a bare
-    // scalar) → the native map/struct type (#108-map: a `{map:V}` write port lowers to map[string]V).
-    const composite = portCompositeRef(node, inputPorts, asBinding, plan);
-    if (composite !== null)
-        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.`);
-    }
-    return ft;
+function portFieldGoType(node, comp, plan, typedNodes, where = "port", opts) {
+    const c = compilePortNode(node, comp, plan, typedNodes, (h) => typedNodes.has(h), where, opts);
+    return c.renderedType ?? renderTypeRef(c.ref);
 }
-/** portCompositeRef (go twin) — the full TypeRef of a port that is a `{ref:[...]}` into a `$as` element
- * MAP or NAMED field (or an input MAP port with elemType). Returns null otherwise (caller falls through
- * to scalar/array inference). #108-map: enables a `{map:V}` write port to lower to map[string]V. */
-function portCompositeRef(node, inputPorts, asBinding, plan) {
-    const e = classifyExpr(node);
-    if (e.kind !== "ref" || plan === undefined)
-        return null;
-    let ref = null;
-    if (asBinding !== undefined && e.path[0] === asBinding.name) {
-        try {
-            ref = goTypedInternals.typedFieldAccess(asBinding.name, asBinding.ref, e.path.slice(1), asBinding.plan).ref;
-        }
-        catch {
-            return null;
+/**
+ * goNativeResolveHead — the ONE ref-head resolver the runtime-free native-expr compiler reads, for cond
+ * `if`/branches, a map/fanout `when` guard, AND a port (go twin — Go's value semantics need no ownership
+ * ceremony). A head is a `$as` element binding, a prior body node's typed local, or an input port.
+ */
+function goNativeResolveHead(comp, plan, typedNodes, isPrior, opts) {
+    return (head) => {
+        if (opts?.asBinding !== undefined && opts.asBase !== undefined && head === opts.asBinding.name) {
+            return { expr: opts.asBase, ref: opts.asBinding.ref };
         }
+        if (isPrior(head))
+            return { expr: typedLocal(head), ref: typedNodes.get(head) };
+        return goInputHeadRef(head, comp, plan);
+    };
+}
+/**
+ * compilePortNode — lower a port expression to its native ports-struct field via the runtime-free
+ * native-expr compiler (native-expr.ts): the ONE port lowering. The port's field TYPE is the compiled
+ * `ref`, its initializer the compiled `expr` — so the two are derived from a SINGLE lowering and can
+ * never disagree. Any closed operator, a literal, a ref (input scalar/array/map, prior-node scalar/array,
+ * `$as` element field), a concat, a static array, an optional-input read — all resolve here. A port that
+ * cannot lower FAILS CLOSED loudly. A lowering that is FALLIBLE (hoists statements) is a covered SHAPE
+ * returned here as-is; only the value site (emitPortInit) rejects it, since a ports-struct literal cannot
+ * host statements — the coverage gate/type site must still see it as covered.
+ */
+function compilePortNode(node, comp, plan, typedNodes, isPrior, where, opts) {
+    const resolveHead = goNativeResolveHead(comp, plan, typedNodes, isPrior, opts);
+    try {
+        // zeroOut is unreachable: a fallible port is rejected at emitPortInit (a ports-struct literal hosts no
+        // statements), so the backend never renders an early-return with it.
+        return new NativeExprCompiler(makeGoExprBackend("", resolveHead, plan)).compilePort(node);
     }
-    else if (e.path.length === 1) {
-        const s = inputPorts[e.path[0]];
-        if (s !== undefined && s.type === "map") {
-            const et = s.elemType;
-            if (et !== undefined)
-                return { kind: "map", value: deriveTypeRef(et, plan) };
-        }
-        return null;
+    catch (e) {
+        if (!(e instanceof GeneratorFailure))
+            throw e;
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (runtime-free): ${where} ${JSON.stringify(node)} does not lower to a native Go value: ${e.message}`);
     }
-    if (ref === null)
-        return null;
-    if (ref.kind === "map" || ref.kind === "named")
-        return ref;
-    return null;
 }
-/** emitCompositePortValue (go twin) — the OWNED native value expr for a `{map:V}`/named port ref: a typed
- * field access `<elemBase>.<field>` (native map/struct, ZERO boxed Value). `elemBaseExpr` is the map arm's
- * element base for a `$as`-headed ref (omitted at top level — only input map-port refs resolve there). */
-function emitCompositePortValue(node, inputPorts, asBinding, plan, elemBaseExpr) {
-    const e = classifyExpr(node);
-    if (e.kind !== "ref")
-        return null;
-    if (asBinding !== undefined && elemBaseExpr !== undefined && e.path[0] === asBinding.name) {
-        let acc;
+/** the prior-node typed-local TypeRef map for a component (control-gate nodes are typeless; a map node
+ * carries its produced-array ref). Shared by coverage, the struct surface, and the runner. */
+function buildTypedNodes(comp, plan) {
+    const typedNodes = new Map();
+    for (const n of comp.body) {
+        if (isControlGate(n))
+            continue;
         try {
-            acc = goTypedInternals.typedFieldAccess(elemBaseExpr, asBinding.ref, e.path.slice(1), plan);
+            typedNodes.set(n.id, "map" in n ? mapNodeArrRef(n, plan) : deriveTypeRef(n.outType, plan));
         }
         catch {
-            return null;
-        }
-        if (acc.ref.kind !== "map" && acc.ref.kind !== "named")
-            return null;
-        return acc.expr;
-    }
-    // a WHOLE-port ref to an input MAP port (with elemType) — valid at top level OR inside a map node (a
-    // ref head that is NOT the `$as` element binding). Reads the native map[string]V off the input struct.
-    if ((asBinding === undefined || e.path[0] !== asBinding.name) && e.path.length === 1) {
-        const s = inputPorts[e.path[0]];
-        if (s !== undefined && s.type === "map" && s.elemType !== undefined) {
-            return `in.${goFieldName(e.path[0])}`;
+            /* untyped node — omit */
         }
     }
-    return null;
+    return typedNodes;
 }
 function staticArrElems(node) {
     if (node === null || typeof node !== "object" || Array.isArray(node))
@@ -214,90 +123,16 @@ function staticArrElems(node) {
     const arg = node.arr;
     return Array.isArray(arg) ? arg : null;
 }
-/**
- * portArrayElemRef (#110) — resolve a componentRef input port that binds a RUNTIME ARRAY (an IN-list /
- * array-bound WHERE head) to its native element TypeRef, or null when the port is not a covered array.
- * The covered shape is a SINGLE-SEGMENT, non-opt `ref` into an INPUT ARRAY port that carries a resolvable
- * `elemType` (scp-ir-architecture.md §5.2 / PortSchema.elemType — BC does NOT infer, consumer-interface
- * C3). The port then lowers to a native `[]ElemT` field fed straight from `in.<Field>` — ZERO boxed Value
- * on the read hot path. This REUSES the bc#108 `elemType` element lowering (deriveTypeRef over the input
- * port's elemType), extended from the `map…over` element-source path to a plain componentRef port.
- *
- * A static string array is a DIFFERENT covered shape ([]string, staticStringArrElems) — handled ahead of
- * this. An array port with NO resolvable elemType, an opt/multi-segment ref, or a non-array input schema
- * resolves to null here → the caller keeps its existing fail-closed behaviour (never a silent box).
- * Requires a TypePlan (an obj elemType maps to a named decl); without one it stays null (fail-closed).
- */
-function portArrayElemRef(node, inputPorts, plan) {
-    if (plan === undefined)
-        return null;
-    if (staticStringArrElems(node) !== null)
-        return null; // the static-string-array port ([]string) — not this shape.
-    const e = classifyExpr(node);
-    if (e.kind !== "ref" || e.opt || e.path.length !== 1)
-        return null;
-    const schema = inputPorts?.[e.path[0]];
-    if (schema === undefined || (schema.type !== "array" && schema.type !== "arr"))
-        return null;
-    const et = schema.elemType;
-    if (et === undefined)
-        return null;
-    return deriveTypeRef(et, plan);
-}
-/**
- * isNativeRawComponent — a component covered by the combined read emitter. Strictly sequential
- * (no real concurrency), body is ALL componentRef (no map/cond), default 'fail'/'continue'
- * policy, relationKind is single/connection or absent, and EVERY node carries outType + the
- * component carries outputType. relationKind:single / bindField ARE the point — inline exec makes
- * the child-present decision from the real parent result. Ports AND the output are evaluated via
- * the primitive SSoT over a Value-space portScope (so a dynamic operator in a port or an
- * obj-assembly output is fine — the SSoT handles fail-closed semantics; only the RESULT plane +
- * PORT container go native). A covered SHAPE that lacks outType is a fail-closed error raised at
- * emit (see assertTypedCoverage) — never a silent re-box.
- */
-/**
- * numLiteralGoExpr — a BARE numeric port literal (JSON number, e.g. the `limit: 20` Query port).
- * `classifyExpr` deliberately leaves a bare number `dynamic` (its checked int/float range rules are
- * the evaluate SSoT, expr.go evalNumberLiteral), so a plain number never reaches the str/bool/null
- * static branch. But a number literal IS statically resolvable to a native Go Value: the SAME
- * range check the runtime applies is performed HERE at generation time (integral literal in the
- * safe 2^53-1 window → int64; a fractional/exponent literal → the checked float64). Returns the Go
- * expression for the literal's Value, or null when the node is not a bare number OR the integral
- * literal is out of the safe window (that out-of-range case keeps the runtime INVALID_LITERAL
- * semantics — the port is NOT covered natively, so the whole component falls through, never a
- * silently-wrong inline). Mirrors coderuntime.evalNumberLiteral exactly.
- */
-const NUM_SAFE_INT = 9007199254740991; // 2^53 - 1 (expr.go safeInt)
-function numLiteralGoExpr(node) {
-    if (typeof node !== "number" || !Number.isFinite(node))
-        return null;
-    if (Number.isInteger(node)) {
-        if (node < -NUM_SAFE_INT || node > NUM_SAFE_INT)
-            return null; // out of safe window → not covered (runtime INVALID_LITERAL)
-        return `${PKG}.Value(int64(${node}))`;
+/** Does a port lower to a native value? The ELIGIBILITY gate ASKS the one port lowering (compilePortNode
+ * / native-expr) whether it can lower this port, rather than re-deriving the shape rules — so the gate
+ * and the emitter can never disagree. A port that does not lower (or lowers fallibly) fails closed. */
+function portIsStatic(node, comp, plan, typedNodes, asBinding) {
+    try {
+        compilePortNode(node, comp, plan, typedNodes, (h) => typedNodes.has(h), "port", asBinding !== undefined ? { asBinding, asBase: asBinding.name } : undefined);
+        return true;
     }
-    // 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) {
-    const arr = staticArrElems(node);
-    if (arr !== null)
-        return arr.every(portIsStatic);
-    if (numLiteralGoExpr(node) !== null)
-        return true; // bare number literal (e.g. Query `limit`)
-    const e = classifyExpr(node);
-    switch (e.kind) {
-        case "str":
-        case "bool":
-        case "null":
-        case "ref":
-            return true;
-        case "concat":
-            return e.parts.every((p) => portIsStatic(reconstructG(p)));
-        default:
-            return false;
+    catch {
+        return false; // an eligibility probe: any lowering failure ⇒ not native-covered here.
     }
 }
 /** The output must lower to a typed struct/value with no Value-scope read: a ref whose head is a
@@ -345,8 +180,8 @@ function isFullyTyped(comp) {
     }
     return true;
 }
-function isNativeRaw(comp) {
-    return isSequentialComponentRefRead(comp) && isFullyTyped(comp);
+function isNativeRaw(comp, plan) {
+    return isSequentialComponentRefRead(comp, plan) && isFullyTyped(comp);
 }
 /**
  * coveredMapNode — the #86 part 2 covered map shape (nestedBatchGet). A BATCHED `map` node whose:
@@ -361,7 +196,7 @@ function isNativeRaw(comp) {
  * element struct by copying the over element's typed fields + materializing the into field from the
  * aligned batch raw — NO boxed Value on any plane.
  */
-function coveredMapNode(n, bodyIds, comp) {
+function coveredMapNode(n, bodyIds, comp, plan, typedNodes) {
     if (n === null || typeof n !== "object" || !("map" in n))
         return false;
     const m = n.map;
@@ -398,11 +233,22 @@ function coveredMapNode(n, bodyIds, comp) {
             return false;
     }
     const ports = m.ports;
+    const asBinding = mapAsBinding(comp, n, typedNodes, plan);
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp, plan, typedNodes, asBinding))
             return false;
     return true;
 }
+/** the `$as` element binding for a covered map/fanout node's element ports (name + over-element TypeRef),
+ * or undefined when the over element type does not resolve (the node is then uncovered upstream). */
+function mapAsBinding(comp, node, typedNodes, plan) {
+    try {
+        return { name: node.map.as, ref: mapOverElemInfo(comp, node, typedNodes, plan).elemRef, plan };
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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,
@@ -411,7 +257,7 @@ function coveredMapNode(n, bodyIds, comp) {
  * 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) {
+function coveredFanoutNode(n, bodyIds, comp, plan, typedNodes) {
     if (n === null || typeof n !== "object" || !("fanout" in n))
         return false;
     const f = n.fanout;
@@ -431,8 +277,15 @@ function coveredFanoutNode(n, bodyIds, comp) {
             return false;
     }
     const ports = f.ports;
+    let asBinding;
+    try {
+        asBinding = { name: f.as, ref: fanoutOverElemInfo(comp, n, typedNodes, plan).elemRef, plan };
+    }
+    catch {
+        asBinding = undefined;
+    }
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp, plan, typedNodes, asBinding))
             return false;
     return true;
 }
@@ -441,8 +294,8 @@ function coveredFanoutNode(n, bodyIds, comp) {
  * reads. A real-concurrency plan whose parallel members include a map / bindField-relation child is
  * NOT covered here (falls through) — the static-parallel orchestration covers the componentRef fan-out
  * (the GroupAccessRead shape); a parallel map/relation-child stage is a further shape (out of scope). */
-function isSequentialComponentRefRead(comp) {
-    return coverageRejectReason(comp) === null;
+function isSequentialComponentRefRead(comp, plan) {
+    return coverageRejectReason(comp, plan) === null;
 }
 /**
  * coverageRejectReason — the DIAGNOSTIC twin of isSequentialComponentRefRead (bc#86/#89). Returns
@@ -452,10 +305,11 @@ function isSequentialComponentRefRead(comp) {
  * never disagree. This is the message the fail-closed dispatch surfaces per non-native component — the
  * user's signal to add native coverage, fix a genuinely-dynamic spec, or use the --ir dynamic surface.
  */
-function coverageRejectReason(comp) {
+function coverageRejectReason(comp, plan) {
     const ep = execPlan(comp);
     if (ep === null)
         return "component is not a straight-line/staged sequential exec plan (no static exec plan)";
+    const typedNodes = buildTypedNodes(comp, plan);
     // A parallel-stage member must be a componentRef node (no map) so the static parallel orchestration
     // is a clean fan-out — the bounded-concurrency error-precedence protocol is proven for that shape.
     // A map child inside a parallel stage still falls through (its per-element loop is a further shape).
@@ -500,7 +354,7 @@ function coverageRejectReason(comp) {
         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))
+            if (!coveredFanoutNode(n, bodyIds, comp, plan, typedNodes))
                 return `node '${n.id}' is a non-covered fanout shape (over an input array without elemType, or a dynamic element port)`;
             continue;
         }
@@ -508,7 +362,7 @@ function coverageRejectReason(comp) {
             // #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
             // elemType) falls through to the loud fail-closed reject.
-            if (!coveredMapNode(n, bodyIds, comp))
+            if (!coveredMapNode(n, bodyIds, comp, plan, typedNodes))
                 return `node '${n.id}' is a non-covered map shape (guard+into heterogeneous, or over an input array without elemType)`;
             continue;
         }
@@ -539,7 +393,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, plan, typedNodes) === false)
                 return `node '${n.id}' port '${p}' is not statically resolvable`;
     }
     if (!outputIsNativeLowerable(comp))
@@ -547,21 +401,21 @@ function coverageRejectReason(comp) {
     return null;
 }
 /** Fail closed if a covered read SHAPE lacks the typed annotations (no silent boxed re-box). */
-function assertTypedCoverage(comp) {
-    if (!isSequentialComponentRefRead(comp))
+function assertTypedCoverage(comp, plan) {
+    if (!isSequentialComponentRefRead(comp, plan))
         return;
     if (isFullyTyped(comp))
         return;
     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, typedNodes) {
+function emitPortsStruct(comp, node, plan, typedNodes, asBinding) {
     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, typedNodes));
+    const fieldTypes = portNames.map((p) => portFieldGoType(node.ports[p], comp, plan, typedNodes, `port '${p}' of node '${node.id}'`, asBinding !== undefined ? { asBinding, asBase: asBinding.name } : undefined));
     const fieldNames = portNames.map(goPortFieldName);
     const fields = portNames
         .map((p, i) => `\t${fieldNames[i]} ${fieldTypes[i]} // ${JSON.stringify(p)}`)
@@ -775,7 +629,7 @@ function emitMapPortsStructs(comp, node, typedNodes, plan) {
     // struct element). A pure-static/concat port ignores the binding.
     const { elemRef } = mapOverElemInfo(comp, node, typedNodes, plan);
     const asBinding = { name: m.as, ref: elemRef, plan };
-    const elemStruct = emitPortsStruct(comp, { id: node.id, component: m.component, ports: m.ports }, asBinding, plan);
+    const elemStruct = emitPortsStruct(comp, { id: node.id, component: m.component, ports: m.ports }, plan, typedNodes, asBinding);
     const batchStruct = `${structName}_batch`;
     return `${elemStruct}
 
@@ -793,7 +647,7 @@ function emitFanoutPortsStructs(comp, node, typedNodes, plan) {
     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 elemStruct = emitPortsStruct(comp, { id: node.id, component: f.component, ports: f.ports }, plan, typedNodes, asBinding);
     const batchStruct = `${structName}_batch`;
     return `${elemStruct}
 
@@ -940,43 +794,6 @@ 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";
@@ -1030,43 +847,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 +896,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 +937,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).
@@ -1175,115 +989,17 @@ function emitInDecoder(comp, plan) {
     return lines.join("\n");
 }
 /**
- * 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
- * `want==="string"`, a bool literal for `want==="bool"`. A ref resolves via `resolveRef` (typed input
- * field / prior-node scalar / element binding). A concat lowers ONLY into `string` and only when EVERY
- * part is itself a native string (so the concat's strings-only TYPE_MISMATCH can never fire — the parts
- * are statically strings), emitting `p0 + p1 + …`. Returns null (fall back to the Value path) otherwise.
+ * emitPortInit — the port field initializer, read off the ONE port lowering (compilePortNode / native-
+ * expr). The field's declared TYPE (portFieldGoType) is the SAME lowering's TypeRef, so type and value
+ * can never disagree. `isPrior` tests whether a ref head names a settled prior node at this position;
+ * `opts.asBinding`/`opts.asBase` carry a map/fanout element binding. A FALLIBLE lowering (hoisted
+ * statements) is rejected HERE — a ports-struct literal cannot host statements.
  */
-function emitNativeScalar(node, want, resolveRef) {
-    // a static arr is a Value port (never a scalar) — not native-lowerable here.
-    if (staticArrElems(node) !== null)
-        return null;
-    const e = classifyExpr(node);
-    switch (e.kind) {
-        case "str":
-            return want === "string" ? JSON.stringify(e.value) : null;
-        case "bool":
-            return want === "bool" ? (e.value ? "true" : "false") : null;
-        case "null":
-            return null; // a null literal is a Value(nil), never a required native scalar
-        case "ref": {
-            const sc = resolveRef(e.path[0], e.path.slice(1), e.opt);
-            if (sc === null || sc.scalar !== want)
-                return null;
-            return sc.expr;
-        }
-        case "concat": {
-            if (want !== "string")
-                return null;
-            const parts = [];
-            for (const p of e.parts) {
-                const sub = emitNativeScalar(reconstructG(p), "string", resolveRef);
-                if (sub === null)
-                    return null;
-                // parenthesize a `+` sub-expression so string concatenation binds correctly (a ref/literal is
-                // atomic; a nested concat is already a single `a + b` — wrap to keep it one operand).
-                parts.push(sub.includes(" + ") ? `(${sub})` : sub);
-            }
-            return parts.join(" + ");
-        }
-        default:
-            return null;
-    }
-}
-/**
- * emitPortInit — emit the port field build for one port as a FULLY NATIVE Go expression (bc#90 /
- * runtime-free). Every covered port lowers to a concrete Go value assigned straight into the ports
- * struct field — NO `dslcontracts.Value`, NO nvVE helper, NO `.(T)` type-assert:
- *   - a static string array (projection) → `[]string{"a", "b", ...}` (change #2);
- *   - a bare int/float number literal (e.g. Query `limit: 20`) → `int64(20)` / `float64(...)`;
- *   - a string/bool/scalar-input port → the native scalar expression (emitNativeScalar).
- * A port that CANNOT lower natively FAILS CLOSED (there is no boxed Value fallback on the covered
- * 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, typedNodes, asBinding, elemBaseExpr) {
-    const fieldName = goPortFieldName(pn);
-    // #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) {
-        const compExpr = emitCompositePortValue(expr, inputPorts ?? {}, asBinding, plan, elemBaseExpr);
-        if (compExpr !== null)
-            return `${fieldName}: ${compExpr}`;
-    }
-    // #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.
-    // The over-elem/element-source case (map…over) already resolves via mapOverElemInfo; this is the plain
-    // componentRef port (an IN-list / array-bound WHERE head).
-    if (inputPorts !== undefined && portArrayElemRef(expr, inputPorts, plan) !== null) {
-        const e = classifyExpr(expr);
-        if (e.kind === "ref" && e.path.length === 1) {
-            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) {
-        if (fieldGoType !== "[]string") {
-            throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90): port '${pn}' is a static string array but its field type is '${fieldGoType}' (expected []string).`);
-        }
-        return `${fieldName}: []string{${strArr.map((s) => JSON.stringify(s)).join(", ")}}`;
-    }
-    // a bare number literal (e.g. Query `limit: 20`): the SSoT range check ran in numLiteralGoExpr —
-    // emit the concrete native int64/float64 (unwrap the dslcontracts.Value(...) box: it was only there
-    // for the old boxed path; the range check is what matters, and it already passed).
-    const num = numLiteralGoExpr(expr);
-    if (num !== null) {
-        if (fieldGoType === "int64")
-            return `${fieldName}: int64(${expr})`;
-        if (fieldGoType === "float64")
-            return `${fieldName}: float64(${expr})`;
-        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go combined read (bc#90): port '${pn}' is a number literal but its field type is '${fieldGoType}'.`);
-    }
-    // string / bool / scalar-input / concat → native scalar expression (no Value, no `.(T)`).
-    const scalarWant = fieldGoType;
-    const native = emitNativeScalar(expr, scalarWant, resolveRef);
-    if (native !== null) {
-        return `${fieldName}: ${native}`;
-    }
-    // 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.`);
+function emitPortInit(pn, expr, comp, plan, typedNodes, isPrior, opts) {
+    const c = compilePortNode(expr, comp, plan, typedNodes, isPrior, `port '${pn}'`, opts);
+    if (c.stmts.length > 0)
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (runtime-free): port '${pn}' ${JSON.stringify(expr)} lowers to 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 `${goPortFieldName(pn)}: ${c.expr}`;
 }
 /**
  * emitParallelStageArm (bc#87) — EXPLICIT static parallel orchestration for a real-concurrency stage.
@@ -1306,7 +1022,7 @@ function emitPortInit(pn, expr, fieldGoType, resolveRef, inputPorts, plan, typed
  *
  * NO RunPlan / []OpSpec / planSpec walk: the staging, the bound, and which ops are parallel are baked.
  */
-function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes, plan, priorNodeAt, zeroOut, flags, resolveRefAt) {
+function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes, plan, priorNodeAt, zeroOut, flags) {
     const lines = [];
     const ids = stage.map((i) => comp.body[i].id);
     lines.push(`\t// ── bc#87 real-concurrency stage {${ids.map((x) => JSON.stringify(x)).join(", ")}} — static parallel`);
@@ -1395,11 +1111,8 @@ function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes
             }
         }
         const inits = [];
-        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, typedNodes);
-            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan, typedNodes));
+            inits.push(emitPortInit(pn, node.ports[pn], comp, plan, typedNodes, (h) => priorNodeAt(h, atPos)));
         }
         lines.push(`${ind}ps_${s} = ${structName}{${inits.join(", ")}}`);
         lines.push(`${ind}run_${s} = true`);
@@ -1506,35 +1219,6 @@ function emitNativeRawRunner(comp, plan, flags) {
     // assert on a row value — the runner reads row.<Field> directly and copies each into the outType local.
     lines.push(`func ${runnerName(comp.name)}[H ${handlerIfaceName(comp.name)}](handlers H, in ${inStructName(comp.name)}) (${outStructType}, error) {`);
     lines.push(`\t_ = in`);
-    // resolveNativeRef for this runner: a ref head is either a PRIOR NODE (read its typed struct field
-    // directly) or an INPUT PORT (read the typed `in.<Field>`). A REQUIRED scalar resolves to a native
-    // Go expression; an opt / non-scalar / refOpt resolves to null (falls back to the nvVE Value path).
-    const resolveRefAt = (atPos) => (head, restPath, opt) => {
-        if (opt)
-            return null; // a refOpt may be nil at runtime — keep the Value path (opt-nil semantics)
-        if (priorNodeAt(head, atPos)) {
-            const baseRef = typedNodes.get(head);
-            let acc;
-            let expr;
-            try {
-                const r = goTypedInternals.typedFieldAccess(typedLocal(head), 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) };
-        }
-        if (restPath.length !== 0)
-            return null; // input.<field> path is a Value walk — not a native scalar
-        const scalar = inputScalarKind(comp.inputPorts?.[head]);
-        if (scalar === undefined)
-            return null;
-        return { expr: `in.${goFieldName(head)}`, scalar };
-    };
     for (const k of order.keys()) {
         const node = comp.body[order[k]];
         const id = node.id;
@@ -1557,7 +1241,7 @@ function emitNativeRawRunner(comp, plan, flags) {
         // ascending-sorted stages), so we emit the block at the first member and skip the rest.
         const stage = ep.parallelStageOf.get(i);
         if (stage !== undefined && stage[0] === i) {
-            lines.push(emitParallelStageArm(comp, stage, k, ep.concurrency, metas, typedNodes, plan, priorNodeAt, zeroOut, flags, resolveRefAt));
+            lines.push(emitParallelStageArm(comp, stage, k, ep.concurrency, metas, typedNodes, plan, priorNodeAt, zeroOut, flags));
             k += stage.length - 1;
             continue;
         }
@@ -1629,11 +1313,8 @@ function emitNativeRawRunner(comp, plan, flags) {
         // dslcontracts.Value, ZERO nvVE helper, ZERO `.(T)`. A genuinely-dynamic port FAILS CLOSED.
         const inits = [];
         const boundArg = node.bindField !== undefined ? `bound_${s}` : "nil";
-        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, typedNodes);
-            inits.push(emitPortInit(pn, expr, fieldGoType, resolveRef, comp.inputPorts, plan, typedNodes));
+            inits.push(emitPortInit(pn, node.ports[pn], comp, plan, typedNodes, (h) => priorNodeAt(h, k)));
         }
         lines.push(`${indent}ports_${s} := ${structName}{${inits.join(", ")}}`);
         const oc = `row_${s}`;
@@ -1726,67 +1407,15 @@ function emitMapArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut, f
     const mkGuard = (elemVar) => {
         if (!hasGuard)
             return null;
-        const resolveHead = (head) => {
-            if (head === asName)
-                return { expr: elemVar, ref: overElemRef };
-            if (priorHere(head))
-                return { expr: typedLocal(head), ref: typedNodes.get(head) };
-            return goInputHeadRef(head, comp, plan);
-        };
-        const be = makeGoExprBackend(zeroOut, resolveHead, plan);
-        return new NativeExprCompiler(be).compileBool(m.when);
+        const resolveHead = goNativeResolveHead(comp, plan, typedNodes, priorHere, { asBinding: { name: asName, ref: overElemRef, plan }, asBase: elemVar });
+        return new NativeExprCompiler(makeGoExprBackend(zeroOut, resolveHead, plan)).compileBool(m.when);
     };
     // emit the per-element native ports struct build (shared; `il` is the indent inside the element
     // loop, `elemVar` the over element loop variable). Returns the lines building `ep_<s>`.
     const buildPorts = (il, elemVar) => {
-        const out = [];
-        const inits = [];
-        // resolveNativeRef for a map element port: a ref head is the element binding ($as → the over element
-        // typed struct field `elemVar.<Field>`), a PRIOR NODE (its typed struct field), or an INPUT PORT
-        // (`in.<Field>`). A REQUIRED scalar lowers to a native Go expr; opt / non-scalar → null (Value path).
-        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(m.ports[pn], comp.inputPorts, `map port '${pn}' of node '${node.id}'`, asBinding, plan);
-            // #108-map: pass the element binding + base expr so a `$as` MAP/NAMED field port reads the typed composite.
-            inits.push(emitPortInit(pn, m.ports[pn], fieldGoType, resolveRef, comp.inputPorts, plan, undefined, asBinding, elemLocal(s)));
-        }
-        out.push(`${il}ep_${s} := ${structName}{${inits.join(", ")}}`);
-        return out;
+        const inits = portNames.map((pn) => emitPortInit(pn, m.ports[pn], comp, plan, typedNodes, priorHere, { asBinding, asBase: elemVar }));
+        return [`${il}ep_${s} := ${structName}{${inits.join(", ")}}`];
     };
     const lines = [];
     const closers = [];
@@ -1924,47 +1553,8 @@ function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut
     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));
-        }
+        const inits = portNames.map((pn) => emitPortInit(pn, f.ports[pn], comp, plan, typedNodes, priorHere, { asBinding, asBase: elemVar }));
         return [`${il}ep_${s} := ${structName}{${inits.join(", ")}}`];
     };
     const lines = [];
@@ -2019,23 +1609,19 @@ 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 null;
+    return { expr: `in.${goFieldName(head)}`, ref };
 }
 /**
  * emitCondArm — the struct-native exec of a covered cond node (#108). Mirrors run_behavior's cond
@@ -2049,11 +1635,7 @@ function emitCondArm(comp, node, atPos, typedNodes, plan, priorNodeAt, zeroOut)
     const c = node.cond;
     const s = sanitize(node.id);
     const priorHere = (head) => priorNodeAt(head, atPos);
-    const resolveHead = (head) => {
-        if (priorHere(head))
-            return { expr: typedLocal(head), ref: typedNodes.get(head) };
-        return goInputHeadRef(head, comp, plan);
-    };
+    const resolveHead = goNativeResolveHead(comp, plan, typedNodes, priorHere);
     const be = makeGoExprBackend(zeroOut, resolveHead, plan);
     const compiler = new NativeExprCompiler(be);
     const cond = compiler.compileBool(c.if);
@@ -2276,11 +1858,31 @@ function makeGoExprBackend(zeroOut, resolveHead, plan) {
         notOp: (a) => `(!${a})`,
         structLit: (name, inits) => `${name}{${inits.map((i) => `${goFieldName(i.field)}: ${i.expr}`).join(", ")}}`,
         arrLit: (elemTy, items) => `[]${elemTy}{${items.join(", ")}}`,
+        // a projection port of static string literals — bare `[]string{"a", "b"}` (Go string literals are
+        // already allocation-free; no divergence from the general arr path, so no golden churn).
+        staticStrArr: (literals) => ({ expr: `[]string{${literals.map((s) => JSON.stringify(s)).join(", ")}}`, type: "[]string" }),
         // an opt (`*T`) NONE literal is `nil` (the inner type is not needed for the untyped nil in Go).
         optNone: (_innerTy) => "nil",
         // 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 }.
@@ -2461,12 +2063,14 @@ var ExpectedSpecVersions = map[string]int64{"behavior": ${sv.behavior}, "express
 }
 // ── module assembly ──────────────────────────────────────────────────────────────────
 function emit(ctx) {
+    // The type plan is the SSoT the coverage gate + the port lowering both read (the gate ASKS the port
+    // lowering whether a port lowers), so it is built up-front — before the coverage checks.
+    const plan = buildTypePlan(ctx.ir);
     // Fail closed if a covered read SHAPE lacks the typed annotations (no silent re-box).
     for (const c of ctx.ir.components)
-        assertTypedCoverage(c);
-    const native = ctx.ir.components.filter(isNativeRaw);
-    const nonNative = ctx.ir.components.filter((c) => !isNativeRaw(c));
-    const plan = buildTypePlan(ctx.ir);
+        assertTypedCoverage(c, plan);
+    const native = ctx.ir.components.filter((c) => isNativeRaw(c, plan));
+    const nonNative = ctx.ir.components.filter((c) => !isNativeRaw(c, plan));
     const decls = emitTypeDecls(plan);
     // #108: reset the native-expr helper-usage accumulator (set by the cond/guard compiler when it emits
     // a fallible checked-arith helper call — determines whether the helper library + `math` import ship).
@@ -2481,11 +2085,7 @@ function emit(ctx) {
     const runnerCodes = [];
     for (const c of native) {
         inStructs.push(emitInStruct(c, plan));
-        const typedNodes = new Map();
-        // build the full typed-node map FIRST so a map's over-element resolution can see every node.
-        for (const n of c.body)
-            if (!isControlGate(n))
-                typedNodes.set(n.id, "map" in n ? mapNodeArrRef(n, plan) : deriveTypeRef(n.outType, plan)); // #125: control-gate typeless; map は produced-array ref に正規化
+        const typedNodes = buildTypedNodes(c, plan);
         for (const n of c.body) {
             if ("fanout" in n) {
                 // v3: a fanout node emits a per-id element ports struct + a batch struct (like a batched map).
@@ -2501,7 +2101,7 @@ function emit(ctx) {
             }
             else {
                 // #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));
+                structs.push(emitPortsStruct(c, n, plan, typedNodes));
             }
         }
         // CONCRETE per-node row structs + the per-component handler interface (the fully-concrete seam).
@@ -2530,7 +2130,7 @@ function emit(ctx) {
     // minimal, runtime-free header.
     if (nonNative.length > 0) {
         const rejects = nonNative
-            .map((c) => `  - component '${c.name}': ${coverageRejectReason(c) ?? "not a covered native read"}`)
+            .map((c) => `  - component '${c.name}': ${coverageRejectReason(c, plan) ?? "not a covered native read"}`)
             .join("\n");
         throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `go typed-native (native codegen) surface: ${nonNative.length} component(s) are NOT a covered native read:\n${rejects}\n\n` +
             `The --typed-native (native codegen) surface is native-only and fail-closed: it does not silently ` +
@@ -2588,8 +2188,8 @@ function emit(ctx) {
  */
 export function goTypedNativeObserve(ir, runtimeImport) {
     const components = ir.components;
-    const native = components.filter(isNativeRaw);
     const plan = buildTypePlan(ir);
+    const native = components.filter((c) => isNativeRaw(c, plan));
     const serializers = emitSerializers(plan);
     const marshallers = goTypedInternals.emitMarshallers(plan);
     const mustHelpers = emitMustHelpers(plan);
@@ -2713,17 +2313,25 @@ ${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" : "_";
+            // a NAMED outType row is FLATTENED (no Val) — echo a named port by copying the struct's fields;
+            // a scalar/arr/opt outType row holds the port in its single Val field.
+            const echoRow = (ep) => ref.kind === "named"
+                ? `${rowT}{${findDecl(plan, ref.name).fields.map((f) => `${goFieldName(f.name)}: ports.${goPortFieldName(ep)}.${goFieldName(f.name)}`).join(", ")}}`
+                : `${rowT}{Val: ports.${goPortFieldName(ep)}}`;
+            const echoBranch = echoable
+                .map((ep) => `\tif src.echo == ${JSON.stringify(ep)} {\n\t\treturn ${echoRow(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 +2383,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 +2479,14 @@ ${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 (a scalar/arr/
+ * opt row via its Val; a NAMED row via its flattened fields copied from the struct port). A port with a
+ * different type is not echoable (the row could not hold it). */
+function echoablePorts(comp, node, ref, plan, typedNodes) {
+    const want = renderTypeRef(ref);
+    return Object.keys(node.ports).filter((p) => portFieldGoType(node.ports[p], comp, plan, typedNodes, `port '${p}'`) === 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