@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/browser.d.ts

@@ -18,6 +18,7 @@ export * from './class';
 export * from './collection';
 export type { AiUsageConfig, GlobalSignalConfig, MetricsConfig, PubSubConfig, } from './config';
 export { config } from './config';
+export { classifyDatabaseError, classifyDialectMessage, type DatabaseErrorClassification, type DatabaseErrorKind, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isTransientDatabaseError, isUniqueViolationError, } from './db-errors';
 export * from './errors';
 export { type HierarchyView, SmrtHierarchical } from './hierarchical';
 export { type JunctionAttachOptions, type JunctionFilterOptions, SmrtJunction, } from './junction';

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,GACvC,MAAM,2BAA2B,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD,cAAc,iBAAiB,CAAC;AAEhC,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAOlC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,yBAAyB,EACzB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,GACvC,MAAM,2BAA2B,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD,cAAc,iBAAiB,CAAC;AAEhC,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,cAAc,eAAe,CAAC"}

package/dist/browser.js

@@ -3,12 +3,13 @@ import { DEFAULT_AI_COST_RATES, estimateAiUsageCost } from "./adapters/cost-rate
 import { MetricsAdapter } from "./adapters/metrics.js";
 import { PubSubAdapter } from "./adapters/pubsub.js";
 import "./adapters/index.js";
+import { classifyDatabaseError, classifyDialectMessage, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isTransientDatabaseError, isUniqueViolationError } from "./db-errors.js";
+import { AIError, ConfigurationError, DatabaseError, ErrorUtils, FilesystemError, NetworkError, RuntimeError, SmrtError, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils } from "./errors.js";
 import { config } from "./config.js";
 import { SignalSanitizer } from "./signals/sanitizer.js";
 import { SignalBus } from "./signals/bus.js";
-import { assertPostgresSystemTimestampsCurrent, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, getDatabaseEngine, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, tableExists } from "./system/compatibility.js";
+import { assertPostgresSystemTimestampsCurrent, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, getDatabaseEngine, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, tableExists } from "./system/compatibility.js";
 import { SmrtClass } from "./class.js";
-import { AIError, ConfigurationError, DatabaseError, ErrorUtils, FilesystemError, NetworkError, RuntimeError, SmrtError, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils } from "./errors.js";
 import { convertTypeToJsonSchema, generateToolFromMethod, generateToolManifest, shouldIncludeMethod } from "./tools/tool-generator.js";
 import { executeToolCall, executeToolCalls, formatToolResults, validateToolCall } from "./tools/tool-executor.js";
 import { SmrtObject } from "./object.js";
@@ -19,6 +20,7 @@ import { SmrtHierarchical } from "./hierarchical.js";
 import { SmrtJunction } from "./junction.js";
 import { SmrtPolymorphicAssociation } from "./polymorphic-association.js";
 import "./signals/index.js";
+import { DEFAULT_RETENTION_POLICY, clearRetentionTasks, getRetentionTasks, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, unregisterRetentionTask } from "./system/retention.js";
 import "./system/index.js";
 import "./tools/index.js";
-export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DatabaseError, ErrorUtils, FilesystemError, MetricsAdapter, NetworkError, ObjectRegistry, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, assertPostgresSystemTimestampsCurrent, config, convertTypeToJsonSchema, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, isSmrtCollectionExtendsName, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, validateToolCall };
+export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DEFAULT_RETENTION_POLICY, DatabaseError, ErrorUtils, FilesystemError, MetricsAdapter, NetworkError, ObjectRegistry, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, assertPostgresSystemTimestampsCurrent, classifyDatabaseError, classifyDialectMessage, clearRetentionTasks, config, convertTypeToJsonSchema, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, getRetentionTasks, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isSmrtCollectionExtendsName, isTransientDatabaseError, isUniqueViolationError, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, unregisterRetentionTask, validateToolCall };

package/dist/cascade.d.ts

