kitcn 0.31.1 → 0.32.1

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
@@ -1279,6 +1322,20 @@ const DEFAULT_RELATION_FAN_OUT_MAX_KEYS = 1e3;
 * satisfies the limit.
 */
 const RELATION_FILTER_STREAM_CHUNK = 32;
+/**
+* Marks a relation config that only exists to answer "does a matching child
+* exist?" for a `where` clause. The lowered load may stop at the first
+* surviving child, but it must not widen the window it walks to find one --
+* that window is what decides the answer, so changing it would change results
+* rather than just their cost.
+*
+* A symbol, not a field: the emitted object is fed to the same relation loader
+* that serves a caller's `with`, and nothing a caller can write should be able
+* to claim this.
+*/
+const RELATION_EXISTENCE_PROBE = Symbol("kitcn.relationExistenceProbe");
+/** Lowering a subtree with this set emits no existence probes anywhere in it. */
+const NO_PROBE_RELATIONS = /* @__PURE__ */ new Set();
 const DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS = 4096;
 const DEFAULT_AGGREGATE_WORK_BUDGET = 16384;
 const PUBLIC_ID_FIELD = "id";
@@ -1290,6 +1347,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 +1785,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 +1840,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;
 	}
@@ -2309,7 +2405,47 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			}
 		}
 	}
+	/**
+	* Relation keys the filter tree mentions exactly once, across every OR/AND/NOT
+	* branch at this table level.
+	*
+	* `_mergeWithConfig` collapses the whole tree into one load per relation key,
+	* so a key two branches disagree about has to be loaded the way both branches
+	* can read. Only a key with a single occurrence has one predicate to satisfy,
+	* and only then can that predicate be pushed into the read plan.
+	*
+	* Relation values are not descended into: they belong to the target table and
+	* get their own count when that level is lowered.
+	*/
+	_collectSingleOccurrenceRelations(filter, tableConfig) {
+		const counts = /* @__PURE__ */ new Map();
+		const walk = (node) => {
+			if (!this._isRecord(node)) return;
+			for (const [key, value] of Object.entries(node)) {
+				if (value === void 0) continue;
+				if (key === "OR" || key === "AND") {
+					if (!Array.isArray(value)) continue;
+					for (const sub of value) walk(sub);
+					continue;
+				}
+				if (key === "NOT") {
+					walk(value);
+					continue;
+				}
+				if (!tableConfig.relations[key]) continue;
+				counts.set(key, (counts.get(key) ?? 0) + 1);
+			}
+		};
+		walk(filter);
+		const single = /* @__PURE__ */ new Set();
+		for (const [key, count] of counts) if (count === 1) single.add(key);
+		return single;
+	}
 	_buildFilterWithConfig(filter, tableConfig) {
+		if (!this._isRecord(filter)) return {};
+		return this._buildFilterWithConfigForLevel(filter, tableConfig, this._collectSingleOccurrenceRelations(filter, tableConfig));
+	}
+	_buildFilterWithConfigForLevel(filter, tableConfig, probeEligible) {
 		if (!this._isRecord(filter)) return {};
 		const result = {};
 		const entries = Object.entries(filter);
@@ -2319,27 +2455,36 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (key === "OR" || key === "AND") {
 				if (!Array.isArray(value) || value.length === 0) continue;
 				for (const sub of value) {
-					const nested = this._buildFilterWithConfig(sub, tableConfig);
+					const nested = this._buildFilterWithConfigForLevel(sub, tableConfig, probeEligible);
 					this._mergeWithConfig(result, nested);
 				}
 				continue;
 			}
 			if (key === "NOT") {
-				const nested = this._buildFilterWithConfig(value, tableConfig);
+				const nested = this._buildFilterWithConfigForLevel(value, tableConfig, probeEligible);
 				this._mergeWithConfig(result, nested);
 				continue;
 			}
 			this._assertNoLegacyPublicFieldName(key);
 			const relation = tableConfig.relations[key];
 			if (!relation) continue;
+			const probe = relation.relationType !== "one" && probeEligible.has(key) ? { [RELATION_EXISTENCE_PROBE]: true } : void 0;
 			if (typeof value === "boolean") {
-				result[key] = true;
+				result[key] = probe ?? true;
 				continue;
 			}
 			const targetTableConfig = this._getTableConfigByDbName(relation.targetTableName);
 			if (!targetTableConfig) continue;
-			const nested = this._buildFilterWithConfig(value, targetTableConfig);
-			result[key] = Object.keys(nested).length > 0 ? { with: nested } : true;
+			const nested = this._buildFilterWithConfigForLevel(value, targetTableConfig, probe ? this._collectSingleOccurrenceRelations(value, targetTableConfig) : NO_PROBE_RELATIONS);
+			const hasNested = Object.keys(nested).length > 0;
+			if (!probe) {
+				result[key] = hasNested ? { with: nested } : true;
+				continue;
+			}
+			const emitted = { ...probe };
+			if (Object.keys(value).length > 0) emitted.where = value;
+			if (hasNested) emitted.with = nested;
+			result[key] = emitted;
 		}
 		return result;
 	}
