@jarenjs/linq 0.46.5 → 0.56.0

package/types/index.d.ts

@@ -14,12 +14,14 @@
 
 /**
  * The nominal date-time brand: annotate a model property as `DateTime`
- * and the date operators (`year()`, `month()`, `day()`, `epoch()`)
- * become available on its expression without making EVERY string a
- * date. Purely a type-level marker — the runtime value is a plain
+ * and the whole §8.13 date family (`year()`, `startOf()`, `dateAdd()`,
+ * `timeBucket()`, …) becomes available on its expression without making
+ * EVERY string a date. Purely a type-level marker — the runtime value is a plain
  * RFC 3339 string; there is no constructor and no runtime cost.
  */
-export type DateTime = string & { readonly __jarenTag: 'date-time' };
+export type DateTime = string & { __jarenTag: 'date-time' };
+
+import type { SchemaBuilder } from './schema.js';
 
 /** The phantom carrier every expression type extends: `__value` never
  * exists at runtime; it lets projections infer their unwrapped shape. */
@@ -59,9 +61,13 @@ export interface NumberExpr extends ExprBase<number>, EqExpr<number> {
   idiv(value: number | NumberExpr): NumberExpr;
   mod(value: number | NumberExpr): NumberExpr;
   neg(): NumberExpr;
+  /** An epoch is a number, so the two instant operators live here too. */
+  datetime(): DateTimeExpr;
+  timeBucket(every: string | number, origin?: string | number | null,
+    context?: CalendarContext): NumberExpr;
 }
 
