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

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

@@ -7,13 +7,15 @@
 import type { QueryField } from '../types.js';
 import type { Clause, Operator } from './predicate.js';
 import type { CollectionIndexes } from '../../with-lookup/indexing/eager-indexes.js';
-import type { JoinContext, JoinLeg, JoinStrategy } from './join.js';
-import type { LiveQuery } from './live.js';
-import type { ReduceSpec, ReduceResult, Reduction } from '../../with-lookup/reduce/reduction.js';
-import type { ReducerBuilder } from '../../with-lookup/reduce/reducers.js';
-import type { GroupedQuery, GroupedQueryN } from '../../with-lookup/reduce/groupby.js';
+import type { JoinContext, JoinLeg } from './relate/join.js';
+import type { HydrationGate } from './hydration.js';
+import type { SourceChange } from './live/incremental.js';
 import { type ReduceStrategy } from '../../with-lookup/reduce/strategy.js';
 import type { ViaPipeline } from '../via/pipeline.js';
+export declare function splitAroundJoins(clauses: readonly Clause[], joins: readonly JoinLeg[]): {
+    readonly preJoin: readonly Clause[];
+    readonly postJoin: readonly Clause[];
+};
 export interface OrderBy {
     readonly field: string;
     readonly direction: 'asc' | 'desc';
@@ -41,6 +43,16 @@ export interface QueryPlan {
     readonly orderBy: readonly OrderBy[];
     readonly limit: number | undefined;
     readonly offset: number;
+    /**
+     * Opaque keyset cursor from `.after(cursor)` (#1346). When present, the
+     * window starts strictly after the `(sortKey, id)` the cursor names,
+     * instead of at a positional offset.
+     *
+     * OPTIONAL, unlike its `limit`/`offset` neighbours: `QueryPlan` is an
+     * exported type that consumers construct, so a required new property would
+     * be a breaking change where an optional one is additive.
+     */
+    readonly after?: string | undefined;
     /**
      * Zero-or-more join legs to apply after where/orderBy/limit/offset.
      * Each leg attaches a resolved right-side record (or null) under its
@@ -48,8 +60,72 @@ export interface QueryPlan {
      */
     readonly joins: readonly JoinLeg[];
 }
-/** Default row ceiling for cross-join expansion. Matches JoinTooLargeError's ceiling. */
-export declare const DEFAULT_CROSS_JOIN_MAX_ROWS = 50000;
+/**
+ * Guard for the terminals that reduce rather than project (#1030). Grouping
+ * or aggregating over a joined alias silently bucketed every row under
+ * `undefined`, because these terminals never apply join legs at all.
+ *
+ * ⭐ **`aggregate()` and `groupBy()` NO LONGER CALL THIS — #1338 supplied the
+ * work the analysis below specifies, and they route instead of refusing.**
+ * The remaining caller is `distinct()`, whose Via question is a different one
+ * (`distinctKeyOf` canonicalises through the LEFT pipeline's index key, so an
+ * aliased value would dedup on the wrong canonicaliser) and which no issue has
+ * asked for. Everything below is the analysis #1338 was built from; it is kept
+ * because it names WHICH properties had to hold, and `join-reduce.ts` is where
+ * each one is now discharged:
+ *
+ *   - the right side's reducer rewrite AND its posture gate, in one call —
+ *     `joinAliasBinding` hands each aliased reducer to the right collection's
+ *     own `wrapReducers` under its bare field name;
+ *   - right-side change streams merged into the live upstreams —
+ *     `Query.rightSideUpstreams()`, shared with `live()`;
+ *   - and the case the analysis could not see, because the grouped terminal
+ *     is one object further along the chain than `Query.aggregate()`: a
+ *     reducer over an alias under a LEFT group key, which returned a confident
+ *     `0`. `refuseAliasBinding` refuses it.
+ *
+ * Refusing rather than reordering was a DELIBERATE, REVIEWED DECISION
+ * (2026-08-10), not an oversight. What follows is why, so it is not
+ * re-litigated from scratch — and so nobody "fixes" it for the wrong reason.
+ *
+ * It is NOT a cardinality problem. A ref join is an equi-join on the target's
+ * PRIMARY KEY, so every left row matches at most one right record and the row
+ * count is constant across legs (see `join.ts`). Aggregating over joined rows
+ * is perfectly well-defined; `count()` is unambiguous. Anyone who reads this
+ * guard as "the semantics are unclear" has the wrong model.
+ *
+ * The actual blocker is that the Via pipeline is LEFT-SCOPED. `aggregate()`
+ * runs `this.source.via.wrapReducers(spec)`, which resolves `postureFor(field)`
+ * against the LEFT collection's field map. For `sum('client.balance')` that map
+ * has no entry, so two things silently do not happen:
+ *
+ *   - money's exact-BigInt reducer rewrite is skipped, and a generic sum runs
+ *     over stored scaled-integer strings — silently wrong numbers;
+ *   - `refuseUnqueryableReducers` does not fire, so the `queryable: 'none'`
+ *     gate that would refuse the field never applies.
+ *
+ * A gate that silently does not apply is worse than a missing feature, which
+ * is why this refuses instead of guessing. Supporting joined aggregation means
+ * resolving a joined field's posture and reducers from the RIGHT collection's
+ * Via pipeline (via `joinContext.resolveSource`), plus merging right-side
+ * change streams into the live-reduction upstreams the way `Query.live()`
+ * already does — otherwise a live joined aggregate silently stops updating.
+ * That is the work. It is not "apply the legs here".
+ *
+ * Two things that are already handled, so they are not reasons to defer: the
+ * MV dependency analyzer already treats `plan.joins` targets as sources and
+ * folds them into the queryHash, and `.crossJoin()` — whose clause lives in
+ * the clause list — already aggregates correctly today. The error below points
+ * there because it is a real answer, not a consolation.
+ *
+ * Deliberately NOT tracked as an issue: no consumer has asked, and #984 is the
+ * cautionary tale — a speculative deferral whose premises had drifted out of
+ * sync with the code by the time anyone re-read it. Build this when a real
+ * query needs it, and design it against that query.
+ * ⭐ It was tracked as one three weeks later (#1338, the accounting-report
+ * shape) and built against that query — which is the paragraph above working,
+ * not failing.
+ */
 /**
  * Source of records that a query executes against.
  *
@@ -64,8 +140,15 @@ export declare const DEFAULT_CROSS_JOIN_MAX_ROWS = 50000;
 export interface QuerySource<T> {
     /** Snapshot of all current records. The query never mutates this array. */
     snapshot(): readonly T[];
-    /** Subscribe to mutations; returns an unsubscribe function. */
-    subscribe?(cb: () => void): () => void;
+    /**
+     * Subscribe to mutations; returns an unsubscribe function.
+     *
+     * A source that knows WHICH record changed passes the delta (#1341) so
+     * `.live()` can patch its result set rather than re-run the plan. Calling
+     * `cb()` with no argument stays valid — it means "something changed", and
+     * the live query answers with a full re-run.
+     */
+    subscribe?(cb: (change?: SourceChange) => void): () => void;
     /** Index store for the indexed-fast-path. Optional. */
     getIndexes?(): CollectionIndexes | null;
     /** O(1) record lookup by id, used to materialize index hits. */
@@ -84,22 +167,52 @@ export interface QuerySource<T> {
         id: string;
         record: T;
     }[];
+    /**
+     * #1414 — cold-collection gate. Present only on collection-backed eager
+     * sources. While `isHydrated()` is false the collection's snapshot is empty
+     * by ABSENCE, not by content, so every terminal returns a pending result
+     * (awaitable, and throwing on synchronous use) instead of a confident empty.
+     * See `query/hydration.ts`.
+     */
+    hydration?: HydrationGate;
+    /**
+     * Stable name for this source (`<vault>/<collection>`), used to bind a
+     * keyset cursor to the query that minted it (#1346) so a cursor replayed
+     * against another collection is refused rather than silently mis-paged.
+     */
+    identity?: string;
+    /**
+     * #1417 — monotonic mutation counter for the backing cache. Two reads
+     * returning the same number means nothing changed between them, which is
+     * what lets `page()`/`after()` reuse one sort across a page walk instead of
+     * re-sorting the whole collection per page.
+     *
+     * Optional, and absence is safe: a source that does not supply it simply
+     * gets no memo. It is a CHANGE COUNTER, never a content hash — see
+     * `kernel/generation-map.ts` for why it is maintained by the container
+     * rather than at the mutation sites.
+     */
+    snapshotVersion?(): number;
 }
 /**
- * The chainable builder. All methods return a new Query — the original
- * remains unchanged. Terminal methods (`toArray`, `first`, `count`,
- * `subscribe`) execute the plan against the source.
- *
- * Type parameter T flows through the public API for ergonomics, but the
- * internal storage uses `unknown` so Collection<T> stays covariant.
- *
- * The optional `joinContext` is attached when the Query is constructed
- * via `Collection.query()` (Collection passes in a context built from
- * the Vault's join resolver). A Query constructed via `new Query`
- * directly — e.g. from tests with a plain-object source — has no
- * joinContext, and calling `.join()` on it throws with an actionable
- * error. See `query/join.ts` for the full design.
+ * @internal #1458 — exported so the extension mixins in `query/{live,reduce,
+ * relate}/` can name the source they read. Not part of the published surface:
+ * `QuerySource<T>` above is what a consumer implements.
  */
