@happyvertical/smrt-core 0.51.38 → 0.52.0

package/dist/object.js

@@ -239,6 +239,22 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*/
 	_insertOnly = false;
 	/**
+	* The slug {@link getSlug} derived from a human value (`name`, `title` or
+	* `label`), or `null` when the slug was set explicitly or derived from the
+	* id. A human value is not an identity — two pictures named `photo.jpg`, two
+	* articles titled "Council meeting" — so a NEW object whose natural key only
+	* matches an existing row through such a slug never adopts that row: it
+	* saves under a unique slug instead (see {@link writeNaturalKeyRow}).
+	*/
+	_derivedSlug = null;
+	/** The slug as first derived, before any free-slug move (see above). */
+	_derivedSlugBase = null;
+	/**
+	* Set by `getOrUpsert()`'s create path: a derived slug then names the row
+	* to update in place, as an explicit key does, instead of moving.
+	*/
+	_adoptNaturalKey = false;
+	/**
 	* Unique identifier for the object
 	*/
 	_id;
@@ -380,6 +396,17 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	requireInsertOnSave() {
 		this._insertOnly = true;
 	}
+	/**
+	* Makes the initial `save()` update the row its natural key names in place
+	* — even when the slug was derived from `name`/`title`/`label` — instead of
+	* moving to a free slug. Set by `collection.getOrUpsert()`'s create path,
+	* whose contract is "update the row this data identifies". The ownership
+	* guard still applies. No effect once the object is persisted.
+	* @internal
+	*/
+	adoptNaturalKeyOnSave() {
+		this._adoptNaturalKey = true;
+	}
 	async verifyStorageReady() {
 		await verifyPersistenceTable(this.db, this.tableName, this.constructor.name);
 	}
@@ -804,6 +831,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			data._meta_data = metaData;
 		}
 		let registeredFields = (this.getRegisteredClassInfo() ?? ObjectRegistry.getClass(this.getResolvedQualifiedName()))?.inheritedFields || ObjectRegistry.getFields(this.getResolvedQualifiedName());
