@prisma-idb/client-idb 0.12.0 → 0.13.0

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

@@ -1,6 +1,8 @@
-import { andExpr, evaluateFilter, fieldFilter, shorthandToFilterExpr } from "@prisma-idb/adapter-idb/runtime";
+import { AsyncIterableResult } from "@prisma/orm-framework/components/runtime";
 import { domainModelsAtDefaultNamespace } from "@prisma/orm-framework/contract/types";
-import { compareFieldValues, fieldValueToken, fieldValuesEqual, isValidIdbKey, keyEquals, keyEquals as keyEquals$1, keyToken } from "@prisma-idb/target-idb/runtime";
+import { IdbExecuteError } from "@prisma-idb/driver-idb/runtime";
+import { absentAsNull, compareDecimalValues, compareFieldValues, fieldValueToken, fieldValuesEqual, isValidIdbKey, keyEquals, keyEquals as keyEquals$1, keyToken, keyToken as keyToken$1, validateRecord } from "@prisma-idb/target-idb/runtime";
+import { andExpr, assertValidDecimalFilter, evaluateFilter, fieldFilter, shorthandToFilterExpr } from "@prisma-idb/adapter-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 +52,301 @@ function getRelation(contract, modelName, relName) {
 	return relation;
 }
 //#endregion
