@prisma-idb/client-idb 0.11.0 → 0.12.0

package/dist/{mutation-executor-SJqTuSbb.mjs → mutation-executor-inLFb0TE.mjs}

@@ -1,6 +1,6 @@
-import { evaluateFilter, shorthandToFilterExpr } from "@prisma-idb/adapter-idb/runtime";
+import { andExpr, evaluateFilter, fieldFilter, shorthandToFilterExpr } from "@prisma-idb/adapter-idb/runtime";
 import { domainModelsAtDefaultNamespace } from "@prisma/orm-framework/contract/types";
-import { fieldValueToken, fieldValuesEqual, keyEquals as keyEquals$1, keyToken } from "@prisma-idb/target-idb/runtime";
+import { compareFieldValues, fieldValueToken, fieldValuesEqual, isValidIdbKey, keyEquals, keyEquals as keyEquals$1, keyToken } from "@prisma-idb/target-idb/runtime";
 import { generateId } from "@prisma/orm-framework/ids/runtime";
 import { keyPathFields } from "@prisma-idb/target-idb/pack";
 //#region src/core/types.ts
@@ -50,6 +50,39 @@ function getRelation(contract, modelName, relName) {
 	return relation;
 }
 //#endregion
+//#region src/core/query-shaping.ts
+/**
+* Combine accumulated filter expressions with AND.
+*
+* Returns `undefined` when no filter is present so callers can skip building a
+* row-filter closure. Shared by {@link IdbStoreAccessorImpl} (top-level scans)
+* and the relation loader (refined `include()` child scans).
+*/
+function combineFilterExprs(filters) {
+	if (filters.length === 0) return void 0;
+	if (filters.length === 1) return filters[0];
+	return andExpr(filters);
+}
+/**
+* Build an in-memory comparator from an `orderBy` spec (field → direction).
+*
+* Returns `undefined` when there is nothing to sort by. Compares fields in
+* declaration order, with {@link compareFieldValues}: the same order an
+* IndexedDB index uses, so equal `Date`s tie and fall through to the next
+* field, and `null`s sort last (first when descending).
+*/
+function buildRowComparator(orderBy) {
+	if (orderBy === void 0) return void 0;
+	return (a, b) => {
+		for (const [field, dir] of Object.entries(orderBy)) {
+			const cmp = compareFieldValues(a[field], b[field]);
+			if (cmp === 0) continue;
+			return dir === "desc" ? -cmp : cmp;
+		}
+		return 0;
+	};
+}
+//#endregion
 //#region src/core/enum-validation.ts
 const rulesByContract = /* @__PURE__ */ new WeakMap();
 function resolveEnumRule(contract, field) {
@@ -178,6 +211,565 @@ function applyUpdateDefaults(defaults, storeName, patch, cache) {
 	return result;
 }
 //#endregion
+//#region src/core/planner/catalog.ts
+const catalogs = /* @__PURE__ */ new WeakMap();
+/** Build a catalog once per contract identity and store name. Contracts are immutable. */
+function buildCatalog(contract, storeName) {
+	const cached = catalogs.get(contract)?.get(storeName);
+	if (cached) return cached;
+	const store = contract.storage.stores[storeName];
+	if (!store) throw new Error(`Store "${storeName}" is not in the contract`);
+	const fields = {};
+	for (const model of Object.values(domainModelsAtDefaultNamespace(contract.domain))) {
+		if (model.storage.storeName !== storeName) continue;
+		for (const [name, field] of Object.entries(model.fields)) fields[name] = Object.freeze({
+			codecId: field.type.kind === "scalar" ? field.type.codecId : void 0,
+			nullable: field.nullable,
+			collection: field.many === true || field.dict === true
+		});
+	}
+	const catalog = Object.freeze({
+		storeName,
+		primaryKey: source(store.keyPath, true, false),
+		indexes: Object.freeze(Object.entries(store.indexes ?? {}).map(([name, index]) => source(index.keyPath, index.unique, index.multiEntry ?? false, name))),
+		fields: Object.freeze(fields)
+	});
+	let byStore = catalogs.get(contract);
+	if (!byStore) {
+		byStore = /* @__PURE__ */ new Map();
+		catalogs.set(contract, byStore);
+	}
+	byStore.set(storeName, catalog);
+	return catalog;
+}
+function source(keyPath, unique, multiEntry, indexName) {
+	const path = typeof keyPath === "string" ? keyPath : Object.freeze([...keyPath]);
+	return Object.freeze({
+		keyPath: path,
+		fields: Object.freeze(typeof path === "string" ? [path] : [...path]),
+		unique,
+		multiEntry,
+		...indexName === void 0 ? {} : { indexName }
+	});
+}
+//#endregion
+//#region src/core/planner/plan.ts
+const COST = {
+	UNIQUE_POINT: 0,
+	PRIMARY_POINT: 1,
+	INDEX_POINT: 2,
+	PREFIX_POINT: 3,
+	TWO_SIDED_RANGE: 4,
+	ONE_SIDED_RANGE: 5,
+	ORDER_ONLY_SCAN: 6
+};
+const KEY_PARTIAL_CODECS = /* @__PURE__ */ new Set(["idb/double@1", "idb/date@1"]);
+const KEY_CODECS = /* @__PURE__ */ new Set([
+	"idb/string@1",
+	"idb/int32@1",
+	"idb/double@1",
+	"idb/date@1",
+	"idb/decimal@1",
+	"idb/bytes@1"
+]);
+/** Choose the cheapest safe access without opening IndexedDB or probing cardinality. */
+function planQuery(catalog, request) {
+	const normalized = normalize(request.where);
+	if (normalized.empty) return {
+		access: { kind: "empty" },
+		exact: true
+	};
+	const orders = Object.entries(request.orderBy ?? {});
+	if (normalized.excluded || request.hasRelationFilter || orders.length > 1) return full(false);
+	const constraints = /* @__PURE__ */ new Map();
+	for (const atom of normalized.atoms) {
+		let constraint = constraints.get(atom.field);
+		if (!constraint) {
+			constraint = { consumed: 0 };
+			constraints.set(atom.field, constraint);
+		}
+		addAtom(constraint, atom, catalog.fields[atom.field]);
+	}
+	for (const [name, constraint] of constraints) {
+		if (keyPartial(catalog.fields[name]) && !constraint.rejectsNonKeys) {
+			delete constraint.lower;
+			delete constraint.upper;
+			constraint.consumed = 0;
+		}
+		if (contradictory(constraint)) return {
+			access: { kind: "empty" },
+			exact: true
+		};
+	}
+	const sources = [catalog.primaryKey, ...catalog.indexes];
+	const candidates = sources.flatMap((source, declaration) => {
+		const candidate = filteringCandidate(catalog, source, constraints, declaration);
+		return candidate ? [candidate] : [];
+	});
+	candidates.sort((a, b) => a.cost - b.cost || a.ranges.length - b.ranges.length || Number(a.source.indexName !== void 0) - Number(b.source.indexName !== void 0) || a.declaration - b.declaration);
+	let selected = candidates[0];
+	let direction;
+	if (orders.length === 1 && request.take !== void 0) {
+		const [field, order] = orders[0];
+		if (selected) {
+			if (singleFieldSource(selected.source, field)) direction = order === "asc" ? "next" : "prev";
+		} else {
+			const ordering = sources.find((source) => !source.multiEntry && singleFieldSource(source, field) && completeKeyField(catalog.fields[field]));
+			if (ordering) {
+				selected = {
+					source: ordering,
+					ranges: [void 0],
+					cost: COST.ORDER_ONLY_SCAN,
+					consumed: 0,
+					declaration: sources.indexOf(ordering)
+				};
+				direction = order === "asc" ? "next" : "prev";
+			}
+		}
+	}
+	if (!selected) {
+		const partialOrder = orders.length === 1 && request.take !== void 0 && keyPartial(catalog.fields[orders[0][0]]);
+		return full(normalized.atoms.length + normalized.residual === 0 && !partialOrder);
+	}
+	return {
+		access: {
+			kind: "ranges",
+			source: selected.source,
+			ranges: selected.ranges
+		},
+		exact: selected.consumed === normalized.atoms.length && normalized.residual === 0,
+		...direction === void 0 ? {} : { direction }
+	};
+}
+function full(exact) {
+	return {
+		access: { kind: "full" },
+		exact
+	};
+}
+function normalize(where) {
+	const result = {
+		atoms: [],
+		residual: 0,
+		excluded: false,
+		empty: false
+	};
+	function visit(expr) {
+		switch (expr.kind) {
+			case "field":
+				if (expr.op === "in" && (!Array.isArray(expr.value) || expr.value.length === 0)) result.empty = true;
+				result.atoms.push(expr);
+				break;
+			case "and":
+				expr.exprs.forEach(visit);
+				break;
+			case "or": {
+				if (expr.exprs.length === 0) {
+					result.empty = true;
+					break;
+				}
+				const branches = expr.exprs;
+				const first = branches[0];
+				if (first.kind !== "field" || !branches.every((branch) => branch.kind === "field" && branch.field === first.field && (branch.op === "eq" || branch.op === "in"))) {
+					result.excluded = true;
+					break;
+				}
+				const values = branches.flatMap((branch) => {
+					const atom = branch;
+					return atom.op === "eq" ? [atom.value] : Array.isArray(atom.value) ? atom.value : [];
+				});
+				visit({
+					kind: "field",
+					field: first.field,
+					op: "in",
+					value: values
+				});
+				break;
+			}
+			case "not":
+				result.excluded = true;
+				break;
+			case "null-check": result.residual++;
+		}
+	}
+	if (where) visit(where);
+	return result;
+}
+function keyTyped(field) {
+	return field !== void 0 && !field.collection && KEY_CODECS.has(field.codecId ?? "");
+}
+function keyPartial(field) {
+	return KEY_PARTIAL_CODECS.has(field?.codecId ?? "");
+}
+function completeKeyField(field, constraint) {
+	return keyTyped(field) && field?.nullable === false && (!keyPartial(field) || constraint?.rejectsNonKeys === true);
+}
+function singleFieldSource(source, field) {
+	return source.fields.length === 1 && source.fields[0] === field;
+}
+function addAtom(constraint, atom, field) {
+	if (atom.op === "eq" || atom.op === "in") {
+		const values = atom.op === "eq" ? [atom.value] : Array.isArray(atom.value) ? atom.value : [];
+		if (!values.every(isValidIdbKey)) return;
+		const points = uniqueKeys(values);
+		constraint.points = constraint.points === void 0 ? points : constraint.points.filter((point) => points.some((value) => keyEquals(point, value)));
+		constraint.rejectsNonKeys = true;
+		constraint.consumed++;
+		return;
+	}
+	if (!keyTyped(field)) return;
+	if (atom.op === "startsWith") {
+		if (field?.codecId !== "idb/string@1" || typeof atom.value !== "string") return;
+		intersectBound(constraint, "lower", {
+			value: atom.value,
+			open: false
+		});
+		const upper = stringSuccessor(atom.value);
+		if (upper !== void 0) intersectBound(constraint, "upper", {
+			value: upper,
+			open: true
+		});
+		constraint.startsWith = true;
+		constraint.consumed++;
+	} else if ([
+		"gt",
+		"gte",
+		"lt",
+		"lte"
+	].includes(atom.op) && isValidIdbKey(atom.value)) {
+		const side = atom.op === "gt" || atom.op === "gte" ? "lower" : "upper";
+		const strict = atom.op === "gt" || atom.op === "lt";
+		intersectBound(constraint, side, {
+			value: atom.value,
+			open: strict
+		});
+		if (strict) constraint.rejectsNonKeys = true;
+		constraint.consumed++;
+	}
+}
+function uniqueKeys(values) {
+	const sorted = [...values].sort(compareFieldValues);
+	return sorted.filter((value, i) => i === 0 || compareFieldValues(sorted[i - 1], value) !== 0);
+}
+function intersectBound(constraint, side, bound) {
+	const previous = constraint[side];
+	const comparison = previous === void 0 ? 0 : compareFieldValues(bound.value, previous.value);
+	if (!previous || (side === "lower" ? comparison > 0 : comparison < 0) || comparison === 0 && bound.open) constraint[side] = bound;
+}
+function insideBounds(value, constraint) {
+	const lower = constraint.lower;
+	const upper = constraint.upper;
+	if (lower && (compareFieldValues(value, lower.value) < 0 || lower.open && keyEquals(value, lower.value))) return false;
+	if (upper && (compareFieldValues(value, upper.value) > 0 || upper.open && keyEquals(value, upper.value))) return false;
+	return true;
+}
+function contradictory(constraint) {
+	if (constraint.points) {
+		constraint.points = constraint.points.filter((value) => insideBounds(value, constraint));
+		return constraint.points.length === 0;
+	}
+	if (!constraint.lower || !constraint.upper) return false;
+	const comparison = compareFieldValues(constraint.lower.value, constraint.upper.value);
+	return comparison > 0 || comparison === 0 && (constraint.lower.open || constraint.upper.open);
+}
+function filteringCandidate(catalog, source, constraints, declaration) {
+	if (source.multiEntry || source.fields.length === 0) return void 0;
+	if (source.fields.some((name) => keyPartial(catalog.fields[name]) && !constraints.get(name)?.rejectsNonKeys)) return void 0;
+	let prefixes = [[]];
+	let consumed = 0;
+	let position = 0;
+	while (position < source.fields.length) {
+		const constraint = constraints.get(source.fields[position]);
+		if (constraint?.points === void 0) break;
+		if (prefixes.length * constraint.points.length > 1024) return void 0;
+		prefixes = prefixes.flatMap((prefix) => constraint.points.map((point) => [...prefix, point]));
+		consumed += constraint.consumed;
+		position++;
+	}
+	const constraint = constraints.get(source.fields[position] ?? "");
+	const hasRange = constraint !== void 0 && (constraint.lower !== void 0 || constraint.upper !== void 0);
+	if (position === 0 && !hasRange) return void 0;
+	const used = position + Number(hasRange);
+	if (!source.fields.slice(used).every((field) => completeKeyField(catalog.fields[field], constraints.get(field)))) return void 0;
+	const compound = typeof source.keyPath !== "string";
+	if (position === source.fields.length) return {
+		source,
+		ranges: prefixes.map((prefix) => ({
+			kind: "only",
+			key: compound ? prefix : prefix[0]
+		})),
+		cost: source.indexName !== void 0 && source.unique ? COST.UNIQUE_POINT : source.indexName === void 0 ? COST.PRIMARY_POINT : COST.INDEX_POINT,
+		consumed,
+		declaration
+	};
+	if (hasRange) consumed += constraint.consumed;
+	const ranges = prefixes.map((prefix) => compound ? compoundRange(prefix, constraint, source.fields.length - used) : scalarRange(constraint));
+	if (ranges.some((range) => range.kind === "bound" && (compareFieldValues(range.lower, range.upper) > 0 || keyEquals(range.lower, range.upper) && (range.lowerOpen || range.upperOpen)))) return void 0;
+	return {
+		source,
+		ranges,
+		cost: hasRange ? constraint.lower && constraint.upper && !constraint.startsWith ? COST.TWO_SIDED_RANGE : COST.ONE_SIDED_RANGE : COST.PREFIX_POINT,
+		consumed,
+		declaration
+	};
+}
+function scalarRange(constraint) {
+	if (constraint.lower && constraint.upper) return {
+		kind: "bound",
+		lower: constraint.lower.value,
+		upper: constraint.upper.value,
+		lowerOpen: constraint.lower.open,
+		upperOpen: constraint.upper.open
+	};
+	if (constraint.lower) return {
+		kind: "lower",
+		key: constraint.lower.value,
+		open: constraint.lower.open
+	};
+	return {
+		kind: "upper",
+		key: constraint.upper.value,
+		open: constraint.upper.open
+	};
+}
+function compoundRange(prefix, constraint, trailing) {
+	const lower = constraint?.lower;
+	const upper = constraint?.upper;
+	return {
+		kind: "bound",
+		lower: lower ? [
+			...prefix,
+			lower.value,
+			...lower.open && trailing > 0 ? [[]] : []
+		] : prefix.length ? prefix : [-Infinity],
+		upper: upper ? [
+			...prefix,
+			upper.value,
+			...!upper.open && trailing > 0 ? [[]] : []
+		] : [...prefix, []],
+		lowerOpen: lower?.open ?? false,
+		upperOpen: upper ? upper.open || trailing > 0 : true
+	};
+}
+function stringSuccessor(prefix) {
+	for (let i = prefix.length - 1; i >= 0; i--) {
+		const code = prefix.charCodeAt(i);
+		if (code < 65535) return prefix.slice(0, i) + String.fromCharCode(code + 1);
+	}
+}
+//#endregion
+//#region src/core/planner/lower.ts
+/**
+* Lower row access without creating IDBKeyRange objects or awaiting work.
+* Run `finish` after the executor has materialized all returned rows.
+* Without `orderBy`, row order and pagination selection are unspecified.
+* Rows tied on every ordering field may appear in any order, including at
+* pagination boundaries. Add a unique ordering field for deterministic pages.
+*/
+function lowerRows(catalog, logical, meta, request, additionalFilter) {
+	const filter = (row) => (request.where === void 0 || evaluateFilter(request.where, row)) && (additionalFilter === void 0 || additionalFilter(row));
+	const comparator = logical.direction === void 0 ? buildRowComparator(request.orderBy) : void 0;
+	const base = {
+		meta,
+		storeName: catalog.storeName
+	};
+	const pagination = {
+		...request.skip === void 0 ? {} : { skip: request.skip },
+		...request.take === void 0 ? {} : { take: request.take }
+	};
+	let shapedByDriver = false;
+	let idbPlan;
+	switch (logical.access.kind) {
+		case "empty":
+			idbPlan = {
+				meta,
+				kind: "batch",
+				storeNames: [catalog.storeName],
+				ops: []
+			};
+			break;
+		case "full":
+			idbPlan = {
+				...base,
+				kind: "cursor-scan",
+				filter,
+				...comparator === void 0 ? {} : { comparator },
+				...pagination
+			};
+			shapedByDriver = true;
+			break;
+		case "ranges": {
+			const { source } = logical.access;
+			const ranges = [...logical.access.ranges];
+			if (logical.direction === "prev") ranges.reverse();
+			const single = ranges.length === 1;
+			const ops = ranges.map((range) => {
+				if (range?.kind === "only" && source.indexName === void 0) return {
+					...base,
+					kind: "key-get",
+					key: range.key
+				};
+				const access = {
+					...base,
+					...source.indexName === void 0 ? {} : { indexName: source.indexName },
+					...range === void 0 ? {} : { range }
+				};
+				if (!single && logical.direction !== void 0 && request.take !== void 0) return {
+					...access,
+					kind: "cursor-scan",
+					direction: logical.direction,
+					filter,
+					take: (request.skip ?? 0) + request.take
+				};
+				if (single && request.take !== void 0) {
+					shapedByDriver = true;
+					return {
+						...access,
+						kind: "cursor-scan",
+						filter,
+						...logical.direction === void 0 ? {} : { direction: logical.direction },
+						...comparator === void 0 ? {} : { comparator },
+						...pagination
+					};
+				}
+				if (logical.direction === "prev") return {
+					...access,
+					kind: "cursor-scan",
+					direction: "prev",
+					filter
+				};
+				return {
+					...access,
+					kind: "get-all"
+				};
+			});
+			idbPlan = single ? ops[0] : {
+				meta,
+				kind: "batch",
+				storeNames: [catalog.storeName],
+				ops
+			};
+			break;
+		}
+	}
+	return {
+		idbPlan,
+		finish(rows) {
+			let result = rows.filter(filter);
+			if (!shapedByDriver) {
+				if (comparator !== void 0) result.sort(comparator);
+				const skip = request.skip ?? 0;
+				result = result.slice(skip, request.take === void 0 ? void 0 : skip + request.take);
+			}
+			return result;
+		}
+	};
+}
+/**
+* Lower a row count. An `exact` plan counts index entries and loads no rows.
+* The planner emits disjoint ranges on a non-multi-entry source, so each row
+* is counted once. Anything else counts the rows that pass the filter.
+* Pagination and `additionalFilter` always take the row path.
+*/
+function lowerCount(catalog, logical, meta, request, additionalFilter) {
+	const paginated = request.skip !== void 0 || request.take !== void 0;
+	if (!logical.exact || paginated || additionalFilter !== void 0) {
+		const lowered = lowerRows(catalog, logical, meta, request, additionalFilter);
+		return {
+			idbPlan: lowered.idbPlan,
+			finish: (rows) => lowered.finish(rows).length
+		};
+	}
+	return {
+		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
+			...target,
+			kind: "count"
+		}))),
+		finish: (rows) => rows.reduce((total, row) => total + row["count"], 0)
+	};
+}
+/**
+* Lower an existence check. An `exact` plan reads one primary key per range
+* and loads no rows. Anything else stops each range at its first row that
+* passes the filter.
+*/
+function lowerExists(catalog, logical, meta, request, additionalFilter) {
+	if (logical.exact && additionalFilter === void 0) return {
+		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
+			...target,
+			kind: "keys",
+			take: 1
+		}))),
+		finish: (rows) => rows.length > 0
+	};
+	const filter = (row) => (request.where === void 0 || evaluateFilter(request.where, row)) && (additionalFilter === void 0 || additionalFilter(row));
+	return {
+		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
+			...target,
+			kind: "cursor-scan",
+			filter,
+			take: 1
+		}))),
+		finish: (rows) => rows.some(filter)
+	};
+}
+/**
+* Lower writes through the same access paths as reads. If the patch touches
+* the walked key, collect every range first so moved rows cannot enter a
+* later range or change the cursor's position. Multiple ranges with a limit
+* also collect first, because the limit applies to their combined matches.
+*/
+function lowerWrite(catalog, logical, meta, request, additionalFilter) {
+	const { access } = logical;
+	const walkedFields = access.kind === "ranges" ? access.source.fields : catalog.primaryKey.fields;
+	const movesKey = request.write === "put-merged" && walkedFields.some((field) => field in (request.patch ?? {}));
+	const limitedRanges = access.kind === "ranges" && access.ranges.length > 1 && request.take !== void 0;
+	if (movesKey || limitedRanges) return {
+		kind: "collect",
+		rows: lowerRows(catalog, logical, meta, request, additionalFilter)
+	};
+	const filter = (row) => (request.where === void 0 || evaluateFilter(request.where, row)) && (additionalFilter === void 0 || additionalFilter(row));
+	return {
+		kind: "scan",
+		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
+			...target,
+			kind: "scan-write",
+			write: request.write,
+			filter,
+			...request.patch === void 0 ? {} : { patch: request.patch },
+			...request.take === void 0 ? {} : { take: request.take }
+		})))
+	};
+}
+/** One operation per planned range, in ascending key order. */
+function accessOps(catalog, meta, logical, build) {
+	const { access } = logical;
+	const base = {
+		meta,
+		storeName: catalog.storeName
+	};
+	switch (access.kind) {
+		case "empty": return [];
+		case "full": return [build(base)];
+		case "ranges": {
+			const { indexName } = access.source;
+			return access.ranges.map((range) => build({
+				...base,
+				...indexName === void 0 ? {} : { indexName },
+				...range === void 0 ? {} : { range }
+			}));
+		}
+	}
+}
+function combine(catalog, meta, ops) {
+	return ops.length === 1 ? ops[0] : {
+		meta,
+		kind: "batch",
+		storeNames: [catalog.storeName],
+		ops
+	};
+}
+//#endregion
 //#region src/core/mutation-scope.ts
 /**
 * Run a callback inside a single multi-store IDB readwrite transaction.
@@ -462,47 +1054,36 @@ async function applyChildOwnedMutation(scope, contract, parentModelName, parentR
 			const setValues = {};
 			for (const [childField, parentValue] of parentValues.entries()) setValues[childField] = parentValue;
 			const patch = applyUpdateDefaults(contract.execution?.mutations.defaults, relation.relatedStoreName, setValues, defaultsCache);
-			const filter = buildCriterionFilter(criterion);
-			const meta = makePlanMeta(contract);
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: relation.relatedStoreName,
+			const where = shorthandToFilterExpr(criterion);
+			await writeMutationRows(scope, contract, relation.relatedModelName, {
 				write: "put-merged",
 				patch,
-				filter
+				...where === void 0 ? {} : { where }
 			});
 		}
 		return;
 	}
 	const setValues = {};
 	for (const childField of parentValues.keys()) setValues[childField] = null;
-	const meta = makePlanMeta(contract);
 	if (!mutation.criteria || mutation.criteria.length === 0) {
 		const patch = applyUpdateDefaults(contract.execution?.mutations.defaults, relation.relatedStoreName, setValues, defaultsCache);
-		const parentJoinFilter = buildParentJoinFilter(parentValues);
-		await scope.execute({
-			meta,
-			kind: "scan-write",
-			storeName: relation.relatedStoreName,
+		const parentJoinWhere = buildParentJoinWhere(parentValues);
+		await writeMutationRows(scope, contract, relation.relatedModelName, {
 			write: "put-merged",
 			patch,
-			filter: parentJoinFilter
+			where: parentJoinWhere
 		});
 		return;
 	}
 	for (const criterion of mutation.criteria) {
 		const patch = applyUpdateDefaults(contract.execution?.mutations.defaults, relation.relatedStoreName, setValues, defaultsCache);
-		const criterionFilter = buildCriterionFilter(criterion);
-		const parentJoinFilter = buildParentJoinFilter(parentValues);
-		const combinedFilter = (row) => parentJoinFilter(row) && criterionFilter(row);
-		await scope.execute({
-			meta,
-			kind: "scan-write",
-			storeName: relation.relatedStoreName,
+		const criterionWhere = shorthandToFilterExpr(criterion);
+		const parentJoinWhere = buildParentJoinWhere(parentValues);
+		const where = criterionWhere === void 0 ? parentJoinWhere : andExpr([parentJoinWhere, criterionWhere]);
+		await writeMutationRows(scope, contract, relation.relatedModelName, {
 			write: "put-merged",
 			patch,
-			filter: combinedFilter
+			where
 		});
 	}
 }
@@ -545,37 +1126,56 @@ function assertNoNestedCallbacks(modelName, data) {
 async function findRowByCriterion(scope, contract, modelName, criterion) {
 	const expr = shorthandToFilterExpr(criterion);
 	if (!expr) throw new Error(`Nested connect for model "${modelName}" requires a non-empty criterion`);
-	const filter = (row) => evaluateFilter(expr, row);
-	return scanOneRow(scope, contract, modelName, filter);
+	return (await readMutationRows(scope, contract, modelName, expr, 1))[0] ?? null;
 }
 async function findFirstByFilters(scope, contract, modelName, filters) {
 	if (filters.length === 0) return null;
-	const combined = filters.length === 1 ? filters[0] : {
-		kind: "and",
-		exprs: filters
-	};
-	const filter = (row) => evaluateFilter(combined, row);
-	return scanOneRow(scope, contract, modelName, filter);
-}
-async function scanOneRow(scope, contract, modelName, filter) {
-	const storeName = getStoreName(contract, modelName);
-	const plan = {
-		meta: makePlanMeta(contract),
-		kind: "cursor-scan",
-		storeName,
-		filter,
-		take: 1
+	return (await readMutationRows(scope, contract, modelName, andExpr(filters), 1))[0] ?? null;
+}
+/** Execute lowered atomic operations without leaving the transaction's microtask chain. */
+async function executeMutationPlan(scope, plan) {
+	const plans = plan.kind === "batch" ? plan.ops : [plan];
+	const rows = [];
+	for (const op of plans) rows.push(...await scope.execute(op));
+	return rows;
+}
+/** Read mutation preimages through the planner, then reapply the original filter. */
+async function readMutationRows(scope, contract, modelName, where, take) {
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName));
+	const request = {
+		...where === void 0 ? {} : { where },
+		...take === void 0 ? {} : { take }
 	};