@@ -0,0 +1,120 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { ObjectRegistry } from './registry.js';
+/**
+ * Referential action applied to rows pointing at a deleted object.
+ *
+ * Same vocabulary as SQL's `ON DELETE`, enforced by the framework instead of
+ * the engine. `NO ACTION` means "leave the rows alone" — SMRT emits no
+ * constraint, so nothing raises.
+ */
+export type OnDeleteAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+/** One reference that must be resolved before the target row can be removed. */
+export interface CascadeReference {
+    /** Registered name of the class holding the referencing column. */
+    className: string;
+    /** Table holding the referencing rows. */
+    tableName: string;
+    /** Field name (camelCase) on the referencing class. */
+    fieldName: string;
+    /** Column (snake_case) holding the reference. */
+    column: string;
+    /** Resolved action, never `NO ACTION` (those are dropped from the plan). */
+    action: Exclude<OnDeleteAction, 'NO ACTION'>;
+    /** `true` when the action was declared rather than derived from the key. */
+    declared: boolean;
+}
+/** A polymorphic association table that can point at any class. */
+export interface CascadePolymorphicReference {
+    /** Registered name of the association class. */
+    className: string;
+    /** Table holding the association rows. */
+    tableName: string;
+}
+/** Everything that must happen before rows of one class can be deleted. */
+export interface CascadePlan {
+    /** Typed `@foreignKey` / `@crossPackageRef` references, action-resolved. */
+    references: CascadeReference[];
+    /** Polymorphic association tables that may point at this class. */
+    polymorphic: CascadePolymorphicReference[];
+    /** `meta_type` values that identify this class in an association row. */
+    metaTypes: string[];
+    /** `true` when nothing references this class and nothing has to be visited. */
+    isEmpty: boolean;
+}
+/**
+ * Read-only slice of `ObjectRegistry` this module needs.
+ *
+ * Taking it as a parameter — rather than importing the registry as a value —
+ * keeps `cascade.ts` out of the `registry → object → cascade` import cycle,
+ * and lets tests drive the planner from a hand-built registry.
+ */
+export type CascadeRegistryView = Pick<typeof ObjectRegistry, 'getRelationshipMap' | 'getFields' | 'getConflictColumns' | 'getTableName' | 'getSelfReferableNames' | 'getClass' | 'getSTIBase' | 'getDescendants'>;
+/**
+ * Normalize a declared `onDelete` value.
+ *
+ * Accepts any casing and both `SET NULL` and `SET_NULL`, matching what the
+ * schema generator has always carried in the manifest. Returns `undefined` for
+ * an unset or unrecognized value so the caller can fall back to the default.
+ */
+export declare function normalizeOnDelete(value: unknown): OnDeleteAction | undefined;
+/**
+ * Build the cascade plan for one class.
+ *
+ * The plan is derived entirely from registry metadata, so it is valid for any
+ * database the class is used against. It is rebuilt per delete rather than
+ * cached: registration is incremental (manifests load lazily, tests register
+ * classes between cases) and a stale plan would silently skip a table.
+ *
+ * @param registry - Registry view (`ObjectRegistry` satisfies it)
+ * @param className - Class whose incoming references should be resolved
+ */
+export declare function buildCascadePlan(registry: CascadeRegistryView, className: string): CascadePlan;
+/** Outcome of a cascade run, returned so the caller can invalidate caches. */
+export interface CascadeResult {
+    /** Tables whose rows were removed or nulled, excluding the target's own. */
+    affectedTables: Set<string>;
+    /**
+     * Qualified class name that owns each entry in {@link affectedTables},
+     * where resolvable — lets the caller check *that* class's own
+     * cross-process cache config rather than only its own.
+     */
+    affectedTableClasses: Map<string, string>;
+}
+/**
+ * Resolve every reference to `ids` of `className` and clean their framework
+ * side rows, then hand control back so the caller can delete the rows.
+ *
+ * Callers are expected to run this on a transaction-bound `db` — see
+ * {@link runCascadeDelete}, which owns that decision.
+ */
+export declare function cascadeReferencesTo(db: DatabaseInterface, registry: CascadeRegistryView, target: {
+    className: string;
+    tableName: string;
+    ids: string[];
+}): Promise<CascadeResult>;
+/**
+ * Run the cascade and the target row's own deletion atomically.
+ *
+ * When anything references the class and the adapter exposes `transaction()`,
+ * the whole sequence runs inside one — including the caller's `deleteSelf`
+ * statement, so a failure part-way through cannot leave the object deleted with
+ * its junction rows intact (or vice versa). Adapters without transaction
+ * support run the same statements sequentially; this is the documented
+ * degradation, not a silent one.
+ *
+ * When nothing references the class there is nothing to keep consistent, and
+ * the transaction is skipped — see the comment on that branch.
+ *
+ * @param db - Database the object is bound to
+ * @param registry - Registry view used to build cascade plans
+ * @param target - Class, table and id of the object being deleted
+ * @param deleteSelf - Issues the target row's own `DELETE`, on the tx-bound db
+ * @returns Tables affected by the cascade, for read-cache invalidation
+ */
+export declare function runCascadeDelete(db: DatabaseInterface, registry: CascadeRegistryView, target: {
+    className: string;
+    tableName: string;
+    /** An unsaved object has none; the cascade is then a no-op. */
+    id: string | null | undefined;
+}, deleteSelf: (db: DatabaseInterface) => Promise<void>): Promise<CascadeResult>;
+//# sourceMappingURL=cascade.d.ts.map

