@atscript/db 0.1.163 → 0.1.165

package/dist/{column-diff-BfNIlMwX.mjs → column-diff-9pF0d8JP.mjs}

@@ -1,7 +1,7 @@
-import { a as aggregateExpressionsNotSupported, c as invalidQuery, d as spaceClosedError, n as CasMismatchError, r as DbError } from "./db-error-hraC12B9.mjs";
-import { a as SOURCE_VALUE_FNS, c as isFirstLast, o as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-DsS9UQVB.mjs";
-import { A as hasRelationOp, D as containsRelationFilter, F as resolveRelationFilterTree, H as tableNameOf, I as compositeKey, J as viewExprNullable, K as isFieldRef, L as findFKEntryForRelation, M as noteRelationFilter, N as relGuardState, O as createRelationFilterHost, R as findFKForRelation, S as uniqueKeyTuple, U as computeOf, V as slicePerGroup, W as computedOperands, Y as walkViewExpr, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as rowMatchesKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as findRowsByKeys, x as sameKey, y as pkTupleKey, z as findRemoteFK } from "./nested-writer-ClUX0DB0.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, d as soleUnionMember, f as unionValueMembers, i as dbPlugin, l as columnUnionBase, n as buildPatchPartial, t as buildDbValidator, u as pathPresence } from "./validator-DuDWsIdQ.mjs";
+import { a as aggregateExpressionsNotSupported, f as spaceClosedError, l as invalidQuery, n as CasMismatchError, r as DbError } from "./db-error-BMy4-OWq.mjs";
+import { a as SOURCE_VALUE_FNS, c as isFirstLast, o as SUPPORTED_AGGREGATE_FNS, r as BASE_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-CmtSNIHm.mjs";
+import { A as createRelationFilterHost, B as findFKForRelation, C as sameKey, F as relGuardState, G as computeOf, J as isFieldRef, K as computedOperands, L as resolveRelationFilterTree, M as hasRelationOp, P as noteRelationFilter, R as compositeKey, S as rowMatchesKey, U as slicePerGroup, V as findRemoteFK, W as tableNameOf, X as viewExprNullable, Z as walkViewExpr, _ as fkRestrictEntry, a as batchPatchNestedFrom, b as findRowsByKeys, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as fkMissingEntries, h as validateBatch, i as batchInsertNestedVia, k as containsRelationFilter, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as normalizeWriteErrors, w as uniqueKeyTuple, x as pkTupleKey, y as remapDeleteFkViolation, z as findFKEntryForRelation } from "./nested-writer-BraWjS8a.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, d as soleUnionMember, f as unionValueMembers, i as dbPlugin, l as columnUnionBase, n as buildPatchPartial, t as buildDbValidator, u as pathPresence } from "./validator-UpgPhwvH.mjs";
 import { a as searchMemberKind, c as DERIVED_INCOMPATIBLE, n as ENCRYPTED_SEARCH_FEATURES, o as numericTypeProblem, t as ENCRYPTED_INCOMPATIBLE, u as isJsonLeafType } from "./search-fields-BPNsxrCk.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, s as stableJson, t as deletePath } from "./object-PQ1J8jri.mjs";
 import { resolveAlias as resolveAlias$1 } from "./agg.mjs";
@@ -10,6 +10,74 @@ import { isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { ARITH_MAX_NODES, BUCKET_UNITS, isAggregateExpr, isAggregateOfExpr, isBucketExpr, isNullsPlacement, isPrimitive, isRelationOp, isSelectArithExpr, resolveAlias, resolveBuckets } from "@uniqu/core";
 import { AsyncLocalStorage } from "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 = tableNameOf(fieldType.ref.type());
-				const targetField = fieldType.ref.field;
+			const fkRef = fieldType.ref ?? soleUnionMember(fieldType)?.ref;
+			if (fkRef) {
+				const targetTable = 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 (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 import("./relation-loader-Qv3LrQ42.mjs").then((n) => n.n);
-		return loadRelationsImpl(rows, withRelations, this);
+		const { loadRelationsImpl } = await import("./relation-loader-BOEVhcBe.mjs").then((n) => n.n);
+		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 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 DbError("FK_VIOLATION", 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 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 DbError("CONFLICT", [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 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) checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = !ignore && this._isSingleStatementWrite(payloads, depth, guard, check);
-		return 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) checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = this._isSingleStatementWrite(payloads, depth, guard, check);
-		return 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) checkDepthOverflow(payloads, maxDepth, this._meta);
 		const singleStatement = this._isSingleStatementWrite(payloads, depth, guard, check);
-		return 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 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 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) {
@@ -9953,4 +10276,4 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 	return diff;
 }
 //#endregion
-export { narrowerFilterOps as $, hasForeignKeyChanges as A, acceptedOperatorsHint as B, ALL_VIEW_CAPABILITIES as C, computeForeignKeyDiff as D, createFailureCollector as E, geoIndexNotFoundMessage as F, classifyQueryPath as G, bucketSourceVerdict as H, searchIndexNotFoundMessage as I, guardAggregate as J, collectQueryPaths as K, vectorIndexNotFoundMessage as L, NativeIntegrity as M, AtscriptDbReadable as N, fkColumns as O, resolveDesignType as P, guardQuery as Q, ADAPTER_FILTER_REASON as R, ALL_ISOLATION_LEVELS as S, NoopLogger as St, createChangeRecorder as T, canFilterLeaf as U, assertGeoPoint as V, checkHavingKeys as W, guardPath as X, guardFilter as Y, guardPaths as Z, isVersionExemptPatch as _, isBucketableField as _t, computeSchemaHash as a, UniquSelect as at, ApplicationIntegrity as b, normalizeComputedSelect as bt, computeViewSnapshot as c, defaultFulltextIndex as ct, snapshotToExistingTableOptions as d, splitFulltextFields as dt, sortFieldNames as et, viewSnapshotSources as f, TableMetadata as ft, AtscriptDbTable as g, aliasTargetOf as gt, isViewType as h, relationalColumnName as ht, canonicalizeQueryNode as i, FieldMappingStrategy as it, IntegrityStrategy as j, fkKey as k, serializeDefaultValue as l, describeFulltext as lt, isAtscriptDbView as m, isGeoPointType as mt, isColumnTypeChanged as n, RelationalFieldMapper as nt, computeTableHash as o, numericOperandProblem as ot, AtscriptDbView as p, isGeoIndexableType as pt, groupSourceVerdict as q, sameDefaultValue as r, DocumentFieldMapper as rt, computeTableSnapshot as s, INTEGER_REGEX_OP as st, computeColumnDiff as t, unsupportedOperatorMessage as tt, snapshotToExistingColumns as u, searchTermInteger as ut, assertNoVersionWrites as v, isJsonValueField as vt, BaseDbAdapter as w, ALL_BUCKET_UNITS as x, resolveCalendarBuckets as xt, decomposePatch as y, jsonValueAncestor as yt, ENCRYPTED_REASON as z };
+export { guardQuery as $, fkKey as A, ENCRYPTED_REASON as B, ALL_ISOLATION_LEVELS as C, resolveCalendarBuckets as Ct, createFailureCollector as D, createChangeRecorder as E, resolveDesignType as F, checkHavingKeys as G, assertGeoPoint as H, geoIndexNotFoundMessage as I, groupSourceVerdict as J, classifyQueryPath as K, searchIndexNotFoundMessage as L, IntegrityStrategy as M, NativeIntegrity as N, computeForeignKeyDiff as O, AtscriptDbReadable as P, guardPaths as Q, vectorIndexNotFoundMessage as R, ALL_BUCKET_UNITS as S, normalizeComputedSelect as St, BaseDbAdapter as T, nestDottedWith as Tt, bucketSourceVerdict as U, acceptedOperatorsHint as V, canFilterLeaf as W, guardFilter as X, guardAggregate as Y, guardPath as Z, isVersionExemptPatch as _, relationalColumnName as _t, computeSchemaHash as a, FieldMappingStrategy as at, fkLookupTargetOf as b, isJsonValueField as bt, computeViewSnapshot as c, INTEGER_REGEX_OP as ct, snapshotToExistingTableOptions as d, resolveFulltextIndex as dt, narrowerFilterOps as et, viewSnapshotSources as f, searchTermInteger as ft, AtscriptDbTable as g, isGeoPointType as gt, isViewType as h, isGeoIndexableType as ht, canonicalizeQueryNode as i, DocumentFieldMapper as it, hasForeignKeyChanges as j, fkColumns as k, serializeDefaultValue as l, defaultFulltextIndex as lt, isAtscriptDbView as m, TableMetadata as mt, isColumnTypeChanged as n, unsupportedOperatorMessage as nt, computeTableHash as o, UniquSelect as ot, AtscriptDbView as p, splitFulltextFields as pt, collectQueryPaths as q, sameDefaultValue as r, RelationalFieldMapper as rt, computeTableSnapshot as s, numericOperandProblem as st, computeColumnDiff as t, sortFieldNames as tt, snapshotToExistingColumns as u, describeFulltext as ut, assertNoVersionWrites as v, aliasTargetOf as vt, ALL_VIEW_CAPABILITIES as w, NoopLogger as wt, ApplicationIntegrity as x, jsonValueAncestor as xt, decomposePatch as y, isBucketableField as yt, ADAPTER_FILTER_REASON as z };