kitcn 0.17.5 → 0.19.0

package/dist/orm/index.js

@@ -1,6 +1,6 @@
 import { A as vectorIndex, B as ConvexColumnBuilder, C as RlsPolicy, D as rankIndex, E as index, F as arrayOf, I as custom, L as json, M as createSystemFields, N as integer, O as searchIndex, P as id, R as objectOf, S as TablePolymorphic, T as aggregateIndex, V as entityKind, _ as OrmSchemaRelations, a as deletion, b as TableDeleteConfig, c as Columns, d as OrmSchemaDefinition, f as OrmSchemaExtensionRelations, g as OrmSchemaOptions, h as OrmSchemaExtensions, i as convexTable, j as text, k as uniqueIndex, l as EnableRLS, m as OrmSchemaExtensionTriggers, o as discriminator, p as OrmSchemaExtensionTables, s as Brand, t as DirectAggregate, u as OrmContext, v as OrmSchemaTriggers, w as rlsPolicy, x as TableName, y as RlsPolicies, z as unionOf } from "../runtime-DmVSOe24.js";
 import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-C7LelqTN.js";
-import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-C90vNlc9.js";
+import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-BzihIpnM.js";
 import { compareValues, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
 
@@ -290,6 +290,19 @@ function check(name, expression) {
 	return new ConvexCheckBuilder(name, expression);
 }
 
+//#endregion
+//#region src/orm/timestamp-mode.ts
+const PUBLIC_CREATED_AT_FIELD = "createdAt";
+const INTERNAL_CREATION_TIME_FIELD = "_creationTime";
+const CREATED_AT_MIGRATION_MESSAGE = "`_creationTime` is no longer public. Use `createdAt` instead.";
+const hasUserCreatedAtColumn = (table) => {
+	if (!table || typeof table !== "object") return false;
+	const columns = table[Columns];
+	if (!columns || typeof columns !== "object") return false;
+	return Object.hasOwn(columns, PUBLIC_CREATED_AT_FIELD);
+};
+const usesSystemCreatedAtAlias = (_table) => true;
+
 //#endregion
 //#region src/orm/index-utils.ts
 function getIndexes(table) {
@@ -319,37 +332,53 @@ function findVectorIndexByName(table, indexName) {
 	return getVectorIndexes(table).find((index) => index.name === indexName) ?? null;
 }
 function findIndexForColumns(indexes, columns) {
-	for (const index of indexes) {
-		if (index.fields.length < columns.length) continue;
-		let matches = true;
-		for (let i = 0; i < columns.length; i++) if (index.fields[i] !== columns[i]) {
-			matches = false;
-			break;
-		}
-		if (matches) return index.name;
-	}
+	for (const index of indexes) if (hasColumnPrefix(index, columns)) return index.name;
 	return null;
 }
-function findRelationIndex(table, columns, relationName, targetTableName, strict = true, allowFullScan = false) {
-	const index = findIndexForColumns(getIndexes(table), columns);
+const hasColumnPrefix = (index, columns) => {
+	if (index.fields.length < columns.length) return false;
+	for (let i = 0; i < columns.length; i += 1) if (index.fields[i] !== columns[i]) return false;
+	return true;
+};
+/**
+* Answers "does scanning this index already produce the requested order?".
+*
+* Convex walks an index in full key order, so once a leading run of fields is
+* pinned to a single value by `eq`, the remainder of the scan is already sorted
+* by the next index field — and by `_creationTime` once every declared field is
+* pinned, because Convex appends it as the implicit trailing key. When that
+* field is the one the caller asked to sort by, `.order(dir).take(n)` returns
+* the exact page and nothing has to be collected and sorted afterwards.
+*
+* This is the single owner of that decision. The top-level query planner and
+* the relation loader both call it, so a bound one of them can push into the
+* index can never be one the other silently drops.
+*
+* Returns the direction to hand to `.order()`, or null when the sort must run
+* after the fetch.
+*/
+function resolveIndexOrderPushdown(params) {
+	const { indexFields, pinnedEqCount, orderSpecs } = params;
+	if (!indexFields || orderSpecs.length !== 1) return null;
+	const primary = orderSpecs[0];
+	const eqCount = Math.min(Math.max(pinnedEqCount, 0), indexFields.length);
+	for (let i = 0; i < eqCount; i += 1) if (indexFields[i] === primary.field) return primary.direction;
+	const nativeField = eqCount >= indexFields.length ? INTERNAL_CREATION_TIME_FIELD : indexFields[eqCount];
+	return primary.field === nativeField ? primary.direction : null;
+}
+function findRelationIndex(table, columns, relationName, targetTableName, strict = true, allowFullScan = false, orderSpecs = []) {
+	const indexes = getIndexes(table);
+	const fallbackIndex = findIndexForColumns(indexes, columns);
+	const index = (orderSpecs.length === 0 ? void 0 : indexes.find((candidate) => hasColumnPrefix(candidate, columns) && resolveIndexOrderPushdown({
+		indexFields: candidate.fields,
+		pinnedEqCount: columns.length,
+		orderSpecs
+	}) !== null))?.name ?? fallbackIndex;
 	if (!index && !allowFullScan) throw new Error(`Relation ${relationName} requires index on '${targetTableName}(${columns.join(", ")})'. Set allowFullScan: true to override.`);
 	if (!index && strict) console.warn(`Relation ${relationName} running without index (allowFullScan: true).`);
 	return index;
 }
 
-//#endregion
-//#region src/orm/timestamp-mode.ts
-const PUBLIC_CREATED_AT_FIELD = "createdAt";
-const INTERNAL_CREATION_TIME_FIELD = "_creationTime";
-const CREATED_AT_MIGRATION_MESSAGE = "`_creationTime` is no longer public. Use `createdAt` instead.";
-const hasUserCreatedAtColumn = (table) => {
-	if (!table || typeof table !== "object") return false;
-	const columns = table[Columns];
-	if (!columns || typeof columns !== "object") return false;
-	return Object.hasOwn(columns, PUBLIC_CREATED_AT_FIELD);
-};
-const usesSystemCreatedAtAlias = (_table) => true;
-
 //#endregion
 //#region src/orm/write-fanout.ts
 /**
@@ -3897,7 +3926,24 @@ async function filterSelectRows(options) {
 
 //#endregion
 //#region src/orm/where-clause-compiler.ts
+/**
+* Enough to clear the 25-point gap between an exact match and a prefix match,
+* so an index that supplies the order outranks a narrower one that does not.
+*/
+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.
+*/
+const MAX_PROMOTED_PROBES = 64;
 var WhereClauseCompiler = class {
+	/**
+	* Requested sort fields for the compile in flight. Index choice has to see
+	* them: an index whose next key after the pinned prefix is the sort field
+	* lets Convex serve the order from the scan, which no narrower index can do.
+	*/
+	orderFields = [];
 	constructor(_tableName, availableIndexes) {
 		this.availableIndexes = availableIndexes;
 	}
@@ -3905,9 +3951,11 @@ var WhereClauseCompiler = class {
 	* Compile a filter expression to Convex query structure
 	*
 	* @param expression - Filter expression tree
+	* @param options.orderFields - Resolved orderBy fields, most significant first
 	* @returns Compilation result with index and filters
 	*/
-	compile(expression) {
+	compile(expression, options) {
+		this.orderFields = options?.orderFields ?? [];
 		if (!expression) return {
 			strategy: "none",
 			selectedIndex: null,
@@ -3919,6 +3967,10 @@ var WhereClauseCompiler = class {
 		if (specialCase) return specialCase;
 		const referencedFields = this.extractFieldReferences(expression);
 		const selectedIndex = this.selectIndex(referencedFields);
+		if (!selectedIndex) {
+			const promoted = this.tryCompileAndInArray(expression);
+			if (promoted) return promoted;
+		}
 		const { indexFilters, postFilters } = this.splitFilters(expression, selectedIndex);
 		return {
 			strategy: this.resolveStrategy(selectedIndex, indexFilters),
@@ -3937,6 +3989,39 @@ var WhereClauseCompiler = class {
 		if (expression.type === "logical") return this.tryCompileOrSpecialCase(expression);
 		return null;
 	}
+	/**
+	* `where: { status: { in: [...] }, name: { contains: 'x' } }` compiles to an
+	* AND, and `extractFieldReferences` treats `inArray` as unindexable, so index
+	* selection sees nothing and the plan degrades to a full table scan — even
+	* though the very same `in` compiles to an index union on its own.
+	*
+	* Only fires when no index was selected at all, so a working `eq`-anchored
+	* plan is never traded for a probe fan-out. Every other term of the AND stays
+	* in `postFilters`, which the executor enforces per probe and again in
+	* JavaScript.
+	*/
+	tryCompileAndInArray(expression) {
+		if (expression.type !== "logical" || expression.operator !== "and") return null;
+		const terms = [];
+		const flatten = (expr) => {
+			if (expr.type === "logical" && expr.operator === "and") {
+				for (const operand of expr.operands) flatten(operand);
+				return;
+			}
+			terms.push(expr);
+		};
+		flatten(expression);
+		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;
+			return {
+				...probePlan,
+				postFilters: [expression]
+			};
+		}
+		return null;
+	}
 	resolveStrategy(selectedIndex, indexFilters) {
 		if (!selectedIndex || indexFilters.length === 0) return "none";
 		return indexFilters.some((filter) => filter.type === "binary" && (filter.operator === "gt" || filter.operator === "gte" || filter.operator === "lt" || filter.operator === "lte")) ? "rangeIndex" : "singleIndex";
@@ -4118,7 +4203,13 @@ var WhereClauseCompiler = class {
 		};
 	}
 	findLeadingIndex(fieldName) {
-		return this.availableIndexes.filter((index) => index.indexFields[0] === fieldName).sort((a, b) => a.indexFields.length - b.indexFields.length)[0] ?? null;
+		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;
+		}
+		return candidates[0] ?? null;
 	}
 	getLikePrefix(pattern) {
 		if (!pattern || pattern.startsWith("%") || pattern.includes("_")) return null;
@@ -4276,7 +4367,7 @@ var WhereClauseCompiler = class {
 		const prefixCount = this.getPrefixMatchCount(indexFields, referencedFields);
 		if (prefixCount > 0) return {
 			index,
-			score: 75 + prefixCount,
+			score: 75 + prefixCount + this.indexOrderBonus(indexFields, prefixCount),
 			matchType: "prefix",
 			matchedFields: indexFields.slice(0, prefixCount)
 		};
@@ -4290,6 +4381,15 @@ var WhereClauseCompiler = class {
 		return null;
 	}
 	/**
+	* 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 }`.
+	*/
+	indexOrderBonus(indexFields, pinnedLength) {
+		if (this.orderFields.length === 0 || pinnedLength >= indexFields.length) return 0;
+		return indexFields[pinnedLength] === this.orderFields[0] ? INDEX_ORDER_BONUS : 0;
+	}
+	/**
 	* Check if referenced fields exactly match index fields in order
 	*/
 	isExactMatch(indexFields, referencedFields) {
@@ -4390,7 +4490,7 @@ var WhereClauseCompiler = class {
 			takeRange(fieldName);
 			break;
 		}
-		for (const binary of binaryFilters) if (!consumed.has(binary) && !postFilters.includes(binary)) postFilters.push(binary);
+		for (const filters of binariesByField.values()) for (const binary of filters) if (!consumed.has(binary)) postFilters.push(binary);
 		return {
 			indexFilters,
 			postFilters
@@ -4419,6 +4519,13 @@ const POST_FETCH_ONLY_OPERATORS = new Set([
 	"arrayOverlaps"
 ]);
 const DEFAULT_RELATION_FAN_OUT_MAX_KEYS = 1e3;
+/**
+* How many child rows the bounded relation stream filters at a time. Batching
+* lets the sub-relation loader de-duplicate foreign keys and run its reads
+* concurrently; the cost is reading at most `chunk - 1` rows past the one that
+* satisfies the limit.
+*/
+const RELATION_FILTER_STREAM_CHUNK = 32;
 const DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS = 4096;
 const DEFAULT_AGGREGATE_WORK_BUDGET = 16384;
 const PUBLIC_ID_FIELD = "id";
@@ -4429,6 +4536,11 @@ const RELATION_COUNT_ERROR = {
 	FILTER_UNSUPPORTED: "RELATION_COUNT_FILTER_UNSUPPORTED"
 };
 /**
+* Physical-table-name lookup, keyed on schema identity. The schema is a
+* module-level immutable, so the index outlives any single request.
+*/
+const tableConfigByDbNameCache = /* @__PURE__ */ new WeakMap();
+/**
 * Replays an already-read run of `[doc | null, indexKey]` entries.
 *
 * `narrow()` filters the buffer instead of re-issuing the read, so a stream
@@ -4473,6 +4585,42 @@ var BufferedQueryStream = class BufferedQueryStream extends QueryStream {
 		return this.equalityIndexFilter;
 	}
 };
+const ID_LIST_POSITION_FIELD = "__kitcn_id_list_position";
+/**
+* Reads an `id` / `id in [...]` where one document at a time, in the order the
+* ids were given.
+*
+* The index key is the position in the de-duplicated id list, so a cursor names
+* a position and `narrow` drops entries without reading them. A page reads only
+* the listed positions it visits, not every id in the list on every page.
+*/
+var LazyIdListQueryStream = class LazyIdListQueryStream extends QueryStream {
+	constructor(readId, entries, order) {
+		super();
+		this.readId = readId;
+		this.entries = entries;
+		this.order = order;
+	}
+	iterWithKeys() {
+		const entries = this.entries;
+		const readId = this.readId;
+		return { async *[Symbol.asyncIterator]() {
+			for (const [position, id] of entries) yield [await readId(id), [position]];
+		} };
+	}
+	narrow(indexBounds) {
+		return new LazyIdListQueryStream(this.readId, this.entries.filter(([position]) => indexKeyWithinBounds([position], indexBounds)), this.order);
+	}
+	getOrder() {
+		return this.order;
+	}
+	getIndexFields() {
+		return [ID_LIST_POSITION_FIELD];
+	}
+	getEqualityIndexFilter() {
+		return [];
+	}
+};
 const PIPELINE_LIMIT_ORDINAL_FIELD = "__kitcn_limit_ordinal";
 /** Cap a stream at its first `limit` matching documents without eager reads. */
 var LimitedMatchesQueryStream = class LimitedMatchesQueryStream extends QueryStream {
@@ -4565,6 +4713,33 @@ var GelRankQuery = class {
 		return await readRankRandom(this.db, plan);
 	}
 };
+const CONFIGURED_INDEX_RANGE_OPERATORS = new Set([
+	"eq",
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+]);
+const observeConfiguredIndexRange = (builder, operations) => new Proxy(builder, { get(target, property) {
+	const value = Reflect.get(target, property, target);
+	if (typeof property === "string" && CONFIGURED_INDEX_RANGE_OPERATORS.has(property) && typeof value === "function") return (field, ...args) => {
+		operations.push({
+			field,
+			operator: property
+		});
+		return observeConfiguredIndexRange(Reflect.apply(value, target, [field, ...args]), operations);
+	};
+	return typeof value === "function" ? value.bind(target) : value;
+} });
+const countConfiguredIndexEqPrefix = (indexFields, operations) => {
+	if (!indexFields) return 0;
+	let count = 0;
+	for (const operation of operations) {
+		if (operation.operator !== "eq" || operation.field !== indexFields[count]) break;
+		count += 1;
+	}
+	return count;
+};
 /**
 * Relational query builder with promise-based execution
 *
@@ -4754,8 +4929,19 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		return 0;
 	}
+	/**
+	* Physical table name to relational config. Called once per row on the
+	* relation-count path, so the linear schema scan is indexed once per schema
+	* object rather than repeated. The schema is fixed for the process lifetime.
+	*/
 	_getTableConfigByDbName(dbName) {
-		return Object.values(this.schema).find((table) => table.name === dbName);
+		let byDbName = tableConfigByDbNameCache.get(this.schema);
+		if (!byDbName) {
+			byDbName = /* @__PURE__ */ new Map();
+			for (const table of Object.values(this.schema)) if (table?.name && !byDbName.has(table.name)) byDbName.set(table.name, table);
+			tableConfigByDbNameCache.set(this.schema, byDbName);
+		}
+		return byDbName.get(dbName);
 	}
 	_matchLike(value, pattern, caseInsensitive) {
 		return matchLikePattern(value, pattern, caseInsensitive);
@@ -5637,9 +5823,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* The where-clause compiler is built from declared indexes only, and `_id` is
 	* never one of them, so an `id` filter can never be index-selected: it lands
 	* in the post-filters and the stream walks the creation-time index until it
-	* happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-	* are fetched directly and replayed as a creation-time-ordered stream — the
-	* order the scan would have produced, so stage order and cursors are the same.
+	* happens on the row. `db.get()` reads exactly the rows asked for.
+	*
+	* Rows come back in the order the ids were given, one read at a time. Missing
+	* or policy-filtered ids still cost a read, but a page does not reread the
+	* complete list. An `orderBy` on creation time is the exception: an id carries
+	* no creation time, so every id must be read before the first row is placed.
 	*
 	* Returns null when something else already owns the read: a pinned index, an
 	* index the compiler did select, a `where(predicate)`, or an `orderBy` that
@@ -5651,13 +5840,26 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const primaryOrder = queryConfig.order?.[0];
 		if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) return null;
 		const ids = idLookup.kind === "in" ? Array.from(new Map(idLookup.ids.map((id) => [String(id), id])).values()) : [idLookup.id];
-		const rows = (await this._mapWithConcurrency(ids, async (id) => {
-			return this._getById(this.tableConfig.name, id);
-		})).filter((row) => !!row);
+		const readId = (id) => this._getById(this.tableConfig.name, id);
+		if (!primaryOrder) {
+			const entries = ids.map((id, position) => [position, id]);
+			if (order === "desc") entries.reverse();
+			return new LazyIdListQueryStream(readId, entries, order);
+		}
+		const rows = (await this._mapWithConcurrency(ids, readId)).filter((row) => !!row);
 		rows.sort((a, b) => compareValues(a[INTERNAL_CREATION_TIME_FIELD], b[INTERNAL_CREATION_TIME_FIELD]) || compareValues(a[INTERNAL_ID_FIELD], b[INTERNAL_ID_FIELD]));
 		if (order === "desc") rows.reverse();
 		return new BufferedQueryStream(rows.map((row) => [row, [row[INTERNAL_CREATION_TIME_FIELD], row[INTERNAL_ID_FIELD]]]), order, [INTERNAL_CREATION_TIME_FIELD, INTERNAL_ID_FIELD], []);
 	}
+	/**
+	* The declared index a stream read can walk to emit `field` in order.
+	*
+	* A stream orders by the index it scans, so only an index that leads with
+	* the field produces that order.
+	*/
+	_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);
@@ -5669,8 +5871,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			return indexQuery;
 		});
 		else if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-		else if (primaryOrder && primaryOrder.field !== "_creationTime") {
-			const orderIndex = getIndexes(this.tableConfig.table).find((idx) => idx.fields[0] === primaryOrder.field);
+		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);
@@ -6828,7 +7030,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					streamQuery = mergedStream(streams, pipeline.interleaveBy.map((field) => this._normalizePublicFieldName(field)));
 				}
 			} else {
-				if (isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in") throw new Error("An id IN pipeline cannot use maxScan because creation-order replay requires reading the complete ID list.");
+				const orderedIdList = isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in" ? queryConfig.order?.[0] : void 0;
+				if (orderedIdList) {
+					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({
 					configuredIndex,
 					idLookup,
@@ -6959,14 +7165,28 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				return indexQuery;
 			});
 			if (primaryOrder) {
-				const orderField = primaryOrder.field;
-				if (queryConfig.index.filters.map((f) => f.operands[0].fieldName).includes(orderField) || orderField === "_creationTime") query = query.order(primaryOrder.direction);
+				const pushdownDirection = resolveIndexOrderPushdown({
+					indexFields: indexConfig.fields,
+					pinnedEqCount: this._indexEqPrefixCount(queryConfig),
+					orderSpecs: [primaryOrder]
+				});
+				if (pushdownDirection) query = query.order(pushdownDirection);
 				else needsPostFetchSortForPrimary = true;
 			}
 		} else if (configuredIndex?.name) {
-			query = query.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-			if (primaryOrder) if (primaryOrder.field === "_creationTime") query = query.order(primaryOrder.direction);
-			else needsPostFetchSortForPrimary = true;
+			const configuredIndexFields = getIndexes(this.tableConfig.table).find((idx) => idx.name === configuredIndex.name)?.fields;
+			const rangeOperations = [];
+			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);
+				else needsPostFetchSortForPrimary = true;
+			}
 		} else if (queryConfig.order && primaryOrder) {
 			const orderField = primaryOrder.field;
 			if (orderField === "_creationTime") query = query.order(primaryOrder.direction);
@@ -7033,32 +7253,42 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			return this._returnSelectedRows(selectedRows);
 		}
 		if (queryConfig.strategy === "multiProbe" && queryConfig.index && !isCursorPaginated) {
+			const probeOffset = config.offset ?? 0;
+			if (typeof probeOffset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
+			const probeLimit = this._resolveNonPaginatedLimit(config);
+			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 probeRows = await Promise.all(queryConfig.probeFilters.map(async (probeFilters) => {
 				let probeQuery = this.db.query(queryConfig.table).withIndex(queryConfig.index.name, (q) => {
 					let indexQuery = q;
 					for (const filter of probeFilters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
 					return indexQuery;
 				});
-				if (queryConfig.postFilters.length > 0) probeQuery = probeQuery.filter((q) => {
+				if (probeBound !== void 0 && probeOrderDirection) probeQuery = probeQuery.order(probeOrderDirection);
+				if (convexProbeFilters.length > 0) probeQuery = probeQuery.filter((q) => {
 					let result = null;
-					for (const filter of queryConfig.postFilters) {
+					for (const filter of convexProbeFilters) {
 						const expr = this._toConvexExpression(filter)(q);
 						result = result ? q.and(result, expr) : expr;
 					}
 					return result ?? q;
 				});
-				return await probeQuery.collect();
+				return probeBound === void 0 ? await probeQuery.collect() : await probeQuery.take(probeBound);
 			}));
 			let rows = Array.from(new Map(probeRows.flat().map((row) => [String(row._id), row])).values());
 			if (queryConfig.postFilters.length > 0) rows = rows.filter((row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
 			rows = await this._applyRlsSelectFilter(rows, this.tableConfig);
 			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
 			if (postFetchOrders.length > 0) rows = rows.sort((a, b) => this._compareByOrderSpecs(a, b, postFetchOrders));
-			const offset = config.offset ?? 0;
-			if (typeof offset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
-			const limit = this._resolveNonPaginatedLimit(config);
-			if (offset > 0) rows = rows.slice(offset);
-			if (limit !== void 0) rows = rows.slice(0, limit);
+			if (probeOffset > 0) rows = rows.slice(probeOffset);
+			if (probeLimit !== void 0) rows = rows.slice(0, probeLimit);
 			const selectedRows = await this._finalizeRows(rows);
 			return this._returnSelectedRows(selectedRows);
 		}
@@ -7195,6 +7425,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		const convexPostFilters = queryConfig.postFilters.filter((filter) => this._isConvexEnforceableFilter(filter));
 		const hasResidualPostFilter = convexPostFilters.length !== queryConfig.postFilters.length;
+		const hasPostFetchMembership = this._hasSearchDisallowedRelationFilter(whereFilter, this.tableConfig) || this.rls?.mode !== "skip" && isRlsEnabled(this.tableConfig.table);
 		if (convexPostFilters.length > 0) query = query.filter((q) => {
 			let result = null;
 			for (const filter of convexPostFilters) {
@@ -7207,7 +7438,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (typeof offset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
 		const limit = this._resolveNonPaginatedLimit(config);
 		const paginateAfterPostFetchSort = usePostFetchSort && postFetchOrders.length > 0;
-		const sizeAfterPostFilter = hasResidualPostFilter && !paginateAfterPostFetchSort;
+		const sizeAfterPostFilter = (hasResidualPostFilter || hasPostFetchMembership) && !paginateAfterPostFetchSort;
 		const residualLimitStream = sizeAfterPostFilter && limit !== void 0 ? this._buildResidualFilterStream({
 			queryConfig,
 			configuredIndex,
@@ -7218,7 +7449,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}) : null;
 		let rows;
 		if (residualLimitStream) rows = await residualLimitStream.take(offset > 0 ? offset + limit : limit);
-		else if (limit === void 0 || paginateAfterPostFetchSort || hasResidualPostFilter) rows = await query.collect();
+		else if (limit === void 0 || paginateAfterPostFetchSort || hasResidualPostFilter || hasPostFetchMembership) rows = await query.collect();
 		else rows = await query.take(offset > 0 ? offset + limit : limit);
 		if (!(paginateAfterPostFetchSort || sizeAfterPostFilter) && offset > 0) rows = rows.slice(offset);
 		if (queryConfig.postFilters.length > 0) rows = rows.filter((row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
@@ -7249,9 +7480,17 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			indexFields: index.fields
 		}));
 		const compiler = new WhereClauseCompiler(this.tableConfig.table.tableName, tableIndexes);
+		let orderSpecs = [];
+		if (config.orderBy) {
+			const orderByValue = typeof config.orderBy === "function" ? config.orderBy(this.tableConfig.table, {
+				asc,
+				desc
+			}) : config.orderBy;
+			orderSpecs = this._orderBySpecs(orderByValue);
+		}
 		let whereExpression = whereExpressionOverride;
 		if (!whereExpression && config.where && typeof config.where !== "function") whereExpression = this._buildFilterExpression(config.where, this.tableConfig);
-		const planned = compiler.compile(whereExpression);
+		const planned = compiler.compile(whereExpression, { orderFields: orderSpecs.map((spec) => spec.field) });
 		const plannedUsesIndex = !!planned.selectedIndex && (planned.indexFilters.length > 0 || planned.probeFilters.length > 0);
 		const compiled = !configuredIndex?.name || !plannedUsesIndex || planned.selectedIndex?.indexName === configuredIndex.name && !configuredIndex.range ? planned : {
 			strategy: "none",
@@ -7268,16 +7507,10 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		};
 		if (compiled.selectedIndex && (compiled.indexFilters.length > 0 || compiled.probeFilters.length > 0)) result.index = {
 			name: compiled.selectedIndex.indexName,
+			fields: compiled.selectedIndex.indexFields,
 			filters: compiled.indexFilters
 		};
-		if (config.orderBy) {
-			const orderByValue = typeof config.orderBy === "function" ? config.orderBy(this.tableConfig.table, {
-				asc,
-				desc
-			}) : config.orderBy;
-			const orderSpecs = this._orderBySpecs(orderByValue);
-			if (orderSpecs.length > 0) result.order = orderSpecs;
-		}
+		if (orderSpecs.length > 0) result.order = orderSpecs;
 		return result;
 	}
 	_buildRelationKey(row, fields) {
@@ -7286,6 +7519,30 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (values.some((value) => value === null || value === void 0)) return null;
 		return JSON.stringify(values);
 	}
+	/**
+	* How many leading fields of the scanned index are pinned to a single value.
+	*
+	* `splitFilters` emits index filters in index-key order — a run of `eq`, then
+	* at most one range on the first unpinned field — so the leading `eq` run is
+	* the prefix Convex holds constant. A multi-probe plan carries no index
+	* filters; each probe supplies its own bound instead, and the union is only
+	* as pinned as its least pinned probe.
+	*/
+	_indexEqPrefixCount(queryConfig) {
+		const countEqPrefix = (filters) => {
+			let count = 0;
+			for (const filter of filters) {
+				if (filter.type !== "binary" || filter.operator !== "eq") break;
+				count += 1;
+			}
+			return count;
+		};
+		if (queryConfig.index && queryConfig.index.filters.length > 0) return countEqPrefix(queryConfig.index.filters);
+		if (queryConfig.probeFilters.length === 0) return 0;
+		let pinned = Number.POSITIVE_INFINITY;
+		for (const probe of queryConfig.probeFilters) pinned = Math.min(pinned, countEqPrefix(probe));
+		return Number.isFinite(pinned) ? pinned : 0;
+	}
 	_buildIndexPredicate(q, fields, values) {
 		let builder = q.eq(fields[0], values[0]);
 		for (let i = 1; i < fields.length; i += 1) builder = builder.eq(fields[i], values[i]);
@@ -7494,16 +7751,6 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (typeof record.where === "function") throw this._createRelationCountError(RELATION_COUNT_ERROR.FILTER_UNSUPPORTED, `with._count.${relationName}.where callback is unsupported in v1`);
 		return record.where;
 	}
-	_normalizeRelationCountCacheValue(value) {
-		if (Array.isArray(value)) return value.map((entry) => this._normalizeRelationCountCacheValue(entry));
-		if (value && typeof value === "object") {
-			const normalized = {};
-			const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
-			for (const [key, entry] of entries) normalized[key] = this._normalizeRelationCountCacheValue(entry);
-			return normalized;
-		}
-		return value;
-	}
 	_getRelationCountParentKey(row, edge) {
 		const sourceFields = edge.sourceFields.length > 0 ? edge.sourceFields : [edge.fieldName];
 		const values = [];
@@ -7514,26 +7761,20 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		return JSON.stringify(values);
 	}
-	_buildRelationCountExecutionKey(relationName, where, parentKey) {
-		return JSON.stringify({
-			relationName,
-			where: this._normalizeRelationCountCacheValue(where ?? null),
-			parentKey
-		});
-	}
-	async _readIndexedRelationCount(tableConfig, where, relationPath) {
+	async _readIndexedRelationCount(tableConfig, where, relationPath, bucketCache) {
 		ensureCountAllowedForRls(tableConfig, this.rls?.mode);
 		try {
 			const plan = compileCountQueryPlan(tableConfig, where);
 			if (isIndexCountZero(plan)) return 0;
 			await this._ensureCountIndexReadyOnce(plan.tableName, plan.indexName);
-			return await readCountFromBuckets(this.db, plan);
+			return await readCountFromBuckets(this.db, plan, bucketCache);
 		} catch (error) {
 			throw this._remapRelationCountError(error, relationPath);
 		}
 	}
-	async _countRelationForRow(row, relationName, edge, where, tableConfig) {
+	async _countRelationForRow(row, relationName, edge, where, tableConfig, caches) {
 		const relationPath = `${tableConfig.name}.${relationName}`;
+		const bucketCache = caches?.buckets;
 		if (edge.through) {
 			const throughTableConfig = this._getTableConfigByDbName(edge.through.table);
 			if (!throughTableConfig) throw this._createRelationCountError(RELATION_COUNT_ERROR.FILTER_UNSUPPORTED, `${relationPath} through table '${edge.through.table}' is not registered`);
@@ -7548,7 +7789,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				throughWhere[throughField] = value;
 				sourceValues.push(value);
 			}
-			if (this._isEmptyWhere(where) || where === void 0) return await this._readIndexedRelationCount(throughTableConfig, throughWhere, relationPath);
+			if (this._isEmptyWhere(where) || where === void 0) return await this._readIndexedRelationCount(throughTableConfig, throughWhere, relationPath, bucketCache);
 			const targetTableConfig = this._getTableConfigByDbName(edge.targetTable);
 			if (!targetTableConfig) throw this._createRelationCountError(RELATION_COUNT_ERROR.FILTER_UNSUPPORTED, `${relationPath} target table '${edge.targetTable}' is not registered`);
 			ensureCountAllowedForRls(targetTableConfig, this.rls?.mode);
@@ -7583,13 +7824,28 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (targetKeyCounts.size === 0) return 0;
 			const useGetById = targetFields.length === 1 && targetFields[0] === "_id";
 			const targetIndexName = useGetById ? null : findRelationIndex(targetTableConfig.table, targetFields, relationPath, edge.targetTable, strict, this.allowFullScan);
-			const targetEntries = Array.from(targetKeyCounts.values());
-			return (await this._mapWithConcurrency(targetEntries, async ({ values, occurrences }) => {
+			const resolveTargetMatch = async (values) => {
 				let target = null;
 				if (useGetById) target = await this._getById(edge.targetTable, values[0]);
 				else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, targetIndexName).first();
-				if (!target) return 0;
-				return this._evaluateTableFilter(target, targetTableConfig, whereRecord) ? occurrences : 0;
+				if (!target) return false;
+				return this._evaluateTableFilter(target, targetTableConfig, whereRecord);
+			};
+			const targetMatchCache = caches?.throughTargetMatches;
+			const targetEntries = Array.from(targetKeyCounts.entries());
+			return (await this._mapWithConcurrency(targetEntries, async ([targetKey, { values, occurrences }]) => {
+				if (!targetMatchCache) return await resolveTargetMatch(values) ? occurrences : 0;
+				let pending = targetMatchCache.get(targetKey);
+				if (!pending) {
+					pending = resolveTargetMatch(values);
+					targetMatchCache.set(targetKey, pending);
+				}
+				try {
+					return await pending ? occurrences : 0;
+				} catch (error) {
+					targetMatchCache.delete(targetKey);
+					throw error;
+				}
 			})).reduce((sum, value) => sum + value, 0);
 		}
 		const targetTableConfig = this._getTableConfigByDbName(edge.targetTable);
@@ -7605,7 +7861,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			relationWhere[targetField] = value;
 		}
 		const mergedWhere = this._isEmptyWhere(where) || where === void 0 ? relationWhere : { AND: [relationWhere, where] };
-		return await this._readIndexedRelationCount(targetTableConfig, mergedWhere, relationPath);
+		return await this._readIndexedRelationCount(targetTableConfig, mergedWhere, relationPath, bucketCache);
 	}
 	async _loadRelationCounts(rows, relationCountConfig, targetTableEdges, tableConfig) {
 		if (!relationCountConfig || typeof relationCountConfig !== "object" || Array.isArray(relationCountConfig)) throw this._createRelationCountError(RELATION_COUNT_ERROR.FILTER_UNSUPPORTED, `with._count on '${tableConfig.name}' requires an object of relation names`);
@@ -7617,18 +7873,21 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (!edge) throw this._createRelationCountError(RELATION_COUNT_ERROR.FILTER_UNSUPPORTED, `with._count.${relationName} is not a relation on '${tableConfig.name}'`);
 			const where = this._coerceRelationCountWhere(relationName, relationSelection);
 			const relationCountExecutionCache = /* @__PURE__ */ new Map();
+			const caches = {
+				buckets: /* @__PURE__ */ new Map(),
+				throughTargetMatches: /* @__PURE__ */ new Map()
+			};
 			const counts = await this._mapWithConcurrency(rows, async (row) => {
 				const parentKey = this._getRelationCountParentKey(row, edge);
 				if (parentKey === null) return 0;
-				const executionKey = this._buildRelationCountExecutionKey(relationName, where, parentKey);
-				const existing = relationCountExecutionCache.get(executionKey);
+				const existing = relationCountExecutionCache.get(parentKey);
 				if (existing) return await existing;
-				const pending = this._countRelationForRow(row, relationName, edge, where, tableConfig);
-				relationCountExecutionCache.set(executionKey, pending);
+				const pending = this._countRelationForRow(row, relationName, edge, where, tableConfig, caches);
+				relationCountExecutionCache.set(parentKey, pending);
 				try {
 					return await pending;
 				} catch (error) {
-					relationCountExecutionCache.delete(executionKey);
+					relationCountExecutionCache.delete(parentKey);
 					throw error;
 				}
 			});
@@ -7708,6 +7967,108 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 	}
 	/**
+	* Junction links per parent, stopped once each parent holds `fetchLimit`
+	* links whose target actually reaches the page.
+	*
+	* A link only contributes if its target exists and survives target RLS and
+	* the relation `where` — all of which run after the junction read. Sizing the
+	* read on links alone therefore under-fills: three dangling or filtered links
+	* first and `{ limit: 3 }` returns nothing. So the read is refilled in rounds,
+	* each round resolving only the targets it newly needs and asking again for
+	* whatever the survivors did not cover.
+	*
+	* Rounds are the unit rather than single links because both the target fetch
+	* and the relation `where` de-duplicate and batch their own reads across the
+	* parents in the round.
+	*/
+	async _readBoundedThroughLinks(params) {
+		const { applyTargetFilters, edge, enforceTargetKeyCap, entries, fetchLimit, fetchTargets, targetFields, throughIndexName, throughTableConfig } = params;
+		const throughTargetFields = edge.through.targetFields;
+		const cursors = entries.map(([key, values]) => ({
+			buffered: [],
+			exhausted: false,
+			iterator: this._queryByFields(this.db.query(edge.through.table), edge.through.sourceFields, values, throughIndexName)[Symbol.asyncIterator](),
+			key,
+			links: []
+		}));
+		const bufferVisibleLinks = async (cursor, count) => {
+			let batch = [];
+			const drain = async () => {
+				const visible = await this._applyRlsSelectFilter(batch, throughTableConfig);
+				batch = [];
+				cursor.buffered.push(...visible);
+			};
+			while (!cursor.exhausted && cursor.buffered.length + batch.length < count) {
+				const next = await cursor.iterator.next();
+				if (next.done) {
+					cursor.exhausted = true;
+					break;
+				}
+				batch.push(next.value);
+				if (batch.length >= RELATION_FILTER_STREAM_CHUNK) await drain();
+			}
+			await drain();
+		};
+		/** Target key -> the surviving document, absent when it did not survive. */
+		const survivorByKey = /* @__PURE__ */ new Map();
+		const resolvedKeys = /* @__PURE__ */ new Set();
+		const survivors = [];
+		while (true) {
+			const active = cursors.filter((cursor) => cursor.links.length < fetchLimit && !(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;
+				await bufferVisibleLinks(cursor, need);
+				return cursor.buffered.splice(0, need);
+			});
+			const newKeys = /* @__PURE__ */ new Map();
+			for (const candidates of candidatesPerCursor) for (const link of candidates) {
+				const values = throughTargetFields.map((field) => link[field]);
+				if (values.some((value) => value === null || value === void 0)) continue;
+				const key = JSON.stringify(values);
+				if (resolvedKeys.has(key) || newKeys.has(key)) continue;
+				newKeys.set(key, values);
+			}
+			if (newKeys.size > 0) {
+				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));
+				for (const target of surviving) {
+					const key = this._buildRelationKey(target, targetFields);
+					if (!key || survivorByKey.has(key)) continue;
+					survivorByKey.set(key, target);
+					survivors.push(target);
+				}
+			}
+			for (let i = 0; i < active.length; i += 1) {
+				const cursor = active[i];
+				for (const link of candidatesPerCursor[i]) {
+					if (cursor.links.length >= fetchLimit) break;
+					const key = this._buildRelationKey(link, throughTargetFields);
+					if (!key || !survivorByKey.has(key)) continue;
+					cursor.links.push(link);
+				}
+			}
+		}
+		const linksBySourceKey = /* @__PURE__ */ new Map();
+		const usedKeys = /* @__PURE__ */ new Set();
+		for (const cursor of cursors) {
+			linksBySourceKey.set(cursor.key, cursor.links);
+			for (const link of cursor.links) {
+				const key = this._buildRelationKey(link, throughTargetFields);
+				if (key) usedKeys.add(key);
+			}
+		}
+		return {
+			linksBySourceKey,
+			targets: survivors.filter((target) => {
+				const key = this._buildRelationKey(target, targetFields);
+				return key !== null && usedKeys.has(key);
+			})
+		};
+	}
+	/**
 	* Load many() relation (one-to-many)
 	* Example: users.posts where posts.authorId → users.id
 	*
@@ -7781,65 +8142,108 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (!throughTableConfig) throw new Error(`Relation '${relationName}' through table '${edge.through.table}' not found.`);
 			const throughIndexName = findRelationIndex(throughTableConfig.table, edge.through.sourceFields, `${tableConfig.name}.${relationName}`, edge.through.table, strict, this.allowFullScan);
 			const entries = Array.from(sourceKeyMap.entries());
-			const throughRowsPerSource = await this._mapWithConcurrency(entries, async ([key, values]) => {
-				const query = this._queryByFields(this.db.query(edge.through.table), edge.through.sourceFields, values, throughIndexName);
-				return {
-					key,
-					rows: await this._applyRlsSelectFilter(await query.collect(), throughTableConfig)
-				};
-			});
-			throughBySourceKey = /* @__PURE__ */ new Map();
-			const targetKeyMap = /* @__PURE__ */ new Map();
-			for (const entry of throughRowsPerSource) {
-				throughBySourceKey.set(entry.key, entry.rows);
-				for (const row of entry.rows) {
-					const values = edge.through.targetFields.map((field) => row[field]);
-					if (values.some((value) => value === null || value === void 0)) continue;
-					const key = JSON.stringify(values);
-					if (!targetKeyMap.has(key)) targetKeyMap.set(key, values);
-				}
-			}
-			this._enforceRelationFanOutKeyCap({
+			const enforceTargetKeyCap = (keyCount) => this._enforceRelationFanOutKeyCap({
 				tableConfig,
 				relationName,
-				keyCount: targetKeyMap.size,
+				keyCount,
 				scope: "through-target"
 			});
-			if (targetKeyMap.size > 0) {
-				const useGetById = targetFields.length === 1 && targetFields[0] === "_id";
-				const targetIndexName = useGetById ? null : findRelationIndex(targetTableConfig.table, targetFields, `${tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan);
-				const targetEntries = Array.from(targetKeyMap.entries());
-				targets = (await this._mapWithConcurrency(targetEntries, async ([key, values]) => {
+			let targetLookup = null;
+			const fetchThroughTargets = async (keyEntries) => {
+				if (!targetLookup) {
+					const useGetById = targetFields.length === 1 && targetFields[0] === "_id";
+					targetLookup = {
+						useGetById,
+						indexName: useGetById ? null : findRelationIndex(targetTableConfig.table, targetFields, `${tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan)
+					};
+				}
+				const { useGetById, indexName } = targetLookup;
+				return await this._mapWithConcurrency(keyEntries, async ([key, values]) => {
 					let target = null;
 					if (useGetById) target = await this._getById(edge.targetTable, values[0]);
-					else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, targetIndexName).first();
+					else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName).first();
 					return {
 						key,
 						target
 					};
-				})).map((entry) => entry.target).filter((value) => !!value);
+				});
+			};
+			if (orderSpecs.length === 0 && effectivePerParentLimit !== void 0) {
+				const bounded = await this._readBoundedThroughLinks({
+					applyTargetFilters: applyPostFetchTargetFilters,
+					edge,
+					enforceTargetKeyCap,
+					entries,
+					fetchLimit: Math.max(perParentOffset ?? 0, 0) + effectivePerParentLimit,
+					fetchTargets: fetchThroughTargets,
+					targetFields,
+					throughIndexName,
+					throughTableConfig
+				});
+				throughBySourceKey = bounded.linksBySourceKey;
+				targets = bounded.targets;
+				targetFiltersApplied = true;
+			} else {
+				const throughRowsPerSource = await this._mapWithConcurrency(entries, async ([key, values]) => {
+					const query = this._queryByFields(this.db.query(edge.through.table), edge.through.sourceFields, values, throughIndexName);
+					return {
+						key,
+						rows: await this._applyRlsSelectFilter(await query.collect(), throughTableConfig)
+					};
+				});
+				throughBySourceKey = /* @__PURE__ */ new Map();
+				const targetKeyMap = /* @__PURE__ */ new Map();
+				for (const entry of throughRowsPerSource) {
+					throughBySourceKey.set(entry.key, entry.rows);
+					for (const row of entry.rows) {
+						const values = edge.through.targetFields.map((field) => row[field]);
+						if (values.some((value) => value === null || value === void 0)) continue;
+						const key = JSON.stringify(values);
+						if (!targetKeyMap.has(key)) targetKeyMap.set(key, values);
+					}
+				}
+				enforceTargetKeyCap(targetKeyMap.size);
+				if (targetKeyMap.size > 0) targets = (await fetchThroughTargets(Array.from(targetKeyMap.entries()))).map((entry) => entry.target).filter((value) => !!value);
 			}
 		} else {
-			const indexName = findRelationIndex(targetTableConfig.table, targetFields, `${tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan);
+			const indexName = findRelationIndex(targetTableConfig.table, targetFields, `${tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan, orderSpecs);
 			const entries = Array.from(sourceKeyMap.entries());
-			const streamPostFetchTargetFilters = orderSpecs.length === 0 && hasPostFetchTargetFilter && effectivePerParentLimit !== void 0;
+			const orderPushdownDirection = resolveIndexOrderPushdown({
+				indexFields: indexName ? getIndexes(targetTableConfig.table).find((idx) => idx.name === indexName)?.fields ?? null : null,
+				pinnedEqCount: targetFields.length,
+				orderSpecs
+			});
+			const orderServedByIndex = orderSpecs.length === 0 || orderPushdownDirection !== null;
+			const applyPushdownOrder = (query) => orderPushdownDirection ? query.order(orderPushdownDirection) : query;
+			const streamPostFetchTargetFilters = orderServedByIndex && hasPostFetchTargetFilter && effectivePerParentLimit !== void 0;
 			targetFiltersApplied = streamPostFetchTargetFilters;
 			targets = (await this._mapWithConcurrency(entries, async ([, values]) => {
 				const query = this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName);
-				if (orderSpecs.length === 0 && !hasPostFetchTargetFilter && effectivePerParentLimit !== void 0) {
+				if (orderServedByIndex && !hasPostFetchTargetFilter && effectivePerParentLimit !== void 0) {
 					const fetchLimit = (perParentOffset ?? 0) + (effectivePerParentLimit ?? 0);
-					return await query.take(fetchLimit);
+					return await applyPushdownOrder(query).take(fetchLimit);
 				}
 				if (streamPostFetchTargetFilters) {
 					const visibleTargets = [];
 					const fetchLimit = Math.max(perParentOffset ?? 0, 0) + (effectivePerParentLimit ?? 0);
-					for await (const target of query) {
-						const filtered = await applyPostFetchTargetFilters([target]);
-						if (filtered.length > 0) {
-							visibleTargets.push(filtered[0]);
-							if (visibleTargets.length >= fetchLimit) break;
+					let batch = [];
+					const drain = async () => {
+						if (batch.length === 0) return;
+						const filtered = await applyPostFetchTargetFilters(batch);
+						batch = [];
+						for (const row of filtered) {
+							if (visibleTargets.length >= fetchLimit) return;
+							visibleTargets.push(row);
 						}
+					};
+					for await (const target of applyPushdownOrder(query)) {
+						batch.push(target);
+						const chunk = Math.min(RELATION_FILTER_STREAM_CHUNK, fetchLimit - visibleTargets.length);
+						if (batch.length < chunk) continue;
+						await drain();
+						if (visibleTargets.length >= fetchLimit) break;
 					}
+					if (visibleTargets.length < fetchLimit) await drain();
 					return visibleTargets;
 				}
 				return await query.collect();
@@ -7847,6 +8251,19 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		if (!targetFiltersApplied) targets = await applyPostFetchTargetFilters(targets);
 		if (orderSpecs.length > 0) targets.sort((a, b) => this._compareByOrderSpecs(a, b, orderSpecs));
+		if (!edge.through && (perParentOffset !== void 0 || effectivePerParentLimit !== void 0)) {
+			const groupedTargets = /* @__PURE__ */ new Map();
+			for (const target of targets) {
+				const parentKey = this._buildRelationKey(target, targetFields);
+				if (!parentKey) continue;
+				const group = groupedTargets.get(parentKey);
+				if (group) group.push(target);
+				else groupedTargets.set(parentKey, [target]);
+			}
+			const trimmed = [];
+			for (const children of groupedTargets.values()) for (const child of applyOffsetAndLimit(children)) trimmed.push(child);
+			targets = trimmed;
+		}
 		if (relationConfig && typeof relationConfig === "object" && "with" in relationConfig) {
 			const targetTableEdges = this._getTargetTableEdges(edge.targetTable);
 			await this._loadRelations(targets, relationConfig.with, depth + 1, maxDepth, targetTableEdges, targetTableConfig);
@@ -7891,7 +8308,6 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				if (!byParentKey.has(parentKey)) byParentKey.set(parentKey, []);
 				byParentKey.get(parentKey).push(mappedTarget);
 			}
-			if (perParentOffset !== void 0 || effectivePerParentLimit !== void 0) for (const [parentKey, children] of byParentKey.entries()) byParentKey.set(parentKey, applyOffsetAndLimit(children));
 			for (const row of rows) {
 				const rowKey = this._buildRelationKey(row, sourceFields);
 				row[relationName] = rowKey ? byParentKey.get(rowKey) ?? [] : [];
@@ -9531,6 +9947,38 @@ var ConvexUpdateBuilder = class extends QueryPromise {
 
 //#endregion
 //#region src/orm/database.ts
+/**
+* `createDatabase` runs on every Convex query and mutation entry, but the
+* foreign-key graph and the per-table edge partition are pure functions of the
+* schema and edge metadata, both fixed for the process lifetime. Caching them
+* on the identity of those objects keeps the per-request work proportional to
+* the table count instead of `tables x edges`.
+*
+* Both caches are only sound because their inputs are module-level immutables:
+* nothing in the ORM mutates a schema or an edge list after construction.
+*/
+const foreignKeyGraphCache = /* @__PURE__ */ new WeakMap();
+const edgesBySourceTableCache = /* @__PURE__ */ new WeakMap();
+const NO_EDGES = [];
+function getForeignKeyGraph(schema) {
+	const cached = foreignKeyGraphCache.get(schema);
+	if (cached) return cached;
+	const graph = buildForeignKeyGraph(schema);
+	foreignKeyGraphCache.set(schema, graph);
+	return graph;
+}
+function getEdgesBySourceTable(edgeMetadata) {
+	const cached = edgesBySourceTableCache.get(edgeMetadata);
+	if (cached) return cached;
+	const grouped = /* @__PURE__ */ new Map();
+	for (const edge of edgeMetadata) {
+		const existing = grouped.get(edge.sourceTable);
+		if (existing) existing.push(edge);
+		else grouped.set(edge.sourceTable, [edge]);
+	}
+	edgesBySourceTableCache.set(edgeMetadata, grouped);
+	return grouped;
+}
 function createDatabase(db, schema, edgeMetadata, options) {
 	const schemaOptions = schema[OrmSchemaOptions];
 	const strict = schemaOptions?.strict ?? true;
@@ -9541,7 +9989,7 @@ function createDatabase(db, schema, edgeMetadata, options) {
 			scheduledMutationBatch: options?.scheduledMutationBatch
 		});
 		const ormContext = {
-			foreignKeyGraph: buildForeignKeyGraph(schema),
+			foreignKeyGraph: getForeignKeyGraph(schema),
 			schema,
 			edgeMetadata,
 			relationLoading: options?.relationLoading,
@@ -9555,7 +10003,8 @@ function createDatabase(db, schema, edgeMetadata, options) {
 		};
 		const baseDb = Object.assign(Object.create(db), { [OrmContext]: ormContext });
 		const query = {};
-		for (const [tableName, tableConfig] of Object.entries(schema)) query[tableName] = new RelationalQueryBuilder(schema, tableConfig, edgeMetadata.filter((edge) => edge.sourceTable === tableConfig.name), baseDb, edgeMetadata, rls, options?.relationLoading, options?.vectorSearch);
+		const edgesBySourceTable = getEdgesBySourceTable(edgeMetadata);
+		for (const [tableName, tableConfig] of Object.entries(schema)) query[tableName] = new RelationalQueryBuilder(schema, tableConfig, edgesBySourceTable.get(tableConfig.name) ?? NO_EDGES, baseDb, edgeMetadata, rls, options?.relationLoading, options?.vectorSearch);
 		const isWriter = typeof db.insert === "function" && typeof db.patch === "function";
 		const isConvexTable = (value) => !!value && typeof value === "object" && value[Brand] === "ConvexTable";
 		const insert = (table) => {
@@ -9600,14 +10049,18 @@ function createDatabase(db, schema, edgeMetadata, options) {
 		return built;
 	};
 	const table = buildDatabase(options?.rls);
-	const skipRulesTable = buildDatabase({
-		...options?.rls ?? {},
-		mode: "skip"
+	let skipRulesTable;
+	return Object.defineProperty({ ...table }, "skipRules", {
+		enumerable: true,
+		configurable: true,
+		get() {
+			skipRulesTable ??= buildDatabase({
+				...options?.rls ?? {},
+				mode: "skip"
+			});
+			return skipRulesTable;
+		}
 	});
-	return {
-		...table,
-		skipRules: skipRulesTable
-	};
 }
 
 //#endregion
@@ -11176,8 +11629,7 @@ function resolveOrmSchemaConfig(schemaInput) {
 		triggers: getSchemaTriggers(schemaInput)
 	};
 }
-function createDbFactory(schema, dbLifecycle, ormFunctions) {
-	const edgeMetadata = extractRelationsConfig(schema);
+function createDbFactory(schema, edgeMetadata, dbLifecycle, ormFunctions) {
 	return ((source, options) => {
 		const ctxSource = isOrmCtx(source) ? source : void 0;
 		const rawDb = ctxSource ? ctxSource.db : source;
@@ -11203,7 +11655,7 @@ function createOrm(config) {
 	const { schema: resolvedSchema, triggers } = resolveOrmSchemaConfig(config.schema);
 	const dbLifecycle = createOrmDbLifecycle(resolvedSchema, triggers);
 	const edgeMetadata = extractRelationsConfig(resolvedSchema);
-	const db = createDbFactory(resolvedSchema, dbLifecycle, config.ormFunctions);
+	const db = createDbFactory(resolvedSchema, edgeMetadata, dbLifecycle, config.ormFunctions);
 	const withContext = (ctx, options) => {
 		const lifecycleCtx = { ...ctx };
 		const wrappedCtx = dbLifecycle.wrapDB(lifecycleCtx);