@quereus/quereus 3.1.2 → 3.2.1

package/dist/src/runtime/emit/async-gather.js

@@ -0,0 +1,234 @@
+import { emitCallFromPlan } from '../emitters.js';
+import { ParallelDriver } from '../parallel-driver.js';
+import { BTree } from 'inheritree';
+import { createCollationRowComparator, BINARY_COLLATION } from '../../util/comparison.js';
+/**
+ * Yield the N-ary Cartesian product of the given per-branch row buffers, in
+ * lexicographic order over branch indices (branch 0 varies slowest). Caller
+ * is responsible for confirming every buffer is non-empty; an empty buffer
+ * means the product is empty and this helper should not be called.
+ *
+ * Exported for unit testing.
+ */
+export function* cartesianProduct(buffers) {
+    const n = buffers.length;
+    const indices = new Array(n).fill(0);
+    while (true) {
+        const row = [];
+        for (let i = 0; i < n; i++) {
+            const sub = buffers[i][indices[i]];
+            for (let j = 0; j < sub.length; j++) {
+                row.push(sub[j]);
+            }
+        }
+        yield row;
+        let k = n - 1;
+        while (k >= 0) {
+            indices[k]++;
+            if (indices[k] < buffers[k].length)
+                break;
+            indices[k] = 0;
+            k--;
+        }
+        if (k < 0)
+            return;
+    }
+}
+/**
+ * Async-iterate the `unionAll` shape: fork N child views off `rctx`, drive
+ * the factories concurrently via {@link ParallelDriver.drive}, and yield every
+ * produced row in arrival order. Yielded order is non-deterministic.
+ *
+ * Exported for unit testing — production callers go through {@link emitAsyncGather}.
+ */
+export async function* runUnionAll(rctx, factories, concurrencyCap, driver = new ParallelDriver()) {
+    const forks = driver.fork(rctx, factories.length);
+    for await (const { value } of driver.drive(factories, forks, { concurrency: concurrencyCap })) {
+        yield value;
+    }
+}
+/**
+ * Async-iterate the `crossProduct` shape: fork N child views off `rctx`,
+ * drive the factories concurrently, buffer every branch's rows in memory,
+ * then yield the full N-ary Cartesian product. **Every branch is drained
+ * before the first row is yielded.** If any branch is empty, the product
+ * is empty.
+ *
+ * Exported for unit testing — production callers go through {@link emitAsyncGather}.
+ */
+export async function* runCrossProduct(rctx, factories, concurrencyCap, driver = new ParallelDriver()) {
+    const n = factories.length;
+    const forks = driver.fork(rctx, n);
+    const buffers = Array.from({ length: n }, () => []);
+    for await (const { branch, value } of driver.drive(factories, forks, {
+        concurrency: concurrencyCap,
+    })) {
+        buffers[branch].push(value);
+    }
+    for (let i = 0; i < n; i++) {
+        if (buffers[i].length === 0)
+            return;
+    }
+    yield* cartesianProduct(buffers);
+}
+/**
+ * Compose the merged key cells for a group **deterministically**: the
+ * lowest-indexed branch that has a row for this key supplies all K key cells.
+ *
+ * This matches `coalesce(b0.k, b1.k, …)`'s left-to-right first-non-null
+ * contract: every branch present for a (non-NULL) key has all its key columns
+ * non-null and collation-equal to the group key, so the first present branch
+ * wins every key position — independent of concurrent arrival order. Callers
+ * guarantee at least one branch is present.
+ */
+function composeMergedKeyCells(cells, branchKeyIndices) {
+    for (let b = 0; b < cells.length; b++) {
+        const cell = cells[b];
+        if (cell)
+            return branchKeyIndices[b].map(ix => cell[ix]);
+    }
+    // Unreachable: a group always has at least one present branch.
+    return [];
+}
+/**
+ * Compose one output row from a key tuple and per-branch row slots:
+ * `[ key cells ] ++ for each branch b: (cells[b] ? its non-key cells : NULLs)`.
+ */
+function composeZipRow(keyCells, cells, branchNonKeyIndices) {
+    const out = [...keyCells];
+    for (let b = 0; b < cells.length; b++) {
+        const cell = cells[b];
+        const nonKeyIx = branchNonKeyIndices[b];
+        if (cell) {
+            for (const ix of nonKeyIx)
+                out.push(cell[ix]);
+        }
+        else {
+            for (let j = 0; j < nonKeyIx.length; j++)
+                out.push(null);
+        }
+    }
+    return out;
+}
+/**
+ * Async-iterate the `zipByKey` shape: a full N-way outer join on the shared key
+ * columns, implemented as an **eager hash-merge**. Forks N child views off
+ * `rctx`, drives the factories concurrently, and upserts each row into a `BTree`
+ * keyed by its key tuple. **Every branch is drained before the first row is
+ * yielded** (memory-bound, like {@link runCrossProduct}).
+ *
+ * NULL keys never merge (SQL `NULL = NULL` is unknown): each NULL-keyed row is
+ * buffered and emitted standalone (only its own branch's columns populated).
+ *
+ * The merged key cells are **deterministic** regardless of concurrent branch
+ * arrival order: at emit time the lowest-indexed present branch supplies them
+ * (see {@link composeMergedKeyCells}), matching `coalesce`'s left-to-right pick
+ * even under a non-binary collation that makes collation-equal keys byte-distinct
+ * (NOCASE `'A'`/`'a'`). The `BTree` is still keyed by whichever key tuple arrived
+ * first, but that only drives comparison (collation-equal → identical merges).
+ *
+ * Within-branch duplicate keys are **unspecified** in v1 — branches are assumed
+ * key-unique; a second write for the same key overwrites the first.
+ *
+ * Exported for unit testing — production callers go through {@link emitAsyncGather}.
+ */
+export async function* runZipByKey(rctx, factories, branchKeyIndices, branchNonKeyIndices, keyComparator, concurrencyCap, driver = new ParallelDriver()) {
+    const n = factories.length;
+    const forks = driver.fork(rctx, n);
+    const tree = new BTree(e => e.key, keyComparator);
+    const nullKeyed = [];
+    for await (const { branch, value } of driver.drive(factories, forks, { concurrency: concurrencyCap })) {
+        const keyRow = branchKeyIndices[branch].map(ix => value[ix]);
+        if (keyRow.some(v => v === null)) {
+            // NULL key: never merges; emit standalone at the end.
+            nullKeyed.push({ branch, value });
+            continue;
+        }
+        const path = tree.find(keyRow);
+        if (path.on) {
+            tree.at(path).cells[branch] = value;
+        }
+        else {
+            const cells = new Array(n).fill(undefined);
+            cells[branch] = value;
+            tree.insert({ key: keyRow, cells });
+        }
+    }
+    // Walk the tree in key order; the tree is no longer mutated, so a plain
+    // first()/moveNext() walk is safe (no safeIterate recovery needed).
+    const path = tree.first();
+    while (path.on) {
+        const entry = tree.at(path);
+        const keyCells = composeMergedKeyCells(entry.cells, branchKeyIndices);
+        yield composeZipRow(keyCells, entry.cells, branchNonKeyIndices);
+        tree.moveNext(path);
+    }
+    // NULL-keyed rows: each emits standalone with only its branch's columns.
+    for (const { branch, value } of nullKeyed) {
+        const cells = new Array(n).fill(undefined);
+        cells[branch] = value;
+        const keyCells = composeMergedKeyCells(cells, branchKeyIndices);
+        yield composeZipRow(keyCells, cells, branchNonKeyIndices);
+    }
+}
+/**
+ * Emit an {@link AsyncGatherNode}.
+ *
+ * - `unionAll`: drives every branch concurrently and yields each branch's
+ *   rows in arrival order (multiset union, no dedup). Downstream consumers
+ *   requiring ordering must wrap the gather in `Sort`.
+ *
+ * - `crossProduct`: drives every branch concurrently, buffers each branch's
+ *   rows in memory, then yields the full N-ary Cartesian product. **All
+ *   branches are materialised before the first row is yielded.**
+ *
+ * - `zipByKey`: drives every branch concurrently, hash-merges rows by key tuple,
+ *   then yields one composed row per distinct key (full N-way outer join).
+ *   **All branches are materialised before the first row is yielded.**
+ *
+ * All combinators inherit cancellation, error propagation, strict-fork
+ * bookkeeping, and consumer-break cleanup from `ParallelDriver.drive`.
+ */
+export function emitAsyncGather(plan, ctx) {
+    const childInstructions = plan.children.map(c => emitCallFromPlan(c, ctx));
+    const concurrencyCap = plan.concurrencyCap;
+    const branchCount = plan.children.length;
+    if (plan.combinator.kind === 'unionAll') {
+        function run(rctx, ...childFactories) {
+            return runUnionAll(rctx, childFactories, concurrencyCap);
+        }
+        return {
+            params: childInstructions,
+            run: run,
+            note: `async_gather(unionAll, N=${branchCount}, cap=${concurrencyCap})`,
+        };
+    }
+    if (plan.combinator.kind === 'zipByKey') {
+        const { branchKeyIndices, branchNonKeyIndices } = plan.getZipByKeyIndices();
+        // Build the key comparator from children[0]'s key column collations (key
+        // columns share affinity across branches per the construction contract).
+        const child0Attrs = plan.children[0].getAttributes();
+        const keyCollations = branchKeyIndices[0].map((colIx) => {
+            const attr = child0Attrs[colIx];
+            return attr.type.collationName ? ctx.resolveCollation(attr.type.collationName) : BINARY_COLLATION;
+        });
+        const keyComparator = createCollationRowComparator(keyCollations);
+        function run(rctx, ...childFactories) {
+            return runZipByKey(rctx, childFactories, branchKeyIndices, branchNonKeyIndices, keyComparator, concurrencyCap);
+        }
+        return {
+            params: childInstructions,
+            run: run,
+            note: `async_gather(zipByKey, N=${branchCount}, cap=${concurrencyCap})`,
+        };
+    }
+    function run(rctx, ...childFactories) {
+        return runCrossProduct(rctx, childFactories, concurrencyCap);
+    }
+    return {
+        params: childInstructions,
+        run: run,
+        note: `async_gather(crossProduct, N=${branchCount}, cap=${concurrencyCap})`,
+    };
+}
+//# sourceMappingURL=async-gather.js.map

