kitcn 0.32.1 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # kitcn
 
+## 0.33.0
+
+### Minor Changes
+
+- [#456](https://github.com/udecode/kitcn/pull/456) [`5b0bd5a`](https://github.com/udecode/kitcn/commit/5b0bd5a1debb4a0e0bb87f79ef1a18f357b614c1) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Breaking changes
+
+  - Support index-ordered pagination for indexed filters with more than 64 values. Pages follow index order, grouped by the filtered value, rather than creation order. Add `orderBy` and `maxScan` to preserve newest-first paging.
+
+  ```ts
+  // Before
+  const page = await db.query.users.withIndex("by_status").findMany({
+    where: { status: { in: manyStatuses } },
+    cursor: null,
+    limit: 20,
+    maxScan: 500,
+  });
+
+  // After
+  const page = await db.query.users.withIndex("by_status").findMany({
+    where: { status: { in: manyStatuses } },
+    orderBy: { createdAt: "desc" },
+    cursor: null,
+    limit: 20,
+    maxScan: 500,
+  });
+  ```
+
+  ## Patches
+
+  - Fix authenticated cRPC query results disappearing when a server-rendered page
+    hydrates.
+  - Fix unnecessary full-table reads for `select()` filters containing more than 64 values.
+  - Fix unnecessary full-table reads for long `in` lists combined with another condition, such as `name: { contains: 'x' }`.
+  - Improve limited reads with additional conditions so they stop after enough matching rows are found when index order satisfies the requested sort.
+  - Support index-bounded reads for indexed `in`, `notIn`, `ne`, and same-field equality `OR` filters regardless of list length.
+  - Support pagination without `maxScan` for wide filters whose requested order follows their indexed values; cross-value sorting, such as `orderBy: { createdAt: 'desc' }`, still requires `maxScan` past 64 values.
+
+- [#449](https://github.com/udecode/kitcn/pull/449) [`b8df2da`](https://github.com/udecode/kitcn/commit/b8df2da49a8733b545f02b84bb538b1cbef275b0) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Breaking changes
+
+  - Read a `select().flatMap(relation, { where })` stage through an index that extends the relation's foreign key when the schema declares one. Children arrive in that index's order, so a lowered range field now orders them ahead of creation time, and outstanding page cursors for those queries do not carry over.
+
+  ```ts
+  // Before: every post by the author is read, then filtered, in creation order.
+  // After: only the by_author_likes range is read, in numLikes order.
+  index("by_author_likes").on(t.authorId, t.numLikes);
+
+  await ctx.orm.query.users
+    .select()
+    .flatMap("posts", { includeParent: false, where: { numLikes: { gt: 10 } } })
+    .paginate({ cursor: null, limit: 20 });
+  ```
+
+  ## Patches
+
+  - Compile a `select().union([{ where }])` source `where` against the table's indexes instead of filtering every scanned row, so an object `where` on an indexed field bounds the read. A source keeps its unanchored read when the lowered one could not supply `interleaveBy`, and a `where` never displaces an index the source or the chain pinned with a range.
+  - Report what a caller can actually do when a `predicate(...)` `where` runs over an unbounded pipeline read: a union source names its own `index` option, and a `flatMap` stage names the relation index it needs.
+  - Resolve a `select()` union source or `flatMap` stage `where` once per read. A callback `where` runs a single time instead of twice, and an object `where` compiles once instead of once per row.
+
+### Patch Changes
+
+- [#455](https://github.com/udecode/kitcn/pull/455) [`a73de28`](https://github.com/udecode/kitcn/commit/a73de28bacf3e518a38762442270d2c54f6989e8) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Fix `findMany` losing its read bound when a `limit` is combined with `in`, `ne`,
+    `notIn` or a same-field `OR` on a table that has RLS enabled, or alongside a
+    filter Convex cannot evaluate such as `contains`. Either one used to make the
+    query read every row it matched against, so
+    `findMany({ where: { ownerId: { in: [a, b] } }, limit: 3 })` read 500 documents
+    on a 500-row table and 200 on a 200-row table. It now reads 6 at either size,
+    and the count no longer grows with the table.
+  - Improve how that `limit` is counted, so it bounds rows the caller can actually
+    see: with 80 rows an RLS policy hides sitting in front of the matches,
+    `limit: 3` still returns three rows and reads 86 documents instead of 200.
+  - Support that bound for an `in` list of any length.
+
+  Rows and their order are unchanged. A `where` that filters through a relation
+  keeps its previous read cost, as does `ne`, `notIn` or `isNotNull` ordered by a
+  field no index can serve.
+
+- [#450](https://github.com/udecode/kitcn/pull/450) [`781af65`](https://github.com/udecode/kitcn/commit/781af65c6e2f9128362378f0cf358d2c8e509b7d) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve update read costs on `aggregateIndex` and `rankIndex` tables: read
+    each row once unless a user `update.before` hook requires a fresh read.
+  - Fix CLEARING checks for deletes of already-deleted rows: report the
+    transient aggregate-index state instead of `Delete on non-existent doc`.
+
+- [#451](https://github.com/udecode/kitcn/pull/451) [`80f7609`](https://github.com/udecode/kitcn/commit/80f7609cb107d23e4688b6877f35787107dd0a39) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve `aggregateIndex` bulk-write read costs by reusing bucket and member
+    reads within uninterrupted ORM statements. User hooks and policy callbacks
+    end reuse so nested mutation writes remain visible to later maintenance.
+
+- [#454](https://github.com/udecode/kitcn/pull/454) [`f399843`](https://github.com/udecode/kitcn/commit/f399843c6bfb46e080558bc22d2cc4a77842cd16) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve bulk aggregate writes by folding shared bucket and extrema updates
+    within uninterrupted statements. A 40-row key migration writes two shared
+    buckets and two extrema entries, plus forty membership rows.
+  - Preserve read-your-own-writes through aggregate reads and nested functions
+    called by lifecycle hooks or RLS policies. Reads and callbacks flush pending
+    writes; callbacks suspend batching until they settle.
+  - Fix mid-statement aggregate reads through `withoutTriggers()` and an ORM
+    rebuilt from a hook context to observe the same rows as `ctx.orm`.
+
+## 0.32.2
+
+### Patch Changes
+
+- [#448](https://github.com/udecode/kitcn/pull/448) [`75ceda6`](https://github.com/udecode/kitcn/commit/75ceda65a12b4dfdd525c97a9401a31c54fd89d0) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve the read cost of a relation `where` on a relation joined on a column
+    other than the primary id, including `through` targets and `_count` on a
+    `through` relation.
+  - Fix relation targets sharing one loaded document, which could add fields to a
+    relation that only another relation in the same query requested.
+
 ## 0.32.1
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Ctcw2VRq.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-BHGHbfb9.js";
+import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Bxzoofl4.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-DrV6lQg0.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/auth/index.js

@@ -4,7 +4,7 @@ import { i as defineAuth, n as createDisabledAuthRuntime, r as getGeneratedAuthD
 import { n as createGeneratedFunctionReference, o as isQueryCtx, s as isRunMutationCtx } from "../api-entry-Buvjl9hn.js";
 import { i as customQuery, n as customCtx, r as customMutation } from "../customFunctions-X_B4kET8.js";
 import { C as eq, o as getAggregateIndexes } from "../index-utils-DvK7P6Q1.js";
-import { o as mergedStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-D4z1CnDH.js";
+import { c as stream, f as unsetToken, s as mergedStream, t as getByIdWithOrmQueryFallback } from "../query-context-DQLv58LH.js";
 import { n as convex } from "../convex-plugin-AbNQl1Sg.js";
 import { v } from "convex/values";
 import { internalActionGeneric, internalMutationGeneric, internalQueryGeneric, paginationOptsValidator } from "convex/server";

package/dist/{capabilities-Ctcw2VRq.d.ts → capabilities-Bxzoofl4.d.ts}

@@ -2149,7 +2149,7 @@ declare const createAggregateError: (code: AggregateErrorCode, message: string)
 declare const ensureCountAllowedForRls: (tableConfig: TableRelationalConfig, rlsMode: "skip" | "default" | undefined) => void;
 declare const ensureAggregateAllowedForRls: (tableConfig: TableRelationalConfig, rlsMode: "skip" | "default" | undefined, methodName: string) => void;
 declare namespace runtime_d_exports$1 {
-  export { AGGREGATE_ERROR, AGGREGATE_STATE_KIND_METRIC, AGGREGATE_STATE_KIND_RANK, AggregateBucketDelta, AggregateErrorCode, AggregateExtremaDelta, AggregateIndexDefinition, AggregateMemberWrite, AggregateMembershipDelta, AggregateQueryPlan, AggregateRangeConstraint, COUNT_ERROR, COUNT_STATUS_BUILDING, COUNT_STATUS_CLEARING, COUNT_STATUS_READY, ClearIndexChunkResult, CountErrorCode, CountIndexDefinition, CountQueryPlan, CountState, NULLISH_PROBE_VALUES, PlanBucketReadCache, applyAggregateIndexesForChange, applyCountIndexesForChange, asUnknownArray, assertAggregateIndexesWritable, clearCountIndexChunk, compileAggregateQueryPlan, compileCountFieldQueryPlan, compileCountQueryPlan, computeAggregateMembershipDelta, computeAggregateMetricValues, computeCountKeyParts, createAggregateError, createCountError, ensureAggregateAllowedForRls, ensureAggregateIndexReady, ensureCountAllowedForRls, ensureCountIndexReady, flushAggregateMembershipDeltas, getAggregateIndexDefinitions, getCountIndexDefinitions, getCountIndexValuesForFields, getCountState, isAggregatePlanZero, isIndexCountZero, listCountStates, listSchemaAggregateIndexes, listSchemaCountIndexes, parseAggregateWhere, parseCountWhere, readAverageFromBuckets, readCountFieldFromBuckets, readCountFromBuckets, readExtremaFromBuckets, readPlanBuckets, readSumFromBuckets, reconcileAggregateMembership, serializeCountKeyParts, setCountState, setCountStateError };
+  export { AGGREGATE_ERROR, AGGREGATE_STATE_KIND_METRIC, AGGREGATE_STATE_KIND_RANK, AggregateBucketDelta, AggregateErrorCode, AggregateExtremaDelta, AggregateIndexDefinition, AggregateMemberWrite, AggregateMembershipDelta, AggregateQueryPlan, AggregateRangeConstraint, COUNT_ERROR, COUNT_STATUS_BUILDING, COUNT_STATUS_CLEARING, COUNT_STATUS_READY, ClearIndexChunkResult, CountErrorCode, CountIndexDefinition, CountMemberRow, CountQueryPlan, CountState, NULLISH_PROBE_VALUES, PlanBucketReadCache, applyAggregateIndexesForChange, applyCountIndexesForChange, asUnknownArray, assertAggregateIndexesWritable, clearCountIndexChunk, compileAggregateQueryPlan, compileCountFieldQueryPlan, compileCountQueryPlan, computeAggregateMembershipDelta, computeAggregateMetricValues, computeCountKeyParts, createAggregateError, createCountError, ensureAggregateAllowedForRls, ensureAggregateIndexReady, ensureCountAllowedForRls, ensureCountIndexReady, flushAggregateMembershipDeltas, getAggregateIndexDefinitions, getCountIndexDefinitions, getCountIndexValuesForFields, getCountState, isAggregatePlanZero, isIndexCountZero, listCountStates, listSchemaAggregateIndexes, listSchemaCountIndexes, parseAggregateWhere, parseCountWhere, readAverageFromBuckets, readCountFieldFromBuckets, readCountFromBuckets, readExtremaFromBuckets, readPlanBuckets, readSumFromBuckets, reconcileAggregateMembership, serializeCountKeyParts, setCountState, setCountStateError };
 }
 declare const AGGREGATE_STATE_KIND_METRIC = "metric";
 declare const AGGREGATE_STATE_KIND_RANK = "rank";
@@ -2188,6 +2188,21 @@ type CountState = {
   completedAt?: number | null;
   lastError?: string | null;
 };
+type CountMemberRow = {
+  _id: GenericId<any>;
+  kind: string;
+  tableKey: string;
+  indexName: string;
+  docId: string;
+  keyHash: string;
+  keyParts: unknown[];
+  sumValues: Record<string, number>;
+  nonNullCountValues: Record<string, number>;
+  extremaValues: Record<string, unknown>;
+  rankNamespace?: unknown;
+  rankKey?: unknown;
+  rankSumValue?: number;
+};
 type CountBucketRow = {
   _id: GenericId<any>;
   tableKey: string;
@@ -2261,6 +2276,11 @@ type AggregateExtremaDelta = {
   value: unknown;
   delta: number;
 };
+/**
+ * `post` is what the write leaves in the member table, so the flush can bring
+ * the member memo forward without reading the row back. The `_id` is missing
+ * because an insert only learns it once the insert returns.
+ */
 type AggregateMemberWrite = {
   kind: 'none';
 } | {
@@ -2270,11 +2290,13 @@ type AggregateMemberWrite = {
   kind: 'patch';
   id: GenericId<any>;
   doc: Record<string, unknown>;
+  post: Omit<CountMemberRow, '_id'>;
 } | {
   kind: 'insert';
-  doc: Record<string, unknown>;
+  doc: Omit<CountMemberRow, '_id'>;
 };
 type AggregateMembershipDelta = {
+  /** The document this delta reconciles, and the member memo's key. */docId: string;
   buckets: AggregateBucketDelta[];
   extrema: AggregateExtremaDelta[];
   member: AggregateMemberWrite;
@@ -2293,8 +2315,28 @@ declare const computeAggregateMembershipDelta: (db: GenericDatabaseWriter<any>,
  */
 declare const flushAggregateMembershipDeltas: (db: GenericDatabaseWriter<any>, tableName: string, indexName: string, deltas: AggregateMembershipDelta[]) => Promise<void>;
 /**
- * Single-document reconciliation. Flushes eagerly so user code reading an
- * aggregate later in the same mutation sees its own writes.
+ * Single-document reconciliation.
+ *
+ * The bucket and extrema writes always go on the transaction's write queue,
+ * never straight to storage: `applyBucketDelta` writes an absolute count
+ * computed from the row it just read, so two of them interleaving would be a
+ * lost update, and routing every one of them through a single drain is what
+ * keeps them serialized. Inside a mutation statement the queue is held to the
+ * end of the statement, which is what lets the fold collapse a page of
+ * documents into one write per key tuple; outside one it is drained
+ * immediately, so a raw `ctx.db` write behaves exactly as it did before.
+ *
+ * The member row is written per document either way, because it is the
+ * pre-image the next reconciliation of this document subtracts. Outside a
+ * statement it is still written after the bucket, preserving the previous
+ * order; inside one it necessarily lands first, and a flush that throws
+ * part-way leaves the index needing a backfill — which a partially applied fold
+ * would anyway, whichever order the two halves ran in.
+ *
+ * Deferral is invisible to aggregate readers: every bucket- and extrema-backed
+ * read path drains the queue first, so user code reading a count later in the
+ * same mutation — including from a trigger firing mid-statement — still sees
+ * its own writes.
  */
 declare const reconcileAggregateMembership: (db: GenericDatabaseWriter<any>, params: {
   tableName: string;
@@ -2755,6 +2797,7 @@ declare class ConvexDeleteBuilder<TTable extends ConvexTable<any>, TReturning ex
   }): this;
   executeAsync(this: ConvexDeleteExecutableThis<TTable, TReturning, TMode>, ...args: TMode extends 'single' ? [config?: Omit<MutationExecuteConfig, 'mode'>] : [config: never]): Promise<TMode extends 'single' ? MutationExecuteResult<TTable, TReturning, 'single'> : never>;
   execute(this: ConvexDeleteExecutableThis<TTable, TReturning, TMode>, ...args: TMode extends 'single' ? [config?: MutationExecuteConfig] : [config?: never]): Promise<MutationExecuteResult<TTable, TReturning, TMode>>;
+  private _runStatement;
 }
 //#endregion
 //#region src/orm/insert.d.ts
@@ -2795,6 +2838,7 @@ declare class ConvexInsertBuilder<TTable extends ConvexTable<any>, TReturning ex
   onConflictDoNothing(config?: InsertOnConflictDoNothingConfig<TTable>): ConvexInsertWithout<this, 'onConflictDoNothing' | 'onConflictDoUpdate'>;
   onConflictDoUpdate(config: InsertOnConflictDoUpdateConfig<TTable>): ConvexInsertWithout<this, 'onConflictDoNothing' | 'onConflictDoUpdate'>;
   execute(): Promise<MutationResult<TTable, TReturning>>;
+  private _runStatement;
   private resolveReturningRow;
   private handleConflict;
   private findConflictRow;
@@ -2922,6 +2966,20 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * intervening write would make it stale.
    */
   private readonly _documentByNormalizedId;
+  /**
+   * Single target documents resolved by an eq-pinned key during one execution,
+   * keyed on the read itself: table, index, join columns and their values.
+   *
+   * `_documentByNormalizedId` only covers a join on the primary id. A relation
+   * joined on any other column resolves its target with `.first()` instead, and
+   * the same one-row-at-a-time membership predicate re-issues that read once per
+   * drain. The index is fixed for the whole relation and the key is pinned by
+   * `eq`, so the first row is a pure function of this key within an execution.
+   *
+   * Same scope and staleness argument as `_documentByNormalizedId`: not handed
+   * to the next run by `_forExecution`, so an intervening write is still seen.
+   */
+  private readonly _firstDocumentByFieldKey;
   constructor(schema: TSchema, tableConfig: TTableConfig, edgeMetadata: EdgeMetadata[], db: GenericDatabaseReader<any>, config: DBQueryConfig<'one' | 'many', boolean, TSchema, TTableConfig>, mode: 'many' | 'first' | 'firstOrThrow' | 'count' | 'aggregate' | 'groupBy', _allEdges?: EdgeMetadata[] | undefined, // M6.5 Phase 2: All edges for nested loading
   rls?: RlsContext | undefined, relationLoading?: {
     concurrency?: number;
@@ -3051,8 +3109,41 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _finalizeRows;
   private _getSchemaDefinitionOrThrow;
   private _applyEqBounds;
-  private _buildTableFilterPredicate;
-  private _assertWhereIndexRequirement;
+  /**
+   * The row filter for an already-resolved pipeline stage `where`.
+   *
+   * Takes the resolved shape rather than the clause so the rows that are read
+   * and the rows that are kept come from the same resolution. Resolving twice
+   * would let a `where` callback that closes over changing state — a clock, a
+   * counter — bound the read with one expression and filter it with another,
+   * dropping rows that the second expression matched but the first never read.
+   */
+  private _buildResolvedWherePredicate;
+  /**
+   * What a pipeline stage `where` is, resolved once.
+   *
+   * Object clauses and callbacks that return an expression can be compiled and
+   * therefore index-lowered. `predicate(...)` is opaque JavaScript and never
+   * can be. Both the anchoring check and the index lowering need to tell those
+   * apart, and a callback `where` should be run once per read rather than once
+   * per caller that asks.
+   */
+  private _resolvePipelineWhere;
+  /**
+   * Reject a `predicate(...)` stage `where` on a read nothing bounds.
+   *
+   * A predicate can only run after the row is read, so it costs one read per
+   * candidate row. That is fine over an index range and unbounded over a table
+   * scan, which is the same line `findMany` draws for a chain-level
+   * `predicate(...)`. An object `where` is not held to it: the compiler
+   * lowers what it can and post-filters the rest, exactly as the chain-level
+   * read does.
+   *
+   * `remedy` is per call site because the anchor a caller can add differs: a
+   * union source takes an index, a `flatMap` stage has no index option at all
+   * and is anchored by the relation's own declared index.
+   */
+  private _assertPipelineWhereIsAnchored;
   private _isFilterExpressionNode;
   private _isPredicateWhereClause;
   private _createFilterOperators;
@@ -3085,14 +3176,31 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   /**
    * The compiled index union, as one ordered stream.
    *
-   * Each probe is its own index range, so the union is only usable where the
-   * merged order is the order the read has to produce. `mergedStream` orders by
-   * a *suffix* of the index key, and a suffix may only drop key components the
+   * Each probe is its own index range, so the union is only usable where its
+   * order is the order the read has to produce. `mergedStream` orders by a
+   * suffix of the index key, and a suffix may only drop key components the
    * probes all pin to a single value — so the requested field has to sit inside
    * the pinned run or immediately after it. Returns null when it does not, and
    * the caller falls back to the plan's plain index range or a bounded scan.
+   *
+   * Two executors, because a union that is too wide to merge is not too wide to
+   * read. A merge registers every probe up front and holds them open for the
+   * life of the read, which is what `MAX_INDEX_UNION_PROBES` refuses; past that
+   * width the probes are concatenated instead, one open query at a time. What
+   * the cap picks is therefore fan-out versus sequential — never index versus
+   * table scan, which is a trade no read wins.
    */
   private _buildProbeUnionStream;
+  /**
+   * `probeFilters` in the order a scan of `indexField` reaches them, or null
+   * when they cannot be proven to be pairwise-disjoint ranges on that field.
+   *
+   * Concatenation stands in for a merge only under those two properties, and
+   * both have to come from the filters themselves rather than from trust in the
+   * compiler that emitted them: overlapping probes would emit a row twice, and
+   * probes handed over out of order would emit index keys backwards.
+   */
+  private _orderDisjointProbes;
   /**
    * The read the compiled plan describes, as a stream, with nothing filtered
    * yet.
@@ -3124,7 +3232,41 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * the caller then falls back to its plain-query path.
    */
   private _buildResidualFilterStream;
+  /**
+   * One `pipeline.union` source, as a stream.
+   *
+   * The source's own `where` is compiled into an index plan first, so an
+   * object `where` bounds the read instead of being discarded row by row after
+   * it. Two rules keep that from changing what the union produces:
+   *
+   * - `_compileQueryPlan` discards a plan that would displace an index the
+   *   caller pinned, so a source's own range (a tenant scope, say) still wins.
+   * - A merged union is ordered by `interleaveBy`, which only some index
+   *   shapes can supply. The lowered read is checked against that before it is
+   *   committed to, and the unlowered scan is used when it cannot serve the
+   *   merge — an index that saves reads is not worth an ordering that throws.
+   *
+   * The `where` stays applied in JS either way. The index range is a bound on
+   * what is read, not a replacement for the predicate.
+   */
   private _buildUnionSourceStream;
+  /**
+   * The index a `flatMap` stage `where` can ride on top of the join keys.
+   *
+   * The join is only correct while `targetFields` stay pinned by equality, and
+   * a Convex range builder pins fields in index-key order with no gaps, so the
+   * candidates are exactly the declared indexes that lead with `targetFields`
+   * and carry at least one more field. Those trailing fields are what the
+   * stage `where` is compiled against — the compiler never sees the join keys,
+   * because their values are per parent and the index choice has to be made
+   * once for all of them.
+   *
+   * Returns null when nothing is gained, and the caller keeps the relation's
+   * own index plus the post-filter. A multi-probe plan is refused: each probe
+   * is its own range, and a union of ranges per parent is a different stream
+   * shape than the one `flatMap` was handed as `mappedIndexFields`.
+   */
+  private _resolveFlatMapStageIndex;
   private _applyFlatMapStage;
   private _applyPipelineStages;
   private _tryNativeUnfilteredCount;
@@ -3189,6 +3331,17 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * Phase 4 implementation with WhereClauseCompiler
    */
   private _toConvexQuery;
+  /**
+   * The read plan for one `where` on this table.
+   *
+   * Split out of `_toConvexQuery` because the chain-level `where` is not the
+   * only one that has to be index-lowered: a `pipeline.union` source carries
+   * its own `where` and its own pinned index, and compiles against the same
+   * table with a different ordering contract (`interleaveBy`, not `orderBy`).
+   * Both go through here so a plain-object `where` is planned the same way
+   * wherever it is written.
+   */
+  private _compileQueryPlan;
   private _buildRelationKey;
   /**
    * How many leading fields of the scanned index are pinned to a single value.
@@ -3219,7 +3372,39 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * Helper for recursive relation loading
    */
   private _getTargetTableEdges;
+  /**
+   * A memo entry is a snapshot, so every caller has to get its own document.
+   *
+   * Relation loaders write nested `with` results and `extras` straight onto the
+   * target they were handed, and `hydrateDateFieldsForRead` copies every own key
+   * it finds. Two loads that share one entry would therefore publish each
+   * other's fields — a relation asked for as `true` coming back carrying a
+   * nested relation only the `where` requested. Those writes are all top-level,
+   * so a shallow copy is exactly as much isolation as they need.
+   */
+  private _ownedCopy;
   private _getById;
+  /**
+   * Identity of one `_firstByFields` read, or null when the join values cannot
+   * be encoded losslessly.
+   *
+   * `JSON.stringify` alone is not safe here. It renders every `ArrayBuffer` as
+   * `{}` and `NaN`/`Infinity`/`-Infinity` as `null`, so two distinct join values
+   * would share one entry, and it throws outright on `int64`. The relation
+   * loader's own per-batch key map cannot catch that, because the residual
+   * relation `where` hands it one row at a time — a map of one never compares
+   * two values. This key is the only thing that tells them apart.
+   *
+   * `convexToJson` is the same wire encoding the client uses for query keys, so
+   * every Convex value round-trips distinctly. Anything it rejects is not a
+   * Convex value and simply goes unmemoized.
+   */
+  private _firstByFieldsMemoKey;
+  /**
+   * `_getById` for a relation joined on something other than the primary id:
+   * resolve one target document by an eq-pinned key, memoized per execution.
+   */
+  private _firstByFields;
   private _getRelationConcurrency;
   private _getRelationFanOutKeyCap;
   private _enforceRelationFanOutKeyCap;
@@ -3588,6 +3773,7 @@ declare class ConvexUpdateBuilder<TTable extends ConvexTable<any>, TReturning ex
   allowFullScan(): ConvexUpdateBuilder<TTable, TReturning, TMode, true>;
   executeAsync(this: ConvexUpdateExecutableThis<TTable, TReturning, TMode>, ...args: TMode extends 'single' ? [config?: Omit<MutationExecuteConfig, 'mode'>] : [config: never]): Promise<TMode extends 'single' ? MutationExecuteResult<TTable, TReturning, 'single'> : never>;
   execute(this: ConvexUpdateExecutableThis<TTable, TReturning, TMode>, ...args: TMode extends 'single' ? [config?: MutationExecuteConfig] : [config?: never]): Promise<MutationExecuteResult<TTable, TReturning, TMode>>;
+  private _runStatement;
 }
 //#endregion
 //#region src/orm/database.d.ts

package/dist/orm/aggregate-index/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-Ctcw2VRq.js";
+import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-Bxzoofl4.js";
 
 //#region src/orm/aggregate-index/capability.d.ts
 /**