@happyvertical/smrt-core 0.60.9 → 0.60.11

package/dist/object.js

@@ -1,11 +1,13 @@
 import { classifyDatabaseError, classifyDialectMessage } from "./db-errors.js";
 import { buildWhere } from "./host.js";
-import { isKnownNativeDuckDbHandle } from "./native-duckdb.js";
-import { isEmbeddedDatabase, isPostgresDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction } from "./embedded-write-queue.js";
+import { isJsonAdapterHandle, isKnownNativeDuckDbHandle } from "./native-duckdb.js";
+import { getDatabaseSyncDeviceId } from "./sync-device.js";
+import { isEmbeddedDatabase, isKnownDatabaseTransaction, isPostgresDatabase, usesEmbeddedRevisionFallback, usesPostgresDialect, withEmbeddedWriteQueue, withEmbeddedWriteTransaction } from "./embedded-write-queue.js";
 import { SmrtError } from "./smrt-error.js";
 import { DatabaseError, ErrorUtils, RuntimeError, TenantIsolationError, ValidationError } from "./errors.js";
+import { bindSyncRevision, compareSyncRevisions, deleteSyncRows, lockSyncRowIdentity, putSyncTombstone, syncRevisionConflict, validateSyncRevision } from "./sync-tombstones.js";
 import { toSnakeCase } from "./utils/naming.js";
-import { buildCascadePlan, cascadeReferencesTo, runCascadeDelete, runInOwningCascadeTransaction } from "./cascade.js";
+import { abortJoinedDuckDbTransaction, buildCascadePlan, cascadeReferencesTo, recordCascadeWrite, runCascadeDelete, runInOwningCascadeTransaction } from "./cascade.js";
 import { broadcastCacheInvalidation, hasCrossProcessCacheInterest, invalidateCollectionCache, resolveDbCacheKey } from "./collection-cache.js";
 import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
 import { detectEngine } from "./schema/ddl/index.js";
