@jarenjs/linq 0.49.2 → 0.66.1

package/src/async.js

@@ -24,6 +24,15 @@
  *  - `mapAsync` applies the bounded-concurrency machinery between
  *    segments; it is NOT translatable to a document, so `toDocument()`
  *    refuses (`JL0005`) and `explain()` reports the split.
+ *  - a PROVIDER origin (`fromAsync(store.entity('Post'))`) runs nothing
+ *    here: everything up to the first `mapAsync` is ONE document the
+ *    provider executes — a terminal's wrapper included, exactly as the
+ *    synchronous surface pushes it, `execute` answering a promise if it
+ *    must (D8). Iteration hands that document to the provider's CURSOR
+ *    when it offers one, so a `for await` pulls one row at a time from
+ *    an open statement and a `break` releases it; the residual after
+ *    the split streams locally, and a `join` exists on this surface
+ *    only inside that pushed document.
  *
  * Early termination CLOSES the source: every consumer is a
  * `for await … break` chain, and async generators propagate `return()`
@@ -31,20 +40,31 @@
  * read transaction open.
  */
 
-import { compileDocument } from './provider.js';
-import { emitDocument, wrapTerminal } from './document.js';
+import {
+  compileDocument, isProviderSource, providerRoot, providerRelations, sharesScope,
+} from './provider.js';
+import {
+  emitDocument, wrapTerminal, snapshot, fanProjection, isReservedBinding, RESERVED_BINDINGS_TEXT,
+  PROJECTING_STAGES,
+} from './document.js';
 import { adaptAsyncSource } from './sources.js';
 import { applyMapAsync, normalizeMapAsyncOptions } from './concurrency.js';
-import { captureExpression, toExpression } from './expression.js';
+import {
+  captureExpression, toExpression, requireJsonBinding, createHopSink, rowRoot, groupRoot,
+} from './expression.js';
 import { LinqBuildError, LinqRuntimeError } from './errors.js';
+import { schemaOf } from './schema-of.js';
 import { semanticKey } from '@jarenjs/core/object';
 
-/** Barrier stage kinds and the reason each materialises. */
+/** Barrier stage kinds and the reason each materialises. A `join` is
+ * never a barrier: over a provider it rides INSIDE the one pushed
+ * document (the only place this surface joins), and over a single-pass
+ * source — a cursor, a queue, a stream — it is refused, because the
+ * inner side would have to read the source twice (QUERY-PEN.md §10). */
 const BARRIERS = {
   orderBy: '$orderby materialises the tuple stream to sort it',
   thenBy: '$orderby materialises the tuple stream to sort it',
   groupBy: '$groupby materialises the tuple stream to group it',
-  join: 'a join needs the whole inner side',
   aggregate: '$fold folds the whole stream into one value',
   reverse: '$reverse needs the last item first',
 };