package/dist/src/runtime/emit/async-gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-gather.js","sourceRoot":"","sources":["../../../../src/runtime/emit/async-gather.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime/emit/bloom-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bloom-join.d.ts","sourceRoot":"","sources":["../../../../src/runtime/emit/bloom-join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAkC,MAAM,aAAa,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAS9D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,GAAG,WAAW,CA2GpF"}
+{"version":3,"file":"bloom-join.d.ts","sourceRoot":"","sources":["../../../../src/runtime/emit/bloom-join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAkC,MAAM,aAAa,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAS9D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,GAAG,WAAW,CA+HpF"}

package/dist/src/runtime/emit/bloom-join.js

@@ -36,27 +36,39 @@ export function emitBloomJoin(plan, ctx) {
     const rightColCount = rightAttributes.length;
     async function* run(rctx, leftSource, rightSource, residualCallback) {
         log('Starting %s hash join: %d equi-pairs, %d left attrs, %d right attrs', plan.joinType.toUpperCase(), plan.equiPairs.length, leftAttributes.length, rightAttributes.length);
-        // === Build phase: materialize right side into hash map ===
-        const hashMap = new Map();
-        for await (const rightRow of rightSource) {
-            const key = serializeRowKey(rightRow, rightIndices, keyNormalizers);
-            if (key === null)
-                continue; // null keys can't match
-            const bucket = hashMap.get(key);
-            if (bucket) {
-                bucket.push(rightRow);
-            }
-            else {
-                hashMap.set(key, [rightRow]);
-            }
-        }
-        log('Build phase complete: %d buckets, right side materialized', hashMap.size);
-        // === Probe phase: stream left side, probe hash map ===
+        // Acquire the left (probe) iterator up front. When `left` is an
+        // EagerPrefetchNode its pump is already running (it forks `rctx` and
+        // starts on run()), so we MUST guarantee the iterator is closed even if
+        // the build phase throws before the probe loop begins — otherwise the
+        // eager pump leaks (fills its buffer then blocks forever) and its
+        // strict-fork counter stays bumped. The `finally` below covers both
+        // phases for exactly that reason.
+        const leftIter = leftSource[Symbol.asyncIterator]();
         const isSemiOrAnti = plan.joinType === 'semi' || plan.joinType === 'anti';
         const leftSlot = createRowSlot(rctx, leftRowDescriptor);
         const rightSlot = createRowSlot(rctx, rightRowDescriptor);
         try {
-            for await (const leftRow of leftSource) {
+            // === Build phase: materialize right side into hash map ===
+            const hashMap = new Map();
+            for await (const rightRow of rightSource) {
+                const key = serializeRowKey(rightRow, rightIndices, keyNormalizers);
+                if (key === null)
+                    continue; // null keys can't match
+                const bucket = hashMap.get(key);
+                if (bucket) {
+                    bucket.push(rightRow);
+                }
+                else {
+                    hashMap.set(key, [rightRow]);
+                }
+            }
+            log('Build phase complete: %d buckets, right side materialized', hashMap.size);
+            // === Probe phase: stream left side, probe hash map ===
+            while (true) {
+                const next = await leftIter.next();
+                if (next.done)
+                    break;
+                const leftRow = next.value;
                 leftSlot.set(leftRow);
                 const key = serializeRowKey(leftRow, leftIndices, keyNormalizers);
                 let matched = false;
@@ -88,6 +100,15 @@ export function emitBloomJoin(plan, ctx) {
         finally {
             leftSlot.close();
             rightSlot.close();
+            // Close the probe iterator on every exit path (normal completion,
+            // consumer break, throw, or build-phase error) so an eager prefetch
+            // pump is always torn down.
+            try {
+                await leftIter.return?.(undefined);
+            }
+            catch {
+                // Swallow — already in cleanup.
+            }
         }
     }
     const leftInstruction = emitPlanNode(plan.left, ctx);

package/dist/src/runtime/emit/bloom-join.js.map

@@ -1 +1 @@
-{"version":3,"file":"bloom-join.js","sourceRoot":"","sources":["../../../../src/runtime/emit/bloom-join.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bloom-join.js","sourceRoot":"","sources":["../../../../src/runtime/emit/bloom-join.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime/emit/eager-prefetch.d.ts

@@ -0,0 +1,77 @@
+import type { EagerPrefetchNode } from '../../planner/nodes/eager-prefetch-node.js';
+import type { Instruction, RuntimeContext } from '../types.js';
+import type { Row } from '../../common/types.js';
+import type { EmissionContext } from '../emission-context.js';
+import { ParallelDriver } from '../parallel-driver.js';
+/**
+ * Bounded promise-based prefetch buffer used by {@link emitEagerPrefetch}.
+ *
+ * Exactly one producer (the pump) and one consumer (the parent emit's
+ * iterator) operate on this at a time, so a single nullable callback for each
+ * direction is enough — no waiter queues required.
+ *
+ * Exported for unit-test access only.
+ */
+export declare class BoundedPrefetchBuffer<T> {
+    private readonly capacity;
+    private readonly queue;
+    private done;
+    private hasError;
+    private error;
+    private spaceWaiter;
+    private itemWaiter;
+    constructor(capacity: number);
+    get size(): number;
+    /**
+     * Push an item, awaiting space when the buffer is full. Returns false if
+     * the abort signal fired before space became available; otherwise true.
+     */
+    push(item: T, signal: AbortSignal): Promise<boolean>;
+    /**
+     * Wait for an item, end-of-stream marker, or buffered error.
+     * Throws the cached error if {@link fail} was called.
+     */
+    shift(): Promise<{
+        done: true;
+    } | {
+        done: false;
+        value: T;
+    }>;
+    /** Mark end-of-stream; wakes a pending shifter. */
+    close(): void;
+    /** Record a producer error; wakes a pending shifter to throw it. */
+    fail(err: unknown): void;
+}
+/**
+ * Core prefetch primitive. Forks `rctx` and **eagerly** — at call time, before
+ * the consumer's first `next()` — starts a detached pump that drains the child
+ * iterator into a bounded buffer. The returned `AsyncIterable<Row>` hands rows
+ * out of that buffer; its iterator owns teardown via `next()`/`return()`/
+ * `throw()`.
+ *
+ * Eager-on-call is the point: when a `BloomJoinNode` wraps its probe (`left`) in
+ * this, the scheduler invokes `run()` during arg-assembly — before the join's
+ * generator body drains the build (`right`) — so the probe's first fetch is
+ * already in flight while the build materializes.
+ *
+ * Cleanup (abort pump, close buffer, child `return()`, drop strict-fork
+ * counters) fires when the iterator reaches done, `return()`, or `throw()`.
+ * Because the fork counters are bumped at construction, a returned iterable that
+ * is **never iterated** leaks the pump (it fills the buffer then blocks forever)
+ * and leaves the counters bumped — every consumer must guarantee iterate-or-
+ * close. Today the only inserter is `rule-eager-prefetch-probe`, and
+ * `emitBloomJoin` closes the left iterator in a `finally` covering both phases.
+ *
+ * Exported for unit testing — production callers go through {@link emitEagerPrefetch}.
+ */
+export declare function prefetchAsyncIterable(rctx: RuntimeContext, sourceCallback: (innerCtx: RuntimeContext) => AsyncIterable<Row>, bufferSize: number, driver?: ParallelDriver): AsyncIterable<Row>;
+/**
+ * Emit an EagerPrefetchNode: forks the runtime context and immediately starts
+ * pumping the child sub-tree into a bounded buffer, yielding rows from that
+ * buffer to the parent emit.
+ *
+ * The pump starts on `run()` (emit / scheduler arg-assembly), not on the
+ * consumer's first `next()`.
+ */
+export declare function emitEagerPrefetch(plan: EagerPrefetchNode, ctx: EmissionContext): Instruction;
+//# sourceMappingURL=eager-prefetch.d.ts.map

package/dist/src/runtime/emit/eager-prefetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eager-prefetch.d.ts","sourceRoot":"","sources":["../../../../src/runtime/emit/eager-prefetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAkB,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,cAAc,EAAgD,MAAM,uBAAuB,CAAC;AAErG;;;;;;;;GAQG;AACH,qBAAa,qBAAqB,CAAC,CAAC;IAQvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAPrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,UAAU,CAA6B;gBAElB,QAAQ,EAAE,MAAM;IAM7C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB1D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAmBlE,mDAAmD;IACnD,KAAK,IAAI,IAAI;IAQb,oEAAoE;IACpE,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;CAQxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,cAAc,EACpB,cAAc,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,aAAa,CAAC,GAAG,CAAC,EAChE,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,cAAqC,GAC3C,aAAa,CAAC,GAAG,CAAC,CA2EpB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,eAAe,GAAG,WAAW,CAkB5F"}

package/dist/src/runtime/emit/eager-prefetch.js

@@ -0,0 +1,223 @@
+import { emitCallFromPlan } from '../emitters.js';
+import { ParallelDriver, bumpParentForkCounter, dropParentForkCounter } from '../parallel-driver.js';
+/**
+ * Bounded promise-based prefetch buffer used by {@link emitEagerPrefetch}.
+ *
+ * Exactly one producer (the pump) and one consumer (the parent emit's
+ * iterator) operate on this at a time, so a single nullable callback for each
+ * direction is enough — no waiter queues required.
+ *
+ * Exported for unit-test access only.
+ */
+export class BoundedPrefetchBuffer {
+    capacity;
+    queue = [];
+    done = false;
+    hasError = false;
+    error;
+    spaceWaiter = null;
+    itemWaiter = null;
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError(`BoundedPrefetchBuffer: capacity must be a positive integer, got ${capacity}`);
+        }
+    }
+    get size() {
+        return this.queue.length;
+    }
+    /**
+     * Push an item, awaiting space when the buffer is full. Returns false if
+     * the abort signal fired before space became available; otherwise true.
+     */
+    async push(item, signal) {
+        while (this.queue.length >= this.capacity && !this.done && !this.hasError && !signal.aborted) {
+            await new Promise(resolve => {
+                this.spaceWaiter = resolve;
+                const onAbort = () => {
+                    const r = this.spaceWaiter;
+                    this.spaceWaiter = null;
+                    if (r)
+                        r();
+                };
+                if (signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+        }
+        if (signal.aborted || this.done || this.hasError)
+            return false;
+        this.queue.push(item);
+        const w = this.itemWaiter;
+        this.itemWaiter = null;
+        if (w)
+            w();
+        return true;
+    }
+    /**
+     * Wait for an item, end-of-stream marker, or buffered error.
+     * Throws the cached error if {@link fail} was called.
+     */
+    async shift() {
+        while (this.queue.length === 0 && !this.done && !this.hasError) {
+            await new Promise(resolve => {
+                this.itemWaiter = resolve;
+            });
+        }
+        if (this.queue.length > 0) {
+            const value = this.queue.shift();
+            const w = this.spaceWaiter;
+            this.spaceWaiter = null;
+            if (w)
+                w();
+            return { done: false, value };
+        }
+        if (this.hasError) {
+            throw this.error;
+        }
+        return { done: true };
+    }
+    /** Mark end-of-stream; wakes a pending shifter. */
+    close() {
+        if (this.done || this.hasError)
+            return;
+        this.done = true;
+        const w = this.itemWaiter;
+        this.itemWaiter = null;
+        if (w)
+            w();
+    }
+    /** Record a producer error; wakes a pending shifter to throw it. */
+    fail(err) {
+        if (this.done || this.hasError)
+            return;
+        this.hasError = true;
+        this.error = err;
+        const w = this.itemWaiter;
+        this.itemWaiter = null;
+        if (w)
+            w();
+    }
+}
+/**
+ * Core prefetch primitive. Forks `rctx` and **eagerly** — at call time, before
+ * the consumer's first `next()` — starts a detached pump that drains the child
+ * iterator into a bounded buffer. The returned `AsyncIterable<Row>` hands rows
+ * out of that buffer; its iterator owns teardown via `next()`/`return()`/
+ * `throw()`.
+ *
+ * Eager-on-call is the point: when a `BloomJoinNode` wraps its probe (`left`) in
+ * this, the scheduler invokes `run()` during arg-assembly — before the join's
+ * generator body drains the build (`right`) — so the probe's first fetch is
+ * already in flight while the build materializes.
+ *
+ * Cleanup (abort pump, close buffer, child `return()`, drop strict-fork
+ * counters) fires when the iterator reaches done, `return()`, or `throw()`.
+ * Because the fork counters are bumped at construction, a returned iterable that
+ * is **never iterated** leaks the pump (it fills the buffer then blocks forever)
+ * and leaves the counters bumped — every consumer must guarantee iterate-or-
+ * close. Today the only inserter is `rule-eager-prefetch-probe`, and
+ * `emitBloomJoin` closes the left iterator in a `finally` covering both phases.
+ *
+ * Exported for unit testing — production callers go through {@link emitEagerPrefetch}.
+ */
+export function prefetchAsyncIterable(rctx, sourceCallback, bufferSize, driver = new ParallelDriver()) {
+    const [forkCtx] = driver.fork(rctx, 1);
+    // Manually bump strict-fork bookkeeping (ParallelDriver.drive does this
+    // internally, but we are using fork() directly). The fork is "live" from
+    // construction — that is the intended eager semantics.
+    const parentTableState = bumpParentForkCounter(forkCtx.tableContexts);
+    const parentRowState = bumpParentForkCounter(forkCtx.context);
+    const childIter = sourceCallback(forkCtx)[Symbol.asyncIterator]();
+    const buf = new BoundedPrefetchBuffer(bufferSize);
+    const abort = new AbortController();
+    // EAGER: start the pump now, not on first next().
+    const pump = (async () => {
+        try {
+            while (!abort.signal.aborted) {
+                const r = await childIter.next();
+                if (r.done) {
+                    buf.close();
+                    return;
+                }
+                const ok = await buf.push(r.value, abort.signal);
+                if (!ok)
+                    return;
+            }
+        }
+        catch (e) {
+            buf.fail(e);
+        }
+    })();
+    // Detach; awaited in cleanup for clean shutdown.
+    void pump;
+    let cleanedUp = false;
+    const cleanup = async () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        abort.abort();
+        buf.close();
+        try {
+            await childIter.return?.(undefined);
+        }
+        catch {
+            // Swallow — already in cleanup.
+        }
+        await pump.catch(() => undefined);
+        dropParentForkCounter(parentTableState);
+        dropParentForkCounter(parentRowState);
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    try {
+                        const item = await buf.shift();
+                        if (item.done) {
+                            await cleanup();
+                            return { done: true, value: undefined };
+                        }
+                        return { done: false, value: item.value };
+                    }
+                    catch (e) {
+                        await cleanup();
+                        throw e;
+                    }
+                },
+                async return(value) {
+                    await cleanup();
+                    return { done: true, value: value };
+                },
+                async throw(err) {
+                    await cleanup();
+                    throw err;
+                },
+            };
+        },
+    };
+}
+/**
+ * Emit an EagerPrefetchNode: forks the runtime context and immediately starts
+ * pumping the child sub-tree into a bounded buffer, yielding rows from that
+ * buffer to the parent emit.
+ *
+ * The pump starts on `run()` (emit / scheduler arg-assembly), not on the
+ * consumer's first `next()`.
+ */
+export function emitEagerPrefetch(plan, ctx) {
+    const driver = new ParallelDriver();
+    const bufferSize = plan.bufferSize;
+    function run(rctx, sourceCallback) {
+        return prefetchAsyncIterable(rctx, sourceCallback, bufferSize, driver);
+    }
+    const sourceInstruction = emitCallFromPlan(plan.source, ctx);
+    return {
+        params: [sourceInstruction],
+        run: run,
+        note: `eager_prefetch(buffer=${bufferSize})`,
+    };
+}
+//# sourceMappingURL=eager-prefetch.js.map