@jarenjs/linq 0.49.2 → 0.56.0

package/types/forms.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Hand-authored declarations for `@jarenjs/linq/forms` — the schema
+ * pen's every name, from subclasses that carry the `x-form` vocabulary,
+ * plus `assertOnSubmit()`.
+ *
+ * A rule is an ANNOTATION, so nothing here changes what a builder
+ * INFERS: `Infer<>`, `Input<>` and the flags read exactly as they do on
+ * the schema pen, and the subclasses exist only so `form()` survives
+ * every chained method. What the rules are typed against is the rule
+ * CONTEXT: `c.root` is the whole form document, typed by annotation
+ * (`(c: RuleContext<Invoice>) => …`) because a member builder is
+ * written before the object that will hold it exists — the same limit
+ * the flow pen's `context` meets, and TypeScript's own.
+ *
+ * Every claim here has a runtime twin in `test/linq/forms-pen.test.js`
+ * and a compile-level pin in `test/consumer/linq-app.ts`; FORMS-PEN.md
+ * is the normative mapping table.
+ */
+
+import type { BoolExpr, DateTime, MemberExpr, StringExpr } from './index.js';
+import type {
+  Annotations, BuilderLike, Flag, Infer, Input, Json, JsonSchema, NamedLike, Simplify,
+  SchemaBuilder, StringBuilder, NumberBuilder, BooleanBuilder, NullBuilder, ArrayBuilder,
+  TupleBuilder, ObjectBuilder, NamedBuilder, WhenBuilder, NeverBuilder,
+} from './schema.js';
+
+type AnyBuilder = BuilderLike<any, any, any>;
+type Props = Record<string, AnyBuilder>;
+type Nullify<T, N extends boolean> = N extends true ? T | null : T;
+
+// ————— the rule context —————
+
+/**
+ * The three names a rule query binds (the forms README, "The rule query
+ * context"): the whole document at `$`, the field's own value as the
+ * `$value` external and its pointer as `$pointer`. `Doc` is the honest
+ * top until the callback is annotated.
+ */
+export interface RuleContext<Doc = unknown, Value = unknown> {
+  /** The whole form document (`$`) — cross-field is the point. */
+  readonly root: MemberExpr<Doc>;
+  /** The field's current value (`$value`); an absent field binds `null`. */
+  readonly value: MemberExpr<Value>;
+  /** The field's data pointer (`$pointer`), `'/vatId'`. */
+  readonly pointer: StringExpr;
+}
+
+/** A rule: a callback captured over the context, or a query document. */
+export type Rule<Doc = unknown, Value = unknown> =
+  | ((context: RuleContext<Doc, Value>) => unknown)
+  | { readonly [keyword: string]: unknown };
+
+/** The message an `assert` failure renders: an inline template, or a
+ * catalog spec (the forms README, "MessageSpec in `x-form.message`"). */
+export type MessageSpec =
+  | string
+  | { readonly $msgid?: string; readonly message?: string; readonly params?: Record<string, Json> };
+
+/**
+ * What `form()` takes — exactly the members `x-form` defines. `preview`
+ * is absent on purpose: a field's preview hint is DERIVED from its
+ * format by the registry, never authored, and writing it is `JL0102`.
+ */
+export interface FormRules<Doc = unknown, Value = unknown> {
+  /** Should the field be shown? Asserted by effective boolean value; fails OPEN. */
+  readonly visible?: Rule<Doc, Value>;
+  /** Should the field accept input? EBV; fails OPEN. */
+  readonly enabled?: Rule<Doc, Value>;
+  /** A cross-field preemptive assertion. EBV; fails CLOSED. */
+  readonly assert?: Rule<Doc, Value>;
+  /** The field's derived value, mapped to plain JSON. */
+  readonly computed?: Rule<Doc, Value>;
+  /** Shown when `assert` fails. */
+  readonly message?: MessageSpec;
+}
+
+// ————— the rule-aware builders —————
+
+/** The base every untyped kind is built from, plus `form()`. */
+export class FormBuilder<Out = unknown, In = Out, F extends Flag = never> extends SchemaBuilder<Out, In, F> {
+  optional(): FormBuilder<Out, In, F | 'optional'>;
+  nullable(): FormBuilder<Out | null, In | null, F>;
+  default(value: Out): FormBuilder<Out, In, F | 'defaulted'>;
+  /** One `x-form` annotation; a second call merges into the same one. */
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  /** As in the schema pen, but `x-form` is owned here. */
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+export class FormStringBuilder<Out = string, In = Out, F extends Flag = never> extends StringBuilder<Out, In, F> {
+  optional(): FormStringBuilder<Out, In, F | 'optional'>;
+  nullable(): FormStringBuilder<Out | null, In | null, F>;
+  default(value: Out): FormStringBuilder<Out, In, F | 'defaulted'>;
+  coerce(): FormStringBuilder<Out, In | number | boolean, F>;
+  format(name: 'date-time' | 'date'): FormStringBuilder<DateTime, DateTime, F>;
+  format(name: string): this;
+  enumOf<const V extends readonly string[]>(values: V): FormStringBuilder<V[number], V[number], F>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+export class FormNumberBuilder<Out = number, In = Out, F extends Flag = never> extends NumberBuilder<Out, In, F> {
+  optional(): FormNumberBuilder<Out, In, F | 'optional'>;
+  nullable(): FormNumberBuilder<Out | null, In | null, F>;
+  default(value: Out): FormNumberBuilder<Out, In, F | 'defaulted'>;
+  coerce(): FormNumberBuilder<Out, In | string, F>;
+  enumOf<const V extends readonly number[]>(values: V): FormNumberBuilder<V[number], V[number] | Exclude<In, number>, F>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+declare class FormBooleanBuilder<Out = boolean, In = Out, F extends Flag = never> extends BooleanBuilder<Out, In, F> {
+  optional(): FormBooleanBuilder<Out, In, F | 'optional'>;
+  nullable(): FormBooleanBuilder<Out | null, In | null, F>;
+  default(value: Out): FormBooleanBuilder<Out, In, F | 'defaulted'>;
+  coerce(): FormBooleanBuilder<Out, In | string, F>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+declare class FormNullBuilder<Out = null, In = Out, F extends Flag = never> extends NullBuilder<Out, In, F> {
+  optional(): FormNullBuilder<Out, In, F | 'optional'>;
+  default(value: Out): FormNullBuilder<Out, In, F | 'defaulted'>;
+  coerce(): FormNullBuilder<Out, In | string, F>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+export class FormArrayBuilder<Out = unknown[], In = Out, F extends Flag = never> extends ArrayBuilder<Out, In, F> {
+  optional(): FormArrayBuilder<Out, In, F | 'optional'>;
+  nullable(): FormArrayBuilder<Out | null, In | null, F>;
+  default(value: Out): FormArrayBuilder<Out, In, F | 'defaulted'>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+export class FormTupleBuilder<
+  T extends readonly AnyBuilder[], R = unknown, RIn = R,
+  N extends boolean = false, F extends Flag = never,
+> extends TupleBuilder<T, R, RIn, N, F> {
+  optional(): FormTupleBuilder<T, R, RIn, N, F | 'optional'>;
+  nullable(): FormTupleBuilder<T, R, RIn, true, F>;
+  rest<B extends AnyBuilder>(builder: B): FormTupleBuilder<T, Infer<B>, Input<B>, N, F>;
+  form<Doc = unknown>(rules: FormRules<Doc, unknown>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+export class FormObjectBuilder<
+  P extends Props, Open extends boolean = false, PV = never, PVIn = PV,
+  N extends boolean = false, F extends Flag = never,
+> extends ObjectBuilder<P, Open, PV, PVIn, N, F> {
+  optional(): FormObjectBuilder<P, Open, PV, PVIn, N, F | 'optional'>;
+  nullable(): FormObjectBuilder<P, Open, PV, PVIn, true, F>;
+  open(): FormObjectBuilder<P, true, PV, PVIn, N, F>;
+  patternProperties<M extends Props>(map: M): FormObjectBuilder<P, Open, Infer<M[keyof M]>, Input<M[keyof M]>, N, F>;
+  extend<Q extends Props>(props: Q): FormObjectBuilder<Simplify<Omit<P, keyof Q> & Q>, Open, PV, PVIn, N, F>;
+  pick<K extends keyof P & string>(keys: readonly K[]): FormObjectBuilder<Pick<P, K>, Open, PV, PVIn, N, F>;
+  omit<K extends keyof P & string>(keys: readonly K[]): FormObjectBuilder<Omit<P, K>, Open, PV, PVIn, N, F>;
+  /** A rule on the ROOT's `visible` is refused by `compileFormRules`:
+   * hiding the whole form would null the render tree and its summary. */
+  form<Doc = unknown>(rules: FormRules<Doc, unknown>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+declare class FormNamedBuilder<Out, In = Out, F extends Flag = never> extends NamedBuilder<Out, In, F> {
+  optional(): FormNamedBuilder<Out, In, F | 'optional'>;
+  nullable(): FormNamedBuilder<Out | null, In | null, F>;
+  form<Doc = unknown>(rules: FormRules<Doc, Out>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+/**
+ * `when()` on this pen. A conditional carries a rule like any other
+ * node: `buildFormModel` reads `x-form` off whatever schema it builds a
+ * field for, so a `when()` used as an object MEMBER answers a field whose
+ * rules evaluate — the runtime twin is in `test/linq/forms-pen.test.js`.
+ * `Value` is `unknown` here, as on the object and tuple builders: the
+ * node describes a shape rather than a value.
+ */
+export class FormWhenBuilder<F extends Flag = never> extends WhenBuilder<F> {
+  optional(): FormWhenBuilder<F | 'optional'>;
+  then(builder: AnyBuilder): FormWhenBuilder<F>;
+  else(builder: AnyBuilder): FormWhenBuilder<F>;
+  form<Doc = unknown>(rules: FormRules<Doc, unknown>): this;
+  meta(annotations: Annotations & { readonly 'x-form'?: never }): this;
+}
+
+/**
+ * `never()` on this pen — and `never()` ANSWERS one, so a caller meets
+ * this class without narrowing to it. A rule is an annotation and
+ * `false` carries no annotation, so `form()` and `meta()` both raise
+ * `JL0102` here: `form()` is not declared at all, and `meta()` is
+ * inherited from `NeverBuilder` with a `never` parameter, so neither
+ * call compiles either. `nullable()` widens the node and hands back this
+ * pen's base builder, where both are legal again.
+ */
+export class FormNeverBuilder<Out = never, In = Out, F extends Flag = never> extends NeverBuilder<Out, In, F> {
+  optional(): FormNeverBuilder<Out, In, F | 'optional'>;
+  /** As on the schema pen: widening to admit `null` is what makes a rule
+   * writable, so it answers this pen's base builder. */
+  nullable(): FormBuilder<Out | null, In | null, F>;
+}
+
+// ————— the named factories —————
+
+export function string(): FormStringBuilder;
+export function number(): FormNumberBuilder;
+export function integer(): FormNumberBuilder;
+export function boolean(): FormBooleanBuilder;
+export function nil(): FormNullBuilder;
+export function literal<const V extends Json>(value: V): FormBuilder<V, V>;
+export function enumOf<const V extends readonly Json[]>(values: V): FormBuilder<V[number], V[number]>;
+export function object<P extends Props>(props: P): FormObjectBuilder<P>;
+export function array<B extends AnyBuilder>(items: B): FormArrayBuilder<Infer<B>[], Input<B>[]>;
+export function tuple<T extends readonly AnyBuilder[]>(items: readonly [...T]): FormTupleBuilder<T>;
+export function record<B extends AnyBuilder>(values: B):
+  FormBuilder<{ [key: string]: Infer<B> }, { [key: string]: Input<B> }>;
+export function union<T extends readonly AnyBuilder[]>(options: readonly [...T]):
+  FormBuilder<Infer<T[number]>, Input<T[number]>>;
+export function discriminated<K extends string, T extends readonly BuilderLike<Record<K, unknown>, any, any>[]>(
+  key: K, options: readonly [...T]): FormBuilder<Infer<T[number]>, Input<T[number]>>;
+export function intersection<T extends readonly AnyBuilder[]>(parts: readonly [...T]):
+  FormBuilder<Intersect<{ [I in keyof T]: Infer<T[I]> }>, Intersect<{ [I in keyof T]: Input<T[I]> }>>;
+type Intersect<T extends readonly unknown[]> = T extends readonly [infer H, ...infer R] ? H & Intersect<R> : unknown;
+export function named<B extends AnyBuilder>(name: string, builder: B): FormNamedBuilder<Infer<B>, Input<B>>;
+export function ref<T = unknown>(name: string): FormBuilder<T, T>;
+export function lazy<T, I = T>(thunk: () => NamedLike<T, I>): FormBuilder<T, I>;
+export function any(): FormBuilder<unknown, unknown>;
+export function never(): FormNeverBuilder;
+export function when(cond: AnyBuilder): FormWhenBuilder;
+export function from<T = unknown>(json: JsonSchema | boolean): FormBuilder<T, T>;
+export function document(root: AnyBuilder, options?: { draft?: '2020-12' }): JsonSchema | boolean;
+export function datetime(): FormStringBuilder<DateTime, DateTime>;
+export function date(): FormStringBuilder<DateTime, DateTime>;
+export function time(): FormStringBuilder;
+export function duration(): FormStringBuilder;
+
+/** The mixin the classes above are built with: a NEW class carrying `form()`. */
+export function withForm<B extends new (...args: any[]) => any>(Base: B): B;
+
+/**
+ * The submit twin of a document's `x-form.assert` rules (the forms
+ * README's layer 3): every assert copied onto the ROOT as its own
+ * `allOf` branch `{ $query, errorMessage }`, so the rule an author wrote
+ * once for per-keystroke feedback is what the compiled validator
+ * enforces. A document with no assert answers itself.
+ */
+export function assertOnSubmit(root: AnyBuilder | JsonSchema): JsonSchema;
+
+export const SCHEMA_BUILDER: unique symbol;
+export function isSchemaBuilder(value: unknown): value is BuilderLike;
+export function schemaOf(value: unknown): unknown;
+export type { BoolExpr };

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,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 {
@@ -364,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`. */
@@ -389,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,
@@ -406,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>;
 
@@ -445,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):
@@ -453,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,
@@ -461,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 {
@@ -476,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`
@@ -490,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. */
@@ -517,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>;
@@ -524,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
@@ -560,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,