@@ -85,24 +105,72 @@ export class AsyncSequence {
   #stages;
   #params;
   #options;
+  #relations;
 
   /**
    * @param {{ kind: 'source', iterate: () => AsyncIterator<any> }
-   *   | { kind: 'sequence', runPrefix: () => any[], prefixDocument: () => any }} origin
+   *   | { kind: 'provider', source: any, root: string }
+   *   | { kind: 'sequence', runPrefix: (params: ReadonlyMap<string, any>) => any[],
+   *       prefixDocument: () => any }} origin
    * @param {readonly any[]} stages
    * @param {ReadonlyMap<string, any>} params
-   * @param {{ compileTypeTest?: any }} options
+   * @param {{ compileTypeTest?: any, functions?: any, collations?: any,
+   *   pathFunctions?: any, limits?: any, registry?: object }} options
+   * @param {{ table: any, resolve: (name: string) => any } | null} [relations] -
+   *   the relation table of the rows the items ARE (a provider's, while
+   *   no stage has projected them), or null — as on the sync surface
    */
-  constructor(origin, stages, params, options) {
+  constructor(origin, stages, params, options, relations = null) {
     this.#origin = origin;
     this.#stages = stages;
     this.#params = params;
     this.#options = options;
+    this.#relations = relations;
   }
 
-  /** @param {any} stage */
-  #with(stage) {
-    return new AsyncSequence(this.#origin, [...this.#stages, stage], this.#params, this.#options);
+  /** @param {any} stage @param {ReadonlyMap<string, any>} [params] */
+  #with(stage, params = this.#params) {
+    // the items stop being rows at a projection, and at the host boundary
+    const projects = PROJECTING_STAGES.has(stage.kind) || stage.kind === 'mapAsync';
+    return new AsyncSequence(this.#origin, [...this.#stages, stage], params, this.#options,
+      projects ? null : this.#relations);
+  }
+
+  /**
+   * Capture one callback over this sequence's items — the expression and
+   * the relation hops it navigated — exactly as the synchronous surface
+   * does, so the two emit one document.
+   * @param {any} fn
+   * @param {(sink: ReturnType<typeof createHopSink>) => readonly any[]} [rootsOf]
+   * @returns {{ expression: any, hops: readonly any[] }}
+   */
+  #capture(fn, rootsOf = (sink) => [this.#rowRoot('it', sink)]) {
+    if (typeof fn !== 'function') {
+      throw new LinqBuildError('JL0005', 'this operator takes a callback function');
+    }
+    const sink = createHopSink();
+    const expression = captureExpression(fn, rootsOf(sink), new Set(this.#params.keys()));
+    return { expression, hops: sink.hops };
+  }
+
+  /** Whether this sequence's items are a `groupBy`'s `{ key, items }`,
+   * as on the synchronous surface. */
+  #grouped() {
+    for (let i = this.#stages.length - 1; i >= 0; i--) {
+      const kind = this.#stages[i].kind;
+      if (PROJECTING_STAGES.has(kind) || kind === 'mapAsync') return kind === 'groupBy';
+    }
+    return false;
+  }
+
+  /** @param {string} name @param {ReturnType<typeof createHopSink>} sink */
+  #rowRoot(name, sink) {
+    return rowRoot(name, this.#relations, sink, this.#grouped());
+  }
+
+  /** The relation hops every stage's callbacks navigated, in order. */
+  #hops() {
+    return this.#stages.flatMap((stage) => stage.hops ?? []);
   }
 
   #externals() {
@@ -112,6 +180,57 @@ export class AsyncSequence {
     };
   }
 
+  /** Whether the chain so far goes to a provider as ONE document: a
+   * provider origin with no `mapAsync` yet (D8 — the document arrives
+   * whole; a host callback is where it splits). */
+  #pushable() {
+    return this.#origin.kind === 'provider'
+      && !this.#stages.some((stage) => stage.kind === 'mapAsync');
+  }
+
+  /** Whether this sequence is a provider's own root, untouched — the
+   * one `$for` source the emitter leaves unpacked (document.js). */
+  #isBareRoot() {
+    return this.#origin.kind === 'provider' && this.#stages.length === 0;
+  }
+
+  /** The root expression the stages iterate: a provider's own root, the
+   * pushed synchronous prefix, or the whole input. */
+  #rootExpression() {
+    if (this.#origin.kind === 'sequence') return this.#origin.prefixDocument();
+    return this.#origin.kind === 'provider' ? this.#origin.root : '$[*]';
+  }
+
+  /** The document for a run of stages over this origin's root. */
+  #documentOf(stages) {
+    return emitDocument(this.#rootExpression(), stages,
+      { bareRoot: this.#origin.kind === 'provider' });
+  }
+
+  /** Hand one document to the provider, whole, with the bound
+   * externals; `execute` may answer a value or a promise here. */
+  async #push(document) {
+    return this.#origin.source.execute(document, { externals: this.#externals().values });
+  }
+
+  /** A pushed element window over `stages`: the provider must answer
+   * exactly one array, as on the synchronous surface (`JL2006`). */
+  async #pushWindow(terminal, args = undefined, stages = this.#stages) {
+    const result = await this.#push(wrapTerminal(this.#documentOf(stages), terminal, args));
+    if (!Array.isArray(result)) {
+      throw new LinqRuntimeError('JL2006',
+        `the provider answered ${terminal}() with ${result === undefined ? 'undefined'
+          : `a ${typeof result}`} — an element terminal emits an array constructor, so a `
+        + 'conforming execute() answers exactly one array (QUERY-PEN.md §8)');
+    }
+    return /** @type {any[]} */ (result);
+  }
+
+  /** A pushed aggregate or quantifier over the whole chain. */
+  #pushTerminal(terminal, args = undefined) {
+    return this.#push(wrapTerminal(this.#documentOf(this.#stages), terminal, args));
+  }
+
   /** Compile one per-item evaluator: the stage expression under
    * `{$let: {it: '$'}}` with the terminal-window discipline. */
   #evaluator(returnExpr) {
