behavior-contracts 0.8.3 → 0.8.5

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

@@ -2,12 +2,12 @@ import { GeneratorFailure } from "./core.js";
 import { isControlGate } from "../behavior.js";
 import { rustStraightlineInternals } from "./emit-shared-rust.js";
 import { rustTypedInternals } from "./emit-shared-rust-typed.js";
-import { buildTypePlan, deriveTypeRef, findDecl } from "./typed.js";
+import { buildTypePlan, deriveTypeRef, findDecl, inputPortIsOptional, inputPortTypeRef } from "./typed.js";
 import { concurrencyPlan, execPlan, analyzeSequentialOps, classifyExpr } from "./straightline.js";
 import { NativeExprCompiler } from "./native-expr.js";
 import { buildAsyncPlans } from "./async-plan.js";
 const { sanitize, rustStrLit } = rustStraightlineInternals;
-const { rustFieldName, renderTypeRef, typedCell, typedFieldAccess, serializeTyped, emitTypeDecls, emitDefaults, emitSerializers, emitTypedValue, emitMarshallers, emitMarshalHelpers, materializeExpr, } = rustTypedInternals;
+const { typeRefIsCopy, rustFieldName, renderTypeRef, typedCell, typedFieldAccess, serializeTyped, emitTypeDecls, emitDefaults, emitSerializers, emitTypedValue, emitMarshallers, emitMarshalHelpers, materializeExpr, } = rustTypedInternals;
 /** rustErr — build the LOCAL concrete error value for a behavior/plan failure on the covered read
  * plane (runtime-free). The covered module declares a local `BehaviorError` (see emitBehaviorErrorType);
  * the runner returns `Result<_, BehaviorError>` over THAT local type. This REPLACES the old
@@ -88,188 +88,15 @@ function staticArrElems(node) {
     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 not a covered array. The covered
- * shape is a SINGLE-SEGMENT, non-opt `ref` into an INPUT ARRAY port carrying a resolvable `elemType`
- * (PortSchema.elemType — BC does NOT infer, consumer-interface C3). The port lowers to a native
- * `Vec<ElemT>` fed from `in_.<field>.clone()`. Reuses the bc#108 elemType lowering, extended from the
- * `map…over` element-source path to a plain componentRef port. A static string array is a different
- * covered shape (Vec<&'static str>) — handled ahead of this. No resolvable elemType / opt / multi-segment
- * ref / non-array schema / no plan → null (caller keeps its existing fail-closed behaviour). */
-function portArrayElemRef(node, inputPorts, plan) {
-    if (plan === undefined)
-        return null;
-    if (staticStringArrElems(node) !== null)
-        return null;
-    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);
-}
-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 } = typedFieldAccess(asBinding.name, asBinding.ref, e.path.slice(1), asBinding.plan);
-                    if (ref.kind === "scalar" && ref.scalar !== "null")
-                        return rustScalar(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 "i64";
-                    if (s.type === "float" || s.type === "number")
-                        return "f64"; // `"number"` = the float channel.
-                    if (s.type === "bool")
-                        return "bool";
-                }
-            }
-            return "Value";
-        }
-        default:
-            return "Value";
-    }
-}
-/** 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;
-}
-/**
- * portFieldRustType — the NATIVE Rust type for a covered port field (bc#90 / runtime-free). The covered
- * ports struct carries NO `Value` field: every port lowers to a concrete Rust type.
- *   - a static string-array (projection) → `Vec<&'static str>` (change #2);
- *   - a bare int/float number literal (e.g. Query `limit: 20`) → `i64` / `f64`;
- *   - a string/bool/scalar-input port → the scalar Rust 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 `Value`
- * fallback on the native module). `where` names the emission site for the error.
+ * portFieldRustType — the NATIVE Rust 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 `Value` field:
+ * every port lowers to a concrete Rust 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 portFieldRustType(node, inputPorts, where = "port", asBinding, plan, typedNodes) {
-    if (staticStringArrElems(node) !== null)
-        return "Vec<&'static str>";
-    // #110: a componentRef port bound to a runtime array input port (with a resolvable elemType) → Vec<ElemT>.
-    const arrElem = portArrayElemRef(node, inputPorts, plan);
-    if (arrElem !== null)
-        return `Vec<${renderTypeRef(arrElem)}>`;
-    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) → Vec<ElemT>.
-    const priorArr = priorNodeArrElemInfo(node, typedNodes, plan);
-    if (priorArr !== null)
-        return `Vec<${renderTypeRef(priorArr.elemRef)}>`;
-    const num = numLiteralRustExpr(node);
-    if (num !== null)
-        return typeof node === "number" && Number.isInteger(node) ? "i64" : "f64";
-    // a ref to a `$as` element field (or an input port) whose type is a MAP or NAMED struct (NOT a bare
-    // scalar) → the native map/struct type. #108-map: a `{map:V}`-typed field (e.g. a nested
-    // `map<map<obj>>` write port) lowers to BTreeMap; a named field lowers to its struct. Reuses the same
-    // typedFieldAccess resolution as the scalar path; a genuinely-untyped ref still falls through.
-    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", `rust combined read (bc#90 / runtime-free): ${where} '${JSON.stringify(node)}' does not lower to a native Rust type (would need a boxed 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;
-}
-/** portCompositeRef — the full TypeRef of a port that is a `{ref:[...]}` into a `$as` element field OR
- * an input port whose type is a MAP or NAMED struct (a non-scalar covered field). Returns null when the
- * node is not such a ref (so the caller falls through to the scalar/array inference). #108-map: enables a
- * `{map:V}`-typed field port (e.g. a nested map write port) to lower to the native BTreeMap. */
-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 = typedFieldAccess(asBinding.name, asBinding.ref, e.path.slice(1), asBinding.plan).ref;
-        }
-        catch {
-            return null;
-        }
-    }
-    else if (e.path.length >= 1) {
-        const s = inputPorts[e.path[0]];
-        // a whole-port ref to an input MAP port carrying an elemType → its BTreeMap type (mirrors
-        // inputPortRustType); a deeper path into an input port is not resolved here (no field type source).
-        if (s !== undefined && s.type === "map" && e.path.length === 1) {
-            const et = s.elemType;
-            if (et !== undefined)
-                return { kind: "map", value: deriveTypeRef(et, plan) };
-        }
-        return null;
-    }
-    if (ref === null)
-        return null;
-    // only MAP / NAMED composite fields here — scalars/arrays keep their existing dedicated paths.
-    if (ref.kind === "map" || ref.kind === "named")
-        return ref;
-    return null;
-}
-/** emitCompositePortValue — the OWNED native value expr for a port that is a ref to a `$as` element
- * MAP/NAMED field (or an input map port): a typed field access `.clone()` (the concrete BTreeMap/struct,
- * ZERO boxed Value). `elemBaseExpr` is the map arm's element base (`oel_<mapId>`) for a `$as`-headed ref;
- * omitted at the top level (only input-port composite refs resolve there). Returns null otherwise. */
-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;
-        try {
-            acc = typedFieldAccess(elemBaseExpr, asBinding.ref, e.path.slice(1), plan);
-        }
-        catch {
-            return null;
-        }
-        if (acc.ref.kind !== "map" && acc.ref.kind !== "named")
-            return null;
-        return `${acc.expr}.clone()`;
-    }
-    // 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). Clones the native BTreeMap 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_.${rustFieldName(e.path[0])}.clone()`;
-        }
-    }
-    return null;
+function portFieldRustType(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);
 }
 /**
  * emitPortsStruct — the CONCRETE native ports struct for a componentRef node. Typed fields per the
@@ -278,13 +105,13 @@ function emitCompositePortValue(node, inputPorts, asBinding, plan, elemBaseExpr)
  * reads `ports.f_<field>` DIRECTLY. The struct derives Clone (a bc#87 parallel stage clones it into the
  * per-worker dispatch). Every field is a NATIVE Rust type (bc#90 / runtime-free) — NO boxed `Value`.
  */
