@stackables/bridge 1.2.0 → 1.4.0

package/build/{bridge-format.js → src/bridge-format.js}

@@ -10,10 +10,50 @@ import { SELF_MODULE } from "./types.js";
  * @param text - Bridge definition text
  * @returns Array of instructions (Bridge, ToolDef)
  */
+const BRIDGE_VERSION = "1.4";
+// Keywords that cannot be used as tool names, aliases, or const names
+const RESERVED_KEYWORDS = new Set(["bridge", "with", "as", "from", "const", "tool", "version", "define"]);
+// Source identifiers reserved for their special meaning inside bridge/tool blocks
+const SOURCE_IDENTIFIERS = new Set(["input", "output", "context"]);
+function assertNotReserved(name, lineNum, label) {
+    if (RESERVED_KEYWORDS.has(name.toLowerCase())) {
+        throw new Error(`Line ${lineNum}: "${name}" is a reserved keyword and cannot be used as a ${label}`);
+    }
+    if (SOURCE_IDENTIFIERS.has(name.toLowerCase())) {
+        throw new Error(`Line ${lineNum}: "${name}" is a reserved source identifier and cannot be used as a ${label}`);
+    }
+}
+/**
+ * Strip a trailing `# comment` from a single source line, respecting string
+ * literals so that a `#` inside `"..."` is never treated as a comment marker.
+ * Leading/trailing whitespace of the returned value is preserved (callers trim
+ * the result themselves as needed).
+ */
+function stripInlineComment(line) {
+    let inString = false;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === '"')
+            inString = !inString;
+        if (!inString && line[i] === "#")
+            return line.slice(0, i).trimEnd();
+    }
+    return line;
+}
 export function parseBridge(text) {
-    // Normalize: CRLF → LF, tabs → 2 spaces
+    // Normalize: CRLF → LF, tabs → 2 spaces, inline comments stripped
     const normalized = text.replace(/\r\n?/g, "\n").replace(/\t/g, "  ");
-    const allLines = normalized.split("\n");
+    const allLines = normalized.split("\n").map(stripInlineComment);
+    // Version check — first non-blank, non-comment line must be `version 1.4`
+    const firstContentIdx = allLines.findIndex((l) => l.trim() !== "" && !l.trim().startsWith("#"));
+    if (firstContentIdx === -1 || !/^version\s+/.test(allLines[firstContentIdx].trim())) {
+        throw new Error(`Missing version declaration. Bridge files must begin with: version ${BRIDGE_VERSION}`);
+    }
+    const versionToken = allLines[firstContentIdx].trim().replace(/^version\s+/, "");
+    if (versionToken !== BRIDGE_VERSION) {
+        throw new Error(`Unsupported bridge version "${versionToken}". This parser requires: version ${BRIDGE_VERSION}`);
+    }
+    // Blank out the version line so block-splitting ignores it
+    allLines[firstContentIdx] = "";
     // Find separator lines (--- with optional surrounding whitespace)
     const isSep = (line) => /^\s*---\s*$/.test(line);
     // Collect block ranges as [start, end) line indices
@@ -35,7 +75,7 @@ export function parseBridge(text) {
         let currentOffset = start;
         for (let i = 0; i < blockLines.length; i++) {
             const trimmed = blockLines[i].trim();
-            if (/^(tool|bridge|const|extend)\s/i.test(trimmed) && currentLines.length > 0) {
+            if (/^(tool|bridge|const|define)\s/i.test(trimmed) && currentLines.length > 0) {
                 // Check if any non-blank content exists
                 if (currentLines.some((l) => l.trim())) {
                     subBlocks.push({ startOffset: currentOffset, lines: currentLines });
@@ -58,17 +98,20 @@ export function parseBridge(text) {
             while (firstContentLine < sub.lines.length && !sub.lines[firstContentLine].trim())
                 firstContentLine++;
             const firstLine = sub.lines[firstContentLine]?.trim();
-            if (firstLine && /^(tool|extend)\s/i.test(firstLine)) {
+            if (firstLine && /^tool\s/i.test(firstLine)) {
                 instructions.push(parseToolBlock(subText, sub.startOffset + firstContentLine, instructions));
             }
+            else if (firstLine && /^define\s/i.test(firstLine)) {
+                instructions.push(parseDefineBlock(subText, sub.startOffset + firstContentLine));
+            }
             else if (firstLine && /^bridge\s/i.test(firstLine)) {
-                instructions.push(...parseBridgeBlock(subText, sub.startOffset + firstContentLine));
+                instructions.push(...parseBridgeBlock(subText, sub.startOffset + firstContentLine, instructions));
             }
             else if (firstLine && /^const\s/i.test(firstLine)) {
                 instructions.push(...parseConstLines(subText, sub.startOffset + firstContentLine));
             }
             else if (firstLine && !firstLine.startsWith("#")) {
-                throw new Error(`Line ${sub.startOffset + firstContentLine + 1}: Expected "tool", "extend", "bridge", or "const" declaration, got: ${firstLine}`);
+                throw new Error(`Line ${sub.startOffset + firstContentLine + 1}: Expected "tool", "define", "bridge", or "const" declaration, got: ${firstLine}`);
             }
         }
     }
@@ -84,7 +127,30 @@ function isJsonLiteral(s) {
     return /^["\{\[\d]/.test(s) || /^-\d/.test(s) ||
         s === "true" || s === "false" || s === "null";
 }
-function parseBridgeBlock(block, lineOffset) {
+function parseBridgeBlock(block, lineOffset, previousInstructions) {
+    // ── Passthrough shorthand: `bridge Type.field with <name>` ──────────
+    // Expands into a full bridge that wires all input through the named
+    // handle (typically a define) and returns its output directly.
+    const shorthandMatch = block.match(/^bridge\s+(\w+)\.(\w+)\s+with\s+(\S+)\s*$/im);
+    if (shorthandMatch) {
+        const [, sType, sField, sName] = shorthandMatch;
+        const sHandle = sName.includes(".") ? sName.substring(sName.lastIndexOf(".") + 1) : sName;
+        const expanded = [
+            `bridge ${sType}.${sField} {`,
+            `  with ${sName} as ${sHandle}`,
+            `  with input`,
+            `  with output as __out`,
+            `  ${sHandle} <- input`,
+            `  __out <- ${sHandle}`,
+            `}`,
+        ].join("\n");
+        const result = parseBridgeBlock(expanded, lineOffset, previousInstructions);
+        // Tag the bridge instruction with the passthrough name for serialization
+        const bridgeInst = result.find((i) => i.kind === "bridge");
+        if (bridgeInst)
+            bridgeInst.passthrough = sName;
+        return result;
+    }
     // Validate mandatory braces: `bridge Foo.bar {` ... `}`
     const rawLines = block.split("\n");
     const keywordIdx = rawLines.findIndex((l) => /^bridge\s/i.test(l.trim()));
@@ -134,7 +200,7 @@ function parseBridgeBlock(block, lineOffset) {
             if (!bridgeType) {
                 throw new Error(`Line ${ln(i)}: "with" declaration must come after "bridge" declaration`);
             }
-            parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBindings, instanceCounters, instructions, ln(i));
+            parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBindings, instanceCounters, previousInstructions ?? [], ln(i));
             continue;
         }
         // First non-header line — body starts here
@@ -147,6 +213,8 @@ function parseBridgeBlock(block, lineOffset) {
     // ── Parse wire lines ────────────────────────────────────────────────
     const wires = [];
     let currentArrayToPath = null;
+    let currentIterHandle = null;
+    const arrayIterators = {};
     /** Monotonically-increasing index; combined with a high base to produce
      *  fork instances that can never collide with regular handle instances. */
     let nextForkSeq = 0;
@@ -167,7 +235,7 @@ function parseBridgeBlock(block, lineOffset) {
     function buildSourceExpr(sourceStr, lineNum, forceOnOutermost) {
         const parts = sourceStr.split(":");
         if (parts.length === 1) {
-            return resolveAddress(sourceStr, handleRes, bridgeType, bridgeField);
+            return resolveAddress(sourceStr, handleRes, bridgeType, bridgeField, lineNum);
         }
         // Pipe chain
         const actualSource = parts[parts.length - 1];
@@ -184,7 +252,7 @@ function parseBridgeBlock(block, lineOffset) {
                 throw new Error(`Line ${lineNum}: Undeclared handle in pipe: "${handleName}". Add 'with <tool> as ${handleName}' to the bridge header.`);
             }
         }
-        let prevOutRef = resolveAddress(actualSource, handleRes, bridgeType, bridgeField);
+        let prevOutRef = resolveAddress(actualSource, handleRes, bridgeType, bridgeField, lineNum);
         const reversedTokens = [...tokenChain].reverse();
         for (let idx = 0; idx < reversedTokens.length; idx++) {
             const tok = reversedTokens[idx];
@@ -205,72 +273,165 @@ function parseBridgeBlock(block, lineOffset) {
         }
         return prevOutRef; // fork-root ref
     }
+    // ── Whether we are inside an element-mapping brace block
+    let inElementBlock = false;
     for (let i = bodyStartIndex; i < lines.length; i++) {
         const raw = lines[i];
         const line = raw.trim();
         if (!line || line.startsWith("#")) {
             continue;
         }
-        // Element mapping: indented line starting with "."
-        const indent = raw.search(/\S/);
-        if (indent >= 2 && line.startsWith(".") && currentArrayToPath) {
-            const match = line.match(/^\.(\S+)\s*<-\s*\.(\S+)$/);
-            if (!match)
-                throw new Error(`Line ${ln(i)}: Invalid element mapping: ${line}`);
-            const toPath = [...currentArrayToPath, ...parsePath(match[1])];
-            const fromPath = parsePath(match[2]);
-            wires.push({
-                from: {
-                    module: SELF_MODULE,
-                    type: bridgeType,
-                    field: bridgeField,
-                    element: true,
-                    path: fromPath,
-                },
-                to: {
-                    module: SELF_MODULE,
-                    type: bridgeType,
-                    field: bridgeField,
-                    path: toPath,
-                },
-            });
-            continue;
+        // Closing brace of an element mapping block `{ ... }`
+        if (line === "}") {
+            if (inElementBlock) {
+                currentArrayToPath = null;
+                currentIterHandle = null;
+                inElementBlock = false;
+                continue;
+            }
+            throw new Error(`Line ${ln(i)}: Unexpected "}" — not inside an element block`);
+        }
+        // Element mapping lines (inside a brace block)
+        if (inElementBlock && currentArrayToPath) {
+            if (!line.startsWith(".")) {
+                throw new Error(`Line ${ln(i)}: Element mapping lines must start with ".": ${line}`);
+            }
+            // Constant: .target = "value" or .target = value
+            const elemConstMatch = line.match(/^\.(\S+)\s*=\s*(?:"([^"]*)"|(\S+))$/);
+            if (elemConstMatch) {
+                const [, fieldName, quotedValue, unquotedValue] = elemConstMatch;
+                const value = quotedValue ?? unquotedValue;
+                wires.push({
+                    value,
+                    to: {
+                        module: SELF_MODULE,
+                        type: bridgeType,
+                        field: bridgeField,
+                        element: true,
+                        path: [...currentArrayToPath, ...parsePath(fieldName)],
+                    },
+                });
+                continue;
+            }
+            // Simple pull: .target <- <iter>.source (element-relative, no fallbacks)
+            const iterPfx = `${currentIterHandle}.`;
+            const elemRelMatch = line.match(/^\.(\S+)\s*<-\s*(\S+)$/);
+            if (elemRelMatch && elemRelMatch[2].startsWith(iterPfx)) {
+                const toPath = [...currentArrayToPath, ...parsePath(elemRelMatch[1])];
+                const fromPath = parsePath(elemRelMatch[2].slice(iterPfx.length));
+                wires.push({
+                    from: {
+                        module: SELF_MODULE,
+                        type: bridgeType,
+                        field: bridgeField,
+                        element: true,
+                        path: fromPath,
+                    },
+                    to: {
+                        module: SELF_MODULE,
+                        type: bridgeType,
+                        field: bridgeField,
+                        path: toPath,
+                    },
+                });
+                continue;
+            }
+            // Pull with fallbacks: .target <- source || "fallback" ?? errorSrc (relative or handle path)
+            const elemArrowMatch = line.match(/^\.(\S+)\s*<-\s*(.+)$/);
+            if (elemArrowMatch) {
+                const [, toField, rhs] = elemArrowMatch;
+                const toPath = [...currentArrayToPath, ...parsePath(toField)];
+                const toRef = { module: SELF_MODULE, type: bridgeType, field: bridgeField, path: toPath };
+                // Strip ?? tail
+                let exprCore = rhs.trim();
+                let fallback;
+                let fallbackRefStr;
+                const qqIdx = exprCore.lastIndexOf(" ?? ");
+                if (qqIdx !== -1) {
+                    const tail = exprCore.slice(qqIdx + 4).trim();
+                    exprCore = exprCore.slice(0, qqIdx).trim();
+                    if (isJsonLiteral(tail))
+                        fallback = tail;
+                    else
+                        fallbackRefStr = tail;
+                }
+                // Split on || — last may be JSON literal (nullFallback)
+                const orParts = exprCore.split(" || ").map((s) => s.trim());
+                let nullFallback;
+                let sourceParts = orParts;
+                if (orParts.length > 1 && isJsonLiteral(orParts[orParts.length - 1])) {
+                    nullFallback = orParts[orParts.length - 1];
+                    sourceParts = orParts.slice(0, -1);
+                }
+                let fallbackRef;
+                let fallbackInternalWires = [];
+                if (fallbackRefStr) {
+                    const preLen = wires.length;
+                    fallbackRef = buildSourceExpr(fallbackRefStr, ln(i), false);
+                    fallbackInternalWires = wires.splice(preLen);
+                }
+                for (let ci = 0; ci < sourceParts.length; ci++) {
+                    const srcStr = sourceParts[ci];
+                    const isLast = ci === sourceParts.length - 1;
+                    // Element-relative source: starts with "<iter>."
+                    const iterPrefix = `${currentIterHandle}.`;
+                    let fromRef;
+                    if (srcStr.startsWith(iterPrefix)) {
+                        fromRef = {
+                            module: SELF_MODULE,
+                            type: bridgeType,
+                            field: bridgeField,
+                            element: true,
+                            path: parsePath(srcStr.slice(iterPrefix.length)),
+                        };
+                    }
+                    else if (srcStr.startsWith(".")) {
+                        throw new Error(`Line ${ln(i)}: Use "${currentIterHandle}.field" to reference element fields, not ".field"`);
+                    }
+                    else {
+                        fromRef = buildSourceExpr(srcStr, ln(i), false);
+                    }
+                    const lastAttrs = isLast ? {
+                        ...(nullFallback ? { nullFallback } : {}),
+                        ...(fallback ? { fallback } : {}),
+                        ...(fallbackRef ? { fallbackRef } : {}),
+                    } : {};
+                    wires.push({ from: fromRef, to: toRef, ...lastAttrs });
+                }
+                wires.push(...fallbackInternalWires);
+                continue;
+            }
+            throw new Error(`Line ${ln(i)}: Invalid element mapping line: ${line}`);
         }
-        // End of array mapping block
-        currentArrayToPath = null;
         // Constant wire: target = "value" or target = value (unquoted)
         const constantMatch = line.match(/^(\S+)\s*=\s*(?:"([^"]*)"|(\S+))$/);
         if (constantMatch) {
             const [, targetStr, quotedValue, unquotedValue] = constantMatch;
             const value = quotedValue ?? unquotedValue;
-            const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField);
+            const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
             wires.push({ value, to: toRef });
             continue;
         }
         // ── Wire: target <- A [|| B [|| C]] [|| "nullLiteral"] [?? errorSrc|"errorLiteral"]
-        //
-        // A, B, C are source expressions (handle.path or pipe|chain|src).
-        // `||` separates null-coalescing alternatives — evaluated left to right;
-        //   the last alternative may be a JSON literal (→ nullFallback).
-        // `??` is the error fallback — fires when ALL sources throw.
-        //   Can be a JSON literal (→ fallback) or a source expression (→ fallbackRef).
-        //
-        // Each `||` source becomes a separate wire targeting the same field.
-        // The last source wire carries nullFallback + error-fallback attributes.
-        // Desugars transparently: serializer emits back as multiple wire lines.
         const arrowMatch = line.match(/^(\S+)\s*<-(!?)\s*(.+)$/);
         if (arrowMatch) {
             const [, targetStr, forceFlag, rhs] = arrowMatch;
             const force = forceFlag === "!";
             const rhsTrimmed = rhs.trim();
-            // ── Array mapping: target[] <- source[]  (no || or ?? here)
-            if (targetStr.endsWith("[]") && /^\S+\[\]$/.test(rhsTrimmed)) {
-                const toClean = targetStr.slice(0, -2);
-                const fromClean = rhsTrimmed.slice(0, -2);
-                const fromRef = resolveAddress(fromClean, handleRes, bridgeType, bridgeField);
-                const toRef = resolveAddress(toClean, handleRes, bridgeType, bridgeField);
+            // ── Array mapping: target <- source[] as <iter> {
+            //    Opens a brace-delimited element block.
+            const arrayBraceMatch = rhsTrimmed.match(/^(\S+)\[\]\s+as\s+(\w+)\s*\{\s*$/);
+            if (arrayBraceMatch) {
+                const fromClean = arrayBraceMatch[1];
+                const iterHandle = arrayBraceMatch[2];
+                assertNotReserved(iterHandle, ln(i), "iterator handle");
+                const fromRef = resolveAddress(fromClean, handleRes, bridgeType, bridgeField, ln(i));
+                const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
                 wires.push({ from: fromRef, to: toRef });
                 currentArrayToPath = toRef.path;
+                currentIterHandle = iterHandle;
+                arrayIterators[toRef.path[0]] = iterHandle;
+                inElementBlock = true;
                 continue;
             }
             // ── Strip the ?? tail (last " ?? " wins in case source contains " ?? ")
@@ -300,38 +461,27 @@ function parseBridgeBlock(block, lineOffset) {
             if (sourceParts.length === 0) {
                 throw new Error(`Line ${ln(i)}: Wire has no source expression: ${line}`);
             }
-            // ── Parse the ?? source/pipe into a fallbackRef (if needed)
-            // Wires added by buildSourceExpr for the fallback fork are deferred and
-            // pushed AFTER the source wires so that wire order is stable across
-            // parse → serialize → re-parse cycles.
             let fallbackRef;
             let fallbackInternalWires = [];
             if (fallbackRefStr) {
                 const preLen = wires.length;
                 fallbackRef = buildSourceExpr(fallbackRefStr, ln(i), false);
-                // Splice out internal wires buildSourceExpr just added; push after sources.
                 fallbackInternalWires = wires.splice(preLen);
             }
-            // ── Build wires for each coalesce part
-            const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField);
+            const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
             for (let ci = 0; ci < sourceParts.length; ci++) {
                 const isFirst = ci === 0;
                 const isLast = ci === sourceParts.length - 1;
                 const srcStr = sourceParts[ci];
-                // Parse source expression; for pipe chains buildSourceExpr pushes
-                // intermediate wires and returns the fork-root ref.
                 const termRef = buildSourceExpr(srcStr, ln(i), force && isFirst);
                 const isPipeFork = termRef.instance != null && termRef.path.length === 0
                     && srcStr.includes(":");
-                // attrs carried only on the LAST wire of the coalesce chain
                 const lastAttrs = isLast ? {
                     ...(nullFallback ? { nullFallback } : {}),
                     ...(fallback ? { fallback } : {}),
                     ...(fallbackRef ? { fallbackRef } : {}),
                 } : {};
                 if (isPipeFork) {
-                    // Terminal pipe wire: fork-root → target  (force only on outermost
-                    // intermediate wire, already set inside buildSourceExpr)
                     wires.push({ from: termRef, to: toRef, pipe: true, ...lastAttrs });
                 }
                 else {
@@ -343,19 +493,29 @@ function parseBridgeBlock(block, lineOffset) {
                     });
                 }
             }
-            // Push fallbackRef internal wires after all source wires (stable round-trip
-            // order: same position whether parsed inline or from serialized separate lines)
             wires.push(...fallbackInternalWires);
             continue;
         }
         throw new Error(`Line ${ln(i)}: Unrecognized line: ${line}`);
     }
+    // ── Inline define invocations ───────────────────────────────────────
+    const nextForkSeqRef = { value: nextForkSeq };
+    for (const hb of handleBindings) {
+        if (hb.kind !== "define")
+            continue;
+        const def = previousInstructions?.find((inst) => inst.kind === "define" && inst.name === hb.name);
+        if (!def) {
+            throw new Error(`Define "${hb.name}" referenced by handle "${hb.handle}" not found`);
+        }
+        inlineDefine(hb.handle, def, bridgeType, bridgeField, wires, pipeHandleEntries, handleBindings, instanceCounters, nextForkSeqRef);
+    }
     instructions.unshift({
         kind: "bridge",
         type: bridgeType,
         field: bridgeField,
         handles: handleBindings,
         wires,
+        arrayIterators: Object.keys(arrayIterators).length > 0 ? arrayIterators : undefined,
         pipeHandles: pipeHandleEntries.length > 0 ? pipeHandleEntries : undefined,
     });
     return instructions;
@@ -390,6 +550,45 @@ function parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBi
         });
         return;
     }
+    // with input (shorthand — handle defaults to "input")
+    match = line.match(/^with\s+input$/i);
+    if (match) {
+        const handle = "input";
+        checkDuplicate(handle);
+        handleBindings.push({ handle, kind: "input" });
+        handleRes.set(handle, {
+            module: SELF_MODULE,
+            type: bridgeType,
+            field: bridgeField,
+        });
+        return;
+    }
+    // with output as <handle>
+    match = line.match(/^with\s+output\s+as\s+(\w+)$/i);
+    if (match) {
+        const handle = match[1];
+        checkDuplicate(handle);
+        handleBindings.push({ handle, kind: "output" });
+        handleRes.set(handle, {
+            module: SELF_MODULE,
+            type: bridgeType,
+            field: bridgeField,
+        });
+        return;
+    }
+    // with output (shorthand — handle defaults to "output")
+    match = line.match(/^with\s+output$/i);
+    if (match) {
+        const handle = "output";
+        checkDuplicate(handle);
+        handleBindings.push({ handle, kind: "output" });
+        handleRes.set(handle, {
+            module: SELF_MODULE,
+            type: bridgeType,
+            field: bridgeField,
+        });
+        return;
+    }
     // with context as <handle>
     match = line.match(/^with\s+context\s+as\s+(\w+)$/i);
     if (match) {
@@ -442,13 +641,24 @@ function parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBi
         });
         return;
     }
-    // with <name> as <handle> — tool reference (covers dotted names like hereapi.geocode)
+    // with <name> as <handle> — check for define invocation first
     match = line.match(/^with\s+(\S+)\s+as\s+(\w+)$/i);
     if (match) {
         const name = match[1];
         const handle = match[2];
         checkDuplicate(handle);
-        // Split dotted name into module.field for NodeRef resolution
+        assertNotReserved(handle, lineNum, "handle alias");
+        // Check if name matches a known define
+        const defineDef = instructions.find((inst) => inst.kind === "define" && inst.name === name);
+        if (defineDef) {
+            handleBindings.push({ handle, kind: "define", name });
+            handleRes.set(handle, {
+                module: `__define_${handle}`,
+                type: bridgeType,
+                field: bridgeField,
+            });
+            return;
+        }
         const lastDot = name.lastIndexOf(".");
         if (lastDot !== -1) {
             const modulePart = name.substring(0, lastDot);
@@ -487,6 +697,17 @@ function parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBi
         const lastDot = name.lastIndexOf(".");
         const handle = lastDot !== -1 ? name.substring(lastDot + 1) : name;
         checkDuplicate(handle);
+        // Check if name matches a known define
+        const defineDef = instructions.find((inst) => inst.kind === "define" && inst.name === name);
+        if (defineDef) {
+            handleBindings.push({ handle, kind: "define", name });
+            handleRes.set(handle, {
+                module: `__define_${handle}`,
+                type: bridgeType,
+                field: bridgeField,
+            });
+            return;
+        }
         if (lastDot !== -1) {
             const modulePart = name.substring(0, lastDot);
             const fieldPart = name.substring(lastDot + 1);
@@ -507,6 +728,155 @@ function parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBi
     }
     throw new Error(`Line ${lineNum}: Invalid with declaration: ${line}`);
 }
+// ── Define inlining ─────────────────────────────────────────────────────────
+/**
+ * Inline a define invocation into a bridge's wires.
+ *
+ * Splits the define handle into separate input/output synthetic trunks,
+ * clones the define's internal wires with remapped references, and adds
+ * them to the bridge. Tool instances are remapped to avoid collisions.
+ *
+ * The executor treats synthetic trunks (module starting with `__define_`)
+ * as pass-through data containers — no tool function is called.
+ */
+function inlineDefine(defineHandle, defineDef, bridgeType, bridgeField, wires, pipeHandleEntries, handleBindings, instanceCounters, nextForkSeqRef) {
+    const genericModule = `__define_${defineHandle}`;
+    const inModule = `__define_in_${defineHandle}`;
+    const outModule = `__define_out_${defineHandle}`;
+    // The define was parsed as synthetic `bridge Define.<name>`, so its
+    // internal refs use type="Define", field=defineName for I/O, and
+    // standard tool resolutions for tools.
+    const defType = "Define";
+    const defField = defineDef.name;
+    // ── 1. Build trunk remapping for define's tool handles ──────────────
+    // Replay define's instance counter to determine original instances
+    const defCounters = new Map();
+    const trunkRemap = new Map();
+    for (const hb of defineDef.handles) {
+        if (hb.kind === "input" || hb.kind === "output" || hb.kind === "context" || hb.kind === "const")
+            continue;
+        if (hb.kind === "define")
+            continue; // nested defines — future
+        const name = hb.kind === "tool" ? hb.name : "";
+        if (!name)
+            continue;
+        const lastDot = name.lastIndexOf(".");
+        let oldModule, oldType, oldField, instanceKey, bridgeKey;
+        if (lastDot !== -1) {
+            oldModule = name.substring(0, lastDot);
+            oldType = defType;
+            oldField = name.substring(lastDot + 1);
+            instanceKey = `${oldModule}:${oldField}`;
+            bridgeKey = instanceKey;
+        }
+        else {
+            oldModule = SELF_MODULE;
+            oldType = "Tools";
+            oldField = name;
+            instanceKey = `Tools:${name}`;
+            bridgeKey = instanceKey;
+        }
+        // Old instance (from define's isolated counter)
+        const oldInstance = (defCounters.get(instanceKey) ?? 0) + 1;
+        defCounters.set(instanceKey, oldInstance);
+        // New instance (from bridge's counter)
+        const newInstance = (instanceCounters.get(bridgeKey) ?? 0) + 1;
+        instanceCounters.set(bridgeKey, newInstance);
+        const oldKey = `${oldModule}:${oldType}:${oldField}:${oldInstance}`;
+        trunkRemap.set(oldKey, { module: oldModule, type: oldType, field: oldField, instance: newInstance });
+        // Add internal tool handle to bridge's handle bindings (namespaced)
+        handleBindings.push({ handle: `${defineHandle}$${hb.handle}`, kind: "tool", name });
+    }
+    // ── 2. Remap bridge wires involving the define handle ───────────────
+    for (const wire of wires) {
+        if ("from" in wire) {
+            if (wire.to.module === genericModule) {
+                wire.to = { ...wire.to, module: inModule };
+            }
+            if (wire.from.module === genericModule) {
+                wire.from = { ...wire.from, module: outModule };
+            }
+            if (wire.fallbackRef?.module === genericModule) {
+                wire.fallbackRef = { ...wire.fallbackRef, module: outModule };
+            }
+        }
+        if ("value" in wire && wire.to.module === genericModule) {
+            wire.to = { ...wire.to, module: inModule };
+        }
+    }
+    // ── 3. Clone, remap, and add define's wires ────────────────────────
+    // Compute fork instance offset (define's fork instances start at 100000,
+    // bridge's may overlap — offset them to avoid collision)
+    const forkOffset = nextForkSeqRef.value;
+    let maxDefForkSeq = 0;
+    function remapRef(ref, side) {
+        // Define I/O trunk → split into input/output synthetic trunks
+        if (ref.module === SELF_MODULE && ref.type === defType && ref.field === defField) {
+            const targetModule = side === "from" ? inModule : outModule;
+            return { ...ref, module: targetModule, type: bridgeType, field: bridgeField };
+        }
+        // Tool trunk → remap instance
+        const key = `${ref.module}:${ref.type}:${ref.field}:${ref.instance ?? ""}`;
+        const newTrunk = trunkRemap.get(key);
+        if (newTrunk) {
+            return { ...ref, module: newTrunk.module, type: newTrunk.type, field: newTrunk.field, instance: newTrunk.instance };
+        }
+        // Fork instance → offset (fork instances are >= 100000)
+        if (ref.instance != null && ref.instance >= 100000) {
+            const defSeq = ref.instance - 100000;
+            if (defSeq + 1 > maxDefForkSeq)
+                maxDefForkSeq = defSeq + 1;
+            return { ...ref, instance: ref.instance + forkOffset };
+        }
+        return ref;
+    }
+    for (const wire of defineDef.wires) {
+        const cloned = JSON.parse(JSON.stringify(wire));
+        if ("from" in cloned) {
+            cloned.from = remapRef(cloned.from, "from");
+            cloned.to = remapRef(cloned.to, "to");
+            if (cloned.fallbackRef) {
+                cloned.fallbackRef = remapRef(cloned.fallbackRef, "from");
+            }
+        }
+        else {
+            // Constant wire
+            cloned.to = remapRef(cloned.to, "to");
+        }
+        wires.push(cloned);
+    }
+    // Advance bridge's fork counter past define's forks
+    nextForkSeqRef.value += maxDefForkSeq;
+    // ── 4. Remap and merge pipe handles ─────────────────────────────────
+    if (defineDef.pipeHandles) {
+        for (const ph of defineDef.pipeHandles) {
+            const parts = ph.key.split(":");
+            // key format: "module:type:field:instance"
+            const phInstance = parseInt(parts[parts.length - 1]);
+            let newKey = ph.key;
+            if (phInstance >= 100000) {
+                const newInst = phInstance + forkOffset;
+                parts[parts.length - 1] = String(newInst);
+                newKey = parts.join(":");
+            }
+            // Remap baseTrunk
+            const bt = ph.baseTrunk;
+            const btKey = `${bt.module}:${defType}:${bt.field}:${bt.instance ?? ""}`;
+            const newBt = trunkRemap.get(btKey);
+            // Also try with Tools type for simple names
+            const btKey2 = `${bt.module}:Tools:${bt.field}:${bt.instance ?? ""}`;
+            const newBt2 = trunkRemap.get(btKey2);
+            const resolvedBt = newBt ?? newBt2;
+            pipeHandleEntries.push({
+                key: newKey,
+                handle: `${defineHandle}$${ph.handle}`,
+                baseTrunk: resolvedBt
+                    ? { module: resolvedBt.module, type: resolvedBt.type, field: resolvedBt.field, instance: resolvedBt.instance }
+                    : ph.baseTrunk,
+            });
+        }
+    }
+}
 /**
  * Resolve an address string into a structured NodeRef.
  *
@@ -516,7 +886,7 @@ function parseWithDeclaration(line, bridgeType, bridgeField, handleRes, handleBi
  *   3. Prefix matches a declared handle → resolve via handle binding
  *   4. Otherwise → nested output path (e.g., topPick.address)
  */
-function resolveAddress(address, handles, bridgeType, bridgeField) {
+function resolveAddress(address, handles, bridgeType, bridgeField, lineNum) {
     const dotIndex = address.indexOf(".");
     if (dotIndex === -1) {
         // Whole address is a declared handle → resolve to its root (path: [])
@@ -532,13 +902,9 @@ function resolveAddress(address, handles, bridgeType, bridgeField) {
                 ref.instance = resolution.instance;
             return ref;
         }
-        // No dot, not a handle — output reference on bridge trunk
-        return {
-            module: SELF_MODULE,
-            type: bridgeType,
-            field: bridgeField,
-            path: parsePath(address),
-        };
+        // Strict scoping: every reference must go through a declared handle.
+        throw new Error(`${lineNum != null ? `Line ${lineNum}: ` : ""}Undeclared reference "${address}". ` +
+            `Add 'with output as o' for output fields, or 'with ${address}' for a tool.`);
     }
     const prefix = address.substring(0, dotIndex);
     const rest = address.substring(dotIndex + 1);
@@ -557,23 +923,9 @@ function resolveAddress(address, handles, bridgeType, bridgeField) {
         }
         return ref;
     }
-    // No handle match — nested local path (e.g., topPick.address)
-    // UNLESS the prefix IS the bridge field itself (e.g., doubled.a when bridge is Query.doubled)
-    // — in that case strip the prefix so path = ["a"], matching the GraphQL resolver path.
-    if (prefix === bridgeField) {
-        return {
-            module: SELF_MODULE,
-            type: bridgeType,
-            field: bridgeField,
-            path: pathParts,
-        };
-    }
-    return {
-        module: SELF_MODULE,
-        type: bridgeType,
-        field: bridgeField,
-        path: [prefix, ...pathParts],
-    };
+    // Strict scoping: prefix must be a known handle.
+    throw new Error(`${lineNum != null ? `Line ${lineNum}: ` : ""}Undeclared handle "${prefix}". ` +
+        `Add 'with ${prefix}' or 'with ${prefix} as ${prefix}' to the bridge header.`);
 }
 // ── Const block parser ──────────────────────────────────────────────────────
 /**
@@ -604,6 +956,7 @@ function parseConstLines(block, lineOffset) {
             throw new Error(`Line ${ln(i)}: Expected const declaration, got: ${line}`);
         }
         const name = constMatch[1];
+        assertNotReserved(name, ln(i), "const name");
         let valuePart = constMatch[2].trim();
         // Multi-line: if value starts with { or [ and isn't balanced, read more lines
         if (/^[{[]/.test(valuePart)) {
@@ -642,38 +995,92 @@ function parseConstLines(block, lineOffset) {
     }
     return results;
 }
-// ── Tool block parser ───────────────────────────────────────────────────────
+// ── Define block parser ─────────────────────────────────────────────────────
 /**
- * Parse a `tool` or `extend` block into a ToolDef instruction.
+ * Parse a `define` block into a DefineDef instruction.
  *
- * Legacy format (root tool):
- *   tool hereapi httpCall
- *     with context
- *     baseUrl = "https://geocode.search.hereapi.com/v1"
- *     headers.apiKey <- context.hereapi.apiKey
+ * Delegates to parseBridgeBlock with a synthetic `bridge Define.<name>` header,
+ * then converts the resulting Bridge to a DefineDef template.
  *
- * Legacy format (child tool with extends):
- *   tool hereapi.geocode extends hereapi
- *     method = GET
- *     path = /geocode
+ * Example:
+ *   define secureProfile {
+ *     with userApi as api
+ *     with input as i
+ *     with output as o
+ *     api.id <- i.userId
+ *     o.name <- api.login
+ *   }
+ */
+function parseDefineBlock(block, lineOffset) {
+    const rawLines = block.split("\n");
+    // Find the define header line
+    let headerIdx = -1;
+    let defineName = "";
+    for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i].trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const m = line.match(/^define\s+(\w+)\s*\{?\s*$/i);
+        if (!m) {
+            throw new Error(`Line ${lineOffset + i + 1}: Expected define declaration: define <name> {. Got: ${line}`);
+        }
+        defineName = m[1];
+        assertNotReserved(defineName, lineOffset + i + 1, "define name");
+        headerIdx = i;
+        break;
+    }
+    if (!defineName) {
+        throw new Error(`Line ${lineOffset + 1}: Missing define declaration`);
+    }
+    // Validate braces
+    const kw = rawLines[headerIdx].trim();
+    if (!kw.endsWith("{")) {
+        throw new Error(`Line ${lineOffset + headerIdx + 1}: define block must use braces: define ${defineName} {`);
+    }
+    const hasClose = rawLines.some((l) => l.trimEnd() === "}");
+    if (!hasClose) {
+        throw new Error(`Line ${lineOffset + headerIdx + 1}: define block missing closing }`);
+    }
+    // Rewrite header to a synthetic bridge: `bridge Define.<name> {`
+    const syntheticLines = [...rawLines];
+    syntheticLines[headerIdx] = rawLines[headerIdx]
+        .replace(/^(\s*)define\s+\w+/i, `$1bridge Define.${defineName}`);
+    const syntheticBlock = syntheticLines.join("\n");
+    const results = parseBridgeBlock(syntheticBlock, lineOffset);
+    const bridge = results[0];
+    return {
+        kind: "define",
+        name: defineName,
+        handles: bridge.handles,
+        wires: bridge.wires,
+        ...(bridge.arrayIterators ? { arrayIterators: bridge.arrayIterators } : {}),
+        ...(bridge.pipeHandles ? { pipeHandles: bridge.pipeHandles } : {}),
+    };
+}
+// ── Tool block parser ───────────────────────────────────────────────────────
+/**
+ * Parse a `tool` block into a ToolDef instruction.
  *
- * New format (extend):
- *   extend httpCall as hereapi
+ * Format:
+ *   tool hereapi from httpCall {
  *     with context
- *     baseUrl = "https://geocode.search.hereapi.com/v1"
+ *     .baseUrl = "https://geocode.search.hereapi.com/v1"
+ *     .headers.apiKey <- context.hereapi.apiKey
+ *   }
  *
- *   extend hereapi as hereapi.geocode
- *     method = GET
- *     path = /geocode
+ *   tool hereapi.geocode from hereapi {
+ *     .method = GET
+ *     .path = /geocode
+ *   }
  *
- * When using `extend`, if the source matches a previously-defined tool name,
- * it's treated as an extends (child inherits parent). Otherwise the source
+ * When the source matches a previously-defined tool name,
+ * it's treated as inheritance (child inherits parent). Otherwise the source
  * is treated as a function name.
  */
 function parseToolBlock(block, lineOffset, previousInstructions) {
     // Validate mandatory braces for blocks that have a body (deps / wires)
     const rawLines = block.split("\n");
-    const keywordIdx = rawLines.findIndex((l) => /^(tool|extend)\s/i.test(l.trim()));
+    const keywordIdx = rawLines.findIndex((l) => /^tool\s/i.test(l.trim()));
     if (keywordIdx !== -1) {
         // Check if there are non-blank, non-comment body lines after the keyword
         const bodyLines = rawLines.slice(keywordIdx + 1).filter((l) => {
@@ -683,11 +1090,11 @@ function parseToolBlock(block, lineOffset, previousInstructions) {
         const kw = rawLines[keywordIdx].trim();
         if (bodyLines.length > 0) {
             if (!kw.endsWith("{")) {
-                throw new Error(`Line ${lineOffset + keywordIdx + 1}: extend/tool block with body must use braces: extend Foo as bar {`);
+                throw new Error(`Line ${lineOffset + keywordIdx + 1}: tool block with body must use braces: tool foo from bar {`);
             }
             const hasClose = rawLines.some((l) => l.trimEnd() === "}");
             if (!hasClose) {
-                throw new Error(`Line ${lineOffset + keywordIdx + 1}: extend/tool block missing closing }`);
+                throw new Error(`Line ${lineOffset + keywordIdx + 1}: tool block missing closing }`);
             }
         }
     }
@@ -696,7 +1103,7 @@ function parseToolBlock(block, lineOffset, previousInstructions) {
         const trimmed = l.trimEnd();
         if (trimmed === "}")
             return "";
-        if (/^(tool|extend)\s/i.test(trimmed) && trimmed.endsWith("{"))
+        if (/^tool\s/i.test(trimmed) && trimmed.endsWith("{"))
             return trimmed.replace(/\s*\{\s*$/, "");
         return trimmed;
     });
@@ -712,31 +1119,16 @@ function parseToolBlock(block, lineOffset, previousInstructions) {
         const line = raw.trim();
         if (!line || line.startsWith("#"))
             continue;
-        // Tool declaration: tool <name> <fn> or tool <name> extends <parent>
+        // Tool declaration: tool <name> from <source>
         if (/^tool\s/i.test(line)) {
-            const extendsMatch = line.match(/^tool\s+(\S+)\s+extends\s+(\S+)$/i);
-            if (extendsMatch) {
-                toolName = extendsMatch[1];
-                toolExtends = extendsMatch[2];
-                continue;
-            }
-            const fnMatch = line.match(/^tool\s+(\S+)\s+(\S+)$/i);
-            if (fnMatch) {
-                toolName = fnMatch[1];
-                toolFn = fnMatch[2];
-                continue;
-            }
-            throw new Error(`Line ${ln(i)}: Invalid tool declaration: ${line}`);
-        }
-        // Extend declaration: extend <source> as <name>
-        if (/^extend\s/i.test(line)) {
-            const extendMatch = line.match(/^extend\s+(\S+)\s+as\s+(\S+)$/i);
-            if (!extendMatch) {
-                throw new Error(`Line ${ln(i)}: Invalid extend declaration: ${line}. Expected: extend <source> as <name>`);
+            const toolMatch = line.match(/^tool\s+(\S+)\s+from\s+(\S+)$/i);
+            if (!toolMatch) {
+                throw new Error(`Line ${ln(i)}: Invalid tool declaration: ${line}. Expected: tool <name> from <source>`);
             }
-            const source = extendMatch[1];
-            toolName = extendMatch[2];
-            // If source matches a previously-defined tool, it's an extends; otherwise it's a function name
+            toolName = toolMatch[1];
+            const source = toolMatch[2];
+            assertNotReserved(toolName, ln(i), "tool name");
+            // If source matches a previously-defined tool, it's inheritance; otherwise it's a function name
             const isKnownTool = previousInstructions?.some((inst) => inst.kind === "tool" && inst.name === source);
             if (isKnownTool) {
                 toolExtends = source;
@@ -800,8 +1192,8 @@ function parseToolBlock(block, lineOffset, previousInstructions) {
             wires.push({ kind: "onError", source: onErrorPullMatch[1] });
             continue;
         }
-        // Constant wire: target = "value" or target = value (unquoted)
-        const constantMatch = line.match(/^(\S+)\s*=\s*(?:"([^"]*)"|(\S+))$/);
+        // Constant wire: .target = "value" or .target = value (unquoted)
+        const constantMatch = line.match(/^\.(\S+)\s*=\s*(?:"([^"]*)"|(\S+))$/);
         if (constantMatch) {
             const value = constantMatch[2] ?? constantMatch[3];
             wires.push({
@@ -811,12 +1203,16 @@ function parseToolBlock(block, lineOffset, previousInstructions) {
             });
             continue;
         }
-        // Pull wire: target <- source
-        const pullMatch = line.match(/^(\S+)\s*<-\s*(\S+)$/);
+        // Pull wire: .target <- source
+        const pullMatch = line.match(/^\.(\S+)\s*<-\s*(\S+)$/);
         if (pullMatch) {
             wires.push({ target: pullMatch[1], kind: "pull", source: pullMatch[2] });
             continue;
         }
+        // Catch bare param lines without leading dot — give a helpful error
+        if (/^[a-zA-Z]/.test(line)) {
+            throw new Error(`Line ${ln(i)}: Tool params require a dot prefix: ".${line.split(/[\s=<]/)[0]} ...". Only 'with' and 'on error' lines are unprefixed.`);
+        }
         throw new Error(`Line ${ln(i)}: Unrecognized tool line: ${line}`);
     }
     if (!toolName)
@@ -862,7 +1258,8 @@ export function serializeBridge(instructions) {
     const bridges = instructions.filter((i) => i.kind === "bridge");
     const tools = instructions.filter((i) => i.kind === "tool");
     const consts = instructions.filter((i) => i.kind === "const");
-    if (bridges.length === 0 && tools.length === 0 && consts.length === 0)
+    const defines = instructions.filter((i) => i.kind === "define");
+    if (bridges.length === 0 && tools.length === 0 && consts.length === 0 && defines.length === 0)
         return "";
     const blocks = [];
     // Group const declarations into a single block
@@ -872,21 +1269,20 @@ export function serializeBridge(instructions) {
     for (const tool of tools) {
         blocks.push(serializeToolBlock(tool));
     }
+    for (const def of defines) {
+        blocks.push(serializeDefineBlock(def));
+    }
     for (const bridge of bridges) {
         blocks.push(serializeBridgeBlock(bridge));
     }
-    return blocks.join("\n\n") + "\n";
+    return `version ${BRIDGE_VERSION}\n\n` + blocks.join("\n\n") + "\n";
 }
 function serializeToolBlock(tool) {
     const lines = [];
     const hasBody = tool.deps.length > 0 || tool.wires.length > 0;
-    // Declaration line — use `extend` format
-    if (tool.extends) {
-        lines.push(hasBody ? `extend ${tool.extends} as ${tool.name} {` : `extend ${tool.extends} as ${tool.name}`);
-    }
-    else {
-        lines.push(hasBody ? `extend ${tool.fn} as ${tool.name} {` : `extend ${tool.fn} as ${tool.name}`);
-    }
+    // Declaration line — use `tool <name> from <source>` format
+    const source = tool.extends ?? tool.fn;
+    lines.push(hasBody ? `tool ${tool.name} from ${source} {` : `tool ${tool.name} from ${source}`);
     // Dependencies
     for (const dep of tool.deps) {
         if (dep.kind === "context") {
@@ -922,14 +1318,14 @@ function serializeToolBlock(tool) {
         else if (wire.kind === "constant") {
             // Use quoted form if value contains spaces or special chars, unquoted otherwise
             if (/\s/.test(wire.value) || wire.value === "") {
-                lines.push(`  ${wire.target} = "${wire.value}"`);
+                lines.push(`  .${wire.target} = "${wire.value}"`);
             }
             else {
-                lines.push(`  ${wire.target} = ${wire.value}`);
+                lines.push(`  .${wire.target} = ${wire.value}`);
             }
         }
         else {
-            lines.push(`  ${wire.target} <- ${wire.source}`);
+            lines.push(`  .${wire.target} <- ${wire.source}`);
         }
     }
     if (hasBody)
@@ -946,7 +1342,7 @@ function serializeToolBlock(tool) {
  * This is used to emit `?? handle.path` or `?? pipe:source` for wire
  * `fallbackRef` values.
  */
-function serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle) {
+function serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle, outputHandle) {
     const refTk = ref.instance != null
         ? `${ref.module}:${ref.type}:${ref.field}:${ref.instance}`
         : `${ref.module}:${ref.type}:${ref.field}`;
@@ -977,13 +1373,37 @@ function serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge
             }
         }
         if (actualSourceRef && handleChain.length > 0) {
-            const sourceStr = serializeRef(actualSourceRef, bridge, handleMap, inputHandle, true);
+            const sourceStr = serializeRef(actualSourceRef, bridge, handleMap, inputHandle, outputHandle, true);
             return `${handleChain.join(":")}:${sourceStr}`;
         }
     }
-    return serializeRef(ref, bridge, handleMap, inputHandle, true);
+    return serializeRef(ref, bridge, handleMap, inputHandle, outputHandle, true);
+}
+/**
+ * Serialize a DefineDef into its textual form.
+ *
+ * Delegates to serializeBridgeBlock with a synthetic Bridge, then replaces
+ * the `bridge Define.<name>` header with `define <name>`.
+ */
+function serializeDefineBlock(def) {
+    const syntheticBridge = {
+        kind: "bridge",
+        type: "Define",
+        field: def.name,
+        handles: def.handles,
+        wires: def.wires,
+        arrayIterators: def.arrayIterators,
+        pipeHandles: def.pipeHandles,
+    };
+    const bridgeText = serializeBridgeBlock(syntheticBridge);
+    // Replace "bridge Define.<name>" → "define <name>"
+    return bridgeText.replace(/^bridge Define\.(\w+)/, "define $1");
 }
 function serializeBridgeBlock(bridge) {
+    // ── Passthrough shorthand ───────────────────────────────────────────
+    if (bridge.passthrough) {
+        return `bridge ${bridge.type}.${bridge.field} with ${bridge.passthrough}`;
+    }
     const lines = [];
     // ── Header ──────────────────────────────────────────────────────────
     lines.push(`bridge ${bridge.type}.${bridge.field} {`);
@@ -1002,7 +1422,20 @@ function serializeBridgeBlock(bridge) {
                 break;
             }
             case "input":
-                lines.push(`  with input as ${h.handle}`);
+                if (h.handle === "input") {
+                    lines.push(`  with input`);
+                }
+                else {
+                    lines.push(`  with input as ${h.handle}`);
+                }
+                break;
+            case "output":
+                if (h.handle === "output") {
+                    lines.push(`  with output`);
+                }
+                else {
+                    lines.push(`  with output as ${h.handle}`);
+                }
                 break;
             case "context":
                 lines.push(`  with context as ${h.handle}`);
@@ -1015,31 +1448,28 @@ function serializeBridgeBlock(bridge) {
                     lines.push(`  with const as ${h.handle}`);
                 }
                 break;
+            case "define":
+                lines.push(`  with ${h.name} as ${h.handle}`);
+                break;
         }
     }
     lines.push("");
     // Mark where the wire body starts — everything after this gets 2-space indent
     const wireBodyStart = lines.length;
     // ── Build handle map for reverse resolution ─────────────────────────
-    const { handleMap, inputHandle } = buildHandleMap(bridge);
+    const { handleMap, inputHandle, outputHandle } = buildHandleMap(bridge);
     // ── Pipe fork registry ──────────────────────────────────────────────
-    // Extend handleMap with fork → handle-name entries and build the set of
-    // known fork trunk keys so the wire classifiers below can use it.
     const pipeHandleTrunkKeys = new Set();
     for (const ph of bridge.pipeHandles ?? []) {
         handleMap.set(ph.key, ph.handle);
         pipeHandleTrunkKeys.add(ph.key);
     }
-    // ── Pipe wire detection ───────────────────────────────────────────────────────
-    // Pipe wires are marked pipe:true.  Classify them into two maps:
-    //   toInMap:    forkTrunkKey → wire feeding the fork's input field
-    //   fromOutMap: forkTrunkKey → wire reading the fork's root result
-    // Terminal out-wires (destination is NOT another fork) are chain anchors.
+    // ── Pipe wire detection ─────────────────────────────────────────────
     const refTrunkKey = (ref) => ref.instance != null
         ? `${ref.module}:${ref.type}:${ref.field}:${ref.instance}`
         : `${ref.module}:${ref.type}:${ref.field}`;
-    const toInMap = new Map(); // forkTrunkKey → wire with to = fork's input field
-    const fromOutMap = new Map(); // forkTrunkKey → wire with from = fork root (path:[])
+    const toInMap = new Map();
+    const fromOutMap = new Map();
     const pipeWireSet = new Set();
     for (const w of bridge.wires) {
         if (!("from" in w) || !w.pipe)
@@ -1047,70 +1477,94 @@ function serializeBridgeBlock(bridge) {
         const fw = w;
         pipeWireSet.add(w);
         const toTk = refTrunkKey(fw.to);
-        // In-wire: single-segment path targeting a known pipe fork
         if (fw.to.path.length === 1 && pipeHandleTrunkKeys.has(toTk)) {
             toInMap.set(toTk, fw);
         }
-        // Out-wire: empty path from a known pipe fork
         if (fw.from.path.length === 0 && pipeHandleTrunkKeys.has(refTrunkKey(fw.from))) {
             fromOutMap.set(refTrunkKey(fw.from), fw);
         }
     }
-    // ── Wires ───────────────────────────────────────────────────────────
-    const elementWires = bridge.wires.filter((w) => "from" in w && !!w.from.element);
-    // Exclude pipe wires and element wires from the regular loop
-    const regularWires = bridge.wires.filter((w) => !pipeWireSet.has(w) && (!("from" in w) || !w.from.element));
-    const elementGroups = new Map();
-    for (const w of elementWires) {
-        const parent = w.to.path[0];
-        if (!elementGroups.has(parent))
-            elementGroups.set(parent, []);
-        elementGroups.get(parent).push(w);
+    // ── Group element wires by array-destination field ──────────────────
+    // Pull wires: from.element=true
+    const elementPullWires = bridge.wires.filter((w) => "from" in w && !!w.from.element);
+    // Constant wires: "value" in w && to.element=true
+    const elementConstWires = bridge.wires.filter((w) => "value" in w && !!w.to.element);
+    // Build grouped maps keyed by the array-destination field name (to.path[0])
+    const elementPullGroups = new Map();
+    const elementConstGroups = new Map();
+    for (const w of elementPullWires) {
+        const key = w.to.path[0];
+        if (!elementPullGroups.has(key))
+            elementPullGroups.set(key, []);
+        elementPullGroups.get(key).push(w);
+    }
+    for (const w of elementConstWires) {
+        const key = w.to.path[0];
+        if (!elementConstGroups.has(key))
+            elementConstGroups.set(key, []);
+        elementConstGroups.get(key).push(w);
     }
+    // Union of keys that have any element wire (pull or constant)
+    const allElementKeys = new Set([...elementPullGroups.keys(), ...elementConstGroups.keys()]);
+    // ── Exclude pipe, element-pull, and element-const wires from main loop
+    const regularWires = bridge.wires.filter((w) => !pipeWireSet.has(w) &&
+        (!("from" in w) || !w.from.element) &&
+        (!("value" in w) || !w.to.element));
     const serializedArrays = new Set();
+    // ── Helper: serialize a reference (forward outputHandle) ─────────────
+    const sRef = (ref, isFrom) => serializeRef(ref, bridge, handleMap, inputHandle, outputHandle, isFrom);
+    const sPipeOrRef = (ref) => serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle, outputHandle);
     for (const w of regularWires) {
         // Constant wire
         if ("value" in w) {
-            const toStr = serializeRef(w.to, bridge, handleMap, inputHandle, false);
+            const toStr = sRef(w.to, false);
             lines.push(`${toStr} = "${w.value}"`);
             continue;
         }
-        // Array mapping
+        // Array mapping — emit brace-delimited element block
         const arrayKey = w.to.path.length === 1 ? w.to.path[0] : null;
-        if (arrayKey &&
-            elementGroups.has(arrayKey) &&
-            !serializedArrays.has(arrayKey)) {
+        if (arrayKey && allElementKeys.has(arrayKey) && !serializedArrays.has(arrayKey)) {
             serializedArrays.add(arrayKey);
-            const fromStr = serializeRef(w.from, bridge, handleMap, inputHandle, true) + "[]";
-            const toStr = serializeRef(w.to, bridge, handleMap, inputHandle, false) + "[]";
-            lines.push(`${toStr} <- ${fromStr}`);
-            for (const ew of elementGroups.get(arrayKey)) {
-                const elemFrom = "." + serPath(ew.from.path);
+            const iterName = bridge.arrayIterators?.[arrayKey] ?? "item";
+            const fromStr = sRef(w.from, true) + "[]";
+            const toStr = sRef(w.to, false);
+            lines.push(`${toStr} <- ${fromStr} as ${iterName} {`);
+            // Element constant wires (e.g. .provider = "RENFE")
+            for (const ew of elementConstGroups.get(arrayKey) ?? []) {
+                const fieldPath = ew.to.path.slice(1); // strip arrayKey prefix
+                const elemTo = "." + serPath(fieldPath);
+                lines.push(`  ${elemTo} = "${ew.value}"`);
+            }
+            // Element pull wires (e.g. .name <- iter.title)
+            for (const ew of elementPullGroups.get(arrayKey) ?? []) {
+                const fromPart = ew.from.element
+                    ? iterName + "." + serPath(ew.from.path)
+                    : sRef(ew.from, true);
                 const elemTo = "." + serPath(ew.to.path.slice(1));
-                lines.push(`  ${elemTo} <- ${elemFrom}`);
+                // Handle fallbacks on element pull wires
+                const nfb = "nullFallback" in ew && ew.nullFallback ? ` || ${ew.nullFallback}` : "";
+                const errf = "fallbackRef" in ew && ew.fallbackRef
+                    ? ` ?? ${sPipeOrRef(ew.fallbackRef)}`
+                    : "fallback" in ew && ew.fallback ? ` ?? ${ew.fallback}` : "";
+                lines.push(`  ${elemTo} <- ${fromPart}${nfb}${errf}`);
             }
+            lines.push(`}`);
             continue;
         }
         // Regular wire
-        const fromStr = serializeRef(w.from, bridge, handleMap, inputHandle, true);
-        const toStr = serializeRef(w.to, bridge, handleMap, inputHandle, false);
+        const fromStr = sRef(w.from, true);
+        const toStr = sRef(w.to, false);
         const arrow = w.force ? "<-!" : "<-";
         const nfb = w.nullFallback ? ` || ${w.nullFallback}` : "";
         const errf = w.fallbackRef
-            ? ` ?? ${serializePipeOrRef(w.fallbackRef, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle)}`
+            ? ` ?? ${sPipeOrRef(w.fallbackRef)}`
             : w.fallback ? ` ?? ${w.fallback}` : "";
         lines.push(`${toStr} ${arrow} ${fromStr}${nfb}${errf}`);
     }
     // ── Pipe wires ───────────────────────────────────────────────────────
-    // Find terminal fromOutMap entries — their destination is NOT another
-    // pipe handle's .in. Follow the chain backward to reconstruct:
-    //   dest <- h1:h2:…:source
-    const serializedPipeTrunks = new Set();
     for (const [tk, outWire] of fromOutMap.entries()) {
-        // Non-terminal: this fork's result feeds another fork's input field
         if (pipeHandleTrunkKeys.has(refTrunkKey(outWire.to)))
             continue;
-        // Follow chain backward to collect handle names (outermost-first)
         const handleChain = [];
         let currentTk = tk;
         let actualSourceRef = null;
@@ -1119,18 +1573,15 @@ function serializeBridgeBlock(bridge) {
             const handleName = handleMap.get(currentTk);
             if (!handleName)
                 break;
-            // Token: "handle" when field is "in" (default), otherwise "handle.field"
             const inWire = toInMap.get(currentTk);
             const fieldName = inWire?.to.path[0] ?? "in";
             const token = fieldName === "in" ? handleName : `${handleName}.${fieldName}`;
             handleChain.push(token);
-            serializedPipeTrunks.add(currentTk);
             if (inWire?.force)
                 chainForced = true;
             if (!inWire)
                 break;
             const fromTk = refTrunkKey(inWire.from);
-            // Inner source is another pipe fork root (empty path) → continue chain
             if (inWire.from.path.length === 0 && pipeHandleTrunkKeys.has(fromTk)) {
                 currentTk = fromTk;
             }
@@ -1140,12 +1591,12 @@ function serializeBridgeBlock(bridge) {
             }
         }
         if (actualSourceRef && handleChain.length > 0) {
-            const sourceStr = serializeRef(actualSourceRef, bridge, handleMap, inputHandle, true);
-            const destStr = serializeRef(outWire.to, bridge, handleMap, inputHandle, false);
+            const sourceStr = sRef(actualSourceRef, true);
+            const destStr = sRef(outWire.to, false);
             const arrow = chainForced ? "<-!" : "<-";
             const nfb = outWire.nullFallback ? ` || ${outWire.nullFallback}` : "";
             const errf = outWire.fallbackRef
-                ? ` ?? ${serializePipeOrRef(outWire.fallbackRef, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle)}`
+                ? ` ?? ${sPipeOrRef(outWire.fallbackRef)}`
                 : outWire.fallback ? ` ?? ${outWire.fallback}` : "";
             lines.push(`${destStr} ${arrow} ${handleChain.join(":")}:${sourceStr}${nfb}${errf}`);
         }
@@ -1165,6 +1616,7 @@ function buildHandleMap(bridge) {
     const handleMap = new Map();
     const instanceCounters = new Map();
     let inputHandle;
+    let outputHandle;
     for (const h of bridge.handles) {
         switch (h.kind) {
             case "tool": {
@@ -1190,19 +1642,27 @@ function buildHandleMap(bridge) {
             case "input":
                 inputHandle = h.handle;
                 break;
+            case "output":
+                outputHandle = h.handle;
+                break;
             case "context":
                 handleMap.set(`${SELF_MODULE}:Context:context`, h.handle);
                 break;
             case "const":
                 handleMap.set(`${SELF_MODULE}:Const:const`, h.handle);
                 break;
+            case "define":
+                handleMap.set(`__define_${h.handle}:${bridge.type}:${bridge.field}`, h.handle);
+                break;
         }
     }
-    return { handleMap, inputHandle };
+    return { handleMap, inputHandle, outputHandle };
 }
-function serializeRef(ref, bridge, handleMap, inputHandle, isFrom) {
+function serializeRef(ref, bridge, handleMap, inputHandle, outputHandle, isFrom) {
     if (ref.element) {
-        return "." + serPath(ref.path);
+        // Element refs are only serialized inside brace blocks (using the iterator name).
+        // This path should not be reached in normal serialization.
+        return "item." + serPath(ref.path);
     }
     // Bridge's own trunk (no instance, no element)
     const isBridgeTrunk = ref.module === SELF_MODULE &&
@@ -1213,16 +1673,17 @@ function serializeRef(ref, bridge, handleMap, inputHandle, isFrom) {
     if (isBridgeTrunk) {
         if (isFrom && inputHandle) {
             // From side: use input handle (data comes from args)
-            return inputHandle + "." + serPath(ref.path);
+            return ref.path.length > 0
+                ? inputHandle + "." + serPath(ref.path)
+                : inputHandle;
         }
-        // To side: sub-fields of the bridge's own return type are prefixed with the
-        // bridge field name so `path: ["a"]` serializes as `doubled.a` (not bare "a").
-        // This is needed for bridges whose output type has named sub-fields
-        // (e.g. `bridge Query.doubled` with `doubled.a <- ...`).
-        if (!isFrom && ref.path.length > 0) {
-            return bridge.field + "." + serPath(ref.path);
+        if (!isFrom && outputHandle) {
+            // To side: use output handle
+            return ref.path.length > 0
+                ? outputHandle + "." + serPath(ref.path)
+                : outputHandle;
         }
-        // Bare path (e.g. top-level scalar output, or no-path for the bridge trunk itself)
+        // Fallback (no handle declared — legacy/serializer-only path)
         return serPath(ref.path);
     }
     // Lookup by trunk key
@@ -1231,7 +1692,6 @@ function serializeRef(ref, bridge, handleMap, inputHandle, isFrom) {
         : `${ref.module}:${ref.type}:${ref.field}`;
     const handle = handleMap.get(trunkStr);
     if (handle) {
-        // Empty path — just the handle name (e.g. pipe result = tool root)
         if (ref.path.length === 0)
             return handle;
         return handle + "." + serPath(ref.path);