@stackables/bridge 1.0.2 → 1.1.1

package/README.md

@@ -5,9 +5,15 @@ Wire data between APIs, tools, and fields using `.bridge` files—no resolvers,
 
 ```bash
 npm install @stackables/bridge
-
 ```
 
+> **Developer Preview**  
+> The Bridge v1.x is a public preview and is not recommended for production use.
+>  - Stability: Breaking changes to the .bridge language and TypeScript API will occur frequently.
+>  - Versioning: We follow strict SemVer starting from v2.0.0.
+>
+> Feedback: We are actively looking for use cases. Please share yours in our GitHub Discussions.
+
 ---
 
 ## The Idea
@@ -41,7 +47,7 @@ Access const values in bridges or tools via `with const as c`, then reference as
 
 ### 2. Extend Blocks (`extend`)
 
-Defines the "Where" and the "How." Takes a function (or parent tool) and configures i, giving it a new namet.
+Defines the "Where" and the "How." Takes a function (or parent tool) and configures i, giving it a new name.
 
 ```hcl
 extend <source> as <name>
@@ -67,9 +73,17 @@ bridge <Type.field>
   with input [as <i>]
 
   # Field Mapping
-  <field> <- <source>               # Standard Pull (Lazy)
-  <field> <-! <source>              # Forced Push (Eager/Side-effect)
-  
+  <field> = <json>                  # Constant value
+  <field> <- <source>               # Standard Pull (lazy)
+  <field> <-! <source>              # Forced Push (eager/side-effect)
+
+  # Pipe chain (tool transformation)
+  <field> <- handle:source          # Route source through tool handle
+
+  # Fallbacks
+  <field> <- <source> || <alt> || <alt> # Null-coalesce: use alt if source is null
+  <field> <- <source> ?? <fallback>     # Error-fallback: use fallback if chain throws
+
   # Array Mapping
   <field>[] <- <source>[]
     .<sub_field> <- .<sub_src>      # Relative scoping
@@ -82,16 +96,64 @@ bridge <Type.field>
 
 ### Resiliency
 
-Two layers of fault tolerance prevent a single API failure from crashing the response:
+Each layer handles a different failure mode. They compose freely.
+
+#### Layer 1 — Tool `on error` (execution errors)
+
+Declared inside the `extend` block. Catches any exception thrown by the tool's `fn(input)`. All tools that `extend` this tool inherit the fallback.
+
+```hcl
+extend httpCall as geo
+  baseUrl = "https://nominatim.openstreetmap.org"
+  method = GET
+  path = /search
+  on error = { "lat": 0, "lon": 0 }   # tool-level default
+```
+
+#### Layer 2 — Wire `||` (null / absent values)
 
-1. **Layer 1 — Tool `on error`**: Catches tool execution failures. Child tools inherit this via `extend`.
-2. **Layer 2 — Wire `??` fallback**: Catches any failure in the resolution chain (missing data, network timeout) as a last resort.
+Fires when a source resolves **successfully but returns `null` or `undefined`**. The fallback can be a JSON literal or another source expression (handle path or pipe chain). Multiple `||` alternatives chain left-to-right like `COALESCE`.
 
 ```hcl
+# JSON literal fallback
+lat <- geo.lat || 0.0
+
+# Alternative source fallback
+label <- api.label || backup.label || "unknown"
+
+# Pipe chain as alternative
+textPart <- i.textBody || convert:i.htmlBody || "empty"
+```
+
+#### Layer 3 — Wire `??` (errors and exceptions)
+
+Fires when the **entire resolution chain throws** (network failure, tool down, dependency error). Does not fire on null values — that's `||`'s job. The fallback can be a JSON literal or a source/pipe expression (evaluated lazily, only when the error fires).
+
+```hcl
+# JSON literal error fallback
 lat <- geo.lat ?? 0.0
 