-function emitPortsStruct(comp, node, asBinding, plan, typedNodes) {
+function emitPortsStruct(comp, node, plan, typedNodes, asBinding) {
     const name = portsStructName(comp.name, node.id);
     const portNames = Object.keys(node.ports);
     if (portNames.length === 0) {
         return `// ${name} — native ports for node '${node.id}' (${node.component}); no ports.\n#[derive(Clone)]\npub struct ${name};`;
     }
-    const types = portNames.map((p) => portFieldRustType(node.ports[p], comp.inputPorts, `port '${p}' of node '${node.id}'`, asBinding, plan, typedNodes));
+    const types = portNames.map((p) => portFieldRustType(node.ports[p], comp, plan, typedNodes, `port '${p}' of node '${node.id}'`, asBinding !== undefined ? { asBinding, asBase: asBinding.name } : undefined));
     const fields = portNames
         .map((p, i) => `    pub ${portFieldName(p)}: ${types[i]}, // ${JSON.stringify(p)}`)
         .join("\n");
@@ -308,7 +135,7 @@ function emitMapPortsStructs(comp, node, typedNodes, plan) {
     // #108: element ports may read the `$as` binding — resolve the over element type for native typing.
     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);
     return `${elemStruct}
 
 // ${batch} — CONCRETE batched ports for map '${node.id}': the Vec of per-element CONCRETE ports structs
@@ -326,7 +153,7 @@ function emitFanoutPortsStructs(comp, node, typedNodes, plan) {
     const batch = `${name}Batch`;
     const { elemRef } = fanoutOverElemInfo(comp, node, typedNodes, plan);
     const asBinding = { name: f.as, ref: elemRef, plan };
-    const elemStruct = emitPortsStruct(comp, { id: node.id, component: f.component, ports: f.ports }, asBinding, plan);
+    const elemStruct = emitPortsStruct(comp, { id: node.id, component: f.component, ports: f.ports }, plan, typedNodes, asBinding);
     return `${elemStruct}
 
 // ${batch} — CONCRETE batched ports for fanout '${node.id}': the Vec of per-id CONCRETE ports structs.
@@ -389,25 +216,47 @@ function makeRustExprBackend(resolveHead, plan) {
         notOp: (a) => `(!${a})`,
         structLit: (name, inits) => `${name} { ${inits.map((i) => `${rustFieldName(i.field)}: ${i.expr}`).join(", ")} }`,
         arrLit: (elemTy, items) => `{ let __v: Vec<${elemTy}> = vec![${items.join(", ")}]; __v }`,
+        // a projection port of static string literals — bare `&'static str` literals, ZERO heap allocation
+        // (the field is `Vec<&'static str>`, so `vec!["a", "b"]` infers `&'static str` elements).
+        staticStrArr: (literals) => ({ expr: `vec![${literals.map((s) => rustStrLit(s)).join(", ")}]`, type: "Vec<&'static str>" }),
         // an opt (`Option<T>`) NONE literal. Annotate as `Option::<T>::None` so it type-infers in ANY
         // position (a bare `None` can be ambiguous; the explicit turbofish keeps it a fully-typed value).
         optNone: (innerTy) => `Option::<${innerTy}>::None`,
         // opt (`Option<T>`) null-presence test: present = `expr.is_some()`, absent = `expr.is_none()`.
-        optIsSome: (expr) => `${expr}.is_some()`,
-        optIsNone: (expr) => `${expr}.is_none()`,
+        // A presence test only READS the discriminant, so an owning clone of the operand (which a head
+        // resolver adds so the value can be moved into a port) is dropped here — testing `Option<String>`
+        // must not heap-allocate. Mirrors the go twin's zero-cost `!= nil`.
+        optIsSome: (expr) => `${rustStripTrailingClone(expr)}.is_some()`,
+        optIsNone: (expr) => `${rustStripTrailingClone(expr)}.is_none()`,
+        // opt (`Option<T>`) defaulted to a PURE default — it cannot fail and has no effect, so its
+        // evaluation order is UNOBSERVABLE and both forms below are correct (a FALLIBLE default, where
+        // laziness IS observable, goes to optCoalesceGuard instead). `unwrap_or` is EAGER — fine for a plain
+        // literal/copy. A default that allocates (an owned `String`, a struct/vec literal) uses
+        // `unwrap_or_else`, whose closure defers the allocation to the absent branch: not a semantic
+        // requirement here, but pointless work otherwise — and what clippy `or_fun_call` asks for.
+        optUnwrapOr: (optExpr, defaultExpr, _innerTy) => /^[A-Za-z0-9_.:]+$/.test(defaultExpr) ? `${optExpr}.unwrap_or(${defaultExpr})` : `${optExpr}.unwrap_or_else(|| ${defaultExpr})`,
+        // opt defaulted to a FALLIBLE default — a `match`, NOT a closure: the default's hoisted `?` early
+        // returns must propagate out of the ENCLOSING fn, which `unwrap_or_else`'s closure would swallow
+        // (it would try to return from the closure). Only the None arm evaluates the default.
+        optCoalesceGuard: (temp, ty, optExpr, bindTemp, dStmts, dExpr) => [
+            `let ${temp}: ${ty} = match ${optExpr} {`,
+            `    Some(${bindTemp}) => ${bindTemp},`,
+            `    None => { ${rustBlockBody(dStmts, dExpr)} }`,
+            `};`,
+        ],
         ternary: (cond, t, e, _ty) => `(if ${rustStripOuterParens(cond)} { ${rustStripOuterParens(t)} } else { ${rustStripOuterParens(e)} })`,
         shortCircuitBool: (op, temp, left, rStmts, rExpr) => {
             // and: let temp = if left { <rStmts> rExpr } else { false };  or: if left { true } else { <rStmts> rExpr }.
             // build a block that runs rStmts then yields rExpr (parens stripped — block-tail is not a sub-expr).
-            const rblock = `{ ${rStmts.join(" ")} ${rustStripOuterParens(rExpr)} }`;
+            const rblock = `{ ${rustBlockBody(rStmts, rExpr)} }`;
             if (op === "and") {
                 return [`let ${temp}: bool = if ${rustStripOuterParens(left)} ${rblock} else { false };`];
             }
             return [`let ${temp}: bool = if ${rustStripOuterParens(left)} { true } else ${rblock};`];
         },
         condGuard: (temp, ty, cond, tStmts, tExpr, eStmts, eExpr) => {
-            const tblock = `{ ${tStmts.join(" ")} ${rustStripOuterParens(tExpr)} }`;
-            const eblock = `{ ${eStmts.join(" ")} ${rustStripOuterParens(eExpr)} }`;
+            const tblock = `{ ${rustBlockBody(tStmts, tExpr)} }`;
+            const eblock = `{ ${rustBlockBody(eStmts, eExpr)} }`;
             return [`let ${temp}: ${ty} = if ${rustStripOuterParens(cond)} ${tblock} else ${eblock};`];
         },
     };
@@ -416,6 +265,17 @@ function makeRustExprBackend(resolveHead, plan) {
 function rustSnake(name) {
     return name.replace(/([a-z])([A-Z0-9])/g, "$1_$2").replace(/([0-9])([a-z])/g, "$1_$2").toLowerCase();
 }
+/** rustBlockBody — the body of a block-expression that runs `stmts` then yields `expr`. A trailing
+ * `let t = E; t` is collapsed to `E`: binding a temp only to return it on the next line is clippy's
+ * `let_and_return` (an error under `-D warnings`), and the hoisted-fallible shape produces exactly that
+ * whenever the block's tail IS the hoisted temp. */
+function rustBlockBody(stmts, expr) {
+    const last = stmts[stmts.length - 1];
+    const m = last !== undefined ? /^let\s+([A-Za-z0-9_]+)(?::\s*[^=]+)?\s*=\s*(.+);$/.exec(last) : null;
+    if (m !== null && m[1] === expr)
+        return [...stmts.slice(0, -1), m[2]].join(" ");
+    return [...stmts, rustStripOuterParens(expr)].join(" ");
+}
 /** strip ONE redundant outer paren pair from an expr (clippy `if (cond)` unused_parens). Only when the
  * whole string is a single balanced `( … )` — a `(a) && (b)` stays untouched. */
 function rustStripOuterParens(expr) {
@@ -433,6 +293,12 @@ function rustStripOuterParens(expr) {
     }
     return expr.slice(1, -1);
 }
+/** Drop a TRAILING `.clone()` from an expression — for a position that only reads the value (no move),
+ * so an owning clone added by a head resolver is pure waste. Only a clone at the very END is dropped: a
+ * `.clone()` mid-path (`t_x.borrow().clone().field`) still owns the field access that follows it. */
+function rustStripTrailingClone(expr) {
+    return expr.endsWith(".clone()") ? expr.slice(0, -".clone()".length) : expr;
+}
 /** Rust float literal (finite; integral gets `.0`). */
 function rustFloatLitExpr(n) {
     if (Number.isInteger(n))
@@ -781,44 +647,6 @@ function mapOverElemInfo(comp, node, typedNodes, plan) {
 function mapOverElemType(comp, node, typedNodes, plan) {
     return renderTypeRef(mapOverElemInfo(comp, node, typedNodes, plan).elemRef);
 }
-/**
- * priorNodeArrElemInfo (#129, rust twin) — 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 OWNED Rust Vec expression that yields it. 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 `Vec<ElemT>` cloned
- * out of the prior node's typed cell — 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 = typedFieldAccess(`${typedCell(e.path[0])}.borrow()`, 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.
-    // OWNED: clone the borrowed slice out of the RefCell so the ports struct owns its Vec<ElemT>.
-    return { elemRef: acc.ref.elem, overExpr: `${acc.expr}.clone()` };
-}
 // ── eligibility ─────────────────────────────────────────────────────────────────────
 function reconstructR(e) {
     switch (e.kind) {
@@ -836,50 +664,35 @@ function reconstructR(e) {
             return e.node;
     }
 }
-/**
- * numLiteralRustExpr — a BARE numeric port literal (JSON number, e.g. the `limit: 20` Query port).
- * `classifyExpr` leaves a bare number `dynamic` (its checked int/float range rules are the evaluate
- * SSoT), so it never reaches the static str/bool/null branch — but a number literal IS statically
- * resolvable to a native `Value`: the SAME range check the runtime applies (integral literal in the
- * safe 2^53-1 window → Value::Int; a fractional/exponent literal → the checked Value::Float) is
- * performed HERE at generation time. Returns the Rust expression for the literal's Value, or null
- * when the node is not a bare number OR an integral literal is out of the safe window (keeping the
- * runtime INVALID_LITERAL semantics — the port is not covered natively, the component falls through).
- * Mirrors behavior_contracts eval of a bare number literal exactly.
- */
-const NUM_SAFE_INT_R = 9007199254740991; // 2^53 - 1 (expr safeInt)
-function numLiteralRustExpr(node) {
-    if (typeof node !== "number" || !Number.isFinite(node))
-        return null;
-    if (Number.isInteger(node)) {
-        if (node < -NUM_SAFE_INT_R || node > NUM_SAFE_INT_R)
-            return null; // out of safe window → not covered
-        return `Value::Int(${node}i64)`;
-    }
-    // fractional / exponent literal → checked f64 (finite, guaranteed above).
-    return `Value::Float(${node}f64)`;
-}
-/** A port node is static (literal / ref / concat of those / static arr / bare number literal) —
- * resolvable to a native Value with no Obj / no evaluate interpreter. */
-function portIsStatic(node) {
-    const arr = staticArrElems(node);
-    if (arr !== null)
-        return arr.every(portIsStatic);
-    if (numLiteralRustExpr(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(reconstructR(p)));
-        default:
-            return false;
+/** 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;
+    }
+    catch {
+        return false; // an eligibility probe: any lowering failure ⇒ not native-covered here.
     }
 }
+/** the prior-node typed-cell 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;
+        // coverage probes under-typed components too; an unresolvable node just isn't a prior-node cell.
+        try {
+            typedNodes.set(n.id, "map" in n ? mapNodeArrRef(n, plan) : deriveTypeRef(n.outType, plan));
+        }
+        catch {
+            /* untyped node — omit */
+        }
+    }
+    return typedNodes;
+}
 /** The output must lower to a typed struct/value with no scope read: a ref to a BODY NODE, an
  * obj/arr of such, or a concat. A ref to an input param / non-concat operator is not lowerable. */
 function outputIsNativeLowerable(comp) {
@@ -911,7 +724,7 @@ function outputIsNativeLowerable(comp) {
 /**
  * coveredMapNode — the #86 part 2 covered map shape (nestedBatchGet), rust twin of the go predicate.
  */
-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;
@@ -943,14 +756,25 @@ 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, rust twin) — a first-class fanout node is covered when its over is a covered
  * ref (prior-node arr / input array with elemType) and its element ports are static. See the go twin. */
-function coveredFanoutNode(n, bodyIds, comp) {
+function coveredFanoutNode(n, bodyIds, comp, plan, typedNodes) {
     if (n === null || typeof n !== "object" || !("fanout" in n))
         return false;
     const f = n.fanout;
@@ -970,8 +794,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;
 }
@@ -1007,8 +838,8 @@ function fanoutOverElemInfo(comp, node, typedNodes, plan) {
 }
 /** A covered read SHAPE with static ports + native-lowerable output (+ covered map...into), OR a
  * real-concurrency staged plan (bc#87) whose parallel-stage members are plain componentRef point reads. */
-function isSequentialComponentRefRead(comp) {
-    return coverageRejectReason(comp) === null;
+function isSequentialComponentRefRead(comp, plan) {
+    return coverageRejectReason(comp, plan) === null;
 }
 /**
  * coverageRejectReason — the DIAGNOSTIC twin of isSequentialComponentRefRead (bc#86/#89), rust twin of
@@ -1017,10 +848,11 @@ function isSequentialComponentRefRead(comp) {
  * IDENTICAL to isSequentialComponentRefRead (defined as `coverageRejectReason(c) === null`) so the two
  * can never disagree. This is the message the fail-closed dispatch surfaces per non-native component.
  */
-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);
     // #114: a bindField relation child (single|connection) IS covered inside a parallel stage — the
     // sibling hasMany fan-out (parent → members ∥ permissions). Its bound-key skip-gate is preflighted
     // per member (from the settled parent) BEFORE dispatch, so the scoped-thread fan-out keeps
@@ -1058,12 +890,12 @@ function coverageRejectReason(comp) {
             continue;
         }
         if ("fanout" in n) {
-            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;
         }
         if ("map" in n) {
-            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;
         }
@@ -1082,7 +914,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))
@@ -1099,55 +931,42 @@ function isFullyTyped(comp) {
             return false;
     return true;
 }
-function isNativeRaw(comp) {
-    return isSequentialComponentRefRead(comp) && isFullyTyped(comp);
+function isNativeRaw(comp, plan) {
+    return isSequentialComponentRefRead(comp, plan) && isFullyTyped(comp);
 }
-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", `rust 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 rust-straightline-native (boxed result).`);
 }
 // ── typed input struct (InNR<Comp>) + NATIVE scalar port lowering ────────────────────────────
-/** Rust type for an input port's declared type (scalar → concrete; array+elemType → Vec<ElemT>; else Value). */
-function inputPortRustType(schema, plan) {
-    switch (schema?.type) {
-        case "string":
-        // a `"literal"` port is a constrained STRING union (`param.literal('a','b',…)`, stored 'S') — its
-        // native representation is a plain String (the union constraint is a validation concern, not a type).
-        case "literal":
-            return "String";
-        case "int":
-            return "i64";
-        case "float":
-        // a `"number"` port is a FLOAT (run_behavior: `typeName(number) === "float"`, expr-eval.ts §value):
-        // a JS number is IEEE754 → f64. (An i64 value is declared `"int"`; `"number"` is the float channel.)
-        case "number":
-            return "f64";
-        case "bool":
-            return "bool";
-        case "array":
-        case "arr": {
-            // #108: an input ARRAY port with a declared elemType lowers to a native Vec<ElemT>.
-            const et = schema.elemType;
-            if (et !== undefined && plan !== undefined)
-                return `Vec<${renderTypeRef(deriveTypeRef(et, plan))}>`;
-            return "Value";
-        }
-        case "map": {
-            // an input MAP port (dynamic string keys, declared value elemType) lowers to a native BTreeMap.
-            const et = schema.elemType;
-            if (et !== undefined && plan !== undefined)
-                return `std::collections::BTreeMap<String, ${renderTypeRef(deriveTypeRef(et, plan))}>`;
-            return "Value";
-        }
-        default:
-            return "Value";
-    }
-}
-/** The scalar kind an input port declares, or undefined if it is not a native scalar. */
+/**
+ * inputPortRustType — the native Rust type for an input port's declared type. Scalars lower to the
+ * concrete scalar; `array`/`map` with a declared elemType to `Vec<ElemT>` / `BTreeMap<String, ElemT>`;
+ * an OPTIONAL port (`{opt:T}` → `required:false`) to `Option<T>` — the native representation of "the
+ * value is absent". A declared type with no native lowering stays the boxed `Value`.
+ *
+ * An OPTIONAL port whose inner type has no native lowering FAILS CLOSED: `Option<Value>` would be a
+ * boxed escape, 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 inputPortRustType(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", `rust typed-native (runtime-free): ${where} is OPTIONAL (declared {opt:…}) but its inner type ${JSON.stringify(schema?.type)} has no native Rust lowering, so "absent" has no native representation (an Option<Value> would be a boxed 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 "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 `Option<T>`, and the
+ * callers of this function build REQUIRED scalar slots (`in_.<field>` read straight into a non-opt port
+ * field). Answering "i64" 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 inputPortRustType).
@@ -1172,7 +991,7 @@ function emitInStruct(comp, plan) {
         return `// ${name} — the CONCRETE input for '${comp.name}' (no input ports).\n#[derive(Default)]\npub struct ${name};`;
     }
     const fields = ports
-        .map((p) => `    pub ${rustFieldName(p)}: ${inputPortRustType(comp.inputPorts[p], plan)}, // ${JSON.stringify(p)}`)
+        .map((p) => `    pub ${rustFieldName(p)}: ${inputPortRustType(comp.inputPorts[p], plan, `input port '${p}' of component '${comp.name}'`)}, // ${JSON.stringify(p)}`)
         .join("\n");
     return `// ${name} — the CONCRETE input for '${comp.name}' (fields = inputPorts; typed, consumer-built —
 // NO generic Value slice, NO per-field boxing crosses the covered read boundary).
@@ -1181,166 +1000,21 @@ pub struct ${name} {
 ${fields}
 }`;
 }
+/** 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. */
 /**
- * emitNativeScalar — lower a static port expr to a NATIVE Rust expression of the concrete `want` scalar
- * type, or null if it cannot be statically proven that type. A string literal is native for
- * `want==="string"`, a bool literal for `want==="bool"`. A ref resolves via `resolveRef`. A concat lowers
- * ONLY into `string` and only when EVERY part is a native string, emitting a single `format!("{}{}…", …)`.
- */
-function emitNativeScalar(node, want, resolveRef) {
-    if (staticArrElems(node) !== null)
-        return null;
-    const e = classifyExpr(node);
-    switch (e.kind) {
-        case "str":
-            return want === "String" ? `${rustStrLit(e.value)}.to_string()` : null;
-        case "bool":
-            return want === "bool" ? (e.value ? "true" : "false") : null;
-        case "null":
-            return null;
-        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;
-            // a single-part concat is just the owned String of that part.
-            if (e.parts.length === 1)
-                return emitNativeScalar(reconstructR(e.parts[0]), "String", resolveRef);
-            // multi-part: fold into ONE format! (statically strings only — the concat's strings-only
-            // TYPE_MISMATCH can never fire, so dropping the check is sound). To stay clippy-clean
-            // (to_string_in_format_args), a string-literal part is baked into the format STRING itself
-            // (escaped) rather than passed as a `{}` arg; a ref part becomes a `{}` arg (Display on String).
-            let fmt = "";
-            const args = [];
-            for (const p of e.parts) {
-                const sub = classifyExpr(reconstructR(p));
-                if (sub.kind === "str") {
-                    fmt += sub.value.replace(/[{}]/g, (c) => c + c); // escape { } for the format string
-                    continue;
-                }
-                const arg = emitNativeScalar(reconstructR(p), "String", resolveRef);
-                if (arg === null)
-                    return null;
-                fmt += "{}";
-                args.push(arg);
-            }
-            if (args.length === 0)
-                return `${rustStrLit(fmt)}.to_string()`;
-            return `format!(${rustStrLit(fmt)}, ${args.join(", ")})`;
-        }
-        default:
-            return null;
-    }
-}
-// bc#90 / runtime-free: the old `emitStaticR` / `inputLeafR` / `valueLeafR` port lowering (which built
-// `Value` leaves via the primitives::* helpers and struct-field serializers) is REMOVED — every covered
-// port now lowers to a FULLY NATIVE Rust value in emitPortInit (string / bool / static-string-array /
-// number literal), and a genuinely-dynamic port fails closed. There is no boxed-Value fallback on the
-// covered read plane.
-/**
- * emitPortInit — emit the port field build for one port as a FULLY NATIVE Rust expression (bc#90 /
- * runtime-free). Every covered port lowers to a concrete Rust value assigned straight into the ports
- * struct field — NO `Value`, NO fallback path, NO `match`:
- *   - a static string array (projection) → `vec!["a", "b", ...]` (change #2);
- *   - a bare int/float number literal (e.g. Query `limit: 20`) → `20i64` / `<n>f64`;
- *   - 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). `fieldRustType` is the
- * ports-struct field type (from portFieldRustType); `resolveRef` resolves a ref head for the scalar path.
+ * emitPortInit — the port field initializer, read off the ONE port lowering (compilePortNode / native-
+ * expr). The field's declared TYPE (portFieldRustType) 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.
  */
-function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan, typedNodes, asBinding, elemBaseExpr) {
-    const field = portFieldName(pn);
-    // #108-map: a port that is a ref to a `$as` element MAP/NAMED field (or an input map port) → CLONE the
-    // typed composite value directly off the element/input (native BTreeMap / struct — ZERO boxed Value).
-    // Reuses portCompositeRef for the type; the value is the typed field access `.clone()`.
-    if (plan !== undefined) {
-        const compExpr = emitCompositePortValue(expr, inputPorts ?? {}, asBinding, plan, elemBaseExpr);
-        if (compExpr !== null)
-            return `${field}: ${compExpr}`;
-    }
-    // #110: a componentRef port bound to a runtime array input port (with elemType) → the native Vec<ElemT>,
-    // cloned out of the concrete input struct (`in_.<field>.clone()`) — ZERO boxed Value on the read hot path.
-    if (inputPorts !== undefined && portArrayElemRef(expr, inputPorts, plan) !== null) {
-        const e = classifyExpr(expr);
-        if (e.kind === "ref" && e.path.length === 1) {
-            return `${field}: in_.${rustFieldName(e.path[0])}.clone()`;
-        }
-    }
-    // #129: a leaf port that is a ref into a PRIOR NODE's typed arr outType (node→leaf array dataflow) →
-    // the native Vec<ElemT> cloned off the prior node's typed cell (`t_<node>.borrow().field….clone()`) —
-    // ZERO boxed Value on the read hot path (a fold/dedup leaf whose `items` = a prior node's array result).
-    const priorArr = priorNodeArrElemInfo(expr, typedNodes, plan);
-    if (priorArr !== null)
-        return `${field}: ${priorArr.overExpr}`;
-    // change #2: a static string array (projection) → a native `vec![...]` of &'static str.
-    const strArr = staticStringArrElems(expr);
-    if (strArr !== null) {
-        if (fieldRustType !== "Vec<&'static str>") {
-            throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust combined read (bc#90): port '${pn}' is a static string array but its field type is '${fieldRustType}' (expected Vec<&'static str>).`);
-        }
-        return `${field}: vec![${strArr.map((s) => rustStrLit(s)).join(", ")}]`;
-    }
-    // a bare number literal (e.g. Query `limit: 20`): the SSoT range check ran in numLiteralRustExpr —
-    // emit the concrete native i64/f64 (unwrap the Value::Int/Float box: it was only there for the old
-    // boxed path; the range check is what matters, and it already passed).
-    const num = numLiteralRustExpr(expr);
-    if (num !== null) {
-        if (fieldRustType === "i64")
-            return `${field}: ${expr}i64`;
-        if (fieldRustType === "f64")
-            return `${field}: ${expr}f64`;
-        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust combined read (bc#90): port '${pn}' is a number literal but its field type is '${fieldRustType}'.`);
-    }
-    // string / bool / scalar-input / concat → native scalar expression (no Value, no `match`).
-    const native = emitNativeScalar(expr, fieldRustType, resolveRef);
-    if (native !== null) {
-        return `${field}: ${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", `rust combined read (bc#90 / runtime-free): port '${pn}' (${JSON.stringify(expr)}) does not lower to a native Rust value of type '${fieldRustType}'. The covered read plane admits NO boxed 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", `rust 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 `${portFieldName(pn)}: ${c.expr}`;
 }
 // ── the combined runner (STRUCT-returning; INLINE sequential; native ports in; concrete row out) ──
-/** resolveRefAt for the top-level runner: a ref head is a PRIOR NODE (its typed scalar field) or an
- * INPUT PORT (in_.<field>). A REQUIRED scalar resolves to an OWNED native Rust expression; opt / non-
- * scalar / refOpt → null (fall back to the Value path). */
-function runnerResolveRef(priorNodeAt, atPos, typedNodes, plan, inputPorts) {
-    return (head, restPath, opt) => {
-        if (opt)
-            return null;
-        if (priorNodeAt(head, atPos)) {
-            const baseRef = typedNodes.get(head);
-            let acc;
-            let expr;
-            try {
-                const r = typedFieldAccess(`${typedCell(head)}.borrow()`, baseRef, restPath, plan);
-                expr = r.expr;
-                acc = r.ref;
-            }
-            catch {
-                return null;
-            }
-            if (acc.kind !== "scalar" || acc.scalar === "null")
-                return null;
-            // OWNED: a string field is cloned; int/float/bool are Copy (deref off the Ref).
-            const owned = acc.scalar === "string" ? `(${expr}).clone()` : `*(${expr})`;
-            return { expr: owned, scalar: rustScalar(acc.scalar) };
-        }
-        if (restPath.length !== 0)
-            return null;
-        const scalar = inputScalarKind(inputPorts?.[head]);
-        if (scalar === undefined)
-            return null;
-        const field = `in_.${rustFieldName(head)}`;
-        const owned = scalar === "String" ? `${field}.clone()` : field;
-        return { expr: owned, scalar };
-    };
-}
 function rustScalar(s) {
     return s === "string" ? "String" : s === "int" ? "i64" : s === "float" ? "f64" : "bool";
 }
@@ -1532,12 +1206,9 @@ function emitNativeRawRunner(comp, plan, ap) {
                 indent += "    ";
             }
         }
-        const resolveRef = runnerResolveRef(priorNodeAt, k, typedNodes, plan, comp.inputPorts);
         const inits = [];
         for (const pn of portNames) {
-            const expr = node.ports[pn];
-            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
-            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan, typedNodes));
+            inits.push(emitPortInit(pn, node.ports[pn], comp, plan, typedNodes, (h) => priorNodeAt(h, k)));
         }
         const boundArg = node.bindField !== undefined ? `bound_${s}` : "None";
         // bc#97: derived per-node await — this point-read's future is awaited HERE (its result-consumption
@@ -1665,12 +1336,9 @@ function emitParallelStageArm(comp, stage, atPos, concurrency, metas, typedNodes
                 ind += "    ";
             }
         }
-        const resolveRef = runnerResolveRef(priorNodeAt, atPos, typedNodes, plan, comp.inputPorts);
         const inits = [];
         for (const pn of Object.keys(node.ports)) {
-            const expr = node.ports[pn];
-            const ty = portFieldRustType(expr, comp.inputPorts, `port '${pn}' of node '${node.id}'`, undefined, plan, typedNodes);
-            inits.push(emitPortInit(pn, expr, ty, resolveRef, comp.inputPorts, plan, typedNodes));
+            inits.push(emitPortInit(pn, node.ports[pn], comp, plan, typedNodes, (h) => priorNodeAt(h, atPos)));
         }
         if (gated) {
             lines.push(`${ind}ports_${s} = Some(${structName} { ${inits.join(", ")} });`);
@@ -1781,78 +1449,18 @@ isAsync = false) {
     const portNames = Object.keys(m.ports);
     const elemArrRef = typedNodes.get(node.id);
     const elemName = renderTypeRef(elemArrRef.elem);
-    const resolveRef = (head, restPath, opt) => {
-        if (opt)
-            return null;
-        let baseExpr;
-        let baseRef;
-        if (head === asName) {
-            baseExpr = `oel_${s}`;
-            baseRef = overElemRef;
-        }
-        else if (priorHere(head)) {
-            baseExpr = `${typedCell(head)}.borrow()`;
-            baseRef = typedNodes.get(head);
-        }
-        else {
-            if (restPath.length !== 0)
-                return null;
-            const scalar = inputScalarKind(comp.inputPorts?.[head]);
-            if (scalar === undefined)
-                return null;
-            const field = `in_.${rustFieldName(head)}`;
-            return { expr: scalar === "String" ? `${field}.clone()` : field, scalar };
-        }
-        let acc;
-        let expr;
-        try {
-            const r = typedFieldAccess(baseExpr, baseRef, restPath, plan);
-            expr = r.expr;
-            acc = r.ref;
-        }
-        catch {
-            return null;
-        }
-        if (acc.kind !== "scalar" || acc.scalar === "null")
-            return null;
-        // OWNED value. When restPath is EMPTY, `expr` is a bare REFERENCE (`oel_${s}` = &Elem-scalar, or
-        // `cell.borrow()` = Ref<scalar>) — deref with `*` (Copy) / `.clone()` via deref (String). When a
-        // `.field` was appended, `expr` is a value PLACE (auto-deref) — read it directly (`.clone()` String).
-        const isBareRef = restPath.length === 0;
-        let owned;
-        if (acc.scalar === "string") {
-            owned = isBareRef ? `(*${expr}).clone()` : `${expr}.clone()`;
-        }
-        else {
-            owned = isBareRef ? `*${expr}` : expr;
-        }
-        return { expr: owned, scalar: rustScalar(acc.scalar) };
-    };
+    const asBinding = { name: asName, ref: overElemRef, plan };
     // build the per-element CONCRETE native ports struct. `il` = indent inside the element loop.
     const buildPorts = (il) => {
-        const out = [];
-        const inits = [];
-        const asBinding = { name: asName, ref: overElemRef, plan };
-        for (const pn of portNames) {
-            const ty = portFieldRustType(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 clones the typed composite.
-            inits.push(emitPortInit(pn, m.ports[pn], ty, resolveRef, comp.inputPorts, plan, undefined, asBinding, `oel_${s}`));
-        }
-        out.push(`${il}let ep_${s} = ${structName} { ${inits.join(", ")} };`);
-        return out;
+        const inits = portNames.map((pn) => emitPortInit(pn, m.ports[pn], comp, plan, typedNodes, priorHere, { asBinding, asBase: `oel_${s}` }));
+        return [`${il}let ep_${s} = ${structName} { ${inits.join(", ")} };`];
     };
     // #108 guard: compile `when` to a native bool over an element-scoped resolveHead ($as element value,
     // prior node, input port). On skip: `continue` (element excluded — matches run_behavior's keep-gate).
     const emitGuard = (il) => {
         if (!hasGuard)
             return [];
-        const resolveHead = (head) => {
-            if (head === asName)
-                return { expr: `oel_${s}.clone()`, ref: overElemRef };
-            if (priorHere(head))
-                return { expr: `${typedCell(head)}.borrow().clone()`, ref: typedNodes.get(head) };
-            return rustInputHeadRef(head, comp, plan);
-        };
+        const resolveHead = nativeResolveHead(comp, plan, typedNodes, priorHere, { asBinding, asBase: `oel_${s}` });
         const g = new NativeExprCompiler(makeRustExprBackend(resolveHead, plan)).compileBool(m.when);
         const out = [];
         for (const st of g.stmts)
@@ -1975,55 +1583,9 @@ function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, isAsync
     if (!dkField || dkField.type.kind !== "scalar" || dkField.type.scalar !== "string")
         throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust fanout (v3): node '${node.id}' dedupeKey '${f.dedupeKey}' must be a string field of the connection items element type '${elemRef.name}'.`);
     const dkRust = rustFieldName(f.dedupeKey);
-    const resolveRef = (head, restPath, opt) => {
-        if (opt)
-            return null;
-        let baseExpr;
-        let baseRef;
-        if (head === asName) {
-            baseExpr = `oel_${s}`;
-            baseRef = overElemRef;
-        }
-        else if (priorHere(head)) {
-            baseExpr = `${typedCell(head)}.borrow()`;
-            baseRef = typedNodes.get(head);
-        }
-        else {
-            if (restPath.length !== 0)
-                return null;
-            const scalar = inputScalarKind(comp.inputPorts?.[head]);
-            if (scalar === undefined)
-                return null;
-            const field = `in_.${rustFieldName(head)}`;
-            return { expr: scalar === "String" ? `${field}.clone()` : field, scalar };
-        }
-        let acc;
-        let expr;
-        try {
-            const r = typedFieldAccess(baseExpr, baseRef, restPath, plan);
-            expr = r.expr;
-            acc = r.ref;
-        }
-        catch {
-            return null;
-        }
-        if (acc.kind !== "scalar" || acc.scalar === "null")
-            return null;
-        const isBareRef = restPath.length === 0;
-        let owned;
-        if (acc.scalar === "string")
-            owned = isBareRef ? `(*${expr}).clone()` : `${expr}.clone()`;
-        else
-            owned = isBareRef ? `*${expr}` : expr;
-        return { expr: owned, scalar: rustScalar(acc.scalar) };
-    };
+    const asBinding = { name: asName, ref: overElemRef, plan };
     const buildPorts = (il) => {
-        const inits = [];
-        const asBinding = { name: asName, ref: overElemRef, plan };
-        for (const pn of portNames) {
-            const ty = portFieldRustType(f.ports[pn], comp.inputPorts, `fanout port '${pn}' of node '${node.id}'`, asBinding, plan);
-            inits.push(emitPortInit(pn, f.ports[pn], ty, resolveRef, comp.inputPorts, plan));
-        }
+        const inits = portNames.map((pn) => emitPortInit(pn, f.ports[pn], comp, plan, typedNodes, priorHere, { asBinding, asBase: `oel_${s}` }));
         return [`${il}let ep_${s} = ${structName} { ${inits.join(", ")} };`];
     };
     const lines = [];
@@ -2077,24 +1639,72 @@ function emitFanoutArm(comp, node, atPos, typedNodes, plan, priorNodeAt, isAsync
         lines.push(c);
     return lines.join("\n");
 }
-/** #108: resolve an INPUT port head for a native-expr ref (rust). Scalar → `in_.<field>` (owned: String
- * cloned, Copy as-is); array WITH elemType → `in_.<field>.clone()` of Vec<ElemT> (for `len`); else null. */
-function rustInputHeadRef(head, comp, plan) {
-    const schema = comp.inputPorts?.[head];
-    if (schema === undefined)
-        return null;
-    const sc = inputScalarKind(schema);
-    if (sc !== undefined) {
-        const scalarRef = { kind: "scalar", scalar: sc === "i64" ? "int" : sc === "f64" ? "float" : sc === "String" ? "string" : "bool" };
-        const field = `in_.${rustFieldName(head)}`;
-        return { expr: sc === "String" ? `${field}.clone()` : field, ref: scalarRef };
+/**
+ * rustOwn — render the OWNED form of a resolved ref value at the LEAF (native-expr calls this after the
+ * field path is walked). `guard` marks a value read through a `RefCell`/`&` borrow (a prior node's
+ * `cell.borrow()`, a `$as` element `&Elem`): a WHOLE-node Copy scalar dereferences (`*expr`), while a
+ * Copy FIELD is already a copy-out of the auto-deref'd place. A String/struct/map clones; an array clones
+ * only when the position OWNS it (a port field) and stays borrowed for a `len`. Cloning a Copy value
+ * would trip clippy's `clone_on_copy`, so Copy never clones.
+ */
+function rustOwn(guard, ownArrays) {
+    return (expr, ref, fieldAccessed) => {
+        if (ref.kind === "arr")
+            return ownArrays ? `${expr}.clone()` : expr;
+        if (typeRefIsCopy(ref))
+            return guard && !fieldAccessed ? `*${expr}` : expr;
+        return `${expr}.clone()`;
+    };
+}
+/**
+ * nativeResolveHead — the ONE ref-head resolver the runtime-free native-expr compiler reads, for cond
+ * `if`/branches, a map/fanout `when` guard, AND a port. A head is a `$as` element binding, a prior body
+ * node's typed cell, or an input port — each a native base expr of the head's TypeRef PLUS an `own`
+ * renderer (rustOwn) that native-expr applies at the resolved LEAF. Ownership lives at the leaf so a
+ * prior-node field ref clones only the field (`cell.borrow().items.clone()`), never the whole struct.
+ * `isPrior` tests whether a head names a settled prior node (position-aware at a runner site; structural
+ * at coverage/struct-def). `asBase` is the element base for a `$as`-headed ref; `ownArrays` owns an array
+ * (a port field) vs borrows it (a cond `len`).
+ */
+function nativeResolveHead(comp, plan, typedNodes, isPrior, opts) {
+    const ownArrays = opts?.ownArrays === true;
+    return (head) => {
+        // a `$as` element (`for oel in vec.iter()`) is a `&Elem` — a borrow guard.
+        if (opts?.asBinding !== undefined && opts.asBase !== undefined && head === opts.asBinding.name) {
+            return { expr: opts.asBase, ref: opts.asBinding.ref, own: rustOwn(true, ownArrays) };
+        }
+        // a prior node's value lives behind a `RefCell` borrow guard.
+        if (isPrior(head)) {
+            const ref = typedNodes.get(head);
+            return { expr: `${typedCell(head)}.borrow()`, ref, own: rustOwn(true, ownArrays) };
+        }
+        // an input port is a by-value struct field (no guard).
+        const ref = inputPortTypeRef(comp.inputPorts?.[head], plan);
+        if (ref === undefined)
+            return null;
+        return { expr: `in_.${rustFieldName(head)}`, ref, own: rustOwn(false, ownArrays) };
+    };
+}
+/**
+ * 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 to a native value 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 = nativeResolveHead(comp, plan, typedNodes, isPrior, { ...opts, ownArrays: true });
+    try {
+        return new NativeExprCompiler(makeRustExprBackend(resolveHead, plan)).compilePort(node);
     }
-    const et = schema.elemType;
-    if ((schema.type === "array" || schema.type === "arr") && et !== undefined) {
-        // no clone: the only array use inside a cond/guard expr is `len`, which BORROWS (`&in_.xs`).
-        return { expr: `in_.${rustFieldName(head)}`, ref: { kind: "arr", elem: deriveTypeRef(et, plan) } };
+    catch (e) {
+        if (!(e instanceof GeneratorFailure))
+            throw e;
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust typed-native (runtime-free): ${where} ${JSON.stringify(node)} does not lower to a native Rust value: ${e.message}`);
     }
-    return null;
 }
 /**
  * emitCondArm — the struct-native exec of a covered cond node (#108, rust). Mirrors run_behavior's cond
@@ -2106,11 +1716,7 @@ function emitCondArm(comp, node, atPos, typedNodes, plan, priorNodeAt) {
     const c = node.cond;
     const s = sanitize(node.id);
     const priorHere = (head) => priorNodeAt(head, atPos);
-    const resolveHead = (head) => {
-        if (priorHere(head))
-            return { expr: `${typedCell(head)}.borrow().clone()`, ref: typedNodes.get(head) };
-        return rustInputHeadRef(head, comp, plan);
-    };
+    const resolveHead = nativeResolveHead(comp, plan, typedNodes, priorHere);
     const compiler = new NativeExprCompiler(makeRustExprBackend(resolveHead, plan));
     const cond = compiler.compileBool(c.if);
     // #125: a when(...) control-gate cond は出力データ型を持たない制御スキップマーカー。typed cell へ何も
@@ -2249,17 +1855,20 @@ function emit(ctx) {
     // rust CONSUMES this annotation (async fn + .await where derived); go ignores it. per-node granularity
     // is a strict generalization of increment-1's uniform ioModel:'async' (= every terminal async).
     const asyncPlans = buildAsyncPlans(ctx.ir, ctx.ioModel);
+    // 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);
     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));
+        assertTypedCoverage(c, plan);
+    const native = ctx.ir.components.filter((c) => isNativeRaw(c, plan));
+    const nonNative = ctx.ir.components.filter((c) => !isNativeRaw(c, plan));
     // FAIL CLOSED (bc#86/#89): the --typed-native (native codegen) surface is native-only. Previously a
     // non-covered component was SILENTLY DROPPED (emitted only as a comment note), concealing that it
     // never got native codegen. We now throw a LOUD GeneratorFailure naming every uncovered component +
     // its specific reject reason. A fully-covered module is unchanged.
     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", `rust 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 ` +
@@ -2273,7 +1882,6 @@ function emit(ctx) {
 ${emitStructSurface([])}
 `;
     }
-    const plan = buildTypePlan(ctx.ir);
     // The typed-native module is a de-boxed CONSUMER artifact: the covered runner RETURNS these outType
     // structs and the consumer reads their fields natively. So the decls (and their FIELDS) are pub — the
     // consumer keeps the model native (mirrors Go's exported outType struct fields on the covered path).
@@ -2291,11 +1899,7 @@ ${emitStructSurface([])}
     const inStructs = [];
     const elemMaterializers = [];
     for (const c of native) {
-        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)
                 structs.push(emitFanoutPortsStructs(c, n, typedNodes, plan));
@@ -2305,7 +1909,7 @@ ${emitStructSurface([])}
                 // #108: a cond node has NO ports struct (pure Expression — no handler dispatch).
             }
             else
-                structs.push(emitPortsStruct(c, n, undefined, plan, typedNodes)); // #129: typedNodes for prior-node arr leaf ports.
+                structs.push(emitPortsStruct(c, n, plan, typedNodes)); // #129: typedNodes for prior-node arr leaf ports.
         }
         rowStructs.push(emitRawRowStructs(c, typedNodes, plan));
         handlerTraits.push(emitHandlerTrait(c, typedNodes, plan, asyncPlans.get(c.name)));
@@ -2370,8 +1974,8 @@ use std::cell::RefCell;`;
  */
 export function rustTypedNativeObserve(ir, ioModel = "sync") {
     const components = ir.components;
-    const native = components.filter(isNativeRaw);
     const plan = buildTypePlan(ir);
+    const native = components.filter((c) => isNativeRaw(c, plan));
     const needSync = native.some((c) => concurrencyPlan(c) !== null);
     const serializers = emitSerializers(plan);
     const marshallers = emitMarshallers(plan);
@@ -2469,17 +2073,27 @@ export function rustTypedNativeObserve(ir, ioModel = "sync") {
             const node = n;
             const rowT = rawRowStructName(c.name, node.id);
             const decode = emitDecodeRow(c.name, node.id, rowT, ref, plan, emittedDecode, decodeFns, "");
-            // #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 `f_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 bound only on the echo path.
-            const canEcho = ref.kind === "arr" && Object.prototype.hasOwnProperty.call(node.ports, "items");
-            const portsParam = canEcho ? "ports" : "_ports";
-            const echoBranch = canEcho
-                ? `\n        if echo == "items" {\n            return Some(${rowT} { val: ${portsParam}.${portFieldName("items")}.clone(), ..Default::default() });\n        }`
-                : "";
-            const okBind = canEcho ? "(is_err, err, ok, echo)" : "(is_err, err, ok, _echo)";
+            // #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
+            // bound only when at least one port qualifies.
+            const echoable = echoablePorts(c, node, ref, plan, typedNodes);
+            const portsParam = echoable.length > 0 ? "ports" : "_ports";
+            // a Copy value (i64/f64/bool/Option<scalar>) is read directly — cloning it trips clippy clone_on_copy.
+            const own = (expr, r) => `${expr}${typeRefIsCopy(r) ? "" : ".clone()"}`;
+            // 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 = (p) => ref.kind === "named"
+                ? `${rowT} { ${findDecl(plan, ref.name).fields.map((f) => `${rustFieldName(f.name)}: ${own(`${portsParam}.${portFieldName(p)}.${rustFieldName(f.name)}`, f.type)}`).join(", ")}, ..Default::default() }`
+                : `${rowT} { val: ${own(`${portsParam}.${portFieldName(p)}`, ref)}, ..Default::default() }`;
+            const echoBranch = echoable
+                .map((p) => `\n        if echo == ${rustStrLit(p)} {\n            return Some(${echoRow(p)});\n        }`)
+                .join("");
+            const okBind = echoable.length > 0 ? "(is_err, err, ok, echo)" : "(is_err, err, ok, _echo)";
             methods.push(`    ${fnKw} ${nodeMethodName(node.id)}(&self, ${portsParam}: &${portsStructName(c.name, node.id)}, _bound: ${bt}) -> Option<${rowT}> {
         let ${okBind} = self.next(${rustStrLit(node.component)})?;
         if is_err {
@@ -2548,7 +2162,14 @@ impl ScriptedNativeRaw {
         let mut queues = self.queues.lock().unwrap();
         let (queue, single) = queues.get_mut(component)?;
         let raw = if *single || queue.len() <= 1 { queue[0].clone() } else { queue.remove(0) };
-        let echo = raw.get("echo").and_then(|e| e.as_str()).unwrap_or("").to_string();
+        // PROTOCOL.md §3.5 echo forms, normalized to the port NAME: {"echo":"port","port":"X"} -> "X"
+        // ({"echo":"items"} is already that shape). The generated node method just compares this
+        // against its echoable port names.
+        let echo = match raw.get("echo").and_then(|e| e.as_str()) {
+            Some("port") => raw.get("port").and_then(|p| p.as_str()).unwrap_or("").to_string(),
+            Some(other) => other.to_string(),
+            None => String::new(),
+        };
         if let Some(okv) = raw.get("ok") {
             let v = behavior_contracts::decode_value(okv).expect("decode ok");
             Some((false, String::new(), Some(v), echo))
@@ -2639,8 +2260,10 @@ ${arms}
 }
 /** emitInDecoder — a TEST-glue decoder `decode_InNR_<comp>(input) -> Result<InNR_<comp>, BehaviorError>`.
  * Reads each declared input port from the generic &[(String,Value)] into the concrete field (scalar →
- * typed read; Value-typed → the raw Value clone). A missing key leaves Default (every covered input is
- * required + supplied by the corpus). Lives ONLY in the observe companion. */
+ * typed read; opt → Some/None; Value-typed → the raw Value clone). A key that is absent, or present as
+ * `Value::Null`, leaves the field's Default — for an OPTIONAL port that is `None` (absent), which is the
+ * same value `refCore` observes for the `null` binding run_behavior is given. Lives ONLY in the observe
+ * companion. */
 function emitInDecoder(comp, plan) {
     const name = inStructName(comp.name);
     const ports = Object.keys(comp.inputPorts ?? {});
@@ -2662,7 +2285,15 @@ function emitInDecoder(comp, plan) {
         const et = schema.elemType;
         const head = i === 0 ? "        if" : "        } else if";
         lines.push(`${head} k == ${rustStrLit(p)} {`);
-        if ((schema?.type === "array" || schema?.type === "arr") && et !== undefined) {
+        if (inputPortIsOptional(schema)) {
+            // An OPTIONAL port decodes into its native Option<T>. materializeExpr's opt de-box IS the wire
+            // rule: `Value::Null` → None (absent), any other value → Some(<inner>). A key that never appears
+            // keeps the struct Default (None) — the same absent value. Checked FIRST: optionality wraps every
+            // inner type (an optional array is Option<Vec<T>>, not Vec<T>).
+            const optRef = inputPortTypeRef(schema, plan);
+            lines.push(`            in_.${field} = ${materializeExpr("v", optRef, plan)};`);
+        }
+        else if ((schema?.type === "array" || schema?.type === "arr") && et !== undefined) {
             // #108: decode the boxed Value::Arr into the native Vec<ElemT> (test glue — materialize each elem).
             const elemRef = deriveTypeRef(et, plan);
             const elemTy = renderTypeRef(elemRef);
@@ -2700,6 +2331,14 @@ function emitInDecoder(comp, plan) {
     lines.push(`}`);
     return lines.join("\n");
 }
+/** 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) => portFieldRustType(node.ports[p], comp, plan, typedNodes, `port '${p}'`) === want);
+}
 /** emitDecodeRow — emit (once, deduped) a decoder `decode_row_<comp>_<node><suffix>(v: &Value) -> <rowT>`
  * that materializes the scripted ok Value into the concrete row struct. Named: reuse the Value->struct
  * marshaller + move fields; scalar/arr/opt: materialize into .val. TEST glue only. */