kitcn 0.32.2 → 0.33.0

package/dist/orm/index.js

@@ -4,8 +4,8 @@ import { a as pretendRequired, i as pretend, n as deprecated } from "../validato
 import { o as id } from "../schema-BFP_awgP.js";
 import { a as OrmSchemaDefinition, c as OrmSchemaExtensionTriggers, d as OrmSchemaRelations, f as OrmSchemaTriggers, g as TablePolymorphic, h as TableName, i as OrmContext, l as OrmSchemaExtensions, n as Columns, o as OrmSchemaExtensionRelations, p as RlsPolicies, r as EnableRLS, s as OrmSchemaExtensionTables, t as Brand, u as OrmSchemaOptions } from "../symbols-DDNAddkd.js";
 import { A as inArray, B as notBetween, C as eq, D as gt, E as filterValuesEqual, F as lt, G as startsWith, H as notInArray, I as lte, L as matchLikePattern, M as isNotNull, N as isNull, O as gte, P as like, R as ne, S as endsWith, T as filterValueInList, U as notLike, V as notIlike, W as or, _ as arrayContains, a as findVectorIndexByName, b as column, c as getRankIndexes, d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, g as arrayContained, h as and, i as findSearchIndexByName, j as isFieldReference, k as ilike, l as resolveIndexOrderPushdown, m as usesSystemCreatedAtAlias, n as findIndexForColumns, o as getAggregateIndexes, r as findRelationIndex, s as getIndexes, t as findExactIndexForColumns, u as CREATED_AT_MIGRATION_MESSAGE, v as arrayOverlaps, w as fieldRef, x as contains, y as between, z as not } from "../index-utils-DvK7P6Q1.js";
