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

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

@@ -0,0 +1,426 @@
+/**
+ * #1458 — **Relate**: every multi-source and plan-level operation.
+ *
+ * `join` · `joinOn` · `rightJoin` · `fullOuterJoin` · `crossJoin` ·
+ * `crossJoinWith` · `traverse` · `ancestorsOf` · `descendantsOf` · `explain`
+ *
+ * The bodies below moved out of `kernel/query/builder.ts` UNCHANGED. They read
+ * `this.source` / `this.plan` / `this.joinContext` exactly as they did while
+ * they were class members, because at runtime that is precisely what they
+ * still are: `install()` copies them onto `Query.prototype`, and TypeScript's
+ * `private` never existed at runtime. The `declare` fields at the top of the
+ * mixin are how the compiler is told the same thing.
+ *
+ * ⚠️ **Do not import this module for its side effects — import
+ * `./index.js`.** This file defines the methods; the barrel installs them, and
+ * the barrel is what `package.json`'s `sideEffects` list names.
+ */
+import type { QueryField } from '../../types.js';
+import { Query } from '../builder.js';
+import type { DeclaredPredicate, InternalSource, QueryPlan } from '../builder.js';
+import type { CrossJoinClause } from '../predicate.js';
+import type { ReduceStrategy } from '../../../with-lookup/reduce/strategy.js';
+import type { JoinableSource, JoinContext, JoinStrategy } from './join.js';
+import { type JoinOnSpec } from './join-on.js';
+import type { QueryExplanation } from './explain.js';
+import type { CyclePolicy, TraversalRow, TraverseOptions } from './traverse.js';
+/**
+ * The Relate half of `Query`, as a mixin whose prototype is copied onto the
+ * real class. Never instantiated.
+ */
+export declare class RelateMethods<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 requireJoinContext: (terminal: string) => JoinContext;
+    ids: () => string[];
+    /**
+     * INNER join (#1361): `{ mode: 'inner' }` drops every left row whose alias
+     * resolves to nothing, and types the alias NON-nullable.
+     *
+     * ```ts
+     * invoices.query()
+     *   .join<'client', Client>('clientId', { as: 'client', mode: 'inner' })
+     *   .orderBy('total', 'desc')
+     *   .limit(10)
+     * // → the ten largest invoices THAT HAVE a client; `row.client.name` needs
+     * //   no null check.
+     * ```
+     *
+     * The long-hand `.join(f, { as }).where(as, '!=', null)` returns the same
+     * rows and keeps working unchanged — what it cannot do is keep the sort on
+     * the pre-join side. That predicate addresses the alias, so #1030 moves the
+     * WHOLE sort and page behind the legs; `mode: 'inner'` moves only the page,
+     * because the drop cannot reorder a left-side sort key. `.explain()` says
+     * which: `pre-join` on the `orderBy` node, `post-join` on the `page` node.
+     *
+     * The drop runs after `attachJoin`, so ref-mode semantics are unchanged — a
+     * `strict` dangling ref still throws rather than vanishing because the
+     * caller asked for an inner join.
+     */
+    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+        mode: 'inner';
+        strategy?: JoinStrategy;
+        maxRows?: number;
+    }): Query<T & Record<As, R>, S, Q, M>;
+    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+        mode?: undefined;
+        strategy?: JoinStrategy;
+        maxRows?: number;
+    }): Query<T & Record<As, R | null>, S, Q, M>;
+    /**
+     * DECLARED non-equi / non-id join (#1339) — a join whose `on` is data, not
+     * a callback.
+     *
+     * ```ts
+     * // composite equality — a hash join over a tuple key
+     * entries.query().joinOn<'rate', Rate>('rates', {
+     *   as: 'rate',
+     *   on: [['clientId', 'clientId'], ['year', 'year']],
+     * })
+     *
+     * // a range — nested loop over a right side sorted once
+     * entries.query().joinOn<'rate', Rate>('rates', {
+     *   as: 'rate',
+     *   on: { left: 'date', op: 'between', right: ['from', 'to'] },
+     * })
+     * ```
+     *
+     * ⭐ **Why this exists when `.crossJoin({ on })` already pairs anything.**
+     * `crossJoin`'s `on` is a closure. It cannot be serialized, so a
+     * materialized view built over one has its drift detection disabled — the
+     * plan summary records the sentinel `'[inline]'` and two different
+     * predicates hash identically. A `joinOn` predicate is plain JSON: it folds
+     * into `toPlan()` and into the MV `queryHash`, so an MV can genuinely
+     * DEPEND on it. That, not the pairing, is the feature.
+     *
+     * **No `ref()` needed** — the predicate names both sides itself, so `target`
+     * is the collection name rather than a declared FK field. Dangling is not a
+     * concept here: a left row matching nothing gets `null` under the alias (a
+     * LEFT outer join, like `.join()`), and `{ mode: 'inner' }` drops it.
+     *
+     * **⚠️ This join EXPANDS rows.** A ref join is one-to-one, so the left row
+     * count is constant; a declared `on` emits one row per MATCH, so a left row
+     * matching three right records becomes three rows. The per-side `maxRows`
+     * ceilings therefore cannot bound the result, and a third ceiling on the
+     * OUTPUT throws `JoinTooLargeError` with `side: 'output'`. Do not remove
+     * it: without it an unbounded theta join is a hang, not an error.
+     *
+     * **Cost.** Composite equality is O(n + m + output). A range is
+     * O(m log m) to sort the right side once, then O(log m) per left row for
+     * `< <= > >=`; `between` is O(log m + p) per left row, where p is the
+     * number of right intervals starting at or before the probe — which
+     * degrades to O(n·m) when every interval starts early. `explain()` names
+     * which of the two ran. Neither reaches the right collection's declared
+     * indexes: a `JoinableSource` does not expose them.
+     */
+    joinOn<As extends string, R = unknown>(target: string, opts: {
+        as: As;
+        on: JoinOnSpec;
+        mode: 'inner';
+        maxRows?: number;
+    }): Query<T & Record<As, R>, S, Q, M>;
+    joinOn<As extends string, R = unknown>(target: string, opts: {
+        as: As;
+        on: JoinOnSpec;
+        mode?: undefined;
+        maxRows?: number;
+    }): Query<T & Record<As, R | null>, S, Q, M>;
+    /**
+     * RIGHT outer join (#1289): every record of the TARGET collection appears,
+     * including one no left row points at. The mirror of `.join()`, which is
+     * and always was the left outer join.
+     *
+     * ```ts
+     * invoices.query().rightJoin<'client', Client>('clientId', { as: 'client' })
+     * // → one row per invoice/client match, PLUS { client } for every client
+     * //   no invoice references. An invoice whose clientId matches nothing is
+     * //   dropped — that is what makes it a right join.
+     * ```
+     *
+     * **The row shape is not `T`.** A right-only row carries the alias and
+     * nothing else, so the left fields are typed `Partial<T>` — SQL's "the left
+     * columns are NULL" in an object language. Read them defensively; a row
+     * where `amount` is `undefined` is a real, correct result, not a bug.
+     *
+     * **Cost.** A forward leg follows the left row's FK and is O(1) per row. A
+     * right leg cannot: the rows it must produce are exactly the ones no FK
+     * names. It builds a reverse index — the left rows bucketed by FK value —
+     * and walks the right snapshot against it. That is one extra pass over the
+     * left set and one `Map` the size of the distinct FK values; both sides are
+     * fully materialized either way, and both row ceilings still apply.
+     *
+     * **Ordering.** Like `.join()`, legs run AFTER `orderBy`/`limit`/`offset`
+     * unless the ordering addresses the alias (#1337),
+     * so those narrow the LEFT side. Rows are emitted in right-snapshot order.
+     *
+     * A left row whose non-null FK resolves to nothing is dropped, but the
+     * ref-mode check still runs on it: `strict` still throws
+     * `DanglingReferenceError`. Corruption should not become invisible because
+     * the caller changed join direction.
+     */
+    rightJoin<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+        strategy?: JoinStrategy;
+        maxRows?: number;
+    }): Query<Partial<T> & Record<As, R>, S, Q, M>;
+    /**
+     * FULL outer join (#1289): the union of `.join()` and `.rightJoin()` —
+     * every left row, every right record, matched where they meet.
+     *
+     * ```ts
+     * invoices.query().fullOuterJoin<'client', Client>('clientId', { as: 'client' })
+     * // → matched rows, plus { client: null, ...invoice } for an unreferenced
+     * //   invoice, plus { client } for a client no invoice points at.
+     * ```
+     *
+     * The alias is `R | null` and the left fields are `Partial<T>`, because a
+     * row can be missing either side — never both. Same reverse index, same
+     * ordering and same ref-mode semantics as {@link rightJoin}; the only
+     * difference is that the unmatched LEFT rows are emitted (after the
+     * right-driven ones) instead of dropped.
+     */
+    fullOuterJoin<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+        strategy?: JoinStrategy;
+        maxRows?: number;
+    }): Query<Partial<T> & Record<As, R | null>, S, Q, M>;
+    /**
+     * The one place a `JoinLeg` is built. `.join()`, `.rightJoin()` and
+     * `.fullOuterJoin()` differ ONLY in `direction` and in the type they
+     * publish — keeping the plan-time validation (ref declared? dict join?
+     * join context?) in a single body is what stops the three from drifting on
+     * which errors they raise.
+     */
+    private withJoinLeg;
+    /**
+     * 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>;
+    /**
+     * Self cross-join with BOTH sides aliased (#1289).
+     *
+     * ```ts
+     * const pairs = trades.query()
+     *   .crossJoinWith({ leftAs: 'a', rightAs: 'b', on: (t) => laterThan(t) })
+     *   .toArray()
+     * // → [{ a: Trade, b: Trade }, ...]  — no field at the top level
+     * ```
+     *
+     * `.crossJoin('trades', { as: 'other' })` can already pair a collection
+     * with itself, but only ASYMMETRICALLY: the left row's fields stay at the
+     * top level and only the right side gets a name. Every comparison then
+     * reads `r.amount` against `r.other.amount`, which is exactly the shape
+     * that makes an accidentally-transposed pair invisible.
+     *
+     * ⚠️ **The cost is not the join, it is the Via dressing.** Aliasing the
+     * left row moves every field off the top level, and the money / i18n /
+     * lookup pipeline keys by BARE FIELD NAME — so the plain top-level decode
+     * `toArray()` applies cannot see either side. Both aliases are therefore
+     * dressed explicitly, through the source's own Via result decode, before
+     * the rows are returned. Silently serving raw money under an alias is the
+     * failure this method exists to not have; `dressAliases` is where it is
+     * prevented and `__tests__/query-outer-join.test.ts` is what proves it.
+     *
+     * `on:` takes the same subset / predicate shapes as `.crossJoin()`, and the
+     * same `maxRows` ceiling applies to the product. The target is always this
+     * query's own collection — a cross-join against a DIFFERENT collection is
+     * `.crossJoin()`, which needs no left alias to stay unambiguous.
+     *
+     * The returned `Query` drops this query's schema / queryable / money field
+     * parameters. That is not laziness: those parameters name TOP-LEVEL fields,
+     * and after `crossJoinWith` there are no top-level fields — only the two
+     * aliases. Carrying them would let `where('amount', ...)` type-check on a
+     * row where `amount` does not exist.
+     */
+    crossJoinWith<LeftAs extends string, RightAs extends string>(opts: {
+        leftAs: LeftAs;
+        rightAs: RightAs;
+        on?: ((left: T) => unknown[] | ((right: T) => boolean)) | {
+            readonly predicate: string;
+        };
+        maxRows?: number;
+    }): Query<{
+        [K in LeftAs]: T;
+    } & {
+        [K in RightAs]: T;
+    }>;
+    /**
+     * Describe how this plan WOULD run (#1348): the dispatch per clause
+     * (`index:hash` vs `scan`, and why), row estimates taken from real index
+     * cardinalities, join strategy and side sizes against the row ceiling,
+     * whether ordering/pagination lands pre- or post-join, and which
+     * cardinality caps are close to tripping. `.text` renders one line per
+     * node.
+     *
+     * ⛔ Purely observational — it probes index buckets and reads snapshot
+     * sizes, never executes the plan. A terminal returns the same thing
+     * whether or not `explain()` was called. See `query/explain.ts`.
+     */
+    explain(): QueryExplanation;
+    /**
+     * Recursive traversal over ONE declared, self-referencing `ref()` field
+     * (#1352) — the org-chart / bill-of-materials / parent-client shape that
+     * otherwise forces the consumer to hand-roll recursion.
+     *
+     * ```ts
+     * people.query().where('name', '==', 'Dana')
+     *   .traverse('parentId', { direction: 'up', maxDepth: 10 })
+     * // → [{ id: 'dana', record, depth: 0, path: ['dana'] },
+     * //    { id: 'bea',  record, depth: 1, path: ['dana', 'bea'] }, …]
+     * ```
+     *
+     * **A TERMINAL.** It returns rows, not a `Query`, so it composes with
+     * `where()` / `orderBy()` / `limit()` on the way IN, not on the way out.
+     *
+     * **Seeds are this query's matched records** — the clauses choose the roots
+     * of the walk, not which nodes the walk may pass through. A traversal from
+     * one seed is `ancestorsOf` / `descendantsOf` below.
+     *
+     * **`maxDepth` is required**, with no default: an unbounded walk over a
+     * large collection is a denial of service against your own UI, and a
+     * silent default would truncate a result without saying so.
+     *
+     * **Cycles terminate.** A parent chain can be circular through user error,
+     * and an unguarded BFS hangs the tab. The default `{ onCycle: 'stop' }`
+     * prunes a node the walk is already standing on; `'throw'` raises
+     * `TraversalCycleError` for hierarchies that are supposed to be acyclic.
+     *
+     * **A node is emitted once**, at its shallowest depth — so a diamond (two
+     * seeds converging on one ancestor) yields ONE row for that ancestor,
+     * carrying the path of whichever branch reached it first.
+     *
+     * **Declared refs only.** This is not a general graph engine: the field
+     * must carry a `ref()` whose target is this same collection.
+     *
+     * **Cost.** Every hop reads the vault's already-decrypted in-memory cache
+     * (`query()` is eager-mode only), so a depth-5 traversal costs
+     * `depth × frontier` Map lookups and ZERO additional decrypts — the
+     * AES-GCM work was paid once at `openVault()`. `direction: 'down'` adds one
+     * O(n) pass to build the reverse-FK index; `'up'` adds nothing.
+     *
+     * ⛔ **Not an `explain()` node.** `explain()` describes the plan, and a
+     * traversal is a terminal over the plan's result rather than a clause in
+     * it — the same reason `.window()` and #1336's post-group ops are absent.
+     * `explain()` on the seed query still describes how the SEEDS are found.
+     */
+    traverse(field: QueryField<T, S>, opts: TraverseOptions): TraversalRow<T>[];
+    /**
+     * `.traverse()` sugar: every ancestor of one record, that record included
+     * at `depth: 0`. See {@link traverse} for the full contract.
+     *
+     * Refused on a query that already carries clauses — the seed is named
+     * explicitly here, so a `where()` would silently do nothing. Use
+     * `.traverse()` when the seeds come from a query.
+     */
+    ancestorsOf(id: string, field: QueryField<T, S>, opts: {
+        maxDepth: number;
+        onCycle?: CyclePolicy;
+    }): TraversalRow<T>[];
+    /**
+     * `.traverse()` sugar: every descendant of one record, that record included
+     * at `depth: 0`. See {@link traverse} for the full contract.
+     */
+    descendantsOf(id: string, field: QueryField<T, S>, opts: {
+        maxDepth: number;
+        onCycle?: CyclePolicy;
+    }): TraversalRow<T>[];
+    private traverseFromId;
+    /**
+     * The one place a traversal runs. Both entry points share it so they cannot
+     * drift on Via decoding or on which source view the walk reads.
+     */
+    private runTraverse;
+    /**
+     * Plan-time validation shared by `.traverse()` and its sugar: the field must
+     * carry a `ref()`, and that ref must point back at this same collection.
+     *
+     * The second half is what keeps this from becoming a general graph engine.
+     * A ref to ANOTHER collection has no second hop — the target's records do
+     * not carry this field — so a two-collection "traversal" is a `.join()`
+     * wearing the wrong name, and would walk exactly one level before stopping
+     * for reasons the caller could not see.
+     */
+    private assertSelfRef;
+}
+/**
+ * The public Relate surface, named once. The `declare module` block in
+ * `./index.ts` merges exactly this into `Query`, so the signatures live in one
+ * place and cannot drift from the implementations above.
+ *
+ * `Pick` rather than the class itself: an interface that extended
+ * `RelateMethods` would inherit the `protected` state declarations too, and
+ * they collide with `Query`'s own `private` fields.
+ */
+export type RelateSurface<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> = Pick<RelateMethods<T, S, Q, M>, 'join' | 'joinOn' | 'rightJoin' | 'fullOuterJoin' | 'crossJoin' | 'crossJoinWith' | 'traverse' | 'ancestorsOf' | 'descendantsOf' | 'explain'>;
+/**
+ * Expand `leftRel` by cross-joining with `rightSource`. Enforces the cost ceiling
+ * BEFORE allocating the expanded relation (full cartesian) or cumulatively
+ * (lateral form). Throws `CrossJoinTooLargeError` on breach.
+ */
+export declare function applyCrossJoin(leftRel: unknown[], clause: CrossJoinClause, rightSource: JoinableSource): unknown[];