+export interface InternalSource {
+    snapshot(): readonly unknown[];
+    subscribe?(cb: (change?: SourceChange) => void): () => void;
+    getIndexes?(): CollectionIndexes | null;
+    lookupById?(id: string): unknown;
+    via?: ViaPipeline;
+    snapshotEntries?(): readonly {
+        id: string;
+        record: unknown;
+    }[];
+    hydration?: HydrationGate;
+    identity?: string;
+    snapshotVersion?(): number;
+}
 /**
  * Declared deterministic predicate. Carries the consumer's
  * stable `hash` (for function-body identity), the function itself,
@@ -110,6 +223,67 @@ export interface DeclaredPredicate {
     hash: string;
     fn: (record: unknown, ctx?: unknown) => boolean;
 }
+/**
+ * The chainable query builder over an eager collection's decrypted cache.
+ *
+ * ## Its terminals are SYNCHRONOUS (#1413)
+ *
+ * `toArray()`, `ids()`, `page()`, `first()`, `count()` and `exists()` return
+ * their value directly — `T[]`, `string[]`, `{ rows, nextCursor }`, `T | null`,
+ * `number`, `boolean` — **not** a `Promise` of it. That is the architecture
+ * showing through, not an oversight: `Query` runs over `source.snapshot()`, an
+ * already-decrypted in-memory view. Decryption happened at hydration, so by the
+ * time a plan executes there is nothing left to await. Making these async would
+ * break every call site and erase the one property that distinguishes a cached
+ * query from a fetch.
+ *
+ * ⚠️ **So `.catch()` / `.then()` on a terminal's result is not part of the
+ * contract.** `query().toArray().catch(fn)` fails with *"catch is not a
+ * function"* on a loaded collection. Handle errors with `try` / `catch` around
+ * the call.
+ *
+ * `await` is always safe, though — awaiting a plain array yields the array —
+ * and on an unhydrated collection it is REQUIRED. See below.
+ *
+ * ## The one exception, and it is not an async terminal (#1414)
+ *
+ * On a collection that has never been loaded, a terminal cannot answer: the
+ * snapshot is empty by ABSENCE, not by content. Rather than return a confident
+ * `[]` / `0` / `false`, it returns a **pending result** — a thenable that
+ * hydrates and re-runs the terminal when awaited, and throws
+ * {@link CollectionNotHydratedError} on every use that READS it — `.length`,
+ * indexing, iteration, spread, `JSON.stringify`, any property access.
+ * `Array.isArray` answers `true`, so the ordinary defensive guard for a `T[]`
+ * reaches that throw rather than silently substituting `[]` (#1462); `typeof`
+ * and truthiness are the two uses that cannot throw, and
+ * `query/hydration.ts` enumerates why. It is deliberately NOT a
+ * promise-shaped array: the moment the collection is hydrated the very same
+ * call returns the plain synchronous value again. Write
+ * `await collection.query().toArray()` — correct in both states — or
+ * `await collection.list()` first and then read synchronously.
+ * See `query/hydration.ts`.
+ *
+ * ## Where the same name IS async
+ *
+ * `PartitionedQuery.toArray()` (`with-store/partitioned/index.ts`) and the lazy
+ * builder's `LazyQuery.toArray()` (`with-lookup/indexing/lazy-builder.ts`)
+ * return `Promise<T[]>`. Both genuinely fetch — across partition legs, or
+ * through the persisted `_idx/` side-car — so both genuinely await. Same
+ * method name, different contract, because the surface underneath differs.
+ *
+ * ---
+ *
+ * All non-terminal methods return a NEW Query — the original is unchanged.
+ * Type parameter T flows through the public API for ergonomics, but the
+ * internal storage uses `unknown` so `Collection<T>` stays covariant.
+ *
+ * The optional `joinContext` is attached when the Query is constructed via
+ * `Collection.query()` (Collection passes in a context built from the Vault's
+ * join resolver). A Query constructed via `new Query` directly — e.g. from
+ * tests with a plain-object source — has no joinContext, and calling `.join()`
+ * on it throws with an actionable error. See `query/join.ts` for the full
+ * design.
+ */
 export declare class Query<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> {
     private readonly source;
     private readonly plan;
@@ -129,6 +303,23 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      * queries constructed without a Collection backing).
      */
     _joinContext(): JoinContext | undefined;