-import { a as indexKeyWithinBounds, c as streamIndexRange, i as getIndexFields, l as isUnsetToken, n as EmptyStream, o as mergedStream, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-D4z1CnDH.js";
-import { $ as patchReferencingRows, A as enforcePolymorphicWrite, B as getForeignKeys, C as collectPrimaryIdLookupRows, D as encodeUndefinedDeep, E as deserializeFilterExpression, F as evaluateCheckConstraintTriState, G as getTableColumns$2, H as getMutationCollectionLimits, I as evaluateFilter, J as getUniqueIndexes, K as getTableDeleteConfig, L as extractPrimaryIdLookup, M as ensureDefaultColumns, N as ensureNonNullValues, O as enforceCheckConstraints, P as ensureNullableColumns, Q as normalizeTemporalComparableValue, R as getChecks, S as collectMutationRowsBounded, T as decodeUndefinedDeep, U as getMutationExecutionMode, V as getMutationAsyncDelayMs, W as getOrmContext, X as hydrateDateFieldsForRead, Y as hardDeleteRow, Z as normalizeDateFieldsForWrite, _ as applyDefaults, at as splitReturningSelection, b as buildForeignKeyGraph, c as getAggregateIndexDefinitions, ct as toConvexFilter, d as COUNT_ERROR, dt as markLifecycleHookedTables, et as resolveOrmRuntimeDefaults, f as createAggregateError, ft as compileConvexFilter, g as ensureCountAllowedForRls, h as ensureAggregateAllowedForRls, ht as mapWithConcurrency, it as softDeleteRow, j as enforceUniqueIndexes, k as enforceForeignKeys, l as getRankIndexDefinitions, lt as unsetFieldsOf, mt as isConvexEnforceableFilter, nt as selectReturningRowWithHydration, o as aggregateExtension, ot as stripUnsetFields, p as createCountError, pt as convexAnd, q as getTableName, rt as serializeFilterExpression, st as takeRowsWithinByteBudget, tt as returningSelectionReadsCreationTime, u as AGGREGATE_ERROR, ut as hasLifecycleHooks, v as applyIncomingForeignKeyActionsOnDelete, w as createForeignKeyProbeMemo, x as canUsePrimaryIdLookupCursor, y as applyIncomingForeignKeyActionsOnUpdate, z as getColumnName$1 } from "../schema-Bh7AmJwY.js";
+import { a as getIndexFields, c as stream, d as isUnsetToken, f as unsetToken, i as concatStreams, l as streamCanOrderBy, n as EmptyStream, o as indexKeyWithinBounds, r as QueryStream, s as mergedStream, t as getByIdWithOrmQueryFallback, u as streamIndexRange } from "../query-context-DQLv58LH.js";
+import { $ as getOrmContext, A as canUsePrimaryIdLookupCursor, B as enforceUniqueIndexes, Ct as isConvexEnforceableFilter, D as applyIncomingForeignKeyActionsOnDelete, E as applyDefaults, F as deserializeFilterExpression, G as evaluateFilter, H as ensureNonNullValues, I as encodeUndefinedDeep, J as getColumnName$1, K as extractPrimaryIdLookup, L as enforceCheckConstraints, M as collectPrimaryIdLookupRows, N as createForeignKeyProbeMemo, O as applyIncomingForeignKeyActionsOnUpdate, P as decodeUndefinedDeep, Q as getMutationExecutionMode, R as enforceForeignKeys, S as createCountError, St as convexAnd, T as ensureCountAllowedForRls, U as ensureNullableColumns, V as ensureDefaultColumns, W as evaluateCheckConstraintTriState, X as getMutationAsyncDelayMs, Y as getForeignKeys, Z as getMutationCollectionLimits, _t as toConvexFilter, at as hydrateDateFieldsForRead, b as COUNT_ERROR, bt as markLifecycleHookedTables, c as getAggregateIndexDefinitions, ct as patchReferencingRows, dt as selectReturningRowWithHydration, et as getTableColumns$2, ft as serializeFilterExpression, g as runInOrmWriteScope, gt as takeRowsWithinByteBudget, ht as stripUnsetFields, it as hardDeleteRow, j as collectMutationRowsBounded, k as buildForeignKeyGraph, l as getRankIndexDefinitions, lt as resolveOrmRuntimeDefaults, m as runInOrmWriteBatch, mt as splitReturningSelection, nt as getTableName, o as aggregateExtension, ot as normalizeDateFieldsForWrite, p as runInOrmUserCallback, pt as softDeleteRow, q as getChecks, rt as getUniqueIndexes, st as normalizeTemporalComparableValue, tt as getTableDeleteConfig, ut as returningSelectionReadsCreationTime, v as markOrmTransactionAnchor, vt as unsetFieldsOf, w as ensureAggregateAllowedForRls, wt as mapWithConcurrency, x as createAggregateError, xt as compileConvexFilter, y as AGGREGATE_ERROR, yt as hasLifecycleHooks, z as enforcePolymorphicWrite } from "../schema-BF4P0ZjS.js";
 import { t as defineSchemaExtension } from "../extensions-Bp0XHanR.js";
 import { compareValues, convexToJson, jsonToConvex, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric, internalQueryGeneric } from "convex/server";
@@ -560,7 +560,7 @@ function policyExpressionPasses(row, expression) {
 async function resolveExpression(policy, checkType, ctx, table) {
 	const candidate = checkType === "withCheck" ? policy.withCheck ?? policy.using : policy.using;
 	if (!candidate) return;
-	if (typeof candidate === "function") return await candidate(ctx, table);
+	if (typeof candidate === "function") return await runInOrmUserCallback(() => candidate(ctx, table));
 	return candidate;
 }
 /**
@@ -703,13 +703,14 @@ async function filterSelectRows(options) {
 */
 const INDEX_ORDER_BONUS = 30;
 /**
-* Widest index union worth opening. Each probe becomes its own index range, and
-* a streamed union holds every one of them open at once, so past this width the
-* fan-out costs more than the single scan it would replace.
+* Widest index union worth reading as one merged stream. A merge holds every
+* probe's index range open at once, and past this width that fan-out costs more
+* than reading the same ranges one after another.
 *
-* Owns both ends of that decision: whether to promote an `in` inside an AND to
-* a union here, and whether the executor may read a compiled union as a merged
-* stream instead of a bounded scan.
+* Only the executor's business: it picks between a merged and a concatenated
+* union. Width is never a reason to compile a scan instead of a union — the
+* ranges an `in` opens are what bounds the read, and a table scan does not stop
+* being a table scan because the list got longer.
 */
 const MAX_INDEX_UNION_PROBES = 64;
 var WhereClauseCompiler = class {
@@ -789,7 +790,7 @@ var WhereClauseCompiler = class {
 		for (const term of terms) {
 			if (term.type !== "binary" || term.operator !== "inArray") continue;
 			const probePlan = this.tryCompileInArray(term);
-			if (!probePlan || probePlan.probeFilters.length > MAX_INDEX_UNION_PROBES) continue;
+			if (!probePlan) continue;
 			return {
 				...probePlan,
 				postFilters: [expression]
@@ -2713,34 +2714,70 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		for (let i = 0; i < fields.length; i += 1) builder = builder.eq(fields[i], values[i]);
 		return builder;
 	}
-	_buildTableFilterPredicate(where, tableConfig) {
-		if (!where) return null;
-		if (typeof where === "function") {
-			const whereResult = this._resolveWhereCallbackExpression(where, tableConfig, { context: "pipeline" });
-			if (!whereResult) return null;
-			if (this._isPredicateWhereClause(whereResult)) return async (row) => await whereResult.predicate(row);
-			return async (row) => this._evaluatePostFetchFilter(row, whereResult);
-		}
-		return async (row) => {
-			const expression = this._buildFilterExpression(where, tableConfig);
-			if (!expression) return true;
-			return this._evaluatePostFetchFilter(row, expression);
-		};
+	/**
+	* The row filter for an already-resolved pipeline stage `where`.
+	*
+	* Takes the resolved shape rather than the clause so the rows that are read
+	* and the rows that are kept come from the same resolution. Resolving twice
+	* would let a `where` callback that closes over changing state — a clock, a
+	* counter — bound the read with one expression and filter it with another,
+	* dropping rows that the second expression matched but the first never read.
+	*/
+	_buildResolvedWherePredicate(where) {
+		if (where.kind === "none") return null;
+		if (where.kind === "predicate") {
+			const { clause } = where;
+			return async (row) => await clause.predicate(row);
+		}
+		const { expression } = where;
+		return async (row) => this._evaluatePostFetchFilter(row, expression);
 	}
-	_assertWhereIndexRequirement(options) {
-		const { where, tableConfig, hasConfiguredIndex, context } = options;
-		if (!where) return;
-		let whereExpression;
+	/**
+	* What a pipeline stage `where` is, resolved once.
+	*
+	* Object clauses and callbacks that return an expression can be compiled and
+	* therefore index-lowered. `predicate(...)` is opaque JavaScript and never
+	* can be. Both the anchoring check and the index lowering need to tell those
+	* apart, and a callback `where` should be run once per read rather than once
+	* per caller that asks.
+	*/
+	_resolvePipelineWhere(where, tableConfig) {
+		if (!where) return { kind: "none" };
 		if (typeof where === "function") {
 			const result = this._resolveWhereCallbackExpression(where, tableConfig, { context: "pipeline" });
-			if (!result) return;
-			if (this._isPredicateWhereClause(result)) {
-				if (!hasConfiguredIndex) throw new Error(`${context} where uses predicate(...) and requires .withIndex(...).`);
-				return;
-			}
-			whereExpression = result;
-		} else whereExpression = this._buildFilterExpression(where, tableConfig);
-		if (!whereExpression) return;
+			if (!result) return { kind: "none" };
+			return this._isPredicateWhereClause(result) ? {
+				kind: "predicate",
+				clause: result
+			} : {
+				kind: "expression",
+				expression: result
+			};
+		}
+		const expression = this._buildFilterExpression(where, tableConfig);
+		return expression ? {
+			kind: "expression",
+			expression
+		} : { kind: "none" };
+	}
+	/**
+	* Reject a `predicate(...)` stage `where` on a read nothing bounds.
+	*
+	* A predicate can only run after the row is read, so it costs one read per
+	* candidate row. That is fine over an index range and unbounded over a table
+	* scan, which is the same line `findMany` draws for a chain-level
+	* `predicate(...)`. An object `where` is not held to it: the compiler
+	* lowers what it can and post-filters the rest, exactly as the chain-level
+	* read does.
+	*
+	* `remedy` is per call site because the anchor a caller can add differs: a
+	* union source takes an index, a `flatMap` stage has no index option at all
+	* and is anchored by the relation's own declared index.
+	*/
+	_assertPipelineWhereIsAnchored(options) {
+		const { where, isAnchored, context, remedy } = options;
+		if (isAnchored || where.kind !== "predicate") return;
+		throw new Error(`${context} where uses predicate(...), which is evaluated after each row is read, so it needs an index-bounded read. ${remedy}`);
 	}
 	_isFilterExpressionNode(value) {
 		return typeof value === "object" && value !== null && "accept" in value && typeof value.accept === "function";
@@ -2837,16 +2874,23 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	/**
 	* The compiled index union, as one ordered stream.
 	*
-	* Each probe is its own index range, so the union is only usable where the
-	* merged order is the order the read has to produce. `mergedStream` orders by
-	* a *suffix* of the index key, and a suffix may only drop key components the
+	* Each probe is its own index range, so the union is only usable where its
+	* order is the order the read has to produce. `mergedStream` orders by a
+	* suffix of the index key, and a suffix may only drop key components the
 	* probes all pin to a single value — so the requested field has to sit inside
 	* the pinned run or immediately after it. Returns null when it does not, and
 	* the caller falls back to the plan's plain index range or a bounded scan.
+	*
+	* Two executors, because a union that is too wide to merge is not too wide to
+	* read. A merge registers every probe up front and holds them open for the
+	* life of the read, which is what `MAX_INDEX_UNION_PROBES` refuses; past that
+	* width the probes are concatenated instead, one open query at a time. What
+	* the cap picks is therefore fan-out versus sequential — never index versus
+	* table scan, which is a trade no read wins.
 	*/
 	_buildProbeUnionStream(params) {
 		const { probeFilters } = params;
-		if (probeFilters.length === 0 || probeFilters.length > MAX_INDEX_UNION_PROBES) return null;
+		if (probeFilters.length === 0) return null;
 		const streamIndexFields = getIndexFields(this.tableConfig.name, params.indexName, params.schemaDefinition);
 		const pinned = this._indexEqPrefixCount({ probeFilters });
 		let mergeOffset = -1;
@@ -2855,11 +2899,102 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			break;
 		}
 		if (mergeOffset === -1) return null;
-		return mergedStream(probeFilters.map((filters) => stream(this.db, params.schemaDefinition).query(this.tableConfig.name).withIndex(params.indexName, (q) => {
+		const probeStream = (filters) => stream(this.db, params.schemaDefinition).query(this.tableConfig.name).withIndex(params.indexName, (q) => {
 			let indexQuery = q;
 			for (const filter of filters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
 			return indexQuery;
-		}).order(params.order)), streamIndexFields.slice(mergeOffset));
+		}).order(params.order);
+		if (probeFilters.length > MAX_INDEX_UNION_PROBES) {
+			if (mergeOffset !== 0) return null;
+			const orderedProbes = this._orderDisjointProbes({
+				probeFilters,
+				indexField: streamIndexFields[0],
+				order: params.order
+			});
+			if (!orderedProbes) return null;
+			return concatStreams(orderedProbes.map(probeStream));
+		}
+		return mergedStream(probeFilters.map(probeStream), streamIndexFields.slice(mergeOffset));
+	}
+	/**
+	* `probeFilters` in the order a scan of `indexField` reaches them, or null
+	* when they cannot be proven to be pairwise-disjoint ranges on that field.
+	*
+	* Concatenation stands in for a merge only under those two properties, and
+	* both have to come from the filters themselves rather than from trust in the
+	* compiler that emitted them: overlapping probes would emit a row twice, and
+	* probes handed over out of order would emit index keys backwards.
+	*/
+	_orderDisjointProbes(params) {
+		const ranges = [];
+		for (const filters of params.probeFilters) {
+			let lower = null;
+			let upper = null;
+			let usable = filters.length > 0;
+			for (const filter of filters) {
+				if (filter.type !== "binary") {
+					usable = false;
+					break;
+				}
+				const [field, rawValue] = filter.operands;
+				if (!isFieldReference(field) || field.fieldName !== params.indexField || rawValue === void 0 || isFieldReference(rawValue)) {
+					usable = false;
+					break;
+				}
+				const value = this._normalizeComparableValue(field.fieldName, rawValue);
+				switch (filter.operator) {
+					case "eq":
+						usable = lower === null && upper === null;
+						lower = {
+							inclusive: true,
+							value
+						};
+						upper = {
+							inclusive: true,
+							value
+						};
+						break;
+					case "gt":
+					case "gte":
+						usable = lower === null;
+						lower = {
+							inclusive: filter.operator === "gte",
+							value
+						};
+						break;
+					case "lt":
+					case "lte":
+						usable = upper === null;
+						upper = {
+							inclusive: filter.operator === "lte",
+							value
+						};
+						break;
+					default: usable = false;
+				}
+				if (!usable) break;
+			}
+			if (!usable) return null;
+			ranges.push({
+				filters,
+				lower,
+				upper
+			});
+		}
+		ranges.sort((a, b) => {
+			if (!(a.lower && b.lower)) return a.lower ? 1 : b.lower ? -1 : 0;
+			return compareValues(a.lower.value, b.lower.value) || Number(!a.lower.inclusive) - Number(!b.lower.inclusive);
+		});
+		for (let i = 1; i < ranges.length; i += 1) {
+			const previous = ranges[i - 1];
+			const current = ranges[i];
+			if (!(previous.upper && current.lower)) return null;
+			const gap = compareValues(previous.upper.value, current.lower.value);
+			if (gap > 0) return null;
+			if (gap === 0 && previous.upper.inclusive && current.lower.inclusive) return null;
+		}
+		const ordered = ranges.map((range) => range.filters);
+		return params.order === "asc" ? ordered : ordered.reverse();
 	}
 	/**
 	* The read the compiled plan describes, as a stream, with nothing filtered
@@ -2886,7 +3021,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				indexName: probeIndex.name,
 				probeFilters: queryConfig.probeFilters,
 				order,
-				orderField: primaryOrder?.field ?? probeIndex.fields[0]
+				orderField: params.probeOrderField ?? primaryOrder?.field ?? probeIndex.fields[0]
 			});
 			if (probeUnion) return {
 				stream: probeUnion,
@@ -2959,22 +3094,82 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		});
 		return streamQuery;
 	}
-	_buildUnionSourceStream(source, fallbackOrder) {
+	/**
+	* One `pipeline.union` source, as a stream.
+	*
+	* The source's own `where` is compiled into an index plan first, so an
+	* object `where` bounds the read instead of being discarded row by row after
+	* it. Two rules keep that from changing what the union produces:
+	*
+	* - `_compileQueryPlan` discards a plan that would displace an index the
+	*   caller pinned, so a source's own range (a tenant scope, say) still wins.
+	* - A merged union is ordered by `interleaveBy`, which only some index
+	*   shapes can supply. The lowered read is checked against that before it is
+	*   committed to, and the unlowered scan is used when it cannot serve the
+	*   merge — an index that saves reads is not worth an ordering that throws.
+	*
+	* The `where` stays applied in JS either way. The index range is a bound on
+	* what is read, not a replacement for the predicate.
+	*/
+	_buildUnionSourceStream(source, fallbackOrder, interleaveFields) {
 		const sourceIndex = source.index ?? this.configuredIndex;
-		this._assertWhereIndexRequirement({
-			where: source.where,
-			tableConfig: this.tableConfig,
-			hasConfiguredIndex: Boolean(sourceIndex?.name),
-			context: "pipeline.union source"
+		const sourceWhere = this._resolvePipelineWhere(source.where, this.tableConfig);
+		this._assertPipelineWhereIsAnchored({
+			where: sourceWhere,
+			isAnchored: Boolean(sourceIndex?.name),
+			context: "pipeline.union source",
+			remedy: "Give the source an index: { name, range }, or pin .withIndex(name, range?) on the chain."
 		});
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
-		let sourceStream = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-		if (sourceIndex?.name) sourceStream = sourceStream.withIndex(sourceIndex.name, sourceIndex.range ? sourceIndex.range : (q) => q);
-		sourceStream = sourceStream.order(fallbackOrder);
-		const sourcePredicate = this._buildTableFilterPredicate(source.where, this.tableConfig);
+		const buildRead = (whereExpression) => this._buildPlanStream({
+			queryConfig: this._compileQueryPlan({
+				whereExpression,
+				configuredIndex: sourceIndex,
+				orderSpecs: []
+			}),
+			configuredIndex: sourceIndex,
+			order: fallbackOrder,
+			orderIndexName: null,
+			probeOrderField: interleaveFields?.[0],
+			schemaDefinition
+		}).stream;
+		const planned = sourceWhere.kind === "expression" ? buildRead(sourceWhere.expression) : null;
+		let sourceStream = planned !== null && (!interleaveFields || streamCanOrderBy(planned, interleaveFields)) ? planned : buildRead();
+		const sourcePredicate = this._buildResolvedWherePredicate(sourceWhere);
 		if (sourcePredicate) sourceStream = sourceStream.filterWith(sourcePredicate);
 		return sourceStream;
 	}
+	/**
+	* The index a `flatMap` stage `where` can ride on top of the join keys.
+	*
+	* The join is only correct while `targetFields` stay pinned by equality, and
+	* a Convex range builder pins fields in index-key order with no gaps, so the
+	* candidates are exactly the declared indexes that lead with `targetFields`
+	* and carry at least one more field. Those trailing fields are what the
+	* stage `where` is compiled against — the compiler never sees the join keys,
+	* because their values are per parent and the index choice has to be made
+	* once for all of them.
+	*
+	* Returns null when nothing is gained, and the caller keeps the relation's
+	* own index plus the post-filter. A multi-probe plan is refused: each probe
+	* is its own range, and a union of ranges per parent is a different stream
+	* shape than the one `flatMap` was handed as `mappedIndexFields`.
+	*/
+	_resolveFlatMapStageIndex(params) {
+		const { where, targetTableConfig, targetFields } = params;
+		if (where.kind !== "expression") return null;
+		const candidates = getIndexes(targetTableConfig.table).filter((index) => index.fields.length > targetFields.length && targetFields.every((field, i) => index.fields[i] === field)).map((index) => ({
+			indexName: index.name,
+			indexFields: index.fields.slice(targetFields.length)
+		}));
+		if (candidates.length === 0) return null;
+		const compiled = new WhereClauseCompiler(targetTableConfig.table.tableName, candidates).compile(where.expression);
+		if (!compiled.selectedIndex || compiled.probeFilters.length > 0 || compiled.indexFilters.length === 0) return null;
+		return {
+			name: compiled.selectedIndex.indexName,
+			filters: compiled.indexFilters
+		};
+	}
 	async _applyFlatMapStage(sourceStream, stage) {
 		const relationName = stage.relation;
 		const edge = this.edgeMetadata.find((e) => e.edgeName === relationName);
@@ -2990,24 +3185,36 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			rls: this.rls
 		});
 		const strict = this.tableConfig.strict !== false;
-		const indexName = targetFields.length === 1 && targetFields[0] === "_id" ? "by_id" : findRelationIndex(targetTableConfig.table, targetFields, `${this.tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan);
+		const useGetById = targetFields.length === 1 && targetFields[0] === "_id";
+		const relationIndexName = useGetById ? "by_id" : findRelationIndex(targetTableConfig.table, targetFields, `${this.tableConfig.name}.${relationName}`, edge.targetTable, strict, this.allowFullScan);
+		const stageWhere = this._resolvePipelineWhere(stage.where, targetTableConfig);
+		const stageIndex = useGetById ? null : this._resolveFlatMapStageIndex({
+			where: stageWhere,
+			targetTableConfig,
+			targetFields
+		});
+		const indexName = stageIndex?.name ?? relationIndexName;
 		const outerOrder = sourceStream.getOrder();
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
 		const innerIndexFields = getIndexFields(edge.targetTable, indexName ?? "by_creation_time" ?? "by_creation_time", schemaDefinition);
 		if (stage.limit !== void 0 && (!Number.isInteger(stage.limit) || stage.limit < 1)) throw new Error("pipeline.flatMap.limit must be a positive integer");
 		const mappedIndexFields = stage.limit === void 0 ? innerIndexFields : [...innerIndexFields, PIPELINE_LIMIT_ORDINAL_FIELD];
-		const stageWherePredicate = this._buildTableFilterPredicate(stage.where, targetTableConfig);
-		this._assertWhereIndexRequirement({
-			where: stage.where,
-			tableConfig: targetTableConfig,
-			hasConfiguredIndex: Boolean(indexName),
-			context: `pipeline.flatMap(${relationName})`
+		const stageWherePredicate = this._buildResolvedWherePredicate(stageWhere);
+		this._assertPipelineWhereIsAnchored({
+			where: stageWhere,
+			isAnchored: Boolean(indexName),
+			context: `pipeline.flatMap(${relationName})`,
+			remedy: `flatMap takes no index of its own — add an index on ${edge.targetTable}(${targetFields.join(", ")}) so the join is anchored, or use an object where().`
 		});
 		return sourceStream.flatMap(async (parent) => {
 			const values = sourceFields.map((field) => parent[field]);
 			if (values.some((value) => value === null || value === void 0)) return new EmptyStream(outerOrder, mappedIndexFields);
 			let inner = stream(this.db, schemaDefinition).query(edge.targetTable);
-			if (indexName) inner = inner.withIndex(indexName, (q) => this._applyEqBounds(q, targetFields, values));
+			if (indexName) inner = inner.withIndex(indexName, (q) => {
+				let range = this._applyEqBounds(q, targetFields, values);
+				for (const filter of stageIndex?.filters ?? []) range = this._applyFilterToQuery(range, filter, targetTableConfig);
+				return range;
+			});
 			inner = inner.order(outerOrder);
 			if (stageWherePredicate) inner = inner.filterWith(stageWherePredicate);
 			if (isRlsEnabled(targetTableConfig.table)) inner = inner.filterWith(async (row) => {
@@ -4109,12 +4316,14 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			let streamQuery;
 			const unionSources = pipeline?.union ?? [];
 			if (unionSources.length > 0) {
-				const streams = unionSources.map((source) => this._buildUnionSourceStream(source, fallbackOrder));
-				if (streams.length === 1) streamQuery = streams[0];
-				else {
-					if (!pipeline?.interleaveBy || pipeline.interleaveBy.length === 0) throw new Error("pipeline.interleaveBy is required when pipeline.union has multiple sources.");
-					streamQuery = mergedStream(streams, pipeline.interleaveBy.map((field) => this._normalizePublicFieldName(field)));
+				let interleaveFields;
+				if (unionSources.length > 1) {
+					const declared = pipeline?.interleaveBy;
+					if (!declared || declared.length === 0) throw new Error("pipeline.interleaveBy is required when pipeline.union has multiple sources.");
+					interleaveFields = declared.map((field) => this._normalizePublicFieldName(field));
 				}
+				const streams = unionSources.map((source) => this._buildUnionSourceStream(source, fallbackOrder, interleaveFields));
+				streamQuery = interleaveFields ? mergedStream(streams, interleaveFields) : streams[0];
 			} else {
 				const orderedIdList = isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in" ? queryConfig.order?.[0] : void 0;
 				if (orderedIdList) {
@@ -4399,41 +4608,53 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			const selectedRows = await this._finalizeRows(rows);
 			return this._returnSelectedRows(selectedRows);
 		}
+		const matchesPostFetchMembership = async (row) => {
+			const visibleRows = await this._applyRlsSelectFilter([row], this.tableConfig);
+			if (visibleRows.length === 0) return false;
+			if (!whereFilter) return true;
+			return (await this._applyRelationsFilterToRows(visibleRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with)).length > 0;
+		};
 		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 probeHasRelationMembership = this._hasSearchDisallowedRelationFilter(whereFilter, this.tableConfig);
+			const probeHasPostFetchMembership = probeHasRelationMembership || this.rls?.mode !== "skip" && isRlsEnabled(this.tableConfig.table);
 			const probeOrderDirection = orderPushdownDirection;
-			const probeBound = probeLimit !== void 0 && !probeHasResidualFilter && !probeHasPostFetchMembership && (postFetchOrders.length === 0 || probeOrderDirection !== null) ? probeOffset + probeLimit : void 0;
+			const probeBound = probeLimit !== void 0 && (postFetchOrders.length === 0 || probeOrderDirection !== null) ? probeOffset + probeLimit : void 0;
+			const probeBoundedTake = probeBound !== void 0 && !probeHasResidualFilter && !probeHasPostFetchMembership;
+			const probeSchemaDefinition = this.schema[OrmSchemaDefinition];
+			const probeStreamed = probeBound !== void 0 && !probeBoundedTake && !probeHasRelationMembership && !!probeSchemaDefinition;
 			const probeRows = await Promise.all(queryConfig.probeFilters.map(async (probeFilters) => {
+				if (probeStreamed) return await stream(this.db, probeSchemaDefinition).query(this.tableConfig.name).withIndex(queryConfig.index.name, (q) => {
+					let indexQuery = q;
+					for (const filter of probeFilters) indexQuery = this._applyFilterToQuery(indexQuery, filter);
+					return indexQuery;
+				}).order(probeOrderDirection ?? "asc").filterWith(async (row) => {
+					for (const filter of queryConfig.postFilters) if (!this._evaluatePostFetchFilter(row, filter)) return false;
+					return await matchesPostFetchMembership(row);
+				}).take(probeBound);
 				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 (probeBound !== void 0 && probeOrderDirection) probeQuery = probeQuery.order(probeOrderDirection);
+				if (probeBoundedTake && probeOrderDirection) probeQuery = probeQuery.order(probeOrderDirection);
 				if (convexProbeFilters.length > 0) probeQuery = probeQuery.filter((q) => convexAnd(q, convexProbeFilters.map((filter) => this._toConvexExpression(filter)(q))));
-				return probeBound === void 0 ? await probeQuery.collect() : await probeQuery.take(probeBound);
+				return probeBoundedTake ? await probeQuery.take(probeBound) : await probeQuery.collect();
 			}));
 			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, MAX_RELATION_DEPTH, this.config.with);
+			if (whereFilter && !probeStreamed) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			if (postFetchOrders.length > 0) rows = rows.sort((a, b) => this._compareByOrderSpecs(a, b, postFetchOrders));
 			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);
 		}
-		const matchesPostFetchMembership = async (row) => {
-			const visibleRows = await this._applyRlsSelectFilter([row], this.tableConfig);
-			if (visibleRows.length === 0) return false;
-			if (!whereFilter) return true;
-			return (await this._applyRelationsFilterToRows(visibleRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with)).length > 0;
-		};
 		if (isCursorPaginated) {
 			const isMultiProbePlan = queryConfig.strategy === "multiProbe" && !!queryConfig.index;
 			const isScanFallbackPlan = !queryConfig.index && queryConfig.postFilters.length > 0;
@@ -4583,11 +4804,6 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	*/
 	_toConvexQuery(whereExpressionOverride, configuredIndex) {
 		const config = this.config;
-		const tableIndexes = getIndexes(this.tableConfig.table).map((index) => ({
-			indexName: index.name,
-			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, {
@@ -4598,7 +4814,29 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		let whereExpression = whereExpressionOverride;
 		if (!whereExpression && config.where && typeof config.where !== "function") whereExpression = this._buildFilterExpression(config.where, this.tableConfig);
-		const planned = compiler.compile(whereExpression, { orderFields: orderSpecs.map((spec) => spec.field) });
+		return this._compileQueryPlan({
+			whereExpression,
+			configuredIndex,
+			orderSpecs
+		});
+	}
+	/**
+	* The read plan for one `where` on this table.
+	*
+	* Split out of `_toConvexQuery` because the chain-level `where` is not the
+	* only one that has to be index-lowered: a `pipeline.union` source carries
+	* its own `where` and its own pinned index, and compiles against the same
+	* table with a different ordering contract (`interleaveBy`, not `orderBy`).
+	* Both go through here so a plain-object `where` is planned the same way
+	* wherever it is written.
+	*/
+	_compileQueryPlan(params) {
+		const { whereExpression, configuredIndex, orderSpecs } = params;
+		const tableIndexes = getIndexes(this.tableConfig.table).map((index) => ({
+			indexName: index.name,
+			indexFields: index.fields
+		}));
+		const planned = new WhereClauseCompiler(this.tableConfig.table.tableName, tableIndexes).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",
@@ -4680,11 +4918,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* Apply a single filter expression to a Convex query builder
 	* Used for index filters (eq operations)
 	*/
-	_applyFilterToQuery(query, filter) {
+	_applyFilterToQuery(query, filter, tableConfig = this.tableConfig) {
 		if (filter.type === "binary") {
 			const [field, value] = filter.operands;
 			if (!isFieldReference(field)) return query;
-			const normalizedValue = this._normalizeComparableValue(field.fieldName, value);
+			const normalizedValue = this._normalizeComparableValue(field.fieldName, value, tableConfig);
 			switch (filter.operator) {
 				case "eq": return query.eq(field.fieldName, normalizedValue);
 				case "gt": return query.gt(field.fieldName, normalizedValue);
@@ -5637,6 +5875,9 @@ var ConvexDeleteBuilder = class extends QueryPromise {
 		});
 	}
 	async execute(...args) {
+		return await runInOrmWriteScope(this.db, () => runInOrmWriteBatch(this.db, () => this._runStatement(...args)));
+	}
+	async _runStatement(...args) {
 		const config = args[0];
 		const tableName = getTableName(this.table);
 		const ormContext = getOrmContext(this.db);
@@ -5928,6 +6169,9 @@ var ConvexInsertBuilder = class extends QueryPromise {
 		return this;
 	}
 	async execute() {
+		return await runInOrmWriteScope(this.db, () => runInOrmWriteBatch(this.db, () => this._runStatement()));
+	}
+	async _runStatement() {
 		if (this.valuesList.length === 0) throw new Error("values() must be called before execute()");
 		const ormContext = getOrmContext(this.db);
 		const tableName = getTableName(this.table);
@@ -6180,6 +6424,7 @@ function normalizeOrmTriggers(triggers) {
 //#region src/orm/lifecycle.ts
 const ORMLIFECYCLE_WRAPPED_DB = Symbol.for("kitcn:OrmLifecycleWrappedDB");
 const ORMLIFECYCLE_INNER_DB = Symbol.for("kitcn:OrmLifecycleInnerDB");
+const wrapUserHook = (hook) => hook ? (...args) => runInOrmUserCallback(() => hook(...args)) : void 0;
 const isWriterDb = (db) => typeof db.insert === "function" && typeof db.patch === "function" && typeof db.delete === "function";
 const isLifecycleWrappedDb = (db) => db[ORMLIFECYCLE_WRAPPED_DB] === true;
 const markLifecycleWrappedDb = (db) => {
@@ -6363,6 +6608,7 @@ function writerWithHooks(ctx, innerDb, hooksByTable, isWithinHook = false) {
 		const tableHooks = hooksByTable.get(tableName);
 		if (!tableHooks) return innerDb.patch(tableName, id, value);
 		return executeThenDrainHooks(ctx, innerDb, hooksByTable, isWithinHook, async (hookCtx) => {
+			await tableHooks.writeBarrier?.(innerDb);
 			const needsDocuments = Boolean(tableHooks.update?.after || tableHooks.change);
 			const oldDoc = needsDocuments ? await innerDb.get(tableName, id) : null;
 			const updatePayload = await mergeBeforeData(tableName, "update", tableHooks.update?.before, value, hookCtx);
@@ -6408,6 +6654,7 @@ function writerWithHooks(ctx, innerDb, hooksByTable, isWithinHook = false) {
 		const tableHooks = hooksByTable.get(tableName);
 		if (!tableHooks) return innerDb.replace(tableName, id, value);
 		return executeThenDrainHooks(ctx, innerDb, hooksByTable, isWithinHook, async (hookCtx) => {
+			await tableHooks.writeBarrier?.(innerDb);
 			const oldDoc = Boolean(tableHooks.update?.after || tableHooks.change) ? await innerDb.get(tableName, id) : null;
 			const updatePayload = await mergeBeforeData(tableName, "update", tableHooks.update?.before, value, hookCtx);
 			await innerDb.replace(tableName, id, updatePayload);
@@ -6443,6 +6690,7 @@ function writerWithHooks(ctx, innerDb, hooksByTable, isWithinHook = false) {
 		const tableHooks = hooksByTable.get(tableName);
 		if (!tableHooks) return innerDb.delete(tableName, id);
 		return executeThenDrainHooks(ctx, innerDb, hooksByTable, isWithinHook, async (hookCtx) => {
+			await tableHooks.writeBarrier?.(innerDb);
 			const oldDoc = Boolean(tableHooks.delete || tableHooks.change) ? await innerDb.get(tableName, id) : null;
 			if (!oldDoc) {
 				await innerDb.delete(tableName, id);
@@ -6478,6 +6726,7 @@ function writerWithHooks(ctx, innerDb, hooksByTable, isWithinHook = false) {
 			const tableHooks = hooksByTable.get(table);
 			if (!tableHooks) return innerDb.insert(table, value);
 			return executeThenDrainHooks(ctx, innerDb, hooksByTable, isWithinHook, async (hookCtx) => {
+				await tableHooks.writeBarrier?.(innerDb);
 				const insertPayload = await mergeBeforeData(table, "create", tableHooks.create?.before, value, hookCtx);
 				const id = await innerDb.insert(table, insertPayload);
 				const newDoc = Boolean(tableHooks.create?.after || tableHooks.change) ? await innerDb.get(table, id) : null;
@@ -6540,53 +6789,57 @@ function createOrmDbLifecycle(schema, triggerDefinitions, capabilities) {
 	for (const [triggerKey, hooks] of normalizedTriggers.entries()) {
 		const tableName = tableNameBySchemaKey.get(triggerKey) ?? (tableNames.has(triggerKey) ? triggerKey : void 0);
 		if (!tableName) throw new Error(`Unknown trigger table '${triggerKey}'. Export triggers with defineTriggers(relations, { ... }) using keys from your relations export.`);
-		tableHooks.set(tableName, hooks);
+		tableHooks.set(tableName, {
+			create: hooks.create && {
+				before: wrapUserHook(hooks.create.before),
+				after: wrapUserHook(hooks.create.after)
+			},
+			update: hooks.update && {
+				before: wrapUserHook(hooks.update.before),
+				after: wrapUserHook(hooks.update.after)
+			},
+			delete: hooks.delete && {
+				before: wrapUserHook(hooks.delete.before),
+				after: wrapUserHook(hooks.delete.after)
+			},
+			change: wrapUserHook(hooks.change)
+		});
 	}
 	for (const tableConfig of Object.values(schema)) {
 		if (!tableConfig?.table || !tableConfig?.name) continue;
 		const aggregateIndexes = getAggregateIndexDefinitions(tableConfig);
 		const rankIndexes = getRankIndexDefinitions(tableConfig);
 		if (aggregateIndexes.length === 0 && rankIndexes.length === 0) continue;
-		const aggregate = requireAggregateCapability(capabilities, `Table '${tableConfig.name}' declares an aggregateIndex/rankIndex, which`);
-		const existing = tableHooks.get(tableConfig.name) ?? {};
+		const tableName = tableConfig.name;
+		const aggregate = requireAggregateCapability(capabilities, `Table '${tableName}' declares an aggregateIndex/rankIndex, which`);
+		const existing = tableHooks.get(tableName) ?? {};
 		const existingChange = existing.change;
+		const existingBarrier = existing.writeBarrier;
 		const metricIndexNames = aggregateIndexes.map((entry) => entry.name);
 		const rankIndexNames = rankIndexes.map((entry) => entry.name);
-		const prependWriteBarrier = (before) => async (data, ctx) => {
-			await aggregate.assertAggregateIndexesWritable(ctx.db, tableConfig.name, metricIndexNames, rankIndexNames);
-			return before?.(data, ctx);
-		};
-		tableHooks.set(tableConfig.name, {
+		tableHooks.set(tableName, {
 			...existing,
-			create: {
-				...existing.create,
-				before: prependWriteBarrier(existing.create?.before)
-			},
-			update: {
-				...existing.update,
-				before: prependWriteBarrier(existing.update?.before)
-			},
-			delete: {
-				...existing.delete,
-				before: prependWriteBarrier(existing.delete?.before)
+			writeBarrier: async (db) => {
+				await existingBarrier?.(db);
+				await aggregate.assertAggregateIndexesWritable(db, tableName, metricIndexNames, rankIndexNames);
 			},
 			change: async (change, ctx) => {
 				if (change.operation === "delete") {
-					if (aggregateIndexes.length > 0) await aggregate.applyAggregateIndexesForChange(ctx.db, tableConfig.name, aggregateIndexes, {
+					if (aggregateIndexes.length > 0) await aggregate.applyAggregateIndexesForChange(ctx.db, tableName, aggregateIndexes, {
 						operation: "delete",
 						id: change.id
 					});
-					if (rankIndexes.length > 0) await aggregate.applyRankIndexesForChange(ctx.db, tableConfig.name, rankIndexes, {
+					if (rankIndexes.length > 0) await aggregate.applyRankIndexesForChange(ctx.db, tableName, rankIndexes, {
 						operation: "delete",
 						id: change.id
 					});
 				} else {
-					if (aggregateIndexes.length > 0) await aggregate.applyAggregateIndexesForChange(ctx.db, tableConfig.name, aggregateIndexes, {
+					if (aggregateIndexes.length > 0) await aggregate.applyAggregateIndexesForChange(ctx.db, tableName, aggregateIndexes, {
 						operation: change.operation,
 						id: change.id,
 						newDoc: change.newDoc
 					});
-					if (rankIndexes.length > 0) await aggregate.applyRankIndexesForChange(ctx.db, tableConfig.name, rankIndexes, {
+					if (rankIndexes.length > 0) await aggregate.applyRankIndexesForChange(ctx.db, tableName, rankIndexes, {
 						operation: change.operation,
 						id: change.id,
 						newDoc: change.newDoc
@@ -6857,6 +7110,9 @@ var ConvexUpdateBuilder = class extends QueryPromise {
 		});
 	}
 	async execute(...args) {
+		return await runInOrmWriteScope(this.db, () => runInOrmWriteBatch(this.db, () => this._runStatement(...args)));
+	}
+	async _runStatement(...args) {
 		if (!this.setValues) throw new Error("set() must be called before execute()");
 		if (Object.keys(this.setValues).length === 0) {
 			if (this.paginateConfig !== void 0) {
@@ -7204,7 +7460,7 @@ function createDatabase(db, schema, edgeMetadata, options) {
 			defaults,
 			resolvedDefaults
 		};
-		const baseDb = Object.assign(Object.create(db), { [OrmContext]: ormContext });
+		const baseDb = markOrmTransactionAnchor(Object.assign(Object.create(db), { [OrmContext]: ormContext }), db);
 		const query = {};
 		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);