@happyvertical/smrt-core 0.30.0

package/dist/registry.d.ts

@@ -0,0 +1,1358 @@
+import { SmrtCollection } from './collection';
+import { CollectionCacheConfig } from './collection-cache';
+import { ClassEmbeddingConfig, ProjectEmbeddingConfig, ResolvedEmbeddingConfig } from './embeddings/types';
+import { SmrtObject } from './object';
+import { RegistryDiagnostic } from './registry/diagnostics';
+import { RegisteredClass, RelationshipMetadata, SmartObjectConfig, SmrtObjectConstructor, ValidatorFunction } from './registry/types';
+import { QualifiedClassName, SmrtVisibility, ValidationRule } from './scanner/types.js';
+import { SchemaDefinition } from './schema/types.js';
+export { isSmrtCollectionExtendsName, SMRT_COLLECTION_BASE_NAMES, } from './registry/collection-resolution';
+export type { RelationshipMetadata, RelationshipType, SmartObjectConfig, } from './registry/types';
+/**
+ * Central registry for all SMRT objects
+ *
+ * Uses globalThis for cross-module state sharing, ensuring all module instances
+ * (even from different package resolution paths) share the same registry state.
+ */
+export declare class ObjectRegistry {
+    /**
+     * Get the classes map from globalThis, initializing if needed
+     */
+    private static get classes();
+    /**
+     * Get the collections map from globalThis, initializing if needed
+     */
+    private static get collections();
+    /**
+     * Get the collection table names map from globalThis, initializing if needed
+     * Maps collection class name -> tableName for getTableName lookups
+     */
+    private static get collectionTableNames();
+    /**
+     * Set the table name for a collection class
+     * Used by @smrt() decorator to enable getTableName lookups for collections
+     */
+    static setCollectionTableName(collectionName: string, tableName: string): void;
+    /**
+     * Get the collection cache from globalThis, initializing if needed
+     */
+    private static get collectionCache();
+    /**
+     * Configure the collection cache size (for testing purposes)
+     *
+     * Resets the collection cache with a new maximum size.
+     * Use this in tests to avoid creating many database files.
+     *
+     * @param maxSize - Maximum number of collections to cache (system default is 100)
+     * @throws Error if maxSize is not a positive finite number
+     * @example
+     * ```typescript
+     * // In test setup, use a small cache to test LRU eviction with fewer DBs
+     * ObjectRegistry.configureCollectionCache(5);
+     * ```
+     */
+    static configureCollectionCache(maxSize: number): void;
+    /**
+     * WeakMap to assign unique IDs to database instances for cache keys
+     * Prevents cache key collisions when different db instances are used
+     */
+    private static get dbInstanceIds();
+    /**
+     * Get/set the next database ID counter
+     */
+    private static get nextDbId();
+    private static set nextDbId(value);
+    /**
+     * Storage for field decorator metadata (decorator pattern)
+     * Maps className → Map<propertyKey, FieldOptions>
+     * Used by @field(), @foreignKey(), @oneToMany(), @manyToMany() decorators
+     */
+    private static get fieldDecorators();
+    /**
+     * Track collections that have been processed for STI siblings
+     * Prevents infinite recursion when loading siblings
+     */
+    private static get stiSiblingsLoaded();
+    /**
+     * Check if a class is already registered (case-insensitive)
+     * Returns the canonical name if found, undefined otherwise.
+     *
+     * Release B (#1133): iteration over `classes` replaces the old eagerly-
+     * maintained classNameMap index. Negligible cost at production scale and
+     * removes an entire class of cache-sync bugs.
+     */
+    static getCanonicalClassName(name: string): string | undefined;
+    /**
+     * Check if a class exists by name (case-insensitive)
+     */
+    static hasClassCaseInsensitive(name: string): boolean;
+    /**
+     * Global cache for inheritance chains (shared across all instances)
+     * Maps className → full inheritance chain (base to child)
+     * Performance optimization: ~100x faster than re-walking prototype chain
+     * Cache size is configurable via smrt.inheritance.cacheSize (default: 200)
+     */
+    private static getInheritanceCache;
+    /**
+     * Global cache for manifest discovery attempts (Issue #735 optimization)
+     * Maps className → boolean (true = found and registered, false = not found)
+     * Prevents repeated discoverManifestSync calls for the same class name
+     */
+    private static getDiscoveryAttemptCache;
+    /**
+     * Register field decorator metadata
+     *
+     * Called by property decorators (@field, @foreignKey, etc.) to store
+     * field configuration metadata. This enables the decorator pattern
+     * where field metadata is attached at class definition time.
+     *
+     * @param className - Name of the class containing the field
+     * @param propertyKey - Name of the property being decorated
+     * @param options - Field options (type, constraints, etc.)
+     * @example
+     * ```typescript
+     * // Called internally by decorators
+     * ObjectRegistry.registerFieldDecorator('Product', 'name', {
+     *   type: 'text',
+     *   required: true
+     * });
+     * ```
+     */
+    static registerFieldDecorator(className: string, propertyKey: string, options: any): void;
+    /**
+     * Get field decorator metadata for a specific field
+     *
+     * @param className - Name of the class
+     * @param propertyKey - Name of the property
+     * @returns Field options or undefined if not decorated
+     * @example
+     * ```typescript
+     * const options = ObjectRegistry.getFieldDecorator('Product', 'name');
+     * // { type: 'text', required: true }
+     * ```
+     */
+    static getFieldDecorator(className: string, propertyKey: string): any | undefined;
+    /**
+     * Get all field decorator metadata for a class
+     *
+     * @param className - Name of the class
+     * @returns Map of property names to field options
+     * @example
+     * ```typescript
+     * const fields = ObjectRegistry.getFieldDecorators('Product');
+     * // Map { 'name' => { type: 'text', required: true }, ... }
+     * ```
+     */
+    static getFieldDecorators(className: string): Map<string, any>;
+    /**
+     * Check if a class has any field decorators registered
+     *
+     * @param className - Name of the class
+     * @returns True if the class has field decorators, false otherwise
+     * @example
+     * ```typescript
+     * if (ObjectRegistry.hasFieldDecorators('Product')) {
+     *   // Class uses decorators - skip legacy field initialization
+     * }
+     * ```
+     */
+    static hasFieldDecorators(className: string): boolean;
+    /**
+     * Register a new SMRT object class with the global registry
+     *
+     * @param constructor - The class constructor extending SmrtObject
+     * @param config - Configuration options for API/CLI/MCP generation
+     * @throws {Error} If the class cannot be introspected for field definitions
+     * @example
+     * ```typescript
+     * ObjectRegistry.register(Product, {
+     *   api: { exclude: ['delete'] },
+     *   cli: true,
+     *   mcp: { include: ['list', 'get'] }
+     * });
+     * ```
+     */
+    static register(ctor: typeof SmrtObject, config?: SmartObjectConfig): void;
+    /**
+     * Register a collection class for an object
+     *
+     * @param objectName - Name of the object class this collection manages
+     * @param collectionConstructor - The collection class constructor
+     * @example
+     * ```typescript
+     * ObjectRegistry.registerCollection('Product', ProductCollection);
+     * ```
+     */
+    static registerCollection(objectName: string, collectionConstructor: new (options: any) => SmrtCollection<any>): void;
+    static registerFromManifest(name: string, objectDef: any, packageName?: string): void;
+    /**
+     * Helper method for class lookup with qualified name support.
+     *
+     * Lookup priority:
+     * 1. Direct hit on classes map (works for qualified names as keys)
+     * 2. If input contains ':', treat as qualified name — direct only, no fallback
+     * 3. classNameMap lookup by simple name (lowercase)
+     *    - Unambiguous (1 entry) → return it
+     *    - Ambiguous (>1 entry) → throw descriptive error
+     * 4. Case-insensitive iteration fallback (backward compat)
+     *
+     * @param name - Name of the class to find (simple or qualified)
+     * @returns Registered class information or undefined if not found
+     * @remarks When a simple name is ambiguous (multiple packages define it),
+     *          logs a warning and returns the first match. Use qualified names
+     *          or resolveType() for strict disambiguation.
+     * @private
+     */
+    private static findClass;
+    /**
+     * Get a registered class by name (case-insensitive)
+     *
+     * @param name - Name of the registered class
+     * @returns Registered class information or undefined if not found
+     * @example
+     * ```typescript
+     * const productInfo = ObjectRegistry.getClass('Product');
+     * // Also works with: 'product', 'PRODUCT', etc.
+     * if (productInfo) {
+     *   console.log(productInfo.config.api?.exclude);
+     * }
+     * ```
+     */
+    static getClass(name: string): RegisteredClass | undefined;
+    /**
+     * Get a registered class by its constructor reference.
+     * This is the most reliable lookup method as it avoids name collision issues
+     * that can occur when multiple packages define classes with the same name.
+     *
+     * Uses a WeakMap index for O(1) lookups.
+     *
+     * @param ctor - The class constructor to look up
+     * @returns Registered class information or undefined if not found
+     * @example
+     * ```typescript
+     * import { Meeting } from '@happyvertical/praeco';
+     *
+     * const info = ObjectRegistry.getClassByConstructor(Meeting);
+     * if (info) {
+     *   console.log(info.qualifiedName); // '@happyvertical/praeco:Meeting'
+     * }
+     * ```
+     */
+    static getClassByConstructor(ctor: SmrtObjectConstructor): RegisteredClass | undefined;
+    /**
+     * Get a registered class by its qualified name.
+     * Qualified names are in format "@package/name:ClassName".
+     *
+     * @param qualifiedName - The fully qualified class name
+     * @returns Registered class information or undefined if not found
+     * @example
+     * ```typescript
+     * const product = ObjectRegistry.getClassByQualifiedName('@happyvertical/smrt-products:Product');
+     * if (product) {
+     *   console.log(`Found: ${product.name} from ${product.packageName}`);
+     * }
+     * ```
+     */
+    static getClassByQualifiedName(qualifiedName: string): RegisteredClass | undefined;
+    /**
+     * Get a registered class by package name and class name.
+     * This is a convenience method for looking up classes by their namespace components.
+     *
+     * @param packageName - The package name (e.g., "@happyvertical/smrt-products")
+     * @param className - The class name (e.g., "Product")
+     * @returns Registered class information or undefined if not found
+     * @example
+     * ```typescript
+     * const product = ObjectRegistry.getClassInPackage('@happyvertical/smrt-products', 'Product');
+     * ```
+     */
+    static getClassInPackage(packageName: string, className: string): RegisteredClass | undefined;
+    /**
+     * Find all registered classes with a given simple class name.
+     * Useful for detecting collisions or when multiple packages have the same class name.
+     *
+     * @param className - The simple class name to search for
+     * @returns Array of registered classes with matching name
+     * @example
+     * ```typescript
+     * const products = ObjectRegistry.findClassesByName('Product');
+     * if (products.length > 1) {
+     *   console.log(`Found ${products.length} classes named "Product":`);
+     *   for (const p of products) {
+     *     console.log(`  - ${p.qualifiedName} from ${p.packageName}`);
+     *   }
+     * }
+     * ```
+     */
+    static findClassesByName(className: string): RegisteredClass[];
+    /**
+     * Resolve a short class name to its qualified name.
+     * Throws an error if the name is ambiguous (multiple packages define the same class name).
+     *
+     * @param shortName - The simple class name to resolve (e.g., 'MeetingRecap')
+     * @returns The qualified class name (e.g., '@happyvertical/praeco:MeetingRecap')
+     * @throws {Error} If no class with that name is registered
+     * @throws {Error} If multiple classes with that name exist (ambiguous)
+     *
+     * @example
+     * ```typescript
+     * // Unambiguous resolution
+     * const qualified = ObjectRegistry.resolveType('MeetingRecap');
+     * // Returns: '@happyvertical/praeco:MeetingRecap'
+     *
+     * // Already qualified names pass through
+     * const same = ObjectRegistry.resolveType('@happyvertical/praeco:MeetingRecap');
+     * // Returns: '@happyvertical/praeco:MeetingRecap'
+     *
+     * // Ambiguous names throw
+     * ObjectRegistry.resolveType('Event');
+     * // Error: "Event" is ambiguous. Found in multiple packages:
+     * //   - @happyvertical/smrt-events:Event
+     * //   - @happyvertical/calendar:Event
+     * // Use the fully qualified name instead.
+     * ```
+     */
+    static resolveType(shortName: string): QualifiedClassName;
+    /**
+     * Get all registered classes from a specific package.
+     *
+     * @param packageName - The package name to filter by
+     * @returns Map of class names to registered class information
+     * @example
+     * ```typescript
+     * const coreClasses = ObjectRegistry.getClassesByPackage('@happyvertical/smrt-core');
+     * for (const [name, info] of coreClasses) {
+     *   console.log(`  ${name}: ${info.qualifiedName}`);
+     * }
+     * ```
+     */
+    static getClassesByPackage(packageName: string): Map<string, RegisteredClass>;
+    /**
+     * Get all registered classes with a specific visibility level.
+     *
+     * @param visibility - The visibility level to filter by
+     * @returns Map of class names to registered class information
+     * @example
+     * ```typescript
+     * const publicClasses = ObjectRegistry.getClassesByVisibility('public');
+     * console.log(`Found ${publicClasses.size} public classes`);
+     * ```
+     */
+    static getClassesByVisibility(visibility: SmrtVisibility): Map<string, RegisteredClass>;
+    /**
+     * Get all public registered classes (excludes 'internal' and 'test' visibility).
+     * Useful for generating published manifests or public APIs.
+     *
+     * @returns Map of class names to registered class information
+     * @example
+     * ```typescript
+     * const publicClasses = ObjectRegistry.getPublicClasses();
+     * console.log(`Publishing ${publicClasses.size} public classes to manifest`);
+     * ```
+     */
+    static getPublicClasses(): Map<string, RegisteredClass>;
+    /**
+     * Get all registered classes
+     *
+     * @returns Map of class names to registered class information
+     * @example
+     * ```typescript
+     * const allClasses = ObjectRegistry.getAllClasses();
+     * for (const [name, info] of allClasses) {
+     *   console.log(`Class: ${name}, Fields: ${info.fields.size}`);
+     * }
+     * ```
+     */
+    static getAllClasses(): Map<string, RegisteredClass>;
+    /**
+     * Get class names, deduplicated by simple class name.
+     *
+     * This is useful for display and backwards compatibility. Use
+     * `getQualifiedClassNames()` for schema/bootstrap loops that must preserve
+     * cross-package collisions.
+     */
+    static getClassNames(): string[];
+    /**
+     * Get one lookup name per registered class, preserving cross-package
+     * collisions by preferring qualified class names where available.
+     */
+    static getQualifiedClassNames(): string[];
+    /**
+     * Try to load and register a class from external SMRT packages
+     *
+     * This method attempts to auto-discover classes from @happyvertical/smrt-* packages
+     * when they're referenced but not yet registered. Solves issue #343 where STI classes
+     * from external packages (e.g., Person from smrt-profiles) weren't loading correctly.
+     *
+     * @param className - Name of the class to load
+     * @returns Promise<boolean> - True if successfully loaded and registered, false otherwise
+     * @private
+     */
+    static tryLoadFromExternalPackage(className: string): Promise<boolean>;
+    /**
+     * Load all manifests upfront so inheritance queries are pure lookups.
+     *
+     * After this method completes, every class across all packages is
+     * registered and `getInheritanceChain()` will never need to mutate
+     * registry state.
+     *
+     * @param options - Optional configuration
+     * @param options.manifestPaths - Explicit list of manifest.json file paths to load.
+     *   When omitted the method discovers packages via `loadExternalManifestSync()`
+     *   for every `@happyvertical` package found in `node_modules`.
+     * @returns Summary statistics about the load operation
+     *
+     * @example
+     * ```typescript
+     * // At CLI / server startup
+     * ObjectRegistry.loadAllManifests();
+     * // All classes are now registered — inheritance lookups are side-effect free
+     * ```
+     *
+     * @see https://github.com/happyvertical/smrt/issues/1007
+     */
+    static loadAllManifests(options?: {
+        manifestPaths?: string[];
+    }): {
+        packagesLoaded: number;
+        objectsRegistered: number;
+    };
+    /**
+     * Register a package's own bundled manifest, called by the package itself at
+     * import time to eliminate the consumer-runtime field-drop bug (issue #1132).
+     *
+     * Packages ship a `dist/manifest.json` next to their compiled entry. A small
+     * `__smrt-register__.js` side-effect module imports that file URL and calls
+     * this method *before* any `@smrt()` decorator in the package fires, so the
+     * decorator's synchronous manifest lookup hits a populated cache instead of
+     * registering classes with zero fields.
+     *
+     * Silently no-ops if the URL can't be read — in dev/test the vitest plugin
+     * populates manifests through a different path, and this fallback is expected
+     * to miss in those contexts.
+     *
+     * @param manifestUrl - File URL (or string) pointing to the package's
+     *   manifest.json. Typical call site:
+     *   `new URL('./manifest.json', import.meta.url)`
+     * @returns Summary with loaded status, package name, and object count
+     *
+     * @example
+     * ```typescript
+     * // packages/smrt-places/src/__smrt-register__.ts
+     * import { ObjectRegistry } from '@happyvertical/smrt-core';
+     * ObjectRegistry.registerPackageManifest(
+     *   new URL('./manifest.json', import.meta.url),
+     * );
+     * ```
+     *
+     * @see https://github.com/happyvertical/smrt/issues/1132
+     */
+    static registerPackageManifest(manifestUrl: string | URL): {
+        loaded: boolean;
+        packageName?: string;
+        objectsRegistered: number;
+    };
+    /**
+     * Snapshot of diagnostics collected from registry load paths.
+     *
+     * Registry paths that previously `console.warn(...); return null` also
+     * record a structured diagnostic. Apps can inspect this buffer at startup
+     * or from an error route to surface failures that would otherwise be silent.
+     *
+     * Strict mode is **on by default** since Release C (#1134): severity
+     * `'error'` diagnostics throw at record time. Set
+     * `SMRT_STRICT_REGISTRY=false` to restore the pre-Release-C permissive
+     * behavior where only the diagnostic is recorded and nothing throws.
+     *
+     * @see https://github.com/happyvertical/smrt/issues/1132
+     * @see https://github.com/happyvertical/smrt/issues/1134
+     */
+    static getDiagnostics(): readonly RegistryDiagnostic[];
+    /** Clear the diagnostic buffer. Primarily for tests. */
+    static clearDiagnostics(): void;
+    /**
+     * Pretty-print the diagnostic buffer via `console.warn` / `console.error`.
+     * No-op when the buffer is empty.
+     */
+    static flushDiagnostics(): void;
+    /**
+     * Check if a class is registered (case-insensitive)
+     */
+    static hasClass(name: string): boolean;
+    /**
+     * Clear all registered classes (mainly for testing)
+     */
+    static clear(): void;
+    /**
+     * Invalidate inheritance cache for a specific class
+     *
+     * Clears cached inheritance chain and merged fields/methods for the given class.
+     * Call this when a class definition changes at runtime (e.g., hot module reload).
+     *
+     * @param className - The class name to invalidate cache for
+     * @example
+     * ```typescript
+     * // After hot module reload of a parent class
+     * ObjectRegistry.invalidateInheritanceCache('BentleyContent');
+     * ```
+     */
+    static invalidateInheritanceCache(className: string): void;
+    /**
+     * Invalidate all inheritance caches
+     *
+     * Clears all cached inheritance chains and merged fields/methods.
+     * Call this when multiple classes change at runtime.
+     *
+     * @example
+     * ```typescript
+     * // After hot module reload of multiple classes
+     * ObjectRegistry.invalidateAllInheritanceCaches();
+     * ```
+     */
+    static invalidateAllInheritanceCaches(): void;
+    /**
+     * Resolve a collection lookup name to the registered object metadata and
+     * collection constructor that should back it.
+     *
+     * Accepts any supported collection identifier:
+     * - simple class name (`FactRecord`)
+     * - qualified class name (`@pkg:FactRecord`)
+     * - explicit collection alias (`fact_records`) when registered
+     *
+     * Returns a canonical class identity so cache keys remain stable across
+     * aliases that refer to the same underlying collection.
+     */
+    private static resolveCollectionRegistration;
+    /**
+     * Get or create a cached collection instance (Singleton pattern - Phase 4 optimization)
+     *
+     * Returns a cached collection if one exists for the given class and options,
+     * otherwise creates, initializes, and caches a new instance. This significantly
+     * improves performance by avoiding repeated collection initialization.
+     *
+     * **Performance Impact**: 60-80% reduction in collection initialization overhead
+     *
+     * **Cache Key Strategy**: Collections are cached based on:
+     * - className
+     * - persistence configuration (type, url, baseUrl)
+     * - db presence (not full config)
+     * - ai presence (not full config)
+     *
+     * Different persistence configurations create separate cached instances.
+     *
+     * @param className - Name of the object class
+     * @param options - Configuration options for the collection
+     * @returns Cached or newly created collection instance
+     * @throws {Error} If the class is not registered or has no collection
+     *
+     * @example
+     * ```typescript
+     * // First call creates and caches the collection
+     * const orders1 = await ObjectRegistry.getCollection('Order', {
+     *   persistence: { type: 'sql', url: 'orders.db' }
+     * });
+     *
+     * // Subsequent calls return the cached instance (much faster)
+     * const orders2 = await ObjectRegistry.getCollection('Order', {
+     *   persistence: { type: 'sql', url: 'orders.db' }
+     * });
+     * console.log(orders1 === orders2); // true (same instance)
+     *
+     * // Different configuration creates new instance
+     * const orders3 = await ObjectRegistry.getCollection('Order', {
+     *   persistence: { type: 'sql', url: 'orders-copy.db' }
+     * });
+     * console.log(orders1 === orders3); // false (different config)
+     * ```
+     *
+     * @see {@link https://github.com/happyvertical/sdk/blob/main/packages/core/CLAUDE.md#singleton-collection-management-phase-4|Phase 4 Documentation}
+     */
+    static getCollection<T extends SmrtObject>(className: string, options?: any): Promise<SmrtCollection<T>>;
+    /**
+     * Get field definitions for a registered class.
+     * Supports both qualified names and simple class names.
+     */
+    static getFields(name: string): Map<string, any>;
+    /**
+     * Get method definitions for a registered class
+     *
+     * Returns method metadata extracted from the manifest during AST scanning.
+     * This enables code generators (CLI, API, MCP) to discover custom methods
+     * and automatically generate corresponding commands/endpoints/tools.
+     *
+     * @param name - Name of the registered class
+     * @returns Map of method names to MethodDefinition objects
+     * @example
+     * ```typescript
+     * const methods = ObjectRegistry.getMethods('Agent');
+     * for (const [name, methodDef] of methods) {
+     *   console.log(`Method: ${name}`);
+     *   console.log(`  Async: ${methodDef.async}`);
+     *   console.log(`  Public: ${methodDef.isPublic}`);
+     *   console.log(`  Params: ${methodDef.parameters.map(p => p.name).join(', ')}`);
+     * }
+     * ```
+     */
+    static getMethods(name: string): Map<string, any>;
+    static compileValidators(className: string, fields: Map<string, any>): ValidatorFunction[];
+    /**
+     * Ensure manifest is loaded for external package classes
+     *
+     * For classes from external packages, the manifest may not be loaded during
+     * initial registration (which must be synchronous for decorator support).
+     * This method loads the manifest asynchronously when needed.
+     *
+     * @param className - Name of the class to ensure manifest is loaded for
+     * @returns Promise that resolves when manifest is loaded (or already loaded)
+     * @throws {Error} If manifest cannot be found
+     *
+     * @example
+     * ```typescript
+     * // Before using fields from external package
+     * await ObjectRegistry.ensureManifestLoaded('Place');
+     * const fields = ObjectRegistry.getFields('Place'); // Now has fields
+     * ```
+     */
+    static ensureManifestLoaded(className: string): Promise<void>;
+    /**
+     * Get configuration for a registered class
+     */
+    static getConfig(name: string): SmartObjectConfig;
+    /**
+     * Get cached schema definition for a registered class
+     */
+    static getSchema(name: string): SchemaDefinition | undefined;
+    /**
+     * Get SQL DDL statement for a registered class
+     */
+    static getSchemaDDL(name: string): string | undefined;
+    /**
+     * Get table name for a registered class
+     */
+    static getTableName(name: string): string | undefined;
+    /**
+     * Get all pre-generated schemas for passing to database adapters
+     */
+    static getAllSchemas(): Record<string, {
+        tableName: string;
+        ddl: string;
+        indexes?: string[];
+    }>;
+    /**
+     * Get all registered schemas as SchemaDefinition objects
+     */
+    static getAllSchemasAsDefinitions(): Record<string, SchemaDefinition>;
+    /**
+     * Get compiled validation functions for a registered class
+     *
+     * Returns pre-compiled validation functions that can be executed
+     * at runtime for efficient validation without repeated setup.
+     *
+     * @param name - Name of the registered class
+     * @returns Array of validation functions or undefined if not found
+     * @example
+     * ```typescript
+     * const validators = ObjectRegistry.getValidators('Product');
+     * for (const validator of validators || []) {
+     *   const error = await validator(productInstance);
+     *   if (error) console.error(error);
+     * }
+     * ```
+     */
+    static getValidators(name: string): ValidatorFunction[] | undefined;
+    /**
+     * Get pre-computed validation rules for a registered class
+     *
+     * Returns serializable validation rules that can be evaluated at runtime
+     * without needing pre-compiled validator closures. This significantly
+     * reduces CLI startup time for projects with many SMRT objects.
+     *
+     * @param name - Name of the registered class
+     * @returns Array of validation rules or undefined if not found
+     * @see https://github.com/happyvertical/smrt/issues/782
+     */
+    static getValidationRules(name: string): ValidationRule[] | undefined;
+    /**
+     * Validate an instance using pre-computed validation rules
+     *
+     * This method evaluates validation rules without creating closures,
+     * providing faster validation than compiled validator functions.
+     *
+     * @param instance - The object instance to validate
+     * @param rules - Array of validation rules to apply
+     * @param className - Name of the class for error messages
+     * @returns Array of validation errors (empty if valid)
+     * @see https://github.com/happyvertical/smrt/issues/782
+     */
+    static validateWithRules(instance: any, rules: ValidationRule[], className: string): Promise<any[]>;
+    /**
+     * Build dependency graph from foreignKey relationships
+     *
+     * Returns a map where keys are class names and values are arrays
+     * of class names that the key depends on (via foreignKey fields).
+     *
+     * @returns Map of class name to array of dependency class names
+     * @example
+     * ```typescript
+     * const deps = ObjectRegistry.getDependencyGraph();
+     * // { 'Order': ['Customer', 'Product'], 'Customer': [], 'Product': ['Category'] }
+     * ```
+     */
+    static getDependencyGraph(): Map<string, string[]>;
+    /**
+     * Get initialization order for classes based on dependency graph
+     *
+     * Uses topological sort to ensure that classes are initialized in
+     * an order that respects foreignKey dependencies (dependencies first).
+     *
+     * Foreign-key cycles (e.g. smrt-chat's ChatMessage.threadId -> ChatThread
+     * and ChatThread.rootMessageId -> ChatMessage) are BROKEN rather than
+     * treated as a fatal error: when a back-edge is encountered the recursion
+     * stops there, so every class still appears in the returned order. SMRT does
+     * not emit real DB `FOREIGN KEY` constraints in its generated CREATE TABLE
+     * DDL, so a table can be created before its cyclic reference target exists —
+     * the reference is satisfied once both tables are present. This mirrors the
+     * standard RDBMS approach (create tables first, wire cyclic references
+     * afterward) and matches SchemaManager.sortByDependencies, which already
+     * tolerates cycles. See issue #1333.
+     *
+     * @returns Array of class names in initialization order. Every registered
+     *   class appears exactly once; cycle back-edges are dropped from the
+     *   ordering constraints.
+     * @example
+     * ```typescript
+     * const order = ObjectRegistry.getInitializationOrder();
+     * // ['Category', 'Product', 'Customer', 'Order']
+     * // Tables are created in this order to avoid foreign key errors
+     * ```
+     */
+    static getInitializationOrder(): string[];
+    /**
+     * Build comprehensive relationship map from all field types
+     *
+     * Returns a map containing all relationships (foreignKey, oneToMany, manyToMany)
+     * discovered in registered classes. This enables runtime relationship traversal
+     * and eager/lazy loading of related objects.
+     *
+     * @returns Map of class name to array of relationship metadata
+     * @example
+     * ```typescript
+     * const relationships = ObjectRegistry.getRelationshipMap();
+     * // {
+     * //   'Order': [
+     * //     { sourceClass: 'Order', fieldName: 'customerId', targetClass: 'Customer',
+     * //       type: 'foreignKey', options: { onDelete: 'restrict' } }
+     * //   ],
+     * //   'Customer': [
+     * //     { sourceClass: 'Customer', fieldName: 'orders', targetClass: 'Order',
+     * //       type: 'oneToMany', options: {} }
+     * //   ]
+     * // }
+     * ```
+     */
+    static getRelationshipMap(): Map<string, RelationshipMetadata[]>;
+    /**
+     * Get relationships for a specific class
+     *
+     * @param className - Name of the class to get relationships for
+     * @returns Array of relationship metadata for the class
+     * @example
+     * ```typescript
+     * const orderRelationships = ObjectRegistry.getRelationships('Order');
+     * // [{ sourceClass: 'Order', fieldName: 'customerId', ... }]
+     * ```
+     */
+    static getRelationships(className: string): RelationshipMetadata[];
+    /**
+     * Get full inheritance chain for a class
+     *
+     * Returns array of registered ancestor class names from the oldest
+     * registered ancestor down to the input class. Framework base classes
+     * (`SmrtObject`, `SmrtClass`, `SmrtCollection`) are **NOT** included
+     * because they are never registered — the walk terminates one step
+     * before them.
+     *
+     * Chain entries are **qualified names** (`@package/name:ClassName`)
+     * whenever the corresponding registration has one — i.e. for every
+     * class loaded via a manifest or `@smrt()` decorator with a package
+     * context. Classes registered without a package (some tests) fall
+     * back to their simple name.
+     *
+     * Results are cached globally for performance (~100x faster than re-walking).
+     *
+     * @param className - Name of the registered class (simple or qualified)
+     * @returns Array of class names from oldest registered ancestor to
+     *   the input class, or empty array if not found
+     * @example
+     * ```typescript
+     * const chain = ObjectRegistry.getInheritanceChain(
+     *   '@happyvertical/smrt-content:BentleyContent',
+     * );
+     * // [
+     * //   '@happyvertical/smrt-content:Content',
+     * //   '@happyvertical/smrt-content:PraecoContent',
+     * //   '@happyvertical/smrt-content:BentleyContent',
+     * // ]
+     * ```
+     */
+    static getInheritanceChain(className: string): string[];
+    /**
+     * Get all fields including inherited ones from parent classes
+     *
+     * **Hybrid approach (v0.17+):**
+     * - External packages: Use build-time merged fields from manifests
+     * - Local classes: Use runtime merging by walking inheritance chain
+     *
+     * @param className - Name of the registered class
+     * @returns Map of all fields (including inherited)
+     */
+    static getAllFields(className: string): Promise<Map<string, any>>;
+    /**
+     * Merge field configurations from parent and child.
+     *
+     * Thin wrapper around the single shared implementation in
+     * registry/inheritance-resolver (#1378). The previous inline copy here had
+     * drifted from the module; both paths now run the same code. Kept as a
+     * private static so existing reach-in tests (issue #841 field-merge coverage)
+     * still resolve it.
+     *
+     * @param parentField - Field config from parent class
+     * @param childField - Field config from child class
+     * @param fieldName - Name of the field (for warning messages)
+     * @returns Merged field configuration
+     */
+    private static mergeFieldConfigs;
+    /**
+     * Get all methods including inherited ones from parent classes
+     *
+     * Walks the full inheritance chain and merges methods:
+     * - Parent methods are added first
+     * - Child methods override parent methods (no config merging for methods)
+     *
+     * Results are cached per-class for performance.
+     *
+     * **Note:** This is an async method that ensures manifests are loaded for external package classes.
+     *
+     * @param className - Name of the registered class
+     * @returns Promise resolving to Map of all methods (own + inherited)
+     * @example
+     * ```typescript
+     * // Given: Content → PraecoContent → BentleyContent
+     * const allMethods = await ObjectRegistry.getAllMethods('BentleyContent');
+     * // Includes: generateSummary() (from PraecoContent) + analyzeLocal() (from BentleyContent)
+     * ```
+     */
+    static getAllMethods(className: string): Promise<Map<string, any>>;
+    /**
+     * Get complete metadata for a single object (convenience method)
+     *
+     * Returns all available metadata for an object in a single call, including:
+     * - Class information
+     * - Field definitions
+     * - Configuration
+     * - Schema definition
+     * - Validators
+     * - Relationships
+     * - Tools (AI-callable methods)
+     *
+     * This is a convenience method that aggregates multiple registry queries
+     * into a single comprehensive metadata object.
+     *
+     * @param className - Name of the class to get metadata for
+     * @returns Complete metadata object or null if class not found
+     * @example
+     * ```typescript
+     * const productMeta = ObjectRegistry.getObjectMetadata('Product');
+     * if (productMeta) {
+     *   console.log('Name:', productMeta.name);
+     *   console.log('Table:', productMeta.schema.tableName);
+     *   console.log('Fields:', productMeta.fields.size);
+     *   console.log('API config:', productMeta.config.api);
+     *   console.log('Relationships:', productMeta.relationships.length);
+     * }
+     * ```
+     */
+    static getObjectMetadata(className: string): {
+        name: string;
+        constructor: typeof SmrtObject;
+        collectionConstructor?: new (options: any) => SmrtCollection<any>;
+        config: SmartObjectConfig;
+        fields: Map<string, any>;
+        methods: Map<string, any>;
+        schema: SchemaDefinition | undefined;
+        validators: ValidatorFunction[];
+        relationships: RelationshipMetadata[];
+        inverseRelationships: RelationshipMetadata[];
+        tools?: Array<{
+            type: 'function';
+            function: {
+                name: string;
+                description?: string;
+                parameters?: Record<string, any>;
+            };
+        }>;
+    } | null;
+    /**
+     * Get metadata for all registered objects (convenience method)
+     *
+     * Returns comprehensive metadata for every registered object, combining
+     * multiple registry queries into a single convenient data structure.
+     *
+     * This is particularly useful for:
+     * - Admin dashboards showing all objects
+     * - Documentation generation
+     * - Schema visualization
+     * - Debugging and introspection
+     *
+     * @returns Array of complete metadata objects for all registered classes
+     * @example
+     * ```typescript
+     * const allMetadata = ObjectRegistry.getAllObjectMetadata();
+     *
+     * // Generate admin dashboard
+     * for (const meta of allMetadata) {
+     *   console.log(`${meta.name}:`);
+     *   console.log(`  Table: ${meta.schema?.tableName}`);
+     *   console.log(`  Fields: ${meta.fields.size}`);
+     *   console.log(`  API: ${meta.config.api ? 'enabled' : 'disabled'}`);
+     *   console.log(`  Relationships: ${meta.relationships.length}`);
+     * }
+     *
+     * // Generate schema documentation
+     * const schemaDoc = allMetadata.map(meta => ({
+     *   name: meta.name,
+     *   table: meta.schema?.tableName,
+     *   fields: Array.from(meta.fields.entries()).map(([name, field]) => ({
+     *     name,
+     *     type: field.type,
+     *     required: field._meta?.required || false
+     *   })),
+     *   relationships: meta.relationships.map(rel => ({
+     *     field: rel.fieldName,
+     *     target: rel.targetClass,
+     *     type: rel.type
+     *   }))
+     * }));
+     * ```
+     */
+    static getAllObjectMetadata(): Array<{
+        name: string;
+        constructor: typeof SmrtObject;
+        collectionConstructor?: new (options: any) => SmrtCollection<any>;
+        config: SmartObjectConfig;
+        fields: Map<string, any>;
+        methods: Map<string, any>;
+        schema: SchemaDefinition | undefined;
+        validators: ValidatorFunction[];
+        relationships: RelationshipMetadata[];
+        inverseRelationships: RelationshipMetadata[];
+        tools?: Array<{
+            type: 'function';
+            function: {
+                name: string;
+                description?: string;
+                parameters?: Record<string, any>;
+            };
+        }>;
+    }>;
+    /**
+     * Get inverse relationships (relationships where this class is the target)
+     *
+     * @param className - Name of the class to find inverse relationships for
+     * @returns Array of relationship metadata where this class is the target
+     * @example
+     * ```typescript
+     * const customerInverseRels = ObjectRegistry.getInverseRelationships('Customer');
+     * // [{ sourceClass: 'Order', fieldName: 'customerId', targetClass: 'Customer', ... }]
+     * ```
+     */
+    static getInverseRelationships(className: string): RelationshipMetadata[];
+    /**
+     * Names by which an instance of `className` can be referenced by an inverse
+     * foreign key: its own (simple) class name plus every registered ancestor in
+     * its inheritance chain.
+     *
+     * Used by oneToMany resolution so an STI subclass can resolve a relationship
+     * declared on its base — the inverse `@foreignKey` is declared against the
+     * base class name, while the runtime instance may be a subclass.
+     *
+     * @param className - Simple or qualified class name
+     * @returns Set of names (simple and, where available, qualified) the
+     *   instance is assignable to
+     */
+    static getSelfReferableNames(className: string): Set<string>;
+    /**
+     * Inverse relationships targeting `className` OR any (STI) ancestor it
+     * inherits from.
+     *
+     * `getInverseRelationships` matches the target class name exactly. This
+     * variant also matches inverse foreign keys declared against an ancestor,
+     * so an STI subclass instance can resolve a `@oneToMany` declared on its
+     * base — whose inverse `@foreignKey` points at the base class name.
+     *
+     * @param className - Name of the class to find inverse relationships for
+     * @returns Relationship metadata whose target is the class or one of its
+     *   registered ancestors
+     */
+    static getInverseRelationshipsForSelf(className: string): RelationshipMetadata[];
+    /**
+     * Get table inheritance strategy for a class
+     *
+     * Returns the table strategy (CTI or STI) for a class, with automatic
+     * inheritance from parent classes. If not explicitly configured,
+     * walks up the inheritance chain to find the strategy.
+     *
+     * **Strategy Inheritance:**
+     * - Set once on base class, children inherit automatically
+     * - Children can explicitly override (not recommended)
+     * - Default is 'cti' if not found in hierarchy
+     *
+     * @param className - Name of the class to get strategy for
+     * @returns 'cti' (Class Table Inheritance) or 'sti' (Single Table Inheritance)
+     * @example
+     * ```typescript
+     * @smrt({ tableStrategy: 'sti' })
+     * class Event extends SmrtObject { }
+     *
+     * @smrt() // Inherits 'sti'
+     * class Meeting extends Event { }
+     *
+     * ObjectRegistry.getTableStrategy('Meeting'); // 'sti'
+     * ObjectRegistry.getTableStrategy('Event'); // 'sti'
+     * ```
+     */
+    static getTableStrategy(className: string): 'cti' | 'sti';
+    /**
+     * Get the conflict columns for UPSERT operations on a class
+     *
+     * Returns custom conflict columns if specified, otherwise defaults based on
+     * table strategy:
+     * - CTI: ['slug', 'context']
+     * - STI: ['slug', 'context', '_meta_type']
+     *
+     * STI subclasses share a table, so the discriminator participates in
+     * identity — two subtypes can coexist with the same (slug, context). The
+     * matching unique constraint on `(slug, context, _meta_type)` must exist
+     * in the live schema; if a deployment carries a stale 2-column unique
+     * instead, run `smrt db:migrate` to repair it (see issue #1165).
+     *
+     * @param className - Name of the class to get conflict columns for
+     * @returns Array of column names to use for conflict detection
+     *
+     * @example
+     * ```typescript
+     * // Junction table with custom conflict columns
+     * @smrt({ conflictColumns: ['event_id', 'profile_id'] })
+     * class EventParticipant extends SmrtObject {}
+     *
+     * ObjectRegistry.getConflictColumns('EventParticipant');
+     * // Returns: ['event_id', 'profile_id']
+     * ```
+     */
+    static getConflictColumns(className: string): string[];
+    /**
+     * Get the tenant scoping configuration for a class (Issue #688)
+     *
+     * Returns the normalized tenant scoping configuration if the class
+     * was registered with `tenantScoped: true` or a tenantScoped config object.
+     *
+     * @param className - Name of the class to check
+     * @returns Tenant scoping config or undefined if not tenant-scoped
+     *
+     * @example
+     * ```typescript
+     * @smrt({ tenantScoped: true })
+     * class Document extends SmrtObject { }
+     *
+     * const config = ObjectRegistry.getTenantScopedConfig('Document');
+     * // { mode: 'required', field: 'tenantId', autoFilter: true, autoPopulate: true, allowSuperAdminBypass: false }
+     * ```
+     */
+    static getTenantScopedConfig(className: string): RegisteredClass['tenantScopedConfig'] | undefined;
+    /**
+     * Check if a class is tenant-scoped (Issue #688)
+     *
+     * @param className - Name of the class to check
+     * @returns true if the class has tenantScoped configuration
+     */
+    static isTenantScoped(className: string): boolean;
+    /**
+     * Get the base class for an STI hierarchy
+     *
+     * Walks up the inheritance chain to find the first class configured
+     * with `tableStrategy: 'sti'`. This is the class that owns the shared table.
+     *
+     * **Returns:**
+     * - The base class's **qualified name** (`@package/name:ClassName`) when
+     *   the registration has one — same convention as
+     *   `getInheritanceChain`. Falls back to the simple name only for
+     *   registrations without a package context (some test classes).
+     * - `null` if the class uses CTI strategy.
+     *
+     * Accepts either a simple or a qualified name on input.
+     *
+     * @param className - Name of the class to find STI base for
+     * @returns Qualified base class name or null if CTI
+     * @example
+     * ```typescript
+     * @smrt({ tableStrategy: 'sti' })
+     * class Event extends SmrtObject { }
+     *
+     * @smrt()
+     * class Meeting extends Event { }
+     *
+     * ObjectRegistry.getSTIBase('@happyvertical/smrt-events:Meeting');
+     * // '@happyvertical/smrt-events:Event'
+     * ObjectRegistry.getSTIBase('@happyvertical/smrt-events:Event');
+     * // '@happyvertical/smrt-events:Event'
+     * ```
+     */
+    static getSTIBase(className: string): string | null;
+    /**
+     * Get all descendant classes of a base class
+     *
+     * Returns all registered classes that inherit from the specified base class.
+     * Uses the `extends` field from manifest to build the descendant tree.
+     *
+     * **Use cases:**
+     * - Schema generation: Aggregate fields from all children for STI table
+     * - Polymorphic queries: Find all types to instantiate
+     * - Documentation: Show class hierarchy
+     *
+     * Accepts either a simple or a qualified name on input. The returned
+     * descendant names are **qualified** (`@package/name:ClassName`) when
+     * the registration has one — same convention as `getInheritanceChain`
+     * and `getSTIBase`.
+     *
+     * @param className - Name of the base class (simple or qualified)
+     * @returns Array of qualified descendant class names (direct and indirect)
+     * @example
+     * ```typescript
+     * @smrt({ tableStrategy: 'sti' })
+     * class Event extends SmrtObject { }
+     *
+     * @smrt()
+     * class Meeting extends Event { }
+     *
+     * @smrt()
+     * class HockeyGame extends Event { }
+     *
+     * ObjectRegistry.getDescendants('@happyvertical/smrt-events:Event');
+     * // [
+     * //   '@happyvertical/smrt-events:Meeting',
+     * //   '@happyvertical/smrt-events:HockeyGame',
+     * // ]
+     * ```
+     */
+    static getDescendants(className: string): string[];
+    /**
+     * Persist registry state to system tables
+     *
+     * Saves all registered class metadata to the _smrt_registry system table
+     * for runtime introspection and debugging. This enables applications to
+     * query what SMRT objects exist and their configurations.
+     *
+     * @param db - Database interface to persist to
+     * @returns Promise that resolves when persistence is complete
+     * @example
+     * ```typescript
+     * // After registering all classes
+     * await ObjectRegistry.persistToDatabase(db);
+     *
+     * // Later, query the system table
+     * const rows = await db.all('SELECT * FROM _smrt_registry');
+     * console.log('Registered classes:', rows.map(r => r.class_name));
+     * ```
+     */
+    static persistToDatabase(db: import('@happyvertical/sql').DatabaseInterface): Promise<void>;
+    /**
+     * Load registry metadata from system tables
+     *
+     * Reads the _smrt_registry system table to inspect what classes
+     * have been registered. This is primarily for introspection and
+     * debugging - actual class registration happens via @smrt() decorator.
+     *
+     * @param db - Database interface to load from
+     * @returns Promise resolving to array of class metadata
+     * @example
+     * ```typescript
+     * const metadata = await ObjectRegistry.loadFromDatabase(db);
+     * for (const meta of metadata) {
+     *   console.log(`Class: ${meta.class_name}`);
+     *   console.log(`Table: ${JSON.parse(meta.manifest).tableName}`);
+     * }
+     * ```
+     */
+    static loadFromDatabase(db: import('@happyvertical/sql').DatabaseInterface): Promise<any[]>;
+    /**
+     * Get embedding configuration for a class
+     *
+     * Returns the class-specific embedding config if embeddings are enabled.
+     * This includes the fields to embed, provider override, and generation options.
+     *
+     * @param className - Name of the class to get embedding config for
+     * @returns Class embedding config or undefined if not configured
+     * @example
+     * ```typescript
+     * @smrt({
+     *   embeddings: {
+     *     fields: ['title', 'body'],
+     *     autoGenerate: true
+     *   }
+     * })
+     * class Article extends SmrtObject { }
+     *
+     * const config = ObjectRegistry.getEmbeddingConfig('Article');
+     * // { fields: ['title', 'body'], autoGenerate: true }
+     * ```
+     */
+    static getEmbeddingConfig(className: string): ClassEmbeddingConfig | undefined;
+    /**
+     * Check if a class has embeddings enabled
+     *
+     * @param className - Name of the class to check
+     * @returns True if the class has embedding configuration
+     * @example
+     * ```typescript
+     * if (ObjectRegistry.hasEmbeddings('Article')) {
+     *   await article.generateEmbeddings();
+     * }
+     * ```
+     */
+    static hasEmbeddings(className: string): boolean;
+    /**
+     * Get all registered classes that have embeddings enabled
+     *
+     * @returns Array of class names with embedding configuration
+     * @example
+     * ```typescript
+     * const embeddableClasses = ObjectRegistry.getEmbeddingClasses();
+     * // ['Article', 'Profile', 'Event']
+     * ```
+     */
+    static getEmbeddingClasses(): string[];
+    /**
+     * Get project-level embedding configuration
+     *
+     * Returns the global embedding settings from smrt.config (or defaults).
+     * These settings apply to all classes unless overridden at the class level.
+     *
+     * @returns Project embedding configuration with defaults applied
+     * @example
+     * ```typescript
+     * const projectConfig = ObjectRegistry.getProjectEmbeddingConfig();
+     * // {
+     * //   dimensions: 768,
+     * //   provider: 'local',
+     * //   localModel: 'Xenova/bge-base-en-v1.5',
+     * //   aiModel: 'text-embedding-3-small',
+     * //   fallbackToAI: false
+     * // }
+     * ```
+     */
+    static getProjectEmbeddingConfig(): ProjectEmbeddingConfig;
+    /**
+     * Resolve complete embedding configuration for a class
+     *
+     * Merges project-level config with class-level overrides.
+     * Returns undefined if the class doesn't have embeddings enabled.
+     *
+     * @param className - Name of the class to resolve config for
+     * @returns Fully resolved embedding config or undefined
+     * @example
+     * ```typescript
+     * const config = ObjectRegistry.resolveEmbeddingConfig('Article');
+     * // Merges project defaults with class-specific settings
+     * // {
+     * //   fields: ['title', 'body'],
+     * //   dimensions: 768,
+     * //   provider: 'local',
+     * //   localModel: 'Xenova/bge-base-en-v1.5',
+     * //   autoGenerate: true,
+     * //   regenerateOnChange: true,
+     * //   ...
+     * // }
+     * ```
+     */
+    static resolveEmbeddingConfig(className: string): ResolvedEmbeddingConfig | undefined;
+    /**
+     * Resolve the effective collection read-cache config for a class (issue #1498)
+     *
+     * Walks the inheritance chain nearest-first so an STI base class opt-in
+     * covers its children, while a child can opt back out with `cache: false`.
+     *
+     * @param className - Simple or qualified class name
+     * @returns Effective cache config, or undefined when caching is not opted in
+     */
+    static resolveCollectionCacheConfig(className: string): CollectionCacheConfig | undefined;
+}
+/**
+ * Registers a `SmrtObject` or `SmrtCollection` subclass with the global `ObjectRegistry`.
+ *
+ * This decorator is the primary entry point for the SMRT framework. Applying it to a class:
+ *
+ * 1. Captures the original class name before minification and stores it as the
+ *    `SMRT_TABLE_NAME` static property — ensuring table names are stable in production builds.
+ * 2. Registers class metadata (fields, schema, config) in the singleton `ObjectRegistry`.
+ * 3. Enables automatic code generation: REST API endpoints (`api`), CLI commands (`cli`),
+ *    and MCP server tools (`mcp`) are generated at build time from the registered config.
+ * 4. Activates lifecycle hooks (`hooks.beforeSave`, `hooks.afterDelete`, etc.).
+ * 5. Configures AI-callable methods exposed to `is()` / `do()` via function calling (`ai`).
+ * 6. Enables automatic vector embedding generation (`embeddings`).
+ *
+ * Apply to `SmrtCollection` subclasses as well — the decorator uses `_itemClass` to
+ * register the collection under the correct table name and creates a collection-to-table
+ * lookup used by the CLI and introspection tools.
+ *
+ * For Single Table Inheritance (STI), set `tableStrategy: 'sti'` on the base class only.
+ * Child classes inherit the strategy automatically.
+ *
+ * @param config - Optional configuration for the class. All fields are optional; defaults
+ *   are derived from the class name and framework conventions.
+ * @returns A class decorator that registers the class and returns the original constructor
+ *
+ * @example
+ * ```typescript
+ * // Basic usage — convention-based defaults
+ * @smrt()
+ * class Product extends SmrtObject {
+ *   @field({ required: true })
+ *   name: string = '';
+ *   price: number = 0.0; // 0.0 → DECIMAL column
+ * }
+ *
+ * // Paired collection (required for collection.create())
+ * @smrt()
+ * class Products extends SmrtCollection<Product> {
+ *   static readonly _itemClass = Product;
+ * }
+ *
+ * // STI base class
+ * @smrt({ tableStrategy: 'sti' })
+ * class Content extends SmrtObject {
+ *   title: string = '';
+ * }
+ *
+ * // STI child — inherits strategy, adds @meta() fields stored in _meta_data JSON
+ * @smrt()
+ * class Article extends Content {
+ *   @meta() wordCount: number = 0;
+ * }
+ *
+ * // Restrict generated API surface
+ * @smrt({ api: { exclude: ['delete'] }, mcp: true, cli: false })
+ * class Invoice extends SmrtObject {}
+ *
+ * // Junction/upsert table with natural key
+ * @smrt({ conflictColumns: ['event_id', 'profile_id'] })
+ * class EventParticipant extends SmrtObject {
+ *   eventId: string = '';
+ *   profileId: string = '';
+ * }
+ * ```
+ *
+ * @see {@link SmartObjectConfig} for all available configuration options
+ * @see {@link field} / {@link meta} / {@link foreignKey} for field decorators
+ */
+export declare function smrt(config?: SmartObjectConfig): <T extends abstract new (...args: any[]) => any>(ctor: T, decoratorContext?: ClassDecoratorContext<T>) => T;
+//# sourceMappingURL=registry.d.ts.map