+    /**
+     * @internal #1414 — clone this Query with the cold-collection gate REMOVED.
+     *
+     * For engine-internal readers only. The materialized-view engine reads its
+     * source collections through the public `collection.query()` on paths that
+     * are synchronous by construction (registration inspects the plan; the
+     * executor's row scan is called from inside a write commit), and it has
+     * always read whatever the in-memory cache held. Gating those would turn a
+     * pre-existing read into a throw for consumers who never asked a question —
+     * so this preserves that behaviour EXACTLY, and confines #1414's change to
+     * the surface a consumer or a guard actually calls.
+     *
+     * ⚠️ It does not make an unhydrated read correct — an MV computed over a
+     * cold source is the same defect wearing a different hat. That is tracked
+     * separately; do not reach for this to silence the gate in new code.
+     */
+    _ungated(): Query<T, S, Q, M>;
     /**
      * @internal — clone this Query with a declared-predicate map
      * attached. Used by the materialized-view registry to enable
@@ -145,6 +336,32 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      * Throws if the source is not collection-backed (no `snapshotEntries`).
      */
     _idArray(): string[];
+    /**
+     * The ids of the records this query matches (#1351) — the public spelling
+     * of {@link _idArray}, and the eager half of the subquery operand:
+     * `where(f, 'in', inner.ids())` and `where(f, 'in', inner)` build the SAME
+     * clause. Reach for the explicit form when you want to reuse the id set, or
+     * to see it.
+     *
+     * Requires a collection-backed query (`collection.query()`); a `crossJoin`
+     * plan is refused, because it produces new row objects and there is no id
+     * to recover.
+     *
+     * **Synchronous** (#1413) — returns `string[]`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+     */
+    ids(): string[];
+    /**
+     * @internal — the id-operand contract `normalizeSubqueryOperand()`
+     * (`predicate.ts`) duck-types when this Query is passed as the operand of
+     * `in`/`!in`. Separate from {@link ids} so the failure a subquery hits is
+     * phrased as a subquery failure rather than as a `retrieve({ within })` one.
+     */
+    _asIdOperand(): {
+        readonly ids: readonly string[];
+        readonly from: string;
+    };
     /**
      * Filter by a registered deterministic predicate. Requires
      * the Query to have been augmented with a predicates map (typically
@@ -200,6 +417,28 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
     }): Query<T, S, Q, M>;
     /** Cap the result size. */
     limit(n: number): Query<T, S, Q, M>;
+    /**
+     * Resume strictly after the row an opaque keyset cursor names (#1346).
+     *
+     * ```ts
+     * const first = people.query().orderBy('name').limit(20).page()
+     * const next = people.query().orderBy('name').limit(20).after(first.nextCursor!).page()
+     * ```
+     *
+     * Unlike `offset(n)`, the window is anchored to a `(sortKey, id)` position,
+     * so a record inserted or deleted before it — including the cursor's own
+     * row — cannot re-serve or skip a record.
+     *
+     * The cursor is OPAQUE: pass back a `nextCursor` from `.page()` verbatim
+     * and do not parse it. It is validated when the query executes (not here —
+     * the sort spec it is bound to may still be added to the chain), and a
+     * cursor from a different collection or a different `orderBy(...)` spec is
+     * REFUSED rather than mis-paged.
+     *
+     * Requires at least one `orderBy(...)`, an id-paired (collection-backed)
+     * source, no join legs and no `offset()`; each is a loud error at execution.
+     */
+    after(cursor: string): Query<T, S, Q, M>;
     /** Skip the first N matching records (after ordering). */
     offset(n: number): Query<T, S, Q, M>;
     /**
@@ -260,89 +499,69 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      * correlation goes through `Noydb.queryAcross`, not
      * `.join()`.
      */
