js-bao 0.2.10 → 0.2.12

package/dist/cloudflare-do.cjs

@@ -0,0 +1,3637 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cloudflare-do.ts
+var cloudflare_do_exports = {};
+__export(cloudflare_do_exports, {
+  DurableObjectEngine: () => DurableObjectEngine,
+  JsonQueryTranslator: () => JsonQueryTranslator,
+  JsonSchemaDDL: () => JsonSchemaDDL,
+  createDatabaseDO: () => createDatabaseDO,
+  createDocumentDO: () => createDocumentDO,
+  handleRequest: () => handleRequest
+});
+module.exports = __toCommonJS(cloudflare_do_exports);
+
+// src/engines/DatabaseEngine.ts
+var DatabaseEngine = class {
+  createTable(_modelName, _schema, _options) {
+    throw new Error("Method not implemented.");
+  }
+  createStringSetJunctionTable(_modelName, _fieldName) {
+    throw new Error("Method not implemented.");
+  }
+  insertStringSetValues(_modelName, _fieldName, _recordId, _values) {
+    throw new Error("Method not implemented.");
+  }
+  removeStringSetValues(_modelName, _fieldName, _recordId, _values) {
+    throw new Error("Method not implemented.");
+  }
+  insert(_modelName, _data) {
+    throw new Error("Method not implemented.");
+  }
+  delete(_modelName, _id) {
+    throw new Error("Method not implemented.");
+  }
+  /**
+   * Deletes all records for a specific document from the given model table.
+   * This is used when disconnecting a document to remove all its data.
+   * @param modelName The name of the model/table
+   * @param docId The document ID to filter by
+   */
+  deleteByDocumentId(_modelName, _docId) {
+    throw new Error("Method not implemented.");
+  }
+  getTableName(_modelName) {
+    throw new Error("Method not implemented.");
+  }
+  // Transaction support
+  async withTransaction(_callback) {
+    throw new Error("Method not implemented.");
+  }
+};
+
+// src/utils/sql.ts
+var IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidIdentifier(name) {
+  return IDENTIFIER_PATTERN.test(name);
+}
+function assertValidIdentifier(name, context) {
+  if (!isValidIdentifier(name)) {
+    throw new Error(
+      `${context}: Identifier "${name}" must match ${IDENTIFIER_PATTERN.source}`
+    );
+  }
+}
+function quoteIdentifier(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+// src/schema/JsonSchemaDDL.ts
+var JsonSchemaDDL = class {
+  /**
+   * Generate CREATE TABLE statement for the records table
+   */
+  static createRecordsTable(options) {
+    if (options.includeDocIdColumn) {
+      return `
+CREATE TABLE IF NOT EXISTS records (
+  _id TEXT NOT NULL,
+  _type TEXT NOT NULL,
+  _data TEXT NOT NULL,
+  _meta_doc_id TEXT,
+  _meta_permission_hint TEXT,
+  PRIMARY KEY (_type, _id)
+)`.trim();
+    } else {
+      return `
+CREATE TABLE IF NOT EXISTS records (
+  _id TEXT NOT NULL,
+  _type TEXT NOT NULL,
+  _data TEXT NOT NULL,
+  PRIMARY KEY (_type, _id)
+)`.trim();
+    }
+  }
+  /**
+   * Generate CREATE TABLE statement for the stringset_index table
+   */
+  static createStringSetIndexTable(options) {
+    if (options.includeDocIdColumn) {
+      return `
+CREATE TABLE IF NOT EXISTS stringset_index (
+  _record_id TEXT NOT NULL,
+  _type TEXT NOT NULL,
+  field TEXT NOT NULL,
+  value TEXT NOT NULL,
+  _meta_doc_id TEXT,
+  UNIQUE(_type, field, _record_id, value)
+)`.trim();
+    } else {
+      return `
+CREATE TABLE IF NOT EXISTS stringset_index (
+  _record_id TEXT NOT NULL,
+  _type TEXT NOT NULL,
+  field TEXT NOT NULL,
+  value TEXT NOT NULL,
+  UNIQUE(_type, field, _record_id, value)
+)`.trim();
+    }
+  }
+  /**
+   * Generate base indexes for the schema
+   */
+  static createBaseIndexes(options) {
+    const indexes = [
+      // Index on _type for filtering by model
+      "CREATE INDEX IF NOT EXISTS idx_records_type ON records(_type)",
+      // StringSet indexes for efficient lookups
+      "CREATE INDEX IF NOT EXISTS idx_ss_type_field_value ON stringset_index(_type, field, value)",
+      "CREATE INDEX IF NOT EXISTS idx_ss_type_field_record ON stringset_index(_type, field, _record_id)"
+    ];
+    if (options.includeDocIdColumn) {
+      indexes.push(
+        "CREATE INDEX IF NOT EXISTS idx_records_doc ON records(_meta_doc_id)",
+        "CREATE INDEX IF NOT EXISTS idx_ss_doc ON stringset_index(_meta_doc_id)"
+      );
+    }
+    return indexes;
+  }
+  /**
+   * Generate CREATE INDEX statement for a model field
+   * Uses json_extract for JSON schema
+   */
+  static createFieldIndex(modelName, fieldName) {
+    assertValidIdentifier(modelName, "createFieldIndex modelName");
+    assertValidIdentifier(fieldName, "createFieldIndex fieldName");
+    const indexName = `idx_records_${modelName.toLowerCase()}_${fieldName.toLowerCase()}`;
+    return `CREATE INDEX IF NOT EXISTS ${indexName} ON records(json_extract(_data, '$.${fieldName}')) WHERE _type = '${modelName}'`;
+  }
+  /**
+   * Generate DROP INDEX statement for a model field
+   */
+  static dropFieldIndex(modelName, fieldName) {
+    assertValidIdentifier(modelName, "dropFieldIndex modelName");
+    assertValidIdentifier(fieldName, "dropFieldIndex fieldName");
+    const indexName = `idx_records_${modelName.toLowerCase()}_${fieldName.toLowerCase()}`;
+    return `DROP INDEX IF EXISTS ${indexName}`;
+  }
+  /**
+   * Generate CREATE TABLE statement for the _indexes table.
+   * Stores per-field index registrations (one row per index).
+   */
+  static createIndexesTable() {
+    return `
+CREATE TABLE IF NOT EXISTS _indexes (
+  model_name TEXT NOT NULL,
+  field_name TEXT NOT NULL,
+  field_type TEXT NOT NULL,
+  is_unique INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (model_name, field_name)
+)`.trim();
+  }
+  /**
+   * Generate CREATE TABLE statement for the _unique_constraints table.
+   * Stores composite (multi-field) unique constraints.
+   */
+  static createUniqueConstraintsTable() {
+    return `
+CREATE TABLE IF NOT EXISTS _unique_constraints (
+  model_name TEXT NOT NULL,
+  constraint_name TEXT NOT NULL,
+  fields_json TEXT NOT NULL,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (model_name, constraint_name)
+)`.trim();
+  }
+  /**
+   * Generate CREATE TABLE statement for the _model_fields table.
+   * Tracks field names and inferred types as records are written.
+   */
+  static createModelFieldsTable() {
+    return `
+CREATE TABLE IF NOT EXISTS _model_fields (
+  model_name TEXT NOT NULL,
+  field_name TEXT NOT NULL,
+  inferred_type TEXT NOT NULL,
+  first_seen_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (model_name, field_name)
+)`.trim();
+  }
+  /**
+   * Generate all DDL statements needed to initialize the schema
+   */
+  static getAllDDL(options) {
+    return [
+      this.createRecordsTable(options),
+      this.createStringSetIndexTable(options),
+      this.createIndexesTable(),
+      this.createUniqueConstraintsTable(),
+      this.createModelFieldsTable(),
+      ...this.createBaseIndexes(options)
+    ];
+  }
+  /**
+   * Generate INSERT statement for a record
+   */
+  static buildInsertSQL(options) {
+    if (options.includeDocIdColumn) {
+      return `
+INSERT OR REPLACE INTO records (_id, _type, _data, _meta_doc_id, _meta_permission_hint)
+VALUES (?, ?, ?, ?, ?)`.trim();
+    } else {
+      return `
+INSERT OR REPLACE INTO records (_id, _type, _data)
+VALUES (?, ?, ?)`.trim();
+    }
+  }
+  /**
+   * Generate DELETE statement for a record by id and type
+   */
+  static buildDeleteSQL(options) {
+    if (options.includeDocIdColumn) {
+      return "DELETE FROM records WHERE _type = ? AND _id = ?";
+    } else {
+      return "DELETE FROM records WHERE _type = ? AND _id = ?";
+    }
+  }
+  /**
+   * Generate DELETE statement for stringset values
+   */
+  static buildDeleteStringSetSQL() {
+    return "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ?";
+  }
+  /**
+   * Generate INSERT statement for stringset values
+   */
+  static buildInsertStringSetSQL(options) {
+    if (options.includeDocIdColumn) {
+      return `
+INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value, _meta_doc_id)
+VALUES (?, ?, ?, ?, ?)`.trim();
+    } else {
+      return `
+INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value)
+VALUES (?, ?, ?, ?)`.trim();
+    }
+  }
+};
+
+// src/engines/JsonSchemaEngine.ts
+var JsonSchemaEngine = class extends DatabaseEngine {
+  schemaOptions;
+  initialized = false;
+  constructor(options) {
+    super();
+    this.schemaOptions = options;
+  }
+  /**
+   * Initialize the JSON schema tables.
+   * Should be called once during engine setup.
+   */
+  async initializeSchema() {
+    if (this.initialized) return;
+    const ddlStatements = JsonSchemaDDL.getAllDDL(this.schemaOptions);
+    for (const ddl of ddlStatements) {
+      await this.execSql(ddl);
+    }
+    this.initialized = true;
+  }
+  /**
+   * Create table for a model.
+   * In JSON schema, this is a no-op since all models share the `records` table.
+   * However, we can create indexes for indexed fields.
+   */
+  async createTable(modelName, schema, _options) {
+    await this.initializeSchema();
+    for (const [fieldName, fieldOptions] of schema) {
+      if (fieldOptions.indexed) {
+        const indexDdl = JsonSchemaDDL.createFieldIndex(modelName, fieldName);
+        await this.execSql(indexDdl);
+      }
+    }
+  }
+  /**
+   * Create StringSet junction table.
+   * In JSON schema, this is a no-op since we use the shared stringset_index table.
+   */
+  async createStringSetJunctionTable(_modelName, _fieldName) {
+    await this.initializeSchema();
+  }
+  /**
+   * Insert or update a record.
+   */
+  async insert(modelName, data) {
+    await this.initializeSchema();
+    const { id, _meta_doc_id, _meta_permission_hint, ...fieldsForJson } = data;
+    const dataJson = JSON.stringify(fieldsForJson);
+    const sql = JsonSchemaDDL.buildInsertSQL(this.schemaOptions);
+    if (this.schemaOptions.includeDocIdColumn) {
+      await this.execSql(sql, [
+        id,
+        modelName,
+        dataJson,
+        _meta_doc_id || null,
+        _meta_permission_hint || null
+      ]);
+    } else {
+      await this.execSql(sql, [id, modelName, dataJson]);
+    }
+  }
+  /**
+   * Delete a record by ID.
+   */
+  async delete(modelName, id) {
+    const sql = JsonSchemaDDL.buildDeleteSQL(this.schemaOptions);
+    await this.execSql(sql, [modelName, id]);
+    const ssDeleteSql = JsonSchemaDDL.buildDeleteStringSetSQL();
+    await this.execSql(ssDeleteSql, [modelName, id]);
+  }
+  /**
+   * Delete all records for a specific document.
+   * Only applicable in yjs mode with doc ID column.
+   */
+  async deleteByDocumentId(modelName, docId) {
+    if (!this.schemaOptions.includeDocIdColumn) {
+      throw new Error(
+        "deleteByDocumentId is only supported in yjs mode with doc ID column"
+      );
+    }
+    await this.execSql(
+      "DELETE FROM records WHERE _type = ? AND _meta_doc_id = ?",
+      [modelName, docId]
+    );
+    await this.execSql(
+      "DELETE FROM stringset_index WHERE _type = ? AND _meta_doc_id = ?",
+      [modelName, docId]
+    );
+  }
+  /**
+   * Insert StringSet values for a record.
+   */
+  async insertStringSetValues(modelName, fieldName, recordId, values, docId) {
+    if (values.length === 0) return;
+    const sql = JsonSchemaDDL.buildInsertStringSetSQL(this.schemaOptions);
+    for (const value of values) {
+      if (this.schemaOptions.includeDocIdColumn) {
+        await this.execSql(sql, [
+          recordId,
+          modelName,
+          fieldName,
+          value,
+          docId || null
+        ]);
+      } else {
+        await this.execSql(sql, [recordId, modelName, fieldName, value]);
+      }
+    }
+  }
+  /**
+   * Remove StringSet values for a record.
+   */
+  async removeStringSetValues(modelName, fieldName, recordId, values) {
+    if (values.length === 0) return;
+    const placeholders = values.map(() => "?").join(", ");
+    const sql = `DELETE FROM stringset_index WHERE _type = ? AND field = ? AND _record_id = ? AND value IN (${placeholders})`;
+    await this.execSql(sql, [modelName, fieldName, recordId, ...values]);
+  }
+  /**
+   * Get table name for a model.
+   * In JSON schema, all models use the 'records' table.
+   */
+  getTableName(_modelName) {
+    return "records";
+  }
+  /**
+   * Execute a query and return results.
+   */
+  async query(sql, params) {
+    return this.execSql(sql, params);
+  }
+  /**
+   * Get the table schema.
+   * Returns information about the records table structure.
+   */
+  async getTableSchema(_tableName) {
+    return this.execSql("PRAGMA table_info(records)");
+  }
+  /**
+   * Get the last error message.
+   * Subclasses can override this if needed.
+   */
+  getLastErrorMessage() {
+    return void 0;
+  }
+  /**
+   * Transaction support.
+   * Default implementation runs callback without actual transaction.
+   * Subclasses should override for proper transaction support.
+   */
+  async withTransaction(callback) {
+    const ops = {
+      insert: async (modelName, data) => {
+        await this.insert(modelName, data);
+      },
+      delete: async (modelName, id) => {
+        await this.delete(modelName, id);
+      },
+      query: async (sql, params) => {
+        return await this.execSql(sql, params);
+      }
+    };
+    return callback(ops);
+  }
+  /**
+   * Parse a record row from the database.
+   * Extracts fields from _data and merges with direct columns.
+   */
+  parseRecordRow(row) {
+    if (!row) return row;
+    const { _id, _type, _data, _meta_doc_id, _meta_permission_hint, ...rest } = row;
+    let parsedData = {};
+    if (_data) {
+      try {
+        parsedData = JSON.parse(_data);
+      } catch (e) {
+        console.warn("Failed to parse _data:", e);
+      }
+    }
+    const result = {
+      id: _id,
+      type: _type,
+      ...parsedData,
+      ...rest
+      // Include any projected fields
+    };
+    if (_meta_doc_id !== void 0) {
+      result._meta_doc_id = _meta_doc_id;
+    }
+    if (_meta_permission_hint !== void 0) {
+      result._meta_permission_hint = _meta_permission_hint;
+    }
+    return result;
+  }
+};
+
+// src/engines/cloudflare/DurableObjectEngine.ts
+var DurableObjectEngine = class extends JsonSchemaEngine {
+  sql;
+  storage;
+  constructor(options) {
+    super({ includeDocIdColumn: false });
+    this.sql = options.sql;
+    this.storage = options.storage;
+  }
+  /**
+   * Initialize the engine — creates tables and restores persisted indexes.
+   */
+  async ensureReady() {
+    await this.initializeSchema();
+    this._migrateSchema();
+    this.loadPersistedIndexes();
+  }
+  /**
+   * Handle schema migrations for existing databases.
+   * Adds columns/tables that were added in later versions.
+   */
+  _migrateSchema() {
+    const cols = this.execSqlSync("PRAGMA table_info(_indexes)");
+    if (!cols.some((c) => c.name === "is_unique")) {
+      this.execSqlSync(
+        "ALTER TABLE _indexes ADD COLUMN is_unique INTEGER DEFAULT 0"
+      );
+    }
+    this.execSqlSync(`
+      CREATE TABLE IF NOT EXISTS _model_fields (
+        model_name TEXT NOT NULL,
+        field_name TEXT NOT NULL,
+        inferred_type TEXT NOT NULL,
+        first_seen_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (model_name, field_name)
+      )
+    `);
+    const recordsCols = this.execSqlSync("PRAGMA table_info(records)");
+    const hasOldSchema = recordsCols.some((c) => c.name === "id");
+    if (hasOldSchema) {
+      this.execSqlSync("ALTER TABLE records RENAME COLUMN id TO _id");
+      this.execSqlSync("ALTER TABLE records RENAME COLUMN type TO _type");
+      this.execSqlSync("ALTER TABLE records RENAME COLUMN data_json TO _data");
+      this.execSqlSync("ALTER TABLE stringset_index RENAME COLUMN record_id TO _record_id");
+      this.execSqlSync("ALTER TABLE stringset_index RENAME COLUMN type TO _type");
+      this.execSqlSync("DROP INDEX IF EXISTS idx_records_type");
+      this.execSqlSync("CREATE INDEX IF NOT EXISTS idx_records_type ON records(_type)");
+      this.execSqlSync("DROP INDEX IF EXISTS idx_ss_type_field_value");
+      this.execSqlSync("CREATE INDEX IF NOT EXISTS idx_ss_type_field_value ON stringset_index(_type, field, value)");
+      this.execSqlSync("DROP INDEX IF EXISTS idx_ss_type_field_record");
+      this.execSqlSync("CREATE INDEX IF NOT EXISTS idx_ss_type_field_record ON stringset_index(_type, field, _record_id)");
+      try {
+        const indexes = this.execSqlSync(
+          "SELECT model_name, field_name FROM _indexes"
+        );
+        for (const row of indexes) {
+          const mn = row.model_name;
+          const fn = row.field_name;
+          const idxName = `idx_records_${mn.toLowerCase()}_${fn.toLowerCase()}`;
+          this.execSqlSync(`DROP INDEX IF EXISTS ${idxName}`);
+          this.execSqlSync(
+            `CREATE INDEX IF NOT EXISTS ${idxName} ON records(json_extract(_data, '$.${fn}')) WHERE _type = '${mn}'`
+          );
+        }
+      } catch (e) {
+        console.debug("Could not recreate field indexes during migration:", e);
+      }
+      try {
+        const constraints = this.execSqlSync(
+          "SELECT model_name, constraint_name, fields_json FROM _unique_constraints"
+        );
+        for (const row of constraints) {
+          const mn = row.model_name;
+          const cn = row.constraint_name;
+          const fields = JSON.parse(row.fields_json);
+          const idxName = `idx_uc_${mn.toLowerCase()}_${cn.toLowerCase()}`;
+          this.execSqlSync(`DROP INDEX IF EXISTS ${idxName}`);
+          const fieldExprs = fields.map((f) => `json_extract(_data, '$.${f}')`).join(", ");
+          this.execSqlSync(
+            `CREATE INDEX IF NOT EXISTS ${idxName} ON records(${fieldExprs}) WHERE _type = '${mn}'`
+          );
+        }
+      } catch (e) {
+        console.debug("Could not recreate unique constraint indexes during migration:", e);
+      }
+    }
+  }
+  /**
+   * Load indexes from the _indexes table and re-ensure they exist.
+   */
+  loadPersistedIndexes() {
+    try {
+      const rows = this.execSqlSync(
+        "SELECT model_name, field_name FROM _indexes"
+      );
+      for (const row of rows) {
+        const createSql = JsonSchemaDDL.createFieldIndex(
+          row.model_name,
+          row.field_name
+        );
+        this.execSqlSync(createSql);
+      }
+    } catch (e) {
+      console.debug("Could not load persisted indexes:", e);
+    }
+  }
+  /**
+   * Register an index on a model field.
+   * Idempotent — re-registering the same index is a no-op.
+   */
+  registerIndex(modelName, fieldName, fieldType, unique = false) {
+    assertValidIdentifier(modelName, "registerIndex modelName");
+    assertValidIdentifier(fieldName, "registerIndex fieldName");
+    this.execSqlSync(
+      `INSERT OR REPLACE INTO _indexes (model_name, field_name, field_type, is_unique)
+       VALUES (?, ?, ?, ?)`,
+      [modelName, fieldName, fieldType, unique ? 1 : 0]
+    );
+    const createSql = JsonSchemaDDL.createFieldIndex(modelName, fieldName);
+    this.execSqlSync(createSql);
+  }
+  /**
+   * Drop an index on a model field.
+   * Idempotent — dropping a non-existent index is a no-op.
+   */
+  dropIndex(modelName, fieldName) {
+    assertValidIdentifier(modelName, "dropIndex modelName");
+    assertValidIdentifier(fieldName, "dropIndex fieldName");
+    this.execSqlSync(
+      "DELETE FROM _indexes WHERE model_name = ? AND field_name = ?",
+      [modelName, fieldName]
+    );
+    const dropSql = JsonSchemaDDL.dropFieldIndex(modelName, fieldName);
+    this.execSqlSync(dropSql);
+  }
+  /**
+   * List all registered indexes, optionally filtered by model.
+   */
+  listIndexes(modelName) {
+    if (modelName) {
+      return this.execSqlSync(
+        "SELECT model_name, field_name, field_type, is_unique, created_at FROM _indexes WHERE model_name = ?",
+        [modelName]
+      );
+    }
+    return this.execSqlSync(
+      "SELECT model_name, field_name, field_type, is_unique, created_at FROM _indexes"
+    );
+  }
+  /**
+   * Get unique single-field indexes for a model.
+   */
+  getUniqueIndexes(modelName) {
+    return this.execSqlSync(
+      "SELECT model_name, field_name, field_type, is_unique, created_at FROM _indexes WHERE model_name = ? AND is_unique = 1",
+      [modelName]
+    );
+  }
+  /**
+   * Register a composite unique constraint.
+   * Idempotent — re-registering the same constraint is a no-op.
+   */
+  registerUniqueConstraint(modelName, constraintName, fields) {
+    assertValidIdentifier(modelName, "registerUniqueConstraint modelName");
+    assertValidIdentifier(constraintName, "registerUniqueConstraint constraintName");
+    for (const f of fields) {
+      assertValidIdentifier(f, "registerUniqueConstraint field");
+    }
+    this.execSqlSync(
+      `INSERT OR REPLACE INTO _unique_constraints (model_name, constraint_name, fields_json)
+       VALUES (?, ?, ?)`,
+      [modelName, constraintName, JSON.stringify(fields)]
+    );
+    const fieldExprs = fields.map((f) => `json_extract(_data, '$.${f}')`).join(", ");
+    const indexName = `idx_uc_${modelName.toLowerCase()}_${constraintName.toLowerCase()}`;
+    this.execSqlSync(
+      `CREATE INDEX IF NOT EXISTS ${indexName} ON records(${fieldExprs}) WHERE _type = '${modelName}'`
+    );
+  }
+  /**
+   * Drop a composite unique constraint.
+   * Idempotent — dropping a non-existent constraint is a no-op.
+   */
+  dropUniqueConstraint(modelName, constraintName) {
+    this.execSqlSync(
+      "DELETE FROM _unique_constraints WHERE model_name = ? AND constraint_name = ?",
+      [modelName, constraintName]
+    );
+    const indexName = `idx_uc_${modelName.toLowerCase()}_${constraintName.toLowerCase()}`;
+    this.execSqlSync(`DROP INDEX IF EXISTS ${indexName}`);
+  }
+  /**
+   * List composite unique constraints, optionally filtered by model.
+   */
+  listUniqueConstraints(modelName) {
+    const sql = modelName ? "SELECT model_name, constraint_name, fields_json, created_at FROM _unique_constraints WHERE model_name = ?" : "SELECT model_name, constraint_name, fields_json, created_at FROM _unique_constraints";
+    const params = modelName ? [modelName] : void 0;
+    const rows = this.execSqlSync(sql, params);
+    return rows.map((row) => ({
+      model_name: row.model_name,
+      constraint_name: row.constraint_name,
+      fields: JSON.parse(row.fields_json),
+      created_at: row.created_at
+    }));
+  }
+  /**
+   * Check all unique constraints for a model before saving.
+   * Returns null if no violation, or an error message string if violated.
+   */
+  checkUniqueConstraints(modelName, id, data) {
+    const uniqueIndexes = this.getUniqueIndexes(modelName);
+    for (const idx of uniqueIndexes) {
+      assertValidIdentifier(idx.field_name, "checkUniqueConstraints field_name");
+      const value = data[idx.field_name];
+      if (value === null || value === void 0) continue;
+      const conflicts = this.execSqlSync(
+        `SELECT _id FROM records WHERE _type = ? AND json_extract(_data, '$.${idx.field_name}') = ? AND _id != ? LIMIT 1`,
+        [modelName, value, id]
+      );
+      if (conflicts.length > 0) {
+        return `Unique constraint violated on field '${idx.field_name}' for model '${modelName}'. Value '${String(value).substring(0, 50)}' already exists on record '${conflicts[0]._id}'.`;
+      }
+    }
+    const composites = this.listUniqueConstraints(modelName);
+    for (const constraint of composites) {
+      for (const f of constraint.fields) {
+        assertValidIdentifier(f, "checkUniqueConstraints composite field");
+      }
+      const values = constraint.fields.map((f) => data[f]);
+      if (values.some((v) => v === null || v === void 0)) continue;
+      const conditions = constraint.fields.map((f) => `json_extract(_data, '$.${f}') = ?`).join(" AND ");
+      const conflicts = this.execSqlSync(
+        `SELECT _id FROM records WHERE _type = ? AND ${conditions} AND _id != ? LIMIT 1`,
+        [modelName, ...values, id]
+      );
+      if (conflicts.length > 0) {
+        return `Unique constraint '${constraint.constraint_name}' violated for model '${modelName}' on fields [${constraint.fields.join(", ")}]. Values already exist on record '${conflicts[0]._id}'.`;
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if a record exists (used by hooks to determine isNew).
+   */
+  recordExists(modelName, id) {
+    const rows = this.execSqlSync(
+      "SELECT 1 FROM records WHERE _type = ? AND _id = ? LIMIT 1",
+      [modelName, id]
+    );
+    return rows.length > 0;
+  }
+  /**
+   * Execute SQL asynchronously.
+   * Wraps the synchronous DO SQLite API.
+   */
+  async execSql(sql, params) {
+    return this.execSqlSync(sql, params);
+  }
+  /**
+   * Execute SQL synchronously.
+   * This is the native mode for DO SQLite.
+   */
+  execSqlSync(sql, params) {
+    try {
+      const cursor = params ? this.sql.exec(sql, ...params) : this.sql.exec(sql);
+      return cursor.toArray();
+    } catch (error) {
+      console.error("SQL execution error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Transaction support using DO's transactionSync.
+   */
+  async withTransaction(callback) {
+    const ops = {
+      insert: async (modelName, data) => {
+        await this.insert(modelName, data);
+      },
+      delete: async (modelName, id) => {
+        await this.delete(modelName, id);
+      },
+      query: async (sql, params) => {
+        return this.execSqlSync(sql, params);
+      }
+    };
+    return callback(ops);
+  }
+  /**
+   * Run operations within a synchronous transaction.
+   */
+  transactionSync(callback) {
+    return this.storage.transactionSync(callback);
+  }
+  /**
+   * Clean up resources.
+   */
+  async destroy() {
+  }
+  /**
+   * Insert a record with StringSet support.
+   */
+  async insertWithStringSets(modelName, data, stringSets) {
+    this.storage.transactionSync(() => {
+      const { id, ...fieldsForJson } = data;
+      const jsonFields = { ...fieldsForJson, ...stringSets };
+      const dataJson = JSON.stringify(jsonFields);
+      this.sql.exec(
+        "INSERT OR REPLACE INTO records (_id, _type, _data) VALUES (?, ?, ?)",
+        id,
+        modelName,
+        dataJson
+      );
+      this.sql.exec(
+        "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ?",
+        modelName,
+        id
+      );
+      for (const [fieldName, values] of Object.entries(stringSets)) {
+        for (const value of values) {
+          this.sql.exec(
+            "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
+            id,
+            modelName,
+            fieldName,
+            value
+          );
+        }
+      }
+    });
+  }
+  /**
+   * Add values to StringSet fields without replacing the entire set.
+   * Also updates the arrays stored in data_json.
+   */
+  addToStringSets(modelName, id, sets) {
+    this.storage.transactionSync(() => {
+      this.addToStringSetsRaw(modelName, id, sets);
+    });
+  }
+  /**
+   * Non-transactional core of addToStringSets.
+   * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+   * @internal
+   */
+  addToStringSetsRaw(modelName, id, sets) {
+    for (const [field, values] of Object.entries(sets)) {
+      for (const value of values) {
+        this.sql.exec(
+          "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
+          id,
+          modelName,
+          field,
+          value
+        );
+      }
+    }
+    this._syncStringSetsToJson(modelName, id, Object.keys(sets));
+  }
+  /**
+   * Remove values from StringSet fields without replacing the entire set.
+   * Also updates the arrays stored in data_json.
+   */
+  removeFromStringSets(modelName, id, sets) {
+    this.storage.transactionSync(() => {
+      this.removeFromStringSetsRaw(modelName, id, sets);
+    });
+  }
+  /**
+   * Non-transactional core of removeFromStringSets.
+   * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+   * @internal
+   */
+  removeFromStringSetsRaw(modelName, id, sets) {
+    for (const [field, values] of Object.entries(sets)) {
+      for (const value of values) {
+        this.sql.exec(
+          "DELETE FROM stringset_index WHERE _record_id = ? AND _type = ? AND field = ? AND value = ?",
+          id,
+          modelName,
+          field,
+          value
+        );
+      }
+    }
+    this._syncStringSetsToJson(modelName, id, Object.keys(sets));
+  }
+  /**
+   * Sync stringset_index state back into data_json arrays for the given fields.
+   * @internal
+   */
+  _syncStringSetsToJson(modelName, id, fields) {
+    const rows = this.execSqlSync(
+      "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+      [id, modelName]
+    );
+    if (rows.length === 0) return;
+    const data = JSON.parse(rows[0]._data);
+    for (const field of fields) {
+      const ssRows = this.execSqlSync(
+        "SELECT value FROM stringset_index WHERE _record_id = ? AND _type = ? AND field = ? ORDER BY value",
+        [id, modelName, field]
+      );
+      data[field] = ssRows.map((r) => r.value);
+    }
+    this.sql.exec(
+      "UPDATE records SET _data = ? WHERE _id = ? AND _type = ?",
+      JSON.stringify(data),
+      id,
+      modelName
+    );
+  }
+  /**
+   * Patch a record: merge provided fields into existing data_json.
+   * Only the specified fields are updated; all other fields are preserved.
+   * If stringSets are provided, those StringSet fields are fully replaced.
+   * Returns false if the record does not exist.
+   */
+  patchRecord(modelName, id, fields, stringSets) {
+    let found = true;
+    this.storage.transactionSync(() => {
+      found = this.patchRecordRaw(modelName, id, fields, stringSets);
+    });
+    return found;
+  }
+  /**
+   * Non-transactional core of patchRecord.
+   * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+   * @internal
+   */
+  patchRecordRaw(modelName, id, fields, stringSets) {
+    const rows = this.execSqlSync(
+      "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+      [id, modelName]
+    );
+    if (rows.length === 0) {
+      return false;
+    }
+    const existing = JSON.parse(rows[0]._data);
+    const { id: _stripId, ...patchFields } = fields;
+    const merged = { ...existing, ...patchFields };
+    if (stringSets) {
+      for (const [field, values] of Object.entries(stringSets)) {
+        merged[field] = values;
+      }
+    }
+    this.sql.exec(
+      "UPDATE records SET _data = ? WHERE _id = ? AND _type = ?",
+      JSON.stringify(merged),
+      id,
+      modelName
+    );
+    if (stringSets) {
+      for (const [fieldName, values] of Object.entries(stringSets)) {
+        this.sql.exec(
+          "DELETE FROM stringset_index WHERE _record_id = ? AND _type = ? AND field = ?",
+          id,
+          modelName,
+          fieldName
+        );
+        for (const value of values) {
+          this.sql.exec(
+            "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
+            id,
+            modelName,
+            fieldName,
+            value
+          );
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Atomically increment/decrement numeric fields on a record.
+   * Each key in `fields` is a field name and its value is the delta.
+   * Missing fields are initialised to 0 before adding the delta.
+   * Returns the new values, or null if the record doesn't exist.
+   */
+  incrementFields(modelName, id, fields) {
+    let result = null;
+    this.storage.transactionSync(() => {
+      result = this.incrementFieldsRaw(modelName, id, fields);
+    });
+    return result;
+  }
+  /**
+   * Non-transactional core of incrementFields.
+   * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+   * @internal
+   */
+  incrementFieldsRaw(modelName, id, fields) {
+    const rows = this.execSqlSync(
+      "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+      [id, modelName]
+    );
+    if (rows.length === 0) return null;
+    const data = JSON.parse(rows[0]._data);
+    const newValues = {};
+    for (const [field, delta] of Object.entries(fields)) {
+      const current = typeof data[field] === "number" ? data[field] : 0;
+      data[field] = current + delta;
+      newValues[field] = data[field];
+    }
+    this.sql.exec(
+      "UPDATE records SET _data = ? WHERE _id = ? AND _type = ?",
+      JSON.stringify(data),
+      id,
+      modelName
+    );
+    return newValues;
+  }
+  /**
+   * Delete a record and its StringSet values atomically.
+   */
+  async deleteWithStringSets(modelName, id) {
+    this.storage.transactionSync(() => {
+      this.sql.exec("DELETE FROM records WHERE _type = ? AND _id = ?", modelName, id);
+      this.sql.exec(
+        "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ?",
+        modelName,
+        id
+      );
+    });
+  }
+  /**
+   * Track field names and inferred types for a model based on written data.
+   * Uses INSERT OR IGNORE so the first-seen type wins.
+   */
+  trackModelFields(modelName, data) {
+    for (const [key, value] of Object.entries(data)) {
+      if (key === "id" || value === null || value === void 0) {
+        continue;
+      }
+      let inferredType;
+      if (typeof value === "number") {
+        inferredType = "number";
+      } else if (typeof value === "boolean") {
+        inferredType = "boolean";
+      } else if (Array.isArray(value)) {
+        inferredType = "array";
+      } else if (typeof value === "object") {
+        inferredType = "object";
+      } else {
+        inferredType = "string";
+      }
+      this.sql.exec(
+        "INSERT OR IGNORE INTO _model_fields (model_name, field_name, inferred_type) VALUES (?, ?, ?)",
+        modelName,
+        key,
+        inferredType
+      );
+    }
+  }
+  /**
+   * Get tracked fields for a model, or all models if no name given.
+   */
+  getModelFields(modelName) {
+    if (modelName) {
+      return this.execSqlSync(
+        "SELECT model_name, field_name, inferred_type, first_seen_at FROM _model_fields WHERE model_name = ? ORDER BY field_name",
+        [modelName]
+      );
+    }
+    return this.execSqlSync(
+      "SELECT model_name, field_name, inferred_type, first_seen_at FROM _model_fields ORDER BY model_name, field_name"
+    );
+  }
+};
+
+// src/types/queryTypes.ts
+var DocumentQueryError = class _DocumentQueryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DocumentQueryError";
+    Object.setPrototypeOf(this, _DocumentQueryError.prototype);
+  }
+};
+var InvalidOperatorError = class _InvalidOperatorError extends DocumentQueryError {
+  field;
+  operator;
+  fieldType;
+  constructor(message, field, operator, fieldType) {
+    super(message);
+    this.name = "InvalidOperatorError";
+    this.field = field;
+    this.operator = operator;
+    this.fieldType = fieldType;
+    Object.setPrototypeOf(this, _InvalidOperatorError.prototype);
+  }
+};
+var InvalidFieldError = class _InvalidFieldError extends DocumentQueryError {
+  field;
+  modelName;
+  constructor(message, field, modelName) {
+    super(message);
+    this.name = "InvalidFieldError";
+    this.field = field;
+    this.modelName = modelName;
+    Object.setPrototypeOf(this, _InvalidFieldError.prototype);
+  }
+};
+var InvalidCursorError = class _InvalidCursorError extends DocumentQueryError {
+  cursor;
+  constructor(message, cursor) {
+    super(message);
+    this.name = "InvalidCursorError";
+    this.cursor = cursor;
+    Object.setPrototypeOf(this, _InvalidCursorError.prototype);
+  }
+};
+
+// src/query/CursorManager.ts
+var base64Encode = (str) => {
+  if (typeof btoa !== "undefined") {
+    return btoa(str);
+  } else if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "utf-8").toString("base64");
+  } else {
+    throw new Error("No base64 encoding available");
+  }
+};
+var base64Decode = (str) => {
+  if (typeof atob !== "undefined") {
+    return atob(str);
+  } else if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "base64").toString("utf-8");
+  } else {
+    throw new Error("No base64 decoding available");
+  }
+};
+var CursorManager = class {
+  /**
+   * Encode cursor data to base64 string
+   */
+  static encodeCursor(cursorData) {
+    try {
+      const jsonString = JSON.stringify(cursorData);
+      return base64Encode(jsonString);
+    } catch (error) {
+      throw new InvalidCursorError(
+        `Failed to encode cursor: ${error instanceof Error ? error.message : "Unknown error"}`,
+        JSON.stringify(cursorData)
+      );
+    }
+  }
+  /**
+   * Decode base64 cursor string to cursor data
+   */
+  static decodeCursor(cursor) {
+    try {
+      const jsonString = base64Decode(cursor);
+      const parsed = JSON.parse(jsonString);
+      if (!parsed || typeof parsed !== "object") {
+        throw new Error("Cursor must be an object");
+      }
+      if (!parsed.values || typeof parsed.values !== "object") {
+        throw new Error("Cursor must have values object");
+      }
+      if (!Array.isArray(parsed.sortFields)) {
+        throw new Error("Cursor must have sortFields array");
+      }
+      if (parsed.direction !== 1 && parsed.direction !== -1) {
+        throw new Error("Cursor direction must be 1 or -1");
+      }
+      return parsed;
+    } catch (error) {
+      throw new InvalidCursorError(
+        `Failed to decode cursor: ${error instanceof Error ? error.message : "Unknown error"}`,
+        cursor
+      );
+    }
+  }
+  /**
+   * Generate cursor from a record and sort specification
+   */
+  static generateCursor(record, sortFields, direction) {
+    const values = {};
+    for (const field of sortFields) {
+      if (record.hasOwnProperty(field)) {
+        values[field] = record[field];
+      } else {
+        throw new Error(
+          `Cannot generate cursor: record missing sort field '${field}'`
+        );
+      }
+    }
+    const cursorData = {
+      values,
+      sortFields,
+      direction
+    };
+    return this.encodeCursor(cursorData);
+  }
+  /**
+   * Build SQL pagination conditions based on cursor
+   * Uses lexicographic ordering for stable pagination with multiple sort fields
+   */
+  static buildPaginationConditions(cursor, currentSortFields, sortDirections, requestedDirection, fieldFormatter = (field) => field) {
+    if (!this.arraysEqual(cursor.sortFields, currentSortFields)) {
+      throw new InvalidCursorError(
+        `Cursor sort fields [${cursor.sortFields.join(
+          ", "
+        )}] don't match query sort fields [${currentSortFields.join(", ")}]`,
+        JSON.stringify(cursor)
+      );
+    }
+    const conditions = [];
+    const params = [];
+    const sortFields = cursor.sortFields;
+    const direction = requestedDirection;
+    for (let i = 0; i < sortFields.length; i++) {
+      const fieldConditions = [];
+      const fieldParams = [];
+      for (let j = 0; j < i; j++) {
+        const field = sortFields[j];
+        const value = cursor.values[field];
+        fieldConditions.push(`${fieldFormatter(field)} = ?`);
+        fieldParams.push(value);
+      }
+      const currentField = sortFields[i];
+      const currentValue = cursor.values[currentField];
+      const fieldSortDir = sortDirections[i] ?? 1;
+      const forwardOp = fieldSortDir === 1 ? ">" : "<";
+      const operator = direction === 1 ? forwardOp : forwardOp === ">" ? "<" : ">";
+      fieldConditions.push(`${fieldFormatter(currentField)} ${operator} ?`);
+      fieldParams.push(currentValue);
+      const levelCondition = fieldConditions.join(" AND ");
+      conditions.push(`(${levelCondition})`);
+      params.push(...fieldParams);
+    }
+    const sql = `(${conditions.join(" OR ")})`;
+    return { sql, params };
+  }
+  /**
+   * Extract sort fields from sort specification, ensuring 'id' is always included for stability
+   */
+  static extractSortFields(sort) {
+    const fields = [];
+    if (sort && Object.keys(sort).length > 0) {
+      fields.push(...Object.keys(sort));
+    }
+    if (!fields.includes("id")) {
+      fields.push("id");
+    }
+    return fields;
+  }
+  /**
+   * Build ORDER BY clause from sort specification
+   */
+  static buildOrderClause(sort, fieldFormatter = (field) => field) {
+    const fields = this.extractSortFields(sort);
+    const clauses = [];
+    const directions = [];
+    if (sort && Object.keys(sort).length > 0) {
+      for (const [field, dir] of Object.entries(sort)) {
+        const sqlDirection = dir === 1 ? "ASC" : "DESC";
+        clauses.push(`${fieldFormatter(field)} ${sqlDirection}`);
+        directions.push(dir);
+      }
+    }
+    if (!sort || !sort.hasOwnProperty("id")) {
+      clauses.push(`${fieldFormatter("id")} ASC`);
+      directions.push(1);
+    } else if (sort && sort.hasOwnProperty("id")) {
+      directions.push(sort["id"]);
+    }
+    return {
+      sql: clauses.join(", "),
+      fields,
+      directions
+    };
+  }
+  /**
+   * Determine if there are more results available for pagination
+   */
+  static hasMoreResults(requestedLimit, actualResultCount) {
+    if (!requestedLimit || requestedLimit <= 0) {
+      return false;
+    }
+    return actualResultCount >= requestedLimit;
+  }
+  /**
+   * Generate next and previous cursors from result set
+   */
+  static generateResultCursors(results, sortFields, _requestedDirection, hasMore, isFirstPage = false) {
+    if (results.length === 0) {
+      return {};
+    }
+    const cursors = {};
+    if (hasMore && results.length > 0) {
+      const lastResult = results[results.length - 1];
+      cursors.nextCursor = this.generateCursor(lastResult, sortFields, 1);
+    }
+    if (results.length > 0 && !isFirstPage) {
+      const firstResult = results[0];
+      cursors.prevCursor = this.generateCursor(firstResult, sortFields, -1);
+    }
+    return cursors;
+  }
+  /**
+   * Utility to compare arrays for equality
+   */
+  static arraysEqual(a, b) {
+    if (a.length !== b.length) return false;
+    return a.every((val, index) => val === b[index]);
+  }
+};
+
+// src/utils/patterns.ts
+function escapeLikeLiteral(input) {
+  return input.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+function buildLikePattern(value, mode) {
+  const trimmed = (value ?? "").trim();
+  if (trimmed.length === 0) return null;
+  if (trimmed.length > 1024) {
+    throw new Error("substring value exceeds 1024 characters");
+  }
+  const escaped = escapeLikeLiteral(trimmed);
+  switch (mode) {
+    case "startsWith":
+      return `${escaped}%`;
+    case "endsWith":
+      return `%${escaped}`;
+    case "containsText":
+      return `%${escaped}%`;
+  }
+}
+function shouldLogLikeEscapes() {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return !!process.env.JS_BAO_DEBUG_LIKE_ESCAPES;
+    }
+  } catch {
+  }
+  return false;
+}
+
+// src/query/JsonQueryTranslator.ts
+var SYSTEM_FIELDS = /* @__PURE__ */ new Set(["id", "type"]);
+var JsonQueryTranslator = class {
+  modelName;
+  schema;
+  options;
+  fieldSqlCache;
+  constructor(modelName, schema, options = { includeDocId: false }) {
+    this.modelName = modelName;
+    this.schema = schema;
+    this.options = options;
+    this.fieldSqlCache = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get SQL expression for a field.
+   * System fields (id, type) map to internal columns (_id, _type);
+   * others use json_extract(_data, ...).
+   * When no schema is provided, any field is accepted (schemaless mode).
+   */
+  getFieldSql(fieldName) {
+    if (!this.fieldSqlCache.has(fieldName)) {
+      if (SYSTEM_FIELDS.has(fieldName)) {
+        const internalName = `_${fieldName}`;
+        this.fieldSqlCache.set(fieldName, quoteIdentifier(internalName));
+      } else {
+        assertValidIdentifier(fieldName, "query field");
+        this.fieldSqlCache.set(
+          fieldName,
+          `json_extract(_data, '$.${fieldName}')`
+        );
+      }
+    }
+    return this.fieldSqlCache.get(fieldName);
+  }
+  /**
+   * Translate document filter and options to SQL for find operations
+   */
+  translateFind(filter, options) {
+    if (options?.projection) {
+      this.validateProjection(options.projection);
+    }
+    const whereClause = this.translateFilter(filter);
+    const orderClause = CursorManager.buildOrderClause(
+      options?.sort,
+      (field) => this.getFieldSql(field)
+    );
+    const limitClause = this.buildLimitClause(options);
+    const paginationClause = this.buildPaginationClause(
+      options,
+      orderClause.fields,
+      orderClause.directions
+    );
+    const selectClause = this.buildSelectClause(options?.projection);
+    let sql = `SELECT ${selectClause} FROM records`;
+    const params = [];
+    const conditions = [`${quoteIdentifier("_type")} = ?`];
+    params.push(this.modelName);
+    if (whereClause.sql) {
+      conditions.push(whereClause.sql);
+      params.push(...whereClause.params);
+    }
+    if (paginationClause.sql) {
+      conditions.push(paginationClause.sql);
+      params.push(...paginationClause.params);
+    }
+    if (this.options.includeDocId) {
+      const documentClause = this.buildDocumentClause(options?.documents);
+      if (documentClause) {
+        conditions.push(documentClause.sql);
+        params.push(...documentClause.params);
+      }
+    }
+    sql += ` WHERE ${conditions.join(" AND ")}`;
+    if (orderClause.sql) {
+      sql += ` ORDER BY ${orderClause.sql}`;
+    }
+    if (limitClause.sql) {
+      sql += ` LIMIT ${limitClause.sql}`;
+    }
+    return {
+      sql,
+      params,
+      sortFields: orderClause.fields,
+      sortDirections: orderClause.directions
+    };
+  }
+  /**
+   * Translate document filter to SQL for count operations
+   */
+  translateCount(filter, options) {
+    const whereClause = this.translateFilter(filter);
+    const conditions = [`${quoteIdentifier("_type")} = ?`];
+    const params = [this.modelName];
+    if (whereClause.sql) {
+      conditions.push(whereClause.sql);
+      params.push(...whereClause.params);
+    }
+    if (this.options.includeDocId) {
+      const documentClause = this.buildDocumentClause(options?.documents);
+      if (documentClause) {
+        conditions.push(documentClause.sql);
+        params.push(...documentClause.params);
+      }
+    }
+    const sql = `SELECT COUNT(*) as count FROM records WHERE ${conditions.join(
+      " AND "
+    )}`;
+    return { sql, params };
+  }
+  /**
+   * Translate document filter to SQL WHERE clause.
+   * Returns the conditions and params without the type = ? prefix.
+   */
+  translateFilter(filter) {
+    if (!filter || Object.keys(filter).length === 0) {
+      return { sql: "", params: [] };
+    }
+    const conditions = [];
+    const params = [];
+    for (const [key, value] of Object.entries(filter)) {
+      if (key === "$and") {
+        const andClause = this.translateLogicalOperator(
+          "AND",
+          value
+        );
+        if (andClause.sql) {
+          conditions.push(`(${andClause.sql})`);
+          params.push(...andClause.params);
+        }
+      } else if (key === "$or") {
+        const orClause = this.translateLogicalOperator(
+          "OR",
+          value
+        );
+        if (orClause.sql) {
+          conditions.push(`(${orClause.sql})`);
+          params.push(...orClause.params);
+        }
+      } else {
+        const fieldClause = this.translateFieldCondition(key, value);
+        if (fieldClause.sql) {
+          conditions.push(fieldClause.sql);
+          params.push(...fieldClause.params);
+        }
+      }
+    }
+    return {
+      sql: conditions.join(" AND "),
+      params
+    };
+  }
+  /**
+   * Translate logical operators ($and, $or)
+   */
+  translateLogicalOperator(operator, filters) {
+    if (!Array.isArray(filters) || filters.length === 0) {
+      return { sql: "", params: [] };
+    }
+    const clauses = [];
+    const params = [];
+    for (const filter of filters) {
+      const clause = this.translateFilter(filter);
+      if (clause.sql) {
+        clauses.push(clause.sql);
+        params.push(...clause.params);
+      }
+    }
+    if (clauses.length === 0) {
+      return { sql: "", params: [] };
+    }
+    return {
+      sql: clauses.join(` ${operator} `),
+      params
+    };
+  }
+  /**
+   * Translate field condition to SQL
+   */
+  translateFieldCondition(fieldName, condition) {
+    const fieldSql = this.getFieldSql(fieldName);
+    if (condition === null || condition === void 0) {
+      return { sql: `${fieldSql} IS NULL`, params: [] };
+    }
+    if (this.isPrimitiveValue(condition)) {
+      this.validateFieldValue(fieldName, condition);
+      return {
+        sql: `${fieldSql} = ?`,
+        params: [this.convertValueForSQLite(condition)]
+      };
+    }
+    if (typeof condition === "object" && !Array.isArray(condition)) {
+      return this.translateFieldOperators(fieldName, condition);
+    }
+    if (Array.isArray(condition)) {
+      this.validateArrayValues(fieldName, condition);
+      const placeholders = condition.map(() => "?").join(",");
+      const convertedValues = condition.map(
+        (v) => this.convertValueForSQLite(v)
+      );
+      return {
+        sql: `${fieldSql} IN (${placeholders})`,
+        params: convertedValues
+      };
+    }
+    throw new InvalidOperatorError(
+      `Unsupported condition type for field ${fieldName}`,
+      fieldName,
+      "unknown"
+    );
+  }
+  /**
+   * Translate field operators to SQL
+   */
+  translateFieldOperators(fieldName, operators) {
+    const conditions = [];
+    const params = [];
+    const fieldOptions = this.schema?.get(fieldName);
+    const fieldType = fieldOptions?.type;
+    const fieldSql = this.getFieldSql(fieldName);
+    const substringOps = [
+      "$startsWith",
+      "$endsWith",
+      "$containsText"
+    ];
+    const presentSubstringOps = substringOps.filter(
+      (op) => Object.prototype.hasOwnProperty.call(operators, op)
+    );
+    if (presentSubstringOps.length > 1) {
+      throw new InvalidOperatorError(
+        `Only one of $startsWith, $endsWith, $containsText may be used per field`,
+        fieldName,
+        presentSubstringOps[1],
+        fieldType
+      );
+    }
+    if (presentSubstringOps.length === 1) {
+      const op = presentSubstringOps[0];
+      const value = operators[op];
+      if (fieldType && fieldType !== "string" && fieldType !== "stringset") {
+        throw new InvalidOperatorError(
+          `${op} operator is only supported for string and stringset fields, field ${fieldName} is type ${fieldType}`,
+          fieldName,
+          op,
+          fieldType
+        );
+      }
+      if (typeof value !== "string") {
+        throw new InvalidOperatorError(
+          `${op} operator requires a string value for field ${fieldName}`,
+          fieldName,
+          op,
+          fieldType
+        );
+      }
+      let pattern;
+      try {
+        const mode = op === "$startsWith" ? "startsWith" : op === "$endsWith" ? "endsWith" : "containsText";
+        pattern = buildLikePattern(value, mode);
+      } catch (e) {
+        throw new InvalidOperatorError(
+          e.message || "invalid substring value",
+          fieldName,
+          op,
+          fieldType
+        );
+      }
+      if (pattern !== null) {
+        if (shouldLogLikeEscapes()) {
+          try {
+            console.debug(
+              `[Substring] field=${fieldName} op=${op} pattern=${pattern} ci=true`
+            );
+          } catch {
+          }
+        }
+        if (fieldType === "stringset") {
+          const likeSql = `EXISTS (SELECT 1 FROM stringset_index WHERE stringset_index._type = ? AND stringset_index.field = ? AND stringset_index._record_id = records._id AND stringset_index.value LIKE ? ESCAPE '\\' COLLATE NOCASE)`;
+          conditions.push(likeSql);
+          params.push(this.modelName, fieldName, pattern);
+        } else {
+          const likeSql = `${fieldSql} LIKE ? ESCAPE '\\' COLLATE NOCASE`;
+          conditions.push(likeSql);
+          params.push(pattern);
+        }
+      }
+    }
+    for (const [operator, value] of Object.entries(operators)) {
+      if (substringOps.includes(operator)) {
+        continue;
+      }
+      const opClause = this.translateOperator(fieldName, operator, value);
+      if (opClause.sql) {
+        conditions.push(opClause.sql);
+        params.push(...opClause.params);
+      }
+    }
+    return {
+      sql: conditions.join(" AND "),
+      params
+    };
+  }
+  /**
+   * Translate individual operator to SQL
+   */
+  translateOperator(fieldName, operator, value) {
+    const fieldOptions = this.schema?.get(fieldName);
+    const fieldType = fieldOptions?.type;
+    const fieldSql = this.getFieldSql(fieldName);
+    switch (operator) {
+      case "$eq":
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} = ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$ne":
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} != ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$gt":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} > ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$gte":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} >= ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$lt":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} < ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$lte":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${fieldSql} <= ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$in":
+        if (!Array.isArray(value)) {
+          throw new InvalidOperatorError(
+            `$in operator requires an array value for field ${fieldName}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        this.validateArrayValues(fieldName, value);
+        if (value.length === 0) {
+          return { sql: "1 = 0", params: [] };
+        }
+        const placeholders = value.map(() => "?").join(",");
+        const convertedValues = value.map((v) => this.convertValueForSQLite(v));
+        return {
+          sql: `${fieldSql} IN (${placeholders})`,
+          params: convertedValues
+        };
+      case "$nin":
+        if (!Array.isArray(value)) {
+          throw new InvalidOperatorError(
+            `$nin operator requires an array value for field ${fieldName}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        this.validateArrayValues(fieldName, value);
+        if (value.length === 0) {
+          return { sql: "", params: [] };
+        }
+        const ninPlaceholders = value.map(() => "?").join(",");
+        const convertedNinValues = value.map(
+          (v) => this.convertValueForSQLite(v)
+        );
+        return {
+          sql: `${fieldSql} NOT IN (${ninPlaceholders})`,
+          params: convertedNinValues
+        };
+      case "$exists":
+        if (typeof value !== "boolean") {
+          throw new InvalidOperatorError(
+            `$exists operator requires a boolean value for field ${fieldName}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        if (SYSTEM_FIELDS.has(fieldName)) {
+          return value ? { sql: `${fieldSql} IS NOT NULL`, params: [] } : { sql: `${fieldSql} IS NULL`, params: [] };
+        } else {
+          return value ? {
+            sql: `json_type(_data, '$.${fieldName}') IS NOT NULL`,
+            params: []
+          } : {
+            sql: `json_type(_data, '$.${fieldName}') IS NULL`,
+            params: []
+          };
+        }
+      case "$contains":
+        if (fieldType && fieldType !== "stringset") {
+          throw new InvalidOperatorError(
+            `$contains operator is only supported for stringset fields, field ${fieldName} is type ${fieldType}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        if (typeof value !== "string") {
+          throw new InvalidOperatorError(
+            `$contains operator requires a string value for field ${fieldName}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        return {
+          sql: `EXISTS (SELECT 1 FROM stringset_index WHERE stringset_index._type = ? AND stringset_index.field = ? AND stringset_index._record_id = records._id AND stringset_index.value = ?)`,
+          params: [this.modelName, fieldName, value]
+        };
+      default:
+        throw new InvalidOperatorError(
+          `Unsupported operator: ${operator} for field ${fieldName}`,
+          fieldName,
+          operator,
+          fieldType
+        );
+    }
+  }
+  /**
+   * Build SELECT clause based on projection
+   * For JSON schema, we need to extract fields from data_json
+   */
+  buildSelectClause(projection) {
+    if (!projection || Object.keys(projection).length === 0) {
+      return "_id, _type, _data";
+    }
+    const includeFields = [];
+    const excludeFields = [];
+    let hasIncludes = false;
+    let hasExcludes = false;
+    for (const [field, include] of Object.entries(projection)) {
+      if (include === 1) {
+        includeFields.push(field);
+        hasIncludes = true;
+      } else if (include === 0) {
+        excludeFields.push(field);
+        hasExcludes = true;
+      }
+    }
+    if (hasIncludes && hasExcludes) {
+      throw new InvalidOperatorError(
+        "Cannot mix inclusion and exclusion in projection",
+        "projection",
+        "mixed"
+      );
+    }
+    if (hasIncludes) {
+      if (!includeFields.includes("id")) {
+        includeFields.unshift("id");
+      }
+      const selectParts = ["_id", "_type"];
+      for (const field of includeFields) {
+        if (field === "id" || field === "type") continue;
+        selectParts.push(
+          `json_extract(_data, '$.${field}') AS ${quoteIdentifier(field)}`
+        );
+      }
+      return selectParts.join(", ");
+    } else if (hasExcludes) {
+      return "_id, _type, _data";
+    }
+    return "_id, _type, _data";
+  }
+  /**
+   * Build LIMIT clause
+   */
+  buildLimitClause(options) {
+    if (options?.limit && options.limit > 0) {
+      return { sql: options.limit.toString() };
+    }
+    return { sql: "" };
+  }
+  /**
+   * Build pagination WHERE clause from cursor
+   */
+  buildPaginationClause(options, sortFields, sortDirections) {
+    if (!options?.uniqueStartKey || !sortFields || !sortDirections) {
+      return { sql: "", params: [] };
+    }
+    try {
+      const cursor = CursorManager.decodeCursor(options.uniqueStartKey);
+      const direction = options.direction || 1;
+      return CursorManager.buildPaginationConditions(
+        cursor,
+        sortFields,
+        sortDirections,
+        direction,
+        (field) => this.getFieldSql(field)
+      );
+    } catch (error) {
+      console.warn("Invalid cursor provided, ignoring pagination:", error);
+      return { sql: "", params: [] };
+    }
+  }
+  /**
+   * Validate projection fields — skipped in schemaless mode
+   */
+  validateProjection(projection) {
+    if (!this.schema) return;
+    for (const fieldName of Object.keys(projection)) {
+      if (!this.schema.has(fieldName) && !SYSTEM_FIELDS.has(fieldName)) {
+        throw new InvalidFieldError(
+          `Unknown field: ${fieldName} in model ${this.modelName}`,
+          fieldName,
+          this.modelName
+        );
+      }
+    }
+  }
+  /**
+   * Validate operator is supported for field type
+   */
+  validateOperatorForType(operator, fieldType, allowedTypes) {
+    if (!fieldType) {
+      console.warn(`Field type not specified, allowing operator ${operator}`);
+      return;
+    }
+    if (!allowedTypes.includes(fieldType)) {
+      throw new InvalidOperatorError(
+        `Operator ${operator} is not supported for field type ${fieldType}. Allowed types: ${allowedTypes.join(
+          ", "
+        )}`,
+        "unknown",
+        operator,
+        fieldType
+      );
+    }
+  }
+  /**
+   * Validate field value matches expected type
+   */
+  validateFieldValue(fieldName, value) {
+    if (!this.schema) return;
+    const fieldOptions = this.schema.get(fieldName);
+    if (!fieldOptions || !fieldOptions.type) {
+      return;
+    }
+    const expectedType = fieldOptions.type;
+    const actualType = this.getValueType(value);
+    if (!this.isTypeCompatible(expectedType, actualType, value)) {
+      throw new InvalidOperatorError(
+        `Field ${fieldName} expects ${expectedType}, got ${actualType}`,
+        fieldName,
+        "type_mismatch",
+        expectedType
+      );
+    }
+  }
+  /**
+   * Validate array values for $in/$nin operators
+   */
+  validateArrayValues(fieldName, values) {
+    for (const value of values) {
+      this.validateFieldValue(fieldName, value);
+    }
+  }
+  /**
+   * Check if value is a primitive (not an object with operators)
+   */
+  isPrimitiveValue(value) {
+    if (value === null || value === void 0) {
+      return true;
+    }
+    const type = typeof value;
+    return type === "string" || type === "number" || type === "boolean" || value instanceof Date;
+  }
+  /**
+   * Get the type of a value for validation
+   */
+  getValueType(value) {
+    if (value === null || value === void 0) {
+      return "null";
+    }
+    if (value instanceof Date) {
+      return "date";
+    }
+    return typeof value;
+  }
+  /**
+   * Check if value type is compatible with field type
+   */
+  isTypeCompatible(expectedType, actualType, value) {
+    if (actualType === "null") {
+      return true;
+    }
+    switch (expectedType) {
+      case "id":
+        return actualType === "string";
+      // id fields are strings
+      case "string":
+        return actualType === "string";
+      case "number":
+        return actualType === "number" && !isNaN(value);
+      case "boolean":
+        return actualType === "boolean";
+      case "date":
+        return actualType === "date" || actualType === "string" && !isNaN(Date.parse(value));
+      default:
+        return true;
+    }
+  }
+  /**
+   * Convert value for SQLite compatibility
+   */
+  convertValueForSQLite(value) {
+    if (typeof value === "boolean") {
+      return value ? 1 : 0;
+    }
+    return value;
+  }
+  normalizeDocumentIds(documents) {
+    if (documents == null) {
+      return null;
+    }
+    const docArray = Array.isArray(documents) ? documents : [documents];
+    const normalized = docArray.map((doc) => `${doc}`.trim()).filter((doc) => doc.length > 0);
+    if (normalized.length === 0) {
+      return [];
+    }
+    return Array.from(new Set(normalized));
+  }
+  buildDocumentClause(documents) {
+    const normalized = this.normalizeDocumentIds(documents);
+    if (normalized === null) {
+      return null;
+    }
+    if (normalized.length === 0) {
+      return { sql: "1 = 0", params: [] };
+    }
+    const placeholders = normalized.map(() => "?").join(", ");
+    return {
+      sql: `${quoteIdentifier("_meta_doc_id")} IN (${placeholders})`,
+      params: normalized
+    };
+  }
+};
+
+// src/engines/cloudflare/createDocumentDO.ts
+function createDatabaseDO(config = {}) {
+  const hooks = config.hooks;
+  return class DocumentDO {
+    /** @internal */
+    _doState;
+    /** @internal */
+    _engine;
+    /** @internal */
+    _initialized = false;
+    /** @internal — cache for $contains misuse check: "model:field" keys known to be in data_json */
+    _containsMisuseCache = /* @__PURE__ */ new Set();
+    constructor(state, _env) {
+      this._doState = state;
+      this._engine = new DurableObjectEngine({
+        sql: state.storage.sql,
+        storage: state.storage
+      });
+    }
+    get state() {
+      return this._doState;
+    }
+    get engine() {
+      return this._engine;
+    }
+    /** @internal */
+    async _ensureInitialized() {
+      if (!this._initialized) {
+        await this._engine.ensureReady();
+        this._initialized = true;
+      }
+    }
+    async fetch(request) {
+      try {
+        await this._ensureInitialized();
+        const url = new URL(request.url);
+        const path = url.pathname;
+        const docId = url.searchParams.get("docId") || "";
+        if (request.method === "DELETE" && path === "/destroy") {
+          await this._doState.storage.deleteAll();
+          this._initialized = false;
+          this._engine.initialized = false;
+          return Response.json({
+            deleted: true,
+            deletedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+        if (request.method !== "POST" && request.method !== "GET") {
+          return this._errorResponse("Method not allowed", 405);
+        }
+        switch (path) {
+          case "/query":
+            return this._handleQuery(request, docId);
+          case "/save":
+            return this._handleSave(request, docId);
+          case "/patch":
+            return this._handlePatch(request, docId);
+          case "/delete":
+            return this._handleDelete(request, docId);
+          case "/batch":
+            return this._handleBatch(request, docId);
+          case "/count":
+            return this._handleCount(request, docId);
+          case "/aggregate":
+            return this._handleAggregate(request, docId);
+          case "/increment":
+            return this._handleIncrement(request, docId);
+          case "/stringset/add":
+            return this._handleStringSetAdd(request, docId);
+          case "/stringset/remove":
+            return this._handleStringSetRemove(request, docId);
+          case "/indexes/sync":
+            return this._handleIndexesSync(request);
+          case "/index/register":
+            return this._handleIndexRegister(request);
+          case "/index/drop":
+            return this._handleIndexDrop(request);
+          case "/indexes":
+            return this._handleIndexList(request);
+          case "/unique-constraint/register":
+            return this._handleUniqueConstraintRegister(request);
+          case "/unique-constraint/drop":
+            return this._handleUniqueConstraintDrop(request);
+          case "/unique-constraints":
+            return this._handleUniqueConstraintList(request);
+          case "/health":
+            return this._handleHealth();
+          case "/describe":
+            return this._handleDescribe(request);
+          case "/models":
+            return this._handleModelList();
+          default:
+            return this._errorResponse("Not found", 404);
+        }
+      } catch (error) {
+        console.error("DO fetch error:", error);
+        return this._errorResponse(
+          error instanceof Error ? error.message : "Internal error",
+          500
+        );
+      }
+    }
+    /** @internal */
+    async _handleQuery(request, docId) {
+      const body = await request.json();
+      const { modelName, options } = body;
+      let filter = body.filter || {};
+      if (hooks?.beforeQuery) {
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          filter,
+          options
+        };
+        const result = await hooks.beforeQuery(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Query denied", 403);
+        }
+        if (result.injectFilter) {
+          filter = { $and: [filter, result.injectFilter] };
+        }
+      }
+      const misuseError = this._checkContainsMisuse(modelName, filter);
+      if (misuseError) return misuseError;
+      const translator = new JsonQueryTranslator(modelName, void 0, {
+        includeDocId: false
+      });
+      const { sql, params, sortFields } = translator.translateFind(filter, options);
+      const rawResults = this._engine.execSqlSync(sql, params);
+      let data = rawResults.map((row) => this._parseRow(row));
+      if (hooks?.afterQuery) {
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          results: data
+        };
+        const result = await hooks.afterQuery(ctx);
+        data = result.results;
+      }
+      if (options?.include && options.include.length > 0) {
+        data = this._resolveIncludes(data, options.include, 0, modelName);
+      }
+      const limit = options?.limit;
+      const hasMore = CursorManager.hasMoreResults(limit, data.length);
+      const isFirstPage = !options?.uniqueStartKey;
+      const cursors = CursorManager.generateResultCursors(
+        data,
+        sortFields || ["id"],
+        options?.direction || 1,
+        hasMore,
+        isFirstPage
+      );
+      const response = {
+        data,
+        hasMore,
+        ...cursors
+      };
+      return Response.json(response);
+    }
+    /** @internal — Check for reserved field names in record data */
+    _checkReservedFields(data) {
+      for (const key of Object.keys(data)) {
+        if (key === "id") continue;
+        if (key.startsWith("_")) {
+          return `Field '${key}' is reserved (fields starting with '_' are internal)`;
+        }
+      }
+      return null;
+    }
+    /** @internal */
+    async _handleSave(request, docId) {
+      const body = await request.json();
+      const { modelName, id, data, stringSets, ifNotExists, condition } = body;
+      if (!modelName || !id) {
+        return this._errorResponse("modelName and id are required", 400);
+      }
+      if (!data) {
+        return this._errorResponse("data is required", 400);
+      }
+      if (data) {
+        const reservedError = this._checkReservedFields(data);
+        if (reservedError) {
+          return this._errorResponse(reservedError, 400);
+        }
+      }
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      if (ifNotExists && this._engine.recordExists(modelName, id)) {
+        return this._errorResponse(
+          `Record ${modelName}/${id} already exists`,
+          409
+        );
+      }
+      if (hooks?.beforeSave) {
+        const isNew = !this._engine.recordExists(modelName, id);
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          id,
+          data,
+          stringSets,
+          isNew
+        };
+        const result = await hooks.beforeSave(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Save denied", 403);
+        }
+      }
+      const violation = this._engine.checkUniqueConstraints(
+        modelName,
+        id,
+        data
+      );
+      if (violation) {
+        return this._errorResponse(violation, 409);
+      }
+      if (stringSets && Object.keys(stringSets).length > 0) {
+        await this._engine.insertWithStringSets(
+          modelName,
+          { id, ...data },
+          stringSets
+        );
+      } else {
+        await this._engine.insert(modelName, { id, ...data });
+      }
+      this._engine.trackModelFields(modelName, data);
+      const response = { success: true, id };
+      return Response.json(response);
+    }
+    /** @internal — Partial update: merge provided fields into existing record */
+    async _handlePatch(request, docId) {
+      const body = await request.json();
+      const { modelName, id, data, stringSets, condition } = body;
+      if (!modelName || !id || !data) {
+        return this._errorResponse("modelName, id, and data are required", 400);
+      }
+      const reservedError = this._checkReservedFields(data);
+      if (reservedError) {
+        return this._errorResponse(reservedError, 400);
+      }
+      if (!this._engine.recordExists(modelName, id)) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      if (hooks?.beforeSave) {
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          id,
+          data,
+          stringSets,
+          isNew: false
+        };
+        const result = await hooks.beforeSave(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Save denied", 403);
+        }
+      }
+      const existing = this._engine.execSqlSync(
+        "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+        [id, modelName]
+      );
+      if (existing.length > 0) {
+        const existingData = JSON.parse(existing[0]._data);
+        const mergedData = { ...existingData, ...data };
+        const violation = this._engine.checkUniqueConstraints(
+          modelName,
+          id,
+          mergedData
+        );
+        if (violation) {
+          return this._errorResponse(violation, 409);
+        }
+      }
+      const found = this._engine.patchRecord(modelName, id, data, stringSets);
+      if (!found) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      this._engine.trackModelFields(modelName, data);
+      const response = { success: true, id };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleDelete(request, docId) {
+      const body = await request.json();
+      const { modelName, id, condition } = body;
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      if (hooks?.beforeDelete) {
+        let record = null;
+        const rows = this._engine.execSqlSync(
+          "SELECT _id, _type, _data FROM records WHERE _id = ? AND _type = ?",
+          [id, modelName]
+        );
+        if (rows.length > 0) {
+          record = this._parseRow(rows[0]);
+        }
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          id,
+          record
+        };
+        const result = await hooks.beforeDelete(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Delete denied", 403);
+        }
+      }
+      await this._engine.deleteWithStringSets(modelName, id);
+      const response = { success: true };
+      return Response.json(response);
+    }
+    /** @internal — Execute multiple save/patch/delete operations in a single transaction */
+    async _handleBatch(request, docId) {
+      const body = await request.json();
+      const { operations } = body;
+      if (!operations || !Array.isArray(operations) || operations.length === 0) {
+        return this._errorResponse("operations array is required and must not be empty", 400);
+      }
+      const hookDenials = /* @__PURE__ */ new Map();
+      for (let i = 0; i < operations.length; i++) {
+        const op = operations[i];
+        if (!op.modelName || !op.id || !op.op) {
+          return this._errorResponse(
+            `Operation ${i}: modelName, id, and op are required`,
+            400
+          );
+        }
+        if (op.op === "save" || op.op === "patch") {
+          if (!op.data) {
+            return this._errorResponse(
+              `Operation ${i}: data is required for ${op.op}`,
+              400
+            );
+          }
+          const reservedError = this._checkReservedFields(op.data);
+          if (reservedError) {
+            return this._errorResponse(
+              `Operation ${i}: ${reservedError}`,
+              400
+            );
+          }
+          if (hooks?.beforeSave) {
+            const isNew = op.op === "save" ? !this._engine.recordExists(op.modelName, op.id) : false;
+            const ctx = {
+              modelName: op.modelName,
+              docId,
+              request,
+              engine: this._engine,
+              id: op.id,
+              data: op.data,
+              stringSets: op.stringSets,
+              isNew
+            };
+            const result = await hooks.beforeSave(ctx);
+            if (!result.allow) {
+              hookDenials.set(i, result.reason || "Save denied");
+            }
+          }
+        } else if (op.op === "delete") {
+          if (hooks?.beforeDelete) {
+            let record = null;
+            const rows = this._engine.execSqlSync(
+              "SELECT _id, _type, _data FROM records WHERE _id = ? AND _type = ?",
+              [op.id, op.modelName]
+            );
+            if (rows.length > 0) {
+              record = this._parseRow(rows[0]);
+            }
+            const ctx = {
+              modelName: op.modelName,
+              docId,
+              request,
+              engine: this._engine,
+              id: op.id,
+              record
+            };
+            const result = await hooks.beforeDelete(ctx);
+            if (!result.allow) {
+              hookDenials.set(i, result.reason || "Delete denied");
+            }
+          }
+        } else if (op.op === "increment") {
+          if (!op.fields || typeof op.fields !== "object") {
+            return this._errorResponse(
+              `Operation ${i}: fields is required for increment`,
+              400
+            );
+          }
+        } else if (op.op === "addToSet" || op.op === "removeFromSet") {
+          if (!op.stringSets || typeof op.stringSets !== "object") {
+            return this._errorResponse(
+              `Operation ${i}: stringSets is required for ${op.op}`,
+              400
+            );
+          }
+        } else {
+          return this._errorResponse(
+            `Operation ${i}: unknown op '${op.op}'.`,
+            400
+          );
+        }
+      }
+      const results = [];
+      const fieldsToTrack = [];
+      this._engine.transactionSync(() => {
+        for (let i = 0; i < operations.length; i++) {
+          const op = operations[i];
+          if (hookDenials.has(i)) {
+            results.push({
+              success: false,
+              id: op.id,
+              error: hookDenials.get(i)
+            });
+            continue;
+          }
+          if (op.condition && !this._checkCondition(op.modelName, op.id, op.condition)) {
+            results.push({
+              success: false,
+              id: op.id,
+              error: `Condition not met for ${op.modelName}/${op.id}`
+            });
+            continue;
+          }
+          if (op.op === "save") {
+            if (op.ifNotExists && this._engine.recordExists(op.modelName, op.id)) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} already exists`
+              });
+              continue;
+            }
+            if (op.data) {
+              const violation = this._engine.checkUniqueConstraints(
+                op.modelName,
+                op.id,
+                op.data
+              );
+              if (violation) {
+                results.push({
+                  success: false,
+                  id: op.id,
+                  error: violation
+                });
+                continue;
+              }
+            }
+            if (op.stringSets && Object.keys(op.stringSets).length > 0) {
+              const { id: _id, ...fieldsForJson } = op.data;
+              const jsonFields = { ...fieldsForJson, ...op.stringSets };
+              const dataJson = JSON.stringify(jsonFields);
+              this._engine.execSqlSync(
+                "INSERT OR REPLACE INTO records (_id, _type, _data) VALUES (?, ?, ?)",
+                [op.id, op.modelName, dataJson]
+              );
+              this._engine.execSqlSync(
+                "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ?",
+                [op.modelName, op.id]
+              );
+              for (const [fieldName, values] of Object.entries(op.stringSets)) {
+                for (const value of values) {
+                  this._engine.execSqlSync(
+                    "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
+                    [op.id, op.modelName, fieldName, value]
+                  );
+                }
+              }
+            } else {
+              const { id: _id, ...fieldsForJson } = op.data;
+              const dataJson = JSON.stringify(fieldsForJson);
+              this._engine.execSqlSync(
+                "INSERT OR REPLACE INTO records (_id, _type, _data) VALUES (?, ?, ?)",
+                [op.id, op.modelName, dataJson]
+              );
+            }
+            if (op.data) fieldsToTrack.push({ modelName: op.modelName, data: op.data });
+            results.push({ success: true, id: op.id });
+          } else if (op.op === "patch") {
+            if (!this._engine.recordExists(op.modelName, op.id)) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} not found`
+              });
+              continue;
+            }
+            if (op.data) {
+              const existing = this._engine.execSqlSync(
+                "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+                [op.id, op.modelName]
+              );
+              if (existing.length > 0) {
+                const existingData = JSON.parse(existing[0]._data);
+                const mergedData = { ...existingData, ...op.data };
+                const violation = this._engine.checkUniqueConstraints(
+                  op.modelName,
+                  op.id,
+                  mergedData
+                );
+                if (violation) {
+                  results.push({
+                    success: false,
+                    id: op.id,
+                    error: violation
+                  });
+                  continue;
+                }
+              }
+            }
+            const found = this._engine.patchRecordRaw(
+              op.modelName,
+              op.id,
+              op.data,
+              op.stringSets
+            );
+            if (!found) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} not found`
+              });
+            } else {
+              if (op.data) fieldsToTrack.push({ modelName: op.modelName, data: op.data });
+              results.push({ success: true, id: op.id });
+            }
+          } else if (op.op === "delete") {
+            this._engine.execSqlSync(
+              "DELETE FROM records WHERE _id = ? AND _type = ?",
+              [op.id, op.modelName]
+            );
+            this._engine.execSqlSync(
+              "DELETE FROM stringset_index WHERE _record_id = ? AND _type = ?",
+              [op.id, op.modelName]
+            );
+            results.push({ success: true, id: op.id });
+          } else if (op.op === "increment") {
+            const newValues = this._engine.incrementFieldsRaw(
+              op.modelName,
+              op.id,
+              op.fields
+            );
+            if (!newValues) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} not found`
+              });
+            } else {
+              results.push({ success: true, id: op.id, values: newValues });
+            }
+          } else if (op.op === "addToSet") {
+            if (!this._engine.recordExists(op.modelName, op.id)) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} not found`
+              });
+              continue;
+            }
+            this._engine.addToStringSetsRaw(
+              op.modelName,
+              op.id,
+              op.stringSets
+            );
+            results.push({ success: true, id: op.id });
+          } else if (op.op === "removeFromSet") {
+            if (!this._engine.recordExists(op.modelName, op.id)) {
+              results.push({
+                success: false,
+                id: op.id,
+                error: `Record ${op.modelName}/${op.id} not found`
+              });
+              continue;
+            }
+            this._engine.removeFromStringSetsRaw(
+              op.modelName,
+              op.id,
+              op.stringSets
+            );
+            results.push({ success: true, id: op.id });
+          }
+        }
+      });
+      for (const entry of fieldsToTrack) {
+        this._engine.trackModelFields(entry.modelName, entry.data);
+      }
+      const response = { results };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleCount(request, docId) {
+      const body = await request.json();
+      const { modelName } = body;
+      let filter = body.filter || {};
+      if (hooks?.beforeQuery) {
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          filter
+        };
+        const result = await hooks.beforeQuery(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Query denied", 403);
+        }
+        if (result.injectFilter) {
+          filter = { $and: [filter, result.injectFilter] };
+        }
+      }
+      const misuseError = this._checkContainsMisuse(modelName, filter);
+      if (misuseError) return misuseError;
+      const translator = new JsonQueryTranslator(modelName, void 0, {
+        includeDocId: false
+      });
+      const { sql, params } = translator.translateCount(filter);
+      const results = this._engine.execSqlSync(sql, params);
+      const response = { count: results[0]?.count ?? 0 };
+      return Response.json(response);
+    }
+    /** @internal — Atomically increment/decrement numeric fields */
+    async _handleIncrement(request, _docId) {
+      const body = await request.json();
+      const { modelName, id, fields, condition } = body;
+      if (!modelName || !id || !fields) {
+        return this._errorResponse("modelName, id, and fields are required", 400);
+      }
+      if (!this._engine.recordExists(modelName, id)) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      const newValues = this._engine.incrementFields(modelName, id, fields);
+      if (!newValues) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      const response = { success: true, id, values: newValues };
+      return Response.json(response);
+    }
+    /** @internal — Atomically add values to StringSet fields */
+    async _handleStringSetAdd(request, _docId) {
+      const body = await request.json();
+      const { modelName, id, sets, condition } = body;
+      if (!modelName || !id || !sets) {
+        return this._errorResponse("modelName, id, and sets are required", 400);
+      }
+      if (!this._engine.recordExists(modelName, id)) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      this._engine.addToStringSets(modelName, id, sets);
+      const response = { success: true };
+      return Response.json(response);
+    }
+    /** @internal — Atomically remove values from StringSet fields */
+    async _handleStringSetRemove(request, _docId) {
+      const body = await request.json();
+      const { modelName, id, sets, condition } = body;
+      if (!modelName || !id || !sets) {
+        return this._errorResponse("modelName, id, and sets are required", 400);
+      }
+      if (!this._engine.recordExists(modelName, id)) {
+        return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
+      }
+      if (condition && !this._checkCondition(modelName, id, condition)) {
+        return this._errorResponse(
+          `Condition not met for ${modelName}/${id}`,
+          409
+        );
+      }
+      this._engine.removeFromStringSets(modelName, id, sets);
+      const response = { success: true };
+      return Response.json(response);
+    }
+    async _handleAggregate(request, docId) {
+      const body = await request.json();
+      const { modelName, options: aggOptions } = body;
+      if (!modelName || !aggOptions || !aggOptions.groupBy || !aggOptions.operations) {
+        return this._errorResponse(
+          "modelName, options.groupBy, and options.operations are required",
+          400
+        );
+      }
+      for (const op of aggOptions.operations) {
+        if (op.type !== "count" && !op.field) {
+          return this._errorResponse(
+            `Operation '${op.type}' requires a field parameter`,
+            400
+          );
+        }
+        if (op.type === "count" && op.field) {
+          return this._errorResponse(
+            `Operation 'count' should not have a field parameter`,
+            400
+          );
+        }
+      }
+      let filter = aggOptions.filter || {};
+      if (hooks?.beforeQuery) {
+        const ctx = {
+          modelName,
+          docId,
+          request,
+          engine: this._engine,
+          filter
+        };
+        const result = await hooks.beforeQuery(ctx);
+        if (!result.allow) {
+          return this._errorResponse(result.reason || "Query denied", 403);
+        }
+        if (result.injectFilter) {
+          filter = { $and: [filter, result.injectFilter] };
+        }
+      }
+      const misuseError = this._checkContainsMisuse(modelName, filter);
+      if (misuseError) return misuseError;
+      const translator = new JsonQueryTranslator(modelName, void 0, {
+        includeDocId: false
+      });
+      const regularGroupBy = [];
+      const stringSetMemberships = [];
+      let stringSetFacetField = null;
+      for (const groupBy of aggOptions.groupBy) {
+        if (typeof groupBy === "string") {
+          regularGroupBy.push(groupBy);
+        } else {
+          assertValidIdentifier(groupBy.field, "aggregation groupBy field");
+          stringSetMemberships.push(groupBy);
+        }
+      }
+      const confirmedRegular = [];
+      for (const field of regularGroupBy) {
+        assertValidIdentifier(field, "aggregation groupBy field");
+        const ssCheck = this._engine.execSqlSync(
+          "SELECT 1 FROM stringset_index WHERE _type = ? AND field = ? LIMIT 1",
+          [modelName, field]
+        );
+        if (ssCheck.length > 0) {
+          if (stringSetFacetField !== null) {
+            return this._errorResponse(
+              "Multiple StringSet facet fields not supported in single aggregation",
+              400
+            );
+          }
+          stringSetFacetField = field;
+        } else {
+          confirmedRegular.push(field);
+        }
+      }
+      try {
+        let sql;
+        let params = [];
+        const aliasMap = [];
+        if (stringSetFacetField && confirmedRegular.length === 0 && stringSetMemberships.length === 0) {
+          const result = this._buildStringSetFacetSql(
+            modelName,
+            stringSetFacetField,
+            aggOptions,
+            filter,
+            translator
+          );
+          sql = result.sql;
+          params = result.params;
+        } else {
+          const result = this._buildRegularAggregationSql(
+            modelName,
+            confirmedRegular,
+            stringSetMemberships,
+            aggOptions,
+            filter,
+            translator
+          );
+          sql = result.sql;
+          params = result.params;
+          aliasMap.push(...result.aliasMap);
+        }
+        const rawResults = this._engine.execSqlSync(sql, params);
+        const processed = this._processAggregationResults(rawResults, aggOptions, aliasMap, stringSetFacetField);
+        const response = { result: processed };
+        return Response.json(response);
+      } catch (err) {
+        return this._errorResponse(
+          err instanceof Error ? err.message : "Aggregation failed",
+          500
+        );
+      }
+    }
+    /** @internal — Build SQL for StringSet facet aggregation */
+    _buildStringSetFacetSql(modelName, facetField, aggOptions, filter, translator) {
+      const selectParts = ["stringset_index.value AS group_key"];
+      for (const op of aggOptions.operations) {
+        switch (op.type) {
+          case "count":
+            selectParts.push("COUNT(*) AS count");
+            break;
+          case "sum":
+            selectParts.push(`SUM(${translator.getFieldSql(op.field)}) AS sum_${op.field}`);
+            break;
+          case "avg":
+            selectParts.push(`AVG(${translator.getFieldSql(op.field)}) AS avg_${op.field}`);
+            break;
+          case "min":
+            selectParts.push(`MIN(${translator.getFieldSql(op.field)}) AS min_${op.field}`);
+            break;
+          case "max":
+            selectParts.push(`MAX(${translator.getFieldSql(op.field)}) AS max_${op.field}`);
+            break;
+        }
+      }
+      let sql = `SELECT ${selectParts.join(", ")} FROM stringset_index`;
+      sql += ` INNER JOIN records ON stringset_index._record_id = records._id AND records._type = stringset_index._type`;
+      const conditions = [
+        "stringset_index._type = ?",
+        "stringset_index.field = ?"
+      ];
+      const params = [modelName, facetField];
+      if (filter && Object.keys(filter).length > 0) {
+        const whereClause = translator.translateFilter(filter);
+        if (whereClause.sql) {
+          conditions.push(whereClause.sql);
+          params.push(...whereClause.params);
+        }
+      }
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+      sql += " GROUP BY stringset_index.value";
+      if (aggOptions.sort) {
+        const sortExpr = aggOptions.sort.field === "count" ? "COUNT(*)" : aggOptions.sort.field;
+        const dir = aggOptions.sort.direction === 1 ? "ASC" : "DESC";
+        sql += ` ORDER BY ${sortExpr} ${dir}`;
+      }
+      if (aggOptions.limit) {
+        sql += ` LIMIT ${Number(aggOptions.limit)}`;
+      }
+      return { sql, params };
+    }
+    /** @internal — Build SQL for regular field aggregation */
+    _buildRegularAggregationSql(modelName, regularGroupBy, stringSetMemberships, aggOptions, filter, translator) {
+      const selectParts = [];
+      const groupByParts = [];
+      const aliasMap = [];
+      for (const field of regularGroupBy) {
+        const fieldSql = translator.getFieldSql(field);
+        selectParts.push(`${fieldSql} AS "${field}"`);
+        groupByParts.push(fieldSql);
+      }
+      for (let i = 0; i < stringSetMemberships.length; i++) {
+        const m = stringSetMemberships[i];
+        const alias = `ss_${m.field}_${i}`;
+        selectParts.push(
+          `CASE WHEN ${alias}._record_id IS NOT NULL THEN 'true' ELSE 'false' END AS "${alias}"`
+        );
+        groupByParts.push(`CASE WHEN ${alias}._record_id IS NOT NULL THEN 'true' ELSE 'false' END`);
+        aliasMap.push({ alias, field: m.field, contains: m.contains });
+      }
+      for (const op of aggOptions.operations) {
+        switch (op.type) {
+          case "count":
+            selectParts.push("COUNT(*) AS count");
+            break;
+          case "sum":
+            selectParts.push(`SUM(${translator.getFieldSql(op.field)}) AS sum_${op.field}`);
+            break;
+          case "avg":
+            selectParts.push(`AVG(${translator.getFieldSql(op.field)}) AS avg_${op.field}`);
+            break;
+          case "min":
+            selectParts.push(`MIN(${translator.getFieldSql(op.field)}) AS min_${op.field}`);
+            break;
+          case "max":
+            selectParts.push(`MAX(${translator.getFieldSql(op.field)}) AS max_${op.field}`);
+            break;
+        }
+      }
+      let sql = `SELECT ${selectParts.join(", ")} FROM records`;
+      const joinParams = [];
+      for (const entry of aliasMap) {
+        sql += ` LEFT JOIN stringset_index AS ${entry.alias}`;
+        sql += ` ON ${entry.alias}._record_id = records._id`;
+        sql += ` AND ${entry.alias}._type = records._type`;
+        sql += ` AND ${entry.alias}.field = ?`;
+        sql += ` AND ${entry.alias}.value = ?`;
+        joinParams.push(entry.field, entry.contains);
+      }
+      const conditions = ["records._type = ?"];
+      const params = [...joinParams, modelName];
+      if (filter && Object.keys(filter).length > 0) {
+        const whereClause = translator.translateFilter(filter);
+        if (whereClause.sql) {
+          conditions.push(whereClause.sql);
+          params.push(...whereClause.params);
+        }
+      }
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+      if (groupByParts.length > 0) {
+        sql += ` GROUP BY ${groupByParts.join(", ")}`;
+      }
+      if (aggOptions.sort) {
+        const sortField = aggOptions.sort.field;
+        let sortExpr;
+        if (sortField === "count") {
+          sortExpr = "COUNT(*)";
+        } else if (sortField.startsWith("sum_") || sortField.startsWith("avg_") || sortField.startsWith("min_") || sortField.startsWith("max_")) {
+          sortExpr = `"${sortField}"`;
+        } else {
+          const aliasEntry = aliasMap.find((a) => a.alias === sortField);
+          sortExpr = aliasEntry ? `"${sortField}"` : translator.getFieldSql(sortField);
+        }
+        const dir = aggOptions.sort.direction === 1 ? "ASC" : "DESC";
+        sql += ` ORDER BY ${sortExpr} ${dir}`;
+      }
+      if (aggOptions.limit) {
+        sql += ` LIMIT ${Number(aggOptions.limit)}`;
+      }
+      return { sql, params, aliasMap };
+    }
+    /** @internal — Extract operation value(s) from a row. Flattens single-op results. */
+    _extractOpValue(row, operations) {
+      if (operations.length === 1) {
+        const op = operations[0];
+        if (op.type === "count") return row.count;
+        return row[`${op.type}_${op.field}`];
+      }
+      const result = {};
+      for (const op of operations) {
+        if (op.type === "count") {
+          result.count = row.count;
+        } else {
+          result[`${op.type}_${op.field}`] = row[`${op.type}_${op.field}`];
+        }
+      }
+      return result;
+    }
+    /** @internal — Process raw aggregation rows into nested result */
+    _processAggregationResults(results, aggOptions, aliasMap, stringSetFacetField) {
+      if (results.length === 0) return {};
+      if (stringSetFacetField !== null) {
+        const facetResult = {};
+        for (const row of results) {
+          const key = row.group_key;
+          facetResult[key] = this._extractOpValue(row, aggOptions.operations);
+        }
+        return facetResult;
+      }
+      const nestedResult = {};
+      const aliasLookup = /* @__PURE__ */ new Map();
+      for (const entry of aliasMap) {
+        const membershipKey = `${entry.field}::${entry.contains}`;
+        aliasLookup.set(membershipKey, entry.alias);
+      }
+      for (const row of results) {
+        let current = nestedResult;
+        for (let i = 0; i < aggOptions.groupBy.length; i++) {
+          const groupBy = aggOptions.groupBy[i];
+          let key;
+          if (typeof groupBy === "string") {
+            key = String(row[groupBy]);
+          } else {
+            const membershipKey = `${groupBy.field}::${groupBy.contains}`;
+            const alias = aliasLookup.get(membershipKey);
+            key = alias ? row[alias] : "unknown";
+          }
+          if (i === aggOptions.groupBy.length - 1) {
+            current[key] = this._extractOpValue(row, aggOptions.operations);
+          } else {
+            if (!current[key]) current[key] = {};
+            current = current[key];
+          }
+        }
+      }
+      return nestedResult;
+    }
+    /** @internal */
+    /** @internal — Batch sync: compare desired indexes against _indexes table, register missing */
+    async _handleIndexesSync(request) {
+      const body = await request.json();
+      if (!body.models || !Array.isArray(body.models)) {
+        return this._errorResponse("models array is required", 400);
+      }
+      let registered = 0;
+      for (const model of body.models) {
+        if (!model.modelName) continue;
+        const existingIndexes = this._engine.listIndexes(model.modelName);
+        const existingIndexMap = new Map(
+          existingIndexes.map((idx) => [idx.field_name, idx])
+        );
+        const existingConstraints = this._engine.listUniqueConstraints(model.modelName);
+        const existingConstraintSet = new Set(
+          existingConstraints.map((c) => c.constraint_name)
+        );
+        for (const idx of model.indexes || []) {
+          const existing = existingIndexMap.get(idx.fieldName);
+          if (existing) {
+            if (idx.unique && !existing.is_unique) {
+              this._engine.registerIndex(model.modelName, idx.fieldName, idx.fieldType, true);
+              registered++;
+            }
+            continue;
+          }
+          this._engine.registerIndex(model.modelName, idx.fieldName, idx.fieldType, idx.unique);
+          registered++;
+        }
+        for (const uc of model.uniqueConstraints || []) {
+          if (existingConstraintSet.has(uc.name)) continue;
+          this._engine.registerUniqueConstraint(model.modelName, uc.name, uc.fields);
+          registered++;
+        }
+      }
+      const response = { registered };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleIndexRegister(request) {
+      const body = await request.json();
+      const { modelName, fieldName, fieldType, unique } = body;
+      if (!modelName || !fieldName || !fieldType) {
+        return this._errorResponse(
+          "modelName, fieldName, and fieldType are required",
+          400
+        );
+      }
+      this._engine.registerIndex(
+        modelName,
+        fieldName,
+        fieldType,
+        unique || false
+      );
+      const response = {
+        success: true,
+        modelName,
+        fieldName
+      };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleIndexDrop(request) {
+      const body = await request.json();
+      const { modelName, fieldName } = body;
+      if (!modelName || !fieldName) {
+        return this._errorResponse(
+          "modelName and fieldName are required",
+          400
+        );
+      }
+      this._engine.dropIndex(modelName, fieldName);
+      const response = {
+        success: true,
+        modelName,
+        fieldName
+      };
+      return Response.json(response);
+    }
+    /** @internal */
+    _handleIndexList(request) {
+      const url = new URL(request.url);
+      const modelName = url.searchParams.get("modelName") || void 0;
+      const indexes = this._engine.listIndexes(modelName);
+      const response = { indexes };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleUniqueConstraintRegister(request) {
+      const body = await request.json();
+      const { modelName, constraintName, fields } = body;
+      if (!modelName || !constraintName || !fields || !Array.isArray(fields) || fields.length < 2) {
+        return this._errorResponse(
+          "modelName, constraintName, and fields (array with 2+ fields) are required",
+          400
+        );
+      }
+      this._engine.registerUniqueConstraint(modelName, constraintName, fields);
+      const response = {
+        success: true,
+        modelName,
+        constraintName
+      };
+      return Response.json(response);
+    }
+    /** @internal */
+    async _handleUniqueConstraintDrop(request) {
+      const body = await request.json();
+      const { modelName, constraintName } = body;
+      if (!modelName || !constraintName) {
+        return this._errorResponse(
+          "modelName and constraintName are required",
+          400
+        );
+      }
+      this._engine.dropUniqueConstraint(modelName, constraintName);
+      const response = {
+        success: true,
+        modelName,
+        constraintName
+      };
+      return Response.json(response);
+    }
+    /** @internal */
+    _handleUniqueConstraintList(request) {
+      const url = new URL(request.url);
+      const modelName = url.searchParams.get("modelName") || void 0;
+      const constraints = this._engine.listUniqueConstraints(modelName);
+      const response = { constraints };
+      return Response.json(response);
+    }
+    /** @internal */
+    /**
+     * Extract field names that use $contains from a filter tree.
+     * @internal
+     */
+    _findContainsFields(filter) {
+      const fields = [];
+      if (!filter || typeof filter !== "object") return fields;
+      for (const [key, value] of Object.entries(filter)) {
+        if (key === "$and" || key === "$or") {
+          if (Array.isArray(value)) {
+            for (const sub of value) {
+              fields.push(...this._findContainsFields(sub));
+            }
+          }
+        } else if (value && typeof value === "object" && !Array.isArray(value) && "$contains" in value) {
+          fields.push(key);
+        }
+      }
+      return fields;
+    }
+    /**
+     * Check for $contains misuse with caching.
+     * Returns an error Response if misuse is detected, or null if OK.
+     * @internal
+     */
+    _checkContainsMisuse(modelName, filter) {
+      const containsFields = this._findContainsFields(filter);
+      for (const field of containsFields) {
+        assertValidIdentifier(field, "$contains field");
+        const cacheKey = `${modelName}:${field}`;
+        if (this._containsMisuseCache.has(cacheKey)) {
+          return this._errorResponse(
+            `Field '${field}' was saved as regular data, not a StringSet. To use $contains, save the field via stringSets instead of data.`,
+            400
+          );
+        }
+        const check = this._engine.execSqlSync(
+          `SELECT 1 FROM records WHERE _type = ? AND json_type(_data, '$.${field}') IS NOT NULL AND json_type(_data, '$.${field}') != 'array' LIMIT 1`,
+          [modelName]
+        );
+        if (check.length > 0) {
+          this._containsMisuseCache.add(cacheKey);
+          return this._errorResponse(
+            `Field '${field}' was saved as regular data, not a StringSet. To use $contains, save the field via stringSets instead of data.`,
+            400
+          );
+        }
+      }
+      return null;
+    }
+    /**
+     * Check a write condition against the current state of a record.
+     * Returns true if the condition is met (record exists and matches the filter).
+     * Returns false if the record doesn't exist or doesn't match.
+     * @internal
+     */
+    _checkCondition(modelName, id, condition) {
+      const translator = new JsonQueryTranslator(modelName, void 0, {
+        includeDocId: false
+      });
+      const whereClause = translator.translateFilter(condition);
+      let sql = "SELECT 1 FROM records WHERE _id = ? AND _type = ?";
+      const params = [id, modelName];
+      if (whereClause.sql) {
+        sql += ` AND ${whereClause.sql}`;
+        params.push(...whereClause.params);
+      }
+      const rows = this._engine.execSqlSync(sql, params);
+      return rows.length > 0;
+    }
+    _handleHealth() {
+      return Response.json({ status: "ok" });
+    }
+    /** @internal — Return tracked field names and types for a model */
+    _handleDescribe(request) {
+      const url = new URL(request.url);
+      const modelName = url.searchParams.get("modelName") || void 0;
+      if (!modelName) {
+        const body = { error: "modelName query parameter is required" };
+        return Response.json(body, { status: 400 });
+      }
+      const fields = this._engine.getModelFields(modelName);
+      const response = { modelName, fields };
+      return Response.json(response);
+    }
+    /** @internal — List all known model names from records and _model_fields */
+    _handleModelList() {
+      const fromRecords = this._engine.execSqlSync(
+        "SELECT DISTINCT _type FROM records ORDER BY _type"
+      );
+      const fromFields = this._engine.execSqlSync(
+        "SELECT DISTINCT model_name FROM _model_fields ORDER BY model_name"
+      );
+      const fromIndexes = this._engine.execSqlSync(
+        "SELECT DISTINCT model_name FROM _indexes ORDER BY model_name"
+      );
+      const modelSet = /* @__PURE__ */ new Set();
+      for (const row of fromRecords) modelSet.add(row._type);
+      for (const row of fromFields) modelSet.add(row.model_name);
+      for (const row of fromIndexes) modelSet.add(row.model_name);
+      return Response.json({ models: Array.from(modelSet).sort() });
+    }
+    /** @internal */
+    _errorResponse(message, status) {
+      const body = { error: message };
+      return Response.json(body, { status });
+    }
+    /** @internal */
+    _parseRow(row) {
+      const { _id, _type, _data, ...rest } = row;
+      let parsed = {};
+      if (_data) {
+        try {
+          parsed = JSON.parse(_data);
+        } catch (e) {
+          console.warn("Failed to parse _data:", e);
+        }
+      }
+      return { id: _id, type: _type, ...parsed, ...rest };
+    }
+    // ─── Include (Related Data Loading) ──────────────────────────────
+    /** @internal — Validate an IncludeSpec, returning an error message or null */
+    _validateIncludeSpec(spec) {
+      if (!spec.model || typeof spec.model !== "string") {
+        return "include: 'model' is required";
+      }
+      try {
+        assertValidIdentifier(spec.model, "include model");
+      } catch {
+        return `include: invalid model name '${spec.model}'`;
+      }
+      if (spec.type !== "refersTo" && spec.type !== "hasMany" && spec.type !== "refersToMany") {
+        return `include: 'type' must be 'refersTo', 'hasMany', or 'refersToMany', got '${spec.type}'`;
+      }
+      if (spec.type === "refersTo") {
+        if (!spec.sourceField) {
+          return "include refersTo: 'sourceField' is required";
+        }
+        try {
+          assertValidIdentifier(spec.sourceField, "include sourceField");
+        } catch {
+          return `include refersTo: invalid sourceField '${spec.sourceField}'`;
+        }
+      }
+      if (spec.type === "refersToMany") {
+        if (!spec.sourceField) {
+          return "include refersToMany: 'sourceField' is required";
+        }
+        try {
+          assertValidIdentifier(spec.sourceField, "include sourceField");
+        } catch {
+          return `include refersToMany: invalid sourceField '${spec.sourceField}'`;
+        }
+      }
+      if (spec.type === "hasMany") {
+        if (!spec.foreignKey) {
+          return "include hasMany: 'foreignKey' is required";
+        }
+        try {
+          assertValidIdentifier(spec.foreignKey, "include foreignKey");
+        } catch {
+          return `include hasMany: invalid foreignKey '${spec.foreignKey}'`;
+        }
+        if (spec.localField) {
+          try {
+            assertValidIdentifier(spec.localField, "include localField");
+          } catch {
+            return `include hasMany: invalid localField '${spec.localField}'`;
+          }
+        }
+      }
+      if (spec.as) {
+        try {
+          assertValidIdentifier(spec.as, "include as");
+        } catch {
+          return `include: invalid alias '${spec.as}'`;
+        }
+      }
+      if (spec.sort) {
+        for (const field of Object.keys(spec.sort)) {
+          try {
+            assertValidIdentifier(field, "include sort field");
+          } catch {
+            return `include: invalid sort field '${field}'`;
+          }
+        }
+      }
+      return null;
+    }
+    /** @internal — Resolve all includes for a set of records */
+    _resolveIncludes(records, includes, depth, _parentModelName) {
+      if (records.length === 0) return records;
+      if (depth >= 3) return records;
+      for (const spec of includes) {
+        const error = this._validateIncludeSpec(spec);
+        if (error) {
+          console.warn(`[include] Skipping invalid spec: ${error}`);
+          continue;
+        }
+        const resultKey = spec.as || spec.model;
+        for (const rec of records) {
+          if (!rec._related) rec._related = {};
+        }
+        if (spec.type === "refersTo") {
+          this._resolveRefersTo(records, spec, resultKey);
+        } else if (spec.type === "refersToMany") {
+          this._resolveRefersToMany(records, spec, resultKey);
+        } else {
+          this._resolveHasMany(records, spec, resultKey);
+        }
+        if (spec.include && spec.include.length > 0) {
+          const allRelated = [];
+          for (const rec of records) {
+            const val = rec._related[resultKey];
+            if (Array.isArray(val)) {
+              allRelated.push(...val);
+            } else if (val) {
+              allRelated.push(val);
+            }
+          }
+          if (allRelated.length > 0) {
+            this._resolveIncludes(allRelated, spec.include, depth + 1, spec.model);
+          }
+        }
+      }
+      return records;
+    }
+    /** @internal — Resolve a refersTo include (parent FK → single related record) */
+    _resolveRefersTo(records, spec, resultKey) {
+      const sourceField = spec.sourceField;
+      const uniqueValues = [
+        ...new Set(
+          records.map((r) => r[sourceField]).filter((v) => v != null && v !== "")
+        )
+      ];
+      if (uniqueValues.length === 0) {
+        for (const rec of records) {
+          rec._related[resultKey] = null;
+        }
+        return;
+      }
+      const related = this._chunkedIn(
+        spec.model,
+        "id",
+        uniqueValues,
+        spec.filter,
+        { projection: spec.projection }
+      );
+      const lookupMap = /* @__PURE__ */ new Map();
+      for (const r of related) {
+        lookupMap.set(r.id, r);
+      }
+      for (const rec of records) {
+        const fk = rec[sourceField];
+        rec._related[resultKey] = fk && lookupMap.get(fk) || null;
+      }
+    }
+    /** @internal — Resolve a refersToMany include (parent StringSet field → array of related records) */
+    _resolveRefersToMany(records, spec, resultKey) {
+      const sourceField = spec.sourceField;
+      const allTargetIds = /* @__PURE__ */ new Set();
+      for (const rec of records) {
+        const values = rec[sourceField];
+        if (Array.isArray(values)) {
+          for (const v of values) {
+            if (v != null && v !== "") allTargetIds.add(v);
+          }
+        }
+      }
+      if (allTargetIds.size === 0) {
+        for (const rec of records) {
+          rec._related[resultKey] = [];
+        }
+        return;
+      }
+      const targets = this._chunkedIn(
+        spec.model,
+        "id",
+        [...allTargetIds],
+        spec.filter,
+        { projection: spec.projection }
+      );
+      const targetLookup = /* @__PURE__ */ new Map();
+      for (const t of targets) {
+        targetLookup.set(t.id, t);
+      }
+      for (const rec of records) {
+        const values = rec[sourceField];
+        if (Array.isArray(values)) {
+          rec._related[resultKey] = values.map((id) => targetLookup.get(id)).filter(Boolean);
+        } else {
+          rec._related[resultKey] = [];
+        }
+      }
+    }
+    /** @internal — Resolve a hasMany include (target FK → array of related records) */
+    _resolveHasMany(records, spec, resultKey) {
+      const localField = spec.localField || "id";
+      const uniqueValues = [
+        ...new Set(
+          records.map((r) => r[localField]).filter((v) => v != null && v !== "")
+        )
+      ];
+      if (uniqueValues.length === 0) {
+        for (const rec of records) {
+          rec._related[resultKey] = [];
+        }
+        return;
+      }
+      let related;
+      if (spec.limit) {
+        related = this._resolveHasManyWithLimit(spec, uniqueValues);
+      } else {
+        related = this._resolveHasManySimple(spec, uniqueValues);
+      }
+      const foreignKey = spec.foreignKey;
+      const grouped = /* @__PURE__ */ new Map();
+      for (const r of related) {
+        const fk = r[foreignKey];
+        if (!grouped.has(fk)) grouped.set(fk, []);
+        grouped.get(fk).push(r);
+      }
+      if (spec.projection) {
+        for (const [key, list] of grouped) {
+          grouped.set(
+            key,
+            list.map((r) => this._applyProjection(r, spec.projection))
+          );
+        }
+      }
+      for (const rec of records) {
+        rec._related[resultKey] = grouped.get(rec[localField]) || [];
+      }
+    }
+    /** @internal — Simple hasMany without per-parent limit */
+    _resolveHasManySimple(spec, parentValues) {
+      return this._chunkedIn(
+        spec.model,
+        spec.foreignKey,
+        parentValues,
+        spec.filter,
+        { sort: spec.sort }
+      );
+    }
+    /** @internal — hasMany with per-parent limit using ROW_NUMBER() */
+    _resolveHasManyWithLimit(spec, parentValues) {
+      const foreignKey = spec.foreignKey;
+      assertValidIdentifier(foreignKey, "include foreignKey");
+      let sortClause = `"_id" ASC`;
+      if (spec.sort) {
+        const parts = [];
+        for (const [field, dir] of Object.entries(spec.sort)) {
+          assertValidIdentifier(field, "include sort field");
+          const fieldSql = field === "id" ? `"_id"` : field === "type" ? `"_type"` : `json_extract(_data, '$.${field}')`;
+          parts.push(`${fieldSql} ${dir === -1 ? "DESC" : "ASC"}`);
+        }
+        sortClause = parts.join(", ");
+      }
+      const translator = new JsonQueryTranslator(spec.model, void 0, {
+        includeDocId: false
+      });
+      let filterClause = "";
+      let filterParams = [];
+      if (spec.filter) {
+        const translated = translator.translateFilter(spec.filter);
+        if (translated.sql) {
+          filterClause = ` AND ${translated.sql}`;
+          filterParams = translated.params;
+        }
+      }
+      const reservedParams = 1 + filterParams.length + 1;
+      const chunkSize = Math.max(1, 100 - reservedParams);
+      const allResults = [];
+      for (let i = 0; i < parentValues.length; i += chunkSize) {
+        const chunk = parentValues.slice(i, i + chunkSize);
+        const inPlaceholders = chunk.map(() => "?").join(", ");
+        const sql = `
+          SELECT "_id", "_type", _data FROM (
+            SELECT "_id", "_type", _data,
+              ROW_NUMBER() OVER (
+                PARTITION BY json_extract(_data, '$.${foreignKey}')
+                ORDER BY ${sortClause}
+              ) as _rn
+            FROM records
+            WHERE "_type" = ?
+              AND json_extract(_data, '$.${foreignKey}') IN (${inPlaceholders})
+              ${filterClause}
+          ) WHERE _rn <= ?
+        `;
+        const params = [spec.model, ...chunk, ...filterParams, spec.limit];
+        const rows = this._engine.execSqlSync(sql, params);
+        allResults.push(...rows.map((row) => this._parseRow(row)));
+      }
+      return allResults;
+    }
+    /**
+     * @internal — Execute IN queries in chunks to stay under Cloudflare DO's
+     * 100 bound parameter limit per SQL statement.
+     */
+    _chunkedIn(model, field, values, extraFilter, extraOptions) {
+      const translator = new JsonQueryTranslator(model, void 0, {
+        includeDocId: false
+      });
+      let filterParamCount = 0;
+      if (extraFilter) {
+        const translated = translator.translateFilter(extraFilter);
+        filterParamCount = translated.params.length;
+      }
+      const reservedParams = 1 + filterParamCount;
+      const chunkSize = Math.max(1, 100 - reservedParams);
+      const allResults = [];
+      for (let i = 0; i < values.length; i += chunkSize) {
+        const chunk = values.slice(i, i + chunkSize);
+        const filter = {
+          [field]: { $in: chunk },
+          ...extraFilter || {}
+        };
+        const options = {};
+        if (extraOptions?.sort) options.sort = extraOptions.sort;
+        if (extraOptions?.projection) options.projection = extraOptions.projection;
+        const { sql, params } = translator.translateFind(filter, options);
+        const rows = this._engine.execSqlSync(sql, params);
+        allResults.push(...rows.map((row) => this._parseRow(row)));
+      }
+      return allResults;
+    }
+    /** @internal — Apply projection to a single record */
+    _applyProjection(record, projection) {
+      const fields = Object.entries(projection);
+      if (fields.length === 0) return record;
+      const isInclusion = fields.some(([, v]) => v === 1);
+      if (isInclusion) {
+        const result = {};
+        if (record.id !== void 0) result.id = record.id;
+        if (record.type !== void 0) result.type = record.type;
+        if (record._related !== void 0) result._related = record._related;
+        for (const [f, v] of fields) {
+          if (v === 1 && record[f] !== void 0) {
+            result[f] = record[f];
+          }
+        }
+        return result;
+      } else {
+        const result = { ...record };
+        for (const [f, v] of fields) {
+          if (v === 0) delete result[f];
+        }
+        return result;
+      }
+    }
+  };
+}
+var createDocumentDO = createDatabaseDO;
+
+// src/engines/cloudflare/worker.template.ts
+var CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization"
+};
+function handleOptions() {
+  return new Response(null, {
+    status: 204,
+    headers: CORS_HEADERS
+  });
+}
+function addCorsHeaders(response) {
+  const newHeaders = new Headers(response.headers);
+  for (const [key, value] of Object.entries(CORS_HEADERS)) {
+    newHeaders.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: newHeaders
+  });
+}
+function getDocumentStub(env, docId) {
+  const doId = env.DOCUMENT_DO.idFromName(docId);
+  return env.DOCUMENT_DO.get(doId);
+}
+async function handleRequest(request, env) {
+  if (request.method === "OPTIONS") {
+    return handleOptions();
+  }
+  const url = new URL(request.url);
+  let docId = url.searchParams.get("docId");
+  if (!docId) {
+    const pathMatch = url.pathname.match(/^\/docs\/([^\/]+)\/(.+)$/);
+    if (pathMatch) {
+      docId = pathMatch[1];
+      url.pathname = "/" + pathMatch[2];
+    }
+  }
+  if (!docId) {
+    return addCorsHeaders(
+      Response.json(
+        { error: "Missing docId parameter" },
+        { status: 400 }
+      )
+    );
+  }
+  const stub = getDocumentStub(env, docId);
+  const doRequest = new Request(url.toString(), {
+    method: request.method,
+    headers: request.headers,
+    body: request.body
+  });
+  const response = await stub.fetch(doRequest);
+  return addCorsHeaders(response);
+}