@happyvertical/smrt-core 0.43.9 → 0.44.0

package/dist/object.js

@@ -3,8 +3,10 @@ import { DatabaseError, ErrorUtils, RuntimeError, SmrtError, TenantIsolationErro
 import { toSnakeCase } from "./utils/naming.js";
 import { runCascadeDelete } from "./cascade.js";
 import { broadcastCacheInvalidation, hasCrossProcessCacheInterest, invalidateCollectionCache, resolveDbCacheKey } from "./collection-cache.js";
-import { isEmbeddedDatabase, withEmbeddedWriteQueue } from "./embedded-write-queue.js";
+import { isEmbeddedDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction } from "./embedded-write-queue.js";
 import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
+import { detectEngine } from "./schema/ddl/index.js";
+import { CHANGE_FEED_WAS_PERSISTED_KEY, recordInstanceChange } from "./change-feed.js";
 import { SmrtClass } from "./class.js";
 import { EmbeddingProvider } from "./embeddings/provider.js";
 import { EmbeddingStorage } from "./embeddings/storage.js";
@@ -14,8 +16,12 @@ import { executeToolCall } from "./tools/tool-executor.js";
 import { fieldsFromClass, keysToSnakeCase, tableNameFromClass } from "./utils.js";
 import { ObjectRegistry } from "./registry.js";
 import { createLogger } from "@happyvertical/logger";
+import { buildWhere } from "@happyvertical/sql";
 //#region src/object.ts
 var logger = createLogger({ level: process.env.DEBUG_STI ? "debug" : "info" });
+function isDuckDbHugeInt(value) {
+	return Boolean(value && typeof value === "object" && "hugeint" in value && (typeof value.hugeint === "number" || typeof value.hugeint === "bigint"));
+}
 /**
 * Default maximum number of characters of serialized object data injected into
 * the AI prompts built by `is()`, `do()`, and `describe()`.
@@ -294,6 +300,38 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		await verifyPersistenceTable(this.db, this.tableName, this.constructor.name);
 	}
 	/**
+	* Run work for this object in a root database transaction.
+	*
+	* Database rollback cannot undo JavaScript mutations made by save(). This
+	* helper therefore restores persistence identity and revision metadata when
+	* the transaction rejects, allowing the same instance to be corrected and
+	* retried without a false revision conflict. Domain-field mutations remain
+	* caller-owned so the caller can inspect or amend them before retrying.
+	*/
+	async withTransaction(operation) {
+		const database = this.db;
+		if (!database.transaction) throw new Error("Object transaction requires transaction support");
+		const persistence = {
+			id: this._id,
+			slug: this._slug,
+			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
+		};
+		try {
+			return await withEmbeddedWriteTransaction(database, isEmbeddedDatabase(database), (transaction) => this.withDatabase(transaction, operation));
+		} catch (error) {
+			this._id = persistence.id;
+			this._slug = persistence.slug;
+			this._context = persistence.context;
+			this.created_at = persistence.createdAt;
+			this.updated_at = persistence.updatedAt;
+			this._persisted = persistence.persisted;
+			throw error;
+		}
+	}
+	/**
 	* Protected setter for STI discriminator to maintain type safety
 	* Used internally for Single Table Inheritance support
 	* @internal
@@ -458,6 +496,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* @throws Error if STI validation fails
 	*/
 	async loadDataFromDb(data) {
+		data = await this.canonicalizePersistedUuidRow(data);
 		const className = this.getResolvedClassName();
 		if (process.env.DEBUG_STI) logger.debug("[loadDataFromDb] Loading", {
 			class: className,
@@ -512,6 +551,8 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 				if (process.env.DEBUG_STI) logger.debug(`[loadDataFromDb] Skipping readonly field '${field}'`);
 			}
 		}
+		if (Object.hasOwn(data, "created_at")) this.created_at = formattedData.created_at ?? formattedData.createdAt;
+		if (Object.hasOwn(data, "updated_at")) this.updated_at = formattedData.updated_at ?? formattedData.updatedAt;
 		if (process.env.DEBUG_STI) logger.debug("[loadDataFromDb] Hydration complete", {
 			class: className,
 			hydratedCount,
@@ -520,6 +561,45 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		});
 		this._persisted = true;
 	}
+	/** Fail closed if a caller tries to hydrate a lossy DuckDB UUID wrapper. */
+	async canonicalizePersistedUuidRow(row) {
+		const schema = ObjectRegistry.getSchema(this.getResolvedQualifiedName()) ?? ObjectRegistry.getSchema(this.getResolvedClassName());
+		const registeredFields = ObjectRegistry.getFields(this.getResolvedQualifiedName()).size > 0 ? ObjectRegistry.getFields(this.getResolvedQualifiedName()) : ObjectRegistry.getFields(this.getResolvedClassName());
+		const instanceColumns = /* @__PURE__ */ new Set(["id", ...Array.from(registeredFields.keys(), (fieldName) => toSnakeCase(fieldName))]);
+		const uuidColumns = Object.entries(schema?.columns ?? {}).filter(([columnName, column]) => instanceColumns.has(columnName) && String(column.type).toUpperCase() === "UUID").map(([columnName]) => columnName);
+		if (uuidColumns.length === 0 || !uuidColumns.some((columnName) => isDuckDbHugeInt(row[columnName]))) return row;
+		throw RuntimeError.invalidState("Native DuckDB UUID row was not canonicalized before hydration", { className: this.getResolvedClassName() });
+	}
+	/** Fetch one exact row while casting native DuckDB UUIDs in that same read. */
+	async getCanonicalPersistedRow(filter) {
+		if (!this.isNativeDuckDb()) return await this.db.get(this.tableName, filter);
+		const schema = ObjectRegistry.getSchema(this.getResolvedQualifiedName()) ?? ObjectRegistry.getSchema(this.getResolvedClassName());
+		const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
+		if (Object.keys(filter).length === 0) return null;
+		for (const fieldName of Object.keys(filter)) {
+			const [, rawColumnName] = fieldName.match(/^(.*?)(?:\s+(?:not in|in|like|>=|<=|!=|>|<|=))?$/i) ?? [];
+			const columnName = toSnakeCase(rawColumnName ?? fieldName);
+			if (!schema?.columns[columnName]) throw RuntimeError.invalidState("Invalid persisted-row filter column", {
+				className: this.getResolvedClassName(),
+				fieldName
+			});
+		}
+		const { sql: whereSql, values } = buildWhere(filter, 1, "duckdb");
+		const readSql = `SELECT * FROM ${quote(this.tableName)} ${whereSql} LIMIT 1`;
+		const uuidColumns = (await this.db.query(`DESCRIBE ${readSql}`, ...values)).rows.filter((column) => String(column.column_type).toUpperCase() === "UUID").map((column) => String(column.column_name));
+		const alias = quote("__smrt_uuid_row");
+		const sql = uuidColumns.length === 0 ? readSql : `SELECT ${alias}.* REPLACE (${uuidColumns.map((columnName) => {
+			const quoted = quote(columnName);
+			return `CAST(${alias}.${quoted} AS VARCHAR) AS ${quoted}`;
+		}).join(", ")}) FROM (${readSql}) AS ${alias}`;
+		const { rows } = await this.db.query(sql, ...values);
+		return rows[0] ?? null;
+	}
+	isNativeDuckDb() {
+		const db = this.db;
+		const isDuckDbConnection = (db.client?.constructor?.name?.toLowerCase() ?? "").includes("duckdb") || typeof db.exportTable === "function" && db.client !== void 0 && "connection" in db.client;
+		return detectEngine(db.url || db.config?.url || "", this.getDatabaseEngineHint() || db.type || db.config?.type || (isDuckDbConnection ? "duckdb" : void 0)) === "duckdb";
+	}
 	/**
 	* Gets the database table name for this object
 	*/
@@ -814,11 +894,16 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	async getId() {
 		if (this.slug) {
 			await this.verifyStorageReady();
-			const saved = await this.db.get(this.tableName, await this.interceptGetFilter({
+			const filter = await this.interceptGetFilter({
 				slug: this.slug,
 				context: this.context
-			}));
-			if (saved) this.id = saved.id;
+			});
+			const saved = await this.getCanonicalPersistedRow(filter);
+			if (saved) {
+				const persistedId = saved.id;
+				if (typeof persistedId !== "string") throw RuntimeError.invalidState("Persisted object id is not a string", { className: this.getResolvedClassName() });
+				this.id = persistedId;
+			}
 		}
 		if (!this.id) this.id = crypto.randomUUID();
 		return this.id;
@@ -868,11 +953,13 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		if (!this.id && !this.slug) return null;
 		await this.verifyStorageReady();
 		if (this.id) {
-			const byId = await this.db.get(this.tableName, await this.interceptGetFilter({ id: this.id }));
+			const filter = await this.interceptGetFilter({ id: this.id });
+			const byId = await this.getCanonicalPersistedRow(filter);
 			if (byId) return byId.id;
 		}
 		if (this.slug) {
-			const bySlug = await this.db.get(this.tableName, await this.interceptGetFilter({ slug: this.slug }));
+			const filter = await this.interceptGetFilter({ slug: this.slug });
+			const bySlug = await this.getCanonicalPersistedRow(filter);
 			if (bySlug) return bySlug.id;
 		}
 		return null;
@@ -1033,16 +1120,22 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* await product.save();
 	* ```
 	*/
-	async save() {
+	async save(options = {}) {
 		const className = this.getResolvedClassName();
+		const expectedUpdatedAt = options.expectedUpdatedAt;
+		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 });
 			await this.validateBeforeSave();
 			await this.validateCrossPackageRefs();
 			const interceptorContext = createInterceptorContext(className, "save");
 			await GlobalInterceptors.executeBeforeSave(this, interceptorContext);
 			if (!this.id) this.id = crypto.randomUUID();
 			if (!this.slug) this.slug = await this.getSlug();
-			this.updated_at = /* @__PURE__ */ new Date();
+			this.updated_at = this.nextRevisionTimestamp(revisionGuard);
 			if (!this.created_at) this.created_at = /* @__PURE__ */ new Date();
 			await this.verifyStorageReady();
 			const tableStrategy = ObjectRegistry.getTableStrategy(this.getResolvedQualifiedName());
@@ -1063,17 +1156,34 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			const data = {};
 			for (const [key, value] of Object.entries(jsonData)) if (key.startsWith("_")) data[key] = value;
 			else data[toSnakeCase(key)] = value;
+			data.updated_at = this.updated_at;
 			await this.coerceEmptyUuidValuesToNull(className, data);
 			const conflictColumns = ObjectRegistry.getConflictColumns(className);
 			const writePlan = await this.planPersistenceWrite(className, tableStrategy, data, conflictColumns);
 			const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
-			const serializeEmbeddedWrite = writePlan.type !== "updateById" && !(this._insertOnly && !this._persisted) && isEmbeddedDatabase(this.db) && upsertConflictColumns.some((column) => data[column] == null);
+			const useEmbeddedRevisionFallback = revisionGuard !== void 0 && usesEmbeddedRevisionFallback(this.db);
+			const serializeEmbeddedWrite = isEmbeddedDatabase(this.db);
+			let revisionMatched = true;
 			await withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, () => ErrorUtils.withRetry(async () => {
 				try {
-					if (writePlan.type === "updateById") {
+					if (writePlan.type === "updateById" || revisionGuard !== void 0) {
 						const { id: _id, ...updateData } = data;
-						await this.db.update(this.tableName, { id: data.id }, updateData);
-						this.setMetaType(writePlan.qualifiedMetaType);
+						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 ? { updated_at: this.revisionPredicateValue(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) {
@@ -1087,12 +1197,17 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 							const field = this.extractConstraintFieldFromChain(error, classification);
 							throw ValidationError.requiredField(field, className);
 						}
-						const operation = writePlan.type === "updateById" ? `UPDATE ${this.tableName} (id-targeted)` : this._insertOnly && !this._persisted ? `INSERT INTO ${this.tableName}` : `UPSERT INTO ${this.tableName}`;
+						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);
 					}
 					throw error;
 				}
 			}, 3, 500));
+			if (!revisionMatched) throw new RuntimeError(`Revision conflict while saving ${className}`, "RUNTIME_REVISION_CONFLICT", {
+				className,
+				id: this.id
+			});
+			revisionPersisted = true;
 			this._persisted = true;
 			this.invalidateCollectionReadCache();
 			await GlobalInterceptors.executeAfterSave(this, interceptorContext);
@@ -1108,12 +1223,85 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			if (skipAutoEmbeddings) this.options._skipAutoEmbeddings = false;
 			return this;
 		} catch (error) {
+			if (!revisionPersisted) this.updated_at = previousUpdatedAt;
 			if (error instanceof SmrtError) throw error;
 			if (this.isTenantContractError(error)) throw error;
 			throw RuntimeError.operationFailed("save", `${className}#${this.id}`, error instanceof Error ? error : new Error(String(error)));
 		}
 	}
 	/**
+	* Atomically claim the current row revision without running model save hooks.
+	*
+	* Artifact-producing workflows use this immediately before persisting their
+	* artifacts in the same transaction. It provides the same compare-and-swap
+	* conflict contract as `save({ expectedUpdatedAt })`, while deliberately not
+	* re-running domain mutation, publication, embedding, or relationship hooks.
+	*/
+	async claimRevision(expectedUpdatedAt) {
+		const className = this.getResolvedClassName();
+		if (!this._persisted || !this.id) throw RuntimeError.invalidState("A revision claim requires a persisted object", { className });
+		await GlobalInterceptors.executeBeforeSave(this, createInterceptorContext(className, "save"));
+		const updatedAt = this.nextRevisionTimestamp(expectedUpdatedAt);
+		let result;
+		let revisionMatched = true;
+		const useEmbeddedRevisionFallback = usesEmbeddedRevisionFallback(this.db);
+		await withEmbeddedWriteQueue(this.db, useEmbeddedRevisionFallback, async () => {
+			let current = null;
+			if (useEmbeddedRevisionFallback) {
+				current = await this.getCanonicalPersistedRow({ id: this.id });
+				if (!current || !this.revisionsEqual(current.updated_at, expectedUpdatedAt)) {
+					revisionMatched = false;
+					return;
+				}
+			}
+			result = useEmbeddedRevisionFallback ? await this.db.upsert(this.tableName, ["id"], {
+				...current,
+				updated_at: updatedAt.toISOString()
+			}) : await this.db.update(this.tableName, {
+				id: this.id,
+				updated_at: this.revisionPredicateValue(expectedUpdatedAt)
+			}, { updated_at: updatedAt.toISOString() });
+		});
+		if (!revisionMatched || result?.affected !== 1) throw new RuntimeError(`Revision conflict while claiming ${className}`, "RUNTIME_REVISION_CONFLICT", {
+			className,
+			id: this.id
+		});
+		this.updated_at = updatedAt;
+		this.invalidateCollectionReadCache();
+		await recordInstanceChange(this, "update");
+		return this;
+	}
+	/**
+	* Complete the observation lifecycle for a guarded update implemented by an
+	* owning subclass outside save(). The confirmed durable row is hydrated
+	* before observers run so cache invalidation, tenant-scoped change feeds,
+	* and other after-save consumers all see authoritative state.
+	*/
+	async completePersistedUpdate(durableRow) {
+		await this.loadDataFromDb(durableRow);
+		this.invalidateCollectionReadCache();
+		const context = createInterceptorContext(this.getResolvedClassName(), "save");
+		context.metadata = {
+			...context.metadata,
+			[CHANGE_FEED_WAS_PERSISTED_KEY]: true
+		};
+		await GlobalInterceptors.executeAfterSave(this, context);
+	}
+	revisionPredicateValue(revision) {
+		return revision instanceof Date ? revision.toISOString() : revision;
+	}
+	revisionsEqual(left, right) {
+		const leftTime = left instanceof Date ? left.getTime() : typeof left === "string" ? Date.parse(left) : NaN;
+		const rightTime = right instanceof Date ? right.getTime() : Date.parse(right);
+		return Number.isFinite(leftTime) && leftTime === rightTime;
+	}
+	nextRevisionTimestamp(expectedUpdatedAt) {
+		const revisionTimes = [this.updated_at, expectedUpdatedAt].filter((revision) => revision != null).map((revision) => revision instanceof Date ? revision.getTime() : Date.parse(revision)).filter(Number.isFinite);
+		const revisionFloor = revisionTimes.length > 0 ? Math.max(...revisionTimes) : Number.NEGATIVE_INFINITY;
+		const nextRevisionTime = Math.max(Date.now(), revisionFloor + 1);
+		return new Date(nextRevisionTime);
+	}
+	/**
 	* Detects tenant-boundary errors that must propagate from `save()` unwrapped.
 	*
 	* Matches both core's {@link TenantIsolationError} and the duck-typed
@@ -1322,7 +1510,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			await this.verifyStorageReady();
 			await ErrorUtils.withRetry(async () => {
 				try {
-					const existing = await this.db.get(this.tableName, filter);
+					const existing = await this.getCanonicalPersistedRow(filter);
 					if (existing) await this.loadDataFromDb(existing);
 				} catch (error) {
 					throw DatabaseError.queryFailed(`get(${this.tableName}, { id: ${this._id} })`, error instanceof Error ? error : new Error(String(error)));
@@ -1354,10 +1542,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*/
 	async loadFromSlug() {
 		await this.verifyStorageReady();
-		const existing = await this.db.get(this.tableName, await this.interceptGetFilter({
+		const filter = await this.interceptGetFilter({
 			slug: this._slug,
 			context: this._context || ""
-		}));
+		});
+		const existing = await this.getCanonicalPersistedRow(filter);
 		if (existing) await this.loadDataFromDb(existing);
 	}
 	/**
@@ -1620,11 +1809,11 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		await GlobalInterceptors.executeBeforeDelete(this, interceptorContext);
 		await this.runHook("beforeDelete");
 		await this.verifyStorageReady();
-		const { affectedTables, affectedTableClasses } = await runCascadeDelete(this.db, ObjectRegistry, {
+		const { affectedTables, affectedTableClasses } = await withEmbeddedWriteQueue(this.db, isEmbeddedDatabase(this.db), () => runCascadeDelete(this.db, ObjectRegistry, {
 			className: this.getResolvedQualifiedName(),
 			tableName: this.tableName,
 			id: this.id
-		}, (db) => db.delete(this.tableName, { id: this.id }).then(() => void 0));
+		}, (db) => db.delete(this.tableName, { id: this.id }).then(() => void 0)));
 		this._persisted = false;
 		this.invalidateCollectionReadCache();
 		for (const table of affectedTables) this.invalidateCollectionReadCache(table, affectedTableClasses.get(table));