@stackables/bridge 1.4.2 → 1.6.0

package/build/ExecutionTree.d.ts

@@ -11,6 +11,45 @@ type Trunk = {
     field: string;
     instance?: number;
 };
+/** Trace verbosity level */
+export type TraceLevel = "basic" | "full";
+/** A single recorded tool invocation. */
+export type ToolTrace = {
+    /** Tool name as resolved (e.g. "hereGeo", "std.upperCase") */
+    tool: string;
+    /** The function that was called (e.g. "httpCall", "upperCase") */
+    fn: string;
+    /** Input object passed to the tool function (only in "full" level) */
+    input?: Record<string, any>;
+    /** Resolved output (only in "full" level, on success) */
+    output?: any;
+    /** Error message (present when the tool threw) */
+    error?: string;
+    /** Wall-clock duration in milliseconds */
+    durationMs: number;
+    /** Monotonic timestamp (ms) relative to the first trace in the request */
+    startedAt: number;
+};
+/** Shared trace collector — one per request, passed through the tree. */
+export declare class TraceCollector {
+    readonly traces: ToolTrace[];
+    readonly level: TraceLevel;
+    private readonly epoch;
+    constructor(level?: TraceLevel);
+    /** Returns ms since the collector was created */
+    now(): number;
+    record(trace: ToolTrace): void;
+    /** Build a trace entry, omitting input/output for basic level. */
+    entry(base: {
+        tool: string;
+        fn: string;
+        startedAt: number;
+        durationMs: number;
+        input?: Record<string, any>;
+        output?: any;
+        error?: string;
+    }): ToolTrace;
+}
 export declare class ExecutionTree {
     trunk: Trunk;
     private instructions;
@@ -22,6 +61,8 @@ export declare class ExecutionTree {
     private toolDepCache;
     private toolDefCache;
     private pipeHandleMap;
+    /** Shared trace collector — present only when tracing is enabled. */
+    tracer?: TraceCollector;
     constructor(trunk: Trunk, instructions: Instruction[], toolFns?: ToolMap | undefined, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
     /** Derive tool name from a trunk */
     private getToolName;
@@ -38,7 +79,15 @@ export declare class ExecutionTree {
     private resolveToolDep;
     schedule(target: Trunk): any;
     shadow(): ExecutionTree;
+    /** Returns collected traces (empty array when tracing is disabled). */
+    getTraces(): ToolTrace[];
     private pullSingle;
+    /**
+     * Infer the cost of resolving a NodeRef.
+     * Cost 0: memory reads (input, context, const) — no I/O.
+     * Cost 1: everything else (tool calls, pipes, defines) — may involve network.
+     */
+    private inferCost;
     pull(refs: NodeRef[]): Promise<any>;
     push(args: Record<string, any>): void;
     /** Eagerly schedule tools targeted by forced (<-!) wires. */

package/build/ExecutionTree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../src/ExecutionTree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EAEN,WAAW,EACX,OAAO,EAGP,OAAO,EAER,MAAM,YAAY,CAAC;AAGpB,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;AAsChF,qBAAa,aAAa;IAQf,KAAK,EAAE,KAAK;IACnB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,MAAM,CAAC;IAXjB,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,CAAsE;gBAGlF,KAAK,EAAE,KAAK,EACX,YAAY,EAAE,WAAW,EAAE,EAC3B,OAAO,CAAC,EAAE,OAAO,YAAA,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAA,EAC7B,MAAM,CAAC,EAAE,aAAa,YAAA;IA8BhC,oCAAoC;IACpC,OAAO,CAAC,WAAW;IAKnB;uGACmG;IACnG,OAAO,CAAC,YAAY;IAsBpB,oEAAoE;IACpE,OAAO,CAAC,oBAAoB;IA8D5B,mEAAmE;YACrD,gBAAgB;IA0B9B,2EAA2E;YAC7D,iBAAiB;IAgC/B,kDAAkD;IAClD,OAAO,CAAC,cAAc;IAgCtB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,GAAG;IAmF5B,MAAM,IAAI,aAAa;YAUT,UAAU;IA4BlB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAqCzC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAI9B,6DAA6D;IAC7D,aAAa,IAAI,IAAI;IAqBrB;;oFAEgF;IAChF,OAAO,CAAC,YAAY;IA8Cd,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;CAsD1D"}
+{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../src/ExecutionTree.ts"],"names":[],"mappings":"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"}

package/build/ExecutionTree.js

@@ -17,6 +17,40 @@ function sameTrunk(a, b) {
 function pathEquals(a, b) {
     return a.length === b.length && a.every((v, i) => v === b[i]);
 }
+/** Shared trace collector — one per request, passed through the tree. */
+export class TraceCollector {
+    traces = [];
+    level;
+    epoch = performance.now();
+    constructor(level = "full") {
+        this.level = level;
+    }
+    /** Returns ms since the collector was created */
+    now() {
+        return Math.round((performance.now() - this.epoch) * 100) / 100;
+    }
+    record(trace) {
+        this.traces.push(trace);
+    }
+    /** Build a trace entry, omitting input/output for basic level. */
+    entry(base) {
+        if (this.level === "basic") {
+            const t = { tool: base.tool, fn: base.fn, durationMs: base.durationMs, startedAt: base.startedAt };
+            if (base.error)
+                t.error = base.error;
+            return t;
+        }
+        // full
+        const t = { tool: base.tool, fn: base.fn, durationMs: base.durationMs, startedAt: base.startedAt };
+        if (base.input)
+            t.input = structuredClone(base.input);
+        if (base.error)
+            t.error = base.error;
+        else if (base.output !== undefined)
+            t.output = base.output;
+        return t;
+    }
+}
 /** Set a value at a nested path, creating intermediate objects/arrays as needed */
 function setNested(obj, path, value) {
     for (let i = 0; i < path.length - 1; i++) {
@@ -42,6 +76,8 @@ export class ExecutionTree {
     toolDepCache = new Map();
     toolDefCache = new Map();
     pipeHandleMap;
+    /** Shared trace collector — present only when tracing is enabled. */
+    tracer;
     constructor(trunk, instructions, toolFns, context, parent) {
         this.trunk = trunk;
         this.instructions = instructions;
@@ -186,10 +222,23 @@ export class ExecutionTree {
             throw new Error(`Unknown source "${handle}" in tool "${toolDef.name}"`);
         let value;
         if (dep.kind === "context") {
-            value = this.context ?? this.parent?.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;
+                cursor = cursor.parent;
+            }
         }
         else if (dep.kind === "const") {
-            value = this.state[trunkKey({ module: SELF_MODULE, type: "Const", field: "const" })] ?? this.parent?.state[trunkKey({ module: SELF_MODULE, type: "Const", field: "const" })];
+            // Walk the full parent chain for const state
+            const constKey = trunkKey({ module: SELF_MODULE, type: "Const", field: "const" });
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            let cursor = this;
+            while (cursor && value === undefined) {
+                value = cursor.state[constKey];
+                cursor = cursor.parent;
+            }
         }
         else if (dep.kind === "tool") {
             value = await this.resolveToolDep(dep.tool);
@@ -217,10 +266,19 @@ export class ExecutionTree {
                 throw new Error(`Tool function "${toolDef.fn}" not registered`);
             // on error: wrap the tool call with fallback from onError wire
             const onErrorWire = toolDef.wires.find((w) => w.kind === "onError");
+            const tracer = this.tracer;
+            const traceStart = tracer?.now();
             try {
-                return await fn(input);
+                const result = await fn(input);
+                if (tracer && traceStart != null) {
+                    tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                }
+                return result;
             }
             catch (err) {
+                if (tracer && traceStart != null) {
+                    tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                }
                 if (!onErrorWire)
                     throw err;
                 if ("value" in onErrorWire)
@@ -258,10 +316,23 @@ export class ExecutionTree {
             if (toolDef) {
                 await this.resolveToolWires(toolDef, input);
             }
-            // Resolve bridge wires and apply on top
-            const resolved = await Promise.all(bridgeWires.map(async (w) => {
-                const value = "value" in w ? w.value : await this.pullSingle(w.from);
-                return [w.to.path, value];
+            // Resolve bridge wires and apply on top.
+            // Group wires by target path so that || (null-fallback) and ??
+            // (error-fallback) semantics are honoured via resolveWires().
+            const wireGroups = new Map();
+            for (const w of bridgeWires) {
+                const key = w.to.path.join(".");
+                let group = wireGroups.get(key);
+                if (!group) {
+                    group = [];
+                    wireGroups.set(key, group);
+                }
+                group.push(w);
+            }
+            const groupEntries = Array.from(wireGroups.entries());
+            const resolved = await Promise.all(groupEntries.map(async ([, group]) => {
+                const value = await this.resolveWires(group);
+                return [group[0].to.path, value];
             }));
             for (const [path, value] of resolved) {
                 if (path.length === 0 && value != null && typeof value === "object") {
@@ -278,10 +349,19 @@ export class ExecutionTree {
                     throw new Error(`Tool function "${toolDef.fn}" not registered`);
                 // on error: wrap the tool call with fallback from onError wire
                 const onErrorWire = toolDef.wires.find((w) => w.kind === "onError");
+                const tracer = this.tracer;
+                const traceStart = tracer?.now();
                 try {
-                    return await fn(input);
+                    const result = await fn(input);
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    return result;
                 }
                 catch (err) {
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
                     if (!onErrorWire)
                         throw err;
                     if ("value" in onErrorWire)
@@ -292,7 +372,21 @@ export class ExecutionTree {
             // Direct tool function lookup by name (simple or dotted)
             const directFn = this.lookupToolFn(toolName);
             if (directFn) {
-                return directFn(input);
+                const tracer = this.tracer;
+                const traceStart = tracer?.now();
+                try {
+                    const result = await directFn(input);
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolName, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    return result;
+                }
+                catch (err) {
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolName, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    throw err;
+                }
             }
             // Define pass-through: synthetic trunks created by define inlining
             // act as data containers — bridge wires set their values, no tool needed.
@@ -303,11 +397,24 @@ export class ExecutionTree {
         })();
     }
     shadow() {
-        return new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+        const child = new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+        child.tracer = this.tracer;
+        return child;
+    }
+    /** Returns collected traces (empty array when tracing is disabled). */
+    getTraces() {
+        return this.tracer?.traces ?? [];
     }
     async pullSingle(ref) {
         const key = trunkKey(ref);
-        let value = this.state[key] ?? this.parent?.state[key];
+        // 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) {
             this.state[key] = this.schedule(ref);
             value = this.state[key];
@@ -326,37 +433,62 @@ export class ExecutionTree {
         }
         return result;
     }
+    /**
+     * Infer the cost of resolving a NodeRef.
+     * Cost 0: memory reads (input, context, const) — no I/O.
+     * Cost 1: everything else (tool calls, pipes, defines) — may involve network.
+     */
+    inferCost(ref) {
+        // Input args, context, and const live in the state map — free reads
+        if (ref.module === SELF_MODULE) {
+            const key = trunkKey(ref);
+            // Already resolved in state? Free.
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            let cursor = this;
+            while (cursor) {
+                if (cursor.state[key] !== undefined)
+                    return 0;
+                cursor = cursor.parent;
+            }
+            // Input/context/const trunks are always cost 0
+            if (ref.type === "Context" || ref.type === "Const")
+                return 0;
+            // Input args trunk: _:Query:fieldName (same as this.trunk) — cost 0
+            if (ref.module === SELF_MODULE && ref.type === this.trunk.type && ref.field === this.trunk.field && !ref.element)
+                return 0;
+        }
+        return 1;
+    }
     async pull(refs) {
         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(); });
+        // Cost-sorted sequential evaluation with short-circuit.
+        //
+        // Sort by inferred cost (stable — preserves declaration order within
+        // the same cost tier). This means:
+        //   • ||  chains (both sources are tools = same cost) → left-to-right
+        //   • Overdefinition with mixed costs → cheapest first
+        //
+        // Evaluate sequentially. Return the first non-null value.
+        // If all return null/undefined → return undefined (lets || fire).
+        // If all throw → throw AggregateError (lets ?? fire).
+        const sorted = [...refs].sort((a, b) => this.inferCost(a) - this.inferCost(b));
+        const errors = [];
+        for (const ref of sorted) {
+            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;
     }
     push(args) {
         this.state[trunkKey(this.trunk)] = args;
@@ -458,6 +590,30 @@ export class ExecutionTree {
                 return s;
             });
         }
+        // Fallback: if this shadow tree has stored element data, resolve the
+        // requested field directly from it. This handles passthrough arrays
+        // where the bridge maps an inner array (e.g. `.stops <- j.stops`) but
+        // doesn't explicitly wire each scalar field on the element type.
+        if (this.parent) {
+            const elementKey = trunkKey({ ...this.trunk, element: true });
+            const elementData = this.state[elementKey];
+            if (elementData != null && typeof elementData === "object" && !Array.isArray(elementData)) {
+                const fieldName = cleanPath[cleanPath.length - 1];
+                if (fieldName !== undefined && fieldName in elementData) {
+                    const value = elementData[fieldName];
+                    if (array && Array.isArray(value)) {
+                        // Nested array: wrap items in shadow trees so they can
+                        // resolve their own fields via this same fallback path.
+                        return value.map((item) => {
+                            const s = this.shadow();
+                            s.state[elementKey] = item;
+                            return s;
+                        });
+                    }
+                    return value;
+                }
+            }
+        }
         // Return self to trigger downstream resolvers
         return this;
     }

package/build/bridge-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-format.d.ts","sourceRoot":"","sources":["../src/bridge-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKR,WAAW,EAMd,MAAM,YAAY,CAAC;AA8CpB,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CA0FvD;AAqwCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAchD;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CA8BnE"}
+{"version":3,"file":"bridge-format.d.ts","sourceRoot":"","sources":["../src/bridge-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKR,WAAW,EAMd,MAAM,YAAY,CAAC;AA8CpB,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CA0FvD;AAmxCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAchD;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CA8BnE"}

package/build/bridge-format.js

@@ -409,6 +409,7 @@ function parseBridgeBlock(block, lineOffset, previousInstructions) {
             const [, targetStr, quotedValue, unquotedValue] = constantMatch;
             const value = quotedValue ?? unquotedValue;
             const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
+            assertNoTargetIndices(toRef, ln(i));
             wires.push({ value, to: toRef });
             continue;
         }
@@ -427,6 +428,7 @@ function parseBridgeBlock(block, lineOffset, previousInstructions) {
                 assertNotReserved(iterHandle, ln(i), "iterator handle");
                 const fromRef = resolveAddress(fromClean, handleRes, bridgeType, bridgeField, ln(i));
                 const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
+                assertNoTargetIndices(toRef, ln(i));
                 wires.push({ from: fromRef, to: toRef });
                 currentArrayToPath = toRef.path;
                 currentIterHandle = iterHandle;
@@ -469,6 +471,7 @@ function parseBridgeBlock(block, lineOffset, previousInstructions) {
                 fallbackInternalWires = wires.splice(preLen);
             }
             const toRef = resolveAddress(targetStr, handleRes, bridgeType, bridgeField, ln(i));
+            assertNoTargetIndices(toRef, ln(i));
             for (let ci = 0; ci < sourceParts.length; ci++) {
                 const isFirst = ci === 0;
                 const isLast = ci === sourceParts.length - 1;
@@ -927,6 +930,14 @@ function resolveAddress(address, handles, bridgeType, bridgeField, lineNum) {
     throw new Error(`${lineNum != null ? `Line ${lineNum}: ` : ""}Undeclared handle "${prefix}". ` +
         `Add 'with ${prefix}' or 'with ${prefix} as ${prefix}' to the bridge header.`);
 }
+/** Reject explicit array indices on the target (LHS) of a wire. */
+function assertNoTargetIndices(ref, lineNum) {
+    if (ref.path.some((seg) => /^\d+$/.test(seg))) {
+        throw new Error(`${lineNum != null ? `Line ${lineNum}: ` : ""}` +
+            `Explicit array index in wire target is not supported. ` +
+            `Use array mapping (\`[] as iter { }\`) instead.`);
+    }
+}
 // ── Const block parser ──────────────────────────────────────────────────────
 /**
  * Parse `const` declarations into ConstDef instructions.

package/build/bridge-transform.d.ts

@@ -1,4 +1,5 @@
 import { type GraphQLSchema } from "graphql";
+import { type ToolTrace, type TraceLevel } from "./ExecutionTree.js";
 import type { Instruction, ToolMap } from "./types.js";
 export type BridgeOptions = {
     /** Tool functions available to the engine.
@@ -9,8 +10,40 @@ export type BridgeOptions = {
     /** Optional function to reshape/restrict the GQL context before it reaches bridge files.
      *  By default the full context is exposed via `with context`. */
     contextMapper?: (context: any) => Record<string, any>;
+    /** Enable tool-call tracing.
+     *  - `true` or `"full"`: record tool, fn, input, output/error, timing
+     *  - `"basic"`: record tool, fn, timing, error (no input/output) */
+    trace?: boolean | TraceLevel;
 };
 /** Instructions can be a static array or a function that selects per-request */
 export type InstructionSource = Instruction[] | ((context: any) => Instruction[]);
 export declare function bridgeTransform(schema: GraphQLSchema, instructions: InstructionSource, options?: BridgeOptions): GraphQLSchema;
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export declare function getBridgeTraces(context: any): ToolTrace[];
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export declare function useBridgeTracing(): {
+    onExecute({ args }: {
+        args: {
+            contextValue: any;
+        };
+    }): {
+        onExecuteDone({ result, setResult, }: {
+            result: any;
+            setResult: (r: any) => void;
+        }): void;
+    };
+};
 //# sourceMappingURL=bridge-transform.d.ts.map

package/build/bridge-transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,WAAW,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACvD,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CA0Ef"}
+{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtD;;wEAEoE;IACpE,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC9B,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAuFf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,EAAE,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB;wBAER;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE;8CAK5C;YACD,MAAM,EAAE,GAAG,CAAC;YACZ,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;SAC7B;;EAeR"}

package/build/bridge-transform.js

@@ -1,11 +1,13 @@
 import { MapperKind, mapSchema } from "@graphql-tools/utils";
 import { GraphQLList, GraphQLNonNull, defaultFieldResolver, } from "graphql";
-import { ExecutionTree } from "./ExecutionTree.js";
+import { ExecutionTree, TraceCollector } from "./ExecutionTree.js";
 import { builtinTools } from "./tools/index.js";
 import { SELF_MODULE } from "./types.js";
 export function bridgeTransform(schema, instructions, options) {
     const userTools = options?.tools;
     const contextMapper = options?.contextMapper;
+    const tracing = options?.trace ?? false;
+    const traceLevel = tracing === true ? "full" : tracing === false ? false : tracing;
     return mapSchema(schema, {
         [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
             let array = false;
@@ -36,6 +38,11 @@ export function bridgeTransform(schema, instructions, options) {
                             ...(userTools ?? {}),
                         };
                         source = new ExecutionTree(trunk, activeInstructions, allTools, bridgeContext);
+                        if (traceLevel) {
+                            source.tracer = new TraceCollector(traceLevel);
+                            // Stash tracer on GQL context so the tracing plugin can read it
+                            context.__bridgeTracer = source.tracer;
+                        }
                     }
                     if (source instanceof ExecutionTree &&
                         args &&
@@ -44,6 +51,11 @@ export function bridgeTransform(schema, instructions, options) {
                     }
                     // Kick off forced wires (<-!) at the root entry point
                     if (source instanceof ExecutionTree && !info.path.prev) {
+                        // Ensure input state exists even with no args (prevents
+                        // recursive scheduling of the input trunk → stack overflow).
+                        if (!args || Object.keys(args).length === 0) {
+                            source.push({});
+                        }
                         source.executeForced();
                     }
                     if (source instanceof ExecutionTree) {
@@ -55,3 +67,41 @@ export function bridgeTransform(schema, instructions, options) {
         },
     });
 }
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export function getBridgeTraces(context) {
+    return context?.__bridgeTracer?.traces ?? [];
+}
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export function useBridgeTracing() {
+    return {
+        onExecute({ args }) {
+            return {
+                onExecuteDone({ result, setResult, }) {
+                    const traces = getBridgeTraces(args.contextValue);
+                    if (traces.length > 0 && result && "data" in result) {
+                        setResult({
+                            ...result,
+                            extensions: {
+                                ...(result.extensions ?? {}),
+                                traces,
+                            },
+                        });
+                    }
+                },
+            };
+        },
+    };
+}

package/build/index.d.ts

@@ -1,6 +1,7 @@
 export { parseBridge } from "./bridge-format.js";
-export { bridgeTransform } from "./bridge-transform.js";
+export { bridgeTransform, getBridgeTraces, useBridgeTracing } from "./bridge-transform.js";
 export type { BridgeOptions, InstructionSource } from "./bridge-transform.js";
 export { builtinTools, std, createHttpCall } from "./tools/index.js";
+export type { ToolTrace, TraceLevel } from "./ExecutionTree.js";
 export type { CacheStore, ConstDef, Instruction, ToolCallFn, ToolDef, ToolMap } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/build/index.js

@@ -1,3 +1,3 @@
 export { parseBridge } from "./bridge-format.js";
-export { bridgeTransform } from "./bridge-transform.js";
+export { bridgeTransform, getBridgeTraces, useBridgeTracing } from "./bridge-transform.js";
 export { builtinTools, std, createHttpCall } from "./tools/index.js";

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@stackables/bridge",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "Declarative dataflow for GraphQL",
   "main": "./build/index.js",
   "type": "module",
   "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
   "files": [
     "build",
     "README.md"