@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/object.js

@@ -1,14 +1,17 @@
+import { classifyDatabaseError, classifyDialectMessage } from "./db-errors.js";
+import { DatabaseError, ErrorUtils, RuntimeError, SmrtError, TenantIsolationError, ValidationError } from "./errors.js";
+import { toSnakeCase } from "./utils/naming.js";
+import { runCascadeDelete } from "./cascade.js";
 import { broadcastCacheInvalidation, hasCrossProcessCacheInterest, invalidateCollectionCache, resolveDbCacheKey } from "./collection-cache.js";
-import { GlobalInterceptors, createInterceptorContext } from "./interceptors.js";
+import { isEmbeddedDatabase, withEmbeddedWriteQueue } from "./embedded-write-queue.js";
+import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
 import { SmrtClass } from "./class.js";
 import { EmbeddingProvider } from "./embeddings/provider.js";
 import { EmbeddingStorage } from "./embeddings/storage.js";
-import { DatabaseError, ErrorUtils, RuntimeError, SmrtError, TenantIsolationError, ValidationError } from "./errors.js";
-import { toSnakeCase } from "./utils/naming.js";
 import { ContentHasher } from "./embeddings/hash.js";
 import { verifyPersistenceTable } from "./schema/table-verifier.js";
 import { executeToolCall } from "./tools/tool-executor.js";
-import { fieldsFromClass, tableNameFromClass } from "./utils.js";
+import { fieldsFromClass, keysToSnakeCase, tableNameFromClass } from "./utils.js";
 import { ObjectRegistry } from "./registry.js";
 import { createLogger } from "@happyvertical/logger";
 //#region src/object.ts
