behavior-contracts 0.8.2 → 0.8.4

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
@@ -135,18 +135,13 @@ function inferPortType(node, inputPorts, asBinding) {
                 }
                 return "Value";
             }
+            // a ref to a REQUIRED scalar input port → that scalar. An OPTIONAL port has no required-scalar
+            // kind (its native type is Option<T>) and is lowered by the opt lane ahead of this — reaching here
+            // with one means the shape is uncovered, and "Value" routes it to the caller's loud fail-closed.
             if (e.path.length === 1) {
-                const s = inputPorts[e.path[0]];
-                if (s) {
-                    if (s.type === "string" || s.type === "literal")
-                        return "String"; // literal = constrained String.
-                    if (s.type === "int")
-                        return "i64";
-                    if (s.type === "float" || s.type === "number")
-                        return "f64"; // `"number"` = the float channel.
-                    if (s.type === "bool")
-                        return "bool";
-                }
+                const sc = inputScalarKind(inputPorts[e.path[0]]);
+                if (sc !== undefined)
+                    return sc;
             }
             return "Value";
         }
@@ -180,6 +175,12 @@ function staticStringArrElems(node) {
  * fallback on the native module). `where` names the emission site for the error.
  */
 function portFieldRustType(node, inputPorts, where = "port", asBinding, plan, typedNodes) {
+    // A port reading an OPTIONAL input port lowers through the shared native-expr compiler (the
+    // Option<T> pass-through / the coalesce default). It runs FIRST so an optional input can never fall
+    // into the required-scalar inference below (which has no way to say "absent").
+    const optPort = optPortCompileR(node, inputPorts, where, plan);
+    if (optPort !== null)
+        return renderTypeRef(optPort.ref);
     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>.
@@ -202,10 +203,61 @@ function portFieldRustType(node, inputPorts, where = "port", asBinding, plan, ty
         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.`);
+        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. ${RUST_STATIC_PORT_FORMS} Regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
     }
     return ft;
 }
+/**
+ * optPortCompileR — the OPTIONAL-input port lane (rust). A component may declare an input port
+ * `{opt:T}` (PortSchema `required:false`); the only native representation of "the value is absent" is
+ * `Option<T>`, so such a port never lowers through the required-scalar inference. This lane compiles the
+ * port expression with the SHARED runtime-free native-expr compiler (native-expr.ts — the same traversal,
+ * type-inference and fail-closed discipline the go twin uses, so the two agree by construction):
+ *
+ *   - `opt($.x)` / `$.x` at port position  → `Option<T>` (the leaf receives the absent value as null,
+ *     exactly as run_behavior's `evalPorts` passes it).
+ *   - `coalesce(opt($.x), <literal>)`      → `in_.x.unwrap_or(<literal>)` — a native `T`, no boxed Value.
+ *   - `ne(opt($.x), null)` / `eq(…, null)` → the native presence test (`is_some()` / `is_none()`).
+ *
+ * Returns null when the port expression reads NO optional input (the caller keeps its existing lowering).
+ * A port that DOES read one but does not compile — or that compiles to a fallible expression, which this
+ * position cannot hoist — FAILS CLOSED loudly rather than degrade to a required type or a zero value.
+ */
+function optPortCompileR(node, inputPorts, where, plan) {
+    if (plan === undefined)
+        return null;
+    if (!exprReadsOptionalInput(node, inputPorts))
+        return null;
+    const resolveHead = (head) => rustInputHeadRef(head, { inputPorts }, plan);
+    let c;
+    try {
+        c = new NativeExprCompiler(makeRustExprBackend(resolveHead, plan)).compilePort(node);
+    }
+    catch (e) {
+        if (!(e instanceof GeneratorFailure))
+            throw e;
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust typed-native (runtime-free): ${where} ${JSON.stringify(node)} reads an OPTIONAL input port but does not lower to a native Rust value: ${e.message}`);
+    }
+    if (c.stmts.length > 0)
+        throw new GeneratorFailure("UNSUPPORTED_NODE_STRAIGHTLINE", `rust typed-native (runtime-free): ${where} ${JSON.stringify(node)} reads an OPTIONAL input port through a FALLIBLE expression (one that can raise INT_OVERFLOW / NAN_OR_INF / MOD_ZERO / PRECISION_LOSS). Such an expression lowers to STATEMENTS carrying an early error-return, and a port is built inline in the ports-struct literal — a position that cannot host them. (A cond/guard position CAN host them, so the same expression is covered there — the boundary is the POSITION, not the operator.) Use a non-fallible port expression.`);
+    return c;
+}
+/** exprReadsOptionalInput — does this port expression reference an OPTIONAL (`required:false`) input
+ * port? Language-neutral scan for `ref`/`refOpt` heads bound to an optional port. Decides ONLY which
+ * lane a port takes; the lane itself then proves the lowering (or fails closed). */
+function exprReadsOptionalInput(node, inputPorts) {
+    if (node === null || typeof node !== "object")
+        return false;
+    if (Array.isArray(node))
+        return node.some((el) => exprReadsOptionalInput(el, inputPorts));
+    const rec = node;
+    const keys = Object.keys(rec);
+    if (keys.length === 1 && (keys[0] === "ref" || keys[0] === "refOpt")) {
+        const path = rec[keys[0]];
+        return Array.isArray(path) && typeof path[0] === "string" && inputPortIsOptional(inputPorts?.[path[0]]);
+    }
+    return keys.some((k) => exprReadsOptionalInput(rec[k], inputPorts));
+}
 /** 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
@@ -393,21 +445,40 @@ function makeRustExprBackend(resolveHead, plan) {
         // 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 +487,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 +515,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))
@@ -667,9 +755,13 @@ function emitHandlerTrait(comp, typedNodes, plan, ap) {
     lines.push(`}`);
     return lines.join("\n");
 }
-/** mapElemMaterializerName — the augmented-element copier for a covered map...into node. */
-function mapElemMaterializerName(nodeId) {
-    return `materialize_map_elem_${typedCell(nodeId)}`;
+/** mapElemMaterializerName — the augmented-element copier for a covered map...into node.
+ * QUALIFIED by component name: two components may each carry a map node at the SAME
+ * recorder-scan index (e.g. both `…authorFollows` and `…groupsNested` have a map at `n4`),
+ * and a node-id-only name would collide at module scope (E0428). Mirrors the Go emitter
+ * (`materializeMapElemNR_<comp>_<node>`) and the sibling `decode_row_<comp>_<node>` helper. */
+function mapElemMaterializerName(compName, nodeId) {
+    return `materialize_map_elem_${sanitize(compName)}_${typedCell(nodeId)}`;
 }
 /** mapNodeArrRef — the map node's PRODUCED-ARRAY TypeRef from its `outType`, normalizing the two IR
  * conventions to the one array shape every downstream site assumes (`typedNodes.get(mapId)` is an arr):
@@ -725,7 +817,7 @@ function emitMapElemMaterializers(comp, typedNodes, plan) {
         const intoField = decl.fields.find((f) => f.name === intoKey);
         const overFields = decl.fields.filter((f) => f.name !== intoKey);
         const overElemTy = mapOverElemType(comp, n, typedNodes, plan);
-        const fn = mapElemMaterializerName(n.id);
+        const fn = mapElemMaterializerName(comp.name, n.id);
         const elemRowGo = rawElemStructName(comp.name, n.id);
         const intoRowRef = mapElemRowRef(n, arrRef, plan);
         const inits = [];
@@ -855,14 +947,20 @@ function numLiteralRustExpr(node) {
     // 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) {
+/** A port node is static (literal / ref / concat of those / static arr / bare number literal / an
+ * optional-input read) — resolvable to a native value with no Obj / no evaluate interpreter. This is the
+ * SHAPE gate that decides native ELIGIBILITY; the lowering itself (portFieldRustType / emitPortInit) is
+ * what proves each shape, and fails closed loudly on one it cannot lower. */
+function portIsStatic(node, inputPorts) {
     const arr = staticArrElems(node);
     if (arr !== null)
-        return arr.every(portIsStatic);
+        return arr.every((el) => portIsStatic(el, inputPorts));
     if (numLiteralRustExpr(node) !== null)
         return true; // bare number literal (e.g. Query `limit`)
+    // An optional-input read (`opt($.x)` / `coalesce(opt($.x), 20)` / `ne(opt($.x), null)`) is a
+    // statically-resolvable port — the opt lane lowers it (or fails closed with the specific reason).
+    if (inputPorts !== undefined && exprReadsOptionalInput(node, inputPorts))
+        return true;
     const e = classifyExpr(node);
     switch (e.kind) {
         case "str":
@@ -871,7 +969,7 @@ function portIsStatic(node) {
         case "ref":
             return true;
         case "concat":
-            return e.parts.every((p) => portIsStatic(reconstructR(p)));
+            return e.parts.every((p) => portIsStatic(reconstructR(p), inputPorts));
         default:
             return false;
     }
@@ -940,7 +1038,7 @@ function coveredMapNode(n, bodyIds, comp) {
     }
     const ports = m.ports;
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp.inputPorts))
             return false;
     return true;
 }
