@atscript/db 0.1.163 → 0.1.165

package/dist/{column-diff-BIGX3sRH.cjs → column-diff-DjeUj9kb.cjs}

@@ -1,7 +1,7 @@
-const require_db_error = require("./db-error-DmF1_xrz.cjs");
-const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
-const require_nested_writer = require("./nested-writer-yCy6wGuN.cjs");
-const require_validator = require("./validator-DK9Ijpo7.cjs");
+const require_db_error = require("./db-error-G3sgvL87.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CNtrSxGH.cjs");
+const require_nested_writer = require("./nested-writer-DOvdbYG-.cjs");
+const require_validator = require("./validator-D7E7T0Oy.cjs");
 const require_search_fields = require("./search-fields-B49-RCWd.cjs");
 const require_object = require("./object-GjsuPNqo.cjs");
 require("./agg.cjs");
@@ -10,6 +10,74 @@ const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_async_hooks = require("node:async_hooks");
+//#region src/shared/with-nesting.ts
+/**
+* Rewrites dotted `$with` names into nesting (since 0.1.165):
+* `{ name: "a.b", filter, controls }` becomes
+* `{ name: "a", controls: { $with: [{ name: "b", filter, controls }] } }`,
+* at every depth. Entries naming the same relation at one level are merged
+* into one — the first one's `filter` / `controls` win, the nested `$with`
+* lists are concatenated — so `$with=a($select=x),a.b` loads `a` once with
+* `b` nested in it. Before, a dotted name was silently skipped.
+*
+* Returns the input array itself when no entry at any level is dotted or a
+* string (the common case allocates nothing). String entries (`"a"`, `"a.b"`
+* — the shorthand the `$with` type admits) are read as `{ name }`.
+*/
+function nestDottedWith(withRelations) {
+	if (!withRelations.some(needsRewrite)) return withRelations;
+	const out = [];
+	const byName = /* @__PURE__ */ new Map();
+	for (const raw of withRelations) {
+		const rel = typeof raw === "string" ? { name: raw } : raw;
+		const dot = rel.name.indexOf(".");
+		const head = dot < 0 ? rel.name : rel.name.slice(0, dot);
+		const entry = dot < 0 ? { ...rel } : {
+			name: head,
+			controls: { $with: [{
+				...rel,
+				name: rel.name.slice(dot + 1)
+			}] }
+		};
+		const existing = byName.get(head);
+		if (!existing) {
+			byName.set(head, entry);
+			out.push(entry);
+			continue;
+		}
+		const extra = entry.controls?.$with;
+		existing.filter ??= entry.filter;
+		const controls = {
+			...entry.controls,
+			...existing.controls
+		};
+		const nested = [...existing.controls?.$with ?? [], ...extra ?? []];
+		if (nested.length > 0) controls.$with = nested;
+		existing.controls = controls;
+	}
+	for (const entry of out) {
+		const nested = entry.controls?.$with;
+		if (nested?.length) {
+			const next = nestDottedWith(nested);
+			if (next !== nested) entry.controls = {
+				...entry.controls,
+				$with: next
+			};
+		}
+	}
+	return out;
+}
+/**
+* An entry is rewritten when it (or a nested one) is dotted, or is the
+* string shorthand (typed as allowed, but the loaders read `.name`).
+*/
+function needsRewrite(raw) {
+	if (typeof raw === "string") return true;
+	if (raw.name.includes(".")) return true;
+	const nested = raw.controls?.$with;
+	return Array.isArray(nested) && nested.some(needsRewrite);
+}
+//#endregion
 //#region src/logger.ts
 const NoopLogger = {
 	error: () => {},
@@ -511,6 +579,12 @@ var TableMetadata = class {
 	*/
 	onUpdateNow = /* @__PURE__ */ new Set();
 	/**
+	* Top-level `number.timestamp.created` fields (since 0.1.165): set by the
+	* insert only — a replace keeps the stored value, a replace or patch
+	* payload's value is dropped.
+	*/
+	insertOnly = /* @__PURE__ */ new Set();
+	/**
 	* Top-level fields annotated with `@db.onUpdate.inc`: `0` on insert, `+1` in
 	* the same statement on every update and replace.
 	* @since 0.1.162
@@ -848,6 +922,7 @@ var TableMetadata = class {
 		const resolvedDefault = resolveDefaultFromMetadata(metadata);
 		if (resolvedDefault) this.defaults.set(fieldName, resolvedDefault);
 		if (metadata.has("db.onUpdate.now")) this.onUpdateNow.add(fieldName);
+		else if (!fieldName.includes(".") && hasPrimitiveTag(fieldType, "created")) this.insertOnly.add(fieldName);
 		if (metadata.has("db.onUpdate.inc")) {
 			if (fieldName.includes(".")) throw new Error(`@db.onUpdate.inc on "${fieldName}" must sit on a top-level field of the table`);
 			this.onUpdateInc.add(fieldName);
@@ -880,9 +955,10 @@ var TableMetadata = class {
 		if (metadata.has("db.rel.FK")) {
 			const raw = metadata.get("db.rel.FK");
 			const alias = raw === true ? void 0 : raw;
-			if (fieldType.ref) {
-				const targetTable = require_nested_writer.tableNameOf(fieldType.ref.type());
-				const targetField = fieldType.ref.field;
+			const fkRef = fieldType.ref ?? require_validator.soleUnionMember(fieldType)?.ref;
+			if (fkRef) {
+				const targetTable = require_nested_writer.tableNameOf(fkRef.type());
+				const targetField = fkRef.field;
 				const key = alias || `__auto_${fieldName}`;
 				const existing = this.foreignKeys.get(key);
 				if (existing) {
@@ -892,7 +968,7 @@ var TableMetadata = class {
 					fields: [fieldName],
 					targetTable,
 					targetFields: [targetField],
-					targetTypeRef: fieldType.ref.type,
+					targetTypeRef: fkRef.type,
 					alias
 				});
 			}
@@ -1242,7 +1318,8 @@ var TableMetadata = class {
 				encrypted: isEncrypted || underEncrypted || void 0,
 				isGeoPoint: isGeoPointType(colType) || void 0,
 				derived: this.derivedFields.get(path),
-				computed: computedMeta(rootType, path)
+				computed: computedMeta(rootType, path),
+				insertOnly: this.insertOnly.has(path) || void 0
 			});
 		}
 		const flatCache = /* @__PURE__ */ new Map();
@@ -1452,6 +1529,16 @@ function computedMeta(rootType, path) {
 		via: Object.freeze(computed.via)
 	} : void 0;
 }
+/**
+* Whether the column of `type` is the tagged primitive: the type itself, or
+* the one value member of `T | null` ({@link columnUnionBase}). Not a
+* reference to another field (`a: Other.createdAt` does not share its
+* semantics), nor a wider union (`number.timestamp.created | string`).
+*/
+function hasPrimitiveTag(type, tag) {
+	if (type.ref?.field) return false;
+	return (require_validator.columnUnionBase(type) ?? type).type.tags?.has(tag) === true;
+}
 //#endregion
 //#region src/shared/search-term.ts
 /**
@@ -1504,6 +1591,16 @@ function describeFulltext(index, textLabel) {
 function defaultFulltextIndex(indexes) {
 	return indexes.find((i) => splitFulltextFields(i).text.length > 0) ?? indexes[0];
 }
+/**
+* The fulltext index a search names (since 0.1.165): the one DECLARED with
+* that name (`@db.index.fulltext 'name'`), else the one whose internal key
+* (`atscript__fulltext__<name>`) it is — a deprecated alias kept for callers
+* that copied the key from an older `getSearchIndexes()`. `undefined` when
+* none matches; a search naming no index uses {@link defaultFulltextIndex}.
+*/
+function resolveFulltextIndex(indexes, indexName) {
+	return indexes.find((i) => i.name === indexName) ?? indexes.find((i) => i.key === indexName);
+}
 //#endregion
 //#region src/query/filter-values.ts
 const OPAQUE = {
@@ -4444,10 +4541,26 @@ var AtscriptDbReadable = class {
 	*/
 	get onUpdateIncPhysical() {
 		this._ensureBuilt();
-		return this._onUpdateIncPhysical ??= [...this._meta.onUpdateInc].map((field) => this._meta.columnMap.get(field) ?? field);
+		return this._onUpdateIncPhysical ??= this._physicalNames(this._meta.onUpdateInc);
 	}
 	_onUpdateIncPhysical;
 	/**
+	* Physical column names of the insert-only fields (`number.timestamp.created`,
+	* since 0.1.165): a full replace keeps their stored values. Empty when
+	* there are none.
+	*
+	* @internal Adapter-facing surface; not part of the consumer API.
+	*/
+	get insertOnlyPhysical() {
+		this._ensureBuilt();
+		return this._insertOnlyPhysical ??= this._physicalNames(this._meta.insertOnly);
+	}
+	_insertOnlyPhysical;
+	/** The physical columns of a set of top-level logical fields. */
+	_physicalNames(fields) {
+		return [...fields].map((field) => this._meta.columnMap.get(field) ?? field);
+	}
+	/**
 	* Logical paths of the `@db.column.version.exempt` fields, including objects
 	* whose direct children are all exempt. A patch that writes only these (and
 	* no `$cas`) does not bump the version column. Empty when the table has no
@@ -4606,8 +4719,22 @@ var AtscriptDbReadable = class {
 	*/
 	_translateRead(query) {
 		let readQuery = query ?? {};
-		const controls = readQuery.controls;
-		const withRelations = controls?.$with;
+		let controls = readQuery.controls;
+		let withRelations = controls?.$with;
+		if (withRelations?.length) {
+			const nested = nestDottedWith(withRelations);
+			if (nested !== withRelations) {
+				withRelations = nested;
+				controls = {
+					...controls,
+					$with: nested
+				};
+				readQuery = {
+					...readQuery,
+					controls
+				};
+			}
+		}
 		let widened = [];
 		if (withRelations?.length && controls?.$select) {
 			const widen = this._widenSelectForWith(controls.$select, withRelations);
@@ -5534,8 +5661,8 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-DujL_Mh9.cjs")).then((n) => n.relation_loader_exports);
-		return loadRelationsImpl(rows, withRelations, this);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-BrkakVF_.cjs")).then((n) => n.relation_loader_exports);
+		return loadRelationsImpl(rows, nestDottedWith(withRelations), this);
 	}
 	/**
 	* Finds the FK entry that connects a `@db.rel.to` relation to its target.
@@ -6779,10 +6906,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 				if (await target.count(filter) < expectedCount) {
 					const sample = firstValues.slice(0, 3).join(", ");
 					const suffix = firstValues.length > 3 ? `, ... (${firstValues.length} total)` : "";
-					throw new require_db_error.DbError("FK_VIOLATION", [{
-						path: fk.fields.join(", "),
-						message: `FK constraint violation: "${fk.fields.join(", ")}" references non-existent record in "${fk.targetTable}" (values: ${sample}${suffix})`
-					}]);
+					throw new require_db_error.DbError("FK_VIOLATION", require_nested_writer.fkMissingEntries(fk.fields, fk.targetTable, `values: ${sample}${suffix}`));
 				}
 			});
 		}
@@ -6860,10 +6984,11 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 					const childFilter = this.buildCascadeChildFilter(records, target.fk);
 					if (!childFilter) continue;
 					restrictChecks.push(target.count(childFilter).then((count) => {
-						if (count > 0) throw new require_db_error.DbError("CONFLICT", [{
-							path: tableName,
-							message: `Cannot delete from "${tableName}": ${count} record(s) in "${target.childTable}" (${target.fk.fields.join(", ")}) reference it (RESTRICT)`
-						}]);
+						if (count > 0) throw new require_db_error.DbError("CONFLICT", [require_nested_writer.fkRestrictEntry(tableName, {
+							referencedBy: target.childTable,
+							count,
+							fields: target.fk.fields
+						})]);
 					}));
 				}
 				if (restrictChecks.length > 0) await Promise.all(restrictChecks);
@@ -6953,6 +7078,22 @@ function pinByPrimaryKey(rows, pk) {
 	return out;
 }
 //#endregion
+//#region src/table/fk-lookup.ts
+/**
+* The FK lookup target of a table: `count` and the key projection `find`
+* (`$select` of the target fields) that `validateRows({ fk: true })` diffs.
+* One wrapper for the space's resolver and a table's writable fallback.
+*/
+function fkLookupTargetOf(table) {
+	return {
+		count: (filter) => table.count({ filter }),
+		find: (filter, fields) => table.findMany({
+			filter,
+			controls: { $select: [...fields] }
+		})
+	};
+}
+//#endregion
 //#region src/patch/array-ops-resolver.ts
 /**
 * Resolves array patch operator keys (`__$insert`, `__$remove`, `__$upsert`,
@@ -7493,6 +7634,23 @@ const UPDATE_RESULT = {
 };
 /** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
 const TOUCH_MANY_CHUNK = 500;
+/** Distinct FK key tuples per `validateRows` lookup query (well under every bind limit). */
+const FK_LOOKUP_CHUNK = 500;
+/** A key tuple's identity for the in-memory diff — scalar-text, so `1` and `"1"` agree like the engine compares them. */
+function fkTupleKey(values) {
+	return JSON.stringify(values.map((v) => v instanceof Date ? v.getTime() : String(v)));
+}
+/** The write mode a standard validator purpose validates in when called without a context. */
+/** The validator purpose a write mode validates with (`validateRows`, the write paths). */
+const MODE_PURPOSE = {
+	insert: "insert",
+	replace: "bulkReplace",
+	patch: "bulkUpdate"
+};
+const PURPOSE_MODES = {
+	...Object.fromEntries(Object.entries(MODE_PURPOSE).map(([mode, purpose]) => [purpose, mode])),
+	patch: "patch"
+};
 var AtscriptDbTable = class extends AtscriptDbReadable {
 	_cascadeResolver;
 	_fkLookupResolver;
@@ -7526,13 +7684,175 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* Adapters may define additional purposes.
 	*/
 	getValidator(purpose) {
-		if (!this.validators.has(purpose)) {
-			const validator = this._buildValidator(purpose);
+		let validator = this.validators.get(purpose);
+		if (!validator) {
+			validator = this._withDefaultContext(this._buildValidator(purpose), purpose);
 			this.validators.set(purpose, validator);
 		}
-		return this.validators.get(purpose);
+		return validator;
+	}
+	/**
+	* A standard purpose's validator called WITHOUT a context validates in that
+	* purpose's write mode (since 0.1.165): `getValidator("insert").validate(row, true)`
+	* accepts what an insert accepts — omitted primary key, defaulted, FK and
+	* navigation fields. Before, the db plugin saw no mode and ran inert while
+	* navigation fields were forced required. An explicit context still wins.
+	*/
+	_withDefaultContext(validator, purpose) {
+		const mode = PURPOSE_MODES[purpose];
+		if (!mode) return validator;
+		const validate = (value, safe, context) => validator.validate(value, safe, context ?? this._validationCtx(mode));
+		return new Proxy(validator, { get: (target, key) => key === "validate" ? validate : Reflect.get(target, key, target) });
+	}
+	/** A fresh validation context of a write `mode` — the one its write paths build. */
+	_validationCtx(mode) {
+		this._ensureBuilt();
+		return {
+			mode,
+			navFields: this._meta.navFields,
+			...mode === "patch" ? { flatMap: this.flatMap } : {}
+		};
+	}
+	/** {@link normalizeWriteErrors} for this table: its constraint errors normalized against its metadata. */
+	_normalizeWrite(fn) {
+		return require_nested_writer.normalizeWriteErrors(this._meta, this.tableName, fn);
+	}
+	/**
+	* Validates rows exactly as a write in `mode` would, without writing
+	* (since 0.1.165): each row is cloned, given the defaults / stamps that
+	* write applies, and validated with that write's validator and context.
+	* Returns one `{ index, path, message }` per problem — `[]` when every row
+	* is valid; the caller's rows are not modified.
+	*
+	* `fk: true` also checks that every foreign key names an existing row
+	* (by lookup, on every adapter — native-FK adapters otherwise leave that to
+	* the engine at write time); a missing target is reported on each of the
+	* key's fields. Rows that fail type validation are not looked up.
+	*
+	* @param mode - `'insert'` (default), `'replace'` or `'patch'`.
+	*/
+	async validateRows(rows, mode = "insert", opts) {
+		this._ensureBuilt();
+		const validator = this.getValidator(MODE_PURPOSE[mode]);
+		const ctx = this._validationCtx(mode);
+		this._applyDepthCtx(ctx, 0);
+		const now = Date.now();
+		const errors = [];
+		const valid = [];
+		for (let index = 0; index < rows.length; index++) {
+			const raw = rows[index];
+			let row = raw;
+			if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+				const clone = _cloneWritePayload(raw);
+				delete clone.$cas;
+				if (mode !== "patch") this._applyDefaults(clone, now);
+				if (mode !== "insert") this._stampOnUpdate(clone, now, mode === "replace");
+				row = clone;
+			}
+			try {
+				if (validator.validate(row, true, ctx)) {
+					valid.push({
+						index,
+						row
+					});
+					continue;
+				}
+				for (const e of validator.errors) errors.push({
+					index,
+					path: e.path,
+					message: e.message
+				});
+			} catch (error) {
+				errors.push({
+					index,
+					path: error.field ?? "",
+					message: error instanceof Error ? error.message : String(error)
+				});
+			}
+		}
+		if (opts?.fk && valid.length > 0) {
+			errors.push(...await this._missingForeignKeys(valid, mode === "patch"));
+			errors.sort((a, b) => a.index - b.index);
+		}
+		return errors;
+	}
+	/**
+	* {@link validateRows}' FK lookup: one entry per FK field of each row naming
+	* a missing target. Distinct key tuples are looked up in chunks of
+	* {@link FK_LOOKUP_CHUNK} — reading the target keys that exist (`$in` for a
+	* single-column key, `$or` for a composite one) and diffing in memory, so a
+	* batch never exceeds a bind-parameter limit and a miss costs no extra
+	* query. A lookup target without `find` (a custom resolver) is counted per
+	* chunk, and per tuple only in a chunk that comes up short.
+	*/
+	async _missingForeignKeys(rows, partial) {
+		const out = [];
+		for (const fk of this._meta.foreignKeys.values()) {
+			const target = this._fkTargetReader(fk);
+			if (!target) continue;
+			const byKey = /* @__PURE__ */ new Map();
+			for (const { index, row } of rows) {
+				if (partial && !fk.fields.some((f) => f in row)) continue;
+				const values = fk.fields.map((f) => row[f]);
+				if (values.some((v) => v === null || v === void 0)) continue;
+				const key = fkTupleKey(values);
+				const entry = byKey.get(key);
+				if (entry) entry.indexes.push(index);
+				else byKey.set(key, {
+					values,
+					indexes: [index]
+				});
+			}
+			const tuples = [...byKey.values()];
+			const tf = fk.targetFields;
+			const filterOf = (values) => Object.fromEntries(tf.map((f, i) => [f, values[i]]));
+			for (let at = 0; at < tuples.length; at += FK_LOOKUP_CHUNK) {
+				const chunk = tuples.slice(at, at + FK_LOOKUP_CHUNK);
+				const filter = tf.length === 1 ? { [tf[0]]: { $in: chunk.map((t) => t.values[0]) } } : { $or: chunk.map((t) => filterOf(t.values)) };
+				let missing;
+				if (target.find) {
+					const found = new Set((await target.find(filter, tf)).map((r) => fkTupleKey(tf.map((f) => r[f]))));
+					missing = chunk.filter((t) => !found.has(fkTupleKey(t.values)));
+				} else {
+					if (await target.count(filter) >= chunk.length) continue;
+					missing = [];
+					for (const t of chunk) if (await target.count(filterOf(t.values)) === 0) missing.push(t);
+				}
+				for (const tuple of missing) {
+					const shown = tuple.values.map((v) => String(v)).join(", ");
+					for (const index of tuple.indexes) for (const field of fk.fields) out.push({
+						index,
+						path: field,
+						message: `References a non-existent record in "${fk.targetTable}" (${shown})`
+					});
+				}
+			}
+		}
+		return out;
+	}
+	/** How {@link _missingForeignKeys} reads an FK's target table, if it can. */
+	_fkTargetReader(fk) {
+		const lookup = this._fkLookupResolver?.(fk.targetTable);
+		if (lookup) return lookup;
+		if (!fk.targetTypeRef || !this._writeTableResolver) return void 0;
+		const table = this._writeTableResolver(fk.targetTypeRef());
+		return table ? fkLookupTargetOf(table) : void 0;
 	}
 	async insertOne(payload, opts) {
+		const { returning, ...insertOpts } = opts ?? {};
+		if (!returning) return this._insertOneRow(payload, insertOpts);
+		return this.adapter.withTransaction(async () => {
+			const result = await this._insertOneRow(payload, insertOpts);
+			if (result.insertedId === void 0) return result;
+			const controls = returning === true ? void 0 : { $select: [...returning] };
+			const row = await this.findById(result.insertedId, controls ? { controls } : void 0);
+			return {
+				...result,
+				row
+			};
+		});
+	}
+	async _insertOneRow(payload, opts) {
 		const result = await this._insertMany([payload], {
 			...opts,
 			_action: "insert"
@@ -7562,7 +7882,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = !ignore && this._isSingleStatementWrite(payloads, depth, guard, check);
-		return require_nested_writer.enrichFkViolation(this._meta, () => this._inWriteTransaction(singleStatement, async () => {
+		return this._normalizeWrite(() => this._inWriteTransaction(singleStatement, async () => {
 			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
 			const now = Date.now();
 			let items = payloads.map((p) => this._applyDefaults(clone(p), now));
@@ -7637,7 +7957,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = this._isSingleStatementWrite(payloads, depth, guard, check);
-		return require_nested_writer.enrichFkViolation(this._meta, () => this._inWriteTransaction(singleStatement, async () => {
+		return this._normalizeWrite(() => this._inWriteTransaction(singleStatement, async () => {
 			const versionColumn = this.versionColumn;
 			const expectedVersions = Array.from({ length: payloads.length });
 			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
@@ -7727,7 +8047,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = this._isSingleStatementWrite(payloads, depth, guard, check);
-		return require_nested_writer.enrichFkViolation(this._meta, () => this._inWriteTransaction(singleStatement, async () => {
+		return this._normalizeWrite(() => this._inWriteTransaction(singleStatement, async () => {
 			const versionColumn = this.versionColumn;
 			const expectedVersions = Array.from({ length: payloads.length });
 			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
@@ -7987,7 +8307,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				modifiedCount: 0
 			};
 		}
-		return require_nested_writer.enrichFkViolation(this._meta, () => {
+		return this._normalizeWrite(() => {
 			if (!bound) return this.adapter.updateMany(translatedFilter, update, ops, ...updateOptsArg(keepVersion));
 			return this._runBounded(bound, UPDATE_RESULT, (f, limit) => this.adapter.updateMany(f, update, ops, ...updateOptsArg(keepVersion, limit)));
 		});
@@ -8013,7 +8333,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const versionColumn = this.versionColumn;
 		if (versionColumn !== void 0) assertNoVersionWrites(dataCopy, versionColumn);
 		await this._encryptItems([dataCopy], "write");
-		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter)));
+		return this._normalizeWrite(() => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter)));
 	}
 	/**
 	* Deletes every row matching `filter` (application-level cascades run first
@@ -8532,6 +8852,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	_stampOnUpdate(data, now, topLevel) {
 		for (const field of this._meta.onUpdateInc) delete data[field];
+		for (const field of this._meta.insertOnly) delete data[field];
 		for (const field of this._meta.onUpdateNow) if (!field.includes(".")) if (topLevel) data[field] = now;
 		else delete data[field];
 		else if (this._nestedDefaultFillable(field)) stampNested(data, field.split("."), 0, now);
@@ -8702,6 +9023,8 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* Used by parent tables to validate FROM children before the main insert,
 	* ensuring errors are caught before the parent is committed.
 	*
+	* @internal Nested-write plumbing — its FK step is a no-op on native-FK
+	* adapters. To validate rows yourself, use {@link validateRows}.
 	* @param opts.excludeFkTargetTable - Skip FK validation to this table (the parent).
 	*/
 	async preValidateItems(items, opts) {
@@ -10205,6 +10528,12 @@ Object.defineProperty(exports, "fkKey", {
 		return fkKey;
 	}
 });
+Object.defineProperty(exports, "fkLookupTargetOf", {
+	enumerable: true,
+	get: function() {
+		return fkLookupTargetOf;
+	}
+});
 Object.defineProperty(exports, "geoIndexNotFoundMessage", {
 	enumerable: true,
 	get: function() {
@@ -10313,6 +10642,12 @@ Object.defineProperty(exports, "narrowerFilterOps", {
 		return narrowerFilterOps;
 	}
 });
+Object.defineProperty(exports, "nestDottedWith", {
+	enumerable: true,
+	get: function() {
+		return nestDottedWith;
+	}
+});
 Object.defineProperty(exports, "normalizeComputedSelect", {
 	enumerable: true,
 	get: function() {
@@ -10343,6 +10678,12 @@ Object.defineProperty(exports, "resolveDesignType", {
 		return resolveDesignType;
 	}
 });
+Object.defineProperty(exports, "resolveFulltextIndex", {
+	enumerable: true,
+	get: function() {
+		return resolveFulltextIndex;
+	}
+});
 Object.defineProperty(exports, "sameDefaultValue", {
 	enumerable: true,
 	get: function() {

package/dist/control-B5BJypqL.cjs

@@ -0,0 +1,16 @@
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
+//#region src/schema/control.as
+var AtscriptControl = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "AtscriptControl";
+	static toJsonSchema() {
+		(0, _atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+(0, _atscript_typescript_utils.$ak)("db.index.fulltext", "db.index.plain", "db.index.unique", "db.view.joins", "expect.pattern");
+(0, _atscript_typescript_utils.$nr)("db.agg.avg", "db.agg.count", "db.agg.countDistinct", "db.agg.max", "db.agg.min", "db.agg.sum", "db.alias", "db.amount.currency.ref", "db.column", "db.column.collate", "db.column.derived", "db.column.dimension", "db.column.filterable", "db.column.measure", "db.column.precision", "db.column.renamed", "db.column.searchable", "db.column.sortable", "db.column.version", "db.column.version.exempt", "db.compute", "db.default", "db.default.increment", "db.default.now", "db.default.uuid", "db.depth.limit", "db.encrypted", "db.http.path", "db.ignore", "db.index.fulltext", "db.index.geo", "db.index.plain", "db.index.unique", "db.json", "db.onUpdate.inc", "db.onUpdate.now", "db.patch.strategy", "db.rel.FK", "db.rel.filter", "db.rel.filterable", "db.rel.from", "db.rel.onDelete", "db.rel.onUpdate", "db.rel.to", "db.rel.via", "db.schema", "db.search.filter", "db.search.vector", "db.search.vector.threshold", "db.sort.nulls", "db.space", "db.sync.method", "db.table", "db.table.filterable", "db.table.preferredId.uniqueIndex", "db.table.renamed", "db.table.sortable", "db.unit.ref", "db.view", "db.view.filter", "db.view.for", "db.view.having", "db.view.joins", "db.view.materialized", "db.view.renamed", "db.writeOnly", "meta.default", "meta.id", "meta.readonly", "meta.required");
+(0, _atscript_typescript_utils.defineAnnotatedType)("object", AtscriptControl).annotate("db.table", "__atscript_control").prop("_id", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("meta.id", true).$type).prop("value", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("lockedBy", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("lockedAt", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").optional().$type).prop("expiresAt", (0, _atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("number").optional().$type);
+//#endregion
+exports.AtscriptControl = AtscriptControl;

package/dist/control-CevYIJC4.mjs

@@ -0,0 +1,16 @@
+import { $ak, $nr, defineAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
+//#region src/schema/control.as
+var AtscriptControl = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "AtscriptControl";
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+$ak("db.index.fulltext", "db.index.plain", "db.index.unique", "db.view.joins", "expect.pattern");
+$nr("db.agg.avg", "db.agg.count", "db.agg.countDistinct", "db.agg.max", "db.agg.min", "db.agg.sum", "db.alias", "db.amount.currency.ref", "db.column", "db.column.collate", "db.column.derived", "db.column.dimension", "db.column.filterable", "db.column.measure", "db.column.precision", "db.column.renamed", "db.column.searchable", "db.column.sortable", "db.column.version", "db.column.version.exempt", "db.compute", "db.default", "db.default.increment", "db.default.now", "db.default.uuid", "db.depth.limit", "db.encrypted", "db.http.path", "db.ignore", "db.index.fulltext", "db.index.geo", "db.index.plain", "db.index.unique", "db.json", "db.onUpdate.inc", "db.onUpdate.now", "db.patch.strategy", "db.rel.FK", "db.rel.filter", "db.rel.filterable", "db.rel.from", "db.rel.onDelete", "db.rel.onUpdate", "db.rel.to", "db.rel.via", "db.schema", "db.search.filter", "db.search.vector", "db.search.vector.threshold", "db.sort.nulls", "db.space", "db.sync.method", "db.table", "db.table.filterable", "db.table.preferredId.uniqueIndex", "db.table.renamed", "db.table.sortable", "db.unit.ref", "db.view", "db.view.filter", "db.view.for", "db.view.having", "db.view.joins", "db.view.materialized", "db.view.renamed", "db.writeOnly", "meta.default", "meta.id", "meta.readonly", "meta.required");
+defineAnnotatedType("object", AtscriptControl).annotate("db.table", "__atscript_control").prop("_id", defineAnnotatedType().designType("string").tags("string").annotate("meta.id", true).$type).prop("value", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("lockedBy", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("lockedAt", defineAnnotatedType().designType("number").tags("number").optional().$type).prop("expiresAt", defineAnnotatedType().designType("number").tags("number").optional().$type);
+//#endregion
+export { AtscriptControl };

package/dist/{db-error-hraC12B9.mjs → db-error-BMy4-OWq.mjs}

@@ -9,6 +9,11 @@ var DbError = class extends Error {
 	code;
 	errors;
 	name = "DbError";
+	/**
+	* Set by {@link constraintViolation}: what the adapter could tell about the
+	* violated constraint, for the table layer to normalize. @internal
+	*/
+	hint;
 	constructor(code, errors, message) {
 		super(message ?? errors[0]?.message ?? "Database error");
 		this.code = code;
@@ -37,6 +42,23 @@ function isRetryableDbError(error) {
 function isConflict(error) {
 	return error instanceof DbError && error.code === "CONFLICT";
 }
+/**
+* The error an adapter throws for an engine unique / foreign-key violation
+* (since 0.1.165): `CONFLICT` (unique, primary key, blocked delete) or
+* `FK_VIOLATION`, carrying the engine's `raw` text and whatever `hint` the
+* engine gave. The table layer rewrites it into one entry per logical field
+* of the violated constraint, with `code` / `params` and the raw text in
+* `details`.
+*/
+function constraintViolation(code, hint, raw) {
+	const error = new DbError(code, [{
+		path: hint.columns?.[0] ?? "",
+		message: raw,
+		details: raw
+	}]);
+	error.hint = hint;
+	return error;
+}
 /** @internal An `INVALID_QUERY` error with a single `{ path, message }` entry. */
 function invalidQuery(path, message) {
 	return new DbError("INVALID_QUERY", [{
@@ -145,4 +167,4 @@ function aggregateExpressionsNotSupported() {
 	}]);
 }
 //#endregion
-export { aggregateExpressionsNotSupported as a, invalidQuery as c, spaceClosedError as d, DepthLimitExceededError as i, isConflict as l, CasMismatchError as n, aggregateFailure as o, DbError as r, bucketTimeZoneUnavailable as s, CasExhaustedError as t, isRetryableDbError as u };
+export { aggregateExpressionsNotSupported as a, constraintViolation as c, isRetryableDbError as d, spaceClosedError as f, DepthLimitExceededError as i, invalidQuery as l, CasMismatchError as n, aggregateFailure as o, DbError as r, bucketTimeZoneUnavailable as s, CasExhaustedError as t, isConflict as u };