@jarenjs/linq 0.49.2 → 0.66.1

package/src/sequence.js

@@ -4,7 +4,7 @@
  * NEW sequence; nothing runs until a terminal operation; a sequence may
  * be enumerated repeatedly and each enumeration re-reads its source —
  * the C# contract, including the part that surprises people
- * (LINQ-FORMAT.md §5 has the worked example).
+ * (QUERY-PEN.md §5 has the worked example).
  *
  * The chain is data: `toDocument()` emits one Jaren query document, and
  * a terminal either compiles it in memory (the reference semantics) or
@@ -13,47 +13,24 @@
  * authorable by a constrained decoder.
  */
 
-import { captureExpression, toExpression } from './expression.js';
-import { emitDocument, wrapTerminal } from './document.js';
-import { classifySource, compileDocument, executeInMemory } from './provider.js';
+import { compileJsonQuery } from '@jarenjs/json/query';
+
+import {
+  captureExpression, toExpression, requireJsonBinding, createHopSink, rowRoot, groupRoot,
+} from './expression.js';
+import {
+  emitDocument, wrapTerminal, snapshot, fanProjection, isReservedBinding, RESERVED_BINDINGS_TEXT,
+  PROJECTING_STAGES,
+} from './document.js';
+import {
+  classifySource, compileDocument, executeInMemory, providerRoot, providerRelations, sharesScope,
+} from './provider.js';
 import { asyncFromSequence } from './async.js';
 import { LinqBuildError, LinqRuntimeError } from './errors.js';