-    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
-        as: As;
-        strategy?: JoinStrategy;
-        maxRows?: number;
-    }): Query<T & Record<As, R | null>, S, Q, M>;
-    /**
-     * Cartesian-product cross-join against `target` collection. Each result row
-     * carries the original `T` fields plus `result[as]` populated from every
-     * right-side row (or the filtered subset when `on:` is supplied).
-     *
-     * **⚠️ INNER-join semantics — an empty right subset DROPS the left row.**
-     * Each left row is emitted once per matching right row, so when `on:`
-     * yields nothing the row vanishes with no error, no warning and no count
-     * mismatch. This bites hardest on a reverse FK, where `.join()` (which is
-     * forward-only, and already a genuine LEFT outer join) does not apply and
-     * `.crossJoin()` is the only tool. To keep the row, return a one-element
-     * array holding `null`:
-     *
-     * ```ts
-     * .crossJoin('clients', { as: 'client', on: (b) => byEntity.get(b.entityId) ?? [null] })
-     * //                                                                          ^^^^^^^^
-     * //                                              the ONLY thing preserving the row
-     * ```
-     *
-     * **Prefer `outer: true`**, which does exactly this and types the alias as
-     * `TTarget | null`:
-     *
-     * ```ts
-     * .crossJoin('clients', { as: 'client', outer: true, on: (b) => byEntity.get(b.entityId) ?? [] })
-     * ```
-     *
-     * The `?? [null]` form remains valid and is what `outer` does internally, but
-     * it is invisible intent: it types the alias as non-null while the row can
-     * hold null, and a later "simplification" that drops it silently
-     * reintroduces the row loss.
-     *
-     * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
-     * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
-     * where clause references the aliased fields).
-     *
-     * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
-     * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
-     * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
-     *
-     * **`on:` shapes:**
-     *   - `on: (left) => TTarget[]`              — subset form (most efficient)
-     *   - `on: (left) => (right) => boolean`     — predicate form
-     *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
-     *     (requires the Query to have been augmented via `_withPredicates`)
-     *
-     * Requires a JoinContext (constructed via `collection.query()`).
-     */
-    crossJoin<TTarget = unknown, As extends string = string, TOuter extends boolean = false>(target: string, opts: {
-        as: As;
-        on?: ((left: T) => unknown[] | ((right: TTarget) => boolean)) | {
-            readonly predicate: string;
-        };
-        maxRows?: number;
-        /**
-         * Keep the left row when its right side is empty, with `null` under
-         * `as`, instead of dropping it (#1130). Widens the alias to
-         * `TTarget | null` — which is why it is a type parameter rather than a
-         * plain boolean: `outer: false` must not pay for a null the row can
-         * never hold.
-         */
-        outer?: TOuter;
-    }): Query<T & {
-        [K in As]: TOuter extends true ? TTarget | null : TTarget;
-    }, S, Q, M>;
     /**
      * Execute the plan and return the matching records. When the plan
      * carries any join legs, they are applied after `where` / `orderBy`
-     * / `limit` / `offset` narrow the left set. See the `.join()` doc
-     * for the ordering rationale.
+     * / `limit` / `offset` narrow the left set — UNLESS a clause (#1030) or
+     * the ordering (#1337) addresses a join alias, in which case the legs run
+     * first and the sort/page observe the joined relation. See the `.join()`
+     * doc for the ordering rationale, and `.explain()` for which one a given
+     * plan gets.
      *
      * `opts.locale` resolves JOINED right-side i18n fields at the
      * `join` layer to that locale; without it, the owning collection's default
      * locale applies, and a locale-less query leaves joined i18n fields raw.
      * (Left/base i18n fields are resolved by `get`/`list`, not here.)
+     *
+     * **Synchronous** (#1413) — returns `T[]`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
      */
     toArray(opts?: {
         locale?: string;
     }): T[];
