@happyvertical/smrt-core 0.30.0

package/dist/object.d.ts

@@ -0,0 +1,1202 @@
+import { AITool } from '@happyvertical/ai';
+import { SmrtClassOptions, SmrtClass } from './class';
+import { GenerateEmbeddingsOptions } from './embeddings/types';
+import { ToolCall, ToolCallResult } from './tools/tool-executor';
+/**
+ * Options for SmrtObject initialization
+ */
+export interface SmrtObjectOptions extends SmrtClassOptions {
+    /**
+     * Unique identifier for the object
+     */
+    id?: string;
+    /**
+     * URL-friendly identifier
+     */
+    slug?: string;
+    /**
+     * Optional context to scope the slug (could be a path, domain, etc.)
+     */
+    context?: string;
+    /**
+     * Creation timestamp
+     */
+    created_at?: Date;
+    /**
+     * Last update timestamp
+     */
+    updated_at?: Date;
+    /**
+     * Flag to skip automatic field extraction (internal use)
+     */
+    _extractingFields?: boolean;
+    /**
+     * Flag to skip database loading (internal use)
+     */
+    _skipLoad?: boolean;
+    /**
+     * Flag to skip save-time embedding auto-generation (internal use).
+     *
+     * This is used when framework code will generate embeddings explicitly after
+     * saving and wants to avoid racing a duplicate background generation.
+     */
+    _skipAutoEmbeddings?: boolean;
+    /**
+     * Allow arbitrary field values to be passed
+     */
+    [key: string]: any;
+}
+/**
+ * Options for the relationship loaders {@link SmrtObject.loadRelated},
+ * {@link SmrtObject.loadRelatedMany}, and {@link SmrtObject.getRelated}.
+ */
+export interface LoadRelatedOptions {
+    /**
+     * Bypass the cross-tenant isolation guard.
+     *
+     * By default, resolving a relationship from a tenant-scoped object to an
+     * object in a *different*, non-null tenant throws a `TenantIsolationError`.
+     * Set this to `true` for deliberate cross-tenant flows (admin tooling,
+     * migrations, super-admin bypass paths) where the access is intentional.
+     *
+     * @default false
+     */
+    allowCrossTenant?: boolean;
+}
+/**
+ * Base class for all persistent SMRT domain objects.
+ *
+ * Provides a full ORM lifecycle: construct with options, call `initialize()`,
+ * then use `save()` / `delete()` for persistence. Objects are identified by a
+ * UUID `id` and an optional URL-friendly `slug` (auto-generated from `name`,
+ * `title`, `label`, or `id` if not provided).
+ *
+ * Key capabilities:
+ * - **Persistence**: `save()` (upsert with retry), `delete()` (with hooks)
+ * - **Loading**: `loadFromId()`, `loadFromSlug()` (called automatically by `initialize()`)
+ * - **AI operations**: `is()` (boolean criteria check), `do()` (freeform instruction)
+ * - **Relationships**: `loadRelated()` (foreignKey), `loadRelatedMany()` (oneToMany)
+ * - **Context memory**: `remember()` / `recall()` / `recallAll()` / `forget()` / `forgetScope()`
+ * - **STI support**: `_meta_type` discriminator, `_meta_data` JSONB for child fields
+ * - **Serialization**: `toJSON()` (framework-managed, handles STI), `transformJSON()` (override hook)
+ *
+ * @example
+ * ```typescript
+ * @smrt()
+ * class Product extends SmrtObject {
+ *   name: string = '';
+ *   price: number = 0.0;
+ * }
+ *
+ * const product = new Product({ db: myDb, name: 'Widget', price: 9.99 });
+ * await product.initialize();
+ * await product.save();
+ * console.log(product.id); // auto-generated UUID
+ * ```
+ */
+export declare class SmrtObject extends SmrtClass {
+    /**
+     * Database table name for this object
+     */
+    _tableName: string;
+    /**
+     * Cache for loaded relationships to avoid repeated database queries
+     * Maps fieldName to loaded object(s)
+     */
+    private _loadedRelationships;
+    /**
+     * 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).
+     */
+    private _persisted;
+    /**
+     * Override options with SmrtObjectOptions type for proper type narrowing.
+     * Initialized by parent constructor via super() call.
+     */
+    options: SmrtObjectOptions;
+    /**
+     * Unique identifier for the object
+     */
+    protected _id: string | null | undefined;
+    /**
+     * URL-friendly identifier
+     */
+    protected _slug: string | null | undefined;
+    /**
+     * Optional context to scope the slug
+     */
+    protected _context: string | null | undefined;
+    /**
+     * Creation timestamp
+     */
+    created_at: Date | null | undefined;
+    /**
+     * Last update timestamp
+     */
+    updated_at: Date | null | undefined;
+    /**
+     * Creates a new SmrtObject instance
+     *
+     * @param options - Configuration options including identifiers and metadata
+     * @throws Error if options is null
+     */
+    constructor(options?: SmrtObjectOptions);
+    private getRegisteredClassInfo;
+    protected getResolvedClassName(): string;
+    protected getResolvedQualifiedName(): string;
+    private getCurrentMetaType;
+    private isLegacySTIDiscriminatorUpgrade;
+    private planPersistenceWrite;
+    /**
+     * Protected setter for ID to maintain type safety
+     * Used internally by collection.create() and other framework code
+     * @internal
+     */
+    protected setId(id: string): void;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): void;
+    protected verifyStorageReady(): Promise<void>;
+    /**
+     * Protected setter for STI discriminator to maintain type safety
+     * Used internally for Single Table Inheritance support
+     * @internal
+     */
+    protected setMetaType(metaType: string): void;
+    /**
+     * 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
+     */
+    private cloneValue;
+    /**
+     * 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)
+     */
+    private initializePropertiesFromOptions;
+    /**
+     * Gets the unique identifier for this object
+     */
+    get id(): string | null | undefined;
+    /**
+     * Sets the unique identifier for this object
+     *
+     * @param value - The ID to set
+     * @throws Error if the value is invalid
+     */
+    set id(value: string | null | undefined);
+    /**
+     * Gets the URL-friendly slug for this object
+     */
+    get slug(): string | null | undefined;
+    /**
+     * Sets the URL-friendly slug for this object
+     *
+     * @param value - The slug to set
+     * @throws Error if the value is invalid
+     */
+    set slug(value: string | null | undefined);
+    /**
+     * Gets the context that scopes this object's slug
+     */
+    get context(): string;
+    /**
+     * 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: string | null | undefined);
+    /**
+     * 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);
+     * ```
+     */
+    initialize(): Promise<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
+     */
+    private needsPropertyInitialization;
+    /**
+     * 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
+     */
+    loadDataFromDb(data: any): Promise<void>;
+    /**
+     * Gets the database table name for this object
+     */
+    get tableName(): string;
+    /**
+     * Gets field definitions and current values for this object
+     *
+     * @returns Object containing field definitions with current values
+     */
+    getFields(): Promise<Record<string, any>>;
+    /**
+     * 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)
+     */
+    protected transformJSON(data: any): any;
+    /**
+     * 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(): any;
+    /**
+     * 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(): Record<string, unknown>;
+    /**
+     * 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.
+     */
+    private getSensitiveFieldNames;
+    /**
+     * 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(): Record<string, unknown>;
+    /**
+     * Gets or generates a unique ID for this object
+     *
+     * @returns Promise resolving to the object's ID
+     */
+    getId(): Promise<string>;
+    /**
+     * 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'
+     * ```
+     */
+    getSlug(): Promise<string | null | undefined>;
+    /**
+     * 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
+     */
+    getSavedId(): Promise<any>;
+    /**
+     * Checks if this object is already saved in the database
+     *
+     * @returns Promise resolving to true if saved, false otherwise
+     */
+    isSaved(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private resolveUuidColumnNames;
+    /**
+     * 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.
+     */
+    private coerceEmptyUuidValuesToNull;
+    /**
+     * 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();
+     * ```
+     */
+    save(): Promise<this>;
+    /**
+     * 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.
+     */
+    private isTenantContractError;
+    /**
+     * Validates object state before saving
+     * Override in subclasses to add custom validation logic
+     */
+    protected validateBeforeSave(): Promise<void>;
+    /**
+     * 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()`).
+     */
+    protected validateCrossPackageRefs(): Promise<void>;
+    /**
+     * Gets the value of a field on this object
+     */
+    protected getFieldValue(fieldName: string): any;
+    /**
+     * Gets the value of a property.
+     *
+     * @param key - Property name to get value from
+     * @returns The property value
+     */
+    protected getPropertyValue(key: string): any;
+    /**
+     * 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: string): 'unique' | 'not_null' | 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.
+     */
+    protected extractConstraintField(errorMessage: string): string;
+    /**
+     * 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
+     * ```
+     */
+    loadFromId(): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    loadFromSlug(): Promise<void>;
+    /**
+     * 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
+     */
+    private serializeForAiPrompt;
+    /**
+     * 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 `''`
+     */
+    private buildAiContentSection;
+    /**
+     * 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
+     */
+    is(criteria: string, options?: any): Promise<any>;
+    /**
+     * 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
+     */
+    do(instructions: string, options?: any): Promise<string>;
+    /**
+     * 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"
+     * ```
+     */
+    describe(options?: any): Promise<string>;
+    /**
+     * 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
+     */
+    protected runHook(hookName: string): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * 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.
+     */
+    private invalidateCollectionReadCache;
+    /**
+     * 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.
+     */
+    private shouldBroadcastCacheInvalidation;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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
+     */
+    loadRelated(fieldName: string, opts?: LoadRelatedOptions): Promise<any>;
+    /**
+     * 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.
+     */
+    private assertRelatedTenant;
+    /**
+     * 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`);
+     * ```
+     */
+    loadRelatedMany(fieldName: string, opts?: LoadRelatedOptions): Promise<any[]>;
+    /**
+     * 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.
+     */
+    protected resolveManyToManyJoin(fieldName: string, relationship: {
+        sourceClass: string;
+        targetClass: string;
+        options?: any;
+    }): Promise<{
+        through: string;
+        sourceColumn: string;
+        targetColumn: string;
+        targetClassName: string;
+    }>;
+    /**
+     * 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');
+     * ```
+     */
+    getRelated(fieldName: string, opts?: LoadRelatedOptions): Promise<any>;
+    /**
+     * 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(): AITool[];
+    /**
+     * 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);
+     * ```
+     */
+    executeToolCall(toolCall: ToolCall): Promise<ToolCallResult>;
+    /**
+     * 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
+     */
+    remember(options: {
+        id?: string;
+        scope: string;
+        key: string;
+        value: any;
+        metadata?: any;
+        confidence?: number;
+        version?: number;
+        expiresAt?: Date;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    recall(options: {
+        scope: string;
+        key: string;
+        includeAncestors?: boolean;
+        minConfidence?: number;
+    }): Promise<any | 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
+     */
+    recallAll(options?: {
+        scope?: string;
+        includeDescendants?: boolean;
+        minConfidence?: number;
+    }): Promise<Map<string, any>>;
+    /**
+     * 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
+     */
+    forget(options: {
+        scope: string;
+        key: string;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    forgetScope(options: {
+        scope: string;
+        includeDescendants?: boolean;
+    }): Promise<number>;
+    /**
+     * 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 });
+     * ```
+     */
+    generateEmbeddings(options?: GenerateEmbeddingsOptions): Promise<void>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    getEmbedding(fieldName: string, model?: string): Promise<number[] | 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();
+     * }
+     * ```
+     */
+    hasStaleEmbeddings(): Promise<boolean>;
+    /**
+     * 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();
+     * ```
+     */
+    clearEmbeddings(): Promise<void>;
+}
+//# sourceMappingURL=object.d.ts.map