kitcn 0.31.1 → 0.32.0

package/dist/orm/index.js

@@ -3,9 +3,9 @@ import { d as boolean, i as detectMigrationDrift, l as migrationExtension, n as
 import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-CIoUYCqO.js";
 import { o as id } from "../schema-BFP_awgP.js";
 import { a as OrmSchemaDefinition, c as OrmSchemaExtensionTriggers, d as OrmSchemaRelations, f as OrmSchemaTriggers, g as TablePolymorphic, h as TableName, i as OrmContext, l as OrmSchemaExtensions, n as Columns, o as OrmSchemaExtensionRelations, p as RlsPolicies, r as EnableRLS, s as OrmSchemaExtensionTables, t as Brand, u as OrmSchemaOptions } from "../symbols-DDNAddkd.js";
-import { A as inArray, B as notBetween, C as eq, D as gt, E as filterValuesEqual, F as lt, G as startsWith, H as notInArray, I as lte, L as matchLikePattern, M as isNotNull, N as isNull, O as gte, P as like, R as ne, S as endsWith, T as filterValueInList, U as notLike, V as notIlike, W as or, _ as arrayContains, a as findVectorIndexByName, b as column, c as getRankIndexes, d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, g as arrayContained, h as and, i as findSearchIndexByName, j as isFieldReference, k as ilike, l as resolveIndexOrderPushdown, m as usesSystemCreatedAtAlias, n as findIndexForColumns, o as getAggregateIndexes, r as findRelationIndex, s as getIndexes, t as findExactIndexForColumns, u as CREATED_AT_MIGRATION_MESSAGE, v as arrayOverlaps, w as fieldRef, x as contains, y as between, z as not } from "../index-utils-C1DyktHe.js";
-import { a as indexKeyWithinBounds, c as streamIndexRange, i as getIndexFields, l as isUnsetToken, n as EmptyStream, o as mergedStream, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-DdSg3fuk.js";
-import { $ as patchReferencingRows, A as enforcePolymorphicWrite, B as getForeignKeys, C as collectPrimaryIdLookupRows, D as encodeUndefinedDeep, E as deserializeFilterExpression, F as evaluateCheckConstraintTriState, G as getTableColumns$2, H as getMutationCollectionLimits, I as evaluateFilter, J as getUniqueIndexes, K as getTableDeleteConfig, L as extractPrimaryIdLookup, M as ensureDefaultColumns, N as ensureNonNullValues, O as enforceCheckConstraints, P as ensureNullableColumns, Q as normalizeTemporalComparableValue, R as getChecks, S as collectMutationRowsBounded, T as decodeUndefinedDeep, U as getMutationExecutionMode, V as getMutationAsyncDelayMs, W as getOrmContext, X as hydrateDateFieldsForRead, Y as hardDeleteRow, Z as normalizeDateFieldsForWrite, _ as applyDefaults, at as splitReturningSelection, b as buildForeignKeyGraph, c as getAggregateIndexDefinitions, ct as toConvexFilter, d as COUNT_ERROR, dt as markLifecycleHookedTables, et as resolveOrmRuntimeDefaults, f as createAggregateError, ft as compileConvexFilter, g as ensureCountAllowedForRls, h as ensureAggregateAllowedForRls, ht as mapWithConcurrency, it as softDeleteRow, j as enforceUniqueIndexes, k as enforceForeignKeys, l as getRankIndexDefinitions, lt as unsetFieldsOf, mt as isConvexEnforceableFilter, nt as selectReturningRowWithHydration, o as aggregateExtension, ot as stripUnsetFields, p as createCountError, pt as convexAnd, q as getTableName, rt as serializeFilterExpression, st as takeRowsWithinByteBudget, tt as returningSelectionReadsCreationTime, u as AGGREGATE_ERROR, ut as hasLifecycleHooks, v as applyIncomingForeignKeyActionsOnDelete, w as createForeignKeyProbeMemo, x as canUsePrimaryIdLookupCursor, y as applyIncomingForeignKeyActionsOnUpdate, z as getColumnName$1 } from "../schema-DbPcDW-N.js";
+import { A as inArray, B as notBetween, C as eq, D as gt, E as filterValuesEqual, F as lt, G as startsWith, H as notInArray, I as lte, L as matchLikePattern, M as isNotNull, N as isNull, O as gte, P as like, R as ne, S as endsWith, T as filterValueInList, U as notLike, V as notIlike, W as or, _ as arrayContains, a as findVectorIndexByName, b as column, c as getRankIndexes, d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, g as arrayContained, h as and, i as findSearchIndexByName, j as isFieldReference, k as ilike, l as resolveIndexOrderPushdown, m as usesSystemCreatedAtAlias, n as findIndexForColumns, o as getAggregateIndexes, r as findRelationIndex, s as getIndexes, t as findExactIndexForColumns, u as CREATED_AT_MIGRATION_MESSAGE, v as arrayOverlaps, w as fieldRef, x as contains, y as between, z as not } from "../index-utils-DvK7P6Q1.js";
+import { a as indexKeyWithinBounds, c as streamIndexRange, i as getIndexFields, l as isUnsetToken, n as EmptyStream, o as mergedStream, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-D4z1CnDH.js";
+import { $ as patchReferencingRows, A as enforcePolymorphicWrite, B as getForeignKeys, C as collectPrimaryIdLookupRows, D as encodeUndefinedDeep, E as deserializeFilterExpression, F as evaluateCheckConstraintTriState, G as getTableColumns$2, H as getMutationCollectionLimits, I as evaluateFilter, J as getUniqueIndexes, K as getTableDeleteConfig, L as extractPrimaryIdLookup, M as ensureDefaultColumns, N as ensureNonNullValues, O as enforceCheckConstraints, P as ensureNullableColumns, Q as normalizeTemporalComparableValue, R as getChecks, S as collectMutationRowsBounded, T as decodeUndefinedDeep, U as getMutationExecutionMode, V as getMutationAsyncDelayMs, W as getOrmContext, X as hydrateDateFieldsForRead, Y as hardDeleteRow, Z as normalizeDateFieldsForWrite, _ as applyDefaults, at as splitReturningSelection, b as buildForeignKeyGraph, c as getAggregateIndexDefinitions, ct as toConvexFilter, d as COUNT_ERROR, dt as markLifecycleHookedTables, et as resolveOrmRuntimeDefaults, f as createAggregateError, ft as compileConvexFilter, g as ensureCountAllowedForRls, h as ensureAggregateAllowedForRls, ht as mapWithConcurrency, it as softDeleteRow, j as enforceUniqueIndexes, k as enforceForeignKeys, l as getRankIndexDefinitions, lt as unsetFieldsOf, mt as isConvexEnforceableFilter, nt as selectReturningRowWithHydration, o as aggregateExtension, ot as stripUnsetFields, p as createCountError, pt as convexAnd, q as getTableName, rt as serializeFilterExpression, st as takeRowsWithinByteBudget, tt as returningSelectionReadsCreationTime, u as AGGREGATE_ERROR, ut as hasLifecycleHooks, v as applyIncomingForeignKeyActionsOnDelete, w as createForeignKeyProbeMemo, x as canUsePrimaryIdLookupCursor, y as applyIncomingForeignKeyActionsOnUpdate, z as getColumnName$1 } from "../schema-Bh7AmJwY.js";
 import { t as defineSchemaExtension } from "../extensions-Bp0XHanR.js";
 import { compareValues, convexToJson, jsonToConvex, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric, internalQueryGeneric } from "convex/server";
@@ -703,11 +703,15 @@ async function filterSelectRows(options) {
 */
 const INDEX_ORDER_BONUS = 30;
 /**
-* Widest `in` list still worth turning into an index union when it is the only
-* indexable term. Each value becomes its own index range, so past this width
-* the fan-out costs more than the single scan it would replace.
+* Widest index union worth opening. Each probe becomes its own index range, and
+* a streamed union holds every one of them open at once, so past this width the
+* fan-out costs more than the single scan it would replace.
+*
+* Owns both ends of that decision: whether to promote an `in` inside an AND to
+* a union here, and whether the executor may read a compiled union as a merged
+* stream instead of a bounded scan.
 */
-const MAX_PROMOTED_PROBES = 64;
+const MAX_INDEX_UNION_PROBES = 64;
 var WhereClauseCompiler = class {
 	/**
 	* Requested sort fields for the compile in flight. Index choice has to see
@@ -785,7 +789,7 @@ var WhereClauseCompiler = class {
 		for (const term of terms) {
 			if (term.type !== "binary" || term.operator !== "inArray") continue;
 			const probePlan = this.tryCompileInArray(term);
-			if (!probePlan || probePlan.probeFilters.length > MAX_PROMOTED_PROBES) continue;
+			if (!probePlan || probePlan.probeFilters.length > MAX_INDEX_UNION_PROBES) continue;
 			return {
 				...probePlan,
 				postFilters: [expression]
@@ -976,9 +980,16 @@ var WhereClauseCompiler = class {
 	findLeadingIndex(fieldName) {
 		const candidates = this.availableIndexes.filter((index) => index.indexFields[0] === fieldName).sort((a, b) => a.indexFields.length - b.indexFields.length);
 		if (this.orderFields.length > 0) {
-			const orderField = this.orderFields[0];
-			const serving = candidates.find((index) => index.indexFields.length > 1 && index.indexFields[1] === orderField);
-			if (serving) return serving;
+			let best = null;
+			let bestServed = 0;
+			for (const index of candidates) {
+				const served = this.servedOrderFieldCount(index.indexFields, 1);
+				if (served > bestServed) {
+					best = index;
+					bestServed = served;
+				}
+			}
+			if (best) return best;
 		}
 		return candidates[0] ?? null;
 	}
@@ -1155,10 +1166,42 @@ var WhereClauseCompiler = class {
 	* Reward an index that also supplies the requested order. Large enough to
 	* clear the 25-point exact-over-prefix premium, so `(orgId, createdAt)` beats
 	* `(orgId)` for `where { orgId } orderBy { createdAt }`.
+	*
+	* The reward grows with how much of the sort the index carries, so
+	* `(orgId, createdAt, title)` beats `(orgId, createdAt)` for a two-field
+	* sort: only the longer one lets the scan produce the whole tuple, and
+	* picking the shorter one costs the entire read bound. The extra point per
+	* field is deliberately small — order coverage breaks ties between indexes
+	* that already serve the filter equally well, it does not outrank filtering.
 	*/
 	indexOrderBonus(indexFields, pinnedLength) {
 		if (this.orderFields.length === 0 || pinnedLength >= indexFields.length) return 0;
-		return indexFields[pinnedLength] === this.orderFields[0] ? INDEX_ORDER_BONUS : 0;
+		const served = this.servedOrderFieldCount(indexFields, pinnedLength);
+		return served === 0 ? 0 : INDEX_ORDER_BONUS + (served - 1);
+	}
+	/**
+	* How many moving sort fields this index would produce for free. Sort fields
+	* inside the pinned prefix are constant and can appear anywhere in the
+	* request; every other field must match the remaining index keys in order.
+	*/
+	servedOrderFieldCount(indexFields, pinnedLength) {
+		const pinnedFields = new Set(indexFields.slice(0, pinnedLength));
+		let indexOffset = pinnedLength;
+		let orderOffset = 0;
+		let served = 0;
+		while (orderOffset < this.orderFields.length) {
+			const orderField = this.orderFields[orderOffset];
+			if (pinnedFields.has(orderField)) {
+				orderOffset += 1;
+				continue;
+			}
+			if (indexFields[indexOffset] !== orderField) break;
+			served += 1;
+			indexOffset += 1;
+			orderOffset += 1;
+		}
+		if (this.orderFields.length > 1 && orderOffset === this.orderFields.length && indexOffset < indexFields.length) return 0;
+		return served;
 	}
 	/**
 	* Check if referenced fields exactly match index fields in order
@@ -1290,6 +1333,22 @@ const RELATION_COUNT_ERROR = {
 };
 const RELATION_DEPTH_ERROR = "RELATION_DEPTH_EXCEEDED";
 /**
+* Whether a compiled column validator admits an absent or null value.
+*
+* `v.optional(...)` is how a non-`.notNull()` column is emitted, and absent is
+* a legal stored value for every document written before the column existed, so
+* both halves matter. Unrecognized shapes answer true: the only caller uses
+* this to decide whether it may skip a sort, and guessing "never null" there
+* silently reorders rows.
+*/
+const validatorAcceptsMissingOrNull = (validator) => {
+	if (!validator) return true;
+	if (validator.isOptional === "optional") return true;
+	if (validator.kind === "null" || validator.kind === "any") return true;
+	if (validator.kind === "union") return (validator.members ?? []).some(validatorAcceptsMissingOrNull);
+	return false;
+};
+/**
 * How many levels of `with` the relation loader will follow. A `with` config is
 * a finite object the caller wrote, so its own nesting is the real bound; this
 * ceiling only stops a self-referential config from recursing forever. Reaching
@@ -1712,18 +1771,41 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		return (Array.isArray(orderBy) ? orderBy : [orderBy]).filter((item) => item !== void 0).map((item) => this._normalizeOrderByValue(item));
 	}
 	_orderBySpecs(orderBy, tableConfig = this.tableConfig) {
+		const withNullability = (spec) => ({
+			...spec,
+			nullable: this._isNullableOrderField(spec.field, tableConfig)
+		});
 		if (orderBy && typeof orderBy === "object" && !Array.isArray(orderBy) && !this._isOrderByClause(orderBy) && !this._isColumnBuilder(orderBy)) return Object.entries(orderBy).map(([field, direction]) => ({
 			field: this._normalizePublicFieldName(field, tableConfig),
 			direction
-		})).filter((entry) => entry.direction === "asc" || entry.direction === "desc").map((entry) => ({
+		})).filter((entry) => entry.direction === "asc" || entry.direction === "desc").map((entry) => withNullability({
 			field: entry.field,
 			direction: entry.direction
 		}));
-		return this._normalizeOrderBy(orderBy).map((clause) => ({
+		return this._normalizeOrderBy(orderBy).map((clause) => withNullability({
 			field: clause.column.columnName,
 			direction: clause.direction
 		}));
 	}
+	/**
+	* Whether rows can be missing this sort column or hold null in it.
+	*
+	* Only the declared validator can answer: a column that is not `.notNull()`
+	* compiles to `v.optional(v.union(v.null(), T))`, so both absent and null are
+	* legal stored values — and `timestamp().notNull().defaultNow()` on
+	* `createdAt` is deliberately emitted as optional for migration safety, so
+	* reading `config.notNull` alone would answer wrong for it. Anything the
+	* lookup cannot resolve counts as nullable, which only costs a pushdown.
+	*/
+	_isNullableOrderField(field, tableConfig) {
+		if (field === INTERNAL_ID_FIELD || field === INTERNAL_CREATION_TIME_FIELD) return false;
+		try {
+			const builder = this._getColumns(tableConfig)[field];
+			return validatorAcceptsMissingOrNull(builder?.build?.());
+		} catch {
+			return true;
+		}
+	}
 	_resolveNonPaginatedLimit(config) {
 		const explicitLimit = config.limit;
 		const defaultLimit = getOrmContext(this.db)?.resolvedDefaults?.defaultLimit ?? this.tableConfig.defaults?.defaultLimit;
@@ -1744,8 +1826,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				return 1;
 			}
 			if (bVal === null || bVal === void 0) return -1;
-			if (aVal < bVal) return order.direction === "asc" ? -1 : 1;
-			if (aVal > bVal) return order.direction === "asc" ? 1 : -1;
+			const comparison = compareValues(aVal, bVal);
+			if (comparison !== 0) return order.direction === "asc" ? comparison : -comparison;
 		}
 		return 0;
 	}
@@ -2675,28 +2757,99 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	_findStreamOrderIndex(field) {
 		return getIndexes(this.tableConfig.table).find((index) => index.fields[0] === field);
 	}
-	_buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex) {
-		const schemaDefinition = this._getSchemaDefinitionOrThrow();
-		let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-		const primaryOrder = queryConfig.order?.[0];
-		const primaryOrderDirection = primaryOrder?.direction ?? "asc";
-		if (queryConfig.index) streamQuery = streamQuery.withIndex(queryConfig.index.name, (q) => {
+	/**
+	* 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
+	* 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.
+	*/
+	_buildProbeUnionStream(params) {
+		const { probeFilters } = params;
+		if (probeFilters.length === 0 || probeFilters.length > MAX_INDEX_UNION_PROBES) return null;
+		const streamIndexFields = getIndexFields(this.tableConfig.name, params.indexName, params.schemaDefinition);
+		const pinned = this._indexEqPrefixCount({ probeFilters });
+		let mergeOffset = -1;
+		for (let i = 0; i <= pinned && i < streamIndexFields.length; i += 1) if (streamIndexFields[i] === params.orderField) {
+			mergeOffset = i;
+			break;
+		}
+		if (mergeOffset === -1) return null;
+		return mergedStream(probeFilters.map((filters) => stream(this.db, params.schemaDefinition).query(this.tableConfig.name).withIndex(params.indexName, (q) => {
+			let indexQuery = q;
+			for (const filter of filters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
+			return indexQuery;
+		}).order(params.order)), streamIndexFields.slice(mergeOffset));
+	}
+	/**
+	* The read the compiled plan describes, as a stream, with nothing filtered
+	* yet.
+	*
+	* Precedence: the compiled index union, then the compiled index range, then
+	* the caller's pinned `.withIndex(...)`, then an index that supplies the
+	* requested order, then a full scan. The first two rungs can only ever refine
+	* what the caller pinned — `_toConvexQuery` discards a compiled plan that
+	* would displace a caller's index or its bounds before it gets here.
+	*
+	* `probeUnion` tells the caller the read is bounded by index ranges rather
+	* than by scan length, which is what makes a scan budget unnecessary. A
+	* rejected union stays unanchored; its original predicate remains in
+	* `queryConfig.postFilters` for the caller to apply while pulling the scan.
+	*/
+	_buildPlanStream(params) {
+		const { queryConfig, configuredIndex, order, primaryOrder } = params;
+		const probeIndex = queryConfig.probeFilters.length > 0 ? queryConfig.index : void 0;
+		const hasProbeUnionPlan = !!probeIndex;
+		if (hasProbeUnionPlan) {
+			const probeUnion = this._buildProbeUnionStream({
+				schemaDefinition: params.schemaDefinition,
+				indexName: probeIndex.name,
+				probeFilters: queryConfig.probeFilters,
+				order,
+				orderField: primaryOrder?.field ?? probeIndex.fields[0]
+			});
+			if (probeUnion) return {
+				stream: probeUnion,
+				probeUnion: true
+			};
+		}
+		let streamQuery = stream(this.db, params.schemaDefinition).query(this.tableConfig.name);
+		if (queryConfig.index && !hasProbeUnionPlan) streamQuery = streamQuery.withIndex(queryConfig.index.name, (q) => {
 			let indexQuery = q;
 			for (const filter of queryConfig.index.filters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
 			return indexQuery;
 		});
-		else if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-		else if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) {
-			const orderIndex = this._findStreamOrderIndex(primaryOrder.field);
-			if (orderIndex) streamQuery = streamQuery.withIndex(orderIndex.name, (q) => q);
-		}
-		streamQuery = streamQuery.order(primaryOrderDirection);
+		else if (!hasProbeUnionPlan && configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
+		else if (!hasProbeUnionPlan && params.orderIndexName) streamQuery = streamQuery.withIndex(params.orderIndexName, (q) => q);
+		return {
+			stream: streamQuery.order(order),
+			probeUnion: false
+		};
+	}
+	_buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex, fallbackOrder) {
+		const schemaDefinition = this._getSchemaDefinitionOrThrow();
+		const primaryOrder = queryConfig.order?.[0];
+		const planStream = this._buildPlanStream({
+			queryConfig,
+			configuredIndex,
+			order: primaryOrder?.direction ?? fallbackOrder,
+			primaryOrder,
+			orderIndexName: primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD ? this._findStreamOrderIndex(primaryOrder.field)?.name ?? null : null,
+			schemaDefinition
+		});
+		let streamQuery = planStream.stream;
 		if (queryConfig.postFilters.length > 0 || wherePredicate) streamQuery = streamQuery.filterWith(async (row) => {
 			for (const filter of queryConfig.postFilters) if (!this._evaluatePostFetchFilter(row, filter)) return false;
 			if (wherePredicate) return await wherePredicate(row);
 			return true;
 		});
-		return streamQuery;
+		return {
+			stream: streamQuery,
+			probeUnion: planStream.probeUnion
+		};
 	}
 	/**
 	* Stream equivalent of the `db.query(...)` chain, used when a post-fetch
@@ -2714,16 +2867,15 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	_buildResidualFilterStream(params) {
 		const schemaDefinition = this.schema[OrmSchemaDefinition];
 		if (!schemaDefinition) return null;
-		const { queryConfig, configuredIndex, membershipFilter, orderIndexName, primaryOrder, fallbackOrder } = params;
-		let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-		if (queryConfig.index) streamQuery = streamQuery.withIndex(queryConfig.index.name, (q) => {
-			let indexQuery = q;
-			for (const filter of queryConfig.index.filters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
-			return indexQuery;
-		});
-		else if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-		else if (orderIndexName) streamQuery = streamQuery.withIndex(orderIndexName, (q) => q);
-		streamQuery = streamQuery.order(primaryOrder ? primaryOrder.direction : fallbackOrder);
+		const { queryConfig, configuredIndex, membershipFilter, orderIndexName, primaryOrder, pushdownDirection, fallbackOrder } = params;
+		let streamQuery = this._buildPlanStream({
+			queryConfig,
+			configuredIndex,
+			order: pushdownDirection ?? (primaryOrder ? primaryOrder.direction : fallbackOrder),
+			primaryOrder,
+			orderIndexName,
+			schemaDefinition
+		}).stream;
 		streamQuery = streamQuery.filterWith(async (row) => {
 			for (const filter of queryConfig.postFilters) if (!this._evaluatePostFetchFilter(row, filter)) return false;
 			return membershipFilter ? await membershipFilter(row) : true;
@@ -3876,7 +4028,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (endCursor !== void 0 && searchConfig) throw new Error("endCursor is not supported with search in findMany().");
 		if (endCursor !== void 0 && vectorSearchConfig) throw new Error("endCursor is not supported with vectorSearch in findMany().");
 		if (useAdvancedStreamPath) {
-			const fallbackOrder = (queryConfig.order?.[0])?.direction ?? "asc";
+			const fallbackOrder = (queryConfig.order?.[0])?.direction ?? (endCursor !== void 0 && !pipeline ? "desc" : "asc");
 			let streamQuery;
 			const unionSources = pipeline?.union ?? [];
 			if (unionSources.length > 0) {
@@ -3892,13 +4044,22 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					if (orderedIdList.field === INTERNAL_CREATION_TIME_FIELD) throw new Error("An id IN pipeline cannot combine orderBy on createdAt with maxScan, because ordering an id list by creation time requires reading every id in the list. Drop maxScan, or drop orderBy to page in id-list order at one read per row.");
 					if (queryConfig.order?.length !== 1 || configuredIndex?.name || queryConfig.index || !this._findStreamOrderIndex(orderedIdList.field)) throw new Error(`An id IN pipeline cannot combine orderBy on ${this._toPublicFilterFieldName(orderedIdList.field)} with maxScan, because the scan cannot produce that order. It needs a single orderBy field that an index leads with, and no index pinned by withIndex().`);
 				}
-				streamQuery = await this._buildIdLookupStream({
+				const idLookupStream = await this._buildIdLookupStream({
 					configuredIndex,
 					idLookup,
 					order: fallbackOrder,
 					queryConfig,
 					wherePredicate
-				}) ?? this._buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex);
+				});
+				if (idLookupStream) streamQuery = idLookupStream;
+				else {
+					const baseStream = this._buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex, fallbackOrder);
+					if (isCursorPaginated && queryConfig.strategy === "multiProbe" && !!queryConfig.index && !baseStream.probeUnion && maxScan === void 0) {
+						if (strict) throw new Error("Pagination with multi-probe index-union filters requires maxScan when strict=true. Add maxScan, order by a field the union can serve, or make the query indexable.");
+						console.warn("Pagination with multi-probe index-union filters is running without maxScan because strict: false.");
+					}
+					streamQuery = baseStream.stream;
+				}
 			}
 			const rootRlsEnabled = isRlsEnabled(this.tableConfig.table);
 			if (rootRlsEnabled) {
@@ -4014,6 +4175,37 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const primaryOrder = postFetchOrders[0];
 		const hasSecondaryOrders = postFetchOrders.length > 1;
 		let orderIndexName = null;
+		/**
+		* Direction the scanned index can be walked in to produce the *whole*
+		* requested sort, or null when some of it still has to run in JavaScript.
+		* This is the read bound: a non-null answer means `take(limit)` is the
+		* exact page.
+		*/
+		let orderPushdownDirection = null;
+		/**
+		* Ask the one owner both questions an index has to answer.
+		*
+		* `whole` decides the read bound. `primary` is narrower and only feeds the
+		* cursor-pagination diagnostics, which are about the leading sort field
+		* having an index at all — an index that anchors the primary but not the
+		* tie-break is still the right index to scan, and must not start reporting
+		* itself as unindexed.
+		*/
+		const resolveOrderForIndex = (indexFields, pinnedEqCount) => {
+			const whole = resolveIndexOrderPushdown({
+				indexFields,
+				pinnedEqCount,
+				orderSpecs: postFetchOrders
+			});
+			return {
+				whole,
+				primary: whole ?? (primaryOrder ? resolveIndexOrderPushdown({
+					indexFields,
+					pinnedEqCount,
+					orderSpecs: [primaryOrder]
+				}) : null)
+			};
+		};
 		if (queryConfig.index) {
 			const indexConfig = queryConfig.index;
 			query = query.withIndex(indexConfig.name, (q) => {
@@ -4022,12 +4214,9 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				return indexQuery;
 			});
 			if (primaryOrder) {
-				const pushdownDirection = resolveIndexOrderPushdown({
-					indexFields: indexConfig.fields,
-					pinnedEqCount: this._indexEqPrefixCount(queryConfig),
-					orderSpecs: [primaryOrder]
-				});
-				if (pushdownDirection) query = query.order(pushdownDirection);
+				const resolved = resolveOrderForIndex(indexConfig.fields, this._indexEqPrefixCount(queryConfig));
+				orderPushdownDirection = resolved.whole;
+				if (resolved.primary) query = query.order(resolved.primary);
 				else needsPostFetchSortForPrimary = true;
 			}
 		} else if (configuredIndex?.name) {
@@ -4036,27 +4225,51 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			const configuredRange = configuredIndex.range;
 			query = query.withIndex(configuredIndex.name, configuredRange ? (q) => configuredRange(observeConfiguredIndexRange(q, rangeOperations)) : (q) => q);
 			if (primaryOrder) {
-				const pushdownDirection = resolveIndexOrderPushdown({
-					indexFields: configuredIndexFields,
-					pinnedEqCount: countConfiguredIndexEqPrefix(configuredIndexFields, rangeOperations),
-					orderSpecs: [primaryOrder]
-				});
-				if (pushdownDirection) query = query.order(pushdownDirection);
+				const resolved = resolveOrderForIndex(configuredIndexFields, countConfiguredIndexEqPrefix(configuredIndexFields, rangeOperations));
+				orderPushdownDirection = resolved.whole;
+				if (resolved.primary) query = query.order(resolved.primary);
 				else needsPostFetchSortForPrimary = true;
 			}
 		} else if (queryConfig.order && primaryOrder) {
 			const orderField = primaryOrder.field;
-			if (orderField === "_creationTime") query = query.order(primaryOrder.direction);
-			else {
-				const orderIndex = getIndexes(this.tableConfig.table).find((idx) => idx.fields[0] === orderField) ?? this.edgeMetadata.find((idx) => idx.indexFields[0] === orderField);
-				if (orderIndex) {
-					orderIndexName = "indexName" in orderIndex ? orderIndex.indexName : orderIndex.name;
+			if (orderField === INTERNAL_CREATION_TIME_FIELD) {
+				query = query.order(primaryOrder.direction);
+				orderPushdownDirection = resolveIndexOrderPushdown({
+					indexFields: [],
+					pinnedEqCount: 0,
+					orderSpecs: postFetchOrders
+				});
+			} else {
+				const candidates = [...getIndexes(this.tableConfig.table).map((idx) => ({
+					fields: idx.fields,
+					name: idx.name
+				})), ...this.edgeMetadata.map((idx) => ({
+					fields: idx.indexFields,
+					name: idx.indexName
+				}))];
+				let selected;
+				for (const candidate of candidates) {
+					const direction = resolveIndexOrderPushdown({
+						indexFields: candidate.fields,
+						pinnedEqCount: 0,
+						orderSpecs: postFetchOrders
+					});
+					if (direction) {
+						selected = candidate;
+						orderPushdownDirection = direction;
+						break;
+					}
+				}
+				selected ??= candidates.find((candidate) => candidate.fields[0] === orderField);
+				if (selected) {
+					orderIndexName = selected.name;
 					query = query.withIndex(orderIndexName, (q) => q);
-					query = query.order(primaryOrder.direction);
+					query = query.order(orderPushdownDirection ?? primaryOrder.direction);
 				} else needsPostFetchSortForPrimary = true;
 			}
 		}
-		usePostFetchSort = needsPostFetchSortForPrimary || hasSecondaryOrders;
+		usePostFetchSort = postFetchOrders.length > 0 && orderPushdownDirection === null;
+		const hasUnservedSecondaryOrders = hasSecondaryOrders && orderPushdownDirection === null;
 		if (wherePredicate) {
 			const predicateIndex = configuredIndex;
 			if (!predicateIndex?.name) throw new Error("predicate(...) requires .withIndex(name, range?) on the query.");
@@ -4068,9 +4281,9 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					if (strict) throw new Error(`Pagination: Field '${primaryOrder?.field}' has no index. Add an index or disable strict.`);
 					console.warn(`Pagination: Field '${primaryOrder?.field}' has no index. Falling back to _creationTime ordering.`);
 				}
-				if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are applied per page and may be unstable across pages.");
+				if (hasUnservedSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are ignored because no index serves the whole sort.");
 			}
-			if (primaryOrder && !needsPostFetchSortForPrimary) streamQuery = streamQuery.order(primaryOrder.direction);
+			if (primaryOrder && !needsPostFetchSortForPrimary) streamQuery = streamQuery.order(orderPushdownDirection ?? primaryOrder.direction);
 			else if (isCursorPaginated) streamQuery = streamQuery.order("desc");
 			streamQuery = streamQuery.filterWith(async (row) => {
 				for (const filter of queryConfig.postFilters) if (!this._evaluatePostFetchFilter(row, filter)) return false;
@@ -4116,12 +4329,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			const convexProbeFilters = queryConfig.postFilters.filter((filter) => this._isConvexEnforceableFilter(filter));
 			const probeHasResidualFilter = convexProbeFilters.length !== queryConfig.postFilters.length;
 			const probeHasPostFetchMembership = this._hasSearchDisallowedRelationFilter(whereFilter, this.tableConfig) || this.rls?.mode !== "skip" && isRlsEnabled(this.tableConfig.table);
-			const probeOrderDirection = primaryOrder ? resolveIndexOrderPushdown({
-				indexFields: queryConfig.index.fields,
-				pinnedEqCount: this._indexEqPrefixCount(queryConfig),
-				orderSpecs: [primaryOrder]
-			}) : null;
-			const probeBound = probeLimit !== void 0 && !probeHasResidualFilter && !probeHasPostFetchMembership && (postFetchOrders.length === 0 || probeOrderDirection !== null && !hasSecondaryOrders) ? probeOffset + probeLimit : void 0;
+			const probeOrderDirection = orderPushdownDirection;
+			const probeBound = probeLimit !== void 0 && !probeHasResidualFilter && !probeHasPostFetchMembership && (postFetchOrders.length === 0 || probeOrderDirection !== null) ? probeOffset + probeLimit : void 0;
 			const probeRows = await Promise.all(queryConfig.probeFilters.map(async (probeFilters) => {
 				let probeQuery = this.db.query(queryConfig.table).withIndex(queryConfig.index.name, (q) => {
 					let indexQuery = q;
@@ -4149,69 +4358,53 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			return (await this._applyRelationsFilterToRows(visibleRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with)).length > 0;
 		};
 		if (isCursorPaginated) {
-			if (queryConfig.strategy === "multiProbe") if (maxScan === void 0) {
-				if (strict) throw new Error("Pagination with multi-probe index-union filters requires maxScan when strict=true. Add maxScan or make the query indexable.");
-				console.warn("Pagination with multi-probe index-union filters is running without maxScan because strict: false.");
-			} else {
+			const isMultiProbePlan = queryConfig.strategy === "multiProbe" && !!queryConfig.index;
+			const isScanFallbackPlan = !queryConfig.index && queryConfig.postFilters.length > 0;
+			if (isMultiProbePlan || isScanFallbackPlan) {
 				const schemaDefinition = this.schema[OrmSchemaDefinition];
-				if (!schemaDefinition) throw new Error("Pagination with maxScan requires defineSchema(). Ensure defineSchema(tables) was used with the same tables object passed to defineRelations.");
-				let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-				if (queryConfig.order && primaryOrder) {
-					if (needsPostFetchSortForPrimary) {
-						if (strict) throw new Error(`Pagination: Field '${primaryOrder.field}' has no index. Add an index or disable strict.`);
-						console.warn(`Pagination: Field '${primaryOrder.field}' has no index. Falling back to _creationTime ordering.`);
+				const probeUnion = isMultiProbePlan && schemaDefinition ? this._buildProbeUnionStream({
+					schemaDefinition,
+					indexName: queryConfig.index.name,
+					probeFilters: queryConfig.probeFilters,
+					order: primaryOrder?.direction ?? "desc",
+					orderField: primaryOrder?.field ?? queryConfig.index.fields[0]
+				}) : null;
+				if (!probeUnion && maxScan === void 0) {
+					if (strict) throw new Error(isMultiProbePlan ? "Pagination with multi-probe index-union filters requires maxScan when strict=true. Add maxScan, order by a field the union can serve, or make the query indexable." : "Cursor pagination with scan fallback requires maxScan when strict=true. Add maxScan or make the query indexable.");
+					if (isMultiProbePlan) console.warn("Pagination with multi-probe index-union filters is running without maxScan because strict: false.");
+				}
+				if (probeUnion || maxScan !== void 0) {
+					if (!schemaDefinition) throw new Error("Pagination with maxScan requires defineSchema(). Ensure defineSchema(tables) was used with the same tables object passed to defineRelations.");
+					let streamQuery = probeUnion;
+					if (!streamQuery) {
+						streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
+						if (isScanFallbackPlan && configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
 					}
-					if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are applied per page and may be unstable across pages.");
-					streamQuery = streamQuery.order(primaryOrder.direction);
-				} else streamQuery = streamQuery.order("desc");
-				if (queryConfig.postFilters.length > 0) streamQuery = streamQuery.filterWith(async (row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
-				const paginationResult = await streamQuery.paginate({
-					cursor: cursor ?? null,
-					limit: config.limit,
-					maxScan
-				});
-				let pageRows = paginationResult.page;
-				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
-				return {
-					page: await this._finalizeRows(pageRows),
-					continueCursor: paginationResult.continueCursor,
-					isDone: paginationResult.isDone,
-					pageStatus: paginationResult.pageStatus,
-					splitCursor: paginationResult.splitCursor
-				};
-			}
-			if (!queryConfig.index && queryConfig.postFilters.length > 0) if (maxScan === void 0) {
-				if (strict) throw new Error("Cursor pagination with scan fallback requires maxScan when strict=true. Add maxScan or make the query indexable.");
-			} else {
-				const schemaDefinition = this.schema[OrmSchemaDefinition];
-				if (!schemaDefinition) throw new Error("Pagination with maxScan requires defineSchema(). Ensure defineSchema(tables) was used with the same tables object passed to defineRelations.");
-				let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-				if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-				if (queryConfig.order && primaryOrder) {
-					if (needsPostFetchSortForPrimary) {
-						if (strict) throw new Error(`Pagination: Field '${primaryOrder.field}' has no index. Add an index or disable strict.`);
-						console.warn(`Pagination: Field '${primaryOrder.field}' has no index. Falling back to _creationTime ordering.`);
+					if (queryConfig.order && primaryOrder) {
+						if (needsPostFetchSortForPrimary) {
+							if (strict) throw new Error(`Pagination: Field '${primaryOrder.field}' has no index. Add an index or disable strict.`);
+							console.warn(`Pagination: Field '${primaryOrder.field}' has no index. Falling back to _creationTime ordering.`);
+						}
+						if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are ignored because this page is not read through an index that orders by them.");
 					}
-					if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are applied per page and may be unstable across pages.");
-					streamQuery = streamQuery.order(primaryOrder.direction);
-				} else streamQuery = streamQuery.order("desc");
-				streamQuery = streamQuery.filterWith(async (row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
-				const paginationResult = await streamQuery.paginate({
-					cursor: cursor ?? null,
-					limit: config.limit,
-					maxScan
-				});
-				let pageRows = paginationResult.page;
-				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
-				return {
-					page: await this._finalizeRows(pageRows),
-					continueCursor: paginationResult.continueCursor,
-					isDone: paginationResult.isDone,
-					pageStatus: paginationResult.pageStatus,
-					splitCursor: paginationResult.splitCursor
-				};
+					if (!probeUnion) streamQuery = streamQuery.order(queryConfig.order && primaryOrder ? primaryOrder.direction : "desc");
+					if (queryConfig.postFilters.length > 0) streamQuery = streamQuery.filterWith(async (row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
+					const paginationResult = await streamQuery.paginate({
+						cursor: cursor ?? null,
+						limit: config.limit,
+						maxScan
+					});
+					let pageRows = paginationResult.page;
+					pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
+					if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
+					return {
+						page: await this._finalizeRows(pageRows),
+						continueCursor: paginationResult.continueCursor,
+						isDone: paginationResult.isDone,
+						pageStatus: paginationResult.pageStatus,
+						splitCursor: paginationResult.splitCursor
+					};
+				}
 			}
 			const convexPostFilters = queryConfig.postFilters.filter((filter) => this._isConvexEnforceableFilter(filter));
 			const hasResidualPostFilter = convexPostFilters.length !== queryConfig.postFilters.length;
@@ -4221,6 +4414,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				membershipFilter: matchesPostFetchMembership,
 				orderIndexName,
 				primaryOrder,
+				pushdownDirection: orderPushdownDirection,
 				fallbackOrder: "desc"
 			}) : null;
 			if (hasResidualPostFilter && !residualPageStream) this._getSchemaDefinitionOrThrow();
@@ -4228,7 +4422,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				if (queryConfig.order && primaryOrder) {
 					if (needsPostFetchSortForPrimary && strict) throw new Error(`Pagination: Field '${primaryOrder.field}' has no index. Add an index or disable strict.`);
 					if (needsPostFetchSortForPrimary) console.warn(`Pagination: Field '${primaryOrder.field}' has no index. Falling back to _creationTime ordering.`);
-					if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are applied per page and may be unstable across pages.");
+					if (hasUnservedSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are ignored because no index serves the whole sort.");
 				}
 				const paginationResult = await residualPageStream.paginate({
 					cursor: cursor ?? null,
@@ -4251,7 +4445,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					console.warn(`Pagination: Field '${primaryOrder.field}' has no index. Falling back to _creationTime ordering.`);
 					query = query.order(primaryOrder.direction === "asc" ? "asc" : "desc");
 				}
-				if (hasSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are applied per page and may be unstable across pages.");
+				if (hasUnservedSecondaryOrders) console.warn("Pagination: Only the first orderBy field is used for cursor ordering. Secondary orderBy fields are ignored because no index serves the whole sort.");
 			} else query = query.order("desc");
 			const paginationResult = await query.paginate({
 				cursor: cursor ?? null,
@@ -4281,6 +4475,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			membershipFilter: matchesPostFetchMembership,
 			orderIndexName,
 			primaryOrder,
+			pushdownDirection: orderPushdownDirection,
 			fallbackOrder: "asc"
 		}) : null;
 		let rows;