+    /**
+     * Apply each aliased side's OWN Via result decode, in place of the
+     * top-level decode that cannot reach it (#1289, and the fix for #1335).
+     *
+     * `decodeVia` keys by bare field name, so it dresses exactly the fields
+     * sitting at the top of the row. Everything a join puts under an alias —
+     * a `.join()`/`.rightJoin()` right record, a `.crossJoin()` right record,
+     * and BOTH sides of a `.crossJoinWith()` pair — is therefore invisible to
+     * it, and was served raw: a self cross-join returned `"10.00"` on the left
+     * and `"1000"` on the right of the same field (#1335).
+     *
+     * Runs LAST, after every filter, sort and page. That is deliberate: a
+     * `where()` operand is built in raw stored space, so dressing earlier would
+     * make a post-join predicate compare a decoded string against a raw one.
+     * Dressing is presentation; it belongs after the plan has finished.
+     *
+     * Each alias is decoded by the Via pipeline of the collection the record
+     * came FROM — money on the right side is the right side's declaration, not
+     * this collection's. A source that declares no result decode returns the
+     * record unchanged, so the whole pass is a no-op for the common query and
+     * is skipped entirely when the plan has no aliases.
+     */
+    private dressAliases;
+    /**
+     * Alias → the Via pipeline of the collection whose records sit under it
+     * (#1337). Every alias this plan can produce: a `.join()`/`.rightJoin()`
+     * leg, a `.crossJoin()` right side, and both sides of `.crossJoinWith()`.
+     *
+     * ⭐ **Ordering compares in RAW STORED SPACE, never in dressed space, and
+     * that is what forces this map to exist.** `dressAliases` runs LAST — after
+     * every filter, sort and page — because a `where` operand is built raw. So
+     * the sort sees money as its stored scaled integer, where a generic compare
+     * is lexical and gets `'9882'` vs `'10004'` backwards. The left side has
+     * always avoided that by asking `source.via.compareForOrder`; an aliased
+     * field needs the same question asked of the RIGHT side's pipeline, keyed
+     * by the field name WITHOUT the alias prefix (a pipeline covers bare field
+     * names — that is the whole of #1335's shape).
+     *
+     * Empty when no alias resolves a pipeline, in which case the comparator
+     * falls back to exactly what it did before.
+     */
+    private aliasVia;
     /**
      * Joins need a `JoinContext`. Unreachable in practice — `.join()` throws
      * when one is missing — but belt-and-braces for a plan built through the
@@ -350,21 +569,97 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      */
     private requireJoinContext;
     /**
-     * Decode this source's Via-covered fields on read (e.g. money: stored
-     * scaled-int → canonical decimal), so `query().toArray()` agrees with
-     * `get()`/`sum()` on the value. No-op when the source's Via pipeline
-     * declares no result decode.
-     *
-     * The query layer carries no locale context, so money decodes with
-     * `'raw'` — canonical decimal, WITHOUT fabricating locale-formatted
-     * `<field>Formatted` / `<field>Number` virtuals. Producing a
-     * guessed-locale string here would reintroduce a "two read paths
-     * disagree" failure on the virtual field (e.g. it-IT via `get()` vs
-     * en-US here). Consumers who need formatted money read through
-     * `get()`/`list()` with a locale.
+     * Present this source's Via-covered fields on read, so `query().toArray()`
+     * agrees with `get()`/`list()` about what a record contains (#1416).
+     *
+     * ⛔ THIS USED TO RUN `decodeResults`, WHICH IS NOT THE SAME QUESTION. That
+     * hook is money's stored→canonical decode and nothing else, so a
+     * `computed({ mode: 'virtual' })` field read `undefined` on a query row while
+     * `get()` returned it — the same record with two shapes depending on which
+     * verb produced it, and a caller summing that field over a query result got
+     * `NaN` with no error. Reported at `receiptAmount get=84715.00 query=undefined`.
+     *
+     * The old doc comment defended the omission of money's `<field>Formatted` /
+     * `<field>Number` virtuals on the grounds that "the query layer carries no
+     * locale context", and that reasoning was right: fabricating a guessed-locale
+     * string here would make it-IT via `get()` disagree with en-US here. ⚠️ But
+     * the premise had gone stale — `toArray({ locale })` exists and threads its
+     * locale into `executePlanWithSource`, `applyJoins` and `applyOrderAndPage`.
+     * This was the one call site that never received it, which is also why joined
+     * ALIASES were dressed while the base row was not.
+     *
+     * So this presents at `'raw'`: values — money's canonical decode and every
+     * virtual computed field — while money's binding gates the locale-formatted
+     * virtuals on `locale !== 'raw'`, so nothing is guessed.
+     *
+     * ⛔ HONOURING `toArray({ locale })` HERE IS A SEPARATE CHANGE, and the
+     * obvious implementation is measurably wrong. Presenting twice — once raw for
+     * the plan, once at the locale for output — silently yields the RAW result:
+     *
+     *     presentSync(stored, raw)              -> { amount: "84715.00" }
+     *     presentSync(that,   'en-US')          -> { amount: "84715.00" }   <-- no siblings
+     *     presentSync(stored, 'en-US')          -> { amount: "84715.00",
+     *                                                amountFormatted: "THB 84,715.00", ... }
+     *
+     * because the second pass sees an already-decoded value and re-emits no
+     * siblings. So formatting has to happen in ONE pass at the final locale —
+     * and one of this method's call sites runs BEFORE the post-join filter,
+     * where a formatted value would change what a `where()` predicate compares
+     * against. That is the same rule `dressAliases` states: dressing is
+     * presentation and belongs after the plan has finished. Deciding it needs
+     * its own change; leaving `toArray({ locale })` inert for base rows is the
+     * status quo, not a new hole.
+     *
+     * ⚠️ SYNCHRONOUS, so it folds only the bindings that declared
+     * `presentIsSync` — money and computed. A collection also using i18n or
+     * lookup keeps those fields undressed here, exactly as today; `presentSync`
+     * reports them and `explain()` says so rather than leaving a silent hole.
+     * Making this complete would mean making `toArray()` async, which is the
+     * contract #1413 deliberately established.
      */
     private decodeVia;
-    /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields. */
+    /**
+     * Terminal sibling of `toArray()` that also returns the cursor for the next
+     * page (#1346): `{ rows, nextCursor }`, where `nextCursor` is `null` once
+     * the last page has been served.
+     *
+     * ```ts
+     * const { rows, nextCursor } = people.query().orderBy('name').limit(20).page()
+     * ```
+     *
+     * Without a sorted index this is still a scan with a keyset filter — stable,
+     * not fast. The fast path is a separate concern (#1344).
+     *
+     * Same requirements as `.after()`: at least one `orderBy(...)`, an id-paired
+     * (collection-backed) source, no join legs, no `offset()`.
+     *
+     * **Synchronous** (#1413) — returns `{ rows, nextCursor }`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+     */
+    page(opts?: {
+        locale?: string;
+    }): {
+        rows: T[];
+        nextCursor: string | null;
+    };
+    /**
+     * The keyset engine behind `page()` / `after()`.
+     *
+     * It deliberately does NOT reuse `applyOrderAndPage`: paging by keyset needs
+     * a TOTAL order (the id breaks ties that the ordinary sort leaves to input
+     * order) and needs the id alongside each row to mint the cursor. Both are
+     * properties of this path only, so the ordinary read path is untouched.
+     */
+    private executeKeyset;
+    /**
+     * Return the first matching record, or null. Joins are applied. `opts.locale`
+     * resolves joined i18n fields.
+     *
+     * **Synchronous** (#1413) — returns `T | null`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+     */
     first(opts?: {
         locale?: string;
     }): T | null;