+# Error fallback pulls from another source
+label <- api.label ?? errorHandler:i.fallbackMsg
 ```
 
+#### Full COALESCE — composing all three layers
+
+`||` and `??` compose into a Postgres-style `COALESCE` with an error guard at the end:
+
+```hcl
+# label <- A || B || C || "literal" ?? errorSource
+label <- api.label || tool:api.backup.label || "unknown" ?? tool:const.errorString
+
+# Evaluation order:
+# api.label non-null     → use it immediately
+# api.label null         → try toolIfNeeded(api.backup.label)
+# that null              → "unknown"  (|| json literal always succeeds)
+# any source throws      → toolIfNeeded(const.errorString)  (?? fires last)
+```
+
+Multiple `||` sources desugar to **parallel wires** — all sources are evaluated concurrently and the first that resolves to a non-null value wins. Cheaper/faster sources (like `input` fields) naturally win without any priority hints.
+
 ### Forced Wires (`<-!`)
 
 By default, the engine is **lazy**. Use `<-!` to force execution regardless of demand—perfect for side-effects like analytics, audit logging, or cache warming.
@@ -101,20 +163,19 @@ bridge Mutation.updateUser
   with audit.logger as log
 
   # 'log' runs even if the client doesn't query the 'status' field
-  status <-! log|i.changeData 
-
+  status <-! log:i.changeData
 ```
 
-### The Pipe Operator (`|`)
+### The Pipe Operator (`:`)
 
-Chains data through tools right-to-left: `dest <- tool | source`.
+Routes data right-to-left through one or more tool handles: `dest <- handle:source`.
 
 ```hcl
-# i.rawData -> normalize -> transform -> result
-result <- transform|normalize|i.rawData 
+# i.rawData → normalize → transform → result
+result <- transform:normalize:i.rawData
 ```
 
-Full example with a tool with 2 input parameters.
+Full example with a tool that has 2 input parameters:
 
 ```hcl
 extend currencyConverter as convert
@@ -126,26 +187,27 @@ bridge Query.price
 
 c.currency <- i.currency   # overrides the default per request
 
-# Safe to use repeatedly
-itemPrice <- c|i.itemPrice
-totalPrice <- c|i.totalPrice
+# Safe to use repeatedly — each is an independent tool call
+itemPrice  <- c:i.itemPrice
+totalPrice <- c:i.totalPrice
 ```
 
 ---
 
 ## Syntax Reference
 
-| Operator | Type | Behavior | Notes |
-| --- | --- | --- | --- |
-| **`=`** | **Constant** | Sets a static value. | |
-| **`<-`** | **Wire** | Pulls data from a source at runtime. | |
-| **`<-!`** | **Force** | Eagerly schedules a tool (for side-effects). | |
-| **`\|`** | **Pipe** | Chains data through tools right-to-left. | |
-| **`??`** | **Fallback** | Wire-level default if the resolution chain fails. | |
-| **`on error`** | **Tool Fallback** | Returns a default if the tool's `fn(input)` throws. | |
-| **`extend`** | **Tool Definition** | Configures a function or extends a parent tool. | |
-| **`const`** | **Named Value** | Declares reusable JSON constants. | |
-| **`[] <- []`** | **Map** | Iterates over arrays to create nested wire contexts. | |
+| Operator | Type | Behavior |
+| --- | --- | --- |
+| **`=`** | Constant | Sets a static value. |
+| **`<-`** | Wire | Pulls data from a source at runtime. |
+| **`<-!`** | Force | Eagerly schedules a tool (for side-effects). |
+| **`:`** | Pipe | Chains data through tools right-to-left. |
+| **`\|\|`** | Null-coalesce | Next alternative if current source is `null`/`undefined`. Fires on absent values, not errors. |
+| **`??`** | Error-fallback | Alternative used when the resolution chain **throws**. Fires on errors, not null values. |
+| **`on error`** | Tool Fallback | Returns a default if the tool's `fn(input)` throws. |
+| **`extend`** | Tool Definition | Configures a function or extends a parent tool. |
+| **`const`** | Named Value | Declares reusable JSON constants. |
+| **`[] <- []`** | Map | Iterates over arrays to create nested wire contexts. |
 
 ---
 