@@ -232,6 +234,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* (issue #1472).
 	*/
 	_persisted = false;
+	_explicitId = false;
 	/**
 	* When set (and the object is not yet persisted), `save()` performs a plain
 	* INSERT instead of an upsert, so ANY collision — primary key or natural
@@ -278,6 +281,43 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* Last update timestamp
 	*/
 	updated_at = null;
+	_syncMetadata = null;
+	/** Sync state read from or committed to the backing row. */
+	get syncMetadata() {
+		return this._syncMetadata;
+	}
+	/** @internal Read only from a physical row, never from model input or STI JSON. */
+	hydrateSyncMetadata(row) {
+		const origin = row._sync_origin_device_id;
+		const revision = Number(row._sync_revision);
+		this._syncMetadata = typeof origin === "string" && Number.isSafeInteger(revision) && revision > 0 ? Object.freeze({
+			originDeviceId: origin,
+			revision,
+			tombstone: false
+		}) : null;
+	}
+	normalizeSyncRowId(id) {
+		if (ObjectRegistry.getConfig(this.getResolvedQualifiedName()).idType === "text" || !usesPostgresDialect(this.db) && !this.isPositivelyNativeDuckDb()) return id;
+		const hex = id.replace(/[-{}]/g, "").toLowerCase();
+		return /^[0-9a-f]{32}$/.test(hex) ? [
+			hex.slice(0, 8),
+			hex.slice(8, 12),
+			hex.slice(12, 16),
+			hex.slice(16, 20),
+			hex.slice(20)
+		].join("-") : id;
+	}
+	nextSyncMetadata(write, trackSync = false) {
+		const previous = this._syncMetadata;
+		if (!write && !previous && !trackSync) return null;
+		if (write && trackSync) throw new ValidationError("Choose either local tracking or an incoming revision", "VALIDATION_SYNC_METADATA");
+		const revision = validateSyncRevision(write?.originDeviceId ?? getDatabaseSyncDeviceId(this.db), write ? write.revision : (previous?.revision ?? 0) + 1);
+		if (write && previous && compareSyncRevisions(revision, previous) <= 0) throw syncRevisionConflict(this.id);
+		return Object.freeze({
+			...revision,
+			tombstone: false
+		});
+	}
 	/**
 	* Creates a new SmrtObject instance
 	*
@@ -289,6 +329,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		this.options = options;
 		if (options === null) throw new Error("options cant be null");
 		this._id = options.id || null;
+		this._explicitId = Boolean(options.id);
 		this._slug = options.slug || null;
 		this._context = options.context || "";
 		if (this.constructor !== SmrtObject && !ObjectRegistry.getClassByConstructor(this.constructor) && !options?._skipRegistration) ObjectRegistry.register(this.constructor, {});
@@ -368,6 +409,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* @internal
 	*/
 	setId(id) {
+		if (id !== this._id) this._explicitId = true;
 		this._id = id;
 	}
 	/**
@@ -436,7 +478,8 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			context: this._context,
 			createdAt: this.created_at instanceof Date ? new Date(this.created_at) : this.created_at,
 			updatedAt: this.updated_at instanceof Date ? new Date(this.updated_at) : this.updated_at,
-			persisted: this._persisted
+			persisted: this._persisted,
+			syncMetadata: this._syncMetadata
 		};
 		try {
 			return await withEmbeddedWriteTransaction(database, isEmbeddedDatabase(database), (transaction) => this.withDatabase(transaction, operation));
@@ -447,6 +490,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			this.created_at = persistence.createdAt;
 			this.updated_at = persistence.updatedAt;
 			this._persisted = persistence.persisted;
+			this._syncMetadata = persistence.syncMetadata;
 			throw error;
 		}
 	}
@@ -521,6 +565,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*/
 	set id(value) {
 		if (!value || value === "undefined" || value === "null") throw new Error(`id is required, ${value} given`);
+		if (value !== this._id) this._explicitId = true;
 		this._id = value;
 	}
 	/**
@@ -678,6 +723,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			skippedCount,
 			totalFields: Object.keys(fields).length
 		});
+		this.hydrateSyncMetadata(data);
 		this._persisted = true;
 	}
 	/** Fail closed if a caller tries to hydrate a lossy DuckDB UUID wrapper. */
@@ -1268,11 +1314,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		const all = [...removed, ...added];
 		const first = all[0];
 		if (!first) return true;
-		if (all.length > 100 || all.some((item) => item.db !== first.db || item.tableName !== first.tableName || item.constructor !== first.constructor || !SmrtObject.prototype.supportsJunctionBatch.call(item)) || added.some((item) => item.isPersisted) || removed.some((item) => !item.id)) return false;
+		if (all.length > 100 || all.some((item) => item.db !== first.db || item.tableName !== first.tableName || item.constructor !== first.constructor || !SmrtObject.prototype.supportsJunctionBatch.call(item)) || added.some((item) => item.isPersisted || item._explicitId) || removed.some((item) => !item.id)) return false;
 		if (first.getDatabaseEngineHint() === "json") return false;
 		const duck = first.isNativeDuckDb();
 		if (duck && !first.isPositivelyNativeDuckDb()) return false;
-		const engine = isPostgresDatabase(first.db) ? "postgres" : duck ? "duckdb" : detectEngine(first.db.url ?? "", first.getDatabaseEngineHint());
+		const engine = usesPostgresDialect(first.db) ? "postgres" : duck ? "duckdb" : detectEngine(first.db.url ?? "", first.getDatabaseEngineHint());
 		if (![
 			"sqlite",
 			"duckdb",
@@ -1334,11 +1380,17 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 					tableName: first.tableName,
 					ids
 				});
-				await db.delete(first.tableName, { "id in": ids });
+				const model = first.getResolvedQualifiedName();
+				await deleteSyncRows(db, {
+					tableName: first.tableName,
+					model,
+					tenantColumn: ObjectRegistry.getOwnershipTenantColumn(model)
+				}, { "id in": ids }, (affected) => recordCascadeWrite(db, { affected }));
 				return result;
 			}, true);
 			for (const instance of removed) {
 				instance._persisted = false;
+				instance._explicitId = true;
 				instance.invalidateCollectionReadCache();
 				await instance.runHook("afterDelete");
 			}