+		const ownFieldKeys = new Set(registeredFields.keys());
 		if (isSTI) {
 			const descendants = getSTIHierarchyMembers(this.getResolvedQualifiedName());
 			if (descendants.length > 0) {
@@ -826,9 +854,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 				const fieldType = prop && typeof prop === "object" && "type" in prop && prop.type || fieldDef?.type;
 				if ((prop && typeof prop === "object" && "__tenancy" in prop ? prop.__tenancy : void 0)?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField) if (isSTI && fieldDef?.type === "meta") metaData[key] = null;
 				else data[key] = null;
-				else if (fieldType === "text") if (isSTI && fieldDef?.type === "meta") metaData[key] = "";
-				else data[key] = "";
-				else if (fieldType === "json") {
+				else if (fieldType === "text") {
+					const emptyValue = isSTI && !ownFieldKeys.has(key) ? null : "";
+					if (isSTI && fieldDef?.type === "meta") metaData[key] = emptyValue;
+					else data[key] = emptyValue;
+				} else if (fieldType === "json") {
 					const defaultValue = fieldDef?.default ?? null;
 					if (isSTI && fieldDef?.type === "meta") metaData[key] = defaultValue;
 					else data[key] = defaultValue;
@@ -1018,7 +1048,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			else if (self.title) sourceField = String(self.title);
 			else if (self.label) sourceField = String(self.label);
 			else if (this.id) sourceField = String(this.id);
-			if (sourceField) this.slug = sourceField.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+			if (sourceField) {
+				this.slug = sourceField.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+				this._derivedSlug = sourceField === String(this.id) ? null : this.slug;
+				this._derivedSlugBase = this._derivedSlug;
+			}
 		}
 		return this.slug;
 	}
@@ -1228,13 +1262,32 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		const columns = prepared[0] ? Object.keys(prepared[0].data) : [];
 		const conflict = prepared[0]?.conflictColumns ?? [];
 		const identities = /* @__PURE__ */ new Set();
-		if (columns.length * added.length > 900 || prepared.some((entry) => {
+		const ownershipColumns = SmrtObject.ownershipColumnsFor(first.getResolvedQualifiedName());
+		if ([...ownershipColumns].some((column) => columns.includes(column) && !conflict.includes(column)) || columns.length * added.length > 900 || prepared.some((entry) => {
 			if (entry.writePlan.type !== "upsert" || JSON.stringify(Object.keys(entry.data)) !== JSON.stringify(columns) || JSON.stringify(entry.conflictColumns) !== JSON.stringify(conflict) || conflict.some((key) => entry.data[key] == null)) return true;
 			const identity = JSON.stringify(conflict.map((key) => entry.data[key]));
 			if (identities.has(identity)) return true;
 			identities.add(identity);
 			return false;
 		})) return false;
+		const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
+		const bindValue = (value) => value instanceof Date ? value.toISOString() : value === void 0 ? null : value !== null && typeof value === "object" ? JSON.stringify(value) : typeof value === "boolean" && engine === "sqlite" ? Number(value) : value;
+		if (added.length > 0 && conflict.length > 0) {
+			const probeValues = [];
+			const placeholder = () => engine === "postgres" ? `$${probeValues.length}` : "?";
+			const clauses = prepared.map(({ data }) => `(${conflict.map((column) => {
+				probeValues.push(bindValue(data[column]));
+				return `${quote(column)} = ${placeholder()}`;
+			}).join(" AND ")})`);
+			const removedIds = new Set(removed.map((item) => String(item.id).toLowerCase()));
+			let existingRows;
+			try {
+				existingRows = (await first.db.query(`SELECT ${quote("id")} FROM ${quote(first.tableName)} WHERE ${clauses.join(" OR ")}`, ...probeValues))?.rows ?? [];
+			} catch {
+				return false;
+			}
+			if (existingRows.some((row) => !removedIds.has(String(row.id).toLowerCase()))) return false;
+		}
 		const deletions = [];
 		for (const instance of removed) {
 			const context = createInterceptorContext(instance.constructor.name, "delete", void 0, void 0, instance.getResolvedQualifiedName());
@@ -1267,14 +1320,12 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			await GlobalInterceptors.executeBulkAfter("afterDelete", deletions);
 		}
 		if (added.length > 0) {
-			const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
 			const values = [];
 			const tuples = prepared.map(({ data }) => `(${columns.map((column) => {
-				const value = data[column];
-				values.push(value instanceof Date ? value.toISOString() : value === void 0 ? null : value !== null && typeof value === "object" ? JSON.stringify(value) : typeof value === "boolean" && engine === "sqlite" ? Number(value) : value);
+				values.push(bindValue(data[column]));
 				return engine === "postgres" ? `$${values.length}` : "?";
 			}).join(", ")})`);
-			const updates = columns.map((column) => `${quote(column)} = excluded.${quote(column)}`).join(", ");
+			const updates = columns.filter((column) => column !== "id" && column !== "created_at" && !ownershipColumns.has(column)).map((column) => `${quote(column)} = excluded.${quote(column)}`).join(", ");
 			const sql = `INSERT INTO ${quote(first.tableName)} (${columns.map(quote).join(", ")}) VALUES ${tuples.join(", ")} ON CONFLICT (${conflict.map(quote).join(", ")}) DO UPDATE SET ${updates}`;
 			await withEmbeddedWriteQueue(first.db, isEmbeddedDatabase(first.db), () => ErrorUtils.withRetry(async () => {
 				try {
@@ -1300,6 +1351,14 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		}
 		return true;
 	}
+	/**
+	* The columns that record a row's owner — see
+	* {@link ObjectRegistry.getOwnershipColumns} (declared, `@tenantId`-marked
+	* and runtime-registered ownership columns, plus `tenant_id`).
+	*/
+	static ownershipColumnsFor(qualifiedName) {
+		return ObjectRegistry.getOwnershipColumns(qualifiedName);
+	}
 	/** Shared preparation for ordinary saves and compatible bulk creates. */
 	async prepareSave(revisionGuard) {
 		const className = this.getResolvedClassName();
@@ -1333,6 +1392,8 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		data.updated_at = this.updated_at;
 		await this.coerceEmptyUuidValuesToNull(data);
 		const conflictColumns = ObjectRegistry.getConflictColumns(this.getResolvedQualifiedName());
+		const ownershipColumn = ObjectRegistry.getOwnershipTenantColumn(this.getResolvedQualifiedName());
+		if (ownershipColumn && conflictColumns.includes(ownershipColumn) && data[ownershipColumn] === void 0) data[ownershipColumn] = null;
 		const derivedColumns = this.getPersistenceDerivedColumns();
 		const registeredFields = ObjectRegistry.getFields(this.getResolvedQualifiedName());
 		const registeredColumns = new Set([...registeredFields].filter(([, field]) => field.type !== "oneToMany" && field.type !== "manyToMany").map(([name]) => toSnakeCase(name)));
@@ -1446,51 +1507,55 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
 			const useEmbeddedRevisionFallback = revisionGuard !== void 0 && usesEmbeddedRevisionFallback(this.db);
 			const serializeEmbeddedWrite = isEmbeddedDatabase(this.db);
+			const naturalKeyUpsert = writePlan.type === "upsert" && revisionGuard === void 0 && !(this._insertOnly && !this._persisted) && !(upsertConflictColumns.length === 1 && upsertConflictColumns[0] === "id");
 			let revisionMatched = true;
-			await withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, () => ErrorUtils.withRetry(async () => {
-				try {
-					if (writePlan.type === "updateById" || revisionGuard !== void 0) {
-						const { id: _id, ...updateData } = data;
-						if (useEmbeddedRevisionFallback) {
-							const current = await this.db.get(this.tableName, { id: data.id });
-							if (!current || !this.revisionsEqual(current.updated_at, revisionGuard)) {
+			let naturalKeyWrite = "upsert";
+			const adopted = {};
+			await withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, async () => {
+				if (naturalKeyUpsert) {
+					naturalKeyWrite = await this.writeNaturalKeyRow(data, upsertConflictColumns, adopted);
+					if (naturalKeyWrite === "done") return;
+				} else if (this._insertOnly && !this._persisted) await this.assertNullableNaturalKeyFree(data, conflictColumns);
+				const insertUnderFreshSlug = naturalKeyWrite === "insert";
+				return ErrorUtils.withRetry(async () => {
+					try {
+						if (writePlan.type === "updateById" || revisionGuard !== void 0) {
+							const { id: _id, ...updateData } = data;
+							if (useEmbeddedRevisionFallback) {
+								const current = await this.db.get(this.tableName, { id: data.id });
+								if (!current || !this.revisionsEqual(current.updated_at, revisionGuard)) {
+									revisionMatched = false;
+									return;
+								}
+							}
+							const updateResult = useEmbeddedRevisionFallback ? await this.db.upsert(this.tableName, ["id"], data) : await this.db.update(this.tableName, {
+								id: data.id,
+								...revisionGuard !== void 0 ? this.revisionPredicate(revisionGuard) : {}
+							}, updateData);
+							if (revisionGuard !== void 0 && updateResult.affected !== 1) {
 								revisionMatched = false;
 								return;
 							}
-						}
-						const updateResult = useEmbeddedRevisionFallback ? await this.db.upsert(this.tableName, ["id"], data) : await this.db.update(this.tableName, {
-							id: data.id,
-							...revisionGuard !== void 0 ? this.revisionPredicate(revisionGuard) : {}
-						}, updateData);
-						if (revisionGuard !== void 0 && updateResult.affected !== 1) {
-							revisionMatched = false;
-							return;
-						}
-						if (writePlan.type === "updateById") this.setMetaType(writePlan.qualifiedMetaType);
-					} else if (this._insertOnly && !this._persisted) await this.db.insert(this.tableName, data);
-					else await this.db.upsert(this.tableName, upsertConflictColumns, data);
-				} catch (error) {
-					if (error instanceof Error) {
-						const classification = classifyDatabaseError(error);
-						if (classification.kind === "unique_violation") {
-							const field = this.extractConstraintFieldFromChain(error, classification);
-							throw ValidationError.uniqueConstraint(field, this.getFieldValue(field));
-						}
-						if (classification.kind === "not_null_violation") {
-							const field = this.extractConstraintFieldFromChain(error, classification);
-							throw ValidationError.requiredField(field, className);
-						}
-						const operation = writePlan.type === "updateById" || revisionGuard !== void 0 ? `UPDATE ${this.tableName} (id-targeted)` : this._insertOnly && !this._persisted ? `INSERT INTO ${this.tableName}` : `UPSERT INTO ${this.tableName}`;
-						throw DatabaseError.queryFailed(operation, error);
+							if (writePlan.type === "updateById") this.setMetaType(writePlan.qualifiedMetaType);
+						} else if (this._insertOnly && !this._persisted || insertUnderFreshSlug) await this.db.insert(this.tableName, data);
+						else await this.db.upsert(this.tableName, upsertConflictColumns, data);
+					} catch (error) {
+						throw this.toTypedWriteError(error, writePlan.type === "updateById" || revisionGuard !== void 0 ? `UPDATE ${this.tableName} (id-targeted)` : this._insertOnly && !this._persisted || insertUnderFreshSlug ? `INSERT INTO ${this.tableName}` : `UPSERT INTO ${this.tableName}`);
 					}
-					throw error;
-				}
-			}, 3, 500));
+				}, 3, 500);
+			});
 			if (!revisionMatched) throw new RuntimeError(`Revision conflict while saving ${className}`, "RUNTIME_REVISION_CONFLICT", {
 				className,
 				id: this.id
 			});
 			revisionPersisted = true;
+			if (adopted.id) {
+				this.id = adopted.id;
+				if (adopted.createdAt != null) {
+					const createdAt = new Date(adopted.createdAt);
+					if (!Number.isNaN(createdAt.getTime())) this.created_at = createdAt;
+				}
+			}
 			await this.completeSave(interceptorContext);
 			return this;
 		} catch (error) {
@@ -1598,6 +1663,230 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		return new Date(nextRevisionTime);
 	}
 	/**
+	* Read the row a natural-key write would hit, directly (no read
+	* interceptors), retrying only transient failures like the write itself.
+	*/
+	async readNaturalKeyRow(filter) {
+		return ErrorUtils.withRetry(async () => {
+			try {
+				return await this.getCanonicalPersistedRow(filter);
+			} catch (error) {
+				if (error instanceof SmrtError) throw error;
+				throw DatabaseError.queryFailed(`get(${this.tableName}, natural-key identity)`, error instanceof Error ? error : new Error(String(error)));
+			}
+		}, 3, 500);
+	}
+	/**
+	* Strict inserts (`_insertOnly`, #1759) rely on the unique conflict index to
+	* reject a natural-key collision. A NULL in that key (a global row of a
+	* tenant-owned table, whose key leads with `tenant_id`) is distinct from
+	* every other NULL on SQLite, DuckDB and PostgreSQL before 15, so the index
+	* admits the duplicate the upsert path would have deduplicated. Check with
+	* the same `IS NULL` match the null-aware upsert uses and raise the unique
+	* violation the index would have.
+	*/
+	async assertNullableNaturalKeyFree(data, conflictColumns) {
+		if (conflictColumns.length === 0 || conflictColumns.length === 1 && conflictColumns[0] === "id" || !conflictColumns.every((column) => Object.hasOwn(data, column)) || !conflictColumns.some((column) => data[column] == null)) return;
+		const filter = {};
+		for (const column of conflictColumns) filter[column] = data[column] ?? null;
+		const existing = await this.readNaturalKeyRow(filter);
+		if (existing && existing.id !== data.id) {
+			const column = conflictColumns.find((name) => data[name] != null) ?? conflictColumns[0];
+			throw ValidationError.uniqueConstraint(column, data[column]);
+		}
+	}
+	/**
+	* Map a failed write to the typed error contract. `@happyvertical/sql` wraps
+	* every driver error as `DatabaseError('Failed to upsert record into
+	* table', { …, originalError })`, so the constraint wording never reaches
+	* `error.message`. Classify through the whole cause chain — driver codes
+	* first (SQLSTATE / SQLite result codes), dialect wording only as the
+	* DuckDB fallback — to restore the typed-error parity the docs promise
+	* (#1378, #2366).
+	*/
+	toTypedWriteError(error, operation) {
+		if (!(error instanceof Error)) return error;
+		const classification = classifyDatabaseError(error);
+		if (classification.kind === "unique_violation") {
+			const field = this.extractConstraintFieldFromChain(error, classification);
+			return ValidationError.uniqueConstraint(field, this.getFieldValue(field));
+		}
+		if (classification.kind === "not_null_violation") {
+			const field = this.extractConstraintFieldFromChain(error, classification);
+			return ValidationError.requiredField(field, this.getResolvedClassName());
+		}
+		return DatabaseError.queryFailed(operation, error);
+	}
+	/**
+	* Natural-key write for a NEW object (identity guard).
+	*
+	* A NEW object upserts on its natural key (`getConflictColumns()`), and the
+	* SDK's `ON CONFLICT (…) DO UPDATE SET` rewrites EVERY column of the matched
+	* row — including `id` and the tenant column. Two failure modes followed:
+	*
+	* - **Cross-tenant takeover.** When the conflict target omits the owner (an
+	*   explicit key without it, or a live table still carrying a global
+	*   `(slug, context)` unique), tenant B's save of a key tenant A already
+	*   owns matched A's row and rewrote its `id` and owner; with
+	*   `ON UPDATE CASCADE` A's children followed it into tenant B. The tenancy
+	*   interceptor cannot prevent this: it filters B's LOOKUP only.
+	* - **Primary-key churn.** A fresh instance saved over an existing same-owner
+	*   row replaced that row's primary key with the instance's new UUID.
+	*
+	* The row the conflict target matches is read directly, bypassing read
+	* interceptors (the collision is a storage fact whatever the caller may
+	* read). A different owner on any ownership column
+	* ({@link ObjectRegistry.getOwnershipColumns}: `tenant_id`, the declared
+	* tenant column, `@tenantId` fields and runtime tenancy registrations) is
+	* refused with {@link TenantIsolationError} (`TENANT_ISOLATION_VIOLATION`)
+	* — under `withSystemContext()` too, and an owner the save leaves unset
+	* counts as NULL: a tenant save never adopts a global row and a global save
+	* never adopts a tenant's row. A same-owner row is adopted: its id and
+	* creation time replace the instance's, so `DO UPDATE` keeps the primary
+	* key and `created_at`.
+	*
+	* A slug {@link getSlug} derived from `name`/`title`/`label` is a human
+	* value, not an identity: such an object never adopts a row (whoever owns
+	* it) and moves to the first free `<slug>-2` … `<slug>-9`, then
+	* `<slug>-<id>`, and INSERTs. `getOrUpsert()` opts back into adoption: its
+	* create path is keyed by the natural key it would have found.
+	*
+	* Concurrency. On PostgreSQL, when no conflict value is NULL, the write is
+	* `INSERT … ON CONFLICT (…) DO NOTHING RETURNING id` first: a new key costs
+	* one statement and no pre-read, and two concurrent first creates can never
+	* both take the upsert path — the loser sees the winner's row and adopts it
+	* (explicit key) or moves (derived slug), retrying a bounded number of
+	* times. Elsewhere (embedded engines, serialized by the in-process write
+	* queue, and NULL-bearing keys, which a standard unique index cannot
+	* arbitrate) the row is read first.
+	*
+	* @returns how the caller writes: `'done'` (already inserted), `'insert'`
+	*   (plain INSERT) or `'upsert'` (natural-key upsert, identity adopted).
+	*/
+	async writeNaturalKeyRow(data, conflictColumns, adopted) {
+		if (conflictColumns.length === 0 || !conflictColumns.every((column) => Object.hasOwn(data, column))) return "upsert";
+		const derived = !this._adoptNaturalKey && conflictColumns.includes("slug") && this._derivedSlug !== null && data.slug === this._derivedSlug;
+		const conflictFilterOf = () => {
+			const filter = {};
+			for (const column of conflictColumns) {
+				const value = data[column];
+				filter[column] = value === void 0 ? null : value;
+			}
+			return filter;
+		};
+		const atomic = isPostgresDatabase(this.db) && conflictColumns.every((column) => data[column] != null);
+		for (let attempt = 0; attempt < 5; attempt += 1) {
+			const conflictFilter = conflictFilterOf();
+			if (atomic) try {
+				if (await this.insertIfAbsent(data, conflictColumns)) return "done";
+			} catch (error) {
+				throw this.toTypedWriteError(error, `INSERT INTO ${this.tableName}`);
+			}
+			const existing = await this.readNaturalKeyRow(conflictFilter);
+			if (!existing) {
+				if (atomic) continue;
+				return derived ? "insert" : "upsert";
+			}
+			if (derived) {
+				await this.moveToFreeDerivedSlug(data, conflictFilter, attempt > 0);
+				if (atomic) continue;
+				return "insert";
+			}
+			this.assertSameNaturalKeyOwner(data, existing, conflictColumns, conflictFilter);
+			const existingId = existing.id;
+			if (typeof existingId === "string" && existingId !== "" && existingId !== data.id) {
+				data.id = existingId;
+				adopted.id = existingId;
+				if (existing.created_at != null && existing.created_at !== "") {
+					data.created_at = existing.created_at;
+					adopted.createdAt = existing.created_at;
+				}
+			}
+			return "upsert";
+		}
+		throw DatabaseError.queryFailed(`INSERT INTO ${this.tableName} (natural key)`, /* @__PURE__ */ new Error("The natural key kept colliding with concurrent writes; retry the save."));
+	}
+	/**
+	* Refuse a natural-key collision with a row owned by someone else. Every
+	* ownership column the stored row carries is compared; one the save leaves
+	* unset counts as NULL (a global save never adopts a tenant's row).
+	*/
+	assertSameNaturalKeyOwner(data, existing, conflictColumns, conflictFilter) {
+		const ownershipColumns = SmrtObject.ownershipColumnsFor(this.getResolvedQualifiedName());
+		const normalizeOwner = (value) => {
+			if (value === null || value === void 0 || value === "") return null;
+			return String(value).trim().toLowerCase();
+		};
+		const differing = [...ownershipColumns].filter((column) => Object.hasOwn(existing, column) && normalizeOwner(data[column]) !== normalizeOwner(existing[column]));
+		if (differing.length === 0) return;
+		const ownTenant = data[differing[0]];
+		throw TenantIsolationError.naturalKeyOwnedElsewhere({
+			className: this.getResolvedClassName(),
+			tableName: this.tableName,
+			conflictColumns,
+			conflictValues: conflictFilter,
+			ownershipColumns: differing,
+			tenantId: typeof ownTenant === "string" ? ownTenant : null
+		});
+	}
+	/**
+	* PostgreSQL: `INSERT … ON CONFLICT (conflict) DO NOTHING RETURNING id`.
+	* Values are serialized exactly as the SDK's insert does (undefined
+	* omitted, Date → ISO, objects → JSON, buffers as-is). A conflict on the
+	* natural key inserts nothing and returns `false`; any other constraint
+	* error propagates for the caller's typed classification.
+	*/
+	async insertIfAbsent(data, conflictColumns) {
+		const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
+		const columns = [];
+		const values = [];
+		for (const [column, value] of Object.entries(data)) {
+			if (value === void 0) continue;
+			columns.push(quote(column));
+			values.push(value === null ? null : value instanceof Date ? value.toISOString() : Buffer.isBuffer(value) || ArrayBuffer.isView(value) ? value : typeof value === "object" ? JSON.stringify(value) : value);
+		}
+		const placeholders = values.map((_, index) => `$${index + 1}`).join(", ");
+		return ((await this.db.query(`INSERT INTO ${quote(this.tableName)} (${columns.join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.map(quote).join(", ")}) DO NOTHING RETURNING ${quote("id")}`, ...values))?.rows?.length ?? 0) > 0;
+	}
+	/**
+	* Moves a NEW object's taken derived slug to the first free `<base>-2` …
+	* `<base>-9` under the same natural key (any owner's row counts as taken),
+	* found with ONE query, then to `<base>-<first 8 id characters>`, which only
+	* this object's id can claim (directly, with `idSuffixOnly`, after a
+	* numbered slug was lost to a concurrent create). `<base>` is the slug as first derived, so a
+	* retried save never compounds suffixes (`foo-2-2`). The caller INSERTs,
+	* so a concurrent claim of the same slug raises or retries instead of
+	* overwriting.
+	*/
+	async moveToFreeDerivedSlug(data, conflictFilter, idSuffixOnly = false) {
+		const base = this._derivedSlugBase ?? String(data.slug);
+		const idSlug = `${base}-${String(data.id).replace(/-/g, "").slice(0, 8)}`;
+		if (idSuffixOnly) {
+			data.slug = idSlug;
+			this.slug = idSlug;
+			this._derivedSlug = idSlug;
+			return;
+		}
+		const candidates = Array.from({ length: 8 }, (_, index) => `${base}-${index + 2}`);
+		const { slug: _slug, ...scope } = conflictFilter;
+		const takenRows = await ErrorUtils.withRetry(async () => {
+			try {
+				return await this.db.list(this.tableName, {
+					...scope,
+					"slug in": candidates
+				});
+			} catch (error) {
+				if (error instanceof SmrtError) throw error;
+				throw DatabaseError.queryFailed(`list(${this.tableName}, free derived slug)`, error instanceof Error ? error : new Error(String(error)));
+			}
+		}, 3, 500);
+		const taken = new Set(takenRows.map((row) => String(row.slug)));
+		const slug = candidates.find((candidate) => candidate !== data.slug && !taken.has(candidate)) ?? idSlug;
+		data.slug = slug;
+		this.slug = slug;
+		this._derivedSlug = slug;
+	}
+	/**
 	* Detects tenant-boundary errors that must propagate from `save()` unwrapped.
 	*
 	* Matches both core's {@link TenantIsolationError} and the duck-typed