@@ -2675,28 +2820,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 +2930,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 +4091,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 +4107,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 +4238,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 +4277,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 +4288,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 +4344,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 +4392,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 +4421,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 +4477,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				membershipFilter: matchesPostFetchMembership,
 				orderIndexName,
 				primaryOrder,
+				pushdownDirection: orderPushdownDirection,
 				fallbackOrder: "desc"
 			}) : null;
 			if (hasResidualPostFilter && !residualPageStream) this._getSchemaDefinitionOrThrow();
@@ -4228,7 +4485,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 +4508,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 +4538,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			membershipFilter: matchesPostFetchMembership,
 			orderIndexName,
 			primaryOrder,
+			pushdownDirection: orderPushdownDirection,
 			fallbackOrder: "asc"
 		}) : null;
 		let rows;
@@ -4760,9 +5018,10 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* parents in the round.
 	*/
 	async _readBoundedThroughLinks(params) {
-		const { applyTargetFilters, edge, enforceTargetKeyCap, entries, fetchLimit, fetchTargets, targetFields, throughIndexName, throughTableConfig } = params;
+		const { applyAmbientTargetFilters, applyConfigTargetFilter, edge, enforceTargetKeyCap, entries, fetchLimit, fetchTargets, scanLimit, targetFields, throughIndexName, throughTableConfig } = params;
 		const throughTargetFields = edge.through.targetFields;
 		const cursors = entries.map(([key, values]) => ({
+			ambientLinks: 0,
 			buffered: [],
 			exhausted: false,
 			iterator: this._queryByFields(this.db.query(edge.through.table), edge.through.sourceFields, values, throughIndexName)[Symbol.asyncIterator](),
@@ -4789,10 +5048,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		};
 		/** Target key -> the surviving document, absent when it did not survive. */
 		const survivorByKey = /* @__PURE__ */ new Map();
+		/** Target keys that cleared the ambient filters, survivors or not. */
+		const ambientKeys = /* @__PURE__ */ new Set();
 		const resolvedKeys = /* @__PURE__ */ new Set();
 		const survivors = [];
 		while (true) {
-			const active = cursors.filter((cursor) => cursor.links.length < fetchLimit && !(cursor.exhausted && cursor.buffered.length === 0));
+			const active = cursors.filter((cursor) => cursor.links.length < fetchLimit && (scanLimit === void 0 || cursor.ambientLinks < scanLimit) && !(cursor.exhausted && cursor.buffered.length === 0));
 			if (active.length === 0) break;
 			const candidatesPerCursor = await this._mapWithConcurrency(active, async (cursor) => {
 				const need = fetchLimit - cursor.links.length;
@@ -4811,7 +5072,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				enforceTargetKeyCap(resolvedKeys.size + newKeys.size);
 				const fetched = await fetchTargets(Array.from(newKeys.entries()));
 				for (const key of newKeys.keys()) resolvedKeys.add(key);
-				const surviving = await applyTargetFilters(fetched.map((entry) => entry.target).filter((target) => !!target));
+				const ambientTargets = await applyAmbientTargetFilters(fetched.map((entry) => entry.target).filter((target) => !!target));
+				for (const target of ambientTargets) {
+					const key = this._buildRelationKey(target, targetFields);
+					if (key) ambientKeys.add(key);
+				}
+				const surviving = await applyConfigTargetFilter(ambientTargets);
 				for (const target of surviving) {
 					const key = this._buildRelationKey(target, targetFields);
 					if (!key || survivorByKey.has(key)) continue;
@@ -4823,8 +5089,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				const cursor = active[i];
 				for (const link of candidatesPerCursor[i]) {
 					if (cursor.links.length >= fetchLimit) break;
+					if (scanLimit !== void 0 && cursor.ambientLinks >= scanLimit) break;
 					const key = this._buildRelationKey(link, throughTargetFields);
-					if (!key || !survivorByKey.has(key)) continue;
+					if (!key) continue;
+					if (ambientKeys.has(key)) cursor.ambientLinks += 1;
+					if (!survivorByKey.has(key)) continue;
 					cursor.links.push(link);
 				}
 			}
@@ -4877,6 +5146,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const relationDefinition = tableConfig.relations[relationName];
 		const strict = tableConfig.strict !== false;
 		const hasPostFetchTargetFilter = this.rls?.mode !== "skip" && isRlsEnabled(targetTableConfig.table) || Boolean(relationDefinition?.where) || Boolean(relationConfig && typeof relationConfig === "object" && "where" in relationConfig && relationConfig.where);
+		const isExistenceProbe = Boolean(relationConfig) && typeof relationConfig === "object" && relationConfig[RELATION_EXISTENCE_PROBE] === true;
 		let orderSpecs = [];
 		if (relationConfig && typeof relationConfig === "object" && "orderBy" in relationConfig) {
 			let orderByValue = relationConfig.orderBy;
@@ -4891,15 +5161,22 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (effectivePerParentLimit === void 0 && !this.allowFullScan) throw new Error(`Relation "${tableConfig.name}.${relationName}" requires limit, allowFullScan: true, or defineSchema(..., { defaults: { defaultLimit } }).`);
 		const perParentOffset = relationConfig && typeof relationConfig === "object" && "offset" in relationConfig ? relationConfig.offset : void 0;
 		if (perParentOffset !== void 0 && typeof perParentOffset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
+		const probeFetchLimit = isExistenceProbe ? 1 : void 0;
+		const probeScanLimit = isExistenceProbe ? effectivePerParentLimit : void 0;
+		const canBoundPerParentRead = effectivePerParentLimit !== void 0 || isExistenceProbe;
 		const applyOffsetAndLimit = (items) => {
 			let result = items;
 			if (perParentOffset !== void 0 && perParentOffset > 0) result = result.slice(perParentOffset);
 			if (effectivePerParentLimit !== void 0) result = result.slice(0, effectivePerParentLimit);
 			return result;
 		};
-		const applyPostFetchTargetFilters = async (candidateTargets) => {
-			let filteredTargets = await this._applyRlsSelectFilter(candidateTargets, targetTableConfig);
-			if (relationDefinition?.where) filteredTargets = filteredTargets.filter((target) => this._evaluateTableFilter(target, targetTableConfig, relationDefinition.where));
+		const applyAmbientTargetFilters = async (candidateTargets) => {
+			const visibleTargets = await this._applyRlsSelectFilter(candidateTargets, targetTableConfig);
+			if (!relationDefinition?.where) return visibleTargets;
+			return visibleTargets.filter((target) => this._evaluateTableFilter(target, targetTableConfig, relationDefinition.where));
+		};
+		const applyConfigTargetFilter = async (ambientTargets) => {
+			let filteredTargets = ambientTargets;
 			if (relationConfig && typeof relationConfig === "object" && "where" in relationConfig) {
 				const whereFilter = relationConfig.where;
 				if (typeof whereFilter === "function") {
@@ -4912,6 +5189,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			}
 			return filteredTargets;
 		};
+		const applyPostFetchTargetFilters = async (candidateTargets) => applyConfigTargetFilter(await applyAmbientTargetFilters(candidateTargets));
 		let targets = [];
 		let throughBySourceKey;
 		let targetFiltersApplied = false;
@@ -4946,14 +5224,16 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					};
 				});
 			};
-			if (orderSpecs.length === 0 && effectivePerParentLimit !== void 0) {
+			if (orderSpecs.length === 0 && canBoundPerParentRead) {
 				const bounded = await this._readBoundedThroughLinks({
-					applyTargetFilters: applyPostFetchTargetFilters,
+					applyAmbientTargetFilters,
+					applyConfigTargetFilter,
 					edge,
 					enforceTargetKeyCap,
 					entries,
-					fetchLimit: Math.max(perParentOffset ?? 0, 0) + effectivePerParentLimit,
+					fetchLimit: probeFetchLimit ?? Math.max(perParentOffset ?? 0, 0) + effectivePerParentLimit,
 					fetchTargets: fetchThroughTargets,
+					scanLimit: probeScanLimit,
 					targetFields,
 					throughIndexName,
 					throughTableConfig
@@ -4993,22 +5273,25 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			});
 			const orderServedByIndex = orderSpecs.length === 0 || orderPushdownDirection !== null;
 			const applyPushdownOrder = (query) => orderPushdownDirection ? query.order(orderPushdownDirection) : query;
-			const streamPostFetchTargetFilters = orderServedByIndex && hasPostFetchTargetFilter && effectivePerParentLimit !== void 0;
+			const streamPostFetchTargetFilters = orderServedByIndex && hasPostFetchTargetFilter && canBoundPerParentRead;
 			targetFiltersApplied = streamPostFetchTargetFilters;
 			targets = (await this._mapWithConcurrency(entries, async ([, values]) => {
 				const query = this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName);
-				if (orderServedByIndex && !hasPostFetchTargetFilter && effectivePerParentLimit !== void 0) {
-					const fetchLimit = (perParentOffset ?? 0) + (effectivePerParentLimit ?? 0);
+				if (orderServedByIndex && !hasPostFetchTargetFilter && canBoundPerParentRead) {
+					const fetchLimit = probeFetchLimit ?? (perParentOffset ?? 0) + (effectivePerParentLimit ?? 0);
 					return await applyPushdownOrder(query).take(fetchLimit);
 				}
 				if (streamPostFetchTargetFilters) {
 					const visibleTargets = [];
-					const fetchLimit = Math.max(perParentOffset ?? 0, 0) + (effectivePerParentLimit ?? 0);
+					const fetchLimit = probeFetchLimit ?? Math.max(perParentOffset ?? 0, 0) + (effectivePerParentLimit ?? 0);
 					let batch = [];
+					let ambientSeen = 0;
 					const drain = async () => {
 						if (batch.length === 0) return;
-						const filtered = await applyPostFetchTargetFilters(batch);
+						const ambientTargets = await applyAmbientTargetFilters(batch);
 						batch = [];
+						ambientSeen += ambientTargets.length;
+						const filtered = await applyConfigTargetFilter(ambientTargets);
 						for (const row of filtered) {
 							if (visibleTargets.length >= fetchLimit) return;
 							visibleTargets.push(row);
@@ -5020,6 +5303,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 						if (batch.length < chunk) continue;
 						await drain();
 						if (visibleTargets.length >= fetchLimit) break;
+						if (probeScanLimit !== void 0 && ambientSeen >= probeScanLimit) break;
 					}
 					if (visibleTargets.length < fetchLimit) await drain();
 					return visibleTargets;