@@ -658,9 +661,9 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			const value = this.getPropertyValue(key);
 			if (value === void 0) {
 				const fieldType = prop && typeof prop === "object" && "type" in prop && prop.type || fieldDef?.type;
-				if (fieldType === "text") 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;
+				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 (isSTI && fieldDef?.type === "meta") metaData[key] = "";
+				else if (fieldType === "text") if (isSTI && fieldDef?.type === "meta") metaData[key] = "";
 				else data[key] = "";
 				else if (fieldType === "json") {
 					const defaultValue = fieldDef?.default ?? null;
@@ -800,15 +803,21 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	/**
 	* Gets or generates a unique ID for this object
 	*
+	* The natural-key lookup runs through the `beforeGet` interceptor pipeline
+	* (#2365), so under an active tenant context this can only adopt the id of
+	* a row visible to that tenant — never another tenant's same-slug row,
+	* which would both disclose the foreign id and steer a subsequent `save()`
+	* onto the foreign row.
+	*
 	* @returns Promise resolving to the object's ID
 	*/
 	async getId() {
 		if (this.slug) {
 			await this.verifyStorageReady();
-			const saved = await this.db.get(this.tableName, {
+			const saved = await this.db.get(this.tableName, await this.interceptGetFilter({
 				slug: this.slug,
 				context: this.context
-			});
+			}));
 			if (saved) this.id = saved.id;
 		}
 		if (!this.id) this.id = crypto.randomUUID();
@@ -849,22 +858,56 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	/**
 	* Gets the ID of this object if it's already saved in the database
 	*
+	* Both lookups run through the `beforeGet` interceptor pipeline (#2365), so
+	* under an active tenant context only rows visible to that tenant count as
+	* "saved".
+	*
 	* @returns Promise resolving to the saved ID or null if not saved
 	*/
 	async getSavedId() {
 		if (!this.id && !this.slug) return null;
 		await this.verifyStorageReady();
 		if (this.id) {
-			const byId = await this.db.get(this.tableName, { id: this.id });
+			const byId = await this.db.get(this.tableName, await this.interceptGetFilter({ id: this.id }));
 			if (byId) return byId.id;
 		}
 		if (this.slug) {
-			const bySlug = await this.db.get(this.tableName, { slug: this.slug });
+			const bySlug = await this.db.get(this.tableName, await this.interceptGetFilter({ slug: this.slug }));
 			if (bySlug) return bySlug.id;
 		}
 		return null;
 	}
 	/**
+	* Run the registered `beforeGet` interceptors over a direct hydration filter
+	* and return it in database column form (#2365).
+	*
+	* `loadFromId()`, `loadFromSlug()`, `getSavedId()` and `getId()` query
+	* `this.db.get` directly instead of going through `SmrtCollection.get()`, so
+	* before this hook they bypassed every read interceptor: under an active tenant context,
+	* `new Model({ slug }).initialize()` happily hydrated another tenant's row
+	* even though every collection read was filtered. Routing the filter through
+	* `GlobalInterceptors.executeBeforeGet` gives hydration the same read
+	* predicate as collection reads — the tenancy interceptor adds its tenant
+	* filter (or throws `TenantContextError` for `mode: 'required'` classes
+	* outside a tenant context), and the existing bypasses (`withSystemContext`,
+	* super-admin bypass) keep working because they short-circuit inside the
+	* interceptor itself.
+	*
+	* Interceptors speak field names (`tenantId`); `this.db.get` speaks column
+	* names, so the merged filter is converted to snake_case before use. The
+	* base filters (`id`, `slug`, `context`) are already column-shaped and pass
+	* through unchanged.
+	*
+	* @param filter - The column-shaped hydration filter to intercept
+	* @returns The intercepted filter with all keys in column form
+	*/
+	async interceptGetFilter(filter) {
+		const className = this.getResolvedClassName();
+		const interceptorContext = createInterceptorContext(className, "get");
+		const intercepted = await GlobalInterceptors.executeBeforeGet(className, filter, interceptorContext);
+		return keysToSnakeCase(typeof intercepted === "string" ? resolveGetStringFilter(intercepted) : intercepted);
+	}
+	/**
 	* Checks if this object is already saved in the database
 	*
 	* @returns Promise resolving to true if saved, false otherwise
@@ -948,16 +991,34 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* 3. Assigns a UUID `id` if not already set
 	* 4. Generates a `slug` via `getSlug()` if not already set
 	* 5. Updates `updated_at` (and sets `created_at` on first save)
-	* 6. Upserts the row with automatic retry (3 attempts, 500 ms backoff)
+	* 6. Upserts the row, retrying only failures a later attempt could survive
 	* 7. Executes `afterSave` interceptors
 	* 8. Triggers embedding generation in the background if configured
 	*
 	* For STI classes, validates that `_meta_type` is present and correct
 	* before writing to the database.
 	*
+	* **Error contract (#2366).** The driver error is classified through its
+	* whole cause chain, because `@happyvertical/sql` wraps it as
+	* `DatabaseError('Failed to upsert record into table', …)` and the
+	* constraint wording never reaches the outer `message`. A deterministic
+	* failure — unique/not-null/foreign-key/check violation, invalid input
+	* syntax, missing table, or a statement issued inside an already-aborted
+	* PostgreSQL transaction (`25P02`) — is raised on the **first** attempt with
+	* no backoff, so the original cause survives instead of being replaced by
+	* `25P02` on a doomed retry inside a caller-managed transaction. Only
+	* transient failures (serialization failure, deadlock, lock timeout, dropped
+	* connection, `SQLITE_BUSY`) are retried: up to 4 attempts total — the
+	* initial try plus 3 retries — sleeping 500, 1000 and 2000 ms between them.
+	*
 	* @returns This instance after saving (enables chaining)
-	* @throws {ValidationError} If a required field is missing or a unique constraint is violated
-	* @throws {DatabaseError} If the table does not exist (`DB_SCHEMA_MISSING`) or the query fails
+	* @throws {ValidationError} `VALIDATION_UNIQUE_CONSTRAINT` on a unique or
+	*   primary-key violation, `VALIDATION_REQUIRED_FIELD` on a NOT NULL
+	*   violation — on every adapter, and never retried
+	* @throws {DatabaseError} If the table does not exist (`DB_SCHEMA_MISSING`),
+	*   or the query fails for any other reason (`DB_QUERY_FAILED`), including
+	*   foreign-key and check violations, whose original driver error is
+	*   preserved on `cause`
 	* @throws {RuntimeError} For any other unexpected failure during save
 	*
 	* @example
@@ -1006,7 +1067,8 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 			const conflictColumns = ObjectRegistry.getConflictColumns(className);
 			const writePlan = await this.planPersistenceWrite(className, tableStrategy, data, conflictColumns);
 			const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
-			await ErrorUtils.withRetry(async () => {
+			const serializeEmbeddedWrite = writePlan.type !== "updateById" && !(this._insertOnly && !this._persisted) && isEmbeddedDatabase(this.db) && upsertConflictColumns.some((column) => data[column] == null);
+			await withEmbeddedWriteQueue(this.db, serializeEmbeddedWrite, () => ErrorUtils.withRetry(async () => {
 				try {
 					if (writePlan.type === "updateById") {
 						const { id: _id, ...updateData } = data;
@@ -1016,13 +1078,13 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 					else await this.db.upsert(this.tableName, upsertConflictColumns, data);
 				} catch (error) {
 					if (error instanceof Error) {
-						const kind = SmrtObject.classifyConstraintError(error.message);
-						if (kind === "unique") {
-							const field = this.extractConstraintField(error.message);
+						const classification = classifyDatabaseError(error);
+						if (classification.kind === "unique_violation") {
+							const field = this.extractConstraintFieldFromChain(error, classification);
 							throw ValidationError.uniqueConstraint(field, this.getFieldValue(field));
 						}
-						if (kind === "not_null") {
-							const field = this.extractConstraintField(error.message);
+						if (classification.kind === "not_null_violation") {
+							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}`;
@@ -1030,7 +1092,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 					}
 					throw error;
 				}
-			}, 3, 500);
+			}, 3, 500));
 			this._persisted = true;
 			this.invalidateCollectionReadCache();
 			await GlobalInterceptors.executeAfterSave(this, interceptorContext);
@@ -1178,11 +1240,34 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*/
 	static classifyConstraintError(message) {
 		if (!message) return null;
-		if (/NOT NULL constraint failed/i.test(message) || /null value in column .* violates not-null/i.test(message)) return "not_null";
-		if (/UNIQUE constraint failed/i.test(message) || /violates unique constraint/i.test(message) || /violates primary key constraint/i.test(message)) return "unique";
+		const kind = classifyDialectMessage(message);
+		if (kind === "not_null_violation") return "not_null";
+		if (kind === "unique_violation") return "unique";
 		return null;
 	}
 	/**
+	* Recovers the offending column for a constraint violation, searching every
+	* message in the driver-error cause chain rather than only the outermost
+	* one (#2366).
+	*
+	* Prefers the column the driver named outright (`node-postgres` sets
+	* `error.column` on a `23502`), then falls back to parsing. The adapter's
+	* wrapper message ("Failed to upsert record into table") carries no column,
+	* and PostgreSQL puts a unique violation's column in the `DETAIL` line
+	* ("Key (sku)=(abc) already exists.") — reachable either as `error.detail`
+	* on the direct INSERT path or folded into `formatDbError`'s `detail=…`
+	* string on the upsert path. Returns `'unknown_field'` only when nothing in
+	* the chain names a column.
+	*/
+	extractConstraintFieldFromChain(error, classification) {
+		if (classification.column) return classification.column;
+		for (const message of [error.message, ...classification.driverMessages]) {
+			const field = this.extractConstraintField(message);
+			if (field !== "unknown_field") return field;
+		}
+		return "unknown_field";
+	}
+	/**
 	* Extracts field name from database constraint error messages.
 	*
 	* Handles SQLite, PostgreSQL and DuckDB phrasings. Returns
@@ -1204,16 +1289,23 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	/**
 	* Hydrates this object from the database using its `id` property.
 	*
-	* Queries the database for a row matching `{ id: this._id }` and calls
-	* `loadDataFromDb()` if found. Uses a 3-attempt retry with 250 ms initial
-	* delay to handle transient failures.
+	* Queries the database for a row matching `{ id: this._id }` — after running
+	* the filter through the `beforeGet` interceptor pipeline (#2365), so tenant
+	* scoping applies to hydration exactly as it does to collection reads — and
+	* calls `loadDataFromDb()` if found. Transient failures are retried up to 4 times
+	* total — the initial try plus 3 retries — sleeping 250, 500 and 1000 ms
+	* between them; deterministic failures are not. A malformed identifier
+	* (PostgreSQL `22P02 invalid_text_representation` on a `uuid` column) is a
+	* deterministic failure, so it now raises on the first attempt instead of
+	* spending three retries re-submitting the same bad literal (#2366).
 	*
 	* Called automatically by `initialize()` when `options.id` is provided.
 	* Typically you do not need to call this directly.
 	*
 	* @returns Promise that resolves when loading is complete (no-op if not found)
 	* @throws {ValidationError} If `this._id` is not set
-	* @throws {DatabaseError} If the query fails after all retries
+	* @throws {DatabaseError} If the query fails; the driver error is preserved
+	*   on `cause`
 	*
 	* @example
 	* ```typescript
@@ -1224,12 +1316,13 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* ```
 	*/
 	async loadFromId() {
+		if (!this._id) throw ValidationError.requiredField("id", this.constructor.name);
+		const filter = await this.interceptGetFilter({ id: this._id });
 		try {
-			if (!this._id) throw ValidationError.requiredField("id", this.constructor.name);
 			await this.verifyStorageReady();
 			await ErrorUtils.withRetry(async () => {
 				try {
-					const existing = await this.db.get(this.tableName, { id: this._id });
+					const existing = await this.db.get(this.tableName, 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)));
@@ -1261,10 +1354,10 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*/
 	async loadFromSlug() {
 		await this.verifyStorageReady();
-		const existing = await this.db.get(this.tableName, {
+		const existing = await this.db.get(this.tableName, await this.interceptGetFilter({
 			slug: this._slug,
 			context: this._context || ""
-		});
+		}));
 		if (existing) await this.loadDataFromDb(existing);
 	}
 	/**
@@ -1463,34 +1556,78 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		} else if (typeof hook === "function") await hook(this);
 	}
 	/**
-	* Deletes this object from the database.
+	* Deletes this object from the database, cascading to the rows that
+	* reference it.
 	*
 	* Runs the full lifecycle in order:
 	* 1. `beforeDelete` interceptors (e.g. tenant validation)
 	* 2. `beforeDelete` lifecycle hook (defined in `@smrt({ hooks })`)
-	* 3. Database row deletion
+	* 3. Referential cleanup and the row deletion (one transaction when there
+	*    is anything to clean up — see below)
 	* 4. `afterDelete` lifecycle hook
 	* 5. `afterDelete` interceptors
 	*
+	* ## Referential cleanup (#2371)
+	*
+	* SMRT emits no DB-level `FOREIGN KEY` constraints, so step 3 enforces
+	* referential integrity in the application layer instead:
+	*
+	* - `_smrt_embeddings` and `_smrt_contexts` rows owned by this object are
+	*   removed, so a deleted object can no longer win a `semanticSearch` slot
+	*   or resurrect stale `recall()` values.
+	* - Polymorphic association rows whose `(metaType, metaId)` points here are
+	*   removed.
+	* - `@foreignKey` / `@crossPackageRef` columns pointing at this class are
+	*   resolved according to their declared `onDelete` — `'CASCADE'`,
+	*   `'SET NULL'` or `'RESTRICT'`. Without a declaration, a column that is
+	*   part of the referencing class's `conflictColumns` (junction and
+	*   association rows) defaults to `CASCADE`; every other column is left
+	*   untouched, as before.
+	*
+	* Cascaded rows are removed with set-based statements: their own hooks and
+	* interceptors do **not** run and no change-feed tombstone is written for
+	* them, exactly as a DB-level `ON DELETE CASCADE` behaves. Only this object
+	* runs the lifecycle above.
+	*
+	* When anything references this class, step 3 runs inside a single
+	* transaction when the adapter supports one, so a failed cascade cannot
+	* leave the object deleted with its junction rows intact. When nothing
+	* references it, there is nothing to keep consistent and the transaction
+	* is skipped so an ordinary delete costs no extra round trip — but that
+	* skip requires no registered polymorphic association class anywhere in
+	* the process, not just no typed reference to this class (see
+	* `cascade.ts`'s module doc: a `metaType` column can point at any class at
+	* runtime, so a polymorphic association class is always plausibly
+	* relevant).
+	*
 	* Prefer `collection.delete(id)` from application code — it loads the
 	* object first (returning `false` when not found) before calling this method.
 	*
 	* @returns Promise that resolves when deletion is complete
+	* @throws {DatabaseError} When a referencing column declares
+	*   `onDelete: 'RESTRICT'` and rows still point at this object
 	*
 	* @example
 	* ```typescript
 	* const product = await products.get('product-uuid');
 	* if (product) await product.delete();
 	* ```
+	*
+	* @see {@link foreignKey} for declaring `onDelete` on the referencing side
 	*/
 	async delete() {
 		const interceptorContext = createInterceptorContext(this.constructor.name, "delete");
 		await GlobalInterceptors.executeBeforeDelete(this, interceptorContext);
 		await this.runHook("beforeDelete");
 		await this.verifyStorageReady();
-		await this.db.delete(this.tableName, { id: this.id });
+		const { affectedTables, affectedTableClasses } = await runCascadeDelete(this.db, ObjectRegistry, {
+			className: this.getResolvedQualifiedName(),
+			tableName: this.tableName,
+			id: this.id
+		}, (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));
 		await this.runHook("afterDelete");
 		await GlobalInterceptors.executeAfterDelete(this, interceptorContext);
 	}
@@ -1504,15 +1641,21 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* broadcast to peer replicas over the database adapter's notification
 	* capability, fire-and-forget. Cache maintenance must never fail the
 	* write that triggered it.
+	*
+	* @param tableName - Table to invalidate; defaults to this object's own.
+	* @param ownerQualifiedClassName - Qualified name of the class that owns
+	*   `tableName`, when it differs from this object's own class (a
+	*   cascade-affected table, #2371) — lets the broadcast decision read
+	*   *that* class's `@smrt({ cache })` config instead of only this one's.
 	*/
-	invalidateCollectionReadCache() {
+	invalidateCollectionReadCache(tableName = this.tableName, ownerQualifiedClassName) {
 		try {
 			const dbKey = resolveDbCacheKey(this.db);
-			invalidateCollectionCache(dbKey, this.tableName);
-			if (this.shouldBroadcastCacheInvalidation(dbKey)) broadcastCacheInvalidation(this.db, this.tableName);
+			invalidateCollectionCache(dbKey, tableName);
+			if (this.shouldBroadcastCacheInvalidation(dbKey, tableName, ownerQualifiedClassName)) broadcastCacheInvalidation(this.db, tableName);
 		} catch (error) {
 			logger.warn("Failed to invalidate collection read cache after write", {
-				table: this.tableName,
+				table: tableName,
 				error: error instanceof Error ? error.message : error
 			});
 		}
@@ -1523,14 +1666,26 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	*
 	* 1. A per-call `crossProcess` cached read in this process registered
 	*    interest in the table — broadcast even without model-level config.
-	* 2. This class's resolved `@smrt({ cache })` config sets `crossProcess`.
+	* 2. The owning class's resolved `@smrt({ cache })` config sets
+	*    `crossProcess`. For this object's own table that class is `this`;
+	*    for a cascade-affected table (#2371) it is whatever class the
+	*    cascade plan attributed the table to, passed in as
+	*    `ownerQualifiedClassName` — a different class's table needs *that*
+	*    class's config checked, not this one's.
 	* 3. Any other STI hierarchy member sharing the table resolves to a
 	*    `crossProcess` config — a child that opted out with `cache: false`
 	*    still mutates the shared table its base/siblings are caching.
+	*
+	* @param ownerQualifiedClassName - Qualified class name to check rules 2
+	*   and 3 against. Defaults to this object's own resolved qualified name
+	*   when `tableName` is this object's own table; when omitted for a
+	*   foreign table (the owning class could not be resolved), rules 2/3 are
+	*   skipped and only rule 1 applies.
 	*/
-	shouldBroadcastCacheInvalidation(dbKey) {
-		if (hasCrossProcessCacheInterest(dbKey, this.tableName)) return true;
-		const qualifiedName = this.getResolvedQualifiedName();
+	shouldBroadcastCacheInvalidation(dbKey, tableName = this.tableName, ownerQualifiedClassName) {
+		if (hasCrossProcessCacheInterest(dbKey, tableName)) return true;
+		const qualifiedName = ownerQualifiedClassName ?? (tableName === this.tableName ? this.getResolvedQualifiedName() : void 0);
+		if (!qualifiedName) return false;
 		if (ObjectRegistry.resolveCollectionCacheConfig(qualifiedName)?.crossProcess) return true;
 		for (const member of getSTIHierarchyMembers(qualifiedName)) {
 			if (member === qualifiedName) continue;