@@ -209,8 +271,8 @@ bridge Query.format
   with std.lowerCase as lo
   with input as i
 
-upper <- up|i.text
-lower <- lo|i.text
+upper <- up:i.text
+lower <- lo:i.text
 ```
 
 Use an `extend` block when you need to configure defaults:
@@ -224,7 +286,7 @@ bridge Query.onlyResult
   with someApi as api
   with input as i
 
-value <- pf|api.items
+value <- pf:api.items
 ```
 
 ### Adding Custom Tools

package/build/ExecutionTree.d.ts

@@ -43,7 +43,9 @@ export declare class ExecutionTree {
     push(args: Record<string, any>): void;
     /** Eagerly schedule tools targeted by forced (<-!) wires. */
     executeForced(): void;
-    /** Resolve a set of matched wires — constants win, then pull from sources.\n   *  If a wire has a `fallback` value and all sources reject, return the fallback. */
+    /** Resolve a set of matched wires — constants win, then pull from sources.
+     *  `||` (nullFallback): fires when all sources resolve to null/undefined.
+     *  `??` (fallback/fallbackRef): fires when all sources reject (throw/error). */
     private resolveWires;
     response(ipath: Path, array: boolean): Promise<any>;
 }

package/build/ExecutionTree.js

@@ -317,7 +317,36 @@ export class ExecutionTree {
         return result;
     }
     async pull(refs) {
-        return Promise.any(refs.map((ref) => this.pullSingle(ref)));
+        if (refs.length === 1)
+            return this.pullSingle(refs[0]);
+        // Multiple sources: all start in parallel.
+        // Return the first that resolves to a non-null/undefined value.
+        // If all resolve to null/undefined → resolve undefined (lets || fire).
+        // If all reject → throw AggregateError (lets ?? fire).
+        return new Promise((resolve, reject) => {
+            let remaining = refs.length;
+            let hasValue = false;
+            const errors = [];
+            const settle = () => {
+                if (--remaining === 0 && !hasValue) {
+                    if (errors.length === refs.length) {
+                        reject(new AggregateError(errors, "All sources failed"));
+                    }
+                    else {
+                        resolve(undefined); // all resolved to null/undefined
+                    }
+                }
+            };
+            for (const ref of refs) {
+                this.pullSingle(ref).then((value) => {
+                    if (!hasValue && value != null) {
+                        hasValue = true;
+                        resolve(value);
+                    }
+                    settle();
+                }, (err) => { errors.push(err); settle(); });
+            }
+        });
     }
     push(args) {
         this.state[trunkKey(this.trunk)] = args;
@@ -340,24 +369,46 @@ export class ExecutionTree {
             Promise.resolve(this.state[key]).catch(() => { });
         }
     }
