@happyvertical/smrt-core 0.30.0

package/dist/registry.js

@@ -0,0 +1,2301 @@
+import { createLogger } from "@happyvertical/logger";
+import { applyOneToManyChildAccessors } from "./child-accessors.js";
+import { SmrtCollection } from "./collection.js";
+import { applyPendingDecoratorRegistrations } from "./decorators/compatibility.js";
+import { ConfigurationError } from "./errors.js";
+import { getDefaultCompositeSource } from "./manifest/sources/composite.js";
+import { ExplicitPathsManifestSource } from "./manifest/sources/explicit-paths.js";
+import { getNodeBuiltins, loadExternalManifestSyncWithNode, cloneManifestSchemaColumns, discoverCachedManifestSync } from "./manifest/store.js";
+import { resolveCollectionCacheConfig } from "./registry/cache-config.js";
+import { register, registerCollection, registerFromManifest, invalidateInheritanceEntries } from "./registry/class-registration.js";
+import { recordRegistryDiagnostic, getRegistryDiagnostics, clearRegistryDiagnostics, flushRegistryDiagnostics } from "./registry/diagnostics.js";
+import { getEmbeddingConfig, hasEmbeddings, getEmbeddingClasses, getProjectEmbeddingConfig, resolveEmbeddingConfig } from "./registry/embedding-manager.js";
+import { getInheritanceChain, getAllFields, mergeFieldConfigs, getAllMethods } from "./registry/inheritance-resolver.js";
+import { manifestFieldDiffers, createFieldFromManifest, mergeManifestField } from "./registry/manifest-field-merge.js";
+import { getCanonicalClassName, hasClassCaseInsensitive, findClass, getClass, getClassByConstructor, getClassByQualifiedName, getClassInPackage, findClassesByName, resolveType, getClassesByPackage, getClassesByVisibility, getPublicClasses, getAllClasses, getClassNames, getQualifiedClassNames, hasClass } from "./registry/name-resolver.js";
+import { getDependencyGraph, getRelationshipMap } from "./registry/relationship-graph.js";
+import { getSchema, getSchemaDDL, getTableName, getAllSchemas, getAllSchemasAsDefinitions } from "./registry/schema-builder.js";
+import { getClasses, getCollections, getCollectionTableNames, getCollectionCache, getDbInstanceIds, getNextDbId, setNextDbId, getFieldDecorators, getStiSiblingsLoaded, getInheritanceCache, getDiscoveryAttemptCache, verboseLog } from "./registry/shared-state.js";
+import { compileValidators } from "./registry/validator.js";
+import "./utils.js";
+import { LRUCache } from "./utils/lru-cache.js";
+import { isQualifiedName, parseQualifiedName, createQualifiedName } from "./utils/qualified-names.js";
+import { SMRT_COLLECTION_BASE_NAMES, isSmrtCollectionExtendsName } from "./registry/collection-resolution.js";
+import { classnameToTablename, toSnakeCase } from "./utils/naming.js";
+const logger = createLogger({ level: "info" });
+function getManifestLoaderSpecifier() {
+  return import.meta.url.endsWith(".ts") ? "./manifest/index.ts" : "./manifest/index.js";
+}
+async function importManifestLoader() {
+  return await import(getManifestLoaderSpecifier());
+}
+function getReferenceKindFromFieldOptions(fieldOptions) {
+  if (fieldOptions?.__tenancy?.isTenantIdField || fieldOptions?._meta?.__tenancy?.isTenantIdField) {
+    return "tenantId";
+  }
+  if (fieldOptions?.type === "foreignKey") {
+    return "foreignKey";
+  }
+  if (fieldOptions?.type === "crossPackageRef") {
+    return "crossPackageRef";
+  }
+  return void 0;
+}
+function applyManifestFieldColumnMetadata(columns, fieldEntries) {
+  if (!fieldEntries) {
+    return;
+  }
+  for (const [fieldName, fieldOptions] of fieldEntries) {
+    const sqlType = fieldOptions?.sqlType ?? fieldOptions?._meta?.sqlType;
+    const referenceKind = getReferenceKindFromFieldOptions(fieldOptions);
+    if (!sqlType && !referenceKind) {
+      continue;
+    }
+    const columnName = toSnakeCase(fieldName);
+    const existingColumn = columns[columnName];
+    if (!existingColumn) {
+      continue;
+    }
+    columns[columnName] = {
+      ...existingColumn,
+      ...sqlType ? { type: String(sqlType).toUpperCase() } : {},
+      ...referenceKind ? { referenceKind } : {}
+    };
+  }
+}
+async function discoverInstalledSmrtPackages() {
+  const discoverSpecifier = import.meta.url.endsWith(".ts") ? "./manifest/discover-smrt-packages.ts" : "./manifest/discover-smrt-packages.js";
+  const { discoverSmrtPackages } = await import(discoverSpecifier);
+  return discoverSmrtPackages();
+}
+function resolveManifestByUpwardSearch(builtins, missingPath) {
+  const { fs, path } = builtins;
+  const fileName = path.basename(missingPath);
+  const MAX_LEVELS = 4;
+  let dir = path.dirname(missingPath);
+  for (let level = 0; level < MAX_LEVELS; level++) {
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    const candidate = path.join(parent, fileName);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    if (fs.existsSync(path.join(parent, "package.json"))) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+class ObjectRegistry {
+  /**
+   * Get the classes map from globalThis, initializing if needed
+   */
+  static get classes() {
+    return getClasses();
+  }
+  /**
+   * Get the collections map from globalThis, initializing if needed
+   */
+  static get collections() {
+    return getCollections();
+  }
+  /**
+   * Get the collection table names map from globalThis, initializing if needed
+   * Maps collection class name -> tableName for getTableName lookups
+   */
+  static get collectionTableNames() {
+    return getCollectionTableNames();
+  }
+  /**
+   * Set the table name for a collection class
+   * Used by @smrt() decorator to enable getTableName lookups for collections
+   */
+  static setCollectionTableName(collectionName, tableName) {
+    ObjectRegistry.collectionTableNames.set(collectionName, tableName);
+  }
+  /**
+   * Get the collection cache from globalThis, initializing if needed
+   */
+  static get collectionCache() {
+    return getCollectionCache();
+  }
+  /**
+   * 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) {
+    if (!Number.isFinite(maxSize) || maxSize <= 0) {
+      throw new Error(`maxSize must be a positive number, got: ${maxSize}`);
+    }
+    globalThis.__smrtRegistryCollectionCache = new LRUCache(maxSize);
+  }
+  /**
+   * WeakMap to assign unique IDs to database instances for cache keys
+   * Prevents cache key collisions when different db instances are used
+   */
+  static get dbInstanceIds() {
+    return getDbInstanceIds();
+  }
+  /**
+   * Get/set the next database ID counter
+   */
+  static get nextDbId() {
+    return getNextDbId();
+  }
+  static set nextDbId(value) {
+    setNextDbId(value);
+  }
+  /**
+   * Storage for field decorator metadata (decorator pattern)
+   * Maps className → Map<propertyKey, FieldOptions>
+   * Used by @field(), @foreignKey(), @oneToMany(), @manyToMany() decorators
+   */
+  static get fieldDecorators() {
+    return getFieldDecorators();
+  }
+  /**
+   * Track collections that have been processed for STI siblings
+   * Prevents infinite recursion when loading siblings
+   */
+  static get stiSiblingsLoaded() {
+    return getStiSiblingsLoaded();
+  }
+  /**
+   * 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) {
+    return getCanonicalClassName(name);
+  }
+  /**
+   * Check if a class exists by name (case-insensitive)
+   */
+  static hasClassCaseInsensitive(name) {
+    return hasClassCaseInsensitive(name);
+  }
+  /**
+   * 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)
+   */
+  static getInheritanceCache() {
+    return 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
+   */
+  static getDiscoveryAttemptCache() {
+    return 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, propertyKey, options) {
+    if (!ObjectRegistry.fieldDecorators.has(className)) {
+      ObjectRegistry.fieldDecorators.set(className, /* @__PURE__ */ new Map());
+    }
+    const classDecorators = ObjectRegistry.fieldDecorators.get(className);
+    if (!classDecorators) {
+      return;
+    }
+    const existing = classDecorators.get(propertyKey);
+    if (existing) {
+      classDecorators.set(propertyKey, { ...existing, ...options });
+    } else {
+      classDecorators.set(propertyKey, options);
+    }
+  }
+  /**
+   * 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, propertyKey) {
+    return ObjectRegistry.fieldDecorators.get(className)?.get(propertyKey);
+  }
+  /**
+   * 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) {
+    return ObjectRegistry.fieldDecorators.get(className) || /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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) {
+    const decorators = ObjectRegistry.fieldDecorators.get(className);
+    return decorators !== void 0 && decorators.size > 0;
+  }
+  /**
+   * 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, config = {}) {
+    register(ctor, config);
+  }
+  /**
+   * 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, collectionConstructor) {
+    registerCollection(objectName, collectionConstructor);
+  }
+  static registerFromManifest(name, objectDef, packageName) {
+    registerFromManifest(name, objectDef, packageName);
+  }
+  /**
+   * 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
+   */
+  static findClass(name) {
+    return findClass(name);
+  }
+  // The private `findClassStrict` wrapper that used to live here was removed
+  // with the inline inheritance-chain copy (#1378); strict, package-aware
+  // resolution now lives solely in registry/inheritance-resolver, which calls
+  // the name-resolver helper directly.
+  /**
+   * 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) {
+    return getClass(name);
+  }
+  /**
+   * 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) {
+    return getClassByConstructor(ctor);
+  }
+  /**
+   * 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) {
+    return getClassByQualifiedName(qualifiedName);
+  }
+  /**
+   * 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, className) {
+    return getClassInPackage(packageName, className);
+  }
+  /**
+   * 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) {
+    return findClassesByName(className);
+  }
+  /**
+   * 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) {
+    return resolveType(shortName);
+  }
+  /**
+   * 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) {
+    return getClassesByPackage(packageName);
+  }
+  /**
+   * 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) {
+    return getClassesByVisibility(visibility);
+  }
+  /**
+   * 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() {
+    return getPublicClasses();
+  }
+  /**
+   * 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() {
+    return getAllClasses();
+  }
+  /**
+   * 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() {
+    return getClassNames();
+  }
+  /**
+   * Get one lookup name per registered class, preserving cross-package
+   * collisions by preferring qualified class names where available.
+   */
+  static getQualifiedClassNames() {
+    return getQualifiedClassNames();
+  }
+  /**
+   * 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 async tryLoadFromExternalPackage(className) {
+    const requestedQualifiedName = isQualifiedName(className) ? parseQualifiedName(className) : null;
+    const requestedClassName = requestedQualifiedName?.className || className;
+    const requestedPackageName = requestedQualifiedName?.packageName;
+    const smrtPackages = requestedPackageName ? [requestedPackageName] : await discoverInstalledSmrtPackages();
+    const { loadExternalManifest } = await importManifestLoader();
+    verboseLog(
+      `[ObjectRegistry] Attempting to auto-load ${className} from ${smrtPackages.length} external packages...`
+    );
+    const matches = [];
+    for (const packageName2 of smrtPackages) {
+      const manifest2 = await loadExternalManifest(packageName2);
+      if (!manifest2 || !manifest2.objects) {
+        continue;
+      }
+      const lowerClassName = requestedClassName.toLowerCase();
+      let objectDef2 = manifest2.objects[lowerClassName] || manifest2.objects[requestedClassName] || (requestedPackageName ? manifest2.objects[`${requestedPackageName}:${requestedClassName}`] : void 0);
+      if (!objectDef2) {
+        for (const [_key, def] of Object.entries(
+          manifest2.objects
+        )) {
+          if (def.className?.toLowerCase() === lowerClassName || def.className === requestedClassName) {
+            objectDef2 = def;
+            break;
+          }
+        }
+      }
+      if (!objectDef2) {
+        continue;
+      }
+      matches.push({
+        manifest: manifest2,
+        packageName: manifest2.packageName || packageName2,
+        objectDef: objectDef2
+      });
+    }
+    if (matches.length === 0) {
+      verboseLog(
+        `[ObjectRegistry] ❌ Could not find ${className} in any SMRT package`
+      );
+      return false;
+    }
+    if (!requestedPackageName && matches.length > 1) {
+      throw new ConfigurationError(
+        `Ambiguous class name "${className}" — found in multiple external SMRT packages: ${matches.map((match) => match.packageName).join(", ")}. Preserve package identity or use a qualified class name to disambiguate.`,
+        "CONFIG_AMBIGUOUS_CLASS",
+        {
+          className,
+          candidates: matches.map((match) => match.packageName)
+        }
+      );
+    }
+    const { manifest, packageName, objectDef } = matches[0];
+    verboseLog(
+      `[ObjectRegistry] ✅ Found ${className} in ${packageName} manifest`
+    );
+    ObjectRegistry.registerFromManifest(
+      objectDef.className || requestedClassName,
+      objectDef,
+      manifest.packageName
+    );
+    const childClassName = objectDef.className || requestedClassName;
+    if (objectDef.extends && objectDef.extends !== childClassName) {
+      const parentName = objectDef.extends;
+      const lowerParentName = parentName.toLowerCase();
+      let parentDef = manifest.objects[lowerParentName] || manifest.objects[parentName];
+      if (!parentDef) {
+        for (const [_key, def] of Object.entries(
+          manifest.objects
+        )) {
+          if (def.className?.toLowerCase() === lowerParentName || def.className === parentName) {
+            parentDef = def;
+            break;
+          }
+        }
+      }
+      if (parentDef && !ObjectRegistry.hasClass(objectDef.extends)) {
+        verboseLog(
+          `[ObjectRegistry] Also registering parent class ${objectDef.extends} for STI`
+        );
+        ObjectRegistry.registerFromManifest(
+          parentDef.className || objectDef.extends,
+          parentDef,
+          manifest.packageName
+        );
+      }
+      verboseLog(
+        `[ObjectRegistry] Merging inherited fields for ${className}...`
+      );
+      await ObjectRegistry.getAllFields(requestedClassName);
+      const registered = ObjectRegistry.findClass(requestedClassName);
+      if (registered?.inheritedFields) {
+        verboseLog(
+          `[ObjectRegistry] ✅ ${className} now has ${registered.inheritedFields.size} total fields (including inherited)`
+        );
+      }
+    }
+    return true;
+  }
+  /**
+   * 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) {
+    let packagesLoaded = 0;
+    let objectsRegistered = 0;
+    if (options?.manifestPaths) {
+      const source = new ExplicitPathsManifestSource(options.manifestPaths);
+      for (const entry of source.entries()) {
+        if (!ObjectRegistry.hasClassCaseInsensitive(entry.className)) {
+          ObjectRegistry.registerFromManifest(
+            entry.className,
+            entry.def,
+            entry.packageName
+          );
+          objectsRegistered++;
+        }
+      }
+      packagesLoaded = source.loadedCount;
+    } else {
+      const packagePrefixes = ["@happyvertical/smrt-"];
+      try {
+        const builtins = getNodeBuiltins();
+        if (!builtins) {
+          return { packagesLoaded, objectsRegistered };
+        }
+        const scopeDir = builtins.path.join(
+          process.cwd(),
+          "node_modules",
+          "@happyvertical"
+        );
+        if (!builtins.fs.existsSync(scopeDir)) {
+          return { packagesLoaded, objectsRegistered };
+        }
+        const packages = builtins.fs.readdirSync(scopeDir).filter(
+          (name) => packagePrefixes.some(
+            (prefix) => `@happyvertical/${name}`.startsWith(prefix)
+          )
+        );
+        const seenPackages = /* @__PURE__ */ new Set();
+        for (const pkgDir of packages) {
+          const packageName = `@happyvertical/${pkgDir}`;
+          const manifest = loadExternalManifestSyncWithNode(packageName);
+          if (!manifest?.objects) continue;
+          seenPackages.add(packageName);
+        }
+        const composite = getDefaultCompositeSource();
+        for (const entry of composite.entries()) {
+          if (!entry.packageName || !seenPackages.has(entry.packageName)) {
+            continue;
+          }
+          if (!ObjectRegistry.hasClassCaseInsensitive(entry.className)) {
+            ObjectRegistry.registerFromManifest(
+              entry.className,
+              entry.def,
+              entry.packageName
+            );
+            objectsRegistered++;
+          }
+        }
+        packagesLoaded = seenPackages.size;
+      } catch (err) {
+        verboseLog(
+          `[ObjectRegistry] Auto-discovery of manifests failed: ${err}`
+        );
+      }
+    }
+    verboseLog(
+      `[ObjectRegistry] loadAllManifests complete: ${packagesLoaded} packages, ${objectsRegistered} objects registered`
+    );
+    return { packagesLoaded, objectsRegistered };
+  }
+  /**
+   * 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) {
+    const builtins = getNodeBuiltins();
+    if (!builtins) {
+      return { loaded: false, objectsRegistered: 0 };
+    }
+    let manifest = null;
+    try {
+      const urlString = manifestUrl instanceof URL ? manifestUrl.href : manifestUrl;
+      let filePath;
+      if (manifestUrl instanceof URL) {
+        filePath = builtins.url.fileURLToPath(manifestUrl);
+      } else if (urlString.startsWith("file:")) {
+        filePath = builtins.url.fileURLToPath(urlString);
+      } else {
+        filePath = urlString;
+      }
+      if (!builtins.fs.existsSync(filePath)) {
+        const recovered = resolveManifestByUpwardSearch(builtins, filePath);
+        if (!recovered) {
+          recordRegistryDiagnostic(
+            "warn",
+            "PACKAGE_MANIFEST_NOT_FOUND",
+            `Package manifest not found at ${filePath}. Self-registration is a no-op; the vitest plugin may still populate this manifest via its own path.`,
+            { manifestUrl: String(manifestUrl), filePath }
+          );
+          return { loaded: false, objectsRegistered: 0 };
+        }
+        filePath = recovered;
+      }
+      const parsed = JSON.parse(
+        builtins.fs.readFileSync(filePath, "utf-8")
+      );
+      if (!parsed?.objects || typeof parsed.objects !== "object") {
+        recordRegistryDiagnostic(
+          "warn",
+          "PACKAGE_MANIFEST_INVALID_SHAPE",
+          `Package manifest at ${String(manifestUrl)} is missing an "objects" record`,
+          { manifestUrl: String(manifestUrl) }
+        );
+        return { loaded: false, objectsRegistered: 0 };
+      }
+      manifest = parsed;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      recordRegistryDiagnostic(
+        "error",
+        "PACKAGE_MANIFEST_READ_FAILED",
+        `registerPackageManifest: failed to read manifest at ${String(manifestUrl)}: ${errorMessage}`,
+        { manifestUrl: String(manifestUrl), errorMessage }
+      );
+      verboseLog(
+        `[ObjectRegistry] registerPackageManifest: failed to read manifest at ${String(manifestUrl)}: ${errorMessage}`
+      );
+      return { loaded: false, objectsRegistered: 0 };
+    }
+    const packageName = manifest.packageName;
+    const manifestGlobals = globalThis;
+    if (!manifestGlobals.__smrtManifestCache) {
+      manifestGlobals.__smrtManifestCache = /* @__PURE__ */ new Map();
+    }
+    const cacheKey = packageName || String(manifestUrl);
+    manifestGlobals.__smrtManifestCache.set(cacheKey, manifest);
+    let objectsRegistered = 0;
+    for (const [key, def] of Object.entries(manifest.objects)) {
+      const objectDef = def;
+      const className = objectDef.className || key;
+      ObjectRegistry.registerFromManifest(className, objectDef, packageName);
+      objectsRegistered++;
+    }
+    verboseLog(
+      `[ObjectRegistry] registerPackageManifest: loaded ${objectsRegistered} objects from ${packageName || String(manifestUrl)}`
+    );
+    return { loaded: true, packageName, objectsRegistered };
+  }
+  /**
+   * 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() {
+    return getRegistryDiagnostics();
+  }
+  /** Clear the diagnostic buffer. Primarily for tests. */
+  static clearDiagnostics() {
+    clearRegistryDiagnostics();
+  }
+  /**
+   * Pretty-print the diagnostic buffer via `console.warn` / `console.error`.
+   * No-op when the buffer is empty.
+   */
+  static flushDiagnostics() {
+    flushRegistryDiagnostics();
+  }
+  /**
+   * Check if a class is registered (case-insensitive)
+   */
+  static hasClass(name) {
+    return hasClass(name);
+  }
+  /**
+   * Clear all registered classes (mainly for testing)
+   */
+  static clear() {
+    ObjectRegistry.classes.clear();
+    ObjectRegistry.collections.clear();
+    ObjectRegistry.collectionCache.clear();
+    ObjectRegistry.collectionTableNames.clear();
+    ObjectRegistry.getInheritanceCache().clear();
+    ObjectRegistry.getDiscoveryAttemptCache().clear();
+    ObjectRegistry.fieldDecorators.clear();
+    ObjectRegistry.stiSiblingsLoaded.clear();
+    ObjectRegistry.nextDbId = 1;
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(className);
+    if (!registered) {
+      ObjectRegistry.getInheritanceCache().delete(className);
+      return;
+    }
+    invalidateInheritanceEntries(registered);
+  }
+  /**
+   * 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() {
+    ObjectRegistry.getInheritanceCache().clear();
+    ObjectRegistry.getDiscoveryAttemptCache().clear();
+    for (const registered of ObjectRegistry.classes.values()) {
+      registered.inheritedFields = void 0;
+      registered.inheritedMethods = void 0;
+    }
+  }
+  /**
+   * 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.
+   */
+  static resolveCollectionRegistration(className) {
+    let registered = ObjectRegistry.findClass(className);
+    let collectionConstructor = registered?.collectionConstructor;
+    if (!collectionConstructor) {
+      collectionConstructor = ObjectRegistry.collections.get(className);
+    }
+    if (!registered && collectionConstructor) {
+      const itemClass = collectionConstructor._itemClass;
+      if (itemClass) {
+        registered = ObjectRegistry.getClassByConstructor(itemClass) || ObjectRegistry.findClass(itemClass.name);
+      }
+    }
+    const canonicalName = registered?.qualifiedName || registered?.name || className;
+    return {
+      canonicalName,
+      registered,
+      collectionConstructor
+    };
+  }
+  /**
+   * 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 async getCollection(className, options = {}) {
+    let { canonicalName, registered, collectionConstructor } = ObjectRegistry.resolveCollectionRegistration(className);
+    if (!registered && !collectionConstructor) {
+      const loaded = await ObjectRegistry.tryLoadFromExternalPackage(className);
+      if (loaded) {
+        ({ canonicalName, registered, collectionConstructor } = ObjectRegistry.resolveCollectionRegistration(className));
+      }
+      if (!registered && !collectionConstructor) {
+        throw new Error(
+          `Class ${className} not found in ObjectRegistry. Make sure to register it with @smrt() decorator or ObjectRegistry.register()`
+        );
+      }
+    }
+    let dbId;
+    if (options.db && typeof options.db === "object") {
+      if (!ObjectRegistry.dbInstanceIds.has(options.db)) {
+        ObjectRegistry.dbInstanceIds.set(options.db, ObjectRegistry.nextDbId++);
+      }
+      dbId = ObjectRegistry.dbInstanceIds.get(options.db);
+    }
+    const cacheKey = `${canonicalName}:${JSON.stringify({
+      persistence: options.persistence,
+      db: dbId !== void 0 ? `db:${dbId}` : void 0,
+      ai: options.ai ? "present" : void 0
+    })}`;
+    if (ObjectRegistry.collectionCache.has(cacheKey)) {
+      return ObjectRegistry.collectionCache.get(cacheKey);
+    }
+    if (!collectionConstructor) {
+      if (!registered) {
+        throw new Error(
+          `Collection ${className} is registered without a backing object class, which is not supported.`
+        );
+      }
+      const { SmrtCollection: SmrtCollectionClass } = await import("./collection.js");
+      class DefaultCollection extends SmrtCollectionClass {
+        static _itemClass = registered?.constructor;
+      }
+      collectionConstructor = DefaultCollection;
+      registered.collectionConstructor = DefaultCollection;
+      ObjectRegistry.collections.set(canonicalName, DefaultCollection);
+    }
+    const collection = await collectionConstructor.create(
+      options
+    );
+    ObjectRegistry.collectionCache.set(cacheKey, collection);
+    return collection;
+  }
+  /**
+   * Get field definitions for a registered class.
+   * Supports both qualified names and simple class names.
+   */
+  static getFields(name) {
+    const registered = ObjectRegistry.findClass(name);
+    return registered ? registered.fields : /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(name);
+    if (registered) {
+      return registered.methods;
+    }
+    return /* @__PURE__ */ new Map();
+  }
+  static compileValidators(className, fields) {
+    return compileValidators(className, fields);
+  }
+  /**
+   * 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 async ensureManifestLoaded(className) {
+    let registered = ObjectRegistry.findClass(className);
+    if (!registered) {
+      const loaded = await ObjectRegistry.tryLoadFromExternalPackage(className);
+      if (loaded) {
+        registered = ObjectRegistry.findClass(className);
+      }
+    }
+    if (!registered) {
+      const isTestEnv = process.env.NODE_ENV === "test" || process.env.VITEST === "true" || typeof globalThis.describe !== "undefined" || typeof globalThis.it !== "undefined";
+      const testHint = isTestEnv ? `
+
+⚠️  Are you using 'smrt test'? Tests require manifest generation.
+   ✅ Use: smrt test
+   ❌ NOT:  npx vitest
+` : "";
+      throw new Error(
+        `Class '${className}' is not registered. Ensure the class is decorated with @smrt() before using it.` + testHint
+      );
+    }
+    const existingFieldCount = registered.fields.size;
+    const { discoverManifestEntry } = await importManifestLoader();
+    const manifestEntry = await discoverManifestEntry(
+      registered.constructor,
+      className
+    );
+    if (!manifestEntry) {
+      if (!registered.packageName || !registered.qualifiedName) {
+        const loaded = await ObjectRegistry.tryLoadFromExternalPackage(className);
+        if (loaded) {
+          ObjectRegistry.invalidateInheritanceCache(className);
+        }
+      }
+      return;
+    }
+    if (manifestEntry?.fields) {
+      const manifestFieldCount = Object.keys(manifestEntry.fields).length;
+      let didHydrate = false;
+      const needsFieldHydration = Object.entries(manifestEntry.fields).some(
+        ([fieldName, fieldDef]) => {
+          const existingField = registered.fields.get(fieldName);
+          if (!existingField) {
+            return true;
+          }
+          return manifestFieldDiffers(existingField, fieldDef);
+        }
+      );
+      const needsMethodHydration = !!manifestEntry.methods && Object.entries(manifestEntry.methods).some(
+        ([methodName, methodDef]) => {
+          return JSON.stringify(registered.methods.get(methodName)) !== JSON.stringify(methodDef);
+        }
+      );
+      const needsRegistrationHydration = !!manifestEntry.packageName && registered.packageName !== manifestEntry.packageName || !!manifestEntry.extends && registered.extends !== manifestEntry.extends;
+      if (existingFieldCount > 0 && existingFieldCount >= manifestFieldCount && !needsFieldHydration && !needsMethodHydration && !needsRegistrationHydration) {
+        return;
+      }
+      for (const [fieldName, fieldDef] of Object.entries(
+        manifestEntry.fields
+      )) {
+        const existingField = registered.fields.get(fieldName);
+        if (!existingField) {
+          registered.fields.set(fieldName, createFieldFromManifest(fieldDef));
+          didHydrate = true;
+          continue;
+        }
+        if (manifestFieldDiffers(existingField, fieldDef)) {
+          registered.fields.set(
+            fieldName,
+            mergeManifestField(existingField, fieldDef)
+          );
+          didHydrate = true;
+        }
+      }
+      if (manifestEntry.methods) {
+        for (const [methodName, methodDef] of Object.entries(
+          manifestEntry.methods
+        )) {
+          registered.methods.set(methodName, methodDef);
+        }
+        didHydrate = true;
+      }
+      if (manifestEntry.schema) {
+        const columns = cloneManifestSchemaColumns(
+          manifestEntry.schema.columns
+        );
+        applyManifestFieldColumnMetadata(columns, registered.fields.entries());
+        registered.schema = {
+          ddl: manifestEntry.schema.ddl,
+          tableName: manifestEntry.schema.tableName || registered.schema?.tableName || classnameToTablename(registered.name),
+          columns,
+          indexes: manifestEntry.schema.indexes?.map((indexDef) => ({
+            ...indexDef,
+            columns: [...indexDef.columns || []]
+          })) || [],
+          triggers: [],
+          foreignKeys: [],
+          dependencies: [],
+          version: manifestEntry.schema.version || "",
+          packageName: manifestEntry.packageName,
+          baseClass: registered.schema?.baseClass
+        };
+        didHydrate = true;
+      }
+      if (manifestEntry.packageName) {
+        registered.packageName = manifestEntry.packageName;
+        registered.qualifiedName = createQualifiedName(
+          manifestEntry.packageName,
+          registered.name
+        );
+        didHydrate = true;
+      }
+      if (manifestEntry.extends) {
+        registered.extends = manifestEntry.extends;
+        didHydrate = true;
+      }
+      if (didHydrate) {
+        ObjectRegistry.invalidateInheritanceCache(className);
+      }
+      verboseLog(
+        `📦 Loaded manifest for external package class: ${className} (${registered.fields.size} fields, ${registered.methods.size} methods)`
+      );
+    } else {
+      throw new Error(
+        `Cannot find manifest for class '${className}'.
+
+SMRT classes require a manifest generated at build time by the AST scanner.
+
+If this is an external package class, verify:
+  1. Package exports manifest: Check package.json has:
+     "exports": { "./manifest": "./dist/manifest.json" }
+  2. Package is built: Run npm run build in the package
+  3. Manifest exists: Confirm dist/manifest.json exists
+
+See: https://github.com/happyvertical/smrt/issues/131`
+      );
+    }
+  }
+  /**
+   * Get configuration for a registered class
+   */
+  static getConfig(name) {
+    const registered = ObjectRegistry.findClass(name);
+    return registered ? registered.config : {};
+  }
+  /**
+   * Get cached schema definition for a registered class
+   */
+  static getSchema(name) {
+    return getSchema(name);
+  }
+  /**
+   * Get SQL DDL statement for a registered class
+   */
+  static getSchemaDDL(name) {
+    return getSchemaDDL(name);
+  }
+  /**
+   * Get table name for a registered class
+   */
+  static getTableName(name) {
+    return getTableName(name);
+  }
+  /**
+   * Get all pre-generated schemas for passing to database adapters
+   */
+  static getAllSchemas() {
+    return getAllSchemas();
+  }
+  /**
+   * Get all registered schemas as SchemaDefinition objects
+   */
+  static getAllSchemasAsDefinitions() {
+    return getAllSchemasAsDefinitions();
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(name);
+    return registered?.validators;
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(name);
+    return registered?.validationRules;
+  }
+  /**
+   * 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 async validateWithRules(instance, rules, className) {
+    const { ValidationError } = await import("./errors.js");
+    const errors = [];
+    for (const rule of rules) {
+      const value = instance[rule.field];
+      switch (rule.rule) {
+        case "required":
+          if (value === null || value === void 0 || value === "") {
+            errors.push(ValidationError.requiredField(rule.field, className));
+          }
+          break;
+        case "min":
+          if (value !== null && value !== void 0 && value < rule.value) {
+            errors.push(
+              ValidationError.rangeError(
+                rule.field,
+                value,
+                rule.value,
+                void 0
+              )
+            );
+          }
+          break;
+        case "max":
+          if (value !== null && value !== void 0 && value > rule.value) {
+            errors.push(
+              ValidationError.rangeError(
+                rule.field,
+                value,
+                void 0,
+                rule.value
+              )
+            );
+          }
+          break;
+        case "minLength":
+          if (value && typeof value === "string" && value.length < rule.value) {
+            errors.push(
+              ValidationError.invalidValue(
+                rule.field,
+                value,
+                `string with minimum length ${rule.value}`
+              )
+            );
+          }
+          break;
+        case "maxLength":
+          if (value && typeof value === "string" && value.length > rule.value) {
+            errors.push(
+              ValidationError.invalidValue(
+                rule.field,
+                value,
+                `string with maximum length ${rule.value}`
+              )
+            );
+          }
+          break;
+        case "pattern":
+          if (value && typeof value === "string") {
+            const regex = new RegExp(rule.value);
+            if (!regex.test(value)) {
+              errors.push(
+                ValidationError.invalidValue(
+                  rule.field,
+                  value,
+                  `string matching pattern ${rule.value}`
+                )
+              );
+            }
+          }
+          break;
+      }
+    }
+    return errors;
+  }
+  /**
+   * 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() {
+    return getDependencyGraph();
+  }
+  /**
+   * 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() {
+    const graph = ObjectRegistry.getDependencyGraph();
+    const visited = /* @__PURE__ */ new Set();
+    const visiting = /* @__PURE__ */ new Set();
+    const order = [];
+    const cycleMembers = /* @__PURE__ */ new Set();
+    function visit(className) {
+      if (visiting.has(className)) {
+        cycleMembers.add(className);
+        return;
+      }
+      if (visited.has(className)) {
+        return;
+      }
+      visiting.add(className);
+      const dependencies = graph.get(className) || [];
+      for (const dep of dependencies) {
+        visit(dep);
+      }
+      visiting.delete(className);
+      visited.add(className);
+      order.push(className);
+    }
+    for (const className of graph.keys()) {
+      if (!visited.has(className)) {
+        visit(className);
+      }
+    }
+    if (cycleMembers.size > 0) {
+      logger.warn(
+        `[ObjectRegistry] Foreign-key cycle(s) detected and broken for ordering: ${[
+          ...cycleMembers
+        ].join(", ")}. Tables are created without strict cyclic ordering; SMRT does not emit DB-level FOREIGN KEY constraints, so this is safe.`
+      );
+    }
+    return order;
+  }
+  /**
+   * 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() {
+    return getRelationshipMap();
+  }
+  /**
+   * 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) {
+    return ObjectRegistry.getRelationshipMap().get(className) || [];
+  }
+  /**
+   * 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) {
+    return getInheritanceChain(className);
+  }
+  /**
+   * 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 async getAllFields(className) {
+    return getAllFields(className);
+  }
+  /**
+   * 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
+   */
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: reached in by issue #841 field-merge tests via `(ObjectRegistry as any).mergeFieldConfigs`; kept as the registry-side surface delegating to the shared resolver impl.
+  static mergeFieldConfigs(parentField, childField, fieldName) {
+    return mergeFieldConfigs(parentField, childField, fieldName);
+  }
+  /**
+   * 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 async getAllMethods(className) {
+    return getAllMethods(className);
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(className);
+    if (!registered) {
+      return null;
+    }
+    return {
+      name: registered.name,
+      constructor: registered.constructor,
+      collectionConstructor: registered.collectionConstructor,
+      config: registered.config,
+      fields: new Map(registered.fields),
+      // Return copy to prevent mutations
+      methods: new Map(registered.methods),
+      // Return copy to prevent mutations
+      schema: registered.schema,
+      validators: registered.validators || [],
+      relationships: ObjectRegistry.getRelationships(className),
+      inverseRelationships: ObjectRegistry.getInverseRelationships(className),
+      tools: registered.tools
+    };
+  }
+  /**
+   * 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() {
+    const allMetadata = [];
+    for (const [_key, entry] of ObjectRegistry.classes) {
+      const metadata = ObjectRegistry.getObjectMetadata(entry.name || _key);
+      if (metadata) {
+        allMetadata.push(metadata);
+      }
+    }
+    return allMetadata;
+  }
+  /**
+   * 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) {
+    const allRelationships = ObjectRegistry.getRelationshipMap();
+    const inverseRelationships = [];
+    for (const [_sourceClass, relationships] of allRelationships) {
+      for (const rel of relationships) {
+        if (rel.targetClass === className) {
+          inverseRelationships.push(rel);
+        }
+      }
+    }
+    return inverseRelationships;
+  }
+  /**
+   * 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) {
+    const names = /* @__PURE__ */ new Set([className]);
+    for (const ancestor of ObjectRegistry.getInheritanceChain(className)) {
+      names.add(ancestor);
+      const simple = ObjectRegistry.getClass(ancestor)?.name;
+      if (simple) {
+        names.add(simple);
+      }
+    }
+    return names;
+  }
+  /**
+   * 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) {
+    const names = ObjectRegistry.getSelfReferableNames(className);
+    const result = [];
+    for (const [, relationships] of ObjectRegistry.getRelationshipMap()) {
+      for (const rel of relationships) {
+        if (names.has(rel.targetClass)) {
+          result.push(rel);
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(className);
+    if (!registered) {
+      return "cti";
+    }
+    if (registered.config?.tableStrategy) {
+      return registered.config.tableStrategy;
+    }
+    const chain = ObjectRegistry.getInheritanceChain(className);
+    for (const ancestorName of chain) {
+      const ancestor = ObjectRegistry.findClass(ancestorName);
+      if (ancestor?.config?.tableStrategy) {
+        return ancestor.config.tableStrategy;
+      }
+    }
+    return "cti";
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(className);
+    if (!registered) {
+      return ["slug", "context"];
+    }
+    if (registered.config?.conflictColumns) {
+      return registered.config.conflictColumns;
+    }
+    const tableStrategy = ObjectRegistry.getTableStrategy(className);
+    return tableStrategy === "sti" ? ["slug", "context", "_meta_type"] : ["slug", "context"];
+  }
+  /**
+   * 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) {
+    const registered = ObjectRegistry.findClass(className);
+    return registered?.tenantScopedConfig;
+  }
+  /**
+   * 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) {
+    return ObjectRegistry.getTenantScopedConfig(className) !== void 0;
+  }
+  /**
+   * 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) {
+    const strategy = ObjectRegistry.getTableStrategy(className);
+    if (strategy === "cti") {
+      return null;
+    }
+    const chain = ObjectRegistry.getInheritanceChain(className);
+    for (const ancestorName of chain) {
+      const ancestor = ObjectRegistry.findClass(ancestorName);
+      if (!ancestor) continue;
+      if (ancestor.config?.tableStrategy === "sti") {
+        return ancestor.qualifiedName ?? ancestor.name;
+      }
+    }
+    const self = ObjectRegistry.findClass(className);
+    return self?.qualifiedName ?? self?.name ?? className;
+  }
+  /**
+   * 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) {
+    const descendants = [];
+    const seenRegistrations = /* @__PURE__ */ new Set();
+    const target = ObjectRegistry.findClass(className);
+    const targetKey = target?.qualifiedName ?? target?.name ?? className;
+    for (const [_key, childClass] of ObjectRegistry.classes) {
+      if (seenRegistrations.has(childClass)) {
+        continue;
+      }
+      seenRegistrations.add(childClass);
+      const childKey = childClass.qualifiedName ?? childClass.name ?? _key;
+      if (childKey === targetKey) continue;
+      const chain = ObjectRegistry.getInheritanceChain(childKey);
+      if (chain.includes(targetKey)) {
+        descendants.push(childKey);
+      }
+    }
+    return descendants;
+  }
+  /**
+   * 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 async persistToDatabase(db) {
+    for (const [className, registered] of ObjectRegistry.classes.entries()) {
+      const fieldsData = {};
+      for (const [key, value] of registered.fields) {
+        fieldsData[key] = {
+          type: value.type,
+          options: value.options
+        };
+      }
+      await db.upsert(
+        "_smrt_registry",
+        ["class_name"],
+        // PRIMARY KEY for conflict detection
+        {
+          class_name: className,
+          schema_version: "1.0.0",
+          // Could be derived from package version
+          fields: JSON.stringify(fieldsData),
+          relationships: JSON.stringify(
+            ObjectRegistry.getRelationships(className)
+          ),
+          config: JSON.stringify(registered.config),
+          manifest: JSON.stringify({
+            name: registered.name,
+            tableName: registered.schema?.tableName,
+            tools: registered.tools
+          }),
+          last_updated: /* @__PURE__ */ new Date()
+        }
+      );
+    }
+  }
+  /**
+   * 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 async loadFromDatabase(db) {
+    const { rows } = await db.query(
+      "SELECT * FROM _smrt_registry ORDER BY class_name"
+    );
+    return rows;
+  }
+  // ============================================================================
+  // Embedding Configuration Methods
+  // ============================================================================
+  /**
+   * 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) {
+    return getEmbeddingConfig(className);
+  }
+  /**
+   * 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) {
+    return hasEmbeddings(className);
+  }
+  /**
+   * 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() {
+    return getEmbeddingClasses();
+  }
+  /**
+   * 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() {
+    return getProjectEmbeddingConfig();
+  }
+  /**
+   * 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) {
+    return resolveEmbeddingConfig(className);
+  }
+  /**
+   * 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) {
+    return resolveCollectionCacheConfig(className);
+  }
+}
+function smrt(config = {}) {
+  return (ctor, decoratorContext) => {
+    applyPendingDecoratorRegistrations(ctor, decoratorContext);
+    const isCollection = ctor.prototype instanceof SmrtCollection;
+    if (isCollection) {
+      const itemClass = ctor._itemClass;
+      if (itemClass) {
+        let tableName = config.tableName;
+        if (!tableName) {
+          const itemClassName = itemClass.name;
+          const itemReg = ObjectRegistry.getClassByConstructor(
+            itemClass
+          );
+          const itemQualified = itemReg?.qualifiedName ?? itemClassName;
+          const stiBase = ObjectRegistry.getSTIBase(itemQualified);
+          if (stiBase && stiBase !== itemQualified) {
+            const baseReg = ObjectRegistry.getClass(stiBase);
+            tableName = baseReg?.schema?.tableName ?? classnameToTablename(baseReg?.name ?? stiBase);
+          } else if (ObjectRegistry.getTableStrategy(itemQualified) === "sti") {
+            tableName = classnameToTablename(itemClassName);
+          } else {
+            tableName = classnameToTablename(itemClassName);
+          }
+        }
+        ObjectRegistry.register(itemClass, { ...config, tableName });
+        const registeredItemClass = ObjectRegistry.getClass(itemClass.name);
+        ObjectRegistry.registerCollection(itemClass.name, ctor);
+        if (registeredItemClass?.qualifiedName) {
+          ObjectRegistry.registerCollection(
+            registeredItemClass.qualifiedName,
+            ctor
+          );
+        }
+        ObjectRegistry.registerCollection(tableName, ctor);
+        ObjectRegistry.setCollectionTableName(ctor.name, tableName);
+      }
+    } else {
+      let tableName = config.tableName;
+      if (!tableName) {
+        const manifestEntry = discoverCachedManifestSync(ctor.name);
+        if (manifestEntry?.decoratorConfig?.tableName) {
+          tableName = manifestEntry.decoratorConfig.tableName;
+        } else if (config.tableStrategy === "sti") {
+          let proto = Object.getPrototypeOf(ctor);
+          let stiBaseName = null;
+          while (proto?.name && proto.name !== "SmrtObject") {
+            const protoReg = ObjectRegistry.getClassByConstructor(proto);
+            const protoKey = protoReg?.qualifiedName ?? proto.name;
+            if (ObjectRegistry.getTableStrategy(protoKey) === "sti") {
+              stiBaseName = ObjectRegistry.getSTIBase(protoKey);
+              break;
+            }
+            proto = Object.getPrototypeOf(proto);
+          }
+          if (stiBaseName) {
+            const baseReg = ObjectRegistry.getClass(stiBaseName);
+            tableName = baseReg?.schema?.tableName ?? classnameToTablename(baseReg?.name ?? stiBaseName);
+          } else {
+            tableName = classnameToTablename(ctor.name);
+          }
+        } else {
+          let proto = Object.getPrototypeOf(ctor);
+          let stiBaseName = null;
+          while (proto?.name && proto.name !== "SmrtObject") {
+            const protoReg = ObjectRegistry.getClassByConstructor(proto);
+            const protoKey = protoReg?.qualifiedName ?? proto.name;
+            if (ObjectRegistry.getTableStrategy(protoKey) === "sti") {
+              stiBaseName = ObjectRegistry.getSTIBase(protoKey);
+              break;
+            }
+            proto = Object.getPrototypeOf(proto);
+          }
+          if (stiBaseName) {
+            const baseReg = ObjectRegistry.getClass(stiBaseName);
+            tableName = baseReg?.schema?.tableName ?? classnameToTablename(baseReg?.name ?? stiBaseName);
+          } else {
+            tableName = classnameToTablename(ctor.name);
+          }
+        }
+      }
+      ObjectRegistry.register(ctor, { ...config, tableName });
+      applyOneToManyChildAccessors(
+        ctor,
+        ObjectRegistry.getRelationships(ctor.name)
+      );
+    }
+    return ctor;
+  };
+}
+export {
+  ObjectRegistry,
+  SMRT_COLLECTION_BASE_NAMES,
+  isSmrtCollectionExtendsName,
+  smrt
+};
+//# sourceMappingURL=registry.js.map