-export interface StringExpr extends ExprBase<string>, EqExpr<string> {
+export interface StringExpr extends ExprBase<string>, EqExpr<string>, SpatialMethods {
   lt(value: string | StringExpr): BoolExpr;
   le(value: string | StringExpr): BoolExpr;
   gt(value: string | StringExpr): BoolExpr;
@@ -79,35 +85,235 @@ export interface StringExpr extends ExprBase<string>, EqExpr<string> {
   replace(pattern: string, replacement: string): StringExpr;
 }
 
-/** A `DateTime`-branded string: the string surface plus the date
- * component operators. */
-export interface DateTimeExpr extends ExprBase<DateTime> {
+/** A calendar unit, as QUERY-FORMAT §8.13 fixes it. The unit is DATA
+ * rather than vocabulary, so an unknown one is a runtime `JQ2001`; this
+ * type is what keeps the common spelling mistake a compile error. */
+export type DateUnit =
+  | 'year' | 'quarter' | 'month' | 'week' | 'day'
+  | 'hour' | 'minute' | 'second' | 'millisecond';
+
+/** The date family (`$is-date` … `$date-format`), available on any
+ * expression whose value carries a date. Every method lowers to the §8.13
+ * operator of the same name; there is no LINQ-only date semantics. */
+export interface DateMethods {
+  /** Lexical date components; a value with no date half is `JQ2001`. */
+  year(): NumberExpr;
+  month(): NumberExpr;
+  day(): NumberExpr;
+  /** Lexical time components; `seconds` carries its fraction. */
+  hours(): NumberExpr;
+  minutes(): NumberExpr;
+  seconds(): NumberExpr;
+  /** Minutes east of UTC; a bare `full-date` yields the empty sequence. */
+  offset(): NumberExpr;
+  /** ISO 8601 week number, and its week-numbering year. */
+  week(): NumberExpr;
+  weekYear(): NumberExpr;
+  /** Calendar quarter 1-4; ISO weekday 1 (Monday) to 7 (Sunday). */
+  quarter(): NumberExpr;
+  weekday(): NumberExpr;
+  /** Epoch milliseconds (`$epoch`) — the one shift to UTC. */
+  epoch(): NumberExpr;
+  /** The inverse: epoch milliseconds → a canonical UTC `date-time`. */
+  datetime(): DateTimeExpr;
+  /** The RFC 3339 lexical-form predicates; these never raise. */
+  isDate(): BoolExpr;
+  isTime(): BoolExpr;
+  isDatetime(): BoolExpr;
+  isDuration(): BoolExpr;
+  /** Truncate to a unit, keeping the lexical form (`$start-of`/`$end-of`). */
+  startOf(unit: DateUnit): DateTimeExpr;
+  endOf(unit: DateUnit): DateTimeExpr;
+  /** Shift by an ISO 8601 duration, or by an amount and a unit. */
+  dateAdd(duration: string): DateTimeExpr;
+  dateAdd(amount: number | NumberExpr, unit: DateUnit): DateTimeExpr;
+  dateSub(duration: string): DateTimeExpr;
+  dateSub(amount: number | NumberExpr, unit: DateUnit): DateTimeExpr;
+  /** Whole units from this value to another; negative when it precedes. */
+  dateDiff(to: string | DateTimeExpr, unit: DateUnit): NumberExpr;
+  /** Render through a Unicode LDML pattern (`yyyy-MM-dd`). */
+  dateFormat(pattern: string): StringExpr;
+  /** The instant labelling the bucket this one falls in (`$time-bucket`). */
+  timeBucket(every: string | number, origin?: string | number | null,
+    context?: CalendarContext): NumberExpr;
+}
+
+/** A `DateTime`-branded string: the string surface plus the whole §8.13
+ * date family. */
+export interface DateTimeExpr extends ExprBase<DateTime>, DateMethods {
   eq(value: string | DateTimeExpr | null): BoolExpr;
   ne(value: string | DateTimeExpr | null): BoolExpr;
   lt(value: string | DateTimeExpr): BoolExpr;
   le(value: string | DateTimeExpr): BoolExpr;
   gt(value: string | DateTimeExpr): BoolExpr;
   ge(value: string | DateTimeExpr): BoolExpr;
-  year(): NumberExpr;
-  month(): NumberExpr;
-  day(): NumberExpr;
-  /** Epoch milliseconds (`$epoch`). */
-  epoch(): NumberExpr;
 }
 
-export interface ArrayExpr<E> extends ExprBase<E[]> {
+/** The wall clock a calendar boundary falls on (QUERY-FORMAT §8.16).
+ * UTC is the default; a named `zone` needs an injected `zoneProvider`. */
+export interface CalendarContext {
+  zone?: string;
+  offset?: number;
+  disambiguation?: 'reject' | 'earlier' | 'later';
+}
+
+/** The aggregates `$resample` and `$rolling` share. */
+export type SeriesAggregate =
+  'sum' | 'mean' | 'min' | 'max' | 'first' | 'last' | 'count';
+
+/** What an EMPTY bucket says, and nothing else. */
+export type SeriesFill = 'omit' | 'null' | 'zero' | 'locf' | 'linear';
+
+/** A width: an ISO 8601 duration, or a count of milliseconds. */
+export type SeriesSpan = string | number;
+
+/** An instant: epoch milliseconds, or an RFC 3339 string. */
+export type SeriesInstant = string | number;
+
+/** A row selector: a singular path whose `$` is the ROW rather than the
+ * document (`'$.on'`, `"$['recorded at']"`). */
+export type RowSelector = string;
+
+/** The `$resample` spec — a literal, read once when the query compiles. */
+export interface ResampleSpec extends CalendarContext {
+  every: SeriesSpan;
+  origin?: SeriesInstant;
+  start?: SeriesInstant;
+  end?: SeriesInstant;
+  aggregate?: SeriesAggregate;
+  fill?: SeriesFill;
+  at?: RowSelector;
+  value?: RowSelector;
+}
+
+/** The `$rolling` spec — a window measured in time, not in rows. */
+export interface RollingSpec extends CalendarContext {
+  width: SeriesSpan;
+  aggregate?: SeriesAggregate;
+  minPeriods?: number;
+  at?: RowSelector;
+  value?: RowSelector;
+}
+
+/** The `$asof` spec — every member optional: backward, unkeyed, unbounded. */
+export interface AsOfSpec {
+  direction?: 'backward' | 'forward' | 'nearest';
+  tolerance?: SeriesSpan;
+  by?: RowSelector;
+  leftAt?: RowSelector;
+  rightAt?: RowSelector;
+}
+
+/** One canonical sample the series operators answer with. */
+export interface SeriesBucket {
+  at: number;
+  value: number | null;
+  count: number;
+}
+
+/** One row of an as-of join; `right` is `null` when nothing matched, and
+ * the row stays in the answer. */
+export interface AsOfMatch {
+  left: unknown;
+  right: unknown;
+  distance: number | null;
+}
+
+/** A half-open interval: `[start, end)`, in epoch milliseconds. */
+export interface Interval {
+  start: SeriesInstant;
+  end: SeriesInstant;
+}
+
+/** The §8.16 operators that take a whole series and answer another one.
+ * Available wherever a MANY-cardinality expression is (an array member,
+ * or a fanned path). */
+export interface SeriesMethods {
+  /** Sorted `{at, value, count}` buckets, one per `every` (`$resample`). */
+  resample(spec: ResampleSpec): Expr<SeriesBucket[]> & AggregatableExpr;
+  /** One row per input instant, over a window measured in time. */
+  rolling(spec: RollingSpec): Expr<SeriesBucket[]> & AggregatableExpr;
+  /** The right row that was current when each left row happened. */
+  asof(right: ExprBase<unknown> | readonly unknown[], spec?: AsOfSpec):
+    Expr<AsOfMatch[]> & AggregatableExpr;
+}
+
+/** A geometry operand: a GeoJSON geometry or position, a WKT string,
+ * or an expression yielding one. */
+export type GeoOperand = ExprBase<unknown> | object | readonly number[] | string;
+
+/** The §8.14 family, one method per operator, on every expression kind
+ * a geometry can be — a position or bbox array, a GeoJSON object, a WKT
+ * or geohash string — and on the honest top. Measurements are numbers,
+ * cells and text are strings, a bbox and a centroid are positions; a
+ * result that is a geometry stays `UnknownExpr`, because a GeoJSON
+ * shape is not a TypeScript type this surface can promise. */
+export interface SpatialMethods {
+  /** `[west, south, east, north]` of the value's positions. */
+  bbox(): ArrayExpr<number>;
+  /** Square metres of the value's polygons (`$area`). */
+  geoArea(): NumberExpr;
+  /** Metres of the value's lines and ring perimeters (`$length`). */
+  geoLength(): NumberExpr;
+  /** The mean of the value's positions, as a position. */
+  centroid(): ArrayExpr<number>;
+  /** Metres between the two representative positions. */
+  distance(other: GeoOperand): NumberExpr;
+  /** Is this value's representative position inside `region`'s surface? */
+  within(region: GeoOperand): BoolExpr;
+  /** Do the two bounding boxes overlap? Touching edges count. */
+  bboxIntersects(other: GeoOperand): BoolExpr;
+  /** The base-32 geohash cell (precision 1–12, default 9). */
+  geohash(precision?: number | NumberExpr): StringExpr;
+  /** A Well-Known Text string → the geometry it denotes. */
+  geoParse(): UnknownExpr;
+  /** Any value → its Well-Known Text. */
+  geoText(): StringExpr;
+  /** A cell string → the `Polygon` covering that cell. */
+  geohashBounds(): UnknownExpr;
+  /** A cell string → the cell and its neighbours, a SEQUENCE of up to
+   * nine cell strings (aggregate it, or `at()` is not available). */
+  geohashNeighbours(): StringExpr & AggregatableExpr;
+  /** The same value with vertices dropped; the tolerance is in degrees. */
+  geoSimplify(tolerance: number | NumberExpr): UnknownExpr;
+}
+
+export interface ArrayExpr<E> extends ExprBase<E[]>, SeriesMethods, SpatialMethods {
   eq(value: readonly E[] | ArrayExpr<E> | null): BoolExpr;
   ne(value: readonly E[] | ArrayExpr<E> | null): BoolExpr;
+  /** Do two half-open `{start, end}` intervals share an instant?
+   * Touching spans do not. */
+  overlaps(other: Interval | ExprBase<unknown>): BoolExpr;
   /** Fan the elements out (`[*]`) — a MANY-cardinality expression the
-   * aggregates apply to (`u.tags.all().count()`). */
-  all(): Expr<E> & AggregatableExpr;
-  /** The element at a 0-based index; negative counts from the end. */
-  at(index: number): Expr<E>;
-  /** `$count` over the fanned elements requires `all()` first; this
-   * counts the ARRAY as one item — see the format doc. */
+   * aggregates and the §8.16 sequence operators apply to
+   * (`u.tags.all().count()`, `rows.all().resample(spec)`); an object
+   * element's members are fanned with it (`lines.all().amount.sum()`). */
+  all(): FannedExpr<E>;
+  /** The element at a 0-based index; negative counts from the end. A
+   * computed index is an expression — the engine's `$get` — which is
+   * what an app-pen patch path lowers to a `$concat` pointer. */
+  at(index: number | NumberExpr): Expr<E>;
+  /** `$count`. Over a GROUP — a `groupBy`'s `items`, a group-join's
+   * group — this is the number of rows, because the chain knows those
+   * are rows and fans them (QUERY-PEN.md §13.3). Over an array a caller
+   * stored, it counts the array as one item, because at capture time an
+   * array member and a scalar member are the same path: fan it first
+   * (`u.tags.all().count()`), or ask `exists()` what this would
+   * otherwise be answering. */
   count(): NumberExpr;
+  /** Cosine similarity to another vector (§8.15): a captured array
+   * embeds as a literal, a `params()` binding stays an external. Only a
+   * numeric array is a vector. */
+  similarity(this: ArrayExpr<number>, other: readonly number[] | ArrayExpr<number>): NumberExpr;
 }
 
+/** A fanned path (`$.lines[*]`): the element's expression, aggregatable,
+ * and — for an object element — every member is a fanned path too
+ * (`$.lines[*].amount`), so it aggregates without a second `all()`. */
+export type FannedExpr<E> = Expr<E> & AggregatableExpr & SeriesMethods &
+  ([E] extends [readonly unknown[]] ? {} :
+    [E] extends [object] ? { readonly [K in keyof E & string]-?: MemberExpr<E[K]> & AggregatableExpr } : {});
+
 /** Aggregates available on any expression (a fanned path, a group). */
 export interface AggregatableExpr {
   count(): NumberExpr;
@@ -118,15 +324,25 @@ export interface AggregatableExpr {
 }
 
 /** An object's expression: exactly its properties, recursively typed —
- * which is what makes a misspelled member a compile error. */
-export type ObjectExpr<T> = ExprBase<T> & EqExpr<T> & {
-  readonly [K in keyof T & string]-?: Expr<NonNullable<T[K]>>;
+ * which is what makes a misspelled member a compile error. A GeoJSON
+ * object carries the spatial family; a `{ start, end }` object the
+ * interval test. */
+export type ObjectExpr<T> = ExprBase<T> & EqExpr<T> & SpatialMethods & {
+  /** Do two half-open `{start, end}` intervals share an instant? */
+  overlaps(other: Interval | ExprBase<unknown>): BoolExpr;
+} & {
+  readonly [K in keyof T & string]-?: MemberExpr<T[K]>;
 };
 
+/** A member's expression: an `unknown` (or `any`) member is the honest
+ * top, never the first conditional arm `Expr<>` would pick for it. */
+export type MemberExpr<V> = unknown extends V ? UnknownExpr : Expr<NonNullable<V>>;
+
 /** The honest top: everything is available, nothing is precise. Used
  * where inference ends (dynamic `get`, post-operator members, unknown
  * elements) — wide, never wrong. */
-export interface UnknownExpr extends ExprBase<unknown>, AggregatableExpr {
+export interface UnknownExpr
+  extends ExprBase<unknown>, AggregatableExpr, DateMethods, SeriesMethods, SpatialMethods {
   eq(value: unknown): BoolExpr;
   ne(value: unknown): BoolExpr;
   lt(value: unknown): BoolExpr;
@@ -153,12 +369,12 @@ export interface UnknownExpr extends ExprBase<unknown>, AggregatableExpr {
   concat(value: unknown): UnknownExpr;
   substring(start: number, length?: number): UnknownExpr;
   replace(pattern: string, replacement: string): UnknownExpr;
-  year(): NumberExpr;
-  month(): NumberExpr;
-  day(): NumberExpr;
-  epoch(): NumberExpr;
   all(): UnknownExpr;
-  at(index: number): UnknownExpr;
+  at(index: number | NumberExpr): UnknownExpr;
+  /** Do two half-open `{start, end}` intervals share an instant? */
+  overlaps(other: Interval | ExprBase<unknown>): BoolExpr;
+  /** Cosine similarity (§8.15) — wide, on the honest top. */
+  similarity(other: unknown): NumberExpr;
 }
 
 /** Value type → expression type. Order matters: the DateTime brand is
@@ -199,17 +415,90 @@ export interface OrderOptions {
   collation?: string;
 }
 
-/** The provider contract (D2): any object exposing
+/** One row of a provider's relation table (MODEL-FORMAT §10.1, as a
+ * store spells it): the declared relation as plain data a hop lowers
+ * from. A foreign-key relation names its key column (`via`), the entity
+ * holding it (`fkEntity`), the entity it references (`fkTargets`) and the
+ * key it references there (`targetKey`); `kind` says which side holds the
+ * key. A many-to-many names its `joinTable` and is refused (`JL0105`). */
+export interface RelationEntry {
+  readonly to: string;
+  readonly kind: 'oneToOne' | 'oneToMany' | 'manyToMany';
+  readonly via?: string;
+  readonly fkEntity?: string;
+  readonly fkTargets?: string;
+  readonly joinTable?: string;
+  readonly targetKey: string;
+}
+
+/** A provider's relation table: one entry per relation member of the
+ * rows it serves. */
+export type RelationTable = Readonly<Record<string, RelationEntry>>;
+
+/** One relation hop a callback navigated (QUERY-PEN §4, relation
+ * navigation): the member read, the relation's kind, and the binding
+ * the lowered correlated phrase ranges over (`r1`, `r2`, …). */
+export interface Hop {
+  member: string;
+  kind: 'oneToOne' | 'oneToMany';
+  binding: string;
+}
+
+/** The provider contract (D2, QUERY-PEN §8): any object exposing
  * `execute(document, options)`. The document arrives whole; the return
- * value uses the engine's result mapping. */
-export interface Provider {
+ * value uses the engine's result mapping. `T` is the item type — read
+ * from the `__item` phantom a typed provider carries (a typed entity
+ * set), stated by the caller (`from<T>(provider)`), or `unknown`. */
+export interface Provider<T = unknown> {
+  /** The item phantom: never present at runtime; what `from` infers `T` from. */
+  readonly __item?: T;
   execute(document: unknown, options: { externals: Record<string, unknown> }): unknown;
+  /** The root expression the items are bound through (`'$.Post[*]'`);
+   * absent means the whole input, `'$[*]'`. */
+  readonly root?: string;
+  /** The entity roots a store-level provider serves when it has no root
+   * of its own — `from()` refuses it (`JL0007`) naming them. */
+  readonly roots?: readonly string[];
+  /** An identity two providers share when their documents may be joined
+   * (one store's entity sets). When it carries `relations` — the tables
+   * of every root of the scope, keyed by root name — a hop continues
+   * into another root (`p.author.posts`). */
+  readonly scope?: unknown;
+  /** The relation table of the rows this provider serves: a relation
+   * member on the chain then hops (§3), lowered to a correlated phrase. */
+  readonly relations?: RelationTable;
 }
 
+/** The asynchronous provider (D8, §12): the same members, and `execute`
+ * may answer a promise — `fromAsync(provider)` awaits it, and the whole
+ * chain up to a `mapAsync` arrives as ONE document. */
+export interface AsyncProvider<T = unknown> {
+  readonly __item?: T;
+  execute(document: unknown, options: { externals: Record<string, unknown> }): unknown | Promise<unknown>;
+  readonly root?: string;
+  readonly roots?: readonly string[];
+  readonly scope?: unknown;
+  readonly relations?: RelationTable;
+}
+
+/** The engine's compile registries, under the engine's own option names
+ * (QUERY-PEN §8.1): what makes an expressible document executable in
+ * memory. Their shapes are the query engine's — wide here, never wrong. */
 export interface LinqOptions {
   /** Enables `ofType`/`cast` (schema operators); e.g.
    * `createTypeTestCompiler()` from `@jarenjs/validate/query`. */
   compileTypeTest?: (schema: unknown, docPath: string) => (value: unknown) => boolean;
+  /** Registered `$call` functions, for a hand-written or saved document. */
+  functions?: Readonly<Record<string, (...args: any[]) => unknown>>;
+  /** Named collations: `orderBy(…, { collation })` is `JQ0010` without one. */
+  collations?: Readonly<Record<string, (a: string, b: string) => number>>;
+  /** Custom RFC 9535 path function extensions. */
+  pathFunctions?: Readonly<Record<string, unknown>>;
+  /** Step, depth and sequence bounds — a SAVED document's guard. */
+  limits?: Readonly<Record<string, number>>;
+  /** An explicit cache-partition key, when the hooks above are rebuilt
+   * per call: compiled documents are shared per registry combination. */
+  registry?: object;
 }
 
 export interface Explanation {
@@ -221,6 +510,13 @@ export interface Explanation {
     readonly functions: readonly string[];
     readonly collations: readonly string[];
   };
+  /** The relation hops the chain's callbacks navigated, in capture
+   * order; a join's inner sequence's hops precede the join's own. */
+  hops: Hop[];
+  /** The values `params()` bound, by name — what a provider receives as
+   * `externals` when the document runs, so a host handed the chain (a
+   * live registration) can carry them without a second spelling. */
+  bindings: Record<string, unknown>;
 }
 
 /** The deferred, immutable sequence of `T` with declared params `P`. */
@@ -246,6 +542,10 @@ export class Sequence<T = unknown, P = {}> {
     result: (outer: Expr<T>, inner: Expr<U>, p: ParamsExpr<P>) => R,
   ): Sequence<Unwrap<R>, P>;
 
+  /** The matching inner group is bound as an ARRAY value: index it
+   * (`g.at(0)`), fan it (`g.all()`), place it in a member (`{ all: g }`),
+   * and aggregate over its MEMBERS (`g.count()` is the number of
+   * matches, `g.exists()` whether there are any). */
   groupJoin<U, R extends ExprResult>(
     inner: Sequence<U, any>,
     outerKey: (it: Expr<T>, p: ParamsExpr<P>) => ExprResult,
@@ -263,13 +563,21 @@ export class Sequence<T = unknown, P = {}> {
   concat(other: Sequence<T, any> | readonly T[]): Sequence<T, P>;
   defaultIfEmpty(fallback?: T | null): Sequence<T | null, P>;
 
-  /** Keep items the schema accepts. `S` is caller-asserted (a JSON
-   * Schema is not a TypeScript type); the default is honest `unknown`. */
+  /** Keep items the schema accepts. A schema-pen builder carries its
+   * own shape (`Infer<>`); for a hand-written document `S` is
+   * caller-asserted (a JSON Schema is not a TypeScript type) and the
+   * default is honest `unknown`. */
+  ofType<S>(schema: SchemaBuilder<S, any, any>): Sequence<S, P>;
   ofType<S = unknown>(schema: object): Sequence<S, P>;
+  cast<S>(schema: SchemaBuilder<S, any, any>): Sequence<S, P>;
   cast<S = unknown>(schema: object): Sequence<S, P>;
 
-  /** Recorded unsupported: throws `JL0006`. */
-  zip(...args: never[]): never;
+  /** Recorded unsupported (§4, §16): the grammar has no positional
+   * co-iteration. The parameter is `never`, not just the return type:
+   * a rest parameter accepts zero arguments, so `q.zip()` — the one
+   * spelling a caller would actually write — type-checked and failed at
+   * run time instead. JavaScript callers still get `JL0006`. */
+  zip(unsupported: never): never;
 
   params<Q extends Record<string, unknown>>(bindings: Q): Sequence<T, P & Q>;
 
@@ -302,7 +610,7 @@ export class Sequence<T = unknown, P = {}> {
   any(predicate?: (it: Expr<T>, p: ParamsExpr<P>) => BoolExpr | boolean): boolean;
   all(predicate: (it: Expr<T>, p: ParamsExpr<P>) => BoolExpr | boolean): boolean;
 
-  /** Cross into the async surface (LINQ-FORMAT.md §11): the sync chain
+  /** Cross into the async surface (QUERY-PEN.md §11): the sync chain
    * becomes the pushed prefix; the element re-types to the callback's
    * RESOLVED type. */
   mapAsync<R>(fn: (item: T, signal: AbortSignal) => R, options: MapAsyncOptions):
@@ -310,7 +618,9 @@ export class Sequence<T = unknown, P = {}> {
 }
 
 export function from<T>(source: Iterable<T>, options?: LinqOptions): Sequence<T, {}>;
-export function from<T = unknown>(source: Provider, options?: LinqOptions): Sequence<T, {}>;
+/** A provider: `T` from its `__item` phantom (a typed entity set infers
+ * without a cast), or as the caller states it, or `unknown`. */
+export function from<T = unknown>(source: Provider<T>, options?: LinqOptions): Sequence<T, {}>;
 
 export function fromDocument<T = unknown>(
   source: Iterable<unknown> | Provider,
@@ -318,7 +628,7 @@ export function fromDocument<T = unknown>(
   options?: LinqOptions,
 ): Sequence<T, {}>;
 
-/** The runtime code table, synced to LINQ-FORMAT.md §9 by a test. */
+/** The runtime code table, synced to QUERY-PEN.md §9 by a test. */
 export const LINQ_CODES: Readonly<Record<string, string>>;
 
 export class LinqBuildError extends Error {
@@ -333,7 +643,7 @@ export class LinqRuntimeError extends Error {
   readonly docPath: string | undefined;
 }
 
-// ————— The asynchronous surface (LINQ-FORMAT.md §§10–12) —————
+// ————— The asynchronous surface (QUERY-PEN.md §§10–12) —————
 
 export interface MapAsyncOptions {
   /** REQUIRED: the in-flight bound (a positive integer, `JL0005`
@@ -347,6 +657,10 @@ export interface MapAsyncOptions {
 
 export interface AsyncExplanation {
   barriers: { operator: string, reason: string }[];
+  /** The relation hops the chain's callbacks navigated (as `Explanation`). */
+  hops: Hop[];
+  /** The values `params()` bound, by name (as `Explanation`). */
+  bindings: Record<string, unknown>;
   /** Present when the chain is document-representable (no mapAsync). */
   document?: unknown;
   /** Present when a mapAsync splits the chain. */
@@ -374,6 +688,24 @@ export class AsyncSequence<T = unknown, P = {}> {
   groupBy<R extends ExprResult>(key: (it: Expr<T>, p: ParamsExpr<P>) => R):
     AsyncSequence<{ key: Unwrap<R> | null, items: T[] }, P>;
   aggregate<A>(seed: A, step: (acc: Expr<A>, it: Expr<T>, p: ParamsExpr<P>) => ExprResult): AsyncSequence<A, P>;
+
+  /** Equi-join, pushed WHOLE: only over a provider origin, before any
+   * `mapAsync`, with an inner async sequence over the same provider or
+   * one sharing its scope (`JL0005` otherwise — a single-pass source
+   * cannot be joined; QUERY-PEN §10). */
+  join<U, R extends ExprResult>(
+    inner: AsyncSequence<U, any>,
+    outerKey: (it: Expr<T>, p: ParamsExpr<P>) => ExprResult,
+    innerKey: (it: Expr<U>, p: ParamsExpr<P>) => ExprResult,
+    result: (outer: Expr<T>, inner: Expr<U>, p: ParamsExpr<P>) => R,
+  ): AsyncSequence<Unwrap<R>, P>;
+  /** Group-join, pushed WHOLE under the same rule as `join`. */
+  groupJoin<U, R extends ExprResult>(
+    inner: AsyncSequence<U, any>,
+    outerKey: (it: Expr<T>, p: ParamsExpr<P>) => ExprResult,
+    innerKey: (it: Expr<U>, p: ParamsExpr<P>) => ExprResult,
+    result: (outer: Expr<T>, group: ArrayExpr<U> & AggregatableExpr, p: ParamsExpr<P>) => R,
+  ): AsyncSequence<Unwrap<R>, P>;
   skip(count: number): AsyncSequence<T, P>;
   take(count: number): AsyncSequence<T, P>;
   distinct(): AsyncSequence<T, P>;
@@ -381,9 +713,12 @@ export class AsyncSequence<T = unknown, P = {}> {
   /** Only a CONSTANT array can join an async stream (§10). */
   concat(other: readonly T[]): AsyncSequence<T, P>;
   defaultIfEmpty(fallback?: T | null): AsyncSequence<T | null, P>;
+  ofType<S>(schema: SchemaBuilder<S, any, any>): AsyncSequence<S, P>;
   ofType<S = unknown>(schema: object): AsyncSequence<S, P>;
+  cast<S>(schema: SchemaBuilder<S, any, any>): AsyncSequence<S, P>;
   cast<S = unknown>(schema: object): AsyncSequence<S, P>;
-  zip(...args: never[]): never;
+  /** Recorded unsupported, as on the synchronous surface. */
+  zip(unsupported: never): never;
   params<Q extends Record<string, unknown>>(bindings: Q): AsyncSequence<T, P & Q>;
 
   /** The bounded-concurrency boundary (§11): re-types the element to
@@ -417,6 +752,19 @@ export class AsyncSequence<T = unknown, P = {}> {
   all(predicate: (it: Expr<T>, p: ParamsExpr<P>) => BoolExpr | boolean): Promise<boolean>;
 }
 
+/** Build an async sequence over a provider (an `execute` duck, asked for
+ * before the iterable shapes): the document arrives whole and `execute`
+ * may answer a promise; `T` from the `__item` phantom, the caller, or
+ * `unknown`. */
+export function fromAsync<T = unknown>(
+  source: AsyncProvider<T>,
+  options?: LinqOptions,
+): AsyncSequence<T, {}>;
+/** Build an async sequence over an async iterable, a sync iterable, a
+ * cursor or a push queue. A STRING is refused (`JL0001`): on this
+ * surface a string is a chunk source — feed it through a push queue —
+ * never a character stream, which is where the twins deliberately
+ * differ from `from('abc')`. */
 export function fromAsync<T>(
   source: AsyncIterable<T> | Iterable<T> | AsyncCursor<T>,
   options?: LinqOptions,