-
-/** Binding names the emitted documents own; parameters may not shadow
- * them (LINQ-FORMAT.md §7). */
-const RESERVED_NAMES = new Set(['it', 'it2', 'acc', 'g']);
+import { schemaOf } from './schema-of.js';
 
 const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-/**
- * A deep, independent copy of an emitted query document. Plain data
- * only, which is exactly what a document is — every captured expression
- * has already passed the JSON-domain boundary in `expression.js`, so
- * there is nothing here a structural copy would lose.
- * @param {any} node
- * @returns {any}
- */
-function snapshot(node) {
-  if (node === null || typeof node !== 'object') return node;
-  if (Array.isArray(node)) return node.map(snapshot);
-  /** @type {Record<string, any>} */
-  const out = {};
-  for (const key of Object.keys(node)) defineOwn(out, key, snapshot(node[key]));
-  return out;
-}
-
-/**
- * Assign an OWN property, so a `__proto__` member stays a member instead
- * of silently replacing the object's prototype and vanishing.
- * @param {Record<string, any>} target
- * @param {string} key
- * @param {any} value
- */
-function defineOwn(target, key, value) {
-  Object.defineProperty(target, key,
-    { value, writable: true, enumerable: true, configurable: true });
-}
-
 /** @param {number} value @param {string} what */
 function requireIndex(value, what) {
   if (!Number.isInteger(value) || value < 0) {
@@ -70,6 +47,7 @@ export class Sequence {
   #stages;
   #params;
   #options;
+  #relations;
 
   /**
    * @param {any} source
@@ -79,61 +57,127 @@ export class Sequence {
    * @param {ReadonlyMap<string, any>} params
    * @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
    */
-  constructor(source, sourceKind, root, stages, params, options) {
+  constructor(source, sourceKind, root, stages, params, options, relations = null) {
     this.#source = source;
     this.#sourceKind = sourceKind;
     this.#root = root;
     this.#stages = stages;
     this.#params = params;
     this.#options = options;
+    this.#relations = relations;
+  }
+
+  /** @param {any} stage @param {ReadonlyMap<string, any>} [params] */
+  #with(stage, params = this.#params) {
+    return new Sequence(this.#source, this.#sourceKind, this.#root,
+      [...this.#stages, stage], params, this.#options,
+      PROJECTING_STAGES.has(stage.kind) ? null : this.#relations);
   }
 
-  /** @param {any} stage */
-  #with(stage) {
+  /** @param {ReadonlyMap<string, any>} params */
+  #rebound(params) {
     return new Sequence(this.#source, this.#sourceKind, this.#root,
-      [...this.#stages, stage], this.#params, this.#options);
+      this.#stages, params, this.#options, this.#relations);
+  }
+
+  /** Whether this sequence's items are a `groupBy`'s `{ key, items }`
+   * — the last stage that reseated them was the grouping. Read from the
+   * stages rather than carried, so it cannot fall out of step with what
+   * the emitter writes. */
+  #grouped() {
+    for (let i = this.#stages.length - 1; i >= 0; i--) {
+      if (PROJECTING_STAGES.has(this.#stages[i].kind)) {
+        return this.#stages[i].kind === 'groupBy';
+      }
+    }
+    return false;
+  }
+
+  /** The `it` (or `it2`) root of a capture over this sequence's items:
+   * an entity's rows carry their relation table, so a relation name
+   * hops; a group's rows carry their member, so `g.items` aggregates as
+   * rows.
+   * @param {string} name @param {ReturnType<typeof createHopSink>} sink */
+  #rowRoot(name, sink) {
+    return rowRoot(name, this.#relations, sink, this.#grouped());
+  }
+
+  /** The group root of a group-join over this sequence's items as the
+   * inner side. @param {ReturnType<typeof createHopSink>} sink */
+  #groupRoot(sink) {
+    return groupRoot(this.#relations, sink);
+  }
+
+  /** The relation hops every stage's callbacks navigated, in order. */
+  #hops() {
+    return this.#stages.flatMap((stage) => stage.hops ?? []);
+  }
+
+  /** Whether this sequence is a provider's own root, untouched — the
+   * one `$for` source the emitter leaves unpacked (document.js). */
+  #isBareRoot() {
+    return this.#sourceKind === 'provider' && this.#stages.length === 0;
   }
 
   #declared() {
     return new Set(this.#params.keys());
   }
 
-  /** @param {(...roots: any[]) => any} fn @param {readonly any[]} roots */
-  #capture(fn, roots = ['it']) {
+  /**
+   * Capture one callback over this sequence's items: the expression and
+   * the relation hops it navigated (one sink per capture, so two roots
+   * of one callback number their hop bindings together).
+   * @param {(...roots: any[]) => any} fn
+   * @param {(sink: ReturnType<typeof createHopSink>) => readonly any[]} [rootsOf] -
+   *   the roots, given the capture's sink; the item root by default
+   * @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');
     }
-    return captureExpression(fn, roots, this.#declared());
+    const sink = createHopSink();
+    const expression = captureExpression(fn, rootsOf(sink), this.#declared());
+    return { expression, hops: sink.hops };
   }
 
   //#region operators (each returns a new immutable Sequence)
 
   /** Filter: `.where(it => it.age.gt(21))` → FLWOR `$where`. */
   where(predicate) {
-    return this.#with({ kind: 'where', predicate: this.#capture(predicate) });
+    const { expression, hops } = this.#capture(predicate);
+    return this.#with({ kind: 'where', predicate: expression, hops });
   }
 
   /** Project: `.select(it => ({ id: it.id }))` → `$return`. */
   select(projection) {
-    return this.#with({ kind: 'select', projection: this.#capture(projection) });
+    const { expression, hops } = this.#capture(projection);
+    return this.#with({ kind: 'select', projection: expression, hops });
   }
 
-  /** Project-and-flatten: a multi-item projection concatenates (the
-   * FLWOR `$return` already flattens per tuple). */
+  /** Project-and-flatten: the projected value is iterated one level
+   * (an array member's elements, a constructed array's members), so
+   * `Seq<R[]>` really answers `Seq<R>`; the FLWOR `$return` then
+   * concatenates per tuple. */
   selectMany(selector) {
-    return this.#with({ kind: 'select', projection: this.#capture(selector) });
+    const { expression, hops } = this.#capture(selector);
+    return this.#with({ kind: 'select', projection: fanProjection(expression), hops });
   }
 
   /** @param {any} key @param {boolean} desc @param {any} [options] */
   #orderStage(kind, key, desc, options) {
-    const spec = { $key: this.#capture(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, spec, hops });
   }
 
   /** Sort ascending → an `$orderby` key spec (`$dir`/`$empty`/
@@ -165,61 +209,108 @@ export class Sequence {
 
   /** Group → `$groupby`; downstream items are `{ key, items }`. */
   groupBy(key) {
-    return this.#with({ kind: 'groupBy', key: this.#capture(key) });
-  }
-
-  /** Both sides read ONE input document in 0.1 — a query document has
-   * one root. Cross-source composition arrives with the relational order.
-   * @param {Sequence} inner @param {string} what */
-  #requireSameSource(inner, what) {
+    const { expression, hops } = this.#capture(key);
+    return this.#with({ kind: 'groupBy', key: expression, hops });
+  }
+
+  /** Both sides read ONE input document — a query document has one
+   * root — so the other side derives from the same source, or (for a
+   * join) from a provider sharing this one's scope: two entity sets of
+   * one store are two roots of ONE multi-entity input, and the store
+   * answers their equijoin in one statement (QUERY-PEN.md §8). A
+   * `concat` stays same-source: its other side contributes an
+   * expression over THIS input, never a second one. Returns the merged
+   * parameter bindings: the inner side's declared externals ride along,
+   * because its document is embedded whole and would otherwise run
+   * against the outer's bindings only — a name both sides bind
+   * differently is `JL0004`, never silently the outer's.
+   * @param {Sequence} inner @param {string} what
+   * @param {boolean} [scoped] - whether a shared provider scope suffices
+   * @returns {ReadonlyMap<string, any>} */
+  #requireSameSource(inner, what, scoped = false) {
     if (!(inner instanceof Sequence)) {
       throw new LinqBuildError('JL0005', `${what} takes another sequence as its inner side`);
     }
-    if (inner.#source !== this.#source) {
+    if (inner.#source !== this.#source && !(scoped && sharesScope(this.#source, inner.#source))) {
       throw new LinqBuildError('JL0005',
-        `${what}'s other side must derive from the same source in 0.1 — `
-        + 'a query document reads one input; load both collections under one root '
-        + '(the relational order lifts this)');
+        `${what}'s other side must derive from the same source`
+        + (scoped ? ", or from two providers sharing one scope (one store's entity sets)" : '')
+        + ' — a query document reads one input; load both collections under one root'
+        + (scoped ? ', or join two entity sets of one store' : ''));
     }
+    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 → nested `$for` + `$where` equality (the engine rewrites
-   * this shape to a hash join; that is why it is fast). */
+   * this shape to a hash join; that is why it is fast). The inner side's
+   * rows keep their relation table under `it2`, so a hop from the joined
+   * row lowers as one from the root does. */
   join(inner, outerKey, innerKey, result) {
-    this.#requireSameSource(inner, 'join');
+    const params = this.#requireSameSource(inner, 'join', true);
+    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(),
-      on: {
-        $eq: [this.#capture(outerKey), this.#capture(innerKey, ['it2'])],
-      },
-      result: this.#capture(result, ['it', 'it2']),
-    });
+      innerBare: inner.#isBareRoot(),
+      on: { $eq: [outer.expression, key.expression] },
+      result: projection.expression,
+      hops: [...inner.#hops(), ...outer.hops, ...key.hops, ...projection.hops],
+    }, params);
   }
 
   /** Group-join: the result selector receives the outer item and the
-   * MATCHING inner group as an expression (`(u, g) => ({ n: g.count() })`). */
+   * MATCHING inner group, bound as an array value (`$let`) so it can be
+   * indexed (`g.at(0)`), fanned (`g.all()`), placed in a member
+   * (`{ matches: g }`) and aggregated over its members
+   * (`(u, g) => ({ n: g.count() })`); the fanned rows keep the inner
+   * side's relation table (`g.all().author`). */
   groupJoin(inner, outerKey, innerKey, result) {
-    this.#requireSameSource(inner, 'groupJoin');
+    const params = this.#requireSameSource(inner, 'groupJoin', true);
+    const innerDoc = inner.toDocument();
+    const outer = this.#capture(outerKey);
+    const key = this.#capture(innerKey, (sink) => [inner.#rowRoot('it2', sink)]);
     const group = {
-      $for: { it2: inner.toDocument() },
-      $where: { $eq: [this.#capture(outerKey), this.#capture(innerKey, ['it2'])] },
+      $for: { it2: inner.#isBareRoot() ? innerDoc : [innerDoc] },
+      $where: { $eq: [outer.expression, key.expression] },
       $return: '$it2',
     };
+    const projection = this.#capture(result,
+      (sink) => [this.#rowRoot('it', sink), inner.#groupRoot(sink)]);
     return this.#with({
-      kind: 'select',
-      projection: this.#capture(result, ['it', { doc: group, pathable: false }]),
-    });
+      kind: 'groupJoin',
+      group,
+      projection: projection.expression,
+      hops: [...inner.#hops(), ...outer.hops, ...key.hops, ...projection.hops],
+    }, params);
   }
 
   /** Seeded fold → `$fold` (the accumulator clause). Only the seeded
    * form exists: JSON has no way to spell an unseeded lambda's implicit
    * first element without one. */
   aggregate(seed, step) {
+    if (typeof seed === 'function' && step === undefined) {
+      throw new LinqBuildError('JL0006',
+        'aggregate(fn) is unsupported: JSON cannot spell the implicit first element as a '
+        + 'lambda seed — pass a seed, aggregate(seed, fn) (see QUERY-PEN.md §4)');
+    }
+    const { expression, hops } = this.#capture(step, (sink) => ['acc', this.#rowRoot('it', sink)]);
     return this.#with({
       kind: 'aggregate',
       seed: toExpression(seed),
-      step: this.#capture(step, ['acc', 'it']),
+      step: expression,
+      hops,
     });
   }
 
