kitcn 0.17.4 → 0.18.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-CJE_hYA3.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
@@ -4565,6 +4677,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 +4893,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);
@@ -6959,14 +7109,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 +7197,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 +7369,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 +7382,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 +7393,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 +7424,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 +7451,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 +7463,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 +7695,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 +7705,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 +7733,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 +7768,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 +7805,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 +7817,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 +7911,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 +8086,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 +8195,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 +8252,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 +9891,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 +9933,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 +9947,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 +9993,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 +11573,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 +11599,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);