@@ -967,7 +1065,7 @@ function coveredFanoutNode(n, bodyIds, comp) {
     }
     const ports = f.ports;
     for (const p of Object.keys(ports))
-        if (!portIsStatic(ports[p]))
+        if (!portIsStatic(ports[p], comp.inputPorts))
             return false;
     return true;
 }
@@ -1078,7 +1176,7 @@ function coverageRejectReason(comp) {
         if (cr.relationKind !== undefined && cr.relationKind !== "single" && cr.relationKind !== "connection")
             return `relationKind '${cr.relationKind}' not native-covered (node '${n.id}')`;
         for (const p of Object.keys(cr.ports))
-            if (portIsStatic(cr.ports[p]) === false)
+            if (portIsStatic(cr.ports[p], comp.inputPorts) === false)
                 return `node '${n.id}' port '${p}' is not statically resolvable`;
     }
     if (!outputIsNativeLowerable(comp))
@@ -1106,44 +1204,31 @@ function assertTypedCoverage(comp) {
     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).
@@ -1168,7 +1253,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).
@@ -1177,6 +1262,9 @@ 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. */
+const RUST_STATIC_PORT_FORMS = "This port does not read an optional input, so it lowers through the STATIC port forms: a string / bool / number literal, a static string-array (projection), a ref to a REQUIRED scalar input port, a ref to an input array/map port or a prior node's array (declared elemType), a ref to a `$as` element field, or a concat of native strings. A dynamic operator at port position is not covered on this lane. (A port that DOES read an optional input lowers through the full native expression compiler, which admits the whole closed operator set — so the covered operator set at port position currently depends on the lane, not on the operator.)";
 /**
  * emitNativeScalar — lower a static port expr to a NATIVE Rust expression of the concrete `want` scalar
  * type, or null if it cannot be statically proven that type. A string literal is native for
@@ -1250,6 +1338,11 @@ function emitNativeScalar(node, want, resolveRef) {
  */
 function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan, typedNodes, asBinding, elemBaseExpr) {
     const field = portFieldName(pn);
+    // The OPTIONAL-input lane (Option<T> pass-through / coalesce default) — same shared compile as
+    // portFieldRustType, so the field type and its initializer are derived from ONE lowering.
+    const optPort = optPortCompileR(expr, inputPorts ?? {}, `port '${pn}'`, plan);
+    if (optPort !== null)
+        return `${field}: ${optPort.expr}`;
     // #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()`.
@@ -1299,7 +1392,7 @@ function emitPortInit(pn, expr, fieldRustType, resolveRef, inputPorts, plan, typ
     // 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.`);
+    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. ${RUST_STATIC_PORT_FORMS} Regenerate on the boxed straight-line path if this port is genuinely dynamic.`);
 }
 // ── 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
@@ -1771,7 +1864,7 @@ isAsync = false) {
     const batch = `${structName}Batch`;
     // #108: over element type + the OWNED over-Vec expression (prior-node arr OR input array w/ elemType).
     const { elemRef: overElemRef, overExpr } = mapOverElemInfo(comp, node, typedNodes, plan);
-    const elemMat = mapElemMaterializerName(node.id);
+    const elemMat = mapElemMaterializerName(comp.name, node.id);
     const priorHere = (head) => priorNodeAt(head, atPos);
     const asName = m.as;
     const portNames = Object.keys(m.ports);
@@ -2073,24 +2166,29 @@ 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. */
+/**
+ * rustInputHeadRef (#108) — resolve an INPUT port head for a native-expr ref (rust). The port's declared
+ * type comes from the shared `inputPortTypeRef` SSoT, so an OPTIONAL port resolves as `{opt:…}` (native
+ * `Option<T>`) and the compiler can see its optionality: a null-compare becomes a real presence test and
+ * a coalesce a real `unwrap_or`, while a REQUIRED-scalar slot fed by an opt fails closed. Exprs are OWNED
+ * (String / Option<String> cloned; Copy scalars as-is), except an array — the only array use inside a
+ * cond/guard expr is `len`, which BORROWS (`&in_.xs`).
+ */
 function rustInputHeadRef(head, comp, plan) {
     const schema = comp.inputPorts?.[head];
-    if (schema === undefined)
+    const ref = inputPortTypeRef(schema, plan);
+    if (ref === 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 };
-    }
-    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) } };
-    }
-    return null;
+    const field = `in_.${rustFieldName(head)}`;
+    return { expr: rustOwnedHeadExpr(field, ref), ref };
+}
+/** The OWNED native expression for a head of type `ref` read off a by-value struct field. A String (or an
+ * Option/collection containing one) is cloned; a Copy scalar (and an Option/array of Copy scalars) is
+ * read directly — cloning a Copy value trips clippy's `clone_on_copy`. An array stays borrowed (`len`). */
+function rustOwnedHeadExpr(field, ref) {
+    if (ref.kind === "arr")
+        return field; // borrowed by `len`
+    return typeRefIsCopy(ref) ? field : `${field}.clone()`;
 }
 /**
  * emitCondArm — the struct-native exec of a covered cond node (#108, rust). Mirrors run_behavior's cond
@@ -2465,17 +2563,22 @@ 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 port (i64/f64/bool/Option<scalar>) is read directly — cloning it trips clippy clone_on_copy.
+            const echoRead = (p) => `${portsParam}.${portFieldName(p)}${typeRefIsCopy(ref) ? "" : ".clone()"}`;
+            const echoBranch = echoable
+                .map((p) => `\n        if echo == ${rustStrLit(p)} {\n            return Some(${rowT} { val: ${echoRead(p)}, ..Default::default() });\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 {
@@ -2544,7 +2647,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))
@@ -2635,8 +2745,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 ?? {});
@@ -2658,7 +2770,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);
@@ -2696,6 +2816,16 @@ 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's `val`. A
+ * port with a different type is not echoable (the row could not hold it), and a NAMED outType has no
+ * `val` at all (its row carries the struct's fields flattened — see emitDecodeRow). */
+function echoablePorts(comp, node, ref, plan, typedNodes) {
+    if (ref.kind === "named")
+        return [];
+    const want = renderTypeRef(ref);
+    return Object.keys(node.ports).filter((p) => portFieldRustType(node.ports[p], comp.inputPorts, `port '${p}'`, undefined, plan, typedNodes) === 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. */