@happyvertical/smrt-core 0.30.0

package/dist/object.js

@@ -0,0 +1,2731 @@
+import { createLogger } from "@happyvertical/logger";
+import { SmrtClass } from "./class.js";
+import { resolveDbCacheKey, invalidateCollectionCache, broadcastCacheInvalidation, hasCrossProcessCacheInterest } from "./collection-cache.js";
+import { ContentHasher } from "./embeddings/hash.js";
+import { EmbeddingProvider } from "./embeddings/provider.js";
+import { EmbeddingStorage } from "./embeddings/storage.js";
+import { ErrorUtils, DatabaseError, ValidationError, SmrtError, RuntimeError, TenantIsolationError } from "./errors.js";
+import { createInterceptorContext, GlobalInterceptors } from "./interceptors.js";
+import { ObjectRegistry } from "./registry.js";
+import { verifyPersistenceTable } from "./schema/table-verifier.js";
+import { executeToolCall } from "./tools/tool-executor.js";
+import { fieldsFromClass, tableNameFromClass } from "./utils.js";
+import { toSnakeCase } from "./utils/naming.js";
+const logger = createLogger({
+  level: process.env.DEBUG_STI ? "debug" : "info"
+});
+const AI_PROMPT_DATA_MAX_LENGTH = 1e5;
+function isValidMetaType(actualMetaType, className) {
+  if (typeof actualMetaType !== "string") {
+    return false;
+  }
+  if (actualMetaType === className) {
+    return true;
+  }
+  const registeredClass = ObjectRegistry.getClass(className);
+  if (registeredClass?.qualifiedName && actualMetaType === registeredClass.qualifiedName) {
+    return true;
+  }
+  return false;
+}
+function getExpectedMetaType(className) {
+  const registeredClass = ObjectRegistry.getClass(className);
+  return registeredClass?.qualifiedName || className;
+}
+function getSTIHierarchyMembers(qualifiedOrSimpleName) {
+  const registered = ObjectRegistry.getClass(qualifiedOrSimpleName);
+  const lookupKey = registered?.qualifiedName ?? registered?.name ?? qualifiedOrSimpleName;
+  const stiBase = ObjectRegistry.getSTIBase(lookupKey);
+  if (!stiBase) {
+    return [];
+  }
+  return Array.from(
+    /* @__PURE__ */ new Set([stiBase, ...ObjectRegistry.getDescendants(stiBase)])
+  );
+}
+let didWarnSkipRehydrate = false;
+function warnIfSkipRehydrateSet() {
+  if (didWarnSkipRehydrate) return;
+  didWarnSkipRehydrate = true;
+  if (process.env.SMRT_SKIP_STI_REHYDRATE !== void 0) {
+    logger.warn(
+      "[smrt] SMRT_SKIP_STI_REHYDRATE is set but has no effect since Release C (#1134). The flag is retired; unconditional STI descendant rehydration is the only behavior. Remove the env variable from your configuration. See issue #1139 for the perf follow-up."
+    );
+  }
+}
+class SmrtObject extends SmrtClass {
+  /**
+   * Database table name for this object
+   */
+  _tableName;
+  /**
+   * Cache for loaded relationships to avoid repeated database queries
+   * Maps fieldName to loaded object(s)
+   */
+  _loadedRelationships = /* @__PURE__ */ new Map();
+  /**
+   * Whether this object is backed by an existing database row.
+   *
+   * Set when the object is hydrated from the database (collection
+   * get/list/query, `loadFromId()`, `loadFromSlug()`) and after a successful
+   * `save()`. `save()` uses it to target the primary key on upsert instead
+   * of the natural-key conflict columns, so natural-key edits (e.g. renaming
+   * a slug) update the existing row rather than colliding on `*_pkey`
+   * (issue #1472).
+   */
+  _persisted = false;
+  /**
+   * Unique identifier for the object
+   */
+  _id;
+  /**
+   * URL-friendly identifier
+   */
+  _slug;
+  /**
+   * Optional context to scope the slug
+   */
+  _context;
+  /**
+   * Creation timestamp
+   */
+  created_at = null;
+  /**
+   * Last update timestamp
+   */
+  updated_at = null;
+  /**
+   * Creates a new SmrtObject instance
+   *
+   * @param options - Configuration options including identifiers and metadata
+   * @throws Error if options is null
+   */
+  constructor(options = {}) {
+    super(options);
+    this.options = options;
+    if (options === null) {
+      throw new Error("options cant be null");
+    }
+    this._id = options.id || null;
+    this._slug = options.slug || null;
+    this._context = options.context || "";
+    if (this.constructor !== SmrtObject && !ObjectRegistry.getClassByConstructor(
+      this.constructor
+    ) && !options?._skipRegistration) {
+      ObjectRegistry.register(this.constructor, {});
+    }
+  }
+  getRegisteredClassInfo() {
+    return ObjectRegistry.getClassByConstructor(
+      this.constructor
+    );
+  }
+  getResolvedClassName() {
+    return this.getRegisteredClassInfo()?.name || this.constructor.name;
+  }
+  getResolvedQualifiedName() {
+    const registered = this.getRegisteredClassInfo();
+    return registered?.qualifiedName || registered?.name || this.constructor.name;
+  }
+  getCurrentMetaType() {
+    const metaType = this._meta_type;
+    return typeof metaType === "string" ? metaType : void 0;
+  }
+  isLegacySTIDiscriminatorUpgrade(currentMetaType, nextMetaType, className) {
+    return typeof nextMetaType === "string" && typeof currentMetaType === "string" && currentMetaType !== nextMetaType && !currentMetaType.includes(":") && isValidMetaType(currentMetaType, className) && isValidMetaType(nextMetaType, className);
+  }
+  async planPersistenceWrite(className, tableStrategy, data, conflictColumns) {
+    const upsertPlan = {
+      type: "upsert",
+      conflictColumns
+    };
+    if (tableStrategy !== "sti" || !data.id) {
+      return upsertPlan;
+    }
+    const currentMetaType = this.getCurrentMetaType();
+    const nextMetaType = data._meta_type;
+    if (!this.isLegacySTIDiscriminatorUpgrade(
+      currentMetaType,
+      nextMetaType,
+      className
+    )) {
+      return upsertPlan;
+    }
+    const qualifiedMetaType = String(nextMetaType);
+    const conflictIdentity = {};
+    for (const column of conflictColumns.filter(
+      (conflictColumn) => conflictColumn !== "_meta_type"
+    )) {
+      if (!Object.hasOwn(data, column)) {
+        return upsertPlan;
+      }
+      conflictIdentity[column] = data[column];
+    }
+    const id = String(data.id);
+    const existingById = await ErrorUtils.withRetry(
+      async () => {
+        try {
+          return await this.db.get(this.tableName, { id });
+        } catch (error) {
+          throw DatabaseError.queryFailed(
+            `get(${this.tableName}, legacy STI id)`,
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+      },
+      3,
+      500
+    );
+    if (!existingById || existingById._meta_type !== currentMetaType) {
+      return upsertPlan;
+    }
+    const slug = String(data.slug ?? "");
+    const context = String(data.context ?? "");
+    const existingQualified = await ErrorUtils.withRetry(
+      async () => {
+        try {
+          return await this.db.get(this.tableName, {
+            ...conflictIdentity,
+            _meta_type: qualifiedMetaType
+          });
+        } catch (error) {
+          throw DatabaseError.queryFailed(
+            `get(${this.tableName}, qualified STI conflict identity)`,
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+      },
+      3,
+      500
+    );
+    if (existingQualified && existingQualified.id !== id) {
+      throw DatabaseError.stiDiscriminatorConflict({
+        className,
+        tableName: this.tableName,
+        id,
+        slug,
+        context,
+        conflictIdentity,
+        legacyMetaType: currentMetaType,
+        qualifiedMetaType,
+        duplicateId: String(existingQualified.id)
+      });
+    }
+    return { type: "updateById", qualifiedMetaType };
+  }
+  /**
+   * Protected setter for ID to maintain type safety
+   * Used internally by collection.create() and other framework code
+   * @internal
+   */
+  setId(id) {
+    this._id = id;
+  }
+  /**
+   * Whether this object is backed by an existing database row.
+   *
+   * True after hydration from the database (collection get/list/query,
+   * `loadFromId()`, `loadFromSlug()`) or after a successful `save()`.
+   */
+  get isPersisted() {
+    return this._persisted;
+  }
+  /**
+   * Marks this object as backed by an existing database row, so `save()`
+   * targets the primary key instead of the natural-key conflict columns.
+   * Called by framework hydration paths (issue #1472).
+   * @internal
+   */
+  markAsPersisted() {
+    this._persisted = true;
+  }
+  async verifyStorageReady() {
+    await verifyPersistenceTable(
+      this.db,
+      this.tableName,
+      this.constructor.name
+    );
+  }
+  /**
+   * Protected setter for STI discriminator to maintain type safety
+   * Used internally for Single Table Inheritance support
+   * @internal
+   */
+  setMetaType(metaType) {
+    this._meta_type = metaType;
+  }
+  /**
+   * Smart clone helper to avoid array/object aliasing (Issue #22)
+   *
+   * Clones values to prevent shared references between options and instance properties:
+   * - Primitives (string, number, boolean, null, undefined): No clone needed
+   * - Dates: No clone needed (immutable)
+   * - Field instances: No clone needed (framework objects)
+   * - Arrays: Shallow clone
+   * - Plain objects: Shallow clone
+   * - Other objects: Pass through (class instances, etc.)
+   *
+   * @param value - Value to clone
+   * @returns Cloned value or original if no cloning needed
+   * @private
+   */
+  cloneValue(value) {
+    if (value === null || value === void 0) return value;
+    if (typeof value !== "object") return value;
+    if (value instanceof Date) return value;
+    if (Array.isArray(value)) return [...value];
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null || proto === Object.prototype) {
+      return { ...value };
+    }
+    return value;
+  }
+  /**
+   * Initialize properties from options after field initializers have run
+   * This ensures option values take precedence over default field initializer values
+   * Uses smart cloning to prevent array/object aliasing (Issue #22)
+   */
+  async initializePropertiesFromOptions() {
+    const options = this.options;
+    if (options.created_at !== void 0) this.created_at = options.created_at;
+    if (options.updated_at !== void 0) this.updated_at = options.updated_at;
+    if (options._meta_type !== void 0) {
+      this.setMetaType(options._meta_type);
+    }
+    const fields = await fieldsFromClass(
+      this.constructor
+    );
+    for (const [key, field] of Object.entries(fields)) {
+      if (options[key] !== void 0) {
+        const clonedValue = this.cloneValue(options[key]);
+        let descriptor = Object.getOwnPropertyDescriptor(this, key);
+        if (!descriptor) {
+          let proto = Object.getPrototypeOf(this);
+          while (proto && !descriptor) {
+            descriptor = Object.getOwnPropertyDescriptor(proto, key);
+            proto = Object.getPrototypeOf(proto);
+          }
+        }
+        if (!descriptor || descriptor.set || descriptor.writable === true) {
+          this[key] = clonedValue;
+        }
+      }
+    }
+  }
+  /**
+   * Gets the unique identifier for this object
+   */
+  get id() {
+    return this._id;
+  }
+  /**
+   * Sets the unique identifier for this object
+   *
+   * @param value - The ID to set
+   * @throws Error if the value is invalid
+   */
+  set id(value) {
+    if (!value || value === "undefined" || value === "null") {
+      throw new Error(`id is required, ${value} given`);
+    }
+    this._id = value;
+  }
+  /**
+   * Gets the URL-friendly slug for this object
+   */
+  get slug() {
+    return this._slug;
+  }
+  /**
+   * Sets the URL-friendly slug for this object
+   *
+   * @param value - The slug to set
+   * @throws Error if the value is invalid
+   */
+  set slug(value) {
+    if (!value || value === "undefined" || value === "null") {
+      throw new Error(`slug is invalid, ${value} given`);
+    }
+    this._slug = value;
+  }
+  /**
+   * Gets the context that scopes this object's slug
+   */
+  get context() {
+    return this._context || "";
+  }
+  /**
+   * Sets the context that scopes this object's slug
+   *
+   * @param value - The context to set
+   * @throws Error if the value is invalid
+   */
+  set context(value) {
+    if (value !== "" && !value) {
+      throw new Error(`context is invalid, ${value} given`);
+    }
+    this._context = value;
+  }
+  /**
+   * Initializes this object and optionally loads its data from the database.
+   *
+   * Initialization order:
+   * 1. Runs TypeScript field initializers (class property defaults)
+   * 2. Applies `options` values on top of defaults (options win)
+   * 3. If `options.id` is set, calls `loadFromId()` to hydrate from DB
+   * 4. If `options.slug` is set (and no id), calls `loadFromSlug()` instead
+   *
+   * Runtime schema verification is deferred until the first actual DB
+   * operation, which keeps initialization safe for SSR and prerendering
+   * without mutating application schema.
+   *
+   * Called automatically by collection methods. Call manually only when
+   * constructing objects outside of a collection.
+   *
+   * @returns This instance, ready to use (enables chaining)
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ db: myDb, id: 'existing-uuid' });
+   * await product.initialize(); // loads product data from DB
+   * console.log(product.name);
+   * ```
+   */
+  async initialize() {
+    await super.initialize();
+    if (!this.options._extractingFields) {
+      await this.initializePropertiesFromOptions();
+    }
+    if (this._id && !this.options._skipLoad) {
+      await this.loadFromId();
+    } else if (this._slug && !this.options._skipLoad) {
+      await this.loadFromSlug();
+    }
+    return this;
+  }
+  /**
+   * Determines if this class needs automatic property initialization from options
+   *
+   * Decorator-based classes handle property assignment in their constructor,
+   * so they don't need the automatic property initialization logic.
+   * This optimization avoids redundant work and Field instance handling.
+   *
+   * @returns True if property initialization is needed, false otherwise
+   * @private
+   */
+  needsPropertyInitialization() {
+    const className = this.getResolvedClassName();
+    if (ObjectRegistry.hasClass(className)) {
+      const hasDecorators = ObjectRegistry.hasFieldDecorators(className);
+      if (hasDecorators) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Loads data from a database row into this object's properties
+   *
+   * STI Support: If using Single Table Inheritance (tableStrategy: 'sti'):
+   * - Merges _meta_data JSONB fields into the main data object
+   * - Validates _meta_type discriminator matches class name
+   *
+   * @param data - Database row data (with snake_case column names)
+   * @throws Error if STI validation fails
+   */
+  async loadDataFromDb(data) {
+    const className = this.getResolvedClassName();
+    if (process.env.DEBUG_STI) {
+      logger.debug("[loadDataFromDb] Loading", {
+        class: className,
+        dataKeys: Object.keys(data),
+        metaType: data._meta_type
+      });
+    }
+    const fields = await this.getFields();
+    if (process.env.DEBUG_STI) {
+      logger.debug("[loadDataFromDb] Field definitions", {
+        class: className,
+        fieldKeys: Object.keys(fields)
+      });
+    }
+    const { formatDataJs } = await import("./utils.js");
+    const formattedData = formatDataJs(data, fields);
+    const tableStrategy = ObjectRegistry.getTableStrategy(
+      this.getResolvedQualifiedName()
+    );
+    const isSTI = tableStrategy === "sti";
+    if (process.env.DEBUG_STI) {
+      logger.debug("[loadDataFromDb] After formatDataJs", {
+        class: className,
+        isSTI,
+        formattedDataKeys: Object.keys(formattedData)
+      });
+    }
+    if (isSTI) {
+      if (!formattedData._meta_type) {
+        throw new Error(
+          `STI validation failed: Missing _meta_type discriminator in database row for ${className}. Ensure the row was saved with STI support enabled.`
+        );
+      }
+      if (!isValidMetaType(formattedData._meta_type, className)) {
+        throw new Error(
+          `STI validation failed: Type mismatch when loading ${className}. Database row has _meta_type='${formattedData._meta_type}' but expected '${getExpectedMetaType(className)}'. This usually means you're trying to load a row with the wrong class.`
+        );
+      }
+      this.setMetaType(formattedData._meta_type);
+    }
+    if (process.env.DEBUG_STI) {
+      logger.debug("[loadDataFromDb] Starting field hydration", {
+        class: className,
+        fieldCount: Object.keys(fields).length
+      });
+    }
+    let hydratedCount = 0;
+    let skippedCount = 0;
+    for (const field in fields) {
+      if (Object.hasOwn(fields, field)) {
+        let descriptor = Object.getOwnPropertyDescriptor(this, field);
+        if (!descriptor) {
+          let proto = Object.getPrototypeOf(this);
+          while (proto && !descriptor) {
+            descriptor = Object.getOwnPropertyDescriptor(proto, field);
+            proto = Object.getPrototypeOf(proto);
+          }
+        }
+        if (!descriptor || descriptor.set || descriptor.writable === true) {
+          const value = formattedData[field];
+          if (process.env.DEBUG_STI && value !== void 0) {
+            logger.debug(`[loadDataFromDb] Setting field '${field}'`, {
+              value,
+              valueType: typeof value
+            });
+          }
+          this[field] = value;
+          hydratedCount++;
+        } else {
+          skippedCount++;
+          if (process.env.DEBUG_STI) {
+            logger.debug(`[loadDataFromDb] Skipping readonly field '${field}'`);
+          }
+        }
+      }
+    }
+    if (process.env.DEBUG_STI) {
+      logger.debug("[loadDataFromDb] Hydration complete", {
+        class: className,
+        hydratedCount,
+        skippedCount,
+        totalFields: Object.keys(fields).length
+      });
+    }
+    this._persisted = true;
+  }
+  /**
+   * Gets the database table name for this object
+   */
+  get tableName() {
+    if (!this._tableName) {
+      const className = this.getResolvedClassName();
+      const qualifiedName = this.getResolvedQualifiedName();
+      const tableStrategy = ObjectRegistry.getTableStrategy(qualifiedName);
+      if (tableStrategy === "sti") {
+        const stiBase = ObjectRegistry.getSTIBase(qualifiedName);
+        if (stiBase) {
+          const baseSchema = ObjectRegistry.getSchema(stiBase);
+          if (baseSchema?.tableName) {
+            this._tableName = baseSchema.tableName;
+          } else {
+            const ownSchema = ObjectRegistry.getSchema(className);
+            this._tableName = ownSchema?.tableName || tableNameFromClass(this.constructor);
+          }
+        } else {
+          const ownSchema = ObjectRegistry.getSchema(className);
+          this._tableName = ownSchema?.tableName || tableNameFromClass(this.constructor);
+        }
+      } else {
+        const ownSchema = ObjectRegistry.getSchema(className);
+        this._tableName = ownSchema?.tableName || tableNameFromClass(this.constructor);
+      }
+    }
+    return this._tableName;
+  }
+  /**
+   * Gets field definitions and current values for this object
+   *
+   * @returns Object containing field definitions with current values
+   */
+  async getFields() {
+    const className = this.getResolvedClassName();
+    const cachedFields = await ObjectRegistry.getAllFields(className);
+    const fields = {};
+    for (const [key, field] of cachedFields.entries()) {
+      const meta = { ...field._meta || {} };
+      delete meta.__smrtSystemField;
+      fields[key] = {
+        name: key,
+        type: field.type || "TEXT",
+        _meta: meta
+      };
+    }
+    for (const key in fields) {
+      fields[key].value = this.getPropertyValue(key);
+    }
+    return fields;
+  }
+  /**
+   * Override hook for customizing JSON serialization output.
+   *
+   * This is the **only safe way** to customize serialization. Do **not** override
+   * `toJSON()` directly — it manages STI discriminator assignment (`_meta_type`),
+   * meta-field extraction into `_meta_data`, and manifest-driven field enumeration.
+   * Overriding it will silently break STI persistence.
+   *
+   * The `data` argument already contains all persisted fields. Return a new object
+   * (spread `data` and add/modify/remove keys) to change what is serialized.
+   * Non-persisted computed properties added here are excluded from `save()` because
+   * the DB write path uses `toJSON()` output, not this hook's additions — unless
+   * those keys also correspond to real schema columns.
+   *
+   * @param data - Fully serialized object produced by the framework's `toJSON()` logic
+   * @returns Transformed data to use as the final serialization result
+   *
+   * @example
+   * ```typescript
+   * class Article extends SmrtObject {
+   *   body: string = '';
+   *
+   *   protected transformJSON(data: any): any {
+   *     return {
+   *       ...data,
+   *       wordCount: this.body.split(/\s+/).length,
+   *       preview: this.body.substring(0, 100),
+   *     };
+   *   }
+   * }
+   * ```
+   *
+   * @see {@link toJSON} for the framework implementation (do not override)
+   */
+  transformJSON(data) {
+    return data;
+  }
+  /**
+   * Custom JSON serialization
+   * Returns a plain object with all field values for proper JSON.stringify() behavior
+   * Field instances automatically call their toJSON() method during serialization
+   *
+   * Issue #205: Filters out undefined values to prevent database errors
+   *
+   * Note: This method cannot be async because JSON.stringify() expects synchronous toJSON()
+   * It uses direct property access instead of getFields() to avoid async issues
+   *
+   * STI Support: If using Single Table Inheritance (tableStrategy: 'sti'):
+   * - Sets _meta_type discriminator to class name
+   * - Extracts meta fields to _meta_data JSONB column
+   *
+   * **Customization:** Override `transformJSON()` instead of this method.
+   * See transformJSON() documentation for safe customization patterns.
+   */
+  toJSON() {
+    const className = this.getResolvedClassName();
+    const data = {
+      id: this.id,
+      slug: this.slug,
+      context: this.context,
+      created_at: this.created_at,
+      updated_at: this.updated_at
+    };
+    const tableStrategy = ObjectRegistry.getTableStrategy(
+      this.getResolvedQualifiedName()
+    );
+    const isSTI = tableStrategy === "sti";
+    if (isSTI) {
+      data._meta_type = this.getResolvedQualifiedName();
+      data._meta_data = {};
+    }
+    const registered = ObjectRegistry.getClass(className);
+    let registeredFields = registered?.inheritedFields || ObjectRegistry.getFields(className);
+    if (isSTI) {
+      const descendants = getSTIHierarchyMembers(
+        this.getResolvedQualifiedName()
+      );
+      if (descendants.length > 0) {
+        const allSTIFields = new Map(registeredFields);
+        for (const descendant of descendants) {
+          const descendantFields = ObjectRegistry.getClass(descendant)?.inheritedFields || ObjectRegistry.getFields(descendant);
+          for (const [key, value] of descendantFields) {
+            if (!allSTIFields.has(key)) {
+              allSTIFields.set(key, value);
+            }
+          }
+        }
+        registeredFields = allSTIFields;
+      }
+    }
+    for (const key of registeredFields.keys()) {
+      if (key.startsWith("_") || key === "id" || key === "slug" || key === "context" || key === "created_at" || key === "updated_at" || key === "options" || // Skip options object (not a database column)
+      typeof this[key] === "function") {
+        continue;
+      }
+      const fieldDef = registeredFields.get(key);
+      if (fieldDef && (fieldDef.transient || fieldDef._meta?.transient)) {
+        continue;
+      }
+      if (fieldDef && (fieldDef.type === "oneToMany" || fieldDef.type === "manyToMany")) {
+        continue;
+      }
+      const prop = this[key];
+      const value = this.getPropertyValue(key);
+      if (value === void 0) {
+        const fieldType = prop && typeof prop === "object" && "type" in prop && prop.type || fieldDef?.type;
+        if (fieldType === "text") {
+          const hasTenancyMarker = prop && typeof prop === "object" && "__tenancy" in prop && prop.__tenancy?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField;
+          if (hasTenancyMarker) {
+            if (isSTI && fieldDef?.type === "meta") {
+              data._meta_data[key] = null;
+            } else {
+              data[key] = null;
+            }
+          } else {
+            if (isSTI && fieldDef?.type === "meta") {
+              data._meta_data[key] = "";
+            } else {
+              data[key] = "";
+            }
+          }
+        } else if (fieldType === "json") {
+          const defaultValue = fieldDef?.default ?? null;
+          if (isSTI && fieldDef?.type === "meta") {
+            data._meta_data[key] = defaultValue;
+          } else {
+            data[key] = defaultValue;
+          }
+        }
+        continue;
+      }
+      if (isSTI && fieldDef && fieldDef.type === "meta") {
+        data._meta_data[key] = value;
+      } else {
+        data[key] = value;
+      }
+    }
+    return this.transformJSON(data);
+  }
+  /**
+   * Converts this object to a plain JavaScript object (POJO)
+   *
+   * Unlike toJSON() which returns an object that can still be a class instance,
+   * this method returns a true plain object suitable for:
+   * - SvelteKit's load function returns (requires serializable data)
+   * - Passing data through web workers
+   * - Any context requiring non-class objects
+   *
+   * @returns Plain JavaScript object with all field values
+   *
+   * @example
+   * ```typescript
+   * // In a SvelteKit +page.server.ts load function:
+   * const users = await userCollection.list();
+   * return {
+   *   users: users.map(u => u.toPlainObject())
+   * };
+   * ```
+   */
+  toPlainObject() {
+    return JSON.parse(JSON.stringify(this));
+  }
+  /**
+   * Collects the property names of fields marked `@field({ sensitive: true })`
+   * for this instance's class (and, under STI, every member of its hierarchy,
+   * since `toJSON()` merges sibling fields into the serialized payload).
+   *
+   * Reads both the first-class `sensitive` flag and the `_meta.sensitive`
+   * mirror so it works regardless of whether the field metadata came from the
+   * AST manifest or a runtime `@field()` decorator registration.
+   */
+  getSensitiveFieldNames() {
+    const className = this.getResolvedClassName();
+    const registered = ObjectRegistry.getClass(className);
+    const fieldMaps = [
+      registered?.inheritedFields || ObjectRegistry.getFields(className)
+    ];
+    const tableStrategy = ObjectRegistry.getTableStrategy(
+      this.getResolvedQualifiedName()
+    );
+    if (tableStrategy === "sti") {
+      const descendants = getSTIHierarchyMembers(
+        this.getResolvedQualifiedName()
+      );
+      for (const descendant of descendants) {
+        fieldMaps.push(
+          ObjectRegistry.getClass(descendant)?.inheritedFields || ObjectRegistry.getFields(descendant)
+        );
+      }
+    }
+    const sensitive = /* @__PURE__ */ new Set();
+    for (const fields of fieldMaps) {
+      for (const [key, def] of fields) {
+        if (def && (def.sensitive === true || def._meta?.sensitive === true)) {
+          sensitive.add(key);
+        }
+      }
+    }
+    return sensitive;
+  }
+  /**
+   * Public-safe serialization for network surfaces.
+   *
+   * Returns the same shape as `toJSON()` but with every `sensitive` field
+   * removed (including STI meta fields nested under `_meta_data`). This is the
+   * serializer used by the generated REST / MCP / SvelteKit routes so that
+   * secret columns (API secrets, credentials, tax IDs) are never returned over
+   * the wire, while `toJSON()` continues to carry them for database persistence.
+   *
+   * @returns A plain object safe to send to API consumers.
+   */
+  toPublicJSON() {
+    const json = this.toJSON();
+    const sensitiveFields = this.getSensitiveFieldNames();
+    if (sensitiveFields.size === 0) {
+      return json;
+    }
+    const metaData = json._meta_data && typeof json._meta_data === "object" ? json._meta_data : null;
+    for (const name of sensitiveFields) {
+      delete json[name];
+      if (metaData) {
+        delete metaData[name];
+      }
+    }
+    return json;
+  }
+  /**
+   * Gets or generates a unique ID for this object
+   *
+   * @returns Promise resolving to the object's ID
+   */
+  async getId() {
+    if (this.slug) {
+      await this.verifyStorageReady();
+      const saved = await this.db.get(this.tableName, {
+        slug: this.slug,
+        context: this.context
+      });
+      if (saved) {
+        this.id = saved.id;
+      }
+    }
+    if (!this.id) {
+      this.id = crypto.randomUUID();
+    }
+    return this.id;
+  }
+  /**
+   * Returns the slug for this object, generating one if not already set.
+   *
+   * Generation falls back through the following fields in order:
+   * `name` → `title` → `label` → `id`
+   *
+   * The generated slug is lowercased, with non-alphanumeric characters
+   * replaced by hyphens and leading/trailing hyphens stripped.
+   *
+   * Called automatically by `save()` when no slug is present.
+   *
+   * @returns The existing slug or a newly generated one (may be `null` if
+   *   none of the fallback fields and `id` are set)
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ name: 'My Widget' });
+   * console.log(await product.getSlug()); // 'my-widget'
+   * ```
+   */
+  async getSlug() {
+    if (!this.slug) {
+      let sourceField = null;
+      if (this.name) {
+        sourceField = String(this.name);
+      } else if (this.title) {
+        sourceField = String(this.title);
+      } else if (this.label) {
+        sourceField = String(this.label);
+      } else if (this.id) {
+        sourceField = String(this.id);
+      }
+      if (sourceField) {
+        this.slug = sourceField.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+      }
+    }
+    return this.slug;
+  }
+  /**
+   * Gets the ID of this object if it's already saved in the database
+   *
+   * @returns Promise resolving to the saved ID or null if not saved
+   */
+  async getSavedId() {
+    if (!this.id && !this.slug) {
+      return null;
+    }
+    await this.verifyStorageReady();
+    if (this.id) {
+      const byId = await this.db.get(this.tableName, { id: this.id });
+      if (byId) return byId.id;
+    }
+    if (this.slug) {
+      const bySlug = await this.db.get(this.tableName, { slug: this.slug });
+      if (bySlug) return bySlug.id;
+    }
+    return null;
+  }
+  /**
+   * Checks if this object is already saved in the database
+   *
+   * @returns Promise resolving to true if saved, false otherwise
+   */
+  async isSaved() {
+    const saved = await this.getSavedId();
+    return !!saved;
+  }
+  /**
+   * Resolve the set of snake_case column names whose database type is `UUID`
+   * for the table this object writes to.
+   *
+   * Declared foreign keys (`@foreignKey()`) and cross-package references
+   * (`@crossPackageRef()`) generate native `UUID` columns (R11). Their default
+   * declared value in TypeScript is the empty string (`''`), which is not a
+   * valid UUID literal. Postgres rejects `''` on a `uuid` column with
+   * `invalid input syntax for type uuid`, so any optional/unset declared FK
+   * (a root entity's self-reference, an optional cross-package link, etc.)
+   * would fail to insert. We coerce `''` → `NULL` for these columns before
+   * binding (see {@link coerceEmptyUuidValuesToNull}); this method tells that
+   * coercion which columns are UUID-typed.
+   *
+   * Resolution prefers the built schema (`getSchema().columns`), which already
+   * reflects all reconciliation — e.g. a `@foreignKey()` whose target class
+   * uses `idType: 'text'` is downgraded to `TEXT` and is therefore correctly
+   * excluded here. For STI children, columns live on the STI base table, so we
+   * union the base schema's columns. When no built schema is available (pure
+   * runtime-registered classes without a manifest) we fall back to field
+   * metadata, mirroring the schema-builder's field→SQL mapping.
+   */
+  async resolveUuidColumnNames(className) {
+    const uuidColumns = /* @__PURE__ */ new Set();
+    const collectFromSchema = (schemaName) => {
+      if (!schemaName) return;
+      const schema = ObjectRegistry.getSchema(schemaName);
+      const columns = schema?.columns;
+      if (!columns) return;
+      for (const [columnName, columnDef] of Object.entries(columns)) {
+        if (columnDef?.type === "UUID") {
+          uuidColumns.add(columnName);
+        }
+      }
+    };
+    collectFromSchema(className);
+    const qualifiedName = this.getResolvedQualifiedName();
+    if (ObjectRegistry.getTableStrategy(qualifiedName) === "sti") {
+      collectFromSchema(ObjectRegistry.getSTIBase(qualifiedName));
+    }
+    if (uuidColumns.size > 0) {
+      return uuidColumns;
+    }
+    try {
+      const fields = await ObjectRegistry.getAllFields(className);
+      for (const [fieldName, field] of fields.entries()) {
+        if (!field) continue;
+        const type = field.type;
+        if (type !== "foreignKey" && type !== "crossPackageRef") {
+          continue;
+        }
+        const metaSqlType = field._meta?.sqlType;
+        if (metaSqlType) {
+          if (metaSqlType === "UUID") {
+            uuidColumns.add(toSnakeCase(fieldName));
+          }
+          continue;
+        }
+        const isTextIdCrossRef = type === "crossPackageRef" && (field._meta?.idType === "text" || field.idType === "text");
+        if (!isTextIdCrossRef) {
+          uuidColumns.add(toSnakeCase(fieldName));
+        }
+      }
+    } catch {
+    }
+    return uuidColumns;
+  }
+  /**
+   * Coerce empty-string values to `NULL` for UUID-typed columns in the
+   * snake_cased write payload.
+   *
+   * Framework-level fix for the whole class of bug where a declared FK field
+   * defaults to `''` (the natural TypeScript default for `string`) and is left
+   * unset on insert — e.g. creating a ROOT entity whose optional self-reference
+   * (`previousFactId`, `parentPartnerId`, …) is empty. On Postgres `uuid`
+   * columns, `''` raises `invalid input syntax for type uuid`. Coercing to
+   * `NULL` here fixes every such field uniformly without per-field type churn
+   * or consumer-facing type changes. Mutates `data` in place.
+   */
+  async coerceEmptyUuidValuesToNull(className, data) {
+    const uuidColumns = await this.resolveUuidColumnNames(className);
+    if (uuidColumns.size === 0) return;
+    for (const columnName of uuidColumns) {
+      if (data[columnName] === "") {
+        data[columnName] = null;
+      }
+    }
+  }
+  /**
+   * Persists this object to the database using an upsert (insert or update).
+   *
+   * Steps performed on every save:
+   * 1. Runs field-level validation (`validateBeforeSave()`)
+   * 2. Executes `beforeSave` interceptors (e.g. tenant injection)
+   * 3. Assigns a UUID `id` if not already set
+   * 4. Generates a `slug` via `getSlug()` if not already set
+   * 5. Updates `updated_at` (and sets `created_at` on first save)
+   * 6. Upserts the row with automatic retry (3 attempts, 500 ms backoff)
+   * 7. Executes `afterSave` interceptors
+   * 8. Triggers embedding generation in the background if configured
+   *
+   * For STI classes, validates that `_meta_type` is present and correct
+   * before writing to the database.
+   *
+   * @returns This instance after saving (enables chaining)
+   * @throws {ValidationError} If a required field is missing or a unique constraint is violated
+   * @throws {DatabaseError} If the table does not exist (`DB_SCHEMA_MISSING`) or the query fails
+   * @throws {RuntimeError} For any other unexpected failure during save
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ db: myDb, name: 'Widget', price: 9.99 });
+   * await product.initialize();
+   * await product.save();
+   * console.log(product.id); // UUID assigned during save
+   *
+   * // Update
+   * product.price = 14.99;
+   * await product.save();
+   * ```
+   */
+  async save() {
+    const className = this.getResolvedClassName();
+    try {
+      await this.validateBeforeSave();
+      await this.validateCrossPackageRefs();
+      const interceptorContext = createInterceptorContext(className, "save");
+      await GlobalInterceptors.executeBeforeSave(this, interceptorContext);
+      if (!this.id) {
+        this.id = crypto.randomUUID();
+      }
+      if (!this.slug) {
+        this.slug = await this.getSlug();
+      }
+      this.updated_at = /* @__PURE__ */ new Date();
+      if (!this.created_at) {
+        this.created_at = /* @__PURE__ */ new Date();
+      }
+      await this.verifyStorageReady();
+      const tableStrategy = ObjectRegistry.getTableStrategy(
+        this.getResolvedQualifiedName()
+      );
+      if (process.env.NODE_ENV === "development") {
+        const hasOverride = this.toJSON !== SmrtObject.prototype.toJSON;
+        const usesSTI = tableStrategy === "sti";
+        if (hasOverride && usesSTI) {
+          logger.warn(
+            `[SMRT STI Warning] ${this.constructor.name} overrides toJSON() but uses STI.
+Ensure super.toJSON() is called or _meta_type is set manually.
+This can cause "Missing _meta_type discriminator" errors.
+Prefer using the transformJSON() hook instead of overriding toJSON().
+See issue #377: https://github.com/happyvertical/smrt/issues/377`
+          );
+        }
+      }
+      if (tableStrategy === "sti") {
+        warnIfSkipRehydrateSet();
+        const qualifiedName = this.getResolvedQualifiedName();
+        const classesNeedingFreshSTIFieldState = Array.from(
+          /* @__PURE__ */ new Set([qualifiedName, ...getSTIHierarchyMembers(qualifiedName)])
+        );
+        for (const stiClassName of classesNeedingFreshSTIFieldState) {
+          await ObjectRegistry.getAllFields(stiClassName);
+        }
+      }
+      const jsonData = this.toJSON();
+      if (tableStrategy === "sti") {
+        if (!jsonData._meta_type) {
+          throw new Error(
+            `STI validation failed: Missing _meta_type discriminator when saving ${className}. This should have been set automatically by toJSON(). Please report this bug.`
+          );
+        }
+        if (!isValidMetaType(jsonData._meta_type, className)) {
+          throw new Error(
+            `STI validation failed: _meta_type mismatch when saving ${className}. Expected '${getExpectedMetaType(className)}' but got '${jsonData._meta_type}'. This should not happen - please report this bug.`
+          );
+        }
+      }
+      const data = {};
+      for (const [key, value] of Object.entries(jsonData)) {
+        if (key.startsWith("_")) {
+          data[key] = value;
+        } else {
+          data[toSnakeCase(key)] = value;
+        }
+      }
+      await this.coerceEmptyUuidValuesToNull(className, data);
+      const conflictColumns = ObjectRegistry.getConflictColumns(className);
+      const writePlan = await this.planPersistenceWrite(
+        className,
+        tableStrategy,
+        data,
+        conflictColumns
+      );
+      const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
+      await ErrorUtils.withRetry(
+        async () => {
+          try {
+            if (writePlan.type === "updateById") {
+              const { id: _id, ...updateData } = data;
+              await this.db.update(this.tableName, { id: data.id }, updateData);
+              this.setMetaType(writePlan.qualifiedMetaType);
+            } else {
+              await this.db.upsert(this.tableName, upsertConflictColumns, data);
+            }
+          } catch (error) {
+            if (error instanceof Error) {
+              const kind = SmrtObject.classifyConstraintError(error.message);
+              if (kind === "unique") {
+                const field = this.extractConstraintField(error.message);
+                throw ValidationError.uniqueConstraint(
+                  field,
+                  this.getFieldValue(field)
+                );
+              }
+              if (kind === "not_null") {
+                const field = this.extractConstraintField(error.message);
+                throw ValidationError.requiredField(field, className);
+              }
+              const operation = writePlan.type === "updateById" ? `UPDATE ${this.tableName} (id-targeted)` : `UPSERT INTO ${this.tableName}`;
+              throw DatabaseError.queryFailed(operation, error);
+            }
+            throw error;
+          }
+        },
+        3,
+        500
+      );
+      this._persisted = true;
+      this.invalidateCollectionReadCache();
+      await GlobalInterceptors.executeAfterSave(this, interceptorContext);
+      const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(className);
+      const skipAutoEmbeddings = this.options._skipAutoEmbeddings === true;
+      if (embeddingConfig && embeddingConfig.autoGenerate !== false && !skipAutoEmbeddings) {
+        const aiClient = await this.getOptionalAiClient();
+        if (aiClient) {
+          const isStale = await this.hasStaleEmbeddings();
+          if (isStale) {
+            this.generateEmbeddings().catch((error) => {
+              logger.warn(
+                `Failed to auto-generate embeddings for ${this.constructor.name}`,
+                { error: error instanceof Error ? error.message : error }
+              );
+            });
+          }
+        }
+      }
+      if (skipAutoEmbeddings) {
+        this.options._skipAutoEmbeddings = false;
+      }
+      return this;
+    } catch (error) {
+      if (error instanceof SmrtError) {
+        throw error;
+      }
+      if (this.isTenantContractError(error)) {
+        throw error;
+      }
+      throw RuntimeError.operationFailed(
+        "save",
+        `${className}#${this.id}`,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  /**
+   * Detects tenant-boundary errors that must propagate from `save()` unwrapped.
+   *
+   * Matches both core's {@link TenantIsolationError} and the duck-typed
+   * tenancy-package errors (`TenantIsolationError` / `TenantContextError`) that
+   * the `beforeSave` interceptor throws. Those tenancy classes extend plain
+   * `Error` — core cannot import the tenancy package (the dependency runs the
+   * other way) — so they are matched by their stable `code` constants, with a
+   * class-name fallback for resilience.
+   */
+  isTenantContractError(error) {
+    if (error instanceof TenantIsolationError) {
+      return true;
+    }
+    const candidate = error;
+    const code = candidate?.code;
+    if (code === "TENANT_ISOLATION_VIOLATION" || code === "TENANT_CONTEXT_REQUIRED") {
+      return true;
+    }
+    const name = candidate?.name;
+    return name === "TenantIsolationError" || name === "TenantContextError";
+  }
+  /**
+   * Validates object state before saving
+   * Override in subclasses to add custom validation logic
+   */
+  async validateBeforeSave() {
+    const className = this.getResolvedClassName();
+    const validationRules = ObjectRegistry.getValidationRules(className);
+    if (validationRules && validationRules.length > 0) {
+      const errors = await ObjectRegistry.validateWithRules(
+        this,
+        validationRules,
+        className
+      );
+      if (errors.length > 0) {
+        throw errors[0];
+      }
+      return;
+    }
+    const validators = ObjectRegistry.getValidators(className);
+    if (validators && validators.length > 0) {
+      const errors = [];
+      for (const validator of validators) {
+        const error = await validator(this);
+        if (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length > 0) {
+        throw errors[0];
+      }
+      return;
+    }
+    const fields = await fieldsFromClass(this.constructor);
+    for (const [fieldName, field] of Object.entries(fields)) {
+      if (field.options?.required) {
+        const value = this.getFieldValue(fieldName);
+        if (value === null || value === void 0 || value === "") {
+          throw ValidationError.requiredField(fieldName, className);
+        }
+      }
+    }
+  }
+  /**
+   * Validates cross-package references that opted in via `validate: true`.
+   *
+   * Iterates registered fields of type `crossPackageRef`. For each one whose
+   * field options include `validate: true` AND has a non-empty value, looks up
+   * the referenced object via the target package's manifest and throws
+   * `ValidationError` if the target row does not exist.
+   *
+   * Empty/null/undefined values are treated as "no reference set" and skipped.
+   * Fields without `validate: true` are always skipped (the registered metadata
+   * still powers eager loading and `loadRelated()`).
+   */
+  async validateCrossPackageRefs() {
+    const className = this.getResolvedClassName();
+    const registered = ObjectRegistry.getClass(className);
+    if (!registered) return;
+    const fields = registered.inheritedFields || registered.fields;
+    if (!fields || fields.size === 0) return;
+    const checks = [];
+    for (const [fieldName, field] of fields) {
+      if (field?.type !== "crossPackageRef") continue;
+      const opts = field._meta || field;
+      if (!opts.validate) continue;
+      if (!field.related) continue;
+      const value = this.getFieldValue(fieldName);
+      if (value === null || value === void 0 || value === "") continue;
+      checks.push({
+        fieldName,
+        qualifiedTarget: String(field.related),
+        value: String(value)
+      });
+    }
+    if (checks.length === 0) return;
+    for (const check of checks) {
+      await ObjectRegistry.ensureManifestLoaded(check.qualifiedTarget);
+      const targetClass = ObjectRegistry.getClassByQualifiedName(check.qualifiedTarget) ?? ObjectRegistry.getClass(check.qualifiedTarget);
+      if (!targetClass) {
+        throw new ValidationError(
+          `crossPackageRef target ${check.qualifiedTarget} for ${className}.${check.fieldName} is not registered. Ensure the target package's manifest is discoverable at runtime.`,
+          "VALIDATION_CROSS_PACKAGE_REF_UNREGISTERED",
+          { className, fieldName: check.fieldName, value: check.value }
+        );
+      }
+      const probe = new targetClass.constructor(this.options);
+      await probe.initialize();
+      await probe.verifyStorageReady();
+      const row = await probe.db.get(probe.tableName, { id: check.value });
+      if (!row) {
+        throw new ValidationError(
+          `crossPackageRef validation failed: ${className}.${check.fieldName} references ${check.qualifiedTarget} id="${check.value}" but no such row exists.`,
+          "VALIDATION_CROSS_PACKAGE_REF_MISSING",
+          { className, fieldName: check.fieldName, value: check.value }
+        );
+      }
+    }
+  }
+  /**
+   * Gets the value of a field on this object
+   */
+  getFieldValue(fieldName) {
+    return this[fieldName];
+  }
+  /**
+   * Gets the value of a property.
+   *
+   * @param key - Property name to get value from
+   * @returns The property value
+   */
+  getPropertyValue(key) {
+    return this[key];
+  }
+  /**
+   * Classifies a raw database driver error message as a unique-constraint or
+   * not-null-constraint violation, across SQLite, PostgreSQL and DuckDB.
+   *
+   * `@happyvertical/sql` does not normalize driver errors, so each dialect's
+   * native wording is matched case-insensitively. Returns `null` when the
+   * message is not a recognized unique/not-null violation (the caller then
+   * falls back to a generic `DatabaseError`). Kept as a pure static so the
+   * cross-dialect matching can be unit-tested directly without a live PG/DuckDB
+   * connection (#1378).
+   *
+   * @param message - The raw driver error message.
+   * @returns `'unique'`, `'not_null'`, or `null`.
+   */
+  static classifyConstraintError(message) {
+    if (!message) {
+      return null;
+    }
+    if (/NOT NULL constraint failed/i.test(message) || /null value in column .* violates not-null/i.test(message)) {
+      return "not_null";
+    }
+    if (/UNIQUE constraint failed/i.test(message) || /violates unique constraint/i.test(message) || /violates primary key constraint/i.test(message)) {
+      return "unique";
+    }
+    return null;
+  }
+  /**
+   * Extracts field name from database constraint error messages.
+   *
+   * Handles SQLite, PostgreSQL and DuckDB phrasings. Returns
+   * `'unknown_field'` when no column name can be recovered.
+   */
+  extractConstraintField(errorMessage) {
+    const patterns = [
+      // SQLite / DuckDB: "UNIQUE constraint failed: products.slug"
+      /UNIQUE constraint failed: \w+\.(\w+)/i,
+      // SQLite / DuckDB: "NOT NULL constraint failed: products.name"
+      /NOT NULL constraint failed: \w+\.(\w+)/i,
+      // PostgreSQL not-null: 'null value in column "name" ...'
+      /null value in column "([^"]+)"/i,
+      // PostgreSQL unique DETAIL line: 'Key (slug)=(foo) already exists.'
+      /Key \(([^)]+)\)=/i,
+      // SQLite / DuckDB generic fallback: "constraint failed: slug"
+      /constraint failed: (\w+)/i
+    ];
+    for (const pattern of patterns) {
+      const match = errorMessage.match(pattern);
+      if (match?.[1]) {
+        return match[1];
+      }
+    }
+    return "unknown_field";
+  }
+  /**
+   * Hydrates this object from the database using its `id` property.
+   *
+   * Queries the database for a row matching `{ id: this._id }` and calls
+   * `loadDataFromDb()` if found. Uses a 3-attempt retry with 250 ms initial
+   * delay to handle transient failures.
+   *
+   * Called automatically by `initialize()` when `options.id` is provided.
+   * Typically you do not need to call this directly.
+   *
+   * @returns Promise that resolves when loading is complete (no-op if not found)
+   * @throws {ValidationError} If `this._id` is not set
+   * @throws {DatabaseError} If the query fails after all retries
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ db: myDb });
+   * await product.initialize();
+   * product._id = 'some-uuid';
+   * await product.loadFromId(); // hydrates from DB
+   * ```
+   */
+  async loadFromId() {
+    try {
+      if (!this._id) {
+        throw ValidationError.requiredField("id", this.constructor.name);
+      }
+      await this.verifyStorageReady();
+      await ErrorUtils.withRetry(
+        async () => {
+          try {
+            const existing = await this.db.get(this.tableName, {
+              id: this._id
+            });
+            if (existing) {
+              await this.loadDataFromDb(existing);
+            }
+          } catch (error) {
+            throw DatabaseError.queryFailed(
+              `get(${this.tableName}, { id: ${this._id} })`,
+              error instanceof Error ? error : new Error(String(error))
+            );
+          }
+        },
+        3,
+        250
+      );
+    } catch (error) {
+      if (error instanceof ValidationError || error instanceof DatabaseError) {
+        throw error;
+      }
+      throw RuntimeError.operationFailed(
+        "loadFromId",
+        `${this.constructor.name}#${this._id}`,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  /**
+   * Hydrates this object from the database using its `slug` (and `context`).
+   *
+   * Queries for a row matching `{ slug, context }`. The `context` defaults to
+   * an empty string when not provided. Calls `loadDataFromDb()` if a matching
+   * row is found.
+   *
+   * Called automatically by `initialize()` when `options.slug` is provided and
+   * no `options.id` is set. Typically you do not need to call this directly.
+   *
+   * @returns Promise that resolves when loading is complete (no-op if not found)
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ db: myDb, slug: 'my-widget', context: 'shop' });
+   * await product.initialize(); // calls loadFromSlug() automatically
+   * console.log(product.name);
+   * ```
+   */
+  async loadFromSlug() {
+    await this.verifyStorageReady();
+    const existing = await this.db.get(this.tableName, {
+      slug: this._slug,
+      context: this._context || ""
+    });
+    if (existing) {
+      await this.loadDataFromDb(existing);
+    }
+  }
+  /**
+   * Serializes this instance into the "content body" injected into the AI
+   * prompts used by {@link is}, {@link do}, and {@link describe} so those
+   * methods reason over the object's own field data, not just the caller's
+   * instruction string.
+   *
+   * Uses {@link toPublicJSON} (never {@link toJSON}) so that
+   * `@field({ sensitive: true })` values — API secrets, credentials, tax IDs —
+   * are never sent to the model. The serialized payload is truncated to
+   * `maxLength` characters as a coarse token-budget guard for large instances;
+   * truncation appends a clear marker so the model knows the data was cut.
+   *
+   * @param maxLength - Maximum characters of object data to include
+   *   (defaults to {@link AI_PROMPT_DATA_MAX_LENGTH}). A non-positive value
+   *   disables truncation.
+   * @returns A JSON string of the object's public (sensitive-stripped) fields
+   */
+  serializeForAiPrompt(maxLength = AI_PROMPT_DATA_MAX_LENGTH) {
+    let serialized;
+    try {
+      serialized = JSON.stringify(this.toPublicJSON(), null, 2);
+    } catch (error) {
+      logger.warn(
+        `Failed to serialize ${this.constructor.name} for AI prompt: ${error instanceof Error ? error.message : String(error)}`
+      );
+      serialized = "{}";
+    }
+    if (Number.isFinite(maxLength) && maxLength > 0 && serialized.length > maxLength) {
+      const marker = `
+… [truncated: object data exceeded ${maxLength} characters]`;
+      const keep = Math.max(0, maxLength - marker.length);
+      serialized = `${serialized.slice(0, keep)}${marker}`;
+    }
+    return serialized;
+  }
+  /**
+   * Builds the optional "content body" section prepended to the AI prompts in
+   * {@link is}, {@link do}, and {@link describe}.
+   *
+   * Returns an empty string when the caller opts out with `includeData: false`
+   * — used by callers that already curate the object's relevant fields into
+   * their own instruction/criteria string (so the data is not duplicated, and
+   * the prompt stays exactly as the caller authored it). Otherwise it wraps
+   * {@link serializeForAiPrompt} in `--- Beginning/End of content ---`
+   * delimiters so the methods reason over the instance's own data by default.
+   *
+   * @param includeData - `false` to omit the section; any other value (incl.
+   *   `undefined`) injects it
+   * @param maxLength - Forwarded to {@link serializeForAiPrompt} as the
+   *   truncation budget
+   * @returns The content-body section (with a trailing newline) or `''`
+   */
+  buildAiContentSection(includeData, maxLength) {
+    if (includeData === false) {
+      return "";
+    }
+    const contentBody = this.serializeForAiPrompt(maxLength);
+    return `--- Beginning of content ---
+${contentBody}
+--- End of content ---
+`;
+  }
+  /**
+   * Evaluates whether this object satisfies the given natural-language criteria using AI.
+   *
+   * Injects the object's own public field data (via {@link toPublicJSON}, so
+   * `@field({ sensitive: true })` values are excluded) into the prompt as the
+   * "content body", then asks the AI whether that data meets the criteria and
+   * to reply with a `{ result: boolean }` JSON response. Uses any AI-callable
+   * tools registered on this class (via `@smrt({ ai })`) as part of the
+   * function-calling context.
+   *
+   * @param criteria - Natural-language description of the condition to evaluate
+   * @param options - AI message options passed to `ai.message()` (e.g. model
+   *   override). Two non-standard control keys are consumed here and not
+   *   forwarded to `ai.message()`:
+   *   - `includeData: false` — omit the injected object "content body" (for
+   *     callers that already curate the relevant fields into `criteria`).
+   *   - `maxDataLength` (number of characters) — override the injected
+   *     object-data truncation limit.
+   * @returns `true` if the object meets the criteria, `false` otherwise
+   * @throws Error if the AI returns a non-boolean or malformed JSON response
+   *
+   * @example
+   * ```typescript
+   * const article = await articles.get('article-uuid');
+   * const isSuitable = await article.is('appropriate for a general audience');
+   * if (isSuitable) await article.publish();
+   * ```
+   *
+   * @see {@link do} for open-ended instructions instead of boolean checks
+   */
+  async is(criteria, options = {}) {
+    const ai = await this.getAiClient();
+    const { maxDataLength, includeData, ...aiOptions } = options ?? {};
+    const contentSection = this.buildAiContentSection(
+      includeData,
+      maxDataLength
+    );
+    const prompt = `${contentSection}--- Beginning of criteria ---
+${criteria}
+--- End of criteria ---
+Does the content meet all the given criteria? Reply with a json object with a single boolean 'result' property`;
+    const tools = this.getAvailableTools();
+    const message = await ai.message(prompt, {
+      ...aiOptions,
+      responseFormat: { type: "json_object" },
+      tools: tools.length > 0 ? tools : void 0
+    });
+    try {
+      const { result } = JSON.parse(message);
+      if (result === true || result === false) {
+        return result;
+      }
+    } catch (_e) {
+      throw new Error(`Unexpected answer: ${message}`);
+    }
+  }
+  /**
+   * Performs a freeform operation on this object using AI instructions.
+   *
+   * Injects the object's own public field data (via {@link toPublicJSON}, so
+   * `@field({ sensitive: true })` values are excluded) into the prompt as the
+   * "content body" the instructions operate on, then returns the raw text
+   * response. Unlike `is()`, this method does not constrain the response
+   * format — use it for transformations, summaries, extractions, or any
+   * open-ended AI task.
+   *
+   * Uses any AI-callable tools registered on this class (via `@smrt({ ai })`)
+   * as part of the function-calling context.
+   *
+   * @param instructions - Natural-language instructions for the AI to follow
+   * @param options - AI message options passed to `ai.message()` (e.g. model
+   *   override). Two non-standard control keys are consumed here and not
+   *   forwarded to `ai.message()`:
+   *   - `includeData: false` — omit the injected object "content body" (for
+   *     callers that already curate the relevant fields into `instructions`).
+   *   - `maxDataLength` (number of characters) — override the injected
+   *     object-data truncation limit.
+   * @returns The raw AI response string
+   *
+   * @example
+   * ```typescript
+   * const article = await articles.get('article-uuid');
+   * const summary = await article.do('summarize this article in 3 bullet points');
+   * const translated = await article.do('translate the title and body to Spanish');
+   * ```
+   *
+   * @see {@link is} for boolean criteria checks
+   */
+  async do(instructions, options = {}) {
+    const ai = await this.getAiClient();
+    const { maxDataLength, includeData, ...aiOptions } = options ?? {};
+    const contentSection = this.buildAiContentSection(
+      includeData,
+      maxDataLength
+    );
+    const prompt = `${contentSection}--- Beginning of instructions ---
+${instructions}
+--- End of instructions ---
+Based on the content body, please follow the instructions and provide a response. Never make use of codeblocks.`;
+    const tools = this.getAvailableTools();
+    const result = await ai.message(prompt, {
+      ...aiOptions,
+      tools: tools.length > 0 ? tools : void 0
+    });
+    return result;
+  }
+  /**
+   * Generates a description of this object using AI (Issue #52)
+   *
+   * Creates a concise, human-readable description based on the object's content
+   * and properties. The object's own public field data (via
+   * {@link toPublicJSON}, so `@field({ sensitive: true })` values are excluded)
+   * is injected into the prompt as the "content body" the description is built
+   * from. Useful for summaries, previews, and documentation.
+   *
+   * @param options - AI message options (can include style, length, focus,
+   *   etc.). Two non-standard control keys are consumed here and not forwarded
+   *   to `ai.message()`:
+   *   - `includeData: false` — omit the injected object "content body".
+   *   - `maxDataLength` (number of characters) — override the injected
+   *     object-data truncation limit.
+   * @returns Promise resolving to the AI-generated description
+   *
+   * @example
+   * ```typescript
+   * const product = await products.get('product-123');
+   * const description = await product.describe();
+   * // "A high-quality widget for home improvement..."
+   *
+   * // With custom options
+   * const shortDesc = await product.describe({ maxTokens: 50 });
+   * // "Premium widget, steel construction"
+   * ```
+   */
+  async describe(options = {}) {
+    const ai = await this.getAiClient();
+    const { maxDataLength, includeData, ...aiOptions } = options ?? {};
+    const contentSection = this.buildAiContentSection(
+      includeData,
+      maxDataLength
+    );
+    const prompt = `${contentSection}Generate a concise, professional description of this object based on its content and properties. The description should be clear, informative, and suitable for display to end users. Focus on the most important and distinctive characteristics.`;
+    const tools = this.getAvailableTools();
+    const result = await ai.message(prompt, {
+      ...aiOptions,
+      tools: tools.length > 0 ? tools : void 0
+    });
+    return result;
+  }
+  /**
+   * Runs a lifecycle hook if it's defined in the object's configuration
+   *
+   * @param hookName - Name of the hook to run (e.g., 'beforeDelete', 'afterDelete')
+   * @returns Promise that resolves when the hook completes
+   */
+  async runHook(hookName) {
+    const config = ObjectRegistry.getConfig(this.constructor.name);
+    const hook = config.hooks?.[hookName];
+    if (!hook) {
+      return;
+    }
+    if (typeof hook === "string") {
+      const method = this[hook];
+      if (typeof method === "function") {
+        await method.call(this);
+      } else {
+        logger.warn(
+          `Hook method '${hook}' not found on ${this.constructor.name}`
+        );
+      }
+    } else if (typeof hook === "function") {
+      await hook(this);
+    }
+  }
+  /**
+   * Deletes this object from the database.
+   *
+   * Runs the full lifecycle in order:
+   * 1. `beforeDelete` interceptors (e.g. tenant validation)
+   * 2. `beforeDelete` lifecycle hook (defined in `@smrt({ hooks })`)
+   * 3. Database row deletion
+   * 4. `afterDelete` lifecycle hook
+   * 5. `afterDelete` interceptors
+   *
+   * Prefer `collection.delete(id)` from application code — it loads the
+   * object first (returning `false` when not found) before calling this method.
+   *
+   * @returns Promise that resolves when deletion is complete
+   *
+   * @example
+   * ```typescript
+   * const product = await products.get('product-uuid');
+   * if (product) await product.delete();
+   * ```
+   */
+  async delete() {
+    const interceptorContext = createInterceptorContext(
+      this.constructor.name,
+      "delete"
+    );
+    await GlobalInterceptors.executeBeforeDelete(this, interceptorContext);
+    await this.runHook("beforeDelete");
+    await this.verifyStorageReady();
+    await this.db.delete(this.tableName, { id: this.id });
+    this._persisted = false;
+    this.invalidateCollectionReadCache();
+    await this.runHook("afterDelete");
+    await GlobalInterceptors.executeAfterDelete(this, interceptorContext);
+  }
+  /**
+   * Invalidate cached collection reads after a successful mutation
+   * (issue #1498).
+   *
+   * Always drops this table's in-process entries — a no-op when nothing
+   * opted into caching. When the table is cached cross-process (see
+   * {@link shouldBroadcastCacheInvalidation}), the invalidation is also
+   * broadcast to peer replicas over the database adapter's notification
+   * capability, fire-and-forget. Cache maintenance must never fail the
+   * write that triggered it.
+   */
+  invalidateCollectionReadCache() {
+    try {
+      const dbKey = resolveDbCacheKey(this.db);
+      invalidateCollectionCache(dbKey, this.tableName);
+      if (this.shouldBroadcastCacheInvalidation(dbKey)) {
+        void broadcastCacheInvalidation(this.db, this.tableName);
+      }
+    } catch (error) {
+      logger.warn("Failed to invalidate collection read cache after write", {
+        table: this.tableName,
+        error: error instanceof Error ? error.message : error
+      });
+    }
+  }
+  /**
+   * Decide whether a mutation should broadcast a cross-process cache
+   * invalidation. Invalidation is table-scoped, so the decision must be too:
+   *
+   * 1. A per-call `crossProcess` cached read in this process registered
+   *    interest in the table — broadcast even without model-level config.
+   * 2. This class's resolved `@smrt({ cache })` config sets `crossProcess`.
+   * 3. Any other STI hierarchy member sharing the table resolves to a
+   *    `crossProcess` config — a child that opted out with `cache: false`
+   *    still mutates the shared table its base/siblings are caching.
+   */
+  shouldBroadcastCacheInvalidation(dbKey) {
+    if (hasCrossProcessCacheInterest(dbKey, this.tableName)) {
+      return true;
+    }
+    const qualifiedName = this.getResolvedQualifiedName();
+    if (ObjectRegistry.resolveCollectionCacheConfig(qualifiedName)?.crossProcess) {
+      return true;
+    }
+    for (const member of getSTIHierarchyMembers(qualifiedName)) {
+      if (member === qualifiedName) continue;
+      if (ObjectRegistry.resolveCollectionCacheConfig(member)?.crossProcess) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if a relationship has been loaded
+   *
+   * @param fieldName - Name of the relationship field
+   * @returns True if the relationship is loaded, false otherwise
+   * @example
+   * ```typescript
+   * if (order.isRelatedLoaded('customer')) {
+   *   console.log('Customer already loaded');
+   * }
+   * ```
+   */
+  isRelatedLoaded(fieldName) {
+    return this._loadedRelationships.has(fieldName);
+  }
+  /**
+   * Lazy-loads a `foreignKey` or `crossPackageRef` relationship and caches the
+   * result.
+   *
+   * Looks up the relationship metadata in the ObjectRegistry, reads the
+   * foreign key value on this object, and fetches the related object from
+   * the database. Subsequent calls return the cached value without hitting
+   * the database again.
+   *
+   * For STI relationships, the correct subclass is determined by reading
+   * `_meta_type` from the database row before instantiation.
+   *
+   * Enforces tenant isolation: if this object and the loaded target both carry
+   * a non-null `tenantId` that differ, a {@link TenantIsolationError} is thrown
+   * (unless `opts.allowCrossTenant` is set). The check is a no-op for
+   * global/null-tenant models and same-tenant loads, so it only catches genuine
+   * cross-tenant leaks (Issue #1321).
+   *
+   * @param fieldName - Name of the `@foreignKey()` or `@crossPackageRef()`
+   *   decorated property
+   * @param opts - Optional loader options; see {@link LoadRelatedOptions}
+   * @returns The related object, or `null` if the foreign key is empty
+   * @throws {RuntimeError} If `fieldName` is not a `foreignKey` or
+   *   `crossPackageRef` relationship, or the target class is not found in the
+   *   ObjectRegistry
+   * @throws {TenantIsolationError} If the target belongs to a different,
+   *   non-null tenant and `opts.allowCrossTenant` is not set
+   *
+   * @example
+   * ```typescript
+   * // class Order { @foreignKey(Customer) customerId: string = ''; }
+   * const customer = await order.loadRelated('customerId');
+   * console.log(customer?.name);
+   * ```
+   *
+   * @see {@link getRelated} for a convenience wrapper that auto-detects relationship type
+   */
+  async loadRelated(fieldName, opts) {
+    if (this._loadedRelationships.has(fieldName)) {
+      const cached = this._loadedRelationships.get(fieldName);
+      this.assertRelatedTenant(cached, fieldName, opts?.allowCrossTenant);
+      return cached;
+    }
+    await ObjectRegistry.ensureManifestLoaded(this.constructor.name);
+    const relationships = ObjectRegistry.getRelationships(
+      this.constructor.name
+    );
+    const relationship = relationships.find(
+      (r) => r.fieldName === fieldName && (r.type === "foreignKey" || r.type === "crossPackageRef")
+    );
+    if (!relationship) {
+      throw RuntimeError.invalidState(
+        `Field ${fieldName} is not a foreignKey or crossPackageRef relationship on ${this.constructor.name}`,
+        { fieldName, className: this.constructor.name }
+      );
+    }
+    const foreignKeyValue = this[fieldName];
+    if (!foreignKeyValue) {
+      this._loadedRelationships.set(fieldName, null);
+      return null;
+    }
+    if (relationship.type === "crossPackageRef") {
+      await ObjectRegistry.ensureManifestLoaded(relationship.targetClass);
+    }
+    const targetClassInfo = relationship.type === "crossPackageRef" ? ObjectRegistry.getClassByQualifiedName(relationship.targetClass) ?? ObjectRegistry.getClass(relationship.targetClass) : ObjectRegistry.getClass(relationship.targetClass);
+    if (!targetClassInfo) {
+      throw RuntimeError.invalidState(
+        `Target class ${relationship.targetClass} not found in ObjectRegistry`,
+        { targetClass: relationship.targetClass, fieldName }
+      );
+    }
+    const tableStrategy = ObjectRegistry.getTableStrategy(
+      relationship.targetClass
+    );
+    const isSTI = tableStrategy === "sti";
+    let actualClassInfo = targetClassInfo;
+    if (isSTI) {
+      const tempInstance = new targetClassInfo.constructor(this.options);
+      await tempInstance.initialize();
+      await tempInstance.verifyStorageReady();
+      const row = await tempInstance.db.get(tempInstance.tableName, {
+        id: foreignKeyValue
+      });
+      if (row?._meta_type) {
+        let actualClass = ObjectRegistry.getClassByQualifiedName(
+          row._meta_type
+        );
+        if (!actualClass) {
+          actualClass = ObjectRegistry.getClass(row._meta_type);
+        }
+        if (actualClass) {
+          actualClassInfo = actualClass;
+        }
+      }
+    }
+    const relatedInstance = new actualClassInfo.constructor(this.options);
+    await relatedInstance.initialize();
+    relatedInstance.id = foreignKeyValue;
+    await relatedInstance.loadFromId();
+    this.assertRelatedTenant(
+      relatedInstance,
+      fieldName,
+      opts?.allowCrossTenant
+    );
+    this._loadedRelationships.set(fieldName, relatedInstance);
+    return relatedInstance;
+  }
+  /**
+   * Guards a loaded relationship target against cross-tenant access.
+   *
+   * Throws {@link TenantIsolationError} when this object and `loaded` both carry
+   * a non-null `tenantId` that differ — the genuine cross-tenant leak. It is a
+   * no-op when `allowCrossTenant === true`, when `loaded` is `null`, when either
+   * side has a `null`/`undefined` tenant (global / non-tenant-scoped models),
+   * and when both sides share the same tenant (Issue #1321).
+   *
+   * `loaded` may be a single related object or an array (oneToMany / manyToMany);
+   * arrays are validated per item. This runs on both fresh loads and cache hits,
+   * so a cache populated by an eager `include` load — or by a prior
+   * `allowCrossTenant` load — cannot leak cross-tenant data through a later
+   * guarded call.
+   *
+   * @param loaded - The loaded related object, or array of objects.
+   * @param fieldName - The relationship field name (for error context).
+   * @param allowCrossTenant - When exactly `true`, bypasses the guard entirely.
+   */
+  assertRelatedTenant(loaded, fieldName, allowCrossTenant) {
+    if (allowCrossTenant === true || loaded == null) {
+      return;
+    }
+    if (Array.isArray(loaded)) {
+      for (const item of loaded) {
+        this.assertRelatedTenant(item, fieldName, allowCrossTenant);
+      }
+      return;
+    }
+    const sourceTenantId = this.tenantId;
+    const targetTenantId = loaded.tenantId;
+    if (sourceTenantId != null && targetTenantId != null && sourceTenantId !== targetTenantId) {
+      throw TenantIsolationError.crossTenantReference({
+        sourceClass: this.constructor.name,
+        fieldName,
+        sourceTenantId: String(sourceTenantId),
+        targetClass: loaded?.constructor?.name,
+        targetTenantId: String(targetTenantId)
+      });
+    }
+  }
+  /**
+   * Load related objects for oneToMany or manyToMany fields (lazy loading)
+   *
+   * Loads all related objects from the database. For oneToMany, queries by
+   * the inverse foreign key. For manyToMany, queries through the join table.
+   *
+   * Enforces tenant isolation per item: if this object and a loaded target both
+   * carry a non-null `tenantId` that differ, a {@link TenantIsolationError} is
+   * thrown (unless `opts.allowCrossTenant` is set). The check is a no-op for
+   * global/null-tenant models and same-tenant loads, so it only catches genuine
+   * cross-tenant leaks (Issue #1321).
+   *
+   * @param fieldName - Name of the oneToMany or manyToMany field
+   * @param opts - Optional loader options; see {@link LoadRelatedOptions}
+   * @returns Promise resolving to array of related objects
+   * @throws {RuntimeError} If the field is not a relationship or not implemented
+   * @throws {TenantIsolationError} If any loaded item belongs to a different,
+   *   non-null tenant and `opts.allowCrossTenant` is not set
+   * @example
+   * ```typescript
+   * // Given: class Customer with orders = oneToMany(Order)
+   * const orders = await customer.loadRelatedMany('orders');
+   * console.log(`${orders.length} orders found`);
+   * ```
+   */
+  async loadRelatedMany(fieldName, opts) {
+    if (this._loadedRelationships.has(fieldName)) {
+      const cached = this._loadedRelationships.get(fieldName);
+      this.assertRelatedTenant(cached, fieldName, opts?.allowCrossTenant);
+      return cached;
+    }
+    await ObjectRegistry.ensureManifestLoaded(this.constructor.name);
+    const relationships = ObjectRegistry.getRelationships(
+      this.constructor.name
+    );
+    const relationship = relationships.find((r) => r.fieldName === fieldName);
+    if (!relationship) {
+      throw RuntimeError.invalidState(
+        `Field ${fieldName} is not a relationship on ${this.constructor.name}`,
+        { fieldName, className: this.constructor.name }
+      );
+    }
+    if (relationship.type === "oneToMany") {
+      const inverseRelationships = ObjectRegistry.getInverseRelationshipsForSelf(this.constructor.name);
+      const inverseCandidates = inverseRelationships.filter(
+        (r) => r.sourceClass === relationship.targetClass && r.type === "foreignKey"
+      );
+      const explicitForeignKey = relationship.options?.foreignKey;
+      const matchedForeignKey = explicitForeignKey ? inverseCandidates.find((r) => r.fieldName === explicitForeignKey) : void 0;
+      if (explicitForeignKey && !matchedForeignKey) {
+        throw RuntimeError.invalidState(
+          `oneToMany ${fieldName} on ${this.constructor.name} specifies foreignKey '${explicitForeignKey}', but ${relationship.targetClass} has no matching inverse foreignKey. Candidates: ${inverseCandidates.map((r) => r.fieldName).join(", ") || "(none)"}`,
+          {
+            fieldName,
+            targetClass: relationship.targetClass,
+            foreignKey: explicitForeignKey
+          }
+        );
+      }
+      const inverseForeignKey = matchedForeignKey ?? inverseCandidates.find(
+        (r) => r.targetClass === this.constructor.name
+      ) ?? inverseCandidates[0];
+      if (!inverseForeignKey) {
+        throw RuntimeError.invalidState(
+          `Could not find inverse foreignKey on ${relationship.targetClass} for oneToMany relationship ${fieldName}`,
+          { fieldName, targetClass: relationship.targetClass }
+        );
+      }
+      const collection = await ObjectRegistry.getCollection(
+        relationship.targetClass,
+        this.options
+      );
+      const relatedObjects = await collection.list({
+        where: { [inverseForeignKey.fieldName]: this.id }
+      });
+      this.assertRelatedTenant(
+        relatedObjects,
+        fieldName,
+        opts?.allowCrossTenant
+      );
+      this._loadedRelationships.set(fieldName, relatedObjects);
+      return relatedObjects;
+    }
+    if (relationship.type === "manyToMany") {
+      const { through, sourceColumn, targetColumn, targetClassName } = await this.resolveManyToManyJoin(fieldName, relationship);
+      if (!this.id) {
+        this._loadedRelationships.set(fieldName, []);
+        return [];
+      }
+      await this.verifyStorageReady();
+      const junctionRows = await this.db.query(
+        `SELECT "${targetColumn}" FROM "${through}" WHERE "${sourceColumn}" = ?`,
+        [this.id]
+      );
+      const targetIds = junctionRows.rows.map((row) => row[targetColumn]).filter(
+        (id) => typeof id === "string" && id.length > 0
+      );
+      if (targetIds.length === 0) {
+        this._loadedRelationships.set(fieldName, []);
+        return [];
+      }
+      const targetCollection = await ObjectRegistry.getCollection(
+        targetClassName,
+        this.options
+      );
+      const targetObjects = await targetCollection.list({
+        where: { "id in": targetIds }
+      });
+      this.assertRelatedTenant(
+        targetObjects,
+        fieldName,
+        opts?.allowCrossTenant
+      );
+      this._loadedRelationships.set(fieldName, targetObjects);
+      return targetObjects;
+    }
+    throw RuntimeError.invalidState(
+      `Field ${fieldName} is not a oneToMany or manyToMany relationship`,
+      { fieldName, type: relationship.type }
+    );
+  }
+  /**
+   * Resolves the junction-table coordinates for a manyToMany relationship.
+   *
+   * Discovers `through`, source-side column, and target-side column from the
+   * registered field metadata. Falls back to convention (`<class>_id`) when
+   * `sourceKey` / `targetKey` are not explicitly set.
+   */
+  async resolveManyToManyJoin(fieldName, relationship) {
+    const decorator = ObjectRegistry.getFieldDecorator(
+      relationship.sourceClass,
+      fieldName
+    );
+    const opts = relationship.options || {};
+    const through = decorator?.through ?? opts.through ?? opts._meta?.through;
+    if (!through) {
+      throw RuntimeError.invalidState(
+        `manyToMany field ${fieldName} on ${relationship.sourceClass} is missing the 'through' join table name`,
+        { fieldName, type: "manyToMany" }
+      );
+    }
+    const targetSimpleName = relationship.targetClass.includes(":") ? relationship.targetClass.split(":").pop() : relationship.targetClass;
+    const sourceSimpleName = relationship.sourceClass.includes(":") ? relationship.sourceClass.split(":").pop() : relationship.sourceClass;
+    const sourceColumn = decorator?.sourceKey ?? opts.sourceKey ?? opts._meta?.sourceKey ?? `${toSnakeCase(sourceSimpleName)}_id`;
+    const targetColumn = decorator?.targetKey ?? opts.targetKey ?? opts._meta?.targetKey ?? `${toSnakeCase(targetSimpleName)}_id`;
+    return {
+      through: String(through),
+      sourceColumn,
+      targetColumn,
+      targetClassName: relationship.targetClass
+    };
+  }
+  /**
+   * Get a related object, loading it if not already loaded
+   *
+   * Convenience method that checks if the relationship is loaded and
+   * loads it if necessary. Automatically detects foreignKey vs oneToMany/manyToMany.
+   *
+   * Tenant isolation is enforced by the underlying loaders; see
+   * {@link loadRelated} and {@link loadRelatedMany}.
+   *
+   * @param fieldName - Name of the relationship field
+   * @param opts - Optional loader options; see {@link LoadRelatedOptions}
+   * @returns Promise resolving to the related object(s)
+   * @throws {TenantIsolationError} If a loaded target belongs to a different,
+   *   non-null tenant and `opts.allowCrossTenant` is not set
+   * @example
+   * ```typescript
+   * // Loads customer if not already loaded
+   * const customer = await order.getRelated('customerId');
+   *
+   * // Loads orders if not already loaded
+   * const orders = await customer.getRelated('orders');
+   * ```
+   */
+  async getRelated(fieldName, opts) {
+    if (this._loadedRelationships.has(fieldName)) {
+      const cached = this._loadedRelationships.get(fieldName);
+      this.assertRelatedTenant(cached, fieldName, opts?.allowCrossTenant);
+      return cached;
+    }
+    await ObjectRegistry.ensureManifestLoaded(this.constructor.name);
+    const relationships = ObjectRegistry.getRelationships(
+      this.constructor.name
+    );
+    const relationship = relationships.find((r) => r.fieldName === fieldName);
+    if (!relationship) {
+      throw RuntimeError.invalidState(
+        `Field ${fieldName} is not a relationship on ${this.constructor.name}`,
+        { fieldName, className: this.constructor.name }
+      );
+    }
+    if (relationship.type === "foreignKey" || relationship.type === "crossPackageRef") {
+      return this.loadRelated(fieldName, opts);
+    }
+    return this.loadRelatedMany(fieldName, opts);
+  }
+  /**
+   * Get available AI-callable tools for this object
+   *
+   * Returns the pre-generated tool definitions from the manifest.
+   * Tools are generated at build time based on the @smrt decorator's AI config.
+   *
+   * @returns Array of AITool definitions for LLM function calling
+   * @example
+   * ```typescript
+   * const tools = document.getAvailableTools();
+   * console.log(`${tools.length} AI-callable methods available`);
+   * ```
+   */
+  getAvailableTools() {
+    const classInfo = ObjectRegistry.getClass(this.constructor.name);
+    return classInfo?.tools || [];
+  }
+  /**
+   * Execute a tool call from AI on this object instance
+   *
+   * Validates the tool call against allowed methods and executes it with
+   * proper error handling and timing.
+   *
+   * @param toolCall - Tool call from AI response
+   * @returns Promise resolving to the tool call result
+   * @example
+   * ```typescript
+   * const toolCall = {
+   *   id: 'call_123',
+   *   type: 'function',
+   *   function: {
+   *     name: 'analyze',
+   *     arguments: '{"type": "detailed"}'
+   *   }
+   * };
+   *
+   * const result = await document.executeToolCall(toolCall);
+   * console.log(result.success ? result.result : result.error);
+   * ```
+   */
+  async executeToolCall(toolCall) {
+    const tools = this.getAvailableTools();
+    const allowedMethods = tools.map((tool) => tool.function.name);
+    return executeToolCall(this, toolCall, allowedMethods);
+  }
+  /**
+   * Stores a named value in the `_smrt_contexts` system table, scoped to this object.
+   *
+   * Context entries are keyed by `(owner_class, owner_id, scope, key, version)` and
+   * support an optional `confidence` score (0–1, default 1.0) for learned patterns.
+   * Calling `remember()` with the same scope+key upserts the existing entry.
+   *
+   * Requires `initialize()` to have been called (needs `this.systemDb`).
+   *
+   * @param options.id - Optional explicit ID for the context entry (auto-generated if omitted)
+   * @param options.scope - Hierarchical path scoping the context (e.g. `'parser/example.com'`)
+   * @param options.key - Lookup key within the scope (e.g. a normalized URL)
+   * @param options.value - Any JSON-serializable value to store
+   * @param options.metadata - Optional additional JSON metadata
+   * @param options.confidence - Confidence score (0–1, default 1.0)
+   * @param options.version - Schema version for the stored value (default 1)
+   * @param options.expiresAt - Optional expiry date after which `recall()` will ignore this entry
+   * @returns Promise that resolves when the context is stored
+   * @throws Error if `initialize()` has not been called
+   *
+   * @example
+   * ```typescript
+   * await agent.remember({
+   *   scope: 'parser/example.com',
+   *   key: normalizedUrl,
+   *   value: { patterns: ['regex1', 'regex2'] },
+   *   confidence: 0.9,
+   * });
+   * ```
+   *
+   * @see {@link recall} to retrieve a single entry
+   * @see {@link recallAll} to retrieve all entries in a scope
+   * @see {@link forget} to delete a specific entry
+   */
+  async remember(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    const id = options.id || crypto.randomUUID();
+    const now = /* @__PURE__ */ new Date();
+    if (!this.id) {
+      this._id = crypto.randomUUID();
+    }
+    await this.systemDb.upsert(
+      "_smrt_contexts",
+      ["owner_class", "owner_id", "scope", "key", "version"],
+      {
+        id,
+        owner_class: this._className,
+        owner_id: this.id,
+        scope: options.scope,
+        key: options.key,
+        value: JSON.stringify(options.value),
+        metadata: options.metadata ? JSON.stringify(options.metadata) : null,
+        version: options.version ?? 1,
+        confidence: options.confidence ?? 1,
+        created_at: now,
+        updated_at: now,
+        last_used_at: now,
+        expires_at: options.expiresAt ?? null
+      }
+    );
+  }
+  /**
+   * Retrieves a single remembered context value for this object.
+   *
+   * Looks up the most recent (highest confidence, then highest version) entry
+   * matching `(owner_class, owner_id, scope, key)`. Returns the JSON-parsed value
+   * or `null` if no matching entry exists.
+   *
+   * When `includeAncestors: true`, walks up the scope hierarchy by progressively
+   * removing the last path segment (e.g. `'a/b/c'` → `'a/b'` → `'a'` → `'global'`)
+   * until a match is found.
+   *
+   * @param options.scope - Scope path to search (e.g. `'parser/example.com/article'`)
+   * @param options.key - Lookup key within the scope
+   * @param options.includeAncestors - If `true`, fall back to parent scopes (default `false`)
+   * @param options.minConfidence - Only return entries at or above this confidence (0–1)
+   * @returns The stored value (parsed from JSON), or `null` if not found
+   * @throws Error if `initialize()` has not been called
+   *
+   * @example
+   * ```typescript
+   * const strategy = await agent.recall({
+   *   scope: 'parser/example.com/article',
+   *   key: normalizedUrl,
+   *   includeAncestors: true,
+   *   minConfidence: 0.6,
+   * });
+   * ```
+   *
+   * @see {@link remember} to store a context entry
+   * @see {@link recallAll} to retrieve all entries in a scope
+   */
+  async recall(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    let result;
+    if (options.minConfidence !== void 0) {
+      result = await this.systemDb.single`
+        SELECT value, confidence
+        FROM _smrt_contexts
+        WHERE owner_class = ${this._className}
+          AND owner_id = ${this.id}
+          AND scope = ${options.scope}
+          AND key = ${options.key}
+          AND confidence >= ${options.minConfidence}
+        ORDER BY confidence DESC, version DESC
+        LIMIT 1
+      `;
+    } else {
+      result = await this.systemDb.single`
+        SELECT value, confidence
+        FROM _smrt_contexts
+        WHERE owner_class = ${this._className}
+          AND owner_id = ${this.id}
+          AND scope = ${options.scope}
+          AND key = ${options.key}
+        ORDER BY confidence DESC, version DESC
+        LIMIT 1
+      `;
+    }
+    if (result) {
+      try {
+        return JSON.parse(result.value);
+      } catch (error) {
+        logger.warn("Skipping corrupted _smrt_contexts value in recall()", {
+          ownerClass: this._className,
+          ownerId: this.id,
+          scope: options.scope,
+          key: options.key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    if (options.includeAncestors) {
+      const scopeParts = options.scope.split("/");
+      while (scopeParts.length > 0) {
+        scopeParts.pop();
+        const parentScope = scopeParts.join("/") || "global";
+        const parentResult = await this.recall({
+          ...options,
+          scope: parentScope,
+          includeAncestors: false
+        });
+        if (parentResult) return parentResult;
+      }
+    }
+    return null;
+  }
+  /**
+   * Retrieves all remembered context entries for this object in a scope.
+   *
+   * Returns a `Map<key, value>` for every entry owned by this object that matches
+   * the scope and optional filters. When `includeDescendants: true`, a LIKE query
+   * (`scope%`) matches the scope itself and all child scopes.
+   *
+   * @param options.scope - Optional scope path filter; omit to retrieve all scopes
+   * @param options.includeDescendants - If `true`, match `scope` and all child scopes (default `false`)
+   * @param options.minConfidence - Only include entries at or above this confidence (0–1)
+   * @returns `Map<string, any>` of key → JSON-parsed value pairs
+   * @throws Error if `initialize()` has not been called
+   *
+   * @example
+   * ```typescript
+   * const strategies = await agent.recallAll({
+   *   scope: 'parser/example.com',
+   *   minConfidence: 0.5,
+   * });
+   * for (const [url, pattern] of strategies) {
+   *   console.log(`Cached pattern for ${url}:`, pattern);
+   * }
+   * ```
+   *
+   * @see {@link recall} to retrieve a single entry by key
+   * @see {@link forgetScope} to delete all entries in a scope
+   */
+  async recallAll(options = {}) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    const results = /* @__PURE__ */ new Map();
+    const where = {
+      owner_class: this._className,
+      owner_id: this.id
+    };
+    if (options.scope) {
+      if (options.includeDescendants) {
+        where["scope like"] = `${options.scope}%`;
+      } else {
+        where.scope = options.scope;
+      }
+    }
+    if (options.minConfidence !== void 0) {
+      where["confidence >="] = options.minConfidence;
+    }
+    const rows = await this.systemDb.list("_smrt_contexts", where);
+    for (const row of rows) {
+      try {
+        results.set(row.key, JSON.parse(row.value));
+      } catch (error) {
+        logger.warn("Skipping corrupted _smrt_contexts value in recallAll()", {
+          ownerClass: this._className,
+          ownerId: this.id,
+          scope: options.scope,
+          key: row.key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Deletes a specific remembered context entry for this object.
+   *
+   * Removes the entry matching `(owner_class, owner_id, scope, key)`. A no-op
+   * if the entry does not exist.
+   *
+   * @param options.scope - Scope path of the entry to delete
+   * @param options.key - Key of the entry to delete
+   * @returns Promise that resolves when the entry is deleted
+   * @throws Error if `initialize()` has not been called
+   *
+   * @example
+   * ```typescript
+   * await agent.forget({ scope: 'parser/example.com', key: normalizedUrl });
+   * ```
+   *
+   * @see {@link forgetScope} to delete all entries in a scope at once
+   * @see {@link remember} to store a context entry
+   */
+  async forget(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    await this.systemDb.delete("_smrt_contexts", {
+      owner_class: this._className,
+      owner_id: this.id,
+      scope: options.scope,
+      key: options.key
+    });
+  }
+  /**
+   * Deletes all remembered context entries in a scope for this object.
+   *
+   * When `includeDescendants: true`, uses a LIKE query (`scope%`) that matches
+   * the scope itself and all child scopes (e.g. `'parser/example.com'` also
+   * deletes `'parser/example.com/article'`).
+   *
+   * @param options.scope - Scope path to clear
+   * @param options.includeDescendants - If `true`, also delete all child scopes (default `false`)
+   * @returns Number of context entries deleted
+   * @throws Error if `initialize()` has not been called
+   *
+   * @example
+   * ```typescript
+   * const count = await agent.forgetScope({
+   *   scope: 'parser/example.com',
+   *   includeDescendants: true,
+   * });
+   * console.log(`Cleared ${count} cached strategies`);
+   * ```
+   *
+   * @see {@link forget} to delete a single entry by key
+   * @see {@link recallAll} to bulk-retrieve before clearing
+   */
+  async forgetScope(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    const where = {
+      owner_class: this._className,
+      owner_id: this.id
+    };
+    if (options.includeDescendants) {
+      where["scope like"] = `${options.scope}%`;
+    } else {
+      where.scope = options.scope;
+    }
+    const result = await this.systemDb.delete("_smrt_contexts", where);
+    return result.affected || 0;
+  }
+  // ============================================================================
+  // Embedding Methods for Semantic Search
+  // ============================================================================
+  /**
+   * Generate embeddings for configured fields
+   *
+   * Creates embedding vectors for fields configured in the @smrt decorator
+   * and stores them in the _smrt_embeddings system table. Uses content hashing
+   * to detect changes and avoid regenerating unchanged content.
+   *
+   * @param options - Generation options
+   * @returns Promise that resolves when embeddings are generated
+   * @throws Error if no embedding configuration or database not initialized
+   *
+   * @example
+   * ```typescript
+   * // Generate embeddings for all configured fields
+   * await article.generateEmbeddings();
+   *
+   * // Generate only for specific fields
+   * await article.generateEmbeddings({ fields: ['title'] });
+   *
+   * // Force regeneration (ignore content hash)
+   * await article.generateEmbeddings({ force: true });
+   * ```
+   */
+  async generateEmbeddings(options = {}) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    if (!this.id) {
+      throw new Error("Object must have an ID before generating embeddings.");
+    }
+    const config = ObjectRegistry.resolveEmbeddingConfig(this.constructor.name);
+    if (!config) {
+      throw new Error(
+        `No embedding configuration found for ${this.constructor.name}. Add embeddings config to the @smrt() decorator.`
+      );
+    }
+    const fieldsToProcess = options.fields || config.fields;
+    const provider = options.provider || config.provider;
+    const aiClient = await this.getOptionalAiClient();
+    const embeddingProvider = new EmbeddingProvider(
+      {
+        dimensions: config.dimensions,
+        provider,
+        localModel: config.localModel,
+        aiModel: config.aiModel,
+        fallbackToAI: config.fallbackToAI
+      },
+      aiClient
+    );
+    const projectConfig = ObjectRegistry.getProjectEmbeddingConfig();
+    const vector = projectConfig?.storage === "native" ? this.systemDb.vector : void 0;
+    for (const fieldName of fieldsToProcess) {
+      const content = this.getPropertyValue(fieldName);
+      if (!content || typeof content !== "string") {
+        continue;
+      }
+      const contentHash = ContentHasher.hash(content);
+      if (!options.force) {
+        const existing = await EmbeddingStorage.get(
+          this.systemDb,
+          this.constructor.name,
+          this.id,
+          fieldName,
+          embeddingProvider.getModelName()
+        );
+        if (existing && existing.content_hash === contentHash) {
+          continue;
+        }
+      }
+      const embeddings = await embeddingProvider.embed(content);
+      const embedding = embeddings[0];
+      await EmbeddingStorage.upsert(
+        this.systemDb,
+        {
+          objectClass: this.constructor.name,
+          objectId: this.id,
+          fieldName,
+          contentHash,
+          embedding,
+          model: embeddingProvider.getModelName(),
+          dimensions: config.dimensions,
+          provider
+        },
+        vector
+      );
+    }
+    if (config.combinedField) {
+      const { name, template } = config.combinedField;
+      let combinedContent = template;
+      for (const fieldName of config.fields) {
+        const value = this.getPropertyValue(fieldName) || "";
+        combinedContent = combinedContent.replace(
+          new RegExp(`\\{${fieldName}\\}`, "g"),
+          String(value)
+        );
+      }
+      if (combinedContent.trim()) {
+        const contentHash = ContentHasher.hash(combinedContent);
+        if (!options.force) {
+          const existing = await EmbeddingStorage.get(
+            this.systemDb,
+            this.constructor.name,
+            this.id,
+            name,
+            embeddingProvider.getModelName()
+          );
+          if (existing && existing.content_hash === contentHash) {
+            return;
+          }
+        }
+        const embeddings = await embeddingProvider.embed(combinedContent);
+        const embedding = embeddings[0];
+        await EmbeddingStorage.upsert(
+          this.systemDb,
+          {
+            objectClass: this.constructor.name,
+            objectId: this.id,
+            fieldName: name,
+            contentHash,
+            embedding,
+            model: embeddingProvider.getModelName(),
+            dimensions: config.dimensions,
+            provider
+          },
+          vector
+        );
+      }
+    }
+  }
+  /**
+   * Get stored embedding for a field
+   *
+   * Retrieves the embedding vector for a specific field from storage.
+   * Returns null if no embedding exists for the field.
+   *
+   * @param fieldName - Name of the field to get embedding for
+   * @param model - Optional model name (defaults to configured model)
+   * @returns Promise resolving to embedding vector or null
+   *
+   * @example
+   * ```typescript
+   * const embedding = await article.getEmbedding('title');
+   * if (embedding) {
+   *   console.log(`Embedding has ${embedding.length} dimensions`);
+   * }
+   * ```
+   */
+  async getEmbedding(fieldName, model) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    if (!this.id) {
+      return null;
+    }
+    let modelName = model;
+    if (!modelName) {
+      const config = ObjectRegistry.resolveEmbeddingConfig(
+        this.constructor.name
+      );
+      if (config) {
+        const aiClient = await this.getOptionalAiClient();
+        const provider = new EmbeddingProvider(
+          {
+            dimensions: config.dimensions,
+            provider: config.provider,
+            localModel: config.localModel,
+            aiModel: config.aiModel,
+            fallbackToAI: config.fallbackToAI
+          },
+          aiClient
+        );
+        modelName = provider.getModelName();
+      } else {
+        modelName = "Xenova/bge-base-en-v1.5";
+      }
+    }
+    const stored = await EmbeddingStorage.get(
+      this.systemDb,
+      this.constructor.name,
+      this.id,
+      fieldName,
+      modelName
+    );
+    return stored?.embedding || null;
+  }
+  /**
+   * Check if any embeddings are stale (content has changed)
+   *
+   * Compares content hashes of configured fields with stored embeddings
+   * to determine if regeneration is needed.
+   *
+   * @returns Promise resolving to true if any embeddings are stale
+   *
+   * @example
+   * ```typescript
+   * if (await article.hasStaleEmbeddings()) {
+   *   await article.generateEmbeddings();
+   * }
+   * ```
+   */
+  async hasStaleEmbeddings() {
+    if (!this.systemDb || !this.id) {
+      return false;
+    }
+    const config = ObjectRegistry.resolveEmbeddingConfig(this.constructor.name);
+    if (!config) {
+      return false;
+    }
+    const aiClient = await this.getOptionalAiClient();
+    const embeddingProvider = new EmbeddingProvider(
+      {
+        dimensions: config.dimensions,
+        provider: config.provider,
+        localModel: config.localModel,
+        aiModel: config.aiModel,
+        fallbackToAI: config.fallbackToAI
+      },
+      aiClient
+    );
+    const modelName = embeddingProvider.getModelName();
+    const storedEmbeddings = await EmbeddingStorage.getForObject(
+      this.systemDb,
+      this.constructor.name,
+      this.id
+    );
+    for (const fieldName of config.fields) {
+      const content = this.getPropertyValue(fieldName);
+      if (!content || typeof content !== "string") {
+        continue;
+      }
+      const currentHash = ContentHasher.hash(content);
+      const stored = storedEmbeddings.find(
+        (e) => e.field_name === fieldName && e.model === modelName
+      );
+      if (!stored) {
+        return true;
+      }
+      if (stored.content_hash !== currentHash) {
+        return true;
+      }
+    }
+    if (config.combinedField) {
+      let combinedContent = config.combinedField.template;
+      for (const fieldName of config.fields) {
+        const value = this.getPropertyValue(fieldName) || "";
+        combinedContent = combinedContent.replace(
+          new RegExp(`\\{${fieldName}\\}`, "g"),
+          String(value)
+        );
+      }
+      const currentHash = ContentHasher.hash(combinedContent);
+      const stored = storedEmbeddings.find(
+        (e) => e.field_name === config.combinedField?.name && e.model === modelName
+      );
+      if (!stored || stored.content_hash !== currentHash) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Clear all embeddings for this object
+   *
+   * Removes all stored embeddings from the _smrt_embeddings table.
+   * Useful when deleting objects or resetting embedding state.
+   *
+   * @returns Promise that resolves when embeddings are cleared
+   *
+   * @example
+   * ```typescript
+   * await article.clearEmbeddings();
+   * ```
+   */
+  async clearEmbeddings() {
+    if (!this.systemDb || !this.id) {
+      return;
+    }
+    await EmbeddingStorage.deleteForObject(
+      this.systemDb,
+      this.constructor.name,
+      this.id
+    );
+  }
+}
+export {
+  SmrtObject
+};
+//# sourceMappingURL=object.js.map