@jarenjs/linq 0.49.2 → 0.66.1

package/types/index.d.ts

@@ -19,7 +19,9 @@
  * 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. */
@@ -65,7 +67,7 @@ export interface NumberExpr extends ExprBase<number>, EqExpr<number> {
     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;
@@ -236,22 +238,82 @@ export interface SeriesMethods {
     Expr<AsOfMatch[]> & AggregatableExpr;
 }
 
-export interface ArrayExpr<E> extends ExprBase<E[]>, SeriesMethods {
+/** 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;
@@ -262,16 +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, DateMethods, SeriesMethods {
+  extends ExprBase<unknown>, AggregatableExpr, DateMethods, SeriesMethods, SpatialMethods {
   eq(value: unknown): BoolExpr;
   ne(value: unknown): BoolExpr;
   lt(value: unknown): BoolExpr;
@@ -299,9 +370,11 @@ export interface UnknownExpr
   substring(start: number, length?: number): UnknownExpr;
   replace(pattern: string, replacement: string): UnknownExpr;
   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
@@ -342,17 +415,97 @@ 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>;
+  /** The cursor protocol, optional: the same document as an item
+   * cursor, one item per pull, `return()` releasing whatever it holds.
+   * A `for await` over the chain hands its pushed document here when
+   * the provider offers it, so iteration never materialises what the
+   * provider can stream; a provider without it is run whole. */
+  cursor?(document: unknown, options: { externals: Record<string, unknown> }):
+    AsyncIterator<unknown> & { return(): 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 {
@@ -364,6 +517,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`. */
@@ -389,6 +549,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,
@@ -406,13 +570,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>;
 
@@ -445,7 +617,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):
@@ -453,7 +625,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,
@@ -461,7 +635,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 {
@@ -476,7 +650,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`
@@ -490,6 +664,17 @@ export interface MapAsyncOptions {
 
 export interface AsyncExplanation {
   barriers: { operator: string, reason: string }[];
+  /** What THIS surface does with the item stream: one item at a time, or
+   * a buffer at its first local barrier. Over a provider the pushed
+   * document's own class — a set residual, an external the database
+   * cannot bind — is the provider's `explain(document, { externals:
+   * bindings })` to report, and its cursor carries the same answer. */
+  streaming: 'row' | 'buffered';
+  barrier: { construct: string, reason: string } | null;
+  /** 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. */
@@ -517,6 +702,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>;
@@ -524,9 +727,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
@@ -560,11 +766,75 @@ 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,
 ): AsyncSequence<T, {}>;
 
+/** One side of a federation, as `explain()` reports it (§12.1). */
+export interface FederatedSide {
+  readonly source: string;
+  readonly root: string;
+  readonly estimatedRows: number | null;
+  /** The join key on this side, as the document spells it. */
+  readonly key: string;
+  /** The document this side's own source is asked. */
+  readonly document: unknown;
+  /** Whether this side is pulled row by row, or answered whole. */
+  readonly streaming: 'row' | 'buffered';
+}
+
+/** What a federated document will do, without doing any of it (§12.1). */
+export interface FederationPlan {
+  readonly strategy: 'hash';
+  readonly budget: { readonly maxRows: number; readonly maxBytes: number };
+  readonly build: FederatedSide;
+  readonly probe: FederatedSide;
+  /** The join itself is the engine's, over the two reduced sides. */
+  readonly resident: { readonly document: unknown };
+}
+
+/** One named source of a federation: an ordinary provider source whose
+ * root is `$.<name>[*]`, sharing one scope with its siblings — which is
+ * what admits the join the federation then executes. */
+export interface FederatedSource<T = unknown> extends AsyncProvider<T> {
+  explain(document: unknown): FederationPlan;
+  readonly root: string;
+}
+
+/** The explicit cross-source boundary (§12.1).
+ *
+ * A query document reads one input, and an ordinary join across two
+ * unrelated sources stays `JL0005`. `federate()` is the one way to opt
+ * out of that, by naming the sources and the bounds together: each
+ * side's own filters and projection run at its source, the smaller side
+ * fills a bounded hash table, the other is probed against it, and the
+ * caller's own document decides over the two reduced sets. A side that
+ * reaches `maxRows` or `maxBytes` raises `JL2008` at the row that would
+ * have broken the bound. */
+export function federate(spec: {
+  sources: Record<string, AsyncProvider | { provider: AsyncProvider; estimatedRows?: number }>;
+  maxRows: number;
+  maxBytes: number;
+  strategy?: 'hash';
+}): {
+  source<T = unknown>(name: string): FederatedSource<T>;
+  readonly names: readonly string[];
+};
+
 /** The push→pull adapter for feed/end readers (§12). */
 export function createPushQueue<T = unknown>(options?: { highWaterMark?: number }): {
   feed(value: T): boolean;

package/types/jslt.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Hand-authored declarations for `@jarenjs/linq/jslt` — the JSLT pen's
+ * type contract, kept to the same line as `index.d.ts`: the common path
+ * is precisely typed, the exotic path is honestly `unknown`, nothing is
+ * ever a WRONG type.
+ *
+ * A body's VALUE is typed by annotating the callback's first argument
+ * (`(v: Expr<Book>) => …`) or by the rule's `schema` match when it is a
+ * schema-pen builder; without either it is the honest top. A body's
+ * externals are `root` and `path` — always present, no declaration —
+ * plus the parameters the body declares by name (`{ externals: ['rate']
+ * }`): a declared name types as `UnknownExpr` until the second argument
+ * is annotated (`x: Externals<{ rate: number }>`), an undeclared name is
+ * a compile error, as with the chain's `params()`.
+ *
+ * The honest limits: a rule's OUTPUT is the unwrapped shape of what its
+ * body returns, with every `apply()` — a dispatch to OTHER rules —
+ * `unknown`; a stylesheet's `In`/`Out` are its FIRST rule's (write the
+ * root rule first, as Appendix A does), or what the author annotates
+ * (`stylesheet<In, Out>(…)`). The built-in rule's rebuilds (`share`/
+ * `fresh` around an unmatched container) are not typed at all: a
+ * stylesheet whose root is unmatched is `Stylesheet<unknown, unknown>`
+ * unless annotated. Every claim here has a runtime twin in
+ * `test/linq/jslt-pen.test.js` and a compile-level pin in
+ * `test/consumer/linq-jslt.ts`.
+ */
+
+import type { ExprBase, MemberExpr, StringExpr, UnknownExpr, Unwrap } from './index.js';
+import type { BuilderLike, Json, JsonSchema } from './schema.js';
+
+/** A mode's built-in-rule disposition (JSLT-FORMAT §5). */
+export type Disposition = 'share' | 'fresh' | 'error';
+
+/**
+ * The externals a body may name: the two the engine binds on every
+ * dispatch (§8.2) and the parameters the body declared (§8.1).
+ */
+export type Externals<X = {}, Root = unknown> = {
+  /** The input document root (`$root`). */
+  readonly root: MemberExpr<Root>;
+  /** The matched value's normalized path (`$path`) — `null` for a location-less value. */
+  readonly path: StringExpr;
+} & {
+  readonly [K in keyof X & string]-?: MemberExpr<X[K]>;
+};
+
+/** Any expression-ish callback result the capture accepts. */
+export type BodyResult = ExprBase<unknown> | object | string | number | boolean | null;
+
+/** The value phantom of an expression type; the honest top otherwise. */
+export type ValueOf<V> = V extends ExprBase<infer T> ? (unknown extends T ? unknown : T) : unknown;
+
+/**
+ * A rule body's document — plain JSON (the `$expr` of a rule), carrying
+ * the value it was captured over and the shape it produces as
+ * phantoms. `body()` writes one; `rule()` reads both phantoms.
+ */
+export type BodyDocument<In = unknown, Out = unknown> = Json & {
+  /** Phantoms: declared, never present at runtime. */
+  readonly __in: In;
+  readonly __out: Out;
+};
+
+export interface BodyOptions<N extends string> {
+  /** The stylesheet parameters this body names (§8.1); `root` and `path` need none. */
+  readonly externals?: readonly N[];
+}
+
+/**
+ * Capture one rule body over the matched value at `$`. Type the value
+ * by annotating `v` (`(v: Expr<Book>) => …`); declare parameters by
+ * name and type them by annotating `x` (`x: Externals<{ rate: number
+ * }>`) — an undeclared name on `x` does not compile.
+ */
+export function body<
+  V extends ExprBase<unknown> = UnknownExpr,
+  N extends string = never,
+  R extends BodyResult = BodyResult,
+  Root = unknown,
+  X extends Record<N, unknown> = Record<N, unknown>,
+>(
+  fn: (value: V, x: Externals<X, Root>) => R,
+  options?: BodyOptions<N>,
+): BodyDocument<ValueOf<V>, Unwrap<R>>;
+
+/**
+ * `{ $apply: selector }` / `{ $apply: [selector, mode] }` — the
+ * apply-templates operator (§6), inside a `body()` callback. Its result
+ * is a dispatch to other rules, so it is the honest top: as an array
+ * element (`[apply(…)]`, the `[]` idiom) it unwraps to `unknown[]`; as a
+ * bare object member it is refused at build time (`JL0102`).
+ */
+export function apply(selector: ExprBase<unknown> | string | Json, mode?: string): UnknownExpr;
+
+/**
+ * `{ [name]: operands }` — a registered operator (§13), spelled without
+ * judging it; the engine's compiler decides. Works in any capture.
+ */
+export function op(name: `$${string}`, operands?: ExprBase<unknown> | Json | readonly (ExprBase<unknown> | Json)[]): UnknownExpr;
+
+/** The `match` member (§3): a JSONPath string, `{ path?, schema? }`, or `null` for the unconditional rule. */
+export type Match =
+  | string
+  | null
+  | undefined
+  | { readonly path?: string; readonly schema?: BuilderLike | JsonSchema | boolean };
+
+/** The value a match types: a schema-pen builder's `Infer<>`; the honest top otherwise. */
+export type MatchIn<M> = M extends { readonly schema: BuilderLike<infer O, any, any> } ? O : unknown;
+
+export interface RuleOptions {
+  /** The rule's mode (§7); the unnamed mode `""` by default. */
+  readonly mode?: string;
+  /** Explicit conflict resolution (§4); the three defaults otherwise. */
+  readonly priority?: number;
+}
+
+/** The `match` member as emitted. */
+export type MatchDocument =
+  | string
+  | { readonly path?: string; readonly schema?: JsonSchema | boolean };
+
+/** A rule as a plain document — what `stylesheet()` takes, by pen or by hand. */
+export interface RuleDocument {
+  readonly mode?: string;
+  readonly match?: MatchDocument;
+  readonly priority?: number;
+  readonly body: Json;
+}
+
+/** One template rule (§2.2), carrying its body's phantoms. */
+export interface Rule<In = unknown, Out = unknown> extends RuleDocument {
+  readonly __in: In;
+  readonly __out: Out;
+}
+
+/** A callback rule: the value is typed by annotating it (`(v: Expr<Book>) => …`)
+ * or by the match's schema builder; the honest top otherwise. */
+export function rule<
+  M extends Match,
+  R extends BodyResult,
+  V extends ExprBase<unknown> = MemberExpr<MatchIn<M>>,
+>(
+  match: M,
+  fn: (value: V, x: Externals<{}, unknown>) => R,
+  options?: RuleOptions,
+): Rule<ValueOf<V>, Unwrap<R>>;
+/** A `body()` document: its phantoms are the rule's (the match's schema types `In` when the body is untyped). */
+export function rule<M extends Match, In, Out>(
+  match: M,
+  body: BodyDocument<In, Out>,
+  options?: RuleOptions,
+): Rule<unknown extends In ? MatchIn<M> : In, Out>;
+/** A query document verbatim: nothing is inferred. */
+export function rule(match: Match, body: Json, options?: RuleOptions): Rule<unknown, unknown>;
+
+export interface StylesheetOptions {
+  /** The default disposition of every mode (§2.1, §5). */
+  readonly unmatched?: Disposition;
+  /** Per-mode overrides. */
+  readonly modes?: { readonly [mode: string]: { readonly unmatched: Disposition } };
+}
+
+/** The envelope (§2.1), carrying the root rule's phantoms. */
+export interface Stylesheet<In = unknown, Out = unknown> {
+  readonly __in: In;
+  readonly __out: Out;
+  readonly $jslt: '0.1';
+  readonly unmatched?: Disposition;
+  readonly modes?: { readonly [mode: string]: { readonly unmatched: Disposition } };
+  readonly rules: readonly RuleDocument[];
+}
+
+/** A rule's `In` phantom; a hand-written rule is `unknown`. */
+export type RuleIn<R> = R extends Rule<infer I, any> ? I : unknown;
+/** A rule's `Out` phantom; a hand-written rule is `unknown`. */
+export type RuleOut<R> = R extends Rule<any, infer O> ? O : unknown;
+
+/** The envelope over rule documents; `In`/`Out` are the FIRST rule's. */
+export function stylesheet<const R extends readonly RuleDocument[]>(
+  rules: R,
+  options?: StylesheetOptions,
+): Stylesheet<RuleIn<R[0]>, RuleOut<R[0]>>;
+/** The envelope with the phantoms as the author states them. */
+export function stylesheet<In, Out>(
+  rules: readonly RuleDocument[],
+  options?: StylesheetOptions,
+): Stylesheet<In, Out>;
+
+/** The input a stylesheet (or rule) was written over. */
+export type Input<S> = S extends { readonly __in: infer I } ? I : unknown;
+/** The shape a stylesheet (or rule) produces. */
+export type Output<S> = S extends { readonly __out: infer O } ? O : unknown;