-	return (await scope.execute(plan))[0] ?? null;
+	const lowered = lowerRows(catalog, planQuery(catalog, request), makePlanMeta(contract), request);
+	return lowered.finish(await executeMutationPlan(scope, lowered.idbPlan));
 }
-function buildCriterionFilter(criterion) {
-	const expr = shorthandToFilterExpr(criterion);
-	if (!expr) return () => true;
-	return (row) => evaluateFilter(expr, row);
+async function writeMutationRows(scope, contract, modelName, request) {
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName));
+	const meta = makePlanMeta(contract);
+	const lowered = lowerWrite(catalog, planQuery(catalog, request), meta, request);
+	if (lowered.kind === "scan") return executeMutationPlan(scope, lowered.idbPlan);
+	const oldRows = lowered.rows.finish(await executeMutationPlan(scope, lowered.rows.idbPlan));
+	const results = [];
+	for (const row of oldRows) {
+		const key = extractKeyFromRow(row, catalog.primaryKey.keyPath);
+		const rows = await scope.execute({
+			meta,
+			storeName: catalog.storeName,
+			...request.write === "delete" ? {
+				kind: "delete",
+				key
+			} : {
+				kind: "update",
+				key,
+				patch: request.patch ?? {}
+			}
+		});
+		results.push(...rows);
+	}
+	return results;
 }
