kitcn 0.32.2 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # 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

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-BJm_VSDT.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-Dgf4lrO-.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/generated/index.d.ts

@@ -1,2 +1,2 @@
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-BRm1dNQE.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-PdNGvNYP.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };

package/dist/auth/index.d.ts

@@ -1,7 +1,7 @@
 import { a as QueryCtxWithPreferredOrmQueryTable, n as LookupByIdResultByCtx, t as DocByCtx } from "../query-context-BkNjkDCk.js";
 import { t as GetAuth } from "../types-ex0-J-SC.js";
 import { t as GenericCtx } from "../context-utils-Cbv4r0AA.js";
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-BRm1dNQE.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-PdNGvNYP.js";
 import * as convex_values0 from "convex/values";
 import { Infer } from "convex/values";
 import { AuthConfig, DocumentByName, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericSchema, PaginationOptions, PaginationResult, SchemaDefinition, TableNamesInDataModel } from "convex/server";
@@ -111,22 +111,22 @@ declare const adapterWhereValidator: convex_values0.VObject<{
   mode?: "sensitive" | "insensitive" | undefined;
   connector?: "AND" | "OR" | undefined;
   operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-  value: string | number | boolean | string[] | number[] | null;
   field: string;
+  value: string | number | boolean | string[] | number[] | null;
 }, {
   connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
   field: convex_values0.VString<string, "required">;
   mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
   operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
   value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-}, "required", "mode" | "value" | "connector" | "field" | "operator">;
+}, "required", "mode" | "connector" | "field" | "operator" | "value">;
 declare const adapterArgsValidator: convex_values0.VObject<{
   where?: {
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined;
   limit?: number | undefined;
   offset?: number | undefined;
@@ -152,21 +152,21 @@ declare const adapterArgsValidator: convex_values0.VObject<{
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined, convex_values0.VObject<{
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }, {
     connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
     field: convex_values0.VString<string, "required">;
     mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
     operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
     value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-  }, "required", "mode" | "value" | "connector" | "field" | "operator">, "optional">;
+  }, "required", "mode" | "connector" | "field" | "operator" | "value">, "optional">;
 }, "required", "model" | "where" | "limit" | "offset" | "select" | "sortBy" | "sortBy.field" | "sortBy.direction">;
 declare const hasUniqueFields: (betterAuthSchema: BetterAuthDBSchema, model: string, input: Record<string, any>) => boolean;
 declare const checkUniqueFields: <Schema extends SchemaDefinition<any, any>>(ctx: GenericQueryCtx<GenericDataModel>, schema: Schema, betterAuthSchema: BetterAuthDBSchema, table: string, input: Record<string, any>, doc?: Record<string, any>) => Promise<void>;

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-BJm_VSDT.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;
@@ -3065,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;
@@ -3099,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.
@@ -3138,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;
@@ -3203,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.
@@ -3634,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/{generated-contract-disabled-BRm1dNQE.d.ts → generated-contract-disabled-PdNGvNYP.d.ts}

@@ -201,8 +201,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     model: string;
   }, Promise<number | null>>;
@@ -211,8 +211,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -239,8 +239,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -268,8 +268,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -283,8 +283,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
@@ -308,8 +308,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     select?: string[] | undefined;
     model: string;
@@ -321,8 +321,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
         mode?: "sensitive" | "insensitive" | undefined;
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       set?: Record<string, any> | undefined;
       model: string;
@@ -335,8 +335,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
       update: {
@@ -370,8 +370,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
       update: {

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-BJm_VSDT.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
 /**