@atscript/db 0.1.154 → 0.1.155

package/dist/{column-diff-qnzx1o3c.cjs → column-diff-DMkGYAGM.cjs}

@@ -1,12 +1,12 @@
 const require_db_error = require("./db-error-JcfJqqpk.cjs");
 const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
 const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
+const require_validator = require("./validator-DHwSyBej.cjs");
 const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 require("./agg.cjs");
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-BxWwh3wf.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_async_hooks = require("node:async_hooks");
@@ -215,7 +215,7 @@ function sourceIndex(type) {
 			if (metadata.has("db.ignore") || navFields.has(path)) idx.unstored.add(path);
 			if (metadata.has("db.column.derived") && fieldType.ref?.field) idx.derived.set(path, fieldType.ref.field);
 			if (metadata.has("db.encrypted")) storage.push([path, false]);
-			else if (metadata.has("db.json") || resolveDesignType(fieldType) === "array") storage.push([path, true]);
+			else if (metadata.has("db.json") || resolveDesignType(fieldType) === "array" || isStructuredMixedUnion(fieldType)) storage.push([path, true]);
 		}
 		storage.sort(([a], [b]) => a.split(".").length - b.split(".").length);
 		for (const [path, json] of storage) if (require_object.findAncestorInSet(path, idx.jsonRoots) === void 0 && require_object.findAncestorInSet(path, idx.encrypted) === void 0) (json ? idx.jsonRoots : idx.encrypted).add(path);