-    /** Resolve a set of matched wires — constants win, then pull from sources.\n   *  If a wire has a `fallback` value and all sources reject, return the fallback. */
+    /** Resolve a set of matched wires — constants win, then pull from sources.
+     *  `||` (nullFallback): fires when all sources resolve to null/undefined.
+     *  `??` (fallback/fallbackRef): fires when all sources reject (throw/error). */
     resolveWires(wires) {
         const constant = wires.find((w) => "value" in w);
         if (constant)
             return Promise.resolve(constant.value);
         const pulls = wires.filter((w) => "from" in w);
-        // Collect any fallback value from the wires (first one wins)
-        const fallbackWire = pulls.find((w) => w.fallback != null);
-        const result = this.pull(pulls.map((w) => w.from));
-        if (!fallbackWire)
+        // First wire with each fallback kind wins
+        const nullFallbackWire = pulls.find((w) => w.nullFallback != null);
+        // Error fallback: JSON literal (`fallback`) or source/pipe reference (`fallbackRef`)
+        const errorFallbackWire = pulls.find((w) => w.fallback != null || w.fallbackRef != null);
+        let result = this.pull(pulls.map((w) => w.from));
+        // || null-guard: fires when resolution succeeds but value is null/undefined
+        if (nullFallbackWire) {
+            result = result.then((value) => {
+                if (value != null)
+                    return value;
+                try {
+                    return JSON.parse(nullFallbackWire.nullFallback);
+                }
+                catch {
+                    return nullFallbackWire.nullFallback;
+                }
+            });
+        }
+        // ?? error-guard: fires when resolution throws
+        if (!errorFallbackWire)
             return result;
         return result.catch(() => {
+            // Source/pipe reference: schedule it lazily and pull the result
+            if (errorFallbackWire.fallbackRef) {
+                return this.pullSingle(errorFallbackWire.fallbackRef);
+            }
+            // JSON literal
             try {
-                return JSON.parse(fallbackWire.fallback);
+                return JSON.parse(errorFallbackWire.fallback);
             }
             catch {
-                // Not valid JSON — return as raw string
-                return fallbackWire.fallback;
+                return errorFallbackWire.fallback;
             }
         });
     }

package/build/bridge-format.js

@@ -75,6 +75,15 @@ export function parseBridge(text) {
     return instructions;
 }
 // ── Bridge block parser ─────────────────────────────────────────────────────