package/dist/cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAsB/E,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,mEAAmE;IACnE,WAAW,EAAE,2BAA2B,EAAE,CAAC;IAC3C,yEAAyE;IACzE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,OAAO,cAAc,EACnB,oBAAoB,GACpB,WAAW,GACX,oBAAoB,GACpB,cAAc,GACd,uBAAuB,GACvB,UAAU,GACV,YAAY,GACZ,gBAAgB,CACnB,CAAC;AASF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAM5E;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,MAAM,GAChB,WAAW,CAwHb;AA8UD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9D,OAAO,CAAC,aAAa,CAAC,CAwBxB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/B,EACD,UAAU,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC,aAAa,CAAC,CAgDxB"}

package/dist/cascade.js

@@ -0,0 +1,430 @@
+import { classifyDatabaseError } from "./db-errors.js";
+import { ConfigurationError, DatabaseError } from "./errors.js";
+import { chunkArray } from "./utils/chunk.js";
+import { toSnakeCase } from "./utils/naming.js";
+import { createLogger } from "@happyvertical/logger";
+//#region src/cascade.ts
+/**
+* App-side referential integrity for `SmrtObject.delete()` (#2371).
+*
+* SMRT emits **no** DB-level `FOREIGN KEY` constraints on any engine, so the
+* database will never clean up after a deleted row. Before this module,
+* `delete()` removed the object's own row and nothing else: junction rows,
+* polymorphic association rows, `_smrt_embeddings` and `_smrt_contexts` entries
+* were all left pointing at an id that no longer resolved, and
+* `@foreignKey(..., { onDelete })` was metadata nobody read.
+*
+* This module implements those semantics in the application layer. It mirrors
+* what a DB-level constraint would do, deliberately including the parts that
+* make it *unlike* a model-layer delete:
+*
+* - Cascaded rows are removed with set-based statements. Their `beforeDelete` /
+*   `afterDelete` hooks and interceptors do **not** run, and no change-feed
+*   tombstone is written for them — exactly as `ON DELETE CASCADE` behaves.
+*   Only the object `delete()` was called on runs the full lifecycle.
+* - When anything needs cascading, everything runs inside a single
+*   transaction when the adapter exposes one, so a partial cascade cannot
+*   survive a failure. A class with no typed references AND no registered
+*   polymorphic association class anywhere in the process skips the
+*   transaction — see {@link runCascadeDelete}. A `metaType` column can point
+*   at any class at runtime, so a polymorphic association class is always
+*   plausibly relevant; in an app with even one registered, this fast path is
+*   rare, not the common case.
+*
+* ## Which references are followed
+*
+* A reference is any `@foreignKey` / `@crossPackageRef` field on a registered
+* class whose target resolves to the deleted object's class (or one of its
+* registered STI ancestors), plus the polymorphic `(metaType, metaId)` pair on
+* {@link SmrtPolymorphicAssociation} subclasses.
+*
+* The action comes from the field's declared `onDelete`. When it is not
+* declared, the default is derived from the referencing class's natural key:
+*
+* | Reference | Default when `onDelete` is absent |
+* |---|---|
+* | Column is part of the referencing class's `conflictColumns`, and is not a `@tenantId()` field | `CASCADE` |
+* | Polymorphic `(metaType, metaId)` association row | `CASCADE` |
+* | Anything else, including every `@tenantId()` field | `NO ACTION` (legacy behaviour — the row is left alone) |
+*
+* The natural-key rule is what makes junction rows work without any
+* per-package annotation: a junction declares
+* `@smrt({ conflictColumns: ['content_id', 'asset_id', 'relationship'] })`, so
+* `content_id` identifies the row and the row cannot outlive the content it
+* links. An ordinary child (`Order.customerId`) is keyed by `(slug, context)`,
+* so it keeps today's behaviour unless it opts in with
+* `@foreignKey(Customer, { onDelete: 'CASCADE' })`.
+*
+* `@tenantId()` fields are excluded from the natural-key rule even though
+* `@happyvertical/smrt-tenancy` leads a tenant-scoped class's *default*
+* `conflictColumns` with the tenant column (#2360): the tenant column scopes
+* ownership, it does not identify the row the way a junction's foreign key
+* does, and it targets a class (`Tenant`) that is virtually always
+* referenced. Without this exclusion, deleting one `Tenant` row would
+* recursively CASCADE through every tenant-scoped table that has not
+* declared its own `conflictColumns` — the overwhelming majority. The field
+* is detected via the `__tenancy.isTenantIdField` marker `@tenantId()`
+* attaches to its own registration (`FieldMeta.__tenancy`, read structurally
+* so `smrt-core` never depends on `smrt-tenancy`). `@tenantId()` exposes no
+* `onDelete` option today, so this cannot currently be overridden per field.
+*
+* @see https://github.com/happyvertical/smrt/issues/2371
+* @module
+*/
+var logger = createLogger({ level: "info" });
+/** Table holding framework-managed per-object memory entries. */
+var CONTEXTS_TABLE = "_smrt_contexts";
+/** Table holding framework-managed per-object embedding vectors. */
+var EMBEDDINGS_TABLE = "_smrt_embeddings";
+/**
+* Reserved `_smrt_contexts.owner_id` used by `SmrtCollection.remember()` for
+* collection-scoped memory. A real object id is a UUID and can never equal it,
+* but the guard keeps a malformed id from wiping every sibling's defaults.
+*/
+var COLLECTION_OWNER_SENTINEL = "__collection__";
+/**
+* Maximum number of cascade levels followed from the object `delete()` was
+* called on. A cycle between two classes that both declare `onDelete: 'CASCADE'`
+* is broken by the visited set; this bound catches unbounded *chains*.
+*/
+var MAX_CASCADE_DEPTH = 10;
+var CASCADE_ACTIONS = /* @__PURE__ */ new Set([
+	"CASCADE",
+	"SET NULL",
+	"RESTRICT",
+	"NO ACTION"
+]);
+/**
+* Normalize a declared `onDelete` value.
+*
+* Accepts any casing and both `SET NULL` and `SET_NULL`, matching what the
+* schema generator has always carried in the manifest. Returns `undefined` for
+* an unset or unrecognized value so the caller can fall back to the default.
+*/
+function normalizeOnDelete(value) {
+	if (typeof value !== "string") return void 0;
+	const normalized = value.trim().toUpperCase().replace(/_/g, " ");
+	return CASCADE_ACTIONS.has(normalized) ? normalized : void 0;
+}
+function isPolymorphicAssociationClass(fields) {
+	return fields.has("metaType") && fields.has("metaId") && fields.has("role");
+}
+/**
+* Build the cascade plan for one class.
+*
+* The plan is derived entirely from registry metadata, so it is valid for any
+* database the class is used against. It is rebuilt per delete rather than
+* cached: registration is incremental (manifests load lazily, tests register
+* classes between cases) and a stale plan would silently skip a table.
+*
+* @param registry - Registry view (`ObjectRegistry` satisfies it)
+* @param className - Class whose incoming references should be resolved
+*/
+function buildCascadePlan(registry, className) {
+	const targetNames = new Set(registry.getSelfReferableNames(className));
+	for (const name of [...targetNames]) {
+		const qualified = registry.getClass(name)?.qualifiedName;
+		if (qualified) targetNames.add(qualified);
+	}
+	const references = [];
+	const polymorphic = [];
+	for (const [sourceClass, relationships] of registry.getRelationshipMap()) {
+		const fields = registry.getFields(sourceClass);
+		if (isPolymorphicAssociationClass(fields)) {
+			const tableName = registry.getTableName(sourceClass);
+			if (tableName) polymorphic.push({
+				className: sourceClass,
+				tableName
+			});
+		}
+		if (relationships.length === 0) continue;
+		let conflictColumns;
+		for (const relationship of relationships) {
+			if (relationship.type !== "foreignKey" && relationship.type !== "crossPackageRef") continue;
+			if (!targetNames.has(relationship.targetClass)) continue;
+			const tableName = registry.getTableName(sourceClass);
+			if (!tableName) continue;
+			const column = toSnakeCase(relationship.fieldName);
+			const declaredAction = normalizeOnDelete(relationship.options?.onDelete);
+			if (!conflictColumns) conflictColumns = new Set(registry.getConflictColumns(sourceClass));
+			const isTenantIdField = relationship.options?.__tenancy?.isTenantIdField === true;
+			const action = declaredAction ?? (!isTenantIdField && conflictColumns.has(column) ? "CASCADE" : "NO ACTION");
+			if (action === "NO ACTION") continue;
+			if (action === "SET NULL" && fields.get(relationship.fieldName)?.required) throw ConfigurationError.invalidConfiguration(`${sourceClass}.${relationship.fieldName} onDelete: 'SET NULL'`, relationship.fieldName, "a nullable field (mark it `nullable: true`, or use 'CASCADE' / 'RESTRICT')");
+			references.push({
+				className: sourceClass,
+				tableName,
+				fieldName: relationship.fieldName,
+				column,
+				action,
+				declared: declaredAction !== void 0
+			});
+		}
+	}
+	const metaTypes = [];
+	const qualified = registry.getClass(className)?.qualifiedName;
+	if (qualified) metaTypes.push(qualified);
+	const simple = registry.getClass(className)?.name ?? className;
+	if (!metaTypes.includes(simple)) metaTypes.push(simple);
+	return {
+		references,
+		polymorphic,
+		metaTypes,
+		isEmpty: references.length === 0 && polymorphic.length === 0
+	};
+}
+/** Resolve a registry-recorded class name to its qualified form, when known. */
+function toQualifiedClassName(registry, className) {
+	return registry.getClass(className)?.qualifiedName ?? className;
+}
+/**
+* Every value `_smrt_contexts.owner_class` / `_smrt_embeddings.object_class`
+* could plausibly hold for a row belonging to an id of `className` (review
+* fix): both name forms (qualified + simple — older rows predate package
+* qualification) of `className` itself, plus every other member of its STI
+* hierarchy sharing its table. A CASCADE-collected id can belong to any
+* concrete STI subclass of the declaring reference, which stamps its own
+* (more specific) runtime class name at write time, not the reference's.
+*
+* Narrowing by this set — instead of matching by id alone — closes a
+* cross-class collision: two unrelated classes using `idType: 'text'`
+* (non-UUID, not guaranteed globally unique) could otherwise share an id
+* value and have one's `remember()`/embeddings rows deleted by the other's
+* cascade.
+*/
+function ownerClassCandidates(registry, className) {
+	const stiBase = registry.getSTIBase(className) ?? className;
+	const members = /* @__PURE__ */ new Set([
+		className,
+		stiBase,
+		...registry.getDescendants(stiBase)
+	]);
+	const names = /* @__PURE__ */ new Set();
+	for (const member of members) {
+		names.add(member);
+		const registered = registry.getClass(member);
+		if (registered?.qualifiedName) names.add(registered.qualifiedName);
+		if (registered?.name) names.add(registered.name);
+	}
+	return [...names];
+}
+/**
+* Build the `where` clause matching `column` against one or more ids.
+*
+* A single id uses equality so the planner can use a plain index; multiple ids
+* use the adapter's `in` operator.
+*/
+function idPredicate(column, ids) {
+	return ids.length === 1 ? { [column]: ids[0] } : { [`${column} in`]: ids };
+}
+/**
+* Run a cascade statement against a *referencing* table, tolerating the
+* table (or an expected column) not existing in this database.
+*
+* The cascade plan is built from the in-process registry, which can carry a
+* class from any imported package — including one whose table this specific
+* database was never migrated to include (a partially adopted feature, a
+* package pulled in for its types, or, in a test process, a fixture some
+* other test file registered). A missing referencing table trivially has no
+* rows to act on, so the correct behaviour is identical to the table
+* existing and being empty — this must never abort an otherwise valid
+* delete. Any other failure (a real constraint violation, a lock timeout, a
+* genuine SQL error unrelated to the table's existence) still propagates.
+*/
+async function tolerateMissingTable(operation, fallback, context) {
+	try {
+		return await operation();
+	} catch (error) {
+		if (classifyDatabaseError(error).kind === "undefined_object") {
+			logger.warn(`Cascade delete skipped ${context.action} on '${context.table}': table or column not found in this database.`, { error: error instanceof Error ? error.message : String(error) });
+			return fallback;
+		}
+		throw error;
+	}
+}
+async function selectIds(db, tableName, column, ids) {
+	const found = [];
+	for (const batch of chunkArray(ids, 900)) {
+		const rows = await tolerateMissingTable(() => db.list(tableName, idPredicate(column, batch)), [], {
+			table: tableName,
+			action: "CASCADE select"
+		});
+		for (const row of rows) {
+			const id = row?.id;
+			if (typeof id === "string" && id.length > 0) found.push(id);
+		}
+	}
+	return found;
+}
+async function deleteByIds(db, tableName, ids) {
+	for (const batch of chunkArray(ids, 900)) await tolerateMissingTable(() => db.delete(tableName, idPredicate("id", batch)), void 0, {
+		table: tableName,
+		action: "CASCADE delete"
+	});
+}
+/**
+* Remove the framework-managed side rows owned by the given object ids.
+*
+* `_smrt_contexts` and `_smrt_embeddings` are keyed by `(owner_class, owner_id)`
+* and `(object_class, object_id)` respectively. Matched by id *and* class
+* (review fix): id alone would let two unrelated classes using
+* `idType: 'text'` (non-UUID, not guaranteed globally unique) collide on a
+* shared id value and delete each other's memory/embeddings rows. `classNames`
+* is the STI-hierarchy-expanded candidate set from
+* {@link ownerClassCandidates} — the class column stores the *runtime*
+* constructor name, which for an STI hierarchy is a concrete subclass rather
+* than the class the cascade was planned from, so a single exact name is not
+* enough.
+*
+* A missing system table is not an error — an application database may predate
+* the table, and losing derived rows must never fail an otherwise valid delete.
+*/
+async function deleteSystemRows(db, ids, classNames) {
+	const ownerIds = ids.filter((id) => typeof id === "string" && id.length > 0 && id !== COLLECTION_OWNER_SENTINEL);
+	if (ownerIds.length === 0 || classNames.length === 0) return;
+	for (const [table, idColumn, classColumn] of [[
+		CONTEXTS_TABLE,
+		"owner_id",
+		"owner_class"
+	], [
+		EMBEDDINGS_TABLE,
+		"object_id",
+		"object_class"
+	]]) for (const batch of chunkArray(ownerIds, 900)) try {
+		await db.delete(table, {
+			...idPredicate(idColumn, batch),
+			...idPredicate(classColumn, classNames)
+		});
+	} catch (error) {
+		logger.warn(`Failed to clean ${table} rows during cascade delete: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Resolve every reference pointing at `ids` of `className`, recursively.
+*
+* Does **not** delete the rows identified by `ids` — the caller owns that, so
+* `SmrtObject.delete()` keeps issuing its own final statement and its own
+* lifecycle hooks.
+*/
+async function resolveReferences(ctx, className, tableName, ids, depth) {
+	const pending = ids.filter((id) => {
+		const key = `${tableName}:${id}`;
+		if (ctx.visited.has(key)) return false;
+		ctx.visited.add(key);
+		return true;
+	});
+	if (pending.length === 0) return;
+	if (depth > MAX_CASCADE_DEPTH) throw DatabaseError.constraintViolation(`cascade delete from ${className} exceeded the maximum depth of ${MAX_CASCADE_DEPTH}; check for a chain of onDelete: 'CASCADE' references that never terminates`, className);
+	const plan = buildCascadePlan(ctx.registry, className);
+	for (const reference of plan.references) {
+		if (reference.action !== "RESTRICT") continue;
+		let remaining = 0;
+		for (const batch of chunkArray(pending, 900)) {
+			remaining += await tolerateMissingTable(() => ctx.db.count(reference.tableName, idPredicate(reference.column, batch)), 0, {
+				table: reference.tableName,
+				action: "RESTRICT check"
+			});
+			if (remaining > 0) break;
+		}
+		if (remaining > 0) throw DatabaseError.constraintViolation(`${reference.className}.${reference.fieldName} declares onDelete: 'RESTRICT' and ${remaining} row(s) still reference this ${className}`, reference.column);
+	}
+	for (const reference of plan.references) {
+		if (reference.action === "SET NULL") {
+			for (const batch of chunkArray(pending, 900)) await tolerateMissingTable(() => ctx.db.update(reference.tableName, idPredicate(reference.column, batch), { [reference.column]: null }), void 0, {
+				table: reference.tableName,
+				action: "SET NULL"
+			});
+			ctx.affectedTables.add(reference.tableName);
+			ctx.affectedTableClasses.set(reference.tableName, toQualifiedClassName(ctx.registry, reference.className));
+			continue;
+		}
+		if (reference.action !== "CASCADE") continue;
+		const childIds = await selectIds(ctx.db, reference.tableName, reference.column, pending);
+		if (childIds.length === 0) continue;
+		await resolveReferences(ctx, reference.className, reference.tableName, childIds, depth + 1);
+		await deleteSystemRows(ctx.db, childIds, ownerClassCandidates(ctx.registry, reference.className));
+		await deleteByIds(ctx.db, reference.tableName, childIds);
+		ctx.affectedTables.add(reference.tableName);
+		ctx.affectedTableClasses.set(reference.tableName, toQualifiedClassName(ctx.registry, reference.className));
+	}
+	for (const association of plan.polymorphic) for (const batch of chunkArray(pending, 900)) {
+		const where = { ...idPredicate("meta_id", batch) };
+		if (plan.metaTypes.length === 1) where.meta_type = plan.metaTypes[0];
+		else where["meta_type in"] = plan.metaTypes;
+		if (((await tolerateMissingTable(() => ctx.db.delete(association.tableName, where), void 0, {
+			table: association.tableName,
+			action: "polymorphic association cleanup"
+		}))?.affected ?? 0) > 0) {
+			ctx.affectedTables.add(association.tableName);
+			ctx.affectedTableClasses.set(association.tableName, toQualifiedClassName(ctx.registry, association.className));
+		}
+	}
+}
+/**
+* Resolve every reference to `ids` of `className` and clean their framework
+* side rows, then hand control back so the caller can delete the rows.
+*
+* Callers are expected to run this on a transaction-bound `db` — see
+* {@link runCascadeDelete}, which owns that decision.
+*/
+async function cascadeReferencesTo(db, registry, target) {
+	const ctx = {
+		db,
+		registry,
+		visited: /* @__PURE__ */ new Set(),
+		affectedTables: /* @__PURE__ */ new Set(),
+		affectedTableClasses: /* @__PURE__ */ new Map()
+	};
+	await resolveReferences(ctx, target.className, target.tableName, target.ids, 0);
+	await deleteSystemRows(db, target.ids, ownerClassCandidates(registry, target.className));
+	return {
+		affectedTables: ctx.affectedTables,
+		affectedTableClasses: ctx.affectedTableClasses
+	};
+}
+/**
+* Run the cascade and the target row's own deletion atomically.
+*
+* When anything references the class and the adapter exposes `transaction()`,
+* the whole sequence runs inside one — including the caller's `deleteSelf`
+* statement, so a failure part-way through cannot leave the object deleted with
+* its junction rows intact (or vice versa). Adapters without transaction
+* support run the same statements sequentially; this is the documented
+* degradation, not a silent one.
+*
+* When nothing references the class there is nothing to keep consistent, and
+* the transaction is skipped — see the comment on that branch.
+*
+* @param db - Database the object is bound to
+* @param registry - Registry view used to build cascade plans
+* @param target - Class, table and id of the object being deleted
+* @param deleteSelf - Issues the target row's own `DELETE`, on the tx-bound db
+* @returns Tables affected by the cascade, for read-cache invalidation
+*/
+async function runCascadeDelete(db, registry, target, deleteSelf) {
+	const ids = target.id ? [target.id] : [];
+	if (buildCascadePlan(registry, target.className).isEmpty) {
+		await deleteSelf(db);
+		await deleteSystemRows(db, ids, ownerClassCandidates(registry, target.className));
+		return {
+			affectedTables: /* @__PURE__ */ new Set(),
+			affectedTableClasses: /* @__PURE__ */ new Map()
+		};
+	}
+	const run = async (bound) => {
+		const result = await cascadeReferencesTo(bound, registry, {
+			className: target.className,
+			tableName: target.tableName,
+			ids
+		});
+		await deleteSelf(bound);
+		return result;
+	};
+	const transaction = db.transaction;
+	if (typeof transaction !== "function") return run(db);
+	return transaction.call(db, run);
+}
+//#endregion
+export { buildCascadePlan, cascadeReferencesTo, normalizeOnDelete, runCascadeDelete };
+
+//# sourceMappingURL=cascade.js.map