@@ -264,8 +264,8 @@ function sourceFieldMetadata(sourceType, logicalPath) {
 * aggregate's field, a predicate operand) to where it is physically stored.
 * Internal — `AtscriptDbView.resolveRefSource` is the public entry.
 *
-* Relational rules (`TableMetadata`'s): the outermost `@db.json` or array
-* node with segments remaining is the column and the rest becomes
+* Relational rules (`TableMetadata`'s): the outermost `@db.json`, array or
+* structured mixed union (`isStructuredMixedUnion`) node with segments remaining is the column and the rest becomes
 * {@link TViewSource.jsonPath}; a flattened leaf is its parent segments
 * joined with `__` plus its `@db.column` (or segment); a top-level field is
 * its `@db.column` or name. Nested-object adapters use the document path
@@ -297,7 +297,8 @@ function resolveViewSource(sourceType, logicalPath, nestedObjects) {
 		};
 	}
 	const jsonRoot = require_object.selfOrAncestor(logicalPath, idx.jsonRoots);
-	const optional = require_object.selfOrAncestor(logicalPath, idx.optional) !== void 0 || jsonRoot !== void 0 && jsonRoot !== logicalPath;
+	const presence = require_validator.pathPresence(sourceType, logicalPath);
+	const optional = (presence === void 0 ? require_object.selfOrAncestor(logicalPath, idx.optional) !== void 0 : presence !== "required") || jsonRoot !== void 0 && jsonRoot !== logicalPath;
 	if (!node) return {
 		column: logicalPath,
 		designType: "unknown",
@@ -385,6 +386,38 @@ function relationalColumnName(path, override, flattened) {
 function isNavRelation(metadata) {
 	return metadata.has("db.rel.to") || metadata.has("db.rel.from") || metadata.has("db.rel.via");
 }
+/**
+* A union whose value members disagree on their design type and include a
+* structure — `Addr | string`, or the leaf `a` of `{ a: Addr } | { a: string }`.
+* It has no column layout of its own: relational storage keeps it as one
+* JSON column, like `@db.json` (since 0.1.155).
+*/
+function isStructuredMixedUnion(type) {
+	if (type.type.kind !== "union" || resolveDesignType(type) !== "union") return false;
+	return require_validator.unionValueMembers(type).members.some((member) => {
+		const kind = member.type.kind;
+		return kind === "object" || kind === "array" || kind === "tuple" || kind === "intersection";
+	});
+}
+/**
+* The type a column of `type` is described by: the value member of a
+* nullable union (`number.int | null` → `number.int`, so type mappers see
+* its tags) carrying the field's own annotations and optionality, else
+* `type` itself.
+*/
+function columnType(type) {
+	const member = require_validator.soleUnionMember(type);
+	if (!member) return type;
+	return {
+		__is_atscript_annotated_type: true,
+		type: member.type,
+		metadata: type.metadata,
+		optional: type.optional,
+		id: member.id,
+		ref: member.ref,
+		validator: (...args) => type.validator(...args)
+	};
+}
 /** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
 function isGeoPointType(fieldType) {
 	return fieldType.type.tags?.has("geoPoint") === true;
@@ -554,6 +587,9 @@ var TableMetadata = class {
 	_alwaysAddressable;
 	_collateMap = /* @__PURE__ */ new Map();
 	_columnFromMap = /* @__PURE__ */ new Map();
+	/** The annotated type `build()` ran on — the root of {@link presence}. */
+	_rootType;
+	_presence = /* @__PURE__ */ new Map();
 	constructor(nestedObjects) {
 		this.nestedObjects = nestedObjects;
 	}
@@ -561,6 +597,72 @@ var TableMetadata = class {
 		return this._built;
 	}
 	/**
+	* Whether the value of the LOGICAL field `path` is always there, may be
+	* NULL / missing, or is declared by only some members of a union of
+	* objects on the way ({@link TPathPresence}); `undefined` inside an array.
+	* @since 0.1.155
+	*/
+	presence(path) {
+		if (this._presence.has(path)) return this._presence.get(path);
+		const root = this._rootType;
+		const answer = root ? require_validator.pathPresence(root, path) : void 0;
+		this._presence.set(path, answer);
+		return answer;
+	}
+	/**
+	* Whether the LOGICAL field `path` can hold NULL (or be missing): it or a
+	* parent object is optional or a `| null` union, or only some members of
+	* a union of objects declare it. Inside an array: the field or a parent
+	* is optional.
+	* @since 0.1.155
+	*/
+	isNullable(path) {
+		const presence = this.presence(path);
+		if (presence !== void 0) return presence !== "required";
+		for (let p = path;;) {
+			if (this.flatMap.get(p)?.optional === true) return true;
+			const dot = p.lastIndexOf(".");
+			if (dot === -1) return false;
+			p = p.slice(0, dot);
+		}
+	}
+	_objectLeaves;
+	/**
+	* The stored fields under the object field `path` that a null test on the
+	* object reads (`rewriteObjectNullTests`, since 0.1.155): its leaf columns
+	* on relational storage, its scalar / array / JSON fields on document
+	* storage (not inside an array or a JSON value). `undefined` when `path`
+	* is no stored object (a leaf, a `@db.json` / encrypted / ignored field,
+	* a navigation relation, inside a JSON value, unknown).
+	*/
+	objectLeaves(path) {
+		this._objectLeaves ??= /* @__PURE__ */ new Map();
+		if (this._objectLeaves.has(path)) return this._objectLeaves.get(path);
+		let leaves;
+		const fd = this.descriptorByPath.get(path);
+		if (require_object.findAncestorInSet(path, this.jsonValueParents) === void 0 && (this.nestedObjects ? fd !== void 0 && fd.designType === "object" && fd.storage !== "json" : this.flattenedParents.has(path) && !this.ignoredFields.has(path))) {
+			const prefix = `${path}.`;
+			leaves = [];
+			for (const [leaf, leafFd] of this.descriptorByPath) {
+				if (!leaf.startsWith(prefix) || leafFd.designType === "object") continue;
+				if (require_object.findAncestorInSet(leaf, this.jsonValueParents) !== void 0) continue;
+				if (this.presence(leaf) === void 0) continue;
+				leaves.push(leaf);
+			}
+		}
+		this._objectLeaves.set(path, leaves);
+		return leaves;
+	}
+	/**
+	* Whether the column of `path` is nullable: {@link isNullable}, except
+	* inside an array (document storage only), where the field's own
+	* optionality counts.
+	*/
+	_columnNullable(path, type) {
+		const presence = this.presence(path);
+		return presence === void 0 ? type.optional === true : presence !== "required";
+	}
+	/**
 	* {@link documentPath} over this table's `columnMap`. A `@db.column.derived`
 	* field has no stored path of its own: it maps to its source leaf.
 	*/
@@ -604,6 +706,7 @@ var TableMetadata = class {
 	build(type, adapter, logger) {
 		if (this._built) return;
 		adapter.onBeforeFlatten?.(type);
+		this._rootType = type;
 		const collected = [];
 		this.flatMap = (0, _atscript_typescript_utils.flattenAnnotatedType)(type, {
 			topLevelArrayTag: adapter.getTopLevelArrayTag?.() ?? "db.__topLevelArray",
@@ -662,10 +765,13 @@ var TableMetadata = class {
 	* into the synthetic flat entry of the prop's path, so a member's
 	* annotations would reach the column (DDL type, size, default). Since
 	* atscript 0.1.103 a built-in primitive member carries its built-in
-	* annotations (`number.timestamp.created | null` → `@db.default.now`,
-	* `string.char` → `@expect.maxLength 1`). Rebuild such an entry from the
-	* prop's own annotations plus the non-`db.*` annotations of named members
-	* (aliases, interfaces), so the column is described as before 0.1.103.
+	* annotations (`string.char` → `@expect.maxLength 1`). Rebuild such an
+	* entry from the prop's own annotations plus the non-`db.*` annotations of
+	* named members (aliases, interfaces), so the column is described as before
+	* 0.1.103. Exception: the one non-`null` member of `T | null` is the
+	* column's type, so its `db.*` annotations apply too — `createdAt:
+	* number.timestamp.created | null` gets `@db.default.now` like
+	* `createdAt: number.timestamp.created`.
 	*/
 	_dropMemberMetadata(collected) {
 		const byPath = /* @__PURE__ */ new Map();
@@ -678,12 +784,16 @@ var TableMetadata = class {
 			if (!entries.some((e) => e.member)) continue;
 			const flat = this.flatMap.get(path);
 			if (!flat?.__flat_union) continue;
+			const prop = entries.find((e) => !e.member);
+			const base = prop && require_validator.columnUnionBase(prop.type);
 			const target = flat.metadata;
 			target.clear();
 			for (const entry of entries) {
-				if (entry.member && isInlinePrimitive(entry.type)) continue;
-				for (const [key, value] of entry.metadata) if (!entry.member || !key.startsWith("db.")) target.set(key, value);
+				const inline = entry.member && isInlinePrimitive(entry.type);
+				const isBase = entry.member && entry.type === base;
+				for (const [key, value] of entry.metadata) if (!entry.member || (key.startsWith("db.") ? isBase : !inline)) target.set(key, value);
 			}
+			if (base && prop) prop.metadata = target;
 		}
 	}
 	/**
@@ -706,7 +816,7 @@ var TableMetadata = class {
 	* Scans `@db.*` and `@meta.id` annotations on a field during flattening.
 	*/
 	_scanGenericAnnotations(fieldName, fieldType, metadata, logger) {
-		if (metadata.has("meta.id")) {
+		if (metadata.has("meta.id") && !fieldName.includes(".")) {
 			this.primaryKeys.push(fieldName);
 			this.originalMetaIdFields.push(fieldName);
 		}
@@ -969,7 +1079,7 @@ var TableMetadata = class {
 			const isJson = this.jsonFields.has(path);
 			const isArray = designType === "array";
 			const isObject = designType === "object";
-			if (isArray) this.jsonFields.add(path);
+			if (isArray || isStructuredMixedUnion(type)) this.jsonFields.add(path);
 			else if (isObject && isJson) {} else if (isObject && !isJson) this.flattenedParents.add(path);
 		}
 		for (const ignoredField of this.ignoredFields) if (this.flattenedParents.has(ignoredField)) {
@@ -1071,6 +1181,7 @@ var TableMetadata = class {
 			const isJson = this.jsonFields.has(path);
 			const isFlattened = !skipFlattening && require_object.findAncestorInSet(path, this.flattenedParents) !== void 0;
 			const designType = isEncrypted ? "string" : isJson ? "json" : resolveDesignType(type);
+			const colType = columnType(type);
 			let storage;
 			if (skipFlattening) storage = "column";
 			else if (isEncrypted) storage = isFlattened ? "flattened" : "column";
@@ -1089,10 +1200,10 @@ var TableMetadata = class {
 			if (quantityRef) this.quantityRefByField.set(path, quantityRef);
 			descriptors.push({
 				path,
-				type,
+				type: colType,
 				physicalName,
 				designType,
-				optional: type.optional === true,
+				optional: skipFlattening ? type.optional === true : this._columnNullable(path, type),
 				isPrimaryKey: this.primaryKeys.includes(path),
 				ignored: this.ignoredFields.has(path),
 				defaultValue: this.defaults.get(path),
@@ -1106,7 +1217,7 @@ var TableMetadata = class {
 				unitCode,
 				unitRefField,
 				encrypted: isEncrypted || underEncrypted || void 0,
-				isGeoPoint: isGeoPointType(type) || void 0,
+				isGeoPoint: isGeoPointType(colType) || void 0,
 				derived: this.derivedFields.get(path),
 				computed: computedMeta(rootType, path)
 			});
@@ -1234,7 +1345,7 @@ var TableMetadata = class {
 		for (const index of this.indexes.values()) for (const field of index.fields) {
 			const ftype = this.flatMap.get(field.name);
 			if (ftype) {
-				field.optional = ftype.optional === true;
+				field.optional = this._columnNullable(field.name, ftype);
 				field.designType = ftype.type.tags?.has("objectId") ? "objectId" : resolveDesignType(ftype);
 			}
 			field.name = this.physicalPath(field.name);
@@ -1647,6 +1758,78 @@ function rewriteIntegerRegex(filter, meta) {
 	return out ?? filter;
 }
 //#endregion
+//#region src/query/object-null.ts
+/**
+* Whether a filter entry's value only asks if the value is there: `null`,
+* `{ $eq: null }`, `{ $ne: null }`, `{ $exists: true | false }` (and
+* combinations of them).
+*/
+function isNullTest(value) {
+	if (value === null) return true;
+	if (!require_object.isPlainObject(value)) return false;
+	const ops = Object.entries(value);
+	return ops.length > 0 && ops.every(([op, operand]) => op === "$exists" ? typeof operand === "boolean" : (op === "$eq" || op === "$ne") && operand === null);
+}
+/**
+* The leaf form of one null test on an object (see
+* {@link rewriteObjectNullTests}) as `$and` members: absent — `$exists: false`
+* on every leaf; present — one `$or` of `$exists: true` per leaf.
+*/
+function objectTest(value, leaves) {
+	const ops = value === null ? { $eq: null } : value;
+	const out = [];
+	for (const [op, operand] of Object.entries(ops)) {
+		const present = op === "$exists" ? operand : op === "$ne";
+		const tests = leaves.map((leaf) => ({ [leaf]: { $exists: present } }));
+		if (present) out.push({ $or: tests });
+		else out.push(...tests);
+	}
+	return out;
+}
+/**
+* A null test on a stored object (since 0.1.155) — `{ address: null }`,
+* `{ address: { $ne: null } }`, `{ address: { $exists: … } }` — on the
+* object's leaves: the object is null when none of its fields holds a value
+* (`$exists: false` on every leaf), present when one does. Relational
+* storage has no column for the object (an all-NULL row reads back as
+* `null`); document storage answers the same, so an object stored as `{}`
+* or with only null fields counts as null everywhere. LOGICAL filter;
+* copy-on-write (the same object comes back when nothing changed).
+*/
+function rewriteObjectNullTests(filter, meta) {
+	if (!require_object.isPlainObject(filter)) return filter;
+	let out;
+	const extra = [];
+	for (const [key, value] of Object.entries(filter)) {
+		let next = value;
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) {
+				const mapped = value.map((f) => rewriteObjectNullTests(f, meta));
+				if (mapped.some((m, i) => m !== value[i])) next = mapped;
+			}
+		} else if (key === "$not") next = rewriteObjectNullTests(value, meta);
+		else if (!key.startsWith("$") && isNullTest(value)) {
+			const leaves = meta.objectLeaves(key);
+			if (leaves && leaves.length > 0) {
+				extra.push(...objectTest(value, leaves));
+				out ??= { ...filter };
+				delete out[key];
+				continue;
+			}
+		}
+		if (next !== value) {
+			out ??= { ...filter };
+			out[key] = next;
+		}
+	}
+	if (!out) return filter;
+	if (extra.length > 0) {
+		const and = out.$and;
+		out.$and = [...Array.isArray(and) ? and : [], ...extra];
+	}
+	return out;
+}
+//#endregion
 //#region src/query/aggregate-expr.ts
 /**
 * Output aliases of the computed `$select` entries of a grouped query —
@@ -2298,7 +2481,7 @@ var FieldMappingStrategy = class {
 	* translate predicate operands at deeper levels).
 	*/
 	translateFilter(filter, meta, depth = 0) {
-		filter = rewriteIntegerRegex(filter, meta);
+		filter = rewriteObjectNullTests(rewriteIntegerRegex(filter, meta), meta);
 		const has = require_nested_writer.containsRelationFilter(filter);
 		const resolved = has ? require_nested_writer.resolveRelationFilterTree(filter, meta, depth) : filter;
 		return this.noteTranslated(filter, this.translateResolvedFilter(resolved, meta), has);
@@ -2640,13 +2823,13 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 					current = created;
 				} else current = next;
 			}
-			current[col.last] = value;
+			if (!col.partial || value !== null && value !== void 0) current[col.last] = value;
 		}
 		for (const parent of plan.parents) collapseNullParent(result, parent);
 		return result;
 	}
 	translateQuery(query, meta) {
-		const logical = rewriteIntegerRegex(query.filter, meta);
+		const logical = rewriteObjectNullTests(rewriteIntegerRegex(query.filter, meta), meta);
 		const has = require_nested_writer.containsRelationFilter(logical);
 		const filter = has ? require_nested_writer.resolveRelationFilterTree(logical, meta, 0) : logical;
 		if (!meta.requiresMappings) {
@@ -2701,7 +2884,11 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return result;
 	}
 	prepareForWrite(payload, meta, adapter) {
-		if (meta.requiresMappings && !meta.onlyColumnRenames) return this.formatWriteValues(this.flattenWritePayload(payload, meta, adapter), meta);
+		if (meta.requiresMappings && !meta.onlyColumnRenames) {
+			const flat = this.flattenWritePayload(payload, meta, adapter);
+			nullAbsentNested(payload, flat, meta);
+			return this.formatWriteValues(flat, meta);
+		}
 		const data = { ...payload };
 		this.prepareCommon(data, meta, adapter);
 		if (meta.onlyColumnRenames) {
@@ -2728,7 +2915,7 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 			const suffix = operatorMatch ? operatorMatch[2] : "";
 			const fd = meta.leafByLogical.get(basePath);
 			const finalKey = (fd?.physicalName ?? basePath) + suffix;
-			if (fd?.storage === "json" && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
+			if (fd?.storage === "json" && value !== null && value !== void 0 && !suffix) result[finalKey] = JSON.stringify(value);
 			else result[finalKey] = value;
 		}
 		return this.formatWriteValues(result, meta);
@@ -2808,6 +2995,49 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return result;
 	}
 };
+const nestedColumns = /* @__PURE__ */ new WeakMap();
+function nestedColumnsFor(meta) {
+	let list = nestedColumns.get(meta);
+	if (list === void 0) {
+		list = [];
+		for (const [physical, fd] of meta.leafByPhysical) {
+			if (fd.derived || fd.isPrimaryKey || fd.storage === "column" || !fd.path.includes(".")) continue;
+			const segs = fd.path.split(".");
+			list.push({
+				physical,
+				parents: segs.slice(0, -1),
+				partial: meta.presence(fd.path) === "partial"
+			});
+		}
+		nestedColumns.set(meta, list);
+	}
+	return list;
+}
+/**
+* Every write through `prepareForWrite` stores a whole row (insert, replace).
+* A column the flattened row leaves out would take its column `DEFAULT` —
+* a `now` default below an absent optional object would make the object
+* reappear on read, and one of another union member's leaves would add a
+* field to the stored member. So a column below an absent / `null` parent
+* object, or one only some union members declare that the written member
+* leaves out, is written as `NULL` (since 0.1.155), as the document adapters
+* store such a row.
+*/
+function nullAbsentNested(payload, flat, meta) {
+	for (const col of nestedColumnsFor(meta)) {
+		if (col.physical in flat) continue;
+		let absent = false;
+		let current = payload;
+		for (const seg of col.parents) {
+			current = current[seg];
+			if (current === null || current === void 0 || typeof current !== "object") {
+				absent = true;
+				break;
+			}
+		}
+		if (absent || col.partial) flat[col.physical] = null;
+	}
+}
 /**
 * Per-table read plan of {@link RelationalFieldMapper.reconstructFromRead}:
 * the per-column decisions (coercion, JSON, nesting — the dot-path pre-split)
@@ -2827,12 +3057,14 @@ function compileReadPlan(meta) {
 	const fromFmts = meta.fromStorageFormatters;
 	const columns = /* @__PURE__ */ new Map();
 	for (const [physical, fd] of meta.leafByPhysical) {
-		const segs = (fd.storage === "json" || fd.storage === "flattened") && fd.path.includes(".") ? fd.path.split(".") : void 0;
+		const nested = (fd.storage === "json" || fd.storage === "flattened") && fd.path.includes(".");
+		const segs = nested ? fd.path.split(".") : void 0;
 		columns.set(physical, {
 			path: fd.path,
 			parents: segs?.slice(0, -1),
 			last: segs ? segs[segs.length - 1] : fd.path,
 			json: fd.storage === "json",
+			partial: nested && meta.presence(fd.path) === "partial",
 			coerce: fd.designType === "boolean" ? toBool : fd.designType === "decimal" ? toDecimalString : void 0,
 			fromFmt: fromFmts?.get(physical)
 		});
@@ -2843,15 +3075,16 @@ function compileReadPlan(meta) {
 		parents.push({
 			ancestors: segs.slice(0, -1),
 			last: segs[segs.length - 1],
-			optional: !!meta.flatMap?.get(parentPath)?.optional
+			presence: meta.presence(parentPath) ?? "required"
 		});
 	}
+	parents.sort((a, b) => b.ancestors.length - a.ancestors.length);
 	return {
 		columns,
 		parents
 	};
 }
-/** If every child of a flattened parent is null / undefined, collapse it (`null` when optional, else `{}`). */
+/** If every child of a flattened parent is null / undefined, collapse it (see {@link TReadParent}). */
 function collapseNullParent(obj, parent) {
 	let current = obj;
 	const ancestors = parent.ancestors;
@@ -2866,7 +3099,8 @@ function collapseNullParent(obj, parent) {
 		const v = parentObj[k];
 		if (v !== null && v !== void 0) return;
 	}
-	current[parent.last] = parent.optional ? null : {};
+	if (parent.presence === "partial") delete current[parent.last];
+	else current[parent.last] = parent.presence === "nullable" ? null : {};
 }
 /**
 * Per-table write plan of the relational flatten: each logical path's
@@ -3308,6 +3542,10 @@ function collectQueryPaths(query, aggregate) {
 			path,
 			predicate,
 			relation: relationOpsOf(value)
+		} : isNullTest(value) ? {
+			path,
+			predicate,
+			nullTest: true
 		} : {
 			path,
 			predicate
@@ -3407,10 +3645,11 @@ function pathSourceOf(meta) {
 * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
 * see and is authoritative — the HTTP gate always answers first.
 */
-function guardPath(meta, adapter, path, op, predicate = "compare") {
+function guardPath(meta, adapter, path, op, predicate = "compare", nullTest = false) {
 	const verb = OP_VERB[op];
 	const { kind, parent } = classifyQueryPath(pathSourceOf(meta), path);
 	if (predicate === "relation" && kind !== "nav" && kind !== "unknown") throw pathError(path, `"$some" / "$none" are only valid on a navigation relation — "${path}" is not one`);
+	if (op === "filter" && nullTest && meta.objectLeaves(path)?.length) return;
 	switch (kind) {
 		case "nav":
 			if (op === "filter" && predicate === "relation" && parent === void 0) return;
@@ -3495,7 +3734,7 @@ function guardPaths(meta, adapter, query, aggregate = false, state) {
 	if (refs.unsupportedOperator !== void 0) throw pathError(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
 	let relState = state;
 	for (const ref of refs.filter) {
-		guardPath(meta, adapter, ref.path, "filter", ref.predicate);
+		guardPath(meta, adapter, ref.path, "filter", ref.predicate, ref.nullTest);
 		if (ref.predicate === "relation") guardRelationRef(meta, adapter, ref, relState ??= require_nested_writer.relGuardState());
 	}
 	for (const path of refs.sort) guardPath(meta, adapter, path, "sort");
@@ -3637,10 +3876,12 @@ var NullsSource = class {
 	}
 	/**
 	* Whether ordering by the LOGICAL field `path` can meet NULL (or a missing
-	* value): the field or one of its parent objects is optional, the field is
-	* a derived column, it is not a known field, or the source is a view. A
-	* `$nulls` entry on any other field changes nothing and is dropped, so the
-	* plain `ORDER BY` keeps using the index.
+	* value): the field can hold NULL (`TableMetadata.isNullable` — it or a
+	* parent object is optional or a `| null` union, or only some members of a
+	* union of objects declare it), the field is a derived column, it is not a
+	* known field, or the source is a view. A `$nulls` entry on any other
+	* field changes nothing and is dropped, so the plain `ORDER BY` keeps
+	* using the index.
 	*/
 	nullable(path) {
 		let answer = this._nullable.get(path);
@@ -3654,12 +3895,7 @@ var NullsSource = class {
 		const { meta } = this._init;
 		const fd = meta.descriptorByPath.get(path);
 		if (!fd || fd.derived) return true;
-		for (let p = path;;) {
-			if (meta.flatMap.get(p)?.optional === true) return true;
-			const dot = p.lastIndexOf(".");
-			if (dot === -1) return false;
-			p = p.slice(0, dot);
-		}
+		return meta.isNullable(path);
 	}
 	/**
 	* The effective `$nulls` of the `$sort` keys of one read: the request's
@@ -3774,7 +4010,9 @@ function geoIndexNotFoundMessage(tableName, indexName) {
 * otherwise trips up every adapter author.
 *
 * For union types (e.g., from flattened `{...} | {...}` objects):
-* - If all members resolve to the same type → returns that type (strong type)
+* - `null` / `undefined` members are left out (since 0.1.155): `T | null`
+*   resolves to the design type of `T`
+* - If all other members resolve to the same type → returns that type (strong type)
 * - If members disagree → returns `'union'` (out of scope for type management)
 */
 function resolveDesignType(fieldType) {
@@ -3782,9 +4020,9 @@ function resolveDesignType(fieldType) {
 	if (fieldType.type.kind === "object") return "object";
 	if (fieldType.type.kind === "array") return "array";
 	if (fieldType.type.kind === "union") {
-		const items = fieldType.type.items;
-		if (items.length > 0) {
-			const resolved = items.map((item) => resolveDesignType(item));
+		const { members } = require_validator.unionValueMembers(fieldType);
+		if (members.length > 0) {
+			const resolved = members.map((item) => resolveDesignType(item));
 			if (resolved.every((type) => type === resolved[0])) return resolved[0];
 		}
 		return "union";
@@ -4440,21 +4678,13 @@ var AtscriptDbReadable = class {
 	_totalOrderKeys() {
 		if (this._totalOrderKeysCache) return this._totalOrderKeysCache;
 		const meta = this._meta;
-		const nullable = (logical) => {
-			for (let path = logical;;) {
-				if (meta.flatMap.get(path)?.optional === true) return true;
-				const dot = path.lastIndexOf(".");
-				if (dot === -1) return false;
-				path = path.slice(0, dot);
-			}
-		};
 		const sets = [];
 		if (meta.primaryKeys.length > 0) sets.push(meta.primaryKeys.map((f) => meta.physicalPath(f)));
 		for (const index of meta.indexes.values()) {
 			if (index.type !== "unique") continue;
-			if (index.fields.every((f) => f.optional !== true && !nullable(meta.physicalToPath.get(f.name) ?? f.name))) sets.push(index.fields.map((f) => f.name));
+			if (index.fields.every((f) => f.optional !== true && !meta.isNullable(meta.physicalToPath.get(f.name) ?? f.name))) sets.push(index.fields.map((f) => f.name));
 		}
-		for (const prop of meta.uniqueProps) if (!nullable(prop)) sets.push([meta.physicalPath(prop)]);
+		for (const prop of meta.uniqueProps) if (!meta.isNullable(prop)) sets.push([meta.physicalPath(prop)]);
 		this._totalOrderKeysCache = sets;
 		return sets;
 	}
@@ -6075,7 +6305,7 @@ var BaseDbAdapter = class {
 	}
 	/**
 	* Whether the table has at least one row. Schema sync uses it in the
-	* pre-flight phase to refuse a primary-key change on a populated table.
+	* pre-flight phase to check a primary-key change on a populated table.
 	* Override with an EXISTS/LIMIT 1 probe — this default is `count() > 0`,
 	* a full scan on some engines, and it can only answer for the adapter's
 	* OWN table: for another `tableName` (or on an administrative adapter
@@ -6495,6 +6725,10 @@ function flattenPatchPayload(payload, prefix, update, meta, table) {
 		const key = prefix ? `${prefix}.${_key}` : _key;
 		if (primaryKeys.includes(key)) continue;
 		if (!(typeof value === "object" && value !== null && !Array.isArray(value))) {
+			if (value === null && meta.flattenedParents.has(key)) {
+				for (const lp of meta.optionalLeavesByLogicalParent.get(key) ?? []) update[lp] = null;
+				continue;
+			}
 			update[key] = value;
 			continue;
 		}
@@ -7672,26 +7906,56 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* full row). Function defaults (`now` / `uuid` / `increment` / custom) the
 	* adapter handles natively are NOT filled — the field stays absent so the
 	* engine's own default applies. The version column is never touched.
+	* A nested field (`audit.createdAt`) is filled inside its object, only when
+	* that object is present (an absent or `null` embedded object stays so), and
+	* in every object of an array on the way; a field inside a JSON value or an
+	* array has no column default, so the SDK fills its function default too.
 	*/
 	_applyDefaults(data) {
 		const nativeFns = this.adapter.nativeDefaultFns();
 		const versionField = this._meta.versionField;
 		for (const [field, def] of this._meta.defaults.entries()) {
 			if (field === versionField) continue;
-			if (data[field] === void 0) {
-				if (def.kind === "value") data[field] = this._valueDefault(field, def.value);
-				else if (def.kind === "fn" && !nativeFns.has(def.fn)) switch (def.fn) {
-					case "now":
-						data[field] = Date.now();
-						break;
-					case "uuid":
-						data[field] = crypto.randomUUID();
-						break;
-				}
+			let make;
+			if (def.kind === "value") make = () => this._valueDefault(field, def.value);
+			else if (def.kind === "fn" && (!nativeFns.has(def.fn) || require_object.findAncestorInSet(field, this._meta.jsonParents) !== void 0)) {
+				if (def.fn === "now") make = Date.now;
+				else if (def.fn === "uuid") make = () => crypto.randomUUID();
 			}
+			if (!make) continue;
+			if (!field.includes(".")) {
+				if (data[field] === void 0) data[field] = make();
+			} else if (this._nestedDefaultFillable(field)) fillNested(data, field.split("."), 0, make);
 		}
 		return data;
 	}
+	/** {@link _nestedDefaultFillable} per nested default path. */
+	_fillableDefaults;
+	/**
+	* Whether every parent of the nested default `field` is one object type —
+	* an object, `T | null` of one, or an array of one. Below a tuple or a
+	* union of several types the default cannot be placed (the item it belongs
+	* to is unknown), so it is not filled.
+	*/
+	_nestedDefaultFillable(field) {
+		const cache = this._fillableDefaults ??= /* @__PURE__ */ new Map();
+		let fillable = cache.get(field);
+		if (fillable === void 0) {
+			fillable = true;
+			for (let dot = field.indexOf("."); dot !== -1; dot = field.indexOf(".", dot + 1)) {
+				let type = this.flatMap.get(field.slice(0, dot));
+				if (type?.type.kind === "union") type = require_validator.soleUnionMember(type);
+				if (type?.type.kind === "array") type = type.type.of;
+				if (type?.type.kind === "union") type = require_validator.soleUnionMember(type);
+				if (type?.type.kind !== "object") {
+					fillable = false;
+					break;
+				}
+			}
+			cache.set(field, fillable);
+		}
+		return fillable;
+	}
 	/**
 	* Parsed `@db.default 'literal'` values that are primitives — reused for
 	* every row (an object / array default is parsed per row: each row gets
@@ -7857,6 +8121,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		return this.createValidator({ plugins: adapterPlugins });
 	}
 };
+/**
+* Sets `segs[i..]` to `make()` where it is `undefined`, inside present plain
+* objects only — fanned out over the objects of every array on the way.
+*/
+function fillNested(value, segs, i, make) {
+	if (Array.isArray(value)) {
+		for (const item of value) fillNested(item, segs, i, make);
+		return;
+	}
+	if (!require_object.isPlainObject(value)) return;
+	const key = segs[i];
+	if (i === segs.length - 1) {
+		if (value[key] === void 0) value[key] = make();
+	} else fillNested(value[key], segs, i + 1, make);
+}
 //#endregion
 //#region src/table/view-read-plan.ts
 /** Design types whose `=` compares one scalar to one scalar on every engine. */
@@ -8969,7 +9248,9 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 					});
 				}
 				const desiredDefault = serializeDefaultValue(field.defaultValue);
-				if (existingCol.dflt_value !== void 0 && existingCol.dflt_value !== desiredDefault) defaultChanged.push({
+				const fn = field.defaultValue?.kind === "fn" ? field.defaultValue.fn : void 0;
+				const missingNative = fn !== void 0 && fn !== "increment" && opts?.nativeDefaultFns?.has(fn) === true;
+				if ((existingCol.dflt_value !== void 0 || missingNative) && existingCol.dflt_value !== desiredDefault) defaultChanged.push({
 					field,
 					oldDefault: existingCol.dflt_value,
 					newDefault: desiredDefault
@@ -9366,6 +9647,12 @@ Object.defineProperty(exports, "numericOperandProblem", {
 		return numericOperandProblem;
 	}
 });
+Object.defineProperty(exports, "relationalColumnName", {
+	enumerable: true,
+	get: function() {
+		return relationalColumnName;
+	}
+});
 Object.defineProperty(exports, "resolveCalendarBuckets", {
 	enumerable: true,
 	get: function() {
@@ -9390,6 +9677,12 @@ Object.defineProperty(exports, "searchTermInteger", {
 		return searchTermInteger;
 	}
 });
+Object.defineProperty(exports, "serializeDefaultValue", {
+	enumerable: true,
+	get: function() {
+		return serializeDefaultValue;
+	}
+});
 Object.defineProperty(exports, "snapshotToExistingColumns", {
 	enumerable: true,
 	get: function() {