@noy-db/hub 0.7.1-pre.0 → 0.8.0

package/dist/kernel/query/live/incremental.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Incremental (delta) maintenance for `.live()` — #1341.
+ *
+ * A live query used to re-run its whole plan on every change event: scan
+ * every record in the collection, re-evaluate every clause, re-sort, re-slice.
+ * That is O(N log N) per keystroke-sized mutation and is what makes a reactive
+ * list unusable at 10k+ rows.
+ *
+ * This module maintains the match set instead. Given a change event
+ * `{ id, action }` it re-evaluates the predicate for **that record only** and
+ * splices it into (or out of) a sorted array, so the per-change cost is
+ * O(log k) comparisons + one array splice, where k is the number of MATCHING
+ * records rather than N.
+ *
+ * ## The correctness contract
+ *
+ * The maintained array must be **identical** — same records, same order — to
+ * what a full re-run would produce, at every step. Two things buy that:
+ *
+ *   1. **Membership is delegated.** The caller passes the very `matches()`
+ *      closure the full pipeline uses (`filterRecords` over the plan's
+ *      clauses), so a maintained membership decision cannot drift from an
+ *      eagerly-computed one. This module never re-implements a predicate.
+ *
+ *   2. **The ordering is delegated too, and then made total.** The sort keys
+ *      are read and ranked by the query's own order key plan — the same
+ *      `buildOrderKeyPlan`/`orderKeyOf`/`compareOrderKeys` trio `sortRecords`
+ *      sorts with and the keyset cursor compares against (#1346), so there is
+ *      one definition of "what order is this query in" rather than two that
+ *      drift. What that trio does NOT decide is equal keys: `compareOrderKeys`
+ *      is handed two KEY TUPLES, not two records, so with equal keys its
+ *      inputs are indistinguishable and 0 is the only answer it can give —
+ *      structurally, not by convention. (#1346 breaks its own ties one level
+ *      up, at the `page()` call site, never inside the comparator.) The eager
+ *      path lets its stable sort resolve those, leaving them in candidate =
+ *      snapshot order; we append each record's snapshot position as a final
+ *      key, which is the same resolution stated explicitly — and being
+ *      explicit is what lets a binary search land on an exact index.
+ *
+ *      ⚠️ That rests on one property of the backing cache: **snapshot order is
+ *      `Map` insertion order.** `Map.set` on an existing key keeps its slot
+ *      (so an update never moves a record), a new key appends (so a new record
+ *      sorts last among ties), and `delete` removes without reordering the
+ *      rest. `Collection`'s eager cache is a `Map`, so this holds. A source
+ *      whose snapshot order is not insertion-stable must not be maintained —
+ *      it would produce a correct SET in a wrong ORDER among ties.
+ *
+ * Anything not provably patchable falls back to a full rebuild: an unknown
+ * (payload-less) change event, an error thrown mid-patch, or a plan shape
+ * `canMaintainIncrementally()` refuses. **The fallback is the default** —
+ * `canMaintainIncrementally` is a whitelist, not a blacklist.
+ *
+ * ## Stacking on top of it
+ *
+ * `apply()` reports what it did as a `PatchOutcome`, and `maintainedEntries()`
+ * exposes the set with its snapshot sequence numbers. Together those let a
+ * DERIVED maintainer mirror this one without forking its membership logic —
+ * which is exactly what per-group maintenance for
+ * `groupBy().aggregate().live()` does (`with-lookup/reduce/incremental-group.ts`).
+ * A layer built that way inherits the whitelist and the fallback rather than
+ * re-deciding them, so there is one answer to "can this plan be maintained"
+ * rather than two that drift.
+ */
+import type { Clause } from '../predicate.js';
+import type { OrderBy } from '../builder.js';
+/**
+ * The delta a source hands to its `subscribe` callback: which record changed
+ * and whether it was written or removed. Deliberately the same shape as the
+ * hub-level `ChangeEvent` minus the vault/collection routing fields, which
+ * the source has already filtered on.
+ *
+ * A source that cannot say WHICH record changed simply calls its callback with
+ * no argument — every consumer treats that as "rebuild from scratch", which is
+ * exactly the pre-#1341 behaviour.
+ */
+export interface SourceChange {
+    readonly id: string;
+    readonly action: 'put' | 'delete';
+}
+/**
+ * One side of a patch: a record that entered or left the maintained set, with
+ * the snapshot sequence number it occupies. `seq` is what makes a patch
+ * composable — a layer built ON TOP of the match set (grouped aggregation,
+ * #1341's second half) can place the record in its own ordering without
+ * re-deriving snapshot position, and sequence numbers are stable across an
+ * update because `Map.set` on an existing key keeps its slot.
+ */
+export interface PatchDelta {
+    readonly seq: number;
+    readonly record: unknown;
+}
+/**
+ * What `apply()` did, so a layer stacked on the maintained set can mirror it.
+ *
+ * `'rebuilt'` is the honest answer for everything that is NOT a clean patch —
+ * a payload-less event, a detached maintainer, an already-stale one. A
+ * consumer reading it must invalidate its own derived state; it must never
+ * read `'rebuilt'` as "nothing happened".
+ *
+ * A `'patched'` outcome with neither `removed` nor `inserted` DID happen: a
+ * non-member changed and stayed a non-member. That is a no-op for every
+ * derived layer, which is exactly why it is reported as a patch rather than a
+ * rebuild.
+ */
+export type PatchOutcome = {
+    readonly kind: 'rebuilt';
+} | {
+    readonly kind: 'patched';
+    readonly id: string;
+    readonly removed?: PatchDelta;
+    readonly inserted?: PatchDelta;
+};
+/** An id-paired member of the maintained set, in maintained order. */
+export interface MaintainedEntry {
+    readonly id: string;
+    readonly seq: number;
+    readonly record: unknown;
+}
+/**
+ * The subset of a query source a DERIVED maintainer needs (#1341, grouped
+ * half). Deliberately a kernel type even though its only consumer today is
+ * the reduce service: everything in it is a kernel concept, and declaring it
+ * here is what lets `kernel/query/builder.ts` hand one to the service without
+ * a new spine to service import specifier.
+ */
+export interface GroupMaintenanceSource {
+    /**
+     * Id-paired snapshot, in snapshot (Map insertion) order.
+     *
+     * ⚠️ Declared as function-typed PROPERTIES, not methods: every member here
+     * is a standalone closure the query builder binds before handing it over,
+     * and property syntax says so — a method declaration would invite a `this`
+     * these closures do not have.
+     */
+    readonly snapshotEntries: () => readonly {
+        id: string;
+        record: unknown;
+    }[];
+    /** O(1) current-state lookup for the AFTER state of a change. */
+    readonly lookupById: (id: string) => unknown;
+    /** The plan's membership test — the same one the eager path runs. */
+    readonly matches: (record: unknown) => boolean;
+    /**
+     * Per-record projection the eager grouping pipeline applies AFTER filtering
+     * and before bucketing — today only `projectDateTruncKeys` (#1350). Applied
+     * per record here because the eager path applies it per record too; a
+     * projection that read across records could not be maintained and must not
+     * be plumbed through this hook.
+     */
+    readonly project?: (record: unknown) => unknown;
+}
+/** Everything the maintainer needs, supplied by the query builder. */
+export interface MaintainerConfig {
+    /** Id-paired snapshot, in snapshot (Map insertion) order. */
+    snapshotEntries(): readonly {
+        id: string;
+        record: unknown;
+    }[];
+    /** O(1) current-state lookup, used to read the AFTER state of a change. */
+    lookupById(id: string): unknown;
+    /** The plan's membership test — the same one the eager path runs. */
+    matches(record: unknown): boolean;
+    /**
+     * The plan's ordering, in the same key-plan shape `sortRecords` and the
+     * keyset cursor use (#1346): read a record's sort-key tuple, and compare two
+     * of those tuples. `undefined` when the plan has no `orderBy` — result order
+     * is then snapshot order alone.
+     *
+     * `compare` need not be a total order: it returns 0 for equal sort keys,
+     * exactly as it does for the eager sort, and the maintainer resolves those
+     * ties by snapshot sequence.
+     */
+    order?: {
+        keyOf(record: unknown): unknown[];
+        compare(a: readonly unknown[], b: readonly unknown[]): number;
+    };
+    /** Plan offset (0 when unset). */
+    offset: number;
+    /** Plan limit, or undefined for "all matching rows". */
+    limit: number | undefined;
+    /**
+     * Post-slice projection the eager path applies to the emitted window (Via
+     * result decoding). Applied to the window, never to the maintained records,
+     * mirroring `toArray()` which decodes AFTER filter/sort/slice.
+     */
+    decode?: (rows: readonly unknown[]) => unknown[];
+}
+/**
+ * Reject any plan whose result set cannot be provably patched from a single
+ * record's delta. Everything this refuses still works — it just re-runs in
+ * full, as it did before #1341.
+ *
+ * Refused, and why:
+ *   - **joins / crossJoin** — a row's membership depends on other collections'
+ *     records, so a left-side delta does not determine the new result.
+ *   - **`.filter(fn)`** — an arbitrary consumer closure with no determinism
+ *     guarantee. `r => r.due < Date.now()` changes its verdict for records that
+ *     never changed, which a full re-run observes and a patch cannot.
+ *     (`.wherePredicate()` is admitted: it is DECLARED deterministic and
+ *     carries a body hash saying so.)
+ *   - **`orderBy(..., { by: 'label' })`** — the label maps are built eagerly
+ *     from a dictionary collection's snapshot, so the comparator would be
+ *     captured at subscribe time and go stale when that dictionary changes.
+ *   - **an index-driven plan** — the rows then reach the pipeline in INDEX
+ *     order rather than snapshot order, so snapshot sequence is the wrong
+ *     tiebreak among equal sort keys. Three shapes qualify, and all three are
+ *     refused: an `==`/`in` clause on any indexed field, a range clause on a
+ *     SORTED-indexed field, and #1344's `orderedIndexRows()` page, which
+ *     serves `orderBy(f).limit(n)` straight off a sorted index with no
+ *     predicate at all. Little is lost: each of those re-runs is already
+ *     proportional to the page or the match set, not to the collection.
+ */
+export declare function canMaintainIncrementally(plan: {
+    readonly clauses: readonly Clause[];
+    readonly orderBy: readonly OrderBy[];
+    readonly limit?: number | undefined;
+    readonly joins: readonly unknown[];
+}, indexes: IndexProbe | null): boolean;
+/**
+ * What the maintainer needs to know about the source's indexes: which fields
+ * carry ANY index, and which carry a SORTED one. Both matter — the sorted
+ * index feeds two paths (#1344) the hash index does not.
+ */
+export interface IndexProbe {
+    covers(field: string): boolean;
+    sorted(field: string): boolean;
+}
+/**
+ * The maintained result set behind one live query.
+ *
+ * Lifecycle: `attach()` when a subscription opens, `apply(change)` per upstream
+ * event, `rows()` to read the current window. Before `attach()` (and after any
+ * fallback) `rows()` recomputes from the snapshot, so a detached maintainer is
+ * simply an eager executor and is safe to read at any time.
+ */
+export declare class LiveMaintainer {
+    private readonly cfg;
+    private entries;
+    private readonly memberById;
+    private seqById;
+    private maxSeq;
+    /** Maintained state is stale — the next `rows()` rebuilds from the snapshot. */
+    private stale;
+    /** True once a subscription is driving `apply()`. */
+    private attached;
+    constructor(cfg: MaintainerConfig);
+    /**
+     * Start accepting deltas. Every read before this rebuilds from the snapshot,
+     * so a detached maintainer is just an eager executor.
+     *
+     * ⚠️ Call this in the SAME synchronous turn as a read — either immediately
+     * before the first `rows()` (the `.live()` path) or immediately after the
+     * initial one (the `.aggregate().live()` path, where the reduction computes
+     * before it subscribes). Attaching in a turn of its own would let a mutation
+     * slip past unrecorded: it arrives with no subscription to `apply()` it, and
+     * the maintained state would then be trusted while already behind.
+     */
+    attach(): void;
+    /**
+     * Stop accepting deltas — the subscription feeding them has gone. Every
+     * later read rebuilds, because nothing is keeping the state current any
+     * more. Without this, a `Reduction` whose `.live()` was stopped would keep
+     * serving its last maintained value from `.run()`.
+     */
+    detach(): void;
+    /** Force the next read to rebuild — the caller saw something it can't patch. */
+    invalidate(): void;
+    /**
+     * Fold one upstream change into the maintained set. A change with no
+     * payload (the source could not say which record moved) invalidates
+     * instead — the next read pays for a full rebuild.
+     */
+    apply(change: SourceChange | undefined): PatchOutcome;
+    /** The current result window — a fresh array on every call. */
+    rows(): unknown[];
+    /**
+     * The whole maintained set — every matching record, in maintained order,
+     * paired with its id and snapshot sequence. Ignores `offset`/`limit`/
+     * `decode` on purpose: this is the input a DERIVED maintainer rebuilds from,
+     * and grouped aggregation reduces the full match set, never a window.
+     *
+     * Rebuilds first when detached or stale, exactly as `rows()` does, so a
+     * caller can read it at any time.
+     */
+    maintainedEntries(): readonly MaintainedEntry[];
+    /**
+     * Full recompute from the source snapshot. Equivalent to the eager path by
+     * construction: filter in snapshot order, then sort with snapshot sequence
+     * as the tiebreak — which is what a stable sort of the same input does.
+     */
+    private rebuild;
+    private patch;
+    private removeEntry;
+    /** First index whose entry does not sort before `probe`. */
+    private lowerBound;
+    private keyOf;
+    /**
+     * The eager path's ordering, made total.
+     *
+     * `order.compare` is the query's own `compareOrderKeys`, the identical
+     * function `sortRecords` sorts with, so sort keys cannot be read or ranked
+     * differently here. It returns 0 for equal keys — it can do nothing else,
+     * having been handed the keys rather than the records — and the eager sort
+     * then leaves those in the order they arrived, which is candidate order,
+     * which is snapshot order given `canMaintainIncrementally` has refused every
+     * plan whose candidates arrive in index order. The sequence number below is
+     * that same resolution, made explicit so a binary search has an exact
+     * position to find. ⚠️ If the eager path ever grows a tiebreak of its own
+     * (an id, say), this stops agreeing with it — which is what
+     * `__tests__/query-incremental.test.ts`'s "inherits an order key plan that
+     * leaves equal keys to the tiebreak" is there to catch.
+     */
+    private compareEntries;
+}

package/dist/kernel/query/live/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@noy-db/hub/query/live` — **the Live group of the query DSL.**
+ *
+ * ```ts
+ * import '@noy-db/hub/query/live'   // once, in your app's entry
+ *
+ * const stop = invoices.query().where('status', '==', 'paid').subscribe(rows => render(rows))
+ * ```
+ *
+ * ⭐ **Imported for its side effect** — it patches `subscribe` and `live` onto
+ * `Query.prototype` and merges their types into `Query`. See
+ * `../relate/index.ts` for the full note on why `package.json`'s `sideEffects`
+ * array must keep naming this file.
+ */
+import type { LiveSurface } from './methods.js';
+declare module '../builder.js' {
+    interface Query<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> extends LiveSurface<T, S, Q, M> {
+    }
+}
+export { buildLiveQuery } from './live.js';
+export type { LiveQuery, LiveUpstream, LiveBuildOptions } from './live.js';
+export type { SourceChange } from './incremental.js';

package/dist/kernel/query/live/install.d.ts

@@ -0,0 +1,2 @@
+/** Idempotent: the root barrel and the subpath entry both call it. */
+export declare function installLive(): void;

package/dist/kernel/query/{live.d.ts → live/live.d.ts}

@@ -38,18 +38,26 @@
  * vault + name. Vault's `resolveSource` reads from
  * `collectionCache` so this assumption holds.
  *
- * **What .live() does NOT do in v1:**
- *   - No granular delta updates — the whole query re-runs on every
- *     change. Granular delta tracking is a v2 optimization once
- *     the API is stable.
- *   - No batching of bursty changes — one event in, one re-run
- *     out. Batching with microtask coalescing is a v2 enhancement.
- *   - No async notifications — every notification is synchronous
+ * **Delta maintenance (#1341).** A live query over a plan
+ * `canMaintainIncrementally()` admits no longer re-runs: the change event
+ * carries which record moved, and `LiveMaintainer` patches the result set —
+ * one predicate evaluation, a binary search, a splice. The emitted value is
+ * identical to a re-run's, because the maintainer is handed the query's OWN
+ * membership test and sort comparator. Every other plan, and every
+ * notification that arrives without a delta, re-runs exactly as before.
+ *
+ * **What .live() still does NOT do:**
+ *   - No batching unless asked — `live({ batch: true })` coalesces a burst
+ *     into one recompute + one notification on a microtask; the default stays
+ *     one event in, one notification out, because batching makes `value`
+ *     stale until the microtask runs.
+ *   - No async notifications — every unbatched notification is synchronous
  *     within the source's change handler.
  *   - No re-planning under live mutations — the planner picks once
  *     at subscription time and reuses the same plan for every
  *     re-run.
  */
+import type { LiveMaintainer, SourceChange } from './incremental.js';
 /**
  * The reactive primitive returned by `Query.live()`.
  *
@@ -118,7 +126,29 @@ export interface LiveQuery<T> {
  * `JoinableSource.subscribe` (added in ).
  */
 export interface LiveUpstream {
-    subscribe(cb: () => void): () => void;
+    /**
+     * `cb` may be handed the delta that caused the notification (#1341) so the
+     * live query can patch its result set instead of re-running. Calling it with
+     * NO argument is always valid and always correct — it means "something
+     * changed, I can't say what", and the live query answers with a full re-run.
+     */
+    subscribe(cb: (change?: SourceChange) => void): () => void;
+}
+/** Options for {@link buildLiveQuery}. */
+export interface LiveBuildOptions {
+    /**
+     * Coalesce a burst of upstream changes into ONE recompute and ONE
+     * notification, flushed on a microtask (#1341). Off by default: with it on,
+     * `live.value` is stale until the microtask runs, so a consumer that reads
+     * synchronously after an `await put()` would see the old value.
+     */
+    readonly batch?: boolean;
+    /**
+     * Incremental maintainer for this query's result set. When present it
+     * REPLACES `recompute` as the value source — it patches per delta and
+     * rebuilds itself whenever a delta is not provably patchable.
+     */
+    readonly maintainer?: LiveMaintainer;
 }
 /**
  * Build a LiveQuery from a `recompute` callback (typically the
@@ -130,4 +160,4 @@ export interface LiveUpstream {
  * thrown by recompute are caught and stored in `error` instead of
  * propagating — see the file docstring for the rationale.
  */
-export declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly LiveUpstream[]): LiveQuery<T>;
+export declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly LiveUpstream[], options?: LiveBuildOptions): LiveQuery<T>;

package/dist/kernel/query/live/methods.d.ts

@@ -0,0 +1,107 @@
+/**
+ * #1458 — **Live**: the same plan, re-run on change.
+ *
+ * `subscribe` · `live`
+ *
+ * Bodies moved out of `kernel/query/builder.ts` unchanged; see
+ * `../relate/methods.ts` for why `this.plan` still resolves.
+ */
+import type { DeclaredPredicate, InternalSource, QueryPlan } from '../builder.js';
+import type { JoinContext } from '../relate/join.js';
+import type { ReduceStrategy } from '../../../with-lookup/reduce/strategy.js';
+import type { LiveQuery } from './live.js';
+import type { LiveMaintainer } from './incremental.js';
+import type { DateTruncKey } from '../reduce/date-trunc.js';
+import type { GroupMaintenanceSource } from './incremental.js';
+/** @internal — the mixin whose prototype `./index.ts` copies onto `Query`. */
+export declare class LiveMethods<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> {
+    protected readonly source: InternalSource;
+    protected readonly plan: QueryPlan;
+    protected readonly joinContext: JoinContext | undefined;
+    protected readonly reduceStrategy: ReduceStrategy;
+    protected readonly predicates: ReadonlyMap<string, DeclaredPredicate> | undefined;
+    protected decodeVia: (records: readonly unknown[], locale?: string) => unknown[];
+    protected incrementalMaintainer: (mode: 'rows' | 'records') => LiveMaintainer | undefined;
+    protected groupMaintenance: (derived: readonly DateTruncKey[]) => GroupMaintenanceSource | undefined;
+    toArray: (opts?: {
+        locale?: string;
+    }) => T[];
+    /**
+     * Re-run the query whenever the source notifies of changes.
+     * Returns an unsubscribe function. The callback receives the latest result.
+     * Throws if the source does not support subscriptions.
+     *
+     * **For joined queries, prefer `.live()`** — `subscribe()`
+     * only re-fires on LEFT-side changes, so joined data can be
+     * stale if the right side mutates between emissions. `.live()`
+     * merges change streams from every join target.
+     */
+    subscribe(cb: (result: T[]) => void): () => void;
+    /**
+     * Reactive terminal — returns a `LiveQuery<T>` that re-runs the
+     * query and updates its `value` whenever any source feeding it
+     * mutates..
+     *
+     * For non-joined queries, `.live()` is a convenience over the
+     * existing `.subscribe()` callback shape: a hand-rolled reactive
+     * primitive with `value` / `error` fields and a `subscribe(cb)`
+     * notification channel. Frame-agnostic — Vue / React / Solid
+     * adapters wrap it in their own primitive.
+     *
+     * For joined queries, `.live()` additionally subscribes to every
+     * join target's change stream. Mutations on a right-side
+     * collection (insert / update / delete of a client referenced by
+     * an invoice) re-fire the live query and re-evaluate every
+     * dependent left row. Right-side targets are deduped by
+     * collection name, so a chain that joins the same target twice
+     * (e.g. billing client + shipping client → both 'clients') only
+     * subscribes once.
+     *
+     * **Ref-mode behavior on right-side disappearance** — matches the
+     * eager `.toArray()` contract from :
+     *   - `strict`  → re-run throws `DanglingReferenceError`. The
+     *     LiveQuery catches the throw, stores it in `live.error`, and
+     *     notifies listeners (the throw does NOT propagate out of
+     *     the source's change handler — that would tear down the
+     *     emitter). Consumers check `live.error` after each
+     *     notification and render an error state in the UI.
+     *   - `warn`    → joined value flips to `null`; the existing
+     *     warn-channel deduplication keeps repeated re-runs from
+     *     spamming the console.
+     *   - `cascade` → no special handling needed; the cascade-
+     *     delete mechanism propagates the right-side delete into the
+     *     left collection on the next tick, and the live query
+     *     naturally re-fires with the orphaned left rows gone.
+     *
+     * Always call `live.stop()` when finished — it tears down every
+     * upstream subscription. The Vue layer's `onUnmounted` hook
+     * should call `stop()` automatically; raw consumers must do it
+     * themselves.
+     *
+     * **Incremental maintenance (#1341).** For a plan
+     * `incrementalMaintainer()` accepts — no joins, no `.filter(fn)`, no
+     * label-sort, and nothing an index would serve in index order (an `==`/`in`
+     * probe, #1344's sorted-index range, or #1344's `orderBy(f).limit(n)`
+     * index page) — the result set is PATCHED per change
+     * event instead of re-run: one predicate evaluation for the changed record,
+     * a binary search, a splice. Everything else, and any change event that
+     * arrives without a delta, still re-runs the whole plan. Either way the
+     * emitted value is identical to `toArray()` — the maintainer reuses this
+     * query's own membership test and sort comparator.
+     *
+     * `options.batch` coalesces a burst of changes into one recompute and one
+     * notification on a microtask. It is OFF by default because it makes
+     * `live.value` stale until the microtask runs: a consumer that reads
+     * synchronously after `await put()` would see the previous value.
+     *
+     * **Limitations:**
+     *   - No re-planning under live mutations — the planner picks
+     *     once at subscription time and reuses the same plan.
+     *   - Streaming live joins are deferred.
+     */
+    live(options?: {
+        batch?: boolean;
+    }): LiveQuery<T>;
+}
+/** The public Live surface — merged into `Query` by `./index.ts`. */
+export type LiveSurface<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> = Pick<LiveMethods<T, S, Q, M>, 'subscribe' | 'live'>;

package/dist/kernel/query/predicate.d.ts

@@ -7,7 +7,45 @@
  * dependency on any Via feature's implementation — still tree-shakeable.
  */
 /** Comparison operators supported by the where() builder. */
-export type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'contains' | 'startsWith' | 'between';
+export type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in'
+/**
+ * Set non-membership (#1351) — the anti-semi-join half of `in`.
+ *
+ * ⚠️ A NULLISH stored value MATCHES `!in`, deliberately: this module
+ * treats an absent field as "not equal" everywhere (`!=`, and money's
+ * `evaluateMoneyClause`), so `!in` follows. SQL's `NOT IN (…)` is
+ * three-valued and would EXCLUDE the row; noy-db has no NULL logic and
+ * inventing one here would make `!in` disagree with `!=` on the same
+ * record. Spell the SQL behaviour as `.where(f, '!=', undefined)` before
+ * the `!in`.
+ *
+ * ⛔ Never index-served. A hash bucket answers "which ids hold this
+ * value"; a negation needs the complement, which is the whole
+ * collection minus a bucket — so `!in` always falls to the scan, the
+ * same as `!=`.
+ */
+ | '!in' | 'contains' | 'startsWith' | 'between'
+/**
+ * Regex / SQL-LIKE pattern match (#1357). Operand: a `RegExp`, or a
+ * LIKE string. Normalized at `where()` time by {@link normalizeMatches}
+ * — an anchored literal prefix is LOWERED to `startsWith` (so it takes
+ * the sorted index), everything else is stored as `{ source, flags }`
+ * and evaluated per record.
+ */
+ | 'matches'
+/**
+ * Proximity (#1355) — operand `{ lat, lng, radiusKm }`, matching a
+ * record whose stored point is within `radiusKm` great-circle
+ * kilometres of the centre.
+ *
+ * ⛔ MEANINGFUL ONLY OVER A `geo()`-DECLARED FIELD. Every other field
+ * has no point to measure, so the case below returns false rather than
+ * guessing at a `{lat,lng}`-shaped object — the geo binding owns both
+ * the comparison and the index cover, and an undeclared field has
+ * neither. `where()` is where a malformed operand throws; here a
+ * type mismatch is simply "no match", as it is for every operator.
+ */
+ | 'near';
 /**
  * A single field comparison clause inside a query plan.
  * Plans are JSON-serializable, so this type uses primitives only.
@@ -41,6 +79,21 @@ export interface FieldClause {
          */
         readonly indexValue?: unknown;
     };
+    /**
+     * Provenance of an `in`/`!in` operand that arrived as a SUBQUERY (#1351)
+     * rather than as a literal array. Set by {@link normalizeSubqueryOperand};
+     * `value` already holds the RESOLVED id array by the time this is present.
+     *
+     * Plain data on purpose — it is part of the plan JSON, so it folds into an
+     * MV's `queryHash` and discriminates two queries whose resolved id sets
+     * happen to coincide but whose inner sources differ.
+     */
+    readonly subquery?: {
+        /** The inner source's `identity` (`<vault>/<collection>`), or `'(unnamed)'`. */
+        readonly from: string;
+        /** How many ids the inner query produced. */
+        readonly ids: number;
+    };
 }
 /**
  * A user-supplied predicate function escape hatch. Not serializable.
@@ -95,6 +148,18 @@ export interface CrossJoinClause {
     readonly target: string;
     /** Alias under which the right-side record is exposed on each result row. */
     readonly as: string;
+    /**
+     * Alias under which the LEFT row is exposed (#1289, `.crossJoinWith()`).
+     * `undefined` — every clause `.crossJoin()` builds — spreads the left row's
+     * own fields at the top level, which is the pre-#1289 shape.
+     *
+     * Set, the row becomes `{ [leftAs]: left, [as]: right }` and NO field sits
+     * at the top level. That is the whole point (a self-join needs both sides
+     * distinguishable) and also its whole cost: Via dressing keys by bare field
+     * name, so an aliased row is invisible to the top-level decode and must be
+     * dressed per alias instead. See `dressAliases` in `builder.ts`.
+     */
+    readonly leftAs?: string;
     /**
      * Lateral filter callback. `undefined` → full cartesian product.
      * Two call shapes:
@@ -128,6 +193,59 @@ export declare function readPath(record: unknown, path: string): unknown;
  * exclude non-matching records by definition.
  */
 export declare function evaluateFieldClause(record: unknown, clause: FieldClause): boolean;
+/**
+ * The generic comparison, with no record and no Via involved.
+ *
+ * Split out of {@link evaluateFieldClause} (#1355) so a Via binding can
+ * DELEGATE the operators it does not itself define. That matters more than
+ * it sounds: a binding that claims a field for one operator and declines
+ * the rest leaves the others with `clause.via` unset, and an unset `via` is
+ * exactly what tells `candidateRecords()` a secondary index may serve the
+ * clause. For a binding that also rewrites the index KEY
+ * (`canonicalizeIndexKey`), that combination lets the index and the scan
+ * answer the same clause differently. Claiming every operator and routing
+ * the uninteresting ones back here keeps the two in step.
+ */
+export declare function evaluateOperator(actual: unknown, op: Operator, value: unknown): boolean;
+/**
+ * Resolve a SUBQUERY operand of `in`/`!in` into the literal id array the rest
+ * of the engine already knows how to handle (#1351).
+ *
+ * ⭐ THE INNER QUERY RUNS HERE — ONCE, at `where()` BUILD time — and never
+ * again. That is the whole design, and it is what keeps an O(n) filter from
+ * becoming O(n·m): by the time a record is evaluated the clause holds a plain
+ * array, so `candidateRecords()` dispatches it through the hash index exactly
+ * as it does a hand-written list. `__tests__/query-subquery-in.test.ts`
+ * witnesses it with an evaluation counter, not by inspection.
+ *
+ * ⚠️ THE PRICE, stated once: the operand is a SNAPSHOT taken when `where()`
+ * was called. A query object built now and executed later — `.live()` being
+ * the case that matters — keeps the id set it was built with, so a change to
+ * the INNER collection does not re-fire the outer live query and does not
+ * change its answer. Rebuild the query to pick up a new inner result.
+ *
+ * Every other operator, and an operand that is not a Query, passes through
+ * untouched — including a malformed one, which keeps this a resolution step
+ * and not a new validation gate.
+ */
+export declare function normalizeSubqueryOperand(op: Operator, value: unknown): {
+    op: Operator;
+    value: unknown;
+    subquery?: FieldClause['subquery'];
+};
+/**
+ * Normalize a `where(field, 'matches', operand)` at BUILD time: refuse an
+ * unsafe pattern, lower an anchored literal prefix to `startsWith`, and
+ * otherwise serialize to `{ source, flags }`. Every other operator passes
+ * through untouched.
+ *
+ * Called by every `where()` (`Query`, `ScanBuilder`, `LazyQuery`) so all
+ * three build the same clause for the same call.
+ */
+export declare function normalizeMatches(op: Operator, value: unknown): {
+    op: Operator;
+    value: unknown;
+};
 /**
  * Evaluate any clause (field / filter / group) against a record.
  * The recursion depth is bounded by the user's query expression — no risk of