package/dist/kernel/query/relate/partition.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Partition pruning — the ONE decision function (#1342, ADR 0007).
+ *
+ * ADR 0007 rules that a partition is a COLLECTION, not a field lifted out of
+ * the ciphertext: `listPage(vault, **collection**, cursor, limit)` already
+ * takes the collection name in cleartext, so a partition modelled as its own
+ * collection buys the pruning for free — no `@noy-db/hub/to` change, no
+ * adapter change, no new leak class. What is left for the kernel is deciding
+ * WHICH member collections a query has to read at all, and that is this file.
+ *
+ * ⭐ **SHARED, NOT MIRRORED.** `explain()` and the executor both call
+ * {@link resolvePartitionScope}. `explain.ts`'s header warns that dispatch
+ * selection is mirrored between it and `candidateRecords`, and #1375 spent a
+ * whole issue deleting one of those mirrors by exporting the classifier from
+ * `builder.ts`. Partition dispatch would have been a THIRD site. It is not:
+ * there is one function, and both callers import it.
+ *
+ * ⛔ **SOUND IN ONE DIRECTION ONLY, AND THE ASYMMETRY IS THE DESIGN.** A
+ * partition wrongly INCLUDED costs a scan nobody needed. A partition wrongly
+ * EXCLUDED is silently missing data — no error, no warning, a short answer
+ * that looks complete. So narrowing happens off a WHITELIST of provable
+ * shapes, never off a blacklist of known-bad ones:
+ *
+ *   - `key == "<string>"`            → that one partition
+ *   - `key in ["<string>", …]`       → that set
+ *   - two of those AND-ed            → their intersection
+ *
+ * and EVERYTHING else degrades to {@link ALL_PARTITIONS} by falling off the
+ * end of the whitelist: `or`/`and` groups (a nested clause is not AND-ed with
+ * the top level), `!=`, `!in`, `<`/`<=`/`>`/`>=`/`between`, `contains`,
+ * `startsWith`, `matches`, `near`, `filter()` callbacks, `wherePredicate()`,
+ * `crossJoin`, a clause on any other field, a non-string operand — and, the
+ * one that is easy to miss, **any Via-covered clause** (`clause.via`), whose
+ * operand is in STORED form rather than in partition-key space. That is the
+ * same reason `candidateRecords()` refuses the index for a Via clause, and
+ * getting it wrong here is worse than getting it wrong there: an index miss
+ * returns the right rows slowly, a partition miss returns the wrong rows fast.
+ *
+ * An operator added next year that this function has never heard of degrades
+ * to "read everything" without anyone editing this file. That is the whole
+ * point of the whitelist, and it is why the tests in
+ * `__tests__/partitioned-collection.test.ts` cover the FALLBACKS at least as
+ * heavily as the fast path.
+ *
+ * ⚠️ One narrowing this file does NOT do, deliberately: a RANGE on an ordered
+ * partition key (`period >= 'FY2026-Q2'`) intersected against declared
+ * partition boundaries. It is sound only once partitions carry declared
+ * boundaries AND the open/closed distinction is honoured — an OPEN period's
+ * upper bound can still move, so any range whose upper end is unbounded or in
+ * the future must keep the open partition. Cheap rule, and the first one a
+ * range narrowing gets wrong; it waits for a declaration that carries
+ * boundaries.
+ */
+import type { Clause } from '../predicate.js';
+/**
+ * "Read every declared partition." The sound fallback, and the value every
+ * shape this file cannot PROVE safe resolves to.
+ */
+export declare const ALL_PARTITIONS: "all";
+/**
+ * The partitions a query must read: {@link ALL_PARTITIONS}, or the exact
+ * subset — which may be EMPTY, when the predicate names a partition value
+ * that has never been declared. An empty scope is a real answer, not a
+ * degenerate one: the partition key is the collection a record lives in, so
+ * "no such partition" means "no such record".
+ */
+export type PartitionScope = typeof ALL_PARTITIONS | readonly string[];
+/**
+ * Narrow `declared` to the partitions `clauses` can PROVE are needed.
+ *
+ * `clauses` must be the plan's TOP-LEVEL clause list — those are AND-ed, and
+ * an intersection across them is therefore sound. Anything nested inside a
+ * `group` is not AND-ed with the top level and is ignored by construction
+ * (a `group` never matches the whitelist).
+ *
+ * The result preserves `declared`'s order, so a caller reading partitions in
+ * sequence gets a stable, declaration-ordered walk whether or not it pruned.
+ */
+export declare function resolvePartitionScope(clauses: readonly Clause[], key: string, declared: readonly string[]): PartitionScope;
+/**
+ * The `explain()` line, in the existing vocabulary: `partitions: 3 of 12
+ * scanned`. Shared so the executor's accounting and the explanation cannot
+ * drift into disagreeing about what "scanned" counts.
+ */
+export declare function describePartitionScope(scope: PartitionScope, declared: readonly string[]): string;
+/** The member partitions a scope resolves to, in declaration order. */
+export declare function partitionsInScope(scope: PartitionScope, declared: readonly string[]): readonly string[];

package/dist/kernel/query/relate/scan-methods.d.ts

@@ -0,0 +1,163 @@
+/**
+ * #1458 — the **Relate** half of `ScanBuilder`.
+ *
+ * `join` · plus the two streaming-join privates the iterator calls.
+ *
+ * ⭐ **`ScanBuilder` gets the same treatment as `Query` because it has the same
+ * problem** (ruled 2026-09-06): it is one class carrying Find (`where`,
+ * `filter`, the async iterator), Reduce (`aggregate`, `groupBy`) and Relate
+ * (`join`) methods, and `sideEffects: false` cannot drop a method. Left
+ * unsplit it would have kept `relate/join.ts` and the whole reducer engine in
+ * every `/query` bundle no matter what `Query` did — the architecture rule
+ * would have been true of `builder.ts` and false of the package.
+ *
+ * ⚠️ `buildJoinResolvers` and `applyOneJoinStreaming` are called from the
+ * ITERATOR, which stays in Find. Both calls sit behind `joins.length === 0`,
+ * so a Find-only scan never reaches them — the same guarantee, and the same
+ * shape of guarantee, as `internal/hooks.ts` gives the eager executor.
+ */
+import { ScanBuilder } from '../scan-builder.js';
+import type { ScanPageProvider } from '../scan-builder.js';
+import type { QueryField } from '../../types.js';
+import type { Clause } from '../predicate.js';
+import type { ViaPipeline } from '../../via/pipeline.js';
+import type { JoinContext, JoinLeg, JoinableSource } from './join.js';
+/** One resolved leg, prepared once per iteration. @internal */
+export interface ScanJoinResolver {
+    leg: JoinLeg;
+    source: JoinableSource;
+    lookupById: ((id: string) => unknown) | null;
+    hashByPrimaryKey: ReadonlyMap<string, unknown> | null;
+    warnedKeys: Set<string>;
+}
+/** @internal — the mixin whose prototype `./index.ts` copies onto `ScanBuilder`. */
+export declare class ScanRelateMethods<T, S extends keyof T = never, M extends keyof T & string = never> {
+    protected readonly pageProvider: ScanPageProvider<T>;
+    protected readonly pageSize: number;
+    protected readonly clauses: readonly Clause[];
+    protected readonly joins: readonly JoinLeg[];
+    protected readonly joinContext: JoinContext | undefined;
+    protected readonly via: ViaPipeline | undefined;
+    /**
+     * Resolve a `ref()`-declared foreign key per record as the scan
+     * stream flows, attaching the right-side record (or null) under
+     * `opts.as`. — streaming joins over `scan()`.
+     *
+     * ```ts
+     * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
+     *   await processInvoice(inv) // inv.client is attached
+     * }
+     *
+     * // Or terminate with .aggregate() for streaming joined aggregation
+     * const { total } = await invoices.scan()
+     *   .where('status', '==', 'open')
+     *   .join('clientId', { as: 'client' })
+     *   .aggregate({ total: sum('amount') })
+     * ```
+     *
+     * **The key difference from eager `.join()`:** the LEFT
+     * side streams page-by-page from the adapter and is never
+     * materialized. Memory ceiling on the left is O(pageSize), not
+     * O(rowCount). This is what makes streaming joins suitable for
+     * collections that exceed the eager join's 50_000-row ceiling.
+     *
+     * **Right-side strategy** is auto-selected per leg:
+     *   - **Indexed** — right source exposes `lookupById`, so each
+     *     left row costs O(1). This is the common path for
+     *     Collection right sides, which back `lookupById` with a Map
+     *     lookup over the in-memory cache. The right collection must
+     *     be in eager mode (the same constraint as eager join's
+     *     `querySourceForJoin` from ).
+     *   - **Hash** — right source has only `snapshot()`. Build a
+     *     `Map<id, record>` once at iteration start, probe per left
+     *     row. Same correctness, same per-row cost as the indexed
+     *     path; the difference is the upfront cost of materializing
+     *     the right side once.
+     *
+     * Both strategies hold the right side in memory for the duration
+     * of the iteration. The "streaming" property applies to the LEFT
+     * side only — true left-and-right streaming joins (where neither
+     * side fits in memory) require a sort-merge join planner that's
+     * out of scope for.
+     *
+     * **Ref-mode semantics** match eager `.join()` exactly:
+     *   - `strict`  → throws `DanglingReferenceError` mid-stream
+     *     when a left record points at a non-existent right id.
+     *     The throw aborts the async iterator — consumers should
+     *     wrap the `for await` in try/catch if they want to recover.
+     *   - `warn`    → attaches `null` and emits a one-shot warning
+     *     per unique dangling pair (deduped via the same warn
+     *     channel as eager join).
+     *   - `cascade` → attaches `null` silently. A delete-time mode;
+     *     dangling refs at read time are mid-flight or pre-existing
+     *     orphans, not a DSL error.
+     *
+     * Left records with null/undefined FK values attach `null`
+     * regardless of mode — same "no reference at all" policy as
+     * eager join and write-time `enforceRefsOnPut`.
+     *
+     * **Multi-FK chaining** is supported via repeated `.join()`
+     * calls: each leg resolves an independent ref. Each leg
+     * independently picks its right-side strategy and applies its
+     * own ref mode.
+     *
+     * **Joins are NOT applied** to a `.aggregate()` terminal that
+     * doesn't reference joined fields — wait, that's not quite
+     * right. The streaming path actually DOES apply joins before
+     * `.aggregate()` because the join attaches a field that the
+     * spec might reference. Unlike `Query.aggregate()` (which skips
+     * joins entirely as a projection-only short-circuit), the
+     * streaming aggregation can't know whether the spec touches a
+     * joined field, so it always applies joins. Consumers who want
+     * unjoined streaming aggregation should leave `.join()` off the
+     * chain — the chain is composable for a reason.
+     *
+     * Every JoinLeg carries `partitionScope: 'all'`, plumbed through but never
+     * read. Same seam as the eager join — see {@link JoinLeg.partitionScope}.
+     */
+    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+    }): ScanBuilder<T & Record<As, R | null>, S, M>;
+    /**
+     * Iterate the scan as an async iterable. Walks the page
+     * provider's cursors forward until exhaustion, applying every
+     * clause per record — only matching records are yielded.
+     *
+     * Backward-compatible with the previous async-generator `scan()`
+     * return type for `for await … of` consumers.
+     */
+    /**
+     * Per-leg right-side resolution state. Built once at iteration
+     * start and reused for every left record. Two strategies:
+     *
+     *   - `lookupById`: present when the right source exposes the
+     *     hook directly (typical Collection right side). Per-row
+     *     cost is O(1).
+     *   - `hashByPrimaryKey`: built from `snapshot()` when no
+     *     lookupById. Per-row cost is O(1) after the upfront O(N)
+     *     materialization. Same as eager join's hash strategy.
+     *
+     * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
+     * key on `field→target:refId` so the same dangling pair only
+     * warns once per iteration. The dedup is per-iteration, not
+     * per-process — a long-running scan that re-iterates would warn
+     * again, which is the desired behavior (the data may have
+     * changed between iterations).
+     */
+    private buildJoinResolvers;
+    /**
+     * Resolve a single join leg for one left record and return the
+     * left record with the joined field attached under
+     * `leg.as`. Pure function over `(left, resolver)`; never
+     * mutates the input.
+     *
+     * Ref-mode dispatch matches eager `applyJoins` from :
+     *   - null/undefined FK → attach null silently (always allowed)
+     *   - dangling FK + strict → throw `DanglingReferenceError`
+     *   - dangling FK + warn → attach null, warn-once per pair
+     *   - dangling FK + cascade → attach null silently
+     */
+    private applyOneJoinStreaming;
+}
+/** The public Relate surface of `ScanBuilder` — merged by `./index.ts`. */
+export type ScanRelateSurface<T, S extends keyof T = never, M extends keyof T & string = never> = Pick<ScanRelateMethods<T, S, M>, 'join'>;