@@ -124,13 +243,21 @@ export class AsyncSequence {
 
   where(predicate) { return this.#chainCaptured('where', 'predicate', predicate); }
   select(projection) { return this.#chainCaptured('select', 'projection', projection); }
-  selectMany(selector) { return this.#chainCaptured('select', 'projection', selector); }
+  selectMany(selector) {
+    const { expression, hops } = this.#capture(selector);
+    return this.#with({
+      kind: 'select', name: 'selectMany',
+      projection: fanProjection(expression),
+      hops,
+    });
+  }
 
   /** @param {string} kind @param {string} slot @param {any} fn */
   #chainCaptured(kind, slot, fn) {
     // reuse the sync Sequence's capture through a local import-free
     // seam: capture lives in expression.js and is stage-agnostic
-    return this.#with({ kind, [slot]: captureFor(this.#params, fn) });
+    const { expression, hops } = this.#capture(fn);
+    return this.#with({ kind, [slot]: expression, hops });
   }
 
   orderBy(key, options) { return this.#orderStage('orderBy', key, false, options); }
@@ -139,25 +266,109 @@ export class AsyncSequence {
   thenByDescending(key, options) { return this.#orderStage('thenBy', key, true, options); }
 
   #orderStage(kind, key, desc, options) {
-    const spec = { $key: captureFor(this.#params, key) };
+    const { expression, hops } = this.#capture(key);
+    const spec = { $key: expression };
     if (desc) spec.$dir = 'desc';
     if (options !== undefined) {
       if (options.empty !== undefined) spec.$empty = options.empty;
       if (options.collation !== undefined) spec.$collation = options.collation;
     }
-    return this.#with({ kind, spec });
+    return this.#with({ kind, name: desc ? `${kind}Descending` : kind, spec, hops });
   }
 
-  groupBy(key) { return this.#with({ kind: 'groupBy', key: captureFor(this.#params, key) }); }
+  groupBy(key) {
+    const { expression, hops } = this.#capture(key);
+    return this.#with({ kind: 'groupBy', key: expression, hops });
+  }
 
   aggregate(seed, step) {
+    const { expression, hops } = this.#capture(step, (sink) => ['acc', this.#rowRoot('it', sink)]);
     return this.#with({
       kind: 'aggregate',
       seed: toExpression(seed),
-      step: captureFor(this.#params, step, ['acc', 'it']),
+      step: expression,
+      hops,
     });
   }
 
+  /** The inner side of a join, checked (QUERY-PEN.md §10): a join on
+   * this surface rides INSIDE the one document a provider receives, so
+   * it needs a provider origin with no `mapAsync` before it, an async
+   * sequence over the same provider (or one sharing its scope) as the
+   * inner side, and — as on the synchronous surface — one binding per
+   * parameter name across the two sides. Over a single-pass source there
+   * is no join: the inner side would read the source twice.
+   * @param {any} inner @param {string} what
+   * @returns {ReadonlyMap<string, any>} the merged parameter bindings */
+  #requireJoinable(inner, what) {
+    if (!this.#pushable()) {
+      throw new LinqBuildError('JL0005',
+        `${what} on the async surface is pushed whole to a provider — it needs a provider `
+        + 'source and comes before any mapAsync; over an iterable, a cursor or a push queue '
+        + 'there is no join, because a single-pass source cannot be read twice (QUERY-PEN.md §10)');
+    }
+    if (!(inner instanceof AsyncSequence) || !inner.#pushable()) {
+      throw new LinqBuildError('JL0005',
+        `${what} takes another async sequence over a provider (with no mapAsync) as its inner side`);
+    }
+    if (!sharesScope(this.#origin.source, inner.#origin.source)) {
+      throw new LinqBuildError('JL0005',
+        `${what}'s other side must derive from the same source, or from two providers sharing `
+        + "one scope (one store's entity sets) — a query document reads one input");
+    }
+    const merged = new Map(this.#params);
+    for (const [name, value] of inner.#params) {
+      if (merged.has(name) && merged.get(name) !== value) {
+        throw new LinqBuildError('JL0004',
+          `parameter '${name}' is bound to different values by the two sides of ${what} — `
+          + 'one document carries one binding per name; bind it once, or rename one side');
+      }
+      merged.set(name, value);
+    }
+    return merged;
+  }
+
+  /** Equi-join, pushed whole: the nested-`$for` shape the synchronous
+   * surface emits (a store answers a two-root join in one statement);
+   * the inner rows keep their relation table under `it2`. */
+  join(inner, outerKey, innerKey, result) {
+    const params = this.#requireJoinable(inner, 'join');
+    const outer = this.#capture(outerKey);
+    const key = this.#capture(innerKey, (sink) => [inner.#rowRoot('it2', sink)]);
+    const projection = this.#capture(result,
+      (sink) => [this.#rowRoot('it', sink), inner.#rowRoot('it2', sink)]);
+    return this.#with({
+      kind: 'join',
+      inner: inner.toDocument(),
+      innerBare: inner.#isBareRoot(),
+      on: { $eq: [outer.expression, key.expression] },
+      result: projection.expression,
+      hops: [...inner.#hops(), ...outer.hops, ...key.hops, ...projection.hops],
+    }, params);
+  }
+
+  /** Group-join, pushed whole: the `$let`-bound group of the synchronous
+   * surface, under the same rule as `join`. */
+  groupJoin(inner, outerKey, innerKey, result) {
+    const params = this.#requireJoinable(inner, 'groupJoin');
+    const innerDoc = inner.toDocument();
+    const outer = this.#capture(outerKey);
+    const key = this.#capture(innerKey, (sink) => [inner.#rowRoot('it2', sink)]);
+    const group = {
+      $for: { it2: inner.#isBareRoot() ? innerDoc : [innerDoc] },
+      $where: { $eq: [outer.expression, key.expression] },
+      $return: '$it2',
+    };
+    const projection = this.#capture(result,
+      (sink) => [this.#rowRoot('it', sink), groupRoot(inner.#relations, sink)]);
+    return this.#with({
+      kind: 'groupJoin',
+      group,
+      projection: projection.expression,
+      hops: [...inner.#hops(), ...outer.hops, ...key.hops, ...projection.hops],
+    }, params);
+  }
+
   skip(count) { return this.#with({ kind: 'skip', count: requireIndex(count, 'skip') }); }
   take(count) { return this.#with({ kind: 'take', count: requireIndex(count, 'take') }); }
   distinct() { return this.#with({ kind: 'distinct' }); }
@@ -170,26 +381,30 @@ export class AsyncSequence {
       throw new LinqBuildError('JL0005',
         'concat on an async sequence takes a constant array — an async source cannot be re-iterated for a second sequence');
     }
+    // the JSON boundary (§5) and one copy at build time: the stage owns
+    // its constants, and hands out a fresh copy per enumeration
+    const items = toExpression(other).$const;
     return this.#with({
       kind: 'concat',
-      other: { $for: { it: { $const: other } }, $return: '$it' },
-      items: other,
+      other: { $for: { it: { $const: items } }, $return: '$it' },
+      items,
     });
   }
 
   defaultIfEmpty(fallback = null) {
-    return this.#with({ kind: 'defaultIfEmpty', fallback: toExpression(fallback), value: fallback });
+    const expr = toExpression(fallback);
+    return this.#with({ kind: 'defaultIfEmpty', fallback: expr, value: expr?.$const ?? fallback });
   }
 
-  ofType(schema) { return this.#with({ kind: 'ofType', schema }); }
-  cast(schema) { return this.#with({ kind: 'cast', schema }); }
+  ofType(schema) { return this.#with({ kind: 'ofType', schema: schemaOf(schema) }); }
+  cast(schema) { return this.#with({ kind: 'cast', schema: schemaOf(schema) }); }
 
   zip() {
     throw new LinqBuildError('JL0006',
-      'zip is unsupported: the query grammar has no positional co-iteration (see LINQ-FORMAT.md §4)');
+      'zip is unsupported: the query grammar has no positional co-iteration (see QUERY-PEN.md §4)');
   }
 
-  /** The bounded-concurrency boundary (LINQ-FORMAT.md §11). */
+  /** The bounded-concurrency boundary (QUERY-PEN.md §11). */
   mapAsync(fn, options) {
     if (typeof fn !== 'function') {
       throw new LinqBuildError('JL0005', 'mapAsync takes an async callback');
@@ -200,8 +415,11 @@ export class AsyncSequence {
   params(bindings) {
     validateParams(bindings);
     const merged = new Map(this.#params);
-    for (const name of Object.keys(bindings)) merged.set(name, bindings[name]);
-    return new AsyncSequence(this.#origin, this.#stages, merged, this.#options);
+    for (const name of Object.keys(bindings)) {
+      requireJsonBinding(name, bindings[name]);
+      merged.set(name, bindings[name]);
+    }
+    return new AsyncSequence(this.#origin, this.#stages, merged, this.#options, this.#relations);
   }
 
   //#endregion
@@ -209,38 +427,58 @@ export class AsyncSequence {
   //#region documents and reporting
 
   /** The chain as one query document — refuses when a `mapAsync` sits
-   * in the chain, because a host callback has no document form. */
+   * in the chain, because a host callback has no document form. A deep
+   * snapshot, as on the sync surface: the emitted tree embeds the
+   * stages' captured expressions, and handing those out by reference
+   * made the document a live window into an immutable sequence. */
   toDocument() {
     if (this.#stages.some((s) => s.kind === 'mapAsync')) {
       throw new LinqBuildError('JL0005',
         'toDocument() cannot represent mapAsync (a host callback); explain() reports the split');
     }
-    const root = this.#origin.kind === 'sequence'
-      ? this.#origin.prefixDocument()
-      : '$[*]';
-    return emitDocument(root, this.#stages);
+    return snapshot(this.#documentOf(this.#stages));
   }
 
-  /** Barriers, the split, and — when representable — the document. */
+  /** Barriers, the split, the relation hops the callbacks navigated,
+   * and — when representable — the document; plus `streaming` and
+   * `barrier`, what this surface's own execution does. Stages are named
+   * by the OPERATOR the caller wrote (`selectMany`, `orderByDescending`),
+   * and a `thenBy` is part of the `$orderby` barrier it extends, not a
+   * barrier of its own. */
   explain() {
+    const firstMap = this.#stages.findIndex((s) => s.kind === 'mapAsync');
+    // over a provider nothing before the split materialises HERE — the
+    // provider runs the pushed document — so only the residual can hold
+    // a barrier of this surface's own
+    const local = this.#origin.kind === 'provider'
+      ? (firstMap < 0 ? [] : this.#stages.slice(firstMap))
+      : this.#stages;
     const barriers = [];
-    for (const stage of this.#stages) {
-      if (BARRIERS[stage.kind] !== undefined) {
-        barriers.push({ operator: stage.kind, reason: BARRIERS[stage.kind] });
+    for (const stage of local) {
+      if (BARRIERS[stage.kind] !== undefined && stage.kind !== 'thenBy') {
+        barriers.push({ operator: stage.name ?? stage.kind, reason: BARRIERS[stage.kind] });
       }
     }
-    const firstMap = this.#stages.findIndex((s) => s.kind === 'mapAsync');
-    const out = { barriers };
+    // what THIS surface does with the item stream: one item at a time,
+    // or a buffer at the first local barrier. Over a provider the pushed
+    // document's own class — a set residual, an unbindable external — is
+    // the provider's to report: `explain(document, { externals: bindings })`
+    // on the source answers it, and its cursor carries the same answer
+    const first = barriers[0];
+    const out = {
+      barriers,
+      streaming: first === undefined ? 'row' : 'buffered',
+      barrier: first === undefined ? null : { construct: first.operator, reason: first.reason },
+      hops: this.#hops(),
+      bindings: this.#externals().values,
+    };
     if (firstMap < 0) {
       out.document = this.toDocument();
     }
     else {
-      const prefix = this.#stages.slice(0, firstMap);
       out.split = {
-        pushed: this.#origin.kind === 'sequence'
-          ? this.#origin.prefixDocument()
-          : emitDocument('$[*]', prefix),
-        residual: this.#stages.slice(firstMap).map((s) => s.kind),
+        pushed: snapshot(this.#documentOf(this.#stages.slice(0, firstMap))),
+        residual: this.#stages.slice(firstMap).map((s) => s.name ?? s.kind),
       };
     }
     return out;
@@ -254,12 +492,22 @@ export class AsyncSequence {
    * barrier chunks. @returns {AsyncGenerator<any>} */
   async* [Symbol.asyncIterator]() {
     const { names, values } = this.#externals();
-    let stream = this.#origin.kind === 'sequence'
-      ? arrayStream(this.#origin.runPrefix())
-      : this.#origin.iterate();
-
     const stages = this.#stages;
+    let stream;
     let i = 0;
+    if (this.#origin.kind === 'sequence') {
+      stream = arrayStream(this.#origin.runPrefix(this.#params));
+    }
+    else if (this.#origin.kind === 'provider') {
+      // everything up to the first mapAsync is ONE document the provider
+      // runs whole; the residual continues locally over its rows
+      const firstMap = stages.findIndex((s) => s.kind === 'mapAsync');
+      i = firstMap < 0 ? stages.length : firstMap;
+      stream = this.#providerStream(stages.slice(0, i), values);
+    }
+    else {
+      stream = this.#origin.iterate();
+    }
     while (i < stages.length) {
       const stage = stages[i];
       if (BARRIERS[stage.kind] !== undefined) {
@@ -290,6 +538,33 @@ export class AsyncSequence {
     yield* iterateAndClose(stream);
   }
 
+  /**
+   * The pushed window as a STREAM. A provider that offers the cursor
+   * protocol (`cursor(document, options)` — the store's entity sets and
+   * collections do) is handed the unwrapped document and answers one
+   * item per pull from an open statement; the generator's `for await`
+   * releases that statement on break, throw and exhaustion alike,
+   * exactly once. A provider without one keeps the element window it
+   * always had: the `toArray`-wrapped document run whole, its array
+   * iterated — a materialisation, which is what such a provider can do.
+   * @param {readonly any[]} stages - the stages up to the split
+   * @param {Record<string, any>} values - the bound externals
+   * @returns {AsyncIterator<any>}
+   */
+  #providerStream(stages, values) {
+    const source = this.#origin.source;
+    if (typeof source.cursor === 'function') {
+      return source.cursor(this.#documentOf(stages), { externals: values });
+    }
+    return this.#materializedWindow(stages);
+  }
+
+  /** The legacy element window, iterated: one `toArray` push, run whole.
+   * @param {readonly any[]} stages */
+  async* #materializedWindow(stages) {
+    yield* await this.#pushWindow('toArray', undefined, stages);
+  }
+
   /** @param {AsyncIterator<any>} stream @param {any} stage @param {any} values */
   #applyStreamStage(stream, stage, values) {
     const self = this;
@@ -360,9 +635,12 @@ export class AsyncSequence {
         })();
       }
       case 'concat': {
+        // a fresh copy per enumeration: a consumer that writes into a
+        // yielded constant must not rewrite what the next enumeration
+        // answers (the sync surface hands out the engine's frozen values)
         return (async function* () {
           yield* iterateAndClose(stream);
-          yield* stage.items;
+          for (const item of stage.items) yield snapshot(item);
         })();
       }
       default: { // 'defaultIfEmpty'
@@ -373,13 +651,18 @@ export class AsyncSequence {
             any = true;
             yield item;
           }
-          if (!any) yield stage.value ?? null;
+          if (!any) yield snapshot(stage.value ?? null);
         })();
       }
     }
   }
 
+  /** The whole result as one array. Over a provider with no `mapAsync`
+   * this is ONE pushed window — the terminal asked for the array, so the
+   * store answers it in one statement rather than one row at a time;
+   * everywhere else it drains the item stream. */
   async toArray() {
+    if (this.#pushable()) return this.#pushWindow('toArray');
     return collect(this[Symbol.asyncIterator]());
   }
 
@@ -394,19 +677,19 @@ export class AsyncSequence {
   }
 
   async first() {
-    const w = await this.#window(1);
+    const w = this.#pushable() ? await this.#pushWindow('first') : await this.#window(1);
     if (w.length === 0) throw new LinqRuntimeError('JL2001', 'first() found no element');
     return w[0];
   }
 
   /** @param {any} [defaultValue] */
   async firstOrDefault(defaultValue) {
-    const w = await this.#window(1);
+    const w = this.#pushable() ? await this.#pushWindow('first') : await this.#window(1);
     return w.length === 0 ? defaultValue : w[0];
   }
 
   async single() {
-    const w = await this.#window(2);
+    const w = this.#pushable() ? await this.#pushWindow('single') : await this.#window(2);
     if (w.length === 0) throw new LinqRuntimeError('JL2001', 'single() found no element');
     if (w.length > 1) throw new LinqRuntimeError('JL2002', 'single() found more than one element');
     return w[0];
@@ -414,27 +697,34 @@ export class AsyncSequence {
 
   /** @param {any} [defaultValue] */
   async singleOrDefault(defaultValue) {
-    const w = await this.#window(2);
+    const w = this.#pushable() ? await this.#pushWindow('single') : await this.#window(2);
     if (w.length > 1) throw new LinqRuntimeError('JL2002', 'singleOrDefault() found more than one element');
     return w.length === 0 ? defaultValue : w[0];
   }
 
   async last() {
-    const all = await this.toArray();
-    if (all.length === 0) throw new LinqRuntimeError('JL2001', 'last() found no element');
-    return all[all.length - 1];
+    const w = this.#pushable() ? await this.#pushWindow('last') : await this.#lastWindow();
+    if (w.length === 0) throw new LinqRuntimeError('JL2001', 'last() found no element');
+    return w[0];
   }
 
   /** @param {any} [defaultValue] */
   async lastOrDefault(defaultValue) {
+    const w = this.#pushable() ? await this.#pushWindow('last') : await this.#lastWindow();
+    return w.length === 0 ? defaultValue : w[0];
+  }
+
+  /** The last item as a window, read from the whole stream. */
+  async #lastWindow() {
     const all = await this.toArray();
-    return all.length === 0 ? defaultValue : all[all.length - 1];
+    return all.length === 0 ? [] : [all[all.length - 1]];
   }
 
   /** @param {number} index */
   async elementAt(index) {
     requireIndex(index, 'elementAt');
-    const w = await this.skip(index).#window(1);
+    const w = this.#pushable()
+      ? await this.#pushWindow('elementAt', [index]) : await this.skip(index).#window(1);
     if (w.length === 0) throw new LinqRuntimeError('JL2003', `elementAt(${index}) is out of range`);
     return w[0];
   }
@@ -442,11 +732,13 @@ export class AsyncSequence {
   /** @param {number} index @param {any} [defaultValue] */
   async elementAtOrDefault(index, defaultValue) {
     requireIndex(index, 'elementAtOrDefault');
-    const w = await this.skip(index).#window(1);
+    const w = this.#pushable()
+      ? await this.#pushWindow('elementAt', [index]) : await this.skip(index).#window(1);
     return w.length === 0 ? defaultValue : w[0];
   }
 
   async count() {
+    if (this.#pushable()) return this.#pushTerminal('count');
     let n = 0;
     // eslint-disable-next-line no-unused-vars
     for await (const item of this) n++;
@@ -457,6 +749,7 @@ export class AsyncSequence {
    * their semantics (type errors included) match the sync surface
    * exactly. @param {string} terminal */
   async #aggregateTerminal(terminal) {
+    if (this.#pushable()) return this.#pushTerminal(terminal);
     const items = await this.toArray();
     const { names, values } = this.#externals();
     const compiled = compileDocument(wrapTerminal('$[*]', terminal),
@@ -486,6 +779,11 @@ export class AsyncSequence {
 
   /** @param {any} [predicate] */
   async any(predicate) {
+    if (this.#pushable()) {
+      return predicate === undefined
+        ? this.#pushTerminal('exists')
+        : this.#pushTerminal('some', [this.#capture(predicate).expression]);
+    }
     const seq = predicate === undefined ? this : this.where(predicate);
     for await (const item of seq) {
       void item;
@@ -496,7 +794,8 @@ export class AsyncSequence {
 
   /** @param {any} predicate */
   async all(predicate) {
-    const q = this.#evaluator(captureFor(this.#params, predicate));
+    if (this.#pushable()) return this.#pushTerminal('every', [this.#capture(predicate).expression]);
+    const q = this.#evaluator(this.#capture(predicate).expression);
     for await (const item of this) {
       if (!q.ebv(item, this.#externals().values)) return false;
     }
@@ -541,14 +840,6 @@ function requireIndex(value, what) {
   return value;
 }
 
-/** @param {ReadonlyMap<string, any>} params @param {any} fn @param {readonly any[]} [roots] */
-function captureFor(params, fn, roots = ['it']) {
-  if (typeof fn !== 'function') {
-    throw new LinqBuildError('JL0005', 'this operator takes a callback function');
-  }
-  return captureExpression(fn, roots, new Set(params.keys()));
-}
-
 /** @param {any} bindings */
 function validateParams(bindings) {
   if (bindings === null || typeof bindings !== 'object' || Array.isArray(bindings)) {
@@ -558,21 +849,31 @@ function validateParams(bindings) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new LinqBuildError('JL0004', `'${name}' is not a valid parameter name`);
     }
-    if (name === 'it' || name === 'it2' || name === 'acc' || name === 'g') {
+    if (isReservedBinding(name)) {
       throw new LinqBuildError('JL0004',
-        `'${name}' is reserved (the emitted document's own binding names: it, it2, acc, g)`);
+        `'${name}' is reserved (the emitted document's own binding names: ${RESERVED_BINDINGS_TEXT})`);
     }
   }
 }
 
 /**
- * Build an async sequence over an async source (LINQ-FORMAT.md §10).
- * @param {any} source - async iterable, sync iterable, cursor or push
- *   queue
- * @param {{ compileTypeTest?: any }} [options]
+ * Build an async sequence over an async source (QUERY-PEN.md §10), or
+ * over a provider (§12): an `execute` duck is asked for BEFORE the
+ * iterable shapes, and its items are bound through its own root — as
+ * `from()` binds them, so the two surfaces emit one document.
+ * @param {any} source - async iterable, sync iterable, cursor, push
+ *   queue, or a provider
+ * @param {{ compileTypeTest?: any, functions?: any, collations?: any,
+ *   pathFunctions?: any, limits?: any, registry?: object }} [options] -
+ *   the engine registries, as `from()` takes them
  * @returns {AsyncSequence}
  */
 export function fromAsync(source, options = {}) {
+  if (isProviderSource(source)) {
+    return new AsyncSequence(
+      { kind: 'provider', source, root: providerRoot(source) },
+      [], new Map(), options, providerRelations(source));
+  }
   return new AsyncSequence(
     { kind: 'source', iterate: adaptAsyncSource(source) },
     [], new Map(), options);
@@ -583,8 +884,9 @@ export function fromAsync(source, options = {}) {
  * PREFIX (compiled in memory or pushed WHOLE to its provider), and the
  * async surface continues locally from its rows. `explain()` reports
  * the split (D8's residual honesty, applied to the async boundary).
- * @param {{ runPrefix: () => any[], prefixDocument: () => any,
- *   params: ReadonlyMap<string, any>, options: { compileTypeTest?: any } }} carrier
+ * @param {{ runPrefix: (params: ReadonlyMap<string, any>) => any[],
+ *   prefixDocument: () => any, params: ReadonlyMap<string, any>,
+ *   options: { compileTypeTest?: any } }} carrier
  * @param {any} fn
  * @param {any} options
  * @returns {AsyncSequence}