@@ -249,17 +340,20 @@ export class Sequence {
    * rows twice instead of concatenating two inputs. */
   concat(other) {
     let expr;
+    let params = this.#params;
     if (other instanceof Sequence) {
-      this.#requireSameSource(other, 'concat');
+      params = this.#requireSameSource(other, 'concat');
       expr = other.toDocument();
     }
     else if (Array.isArray(other)) {
-      expr = { $for: { it: { $const: other } }, $return: '$it' };
+      // the same JSON boundary a captured constant crosses (§5): a Date
+      // or a Map in the array would embed as {} and NaN would fold to null
+      expr = { $for: { it: { $const: toExpression(other).$const } }, $return: '$it' };
     }
     else {
       throw new LinqBuildError('JL0005', 'concat takes a sequence or a constant array');
     }
-    return this.#with({ kind: 'concat', other: expr });
+    return this.#with({ kind: 'concat', other: expr }, params);
   }
 
   /** `$default`: the sequence, or the fallback when it is empty. */
@@ -267,36 +361,40 @@ export class Sequence {
     return this.#with({ kind: 'defaultIfEmpty', fallback: toExpression(fallback) });
   }
 
-  /** Keep only items matching the JSON Schema (`$valid` filter). */
+  /** Keep only items matching the JSON Schema (`$valid` filter) — a
+   * document, or a schema-pen builder, whose document is taken. */
   ofType(schema) {
-    return this.#with({ kind: 'ofType', schema });
+    return this.#with({ kind: 'ofType', schema: schemaOf(schema) });
   }
 
   /** Assert every item against the JSON Schema (`$assert`). */
   cast(schema) {
-    return this.#with({ kind: 'cast', schema });
+    return this.#with({ kind: 'cast', schema: schemaOf(schema) });
   }
 
   /** Cross into the async surface: everything BEFORE this call is the
    * prefix — compiled in memory, or pushed WHOLE to the provider — and
    * `mapAsync` plus everything after runs locally over its rows.
-   * `explain()` on the result reports the split (LINQ-FORMAT.md §11).
+   * `explain()` on the result reports the split (QUERY-PEN.md §11).
    * @param {(item: any, signal: AbortSignal) => any} fn
    * @param {{ concurrency: number, mode?: string, ordered?: boolean }} options */
   mapAsync(fn, options) {
     return asyncFromSequence({
-      runPrefix: () => this.toArray(),
+      // the prefix runs under the bindings the ASYNC sequence holds at
+      // enumeration time — a `params()` after the split rebinds the
+      // whole document, exactly as it would on the sync surface
+      runPrefix: (params) => this.#rebound(params).toArray(),
       prefixDocument: () => this.toDocument(),
       params: this.#params,
       options: this.#options,
     }, fn, options);
   }
 
-  /** Recorded `unsupported` (LINQ-FORMAT.md §4): the grammar has no
+  /** Recorded `unsupported` (QUERY-PEN.md §4): the grammar has no
    * positional co-iteration. */
   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)');
   }
 
   /** Declare (and bind) external parameters: `.params({ tenantId })`.
@@ -312,14 +410,14 @@ export class Sequence {
       if (!VAR_NAME_RE.test(name)) {
         throw new LinqBuildError('JL0004', `'${name}' is not a valid parameter name`);
       }
-      if (RESERVED_NAMES.has(name)) {
+      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})`);
       }
+      requireJsonBinding(name, bindings[name]);
       merged.set(name, bindings[name]);
     }
-    return new Sequence(this.#source, this.#sourceKind, this.#root,
-      this.#stages, merged, this.#options);
+    return this.#rebound(merged);
   }
 
   //#endregion
@@ -336,18 +434,21 @@ export class Sequence {
    * the returned document rewrote the predicate, and the next
    * enumeration answered differently. A snapshot cannot do that. */
   toDocument() {
-    return snapshot(emitDocument(this.#root, this.#stages));
+    return snapshot(emitDocument(this.#root, this.#stages,
+      { bareRoot: this.#sourceKind === 'provider' }));
   }
 
-  /** The compiled view of the chain: the document, its externals and
-   * its dependency sets.
+  /** The compiled view of the chain: the document, its externals, its
+   * dependency sets and the relation hops its callbacks navigated (the
+   * member, the relation's kind and the binding the lowered phrase
+   * ranges over — QUERY-PEN §4, relation navigation).
    *
    * This always explains the IN-MEMORY compilation — it is the reference
    * semantics, and it is not the provider's plan. It cannot report SQL
    * pushdown, index use, residual execution or a strict refusal, and it
    * will fail on an operator or collation only the provider can compile.
    * For a provider's real plan, emit `toDocument()` and call that
-   * provider's own explanation. */
+   * provider's own explanation — a lowered hop is a residual there. */
   explain() {
     const document = this.toDocument();
     const compiled = compileDocument(document, {
@@ -358,6 +459,8 @@ export class Sequence {
       document,
       externals: [...compiled.externals],
       dependencies: compiled.dependencies,
+      hops: this.#hops(),
+      bindings: Object.fromEntries(this.#params),
     };
   }
 
@@ -394,8 +497,17 @@ export class Sequence {
   /** @param {string} terminal @param {readonly any[]} [args] */
   #window(terminal, args) {
     // element terminals emit `[window]`, so the result is always one
-    // array item and element extraction is unambiguous
-    return /** @type {any[]} */ (this.#execute(terminal, args));
+    // array item and element extraction is unambiguous — for a provider
+    // that keeps the contract; one that answers anything else is named,
+    // rather than indexed into a TypeError or an `undefined` typed `T[]`
+    const result = this.#execute(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);
   }
 
   toArray() {
@@ -489,12 +601,12 @@ export class Sequence {
    * @param {(...roots: any[]) => any} [predicate] */
   any(predicate) {
     if (predicate === undefined) return this.#execute('exists');
-    return this.#execute('some', [this.#capture(predicate)]);
+    return this.#execute('some', [this.#capture(predicate).expression]);
   }
 
   /** The `$every` quantifier (vacuously true over the empty sequence). */
   all(predicate) {
-    return this.#execute('every', [this.#capture(predicate)]);
+    return this.#execute('every', [this.#capture(predicate).expression]);
   }
 
   //#endregion
@@ -505,7 +617,10 @@ export class Sequence {
  * happens ONCE, here: an `execute` duck is a provider and is never
  * enumerated locally; any iterable gets the in-memory reference
  * semantics; anything else is `JL0001` now, not at enumeration time.
- * @param {any} source
+ * @param {any} source - an iterable, or a provider; a provider carrying
+ *   `root` binds its items through that root (`'$.Post[*]'` for an entity
+ *   set), one carrying `relations` lets a relation member navigate (§3),
+ *   one carrying `roots` and no `root` of its own is `JL0007`
  * @param {{ compileTypeTest?: any, functions?: any, collations?: any,
  *   pathFunctions?: any, limits?: any, registry?: object }} [options] -
  *   the engine registries this sequence compiles against, under the
@@ -518,13 +633,21 @@ export class Sequence {
  * @returns {Sequence}
  */
 export function from(source, options = {}) {
-  return new Sequence(source, classifySource(source), '$[*]', [], new Map(), options);
+  const kind = classifySource(source);
+  const root = kind === 'provider' ? providerRoot(source) : '$[*]';
+  const relations = kind === 'provider' ? providerRelations(source) : null;
+  return new Sequence(source, kind, root, [], new Map(), options, relations);
 }
 
 /**
  * Attach a hand-written (or stored) query document to a source. The
  * document's result is the item sequence; further operators chain over
- * it. A version envelope is unwrapped so the expression embeds.
+ * it. A version envelope is unwrapped so the expression embeds — only
+ * the envelope this version knows (`{ $query: '0.1', $expr }`, nothing
+ * else); any other spelling is handed to the engine first so its own
+ * verdict (`JQ0006` for a version this consumer does not implement,
+ * `JQ0003` for a stray member) is what surfaces, never a silent run of
+ * a future document as a 0.1 one.
  * @param {any} source - iterable or provider, as `from`
  * @param {any} document - a Jaren query document
  * @param {{ compileTypeTest?: any, functions?: any, collations?: any,
@@ -536,7 +659,14 @@ export function from(source, options = {}) {
 export function fromDocument(source, document, options = {}) {
   let root = document;
   if (root !== null && typeof root === 'object' && !Array.isArray(root)
-    && Object.hasOwn(root, '$expr')) {
+    && (Object.hasOwn(root, '$expr') || Object.hasOwn(root, '$query'))) {
+    const keys = Object.keys(root);
+    const known = root.$query === '0.1' && keys.length === 2 && Object.hasOwn(root, '$expr');
+    if (!known) {
+      compileJsonQuery(root); // the engine's verdict, or —
+      throw new LinqBuildError('JL0005',
+        "a version envelope is exactly { $query: '0.1', $expr: … } (QUERY-FORMAT §4.1)");
+    }
     root = root.$expr;
   }
   return new Sequence(source, classifySource(source), root, [], new Map(), options);

package/src/sources.js

@@ -1,6 +1,6 @@
 //@ts-check
 /**
- * @file Async source adapters (LINQ-FORMAT.md §12): everything
+ * @file Async source adapters (QUERY-PEN.md §12): everything
  * `fromAsync` accepts normalizes to "a factory of async iterators" —
  * a fresh iterator per enumeration, so the deferred re-enumeration
  * contract carries over exactly (a one-shot generator object simply
@@ -12,7 +12,7 @@
  * for feed/end-style readers that have no pull protocol of their own.
  */
 
-import { LinqBuildError } from './errors.js';
+import { LinqBuildError, LinqRuntimeError } from './errors.js';
 
 /**
  * Normalize an async source into an iterator factory, or throw
@@ -25,6 +25,10 @@ export function adaptAsyncSource(source) {
     if (typeof source[Symbol.asyncIterator] === 'function') {
       return () => source[Symbol.asyncIterator]();
     }
+    // a string is refused on purpose: on this surface a string is a
+    // CHUNK source (feed it through a push queue), never a character
+    // stream — `from('abc')` iterates characters, and the twins differ
+    // here by design (QUERY-PEN.md §12)
     if (typeof source[Symbol.iterator] === 'function' && typeof source !== 'string') {
       return () => (async function* () { yield* source; })();
     }
@@ -71,7 +75,10 @@ export function createPushQueue(options = {}) {
 
   return {
     feed(value) {
-      if (ended) throw new LinqBuildError('JL0005', 'feed() after end()');
+      if (ended) {
+        throw new LinqRuntimeError('JL2005',
+          'feed() after end(): the push queue is closed and takes no more values');
+      }
       buffer.push(value);
       signal();
       return buffer.length <= highWaterMark;