@@ -1352,19 +1404,20 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 				return engine === "postgres" ? `$${values.length}` : "?";
 			}).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 () => {
+			const sql = `INSERT INTO ${quote(first.tableName)} (${columns.map(quote).join(", ")}) VALUES ${tuples.join(", ")} ON CONFLICT (${conflict.map(quote).join(", ")}) DO UPDATE SET ${updates} RETURNING *`;
+			await ErrorUtils.withRetry(async () => {
 				try {
-					await first.db.query(sql, ...values);
+					await withEmbeddedWriteTransaction(first.db, isEmbeddedDatabase(first.db), async (db) => {
+						const { rows } = await db.query(sql, ...values);
+						const tracked = rows.find((row) => row._sync_origin_device_id != null);
+						if (!tracked) return;
+						if (duck && db === first.db) await abortJoinedDuckDbTransaction(db, "smrt: tracked junction conflict aborted the caller transaction");
+						throw first.trackedIdentityWriteError(typeof tracked.id === "string" ? tracked.id : void 0);
+					}, duck);
 				} catch (error) {
-					if (!(error instanceof Error)) throw error;
-					const classification = classifyDatabaseError(error);
-					const field = first.extractConstraintFieldFromChain(error, classification);
-					if (classification.kind === "unique_violation") throw ValidationError.uniqueConstraint(field, first.getFieldValue(field));
-					if (classification.kind === "not_null_violation") throw ValidationError.requiredField(field, first.getResolvedClassName());
-					throw DatabaseError.queryFailed(`UPSERT INTO ${first.tableName}`, error);
+					throw first.toTypedWriteError(error, `UPSERT INTO ${first.tableName}`);
 				}
-			}, 3, 500));
+			}, 3, 500);
 			const completions = [];
 			for (let i = 0; i < added.length; i++) {
 				await added[i].completeSave(prepared[i].interceptorContext, false);
@@ -1386,7 +1439,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		return ObjectRegistry.getOwnershipColumns(qualifiedName);
 	}
 	/** Shared preparation for ordinary saves and compatible bulk creates. */
-	async prepareSave(revisionGuard) {
+	async prepareSave(revisionGuard, syncMetadata = null) {
 		const className = this.getResolvedClassName();
 		if (ObjectRegistry.getConfig(this.getResolvedQualifiedName()).abstract) throw new ValidationError(`Cannot save abstract model ${className}`, "VALIDATION_ABSTRACT_MODEL", { className });
 		await this.validateBeforeSave();
@@ -1422,6 +1475,12 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			data._meta_data = sanitizeMetaData(data._meta_data, reservedFields);
 		}
 		data.updated_at = this.updated_at;
+		delete data._sync_origin_device_id;
+		delete data._sync_revision;
+		if (syncMetadata) {
+			data._sync_origin_device_id = syncMetadata.originDeviceId;
+			data._sync_revision = bindSyncRevision(syncMetadata.revision, this.isPositivelyNativeDuckDb());
+		}
 		await this.coerceEmptyUuidValuesToNull(data);
 		const conflictColumns = ObjectRegistry.getConflictColumns(this.getResolvedQualifiedName());
 		const ownershipColumn = ObjectRegistry.getOwnershipTenantColumn(this.getResolvedQualifiedName());
@@ -1437,6 +1496,8 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			"updated_at",
 			"_meta_type",
 			"_meta_data",
+			"_sync_origin_device_id",
+			"_sync_revision",
 			...conflictColumns.map(toSnakeCase)
 		]);
 		for (const [name, field] of registeredFields) if (field.__tenancy?.isTenantIdField || field._meta?.__tenancy?.isTenantIdField) protectedColumns.add(toSnakeCase(name));