+//#region src/core/planner/catalog.ts
+const catalogs = /* @__PURE__ */ new WeakMap();
+/**
+* Build a catalog once per contract identity, store name and model name.
+* Contracts are immutable.
+*
+* Several models can share one store, and each reads the rows differently.
+* Pass the model that owns the request. Omit `modelName` for a store that no
+* app model owns, such as an extension's own store: it has no fields to fill.
+*/
+function buildCatalog(contract, storeName, modelName) {
+	const cacheKey = `${storeName}\0${modelName ?? ""}`;
+	const cached = catalogs.get(contract)?.get(cacheKey);
+	if (cached) return cached;
+	const store = contract.storage.stores[storeName];
+	if (!store) throw new Error(`Store "${storeName}" is not in the contract`);
+	const fields = {};
+	let normalize = (row) => row;
+	if (modelName !== void 0) {
+		const model = domainModelsAtDefaultNamespace(contract.domain)[modelName];
+		if (model === void 0) throw new Error(`Model "${modelName}" is not in the contract`);
+		if (getStoreName(contract, modelName) !== storeName) throw new Error(`Model "${modelName}" is not stored in "${storeName}"`);
+		normalize = absentAsNull(contract, modelName);
+		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: Boolean(field.many) || 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),
+		absentAsNull: normalize
+	});
+	let byStore = catalogs.get(contract);
+	if (!byStore) {
+		byStore = /* @__PURE__ */ new Map();
+		catalogs.set(contract, byStore);
+	}
+	byStore.set(cacheKey, catalog);
+	return catalog;
+}
+/** Freeze a key source and its field order for deterministic access selection. */
+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/decimal-identity.ts
+/** A legacy store or sync metadata set contains several spellings of one Decimal key. */
+var IdbDecimalIdentityConflictError = class extends Error {
+	code = "DECIMAL_IDENTITY_CONFLICT";
+	constructor(modelName) {
+		super(`Several stored keys identify the same Decimal value in model "${modelName}". Resolve the conflicting records before retrying.`);
+		this.name = "IdbDecimalIdentityConflictError";
+	}
+};
+/** Whether a primary key contains a contract-declared Decimal field. */
+function hasDecimalPrimaryKey(contract, modelName) {
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
+	return hasDecimalFields(catalog, catalog.primaryKey);
+}
+/** Compare scalar or compound primary keys using Decimal codecs and native IDB equality elsewhere. */
+function decimalKeysEqual(contract, modelName, left, right) {
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
+	const leftParts = typeof catalog.primaryKey.keyPath === "string" ? [left] : left;
+	const rightParts = typeof catalog.primaryKey.keyPath === "string" ? [right] : right;
+	if (!Array.isArray(leftParts) || !Array.isArray(rightParts) || leftParts.length !== catalog.primaryKey.fields.length || rightParts.length !== leftParts.length) return false;
+	return catalog.primaryKey.fields.every((field, i) => valuesEqual(catalog, field, leftParts[i], rightParts[i]));
+}
+/** Keep an existing Decimal primary-key spelling when the supplied value identifies the same row. */
+function preserveDecimalKeySpelling(contract, modelName, record, storedKey) {
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
+	const parts = typeof catalog.primaryKey.keyPath === "string" ? [storedKey] : storedKey;
+	if (!Array.isArray(parts) || parts.length !== catalog.primaryKey.fields.length) return record;
+	const result = { ...record };
+	catalog.primaryKey.fields.forEach((field, i) => {
+		if (catalog.fields[field]?.codecId === "idb/decimal@1" && result[field] !== void 0 && valuesEqual(catalog, field, result[field], parts[i])) result[field] = parts[i];
+	});
+	return result;
+}
+/** Read the physical key first, then check Decimal aliases without choosing a legacy duplicate. */
+async function resolveDecimalKey(scope, contract, modelName, key, snapshot) {
+	if (!isValidIdbKey(key)) return void 0;
+	const storeName = getStoreName(contract, modelName);
+	const decimal = hasDecimalPrimaryKey(contract, modelName);
+	if (decimal && !decimalKeysEqual(contract, modelName, key, key)) return void 0;
+	if (!snapshot) {
+		const [exact] = await scope.execute({
+			kind: "key-get",
+			storeName,
+			key
+		});
+		if (!decimal) return exact;
+	}
+	const matches = (snapshot ?? await scope.execute({
+		kind: "cursor-scan",
+		storeName
+	})).filter((row) => decimalKeysEqual(contract, modelName, extractKeyFromRow(row, buildCatalog(contract, storeName, modelName).primaryKey.keyPath), key));
+	if (matches.length > 1) throw new IdbDecimalIdentityConflictError(modelName);
+	return matches[0];
+}
+/** Whether this key source needs numeric equality instead of the native string index. */
+function hasDecimalFields(catalog, source) {
+	return source.fields.some((field) => catalog.fields[field]?.codecId === "idb/decimal@1");
+}
+/** Compare one declared scalar without converting Decimal text through Number. */
+function valuesEqual(catalog, field, left, right) {
+	return catalog.fields[field]?.codecId === "idb/decimal@1" ? typeof left === "string" && typeof right === "string" && compareDecimalValues(left, right) === 0 : isValidIdbKey(left) && isValidIdbKey(right) && keyEquals(left, right);
+}
+/** Numeric unique sources only; ordinary native indexes continue to enforce their own constraints. */
+function decimalUniqueSources(catalog) {
+	return [catalog.primaryKey, ...catalog.indexes].filter((source) => source.unique && hasDecimalFields(catalog, source));
+}
+/** Match one index entry, excluding absent/null keys just as IndexedDB does. */
+function sourceCollides(catalog, source, left, right) {
+	if (source.multiEntry && source.fields.length === 1) {
+		const field = source.fields[0];
+		const a = Array.isArray(left[field]) ? left[field] : [left[field]];
+		const b = Array.isArray(right[field]) ? right[field] : [right[field]];
+		return a.some((x) => b.some((y) => valuesEqual(catalog, field, x, y)));
+	}
+	return source.fields.every((field) => valuesEqual(catalog, field, left[field], right[field]));
+}
+/** Check new values against every other physical row inside the write transaction. */
+async function assertUnique(scope, catalog, record, previousKey, kind, modelName, snapshot) {
+	const rows = snapshot ?? await scope.execute({
+		kind: "cursor-scan",
+		storeName: catalog.storeName
+	});
+	const previous = rows.find((row) => previousKey !== void 0 && keyEquals(extractKeyFromRow(row, catalog.primaryKey.keyPath), previousKey));
+	for (const source of decimalUniqueSources(catalog)) {
+		const matches = rows.filter((row) => sourceCollides(catalog, source, row, record));
+		if (matches.length > 1 || previous && rows.filter((row) => sourceCollides(catalog, source, row, previous)).length > 1) throw new IdbDecimalIdentityConflictError(modelName);
+		if (matches.some((row) => previousKey === void 0 || !keyEquals(extractKeyFromRow(row, catalog.primaryKey.keyPath), previousKey))) throw new IdbExecuteError({
+			code: kind === "add" ? "ADD_FAILED" : "PUT_FAILED",
+			planKind: kind,
+			storeName: catalog.storeName,
+			cause: new DOMException("Numerically equal Decimal key already exists", "ConstraintError")
+		}, "Unique constraint failed for a Decimal key");
+	}
+}
+const decimalModelCache = /* @__PURE__ */ new WeakMap();
+/** Cache the contract models whose uniqueness needs more than native string indexes. */
+function decimalModels(contract) {
+	const cached = decimalModelCache.get(contract);
+	if (cached) return cached;
+	const models = /* @__PURE__ */ new Map();
+	for (const modelName of Object.keys(domainModelsAtDefaultNamespace(contract.domain))) {
+		const store = getStoreName(contract, modelName);
+		if (decimalUniqueSources(buildCatalog(contract, store, modelName)).length > 0) models.set(store, modelName);
+	}
+	decimalModelCache.set(contract, models);
+	return models;
+}
+/** Wrap the transaction seam so nested, bulk and raw sync writes share the same identity rules. */
+function withDecimalIdentityScope(scope, contract) {
+	const models = decimalModels(contract);
+	if (models.size === 0) return scope;
+	return {
+		commit: () => scope.commit(),
+		rollback: () => scope.rollback(),
+		async execute(plan) {
+			const modelName = models.get(plan.storeName);
+			if (modelName === void 0) return scope.execute(plan);
+			try {
+				return await executeDecimalWrite(scope, contract, modelName, plan);
+			} catch (error) {
+				scope.rollback();
+				throw error;
+			}
+		}
+	};
+}
+/** Resolve a keyed write or materialize a scan before enforcing its numeric constraints. */
+async function executeDecimalWrite(scope, contract, modelName, plan, snapshot) {
+	const catalog = buildCatalog(contract, plan.storeName, modelName);
+	if (plan.kind === "scan-write") return executeDecimalScanWrite(scope, contract, modelName, plan);
+	if (plan.kind === "delete") {
+		if (!isValidIdbKey(plan.key)) return scope.execute(plan);
+		const row = await resolveDecimalKey(scope, contract, modelName, plan.key, snapshot);
+		return scope.execute({
+			...plan,
+			key: row ? extractKeyFromRow(row, catalog.primaryKey.keyPath) : plan.key
+		});
+	}
+	if (plan.kind !== "add" && plan.kind !== "put" && plan.kind !== "update") return scope.execute(plan);
+	const key = plan.kind === "update" ? plan.key : extractKeyFromRow(plan.record, catalog.primaryKey.keyPath);
+	const previous = plan.kind === "add" ? void 0 : await resolveDecimalKey(scope, contract, modelName, key, snapshot);
+	const previousKey = previous && extractKeyFromRow(previous, catalog.primaryKey.keyPath);
+	const record = preserveDecimalKeySpelling(contract, modelName, plan.kind === "update" ? {
+		...previous,
+		...plan.patch
+	} : plan.record, previousKey);
+	await assertUnique(scope, catalog, record, previousKey, plan.kind, modelName, snapshot);
+	return scope.execute(plan.kind === "update" ? {
+		...plan,
+		key: previousKey ?? plan.key,
+		patch: preserveDecimalKeySpelling(contract, modelName, plan.patch, previousKey)
+	} : {
+		...plan,
+		record
+	});
+}
+/** Materialize preimages once so moving indexed fields cannot revisit a row. */
+async function executeDecimalScanWrite(scope, contract, modelName, plan) {
+	const catalog = buildCatalog(contract, plan.storeName, modelName);
+	const { take, ...scan } = plan;
+	const rows = await scope.execute({
+		...scan,
+		kind: "cursor-scan"
+	});
+	const seen = /* @__PURE__ */ new Set();
+	const matches = rows.filter((row) => {
+		const token = keyToken(extractKeyFromRow(row, catalog.primaryKey.keyPath));
+		if (seen.has(token)) return false;
+		seen.add(token);
+		return true;
+	}).slice(0, take);
+	if (matches.length === 0) return [];
+	const snapshot = !plan.indexName && !plan.range && !plan.filter ? [...rows] : await scope.execute({
+		kind: "cursor-scan",
+		storeName: plan.storeName
+	});
+	const result = [];
+	for (const row of matches) {
+		const key = extractKeyFromRow(row, catalog.primaryKey.keyPath);
+		const written = await executeDecimalWrite(scope, contract, modelName, plan.write === "delete" ? {
+			...plan,
+			kind: "delete",
+			key
+		} : {
+			...plan,
+			kind: "update",
+			key,
+			patch: plan.patch ?? {}
+		}, snapshot);
+		result.push(...written);
+		const index = snapshot.findIndex((stored) => keyEquals(extractKeyFromRow(stored, catalog.primaryKey.keyPath), key));
+		if (index >= 0) snapshot.splice(index, 1, ...plan.write === "delete" ? [] : written);
+		else if (plan.write !== "delete") snapshot.push(...written);
+	}
+	return result;
+}
+/** Decorate only Decimal-key mutations; all other queries retain their existing execution path. */
+function withDecimalIdentityExecutor(contract, executor) {
+	const models = decimalModels(contract);
+	if (models.size === 0) return executor;
+	const inner = executor;
+	/** Only mutations of declared Decimal key sources need a transaction wrapper. */
+	const needsCheck = (plan) => {
+		if (![
+			"add",
+			"put",
+			"update",
+			"delete",
+			"scan-write"
+		].includes(plan.kind)) return false;
+		return models.has(plan.storeName);
+	};
+	/** Keep validation and the write under the caller's transaction and sync interceptor. */
+	const transaction = async (stores, mode) => {
+		if (typeof inner.transaction !== "function") throw new Error("Decimal key mutations require a transaction-capable executor");
+		return withDecimalIdentityScope(await inner.transaction(stores, mode), contract);
+	};
+	return {
+		...typeof inner.transaction === "function" ? { transaction } : {},
+		query(plan) {
+			const body = plan.idbPlan;
+			const ops = body.kind === "batch" ? body.ops : [body];
+			if (!ops.some(needsCheck)) return executor.query(plan);
+			return new AsyncIterableResult((async function* () {
+				const scope = await transaction(body.kind === "batch" ? [...body.storeNames] : [body.storeName], "readwrite");
+				try {
+					const rows = [];
+					for (const op of ops) rows.push(...await scope.execute(op));
+					await scope.commit();
+					for (const row of rows) yield row;
+				} catch (error) {
+					scope.rollback();
+					throw error;
+				}
+			})());
+		}
+	};
+}
+//#endregion
 //#region src/core/query-shaping.ts
 /**
 * Combine accumulated filter expressions with AND.
@@ -67,15 +364,19 @@ function combineFilterExprs(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
+* declaration order. Decimal fields use exact numeric order; other fields
+* use {@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) {
+function buildRowComparator(orderBy, fields = {}) {
 	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]);
+			const metadata = fields[field];
+			const decimal = metadata?.codecId === "idb/decimal@1" && !metadata.collection;
+			const present = a[field] != null && b[field] != null;
+			const cmp = decimal && present ? compareDecimalValues(a[field], b[field]) : compareFieldValues(a[field], b[field]);
 			if (cmp === 0) continue;
 			return dir === "desc" ? -cmp : cmp;
 		}
@@ -85,6 +386,7 @@ function buildRowComparator(orderBy) {
 //#endregion
 //#region src/core/enum-validation.ts
 const rulesByContract = /* @__PURE__ */ new WeakMap();