+/**
+ * Returns true when the token looks like a JSON literal rather than a
+ * source reference (dotted path or pipe chain).
+ * JSON start chars: `"`, `{`, `[`, digit, `-` + digit, `true`, `false`, `null`.
+ */
+function isJsonLiteral(s) {
+    return /^["\{\[\d]/.test(s) || /^-\d/.test(s) ||
+        s === "true" || s === "false" || s === "null";
+}
 function parseBridgeBlock(block, lineOffset) {
     const lines = block.split("\n").map((l) => l.trimEnd());
     const instructions = [];
@@ -121,6 +130,60 @@ function parseBridgeBlock(block, lineOffset) {
      *  fork instances that can never collide with regular handle instances. */
     let nextForkSeq = 0;
     const pipeHandleEntries = [];
+    /**
+     * Parse a source expression (`handle.path` or `h1:h2:source`) into bridge
+     * wires, returning the terminal NodeRef.
+     *
+     * For pipe chains: pushes the intermediate `.in <- prev` wires and registers
+     * the fork instances, then returns the fork-root ref. The caller is
+     * responsible for pushing the TERMINAL wire (forkRoot → target).
+     *
+     * For simple refs: returns the resolved NodeRef directly (no wires pushed).
+     *
+     * @param forceOnOutermost  When true, marks the outermost intermediate pipe
+     *                          wire with `force: true` (used for `<-!`).
+     */
+    function buildSourceExpr(sourceStr, lineNum, forceOnOutermost) {
+        const parts = sourceStr.split(":");
+        if (parts.length === 1) {
+            return resolveAddress(sourceStr, handleRes, bridgeType, bridgeField);
+        }
+        // Pipe chain
+        const actualSource = parts[parts.length - 1];
+        const tokenChain = parts.slice(0, -1);
+        const parseToken = (t) => {
+            const dot = t.indexOf(".");
+            return dot === -1
+                ? { handleName: t, fieldName: "in" }
+                : { handleName: t.substring(0, dot), fieldName: t.substring(dot + 1) };
+        };
+        for (const tok of tokenChain) {
+            const { handleName } = parseToken(tok);
+            if (!handleRes.has(handleName)) {
+                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);
+        const reversedTokens = [...tokenChain].reverse();
+        for (let idx = 0; idx < reversedTokens.length; idx++) {
+            const tok = reversedTokens[idx];
+            const { handleName, fieldName } = parseToken(tok);
+            const res = handleRes.get(handleName);
+            const forkInstance = 100000 + nextForkSeq++;
+            const forkKey = `${res.module}:${res.type}:${res.field}:${forkInstance}`;
+            pipeHandleEntries.push({
+                key: forkKey,
+                handle: handleName,
+                baseTrunk: { module: res.module, type: res.type, field: res.field, instance: res.instance },
+            });
+            const forkInRef = { module: res.module, type: res.type, field: res.field, instance: forkInstance, path: parsePath(fieldName) };
+            const forkRootRef = { module: res.module, type: res.type, field: res.field, instance: forkInstance, path: [] };
+            const isOutermost = idx === reversedTokens.length - 1;
+            wires.push({ from: prevOutRef, to: forkInRef, pipe: true, ...(forceOnOutermost && isOutermost ? { force: true } : {}) });
+            prevOutRef = forkRootRef;
+        }
+        return prevOutRef; // fork-root ref
+    }
     for (let i = bodyStartIndex; i < lines.length; i++) {
         const raw = lines[i];
         const line = raw.trim();
@@ -163,80 +226,105 @@ function parseBridgeBlock(block, lineOffset) {
             wires.push({ value, to: toRef });
             continue;
         }
-        // Wire: target <- source  OR  target <-! source (forced)
-        // Optional fallback: target <- source ?? <json_value>
-        const arrowMatch = line.match(/^(\S+)\s*<-(!?)\s*(\S+(?:\|\S+)*)(?:\s*\?\?\s*(.+))?$/);
+        // ── 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, sourceStr, fallbackRaw] = arrowMatch;
+            const [, targetStr, forceFlag, rhs] = arrowMatch;
             const force = forceFlag === "!";
-            const fallback = fallbackRaw?.trim();
-            // Array mapping: target[] <- source[]
-            if (targetStr.endsWith("[]") && sourceStr.endsWith("[]")) {
+            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 = sourceStr.slice(0, -2);
+                const fromClean = rhsTrimmed.slice(0, -2);
                 const fromRef = resolveAddress(fromClean, handleRes, bridgeType, bridgeField);
                 const toRef = resolveAddress(toClean, handleRes, bridgeType, bridgeField);
                 wires.push({ from: fromRef, to: toRef });
                 currentArrayToPath = toRef.path;
                 continue;
             }
-            // Pipe chain: target <- tok1|tok2|...|source
-            // Each token is either "handle" (input field defaults to "in") or
-            // "handle.field" (explicit input field name).
-            // Every token creates an INDEPENDENT fork — a fresh tool invocation with
-            // its own instance number — so repeated use of the same handle produces
-            // separate calls.
-            // Execution order: source → tokN → … → tok1 → target (right-to-left).
-            const parts = sourceStr.split("|");
-            if (parts.length > 1) {
-                const actualSource = parts[parts.length - 1];
-                const tokenChain = parts.slice(0, -1); // [tok1, …, tokN] outermost→innermost
-                /** Parse "handle" or "handle.field" → {handleName, fieldName} */
-                const parseToken = (t) => {
-                    const dot = t.indexOf(".");
-                    return dot === -1
-                        ? { handleName: t, fieldName: "in" }
-                        : { handleName: t.substring(0, dot), fieldName: t.substring(dot + 1) };
-                };
-                for (const tok of tokenChain) {
-                    const { handleName } = parseToken(tok);
-                    if (!handleRes.has(handleName)) {
-                        throw new Error(`Line ${ln(i)}: Undeclared handle in pipe: "${handleName}". Add 'with <tool> as ${handleName}' to the bridge header.`);
-                    }
+            // ── Strip the ?? tail (last " ?? " wins in case source contains " ?? ")
+            let exprCore = rhsTrimmed;
+            let fallback;
+            let fallbackRefStr;
+            const qqIdx = rhsTrimmed.lastIndexOf(" ?? ");
+            if (qqIdx !== -1) {
+                exprCore = rhsTrimmed.slice(0, qqIdx).trim();
+                const tail = rhsTrimmed.slice(qqIdx + 4).trim();
+                if (isJsonLiteral(tail)) {
+                    fallback = tail;
                 }
-                let prevOutRef = resolveAddress(actualSource, handleRes, bridgeType, bridgeField);
-                const reversedTokens = [...tokenChain].reverse();
-                for (let idx = 0; idx < reversedTokens.length; idx++) {
-                    const tok = reversedTokens[idx];
-                    const { handleName, fieldName } = parseToken(tok);
-                    const res = handleRes.get(handleName);
-                    // Allocate a unique fork instance (100000+ avoids collision with
-                    // regular instances which start at 1).
-                    const forkInstance = 100000 + nextForkSeq++;
-                    const forkKey = `${res.module}:${res.type}:${res.field}:${forkInstance}`;
-                    pipeHandleEntries.push({
-                        key: forkKey,
-                        handle: handleName,
-                        baseTrunk: { module: res.module, type: res.type, field: res.field, instance: res.instance },
-                    });
-                    const forkInRef = { module: res.module, type: res.type, field: res.field, instance: forkInstance, path: parsePath(fieldName) };
-                    const forkRootRef = { module: res.module, type: res.type, field: res.field, instance: forkInstance, path: [] };
-                    const isOutermost = idx === reversedTokens.length - 1;
-                    wires.push({ from: prevOutRef, to: forkInRef, pipe: true, ...(force && isOutermost ? { force: true } : {}) });
-                    prevOutRef = forkRootRef;
+                else {
+                    fallbackRefStr = tail;
                 }
-                const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField);
-                wires.push({ from: prevOutRef, to: toRef, pipe: true, ...(fallback ? { fallback } : {}) });
-                continue;
             }
-            const fromRef = resolveAddress(sourceStr, handleRes, bridgeType, bridgeField);
+            // ── Split on " || " to get coalesce chain parts
+            const orParts = exprCore.split(" || ").map((s) => s.trim());
+            // Last part may be a JSON literal → becomes nullFallback on the last source wire
+            let nullFallback;
+            let sourceParts = orParts;
+            if (orParts.length > 1 && isJsonLiteral(orParts[orParts.length - 1])) {
+                nullFallback = orParts[orParts.length - 1];
+                sourceParts = orParts.slice(0, -1);
+            }
+            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);
-            wires.push({
-                from: fromRef,
-                to: toRef,
-                ...(force ? { force: true } : {}),
-                ...(fallback ? { fallback } : {}),
-            });
+            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 {
+                    wires.push({
+                        from: termRef,
+                        to: toRef,
+                        ...(force && isFirst ? { force: true } : {}),
+                        ...lastAttrs,
+                    });
+                }
+            }
+            // 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}`);
@@ -796,6 +884,53 @@ function serializeToolBlock(tool) {
     }
     return lines.join("\n");
 }
+/**
+ * Serialize a fallback NodeRef as a human-readable source string.
+ *
+ * If the ref is a pipe-fork root, reconstructs the pipe chain by walking
+ * the `toInMap` backward (same logic as the main pipe serializer).
+ * Otherwise delegates to `serializeRef`.
+ *
+ * This is used to emit `?? handle.path` or `?? pipe:source` for wire
+ * `fallbackRef` values.
+ */
+function serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle) {
+    const refTk = ref.instance != null
+        ? `${ref.module}:${ref.type}:${ref.field}:${ref.instance}`
+        : `${ref.module}:${ref.type}:${ref.field}`;
+    if (ref.path.length === 0 && pipeHandleTrunkKeys.has(refTk)) {
+        // Pipe-fork root — walk the chain to reconstruct `pipe:source` notation
+        const handleChain = [];
+        let currentTk = refTk;
+        let actualSourceRef = null;
+        for (;;) {
+            const handleName = handleMap.get(currentTk);
+            if (!handleName)
+                break;
+            const inWire = toInMap.get(currentTk);
+            const fieldName = inWire?.to.path[0] ?? "in";
+            const token = fieldName === "in" ? handleName : `${handleName}.${fieldName}`;
+            handleChain.push(token);
+            if (!inWire)
+                break;
+            const fromTk = inWire.from.instance != null
+                ? `${inWire.from.module}:${inWire.from.type}:${inWire.from.field}:${inWire.from.instance}`
+                : `${inWire.from.module}:${inWire.from.type}:${inWire.from.field}`;
+            if (inWire.from.path.length === 0 && pipeHandleTrunkKeys.has(fromTk)) {
+                currentTk = fromTk;
+            }
+            else {
+                actualSourceRef = inWire.from;
+                break;
+            }
+        }
+        if (actualSourceRef && handleChain.length > 0) {
+            const sourceStr = serializeRef(actualSourceRef, bridge, handleMap, inputHandle, true);
+            return `${handleChain.join(":")}:${sourceStr}`;
+        }
+    }
+    return serializeRef(ref, bridge, handleMap, inputHandle, true);
+}
 function serializeBridgeBlock(bridge) {
     const lines = [];
     // ── Header ──────────────────────────────────────────────────────────
@@ -906,13 +1041,16 @@ function serializeBridgeBlock(bridge) {
         const fromStr = serializeRef(w.from, bridge, handleMap, inputHandle, true);
         const toStr = serializeRef(w.to, bridge, handleMap, inputHandle, false);
         const arrow = w.force ? "<-!" : "<-";
-        const fb = w.fallback ? ` ?? ${w.fallback}` : "";
-        lines.push(`${toStr} ${arrow} ${fromStr}${fb}`);
+        const nfb = w.nullFallback ? ` || ${w.nullFallback}` : "";
+        const errf = w.fallbackRef
+            ? ` ?? ${serializePipeOrRef(w.fallbackRef, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle)}`
+            : 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
+    //   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
@@ -951,8 +1089,11 @@ function serializeBridgeBlock(bridge) {
             const sourceStr = serializeRef(actualSourceRef, bridge, handleMap, inputHandle, true);
             const destStr = serializeRef(outWire.to, bridge, handleMap, inputHandle, false);
             const arrow = chainForced ? "<-!" : "<-";
-            const fb = outWire.fallback ? ` ?? ${outWire.fallback}` : "";
-            lines.push(`${destStr} ${arrow} ${handleChain.join("|")}|${sourceStr}${fb}`);
+            const nfb = outWire.nullFallback ? ` || ${outWire.nullFallback}` : "";
+            const errf = outWire.fallbackRef
+                ? ` ?? ${serializePipeOrRef(outWire.fallbackRef, pipeHandleTrunkKeys, toInMap, handleMap, bridge, inputHandle)}`
+                : outWire.fallback ? ` ?? ${outWire.fallback}` : "";
+            lines.push(`${destStr} ${arrow} ${handleChain.join(":")}:${sourceStr}${nfb}${errf}`);
         }
     }
     return lines.join("\n");

package/build/types.d.ts

@@ -25,7 +25,7 @@ export type NodeRef = {
  *
  * Constant wires (`=`) set a fixed value on the target.
  * Pull wires (`<-`) resolve the source at runtime.
- * Pipe wires (`pipe: true`) are generated by the `<- h1|h2|source` shorthand
+ * Pipe wires (`pipe: true`) are generated by the `<- h1:h2:source` shorthand
  * and route data through declared tool handles; the serializer collapses them
  * back to pipe notation.
  */
@@ -34,7 +34,9 @@ export type Wire = {
     to: NodeRef;
     pipe?: true;
     force?: true;
+    nullFallback?: string;
     fallback?: string;
+    fallbackRef?: NodeRef;
 } | {
     value: string;
     to: NodeRef;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Declarative dataflow for GraphQL",
   "main": "./build/index.js",
   "type": "module",