@happyvertical/smrt-core 0.42.6 → 0.43.0

package/dist/cascade.js.map

@@ -1 +1 @@
-{"version":3,"file":"cascade.js","names":[],"sources":["../src/cascade.ts"],"sourcesContent":["/**\n * App-side referential integrity for `SmrtObject.delete()` (#2371).\n *\n * SMRT emits **no** DB-level `FOREIGN KEY` constraints on any engine, so the\n * database will never clean up after a deleted row. Before this module,\n * `delete()` removed the object's own row and nothing else: junction rows,\n * polymorphic association rows, `_smrt_embeddings` and `_smrt_contexts` entries\n * were all left pointing at an id that no longer resolved, and\n * `@foreignKey(..., { onDelete })` was metadata nobody read.\n *\n * This module implements those semantics in the application layer. It mirrors\n * what a DB-level constraint would do, deliberately including the parts that\n * make it *unlike* a model-layer delete:\n *\n * - Cascaded rows are removed with set-based statements. Their `beforeDelete` /\n *   `afterDelete` hooks and interceptors do **not** run, and no change-feed\n *   tombstone is written for them — exactly as `ON DELETE CASCADE` behaves.\n *   Only the object `delete()` was called on runs the full lifecycle.\n * - When anything needs cascading, everything runs inside a single\n *   transaction when the adapter exposes one, so a partial cascade cannot\n *   survive a failure. A class with no typed references AND no registered\n *   polymorphic association class anywhere in the process skips the\n *   transaction — see {@link runCascadeDelete}. A `metaType` column can point\n *   at any class at runtime, so a polymorphic association class is always\n *   plausibly relevant; in an app with even one registered, this fast path is\n *   rare, not the common case.\n *\n * ## Which references are followed\n *\n * A reference is any `@foreignKey` / `@crossPackageRef` field on a registered\n * class whose target resolves to the deleted object's class (or one of its\n * registered STI ancestors), plus the polymorphic `(metaType, metaId)` pair on\n * {@link SmrtPolymorphicAssociation} subclasses.\n *\n * The action comes from the field's declared `onDelete`. When it is not\n * declared, the default is derived from the referencing class's natural key:\n *\n * | Reference | Default when `onDelete` is absent |\n * |---|---|\n * | Column is part of the referencing class's `conflictColumns`, and is not a `@tenantId()` field | `CASCADE` |\n * | Polymorphic `(metaType, metaId)` association row | `CASCADE` |\n * | Anything else, including every `@tenantId()` field | `NO ACTION` (legacy behaviour — the row is left alone) |\n *\n * The natural-key rule is what makes junction rows work without any\n * per-package annotation: a junction declares\n * `@smrt({ conflictColumns: ['content_id', 'asset_id', 'relationship'] })`, so\n * `content_id` identifies the row and the row cannot outlive the content it\n * links. An ordinary child (`Order.customerId`) is keyed by `(slug, context)`,\n * so it keeps today's behaviour unless it opts in with\n * `@foreignKey(Customer, { onDelete: 'CASCADE' })`.\n *\n * `@tenantId()` fields are excluded from the natural-key rule even though\n * `@happyvertical/smrt-tenancy` leads a tenant-scoped class's *default*\n * `conflictColumns` with the tenant column (#2360): the tenant column scopes\n * ownership, it does not identify the row the way a junction's foreign key\n * does, and it targets a class (`Tenant`) that is virtually always\n * referenced. Without this exclusion, deleting one `Tenant` row would\n * recursively CASCADE through every tenant-scoped table that has not\n * declared its own `conflictColumns` — the overwhelming majority. The field\n * is detected via the `__tenancy.isTenantIdField` marker `@tenantId()`\n * attaches to its own registration (`FieldMeta.__tenancy`, read structurally\n * so `smrt-core` never depends on `smrt-tenancy`). `@tenantId()` exposes no\n * `onDelete` option today, so this cannot currently be overridden per field.\n *\n * @see https://github.com/happyvertical/smrt/issues/2371\n * @module\n */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { classifyDatabaseError } from './db-errors.js';\nimport { ConfigurationError, DatabaseError } from './errors.js';\n// Type-only: erased at runtime, so it cannot re-enter the\n// `registry → object → cascade` import cycle.\nimport type { ObjectRegistry } from './registry.js';\nimport { chunkArray, IN_LIST_CHUNK_SIZE } from './utils/chunk.js';\nimport { toSnakeCase } from './utils/naming.js';\n\nconst logger = createLogger({ level: 'info' });\n\n/**\n * Referential action applied to rows pointing at a deleted object.\n *\n * Same vocabulary as SQL's `ON DELETE`, enforced by the framework instead of\n * the engine. `NO ACTION` means \"leave the rows alone\" — SMRT emits no\n * constraint, so nothing raises.\n */\nexport type OnDeleteAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';\n\n/** Table holding framework-managed per-object memory entries. */\nconst CONTEXTS_TABLE = '_smrt_contexts';\n\n/** Table holding framework-managed per-object embedding vectors. */\nconst EMBEDDINGS_TABLE = '_smrt_embeddings';\n\n/**\n * Reserved `_smrt_contexts.owner_id` used by `SmrtCollection.remember()` for\n * collection-scoped memory. A real object id is a UUID and can never equal it,\n * but the guard keeps a malformed id from wiping every sibling's defaults.\n */\nconst COLLECTION_OWNER_SENTINEL = '__collection__';\n\n/**\n * Maximum number of cascade levels followed from the object `delete()` was\n * called on. A cycle between two classes that both declare `onDelete: 'CASCADE'`\n * is broken by the visited set; this bound catches unbounded *chains*.\n */\nconst MAX_CASCADE_DEPTH = 10;\n\n/** One reference that must be resolved before the target row can be removed. */\nexport interface CascadeReference {\n  /** Registered name of the class holding the referencing column. */\n  className: string;\n  /** Table holding the referencing rows. */\n  tableName: string;\n  /** Field name (camelCase) on the referencing class. */\n  fieldName: string;\n  /** Column (snake_case) holding the reference. */\n  column: string;\n  /** Resolved action, never `NO ACTION` (those are dropped from the plan). */\n  action: Exclude<OnDeleteAction, 'NO ACTION'>;\n  /** `true` when the action was declared rather than derived from the key. */\n  declared: boolean;\n}\n\n/** A polymorphic association table that can point at any class. */\nexport interface CascadePolymorphicReference {\n  /** Registered name of the association class. */\n  className: string;\n  /** Table holding the association rows. */\n  tableName: string;\n}\n\n/** Everything that must happen before rows of one class can be deleted. */\nexport interface CascadePlan {\n  /** Typed `@foreignKey` / `@crossPackageRef` references, action-resolved. */\n  references: CascadeReference[];\n  /** Polymorphic association tables that may point at this class. */\n  polymorphic: CascadePolymorphicReference[];\n  /** `meta_type` values that identify this class in an association row. */\n  metaTypes: string[];\n  /** `true` when nothing references this class and nothing has to be visited. */\n  isEmpty: boolean;\n}\n\n/**\n * Read-only slice of `ObjectRegistry` this module needs.\n *\n * Taking it as a parameter — rather than importing the registry as a value —\n * keeps `cascade.ts` out of the `registry → object → cascade` import cycle,\n * and lets tests drive the planner from a hand-built registry.\n */\nexport type CascadeRegistryView = Pick<\n  typeof ObjectRegistry,\n  | 'getRelationshipMap'\n  | 'getFields'\n  | 'getConflictColumns'\n  | 'getTableName'\n  | 'getSelfReferableNames'\n  | 'getClass'\n  | 'getSTIBase'\n  | 'getDescendants'\n>;\n\nconst CASCADE_ACTIONS = new Set<OnDeleteAction>([\n  'CASCADE',\n  'SET NULL',\n  'RESTRICT',\n  'NO ACTION',\n]);\n\n/**\n * Normalize a declared `onDelete` value.\n *\n * Accepts any casing and both `SET NULL` and `SET_NULL`, matching what the\n * schema generator has always carried in the manifest. Returns `undefined` for\n * an unset or unrecognized value so the caller can fall back to the default.\n */\nexport function normalizeOnDelete(value: unknown): OnDeleteAction | undefined {\n  if (typeof value !== 'string') return undefined;\n  const normalized = value.trim().toUpperCase().replace(/_/g, ' ');\n  return CASCADE_ACTIONS.has(normalized as OnDeleteAction)\n    ? (normalized as OnDeleteAction)\n    : undefined;\n}\n\nfunction isPolymorphicAssociationClass(fields: Map<string, unknown>): boolean {\n  // The three columns `SmrtPolymorphicAssociation` contributes. Requiring all\n  // of them keeps an unrelated class that happens to carry a `metaType` from\n  // being treated as an association table.\n  return fields.has('metaType') && fields.has('metaId') && fields.has('role');\n}\n\n/**\n * Build the cascade plan for one class.\n *\n * The plan is derived entirely from registry metadata, so it is valid for any\n * database the class is used against. It is rebuilt per delete rather than\n * cached: registration is incremental (manifests load lazily, tests register\n * classes between cases) and a stale plan would silently skip a table.\n *\n * @param registry - Registry view (`ObjectRegistry` satisfies it)\n * @param className - Class whose incoming references should be resolved\n */\nexport function buildCascadePlan(\n  registry: CascadeRegistryView,\n  className: string,\n): CascadePlan {\n  // `className` is normally already qualified (delete() passes\n  // getResolvedQualifiedName()), but a common same-package `@foreignKey('X')`\n  // still stores its target as the bare simple name `X`. That still matches:\n  // getSelfReferableNames() walks the full ancestor chain (self included) and\n  // adds each ancestor's *simple* name via `getClass(ancestor)?.name`, so the\n  // simple form is already in the seed set below, not just the loop's\n  // qualified-variant augmentation.\n  const targetNames = new Set(registry.getSelfReferableNames(className));\n  for (const name of [...targetNames]) {\n    const qualified = registry.getClass(name)?.qualifiedName;\n    if (qualified) targetNames.add(qualified);\n  }\n\n  const references: CascadeReference[] = [];\n  const polymorphic: CascadePolymorphicReference[] = [];\n\n  for (const [sourceClass, relationships] of registry.getRelationshipMap()) {\n    const fields = registry.getFields(sourceClass);\n\n    if (isPolymorphicAssociationClass(fields)) {\n      const tableName = registry.getTableName(sourceClass);\n      if (tableName) {\n        polymorphic.push({ className: sourceClass, tableName });\n      }\n    }\n\n    if (relationships.length === 0) continue;\n\n    let conflictColumns: Set<string> | undefined;\n\n    for (const relationship of relationships) {\n      if (\n        relationship.type !== 'foreignKey' &&\n        relationship.type !== 'crossPackageRef'\n      ) {\n        continue;\n      }\n      if (!targetNames.has(relationship.targetClass)) continue;\n\n      const tableName = registry.getTableName(sourceClass);\n      if (!tableName) continue;\n\n      const column = toSnakeCase(relationship.fieldName);\n      const declaredAction = normalizeOnDelete(relationship.options?.onDelete);\n\n      if (!conflictColumns) {\n        conflictColumns = new Set(registry.getConflictColumns(sourceClass));\n      }\n\n      // A `@tenantId()` field is a structural scoping marker, not a\n      // junction/ownership key — it lands in `conflictColumns` only because\n      // #2360 leads every tenant-scoped class's *default* natural key with\n      // the tenant column, not because the referencing row is *identified*\n      // by its tenant the way a junction row is identified by its parent.\n      // Without this guard, deleting a `Tenant` would silently CASCADE\n      // through the tenant column of every tenant-scoped class in the\n      // schema that has not declared its own `conflictColumns` — the\n      // overwhelming majority. `@tenantId()` exposes no `onDelete` today, so\n      // an explicit declaration can never widen this back to CASCADE; that\n      // is deliberate until tenant-delete cascade is an explicit decision.\n      const isTenantIdField =\n        relationship.options?.__tenancy?.isTenantIdField === true;\n\n      const action =\n        declaredAction ??\n        (!isTenantIdField && conflictColumns.has(column)\n          ? 'CASCADE'\n          : 'NO ACTION');\n\n      if (action === 'NO ACTION') continue;\n\n      if (\n        action === 'SET NULL' &&\n        fields.get(relationship.fieldName)?.required\n      ) {\n        // Fail on the declaration, not later on a NOT NULL violation from the\n        // engine — the message there names a column, not the decorator.\n        throw ConfigurationError.invalidConfiguration(\n          `${sourceClass}.${relationship.fieldName} onDelete: 'SET NULL'`,\n          relationship.fieldName,\n          \"a nullable field (mark it `nullable: true`, or use 'CASCADE' / 'RESTRICT')\",\n        );\n      }\n\n      references.push({\n        className: sourceClass,\n        tableName,\n        fieldName: relationship.fieldName,\n        column,\n        action,\n        declared: declaredAction !== undefined,\n      });\n    }\n  }\n\n  // Both forms are matched deliberately: an association row written before a\n  // class was package-qualified still carries the simple `meta_type`. The\n  // qualified form alone is unambiguous; the simple-name fallback can still\n  // match a same-simple-name sibling class's row if it also shares a\n  // `meta_id` — a real, not just theoretical, risk for a class declaring\n  // `idType: 'text'` (non-UUID, not guaranteed globally unique), the same gap\n  // `deleteSystemRows()` closed for `_smrt_contexts` / `_smrt_embeddings`\n  // (review fix) by adding a class-name filter. Closing it here needs the\n  // same STI-and-legacy-name-aware filter this module already builds for\n  // `deleteSystemRows()` narrowed further to registry-unambiguous simple\n  // names; tracked under #2419 alongside the other same-simple-name\n  // collision gaps rather than reworked here.\n  const metaTypes: string[] = [];\n  const qualified = registry.getClass(className)?.qualifiedName;\n  if (qualified) metaTypes.push(qualified);\n  const simple = registry.getClass(className)?.name ?? className;\n  if (!metaTypes.includes(simple)) metaTypes.push(simple);\n\n  return {\n    references,\n    polymorphic,\n    metaTypes,\n    isEmpty: references.length === 0 && polymorphic.length === 0,\n  };\n}\n\n/** Per-delete state shared by every level of the cascade. */\ninterface CascadeContext {\n  db: DatabaseInterface;\n  registry: CascadeRegistryView;\n  /** `table:id` pairs already expanded, so a reference cycle terminates. */\n  visited: Set<string>;\n  /** Tables touched by the cascade, for read-cache invalidation. */\n  affectedTables: Set<string>;\n  /**\n   * Qualified name of the class that owns each affected table, so the\n   * caller can resolve *that* class's own `@smrt({ cache })` config —\n   * cross-process cache invalidation is a per-class opt-in, and a table\n   * cascaded into belongs to a different class than the one `delete()` was\n   * called on.\n   */\n  affectedTableClasses: Map<string, string>;\n}\n\n/** Resolve a registry-recorded class name to its qualified form, when known. */\nfunction toQualifiedClassName(\n  registry: CascadeRegistryView,\n  className: string,\n): string {\n  return registry.getClass(className)?.qualifiedName ?? className;\n}\n\n/**\n * Every value `_smrt_contexts.owner_class` / `_smrt_embeddings.object_class`\n * could plausibly hold for a row belonging to an id of `className` (review\n * fix): both name forms (qualified + simple — older rows predate package\n * qualification) of `className` itself, plus every other member of its STI\n * hierarchy sharing its table. A CASCADE-collected id can belong to any\n * concrete STI subclass of the declaring reference, which stamps its own\n * (more specific) runtime class name at write time, not the reference's.\n *\n * Narrowing by this set — instead of matching by id alone — closes a\n * cross-class collision: two unrelated classes using `idType: 'text'`\n * (non-UUID, not guaranteed globally unique) could otherwise share an id\n * value and have one's `remember()`/embeddings rows deleted by the other's\n * cascade.\n */\nfunction ownerClassCandidates(\n  registry: CascadeRegistryView,\n  className: string,\n): string[] {\n  const stiBase = registry.getSTIBase(className) ?? className;\n  const members = new Set<string>([\n    className,\n    stiBase,\n    ...registry.getDescendants(stiBase),\n  ]);\n\n  const names = new Set<string>();\n  for (const member of members) {\n    names.add(member);\n    const registered = registry.getClass(member);\n    if (registered?.qualifiedName) names.add(registered.qualifiedName);\n    if (registered?.name) names.add(registered.name);\n  }\n  return [...names];\n}\n\n/**\n * Build the `where` clause matching `column` against one or more ids.\n *\n * A single id uses equality so the planner can use a plain index; multiple ids\n * use the adapter's `in` operator.\n */\nfunction idPredicate(column: string, ids: string[]): Record<string, unknown> {\n  return ids.length === 1 ? { [column]: ids[0] } : { [`${column} in`]: ids };\n}\n\n/**\n * Run a cascade statement against a *referencing* table, tolerating the\n * table (or an expected column) not existing in this database.\n *\n * The cascade plan is built from the in-process registry, which can carry a\n * class from any imported package — including one whose table this specific\n * database was never migrated to include (a partially adopted feature, a\n * package pulled in for its types, or, in a test process, a fixture some\n * other test file registered). A missing referencing table trivially has no\n * rows to act on, so the correct behaviour is identical to the table\n * existing and being empty — this must never abort an otherwise valid\n * delete. Any other failure (a real constraint violation, a lock timeout, a\n * genuine SQL error unrelated to the table's existence) still propagates.\n */\nasync function tolerateMissingTable<T>(\n  operation: () => Promise<T>,\n  fallback: T,\n  context: { table: string; action: string },\n): Promise<T> {\n  try {\n    return await operation();\n  } catch (error) {\n    if (classifyDatabaseError(error).kind === 'undefined_object') {\n      logger.warn(\n        `Cascade delete skipped ${context.action} on '${context.table}': ` +\n          'table or column not found in this database.',\n        { error: error instanceof Error ? error.message : String(error) },\n      );\n      return fallback;\n    }\n    throw error;\n  }\n}\n\nasync function selectIds(\n  db: DatabaseInterface,\n  tableName: string,\n  column: string,\n  ids: string[],\n): Promise<string[]> {\n  const found: string[] = [];\n  for (const batch of chunkArray(ids, IN_LIST_CHUNK_SIZE)) {\n    const rows = await tolerateMissingTable(\n      () => db.list(tableName, idPredicate(column, batch)),\n      [] as Record<string, unknown>[],\n      { table: tableName, action: 'CASCADE select' },\n    );\n    for (const row of rows) {\n      const id = row?.id;\n      if (typeof id === 'string' && id.length > 0) found.push(id);\n    }\n  }\n  return found;\n}\n\nasync function deleteByIds(\n  db: DatabaseInterface,\n  tableName: string,\n  ids: string[],\n): Promise<void> {\n  for (const batch of chunkArray(ids, IN_LIST_CHUNK_SIZE)) {\n    await tolerateMissingTable(\n      () => db.delete(tableName, idPredicate('id', batch)),\n      undefined,\n      { table: tableName, action: 'CASCADE delete' },\n    );\n  }\n}\n\n/**\n * Remove the framework-managed side rows owned by the given object ids.\n *\n * `_smrt_contexts` and `_smrt_embeddings` are keyed by `(owner_class, owner_id)`\n * and `(object_class, object_id)` respectively. Matched by id *and* class\n * (review fix): id alone would let two unrelated classes using\n * `idType: 'text'` (non-UUID, not guaranteed globally unique) collide on a\n * shared id value and delete each other's memory/embeddings rows. `classNames`\n * is the STI-hierarchy-expanded candidate set from\n * {@link ownerClassCandidates} — the class column stores the *runtime*\n * constructor name, which for an STI hierarchy is a concrete subclass rather\n * than the class the cascade was planned from, so a single exact name is not\n * enough.\n *\n * A missing system table is not an error — an application database may predate\n * the table, and losing derived rows must never fail an otherwise valid delete.\n */\nasync function deleteSystemRows(\n  db: DatabaseInterface,\n  ids: string[],\n  classNames: string[],\n): Promise<void> {\n  const ownerIds = ids.filter(\n    (id) =>\n      typeof id === 'string' &&\n      id.length > 0 &&\n      id !== COLLECTION_OWNER_SENTINEL,\n  );\n  if (ownerIds.length === 0 || classNames.length === 0) return;\n\n  for (const [table, idColumn, classColumn] of [\n    [CONTEXTS_TABLE, 'owner_id', 'owner_class'],\n    [EMBEDDINGS_TABLE, 'object_id', 'object_class'],\n  ] as const) {\n    for (const batch of chunkArray(ownerIds, IN_LIST_CHUNK_SIZE)) {\n      try {\n        await db.delete(table, {\n          ...idPredicate(idColumn, batch),\n          ...idPredicate(classColumn, classNames),\n        });\n      } catch (error) {\n        logger.warn(\n          `Failed to clean ${table} rows during cascade delete: ${\n            error instanceof Error ? error.message : String(error)\n          }`,\n        );\n      }\n    }\n  }\n}\n\n/**\n * Resolve every reference pointing at `ids` of `className`, recursively.\n *\n * Does **not** delete the rows identified by `ids` — the caller owns that, so\n * `SmrtObject.delete()` keeps issuing its own final statement and its own\n * lifecycle hooks.\n */\nasync function resolveReferences(\n  ctx: CascadeContext,\n  className: string,\n  tableName: string,\n  ids: string[],\n  depth: number,\n): Promise<void> {\n  const pending = ids.filter((id) => {\n    const key = `${tableName}:${id}`;\n    if (ctx.visited.has(key)) return false;\n    ctx.visited.add(key);\n    return true;\n  });\n  if (pending.length === 0) return;\n\n  if (depth > MAX_CASCADE_DEPTH) {\n    throw DatabaseError.constraintViolation(\n      `cascade delete from ${className} exceeded the maximum depth of ` +\n        `${MAX_CASCADE_DEPTH}; check for a chain of onDelete: 'CASCADE' ` +\n        'references that never terminates',\n      className,\n    );\n  }\n\n  const plan = buildCascadePlan(ctx.registry, className);\n\n  // RESTRICT first: refuse before anything has been mutated.\n  for (const reference of plan.references) {\n    if (reference.action !== 'RESTRICT') continue;\n    let remaining = 0;\n    for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n      remaining += await tolerateMissingTable(\n        () =>\n          ctx.db.count(\n            reference.tableName,\n            idPredicate(reference.column, batch),\n          ),\n        0,\n        { table: reference.tableName, action: 'RESTRICT check' },\n      );\n      if (remaining > 0) break;\n    }\n    if (remaining > 0) {\n      throw DatabaseError.constraintViolation(\n        `${reference.className}.${reference.fieldName} declares ` +\n          `onDelete: 'RESTRICT' and ${remaining} row(s) still reference this ` +\n          `${className}`,\n        reference.column,\n      );\n    }\n  }\n\n  for (const reference of plan.references) {\n    if (reference.action === 'SET NULL') {\n      for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n        await tolerateMissingTable(\n          () =>\n            ctx.db.update(\n              reference.tableName,\n              idPredicate(reference.column, batch),\n              { [reference.column]: null },\n            ),\n          undefined,\n          { table: reference.tableName, action: 'SET NULL' },\n        );\n      }\n      ctx.affectedTables.add(reference.tableName);\n      ctx.affectedTableClasses.set(\n        reference.tableName,\n        toQualifiedClassName(ctx.registry, reference.className),\n      );\n      continue;\n    }\n\n    if (reference.action !== 'CASCADE') continue;\n\n    const childIds = await selectIds(\n      ctx.db,\n      reference.tableName,\n      reference.column,\n      pending,\n    );\n    if (childIds.length === 0) continue;\n\n    await resolveReferences(\n      ctx,\n      reference.className,\n      reference.tableName,\n      childIds,\n      depth + 1,\n    );\n    await deleteSystemRows(\n      ctx.db,\n      childIds,\n      ownerClassCandidates(ctx.registry, reference.className),\n    );\n    await deleteByIds(ctx.db, reference.tableName, childIds);\n    ctx.affectedTables.add(reference.tableName);\n    ctx.affectedTableClasses.set(\n      reference.tableName,\n      toQualifiedClassName(ctx.registry, reference.className),\n    );\n  }\n\n  for (const association of plan.polymorphic) {\n    for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n      const where: Record<string, unknown> = {\n        ...idPredicate('meta_id', batch),\n      };\n      if (plan.metaTypes.length === 1) {\n        where.meta_type = plan.metaTypes[0];\n      } else {\n        where['meta_type in'] = plan.metaTypes;\n      }\n      const result = await tolerateMissingTable(\n        () => ctx.db.delete(association.tableName, where),\n        undefined,\n        {\n          table: association.tableName,\n          action: 'polymorphic association cleanup',\n        },\n      );\n      if ((result?.affected ?? 0) > 0) {\n        ctx.affectedTables.add(association.tableName);\n        ctx.affectedTableClasses.set(\n          association.tableName,\n          toQualifiedClassName(ctx.registry, association.className),\n        );\n      }\n    }\n  }\n}\n\n/** Outcome of a cascade run, returned so the caller can invalidate caches. */\nexport interface CascadeResult {\n  /** Tables whose rows were removed or nulled, excluding the target's own. */\n  affectedTables: Set<string>;\n  /**\n   * Qualified class name that owns each entry in {@link affectedTables},\n   * where resolvable — lets the caller check *that* class's own\n   * cross-process cache config rather than only its own.\n   */\n  affectedTableClasses: Map<string, string>;\n}\n\n/**\n * Resolve every reference to `ids` of `className` and clean their framework\n * side rows, then hand control back so the caller can delete the rows.\n *\n * Callers are expected to run this on a transaction-bound `db` — see\n * {@link runCascadeDelete}, which owns that decision.\n */\nexport async function cascadeReferencesTo(\n  db: DatabaseInterface,\n  registry: CascadeRegistryView,\n  target: { className: string; tableName: string; ids: string[] },\n): Promise<CascadeResult> {\n  const ctx: CascadeContext = {\n    db,\n    registry,\n    visited: new Set(),\n    affectedTables: new Set(),\n    affectedTableClasses: new Map(),\n  };\n  await resolveReferences(\n    ctx,\n    target.className,\n    target.tableName,\n    target.ids,\n    0,\n  );\n  await deleteSystemRows(\n    db,\n    target.ids,\n    ownerClassCandidates(registry, target.className),\n  );\n  return {\n    affectedTables: ctx.affectedTables,\n    affectedTableClasses: ctx.affectedTableClasses,\n  };\n}\n\ntype TransactionCapable = DatabaseInterface & {\n  transaction?: <T>(\n    this: DatabaseInterface,\n    callback: (tx: DatabaseInterface) => Promise<T>,\n  ) => Promise<T>;\n};\n\n/**\n * Run the cascade and the target row's own deletion atomically.\n *\n * When anything references the class and the adapter exposes `transaction()`,\n * the whole sequence runs inside one — including the caller's `deleteSelf`\n * statement, so a failure part-way through cannot leave the object deleted with\n * its junction rows intact (or vice versa). Adapters without transaction\n * support run the same statements sequentially; this is the documented\n * degradation, not a silent one.\n *\n * When nothing references the class there is nothing to keep consistent, and\n * the transaction is skipped — see the comment on that branch.\n *\n * @param db - Database the object is bound to\n * @param registry - Registry view used to build cascade plans\n * @param target - Class, table and id of the object being deleted\n * @param deleteSelf - Issues the target row's own `DELETE`, on the tx-bound db\n * @returns Tables affected by the cascade, for read-cache invalidation\n */\nexport async function runCascadeDelete(\n  db: DatabaseInterface,\n  registry: CascadeRegistryView,\n  target: {\n    className: string;\n    tableName: string;\n    /** An unsaved object has none; the cascade is then a no-op. */\n    id: string | null | undefined;\n  },\n  deleteSelf: (db: DatabaseInterface) => Promise<void>,\n): Promise<CascadeResult> {\n  const ids = target.id ? [target.id] : [];\n\n  // Nothing references this class AND no polymorphic association class is\n  // registered anywhere in the process. `plan.polymorphic` is unconditionally\n  // every registered `SmrtPolymorphicAssociation` subclass — a `metaType`\n  // column can point at any class at runtime, so there is no static metadata\n  // to scope it by, unlike a typed `@foreignKey`/`@crossPackageRef`. This\n  // branch is therefore common for a class with no incoming references in an\n  // app with no polymorphic associations at all, but rare — not \"the\n  // overwhelmingly common case\" — once even one polymorphic class exists\n  // anywhere in the process, since every delete's plan then carries it.\n  // Opening a transaction to wrap statements that cannot disagree with each\n  // other would cost two extra round trips, and on single-connection adapters\n  // it would serialize concurrent deletes behind the transaction queue. Order\n  // the two statements instead: the row goes first, so a failure leaves\n  // everything as it was, and the derived side rows follow under the\n  // best-effort contract they already carry.\n  if (buildCascadePlan(registry, target.className).isEmpty) {\n    await deleteSelf(db);\n    await deleteSystemRows(\n      db,\n      ids,\n      ownerClassCandidates(registry, target.className),\n    );\n    return { affectedTables: new Set(), affectedTableClasses: new Map() };\n  }\n\n  const run = async (bound: DatabaseInterface): Promise<CascadeResult> => {\n    const result = await cascadeReferencesTo(bound, registry, {\n      className: target.className,\n      tableName: target.tableName,\n      ids,\n    });\n    await deleteSelf(bound);\n    return result;\n  };\n\n  const transaction = (db as TransactionCapable).transaction;\n  if (typeof transaction !== 'function') {\n    return run(db);\n  }\n\n  return transaction.call<\n    DatabaseInterface,\n    [(tx: DatabaseInterface) => Promise<CascadeResult>],\n    Promise<CascadeResult>\n  >(db, run);\n}\n"],"mappings":"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"}
+{"version":3,"file":"cascade.js","names":[],"sources":["../src/cascade.ts"],"sourcesContent":["/**\n * App-side referential integrity for `SmrtObject.delete()` (#2371).\n *\n * Same-package `@foreignKey` fields now emit database constraints where the\n * engine can enforce the declared policy. Cross-package references and older\n * schemas still rely on this application-side path. Before this module,\n * `delete()` removed the object's own row and nothing else: junction rows,\n * polymorphic association rows, `_smrt_embeddings` and `_smrt_contexts` entries\n * were all left pointing at an id that no longer resolved, and\n * `@foreignKey(..., { onDelete })` was metadata nobody read.\n *\n * This module implements those semantics in the application layer. It mirrors\n * what a DB-level constraint would do, deliberately including the parts that\n * make it *unlike* a model-layer delete:\n *\n * - Cascaded rows are removed with set-based statements. Their `beforeDelete` /\n *   `afterDelete` hooks and interceptors do **not** run, and no change-feed\n *   tombstone is written for them — exactly as `ON DELETE CASCADE` behaves.\n *   Only the object `delete()` was called on runs the full lifecycle.\n * - When anything needs cascading, everything runs inside a single\n *   transaction when the adapter exposes one, so a partial cascade cannot\n *   survive a failure. A class with no typed references AND no registered\n *   polymorphic association class anywhere in the process skips the\n *   transaction — see {@link runCascadeDelete}. A `metaType` column can point\n *   at any class at runtime, so a polymorphic association class is always\n *   plausibly relevant; in an app with even one registered, this fast path is\n *   rare, not the common case.\n *\n * ## Which references are followed\n *\n * A reference is any `@foreignKey` / `@crossPackageRef` field on a registered\n * class whose target resolves to the deleted object's class (or one of its\n * registered STI ancestors), plus the polymorphic `(metaType, metaId)` pair on\n * {@link SmrtPolymorphicAssociation} subclasses.\n *\n * The action comes from the field's declared `onDelete`. When it is not\n * declared, the default is derived from the referencing class's natural key:\n *\n * | Reference | Default when `onDelete` is absent |\n * |---|---|\n * | Column is part of the referencing class's `conflictColumns`, and is not a `@tenantId()` field | `CASCADE` |\n * | Polymorphic `(metaType, metaId)` association row | `CASCADE` |\n * | Ordinary same-package reference | `NO ACTION` (deletion is refused while references remain) |\n * | Every `@tenantId()` field | Excluded: tenant scope is not an ownership edge |\n *\n * The natural-key rule is what makes junction rows work without any\n * per-package annotation: a junction declares\n * `@smrt({ conflictColumns: ['content_id', 'asset_id', 'relationship'] })`, so\n * `content_id` identifies the row and the row cannot outlive the content it\n * links. An ordinary child (`Order.customerId`) is keyed by `(slug, context)`,\n * so it defaults to immediate `NO ACTION` unless it opts in with\n * `@foreignKey(Customer, { onDelete: 'CASCADE' })`.\n *\n * `@tenantId()` fields are excluded from the natural-key rule even though\n * `@happyvertical/smrt-tenancy` leads a tenant-scoped class's *default*\n * `conflictColumns` with the tenant column (#2360): the tenant column scopes\n * ownership, it does not identify the row the way a junction's foreign key\n * does, and it targets a class (`Tenant`) that is virtually always\n * referenced. Without this exclusion, deleting one `Tenant` row would\n * recursively CASCADE through every tenant-scoped table that has not\n * declared its own `conflictColumns` — the overwhelming majority. The field\n * is detected via the `__tenancy.isTenantIdField` marker `@tenantId()`\n * attaches to its own registration (`FieldMeta.__tenancy`, read structurally\n * so `smrt-core` never depends on `smrt-tenancy`). `@tenantId()` exposes no\n * `onDelete` option today, so this cannot currently be overridden per field.\n *\n * @see https://github.com/happyvertical/smrt/issues/2371\n * @module\n */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { classifyDatabaseError } from './db-errors.js';\nimport { ConfigurationError, DatabaseError } from './errors.js';\n// Type-only: erased at runtime, so it cannot re-enter the\n// `registry → object → cascade` import cycle.\nimport type { ObjectRegistry } from './registry.js';\nimport {\n  normalizeForeignKeyAction,\n  resolveForeignKeyDeleteAction,\n} from './schema/foreign-key-policy.js';\nimport type { ForeignKeyAction } from './schema/types.js';\nimport { chunkArray, IN_LIST_CHUNK_SIZE } from './utils/chunk.js';\nimport { toSnakeCase } from './utils/naming.js';\n\nconst logger = createLogger({ level: 'info' });\n\n/**\n * Referential action applied to rows pointing at a deleted object.\n *\n * Same vocabulary as SQL's `ON DELETE`, enforced by the framework before the\n * engine. `NO ACTION` is preflighted like an immediate restrictive action so\n * application-side and database-side enforcement agree.\n */\nexport type OnDeleteAction = ForeignKeyAction;\n\n/** Table holding framework-managed per-object memory entries. */\nconst CONTEXTS_TABLE = '_smrt_contexts';\n\n/** Table holding framework-managed per-object embedding vectors. */\nconst EMBEDDINGS_TABLE = '_smrt_embeddings';\n\n/**\n * Reserved `_smrt_contexts.owner_id` used by `SmrtCollection.remember()` for\n * collection-scoped memory. A real object id is a UUID and can never equal it,\n * but the guard keeps a malformed id from wiping every sibling's defaults.\n */\nconst COLLECTION_OWNER_SENTINEL = '__collection__';\n\n/**\n * Maximum number of cascade levels followed from the object `delete()` was\n * called on. A cycle between two classes that both declare `onDelete: 'CASCADE'`\n * is broken by the visited set; this bound catches unbounded *chains*.\n */\nconst MAX_CASCADE_DEPTH = 10;\n\n/** One reference that must be resolved before the target row can be removed. */\nexport interface CascadeReference {\n  /** Registered name of the class holding the referencing column. */\n  className: string;\n  /** Table holding the referencing rows. */\n  tableName: string;\n  /** Field name (camelCase) on the referencing class. */\n  fieldName: string;\n  /** Column (snake_case) holding the reference. */\n  column: string;\n  /** Resolved action. `NO ACTION` is preflighted like an immediate RESTRICT. */\n  action: OnDeleteAction;\n  /** `true` when the action was declared rather than derived from the key. */\n  declared: boolean;\n}\n\n/** A polymorphic association table that can point at any class. */\nexport interface CascadePolymorphicReference {\n  /** Registered name of the association class. */\n  className: string;\n  /** Table holding the association rows. */\n  tableName: string;\n}\n\n/** Everything that must happen before rows of one class can be deleted. */\nexport interface CascadePlan {\n  /** Typed `@foreignKey` / `@crossPackageRef` references, action-resolved. */\n  references: CascadeReference[];\n  /** Polymorphic association tables that may point at this class. */\n  polymorphic: CascadePolymorphicReference[];\n  /** `meta_type` values that identify this class in an association row. */\n  metaTypes: string[];\n  /** `true` when nothing references this class and nothing has to be visited. */\n  isEmpty: boolean;\n}\n\n/**\n * Read-only slice of `ObjectRegistry` this module needs.\n *\n * Taking it as a parameter — rather than importing the registry as a value —\n * keeps `cascade.ts` out of the `registry → object → cascade` import cycle,\n * and lets tests drive the planner from a hand-built registry.\n */\nexport type CascadeRegistryView = Pick<\n  typeof ObjectRegistry,\n  | 'getRelationshipMap'\n  | 'getFields'\n  | 'getConflictColumns'\n  | 'getTableName'\n  | 'getSelfReferableNames'\n  | 'getClass'\n  | 'getSTIBase'\n  | 'getDescendants'\n>;\n\n/**\n * Normalize a declared `onDelete` value.\n *\n * Accepts any casing and both `SET NULL` and `SET_NULL`, matching what the\n * schema generator has always carried in the manifest. Returns `undefined` for\n * an unset or unrecognized value so the caller can fall back to the default.\n */\nexport function normalizeOnDelete(value: unknown): OnDeleteAction | undefined {\n  return normalizeForeignKeyAction(value);\n}\n\nfunction isPolymorphicAssociationClass(fields: Map<string, unknown>): boolean {\n  // The three columns `SmrtPolymorphicAssociation` contributes. Requiring all\n  // of them keeps an unrelated class that happens to carry a `metaType` from\n  // being treated as an association table.\n  return fields.has('metaType') && fields.has('metaId') && fields.has('role');\n}\n\n/**\n * Build the cascade plan for one class.\n *\n * The plan is derived entirely from registry metadata, so it is valid for any\n * database the class is used against. It is rebuilt per delete rather than\n * cached: registration is incremental (manifests load lazily, tests register\n * classes between cases) and a stale plan would silently skip a table.\n *\n * @param registry - Registry view (`ObjectRegistry` satisfies it)\n * @param className - Class whose incoming references should be resolved\n */\nexport function buildCascadePlan(\n  registry: CascadeRegistryView,\n  className: string,\n): CascadePlan {\n  // `className` is normally already qualified (delete() passes\n  // getResolvedQualifiedName()), but a common same-package `@foreignKey('X')`\n  // still stores its target as the bare simple name `X`. That still matches:\n  // getSelfReferableNames() walks the full ancestor chain (self included) and\n  // adds each ancestor's *simple* name via `getClass(ancestor)?.name`, so the\n  // simple form is already in the seed set below, not just the loop's\n  // qualified-variant augmentation.\n  const targetNames = new Set(registry.getSelfReferableNames(className));\n  for (const name of [...targetNames]) {\n    const qualified = registry.getClass(name)?.qualifiedName;\n    if (qualified) targetNames.add(qualified);\n  }\n\n  const references: CascadeReference[] = [];\n  const polymorphic: CascadePolymorphicReference[] = [];\n\n  for (const [sourceClass, relationships] of registry.getRelationshipMap()) {\n    const fields = registry.getFields(sourceClass);\n\n    if (isPolymorphicAssociationClass(fields)) {\n      const tableName = registry.getTableName(sourceClass);\n      if (tableName) {\n        polymorphic.push({ className: sourceClass, tableName });\n      }\n    }\n\n    if (relationships.length === 0) continue;\n\n    let conflictColumns: Set<string> | undefined;\n\n    for (const relationship of relationships) {\n      if (\n        relationship.type !== 'foreignKey' &&\n        relationship.type !== 'crossPackageRef'\n      ) {\n        continue;\n      }\n      if (!targetNames.has(relationship.targetClass)) continue;\n\n      // An explicit app-side-only relationship is archival metadata, not a\n      // referential-integrity rule. Its identifier is deliberately allowed to\n      // outlive the parent, so delete planning must not block, null, or remove\n      // the retained row (#2413).\n      if (\n        relationship.type === 'foreignKey' &&\n        relationship.options?.constraint === false\n      ) {\n        continue;\n      }\n\n      const tableName = registry.getTableName(sourceClass);\n      if (!tableName) continue;\n\n      const column = toSnakeCase(relationship.fieldName);\n      if (!conflictColumns) {\n        conflictColumns = new Set(registry.getConflictColumns(sourceClass));\n      }\n\n      // A `@tenantId()` field is a structural scoping marker, not a\n      // junction/ownership key — it lands in `conflictColumns` only because\n      // #2360 leads every tenant-scoped class's *default* natural key with\n      // the tenant column, not because the referencing row is *identified*\n      // by its tenant the way a junction row is identified by its parent.\n      // Without this guard, deleting a `Tenant` would silently CASCADE\n      // through the tenant column of every tenant-scoped class in the\n      // schema that has not declared its own `conflictColumns` — the\n      // overwhelming majority. `@tenantId()` exposes no `onDelete` today, so\n      // an explicit declaration can never widen this back to CASCADE; that\n      // is deliberate until tenant-delete cascade is an explicit decision.\n      const isTenantIdField =\n        relationship.options?.__tenancy?.isTenantIdField === true;\n      if (isTenantIdField) continue;\n\n      const { action, declared } = resolveForeignKeyDeleteAction({\n        declared: relationship.options?.onDelete,\n        isConflictColumn: conflictColumns.has(column),\n        isTenantIdField: false,\n      });\n\n      if (\n        action === 'SET NULL' &&\n        fields.get(relationship.fieldName)?.required\n      ) {\n        // Fail on the declaration, not later on a NOT NULL violation from the\n        // engine — the message there names a column, not the decorator.\n        throw ConfigurationError.invalidConfiguration(\n          `${sourceClass}.${relationship.fieldName} onDelete: 'SET NULL'`,\n          relationship.fieldName,\n          \"a nullable field (mark it `nullable: true`, or use 'CASCADE' / 'RESTRICT')\",\n        );\n      }\n\n      references.push({\n        className: sourceClass,\n        tableName,\n        fieldName: relationship.fieldName,\n        column,\n        action,\n        declared,\n      });\n    }\n  }\n\n  // Both forms are matched deliberately: an association row written before a\n  // class was package-qualified still carries the simple `meta_type`. The\n  // qualified form alone is unambiguous; the simple-name fallback can still\n  // match a same-simple-name sibling class's row if it also shares a\n  // `meta_id` — a real, not just theoretical, risk for a class declaring\n  // `idType: 'text'` (non-UUID, not guaranteed globally unique), the same gap\n  // `deleteSystemRows()` closed for `_smrt_contexts` / `_smrt_embeddings`\n  // (review fix) by adding a class-name filter. Closing it here needs the\n  // same STI-and-legacy-name-aware filter this module already builds for\n  // `deleteSystemRows()` narrowed further to registry-unambiguous simple\n  // names; tracked under #2419 alongside the other same-simple-name\n  // collision gaps rather than reworked here.\n  const metaTypes: string[] = [];\n  const qualified = registry.getClass(className)?.qualifiedName;\n  if (qualified) metaTypes.push(qualified);\n  const simple = registry.getClass(className)?.name ?? className;\n  if (!metaTypes.includes(simple)) metaTypes.push(simple);\n\n  return {\n    references,\n    polymorphic,\n    metaTypes,\n    isEmpty: references.length === 0 && polymorphic.length === 0,\n  };\n}\n\n/** Per-delete state shared by every level of the cascade. */\ninterface CascadeContext {\n  db: DatabaseInterface;\n  registry: CascadeRegistryView;\n  /** `table:id` pairs already expanded, so a reference cycle terminates. */\n  visited: Set<string>;\n  /** Tables touched by the cascade, for read-cache invalidation. */\n  affectedTables: Set<string>;\n  /**\n   * Qualified name of the class that owns each affected table, so the\n   * caller can resolve *that* class's own `@smrt({ cache })` config —\n   * cross-process cache invalidation is a per-class opt-in, and a table\n   * cascaded into belongs to a different class than the one `delete()` was\n   * called on.\n   */\n  affectedTableClasses: Map<string, string>;\n}\n\n/** Resolve a registry-recorded class name to its qualified form, when known. */\nfunction toQualifiedClassName(\n  registry: CascadeRegistryView,\n  className: string,\n): string {\n  return registry.getClass(className)?.qualifiedName ?? className;\n}\n\n/**\n * Every value `_smrt_contexts.owner_class` / `_smrt_embeddings.object_class`\n * could plausibly hold for a row belonging to an id of `className` (review\n * fix): both name forms (qualified + simple — older rows predate package\n * qualification) of `className` itself, plus every other member of its STI\n * hierarchy sharing its table. A CASCADE-collected id can belong to any\n * concrete STI subclass of the declaring reference, which stamps its own\n * (more specific) runtime class name at write time, not the reference's.\n *\n * Narrowing by this set — instead of matching by id alone — closes a\n * cross-class collision: two unrelated classes using `idType: 'text'`\n * (non-UUID, not guaranteed globally unique) could otherwise share an id\n * value and have one's `remember()`/embeddings rows deleted by the other's\n * cascade.\n */\nfunction ownerClassCandidates(\n  registry: CascadeRegistryView,\n  className: string,\n): string[] {\n  const stiBase = registry.getSTIBase(className) ?? className;\n  const members = new Set<string>([\n    className,\n    stiBase,\n    ...registry.getDescendants(stiBase),\n  ]);\n\n  const names = new Set<string>();\n  for (const member of members) {\n    names.add(member);\n    const registered = registry.getClass(member);\n    if (registered?.qualifiedName) names.add(registered.qualifiedName);\n    if (registered?.name) names.add(registered.name);\n  }\n  return [...names];\n}\n\n/**\n * Build the `where` clause matching `column` against one or more ids.\n *\n * A single id uses equality so the planner can use a plain index; multiple ids\n * use the adapter's `in` operator.\n */\nfunction idPredicate(column: string, ids: string[]): Record<string, unknown> {\n  return ids.length === 1 ? { [column]: ids[0] } : { [`${column} in`]: ids };\n}\n\n/**\n * Run a cascade statement against a *referencing* table, tolerating the\n * table (or an expected column) not existing in this database.\n *\n * The cascade plan is built from the in-process registry, which can carry a\n * class from any imported package — including one whose table this specific\n * database was never migrated to include (a partially adopted feature, a\n * package pulled in for its types, or, in a test process, a fixture some\n * other test file registered). A missing referencing table trivially has no\n * rows to act on, so the correct behaviour is identical to the table\n * existing and being empty — this must never abort an otherwise valid\n * delete. Any other failure (a real constraint violation, a lock timeout, a\n * genuine SQL error unrelated to the table's existence) still propagates.\n */\nasync function tolerateMissingTable<T>(\n  operation: () => Promise<T>,\n  fallback: T,\n  context: { table: string; action: string },\n): Promise<T> {\n  try {\n    return await operation();\n  } catch (error) {\n    if (classifyDatabaseError(error).kind === 'undefined_object') {\n      logger.warn(\n        `Cascade delete skipped ${context.action} on '${context.table}': ` +\n          'table or column not found in this database.',\n        { error: error instanceof Error ? error.message : String(error) },\n      );\n      return fallback;\n    }\n    throw error;\n  }\n}\n\nasync function selectIds(\n  db: DatabaseInterface,\n  tableName: string,\n  column: string,\n  ids: string[],\n): Promise<string[]> {\n  const found: string[] = [];\n  for (const batch of chunkArray(ids, IN_LIST_CHUNK_SIZE)) {\n    const rows = await tolerateMissingTable(\n      () => db.list(tableName, idPredicate(column, batch)),\n      [] as Record<string, unknown>[],\n      { table: tableName, action: 'CASCADE select' },\n    );\n    for (const row of rows) {\n      const id = row?.id;\n      if (typeof id === 'string' && id.length > 0) found.push(id);\n    }\n  }\n  return found;\n}\n\nasync function deleteByIds(\n  db: DatabaseInterface,\n  tableName: string,\n  ids: string[],\n): Promise<void> {\n  for (const batch of chunkArray(ids, IN_LIST_CHUNK_SIZE)) {\n    await tolerateMissingTable(\n      () => db.delete(tableName, idPredicate('id', batch)),\n      undefined,\n      { table: tableName, action: 'CASCADE delete' },\n    );\n  }\n}\n\n/**\n * Remove the framework-managed side rows owned by the given object ids.\n *\n * `_smrt_contexts` and `_smrt_embeddings` are keyed by `(owner_class, owner_id)`\n * and `(object_class, object_id)` respectively. Matched by id *and* class\n * (review fix): id alone would let two unrelated classes using\n * `idType: 'text'` (non-UUID, not guaranteed globally unique) collide on a\n * shared id value and delete each other's memory/embeddings rows. `classNames`\n * is the STI-hierarchy-expanded candidate set from\n * {@link ownerClassCandidates} — the class column stores the *runtime*\n * constructor name, which for an STI hierarchy is a concrete subclass rather\n * than the class the cascade was planned from, so a single exact name is not\n * enough.\n *\n * A missing system table is not an error — an application database may predate\n * the table, and losing derived rows must never fail an otherwise valid delete.\n */\nasync function deleteSystemRows(\n  db: DatabaseInterface,\n  ids: string[],\n  classNames: string[],\n): Promise<void> {\n  const ownerIds = ids.filter(\n    (id) =>\n      typeof id === 'string' &&\n      id.length > 0 &&\n      id !== COLLECTION_OWNER_SENTINEL,\n  );\n  if (ownerIds.length === 0 || classNames.length === 0) return;\n\n  for (const [table, idColumn, classColumn] of [\n    [CONTEXTS_TABLE, 'owner_id', 'owner_class'],\n    [EMBEDDINGS_TABLE, 'object_id', 'object_class'],\n  ] as const) {\n    for (const batch of chunkArray(ownerIds, IN_LIST_CHUNK_SIZE)) {\n      try {\n        await db.delete(table, {\n          ...idPredicate(idColumn, batch),\n          ...idPredicate(classColumn, classNames),\n        });\n      } catch (error) {\n        logger.warn(\n          `Failed to clean ${table} rows during cascade delete: ${\n            error instanceof Error ? error.message : String(error)\n          }`,\n        );\n      }\n    }\n  }\n}\n\n/**\n * Resolve every reference pointing at `ids` of `className`, recursively.\n *\n * Does **not** delete the rows identified by `ids` — the caller owns that, so\n * `SmrtObject.delete()` keeps issuing its own final statement and its own\n * lifecycle hooks.\n */\nasync function resolveReferences(\n  ctx: CascadeContext,\n  className: string,\n  tableName: string,\n  ids: string[],\n  depth: number,\n): Promise<void> {\n  const pending = ids.filter((id) => {\n    const key = `${tableName}:${id}`;\n    if (ctx.visited.has(key)) return false;\n    ctx.visited.add(key);\n    return true;\n  });\n  if (pending.length === 0) return;\n\n  if (depth > MAX_CASCADE_DEPTH) {\n    throw DatabaseError.constraintViolation(\n      `cascade delete from ${className} exceeded the maximum depth of ` +\n        `${MAX_CASCADE_DEPTH}; check for a chain of onDelete: 'CASCADE' ` +\n        'references that never terminates',\n      className,\n    );\n  }\n\n  const plan = buildCascadePlan(ctx.registry, className);\n\n  // SQL NO ACTION is immediate on every supported SMRT migration path, so the\n  // app-side belt preflights it exactly like RESTRICT before any mutation.\n  for (const reference of plan.references) {\n    if (reference.action !== 'RESTRICT' && reference.action !== 'NO ACTION') {\n      continue;\n    }\n    let remaining = 0;\n    for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n      remaining += await tolerateMissingTable(\n        () =>\n          ctx.db.count(\n            reference.tableName,\n            idPredicate(reference.column, batch),\n          ),\n        0,\n        { table: reference.tableName, action: `${reference.action} check` },\n      );\n      if (remaining > 0) break;\n    }\n    if (remaining > 0) {\n      throw DatabaseError.constraintViolation(\n        `${reference.className}.${reference.fieldName} ` +\n          `${reference.declared ? 'declares' : 'resolves to'} onDelete: ` +\n          `'${reference.action}' and ${remaining} row(s) still reference this ` +\n          `${className}`,\n        reference.column,\n      );\n    }\n  }\n\n  for (const reference of plan.references) {\n    if (reference.action === 'SET NULL') {\n      for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n        await tolerateMissingTable(\n          () =>\n            ctx.db.update(\n              reference.tableName,\n              idPredicate(reference.column, batch),\n              { [reference.column]: null },\n            ),\n          undefined,\n          { table: reference.tableName, action: 'SET NULL' },\n        );\n      }\n      ctx.affectedTables.add(reference.tableName);\n      ctx.affectedTableClasses.set(\n        reference.tableName,\n        toQualifiedClassName(ctx.registry, reference.className),\n      );\n      continue;\n    }\n\n    if (reference.action !== 'CASCADE') continue;\n\n    const childIds = await selectIds(\n      ctx.db,\n      reference.tableName,\n      reference.column,\n      pending,\n    );\n    if (childIds.length === 0) continue;\n\n    await resolveReferences(\n      ctx,\n      reference.className,\n      reference.tableName,\n      childIds,\n      depth + 1,\n    );\n    await deleteSystemRows(\n      ctx.db,\n      childIds,\n      ownerClassCandidates(ctx.registry, reference.className),\n    );\n    await deleteByIds(ctx.db, reference.tableName, childIds);\n    ctx.affectedTables.add(reference.tableName);\n    ctx.affectedTableClasses.set(\n      reference.tableName,\n      toQualifiedClassName(ctx.registry, reference.className),\n    );\n  }\n\n  for (const association of plan.polymorphic) {\n    for (const batch of chunkArray(pending, IN_LIST_CHUNK_SIZE)) {\n      const where: Record<string, unknown> = {\n        ...idPredicate('meta_id', batch),\n      };\n      if (plan.metaTypes.length === 1) {\n        where.meta_type = plan.metaTypes[0];\n      } else {\n        where['meta_type in'] = plan.metaTypes;\n      }\n      const result = await tolerateMissingTable(\n        () => ctx.db.delete(association.tableName, where),\n        undefined,\n        {\n          table: association.tableName,\n          action: 'polymorphic association cleanup',\n        },\n      );\n      if ((result?.affected ?? 0) > 0) {\n        ctx.affectedTables.add(association.tableName);\n        ctx.affectedTableClasses.set(\n          association.tableName,\n          toQualifiedClassName(ctx.registry, association.className),\n        );\n      }\n    }\n  }\n}\n\n/** Outcome of a cascade run, returned so the caller can invalidate caches. */\nexport interface CascadeResult {\n  /** Tables whose rows were removed or nulled, excluding the target's own. */\n  affectedTables: Set<string>;\n  /**\n   * Qualified class name that owns each entry in {@link affectedTables},\n   * where resolvable — lets the caller check *that* class's own\n   * cross-process cache config rather than only its own.\n   */\n  affectedTableClasses: Map<string, string>;\n}\n\n/**\n * Resolve every reference to `ids` of `className` and clean their framework\n * side rows, then hand control back so the caller can delete the rows.\n *\n * Callers are expected to run this on a transaction-bound `db` — see\n * {@link runCascadeDelete}, which owns that decision.\n */\nexport async function cascadeReferencesTo(\n  db: DatabaseInterface,\n  registry: CascadeRegistryView,\n  target: { className: string; tableName: string; ids: string[] },\n): Promise<CascadeResult> {\n  const ctx: CascadeContext = {\n    db,\n    registry,\n    visited: new Set(),\n    affectedTables: new Set(),\n    affectedTableClasses: new Map(),\n  };\n  await resolveReferences(\n    ctx,\n    target.className,\n    target.tableName,\n    target.ids,\n    0,\n  );\n  await deleteSystemRows(\n    db,\n    target.ids,\n    ownerClassCandidates(registry, target.className),\n  );\n  return {\n    affectedTables: ctx.affectedTables,\n    affectedTableClasses: ctx.affectedTableClasses,\n  };\n}\n\ntype TransactionCapable = DatabaseInterface & {\n  transaction?: <T>(\n    this: DatabaseInterface,\n    callback: (tx: DatabaseInterface) => Promise<T>,\n  ) => Promise<T>;\n};\n\n/**\n * Run the cascade and the target row's own deletion atomically.\n *\n * When anything references the class and the adapter exposes `transaction()`,\n * the whole sequence runs inside one — including the caller's `deleteSelf`\n * statement, so a failure part-way through cannot leave the object deleted with\n * its junction rows intact (or vice versa). Adapters without transaction\n * support run the same statements sequentially; this is the documented\n * degradation, not a silent one.\n *\n * When nothing references the class there is nothing to keep consistent, and\n * the transaction is skipped — see the comment on that branch.\n *\n * @param db - Database the object is bound to\n * @param registry - Registry view used to build cascade plans\n * @param target - Class, table and id of the object being deleted\n * @param deleteSelf - Issues the target row's own `DELETE`, on the tx-bound db\n * @returns Tables affected by the cascade, for read-cache invalidation\n */\nexport async function runCascadeDelete(\n  db: DatabaseInterface,\n  registry: CascadeRegistryView,\n  target: {\n    className: string;\n    tableName: string;\n    /** An unsaved object has none; the cascade is then a no-op. */\n    id: string | null | undefined;\n  },\n  deleteSelf: (db: DatabaseInterface) => Promise<void>,\n): Promise<CascadeResult> {\n  const ids = target.id ? [target.id] : [];\n\n  // Nothing references this class AND no polymorphic association class is\n  // registered anywhere in the process. `plan.polymorphic` is unconditionally\n  // every registered `SmrtPolymorphicAssociation` subclass — a `metaType`\n  // column can point at any class at runtime, so there is no static metadata\n  // to scope it by, unlike a typed `@foreignKey`/`@crossPackageRef`. This\n  // branch is therefore common for a class with no incoming references in an\n  // app with no polymorphic associations at all, but rare — not \"the\n  // overwhelmingly common case\" — once even one polymorphic class exists\n  // anywhere in the process, since every delete's plan then carries it.\n  // Opening a transaction to wrap statements that cannot disagree with each\n  // other would cost two extra round trips, and on single-connection adapters\n  // it would serialize concurrent deletes behind the transaction queue. Order\n  // the two statements instead: the row goes first, so a failure leaves\n  // everything as it was, and the derived side rows follow under the\n  // best-effort contract they already carry.\n  if (buildCascadePlan(registry, target.className).isEmpty) {\n    await deleteSelf(db);\n    await deleteSystemRows(\n      db,\n      ids,\n      ownerClassCandidates(registry, target.className),\n    );\n    return { affectedTables: new Set(), affectedTableClasses: new Map() };\n  }\n\n  const run = async (bound: DatabaseInterface): Promise<CascadeResult> => {\n    const result = await cascadeReferencesTo(bound, registry, {\n      className: target.className,\n      tableName: target.tableName,\n      ids,\n    });\n    await deleteSelf(bound);\n    return result;\n  };\n\n  const transaction = (db as TransactionCapable).transaction;\n  if (typeof transaction !== 'function') {\n    return run(db);\n  }\n\n  return transaction.call<\n    DatabaseInterface,\n    [(tx: DatabaseInterface) => Promise<CascadeResult>],\n    Promise<CascadeResult>\n  >(db, run);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqFA,IAAM,SAAS,aAAa,EAAE,OAAO,OAAO,CAAC;;AAY7C,IAAM,iBAAiB;;AAGvB,IAAM,mBAAmB;;;;;;AAOzB,IAAM,4BAA4B;;;;;;AAOlC,IAAM,oBAAoB;;;;;;;;AAgE1B,SAAgB,kBAAkB,OAA4C;CAC5E,OAAO,0BAA0B,KAAK;AACxC;AAEA,SAAS,8BAA8B,QAAuC;CAI5E,OAAO,OAAO,IAAI,UAAU,KAAK,OAAO,IAAI,QAAQ,KAAK,OAAO,IAAI,MAAM;AAC5E;;;;;;;;;;;;AAaA,SAAgB,iBACd,UACA,WACa;CAQb,MAAM,cAAc,IAAI,IAAI,SAAS,sBAAsB,SAAS,CAAC;CACrE,KAAK,MAAM,QAAQ,CAAC,GAAG,WAAW,GAAG;EACnC,MAAM,YAAY,SAAS,SAAS,IAAI,CAAC,EAAE;EAC3C,IAAI,WAAW,YAAY,IAAI,SAAS;CAC1C;CAEA,MAAM,aAAiC,CAAC;CACxC,MAAM,cAA6C,CAAC;CAEpD,KAAK,MAAM,CAAC,aAAa,kBAAkB,SAAS,mBAAmB,GAAG;EACxE,MAAM,SAAS,SAAS,UAAU,WAAW;EAE7C,IAAI,8BAA8B,MAAM,GAAG;GACzC,MAAM,YAAY,SAAS,aAAa,WAAW;GACnD,IAAI,WACF,YAAY,KAAK;IAAE,WAAW;IAAa;GAAU,CAAC;EAE1D;EAEA,IAAI,cAAc,WAAW,GAAG;EAEhC,IAAI;EAEJ,KAAK,MAAM,gBAAgB,eAAe;GACxC,IACE,aAAa,SAAS,gBACtB,aAAa,SAAS,mBAEtB;GAEF,IAAI,CAAC,YAAY,IAAI,aAAa,WAAW,GAAG;GAMhD,IACE,aAAa,SAAS,gBACtB,aAAa,SAAS,eAAe,OAErC;GAGF,MAAM,YAAY,SAAS,aAAa,WAAW;GACnD,IAAI,CAAC,WAAW;GAEhB,MAAM,SAAS,YAAY,aAAa,SAAS;GACjD,IAAI,CAAC,iBACH,kBAAkB,IAAI,IAAI,SAAS,mBAAmB,WAAW,CAAC;GAgBpE,IADE,aAAa,SAAS,WAAW,oBAAoB,MAClC;GAErB,MAAM,EAAE,QAAQ,aAAa,8BAA8B;IACzD,UAAU,aAAa,SAAS;IAChC,kBAAkB,gBAAgB,IAAI,MAAM;IAC5C,iBAAiB;GACnB,CAAC;GAED,IACE,WAAW,cACX,OAAO,IAAI,aAAa,SAAS,CAAC,EAAE,UAIpC,MAAM,mBAAmB,qBACvB,GAAG,YAAY,GAAG,aAAa,UAAU,wBACzC,aAAa,WACb,4EACF;GAGF,WAAW,KAAK;IACd,WAAW;IACX;IACA,WAAW,aAAa;IACxB;IACA;IACA;GACF,CAAC;EACH;CACF;CAcA,MAAM,YAAsB,CAAC;CAC7B,MAAM,YAAY,SAAS,SAAS,SAAS,CAAC,EAAE;CAChD,IAAI,WAAW,UAAU,KAAK,SAAS;CACvC,MAAM,SAAS,SAAS,SAAS,SAAS,CAAC,EAAE,QAAQ;CACrD,IAAI,CAAC,UAAU,SAAS,MAAM,GAAG,UAAU,KAAK,MAAM;CAEtD,OAAO;EACL;EACA;EACA;EACA,SAAS,WAAW,WAAW,KAAK,YAAY,WAAW;CAC7D;AACF;;AAqBA,SAAS,qBACP,UACA,WACQ;CACR,OAAO,SAAS,SAAS,SAAS,CAAC,EAAE,iBAAiB;AACxD;;;;;;;;;;;;;;;;AAiBA,SAAS,qBACP,UACA,WACU;CACV,MAAM,UAAU,SAAS,WAAW,SAAS,KAAK;CAClD,MAAM,0BAAU,IAAI,IAAY;EAC9B;EACA;EACA,GAAG,SAAS,eAAe,OAAO;CACpC,CAAC;CAED,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,IAAI,MAAM;EAChB,MAAM,aAAa,SAAS,SAAS,MAAM;EAC3C,IAAI,YAAY,eAAe,MAAM,IAAI,WAAW,aAAa;EACjE,IAAI,YAAY,MAAM,MAAM,IAAI,WAAW,IAAI;CACjD;CACA,OAAO,CAAC,GAAG,KAAK;AAClB;;;;;;;AAQA,SAAS,YAAY,QAAgB,KAAwC;CAC3E,OAAO,IAAI,WAAW,IAAI,GAAG,SAAS,IAAI,GAAG,IAAI,GAAG,GAAG,OAAO,OAAO,IAAI;AAC3E;;;;;;;;;;;;;;;AAgBA,eAAe,qBACb,WACA,UACA,SACY;CACZ,IAAI;EACF,OAAO,MAAM,UAAU;CACzB,SAAS,OAAO;EACd,IAAI,sBAAsB,KAAK,CAAC,CAAC,SAAS,oBAAoB;GAC5D,OAAO,KACL,0BAA0B,QAAQ,OAAO,OAAO,QAAQ,MAAM,iDAE9D,EAAE,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,CAClE;GACA,OAAO;EACT;EACA,MAAM;CACR;AACF;AAEA,eAAe,UACb,IACA,WACA,QACA,KACmB;CACnB,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,WAAW,KAAA,GAAuB,GAAG;EACvD,MAAM,OAAO,MAAM,2BACX,GAAG,KAAK,WAAW,YAAY,QAAQ,KAAK,CAAC,GACnD,CAAC,GACD;GAAE,OAAO;GAAW,QAAQ;EAAiB,CAC/C;EACA,KAAK,MAAM,OAAO,MAAM;GACtB,MAAM,KAAK,KAAK;GAChB,IAAI,OAAO,OAAO,YAAY,GAAG,SAAS,GAAG,MAAM,KAAK,EAAE;EAC5D;CACF;CACA,OAAO;AACT;AAEA,eAAe,YACb,IACA,WACA,KACe;CACf,KAAK,MAAM,SAAS,WAAW,KAAA,GAAuB,GACpD,MAAM,2BACE,GAAG,OAAO,WAAW,YAAY,MAAM,KAAK,CAAC,GACnD,KAAA,GACA;EAAE,OAAO;EAAW,QAAQ;CAAiB,CAC/C;AAEJ;;;;;;;;;;;;;;;;;;AAmBA,eAAe,iBACb,IACA,KACA,YACe;CACf,MAAM,WAAW,IAAI,QAClB,OACC,OAAO,OAAO,YACd,GAAG,SAAS,KACZ,OAAO,yBACX;CACA,IAAI,SAAS,WAAW,KAAK,WAAW,WAAW,GAAG;CAEtD,KAAK,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAC3C;EAAC;EAAgB;EAAY;CAAa,GAC1C;EAAC;EAAkB;EAAa;CAAc,CAChD,GACE,KAAK,MAAM,SAAS,WAAW,UAAA,GAA4B,GACzD,IAAI;EACF,MAAM,GAAG,OAAO,OAAO;GACrB,GAAG,YAAY,UAAU,KAAK;GAC9B,GAAG,YAAY,aAAa,UAAU;EACxC,CAAC;CACH,SAAS,OAAO;EACd,OAAO,KACL,mBAAmB,MAAM,+BACvB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAEzD;CACF;AAGN;;;;;;;;AASA,eAAe,kBACb,KACA,WACA,WACA,KACA,OACe;CACf,MAAM,UAAU,IAAI,QAAQ,OAAO;EACjC,MAAM,MAAM,GAAG,UAAU,GAAG;EAC5B,IAAI,IAAI,QAAQ,IAAI,GAAG,GAAG,OAAO;EACjC,IAAI,QAAQ,IAAI,GAAG;EACnB,OAAO;CACT,CAAC;CACD,IAAI,QAAQ,WAAW,GAAG;CAE1B,IAAI,QAAQ,mBACV,MAAM,cAAc,oBAClB,uBAAuB,UAAU,iCAC5B,kBAAkB,8EAEvB,SACF;CAGF,MAAM,OAAO,iBAAiB,IAAI,UAAU,SAAS;CAIrD,KAAK,MAAM,aAAa,KAAK,YAAY;EACvC,IAAI,UAAU,WAAW,cAAc,UAAU,WAAW,aAC1D;EAEF,IAAI,YAAY;EAChB,KAAK,MAAM,SAAS,WAAW,SAAA,GAA2B,GAAG;GAC3D,aAAa,MAAM,2BAEf,IAAI,GAAG,MACL,UAAU,WACV,YAAY,UAAU,QAAQ,KAAK,CACrC,GACF,GACA;IAAE,OAAO,UAAU;IAAW,QAAQ,GAAG,UAAU,OAAO;GAAQ,CACpE;GACA,IAAI,YAAY,GAAG;EACrB;EACA,IAAI,YAAY,GACd,MAAM,cAAc,oBAClB,GAAG,UAAU,UAAU,GAAG,UAAU,UAAU,GACzC,UAAU,WAAW,aAAa,cAAc,cAC/C,UAAU,OAAO,QAAQ,UAAU,+BACpC,aACL,UAAU,MACZ;CAEJ;CAEA,KAAK,MAAM,aAAa,KAAK,YAAY;EACvC,IAAI,UAAU,WAAW,YAAY;GACnC,KAAK,MAAM,SAAS,WAAW,SAAA,GAA2B,GACxD,MAAM,2BAEF,IAAI,GAAG,OACL,UAAU,WACV,YAAY,UAAU,QAAQ,KAAK,GACnC,GAAG,UAAU,SAAS,KAAK,CAC7B,GACF,KAAA,GACA;IAAE,OAAO,UAAU;IAAW,QAAQ;GAAW,CACnD;GAEF,IAAI,eAAe,IAAI,UAAU,SAAS;GAC1C,IAAI,qBAAqB,IACvB,UAAU,WACV,qBAAqB,IAAI,UAAU,UAAU,SAAS,CACxD;GACA;EACF;EAEA,IAAI,UAAU,WAAW,WAAW;EAEpC,MAAM,WAAW,MAAM,UACrB,IAAI,IACJ,UAAU,WACV,UAAU,QACV,OACF;EACA,IAAI,SAAS,WAAW,GAAG;EAE3B,MAAM,kBACJ,KACA,UAAU,WACV,UAAU,WACV,UACA,QAAQ,CACV;EACA,MAAM,iBACJ,IAAI,IACJ,UACA,qBAAqB,IAAI,UAAU,UAAU,SAAS,CACxD;EACA,MAAM,YAAY,IAAI,IAAI,UAAU,WAAW,QAAQ;EACvD,IAAI,eAAe,IAAI,UAAU,SAAS;EAC1C,IAAI,qBAAqB,IACvB,UAAU,WACV,qBAAqB,IAAI,UAAU,UAAU,SAAS,CACxD;CACF;CAEA,KAAK,MAAM,eAAe,KAAK,aAC7B,KAAK,MAAM,SAAS,WAAW,SAAA,GAA2B,GAAG;EAC3D,MAAM,QAAiC,EACrC,GAAG,YAAY,WAAW,KAAK,EACjC;EACA,IAAI,KAAK,UAAU,WAAW,GAC5B,MAAM,YAAY,KAAK,UAAU;OAEjC,MAAM,kBAAkB,KAAK;EAU/B,MAAK,MARgB,2BACb,IAAI,GAAG,OAAO,YAAY,WAAW,KAAK,GAChD,KAAA,GACA;GACE,OAAO,YAAY;GACnB,QAAQ;EACV,CACF,EAAA,EACa,YAAY,KAAK,GAAG;GAC/B,IAAI,eAAe,IAAI,YAAY,SAAS;GAC5C,IAAI,qBAAqB,IACvB,YAAY,WACZ,qBAAqB,IAAI,UAAU,YAAY,SAAS,CAC1D;EACF;CACF;AAEJ;;;;;;;;AAqBA,eAAsB,oBACpB,IACA,UACA,QACwB;CACxB,MAAM,MAAsB;EAC1B;EACA;EACA,yBAAS,IAAI,IAAI;EACjB,gCAAgB,IAAI,IAAI;EACxB,sCAAsB,IAAI,IAAI;CAChC;CACA,MAAM,kBACJ,KACA,OAAO,WACP,OAAO,WACP,OAAO,KACP,CACF;CACA,MAAM,iBACJ,IACA,OAAO,KACP,qBAAqB,UAAU,OAAO,SAAS,CACjD;CACA,OAAO;EACL,gBAAgB,IAAI;EACpB,sBAAsB,IAAI;CAC5B;AACF;;;;;;;;;;;;;;;;;;;;AA4BA,eAAsB,iBACpB,IACA,UACA,QAMA,YACwB;CACxB,MAAM,MAAM,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC;CAiBvC,IAAI,iBAAiB,UAAU,OAAO,SAAS,CAAC,CAAC,SAAS;EACxD,MAAM,WAAW,EAAE;EACnB,MAAM,iBACJ,IACA,KACA,qBAAqB,UAAU,OAAO,SAAS,CACjD;EACA,OAAO;GAAE,gCAAgB,IAAI,IAAI;GAAG,sCAAsB,IAAI,IAAI;EAAE;CACtE;CAEA,MAAM,MAAM,OAAO,UAAqD;EACtE,MAAM,SAAS,MAAM,oBAAoB,OAAO,UAAU;GACxD,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB;EACF,CAAC;EACD,MAAM,WAAW,KAAK;EACtB,OAAO;CACT;CAEA,MAAM,cAAe,GAA0B;CAC/C,IAAI,OAAO,gBAAgB,YACzB,OAAO,IAAI,EAAE;CAGf,OAAO,YAAY,KAIjB,IAAI,GAAG;AACX"}

package/dist/class.d.ts

@@ -254,6 +254,13 @@ export declare class SmrtClass {
      * System tables use _smrt_ prefix to avoid conflicts with user tables
      */
     protected get systemDb(): DatabaseInterface;
+    /**
+     * Return the database engine hint captured from the caller's configuration.
+     * Adapters may not expose their original type after construction (notably
+     * in-memory DuckDB/JSON connections), so query helpers can combine this
+     * hint with their public connection capabilities.
+     */
+    protected getDatabaseEngineHint(): string | undefined;
     /**
      * Initialize signal bus and adapters
      *
@@ -293,6 +300,16 @@ export declare class SmrtClass {
      * Gets the database interface instance
      */
     get db(): DatabaseInterface;
+    /**
+     * Temporarily bind this initialized instance to another database interface.
+     *
+     * This is intended for transaction-scoped work where a caller must ensure
+     * that every nested SMRT read and write uses the transaction database passed
+     * to its callback. The original database is restored whether the callback
+     * succeeds or throws. Do not use the same instance concurrently while it is
+     * temporarily bound.
+     */
+    withDatabase<T>(db: DatabaseInterface, operation: (bound: this) => Promise<T>): Promise<T>;
     /**
      * Gets the AI client instance
      */

package/dist/class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,KAAK,QAAQ,EAAS,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EACV,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAGV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,aAAa,EAEb,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,iBAAiB,EAAe,MAAM,oBAAoB,CAAC;AAOzE,OAAO,KAAK,EAEV,aAAa,EAEb,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAkR7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;OASG;IACH,EAAE,CAAC,EAAE,cAAc,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAE7B;;OAEG;IACH,EAAE,CAAC,EAAE,wBAAwB,CAAC;IAE9B;;OAEG;IACH,EAAE,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC;IAEhC;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,aAAa,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC;IAExE;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,iCAAiC;QACjC,GAAG,CAAC,EAAE,SAAS,CAAC;QAChB,iCAAiC;QACjC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,QAAQ,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,iBAAiB,CAAC;IAElC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,iBAAiB,CAAC;IAClC,OAAO,CAAC,aAAa,CAAC,CAAS;IAE/B;;OAEG;IACH,SAAS,CAAC,UAAU,EAAG,MAAM,CAAC;IAE9B;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAEjC;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAuB;IAElD;;OAEG;IACH,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAE7C;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAwB;IAEhD;;OAEG;IACH,OAAO,CAAC,2BAA2B,CAAS;IAE5C;;OAEG;IACH,OAAO,CAAC,2BAA2B,CAAC,CAAgB;IAEpD;;OAEG;IACI,OAAO,EAAE,gBAAgB,CAAC;IAEjC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAoC;IAC3E,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAqB;IAEjE;;;;OAIG;gBACS,OAAO,GAAE,gBAAqB;IAK1C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,gBAAgB,IAAI,OAAO;IAIrC;;;;;;;;OAQG;cACa,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3C;;;;;;OAMG;cACa,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IA2GxD;;OAEG;cACa,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC;IA4G1D;;OAEG;cACa,gCAAgC,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjE;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAahD;;OAEG;cACa,mBAAmB,IAAI,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;YAKtD,4BAA4B;IA6B1C;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,kBAAkB;IAiDhC;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,sCAAsC;YAkCtC,yBAAyB;IAgCvC;;;OAGG;IACH,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAE1C;IAED;;;;;OAKG;IACH,SAAS,CAAC,qBAAqB,IAAI,MAAM,GAAG,SAAS;IAIrD;;;;;OAKG;YACW,iBAAiB;IAqB/B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;;OAIG;YACW,gBAAgB;IAuC9B;;OAEG;IACH,IAAI,EAAE,sBAEL;IAED;;OAEG;IACH,IAAI,EAAE,sBASL;IAED;;;;;;;;OAQG;IACG,YAAY,CAAC,CAAC,EAClB,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC;IAeb;;OAEG;IACH,IAAI,EAAE,aAEL;IAED;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS;IAIjD;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACG,WAAW,CACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAwD/B;;OAEG;IACG,gBAAgB,CACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAyExC;;;;OAIG;IACH,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAED;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,kBAAkB;IAsB1B,OAAO,CAAC,yBAAyB;YAkBnB,qBAAqB;IAwCnC,OAAO,CAAC,qBAAqB;CAoD9B"}

package/dist/class.js

@@ -480,6 +480,15 @@ var SmrtClass = class SmrtClass {
 		return this._db;
 	}
 	/**
+	* Return the database engine hint captured from the caller's configuration.
+	* Adapters may not expose their original type after construction (notably
+	* in-memory DuckDB/JSON connections), so query helpers can combine this
+	* hint with their public connection capabilities.
+	*/
+	getDatabaseEngineHint() {
+		return this._dbEngineHint;
+	}
+	/**
 	* Initialize signal bus and adapters
 	*
 	* Merges global configuration with instance-specific overrides.
@@ -572,6 +581,27 @@ var SmrtClass = class SmrtClass {
 		return this._db;
 	}
 	/**
+	* Temporarily bind this initialized instance to another database interface.
+	*
+	* This is intended for transaction-scoped work where a caller must ensure
+	* that every nested SMRT read and write uses the transaction database passed
+	* to its callback. The original database is restored whether the callback
+	* succeeds or throws. Do not use the same instance concurrently while it is
+	* temporarily bound.
+	*/
+	async withDatabase(db, operation) {
+		const previousDb = this.db;
+		const previousOptionDb = this.options.db;
+		this._db = db;
+		this.options.db = db;
+		try {
+			return await operation(this);
+		} finally {
+			this._db = previousDb;
+			this.options.db = previousOptionDb;
+		}
+	}
+	/**
 	* Gets the AI client instance
 	*/
 	get ai() {

package/dist/class.js.map

@@ -1 +1 @@
-{"version":3,"file":"class.js","names":[],"sources":["../src/class.ts"],"sourcesContent":["import type { AIClientOptions } from '@happyvertical/ai';\nimport { type AIClient, getAI } from '@happyvertical/ai';\nimport type {\n  FilesystemAdapter,\n  FilesystemAdapterOptions,\n} from '@happyvertical/files';\nimport { createLogger, type LoggerConfig } from '@happyvertical/logger';\nimport type {\n  AiTokenUsage,\n  AiUsageHandler,\n  AiUsageListOptions,\n  AiUsageSnapshot,\n  AiUsageStats,\n  AiUsageSummaryOptions,\n  SignalAdapter,\n  SmrtAiUsageEvent,\n  SmrtAiUsageRecord,\n} from '@happyvertical/smrt-types';\nimport { type DatabaseInterface, getDatabase } from '@happyvertical/sql';\nimport {\n  AiUsageCollector,\n  AiUsagePersistenceHandler,\n} from './adapters/ai-usage.js';\nimport { estimateAiUsageCost } from './adapters/cost-rates.js';\nimport { registerChangeFeedWriter } from './change-feed.js';\nimport type {\n  AIConfig,\n  AiUsageConfig,\n  GlobalSignalConfig,\n  MetricsConfig,\n  PubSubConfig,\n} from './config.js';\nimport { config } from './config.js';\nimport type { DatabaseConfig } from './database.js';\nimport { createFilesystemAdapter } from './filesystem-loader.js';\nimport { applyPostgresRuntimeTimeouts } from './postgres-timeouts.js';\nimport { detectEngine } from './schema/ddl/index.js';\nimport { SignalBus } from './signals/bus.js';\nimport { ensureSystemTables as ensureFrameworkSystemTables } from './system/bootstrap.js';\nimport {\n  ensureDeferredSystemTableCompatibility,\n  tableExists,\n} from './system/compatibility.js';\nimport { SMRT_SCHEMA_VERSION } from './system/schema.js';\nimport { toSafeInteger } from './utils/safe-integer.js';\n\n/**\n * `_smrt_migrations.version` suffix marking that the deferred (manifest-created)\n * system tables have been through their compatibility pass (issue #2376).\n */\nconst DEFERRED_COMPATIBILITY_VERSION_SUFFIX = '+deferred-compat';\n\nconst logger = createLogger({ level: 'info' });\n\ntype DatabaseWithConfig = DatabaseInterface & {\n  config?: {\n    type?: string;\n    url?: string;\n  };\n  type?: string;\n};\n\ninterface ResolvedAiUsageConfig {\n  enabled: boolean;\n  persist: boolean;\n  estimateCosts: boolean;\n  costRates?: Record<string, { input: number; output: number }>;\n  handlers: AiUsageHandler[];\n}\n\ntype AiUsageFilterOptions = Pick<\n  AiUsageListOptions,\n  | 'since'\n  | 'until'\n  | 'provider'\n  | 'model'\n  | 'operation'\n  | 'className'\n  | 'tenantId'\n>;\n\ninterface AiUsageWhereClause {\n  conditions: string[];\n  params: unknown[];\n  nextParamIndex: number;\n}\n\nfunction firstString(...candidates: unknown[]): string | undefined {\n  return candidates.find((candidate): candidate is string => {\n    return typeof candidate === 'string';\n  });\n}\n\nfunction firstNumber(...candidates: unknown[]): number | undefined {\n  return candidates.find((candidate): candidate is number => {\n    return typeof candidate === 'number';\n  });\n}\n\nfunction getDatabaseUrl(db: DatabaseInterface): string {\n  const dbWithConfig = db as DatabaseWithConfig;\n  return db.url || dbWithConfig.config?.url || '';\n}\n\nfunction getDatabaseTypeHint(\n  config: DatabaseConfig | undefined,\n): string | undefined {\n  if (!config || typeof config === 'string') {\n    return undefined;\n  }\n\n  const configWithType = config as DatabaseWithConfig & {\n    client?: unknown;\n  };\n\n  if (typeof configWithType.type === 'string') {\n    return configWithType.type;\n  }\n\n  if (typeof configWithType.config?.type === 'string') {\n    return configWithType.config.type;\n  }\n\n  if ('query' in configWithType && typeof configWithType.query === 'function') {\n    return undefined;\n  }\n\n  if ('client' in configWithType && configWithType.client) {\n    return 'postgres';\n  }\n\n  return undefined;\n}\n\nfunction normalizeIncomingAiUsageTokens(\n  value: unknown,\n): AiTokenUsage | undefined {\n  if (!value || typeof value !== 'object') {\n    return undefined;\n  }\n\n  const usage = value as Record<string, unknown>;\n  const promptTokens =\n    typeof usage.promptTokens === 'number'\n      ? usage.promptTokens\n      : typeof usage.inputTokens === 'number'\n        ? usage.inputTokens\n        : undefined;\n  const completionTokens =\n    typeof usage.completionTokens === 'number'\n      ? usage.completionTokens\n      : typeof usage.outputTokens === 'number'\n        ? usage.outputTokens\n        : undefined;\n  const totalTokens =\n    typeof usage.totalTokens === 'number'\n      ? usage.totalTokens\n      : promptTokens !== undefined || completionTokens !== undefined\n        ? (promptTokens ?? 0) + (completionTokens ?? 0)\n        : undefined;\n\n  if (\n    promptTokens === undefined &&\n    completionTokens === undefined &&\n    totalTokens === undefined\n  ) {\n    return undefined;\n  }\n\n  return {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n  };\n}\n\nfunction hydratePersistedAiUsageTokens(row: {\n  prompt_tokens?: unknown;\n  completion_tokens?: unknown;\n  total_tokens?: unknown;\n}): AiTokenUsage | undefined {\n  const promptTokens =\n    row.prompt_tokens === null || row.prompt_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.prompt_tokens, 'AI usage prompt tokens');\n  const completionTokens =\n    row.completion_tokens === null || row.completion_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.completion_tokens, 'AI usage completion tokens');\n  const totalTokens =\n    row.total_tokens === null || row.total_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.total_tokens, 'AI usage total tokens');\n\n  if (\n    promptTokens === undefined &&\n    completionTokens === undefined &&\n    totalTokens === undefined\n  ) {\n    return undefined;\n  }\n\n  return {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n  };\n}\n\nfunction normalizeAiUsageTags(\n  value: unknown,\n): Record<string, string> | undefined {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return undefined;\n  }\n\n  const tags: Record<string, string> = {};\n  for (const [key, tagValue] of Object.entries(value)) {\n    if (tagValue === undefined || tagValue === null) continue;\n    tags[key] = String(tagValue);\n  }\n\n  return Object.keys(tags).length > 0 ? tags : undefined;\n}\n\nfunction parseAiUsageTags(value: unknown): Record<string, string> | undefined {\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n\n  try {\n    return normalizeAiUsageTags(JSON.parse(value));\n  } catch {\n    return undefined;\n  }\n}\n\nfunction normalizeAiUsageTimestamp(value: unknown): Date {\n  if (value instanceof Date) {\n    return value;\n  }\n\n  if (typeof value === 'string' || typeof value === 'number') {\n    const date = new Date(value);\n    if (!Number.isNaN(date.getTime())) {\n      return date;\n    }\n  }\n\n  return new Date();\n}\n\nfunction getQueryRows(\n  result: Awaited<ReturnType<DatabaseInterface['query']>>,\n): Record<string, unknown>[] {\n  return Array.isArray(result)\n    ? (result as Record<string, unknown>[])\n    : ((result as { rows?: Record<string, unknown>[] }).rows ?? []);\n}\n\nfunction buildAiUsageWhereClause(\n  options: AiUsageFilterOptions,\n): AiUsageWhereClause {\n  const conditions: string[] = [];\n  const params: unknown[] = [];\n  let nextParamIndex = 1;\n\n  if (options.since) {\n    conditions.push(`created_at >= $${nextParamIndex++}`);\n    params.push(options.since.toISOString());\n  }\n\n  if (options.until) {\n    conditions.push(`created_at <= $${nextParamIndex++}`);\n    params.push(options.until.toISOString());\n  }\n\n  if (options.provider) {\n    conditions.push(`provider = $${nextParamIndex++}`);\n    params.push(options.provider);\n  }\n\n  if (options.model) {\n    conditions.push(`model = $${nextParamIndex++}`);\n    params.push(options.model);\n  }\n\n  if (options.operation) {\n    conditions.push(`operation = $${nextParamIndex++}`);\n    params.push(options.operation);\n  }\n\n  if (options.className) {\n    conditions.push(`class_name = $${nextParamIndex++}`);\n    params.push(options.className);\n  }\n\n  if (options.tenantId === null) {\n    conditions.push(`tenant_id IS NULL`);\n  } else if (options.tenantId) {\n    conditions.push(`tenant_id = $${nextParamIndex++}`);\n    params.push(options.tenantId);\n  }\n\n  return {\n    conditions,\n    params,\n    nextParamIndex,\n  };\n}\n\n/**\n * Configuration options for the SmrtClass\n */\nexport interface SmrtClassOptions {\n  /**\n   * Optional custom class name override\n   */\n  _className?: string;\n\n  /**\n   * Database configuration - unified approach matching @happyvertical/sql\n   *\n   * Supports three formats:\n   * - String shortcut: 'products.db' (auto-detects database type)\n   * - Config object: { type: 'sqlite', url: 'products.db' }\n   * - DatabaseInterface instance: await getDatabase(...)\n   *\n   * @see DatabaseConfig for type definition\n   */\n  db?: DatabaseConfig;\n\n  /**\n   * Alias for db option - for backward compatibility with documentation\n   *\n   * @deprecated Use 'db' instead. This alias exists for backward compatibility.\n   */\n  persistence?: DatabaseConfig;\n\n  /**\n   * Filesystem adapter configuration options\n   */\n  fs?: FilesystemAdapterOptions;\n\n  /**\n   * AI client configuration options or instance\n   */\n  ai?: AIClientOptions | AIClient;\n\n  /**\n   * AI usage tracking configuration (overrides global defaults)\n   */\n  usage?: AiUsageConfig;\n\n  /**\n   * Logging configuration (overrides global default)\n   */\n  logging?: LoggerConfig;\n\n  /**\n   * Metrics configuration (overrides global default)\n   */\n  metrics?: MetricsConfig;\n\n  /**\n   * Pub/Sub configuration (overrides global default)\n   */\n  pubsub?: PubSubConfig;\n\n  /**\n   * Sanitization configuration (overrides global default)\n   */\n  sanitization?: import('./config.js').GlobalSignalConfig['sanitization'];\n\n  /**\n   * Custom signal configuration (overrides global default)\n   */\n  signals?: {\n    /** Shared signal bus instance */\n    bus?: SignalBus;\n    /** Additional custom adapters */\n    adapters?: SignalAdapter[];\n  };\n\n  /**\n   * Internal flag to reuse an already initialized DatabaseInterface instance.\n   *\n   * Skips database resolution and system-table setup during lightweight hydration.\n   * @internal\n   */\n  _reuseInitializedDb?: boolean;\n\n  /**\n   * Internal flag to defer runtime-only services such as signals and AI setup.\n   *\n   * Lightweight hydration paths set this so plain query reads avoid per-row\n   * runtime bootstrap costs.\n   * @internal\n   */\n  _deferRuntimeInitialization?: boolean;\n}\n\n/**\n * Foundation class providing core functionality for the SMRT framework\n *\n * SmrtClass provides unified access to database, filesystem, and AI client\n * interfaces. It serves as the foundation for all other classes in the\n * SMRT framework.\n */\nexport class SmrtClass {\n  /**\n   * AI client instance for interacting with AI models\n   */\n  protected _ai!: AIClient;\n\n  /**\n   * Filesystem adapter for file operations\n   */\n  protected _fs!: FilesystemAdapter;\n\n  /**\n   * Database interface for data persistence\n   */\n  protected _db!: DatabaseInterface;\n  private _dbEngineHint?: string;\n\n  /**\n   * Class name used for identification\n   */\n  protected _className!: string;\n\n  /**\n   * Signal bus for method execution tracking\n   */\n  protected _signalBus?: SignalBus;\n\n  /**\n   * Adapters registered by this instance (for cleanup)\n   */\n  private _registeredAdapters: SignalAdapter[] = [];\n\n  /**\n   * In-memory AI usage collector for quick inspection.\n   */\n  private _aiUsageCollector?: AiUsageCollector;\n\n  /**\n   * Registered AI usage handlers for this instance.\n   */\n  private _aiUsageHandlers: AiUsageHandler[] = [];\n\n  /**\n   * Tracks whether optional runtime services (signals, AI, fs) are ready.\n   */\n  private _runtimeServicesInitialized = false;\n\n  /**\n   * Shared in-flight runtime initialization promise for single-flight setup.\n   */\n  private _runtimeServicesInitPromise?: Promise<void>;\n\n  /**\n   * Configuration options provided to the class\n   */\n  public options: SmrtClassOptions;\n\n  /**\n   * Track which databases have had system tables initialized\n   * - WeakSet for :memory: databases (URL not unique, track by instance)\n   * - Set<string> for all others (URL is unique identifier)\n   */\n  private static _systemTablesInitialized = new WeakSet<DatabaseInterface>();\n  private static _systemTablesInitializedByUrl = new Set<string>();\n\n  /**\n   * Creates a new SmrtClass instance\n   *\n   * @param options - Configuration options for database, filesystem, and AI clients\n   */\n  constructor(options: SmrtClassOptions = {}) {\n    this.options = options;\n    this._className = this.constructor.name;\n  }\n\n  /**\n   * Determines whether this class requires a database to function\n   *\n   * Override this method in subclasses that require database access\n   * to enable early validation during initialization.\n   *\n   * @returns True if database is required, false otherwise\n   * @example\n   * ```typescript\n   * class MyDataModel extends SmrtClass {\n   *   protected requiresDatabase(): boolean {\n   *     return true; // This class needs database access\n   *   }\n   * }\n   * ```\n   */\n  protected requiresDatabase(): boolean {\n    return false; // Base class doesn't require database by default\n  }\n\n  /**\n   * Initializes database, filesystem, and AI client connections\n   *\n   * This method sets up all required services based on the provided options.\n   * It should be called before using any of the service interfaces.\n   *\n   * @returns Promise that resolves to this instance for chaining\n   * @throws {Error} If database is required but not provided in options\n   */\n  protected async initialize(): Promise<this> {\n    await this.initializeCoreResources();\n\n    if (!this.options._deferRuntimeInitialization) {\n      await this.initializeRuntimeServices();\n    }\n\n    return this;\n  }\n\n  /**\n   * Initialize core resources required for ORM behavior.\n   *\n   * This setup is shared by both full runtime initialization and lightweight\n   * query hydration. Hydrated objects reuse an existing DB connection and skip\n   * repeated system-table checks.\n   */\n  protected async initializeCoreResources(): Promise<void> {\n    // Framework init hook for the change feed (#1758): make sure the writer\n    // interceptor observes every save/delete before any instance can write.\n    // Idempotent and cheap when already registered.\n    registerChangeFeedWriter();\n\n    // Map persistence to db for backward compatibility\n    if (this.options.persistence && !this.options.db) {\n      this.options.db = this.options.persistence;\n    }\n\n    // Validate database configuration if required\n    if (this.requiresDatabase() && !this.options.db) {\n      throw new Error(\n        `${this._className} requires a database configuration. ` +\n          `Please provide 'db' in options: { db: { url: '...' } } or { db: 'database.db' }`,\n      );\n    }\n\n    if (this.options.db) {\n      this._dbEngineHint = getDatabaseTypeHint(this.options.db);\n\n      if (\n        this.options._reuseInitializedDb &&\n        typeof this.options.db === 'object' &&\n        'query' in this.options.db\n      ) {\n        this._db = this.options.db as DatabaseInterface;\n        this.options.db = this._db;\n      } else {\n        // Handle four db config formats (in implementation order):\n        // 1. String URL: 'products.db' (shortcut)\n        // 2. DatabaseInterface instance: already initialized db (has 'query' method)\n        // 3. Config with client: { type: 'postgres', client: pgPool } (SvelteKit pattern)\n        // 4. Config object: { type: 'sqlite', url: 'products.db' }\n        if (typeof this.options.db === 'string') {\n          // Format 1: String shortcut - let getDatabase auto-detect type from URL\n          // Preserve connection sharing for file-backed databases while leaving\n          // true in-memory databases isolated per instance.\n          const isMemoryDb = this.options.db === ':memory:';\n          // PostgreSQL URLs pick up the runtime timeout bounds, and the dbid is\n          // derived from the bounded URL so the same rewrite at every call site\n          // still resolves to one shared pool (#2377).\n          const bounded = applyPostgresRuntimeTimeouts({\n            url: this.options.db,\n          });\n          this._db = await getDatabase({\n            ...bounded,\n            ...(isMemoryDb ? {} : { dbid: `smrt:${bounded.url}` }),\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        } else if ('query' in this.options.db) {\n          // Format 2: Already a DatabaseInterface instance - return as-is\n          this._db = this.options.db as DatabaseInterface;\n        } else if ('client' in this.options.db && this.options.db.client) {\n          // Format 3: Config with pre-created client (e.g., from SvelteKit's $env-based connection)\n          // Pass the client to getDatabase which will use it instead of creating a new connection\n          const dbConfig = this.options.db as {\n            type?: string;\n            client: unknown;\n            url?: string;\n          };\n          // `client` is a runtime-only property the postgres adapter reads\n          // but the public `getDatabase` option union does not model, so the\n          // literal is routed through the function's own parameter type.\n          this._db = await getDatabase({\n            type: dbConfig.type || 'postgres',\n            client: dbConfig.client,\n            url: dbConfig.url,\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        } else {\n          // Format 4: Config object - pass to getDatabase (handles all types uniformly)\n          // Preserve connection sharing for file-backed databases while leaving\n          // true in-memory databases isolated per instance.\n          const dbConfig = this.options.db as { url?: string; type?: string };\n          const dbUrl = dbConfig.url || 'memory';\n          const isMemoryDb = dbUrl === ':memory:' || dbUrl === 'memory';\n          // Keep the config's own key set: an object with no `url` must stay\n          // that way so the adapter applies its own default (#2377).\n          const bounded = applyPostgresRuntimeTimeouts({ ...this.options.db });\n          // The loose config-object variant of `DatabaseConfig` carries an\n          // index signature that the closed `getDatabase` option union does\n          // not accept structurally, so route through its parameter type.\n          this._db = await getDatabase({\n            ...bounded,\n            ...(isMemoryDb ? {} : { dbid: `smrt:${bounded.url ?? dbUrl}` }),\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        }\n\n        /**\n         * INTENTIONAL MUTATION: After resolving the database config,\n         * we replace options.db with the actual DatabaseInterface instance.\n         * This enables child objects to share the same connection via:\n         *\n         *   const child = new ChildObject({ db: parent.options.db });\n         *\n         * Without this, passing this.options to getCollection() would use the config object\n         * which causes a NEW db instance to be created, losing data isolation.\n         *\n         * See issue #567 for context on why this pattern is necessary.\n         */\n        this.options.db = this._db;\n\n        await this.ensureSystemTables();\n      }\n    }\n  }\n\n  /**\n   * Initialize optional runtime services that are not required for plain ORM reads.\n   */\n  protected async initializeRuntimeServices(): Promise<void> {\n    if (this._runtimeServicesInitialized) {\n      return;\n    }\n\n    if (!this._runtimeServicesInitPromise) {\n      this._runtimeServicesInitPromise = (async () => {\n        if (this.options.fs && !this._fs) {\n          // Acquired through the boundary in filesystem-loader.ts so the\n          // @happyvertical/files SDK (S3/googleapis) never enters\n          // provider-neutral consumer bundles (#1977/#1979).\n          this._fs = await createFilesystemAdapter(this.options.fs);\n        }\n\n        // Initialize AI client with environment variable support\n        // Priority: instance options > env vars > global config > defaults\n        const globalConfig = config.toJSON();\n        const usageConfig = this.mergeAiUsageConfig(globalConfig);\n        this.initializeAiUsageHandlers(usageConfig);\n\n        if (\n          !this._ai &&\n          (this.options.ai || globalConfig.ai || process.env.SMRT_AI_PROVIDER)\n        ) {\n          // Check if options.ai is already a client-like object with embed method\n          // This allows passing mock AI clients for testing\n          const aiOption = this.options.ai as\n            | Record<string, unknown>\n            | undefined;\n          if (\n            aiOption &&\n            typeof aiOption === 'object' &&\n            typeof aiOption.embed === 'function' &&\n            !aiOption.provider\n          ) {\n            this._ai = aiOption as unknown as AIClient;\n          } else {\n            // CC-8 follow-up: ideally this would route through\n            // `@happyvertical/smrt-config` for sanitization parity (e.g. via\n            // `getPackageConfig('ai', ...)`), but smrt-config currently only\n            // merges file-based config + runtime overrides — it does NOT\n            // read from `process.env` with a typed prefix/schema. Until\n            // smrt-config grows an env-loader (or wraps `loadEnvConfig`),\n            // we continue to use the underlying utility directly. Tracked\n            // alongside the CC-8 audit on issue #1199.\n            const { loadEnvConfig } = await import('@happyvertical/utils');\n\n            // Start with global defaults\n            const baseConfig = globalConfig.ai || {};\n\n            // Merge with instance options (takes priority over global)\n            const userConfig = { ...baseConfig, ...this.options.ai };\n\n            // Load environment variables and merge (user options take priority).\n            // `AIConfig` carries an index signature, so provider-specific keys\n            // (`type`, `onUsage`, `defaultModel`, …) read back as `unknown`.\n            const aiConfig = loadEnvConfig<AIConfig>(userConfig, {\n              packageName: 'ai',\n              prefix: 'SMRT',\n              schema: {\n                provider: 'string',\n                model: 'string',\n                apiKey: 'string',\n                timeout: 'number',\n                maxRetries: 'number',\n                temperature: 'number',\n                maxTokens: 'number',\n              },\n            });\n\n            const existingOnUsage =\n              aiConfig.onUsage ??\n              (userConfig as Record<string, unknown>).onUsage ??\n              undefined;\n            aiConfig.onUsage = async (event: unknown) => {\n              if (typeof existingOnUsage === 'function') {\n                await (existingOnUsage as (usageEvent: unknown) => unknown)(\n                  event,\n                );\n              }\n              await this.handleAiUsageCallback(event, aiConfig, usageConfig);\n            };\n\n            // Only initialize if we have a provider configured\n            if (aiConfig.provider || aiConfig.type || aiConfig.apiKey) {\n              // Use getAI() factory to support all AI providers (OpenAI, Anthropic, Gemini, etc.)\n              // getAI() returns AIInterface, which we narrow to AIClient for\n              // backward compatibility. The index-signature `AIConfig` is routed\n              // through getAI's own parameter type rather than the closed union.\n              this._ai = (await getAI(\n                aiConfig as unknown as Parameters<typeof getAI>[0],\n              )) as unknown as AIClient;\n            }\n          }\n        }\n\n        await this.initializeSignals();\n        this._runtimeServicesInitialized = true;\n      })();\n    }\n\n    try {\n      await this._runtimeServicesInitPromise;\n    } finally {\n      this._runtimeServicesInitPromise = undefined;\n    }\n  }\n\n  /**\n   * Ensure deferred runtime services are ready before using them.\n   */\n  protected async ensureRuntimeServicesInitialized(): Promise<void> {\n    if (!this._runtimeServicesInitialized) {\n      await this.initializeRuntimeServices();\n    }\n  }\n\n  /**\n   * Resolve the AI client, initializing deferred runtime services on demand.\n   */\n  protected async getAiClient(): Promise<AIClient> {\n    await this.ensureRuntimeServicesInitialized();\n\n    if (!this._ai) {\n      throw new Error(\n        `${this._className} does not have an AI client configured. ` +\n          `Provide 'ai' in options or configure a global SMRT AI provider.`,\n      );\n    }\n\n    return this._ai;\n  }\n\n  /**\n   * Resolve the AI client if one is configured, otherwise return undefined.\n   */\n  protected async getOptionalAiClient(): Promise<AIClient | undefined> {\n    await this.ensureRuntimeServicesInitialized();\n    return this._ai;\n  }\n\n  private async isSystemSchemaVersionApplied(\n    db: DatabaseInterface,\n    version: string,\n  ): Promise<boolean> {\n    const engine = detectEngine(getDatabaseUrl(db), this._dbEngineHint);\n\n    if (\n      engine === 'postgres' &&\n      !(await tableExists(db, '_smrt_migrations', this._dbEngineHint))\n    ) {\n      return false;\n    }\n\n    try {\n      const versionParam = engine === 'postgres' ? '$1' : '?';\n      const rows = await db.query(\n        `SELECT 1 FROM _smrt_migrations WHERE version = ${versionParam} LIMIT 1`,\n        version,\n      );\n      return getQueryRows(rows).length > 0;\n    } catch (error) {\n      if (engine === 'postgres') {\n        throw error;\n      }\n\n      return false;\n    }\n  }\n\n  /**\n   * Ensure SMRT system tables exist in the database\n   *\n   * System tables use the _smrt_ prefix and store framework metadata:\n   * - _smrt_contexts: Context memory storage for remembered patterns\n   * - _smrt_migrations: Schema version tracking\n   * - _smrt_schema_migrations / _smrt_backfills: Migration and backfill ledgers\n   * - _smrt_embeddings: Embedding vectors for semantic search\n   * - _smrt_dispatch / _smrt_dispatch_subscriptions: Inter-agent dispatch queue\n   * - _smrt_ai_usage: AI usage telemetry\n   * - _smrt_changes: Append-only change feed\n   *\n   * Note that the _smrt_ prefix alone does NOT mean \"system table\" — ~25\n   * `@smrt()` domain tables (feature flags, prompt overrides, subscription\n   * plans, …) carry it too and are created by `db:migrate`, not here. The\n   * framework's own list is `SYSTEM_TABLE_NAMES` in\n   * `schema/system-table-shapes.ts`, derived from this DDL.\n   *\n   * This method is idempotent and safe to call multiple times.\n   * Tables are only created once per database connection.\n   */\n  private async ensureSystemTables(): Promise<void> {\n    if (!this._db) return;\n\n    const dbUrl = getDatabaseUrl(this._db);\n\n    // Some databases share URLs but are different instances:\n    // - :memory: databases (SQLite/DuckDB in-memory)\n    // - JSON databases (may have undefined or shared URLs)\n    // - Any database with undefined URL\n    // Use WeakSet for instance tracking, Set<string> for URL tracking\n    const dbConstructorName = this._db.constructor?.name || '';\n    const isMemoryDb = dbUrl === ':memory:';\n    const isJsonDb = dbConstructorName.toLowerCase().includes('json');\n    const hasUndefinedUrl = !dbUrl;\n    const useInstanceTracking = isMemoryDb || isJsonDb || hasUndefinedUrl;\n\n    if (useInstanceTracking) {\n      // Check WeakSet for databases that may share URLs (track by instance)\n      if (SmrtClass._systemTablesInitialized.has(this._db)) {\n        return;\n      }\n    } else {\n      // Check Set<string> for URL-based databases (track by URL)\n      if (SmrtClass._systemTablesInitializedByUrl.has(dbUrl)) {\n        return;\n      }\n    }\n\n    try {\n      await ensureFrameworkSystemTables(this._db, this._dbEngineHint);\n      await this.settleDeferredSystemTableCompatibility(this._db);\n      await this.ensureNativeVectorStorage();\n\n      // Mark as initialized using appropriate tracking mechanism\n      if (useInstanceTracking) {\n        SmrtClass._systemTablesInitialized.add(this._db);\n      } else {\n        SmrtClass._systemTablesInitializedByUrl.add(dbUrl);\n      }\n    } catch (error) {\n      // DO NOT SWALLOW ERRORS - fail loudly so we know what's wrong\n      const dbInfo = this._db.constructor?.name || 'unknown database';\n      throw new Error(\n        `Failed to create system tables for ${dbInfo}: ${error instanceof Error ? error.message : String(error)}`,\n        { cause: error },\n      );\n    }\n  }\n\n  /**\n   * Run the compatibility pass for the system tables `db:migrate` creates, then\n   * stamp its own marker in `_smrt_migrations` (issue #2376).\n   *\n   * Deliberately runs OUTSIDE the bootstrap lock/transaction, and deliberately\n   * cannot fail startup:\n   *\n   * - `_smrt_jobs` / `_smrt_job_events` are created by `db:migrate` from the\n   *   jobs manifest, which on a fresh install runs AFTER the framework's first\n   *   bootstrap. Gating this pass on {@link SMRT_SCHEMA_VERSION} would mean the\n   *   version gets stamped while the tables are still absent and the pass never\n   *   runs on that database again. It therefore carries its own marker, which\n   *   is written only once every deferred table exists and has been upgraded.\n   * - Its statements are ALTER TABLE / CREATE INDEX against tables the\n   *   framework does not own. Inside the PostgreSQL bootstrap transaction one\n   *   failure (a permissions problem, say) would abort the transaction and roll\n   *   back system-table creation with it. Outside, a failure is a logged\n   *   warning and the next process start retries — the pass is idempotent and\n   *   already tolerates concurrent creators.\n   *\n   * Until the tables exist this costs two catalog probes per process per\n   * database; afterwards the marker short-circuits it.\n   */\n  private async settleDeferredSystemTableCompatibility(\n    db: DatabaseInterface,\n  ): Promise<void> {\n    const marker = `${SMRT_SCHEMA_VERSION}${DEFERRED_COMPATIBILITY_VERSION_SUFFIX}`;\n\n    try {\n      if (await this.isSystemSchemaVersionApplied(db, marker)) {\n        return;\n      }\n\n      const { settled } = await ensureDeferredSystemTableCompatibility(\n        db,\n        this._dbEngineHint,\n      );\n      if (!settled) {\n        return;\n      }\n\n      const id = crypto.randomUUID();\n      const description = 'Deferred SMRT system table compatibility';\n      await db.execute`\n        INSERT INTO _smrt_migrations (id, version, description)\n        VALUES (${id}, ${marker}, ${description})\n        ON CONFLICT(version) DO NOTHING\n      `;\n    } catch (error) {\n      logger.warn(\n        `[smrt] Deferred system table compatibility did not complete; retrying on the next start: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n      );\n    }\n  }\n\n  private async ensureNativeVectorStorage(): Promise<void> {\n    if (!this._db) {\n      return;\n    }\n\n    try {\n      const { ObjectRegistry } = await import('./registry.js');\n      const embeddingConfig = ObjectRegistry.getProjectEmbeddingConfig();\n      if (embeddingConfig?.storage === 'native') {\n        const { EmbeddingStorage } = await import('./embeddings/storage.js');\n        const vector = this._db.vector;\n        if (vector) {\n          const dimensions = embeddingConfig.dimensions || 768;\n          await EmbeddingStorage.ensureVectorStorage(\n            this._db,\n            dimensions,\n            vector,\n          );\n        } else {\n          logger.warn(\n            '[smrt] Embedding storage set to \"native\" but database has no vector capability. Falling back to JSON storage.',\n          );\n        }\n      }\n    } catch (error) {\n      // Don't fail system table initialization for vector setup errors\n      logger.warn(\n        `[smrt] Failed to initialize vector storage: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  /**\n   * Access system tables through standard database interface\n   * System tables use _smrt_ prefix to avoid conflicts with user tables\n   */\n  protected get systemDb(): DatabaseInterface {\n    return this._db;\n  }\n\n  /**\n   * Initialize signal bus and adapters\n   *\n   * Merges global configuration with instance-specific overrides.\n   * Registers built-in and custom adapters based on configuration.\n   */\n  private async initializeSignals(): Promise<void> {\n    const globalConfig = config.toJSON();\n    const effectiveConfig = this.mergeSignalConfig(globalConfig);\n\n    // If a shared bus is provided, always use it (don't create new adapters)\n    if (this.options.signals?.bus) {\n      this._signalBus = this.options.signals.bus;\n      return;\n    }\n\n    // Otherwise, check if we should initialize signals based on config\n    if (!this.shouldInitializeSignals(effectiveConfig)) {\n      return;\n    }\n\n    this._signalBus = new SignalBus({\n      sanitization: effectiveConfig.sanitization,\n    });\n    await this.registerAdapters(effectiveConfig);\n  }\n\n  /**\n   * Merge global and instance signal configuration\n   *\n   * Instance configuration takes priority over global defaults.\n   *\n   * @param globalConfig - Global configuration from smrt.configure()\n   * @returns Merged configuration\n   */\n  private mergeSignalConfig(\n    globalConfig: GlobalSignalConfig,\n  ): GlobalSignalConfig {\n    return {\n      logging: this.options.logging ?? globalConfig.logging,\n      metrics: this.options.metrics ?? globalConfig.metrics,\n      pubsub: this.options.pubsub ?? globalConfig.pubsub,\n      usage: this.mergeAiUsageConfig(globalConfig),\n      sanitization: this.options.sanitization ?? globalConfig.sanitization,\n      signals: {\n        bus: this.options.signals?.bus ?? globalConfig.signals?.bus,\n        adapters: [\n          ...(globalConfig.signals?.adapters ?? []),\n          ...(this.options.signals?.adapters ?? []),\n        ],\n      },\n    };\n  }\n\n  /**\n   * Check if signals should be initialized\n   *\n   * Signals are initialized if any adapter is configured.\n   *\n   * @param config - Effective signal configuration\n   * @returns True if signals should be initialized\n   */\n  private shouldInitializeSignals(config: GlobalSignalConfig): boolean {\n    return !!(\n      config.logging !== false ||\n      config.metrics?.enabled ||\n      config.pubsub?.enabled ||\n      config.signals?.adapters?.length\n    );\n  }\n\n  /**\n   * Register signal adapters based on configuration\n   *\n   * @param config - Effective signal configuration\n   */\n  private async registerAdapters(config: GlobalSignalConfig): Promise<void> {\n    if (!this._signalBus) return;\n\n    // Logging adapter (default: enabled with console)\n    if (config.logging !== false) {\n      const { createLogger, LoggerAdapter } = await import(\n        '@happyvertical/logger'\n      );\n      const logger = createLogger(config.logging ?? true);\n      const adapter = new LoggerAdapter(logger);\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Metrics adapter (default: disabled)\n    if (config.metrics?.enabled) {\n      const { MetricsAdapter } = await import('./adapters/metrics.js');\n      const adapter = new MetricsAdapter();\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Pub/Sub adapter (default: disabled)\n    if (config.pubsub?.enabled) {\n      const { PubSubAdapter } = await import('./adapters/pubsub.js');\n      const adapter = new PubSubAdapter();\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Custom adapters\n    if (config.signals?.adapters) {\n      for (const adapter of config.signals.adapters) {\n        this._signalBus.register(adapter);\n        this._registeredAdapters.push(adapter);\n      }\n    }\n  }\n\n  /**\n   * Gets the filesystem adapter instance\n   */\n  get fs() {\n    return this._fs;\n  }\n\n  /**\n   * Gets the database interface instance\n   */\n  get db() {\n    // Throw helpful error if database is accessed before initialization\n    if (!this._db) {\n      throw new Error(\n        `Database accessed before initialization. ` +\n          `Please call await instance.initialize() before accessing the database.`,\n      );\n    }\n    return this._db;\n  }\n\n  /**\n   * Gets the AI client instance\n   */\n  get ai() {\n    return this._ai;\n  }\n\n  /**\n   * Get the in-memory AI usage snapshot for this instance.\n   */\n  getAiUsageSnapshot(): AiUsageSnapshot | undefined {\n    return this._aiUsageCollector?.getSnapshot();\n  }\n\n  /**\n   * Reset the in-memory AI usage collector.\n   */\n  resetAiUsage(): void {\n    this._aiUsageCollector?.reset();\n  }\n\n  /**\n   * List persisted AI usage records.\n   */\n  async listAiUsage(\n    options: AiUsageListOptions = {},\n  ): Promise<SmrtAiUsageRecord[]> {\n    if (!this._db) {\n      throw new Error(\n        `AI usage requires a database configuration. ` +\n          `Please call initialize() with a db option before querying usage.`,\n      );\n    }\n\n    const { conditions, params } = buildAiUsageWhereClause(options);\n    let paramIndex = params.length + 1;\n\n    let sql = 'SELECT * FROM _smrt_ai_usage';\n    if (conditions.length > 0) {\n      sql += ` WHERE ${conditions.join(' AND ')}`;\n    }\n\n    sql += ` ORDER BY ${\n      options.orderBy === 'timestamp ASC' ? 'created_at ASC' : 'created_at DESC'\n    }`;\n\n    if (options.limit !== undefined) {\n      sql += ` LIMIT $${paramIndex++}`;\n      params.push(options.limit);\n    }\n\n    if (options.offset !== undefined) {\n      sql += ` OFFSET $${paramIndex++}`;\n      params.push(options.offset);\n    }\n\n    const rows = getQueryRows(await this._db.query(sql, ...params));\n\n    return rows.map((row) => ({\n      id: String(row.id),\n      provider: String(row.provider),\n      model: String(row.model),\n      operation: String(row.operation),\n      usage: hydratePersistedAiUsageTokens(row),\n      estimatedCost:\n        row.estimated_cost === null || row.estimated_cost === undefined\n          ? undefined\n          : Number(row.estimated_cost),\n      duration: toSafeInteger(row.duration ?? 0, 'AI usage duration'),\n      className:\n        row.class_name === null || row.class_name === undefined\n          ? undefined\n          : String(row.class_name),\n      tenantId:\n        row.tenant_id === undefined\n          ? undefined\n          : (row.tenant_id as string | null),\n      tags: parseAiUsageTags(row.tags),\n      timestamp: normalizeAiUsageTimestamp(row.created_at),\n    }));\n  }\n\n  /**\n   * Summarize persisted AI usage records by a grouping dimension.\n   */\n  async summarizeAiUsage(\n    options: AiUsageSummaryOptions = {},\n  ): Promise<Record<string, AiUsageStats>> {\n    if (!this._db) {\n      throw new Error(\n        `AI usage requires a database configuration. ` +\n          `Please call initialize() with a db option before querying usage.`,\n      );\n    }\n\n    const groupBy = options.groupBy ?? 'model';\n    const bucketExpression =\n      groupBy === 'provider'\n        ? `provider`\n        : groupBy === 'model'\n          ? `provider || ':' || model`\n          : groupBy === 'class'\n            ? `COALESCE(class_name, 'unknown')`\n            : groupBy === 'tenant'\n              ? `COALESCE(tenant_id, 'global')`\n              : groupBy === 'operation'\n                ? `operation`\n                : `substr(CAST(created_at AS TEXT), 1, 10)`;\n\n    const { conditions, params } = buildAiUsageWhereClause(options);\n\n    let sql = `\n      SELECT ${bucketExpression} AS bucket,\n             COUNT(*) AS call_count,\n             COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,\n             COALESCE(SUM(completion_tokens), 0) AS completion_tokens,\n             COALESCE(SUM(total_tokens), 0) AS total_tokens,\n             COALESCE(SUM(duration), 0) AS total_duration,\n             COALESCE(SUM(estimated_cost), 0) AS estimated_cost,\n             MAX(created_at) AS last_used\n      FROM _smrt_ai_usage\n    `;\n\n    if (conditions.length > 0) {\n      sql += ` WHERE ${conditions.join(' AND ')}`;\n    }\n\n    sql += ' GROUP BY bucket ORDER BY bucket ASC';\n\n    const rows = getQueryRows(await this._db.query(sql, ...params));\n    const summary: Record<string, AiUsageStats> = {};\n\n    for (const row of rows) {\n      const bucket = String(row.bucket);\n      summary[bucket] = {\n        callCount: toSafeInteger(row.call_count ?? 0, 'AI usage call count'),\n        promptTokens: toSafeInteger(\n          row.prompt_tokens ?? 0,\n          'AI usage prompt-token total',\n        ),\n        completionTokens: toSafeInteger(\n          row.completion_tokens ?? 0,\n          'AI usage completion-token total',\n        ),\n        totalTokens: toSafeInteger(\n          row.total_tokens ?? 0,\n          'AI usage token total',\n        ),\n        totalDuration: toSafeInteger(\n          row.total_duration ?? 0,\n          'AI usage duration total',\n        ),\n        estimatedCost: Number(row.estimated_cost ?? 0),\n        lastUsed: row.last_used ? new Date(String(row.last_used)).getTime() : 0,\n      };\n    }\n\n    return summary;\n  }\n\n  /**\n   * Gets the signal bus instance\n   *\n   * @returns Signal bus if signals are enabled, undefined otherwise\n   */\n  get signalBus(): SignalBus | undefined {\n    return this._signalBus;\n  }\n\n  /**\n   * Cleanup method to prevent memory leaks\n   *\n   * Unregisters all adapters from the signal bus that were registered\n   * by this instance. Call this when the SmrtClass instance is no longer\n   * needed to prevent memory leaks.\n   *\n   * @example\n   * ```typescript\n   * const product = new Product({ name: 'Widget' });\n   * await product.initialize();\n   * // ... use product ...\n   * product.destroy(); // Clean up when done\n   * ```\n   */\n  destroy(): void {\n    // Only unregister adapters if we own the bus (not shared)\n    if (this._signalBus && !this.options.signals?.bus) {\n      for (const adapter of this._registeredAdapters) {\n        this._signalBus.unregister(adapter);\n      }\n      this._registeredAdapters = [];\n    }\n\n    // TODO: If SmrtClass grows a broader async teardown lifecycle, move\n    // AI usage handler cleanup there alongside other connection-bound state.\n    this._aiUsageCollector = undefined;\n    this._aiUsageHandlers = [];\n  }\n\n  private mergeAiUsageConfig(\n    globalConfig: GlobalSignalConfig,\n  ): ResolvedAiUsageConfig {\n    const globalUsage = globalConfig.usage ?? {};\n    const instanceUsage = this.options.usage ?? {};\n\n    return {\n      enabled: instanceUsage.enabled ?? globalUsage.enabled ?? true,\n      persist: instanceUsage.persist ?? globalUsage.persist ?? true,\n      estimateCosts:\n        instanceUsage.estimateCosts ?? globalUsage.estimateCosts ?? true,\n      costRates: {\n        ...(globalUsage.costRates ?? {}),\n        ...(instanceUsage.costRates ?? {}),\n      },\n      handlers: [\n        ...(globalUsage.handlers ?? []),\n        ...(instanceUsage.handlers ?? []),\n      ],\n    };\n  }\n\n  private initializeAiUsageHandlers(config: ResolvedAiUsageConfig): void {\n    this._aiUsageCollector = undefined;\n    this._aiUsageHandlers = [];\n\n    if (!config.enabled) {\n      return;\n    }\n\n    this._aiUsageCollector = new AiUsageCollector();\n    this._aiUsageHandlers.push(this._aiUsageCollector);\n\n    if (config.persist && this._db) {\n      this._aiUsageHandlers.push(new AiUsagePersistenceHandler(this._db));\n    }\n\n    this._aiUsageHandlers.push(...config.handlers);\n  }\n\n  private async handleAiUsageCallback(\n    event: unknown,\n    aiConfig: Record<string, unknown>,\n    usageConfig: ResolvedAiUsageConfig,\n  ): Promise<void> {\n    if (!usageConfig.enabled || this._aiUsageHandlers.length === 0) {\n      return;\n    }\n\n    const normalizedEvent = this.normalizeAiUsageEvent(event, aiConfig);\n    if (!normalizedEvent) {\n      return;\n    }\n\n    if (usageConfig.estimateCosts) {\n      normalizedEvent.estimatedCost = estimateAiUsageCost(\n        normalizedEvent.provider,\n        normalizedEvent.model,\n        normalizedEvent.usage,\n        usageConfig.costRates,\n      );\n    }\n\n    const results = await Promise.allSettled(\n      this._aiUsageHandlers.map((handler) => handler.handle(normalizedEvent)),\n    );\n\n    for (const result of results) {\n      if (result.status === 'rejected') {\n        logger.warn(\n          `[smrt] AI usage handler failed for ${normalizedEvent.provider}:${normalizedEvent.model}: ${\n            result.reason instanceof Error\n              ? result.reason.message\n              : String(result.reason)\n          }`,\n        );\n      }\n    }\n  }\n\n  private normalizeAiUsageEvent(\n    event: unknown,\n    aiConfig: Record<string, unknown>,\n  ): SmrtAiUsageEvent | undefined {\n    const raw = (event ?? {}) as Record<string, unknown>;\n    const provider = firstString(\n      raw.provider,\n      raw.type,\n      aiConfig.provider,\n      aiConfig.type,\n    );\n    const model = firstString(\n      raw.model,\n      raw.defaultModel,\n      aiConfig.model,\n      aiConfig.defaultModel,\n    );\n    const operation =\n      firstString(raw.operation, raw.kind, raw.method) ?? 'unknown';\n    const usage =\n      normalizeIncomingAiUsageTokens(raw.usage) ??\n      normalizeIncomingAiUsageTokens(raw.tokenUsage) ??\n      normalizeIncomingAiUsageTokens({\n        promptTokens: raw.promptTokens,\n        completionTokens: raw.completionTokens,\n        totalTokens: raw.totalTokens,\n      });\n\n    if (!provider || !model) {\n      return undefined;\n    }\n\n    const duration =\n      firstNumber(raw.duration, raw.durationMs, raw.latency) ?? 0;\n    const tenantId =\n      'tenantId' in this &&\n      (this as { tenantId?: string | null }).tenantId !== undefined\n        ? ((this as { tenantId?: string | null }).tenantId ?? null)\n        : undefined;\n\n    return {\n      provider,\n      model,\n      operation,\n      usage,\n      duration,\n      timestamp: normalizeAiUsageTimestamp(raw.timestamp),\n      tags: normalizeAiUsageTags(raw.tags),\n      className: this._className,\n      tenantId,\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"class.js","names":[],"sources":["../src/class.ts"],"sourcesContent":["import type { AIClientOptions } from '@happyvertical/ai';\nimport { type AIClient, getAI } from '@happyvertical/ai';\nimport type {\n  FilesystemAdapter,\n  FilesystemAdapterOptions,\n} from '@happyvertical/files';\nimport { createLogger, type LoggerConfig } from '@happyvertical/logger';\nimport type {\n  AiTokenUsage,\n  AiUsageHandler,\n  AiUsageListOptions,\n  AiUsageSnapshot,\n  AiUsageStats,\n  AiUsageSummaryOptions,\n  SignalAdapter,\n  SmrtAiUsageEvent,\n  SmrtAiUsageRecord,\n} from '@happyvertical/smrt-types';\nimport { type DatabaseInterface, getDatabase } from '@happyvertical/sql';\nimport {\n  AiUsageCollector,\n  AiUsagePersistenceHandler,\n} from './adapters/ai-usage.js';\nimport { estimateAiUsageCost } from './adapters/cost-rates.js';\nimport { registerChangeFeedWriter } from './change-feed.js';\nimport type {\n  AIConfig,\n  AiUsageConfig,\n  GlobalSignalConfig,\n  MetricsConfig,\n  PubSubConfig,\n} from './config.js';\nimport { config } from './config.js';\nimport type { DatabaseConfig } from './database.js';\nimport { createFilesystemAdapter } from './filesystem-loader.js';\nimport { applyPostgresRuntimeTimeouts } from './postgres-timeouts.js';\nimport { detectEngine } from './schema/ddl/index.js';\nimport { SignalBus } from './signals/bus.js';\nimport { ensureSystemTables as ensureFrameworkSystemTables } from './system/bootstrap.js';\nimport {\n  ensureDeferredSystemTableCompatibility,\n  tableExists,\n} from './system/compatibility.js';\nimport { SMRT_SCHEMA_VERSION } from './system/schema.js';\nimport { toSafeInteger } from './utils/safe-integer.js';\n\n/**\n * `_smrt_migrations.version` suffix marking that the deferred (manifest-created)\n * system tables have been through their compatibility pass (issue #2376).\n */\nconst DEFERRED_COMPATIBILITY_VERSION_SUFFIX = '+deferred-compat';\n\nconst logger = createLogger({ level: 'info' });\n\ntype DatabaseWithConfig = DatabaseInterface & {\n  config?: {\n    type?: string;\n    url?: string;\n  };\n  type?: string;\n};\n\ninterface ResolvedAiUsageConfig {\n  enabled: boolean;\n  persist: boolean;\n  estimateCosts: boolean;\n  costRates?: Record<string, { input: number; output: number }>;\n  handlers: AiUsageHandler[];\n}\n\ntype AiUsageFilterOptions = Pick<\n  AiUsageListOptions,\n  | 'since'\n  | 'until'\n  | 'provider'\n  | 'model'\n  | 'operation'\n  | 'className'\n  | 'tenantId'\n>;\n\ninterface AiUsageWhereClause {\n  conditions: string[];\n  params: unknown[];\n  nextParamIndex: number;\n}\n\nfunction firstString(...candidates: unknown[]): string | undefined {\n  return candidates.find((candidate): candidate is string => {\n    return typeof candidate === 'string';\n  });\n}\n\nfunction firstNumber(...candidates: unknown[]): number | undefined {\n  return candidates.find((candidate): candidate is number => {\n    return typeof candidate === 'number';\n  });\n}\n\nfunction getDatabaseUrl(db: DatabaseInterface): string {\n  const dbWithConfig = db as DatabaseWithConfig;\n  return db.url || dbWithConfig.config?.url || '';\n}\n\nfunction getDatabaseTypeHint(\n  config: DatabaseConfig | undefined,\n): string | undefined {\n  if (!config || typeof config === 'string') {\n    return undefined;\n  }\n\n  const configWithType = config as DatabaseWithConfig & {\n    client?: unknown;\n  };\n\n  if (typeof configWithType.type === 'string') {\n    return configWithType.type;\n  }\n\n  if (typeof configWithType.config?.type === 'string') {\n    return configWithType.config.type;\n  }\n\n  if ('query' in configWithType && typeof configWithType.query === 'function') {\n    return undefined;\n  }\n\n  if ('client' in configWithType && configWithType.client) {\n    return 'postgres';\n  }\n\n  return undefined;\n}\n\nfunction normalizeIncomingAiUsageTokens(\n  value: unknown,\n): AiTokenUsage | undefined {\n  if (!value || typeof value !== 'object') {\n    return undefined;\n  }\n\n  const usage = value as Record<string, unknown>;\n  const promptTokens =\n    typeof usage.promptTokens === 'number'\n      ? usage.promptTokens\n      : typeof usage.inputTokens === 'number'\n        ? usage.inputTokens\n        : undefined;\n  const completionTokens =\n    typeof usage.completionTokens === 'number'\n      ? usage.completionTokens\n      : typeof usage.outputTokens === 'number'\n        ? usage.outputTokens\n        : undefined;\n  const totalTokens =\n    typeof usage.totalTokens === 'number'\n      ? usage.totalTokens\n      : promptTokens !== undefined || completionTokens !== undefined\n        ? (promptTokens ?? 0) + (completionTokens ?? 0)\n        : undefined;\n\n  if (\n    promptTokens === undefined &&\n    completionTokens === undefined &&\n    totalTokens === undefined\n  ) {\n    return undefined;\n  }\n\n  return {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n  };\n}\n\nfunction hydratePersistedAiUsageTokens(row: {\n  prompt_tokens?: unknown;\n  completion_tokens?: unknown;\n  total_tokens?: unknown;\n}): AiTokenUsage | undefined {\n  const promptTokens =\n    row.prompt_tokens === null || row.prompt_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.prompt_tokens, 'AI usage prompt tokens');\n  const completionTokens =\n    row.completion_tokens === null || row.completion_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.completion_tokens, 'AI usage completion tokens');\n  const totalTokens =\n    row.total_tokens === null || row.total_tokens === undefined\n      ? undefined\n      : toSafeInteger(row.total_tokens, 'AI usage total tokens');\n\n  if (\n    promptTokens === undefined &&\n    completionTokens === undefined &&\n    totalTokens === undefined\n  ) {\n    return undefined;\n  }\n\n  return {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n  };\n}\n\nfunction normalizeAiUsageTags(\n  value: unknown,\n): Record<string, string> | undefined {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return undefined;\n  }\n\n  const tags: Record<string, string> = {};\n  for (const [key, tagValue] of Object.entries(value)) {\n    if (tagValue === undefined || tagValue === null) continue;\n    tags[key] = String(tagValue);\n  }\n\n  return Object.keys(tags).length > 0 ? tags : undefined;\n}\n\nfunction parseAiUsageTags(value: unknown): Record<string, string> | undefined {\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n\n  try {\n    return normalizeAiUsageTags(JSON.parse(value));\n  } catch {\n    return undefined;\n  }\n}\n\nfunction normalizeAiUsageTimestamp(value: unknown): Date {\n  if (value instanceof Date) {\n    return value;\n  }\n\n  if (typeof value === 'string' || typeof value === 'number') {\n    const date = new Date(value);\n    if (!Number.isNaN(date.getTime())) {\n      return date;\n    }\n  }\n\n  return new Date();\n}\n\nfunction getQueryRows(\n  result: Awaited<ReturnType<DatabaseInterface['query']>>,\n): Record<string, unknown>[] {\n  return Array.isArray(result)\n    ? (result as Record<string, unknown>[])\n    : ((result as { rows?: Record<string, unknown>[] }).rows ?? []);\n}\n\nfunction buildAiUsageWhereClause(\n  options: AiUsageFilterOptions,\n): AiUsageWhereClause {\n  const conditions: string[] = [];\n  const params: unknown[] = [];\n  let nextParamIndex = 1;\n\n  if (options.since) {\n    conditions.push(`created_at >= $${nextParamIndex++}`);\n    params.push(options.since.toISOString());\n  }\n\n  if (options.until) {\n    conditions.push(`created_at <= $${nextParamIndex++}`);\n    params.push(options.until.toISOString());\n  }\n\n  if (options.provider) {\n    conditions.push(`provider = $${nextParamIndex++}`);\n    params.push(options.provider);\n  }\n\n  if (options.model) {\n    conditions.push(`model = $${nextParamIndex++}`);\n    params.push(options.model);\n  }\n\n  if (options.operation) {\n    conditions.push(`operation = $${nextParamIndex++}`);\n    params.push(options.operation);\n  }\n\n  if (options.className) {\n    conditions.push(`class_name = $${nextParamIndex++}`);\n    params.push(options.className);\n  }\n\n  if (options.tenantId === null) {\n    conditions.push(`tenant_id IS NULL`);\n  } else if (options.tenantId) {\n    conditions.push(`tenant_id = $${nextParamIndex++}`);\n    params.push(options.tenantId);\n  }\n\n  return {\n    conditions,\n    params,\n    nextParamIndex,\n  };\n}\n\n/**\n * Configuration options for the SmrtClass\n */\nexport interface SmrtClassOptions {\n  /**\n   * Optional custom class name override\n   */\n  _className?: string;\n\n  /**\n   * Database configuration - unified approach matching @happyvertical/sql\n   *\n   * Supports three formats:\n   * - String shortcut: 'products.db' (auto-detects database type)\n   * - Config object: { type: 'sqlite', url: 'products.db' }\n   * - DatabaseInterface instance: await getDatabase(...)\n   *\n   * @see DatabaseConfig for type definition\n   */\n  db?: DatabaseConfig;\n\n  /**\n   * Alias for db option - for backward compatibility with documentation\n   *\n   * @deprecated Use 'db' instead. This alias exists for backward compatibility.\n   */\n  persistence?: DatabaseConfig;\n\n  /**\n   * Filesystem adapter configuration options\n   */\n  fs?: FilesystemAdapterOptions;\n\n  /**\n   * AI client configuration options or instance\n   */\n  ai?: AIClientOptions | AIClient;\n\n  /**\n   * AI usage tracking configuration (overrides global defaults)\n   */\n  usage?: AiUsageConfig;\n\n  /**\n   * Logging configuration (overrides global default)\n   */\n  logging?: LoggerConfig;\n\n  /**\n   * Metrics configuration (overrides global default)\n   */\n  metrics?: MetricsConfig;\n\n  /**\n   * Pub/Sub configuration (overrides global default)\n   */\n  pubsub?: PubSubConfig;\n\n  /**\n   * Sanitization configuration (overrides global default)\n   */\n  sanitization?: import('./config.js').GlobalSignalConfig['sanitization'];\n\n  /**\n   * Custom signal configuration (overrides global default)\n   */\n  signals?: {\n    /** Shared signal bus instance */\n    bus?: SignalBus;\n    /** Additional custom adapters */\n    adapters?: SignalAdapter[];\n  };\n\n  /**\n   * Internal flag to reuse an already initialized DatabaseInterface instance.\n   *\n   * Skips database resolution and system-table setup during lightweight hydration.\n   * @internal\n   */\n  _reuseInitializedDb?: boolean;\n\n  /**\n   * Internal flag to defer runtime-only services such as signals and AI setup.\n   *\n   * Lightweight hydration paths set this so plain query reads avoid per-row\n   * runtime bootstrap costs.\n   * @internal\n   */\n  _deferRuntimeInitialization?: boolean;\n}\n\n/**\n * Foundation class providing core functionality for the SMRT framework\n *\n * SmrtClass provides unified access to database, filesystem, and AI client\n * interfaces. It serves as the foundation for all other classes in the\n * SMRT framework.\n */\nexport class SmrtClass {\n  /**\n   * AI client instance for interacting with AI models\n   */\n  protected _ai!: AIClient;\n\n  /**\n   * Filesystem adapter for file operations\n   */\n  protected _fs!: FilesystemAdapter;\n\n  /**\n   * Database interface for data persistence\n   */\n  protected _db!: DatabaseInterface;\n  private _dbEngineHint?: string;\n\n  /**\n   * Class name used for identification\n   */\n  protected _className!: string;\n\n  /**\n   * Signal bus for method execution tracking\n   */\n  protected _signalBus?: SignalBus;\n\n  /**\n   * Adapters registered by this instance (for cleanup)\n   */\n  private _registeredAdapters: SignalAdapter[] = [];\n\n  /**\n   * In-memory AI usage collector for quick inspection.\n   */\n  private _aiUsageCollector?: AiUsageCollector;\n\n  /**\n   * Registered AI usage handlers for this instance.\n   */\n  private _aiUsageHandlers: AiUsageHandler[] = [];\n\n  /**\n   * Tracks whether optional runtime services (signals, AI, fs) are ready.\n   */\n  private _runtimeServicesInitialized = false;\n\n  /**\n   * Shared in-flight runtime initialization promise for single-flight setup.\n   */\n  private _runtimeServicesInitPromise?: Promise<void>;\n\n  /**\n   * Configuration options provided to the class\n   */\n  public options: SmrtClassOptions;\n\n  /**\n   * Track which databases have had system tables initialized\n   * - WeakSet for :memory: databases (URL not unique, track by instance)\n   * - Set<string> for all others (URL is unique identifier)\n   */\n  private static _systemTablesInitialized = new WeakSet<DatabaseInterface>();\n  private static _systemTablesInitializedByUrl = new Set<string>();\n\n  /**\n   * Creates a new SmrtClass instance\n   *\n   * @param options - Configuration options for database, filesystem, and AI clients\n   */\n  constructor(options: SmrtClassOptions = {}) {\n    this.options = options;\n    this._className = this.constructor.name;\n  }\n\n  /**\n   * Determines whether this class requires a database to function\n   *\n   * Override this method in subclasses that require database access\n   * to enable early validation during initialization.\n   *\n   * @returns True if database is required, false otherwise\n   * @example\n   * ```typescript\n   * class MyDataModel extends SmrtClass {\n   *   protected requiresDatabase(): boolean {\n   *     return true; // This class needs database access\n   *   }\n   * }\n   * ```\n   */\n  protected requiresDatabase(): boolean {\n    return false; // Base class doesn't require database by default\n  }\n\n  /**\n   * Initializes database, filesystem, and AI client connections\n   *\n   * This method sets up all required services based on the provided options.\n   * It should be called before using any of the service interfaces.\n   *\n   * @returns Promise that resolves to this instance for chaining\n   * @throws {Error} If database is required but not provided in options\n   */\n  protected async initialize(): Promise<this> {\n    await this.initializeCoreResources();\n\n    if (!this.options._deferRuntimeInitialization) {\n      await this.initializeRuntimeServices();\n    }\n\n    return this;\n  }\n\n  /**\n   * Initialize core resources required for ORM behavior.\n   *\n   * This setup is shared by both full runtime initialization and lightweight\n   * query hydration. Hydrated objects reuse an existing DB connection and skip\n   * repeated system-table checks.\n   */\n  protected async initializeCoreResources(): Promise<void> {\n    // Framework init hook for the change feed (#1758): make sure the writer\n    // interceptor observes every save/delete before any instance can write.\n    // Idempotent and cheap when already registered.\n    registerChangeFeedWriter();\n\n    // Map persistence to db for backward compatibility\n    if (this.options.persistence && !this.options.db) {\n      this.options.db = this.options.persistence;\n    }\n\n    // Validate database configuration if required\n    if (this.requiresDatabase() && !this.options.db) {\n      throw new Error(\n        `${this._className} requires a database configuration. ` +\n          `Please provide 'db' in options: { db: { url: '...' } } or { db: 'database.db' }`,\n      );\n    }\n\n    if (this.options.db) {\n      this._dbEngineHint = getDatabaseTypeHint(this.options.db);\n\n      if (\n        this.options._reuseInitializedDb &&\n        typeof this.options.db === 'object' &&\n        'query' in this.options.db\n      ) {\n        this._db = this.options.db as DatabaseInterface;\n        this.options.db = this._db;\n      } else {\n        // Handle four db config formats (in implementation order):\n        // 1. String URL: 'products.db' (shortcut)\n        // 2. DatabaseInterface instance: already initialized db (has 'query' method)\n        // 3. Config with client: { type: 'postgres', client: pgPool } (SvelteKit pattern)\n        // 4. Config object: { type: 'sqlite', url: 'products.db' }\n        if (typeof this.options.db === 'string') {\n          // Format 1: String shortcut - let getDatabase auto-detect type from URL\n          // Preserve connection sharing for file-backed databases while leaving\n          // true in-memory databases isolated per instance.\n          const isMemoryDb = this.options.db === ':memory:';\n          // PostgreSQL URLs pick up the runtime timeout bounds, and the dbid is\n          // derived from the bounded URL so the same rewrite at every call site\n          // still resolves to one shared pool (#2377).\n          const bounded = applyPostgresRuntimeTimeouts({\n            url: this.options.db,\n          });\n          this._db = await getDatabase({\n            ...bounded,\n            ...(isMemoryDb ? {} : { dbid: `smrt:${bounded.url}` }),\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        } else if ('query' in this.options.db) {\n          // Format 2: Already a DatabaseInterface instance - return as-is\n          this._db = this.options.db as DatabaseInterface;\n        } else if ('client' in this.options.db && this.options.db.client) {\n          // Format 3: Config with pre-created client (e.g., from SvelteKit's $env-based connection)\n          // Pass the client to getDatabase which will use it instead of creating a new connection\n          const dbConfig = this.options.db as {\n            type?: string;\n            client: unknown;\n            url?: string;\n          };\n          // `client` is a runtime-only property the postgres adapter reads\n          // but the public `getDatabase` option union does not model, so the\n          // literal is routed through the function's own parameter type.\n          this._db = await getDatabase({\n            type: dbConfig.type || 'postgres',\n            client: dbConfig.client,\n            url: dbConfig.url,\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        } else {\n          // Format 4: Config object - pass to getDatabase (handles all types uniformly)\n          // Preserve connection sharing for file-backed databases while leaving\n          // true in-memory databases isolated per instance.\n          const dbConfig = this.options.db as { url?: string; type?: string };\n          const dbUrl = dbConfig.url || 'memory';\n          const isMemoryDb = dbUrl === ':memory:' || dbUrl === 'memory';\n          // Keep the config's own key set: an object with no `url` must stay\n          // that way so the adapter applies its own default (#2377).\n          const bounded = applyPostgresRuntimeTimeouts({ ...this.options.db });\n          // The loose config-object variant of `DatabaseConfig` carries an\n          // index signature that the closed `getDatabase` option union does\n          // not accept structurally, so route through its parameter type.\n          this._db = await getDatabase({\n            ...bounded,\n            ...(isMemoryDb ? {} : { dbid: `smrt:${bounded.url ?? dbUrl}` }),\n          } as unknown as Parameters<typeof getDatabase>[0]);\n        }\n\n        /**\n         * INTENTIONAL MUTATION: After resolving the database config,\n         * we replace options.db with the actual DatabaseInterface instance.\n         * This enables child objects to share the same connection via:\n         *\n         *   const child = new ChildObject({ db: parent.options.db });\n         *\n         * Without this, passing this.options to getCollection() would use the config object\n         * which causes a NEW db instance to be created, losing data isolation.\n         *\n         * See issue #567 for context on why this pattern is necessary.\n         */\n        this.options.db = this._db;\n\n        await this.ensureSystemTables();\n      }\n    }\n  }\n\n  /**\n   * Initialize optional runtime services that are not required for plain ORM reads.\n   */\n  protected async initializeRuntimeServices(): Promise<void> {\n    if (this._runtimeServicesInitialized) {\n      return;\n    }\n\n    if (!this._runtimeServicesInitPromise) {\n      this._runtimeServicesInitPromise = (async () => {\n        if (this.options.fs && !this._fs) {\n          // Acquired through the boundary in filesystem-loader.ts so the\n          // @happyvertical/files SDK (S3/googleapis) never enters\n          // provider-neutral consumer bundles (#1977/#1979).\n          this._fs = await createFilesystemAdapter(this.options.fs);\n        }\n\n        // Initialize AI client with environment variable support\n        // Priority: instance options > env vars > global config > defaults\n        const globalConfig = config.toJSON();\n        const usageConfig = this.mergeAiUsageConfig(globalConfig);\n        this.initializeAiUsageHandlers(usageConfig);\n\n        if (\n          !this._ai &&\n          (this.options.ai || globalConfig.ai || process.env.SMRT_AI_PROVIDER)\n        ) {\n          // Check if options.ai is already a client-like object with embed method\n          // This allows passing mock AI clients for testing\n          const aiOption = this.options.ai as\n            | Record<string, unknown>\n            | undefined;\n          if (\n            aiOption &&\n            typeof aiOption === 'object' &&\n            typeof aiOption.embed === 'function' &&\n            !aiOption.provider\n          ) {\n            this._ai = aiOption as unknown as AIClient;\n          } else {\n            // CC-8 follow-up: ideally this would route through\n            // `@happyvertical/smrt-config` for sanitization parity (e.g. via\n            // `getPackageConfig('ai', ...)`), but smrt-config currently only\n            // merges file-based config + runtime overrides — it does NOT\n            // read from `process.env` with a typed prefix/schema. Until\n            // smrt-config grows an env-loader (or wraps `loadEnvConfig`),\n            // we continue to use the underlying utility directly. Tracked\n            // alongside the CC-8 audit on issue #1199.\n            const { loadEnvConfig } = await import('@happyvertical/utils');\n\n            // Start with global defaults\n            const baseConfig = globalConfig.ai || {};\n\n            // Merge with instance options (takes priority over global)\n            const userConfig = { ...baseConfig, ...this.options.ai };\n\n            // Load environment variables and merge (user options take priority).\n            // `AIConfig` carries an index signature, so provider-specific keys\n            // (`type`, `onUsage`, `defaultModel`, …) read back as `unknown`.\n            const aiConfig = loadEnvConfig<AIConfig>(userConfig, {\n              packageName: 'ai',\n              prefix: 'SMRT',\n              schema: {\n                provider: 'string',\n                model: 'string',\n                apiKey: 'string',\n                timeout: 'number',\n                maxRetries: 'number',\n                temperature: 'number',\n                maxTokens: 'number',\n              },\n            });\n\n            const existingOnUsage =\n              aiConfig.onUsage ??\n              (userConfig as Record<string, unknown>).onUsage ??\n              undefined;\n            aiConfig.onUsage = async (event: unknown) => {\n              if (typeof existingOnUsage === 'function') {\n                await (existingOnUsage as (usageEvent: unknown) => unknown)(\n                  event,\n                );\n              }\n              await this.handleAiUsageCallback(event, aiConfig, usageConfig);\n            };\n\n            // Only initialize if we have a provider configured\n            if (aiConfig.provider || aiConfig.type || aiConfig.apiKey) {\n              // Use getAI() factory to support all AI providers (OpenAI, Anthropic, Gemini, etc.)\n              // getAI() returns AIInterface, which we narrow to AIClient for\n              // backward compatibility. The index-signature `AIConfig` is routed\n              // through getAI's own parameter type rather than the closed union.\n              this._ai = (await getAI(\n                aiConfig as unknown as Parameters<typeof getAI>[0],\n              )) as unknown as AIClient;\n            }\n          }\n        }\n\n        await this.initializeSignals();\n        this._runtimeServicesInitialized = true;\n      })();\n    }\n\n    try {\n      await this._runtimeServicesInitPromise;\n    } finally {\n      this._runtimeServicesInitPromise = undefined;\n    }\n  }\n\n  /**\n   * Ensure deferred runtime services are ready before using them.\n   */\n  protected async ensureRuntimeServicesInitialized(): Promise<void> {\n    if (!this._runtimeServicesInitialized) {\n      await this.initializeRuntimeServices();\n    }\n  }\n\n  /**\n   * Resolve the AI client, initializing deferred runtime services on demand.\n   */\n  protected async getAiClient(): Promise<AIClient> {\n    await this.ensureRuntimeServicesInitialized();\n\n    if (!this._ai) {\n      throw new Error(\n        `${this._className} does not have an AI client configured. ` +\n          `Provide 'ai' in options or configure a global SMRT AI provider.`,\n      );\n    }\n\n    return this._ai;\n  }\n\n  /**\n   * Resolve the AI client if one is configured, otherwise return undefined.\n   */\n  protected async getOptionalAiClient(): Promise<AIClient | undefined> {\n    await this.ensureRuntimeServicesInitialized();\n    return this._ai;\n  }\n\n  private async isSystemSchemaVersionApplied(\n    db: DatabaseInterface,\n    version: string,\n  ): Promise<boolean> {\n    const engine = detectEngine(getDatabaseUrl(db), this._dbEngineHint);\n\n    if (\n      engine === 'postgres' &&\n      !(await tableExists(db, '_smrt_migrations', this._dbEngineHint))\n    ) {\n      return false;\n    }\n\n    try {\n      const versionParam = engine === 'postgres' ? '$1' : '?';\n      const rows = await db.query(\n        `SELECT 1 FROM _smrt_migrations WHERE version = ${versionParam} LIMIT 1`,\n        version,\n      );\n      return getQueryRows(rows).length > 0;\n    } catch (error) {\n      if (engine === 'postgres') {\n        throw error;\n      }\n\n      return false;\n    }\n  }\n\n  /**\n   * Ensure SMRT system tables exist in the database\n   *\n   * System tables use the _smrt_ prefix and store framework metadata:\n   * - _smrt_contexts: Context memory storage for remembered patterns\n   * - _smrt_migrations: Schema version tracking\n   * - _smrt_schema_migrations / _smrt_backfills: Migration and backfill ledgers\n   * - _smrt_embeddings: Embedding vectors for semantic search\n   * - _smrt_dispatch / _smrt_dispatch_subscriptions: Inter-agent dispatch queue\n   * - _smrt_ai_usage: AI usage telemetry\n   * - _smrt_changes: Append-only change feed\n   *\n   * Note that the _smrt_ prefix alone does NOT mean \"system table\" — ~25\n   * `@smrt()` domain tables (feature flags, prompt overrides, subscription\n   * plans, …) carry it too and are created by `db:migrate`, not here. The\n   * framework's own list is `SYSTEM_TABLE_NAMES` in\n   * `schema/system-table-shapes.ts`, derived from this DDL.\n   *\n   * This method is idempotent and safe to call multiple times.\n   * Tables are only created once per database connection.\n   */\n  private async ensureSystemTables(): Promise<void> {\n    if (!this._db) return;\n\n    const dbUrl = getDatabaseUrl(this._db);\n\n    // Some databases share URLs but are different instances:\n    // - :memory: databases (SQLite/DuckDB in-memory)\n    // - JSON databases (may have undefined or shared URLs)\n    // - Any database with undefined URL\n    // Use WeakSet for instance tracking, Set<string> for URL tracking\n    const dbConstructorName = this._db.constructor?.name || '';\n    const isMemoryDb = dbUrl === ':memory:';\n    const isJsonDb = dbConstructorName.toLowerCase().includes('json');\n    const hasUndefinedUrl = !dbUrl;\n    const useInstanceTracking = isMemoryDb || isJsonDb || hasUndefinedUrl;\n\n    if (useInstanceTracking) {\n      // Check WeakSet for databases that may share URLs (track by instance)\n      if (SmrtClass._systemTablesInitialized.has(this._db)) {\n        return;\n      }\n    } else {\n      // Check Set<string> for URL-based databases (track by URL)\n      if (SmrtClass._systemTablesInitializedByUrl.has(dbUrl)) {\n        return;\n      }\n    }\n\n    try {\n      await ensureFrameworkSystemTables(this._db, this._dbEngineHint);\n      await this.settleDeferredSystemTableCompatibility(this._db);\n      await this.ensureNativeVectorStorage();\n\n      // Mark as initialized using appropriate tracking mechanism\n      if (useInstanceTracking) {\n        SmrtClass._systemTablesInitialized.add(this._db);\n      } else {\n        SmrtClass._systemTablesInitializedByUrl.add(dbUrl);\n      }\n    } catch (error) {\n      // DO NOT SWALLOW ERRORS - fail loudly so we know what's wrong\n      const dbInfo = this._db.constructor?.name || 'unknown database';\n      throw new Error(\n        `Failed to create system tables for ${dbInfo}: ${error instanceof Error ? error.message : String(error)}`,\n        { cause: error },\n      );\n    }\n  }\n\n  /**\n   * Run the compatibility pass for the system tables `db:migrate` creates, then\n   * stamp its own marker in `_smrt_migrations` (issue #2376).\n   *\n   * Deliberately runs OUTSIDE the bootstrap lock/transaction, and deliberately\n   * cannot fail startup:\n   *\n   * - `_smrt_jobs` / `_smrt_job_events` are created by `db:migrate` from the\n   *   jobs manifest, which on a fresh install runs AFTER the framework's first\n   *   bootstrap. Gating this pass on {@link SMRT_SCHEMA_VERSION} would mean the\n   *   version gets stamped while the tables are still absent and the pass never\n   *   runs on that database again. It therefore carries its own marker, which\n   *   is written only once every deferred table exists and has been upgraded.\n   * - Its statements are ALTER TABLE / CREATE INDEX against tables the\n   *   framework does not own. Inside the PostgreSQL bootstrap transaction one\n   *   failure (a permissions problem, say) would abort the transaction and roll\n   *   back system-table creation with it. Outside, a failure is a logged\n   *   warning and the next process start retries — the pass is idempotent and\n   *   already tolerates concurrent creators.\n   *\n   * Until the tables exist this costs two catalog probes per process per\n   * database; afterwards the marker short-circuits it.\n   */\n  private async settleDeferredSystemTableCompatibility(\n    db: DatabaseInterface,\n  ): Promise<void> {\n    const marker = `${SMRT_SCHEMA_VERSION}${DEFERRED_COMPATIBILITY_VERSION_SUFFIX}`;\n\n    try {\n      if (await this.isSystemSchemaVersionApplied(db, marker)) {\n        return;\n      }\n\n      const { settled } = await ensureDeferredSystemTableCompatibility(\n        db,\n        this._dbEngineHint,\n      );\n      if (!settled) {\n        return;\n      }\n\n      const id = crypto.randomUUID();\n      const description = 'Deferred SMRT system table compatibility';\n      await db.execute`\n        INSERT INTO _smrt_migrations (id, version, description)\n        VALUES (${id}, ${marker}, ${description})\n        ON CONFLICT(version) DO NOTHING\n      `;\n    } catch (error) {\n      logger.warn(\n        `[smrt] Deferred system table compatibility did not complete; retrying on the next start: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n      );\n    }\n  }\n\n  private async ensureNativeVectorStorage(): Promise<void> {\n    if (!this._db) {\n      return;\n    }\n\n    try {\n      const { ObjectRegistry } = await import('./registry.js');\n      const embeddingConfig = ObjectRegistry.getProjectEmbeddingConfig();\n      if (embeddingConfig?.storage === 'native') {\n        const { EmbeddingStorage } = await import('./embeddings/storage.js');\n        const vector = this._db.vector;\n        if (vector) {\n          const dimensions = embeddingConfig.dimensions || 768;\n          await EmbeddingStorage.ensureVectorStorage(\n            this._db,\n            dimensions,\n            vector,\n          );\n        } else {\n          logger.warn(\n            '[smrt] Embedding storage set to \"native\" but database has no vector capability. Falling back to JSON storage.',\n          );\n        }\n      }\n    } catch (error) {\n      // Don't fail system table initialization for vector setup errors\n      logger.warn(\n        `[smrt] Failed to initialize vector storage: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  /**\n   * Access system tables through standard database interface\n   * System tables use _smrt_ prefix to avoid conflicts with user tables\n   */\n  protected get systemDb(): DatabaseInterface {\n    return this._db;\n  }\n\n  /**\n   * Return the database engine hint captured from the caller's configuration.\n   * Adapters may not expose their original type after construction (notably\n   * in-memory DuckDB/JSON connections), so query helpers can combine this\n   * hint with their public connection capabilities.\n   */\n  protected getDatabaseEngineHint(): string | undefined {\n    return this._dbEngineHint;\n  }\n\n  /**\n   * Initialize signal bus and adapters\n   *\n   * Merges global configuration with instance-specific overrides.\n   * Registers built-in and custom adapters based on configuration.\n   */\n  private async initializeSignals(): Promise<void> {\n    const globalConfig = config.toJSON();\n    const effectiveConfig = this.mergeSignalConfig(globalConfig);\n\n    // If a shared bus is provided, always use it (don't create new adapters)\n    if (this.options.signals?.bus) {\n      this._signalBus = this.options.signals.bus;\n      return;\n    }\n\n    // Otherwise, check if we should initialize signals based on config\n    if (!this.shouldInitializeSignals(effectiveConfig)) {\n      return;\n    }\n\n    this._signalBus = new SignalBus({\n      sanitization: effectiveConfig.sanitization,\n    });\n    await this.registerAdapters(effectiveConfig);\n  }\n\n  /**\n   * Merge global and instance signal configuration\n   *\n   * Instance configuration takes priority over global defaults.\n   *\n   * @param globalConfig - Global configuration from smrt.configure()\n   * @returns Merged configuration\n   */\n  private mergeSignalConfig(\n    globalConfig: GlobalSignalConfig,\n  ): GlobalSignalConfig {\n    return {\n      logging: this.options.logging ?? globalConfig.logging,\n      metrics: this.options.metrics ?? globalConfig.metrics,\n      pubsub: this.options.pubsub ?? globalConfig.pubsub,\n      usage: this.mergeAiUsageConfig(globalConfig),\n      sanitization: this.options.sanitization ?? globalConfig.sanitization,\n      signals: {\n        bus: this.options.signals?.bus ?? globalConfig.signals?.bus,\n        adapters: [\n          ...(globalConfig.signals?.adapters ?? []),\n          ...(this.options.signals?.adapters ?? []),\n        ],\n      },\n    };\n  }\n\n  /**\n   * Check if signals should be initialized\n   *\n   * Signals are initialized if any adapter is configured.\n   *\n   * @param config - Effective signal configuration\n   * @returns True if signals should be initialized\n   */\n  private shouldInitializeSignals(config: GlobalSignalConfig): boolean {\n    return !!(\n      config.logging !== false ||\n      config.metrics?.enabled ||\n      config.pubsub?.enabled ||\n      config.signals?.adapters?.length\n    );\n  }\n\n  /**\n   * Register signal adapters based on configuration\n   *\n   * @param config - Effective signal configuration\n   */\n  private async registerAdapters(config: GlobalSignalConfig): Promise<void> {\n    if (!this._signalBus) return;\n\n    // Logging adapter (default: enabled with console)\n    if (config.logging !== false) {\n      const { createLogger, LoggerAdapter } = await import(\n        '@happyvertical/logger'\n      );\n      const logger = createLogger(config.logging ?? true);\n      const adapter = new LoggerAdapter(logger);\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Metrics adapter (default: disabled)\n    if (config.metrics?.enabled) {\n      const { MetricsAdapter } = await import('./adapters/metrics.js');\n      const adapter = new MetricsAdapter();\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Pub/Sub adapter (default: disabled)\n    if (config.pubsub?.enabled) {\n      const { PubSubAdapter } = await import('./adapters/pubsub.js');\n      const adapter = new PubSubAdapter();\n      this._signalBus.register(adapter);\n      this._registeredAdapters.push(adapter);\n    }\n\n    // Custom adapters\n    if (config.signals?.adapters) {\n      for (const adapter of config.signals.adapters) {\n        this._signalBus.register(adapter);\n        this._registeredAdapters.push(adapter);\n      }\n    }\n  }\n\n  /**\n   * Gets the filesystem adapter instance\n   */\n  get fs() {\n    return this._fs;\n  }\n\n  /**\n   * Gets the database interface instance\n   */\n  get db() {\n    // Throw helpful error if database is accessed before initialization\n    if (!this._db) {\n      throw new Error(\n        `Database accessed before initialization. ` +\n          `Please call await instance.initialize() before accessing the database.`,\n      );\n    }\n    return this._db;\n  }\n\n  /**\n   * Temporarily bind this initialized instance to another database interface.\n   *\n   * This is intended for transaction-scoped work where a caller must ensure\n   * that every nested SMRT read and write uses the transaction database passed\n   * to its callback. The original database is restored whether the callback\n   * succeeds or throws. Do not use the same instance concurrently while it is\n   * temporarily bound.\n   */\n  async withDatabase<T>(\n    db: DatabaseInterface,\n    operation: (bound: this) => Promise<T>,\n  ): Promise<T> {\n    // Read through the public getter so an uninitialized instance fails with\n    // the normal, actionable SmrtClass error before any state is mutated.\n    const previousDb = this.db;\n    const previousOptionDb = this.options.db;\n    this._db = db;\n    this.options.db = db;\n    try {\n      return await operation(this);\n    } finally {\n      this._db = previousDb;\n      this.options.db = previousOptionDb;\n    }\n  }\n\n  /**\n   * Gets the AI client instance\n   */\n  get ai() {\n    return this._ai;\n  }\n\n  /**\n   * Get the in-memory AI usage snapshot for this instance.\n   */\n  getAiUsageSnapshot(): AiUsageSnapshot | undefined {\n    return this._aiUsageCollector?.getSnapshot();\n  }\n\n  /**\n   * Reset the in-memory AI usage collector.\n   */\n  resetAiUsage(): void {\n    this._aiUsageCollector?.reset();\n  }\n\n  /**\n   * List persisted AI usage records.\n   */\n  async listAiUsage(\n    options: AiUsageListOptions = {},\n  ): Promise<SmrtAiUsageRecord[]> {\n    if (!this._db) {\n      throw new Error(\n        `AI usage requires a database configuration. ` +\n          `Please call initialize() with a db option before querying usage.`,\n      );\n    }\n\n    const { conditions, params } = buildAiUsageWhereClause(options);\n    let paramIndex = params.length + 1;\n\n    let sql = 'SELECT * FROM _smrt_ai_usage';\n    if (conditions.length > 0) {\n      sql += ` WHERE ${conditions.join(' AND ')}`;\n    }\n\n    sql += ` ORDER BY ${\n      options.orderBy === 'timestamp ASC' ? 'created_at ASC' : 'created_at DESC'\n    }`;\n\n    if (options.limit !== undefined) {\n      sql += ` LIMIT $${paramIndex++}`;\n      params.push(options.limit);\n    }\n\n    if (options.offset !== undefined) {\n      sql += ` OFFSET $${paramIndex++}`;\n      params.push(options.offset);\n    }\n\n    const rows = getQueryRows(await this._db.query(sql, ...params));\n\n    return rows.map((row) => ({\n      id: String(row.id),\n      provider: String(row.provider),\n      model: String(row.model),\n      operation: String(row.operation),\n      usage: hydratePersistedAiUsageTokens(row),\n      estimatedCost:\n        row.estimated_cost === null || row.estimated_cost === undefined\n          ? undefined\n          : Number(row.estimated_cost),\n      duration: toSafeInteger(row.duration ?? 0, 'AI usage duration'),\n      className:\n        row.class_name === null || row.class_name === undefined\n          ? undefined\n          : String(row.class_name),\n      tenantId:\n        row.tenant_id === undefined\n          ? undefined\n          : (row.tenant_id as string | null),\n      tags: parseAiUsageTags(row.tags),\n      timestamp: normalizeAiUsageTimestamp(row.created_at),\n    }));\n  }\n\n  /**\n   * Summarize persisted AI usage records by a grouping dimension.\n   */\n  async summarizeAiUsage(\n    options: AiUsageSummaryOptions = {},\n  ): Promise<Record<string, AiUsageStats>> {\n    if (!this._db) {\n      throw new Error(\n        `AI usage requires a database configuration. ` +\n          `Please call initialize() with a db option before querying usage.`,\n      );\n    }\n\n    const groupBy = options.groupBy ?? 'model';\n    const bucketExpression =\n      groupBy === 'provider'\n        ? `provider`\n        : groupBy === 'model'\n          ? `provider || ':' || model`\n          : groupBy === 'class'\n            ? `COALESCE(class_name, 'unknown')`\n            : groupBy === 'tenant'\n              ? `COALESCE(tenant_id, 'global')`\n              : groupBy === 'operation'\n                ? `operation`\n                : `substr(CAST(created_at AS TEXT), 1, 10)`;\n\n    const { conditions, params } = buildAiUsageWhereClause(options);\n\n    let sql = `\n      SELECT ${bucketExpression} AS bucket,\n             COUNT(*) AS call_count,\n             COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,\n             COALESCE(SUM(completion_tokens), 0) AS completion_tokens,\n             COALESCE(SUM(total_tokens), 0) AS total_tokens,\n             COALESCE(SUM(duration), 0) AS total_duration,\n             COALESCE(SUM(estimated_cost), 0) AS estimated_cost,\n             MAX(created_at) AS last_used\n      FROM _smrt_ai_usage\n    `;\n\n    if (conditions.length > 0) {\n      sql += ` WHERE ${conditions.join(' AND ')}`;\n    }\n\n    sql += ' GROUP BY bucket ORDER BY bucket ASC';\n\n    const rows = getQueryRows(await this._db.query(sql, ...params));\n    const summary: Record<string, AiUsageStats> = {};\n\n    for (const row of rows) {\n      const bucket = String(row.bucket);\n      summary[bucket] = {\n        callCount: toSafeInteger(row.call_count ?? 0, 'AI usage call count'),\n        promptTokens: toSafeInteger(\n          row.prompt_tokens ?? 0,\n          'AI usage prompt-token total',\n        ),\n        completionTokens: toSafeInteger(\n          row.completion_tokens ?? 0,\n          'AI usage completion-token total',\n        ),\n        totalTokens: toSafeInteger(\n          row.total_tokens ?? 0,\n          'AI usage token total',\n        ),\n        totalDuration: toSafeInteger(\n          row.total_duration ?? 0,\n          'AI usage duration total',\n        ),\n        estimatedCost: Number(row.estimated_cost ?? 0),\n        lastUsed: row.last_used ? new Date(String(row.last_used)).getTime() : 0,\n      };\n    }\n\n    return summary;\n  }\n\n  /**\n   * Gets the signal bus instance\n   *\n   * @returns Signal bus if signals are enabled, undefined otherwise\n   */\n  get signalBus(): SignalBus | undefined {\n    return this._signalBus;\n  }\n\n  /**\n   * Cleanup method to prevent memory leaks\n   *\n   * Unregisters all adapters from the signal bus that were registered\n   * by this instance. Call this when the SmrtClass instance is no longer\n   * needed to prevent memory leaks.\n   *\n   * @example\n   * ```typescript\n   * const product = new Product({ name: 'Widget' });\n   * await product.initialize();\n   * // ... use product ...\n   * product.destroy(); // Clean up when done\n   * ```\n   */\n  destroy(): void {\n    // Only unregister adapters if we own the bus (not shared)\n    if (this._signalBus && !this.options.signals?.bus) {\n      for (const adapter of this._registeredAdapters) {\n        this._signalBus.unregister(adapter);\n      }\n      this._registeredAdapters = [];\n    }\n\n    // TODO: If SmrtClass grows a broader async teardown lifecycle, move\n    // AI usage handler cleanup there alongside other connection-bound state.\n    this._aiUsageCollector = undefined;\n    this._aiUsageHandlers = [];\n  }\n\n  private mergeAiUsageConfig(\n    globalConfig: GlobalSignalConfig,\n  ): ResolvedAiUsageConfig {\n    const globalUsage = globalConfig.usage ?? {};\n    const instanceUsage = this.options.usage ?? {};\n\n    return {\n      enabled: instanceUsage.enabled ?? globalUsage.enabled ?? true,\n      persist: instanceUsage.persist ?? globalUsage.persist ?? true,\n      estimateCosts:\n        instanceUsage.estimateCosts ?? globalUsage.estimateCosts ?? true,\n      costRates: {\n        ...(globalUsage.costRates ?? {}),\n        ...(instanceUsage.costRates ?? {}),\n      },\n      handlers: [\n        ...(globalUsage.handlers ?? []),\n        ...(instanceUsage.handlers ?? []),\n      ],\n    };\n  }\n\n  private initializeAiUsageHandlers(config: ResolvedAiUsageConfig): void {\n    this._aiUsageCollector = undefined;\n    this._aiUsageHandlers = [];\n\n    if (!config.enabled) {\n      return;\n    }\n\n    this._aiUsageCollector = new AiUsageCollector();\n    this._aiUsageHandlers.push(this._aiUsageCollector);\n\n    if (config.persist && this._db) {\n      this._aiUsageHandlers.push(new AiUsagePersistenceHandler(this._db));\n    }\n\n    this._aiUsageHandlers.push(...config.handlers);\n  }\n\n  private async handleAiUsageCallback(\n    event: unknown,\n    aiConfig: Record<string, unknown>,\n    usageConfig: ResolvedAiUsageConfig,\n  ): Promise<void> {\n    if (!usageConfig.enabled || this._aiUsageHandlers.length === 0) {\n      return;\n    }\n\n    const normalizedEvent = this.normalizeAiUsageEvent(event, aiConfig);\n    if (!normalizedEvent) {\n      return;\n    }\n\n    if (usageConfig.estimateCosts) {\n      normalizedEvent.estimatedCost = estimateAiUsageCost(\n        normalizedEvent.provider,\n        normalizedEvent.model,\n        normalizedEvent.usage,\n        usageConfig.costRates,\n      );\n    }\n\n    const results = await Promise.allSettled(\n      this._aiUsageHandlers.map((handler) => handler.handle(normalizedEvent)),\n    );\n\n    for (const result of results) {\n      if (result.status === 'rejected') {\n        logger.warn(\n          `[smrt] AI usage handler failed for ${normalizedEvent.provider}:${normalizedEvent.model}: ${\n            result.reason instanceof Error\n              ? result.reason.message\n              : String(result.reason)\n          }`,\n        );\n      }\n    }\n  }\n\n  private normalizeAiUsageEvent(\n    event: unknown,\n    aiConfig: Record<string, unknown>,\n  ): SmrtAiUsageEvent | undefined {\n    const raw = (event ?? {}) as Record<string, unknown>;\n    const provider = firstString(\n      raw.provider,\n      raw.type,\n      aiConfig.provider,\n      aiConfig.type,\n    );\n    const model = firstString(\n      raw.model,\n      raw.defaultModel,\n      aiConfig.model,\n      aiConfig.defaultModel,\n    );\n    const operation =\n      firstString(raw.operation, raw.kind, raw.method) ?? 'unknown';\n    const usage =\n      normalizeIncomingAiUsageTokens(raw.usage) ??\n      normalizeIncomingAiUsageTokens(raw.tokenUsage) ??\n      normalizeIncomingAiUsageTokens({\n        promptTokens: raw.promptTokens,\n        completionTokens: raw.completionTokens,\n        totalTokens: raw.totalTokens,\n      });\n\n    if (!provider || !model) {\n      return undefined;\n    }\n\n    const duration =\n      firstNumber(raw.duration, raw.durationMs, raw.latency) ?? 0;\n    const tenantId =\n      'tenantId' in this &&\n      (this as { tenantId?: string | null }).tenantId !== undefined\n        ? ((this as { tenantId?: string | null }).tenantId ?? null)\n        : undefined;\n\n    return {\n      provider,\n      model,\n      operation,\n      usage,\n      duration,\n      timestamp: normalizeAiUsageTimestamp(raw.timestamp),\n      tags: normalizeAiUsageTags(raw.tags),\n      className: this._className,\n      tenantId,\n    };\n  }\n}\n"],"mappings":"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"}