@@ -1529,13 +1590,20 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	async save(options = {}) {
 		const className = this.getResolvedClassName();
 		const expectedUpdatedAt = options.expectedUpdatedAt;
+		const explicitNewId = !this._persisted && (this._explicitId || options.sync || options.trackSync) && this.id;
 		const previousUpdatedAt = this.updated_at;
 		let revisionPersisted = false;
 		const loadedRevision = expectedUpdatedAt ?? (this._persisted ? this.updated_at ?? void 0 : void 0);
 		const revisionGuard = loadedRevision instanceof Date ? loadedRevision.toISOString() : loadedRevision;
 		try {
 			if (expectedUpdatedAt !== void 0 && (!this._persisted || !this.id)) throw RuntimeError.invalidState("A revision-guarded save requires a persisted object", { className });
-			const { interceptorContext, data, writePlan, conflictColumns } = await this.prepareSave(revisionGuard);
+			const syncMetadata = this.nextSyncMetadata(options.sync, options.trackSync);
+			if (syncMetadata && (this.getDatabaseEngineHint() === "json" || isJsonAdapterHandle(this.db))) throw RuntimeError.invalidState("Sync revisions require a SQL database", { className });
+			if (syncMetadata && !this._persisted) {
+				if (!this.id) throw RuntimeError.invalidState("A tracked create requires an explicit id", { className });
+				this.requireInsertOnSave();
+			}
+			const { interceptorContext, data, writePlan, conflictColumns } = await this.prepareSave(revisionGuard, syncMetadata);
 			const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
 			const useEmbeddedRevisionFallback = revisionGuard !== void 0 && usesEmbeddedRevisionFallback(this.db);
 			const serializeEmbeddedWrite = isEmbeddedDatabase(this.db);
@@ -1543,7 +1611,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			let revisionMatched = true;
 			let naturalKeyWrite = "upsert";
 			const adopted = {};
-			await withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, async () => {
+			const write = () => withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, async () => {
 				const writeGuard = GlobalInterceptors.executeWriteGuard(this, interceptorContext);
 				if (naturalKeyUpsert) {
 					naturalKeyWrite = await this.writeNaturalKeyRow(data, upsertConflictColumns, adopted);
@@ -1574,18 +1642,35 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 						} else if (this._insertOnly && !this._persisted || insertUnderFreshSlug) await this.db.insert(this.tableName, data);
 						else {
 							const naturalKeyConflictColumns = ObjectRegistry.getConflictPredicate(this.getResolvedQualifiedName()) ? ["id"] : upsertConflictColumns;
-							await this.writeNaturalKeyUpsert(data, naturalKeyConflictColumns, adopted.existing ?? null, writeGuard);
+							await this.writeNaturalKeyUpsert(data, naturalKeyConflictColumns, adopted, writeGuard);
 						}
 					} 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}`);
 					}
 				}, 3, 500);
 			});
+			if (explicitNewId && this.getDatabaseEngineHint() !== "json" && !isJsonAdapterHandle(this.db)) {
+				const guardedWrite = async (tx) => {
+					const rowId = this.normalizeSyncRowId(explicitNewId);
+					const filter = {
+						table_name: this.tableName,
+						row_id: rowId
+					};
+					await lockSyncRowIdentity(tx, this.tableName, rowId);
+					if (await tx.get("_smrt_sync_tombstones", filter)) throw syncRevisionConflict(rowId);
+					await this.withDatabase(tx, write);
+					if (isPostgresDatabase(tx) && await tx.get("_smrt_sync_tombstones", filter)) throw syncRevisionConflict(rowId);
+				};
+				const embedded = usesEmbeddedRevisionFallback(this.db);
+				if (embedded && isKnownDatabaseTransaction(this.db)) await withEmbeddedWriteQueue(this.db, true, () => guardedWrite(this.db));
+				else await withEmbeddedWriteTransaction(this.db, serializeEmbeddedWrite, guardedWrite, embedded);
+			} else await write();
 			if (!revisionMatched) throw new RuntimeError(`Revision conflict while saving ${className}`, "RUNTIME_REVISION_CONFLICT", {
 				className,
 				id: this.id
 			});
 			revisionPersisted = true;
+			this._syncMetadata = syncMetadata;
 			if (adopted.id) {
 				this.id = adopted.id;
 				if (adopted.createdAt != null) {
@@ -1616,6 +1701,14 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		const interceptorContext = createInterceptorContext(className, "save", void 0, void 0, this.getResolvedQualifiedName());
 		await GlobalInterceptors.executeBeforeSave(this, interceptorContext);
 		const updatedAt = this.nextRevisionTimestamp(expectedUpdatedAt);
+		const syncMetadata = this.nextSyncMetadata();
+		const updates = {
+			updated_at: updatedAt.toISOString(),
+			...syncMetadata && {
+				_sync_origin_device_id: syncMetadata.originDeviceId,
+				_sync_revision: bindSyncRevision(syncMetadata.revision, this.isPositivelyNativeDuckDb())
+			}
+		};
 		let result;
 		let revisionMatched = true;
 		const useEmbeddedRevisionFallback = usesEmbeddedRevisionFallback(this.db);
@@ -1632,11 +1725,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			if (!useEmbeddedRevisionFallback) result = await this.db.update(this.tableName, this.guardedWriteFilter({
 				id: this.id,
 				...this.revisionPredicate(expectedUpdatedAt)
-			}, writeGuard), { updated_at: updatedAt.toISOString() });
-			else if (this.isPositivelyNativeDuckDb()) result = await this.updateDuckDbRowById(this.id, { updated_at: updatedAt.toISOString() });
+			}, writeGuard), updates);
+			else if (this.isPositivelyNativeDuckDb()) result = await this.updateDuckDbRowById(this.id, updates);
 			else result = await this.db.upsert(this.tableName, ["id"], {
 				...current,
-				updated_at: updatedAt.toISOString()
+				...updates
 			});
 		});
 		if (!revisionMatched || result?.affected !== 1) throw new RuntimeError(`Revision conflict while claiming ${className}`, "RUNTIME_REVISION_CONFLICT", {
@@ -1644,6 +1737,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			id: this.id
 		});
 		this.updated_at = updatedAt;
+		this._syncMetadata = syncMetadata;
 		this.invalidateCollectionReadCache();
 		await recordInstanceChange(this, "update");
 		return this;
@@ -1742,21 +1836,56 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			...guard
 		};
 	}
-	async writeNaturalKeyUpsert(data, conflictColumns, existing, writeGuard) {
-		if (writeGuard) {
+	async writeNaturalKeyUpsert(data, conflictColumns, adopted, writeGuard) {
+		const existing = adopted.existing ?? null;
+		const postgres = isPostgresDatabase(this.db);
+		const crossProcess = !usesEmbeddedRevisionFallback(this.db);
+		const guardAdoptedSync = crossProcess && existing !== null;
+		if (writeGuard || guardAdoptedSync) {
 			const stored = existing;
 			if (!stored) return this.db.insert(this.tableName, data);
 			const unchanged = await this.unchangedIndexedColumnsOf(data, stored);
-			const assignments = Object.fromEntries(Object.entries(data).filter(([column]) => column !== "id" && !unchanged.has(column) && !conflictColumns.includes(column)));
-			const filter = this.guardedWriteFilter({ id: stored.id }, writeGuard);
+			const assignments = Object.fromEntries(Object.entries(data).filter(([column]) => column !== "id" && (!guardAdoptedSync || column !== "created_at") && !unchanged.has(column) && !conflictColumns.includes(column)));
+			const filter = this.guardedWriteFilter({
+				id: stored.id,
+				...guardAdoptedSync ? { _sync_origin_device_id: null } : {}
+			}, writeGuard);
 			let result;
 			if (this.isPositivelyNativeDuckDb()) {
 				if (!await this.db.get(this.tableName, filter)) throw new Error("Mandatory write predicate denied mutation");
 				result = await this.updateDuckDbRowById(stored.id, assignments);
 			} else result = await this.db.update(this.tableName, filter, assignments);
-			if (result.affected !== 1) throw new Error("Mandatory write predicate denied mutation");
+			if (result.affected !== 1) {
+				if (guardAdoptedSync && !writeGuard) throw this.trackedIdentityWriteError(stored.id);
+				throw new Error("Mandatory write predicate denied mutation");
+			}
 			return result;
 		}
+		const idConflict = conflictColumns.length === 1 && conflictColumns[0] === "id";
+		if (!this._persisted && idConflict && postgres) {
+			if (!await this.insertIfAbsent(data, conflictColumns, true)) throw this.trackedIdentityWriteError(data.id);
+			return;
+		}
+		if (!this._persisted && (!crossProcess && idConflict || !conflictColumns.every((column) => data[column] !== void 0))) {
+			if ((await this.readNaturalKeyRow({ id: data.id }))?._sync_origin_device_id != null) throw this.trackedIdentityWriteError(data.id);
+		}
+		if (!this._persisted && crossProcess && conflictColumns.every((column) => data[column] !== void 0) && (!postgres || !existing && conflictColumns.some((column) => data[column] === null))) {
+			const filter = Object.fromEntries(conflictColumns.map((column) => [column, data[column]]));
+			return withEmbeddedWriteTransaction(this.db, false, async (tx) => {
+				if (postgres) await tx.query("SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))", `smrt.nullable-natural-key:${this.tableName}`, JSON.stringify(Object.keys(filter).sort().map((column) => [column, filter[column]]), (_, value) => typeof value === "bigint" || typeof value === "number" ? String(value) : value));
+				return this.withDatabase(tx, async () => {
+					const current = await this.readNaturalKeyRow(filter);
+					if (!current) {
+						if (!postgres) return tx.insert(this.tableName, data);
+						if (await this.insertIfAbsent(data, conflictColumns)) return;
+					}
+					const winner = current ?? await this.readNaturalKeyRow(filter);
+					if (!winner) throw RuntimeError.invalidState("Natural-key winner disappeared before it could be adopted", { className: this.getResolvedClassName() });
+					this.adoptNaturalKeyRow(data, winner, conflictColumns, filter, adopted);
+					return this.writeNaturalKeyUpsert(data, conflictColumns, adopted);
+				});
+			});
+		}
 		const unchanged = await this.unchangedIndexedColumnsOf(data, existing);
 		if (!existing || unchanged.size === 0 || existing.id == null) return this.db.upsert(this.tableName, conflictColumns, data);
 		const assignments = {};
@@ -1764,10 +1893,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			if (column === "id" || unchanged.has(column) || conflictColumns.includes(column)) continue;
 			assignments[column] = value;
 		}
-		return Object.keys(assignments).length === 0 ? {
-			operation: "upsert",
-			affected: 1
-		} : this.updateDuckDbRowById(existing.id, assignments);
+		return Object.keys(assignments).length === 0 ? { affected: 1 } : this.updateDuckDbRowById(existing.id, assignments);
 	}
 	/**
 	* One id-targeted `UPDATE` on native DuckDB (see {@link buildDuckDbIdUpdate}
@@ -1809,7 +1935,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* compare/upsert fallback in {@link usesEmbeddedRevisionFallback}.
 	*/
 	revisionPredicate(revision) {
-		if (isPostgresDatabase(this.db)) return postgresRevisionCondition(revision);
+		if (usesPostgresDialect(this.db)) return postgresRevisionCondition(revision);
 		return { updated_at: this.revisionPredicateValue(revision) };
 	}
 	revisionPredicateValue(revision) {
@@ -1959,21 +2085,25 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 				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;
-				}
-			}
-			adopted.existing = existing;
+			this.adoptNaturalKeyRow(data, existing, conflictColumns, conflictFilter, adopted);
 			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."));
 	}
+	adoptNaturalKeyRow(data, existing, conflictColumns, conflictFilter, adopted) {
+		this.assertSameNaturalKeyOwner(data, existing, conflictColumns, conflictFilter);
+		if (existing._sync_origin_device_id != null) throw this.trackedIdentityWriteError(existing.id);
+		const existingId = existing.id;
+		if (typeof existingId === "string" && existingId !== "") {
+			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;
+			}
+		}
+		adopted.existing = existing;
+	}
 	scopePartialConflictFilter(filter, data) {
 		const className = this.getResolvedQualifiedName();
 		const overrides = ObjectRegistry.getSTIConflictOverrides(className);
@@ -2004,6 +2134,12 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			tenantId: typeof ownTenant === "string" ? ownTenant : null
 		});
 	}
+	trackedIdentityWriteError(id) {
+		return RuntimeError.invalidState("A tracked row must be loaded by identity before saving", {
+			className: this.getResolvedClassName(),
+			id
+		});
+	}
 	/**
 	* PostgreSQL: `INSERT … ON CONFLICT (conflict) DO NOTHING RETURNING id`.
 	* Values are serialized exactly as the SDK's insert does (undefined
@@ -2011,7 +2147,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* natural key inserts nothing and returns `false`; any other constraint
 	* error propagates for the caller's typed classification.
 	*/
-	async insertIfAbsent(data, conflictColumns) {
+	async insertIfAbsent(data, conflictColumns, updateUntrackedId = false) {
 		const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
 		const columns = [];
 		const values = [];
@@ -2021,9 +2157,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			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(", ");
-		const predicate = ObjectRegistry.getConflictPredicate(this.getResolvedQualifiedName());
+		const table = quote(this.tableName);
+		const predicate = updateUntrackedId ? void 0 : ObjectRegistry.getConflictPredicate(this.getResolvedQualifiedName());
 		const conflictWhere = predicate ? ` WHERE ${predicate}` : "";
-		return ((await this.db.query(`INSERT INTO ${quote(this.tableName)} (${columns.join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.map(quote).join(", ")})${conflictWhere} DO NOTHING RETURNING ${quote("id")}`, ...values))?.rows?.length ?? 0) > 0;
+		const action = updateUntrackedId ? `DO UPDATE SET ${columns.filter((column) => column !== quote("id") && column !== quote("created_at")).map((column) => `${column} = excluded.${column}`).join(", ")} WHERE ${table}."_sync_origin_device_id" IS NULL` : "DO NOTHING";
+		return ((await this.db.query(`INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.map(quote).join(", ")})${conflictWhere} ${action} RETURNING ${quote("id")}`, ...values))?.rows?.length ?? 0) > 0;
 	}
 	/**
 	* Moves a NEW object's taken derived slug to the first free `<base>-2` …
@@ -2723,11 +2861,30 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	async delete(options = {}) {
 		const className = this.getResolvedClassName();
 		const expectedUpdatedAt = options.expectedUpdatedAt;
+		const incoming = options.sync && validateSyncRevision(options.sync.originDeviceId, options.sync.revision);
+		const model = this.getResolvedQualifiedName();
+		const identity = {
+			tableName: this.tableName,
+			model,
+			sti: ObjectRegistry.getTableStrategy(model) === "sti",
+			tenantColumn: ObjectRegistry.getOwnershipTenantColumn(model)
+		};
+		if (incoming && !this.id) throw RuntimeError.invalidState("An incoming deletion requires an explicit id", { className });
 		if (expectedUpdatedAt !== void 0 && (!this._persisted || !this.id)) throw RuntimeError.invalidState("A revision-guarded delete requires a persisted object", { className });
 		const interceptorContext = createInterceptorContext(this.constructor.name, "delete", void 0, void 0, this.getResolvedQualifiedName());
 		await GlobalInterceptors.executeBeforeDelete(this, interceptorContext);
 		await this.runHook("beforeDelete");
 		await this.verifyStorageReady();
+		const incomingDeletion = (() => {
+			if (!incoming || !this.id) return void 0;
+			const tenantId = identity.tenantColumn ? Object.entries(this.toJSON()).find(([key]) => toSnakeCase(key) === identity.tenantColumn)?.[1] ?? null : null;
+			if (tenantId !== null && typeof tenantId !== "string") throw syncRevisionConflict(this.id);
+			return {
+				rowId: this.normalizeSyncRowId(this.id),
+				tenantId,
+				revision: incoming
+			};
+		})();
 		const embeddedRevisionGuard = expectedUpdatedAt !== void 0 && usesEmbeddedRevisionFallback(this.db);
 		const { affectedTables, affectedTableClasses } = await withEmbeddedWriteQueue(this.db, isEmbeddedDatabase(this.db), async () => {
 			const writeGuard = GlobalInterceptors.executeWriteGuard(this, interceptorContext);
@@ -2747,19 +2904,22 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 					id: this.id,
 					...expectedUpdatedAt !== void 0 && !embeddedRevisionGuard ? this.revisionPredicate(expectedUpdatedAt) : {}
 				}, writeGuard);
-				let affected;
-				if (writeGuard) {
-					const { sql, values } = buildWhere(filter, 1, isPostgresDatabase(this.db) ? "postgres" : this.isNativeDuckDb() ? "duckdb" : "sqlite");
-					const table = `"${this.tableName.replaceAll("\"", "\"\"")}"`;
-					affected = (await db.query(`DELETE FROM ${table} ${sql} RETURNING id`, ...values)).rows.length;
-				} else affected = (await db.delete(this.tableName, filter)).affected;
+				const { affected } = await deleteSyncRows(db, identity, filter, (count) => recordCascadeWrite(db, { affected: count }), incomingDeletion);
 				if ((expectedUpdatedAt !== void 0 || writeGuard !== void 0) && affected !== 1) throw new RuntimeError(`Revision conflict while deleting ${className}`, "RUNTIME_REVISION_CONFLICT", {
 					className,
 					id: this.id
 				});
-			});
+				if (incomingDeletion && affected === 0) {
+					if (await db.get(this.tableName, { id: this.id })) throw syncRevisionConflict(this.id);
+					await putSyncTombstone(db, identity, incomingDeletion.rowId, identity.model, incomingDeletion.tenantId, incomingDeletion.revision);
+				}
+			}, incomingDeletion ? async (db) => {
+				await lockSyncRowIdentity(db, this.tableName, incomingDeletion.rowId);
+				return Boolean(await db.get(this.tableName, this.guardedWriteFilter({ id: this.id }, writeGuard)));
+			} : void 0);
 		});
 		this._persisted = false;
+		this._explicitId = true;
 		this.invalidateCollectionReadCache();
 		for (const table of affectedTables) this.invalidateCollectionReadCache(table, affectedTableClasses.get(table));
 		await this.runHook("afterDelete");