+/** Resolve an enum reference against its declared namespace before validating writes. */
 function resolveEnumRule(contract, field) {
 	const ref = field.valueSet;
 	if (ref === void 0 || ref.plane !== "domain" || ref.entityKind !== "enum") return void 0;
@@ -94,9 +396,11 @@ function resolveEnumRule(contract, field) {
 		enumName: ref.entityName,
 		values: new Set(contractEnum.members.map((member) => member.value)),
 		nullable: field.nullable,
-		many: field.many === true
+		many: Boolean(field.many),
+		elementNullable: typeof field.many === "object" && field.many.elementNullable === true
 	};
 }
+/** Cache enum rules by contract identity and model to avoid rebuilding them for each write. */
 function getModelEnumRules(contract, modelName) {
 	let byModel = rulesByContract.get(contract);
 	if (byModel === void 0) {
@@ -117,6 +421,7 @@ function getModelEnumRules(contract, modelName) {
 function describe(value) {
 	return typeof value === "string" ? JSON.stringify(value) : `${String(value)} (${typeof value})`;
 }
+/** Describe an invalid enum value together with the declared alternatives. */
 function invalidValueError(modelName, fieldName, rule, value) {
 	const expected = [...rule.values].map((v) => JSON.stringify(v)).join(", ");
 	return /* @__PURE__ */ new Error(`Invalid value ${describe(value)} for enum field "${modelName}.${fieldName}". Expected one of enum "${rule.enumName}": ${expected}.`);
@@ -125,7 +430,7 @@ function invalidValueError(modelName, fieldName, rule, value) {
 * Throws if `data` sets an enum field to a value its enum doesn't declare.
 * Fields left `undefined` are not checked. `null` is accepted only on an
 * optional (`Role?`) field; a list (`Role[]`) field must be an array whose
-* every element is a declared value.
+* every element is a declared value, or `null` when the list allows nullable elements.
 */
 function assertEnumValues(contract, modelName, data) {
 	const rules = getModelEnumRules(contract, modelName);
@@ -139,19 +444,49 @@ function assertEnumValues(contract, modelName, data) {
 		}
 		if (rule.many) {
 			if (!Array.isArray(value)) throw new Error(`Enum list field "${modelName}.${fieldName}" expects an array of "${rule.enumName}" values, got ${describe(value)}.`);
-			for (const element of value) if (!rule.values.has(element)) throw invalidValueError(modelName, fieldName, rule, element);
+			for (const element of value) {
+				if (element === null && rule.elementNullable) continue;
+				if (!rule.values.has(element)) throw invalidValueError(modelName, fieldName, rule, element);
+			}
 			continue;
 		}
 		if (!rule.values.has(value)) throw invalidValueError(modelName, fieldName, rule, value);
 	}
 }
 //#endregion
+//#region src/core/record-validation.ts
+/** A local ORM create or update failed the contract's native record validation. */
+var IdbRecordValidationError = class extends Error {
+	modelName;
+	operation;
+	issues;
+	constructor(modelName, operation, issues) {
+		super(`Invalid ${operation} record for "${modelName}": ${issues.join("; ")}`);
+		this.modelName = modelName;
+		this.operation = operation;
+		this.issues = issues;
+		this.name = "IdbRecordValidationError";
+	}
+};
+/** Validate final write data, after defaults and relation scalar values are resolved. */
+function assertValidRecord(contract, modelName, operation, data) {
+	const keyPath = getKeyPath(contract, modelName);
+	const store = contract.storage.stores[getStoreName(contract, modelName)];
+	const optionalFields = operation === "create" && store?.autoIncrement && typeof keyPath === "string" && !Object.hasOwn(data, keyPath) ? [keyPath] : [];
+	const result = validateRecord(contract, modelName, data, {
+		partial: operation === "update",
+		optionalFields
+	});
+	if (!result.ok) throw new IdbRecordValidationError(modelName, operation, result.issues);
+}
+//#endregion
 //#region src/core/mutation-defaults.ts
 function createMutationDefaultsCache() {
 	return /* @__PURE__ */ new Map();
 }
 /** Generator ids whose value is shared across an entire top-level call. Every other id always regenerates. */
 const CACHEABLE_GENERATOR_IDS = /* @__PURE__ */ new Set(["timestampNow"]);
+/** Resolve one declared default with the same generator IDs as the SQL execution layer. */
 function computeGeneratedValue(spec) {
 	const id = spec.id;
 	switch (id) {
@@ -166,6 +501,7 @@ function computeGeneratedValue(spec) {
 		default: throw new Error(`Unknown mutation-default generator id "${String(id)}"`);
 	}
 }
+/** Share query-stable defaults across one mutation while generating fresh IDs for each field. */
 function resolveGeneratedValue(spec, cache) {
 	const id = spec.id;
 	if (!CACHEABLE_GENERATOR_IDS.has(id)) return computeGeneratedValue(spec);
@@ -184,14 +520,25 @@ function applyCreateDefaults(defaults, storeName, data, cache) {
 	if (!defaults || defaults.length === 0) return data;
 	let result = data;
 	for (const d of defaults) {
-		if (d.ref.table !== storeName || !d.onCreate) continue;
-		if (result[d.ref.column] !== void 0) continue;
+		if (d.ref.entry !== storeName || !d.onCreate) continue;
+		if (result[d.ref.field] !== void 0) continue;
 		if (result === data) result = { ...data };
-		result[d.ref.column] = resolveGeneratedValue(d.onCreate, cache);
+		result[d.ref.field] = resolveGeneratedValue(d.onCreate, cache);
 	}
 	return result;
 }
 /**
+* Completes a create record: applies the `onCreate` defaults, then stores
+* `null` for every nullable field the record still lacks. IndexedDB has no
+* column defaults, so this is what keeps stored rows complete while the create
+* input leaves nullable fields optional, as Prisma's does. Call it after any
+* relation values are resolved into `data`, and validate the result.
+*/
+function completeCreateRecord(contract, modelName, data, cache) {
+	const withDefaults = applyCreateDefaults(contract.execution?.mutations.defaults, getStoreName(contract, modelName), data, cache);
+	return absentAsNull(contract, modelName)(withDefaults);
+}
+/**
 * Fills in every column with an `onUpdate` default that `patch` doesn't
 * already set. A patch with no defined values (empty, or every field
 * explicitly `undefined`) is returned unchanged — no write means no default
@@ -203,56 +550,14 @@ function applyUpdateDefaults(defaults, storeName, patch, cache) {
 	if (!defaults || defaults.length === 0) return patch;
 	let result = patch;
 	for (const d of defaults) {
-		if (d.ref.table !== storeName || !d.onUpdate) continue;
-		if (result[d.ref.column] !== void 0) continue;
+		if (d.ref.entry !== storeName || !d.onUpdate) continue;
+		if (result[d.ref.field] !== void 0) continue;
 		if (result === patch) result = { ...patch };
-		result[d.ref.column] = resolveGeneratedValue(d.onUpdate, cache);
+		result[d.ref.field] = resolveGeneratedValue(d.onUpdate, 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,
@@ -269,11 +574,11 @@ const KEY_CODECS = /* @__PURE__ */ new Set([
 	"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) {
+	if (request.where !== void 0) assertValidDecimalFilter(request.where, catalog.fields);
 	const normalized = normalize(request.where);
 	if (normalized.empty) return {
 		access: { kind: "empty" },
@@ -312,7 +617,7 @@ function planQuery(catalog, request) {
 	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";
+			if (catalog.fields[field]?.codecId !== "idb/decimal@1" && sourceOrdersField(selected.source, field, constraints)) direction = order === "asc" ? "next" : "prev";
 		} else {
 			const ordering = sources.find((source) => !source.multiEntry && singleFieldSource(source, field) && completeKeyField(catalog.fields[field]));
 			if (ordering) {
@@ -347,6 +652,7 @@ function full(exact) {
 		exact
 	};
 }
+/** Flatten supported conjunctions and same-field unions while retaining unsupported predicates. */
 function normalize(where) {
 	const result = {
 		atoms: [],
@@ -354,6 +660,7 @@ function normalize(where) {
 		excluded: false,
 		empty: false
 	};
+	/** Collect usable atoms and mark filters that require the full-row path. */
 	function visit(expr) {
 		switch (expr.kind) {
 			case "field":
@@ -404,10 +711,17 @@ function keyPartial(field) {
 function completeKeyField(field, constraint) {
 	return keyTyped(field) && field?.nullable === false && (!keyPartial(field) || constraint?.rejectsNonKeys === true);
 }
+/** A compound cursor orders a suffix only within one fixed preceding key. */
+function sourceOrdersField(source, field, constraints) {
+	const position = source.fields.indexOf(field);
+	return position >= 0 && source.fields.slice(0, position).every((name) => constraints.get(name)?.points?.length === 1);
+}
 function singleFieldSource(source, field) {
 	return source.fields.length === 1 && source.fields[0] === field;
 }
+/** Intersect one supported predicate with a field constraint without narrowing unsafe values. */
 function addAtom(constraint, atom, field) {
+	if (field?.codecId === "idb/decimal@1") return;
 	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;
@@ -451,11 +765,13 @@ function uniqueKeys(values) {
 	const sorted = [...values].sort(compareFieldValues);
 	return sorted.filter((value, i) => i === 0 || compareFieldValues(sorted[i - 1], value) !== 0);
 }
+/** Keep the tighter endpoint when several comparisons constrain the same field. */
 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;
 }
+/** Check a point against both endpoints, including open-bound equality. */
 function insideBounds(value, constraint) {
 	const lower = constraint.lower;
 	const upper = constraint.upper;
@@ -463,6 +779,7 @@ function insideBounds(value, constraint) {
 	if (upper && (compareFieldValues(value, upper.value) > 0 || upper.open && keyEquals(value, upper.value))) return false;
 	return true;
 }
+/** Discard points outside the bounds and detect ranges that cannot match. */
 function contradictory(constraint) {
 	if (constraint.points) {
 		constraint.points = constraint.points.filter((value) => insideBounds(value, constraint));
@@ -472,6 +789,7 @@ function contradictory(constraint) {
 	const comparison = compareFieldValues(constraint.lower.value, constraint.upper.value);
 	return comparison > 0 || comparison === 0 && (constraint.lower.open || constraint.upper.open);
 }
+/** Build a safe source range only when its index contains every possible match. */
 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;
@@ -513,6 +831,7 @@ function filteringCandidate(catalog, source, constraints, declaration) {
 		declaration
 	};
 }
+/** Convert scalar endpoints into the matching driver range descriptor. */
 function scalarRange(constraint) {
 	if (constraint.lower && constraint.upper) return {
 		kind: "bound",
@@ -532,6 +851,7 @@ function scalarRange(constraint) {
 		open: constraint.upper.open
 	};
 }
+/** Bound a compound prefix and suffix using IndexedDB key ordering. */
 function compoundRange(prefix, constraint, trailing) {
 	const lower = constraint?.lower;
 	const upper = constraint?.upper;
@@ -551,6 +871,7 @@ function compoundRange(prefix, constraint, trailing) {
 		upperOpen: upper ? upper.open || trailing > 0 : true
 	};
 }
+/** Find the exclusive upper bound of a UTF-16 prefix, if one exists. */
 function stringSuccessor(prefix) {
 	for (let i = prefix.length - 1; i >= 0; i--) {
 		const code = prefix.charCodeAt(i);
@@ -560,6 +881,17 @@ function stringSuccessor(prefix) {
 //#endregion
 //#region src/core/planner/lower.ts
 /**
+* The row filter shared by every lowered read and write. The driver runs it on stored rows, so it
+* reads each row as the contract describes it first: a filter on `null` matches a row that
+* lacks the field.
+*/
+function rowFilter(catalog, request, additionalFilter) {
+	return (stored) => {
+		const row = catalog.absentAsNull(stored);
+		return (request.where === void 0 || evaluateFilter(request.where, row, catalog.fields)) && (additionalFilter === void 0 || additionalFilter(row));
+	};
+}
+/**
 * 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.
@@ -567,8 +899,8 @@ function stringSuccessor(prefix) {
 * 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 filter = request.where === void 0 && additionalFilter === void 0 ? void 0 : rowFilter(catalog, request, additionalFilter);
+	const comparator = logical.direction === void 0 ? buildRowComparator(request.orderBy, catalog.fields) : void 0;
 	const base = {
 		meta,
 		storeName: catalog.storeName
@@ -592,7 +924,7 @@ function lowerRows(catalog, logical, meta, request, additionalFilter) {
 			idbPlan = {
 				...base,
 				kind: "cursor-scan",
-				filter,
+				...filter === void 0 ? {} : { filter },
 				...comparator === void 0 ? {} : { comparator },
 				...pagination
 			};
@@ -618,7 +950,7 @@ function lowerRows(catalog, logical, meta, request, additionalFilter) {
 					...access,
 					kind: "cursor-scan",
 					direction: logical.direction,
-					filter,
+					...filter === void 0 ? {} : { filter },
 					take: (request.skip ?? 0) + request.take
 				};
 				if (single && request.take !== void 0) {
@@ -626,7 +958,7 @@ function lowerRows(catalog, logical, meta, request, additionalFilter) {
 					return {
 						...access,
 						kind: "cursor-scan",
-						filter,
+						...filter === void 0 ? {} : { filter },
 						...logical.direction === void 0 ? {} : { direction: logical.direction },
 						...comparator === void 0 ? {} : { comparator },
 						...pagination
@@ -636,7 +968,7 @@ function lowerRows(catalog, logical, meta, request, additionalFilter) {
 					...access,
 					kind: "cursor-scan",
 					direction: "prev",
-					filter
+					...filter === void 0 ? {} : { filter }
 				};
 				return {
 					...access,
@@ -654,8 +986,10 @@ function lowerRows(catalog, logical, meta, request, additionalFilter) {
 	}
 	return {
 		idbPlan,
+		/** Normalize returned rows and apply filtering and shaping not already handled by the driver. */
 		finish(rows) {
-			let result = rows.filter(filter);
+			let result = rows.map(catalog.absentAsNull);
+			if (filter !== void 0) result = result.filter(filter);
 			if (!shapedByDriver) {
 				if (comparator !== void 0) result.sort(comparator);
 				const skip = request.skip ?? 0;
@@ -702,7 +1036,7 @@ function lowerExists(catalog, logical, meta, request, additionalFilter) {
 		}))),
 		finish: (rows) => rows.length > 0
 	};
-	const filter = (row) => (request.where === void 0 || evaluateFilter(request.where, row)) && (additionalFilter === void 0 || additionalFilter(row));
+	const filter = rowFilter(catalog, request, additionalFilter);
 	return {
 		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
 			...target,
@@ -728,7 +1062,7 @@ function lowerWrite(catalog, logical, meta, request, additionalFilter) {
 		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));
+	const filter = rowFilter(catalog, request, additionalFilter);
 	return {
 		kind: "scan",
 		idbPlan: combine(catalog, meta, accessOps(catalog, meta, logical, (target) => ({
@@ -794,8 +1128,10 @@ async function withMutationScope(executor, storeNames, run) {
 }
 //#endregion
 //#region src/core/relation-mutator.ts
+/** Build the relation descriptors consumed by the nested-write executor. */
 function createRelationMutator() {
 	return {
+		/** Normalize a single nested record or a list into one create descriptor. */
 		create(data) {
 			return {
 				kind: "create",
@@ -827,6 +1163,7 @@ function isRelationMutationCallback(value) {
 }
 //#endregion
 //#region src/core/mutation-executor.ts
+/** Plan metadata for the raw plans the mutation executor issues itself, outside any accessor's grouping key. */
 function makePlanMeta(contract) {
 	return {
 		target: "idb",
@@ -836,6 +1173,7 @@ function makePlanMeta(contract) {
 	};
 }
 const relationDefsCache = /* @__PURE__ */ new WeakMap();
+/** Cache reference-relation metadata by contract identity and model. */
 function getRelationDefinitions(contract, modelName) {
 	let perContract = relationDefsCache.get(contract);
 	if (!perContract) {
@@ -886,6 +1224,7 @@ function requireTransactionExecutor(executor) {
 	if (typeof executor.transaction !== "function") throw new Error("This operation requires an executor with transaction support (nested relation writes, FK-validated create/update, and referential-action delete all need it). Use IdbRuntime (createIdbRuntime or createAutoMigratingIdbClient) instead of a plain IdbQueryExecutor.");
 	return executor;
 }
+/** Create a parent and its nested related rows in one transaction. */
 async function executeNestedCreateMutation(options) {
 	const { executor, contract, modelName, data } = options;
 	const record = data;
@@ -893,6 +1232,7 @@ async function executeNestedCreateMutation(options) {
 	const defaultsCache = createMutationDefaultsCache();
 	return withMutationScope(executor, storeNames, (scope) => createGraph(scope, contract, modelName, record, defaultsCache));
 }
+/** Update the first filtered parent and its nested relations in one transaction. */
 async function executeNestedUpdateMutation(options) {
 	const { executor, contract, modelName, filters, data } = options;
 	const record = data;
@@ -932,6 +1272,7 @@ function collectStoreNames(contract, modelName, data, kind) {
 function fkParentStoreNames(contract, modelName) {
 	return getRelationDefinitions(contract, modelName).filter((def) => def.cardinality === "N:1").map((def) => def.relatedStoreName);
 }
+/** Resolve parent-owned references before inserting the parent, then write its children. */
 async function createGraph(scope, contract, modelName, input, defaultsCache) {
 	const parsed = parseMutationInput(contract, modelName, input);
 	const { parentOwned, childOwned } = partitionByOwnership(parsed.relationMutations);
@@ -947,6 +1288,7 @@ async function createGraph(scope, contract, modelName, input, defaultsCache) {
 	}
 	return parentRow;
 }
+/** Read the parent before resolving relation mutations and validating its scalar patch. */
 async function updateFirstGraph(scope, contract, modelName, filters, input, defaultsCache) {
 	const existingRow = await findFirstByFilters(scope, contract, modelName, filters);
 	if (!existingRow) return null;
@@ -961,6 +1303,7 @@ async function updateFirstGraph(scope, contract, modelName, filters, input, defa
 		const meta = makePlanMeta(contract);
 		const patch = applyUpdateDefaults(contract.execution?.mutations.defaults, storeName, scalarData, defaultsCache);
 		assertEnumValues(contract, modelName, patch);
+		assertValidRecord(contract, modelName, "update", patch);
 		await validateScalarFks(scope, contract, modelName, patch, existingRow);
 		await applyReferentialActionsForRowOnUpdate(scope, contract, modelName, existingRow, patch);
 		const updated = (await scope.execute({
@@ -970,11 +1313,12 @@ async function updateFirstGraph(scope, contract, modelName, filters, input, defa
 			key,
 			patch
 		}))[0];
-		if (updated) parentRow = updated;
+		if (updated) parentRow = absentAsNull(contract, modelName)(updated);
 	}
 	for (const item of childOwned) await applyChildOwnedMutation(scope, contract, modelName, parentRow, item.relation, item.mutation, defaultsCache);
 	return parentRow;
 }
+/** Separate scalar values from validated relation callback results. */
 function parseMutationInput(contract, modelName, input) {
 	const scalarData = {};
 	const relationDefs = new Map(getRelationDefinitions(contract, modelName).map((r) => [r.relationName, r]));
@@ -998,6 +1342,7 @@ function parseMutationInput(contract, modelName, input) {
 		relationMutations
 	};
 }
+/** Separate relations whose foreign keys belong to the parent from those owned by children. */
 function partitionByOwnership(mutations) {
 	const parentOwned = [];
 	const childOwned = [];
@@ -1014,6 +1359,7 @@ function partitionByOwnership(mutations) {
 		childOwned
 	};
 }
+/** Resolve a to-one mutation into scalar foreign-key values on the parent. */
 async function applyParentOwnedMutation(scope, contract, scalarData, relation, mutation, defaultsCache) {
 	if (mutation.kind === "disconnect") {
 		for (const localField of relation.localFields) scalarData[localField] = null;
@@ -1031,6 +1377,7 @@ async function applyParentOwnedMutation(scope, contract, scalarData, relation, m
 	if (!relatedRow) throw new Error(`connect() nested mutation for relation "${relation.relationName}" did not find a matching row`);
 	copyRelatedValuesToParent(relation, scalarData, relatedRow);
 }
+/** Copy each referenced value into the matching local foreign-key field. */
 function copyRelatedValuesToParent(relation, scalarData, relatedRow) {
 	for (let i = 0; i < relation.localFields.length; i++) {
 		const localField = relation.localFields[i];
@@ -1039,6 +1386,7 @@ function copyRelatedValuesToParent(relation, scalarData, relatedRow) {
 		scalarData[localField] = relatedRow[targetField];
 	}
 }
+/** Create, connect, or disconnect children using the persisted parent join values. */
 async function applyChildOwnedMutation(scope, contract, parentModelName, parentRow, relation, mutation, defaultsCache) {
 	const parentValues = readParentColumnValues(parentModelName, relation, parentRow);
 	if (mutation.kind === "create") {
@@ -1087,6 +1435,7 @@ async function applyChildOwnedMutation(scope, contract, parentModelName, parentR
 		});
 	}
 }
+/** Resolve parent join values before writing children; missing values cannot form a relation. */
 function readParentColumnValues(parentModelName, relation, parentRow) {
 	const values = /* @__PURE__ */ new Map();
 	for (let i = 0; i < relation.localFields.length; i++) {
@@ -1099,12 +1448,14 @@ function readParentColumnValues(parentModelName, relation, parentRow) {
 	}
 	return values;
 }
+/** Complete and validate a nested record, then insert it with foreign-key checks. */
 async function insertSingleRow(scope, contract, modelName, data, defaultsCache) {
 	assertNoNestedCallbacks(modelName, data);
 	const storeName = getStoreName(contract, modelName);
 	const meta = makePlanMeta(contract);
-	const record = applyCreateDefaults(contract.execution?.mutations.defaults, storeName, data, defaultsCache);
+	const record = completeCreateRecord(contract, modelName, data, defaultsCache);
 	assertEnumValues(contract, modelName, record);
+	assertValidRecord(contract, modelName, "create", record);
 	await validateScalarFks(scope, contract, modelName, record);
 	return (await scope.execute({
 		meta,
@@ -1115,19 +1466,21 @@ async function insertSingleRow(scope, contract, modelName, data, defaultsCache)
 }
 /**
 * Recursive nesting (a relation callback inside an already-nested create) is
-* not supported in Phase 6.4. Without this guard the callback function would be
+* not supported. Without this guard the callback function would be
 * handed to `store.put(...)`, where IDB's structured-clone throws an opaque
 * `DataCloneError` ("could not be cloned") that gives the developer no hint
-* about the real cause. Surface a precise error instead. (PLAN Issue #22.)
+* about the real cause. Surface a precise error instead.
 */
 function assertNoNestedCallbacks(modelName, data) {
 	for (const [field, value] of Object.entries(data)) if (typeof value === "function") throw new Error(`Recursive nested writes are not supported: field "${field}" on a nested "${modelName}" record is a relation callback. Only one level of relation nesting is supported — flatten the inner relation into a separate create/connect call.`);
 }
+/** Require a non-empty connect criterion and return its first matching row. */
 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`);
 	return (await readMutationRows(scope, contract, modelName, expr, 1))[0] ?? null;
 }
+/** Find the first parent selected by the nested-update filters. */
 async function findFirstByFilters(scope, contract, modelName, filters) {
 	if (filters.length === 0) return null;
 	return (await readMutationRows(scope, contract, modelName, andExpr(filters), 1))[0] ?? null;
@@ -1141,7 +1494,7 @@ async function executeMutationPlan(scope, plan) {
 }
 /** 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 catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
 	const request = {
 		...where === void 0 ? {} : { where },
 		...take === void 0 ? {} : { take }
@@ -1149,8 +1502,10 @@ async function readMutationRows(scope, contract, modelName, where, take) {
 	const lowered = lowerRows(catalog, planQuery(catalog, request), makePlanMeta(contract), request);
 	return lowered.finish(await executeMutationPlan(scope, lowered.idbPlan));
 }
+/** Write planned matches, collecting preimages first when changing the walked index key. */
 async function writeMutationRows(scope, contract, modelName, request) {
-	const catalog = buildCatalog(contract, getStoreName(contract, modelName));
+	if (request.write !== "delete") assertValidRecord(contract, modelName, "update", request.patch ?? {});
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
 	const meta = makePlanMeta(contract);
 	const lowered = lowerWrite(catalog, planQuery(catalog, request), meta, request);
 	if (lowered.kind === "scan") return executeMutationPlan(scope, lowered.idbPlan);
@@ -1177,6 +1532,7 @@ async function writeMutationRows(scope, contract, modelName, request) {
 function buildParentJoinWhere(parentValues) {
 	return andExpr([...parentValues].map(([field, value]) => fieldFilter(field, "eq", value)));
 }
+/** Read an explicitly declared referential action from model storage metadata. */
 function getStoredAction(contract, modelName, relationName, kind) {
 	return (domainModelsAtDefaultNamespace(contract.domain)[modelName]?.storage)?.relations?.[relationName]?.[kind];
 }
@@ -1203,6 +1559,7 @@ function sameFields(a, b) {
 function getReferentialActionForRelation(contract, modelName, def, kind) {
 	return enforcedAction(findDeclaredAction(contract, modelName, def, kind));
 }
+/** Find an action on the enforcement side or on its matching inverse relation. */
 function findDeclaredAction(contract, modelName, def, kind) {
 	const direct = getStoredAction(contract, modelName, def.relationName, kind);
 	if (direct !== void 0) return direct;
@@ -1228,6 +1585,7 @@ function findDeclaredAction(contract, modelName, def, kind) {
 function enforcedAction(declared) {
 	return declared === void 0 || declared === "noAction" ? "restrict" : declared;
 }
+/** Identify relations that need child checks when this model changes. */
 function isChildEnforcementRelation(contract, modelName, def) {
 	if (def.cardinality === "1:N") return true;
 	if (def.cardinality === "1:1") {
@@ -1243,16 +1601,16 @@ function isChildEnforcementRelation(contract, modelName, def) {
 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);
+	return rowExists(scope, contract, meta, def.relatedModelName, def.targetFields, values);
 }
 /**
-* Does `storeName` have a row whose `fields` equal `values`, pairwise?
+* Does `modelName` 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) {
+async function rowExists(scope, contract, meta, modelName, fields, values, additionalFilter) {
 	const where = andExpr(fields.map((field, i) => fieldFilter(field, "eq", values[i])));
-	const catalog = buildCatalog(contract, storeName);
+	const catalog = buildCatalog(contract, getStoreName(contract, modelName), modelName);
 	const lowered = lowerExists(catalog, planQuery(catalog, { where }), meta, { where }, additionalFilter);
 	return lowered.finish(await executeMutationPlan(scope, lowered.idbPlan));
 }
@@ -1336,26 +1694,15 @@ async function validateSetDefaultPatch(scope, contract, modelName, def, patch, e
 */
 function collectOnUpdateEnforcementStoreNames(contract, modelName, data) {
 	const stores = /* @__PURE__ */ new Set([getStoreName(contract, modelName)]);
-	const visitedModels = /* @__PURE__ */ new Set();
+	const visitedModels = /* @__PURE__ */ new Set([modelName]);
 	let enforces = false;
-	function walkCascadeChain(mName) {
-		if (visitedModels.has(mName)) return;
-		visitedModels.add(mName);
-		for (const def of getRelationDefinitions(contract, mName)) {
-			if (!isChildEnforcementRelation(contract, mName, def)) continue;
-			const action = getReferentialActionForRelation(contract, mName, def, "onUpdate");
-			stores.add(def.relatedStoreName);
-			if (action === "cascade") walkCascadeChain(def.relatedModelName);
-		}
-	}
-	visitedModels.add(modelName);
 	for (const def of getRelationDefinitions(contract, modelName)) {
 		if (!isChildEnforcementRelation(contract, modelName, def)) continue;
 		if (!def.localFields.some((f) => f in data)) continue;
 		const action = getReferentialActionForRelation(contract, modelName, def, "onUpdate");
 		enforces = true;
 		stores.add(def.relatedStoreName);
-		if (action === "cascade") walkCascadeChain(def.relatedModelName);
+		if (action === "cascade") addOnUpdateCascadeStores(contract, def.relatedModelName, stores, visitedModels);
 	}
 	return {
 		storeNames: [...stores],
@@ -1384,7 +1731,8 @@ function collectOnUpdateEnforcementStoreNames(contract, modelName, data) {
 */
 async function applyReferentialActionsForRowOnUpdate(scope, contract, modelName, oldRow, patch, visited = /* @__PURE__ */ new Set()) {
 	const keyPath = getKeyPath(contract, modelName);
-	const rowKey = `${getStoreName(contract, modelName)}::${keyToken(extractKeyFromRow(oldRow, keyPath))}`;
+	patch = preserveDecimalKeySpelling(contract, modelName, patch, extractKeyFromRow(oldRow, keyPath));
+	const rowKey = `${getStoreName(contract, modelName)}::${keyToken$1(extractKeyFromRow(oldRow, keyPath))}`;
 	if (visited.has(rowKey)) return;
 	visited.add(rowKey);
 	const meta = makePlanMeta(contract);
@@ -1395,7 +1743,7 @@ async function applyReferentialActionsForRowOnUpdate(scope, contract, modelName,
 		const action = getReferentialActionForRelation(contract, modelName, def, "onUpdate");
 		const childWhere = buildChildWhereFromRow(def, oldRow);
 		if (action === "restrict") {
-			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.`);
+			if (await childExists(scope, contract, meta, def, oldRow)) throw new Error(`Cannot update ${modelName} '${keyToken$1(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") {
@@ -1447,6 +1795,7 @@ function hasScalarFkFields(contract, modelName, data) {
 	}
 	return false;
 }
+/** Include parent stores for the non-null foreign keys supplied by this write. */
 function collectScalarFkStoreNames(contract, modelName, data) {
 	const stores = /* @__PURE__ */ new Set([getStoreName(contract, modelName)]);
 	for (const def of getRelationDefinitions(contract, modelName)) {
@@ -1496,18 +1845,18 @@ function fkCheckNeedsExistingRow(contract, modelName, data) {
 * 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);
-	return rowExists(scope, contract, meta, storeName, fields, values, excludeKey === void 0 ? void 0 : (row) => !keyEquals$1(extractKeyFromRow(row, keyPath), excludeKey));
+	return rowExists(scope, contract, meta, parentModel, 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) {
 	return fields.map((f, i) => `${f}='${String(values[i])}'`).join(", ");
 }
+/** Create one completed record and check its foreign keys in the same transaction. */
 async function executeScalarCreateWithFkValidation(options) {
 	const { executor, contract, modelName, data } = options;
 	const defaultsCache = createMutationDefaultsCache();
-	const record = applyCreateDefaults(contract.execution?.mutations.defaults, getStoreName(contract, modelName), data, defaultsCache);
+	const record = completeCreateRecord(contract, modelName, data, defaultsCache);
 	return withMutationScope(executor, collectScalarFkStoreNames(contract, modelName, record), (scope) => insertSingleRow(scope, contract, modelName, record, defaultsCache));
 }
 /**
@@ -1518,8 +1867,7 @@ async function executeScalarCreateWithFkValidation(options) {
 async function executeScalarCreateAllWithFkValidation(options) {
 	const { executor, contract, modelName, data } = options;
 	const defaultsCache = createMutationDefaultsCache();
-	const storeName = getStoreName(contract, modelName);
-	const records = data.map((row) => applyCreateDefaults(contract.execution?.mutations.defaults, storeName, row, defaultsCache));
+	const records = data.map((row) => completeCreateRecord(contract, modelName, row, defaultsCache));
 	return withMutationScope(executor, [...new Set(records.flatMap((row) => collectScalarFkStoreNames(contract, modelName, row)))], async (scope) => {
 		const inserted = [];
 		for (const record of records) inserted.push(await insertSingleRow(scope, contract, modelName, record, defaultsCache));
@@ -1527,6 +1875,29 @@ async function executeScalarCreateAllWithFkValidation(options) {
 	});
 }
 /**
+* Adds the stores an `onUpdate` cascade reaches from `modelName`: every child
+* relation's store, walking further through `cascade` edges only.
+*/
+function addOnUpdateCascadeStores(contract, modelName, stores, visitedModels) {
+	if (visitedModels.has(modelName)) return;
+	visitedModels.add(modelName);
+	for (const def of getRelationDefinitions(contract, modelName)) {
+		if (!isChildEnforcementRelation(contract, modelName, def)) continue;
+		stores.add(def.relatedStoreName);
+		if (getReferentialActionForRelation(contract, modelName, def, "onUpdate") === "cascade") addOnUpdateCascadeStores(contract, def.relatedModelName, stores, visitedModels);
+	}
+}
+/**
+* Every store an `onUpdate` enforcement on `modelName` could touch, whichever
+* fields the write sets. Use it to open a transaction before the write's
+* fields are known.
+*/
+function collectOnUpdateClosureStoreNames(contract, modelName) {
+	const stores = /* @__PURE__ */ new Set([getStoreName(contract, modelName)]);
+	addOnUpdateCascadeStores(contract, modelName, stores, /* @__PURE__ */ new Set());
+	return [...stores];
+}
+/**
 * Combines FK-existence store scope (this model's own N:1 relations) with
 * `onUpdate` enforcement store scope (this model's child relations) for a
 * single write. Returns the union alongside whether `onUpdate` enforcement
@@ -1565,9 +1936,10 @@ async function executeScalarUpdates(options, take) {
 	const storeName = getStoreName(contract, modelName);
 	const patch = applyUpdateDefaults(contract.execution?.mutations.defaults, storeName, data, createMutationDefaultsCache());
 	assertEnumValues(contract, modelName, patch);
+	assertValidRecord(contract, modelName, "update", patch);
 	const { storeNames, enforcesOnUpdate } = collectUpdateStoreNames(contract, modelName, patch);
 	const needsRowForFks = fkCheckNeedsExistingRow(contract, modelName, patch);
-	return withMutationScope(executor, storeNames, async (scope) => {
+	return (await withMutationScope(executor, storeNames, async (scope) => {
 		if (!needsRowForFks) await validateScalarFks(scope, contract, modelName, patch);
 		const meta = makePlanMeta(contract);
 		const where = filters.length === 0 ? void 0 : andExpr(filters);
@@ -1594,7 +1966,7 @@ async function executeScalarUpdates(options, take) {
 			if (updated) results.push(updated);
 		}
 		return results;
-	});
+	})).map(absentAsNull(contract, modelName));
 }
 /**
 * Returns true if the model has at least one child relation (1:N or parent-side
@@ -1604,6 +1976,12 @@ async function executeScalarUpdates(options, take) {
 function hasEnforceableChildRelations(contract, modelName) {
 	return getRelationDefinitions(contract, modelName).some((def) => isChildEnforcementRelation(contract, modelName, def));
 }
+/** The store of `modelName` plus the store of every model it has a relation to, in either direction. */
+function collectRelatedStoreNames(contract, modelName) {
+	const stores = /* @__PURE__ */ new Set([getStoreName(contract, modelName)]);
+	for (const def of getRelationDefinitions(contract, modelName)) stores.add(def.relatedStoreName);
+	return [...stores];
+}
 /**
 * Transitively walks the `onDelete` cascade graph from `modelName`, collecting
 * every store a recursive delete might touch. `cascade` edges are walked
@@ -1618,6 +1996,7 @@ function hasEnforceableChildRelations(contract, modelName) {
 function collectDeleteStoreNames(contract, modelName) {
 	const stores = /* @__PURE__ */ new Set();
 	const visitedModels = /* @__PURE__ */ new Set();
+	/** Collect cascade stores once per model so cyclic relations cannot recurse indefinitely. */
 	function walk(mName) {
 		if (visitedModels.has(mName)) return;
 		visitedModels.add(mName);
@@ -1652,7 +2031,7 @@ function collectDeleteStoreNames(contract, modelName) {
 */
 async function applyReferentialActionsForRow(scope, contract, modelName, row, visited = /* @__PURE__ */ new Set()) {
 	const keyPath = getKeyPath(contract, modelName);
-	const rowKey = `${getStoreName(contract, modelName)}::${keyToken(extractKeyFromRow(row, keyPath))}`;
+	const rowKey = `${getStoreName(contract, modelName)}::${keyToken$1(extractKeyFromRow(row, keyPath))}`;
 	if (visited.has(rowKey)) return;
 	visited.add(rowKey);
 	const meta = makePlanMeta(contract);
@@ -1661,7 +2040,7 @@ async function applyReferentialActionsForRow(scope, contract, modelName, row, vi
 		const action = getReferentialActionForRelation(contract, modelName, def, "onDelete");
 		const childWhere = buildChildWhereFromRow(def, row);
 		if (action === "restrict") {
-			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.`);
+			if (await childExists(scope, contract, meta, def, row)) throw new Error(`Cannot delete ${modelName} '${keyToken$1(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") {
@@ -1700,6 +2079,7 @@ async function applyReferentialActionsForRow(scope, contract, modelName, row, vi
 		}
 	}
 }
+/** Load a keyed row, apply its child actions, and delete it in one transaction. */
 async function executeDeleteWithReferentialActions(options) {
 	const { executor, contract, modelName, key } = options;
 	await withMutationScope(executor, collectDeleteStoreNames(contract, modelName), async (scope) => {
@@ -1721,16 +2101,17 @@ async function executeDeleteWithReferentialActions(options) {
 		return [];
 	});
 }
+/** Delete filtered rows with all child actions inside the same transaction. */
 async function executeDeleteAllWithReferentialActions(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);
-		if (!hasEnforceableChildRelations(contract, modelName)) return writeMutationRows(scope, contract, modelName, {
+		if (!hasEnforceableChildRelations(contract, modelName)) return (await writeMutationRows(scope, contract, modelName, {
 			write: "delete",
 			...where === void 0 ? {} : { where }
-		});
+		})).map(absentAsNull(contract, modelName));
 		const rows = await readMutationRows(scope, contract, modelName, where);
 		for (const row of rows) {
 			await applyReferentialActionsForRow(scope, contract, modelName, row);
@@ -1746,6 +2127,6 @@ async function executeDeleteAllWithReferentialActions(options) {
 	});
 }
 //#endregion
-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 };
+export { createMutationDefaultsCache as A, resolveDecimalKey as B, validateScalarFks as C, planQuery as D, lowerRows as E, combineFilterExprs as F, fieldValueToken as G, withDecimalIdentityScope as H, IdbDecimalIdentityConflictError as I, getStoreName as J, getKeyPath as K, decimalKeysEqual as L, assertValidRecord as M, assertEnumValues as N, applyUpdateDefaults as O, buildRowComparator as P, hasDecimalPrimaryKey as R, requireTransactionExecutor as S, lowerCount as T, buildCatalog as U, withDecimalIdentityExecutor as V, extractKeyFromRow as W, keyToken$1 as X, keyEquals$1 as Y, hasEnforceableChildRelations as _, collectOnUpdateEnforcementStoreNames as a, makePlanMeta as b, executeBulkUpdateWithFkValidation as c, executeMutationPlan as d, executeNestedCreateMutation as f, executeScalarUpdateWithFkValidation as g, executeScalarCreateWithFkValidation as h, collectOnUpdateClosureStoreNames as i, IdbRecordValidationError as j, completeCreateRecord as k, executeDeleteAllWithReferentialActions as l, executeScalarCreateAllWithFkValidation as m, applyReferentialActionsForRowOnUpdate as n, collectRelatedStoreNames as o, executeNestedUpdateMutation as p, getRelation as q, collectDeleteStoreNames as r, collectScalarFkStoreNames as s, applyReferentialActionsForRow as t, executeDeleteWithReferentialActions as u, hasNestedMutationCallbacks as v, withMutationScope as w, readMutationRows as x, hasScalarFkFields as y, preserveDecimalKeySpelling as z };
 
-//# sourceMappingURL=mutation-executor-inLFb0TE.mjs.map
+//# sourceMappingURL=mutation-executor-IuJmyWEG.mjs.map