@happyvertical/smrt-core 0.30.0

package/dist/collection.js

@@ -0,0 +1,1987 @@
+import { createLogger } from "@happyvertical/logger";
+import { buildWhere } from "@happyvertical/sql";
+import { SmrtClass } from "./class.js";
+import { resolveDbCacheKey, buildQueryCacheKey, ensureCacheInvalidationListener, registerCrossProcessCacheInterest, getCachedRows, getCacheGeneration, setCachedRows, invalidateCollectionCache } from "./collection-cache.js";
+import { EmbeddingProvider } from "./embeddings/provider.js";
+import { EmbeddingStorage } from "./embeddings/storage.js";
+import { createInterceptorContext, GlobalInterceptors } from "./interceptors.js";
+import { ObjectRegistry } from "./registry.js";
+import { verifyPersistenceTable } from "./schema/table-verifier.js";
+import { fieldsFromClass, toCamelCase, formatDataJs } from "./utils.js";
+import { chunkArray, IN_LIST_CHUNK_SIZE } from "./utils/chunk.js";
+import { toSnakeCase, classnameToTablename } from "./utils/naming.js";
+const logger = createLogger({ level: "info" });
+function resolveMetaTypeInWhere(where) {
+  if (!where?._meta_type || typeof where._meta_type !== "string") {
+    return where;
+  }
+  const metaTypeValue = where._meta_type;
+  if (metaTypeValue.includes(":")) {
+    return where;
+  }
+  const registeredClass = ObjectRegistry.getClass(metaTypeValue);
+  if (registeredClass?.qualifiedName) {
+    return {
+      ...where,
+      _meta_type: registeredClass.qualifiedName
+    };
+  }
+  return where;
+}
+class SmrtCollection extends SmrtClass {
+  /**
+   * Cached fields for sync access during queries.
+   * Populated during create() to avoid async getFields() calls on every query.
+   * @private
+   */
+  _cachedFields = null;
+  getRegisteredItemClass() {
+    return ObjectRegistry.getClassByConstructor(this._itemClass) || ObjectRegistry.getClass(this._itemClass.name);
+  }
+  getResolvedItemClassName() {
+    return this.getRegisteredItemClass()?.name || this._itemClass.name;
+  }
+  getResolvedItemQualifiedName() {
+    const registered = this.getRegisteredItemClass();
+    return registered?.qualifiedName || registered?.name || this._itemClass.name;
+  }
+  /**
+   * Convert WHERE clause field names from camelCase to snake_case while preserving operators.
+   * Validates operators and field names to prevent SQL injection and invalid queries.
+   *
+   * Uses cached fields for sync access (issue #663) to avoid async overhead on every query.
+   *
+   * @param where - WHERE clause object with camelCase field names
+   * @returns WHERE clause object with snake_case field names
+   * @private
+   *
+   * @example
+   * ```typescript
+   * // Input: { 'typeId': 'foo', 'categoryId >': 100 }
+   * // Output: { 'type_id': 'foo', 'category_id >': 100 }
+   * ```
+   */
+  convertWhereKeys(where) {
+    const VALID_OPERATORS = [
+      "=",
+      ">",
+      "<",
+      ">=",
+      "<=",
+      "!=",
+      "in",
+      "not in",
+      "like",
+      "contains"
+    ];
+    const fields = this.getFieldsSync();
+    const validFieldNames = new Set(
+      Object.keys(fields).map((f) => toSnakeCase(f))
+    );
+    const sensitiveFieldNames = /* @__PURE__ */ new Set();
+    const collectSensitive = (fieldMap) => {
+      const entries = fieldMap instanceof Map ? fieldMap.entries() : Object.entries(fieldMap);
+      for (const [fieldName, def] of entries) {
+        if (def && (def.sensitive === true || def._meta?.sensitive === true)) {
+          sensitiveFieldNames.add(toSnakeCase(fieldName));
+          sensitiveFieldNames.add(fieldName);
+        }
+      }
+    };
+    collectSensitive(fields);
+    validFieldNames.add("id");
+    validFieldNames.add("slug");
+    validFieldNames.add("context");
+    validFieldNames.add("created_at");
+    validFieldNames.add("updated_at");
+    const itemClassName = this.getResolvedItemClassName();
+    const itemQualifiedName = this.getResolvedItemQualifiedName();
+    const tableStrategy = ObjectRegistry.getTableStrategy(itemQualifiedName);
+    if (tableStrategy === "sti") {
+      validFieldNames.add("_meta_type");
+      validFieldNames.add("meta_type");
+      validFieldNames.add("_meta_data");
+      validFieldNames.add("meta_data");
+      const inheritanceChain = ObjectRegistry.getInheritanceChain(itemQualifiedName);
+      for (const ancestorName of inheritanceChain) {
+        if (ancestorName === "SmrtObject" || ancestorName === "SmrtClass" || ancestorName === itemQualifiedName || ancestorName === itemClassName) {
+          continue;
+        }
+        const ancestorFields = ObjectRegistry.getFields(ancestorName);
+        for (const fieldName of ancestorFields.keys()) {
+          validFieldNames.add(toSnakeCase(fieldName));
+        }
+        collectSensitive(ancestorFields);
+      }
+      const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+      if (stiBase) {
+        for (const descendant of ObjectRegistry.getDescendants(stiBase)) {
+          collectSensitive(ObjectRegistry.getFields(descendant));
+        }
+      }
+    }
+    const hasRegisteredFields = Object.keys(fields).length > 0;
+    const skipFieldValidation = !hasRegisteredFields;
+    const converted = {};
+    if (Object.hasOwn(where, "__proto__") || Object.hasOwn(where, "constructor") || Object.hasOwn(where, "prototype")) {
+      throw new Error(
+        `Invalid WHERE clause: Prototype pollution attempts are not allowed. Detected dangerous properties in WHERE clause.`
+      );
+    }
+    for (const [key, value] of Object.entries(where)) {
+      const parts = key.trim().split(/\s+/);
+      const fieldName = parts[0];
+      const operator = parts.slice(1).join(" ") || "=";
+      if (fieldName === "__proto__" || fieldName === "constructor" || fieldName === "prototype" || fieldName.includes("__proto__") || fieldName.includes("constructor") || fieldName.includes("prototype")) {
+        throw new Error(
+          `Invalid WHERE clause field: '${fieldName}'. Prototype pollution attempts are not allowed.`
+        );
+      }
+      const dotIndex = fieldName.indexOf(".");
+      const baseFieldName = dotIndex >= 0 ? fieldName.substring(0, dotIndex) : fieldName;
+      const jsonPath = dotIndex >= 0 ? fieldName.substring(dotIndex) : null;
+      const snakeBaseFieldName = baseFieldName.startsWith("_") ? `_${toSnakeCase(baseFieldName.slice(1))}` : toSnakeCase(baseFieldName);
+      const snakeFieldName = jsonPath ? `${snakeBaseFieldName}${jsonPath}` : snakeBaseFieldName;
+      if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)*$/.test(snakeFieldName)) {
+        throw new Error(
+          `Invalid WHERE clause field: '${fieldName}'. Field names must be identifiers (letters, digits, underscore) with optional dot-separated JSON-path segments.`
+        );
+      }
+      const baseIsMetaData = snakeBaseFieldName === "_meta_data" || snakeBaseFieldName === "meta_data";
+      const metaPathTargetsSensitive = baseIsMetaData && !!jsonPath && jsonPath.split(".").filter(Boolean).some(
+        (segment) => sensitiveFieldNames.has(segment) || sensitiveFieldNames.has(toSnakeCase(segment))
+      );
+      if (sensitiveFieldNames.has(snakeBaseFieldName) || metaPathTargetsSensitive) {
+        throw new Error(
+          `Invalid WHERE clause field: '${fieldName}'. Filtering on sensitive fields is not allowed.`
+        );
+      }
+      const effectiveOperator = operator === "=" && Array.isArray(value) ? "in" : operator;
+      if (!VALID_OPERATORS.includes(effectiveOperator)) {
+        throw new Error(
+          `Invalid WHERE clause operator: '${operator}'. Valid operators: ${VALID_OPERATORS.join(", ")}`
+        );
+      }
+      if (!skipFieldValidation && !validFieldNames.has(snakeBaseFieldName)) {
+        throw new Error(
+          `Invalid WHERE clause field: '${fieldName}'. Field does not exist on ${itemClassName}. Valid fields: ${Array.from(validFieldNames).sort().join(", ")}`
+        );
+      }
+      if ((effectiveOperator === "in" || effectiveOperator === "not in") && !Array.isArray(value)) {
+        throw new Error(
+          `WHERE clause operator '${effectiveOperator}' requires an array value for field '${fieldName}', got ${typeof value}`
+        );
+      }
+      if ((effectiveOperator === "in" || effectiveOperator === "not in") && Array.isArray(value) && value.length === 0) {
+        throw new Error(
+          `WHERE clause operator '${effectiveOperator}' requires a non-empty array for field '${fieldName}'. Use listByIds([]) for graceful empty array handling.`
+        );
+      }
+      if (effectiveOperator === "like" && typeof value !== "string") {
+        throw new Error(
+          `WHERE clause operator 'like' requires a string value for field '${fieldName}', got ${typeof value}`
+        );
+      }
+      const newKey = effectiveOperator === "=" ? snakeFieldName : `${snakeFieldName} ${effectiveOperator}`;
+      converted[newKey] = value;
+    }
+    return converted;
+  }
+  /**
+   * Gets the class constructor for items in this collection
+   */
+  get _itemClass() {
+    const ctor = this.constructor;
+    if (!ctor._itemClass) {
+      const className = this.constructor.name;
+      const errorMessage = [
+        `Collection "${className}" must define a static _itemClass property.`,
+        "",
+        "Example:",
+        `  class ${className} extends SmrtCollection<YourItemClass> {`,
+        "    static readonly _itemClass = YourItemClass;",
+        "  }",
+        "",
+        "Make sure your item class is imported and defined before the collection class."
+      ].join("\n");
+      throw new Error(errorMessage);
+    }
+    return ctor._itemClass;
+  }
+  /**
+   * Static reference to the item class constructor
+   */
+  static _itemClass;
+  /**
+   * Validates that the collection is properly configured
+   * Call this during development to catch configuration issues early
+   */
+  static validate() {
+    if (!SmrtCollection._itemClass) {
+      const className = SmrtCollection.name;
+      const errorMessage = [
+        `Collection "${className}" is missing required static _itemClass property.`,
+        "",
+        "Fix by adding:",
+        `  class ${className} extends SmrtCollection<YourItemClass> {`,
+        "    static readonly _itemClass = YourItemClass;",
+        "  }"
+      ].join("\n");
+      throw new Error(errorMessage);
+    }
+    if (typeof SmrtCollection._itemClass !== "function") {
+      throw new Error(
+        `Collection "${SmrtCollection.name}"._itemClass must be a constructor function`
+      );
+    }
+    const hasCreateMethod = typeof SmrtCollection._itemClass.create === "function" || typeof SmrtCollection._itemClass.prototype?.create === "function";
+    if (!hasCreateMethod) {
+      logger.warn(
+        `Collection "${SmrtCollection.name}"._itemClass should have a create() method for optimal functionality`
+      );
+    }
+  }
+  /**
+   * Database table name for this collection
+   */
+  _tableName;
+  /**
+   * Creates a new SmrtCollection instance
+   *
+   * @deprecated Use the static create() factory method instead
+   * @param options - Configuration options
+   */
+  constructor(options = {}) {
+    super(options);
+    if (this.constructor !== SmrtCollection && this.constructor._itemClass) {
+      const itemClass = this.constructor._itemClass;
+      const itemClassName = ObjectRegistry.getClassByConstructor(itemClass)?.name || itemClass.name;
+      ObjectRegistry.registerCollection(itemClassName, this.constructor);
+    }
+  }
+  /**
+   * Factory method — the recommended way to instantiate a collection.
+   *
+   * Creates the collection instance, calls `initialize()`, and pre-populates
+   * the field cache used by synchronous query helpers.
+   *
+   * Pass the same `options` object you received in a `SmrtObject` constructor
+   * or a `SvelteKit` load function to share the database connection.
+   *
+   * @param options - Database, AI, filesystem, and other configuration options.
+   *   At minimum, provide `db` (or `persistence`) to connect to a database.
+   * @returns A fully initialized, ready-to-query collection instance
+   *
+   * @example
+   * ```typescript
+   * // Share a DB connection from a SvelteKit load function
+   * const products = await Products.create(event.locals.smrtOptions);
+   *
+   * // Explicit configuration
+   * const products = await Products.create({
+   *   db: myDb,
+   *   ai: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
+   * });
+   * ```
+   */
+  static async create(options = {}) {
+    const {
+      _className,
+      db,
+      persistence,
+      // Also extract persistence alias
+      ai,
+      fs,
+      logging,
+      metrics,
+      pubsub,
+      sanitization,
+      signals
+    } = options;
+    const collectionOptions = {
+      _className,
+      db,
+      persistence,
+      // Pass persistence through so initialize() can map it to db
+      ai,
+      fs,
+      logging,
+      metrics,
+      pubsub,
+      sanitization,
+      signals
+    };
+    if (this._isJunctionBase === true) {
+      const itemCtor = this._itemClass;
+      const itemRegistered = itemCtor && ObjectRegistry.getClassByConstructor(itemCtor);
+      if (!itemRegistered) {
+        throw new Error(
+          `SmrtJunction subclass "${this.name}" has no registered item class. The scanner likely didn't pick up its model — usually because the consuming package's manifest doesn't include "${itemCtor?.name ?? "<unknown>"}". Check that the scanner's FRAMEWORK_BASE_CLASSES (packages/scanner/src/inheritance-resolver.ts) recognizes every framework abstract base in your inheritance chain, that the package has been built (manifest.json present in dist/), and that runtime manifest loading (__smrt-register__.ts) runs before any junction is instantiated.`
+        );
+      }
+    }
+    const instance = new this(collectionOptions);
+    await instance.initialize();
+    const fields = await instance.getFields();
+    instance._cachedFields = fields;
+    return instance;
+  }
+  /**
+   * Async initialization hook for the collection.
+   *
+   * Called automatically by the static `create()` factory. In most cases you
+   * do not need to call this directly — use `create()` instead.
+   *
+   * Runtime schema checks are deferred until a query actually touches the
+   * backing table. This keeps collection construction safe during SSR and
+   * import-time module evaluation without mutating application schema.
+   *
+   * @returns This instance (enables chaining)
+   */
+  async initialize() {
+    await super.initialize();
+    return this;
+  }
+  /**
+   * Verify that the collection's backing table exists before running a query.
+   *
+   * This is a fail-fast check only. It does not create or alter schema.
+   */
+  async ensureStorageReady() {
+    await verifyPersistenceTable(
+      this.db,
+      this.tableName,
+      this.getResolvedItemClassName()
+    );
+  }
+  /**
+   * Find a single record by criteria (convenience method - delegates to get())
+   *
+   * @param options - Query options with where clause
+   * @returns Promise resolving to the object or null if not found
+   *
+   * @example
+   * ```typescript
+   * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+   * const council = await councils.findOne({ where: { name: 'Example Council' } });
+   * ```
+   */
+  async findOne(options) {
+    return await this.get(options.where);
+  }
+  /**
+   * Find a record by ID (convenience method - delegates to get())
+   *
+   * @param id - Record ID to find (string or Field instance)
+   * @returns Promise resolving to the object or null if not found
+   *
+   * @example
+   * ```typescript
+   * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+   * const council = await councils.findById('uuid-123');
+   *
+   * // Also works with Field instances (e.g., from foreignKey fields)
+   * const meeting = new Meeting({ councilId: 'uuid-123' });
+   * const council = await councils.findById(meeting.councilId);
+   * ```
+   */
+  async findById(id) {
+    return await this.get(id);
+  }
+  /**
+   * Find all records matching criteria (convenience method - delegates to list())
+   *
+   * @param options - Query options (where, orderBy, limit, etc.)
+   * @returns Promise resolving to array of objects
+   *
+   * @example
+   * ```typescript
+   * const councils = await Councils.create({ persistence: { type: 'sql', url: 'db.sqlite' } });
+   * const active = await councils.findAll({ where: { status: 'active' } });
+   * ```
+   */
+  async findAll(options = {}) {
+    return await this.list(options);
+  }
+  /**
+   * Find multiple objects by their IDs in a single query.
+   *
+   * This is a convenience method that avoids N+1 queries when you have
+   * a list of IDs and need to fetch the corresponding records.
+   *
+   * @param ids - Array of UUIDs to fetch
+   * @returns Promise resolving to array of objects (order not guaranteed)
+   *
+   * @example
+   * ```typescript
+   * const profiles = await profileCollection.listByIds(['id1', 'id2', 'id3']);
+   * ```
+   */
+  async listByIds(ids) {
+    if (ids.length === 0) return [];
+    return this.list({ where: { id: ids } });
+  }
+  /**
+   * Resolve the effective cache config for a read (issue #1498).
+   *
+   * Per-call options win: `false` forces a fresh read, `{ ttl }` enables
+   * caching for this call. Otherwise falls back to the model-level
+   * `@smrt({ cache })` config (inheritance-aware). Returns undefined when
+   * the read should go straight to the database — the default.
+   */
+  resolveReadCacheConfig(perCall) {
+    if (perCall === false) return void 0;
+    if (perCall) return perCall.ttl > 0 ? perCall : void 0;
+    return ObjectRegistry.resolveCollectionCacheConfig(
+      this.getResolvedItemQualifiedName()
+    );
+  }
+  /**
+   * Execute a SELECT, optionally through the collection read cache.
+   *
+   * The cache key is the final SQL + bound parameters — computed after
+   * interceptors (tenancy filters) and STI discriminators are applied, so
+   * differently-scoped queries can never share an entry. Cached values are
+   * raw rows; hydration and read interceptors still run on every call.
+   */
+  async queryRowsWithCache(sql, params, cacheConfig) {
+    if (!cacheConfig) {
+      const result2 = await this.db.query(sql, ...params);
+      return result2.rows;
+    }
+    const dbKey = resolveDbCacheKey(this.db);
+    const queryKey = buildQueryCacheKey(sql, params);
+    if (cacheConfig.crossProcess) {
+      ensureCacheInvalidationListener(this.db);
+      registerCrossProcessCacheInterest(dbKey, this.tableName);
+    }
+    const cached = getCachedRows(dbKey, this.tableName, queryKey);
+    if (cached) {
+      return cached;
+    }
+    const generation = getCacheGeneration(dbKey, this.tableName);
+    const result = await this.db.query(sql, ...params);
+    setCachedRows(
+      dbKey,
+      this.tableName,
+      queryKey,
+      result.rows,
+      cacheConfig.ttl,
+      generation
+    );
+    return result.rows;
+  }
+  /**
+   * Retrieves a single object from the collection by ID, slug, or a custom filter.
+   *
+   * Filter resolution:
+   * - UUID string → `WHERE id = ?`
+   * - Non-UUID string → `WHERE slug = ? AND context = ''`
+   * - Object → `WHERE <key> = <value> [AND ...]`
+   *
+   * For STI child collections, an `AND _meta_type = '<qualifiedName>'` clause is
+   * automatically appended so you only receive the correct subclass.
+   *
+   * Runs `beforeGet` / `afterGet` interceptors (used by multi-tenancy, etc.).
+   *
+   * @param filter - UUID string, slug string, or a WHERE conditions object
+   * @param options.cache - Opt-in read-through cache for this call
+   *   (`{ ttl }` in milliseconds), or `false` to force a fresh read when the
+   *   model opted in via `@smrt({ cache })`. Defaults to the model config.
+   * @returns The matching object instance, or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * // By UUID
+   * const product = await products.get('550e8400-e29b-41d4-a716-446655440000');
+   *
+   * // By slug
+   * const product = await products.get('my-widget');
+   *
+   * // By custom filter
+   * const product = await products.get({ sku: 'WID-001' });
+   *
+   * // Cached read (memoized for 60s, invalidated on writes)
+   * const product = await products.get('my-widget', { cache: { ttl: 60_000 } });
+   * ```
+   *
+   * @see {@link list} for multiple results
+   * @see {@link findById} / {@link findOne} for convenience aliases
+   */
+  async get(filter, options = {}) {
+    await this.ensureStorageReady();
+    const itemClassName = this.getResolvedItemClassName();
+    const itemQualifiedName = this.getResolvedItemQualifiedName();
+    const interceptorContext = createInterceptorContext(
+      itemClassName,
+      "get",
+      this.constructor.name
+    );
+    const interceptedFilter = await GlobalInterceptors.executeBeforeGet(
+      itemClassName,
+      filter,
+      interceptorContext
+    );
+    let where = typeof interceptedFilter === "string" ? /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      interceptedFilter
+    ) ? { id: interceptedFilter } : { slug: interceptedFilter, context: "" } : interceptedFilter;
+    const tableStrategy = ObjectRegistry.getTableStrategy(itemQualifiedName);
+    const isSTI = tableStrategy === "sti";
+    if (isSTI) {
+      const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+      if (stiBase && stiBase !== itemQualifiedName) {
+        where = {
+          _meta_type: itemQualifiedName,
+          ...where
+        };
+      }
+    }
+    const convertedWhere = this.convertWhereKeys(where);
+    const { sql: whereSql, values: whereValues } = buildWhere(convertedWhere);
+    const fullSQL = `SELECT * FROM ${this.tableName} ${whereSql}`;
+    const rows = await this.queryRowsWithCache(
+      fullSQL,
+      whereValues,
+      this.resolveReadCacheConfig(options.cache)
+    );
+    if (!rows?.[0]) {
+      return await GlobalInterceptors.executeAfterGet(
+        itemClassName,
+        null,
+        interceptorContext
+      );
+    }
+    const fields = this.getFieldsSync();
+    const instance = await this.hydrateResultRow(rows[0], fields, isSTI);
+    return await GlobalInterceptors.executeAfterGet(
+      itemClassName,
+      instance,
+      interceptorContext
+    );
+  }
+  /**
+   * Lists records from the collection with flexible filtering options
+   *
+   * @param options - Query options object
+   * @param options.where - Record of conditions to filter results. Each key can include an operator
+   *                      separated by a space (e.g., 'price >', 'name like'). Default operator is '='.
+   * @param options.offset - Number of records to skip
+   * @param options.limit - Maximum number of records to return
+   * @param options.orderBy - Field(s) to order results by, with optional direction
+   *
+   * @example
+   * ```typescript
+   * // Find active products priced between $100-$200
+   * await collection.list({
+   *   where: {
+   *     'price >': 100,
+   *     'price <=': 200,
+   *     'status': 'active',              // equals operator is default
+   *     'category in': ['A', 'B', 'C'],  // IN operator for arrays
+   *     'name like': '%shirt%',          // LIKE for pattern matching
+   *     'deleted_at !=': null            // exclude deleted items
+   *   },
+   *   limit: 10,
+   *   offset: 0
+   * });
+   *
+   * // Find users matching pattern but not in specific roles
+   * await users.list({
+   *   where: {
+   *     'email like': '%@company.com',
+   *     'active': true,
+   *     'role in': ['guest', 'blocked'],
+   *     'last_login <': lastMonth
+   *   }
+   * });
+   * ```
+   *
+   * @returns Promise resolving to an array of model instances
+   */
+  async list(options = {}) {
+    await this.ensureStorageReady();
+    const itemClassName = this.getResolvedItemClassName();
+    const itemQualifiedName = this.getResolvedItemQualifiedName();
+    const interceptorContext = createInterceptorContext(
+      itemClassName,
+      "list",
+      this.constructor.name
+    );
+    const interceptedOptions = await GlobalInterceptors.executeBeforeList(
+      itemClassName,
+      options,
+      interceptorContext
+    ) ?? options ?? {};
+    let { where, offset, limit, orderBy } = interceptedOptions;
+    const tableStrategy = ObjectRegistry.getTableStrategy(itemQualifiedName);
+    const isSTI = tableStrategy === "sti";
+    if (isSTI) {
+      const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+      if (stiBase && stiBase !== itemQualifiedName) {
+        where = {
+          _meta_type: itemQualifiedName,
+          ...where || {}
+        };
+      }
+    }
+    where = resolveMetaTypeInWhere(where);
+    const convertedWhere = this.convertWhereKeys(where || {});
+    const { sql: whereSql, values: whereValues } = buildWhere(convertedWhere);
+    let orderBySql = "";
+    if (orderBy) {
+      orderBySql = " ORDER BY ";
+      const orderByItems = Array.isArray(orderBy) ? orderBy : [orderBy];
+      orderBySql += orderByItems.map((item) => {
+        const [field, direction = "ASC"] = item.split(" ");
+        if (!/^[a-zA-Z0-9_]+$/.test(field)) {
+          throw new Error(`Invalid field name for ordering: ${field}`);
+        }
+        const normalizedDirection = direction.toUpperCase();
+        if (normalizedDirection !== "ASC" && normalizedDirection !== "DESC") {
+          throw new Error(
+            `Invalid sort direction: ${direction}. Must be ASC or DESC.`
+          );
+        }
+        const snakeField = toSnakeCase(field);
+        return `${snakeField} ${normalizedDirection}`;
+      }).join(", ");
+    }
+    let limitOffsetSql = "";
+    const limitOffsetValues = [];
+    let paramIndex = whereValues.length + 1;
+    if (limit !== void 0) {
+      limitOffsetSql += ` LIMIT $${paramIndex++}`;
+      limitOffsetValues.push(limit);
+    }
+    if (offset !== void 0) {
+      limitOffsetSql += ` OFFSET $${paramIndex++}`;
+      limitOffsetValues.push(offset);
+    }
+    const sql = `SELECT * FROM ${this.tableName} ${whereSql} ${orderBySql} ${limitOffsetSql}`;
+    const params = [...whereValues, ...limitOffsetValues];
+    const rows = await this.queryRowsWithCache(
+      sql,
+      params,
+      this.resolveReadCacheConfig(
+        interceptedOptions.cache
+      )
+    );
+    const fields = this.getFieldsSync();
+    const instances = await Promise.all(
+      rows.map((item) => this.hydrateResultRow(item, fields, isSTI))
+    );
+    if (interceptedOptions.include && interceptedOptions.include.length > 0) {
+      await this.eagerLoadRelationships(
+        instances,
+        interceptedOptions.include
+      );
+    }
+    const finalInstances = await GlobalInterceptors.executeAfterList(
+      itemClassName,
+      instances,
+      interceptorContext
+    );
+    return finalInstances;
+  }
+  /**
+   * Eagerly load relationships for a collection of instances
+   *
+   * Optimizes loading by batching queries for foreignKey relationships to avoid N+1 queries.
+   *
+   * @param instances - Array of object instances to load relationships for
+   * @param relationships - Array of relationship field names to load
+   * @private
+   */
+  async eagerLoadRelationships(instances, relationships) {
+    if (instances.length === 0) return;
+    for (const fieldName of relationships) {
+      const relationshipMeta = ObjectRegistry.getRelationships(
+        this._itemClass.name
+      );
+      const relationship = relationshipMeta.find(
+        (r) => r.fieldName === fieldName
+      );
+      if (!relationship) {
+        logger.warn(
+          `Relationship ${fieldName} not found on ${this._itemClass.name}, skipping eager load`
+        );
+        continue;
+      }
+      if (relationship.type === "foreignKey" || relationship.type === "crossPackageRef") {
+        if (relationship.type === "crossPackageRef") {
+          await ObjectRegistry.ensureManifestLoaded(relationship.targetClass);
+        }
+        await this.batchLoadForeignKeys(instances, fieldName, relationship);
+      } else if (relationship.type === "oneToMany") {
+        await this.batchLoadOneToMany(instances, fieldName, relationship);
+      } else if (relationship.type === "manyToMany") {
+        await this.batchLoadManyToMany(instances, fieldName, relationship);
+      }
+    }
+  }
+  /**
+   * Batch load foreignKey relationships to avoid N+1 queries
+   *
+   * @param instances - Instances to load relationships for
+   * @param fieldName - Name of the foreignKey field
+   * @param relationship - Relationship metadata
+   * @private
+   */
+  async batchLoadForeignKeys(instances, fieldName, relationship) {
+    const foreignKeyValues = /* @__PURE__ */ new Set();
+    for (const instance of instances) {
+      const value = instance[fieldName];
+      if (value && typeof value === "string") {
+        foreignKeyValues.add(value);
+      }
+    }
+    if (foreignKeyValues.size === 0) return;
+    let targetCollection;
+    try {
+      targetCollection = await ObjectRegistry.getCollection(
+        relationship.targetClass,
+        this.options
+      );
+    } catch (error) {
+      logger.warn(`Could not get collection for ${relationship.targetClass}`, {
+        error
+      });
+      return;
+    }
+    const fkValueList = Array.from(foreignKeyValues);
+    const relatedObjects = [];
+    for (const idChunk of chunkArray(fkValueList, IN_LIST_CHUNK_SIZE)) {
+      const batch = await targetCollection.list({
+        where: { "id in": idChunk }
+      });
+      relatedObjects.push(...batch);
+    }
+    const relatedMap = /* @__PURE__ */ new Map();
+    for (const obj of relatedObjects) {
+      relatedMap.set(obj.id, obj);
+    }
+    for (const instance of instances) {
+      const foreignKeyValue = instance[fieldName];
+      if (foreignKeyValue && typeof foreignKeyValue === "string") {
+        const relatedObject = relatedMap.get(foreignKeyValue);
+        if (relatedObject) {
+          instance._loadedRelationships.set(fieldName, relatedObject);
+        }
+      }
+    }
+  }
+  /**
+   * Batch load oneToMany relationships
+   *
+   * @param instances - Instances to load relationships for
+   * @param fieldName - Name of the oneToMany field
+   * @param relationship - Relationship metadata
+   * @private
+   */
+  async batchLoadOneToMany(instances, fieldName, relationship) {
+    const inverseRelationships = ObjectRegistry.getInverseRelationshipsForSelf(
+      this._itemClass.name
+    );
+    const inverseCandidates = inverseRelationships.filter(
+      (r) => r.sourceClass === relationship.targetClass && r.type === "foreignKey"
+    );
+    const explicitForeignKey = relationship.options?.foreignKey;
+    const matchedForeignKey = explicitForeignKey ? inverseCandidates.find((r) => r.fieldName === explicitForeignKey) : void 0;
+    if (explicitForeignKey && !matchedForeignKey) {
+      throw new Error(
+        `oneToMany ${fieldName} specifies foreignKey '${explicitForeignKey}', but ${relationship.targetClass} has no matching inverse foreignKey. Candidates: ${inverseCandidates.map((r) => r.fieldName).join(", ") || "(none)"}`
+      );
+    }
+    const inverseForeignKey = matchedForeignKey ?? inverseCandidates.find((r) => r.targetClass === this._itemClass.name) ?? inverseCandidates[0];
+    if (!inverseForeignKey) {
+      logger.warn(
+        `Could not find inverse foreignKey for oneToMany ${fieldName}`
+      );
+      return;
+    }
+    const instanceIds = instances.map((i) => i.id).filter((id) => !!id);
+    if (instanceIds.length === 0) return;
+    let targetCollection;
+    try {
+      targetCollection = await ObjectRegistry.getCollection(
+        relationship.targetClass,
+        this.options
+      );
+    } catch (error) {
+      logger.warn(`Could not get collection for ${relationship.targetClass}`, {
+        error
+      });
+      return;
+    }
+    const relatedObjects = [];
+    for (const idChunk of chunkArray(instanceIds, IN_LIST_CHUNK_SIZE)) {
+      const batch = await targetCollection.list({
+        where: { [`${inverseForeignKey.fieldName} in`]: idChunk }
+      });
+      relatedObjects.push(...batch);
+    }
+    const relatedMap = /* @__PURE__ */ new Map();
+    for (const obj of relatedObjects) {
+      const foreignKeyValue = obj[inverseForeignKey.fieldName];
+      if (!relatedMap.has(foreignKeyValue)) {
+        relatedMap.set(foreignKeyValue, []);
+      }
+      relatedMap.get(foreignKeyValue)?.push(obj);
+    }
+    for (const instance of instances) {
+      const relatedArray = relatedMap.get(instance.id) || [];
+      instance._loadedRelationships.set(fieldName, relatedArray);
+    }
+  }
+  /**
+   * Batch-load manyToMany relationships through a junction table.
+   *
+   * Issues two queries instead of N: one against the junction table to map
+   * source IDs to target IDs, and one against the target table to hydrate
+   * the related rows. Results are grouped by source instance.
+   *
+   * @param instances - Instances whose manyToMany field should be populated
+   * @param fieldName - Name of the @manyToMany decorated field
+   * @param relationship - Relationship metadata from the registry
+   * @private
+   */
+  async batchLoadManyToMany(instances, fieldName, relationship) {
+    const instanceIds = instances.map((i) => i.id).filter((id) => !!id);
+    if (instanceIds.length === 0) return;
+    let through;
+    let sourceColumn;
+    let targetColumn;
+    let targetClassName;
+    try {
+      const sample = instances[0];
+      const join = await sample.resolveManyToManyJoin(fieldName, relationship);
+      through = join.through;
+      sourceColumn = join.sourceColumn;
+      targetColumn = join.targetColumn;
+      targetClassName = join.targetClassName;
+    } catch (error) {
+      logger.warn(
+        `Could not resolve manyToMany join for ${fieldName} on ${this._itemClass.name}`,
+        { error }
+      );
+      return;
+    }
+    for (const instance of instances) {
+      instance._loadedRelationships.set(fieldName, []);
+    }
+    const junctionRowsAll = [];
+    for (const idChunk of chunkArray(instanceIds, IN_LIST_CHUNK_SIZE)) {
+      const placeholders = idChunk.map(() => "?").join(", ");
+      const result = await this.db.query(
+        `SELECT "${sourceColumn}", "${targetColumn}" FROM "${through}" WHERE "${sourceColumn}" IN (${placeholders})`,
+        idChunk
+      );
+      junctionRowsAll.push(...result.rows);
+    }
+    if (junctionRowsAll.length === 0) return;
+    const sourceToTargets = /* @__PURE__ */ new Map();
+    const allTargetIds = /* @__PURE__ */ new Set();
+    for (const row of junctionRowsAll) {
+      const sId = row[sourceColumn];
+      const tId = row[targetColumn];
+      if (typeof sId !== "string" || typeof tId !== "string") continue;
+      allTargetIds.add(tId);
+      const list = sourceToTargets.get(sId) ?? [];
+      list.push(tId);
+      sourceToTargets.set(sId, list);
+    }
+    if (allTargetIds.size === 0) return;
+    let targetCollection;
+    try {
+      targetCollection = await ObjectRegistry.getCollection(
+        targetClassName,
+        this.options
+      );
+    } catch (error) {
+      logger.warn(
+        `Could not get collection for manyToMany target ${targetClassName}`,
+        { error }
+      );
+      return;
+    }
+    const targetIdList = Array.from(allTargetIds);
+    const targetObjects = [];
+    for (const idChunk of chunkArray(targetIdList, IN_LIST_CHUNK_SIZE)) {
+      const batch = await targetCollection.list({
+        where: { "id in": idChunk }
+      });
+      targetObjects.push(...batch);
+    }
+    const targetById = /* @__PURE__ */ new Map();
+    for (const obj of targetObjects) {
+      if (obj.id) targetById.set(obj.id, obj);
+    }
+    for (const instance of instances) {
+      const targetIds = sourceToTargets.get(instance.id) ?? [];
+      const objects = targetIds.map((id) => targetById.get(id)).filter((o) => o !== void 0);
+      instance._loadedRelationships.set(fieldName, objects);
+    }
+  }
+  /**
+   * Creates and persists a new instance of the collection's item class.
+   *
+   * Instantiates the model with the given field values, calls `initialize()`,
+   * assigns a UUID if none is provided, then calls `save()` to write the row
+   * to the database.
+   *
+   * For STI collections, pass `_meta_type` to create a specific subclass.
+   * The correct constructor is resolved via `ObjectRegistry` (polymorphic creation).
+   *
+   * @param options - Field values for the new object. Accepts any public field on
+   *   the model class plus the STI `_meta_type` discriminator.
+   * @returns The newly created and saved model instance
+   * @throws {ValidationError} If a `required` field is missing or a unique constraint is violated
+   * @throws {DatabaseError} If the write fails
+   *
+   * @example
+   * ```typescript
+   * // Regular creation
+   * const product = await products.create({ name: 'Widget', price: 9.99 });
+   * console.log(product.id); // UUID assigned during save
+   *
+   * // STI polymorphic creation
+   * const article = await contents.create({
+   *   _meta_type: '@happyvertical/smrt-content:Article',
+   *   title: 'Hello World',
+   * });
+   * ```
+   *
+   * @see {@link getOrUpsert} to avoid duplicates by finding-or-creating
+   */
+  async create(options) {
+    let itemClassName = this.getResolvedItemClassName();
+    await ObjectRegistry.ensureManifestLoaded(itemClassName);
+    itemClassName = this.getResolvedItemClassName();
+    const itemQualifiedName = this.getResolvedItemQualifiedName();
+    const tableStrategy = ObjectRegistry.getTableStrategy(itemQualifiedName);
+    if (tableStrategy === "sti" && options._meta_type) {
+      const instance2 = await this.createPolymorphic(
+        options._meta_type,
+        options
+      );
+      if (!instance2.id) {
+        instance2._id = crypto.randomUUID();
+      }
+      await instance2.save();
+      return instance2;
+    }
+    const params = {
+      ai: this.options.ai,
+      // Pass the actual database instance, not options
+      // This ensures objects share the same connection as the collection
+      // Critical for in-memory databases like DuckDB :memory: where each
+      // connection gets a separate database
+      db: this.db,
+      _skipLoad: true,
+      // Don't try to load from DB - this is a new object
+      ...options
+    };
+    const instance = new this._itemClass(params);
+    await instance.initialize();
+    if (tableStrategy === "sti") {
+      instance._meta_type = itemQualifiedName;
+    }
+    if (!instance.id) {
+      instance._id = crypto.randomUUID();
+    }
+    await instance.save();
+    return instance;
+  }
+  /**
+   * Creates an instance of the correct subclass for STI polymorphic queries
+   *
+   * @param className - Name of the class to instantiate (from _meta_type)
+   * @param options - Data to initialize the instance with
+   * @returns Promise resolving to the instance of the correct subclass
+   * @private
+   */
+  async createPolymorphic(className, options, hydrationOptions = {}) {
+    if (!className || className === null || className === void 0) {
+      const { DatabaseError } = await import("./errors.js");
+      throw DatabaseError.missingDiscriminator(
+        this._itemClass.name,
+        options?.id
+      );
+    }
+    let registeredClass = ObjectRegistry.getClassByQualifiedName(className);
+    if (!registeredClass) {
+      registeredClass = ObjectRegistry.getClass(className);
+    }
+    if (!registeredClass) {
+      await ObjectRegistry.ensureManifestLoaded(className);
+      registeredClass = ObjectRegistry.getClassByQualifiedName(className);
+      if (!registeredClass) {
+        registeredClass = ObjectRegistry.getClass(className);
+      }
+    }
+    if (!registeredClass) {
+      throw new Error(
+        `STI polymorphic query failed: Class '${className}' not found in ObjectRegistry. Ensure the class is registered with @smrt() decorator or available via an installed SMRT manifest.`
+      );
+    }
+    const params = {
+      ai: this.options.ai,
+      db: this.db,
+      _skipLoad: true,
+      ...hydrationOptions.hydrateOnly ? {
+        _reuseInitializedDb: true,
+        _deferRuntimeInitialization: true
+      } : {},
+      ...options
+    };
+    const instance = new registeredClass.constructor(params);
+    await instance.initialize();
+    instance._meta_type = registeredClass?.qualifiedName || className;
+    return instance;
+  }
+  /**
+   * Finds an existing record matching `data` or creates it if not found.
+   *
+   * Look-up priority:
+   * 1. `data.id` — query by primary key
+   * 2. `data.slug` — query by slug + context
+   * 3. Fallback — query by the full `data` object as a WHERE clause
+   *
+   * If a matching record is found, it is updated with any changed fields from
+   * `data` (diffed against the existing record) and saved. If no match is
+   * found, `defaults` are merged with `data` and a new record is created.
+   *
+   * @param data - The field values to find or upsert
+   * @param defaults - Extra default values applied only when creating a new record
+   * @returns The existing (possibly updated) or newly created object instance
+   *
+   * @example
+   * ```typescript
+   * // Find-or-create a tag by slug
+   * const tag = await tags.getOrUpsert({ slug: 'javascript', name: 'JavaScript' });
+   *
+   * // With defaults applied only on creation
+   * const user = await users.getOrUpsert(
+   *   { email: 'alice@example.com' },
+   *   { role: 'member', active: true },
+   * );
+   * ```
+   *
+   * @see {@link create} for always-insert semantics
+   * @see {@link get} for read-only lookup
+   */
+  async getOrUpsert(data, defaults = {}) {
+    const logicalData = this.normalizeLogicalData(data);
+    const logicalDefaults = this.normalizeLogicalData(defaults);
+    let where = {};
+    const diffData = { ...logicalData };
+    if (logicalData.id) {
+      where = { id: logicalData.id };
+      delete diffData.id;
+      delete diffData.slug;
+      delete diffData.context;
+    } else if (logicalData.slug) {
+      where = { slug: logicalData.slug, context: logicalData.context || "" };
+      delete diffData.slug;
+      delete diffData.context;
+    } else {
+      where = logicalData;
+    }
+    const existing = await this.get(where, { cache: false });
+    if (existing) {
+      const diff = this.getDiffSync(existing, diffData);
+      if (diff) {
+        Object.assign(existing, diff);
+        await existing.save();
+      }
+      return existing;
+    }
+    const createData = {
+      ...logicalDefaults,
+      ...logicalData
+    };
+    return await this.create(createData);
+  }
+  /**
+   * Gets differences between an existing object and new data
+   *
+   * @param existing - Existing object
+   * @param data - New data
+   * @returns Object containing only the changed fields
+   */
+  async getDiff(existing, data) {
+    return this.getDiffSync(existing, data);
+  }
+  getDiffSync(existing, data) {
+    const fields = this.getFieldsSync();
+    const validKeys = /* @__PURE__ */ new Set([
+      ...Object.keys(fields),
+      "id",
+      "slug",
+      "context"
+    ]);
+    const diff = Object.keys(data).reduce(
+      (acc, key) => {
+        if (validKeys.has(key) && !this.areEquivalentValues(existing[key], data[key])) {
+          acc[key] = data[key];
+        }
+        return acc;
+      },
+      {}
+    );
+    return Object.keys(diff).length > 0 ? diff : null;
+  }
+  /**
+   * Gets field definitions for the collection's item class
+   *
+   * @returns Object containing field definitions
+   */
+  async getFields() {
+    return await fieldsFromClass(this._itemClass);
+  }
+  /**
+   * Normalize user input into the model's logical field names before diffing or creation.
+   *
+   * Accepts both camelCase and snake_case keys while preserving framework meta fields.
+   */
+  normalizeLogicalData(data) {
+    const fields = this.getFieldsSync();
+    const normalized = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key.startsWith("_")) {
+        normalized[key] = value;
+        continue;
+      }
+      const camelKey = key.includes("_") ? toCamelCase(key) : key;
+      const snakeKey = key.includes("_") ? key : toSnakeCase(key);
+      const outputKey = key in fields ? key : camelKey in fields ? camelKey : snakeKey in fields ? snakeKey : key;
+      normalized[outputKey] = value;
+    }
+    return normalized;
+  }
+  /**
+   * Preserve persisted core timestamp fields during lightweight hydration.
+   */
+  withHydratedCoreFields(data) {
+    const hydratedData = { ...data };
+    if (hydratedData.createdAt !== void 0 && hydratedData.created_at === void 0) {
+      hydratedData.created_at = hydratedData.createdAt;
+    }
+    if (hydratedData.updatedAt !== void 0 && hydratedData.updated_at === void 0) {
+      hydratedData.updated_at = hydratedData.updatedAt;
+    }
+    return hydratedData;
+  }
+  /**
+   * Treat date-equivalent values as unchanged even if their runtime types differ.
+   */
+  areEquivalentValues(existingValue, nextValue) {
+    if (existingValue instanceof Date || nextValue instanceof Date) {
+      const existingTime = this.toComparableTime(existingValue);
+      const nextTime = this.toComparableTime(nextValue);
+      if (existingTime !== null && nextTime !== null) {
+        return existingTime === nextTime;
+      }
+    }
+    return existingValue === nextValue;
+  }
+  /**
+   * Convert supported date inputs into comparable timestamps.
+   */
+  toComparableTime(value) {
+    if (value instanceof Date) {
+      const timestamp = value.getTime();
+      return Number.isNaN(timestamp) ? null : timestamp;
+    }
+    if (typeof value === "string" && value.trim()) {
+      const parsedDate = new Date(value);
+      const timestamp = parsedDate.getTime();
+      return Number.isNaN(timestamp) ? null : timestamp;
+    }
+    return null;
+  }
+  /**
+   * Gets field definitions synchronously from cache.
+   *
+   * This method provides sync access to fields for use in query methods,
+   * avoiding the async overhead of getFields() on every query.
+   * Fields are cached during create() initialization.
+   *
+   * @returns Map containing field definitions
+   * @private
+   */
+  getFieldsSync() {
+    if (this._cachedFields) {
+      return this._cachedFields;
+    }
+    const className = this.getResolvedItemClassName();
+    const fields = ObjectRegistry.getFields(className);
+    return Object.fromEntries(fields);
+  }
+  /**
+   * Generates database schema for the collection's item class
+   *
+   * Leverages ObjectRegistry's cached schema for instant retrieval.
+   *
+   * @returns Schema object for database setup
+   */
+  async generateSchema() {
+    const { generateSchema } = await import("./schema/utils.js");
+    return await generateSchema(this._itemClass);
+  }
+  /**
+   * Gets the database table name for this collection
+   */
+  get tableName() {
+    if (!this._tableName) {
+      const className = this.getResolvedItemClassName();
+      const qualifiedName = this.getResolvedItemQualifiedName();
+      const tableStrategy = ObjectRegistry.getTableStrategy(qualifiedName);
+      const fallbackTableName = this._itemClass.SMRT_TABLE_NAME || classnameToTablename(className);
+      if (tableStrategy === "sti") {
+        const stiBase = ObjectRegistry.getSTIBase(qualifiedName);
+        if (stiBase) {
+          const baseSchema = ObjectRegistry.getSchema(stiBase);
+          if (baseSchema?.tableName) {
+            this._tableName = baseSchema.tableName;
+          } else {
+            const ownSchema = ObjectRegistry.getSchema(className);
+            this._tableName = ownSchema?.tableName || fallbackTableName;
+          }
+        } else {
+          const ownSchema = ObjectRegistry.getSchema(className);
+          this._tableName = ownSchema?.tableName || fallbackTableName;
+        }
+      } else {
+        const ownSchema = ObjectRegistry.getSchema(className);
+        this._tableName = ownSchema?.tableName || fallbackTableName;
+      }
+    }
+    return this._tableName;
+  }
+  /**
+   * Generates a table name from the collection class name
+   *
+   * @returns Generated table name
+   */
+  generateTableName() {
+    const tableName = this._className.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase().replace(/([^s])$/, "$1s").replace(/y$/, "ies");
+    return tableName;
+  }
+  /**
+   * Deletes a record from the collection by ID
+   *
+   * Loads the object and calls its delete() method, ensuring all interceptors
+   * and lifecycle hooks (beforeDelete/afterDelete) are executed correctly.
+   *
+   * @param id - The ID of the record to delete
+   * @returns Promise resolving to true if deleted, false if not found
+   *
+   * @example
+   * ```typescript
+   * const success = await collection.delete('some-uuid');
+   * if (success) {
+   *   console.log('Record deleted');
+   * }
+   * ```
+   */
+  async delete(id) {
+    await ObjectRegistry.ensureManifestLoaded(this.getResolvedItemClassName());
+    const instance = await this.get(id, { cache: false });
+    if (!instance) {
+      return false;
+    }
+    await instance.delete();
+    return true;
+  }
+  /**
+   * Returns the number of records matching the given filter conditions.
+   *
+   * Executes a `SELECT COUNT(*)` query with the same WHERE conversion as
+   * `list()` (camelCase field names, operator suffixes, STI auto-filtering).
+   * `limit`, `offset`, and `orderBy` are not applicable and are ignored.
+   *
+   * Note: `count()` is never served from the read cache (issue #1498) — only
+   * `list()`/`get()` are. On a page that caches `list()`, a `count()` issued
+   * in the same request reflects the live database and may briefly diverge
+   * from the cached rows within the TTL window.
+   *
+   * @param options.where - Filter conditions (same syntax as `list()`)
+   * @returns Total count of matching records as an integer
+   *
+   * @example
+   * ```typescript
+   * const total = await products.count();
+   * const activeCount = await products.count({ where: { status: 'active' } });
+   * const expensiveCount = await products.count({ where: { 'price >': 100 } });
+   * ```
+   *
+   * @see {@link list} for retrieving the actual records
+   */
+  async count(options = {}) {
+    await this.ensureStorageReady();
+    const itemQualifiedName = this.getResolvedItemQualifiedName();
+    const itemClassName = this.getResolvedItemClassName();
+    const interceptorContext = createInterceptorContext(
+      itemClassName,
+      "list",
+      this.constructor.name
+    );
+    const interceptedOptions = await GlobalInterceptors.executeBeforeList(
+      itemClassName,
+      options,
+      interceptorContext
+    ) ?? options ?? {};
+    let { where } = interceptedOptions;
+    const tableStrategy = ObjectRegistry.getTableStrategy(itemQualifiedName);
+    const isSTI = tableStrategy === "sti";
+    if (isSTI) {
+      const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+      if (stiBase && stiBase !== itemQualifiedName) {
+        where = {
+          _meta_type: itemQualifiedName,
+          ...where || {}
+        };
+      }
+    }
+    where = resolveMetaTypeInWhere(where);
+    const { sql: whereSql, values: whereValues } = buildWhere(
+      this.convertWhereKeys(where || {})
+    );
+    const result = await this.db.query(
+      `SELECT COUNT(*) as count FROM ${this.tableName} ${whereSql}`,
+      ...whereValues
+    );
+    return Number.parseInt(result.rows[0].count, 10);
+  }
+  /**
+   * Execute a raw SQL query and hydrate results as collection item instances
+   *
+   * Provides full SQL power for complex queries (JOINs, CTEs, NOT EXISTS, etc.)
+   * while still returning properly hydrated SMRT objects.
+   *
+   * @param sql - Raw SQL query string (should select from this.tableName)
+   * @param params - Query parameters for prepared statement
+   * @returns Promise resolving to array of hydrated model instances
+   *
+   * @example
+   * ```typescript
+   * // Find meetings without corresponding recaps (NOT EXISTS pattern)
+   * const meetings = await meetingCollection.query(`
+   *   SELECT m.* FROM meetings m
+   *   WHERE m.start_date < datetime('now')
+   *   AND NOT EXISTS (
+   *     SELECT 1 FROM contents c
+   *     WHERE c.meeting_id = m.id
+   *     AND c._meta_type = 'MeetingRecap'
+   *   )
+   *   ORDER BY m.start_date DESC
+   *   LIMIT ?
+   * `, [10]);
+   *
+   * // Complex JOIN query
+   * const products = await productCollection.query(`
+   *   SELECT p.* FROM products p
+   *   INNER JOIN categories c ON p.category_id = c.id
+   *   WHERE c.name = ? AND p.price > ?
+   *   ORDER BY p.price ASC
+   * `, ['Electronics', 100]);
+   * ```
+   */
+  async query(sql, params = [], options = {}) {
+    await this.ensureStorageReady();
+    const interceptorContext = createInterceptorContext(
+      this._itemClass.name,
+      "query",
+      this.constructor.name
+    );
+    const interceptedQuery = await GlobalInterceptors.executeBeforeQuery(
+      this._itemClass.name,
+      { sql, params, allowRawOnTenantScoped: options.allowRawOnTenantScoped },
+      interceptorContext
+    );
+    const result = await this.db.query(
+      interceptedQuery.sql,
+      ...interceptedQuery.params
+    );
+    if (/\b(?:insert|update|delete|merge|truncate|replace)\b/i.test(
+      interceptedQuery.sql
+    )) {
+      invalidateCollectionCache(resolveDbCacheKey(this.db), this.tableName);
+    }
+    const fields = this.getFieldsSync();
+    const tableStrategy = ObjectRegistry.getTableStrategy(
+      this.getResolvedItemQualifiedName()
+    );
+    const isSTI = tableStrategy === "sti";
+    const instances = await Promise.all(
+      result.rows.map((row) => this.hydrateResultRow(row, fields, isSTI))
+    );
+    return await GlobalInterceptors.executeAfterQuery(
+      this._itemClass.name,
+      instances,
+      interceptorContext
+    );
+  }
+  async hydrateResultRow(row, fields, isSTI) {
+    const formattedData = this.withHydratedCoreFields(
+      formatDataJs(row, fields)
+    );
+    if (isSTI && formattedData._meta_type) {
+      const polymorphicInstance = await this.createPolymorphic(
+        formattedData._meta_type,
+        formattedData,
+        { hydrateOnly: true }
+      );
+      polymorphicInstance.markAsPersisted();
+      return polymorphicInstance;
+    }
+    const instanceParams = {
+      ai: this.options.ai,
+      db: this.db,
+      _skipLoad: true,
+      _reuseInitializedDb: true,
+      _deferRuntimeInitialization: true,
+      ...formattedData
+    };
+    const instance = new this._itemClass(instanceParams);
+    await instance.initialize();
+    if (isSTI) {
+      const registeredClass = ObjectRegistry.getClass(this._itemClass.name);
+      instance._meta_type = registeredClass?.qualifiedName || this._itemClass.name;
+    }
+    instance.markAsPersisted();
+    return instance;
+  }
+  /**
+   * Remember collection-level context
+   *
+   * Stores context applicable to all instances of this collection type.
+   * Use for patterns that apply to the entire collection (e.g., default parsing strategies).
+   *
+   * @param options - Context options
+   * @returns Promise that resolves when context is stored
+   * @example
+   * ```typescript
+   * // Remember a default parsing strategy for all documents
+   * await documentCollection.remember({
+   *   scope: 'parser/default',
+   *   key: 'selector',
+   *   value: { pattern: '.content article' },
+   *   confidence: 0.8
+   * });
+   *
+   * // Update an existing context entry by specifying id
+   * await documentCollection.remember({
+   *   id: 'existing-context-id',
+   *   scope: 'parser/default',
+   *   key: 'selector',
+   *   value: { pattern: '.content main article' },
+   *   confidence: 0.85
+   * });
+   * ```
+   */
+  async remember(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    const id = options.id || crypto.randomUUID();
+    const now = /* @__PURE__ */ new Date();
+    await this.systemDb.upsert(
+      "_smrt_contexts",
+      // UNIQUE constraint: (owner_class, owner_id, scope, key, version)
+      ["owner_class", "owner_id", "scope", "key", "version"],
+      {
+        id,
+        owner_class: this._itemClass.name,
+        owner_id: "__collection__",
+        scope: options.scope,
+        key: options.key,
+        value: JSON.stringify(options.value),
+        metadata: options.metadata ? JSON.stringify(options.metadata) : null,
+        version: options.version ?? 1,
+        confidence: options.confidence ?? 1,
+        success_count: 0,
+        failure_count: 0,
+        created_at: now,
+        updated_at: now,
+        last_used_at: now,
+        expires_at: options.expiresAt ?? null
+      }
+    );
+  }
+  /**
+   * Recall collection-level context
+   *
+   * Retrieves context that applies to all instances of this collection.
+   *
+   * @param options - Recall options
+   * @returns Promise resolving to the context value or null if not found
+   * @example
+   * ```typescript
+   * // Recall default parsing strategy
+   * const strategy = await documentCollection.recall({
+   *   scope: 'parser/default',
+   *   key: 'selector',
+   *   minConfidence: 0.5
+   * });
+   * ```
+   */
+  async recall(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    let result;
+    if (options.minConfidence !== void 0) {
+      result = await this.systemDb.single`
+        SELECT value, confidence
+        FROM _smrt_contexts
+        WHERE owner_class = ${this._itemClass.name}
+          AND owner_id = ${"__collection__"}
+          AND scope = ${options.scope}
+          AND key = ${options.key}
+          AND confidence >= ${options.minConfidence}
+        ORDER BY confidence DESC, version DESC
+        LIMIT 1
+      `;
+    } else {
+      result = await this.systemDb.single`
+        SELECT value, confidence
+        FROM _smrt_contexts
+        WHERE owner_class = ${this._itemClass.name}
+          AND owner_id = ${"__collection__"}
+          AND scope = ${options.scope}
+          AND key = ${options.key}
+        ORDER BY confidence DESC, version DESC
+        LIMIT 1
+      `;
+    }
+    if (result) {
+      try {
+        return JSON.parse(result.value);
+      } catch (error) {
+        logger.warn("Skipping corrupted _smrt_contexts value in recall()", {
+          ownerClass: this._itemClass.name,
+          scope: options.scope,
+          key: options.key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    if (options.includeAncestors) {
+      const scopeParts = options.scope.split("/");
+      while (scopeParts.length > 0) {
+        scopeParts.pop();
+        const parentScope = scopeParts.join("/") || "global";
+        const parentResult = await this.recall({
+          ...options,
+          scope: parentScope,
+          includeAncestors: false
+        });
+        if (parentResult) return parentResult;
+      }
+    }
+    return null;
+  }
+  /**
+   * Recall all collection-level context in a scope
+   *
+   * Returns a Map of key -> value for all collection contexts matching the criteria.
+   *
+   * @param options - Recall options
+   * @returns Promise resolving to Map of key -> value pairs
+   * @example
+   * ```typescript
+   * // Get all default strategies
+   * const strategies = await documentCollection.recallAll({
+   *   scope: 'parser/default',
+   *   minConfidence: 0.5
+   * });
+   * ```
+   */
+  async recallAll(options = {}) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    const results = /* @__PURE__ */ new Map();
+    let query = `
+      SELECT key, value, confidence
+      FROM _smrt_contexts
+      WHERE owner_class = ? AND owner_id = ?
+    `;
+    const params = [this._itemClass.name, "__collection__"];
+    if (options.scope) {
+      if (options.includeDescendants) {
+        query += ` AND (scope = ? OR scope LIKE ?)`;
+        params.push(options.scope, `${options.scope}/%`);
+      } else {
+        query += ` AND scope = ?`;
+        params.push(options.scope);
+      }
+    }
+    if (options.minConfidence !== void 0) {
+      query += ` AND confidence >= ?`;
+      params.push(options.minConfidence);
+    }
+    query += ` ORDER BY confidence DESC`;
+    const { rows } = await this.systemDb.query(query, ...params);
+    for (const row of rows) {
+      try {
+        results.set(row.key, JSON.parse(row.value));
+      } catch (error) {
+        logger.warn("Skipping corrupted _smrt_contexts value in recallAll()", {
+          ownerClass: this._itemClass.name,
+          scope: options.scope,
+          key: row.key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Forget collection-level context
+   *
+   * Deletes collection context by scope and key.
+   *
+   * @param options - Context identification
+   * @returns Promise that resolves when context is deleted
+   * @example
+   * ```typescript
+   * // Remove a default strategy
+   * await documentCollection.forget({
+   *   scope: 'parser/default',
+   *   key: 'selector'
+   * });
+   * ```
+   */
+  async forget(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    await this.systemDb.query(
+      `DELETE FROM _smrt_contexts
+       WHERE owner_class = ? AND owner_id = ? AND scope = ? AND key = ?`,
+      this._itemClass.name,
+      "__collection__",
+      options.scope,
+      options.key
+    );
+  }
+  /**
+   * Forget all collection-level context in a scope
+   *
+   * Deletes all collection contexts matching the scope pattern.
+   *
+   * @param options - Scope options
+   * @returns Promise resolving to number of contexts deleted
+   * @example
+   * ```typescript
+   * // Clear all default strategies
+   * const count = await documentCollection.forgetScope({
+   *   scope: 'parser/default',
+   *   includeDescendants: true
+   * });
+   * ```
+   */
+  async forgetScope(options) {
+    if (!this.systemDb) {
+      throw new Error("Database not initialized. Call initialize() first.");
+    }
+    let query = `
+      DELETE FROM _smrt_contexts
+      WHERE owner_class = ? AND owner_id = ?
+    `;
+    const params = [this._itemClass.name, "__collection__"];
+    if (options.includeDescendants) {
+      query += ` AND (scope = ? OR scope LIKE ?)`;
+      params.push(options.scope, `${options.scope}/%`);
+    } else {
+      query += ` AND scope = ?`;
+      params.push(options.scope);
+    }
+    const { rowCount } = await this.systemDb.query(query, ...params);
+    return rowCount || 0;
+  }
+  // ============================================================================
+  // Semantic Search Methods
+  // ============================================================================
+  /**
+   * Semantic search by text query
+   *
+   * Generates an embedding for the query text and finds similar objects
+   * based on cosine similarity of stored embeddings.
+   *
+   * @param query - Text to search for
+   * @param options - Search options
+   * @param options.field - Specific field to search (defaults to first embedding field)
+   * @param options.limit - Maximum results to return (default: 10)
+   * @param options.minSimilarity - Minimum similarity threshold 0-1 (default: 0)
+   * @param options.where - Additional WHERE filters to apply
+   * @returns Promise resolving to array of objects with _similarity score
+   *
+   * @example
+   * ```typescript
+   * const results = await articles.semanticSearch('machine learning trends', {
+   *   limit: 10,
+   *   minSimilarity: 0.7
+   * });
+   *
+   * for (const article of results) {
+   *   console.log(`${article.title} (similarity: ${article._similarity})`);
+   * }
+   * ```
+   */
+  async semanticSearch(query, options = {}) {
+    const { field, limit = 10, minSimilarity = 0, where } = options;
+    const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(
+      this._itemClass.name
+    );
+    if (!embeddingConfig) {
+      throw new Error(
+        `No embedding configuration found for ${this._itemClass.name}. Add embeddings config to @smrt() decorator.`
+      );
+    }
+    const searchField = field || embeddingConfig.fields[0];
+    if (!embeddingConfig.fields.includes(searchField)) {
+      throw new Error(
+        `Field '${searchField}' is not configured for embeddings on ${this._itemClass.name}. Available fields: ${embeddingConfig.fields.join(", ")}`
+      );
+    }
+    const provider = new EmbeddingProvider(
+      {
+        dimensions: embeddingConfig.dimensions,
+        provider: embeddingConfig.provider,
+        localModel: embeddingConfig.localModel,
+        aiModel: embeddingConfig.aiModel,
+        fallbackToAI: embeddingConfig.fallbackToAI
+      },
+      this.ai
+    );
+    const [queryEmbedding] = await provider.embed(query);
+    return this.findSimilarToEmbedding(queryEmbedding, {
+      field: searchField,
+      limit,
+      minSimilarity,
+      where
+    });
+  }
+  /**
+   * Find objects similar to a given object
+   *
+   * Uses stored embeddings to find objects most similar to the provided object.
+   *
+   * @param object - Object to find similar items for (or object ID)
+   * @param options - Search options
+   * @param options.field - Specific field to compare (defaults to first embedding field)
+   * @param options.limit - Maximum results to return (default: 5)
+   * @param options.excludeSelf - Whether to exclude the source object (default: true)
+   * @returns Promise resolving to array of similar objects with _similarity score
+   *
+   * @example
+   * ```typescript
+   * const article = await articles.get('some-article-id');
+   * const similar = await articles.findSimilar(article, {
+   *   limit: 5,
+   *   excludeSelf: true
+   * });
+   * ```
+   */
+  async findSimilar(object, options = {}) {
+    const { field, limit = 5, excludeSelf = true } = options;
+    let sourceObject;
+    if (typeof object === "string") {
+      const found = await this.get(object);
+      if (!found) {
+        throw new Error(`Object not found: ${object}`);
+      }
+      sourceObject = found;
+    } else {
+      sourceObject = object;
+    }
+    const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(
+      this._itemClass.name
+    );
+    if (!embeddingConfig) {
+      throw new Error(
+        `No embedding configuration found for ${this._itemClass.name}.`
+      );
+    }
+    const searchField = field || embeddingConfig.fields[0];
+    const provider = new EmbeddingProvider(
+      {
+        dimensions: embeddingConfig.dimensions,
+        provider: embeddingConfig.provider,
+        localModel: embeddingConfig.localModel,
+        aiModel: embeddingConfig.aiModel,
+        fallbackToAI: embeddingConfig.fallbackToAI
+      },
+      this.ai
+    );
+    const model = provider.getModelName();
+    const storedEmbedding = await EmbeddingStorage.get(
+      this.systemDb,
+      this._itemClass.name,
+      sourceObject.id,
+      searchField,
+      model
+    );
+    if (!storedEmbedding) {
+      throw new Error(
+        `No embedding found for object ${sourceObject.id} field '${searchField}'. Generate embeddings first with object.generateEmbeddings().`
+      );
+    }
+    const where = excludeSelf ? { "id !=": sourceObject.id } : void 0;
+    return this.findSimilarToEmbedding(storedEmbedding.embedding, {
+      field: searchField,
+      limit,
+      minSimilarity: 0,
+      where
+    });
+  }
+  /**
+   * Find objects similar to a raw embedding vector
+   *
+   * Low-level method for finding objects by embedding similarity.
+   *
+   * @param embedding - Embedding vector to compare against
+   * @param options - Search options
+   * @param options.field - Field name to search (defaults to first embedding field)
+   * @param options.limit - Maximum results to return (default: 10)
+   * @param options.minSimilarity - Minimum similarity threshold 0-1 (default: 0)
+   * @param options.where - Additional WHERE filters to apply
+   * @returns Promise resolving to array of objects with _similarity score
+   *
+   * @example
+   * ```typescript
+   * // Using a pre-computed embedding
+   * const results = await articles.findSimilarToEmbedding(myEmbedding, {
+   *   limit: 10,
+   *   minSimilarity: 0.5
+   * });
+   * ```
+   */
+  async findSimilarToEmbedding(embedding, options = {}) {
+    const { field, limit = 10, minSimilarity = 0, where } = options;
+    const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(
+      this._itemClass.name
+    );
+    if (!embeddingConfig) {
+      throw new Error(
+        `No embedding configuration found for ${this._itemClass.name}.`
+      );
+    }
+    const searchField = field || embeddingConfig.fields[0];
+    const provider = new EmbeddingProvider(
+      {
+        dimensions: embeddingConfig.dimensions,
+        provider: embeddingConfig.provider,
+        localModel: embeddingConfig.localModel,
+        aiModel: embeddingConfig.aiModel,
+        fallbackToAI: embeddingConfig.fallbackToAI
+      },
+      this.ai
+    );
+    const model = provider.getModelName();
+    const projectConfig = ObjectRegistry.getProjectEmbeddingConfig();
+    const storage = projectConfig?.storage || "json";
+    const vector = storage === "native" ? this.systemDb.vector : void 0;
+    const scored = await EmbeddingStorage.searchSimilar(
+      this.systemDb,
+      this._itemClass.name,
+      embedding,
+      {
+        field: searchField,
+        model,
+        limit,
+        minSimilarity
+      },
+      vector
+    );
+    if (scored.length === 0) {
+      return [];
+    }
+    const objectIds = scored.map((s) => s.objectId);
+    const similarityMap = new Map(
+      scored.map((s) => [s.objectId, s.similarity])
+    );
+    const whereClause = where ? { "id in": objectIds, ...where } : { "id in": objectIds };
+    const objects = await this.list({
+      where: whereClause
+    });
+    const results = objects.map((obj) => {
+      obj._similarity = similarityMap.get(obj.id) || 0;
+      return obj;
+    });
+    results.sort((a, b) => b._similarity - a._similarity);
+    return results;
+  }
+  /**
+   * Generate missing embeddings for all objects in the collection
+   *
+   * Batch generates embeddings for objects that don't have them yet
+   * or have stale embeddings.
+   *
+   * @param options - Generation options
+   * @param options.batchSize - Number of objects to process at once (default: 50)
+   * @param options.onProgress - Progress callback
+   * @returns Promise resolving to generation statistics
+   *
+   * @example
+   * ```typescript
+   * const stats = await articles.generateMissingEmbeddings({
+   *   batchSize: 100,
+   *   onProgress: ({ completed, total }) => {
+   *     console.log(`Progress: ${completed}/${total}`);
+   *   }
+   * });
+   *
+   * console.log(`Generated: ${stats.generated}, Skipped: ${stats.skipped}`);
+   * ```
+   */
+  async generateMissingEmbeddings(options = {}) {
+    const { batchSize = 50, onProgress } = options;
+    const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(
+      this._itemClass.name
+    );
+    if (!embeddingConfig) {
+      throw new Error(
+        `No embedding configuration found for ${this._itemClass.name}.`
+      );
+    }
+    const total = await this.count({});
+    let completed = 0;
+    let generated = 0;
+    let skipped = 0;
+    let offset = 0;
+    while (offset < total) {
+      const batch = await this.list({ limit: batchSize, offset });
+      for (const obj of batch) {
+        try {
+          const hasStale = await obj.hasStaleEmbeddings();
+          if (hasStale) {
+            await obj.generateEmbeddings();
+            generated++;
+          } else {
+            skipped++;
+          }
+        } catch (error) {
+          logger.warn(`Failed to generate embeddings for ${obj.id}`, {
+            error: error instanceof Error ? error.message : error
+          });
+          skipped++;
+        }
+        completed++;
+        if (onProgress) {
+          onProgress({ completed, total });
+        }
+      }
+      offset += batchSize;
+    }
+    return { generated, skipped };
+  }
+}
+export {
+  SmrtCollection
+};
+//# sourceMappingURL=collection.js.map