@@ -383,173 +678,45 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      * A strict-mode `DanglingReferenceError` becomes reachable from `count()`
      * in exactly that case, which is acceptable: the caller asked to filter on
      * the joined side, so they asked for the join.
+     *
+     * **Synchronous** (#1413) — returns `number`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
      */
     count(): number;
     /**
-     * Reduce the matching records through a named set of reducers.
-     * the aggregation terminal.
-     *
-     * ```ts
-     * const { total, n, avgAmount } = invoices.query()
-     *   .where('status', '==', 'open')
-     *   .aggregate({
-     *     total:     sum('amount'),
-     *     n:         count(),
-     *     avgAmount: avg('amount'),
-     *   })
-     *   .run()
-     * ```
-     *
-     * Returns an `Reduction<R>` wrapper with two terminals:
-     *   - `.run(): R` — synchronous one-shot reduction
-     *   - `.live(): LiveReduction<R>` — reactive primitive that
-     *     re-runs the reduction whenever the source notifies of a
-     *     change. Always call `live.stop()` when finished.
-     *
-     * The reducer spec is bound here once and reused by both
-     * terminals — this is why `.aggregate()` returns a wrapper instead
-     * of being a direct terminal. Consumers who only need the static
-     * value read `.run()`; consumers wiring a reactive UI read
-     * `.live()`.
-     *
-     * Joins are intentionally NOT applied to aggregations in —
-     * the same logic as `.count()`. Joins in are projection-only
-     * (they attach an aliased field and never filter), so running
-     * them just to throw the aliases away would be wasteful. If you
-     * need a reducer that reads a joined field, open an issue —
-     * aggregations-across-joins is explicitly out of scope for v1.
-     *
-     * Every reducer factory accepts an optional `{ seed }` parameter
-     * that is plumbed through the protocol but unused by the
-     * executor — that's  constraint #2. When partition-aware
-     * aggregation lands, the seed will carry running state across
-     * partition boundaries without an API break.
-     *
-     * KNOWN GAP (sealed fields, bare-spec form): `where`/`orderBy`/`groupBy`
-     * refuse a `sensitive` field at compile time, but a reducer over a sensitive
-     * field in the BARE-SPEC form (e.g. `aggregate({ x: sum('ssn') })`) is NOT
-     * refused — the reducer factories (`sum`/`min`/`max`/…) are standalone
-     * `(field: string)` functions with no collection-type context. This form is
-     * preserved as-is for backward compatibility.
-     *
-     * The BUILDER form closes this gap: `aggregate(b => ({ x: b.sum('field') }))`
-     * types the builder's field parameter as `QueryField<T, S>`, refusing any
-     * `sensitive` field at compile time. Use the builder form for new code that
-     * aggregates over a collection with sensitive fields.
-     *
-     */
-    aggregate<Spec extends ReduceSpec>(spec: Spec): Reduction<ReduceResult<Spec>>;
-    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Reduction<ReduceResult<Spec>>;
-    /**
-     * Partition matching records into buckets keyed by a field, then
-     * terminate with `.aggregate(spec)` to compute per-bucket
-     * reducers..
-     *
-     * ```ts
-     * const byClient = invoices.query()
-     *   .where('status', '==', 'open')
-     *   .groupBy('clientId')
-     *   .aggregate({ total: sum('amount'), n: count() })
-     *   .run()
-     * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
-     * ```
-     *
-     * Result rows carry the group key value under the grouping field
-     * name plus every reducer output from the spec. Buckets are
-     * emitted in first-seen order — consumers who want a specific
-     * ordering should `.sort()` downstream.
-     *
-     * **Cardinality caps:** a one-shot warning fires at 10_000
-     * distinct groups; `GroupCardinalityError` throws at 100_000.
-     * Grouping on a high-uniqueness field like `id` or `createdAt` is
-     * almost always a query mistake — the error message names the
-     * field and observed cardinality and suggests narrowing with
-     * `.where()` first.
-     *
-     * **Null / undefined keys:** records with a missing or explicitly
-     * `null` group field get their own buckets. `Map`-based
-     * partitioning distinguishes `undefined` from `null`, so the two
-     * cases do NOT merge. Consumers who want them merged should
-     * coalesce upstream with `.filter()`.
-     *
-     * **Joins are not applied** — same rationale as `.count()` and
-     * `.aggregate()`. Joined fields in are projection-only, so
-     * running a join inside a grouping pipeline would be wasteful and
-     * could trigger `DanglingReferenceError` in strict mode for a
-     * call whose intent is purely to bucket-and-reduce. Grouping by
-     * a joined field is explicitly out of scope for — file an
-     * issue if a real consumer needs it.
-     *
-     * **Filter clauses (`.filter(fn)`):** grouped queries still
-     * support filter clauses in the underlying plan — they run in
-     * the same candidate/filter pipeline that `.aggregate()` uses.
-     * The performance caveat is the same: filter clauses cost O(N)
-     * per record and can't be index-accelerated.
-     */
-    groupBy<F extends QueryField<T, S>>(field: F): GroupedQuery<T, F, S, M>;
-    groupBy<F extends readonly [QueryField<T, S>, QueryField<T, S>, ...QueryField<T, S>[]]>(...fields: F): GroupedQueryN<T, F, S, M>;
-    /**
-     * 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.
-     *
-     * **Limitations:**
-     *   - No granular delta updates — the whole query re-runs on
-     *     every change.
-     *   - No microtask batching — bursty changes produce one re-run
-     *     per change.
-     *   - No re-planning under live mutations — the planner picks
-     *     once at subscription time and reuses the same plan.
-     *   - Streaming live joins are deferred.
-     */
-    live(): LiveQuery<T>;
+     * The match set every reduce-shaped terminal reports over: `count()`,
+     * `distinct()`, and `exists()`'s non-short-circuit fallbacks.
+     *
+     * Extracted (#1347) rather than copied a third time, because "which records
+     * does this terminal see" is an INVARIANT across them — `distinct()`
+     * returning values `count()` never counted would be a bug nobody would look
+     * for. It is deliberately the `count()` pipeline: where/filter apply, joins
+     * apply only when a predicate addresses one (#1030), and orderBy/limit/offset
+     * do NOT — those describe a page, and a reduction is not paginated.
+     */
+    private matchedRecords;
+    /**
+     * Whether ANY record matches (#1347) — `count() > 0` without paying for the
+     * records after the first.
+     *
+     * The saving is real rather than cosmetic: `count()` evaluates every
+     * remaining clause against every candidate, so a `.filter(fn)` over 10_000
+     * records calls `fn` 10_000 times to answer a yes/no question. This returns
+     * at the first hit, and `__tests__/query-distinct-exists.test.ts` witnesses
+     * that by COUNTING the predicate's invocations — a boolean assertion cannot
+     * tell a short-circuit from a full scan.
+     *
+     * Same match set as `count()`. Two shapes do NOT short-circuit and fall
+     * back to it, because both must materialize the relation before anything
+     * can be tested: a `crossJoin` expansion, and a `where` clause addressing a
+     * join alias (#1030). Both still answer correctly.
+     *
+     * **Synchronous** (#1413) — returns `boolean`, not a promise; the cache it reads is
+     * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+     * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+     */
+    exists(): boolean;
     /**
      * Return the plan as a JSON-friendly object. FilterClause entries are
      * stripped (their `fn` cannot be serialized) and replaced with
@@ -557,6 +724,95 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      */
     toPlan(): unknown;
 }
+export declare function isRangeOperator(op: string): op is '<' | '<=' | '>' | '>=' | 'between' | 'startsWith';
+/**
+ * True when a Via binding claims the ORDERING of this field. Probed with
+ * two equal strings: `compareForOrder` returns `undefined` for any field
+ * no binding covers (money checks its field map first; lookup checks its
+ * `sortBy` declaration), and a number for one it does.
+ */
+export declare function viaOrdersField(via: ViaPipeline | undefined, field: string): boolean;
+/**
+ * A range operand for the component just past a compound index's equality
+ * prefix. `op` repeats {@link isRangeOperator}'s union rather than importing
+ * `RangeOperator`, keeping this file's import list unchanged.
+ */
+/**
+ * The only slice of an index store the compound PICKERS read. Declared
+ * structurally (#1375) so `query/explain.ts` can share these pickers rather
+ * than re-implementing them — the mirror this file's `explain()` header warns
+ * about is one function narrower for every picker that moves here.
+ */
+export interface CompoundTupleSource {
+    compoundTuples(): ReadonlyArray<readonly string[]>;
+}
+export interface CompoundRange {
+    readonly op: '<' | '<=' | '>' | '>=' | 'between' | 'startsWith';
+    readonly value: unknown;
+}
+export interface CompoundPick {
+    readonly fields: readonly string[];
+    /** Equality operands for `fields[0..values.length-1]`, in index order. */
+    readonly values: readonly unknown[];
+    readonly range?: CompoundRange;
+    /** Indices into the plan's clause list that this pick answers. */
+    readonly consumed: ReadonlySet<number>;
+}
+/**
+ * Split the top-level clauses into the `==` and range clauses a compound
+ * index could answer. Via-covered clauses are excluded for the same reason
+ * `candidateRecords` excludes them from the sorted path — a binding's
+ * `indexProbe` yields an equality operand in STORED form, never an ordered
+ * one, and this path compares raw operands. A repeated field keeps its FIRST
+ * clause; the duplicate stays in `remainingClauses` and is re-evaluated.
+ */
+export declare function indexableClauses(clauses: readonly Clause[]): {
+    eq: Map<string, {
+        value: unknown;
+        at: number;
+    }>;
+    ranges: Map<string, {
+        op: CompoundRange['op'];
+        value: unknown;
+        at: number;
+    }>;
+};
+/**
+ * Choose the declared field tuple that answers the most clauses: the longest
+ * equality PREFIX of the tuple, plus a range on the component immediately
+ * after it. A pick answering fewer than two clauses is declined — the
+ * single-field hash or sorted index already covers that, at lower cost.
+ */
+export declare function pickCompound(indexes: CompoundTupleSource, clauses: readonly Clause[]): CompoundPick | null;
+/** The declared tuple that is exactly `eq`'s fields followed by `orderField`. */
+export declare function pickCompoundOrder(indexes: CompoundTupleSource, eq: ReadonlyMap<string, {
+    value: unknown;
+    at: number;
+}>, orderField: string): {
+    fields: readonly string[];
+    values: readonly unknown[];
+} | null;
+interface CandidateResult {
+    /** The reduced candidate set, materialized to record objects. */
+    readonly candidates: readonly unknown[];
+    /** The clauses that the index could not satisfy and must still be evaluated. */
+    readonly remainingClauses: readonly Clause[];
+}
+/**
+ * Pick a candidate record set using the index store when possible.
+ *
+ * Strategy: scan the top-level clauses for the FIRST `==` or `in` clause
+ * against an indexed field. If found, use the index to materialize a
+ * candidate set and return the OTHER clauses as `remainingClauses`. The
+ * caller skips re-evaluating the index-driving clause because the index
+ * is authoritative for that field.
+ *
+ * This is a deliberately simple planner. A future optimizer could pick
+ * the most selective index, intersect multiple indexes, or push composite
+ * keys through. For the single-index fast path is good enough.
+ */
+/** @internal #1458 — used by the extension mixins in `query/reduce/`. */
+export declare function candidateRecords(source: InternalSource, clauses: readonly Clause[]): CandidateResult;
 /**
  * Execute a plan against a snapshot of records.
  * Pure function — same input, same output, no side effects.
@@ -565,3 +821,78 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
  * cast the return type at the API surface (see `Query.toArray()`).
  */
 export declare function executePlan(records: readonly unknown[], plan: QueryPlan): unknown[];
+/**
+ * Build the per-record DECODED view factory for user-callback clauses
+ * (`filter` / `wherePredicate`) — those callbacks must see the canonical
+ * shape (e.g. money's decimal string), never a Via-transformed stored
+ * form. Field clauses are NOT affected: their operands were pre-built
+ * into raw stored space at build time. Returns undefined when the
+ * source's Via pipeline declares no result decode.
+ */
+/** @internal #1458 — used by `query/internal/maintenance.ts`. */
+export declare function fnViewDecoder(source: InternalSource): ((r: unknown) => unknown) | undefined;
+/** @internal #1458 — used by `query/internal/maintenance.ts`. */
+export declare function filterRecords(records: readonly unknown[], clauses: readonly Clause[], decodeForFns?: (r: unknown) => unknown): unknown[];
+/**
+ * Walk the clause list in declaration order, batching filter clauses and
+ * expanding on crossJoin clauses. Falls back to `candidateRecords + filterRecords`
+ * (index fast-path) when no crossJoin clauses are present.
+ *
+ * Precondition: `joinContext` must be non-null when any `CrossJoinClause` is in `clauses`.
+ */
+/** @internal #1458 — used by the extension mixins in `query/reduce/`. */
+export declare function executeClausePipeline(source: InternalSource, clauses: readonly Clause[], joinContext: JoinContext): unknown[];
+/**
+ * One `orderBy` entry, resolved: how to read its sort value off a record and
+ * how to compare two of those values.
+ *
+ * Split out of `sortRecords` so the keyset path (`page()`/`after()`) can
+ * compare a row against a cursor's STORED values with exactly the ordering
+ * the sort used — the alternative was a second comparator that would drift.
+ */
+interface OrderKeyPlan {
+    readonly entries: readonly {
+        readonly field: string;
+        readonly direction: 'asc' | 'desc';
+        readonly labelResolver: ((code: string) => string | undefined) | undefined;
+        /**
+         * The pipeline to ask for this entry's exact ordering, and the name to
+         * ask it about (#1337). For a left-side field that is the source's own
+         * pipeline and the field verbatim; for `client.credit` it is the RIGHT
+         * collection's pipeline and `credit`, because a pipeline covers bare
+         * field names. `undefined` → the generic comparator, as before.
+         */
+        readonly via: ViaPipeline | undefined;
+        readonly viaField: string;
+    }[];
+}
+/** @internal #1458 — used by `query/internal/maintenance.ts`. */
+export declare function buildOrderKeyPlan(orderBy: readonly OrderBy[], via?: ViaPipeline, labelMaps?: Map<string, (code: string) => string | undefined>, aliasVia?: ReadonlyMap<string, ViaPipeline>): OrderKeyPlan;
+/** The sort-key tuple of one record, in `orderBy` order. */
+/** @internal #1458 — used by `query/internal/maintenance.ts`. */
+export declare function orderKeyOf(plan: OrderKeyPlan, record: unknown): unknown[];
+/** @internal #1458 — used by `query/internal/maintenance.ts`. */
+export declare function compareOrderKeys(plan: OrderKeyPlan, a: readonly unknown[], b: readonly unknown[]): number;
+/**
+ * Exported (#1342) for the cross-collection union read path: a union's sort
+ * runs AFTER the legs are concatenated, and it has to be the same comparator
+ * a single collection's `orderBy` uses or two queries over the same rows
+ * would order them differently.
+ */
+export declare function sortRecords(records: unknown[], orderBy: readonly OrderBy[], via?: ViaPipeline, labelMaps?: Map<string, (code: string) => string | undefined>, aliasVia?: ReadonlyMap<string, ViaPipeline>): unknown[];
+/**
+ * Build a dict-label resolver for `Query.groupBy(field)` when the
+ * grouping field is a `dictKey`. Extracted from the inline closure
+ * inside `groupBy` so the multi-key path (which has no meaningful
+ * `<field>Label` shape) can skip it cleanly. Pure refactor — no
+ * behaviour change for the single-field path.
+ *
+ * Returns `undefined` when:
+ *   - the join context lacks a `resolveDictSource` hook, or
+ *   - no dictionary source is registered for `field`.
+ *
+ * @internal
+ */
+/** @internal #1458 — used by the extension mixins in `query/reduce/`. */
+export declare function buildDictLabelResolver(joinCtx: JoinContext | undefined, field: string): ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined;
+export {};