-function buildParentJoinFilter(parentValues) {
-	const pairs = [...parentValues.entries()];
-	return (row) => pairs.every(([childField, parentValue]) => fieldValuesEqual(row[childField], parentValue));
+function buildParentJoinWhere(parentValues) {
+	return andExpr([...parentValues].map(([field, value]) => fieldFilter(field, "eq", value)));
 }
 function getStoredAction(contract, modelName, relationName, kind) {
 	return (domainModelsAtDefaultNamespace(contract.domain)[modelName]?.storage)?.relations?.[relationName]?.[kind];
@@ -638,28 +1238,31 @@ function isChildEnforcementRelation(contract, modelName, def) {
 }
 /**
 * `true` if any child row matches the relation against `parentRow`'s values —
-* the existence check behind `restrict`.
+* the existence check behind `restrict`. A null value references no child.
 */
-async function childExists(scope, meta, def, parentRow) {
-	return (await scope.execute({
-		meta,
-		kind: "cursor-scan",
-		storeName: def.relatedStoreName,
-		filter: buildChildFilterFromRow(def, parentRow),
-		take: 1
-	})).length > 0;
+async function childExists(scope, contract, meta, def, parentRow) {
+	const values = def.localFields.map((field) => parentRow[field]);
+	if (values.some((value) => value === null || value === void 0)) return false;
+	return rowExists(scope, contract, meta, def.relatedStoreName, def.targetFields, values);
+}
+/**
+* Does `storeName` have a row whose `fields` equal `values`, pairwise?
+* Compares values the way IndexedDB compares keys. `additionalFilter` narrows
+* the match in memory; it makes the check read rows instead of keys.
+*/
+async function rowExists(scope, contract, meta, storeName, fields, values, additionalFilter) {
+	const where = andExpr(fields.map((field, i) => fieldFilter(field, "eq", values[i])));
+	const catalog = buildCatalog(contract, storeName);
+	const lowered = lowerExists(catalog, planQuery(catalog, { where }), meta, { where }, additionalFilter);
+	return lowered.finish(await executeMutationPlan(scope, lowered.idbPlan));
 }
 /**
 * Builds a filter matching a relation's children against one specific parent
 * row's values. Shared by `onDelete` cascade (`applyReferentialActionsForRow`)
 * and `onUpdate` cascade (`applyReferentialActionsForRowOnUpdate`).
 */
-function buildChildFilterFromRow(def, row) {
-	const pairs = def.localFields.map((lf, i) => ({
-		childField: def.targetFields[i],
-		parentValue: row[lf]
-	}));
-	return (child) => pairs.every(({ childField, parentValue }) => fieldValuesEqual(child[childField], parentValue));
+function buildChildWhereFromRow(def, row) {
+	return andExpr(def.targetFields.map((field, i) => fieldFilter(field, "eq", row[def.localFields[i]])));
 }
 /** Reads a field's literal `@default(...)` value from `IdbModelStorage.fieldDefaults`, if declared. */
 function getFieldDefault(contract, modelName, fieldName) {
@@ -790,9 +1393,9 @@ async function applyReferentialActionsForRowOnUpdate(scope, contract, modelName,
 		const changedFields = def.localFields.filter((f) => f in patch && !fieldValuesEqual(patch[f], oldRow[f]));
 		if (changedFields.length === 0) continue;
 		const action = getReferentialActionForRelation(contract, modelName, def, "onUpdate");
-		const childFilter = buildChildFilterFromRow(def, oldRow);
+		const childWhere = buildChildWhereFromRow(def, oldRow);
 		if (action === "restrict") {
-			if (await childExists(scope, meta, def, oldRow)) throw new Error(`Cannot update ${modelName} '${keyToken(extractKeyFromRow(oldRow, keyPath))}': changing field(s) ${changedFields.join(", ")} would orphan child records on relation '${def.relationName}'. Update or remove those children first, or declare onUpdate: Cascade, SetNull or SetDefault on the relation.`);
+			if (await childExists(scope, contract, meta, def, oldRow)) throw new Error(`Cannot update ${modelName} '${keyToken(extractKeyFromRow(oldRow, keyPath))}': changing field(s) ${changedFields.join(", ")} would orphan child records on relation '${def.relationName}'. Update or remove those children first, or declare onUpdate: Cascade, SetNull or SetDefault on the relation.`);
 			continue;
 		}
 		if (action === "cascade") {
@@ -802,46 +1405,32 @@ async function applyReferentialActionsForRowOnUpdate(scope, contract, modelName,
 				const tf = def.targetFields[i];
 				if (changedFields.includes(lf)) childPatch[tf] = patch[lf];
 			}
-			const children = await scope.execute({
-				meta,
-				kind: "cursor-scan",
-				storeName: def.relatedStoreName,
-				filter: childFilter
-			});
+			const children = await readMutationRows(scope, contract, def.relatedModelName, childWhere);
 			for (const child of children) await applyReferentialActionsForRowOnUpdate(scope, contract, def.relatedModelName, child, childPatch, visited);
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: def.relatedStoreName,
+			await writeMutationRows(scope, contract, def.relatedModelName, {
 				write: "put-merged",
 				patch: childPatch,
-				filter: childFilter
+				where: childWhere
 			});
 			continue;
 		}
 		if (action === "setNull") {
 			const childPatch = {};
 			for (const targetField of def.targetFields) childPatch[targetField] = null;
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: def.relatedStoreName,
+			await writeMutationRows(scope, contract, def.relatedModelName, {
 				write: "put-merged",
 				patch: childPatch,
-				filter: childFilter
+				where: childWhere
 			});
 			continue;
 		}
 		if (action === "setDefault") {
 			const childPatch = buildSetDefaultPatch(contract, def);
 			await validateSetDefaultPatch(scope, contract, modelName, def, childPatch, extractKeyFromRow(oldRow, keyPath));
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: def.relatedStoreName,
+			await writeMutationRows(scope, contract, def.relatedModelName, {
 				write: "put-merged",
 				patch: childPatch,
-				filter: childFilter
+				where: childWhere
 			});
 			continue;
 		}
@@ -903,21 +1492,13 @@ function fkCheckNeedsExistingRow(contract, modelName, data) {
 /**
 * Does `parentModel` have a row whose `fields` equal `values`, pairwise?
 *
-* Scans the parent store, comparing values the way IndexedDB compares keys.
 * `excludeKey` leaves out one parent row, for checks that run while that row
 * is being deleted or changed.
 */
 async function parentExists(scope, contract, meta, parentModel, fields, values, excludeKey) {
 	const storeName = getStoreName(contract, parentModel);
 	const keyPath = getKeyPath(contract, parentModel);
-	const filter = (row) => fields.every((f, i) => fieldValuesEqual(row[f], values[i])) && (excludeKey === void 0 || !keyEquals$1(extractKeyFromRow(row, keyPath), excludeKey));
-	return (await scope.execute({
-		meta,
-		kind: "cursor-scan",
-		storeName,
-		filter,
-		take: 1
-	})).length > 0;
+	return rowExists(scope, contract, meta, storeName, fields, values, excludeKey === void 0 ? void 0 : (row) => !keyEquals$1(extractKeyFromRow(row, keyPath), excludeKey));
 }
 /** `id='u1'`, or `orgId='a', id='u1'` for a compound key. */
 function describeTuple(fields, values) {
@@ -989,27 +1570,14 @@ async function executeScalarUpdates(options, take) {
 	return withMutationScope(executor, storeNames, async (scope) => {
 		if (!needsRowForFks) await validateScalarFks(scope, contract, modelName, patch);
 		const meta = makePlanMeta(contract);
-		const combined = filters.length === 0 ? void 0 : filters.length === 1 ? filters[0] : {
-			kind: "and",
-			exprs: filters
-		};
-		const filter = combined !== void 0 ? (row) => evaluateFilter(combined, row) : void 0;
-		if (!enforcesOnUpdate && !needsRowForFks) return scope.execute({
-			meta,
-			kind: "scan-write",
-			storeName,
+		const where = filters.length === 0 ? void 0 : andExpr(filters);
+		if (!enforcesOnUpdate && !needsRowForFks) return writeMutationRows(scope, contract, modelName, {
 			write: "put-merged",
 			patch,
-			...take !== void 0 ? { take } : {},
-			...filter !== void 0 ? { filter } : {}
-		});
-		const oldRows = await scope.execute({
-			meta,
-			kind: "cursor-scan",
-			storeName,
-			...take !== void 0 ? { take } : {},
-			...filter !== void 0 ? { filter } : {}
+			...take === void 0 ? {} : { take },
+			...where === void 0 ? {} : { where }
 		});
+		const oldRows = await readMutationRows(scope, contract, modelName, where, take);
 		const keyPath = getKeyPath(contract, modelName);
 		const results = [];
 		for (const oldRow of oldRows) {
@@ -1091,19 +1659,14 @@ async function applyReferentialActionsForRow(scope, contract, modelName, row, vi
 	for (const def of getRelationDefinitions(contract, modelName)) {
 		if (!isChildEnforcementRelation(contract, modelName, def)) continue;
 		const action = getReferentialActionForRelation(contract, modelName, def, "onDelete");
-		const childFilter = buildChildFilterFromRow(def, row);
+		const childWhere = buildChildWhereFromRow(def, row);
 		if (action === "restrict") {
-			if (await childExists(scope, meta, def, row)) throw new Error(`Cannot delete ${modelName} '${keyToken(extractKeyFromRow(row, keyPath))}': child records exist on relation '${def.relationName}'. Delete those children first, or declare onDelete: Cascade, SetNull or SetDefault on the relation.`);
+			if (await childExists(scope, contract, meta, def, row)) throw new Error(`Cannot delete ${modelName} '${keyToken(extractKeyFromRow(row, keyPath))}': child records exist on relation '${def.relationName}'. Delete those children first, or declare onDelete: Cascade, SetNull or SetDefault on the relation.`);
 			continue;
 		}
 		if (action === "cascade") {
 			const childKeyPath = getKeyPath(contract, def.relatedModelName);
-			const children = await scope.execute({
-				meta,
-				kind: "cursor-scan",
-				storeName: def.relatedStoreName,
-				filter: childFilter
-			});
+			const children = await readMutationRows(scope, contract, def.relatedModelName, childWhere);
 			for (const child of children) {
 				await applyReferentialActionsForRow(scope, contract, def.relatedModelName, child, visited);
 				await scope.execute({
@@ -1118,26 +1681,20 @@ async function applyReferentialActionsForRow(scope, contract, modelName, row, vi
 		if (action === "setNull") {
 			const patch = {};
 			for (const targetField of def.targetFields) patch[targetField] = null;
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: def.relatedStoreName,
+			await writeMutationRows(scope, contract, def.relatedModelName, {
 				write: "put-merged",
 				patch,
-				filter: childFilter
+				where: childWhere
 			});
 			continue;
 		}
 		if (action === "setDefault") {
 			const patch = buildSetDefaultPatch(contract, def);
 			await validateSetDefaultPatch(scope, contract, modelName, def, patch, extractKeyFromRow(row, keyPath));
-			await scope.execute({
-				meta,
-				kind: "scan-write",
-				storeName: def.relatedStoreName,
+			await writeMutationRows(scope, contract, def.relatedModelName, {
 				write: "put-merged",
 				patch,
-				filter: childFilter
+				where: childWhere
 			});
 			continue;
 		}
@@ -1148,12 +1705,11 @@ async function executeDeleteWithReferentialActions(options) {
 	await withMutationScope(executor, collectDeleteStoreNames(contract, modelName), async (scope) => {
 		const storeName = getStoreName(contract, modelName);
 		const meta = makePlanMeta(contract);
-		const row = (await scope.execute({
-			meta,
-			kind: "key-get",
-			storeName,
-			key
-		}))[0];
+		const keyPath = getKeyPath(contract, modelName);
+		const fields = keyPathFields(keyPath);
+		const values = typeof keyPath === "string" ? [key] : key;
+		const where = andExpr(fields.map((field, i) => fieldFilter(field, "eq", values[i])));
+		const row = (await readMutationRows(scope, contract, modelName, where, 1))[0];
 		if (!row) return [];
 		await applyReferentialActionsForRow(scope, contract, modelName, row);
 		await scope.execute({
@@ -1166,17 +1722,16 @@ async function executeDeleteWithReferentialActions(options) {
 	});
 }
 async function executeDeleteAllWithReferentialActions(options) {
-	const { executor, contract, modelName, filter } = options;
+	const { executor, contract, modelName, where } = options;
 	return withMutationScope(executor, collectDeleteStoreNames(contract, modelName), async (scope) => {
 		const storeName = getStoreName(contract, modelName);
 		const meta = makePlanMeta(contract);
 		const keyPath = getKeyPath(contract, modelName);
-		const rows = await scope.execute({
-			meta,
-			kind: "cursor-scan",
-			storeName,
-			...filter !== void 0 ? { filter } : {}
+		if (!hasEnforceableChildRelations(contract, modelName)) return writeMutationRows(scope, contract, modelName, {
+			write: "delete",
+			...where === void 0 ? {} : { where }
 		});
+		const rows = await readMutationRows(scope, contract, modelName, where);
 		for (const row of rows) {
 			await applyReferentialActionsForRow(scope, contract, modelName, row);
 			const key = extractKeyFromRow(row, keyPath);
@@ -1191,6 +1746,6 @@ async function executeDeleteAllWithReferentialActions(options) {
 	});
 }
 //#endregion
-export { keyToken as A, assertEnumValues as C, getRelation as D, getKeyPath as E, getStoreName as O, createMutationDefaultsCache as S, fieldValueToken as T, requireTransactionExecutor as _, collectScalarFkStoreNames as a, applyCreateDefaults as b, executeDeleteWithReferentialActions as c, executeScalarCreateAllWithFkValidation as d, executeScalarCreateWithFkValidation as f, hasScalarFkFields as g, hasNestedMutationCallbacks as h, collectOnUpdateEnforcementStoreNames as i, keyEquals$1 as k, executeNestedCreateMutation as l, hasEnforceableChildRelations as m, applyReferentialActionsForRowOnUpdate as n, executeBulkUpdateWithFkValidation as o, executeScalarUpdateWithFkValidation as p, collectDeleteStoreNames as r, executeDeleteAllWithReferentialActions as s, applyReferentialActionsForRow as t, executeNestedUpdateMutation as u, validateScalarFks as v, extractKeyFromRow as w, applyUpdateDefaults as x, withMutationScope as y };
+export { combineFilterExprs as A, planQuery as C, createMutationDefaultsCache as D, applyUpdateDefaults as E, getStoreName as F, keyEquals$1 as I, keyToken as L, fieldValueToken as M, getKeyPath as N, assertEnumValues as O, getRelation as P, lowerRows as S, applyCreateDefaults as T, readMutationRows as _, collectScalarFkStoreNames as a, withMutationScope as b, executeDeleteWithReferentialActions as c, executeScalarCreateAllWithFkValidation as d, executeScalarCreateWithFkValidation as f, hasScalarFkFields as g, hasNestedMutationCallbacks as h, collectOnUpdateEnforcementStoreNames as i, extractKeyFromRow as j, buildRowComparator as k, executeNestedCreateMutation as l, hasEnforceableChildRelations as m, applyReferentialActionsForRowOnUpdate as n, executeBulkUpdateWithFkValidation as o, executeScalarUpdateWithFkValidation as p, collectDeleteStoreNames as r, executeDeleteAllWithReferentialActions as s, applyReferentialActionsForRow as t, executeNestedUpdateMutation as u, requireTransactionExecutor as v, buildCatalog as w, lowerCount as x, validateScalarFks as y };
 
-//# sourceMappingURL=mutation-executor-SJqTuSbb.mjs.map
+//# sourceMappingURL=mutation-executor-inLFb0TE.mjs.map