@stackables/bridge-core 0.0.1 → 1.0.1

package/README.md

@@ -0,0 +1,55 @@
+[![github](https://img.shields.io/badge/github-stackables/bridge-blue?logo=github)](https://github.com/stackables/bridge)
+
+# The Bridge Runtime
+
+The lightweight runtime engine for [The Bridge](https://github.com/stackables/bridge).
+
+This is **The Engine** — it takes pre-compiled bridge instructions (a JSON AST) and executes them. No parser, no GraphQL, no heavy dependencies. If you're deploying to a Cloudflare Worker, a Vercel Edge function, or any environment where bundle size matters, this is the package you want in production.
+
+## Installing
+
+```bash
+npm install @stackables/bridge-core
+```
+
+## When to Use This
+
+The most common pattern is the **Ahead-of-Time (AOT) workflow**: compile your `.bridge` files to JSON during CI/CD, then ship only the instructions + this engine to production. The parser and its dependencies never touch your production bundle.
+
+```ts
+import { executeBridge } from "@stackables/bridge-core";
+import instructions from "./compiled-bridge.json" assert { type: "json" };
+
+const { data } = await executeBridge({
+  instructions,
+  operation: "Query.searchTrains",
+  input: { from: "Bern", to: "Zürich" },
+});
+
+console.log(data);
+```
+
+## Options
+
+| Option         | What it does                                             |
+| -------------- | -------------------------------------------------------- |
+| `instructions` | Pre-compiled bridge instructions (from the compiler)     |
+| `operation`    | Which bridge to run, e.g. `"Query.myField"`              |
+| `input`        | Input arguments — like GraphQL field args                |
+| `tools`        | Your custom tool functions (merged with built-in `std`)  |
+| `context`      | Shared data available via `with context` in bridge files |
+| `trace`        | Tool-call tracing: `"off"`, `"basic"`, or `"full"`       |
+| `logger`       | Plug in pino, winston, console — whatever you use        |
+| `signal`       | Pass an `AbortSignal` to cancel execution mid-flight     |
+
+Returns `{ data, traces }`.
+
+## Part of the Bridge Ecosystem
+
+| Package                                                                                    | What it does                                                                 |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| [`@stackables/bridge`](https://www.npmjs.com/package/@stackables/bridge)                   | **The All-in-One** — everything in a single install                          |
+| [`@stackables/bridge-compiler`](https://www.npmjs.com/package/@stackables/bridge-compiler) | **The Parser** — turns `.bridge` text into the instructions this engine runs |
+| [`@stackables/bridge-graphql`](https://www.npmjs.com/package/@stackables/bridge-graphql)   | **The Adapter** — wires bridges into a GraphQL schema                        |
+| [`@stackables/bridge-stdlib`](https://www.npmjs.com/package/@stackables/bridge-stdlib)     | **The Standard Library** — httpCall, strings, arrays, and more               |
+| [`@stackables/bridge-types`](https://www.npmjs.com/package/@stackables/bridge-types)       | **Shared Types** — `ToolCallFn`, `ToolMap`, `CacheStore`                     |

package/build/{ExecutionTree.d.ts → bridge-core/src/ExecutionTree.d.ts}

@@ -1,4 +1,4 @@
-import type { Bridge, Instruction, NodeRef, ToolMap, Wire } from "./types.ts";
+import type { Bridge, BridgeDocument, ToolMap } from "./types.ts";
 /** Fatal panic error — bypasses all error boundaries (`?.` and `catch`). */
 export declare class BridgePanicError extends Error {
     constructor(message: string);
@@ -7,6 +7,8 @@ export declare class BridgePanicError extends Error {
 export declare class BridgeAbortError extends Error {
     constructor(message?: string);
 }
+/** Maximum shadow-tree nesting depth before a BridgePanicError is thrown. */
+export declare const MAX_EXECUTION_DEPTH = 30;
 /**
  * Structured logger interface for Bridge engine events.
  * Accepts any compatible logger: pino, winston, bunyan, `console`, etc.
@@ -74,7 +76,7 @@ export declare class TraceCollector {
 }
 export declare class ExecutionTree {
     trunk: Trunk;
-    private instructions;
+    private document;
     private context?;
     private parent?;
     state: Record<string, any>;
@@ -82,6 +84,12 @@ export declare class ExecutionTree {
     private toolDepCache;
     private toolDefCache;
     private pipeHandleMap;
+    /**
+     * Maps trunk keys to `@version` strings from handle bindings.
+     * Populated in the constructor so `schedule()` can prefer versioned
+     * tool lookups (e.g. `std.str.toLowerCase@999.1`) over the default.
+     */
+    private handleVersionMap;
     /** Promise that resolves when all critical `force` handles have settled. */
     private forcedExecution?;
     /** Shared trace collector — present only when tracing is enabled. */
@@ -91,7 +99,9 @@ export declare class ExecutionTree {
     /** External abort signal — cancels execution when triggered. */
     signal?: AbortSignal;
     private toolFns?;
-    constructor(trunk: Trunk, instructions: Instruction[], toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
+    /** Shadow-tree nesting depth (0 for root). */
+    private depth;
+    constructor(trunk: Trunk, document: BridgeDocument, toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
     /** Derive tool name from a trunk */
     private getToolName;
     /** Deep-lookup a tool function by dotted name (e.g. "std.str.toUpperCase").
@@ -105,7 +115,7 @@ export declare class ExecutionTree {
     private resolveToolSource;
     /** Call a tool dependency (cached per request) */
     private resolveToolDep;
-    schedule(target: Trunk): any;
+    schedule(target: Trunk, pullChain?: Set<string>): any;
     /**
      * Invoke a tool function, recording both an OpenTelemetry span and (when
      * tracing is enabled) a ToolTrace entry.  All three tool-call sites in the
@@ -116,15 +126,6 @@ export declare class ExecutionTree {
     /** Returns collected traces (empty array when tracing is disabled). */
     getTraces(): ToolTrace[];
     private pullSingle;
-    pull(refs: NodeRef[]): Promise<any>;
-    /**
-     * Safe execution pull: wraps individual safe-flagged pulls in try/catch.
-     * Wires with `safe: true` swallow errors and return undefined.
-     * Non-safe wires propagate errors normally.
-     */
-    pullSafe(pulls: Extract<Wire, {
-        from: NodeRef;
-    }>[]): Promise<any>;
     push(args: Record<string, any>): void;
     /** Store the aggregated promise for critical forced handles so
      *  `response()` can await it exactly once per bridge execution. */

package/build/bridge-core/src/ExecutionTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../../../src/ExecutionTree.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,MAAM,EACN,cAAc,EAMd,OAAO,EAER,MAAM,YAAY,CAAC;AAGpB,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,2EAA2E;AAC3E,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAAyC;CAI7D;AAOD,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAwBtC;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CAClC;AAED,gFAAgF;AAChF,UAAU,IAAI;IACZ,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,KAAK,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA0ChF;;;yDAGyD;AACzD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAElD,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG;IACtB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,yDAAyD;IACzD,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,yEAAyE;AACzE,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAM;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,KAAK,GAAE,OAAO,GAAG,MAAe;IAI5C,iDAAiD;IACjD,GAAG,IAAI,MAAM;IAIb,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI9B,kEAAkE;IAClE,KAAK,CAAC,IAAI,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5B,MAAM,CAAC,EAAE,GAAG,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,SAAS;CAuBd;AAwCD,qBAAa,aAAa;IA2Bf,KAAK,EAAE,KAAK;IACnB,OAAO,CAAC,QAAQ;IAEhB,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,MAAM,CAAC;IA9BjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;IAChC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,CAAC,YAAY,CAAwC;IAC5D,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,aAAa,CAEP;IACd;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,4EAA4E;IAC5E,OAAO,CAAC,eAAe,CAAC,CAAgB;IACxC,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,8CAA8C;IAC9C,OAAO,CAAC,KAAK,CAAS;gBAGb,KAAK,EAAE,KAAK,EACX,QAAQ,EAAE,cAAc,EAChC,OAAO,CAAC,EAAE,OAAO,EACT,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAA,EAC7B,MAAM,CAAC,EAAE,aAAa,YAAA;IAiEhC,oCAAoC;IACpC,OAAO,CAAC,WAAW;IAKnB;uGACmG;IACnG,OAAO,CAAC,YAAY;IA2DpB,oEAAoE;IACpE,OAAO,CAAC,oBAAoB;IA8D5B,mEAAmE;YACrD,gBAAgB;IA0B9B,2EAA2E;YAC7D,iBAAiB;IA2C/B,kDAAkD;IAClD,OAAO,CAAC,cAAc;IAgCtB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG;IAgKrD;;;;OAIG;YACW,QAAQ;IAsFtB,MAAM,IAAI,aAAa;IAcvB,uEAAuE;IACvE,SAAS,IAAI,SAAS,EAAE;YAIV,UAAU;IAqFxB,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAI9B;uEACmE;IACnE,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI1C,6DAA6D;IAC7D,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;IAI/C;;;;;;;;;OASG;IACH,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE;IA6B/B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,YAAY;IAuJ1B;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBtE;;;;;;;;OAQG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAgI3D;;;;;;;;OAQG;YACW,kBAAkB;IAmG1B,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAsIzD;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;CAyB7B"}

package/build/{ExecutionTree.js → bridge-core/src/ExecutionTree.js}

@@ -20,6 +20,8 @@ export class BridgeAbortError extends Error {
 const CONTINUE_SYM = Symbol.for("BRIDGE_CONTINUE");
 /** Sentinel for `break` — halt array iteration */
 const BREAK_SYM = Symbol.for("BRIDGE_BREAK");
+/** Maximum shadow-tree nesting depth before a BridgePanicError is thrown. */
+export const MAX_EXECUTION_DEPTH = 30;
 const otelTracer = trace.getTracer("@stackables/bridge");
 const otelMeter = metrics.getMeter("@stackables/bridge");
 const toolCallCounter = otelMeter.createCounter("bridge.tool.calls", {
@@ -154,7 +156,7 @@ function setNested(obj, path, value) {
 }
 export class ExecutionTree {
     trunk;
-    instructions;
+    document;
     context;
     parent;
     state = {};
@@ -162,6 +164,12 @@ export class ExecutionTree {
     toolDepCache = new Map();
     toolDefCache = new Map();
     pipeHandleMap;
+    /**
+     * Maps trunk keys to `@version` strings from handle bindings.
+     * Populated in the constructor so `schedule()` can prefer versioned
+     * tool lookups (e.g. `std.str.toLowerCase@999.1`) over the default.
+     */
+    handleVersionMap = new Map();
     /** Promise that resolves when all critical `force` handles have settled. */
     forcedExecution;
     /** Shared trace collector — present only when tracing is enabled. */
@@ -171,16 +179,52 @@ export class ExecutionTree {
     /** External abort signal — cancels execution when triggered. */
     signal;
     toolFns;
-    constructor(trunk, instructions, toolFns, context, parent) {
+    /** Shadow-tree nesting depth (0 for root). */
+    depth;
+    constructor(trunk, document, toolFns, context, parent) {
         this.trunk = trunk;
-        this.instructions = instructions;
+        this.document = document;
         this.context = context;
         this.parent = parent;
+        this.depth = parent ? parent.depth + 1 : 0;
+        if (this.depth > MAX_EXECUTION_DEPTH) {
+            throw new BridgePanicError(`Maximum execution depth exceeded (${this.depth}) at ${trunkKey(trunk)}. Check for infinite recursion or circular array mappings.`);
+        }
         this.toolFns = { internal, ...(toolFns ?? {}) };
+        const instructions = document.instructions;
         this.bridge = instructions.find((i) => i.kind === "bridge" && i.type === trunk.type && i.field === trunk.field);
         if (this.bridge?.pipeHandles) {
             this.pipeHandleMap = new Map(this.bridge.pipeHandles.map((ph) => [ph.key, ph]));
         }
+        // Build handle→version map from bridge handle bindings
+        if (this.bridge) {
+            const instanceCounters = new Map();
+            for (const h of this.bridge.handles) {
+                if (h.kind !== "tool")
+                    continue;
+                const name = h.name;
+                const lastDot = name.lastIndexOf(".");
+                let module, field, counterKey, type;
+                if (lastDot !== -1) {
+                    module = name.substring(0, lastDot);
+                    field = name.substring(lastDot + 1);
+                    counterKey = `${module}:${field}`;
+                    type = this.trunk.type;
+                }
+                else {
+                    module = SELF_MODULE;
+                    field = name;
+                    counterKey = `Tools:${name}`;
+                    type = "Tools";
+                }
+                const instance = (instanceCounters.get(counterKey) ?? 0) + 1;
+                instanceCounters.set(counterKey, instance);
+                if (h.version) {
+                    const key = trunkKey({ module, type, field, instance });
+                    this.handleVersionMap.set(key, h.version);
+                }
+            }
+        }
         if (context) {
             this.state[trunkKey({ module: SELF_MODULE, type: "Context", field: "context" })] = context;
         }
@@ -221,7 +265,35 @@ export class ExecutionTree {
                 return current;
             // Fall back to flat key (e.g. "hereapi.geocode" as a literal property name)
             const flat = this.toolFns?.[name];
-            return typeof flat === "function" ? flat : undefined;
+            if (typeof flat === "function")
+                return flat;
+            // Try versioned namespace keys (e.g. "std.str@999.1" → { toLowerCase })
+            // For "std.str.toLowerCase@999.1", check:
+            //   toolFns["std.str@999.1"]?.toLowerCase
+            //   toolFns["std@999.1"]?.str?.toLowerCase
+            const atIdx = name.lastIndexOf("@");
+            if (atIdx > 0) {
+                const baseName = name.substring(0, atIdx);
+                const version = name.substring(atIdx + 1);
+                const nameParts = baseName.split(".");
+                for (let i = nameParts.length - 1; i >= 1; i--) {
+                    const nsKey = nameParts.slice(0, i).join(".") + "@" + version;
+                    const remainder = nameParts.slice(i);
+                    let ns = this.toolFns?.[nsKey];
+                    if (ns != null && typeof ns === "object") {
+                        for (const part of remainder) {
+                            if (ns == null || typeof ns !== "object") {
+                                ns = undefined;
+                                break;
+                            }
+                            ns = ns[part];
+                        }
+                        if (typeof ns === "function")
+                            return ns;
+                    }
+                }
+            }
+            return undefined;
         }
         // Try root level first
         const fn = this.toolFns?.[name];
@@ -239,7 +311,7 @@ export class ExecutionTree {
     resolveToolDefByName(name) {
         if (this.toolDefCache.has(name))
             return this.toolDefCache.get(name) ?? undefined;
-        const toolDefs = this.instructions.filter((i) => i.kind === "tool");
+        const toolDefs = this.document.instructions.filter((i) => i.kind === "tool");
         const base = toolDefs.find((t) => t.name === name);
         if (!base) {
             this.toolDefCache.set(name, null);
@@ -322,7 +394,6 @@ export class ExecutionTree {
         let value;
         if (dep.kind === "context") {
             // Walk the full parent chain for context
-            // eslint-disable-next-line @typescript-eslint/no-this-alias
             let cursor = this;
             while (cursor && value === undefined) {
                 value = cursor.context;
@@ -336,7 +407,6 @@ export class ExecutionTree {
                 type: "Const",
                 field: "const",
             });
-            // eslint-disable-next-line @typescript-eslint/no-this-alias
             let cursor = this;
             while (cursor && value === undefined) {
                 value = cursor.state[constKey];
@@ -383,7 +453,7 @@ export class ExecutionTree {
         this.toolDepCache.set(toolName, promise);
         return promise;
     }
-    schedule(target) {
+    schedule(target, pullChain) {
         // Delegate to parent (shadow trees don't schedule directly) unless
         // the target fork has bridge wires sourced from element data,
         // or a __local binding whose source chain touches element data.
@@ -409,7 +479,7 @@ export class ExecutionTree {
                     return (this.bridge?.wires.some((iw) => sameTrunk(iw.to, srcTrunk) && "from" in iw && !!iw.from.element) ?? false);
                 });
             if (!hasElementSource && !hasTransitiveElementSource) {
-                return this.parent.schedule(target);
+                return this.parent.schedule(target, pullChain);
             }
         }
         return (async () => {
@@ -449,7 +519,7 @@ export class ExecutionTree {
             }
             const groupEntries = Array.from(wireGroups.entries());
             const resolved = await Promise.all(groupEntries.map(async ([, group]) => {
-                const value = await this.resolveWires(group);
+                const value = await this.resolveWires(group, pullChain);
                 return [group[0].to.path, value];
             }));
             for (const [path, value] of resolved) {
@@ -478,8 +548,21 @@ export class ExecutionTree {
                     return this.resolveToolSource(onErrorWire.source, toolDef);
                 }
             }
-            // Direct tool function lookup by name (simple or dotted)
-            const directFn = this.lookupToolFn(toolName);
+            // Direct tool function lookup by name (simple or dotted).
+            // When the handle carries a @version tag, try the versioned key first
+            // (e.g. "std.str.toLowerCase@999.1") so user-injected overrides win.
+            // For pipe forks, fall back to the baseTrunk's version since forks
+            // use synthetic instance numbers (100000+).
+            const handleVersion = this.handleVersionMap.get(trunkKey(target)) ??
+                (baseTrunk
+                    ? this.handleVersionMap.get(trunkKey(baseTrunk))
+                    : undefined);
+            let directFn = handleVersion
+                ? this.lookupToolFn(`${toolName}@${handleVersion}`)
+                : undefined;
+            if (!directFn) {
+                directFn = this.lookupToolFn(toolName);
+            }
             if (directFn) {
                 return this.callTool(toolName, toolName, directFn, input);
             }
@@ -574,7 +657,7 @@ export class ExecutionTree {
         });
     }
     shadow() {
-        const child = new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+        const child = new ExecutionTree(this.trunk, this.document, this.toolFns, undefined, this);
         child.tracer = this.tracer;
         child.logger = this.logger;
         child.signal = this.signal;
@@ -584,17 +667,23 @@ export class ExecutionTree {
     getTraces() {
         return this.tracer?.traces ?? [];
     }
-    async pullSingle(ref) {
+    async pullSingle(ref, pullChain = new Set()) {
         const key = trunkKey(ref);
+        // ── Cycle detection ─────────────────────────────────────────────
+        // If this exact key is already in our active pull chain, it is a
+        // circular dependency that would deadlock (await-on-self).
+        if (pullChain.has(key)) {
+            throw new BridgePanicError(`Circular dependency detected: "${key}" depends on itself`);
+        }
         // Walk the full parent chain — shadow trees may be nested multiple levels
         let value = undefined;
-        // eslint-disable-next-line @typescript-eslint/no-this-alias
         let cursor = this;
         while (cursor && value === undefined) {
             value = cursor.state[key];
             cursor = cursor.parent;
         }
         if (value === undefined) {
+            const nextChain = new Set(pullChain).add(key);
             // ── Lazy define field resolution ────────────────────────────────
             // For define trunks (__define_in_* / __define_out_*) with a specific
             // field path, resolve ONLY the wire(s) targeting that field instead
@@ -604,10 +693,10 @@ export class ExecutionTree {
             if (ref.path.length > 0 && ref.module.startsWith("__define_")) {
                 const fieldWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, ref) && pathEquals(w.to.path, ref.path)) ?? [];
                 if (fieldWires.length > 0) {
-                    return this.resolveWires(fieldWires);
+                    return this.resolveWires(fieldWires, nextChain);
                 }
             }
-            this.state[key] = this.schedule(ref);
+            this.state[key] = this.schedule(ref, nextChain);
             value = this.state[key];
         }
         // Always await in case the stored value is a Promise (e.g. from schedule()).
@@ -640,64 +729,6 @@ export class ExecutionTree {
         }
         return result;
     }
-    async pull(refs) {
-        if (refs.length === 1)
-            return this.pullSingle(refs[0]);
-        // Strict left-to-right sequential evaluation with short-circuit.
-        // We respect the exact fallback priority authored by the developer.
-        const errors = [];
-        for (const ref of refs) {
-            try {
-                const value = await this.pullSingle(ref);
-                if (value != null)
-                    return value; // Short-circuit: found data
-            }
-            catch (err) {
-                errors.push(err);
-            }
-        }
-        // All resolved to null/undefined, or all threw
-        if (errors.length === refs.length) {
-            throw new AggregateError(errors, "All sources failed");
-        }
-        return undefined;
-    }
-    /**
-     * Safe execution pull: wraps individual safe-flagged pulls in try/catch.
-     * Wires with `safe: true` swallow errors and return undefined.
-     * Non-safe wires propagate errors normally.
-     */
-    async pullSafe(pulls) {
-        if (pulls.length === 1) {
-            const w = pulls[0];
-            if (w.safe) {
-                try {
-                    return await this.pullSingle(w.from);
-                }
-                catch {
-                    return undefined;
-                }
-            }
-            return this.pullSingle(w.from);
-        }
-        const errors = [];
-        for (const w of pulls) {
-            try {
-                const value = w.safe
-                    ? await this.pullSingle(w.from).catch(() => undefined)
-                    : await this.pullSingle(w.from);
-                if (value != null)
-                    return value;
-            }
-            catch (err) {
-                errors.push(err);
-            }
-        }
-        if (errors.length === pulls.length) {
-            throw new AggregateError(errors, "All sources failed");
-        }
-        return undefined;
-    }
     push(args) {
         this.state[trunkKey(this.trunk)] = args;
     }
@@ -769,7 +800,7 @@ export class ExecutionTree {
      * After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
      * to return or continue to the next wire.
      */
-    async resolveWires(wires) {
+    async resolveWires(wires, pullChain) {
         let lastError;
         for (const w of wires) {
             // Constant wire — always wins, no modifiers
@@ -779,16 +810,16 @@ export class ExecutionTree {
                 // --- Layer 1: Execution ---
                 let resolvedValue;
                 if ("cond" in w) {
-                    const condValue = await this.pullSingle(w.cond);
+                    const condValue = await this.pullSingle(w.cond, pullChain);
                     if (condValue) {
                         if (w.thenRef !== undefined)
-                            resolvedValue = await this.pullSingle(w.thenRef);
+                            resolvedValue = await this.pullSingle(w.thenRef, pullChain);
                         else if (w.thenValue !== undefined)
                             resolvedValue = coerceConstant(w.thenValue);
                     }
                     else {
                         if (w.elseRef !== undefined)
-                            resolvedValue = await this.pullSingle(w.elseRef);
+                            resolvedValue = await this.pullSingle(w.elseRef, pullChain);
                         else if (w.elseValue !== undefined)
                             resolvedValue = coerceConstant(w.elseValue);
                     }
@@ -796,23 +827,23 @@ export class ExecutionTree {
                 else if ("condAnd" in w) {
                     const { leftRef, rightRef, rightValue, safe: isSafe, rightSafe, } = w.condAnd;
                     const leftVal = isSafe
-                        ? await this.pullSingle(leftRef).catch((e) => {
+                        ? await this.pullSingle(leftRef, pullChain).catch((e) => {
                             if (isFatalError(e))
                                 throw e;
                             return undefined;
                         })
-                        : await this.pullSingle(leftRef);
+                        : await this.pullSingle(leftRef, pullChain);
                     if (!leftVal) {
                         resolvedValue = false;
                     }
                     else if (rightRef !== undefined) {
                         const rightVal = rightSafe
-                            ? await this.pullSingle(rightRef).catch((e) => {
+                            ? await this.pullSingle(rightRef, pullChain).catch((e) => {
                                 if (isFatalError(e))
                                     throw e;
                                 return undefined;
                             })
-                            : await this.pullSingle(rightRef);
+                            : await this.pullSingle(rightRef, pullChain);
                         resolvedValue = Boolean(rightVal);
                     }
                     else if (rightValue !== undefined) {
@@ -825,23 +856,23 @@ export class ExecutionTree {
                 else if ("condOr" in w) {
                     const { leftRef, rightRef, rightValue, safe: isSafe, rightSafe, } = w.condOr;
                     const leftVal = isSafe
-                        ? await this.pullSingle(leftRef).catch((e) => {
+                        ? await this.pullSingle(leftRef, pullChain).catch((e) => {
                             if (isFatalError(e))
                                 throw e;
                             return undefined;
                         })
-                        : await this.pullSingle(leftRef);
+                        : await this.pullSingle(leftRef, pullChain);
                     if (leftVal) {
                         resolvedValue = true;
                     }
                     else if (rightRef !== undefined) {
                         const rightVal = rightSafe
-                            ? await this.pullSingle(rightRef).catch((e) => {
+                            ? await this.pullSingle(rightRef, pullChain).catch((e) => {
                                 if (isFatalError(e))
                                     throw e;
                                 return undefined;
                             })
-                            : await this.pullSingle(rightRef);
+                            : await this.pullSingle(rightRef, pullChain);
                         resolvedValue = Boolean(rightVal);
                     }
                     else if (rightValue !== undefined) {
@@ -854,7 +885,7 @@ export class ExecutionTree {
                 else if ("from" in w) {
                     if (w.safe) {
                         try {
-                            resolvedValue = await this.pullSingle(w.from);
+                            resolvedValue = await this.pullSingle(w.from, pullChain);
                         }
                         catch (err) {
                             if (isFatalError(err))
@@ -863,7 +894,7 @@ export class ExecutionTree {
                         }
                     }
                     else {
-                        resolvedValue = await this.pullSingle(w.from);
+                        resolvedValue = await this.pullSingle(w.from, pullChain);
                     }
                 }
                 else {
@@ -874,7 +905,7 @@ export class ExecutionTree {
                     for (const ref of w.falsyFallbackRefs) {
                         // Assign the fallback value regardless of whether it is truthy or falsy.
                         // e.g. `false || 0` will correctly update resolvedValue to `0`.
-                        resolvedValue = await this.pullSingle(ref);
+                        resolvedValue = await this.pullSingle(ref, pullChain);
                         // If it is truthy, we are done! Short-circuit the || chain.
                         if (resolvedValue)
                             break;
@@ -894,7 +925,7 @@ export class ExecutionTree {
                         resolvedValue = applyControlFlow(w.nullishControl);
                     }
                     else if (w.nullishFallbackRef) {
-                        resolvedValue = await this.pullSingle(w.nullishFallbackRef);
+                        resolvedValue = await this.pullSingle(w.nullishFallbackRef, pullChain);
                     }
                     else if (w.nullishFallback != null) {
                         resolvedValue = coerceConstant(w.nullishFallback);
@@ -911,7 +942,7 @@ export class ExecutionTree {
                 if (w.catchControl)
                     return applyControlFlow(w.catchControl);
                 if (w.catchFallbackRef)
-                    return this.pullSingle(w.catchFallbackRef);
+                    return this.pullSingle(w.catchFallbackRef, pullChain);
                 if (w.catchFallback != null)
                     return coerceConstant(w.catchFallback);
                 lastError = err;
@@ -1024,9 +1055,40 @@ export class ExecutionTree {
                 `Ensure at least one wire targets the output (e.g. \`o.field <- ...\`).`);
         }
         const result = {};
+        // Resolves a single output field at `prefix` — either via an exact-match
+        // wire (leaf), or by collecting sub-fields from deeper wires (nested object).
+        const resolveField = async (prefix) => {
+            const exactWires = bridge.wires.filter((w) => w.to.module === SELF_MODULE &&
+                w.to.type === type &&
+                w.to.field === field &&
+                pathEquals(w.to.path, prefix));
+            if (exactWires.length > 0) {
+                return this.resolveWires(exactWires);
+            }
+            // No exact wire — gather sub-field names from deeper-path wires
+            // (e.g. `o.why { .temperature <- ... }` produces path ["why","temperature"])
+            const subFields = new Set();
+            for (const wire of bridge.wires) {
+                const p = wire.to.path;
+                if (wire.to.module === SELF_MODULE &&
+                    wire.to.type === type &&
+                    wire.to.field === field &&
+                    p.length > prefix.length &&
+                    prefix.every((seg, i) => p[i] === seg)) {
+                    subFields.add(p[prefix.length]);
+                }
+            }
+            if (subFields.size === 0)
+                return undefined;
+            const obj = {};
+            await Promise.all([...subFields].map(async (sub) => {
+                obj[sub] = await resolveField([...prefix, sub]);
+            }));
+            return obj;
+        };
         await Promise.all([
             ...[...outputFields].map(async (name) => {
-                result[name] = await this.pullOutputField([name]);
+                result[name] = await resolveField([name]);
             }),
             ...forcePromises,
         ]);

package/build/{execute-bridge.d.ts → bridge-core/src/execute-bridge.d.ts}

@@ -1,8 +1,8 @@
 import type { Logger, ToolTrace, TraceLevel } from "./ExecutionTree.ts";
-import type { Instruction, ToolMap } from "./types.ts";
+import type { BridgeDocument, ToolMap } from "./types.ts";
 export type ExecuteBridgeOptions = {
-    /** Parsed bridge instructions (from `parseBridgeDiagnostics`). */
-    instructions: Instruction[];
+    /** Parsed bridge document (from `parseBridge` or `parseBridgeDiagnostics`). */
+    document: BridgeDocument;
     /**
      * Which bridge to execute, as `"Type.field"`.
      * Mirrors the `bridge Type.field { ... }` declaration.
@@ -11,7 +11,19 @@ export type ExecuteBridgeOptions = {
     operation: string;
     /** Input arguments — equivalent to GraphQL field arguments. */
     input?: Record<string, unknown>;
-    /** Additional tools to merge with the built-in `std` namespace. */
+    /**
+     * Tool functions available to the engine.
+     *
+     * Supports namespaced nesting: `{ myNamespace: { myTool } }`.
+     * The built-in `std` namespace is always included; user tools are
+     * merged on top (shallow).
+     *
+     * To provide a specific version of std (e.g. when the bridge file
+     * targets an older major), use a versioned namespace key:
+     * ```ts
+     * tools: { "std@1.5": oldStdNamespace }
+     * ```
+     */
     tools?: ToolMap;
     /** Context available via `with context as ctx` inside the bridge. */
     context?: Record<string, unknown>;
@@ -41,12 +53,12 @@ export type ExecuteBridgeResult<T = unknown> = {
  *
  * @example
  * ```ts
- * import { parseBridgeDiagnostics, executeBridge } from "@stackables/bridge";
+ * import { parseBridge, executeBridge } from "@stackables/bridge";
  * import { readFileSync } from "node:fs";
  *
- * const { instructions } = parseBridgeDiagnostics(readFileSync("my.bridge", "utf8"));
+ * const document = parseBridge(readFileSync("my.bridge", "utf8"));
  * const { data } = await executeBridge({
- *   instructions,
+ *   document,
  *   operation: "Query.myField",
  *   input: { city: "Berlin" },
  * });

package/build/bridge-core/src/execute-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-bridge.d.ts","sourceRoot":"","sources":["../../../src/execute-bridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ1D,MAAM,MAAM,oBAAoB,GAAG;IACjC,+EAA+E;IAC/E,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC7C,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAyCjC"}