@stackables/bridge-core 1.0.0 → 1.0.2

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

@@ -23,6 +23,23 @@ 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");
+/**
+ * Lazily detect whether the OpenTelemetry tracer is a real (recording)
+ * tracer or the default no-op.  Probed once on first tool call; result
+ * is cached for the lifetime of the process.
+ *
+ * If the SDK has not been registered by the time the first tool runs,
+ * all subsequent calls will skip OTel instrumentation.
+ */
+let _otelActive;
+function isOtelActive() {
+    if (_otelActive === undefined) {
+        const probe = otelTracer.startSpan("_bridge_probe_");
+        _otelActive = probe.isRecording();
+        probe.end();
+    }
+    return _otelActive;
+}
 const otelMeter = metrics.getMeter("@stackables/bridge");
 const toolCallCounter = otelMeter.createCounter("bridge.tool.calls", {
     description: "Total number of tool invocations",
@@ -51,9 +68,17 @@ function sameTrunk(a, b) {
         a.field === b.field &&
         (a.instance ?? undefined) === (b.instance ?? undefined));
 }
-/** Strict path equality */
+/** Strict path equality — manual loop avoids `.every()` closure allocation.  See docs/performance.md (#7). */
 function pathEquals(a, b) {
-    return a.length === b.length && a.every((v, i) => v === b[i]);
+    if (!a || !b)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
 }
 /** Check whether an error is a fatal halt (abort or panic) that must bypass all error boundaries. */
 function isFatalError(err) {
@@ -62,6 +87,37 @@ function isFatalError(err) {
         err?.name === "BridgeAbortError" ||
         err?.name === "BridgePanicError");
 }
+/** Returns `true` when `value` is a thenable (Promise or Promise-like). */
+function isPromise(value) {
+    return typeof value?.then === "function";
+}
+/**
+ * Returns the `from` NodeRef when a wire qualifies for the simple-pull fast
+ * path (single `from` wire, no safe/falsy/nullish/catch modifiers).  Returns
+ * `null` otherwise.  The result is cached on the wire object so subsequent
+ * calls are a single property read.  See docs/performance.md (#11).
+ */
+function getSimplePullRef(w) {
+    let ref = w.__simplePullRef;
+    if (ref !== undefined)
+        return ref;
+    ref =
+        "from" in w &&
+            !w.safe &&
+            !w.falsyFallbackRefs?.length &&
+            w.falsyControl == null &&
+            w.falsyFallback == null &&
+            w.nullishControl == null &&
+            !w.nullishFallbackRef &&
+            w.nullishFallback == null &&
+            !w.catchControl &&
+            !w.catchFallbackRef &&
+            w.catchFallback == null
+            ? w.from
+            : null;
+    w.__simplePullRef = ref;
+    return ref;
+}
 /** Execute a control flow instruction, returning a sentinel or throwing. */
 function applyControlFlow(ctrl) {
     if (ctrl.kind === "throw")
@@ -126,14 +182,29 @@ export class TraceCollector {
  *   "true" → true, "false" → false, "null" → null, "42" → 42
  * Plain strings that aren't valid JSON (like "hello", "/search") fall
  * through and are returned as-is.
+ *
+ * Results are cached in a module-level Map because the same constant
+ * strings appear repeatedly across shadow trees.  Only safe for
+ * immutable values (primitives); callers must not mutate the returned
+ * value.  See docs/performance.md (#6).
  */
+const constantCache = new Map();
 function coerceConstant(raw) {
+    const cached = constantCache.get(raw);
+    if (cached !== undefined)
+        return cached;
+    let result;
     try {
-        return JSON.parse(raw);
+        result = JSON.parse(raw);
     }
     catch {
-        return raw;
+        result = raw;
     }
+    // Hard cap to prevent unbounded growth over long-lived processes.
+    if (constantCache.size > 10_000)
+        constantCache.clear();
+    constantCache.set(raw, result);
+    return result;
 }
 const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function setNested(obj, path, value) {
@@ -181,6 +252,8 @@ export class ExecutionTree {
     toolFns;
     /** Shadow-tree nesting depth (0 for root). */
     depth;
+    /** Pre-computed `trunkKey({ ...this.trunk, element: true })`.  See docs/performance.md (#4). */
+    elementTrunkKey;
     constructor(trunk, document, toolFns, context, parent) {
         this.trunk = trunk;
         this.document = document;
@@ -190,6 +263,7 @@ export class ExecutionTree {
         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.elementTrunkKey = `${trunk.module}:${trunk.type}:${trunk.field}:*`;
         this.toolFns = { internal, ...(toolFns ?? {}) };
         const instructions = document.instructions;
         this.bridge = instructions.find((i) => i.kind === "bridge" && i.type === trunk.type && i.field === trunk.field);
@@ -482,117 +556,161 @@ export class ExecutionTree {
                 return this.parent.schedule(target, pullChain);
             }
         }
-        return (async () => {
-            // If this target is a pipe fork, also apply bridge wires from its base
-            // handle (non-pipe wires, e.g. `c.currency <- i.currency`) as defaults
-            // before the fork-specific pipe wires.
-            const targetKey = trunkKey(target);
-            const pipeFork = this.pipeHandleMap?.get(targetKey);
-            const baseTrunk = pipeFork?.baseTrunk;
-            const baseWires = baseTrunk
-                ? (this.bridge?.wires.filter((w) => !("pipe" in w) && sameTrunk(w.to, baseTrunk)) ?? [])
-                : [];
-            // Fork-specific wires (pipe wires targeting the fork's own instance)
-            const forkWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, target)) ?? [];
-            // Merge: base provides defaults, fork overrides
-            const bridgeWires = [...baseWires, ...forkWires];
-            // Look up ToolDef for this target
-            const toolName = this.getToolName(target);
-            const toolDef = this.resolveToolDefByName(toolName);
-            // Build input object: tool wires first (base), then bridge wires (override)
-            const input = {};
-            if (toolDef) {
-                await this.resolveToolWires(toolDef, input);
-            }
-            // 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);
+        // ── Sync work: collect and group bridge wires ─────────────────
+        // If this target is a pipe fork, also apply bridge wires from its base
+        // handle (non-pipe wires, e.g. `c.currency <- i.currency`) as defaults
+        // before the fork-specific pipe wires.
+        const targetKey = trunkKey(target);
+        const pipeFork = this.pipeHandleMap?.get(targetKey);
+        const baseTrunk = pipeFork?.baseTrunk;
+        const baseWires = baseTrunk
+            ? (this.bridge?.wires.filter((w) => !("pipe" in w) && sameTrunk(w.to, baseTrunk)) ?? [])
+            : [];
+        // Fork-specific wires (pipe wires targeting the fork's own instance)
+        const forkWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, target)) ?? [];
+        // Merge: base provides defaults, fork overrides
+        const bridgeWires = [...baseWires, ...forkWires];
+        // Look up ToolDef for this target
+        const toolName = this.getToolName(target);
+        const toolDef = this.resolveToolDefByName(toolName);
+        // 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);
             }
-            const groupEntries = Array.from(wireGroups.entries());
-            const resolved = await Promise.all(groupEntries.map(async ([, group]) => {
-                const value = await this.resolveWires(group, pullChain);
-                return [group[0].to.path, value];
-            }));
-            for (const [path, value] of resolved) {
-                if (path.length === 0 && value != null && typeof value === "object") {
-                    Object.assign(input, value);
-                }
-                else {
-                    setNested(input, path, value);
-                }
-            }
-            // Call ToolDef-backed tool function
-            if (toolDef) {
-                const fn = this.lookupToolFn(toolDef.fn);
-                if (!fn)
-                    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");
-                try {
-                    return await this.callTool(toolName, toolDef.fn, fn, input);
-                }
-                catch (err) {
-                    if (!onErrorWire)
-                        throw err;
-                    if ("value" in onErrorWire)
-                        return JSON.parse(onErrorWire.value);
-                    return this.resolveToolSource(onErrorWire.source, toolDef);
-                }
+            group.push(w);
+        }
+        // ── Async path: tool definition requires resolveToolWires + callTool ──
+        if (toolDef) {
+            return this.scheduleToolDef(toolName, toolDef, wireGroups, pullChain);
+        }
+        // ── Sync-capable path: no tool definition ──
+        // For __local bindings, __define_ pass-throughs, pipe forks backed by
+        // sync tools, and logic nodes — resolve bridge wires and return
+        // synchronously when all sources are already in state.
+        // See docs/performance.md (#12).
+        const groupEntries = Array.from(wireGroups.entries());
+        const nGroups = groupEntries.length;
+        const values = new Array(nGroups);
+        let hasAsync = false;
+        for (let i = 0; i < nGroups; i++) {
+            const v = this.resolveWires(groupEntries[i][1], pullChain);
+            values[i] = v;
+            if (!hasAsync && isPromise(v))
+                hasAsync = true;
+        }
+        if (!hasAsync) {
+            return this.scheduleFinish(target, toolName, groupEntries, values, baseTrunk);
+        }
+        return Promise.all(values).then((resolved) => this.scheduleFinish(target, toolName, groupEntries, resolved, baseTrunk));
+    }
+    /**
+     * Assemble input from resolved wire values and either invoke a direct tool
+     * function or return the data for pass-through targets (local/define/logic).
+     * Returns synchronously when the tool function (if any) returns sync.
+     * See docs/performance.md (#12).
+     */
+    scheduleFinish(target, toolName, groupEntries, resolvedValues, baseTrunk) {
+        const input = {};
+        const resolved = [];
+        for (let i = 0; i < groupEntries.length; i++) {
+            const path = groupEntries[i][1][0].to.path;
+            const value = resolvedValues[i];
+            resolved.push([path, value]);
+            if (path.length === 0 && value != null && typeof value === "object") {
+                Object.assign(input, value);
             }
-            // 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);
+            else {
+                setNested(input, path, value);
             }
-            if (directFn) {
-                return this.callTool(toolName, toolName, directFn, input);
+        }
+        // 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);
+        }
+        // Define pass-through: synthetic trunks created by define inlining
+        // act as data containers — bridge wires set their values, no tool needed.
+        if (target.module.startsWith("__define_")) {
+            return input;
+        }
+        // Local binding or logic node: the wire resolves the source and stores
+        // the result — no tool call needed.  For path=[] wires the resolved
+        // value may be a primitive (boolean from condAnd/condOr, string from
+        // a pipe tool like upperCase), so return the resolved value directly.
+        if (target.module === "__local" ||
+            target.field === "__and" ||
+            target.field === "__or") {
+            for (const [path, value] of resolved) {
+                if (path.length === 0)
+                    return value;
             }
-            // Define pass-through: synthetic trunks created by define inlining
-            // act as data containers — bridge wires set their values, no tool needed.
-            if (target.module.startsWith("__define_")) {
-                return input;
+            return input;
+        }
+        throw new Error(`No tool found for "${toolName}"`);
+    }
+    /**
+     * Full async schedule path for targets backed by a ToolDef.
+     * Resolves tool wires, bridge wires, and invokes the tool function
+     * with error recovery support.
+     */
+    async scheduleToolDef(toolName, toolDef, wireGroups, pullChain) {
+        // Build input object: tool wires first (base), then bridge wires (override)
+        const input = {};
+        await this.resolveToolWires(toolDef, input);
+        // Resolve bridge wires and apply on top
+        const groupEntries = Array.from(wireGroups.entries());
+        const resolved = await Promise.all(groupEntries.map(async ([, group]) => {
+            const value = await this.resolveWires(group, pullChain);
+            return [group[0].to.path, value];
+        }));
+        for (const [path, value] of resolved) {
+            if (path.length === 0 && value != null && typeof value === "object") {
+                Object.assign(input, value);
             }
-            // Local binding or logic node: the wire resolves the source and stores
-            // the result — no tool call needed.  For path=[] wires the resolved
-            // value may be a primitive (boolean from condAnd/condOr, string from
-            // a pipe tool like upperCase), so return the resolved value directly.
-            if (target.module === "__local" ||
-                target.field === "__and" ||
-                target.field === "__or") {
-                for (const [path, value] of resolved) {
-                    if (path.length === 0)
-                        return value;
-                }
-                return input;
+            else {
+                setNested(input, path, value);
             }
-            throw new Error(`No tool found for "${toolName}"`);
-        })();
+        }
+        // Call ToolDef-backed tool function
+        const fn = this.lookupToolFn(toolDef.fn);
+        if (!fn)
+            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");
+        try {
+            return await this.callTool(toolName, toolDef.fn, fn, input);
+        }
+        catch (err) {
+            if (!onErrorWire)
+                throw err;
+            if ("value" in onErrorWire)
+                return JSON.parse(onErrorWire.value);
+            return this.resolveToolSource(onErrorWire.source, toolDef);
+        }
     }
     /**
      * Invoke a tool function, recording both an OpenTelemetry span and (when
      * tracing is enabled) a ToolTrace entry.  All three tool-call sites in the
      * engine delegate here so instrumentation lives in exactly one place.
      */
-    async callTool(toolName, fnName, fnImpl, input) {
+    callTool(toolName, fnName, fnImpl, input) {
         // Short-circuit before starting if externally aborted
         if (this.signal?.aborted) {
             throw new BridgeAbortError();
@@ -603,6 +721,15 @@ export class ExecutionTree {
             logger: logger ?? {},
             signal: this.signal,
         };
+        // ── Fast path: no instrumentation configured ──────────────────
+        // When there is no internal tracer, no logger, and OpenTelemetry
+        // has its default no-op provider, skip all instrumentation to
+        // avoid closure allocation, template-string building, and no-op
+        // metric calls.  See docs/performance.md (#5).
+        if (!tracer && !logger && !isOtelActive()) {
+            return fnImpl(input, toolContext);
+        }
+        // ── Instrumented path ─────────────────────────────────────────
         const traceStart = tracer?.now();
         const metricAttrs = {
             "bridge.tool.name": toolName,
@@ -657,7 +784,26 @@ export class ExecutionTree {
         });
     }
     shadow() {
-        const child = new ExecutionTree(this.trunk, this.document, this.toolFns, undefined, this);
+        // Lightweight: bypass the constructor to avoid redundant work that
+        // re-derives data identical to the parent (bridge lookup, pipeHandleMap,
+        // handleVersionMap, constObj, toolFns spread).  See docs/performance.md (#2).
+        const child = Object.create(ExecutionTree.prototype);
+        child.trunk = this.trunk;
+        child.document = this.document;
+        child.parent = this;
+        child.depth = this.depth + 1;
+        if (child.depth > MAX_EXECUTION_DEPTH) {
+            throw new BridgePanicError(`Maximum execution depth exceeded (${child.depth}) at ${trunkKey(this.trunk)}. Check for infinite recursion or circular array mappings.`);
+        }
+        child.state = {};
+        child.toolDepCache = new Map();
+        child.toolDefCache = new Map();
+        // Share read-only pre-computed data from parent
+        child.bridge = this.bridge;
+        child.pipeHandleMap = this.pipeHandleMap;
+        child.handleVersionMap = this.handleVersionMap;
+        child.toolFns = this.toolFns;
+        child.elementTrunkKey = this.elementTrunkKey;
         child.tracer = this.tracer;
         child.logger = this.logger;
         child.signal = this.signal;
@@ -667,11 +813,47 @@ export class ExecutionTree {
     getTraces() {
         return this.tracer?.traces ?? [];
     }
-    async pullSingle(ref, pullChain = new Set()) {
-        const key = trunkKey(ref);
+    /**
+     * Traverse `ref.path` on an already-resolved value, respecting null guards.
+     * Extracted from `pullSingle` so the sync and async paths can share logic.
+     */
+    applyPath(resolved, ref) {
+        if (!ref.path.length)
+            return resolved;
+        let result = resolved;
+        // Root-level null check
+        if (result == null) {
+            if (ref.rootSafe)
+                return undefined;
+            throw new TypeError(`Cannot read properties of ${result} (reading '${ref.path[0]}')`);
+        }
+        for (let i = 0; i < ref.path.length; i++) {
+            const segment = ref.path[i];
+            if (UNSAFE_KEYS.has(segment))
+                throw new Error(`Unsafe property traversal: ${segment}`);
+            if (Array.isArray(result) && !/^\d+$/.test(segment)) {
+                this.logger?.warn?.(`[bridge] Accessing ".${segment}" on an array (${result.length} items) — did you mean to use pickFirst or array mapping? Source: ${trunkKey(ref)}.${ref.path.join(".")}`);
+            }
+            result = result[segment];
+            if (result == null && i < ref.path.length - 1) {
+                const nextSafe = ref.pathSafe?.[i + 1] ?? false;
+                if (nextSafe)
+                    return undefined;
+                throw new TypeError(`Cannot read properties of ${result} (reading '${ref.path[i + 1]}')`);
+            }
+        }
+        return result;
+    }
+    /**
+     * Pull a single value.  Returns synchronously when already in state;
+     * returns a Promise only when the value is a pending tool call.
+     * See docs/performance.md (#10).
+     */
+    pullSingle(ref, pullChain = new Set()) {
+        // Cache trunkKey on the NodeRef to avoid repeated string allocation
+        // for the same AST node.  See docs/performance.md (#11).
+        const key = (ref.__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`);
         }
@@ -693,41 +875,19 @@ 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) {
+                    // resolveWires already delivers the value at ref.path — no applyPath.
                     return this.resolveWires(fieldWires, nextChain);
                 }
             }
             this.state[key] = this.schedule(ref, nextChain);
-            value = this.state[key];
+            value = this.state[key]; // sync value or Promise (see #12)
         }
-        // Always await in case the stored value is a Promise (e.g. from schedule()).
-        const resolved = await Promise.resolve(value);
-        if (!ref.path.length) {
-            return resolved;
-        }
-        let result = resolved;
-        // Root-level null check: if root data is null/undefined
-        if (result == null && ref.path.length > 0) {
-            if (ref.rootSafe)
-                return undefined;
-            throw new TypeError(`Cannot read properties of ${result} (reading '${ref.path[0]}')`);
-        }
-        for (let i = 0; i < ref.path.length; i++) {
-            const segment = ref.path[i];
-            if (UNSAFE_KEYS.has(segment))
-                throw new Error(`Unsafe property traversal: ${segment}`);
-            if (Array.isArray(result) && !/^\d+$/.test(segment)) {
-                this.logger?.warn?.(`[bridge] Accessing ".${segment}" on an array (${result.length} items) — did you mean to use pickFirst or array mapping? Source: ${trunkKey(ref)}.${ref.path.join(".")}`);
-            }
-            result = result[segment];
-            // Check for null/undefined AFTER access, before next segment
-            if (result == null && i < ref.path.length - 1) {
-                const nextSafe = ref.pathSafe?.[i + 1] ?? false;
-                if (nextSafe)
-                    return undefined;
-                throw new TypeError(`Cannot read properties of ${result} (reading '${ref.path[i + 1]}')`);
-            }
+        // Sync fast path: value is already resolved (not a pending Promise).
+        if (!isPromise(value)) {
+            return this.applyPath(value, ref);
         }
-        return result;
+        // Async: chain path traversal onto the pending promise.
+        return value.then((resolved) => this.applyPath(resolved, ref));
     }
     push(args) {
         this.state[trunkKey(this.trunk)] = args;
@@ -800,7 +960,26 @@ export class ExecutionTree {
      * After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
      * to return or continue to the next wire.
      */
-    async resolveWires(wires, pullChain) {
+    /**
+     * Resolve wires, returning synchronously when the hot path allows it.
+     *
+     * Fast path: single `from` wire with no fallback/catch modifiers, which is
+     * the common case for element field wires like `.id <- it.id`.  Delegates to
+     * `resolveWiresAsync` for anything more complex.
+     * See docs/performance.md (#10).
+     */
+    resolveWires(wires, pullChain) {
+        if (wires.length === 1) {
+            const w = wires[0];
+            if ("value" in w)
+                return coerceConstant(w.value);
+            const ref = getSimplePullRef(w);
+            if (ref)
+                return this.pullSingle(ref, pullChain);
+        }
+        return this.resolveWiresAsync(wires, pullChain);
+    }
+    async resolveWiresAsync(wires, pullChain) {
         let lastError;
         for (const w of wires) {
             // Constant wire — always wins, no modifiers
@@ -984,11 +1163,110 @@ export class ExecutionTree {
             if (item === CONTINUE_SYM)
                 continue;
             const s = this.shadow();
-            s.state[trunkKey({ ...this.trunk, element: true })] = item;
+            s.state[this.elementTrunkKey] = item;
             finalShadowTrees.push(s);
         }
         return finalShadowTrees;
     }
+    /**
+     * Resolve pre-grouped wires on this shadow tree without re-filtering.
+     * Called by the parent's `materializeShadows` to skip per-element wire
+     * filtering.  Returns synchronously when the wire resolves sync (hot path).
+     * See docs/performance.md (#8, #10).
+     */
+    resolvePreGrouped(wires) {
+        return this.resolveWires(wires);
+    }
+    /**
+     * Materialise all output wires into a plain JS object.
+     *
+     * Used by the GraphQL adapter when a bridge field returns a scalar type
+     * (e.g. `JSON`, `JSONObject`). In that case GraphQL won't call sub-field
+     * resolvers, so we need to eagerly resolve every output wire and assemble
+     * the result ourselves — the same logic `run()` uses for object output.
+     */
+    async collectOutput() {
+        const bridge = this.bridge;
+        if (!bridge)
+            return undefined;
+        const { type, field } = this.trunk;
+        // Shadow tree (array element) — resolve element-level output fields.
+        // For scalar arrays ([JSON!]) GraphQL won't call sub-field resolvers,
+        // so we eagerly materialise each element here.
+        if (this.parent) {
+            const outputFields = new Set();
+            for (const wire of bridge.wires) {
+                if (wire.to.module === SELF_MODULE &&
+                    wire.to.type === type &&
+                    wire.to.field === field &&
+                    wire.to.path.length > 0) {
+                    outputFields.add(wire.to.path[0]);
+                }
+            }
+            if (outputFields.size > 0) {
+                const result = {};
+                await Promise.all([...outputFields].map(async (name) => {
+                    result[name] = await this.pullOutputField([name]);
+                }));
+                return result;
+            }
+            // Passthrough: return stored element data directly
+            return this.state[this.elementTrunkKey];
+        }
+        // Root wire (`o <- src`) — whole-object passthrough
+        const hasRootWire = bridge.wires.some((w) => "from" in w &&
+            w.to.module === SELF_MODULE &&
+            w.to.type === type &&
+            w.to.field === field &&
+            w.to.path.length === 0);
+        if (hasRootWire) {
+            return this.pullOutputField([]);
+        }
+        // Object output — collect unique top-level field names
+        const outputFields = new Set();
+        for (const wire of bridge.wires) {
+            if (wire.to.module === SELF_MODULE &&
+                wire.to.type === type &&
+                wire.to.field === field &&
+                wire.to.path.length > 0) {
+                outputFields.add(wire.to.path[0]);
+            }
+        }
+        if (outputFields.size === 0)
+            return undefined;
+        const result = {};
+        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);
+            }
+            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 resolveField([name]);
+        }));
+        return result;
+    }
     /**
      * Execute the bridge end-to-end without GraphQL.
      *
@@ -1055,9 +1333,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,
         ]);
@@ -1077,6 +1386,9 @@ export class ExecutionTree {
         const { type, field } = this.trunk;
         const directFields = new Set();
         const deepPaths = new Map();
+        // #8: Pre-group wires by exact path — eliminates per-element re-filtering.
+        // Key: wire.to.path joined by \0 (null char is safe — field names are identifiers).
+        const wireGroupsByPath = new Map();
         for (const wire of wires) {
             const p = wire.to.path;
             if (wire.to.module !== SELF_MODULE ||
@@ -1090,6 +1402,13 @@ export class ExecutionTree {
             const name = p[pathPrefix.length];
             if (p.length === pathPrefix.length + 1) {
                 directFields.add(name);
+                const pathKey = p.join("\0");
+                let group = wireGroupsByPath.get(pathKey);
+                if (!group) {
+                    group = [];
+                    wireGroupsByPath.set(pathKey, group);
+                }
+                group.push(wire);
             }
             else {
                 let arr = deepPaths.get(name);
@@ -1100,6 +1419,63 @@ export class ExecutionTree {
                 arr.push(p);
             }
         }
+        // #9/#10: Fast path — no nested arrays, only direct fields.
+        // Collect all (shadow × field) resolutions.  When every value is already in
+        // state (the hot case for element passthrough), resolvePreGrouped returns
+        // synchronously and we skip Promise.all entirely.
+        // See docs/performance.md (#9, #10).
+        if (deepPaths.size === 0) {
+            const directFieldArray = [...directFields];
+            const nFields = directFieldArray.length;
+            const nItems = items.length;
+            // Pre-compute pathKeys and wire groups — only depend on j, not i.
+            // See docs/performance.md (#11).
+            const preGroups = new Array(nFields);
+            for (let j = 0; j < nFields; j++) {
+                const pathKey = [...pathPrefix, directFieldArray[j]].join("\0");
+                preGroups[j] = wireGroupsByPath.get(pathKey);
+            }
+            const rawValues = new Array(nItems * nFields);
+            let hasAsync = false;
+            for (let i = 0; i < nItems; i++) {
+                const shadow = items[i];
+                for (let j = 0; j < nFields; j++) {
+                    const v = shadow.resolvePreGrouped(preGroups[j]);
+                    rawValues[i * nFields + j] = v;
+                    if (!hasAsync && isPromise(v))
+                        hasAsync = true;
+                }
+            }
+            const flatValues = hasAsync
+                ? await Promise.all(rawValues)
+                : rawValues;
+            const finalResults = [];
+            for (let i = 0; i < items.length; i++) {
+                const obj = {};
+                let doBreak = false;
+                let doSkip = false;
+                for (let j = 0; j < nFields; j++) {
+                    const v = flatValues[i * nFields + j];
+                    if (v === BREAK_SYM) {
+                        doBreak = true;
+                        break;
+                    }
+                    if (v === CONTINUE_SYM) {
+                        doSkip = true;
+                        break;
+                    }
+                    obj[directFieldArray[j]] = v;
+                }
+                if (doBreak)
+                    break;
+                if (doSkip)
+                    continue;
+                finalResults.push(obj);
+            }
+            return finalResults;
+        }
+        // Slow path: deep paths (nested arrays) present.
+        // Uses pre-grouped wires for direct fields (#8), original logic for the rest.
         const rawResults = await Promise.all(items.map(async (shadow) => {
             const obj = {};
             const tasks = [];
@@ -1114,7 +1490,10 @@ export class ExecutionTree {
                             : children;
                     }
                     else {
-                        obj[name] = await shadow.pullOutputField(fullPath);
+                        // #8: wireGroupsByPath is built in the same branch that populates
+                        // directFields, so the group is always present — no fallback needed.
+                        const pathKey = fullPath.join("\0");
+                        obj[name] = await shadow.resolvePreGrouped(wireGroupsByPath.get(pathKey));
                     }
                 })());
             }
@@ -1205,7 +1584,7 @@ export class ExecutionTree {
                 if (item === CONTINUE_SYM)
                     continue;
                 const s = this.shadow();
-                s.state[trunkKey({ ...this.trunk, element: true })] = item;
+                s.state[this.elementTrunkKey] = item;
                 shadowTrees.push(s);
             }
             return shadowTrees;
@@ -1231,7 +1610,7 @@ export class ExecutionTree {
                     if (item === CONTINUE_SYM)
                         continue;
                     const s = this.shadow();
-                    s.state[trunkKey({ ...this.trunk, element: true })] = item;
+                    s.state[this.elementTrunkKey] = item;
                     shadowTrees.push(s);
                 }
                 return shadowTrees;
@@ -1242,8 +1621,7 @@ export class ExecutionTree {
         // 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];
+            const elementData = this.state[this.elementTrunkKey];
             if (elementData != null &&
                 typeof elementData === "object" &&
                 !Array.isArray(elementData)) {
@@ -1255,7 +1633,7 @@ export class ExecutionTree {
                         // resolve their own fields via this same fallback path.
                         return value.map((item) => {
                             const s = this.shadow();
-                            s.state[elementKey] = item;
+                            s.state[this.elementTrunkKey] = item;
                             return s;
                         });
                     }