js-bao 0.2.11 → 0.2.12

package/dist/chunk-6UX3YSCW.js

@@ -0,0 +1,4151 @@
+// src/models/BaseModel.ts
+import * as Y from "yjs";
+import { ulid } from "ulid";
+
+// src/models/StringSet.ts
+var StringSet = class _StringSet {
+  _values;
+  _model;
+  _fieldName;
+  constructor(model, fieldName, initialValues = []) {
+    this._model = model;
+    this._fieldName = fieldName;
+    this._values = new Set(initialValues);
+  }
+  /**
+   * Add a string to the set
+   */
+  add(value) {
+    if (typeof value !== "string") {
+      throw new Error("StringSet can only contain string values");
+    }
+    if (!this._values.has(value)) {
+      this._values.add(value);
+      this._model.markStringSetChange(this._fieldName, "add", value);
+    }
+  }
+  /**
+   * Remove a string from the set
+   */
+  remove(value) {
+    if (this._values.has(value)) {
+      this._values.delete(value);
+      this._model.markStringSetChange(this._fieldName, "remove", value);
+    }
+  }
+  /**
+   * Check if the set contains a string
+   */
+  has(value) {
+    return this._values.has(value);
+  }
+  /**
+   * Clear all strings from the set
+   */
+  clear() {
+    if (this._values.size > 0) {
+      this._values.clear();
+      this._model.markStringSetChange(this._fieldName, "clear");
+    }
+  }
+  /**
+   * Get the number of strings in the set
+   */
+  get size() {
+    return this._values.size;
+  }
+  /**
+   * Get an iterator of all values
+   */
+  values() {
+    return this._values.values();
+  }
+  /**
+   * Make the StringSet iterable
+   */
+  [Symbol.iterator]() {
+    return this._values[Symbol.iterator]();
+  }
+  /**
+   * Convert to array
+   */
+  toArray() {
+    return Array.from(this._values);
+  }
+  /**
+   * Union with another StringSet
+   */
+  union(other) {
+    const result = new _StringSet(this._model, this._fieldName, this.toArray());
+    for (const value of other) {
+      result._values.add(value);
+    }
+    return result;
+  }
+  /**
+   * Intersection with another StringSet
+   */
+  intersection(other) {
+    const result = new _StringSet(this._model, this._fieldName);
+    for (const value of this._values) {
+      if (other.has(value)) {
+        result._values.add(value);
+      }
+    }
+    return result;
+  }
+  /**
+   * Difference with another StringSet (values in this set but not in other)
+   */
+  difference(other) {
+    const result = new _StringSet(this._model, this._fieldName);
+    for (const value of this._values) {
+      if (!other.has(value)) {
+        result._values.add(value);
+      }
+    }
+    return result;
+  }
+  /**
+   * Get the current state including pending changes
+   * This is used internally by the model to determine the current view
+   */
+  _getCurrentState() {
+    return new Set(this._values);
+  }
+  /**
+   * Update the internal state (used when loading from Yjs or applying changes)
+   */
+  _updateInternalState(values) {
+    this._values = new Set(values);
+  }
+};
+
+// src/types/documentTypes.ts
+var DocumentClosedError = class extends Error {
+  code = "ERR_DOC_CLOSED";
+  constructor(message) {
+    super(message);
+    this.name = "DocumentClosedError";
+  }
+};
+var DocumentResolutionError = class extends Error {
+  code = "ERR_DOC_UNRESOLVED";
+  constructor(message) {
+    super(message);
+    this.name = "DocumentResolutionError";
+  }
+};
+
+// 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/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, '""')}"`;
+}
+function deterministicIdentifierHash(value) {
+  let hash = 0;
+  for (let i = 0; i < value.length; i++) {
+    hash = (hash << 5) - hash + value.charCodeAt(i);
+    hash |= 0;
+  }
+  const positiveHash = hash === 0 ? 0 : Math.abs(hash);
+  return positiveHash.toString(36);
+}
+function buildSafeAlias(prefix, rawDescriptor) {
+  const suffix = deterministicIdentifierHash(rawDescriptor);
+  const candidate = `${prefix}_${suffix}`;
+  assertValidIdentifier(candidate, "Alias generation");
+  return candidate;
+}
+
+// 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/DocumentQueryTranslator.ts
+var SYSTEM_FIELDS = /* @__PURE__ */ new Set(["id", "type"]);
+var DocumentQueryTranslator = class {
+  modelName;
+  schema;
+  tableName;
+  quotedTableName;
+  fieldSqlCache;
+  constructor(modelName, schema) {
+    this.modelName = modelName;
+    this.schema = schema;
+    this.tableName = `model_${modelName.toLowerCase()}`;
+    this.quotedTableName = quoteIdentifier(this.tableName);
+    this.fieldSqlCache = /* @__PURE__ */ new Map();
+  }
+  getQuotedField(fieldName) {
+    if (!this.fieldSqlCache.has(fieldName)) {
+      if (!this.schema.has(fieldName) && !SYSTEM_FIELDS.has(fieldName)) {
+        throw new InvalidFieldError(
+          `Unknown field: ${fieldName} in model ${this.modelName}`,
+          fieldName,
+          this.modelName
+        );
+      }
+      this.fieldSqlCache.set(fieldName, quoteIdentifier(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.getQuotedField(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 ${this.quotedTableName}`;
+    const params = [];
+    const conditions = [];
+    if (whereClause.sql) {
+      conditions.push(whereClause.sql);
+      params.push(...whereClause.params);
+    }
+    if (paginationClause.sql) {
+      conditions.push(paginationClause.sql);
+      params.push(...paginationClause.params);
+    }
+    const documentClause = this.buildDocumentClause(options?.documents);
+    if (documentClause) {
+      conditions.push(documentClause.sql);
+      params.push(...documentClause.params);
+    }
+    if (conditions.length > 0) {
+      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 documentClause = this.buildDocumentClause(options?.documents);
+    const conditions = [];
+    const params = [];
+    if (whereClause.sql) {
+      conditions.push(whereClause.sql);
+      params.push(...whereClause.params);
+    }
+    if (documentClause) {
+      conditions.push(documentClause.sql);
+      params.push(...documentClause.params);
+    }
+    let sql = `SELECT COUNT(*) as count FROM ${this.quotedTableName}`;
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    return {
+      sql,
+      params
+    };
+  }
+  /**
+   * Translate document filter to SQL WHERE clause
+   */
+  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 column = this.getQuotedField(fieldName);
+    if (condition === null || condition === void 0) {
+      return { sql: `${column} IS NULL`, params: [] };
+    }
+    if (this.isPrimitiveValue(condition)) {
+      this.validateFieldValue(fieldName, condition);
+      return {
+        sql: `${column} = ?`,
+        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: `${column} 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 column = this.getQuotedField(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 !== "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 === "string") {
+          const likeSql = `${column} LIKE ? ESCAPE '\\' COLLATE NOCASE`;
+          conditions.push(likeSql);
+          params.push(pattern);
+        } else {
+          const junctionTableName = `${this.tableName}_${fieldName}`;
+          const foreignKeyColumn = `${this.modelName.toLowerCase()}_id`;
+          const quotedJunctionTable = quoteIdentifier(junctionTableName);
+          const quotedForeignKey = quoteIdentifier(foreignKeyColumn);
+          const quotedValueColumn = quoteIdentifier("value");
+          const quotedPrimaryKey = quoteIdentifier("id");
+          const likeSql = `EXISTS (SELECT 1 FROM ${quotedJunctionTable} WHERE ${quotedJunctionTable}.${quotedForeignKey} = ${this.quotedTableName}.${quotedPrimaryKey} AND ${quotedJunctionTable}.${quotedValueColumn} 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 column = this.getQuotedField(fieldName);
+    switch (operator) {
+      case "$eq":
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} = ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$ne":
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} != ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$gt":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} > ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$gte":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} >= ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$lt":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} < ?`,
+          params: [this.convertValueForSQLite(value)]
+        };
+      case "$lte":
+        this.validateOperatorForType(operator, fieldType, [
+          "id",
+          "string",
+          "number",
+          "date"
+        ]);
+        this.validateFieldValue(fieldName, value);
+        return {
+          sql: `${column} <= ?`,
+          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: `${column} 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: `${column} 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
+          );
+        }
+        return value ? { sql: `${column} IS NOT NULL`, params: [] } : { sql: `${column} IS NULL`, params: [] };
+      case "$contains":
+        if (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 stringset field ${fieldName}`,
+            fieldName,
+            operator,
+            fieldType
+          );
+        }
+        const junctionTableName = `${this.tableName}_${fieldName}`;
+        const foreignKeyColumn = `${this.modelName.toLowerCase()}_id`;
+        const quotedJunctionTable = quoteIdentifier(junctionTableName);
+        const quotedForeignKey = quoteIdentifier(foreignKeyColumn);
+        const quotedValueColumn = quoteIdentifier("value");
+        const quotedPrimaryKey = quoteIdentifier("id");
+        return {
+          sql: `EXISTS (SELECT 1 FROM ${quotedJunctionTable} WHERE ${quotedJunctionTable}.${quotedForeignKey} = ${this.quotedTableName}.${quotedPrimaryKey} AND ${quotedJunctionTable}.${quotedValueColumn} = ?)`,
+          params: [value]
+        };
+      default:
+        throw new InvalidOperatorError(
+          `Unsupported operator: ${operator} for field ${fieldName}`,
+          fieldName,
+          operator,
+          fieldType
+        );
+    }
+  }
+  /**
+   * Build SELECT clause based on projection
+   */
+  buildSelectClause(projection) {
+    if (!projection || Object.keys(projection).length === 0) {
+      return "*";
+    }
+    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 quoted = includeFields.map((field) => this.getQuotedField(field));
+      return quoted.join(", ");
+    } else if (hasExcludes) {
+      const allFields = Array.from(this.schema.keys());
+      const selectedFields = allFields.filter(
+        (field) => !excludeFields.includes(field)
+      );
+      const quoted = selectedFields.map((field) => this.getQuotedField(field));
+      return quoted.join(", ");
+    }
+    return "*";
+  }
+  /**
+   * 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.getQuotedField(field)
+      );
+    } catch (error) {
+      console.warn("Invalid cursor provided, ignoring pagination:", error);
+      return { sql: "", params: [] };
+    }
+  }
+  /**
+   * Validate that field exists in schema
+   */
+  validateField(fieldName) {
+    if (!this.schema.has(fieldName) && !SYSTEM_FIELDS.has(fieldName)) {
+      throw new InvalidFieldError(
+        `Unknown field: ${fieldName} in model ${this.modelName}`,
+        fieldName,
+        this.modelName
+      );
+    }
+  }
+  /**
+   * Validate projection fields
+   */
+  validateProjection(projection) {
+    for (const fieldName of Object.keys(projection)) {
+      this.validateField(fieldName);
+    }
+  }
+  /**
+   * 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) {
+    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/models/BaseModel.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["SILENT"] = 0] = "SILENT";
+  LogLevel2[LogLevel2["ERROR"] = 1] = "ERROR";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["INFO"] = 3] = "INFO";
+  LogLevel2[LogLevel2["DEBUG"] = 4] = "DEBUG";
+  LogLevel2[LogLevel2["VERBOSE"] = 5] = "VERBOSE";
+  return LogLevel2;
+})(LogLevel || {});
+var Logger = class {
+  static _logLevel = 1 /* ERROR */;
+  static _logCallback = null;
+  static setLogLevel(level) {
+    this._logLevel = level;
+  }
+  static getLogLevel() {
+    return this._logLevel;
+  }
+  static setLogCallback(callback) {
+    this._logCallback = callback;
+  }
+  static error(message, ...args) {
+    if (this._logLevel >= 1 /* ERROR */) {
+      const fullMessage = args.length > 0 ? `${message} ${args.map(
+        (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+      ).join(" ")}` : message;
+      console.error(`[ERROR] ${message}`, ...args);
+      if (this._logCallback) {
+        this._logCallback(fullMessage, 1 /* ERROR */);
+      }
+    }
+  }
+  static warn(message, ...args) {
+    if (this._logLevel >= 2 /* WARN */) {
+      const fullMessage = args.length > 0 ? `${message} ${args.map(
+        (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+      ).join(" ")}` : message;
+      console.warn(`[WARN] ${message}`, ...args);
+      if (this._logCallback) {
+        this._logCallback(fullMessage, 2 /* WARN */);
+      }
+    }
+  }
+  static info(message, ...args) {
+    if (this._logLevel >= 3 /* INFO */) {
+      const fullMessage = args.length > 0 ? `${message} ${args.map(
+        (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+      ).join(" ")}` : message;
+      console.log(`[INFO] ${message}`, ...args);
+      if (this._logCallback) {
+        this._logCallback(fullMessage, 3 /* INFO */);
+      }
+    }
+  }
+  static debug(message, ...args) {
+    if (this._logLevel >= 4 /* DEBUG */) {
+      const fullMessage = args.length > 0 ? `${message} ${args.map(
+        (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+      ).join(" ")}` : message;
+      console.log(`[DEBUG] ${message}`, ...args);
+      if (this._logCallback) {
+        this._logCallback(fullMessage, 4 /* DEBUG */);
+      }
+    }
+  }
+  static verbose(message, ...args) {
+    if (this._logLevel >= 5 /* VERBOSE */) {
+      const fullMessage = args.length > 0 ? `${message} ${args.map(
+        (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+      ).join(" ")}` : message;
+      console.log(`[VERBOSE] ${message}`, ...args);
+      if (this._logCallback) {
+        this._logCallback(fullMessage, 5 /* VERBOSE */);
+      }
+    }
+  }
+};
+var UniqueConstraintViolationError = class _UniqueConstraintViolationError extends Error {
+  modelName;
+  constraintName;
+  fields;
+  recordIdAttempted;
+  // ID of the record that failed to save/update
+  conflictingRecordId;
+  // ID of the record that already has the unique value
+  constructor(message, modelName, constraintName, fields, recordIdAttempted, conflictingRecordId) {
+    super(message);
+    this.name = "UniqueConstraintViolationError";
+    this.modelName = modelName;
+    this.constraintName = constraintName;
+    this.fields = fields;
+    this.recordIdAttempted = recordIdAttempted;
+    this.conflictingRecordId = conflictingRecordId;
+    Object.setPrototypeOf(this, _UniqueConstraintViolationError.prototype);
+  }
+};
+var RecordNotFoundError = class _RecordNotFoundError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RecordNotFoundError";
+    Object.setPrototypeOf(this, _RecordNotFoundError.prototype);
+  }
+};
+function generateULID() {
+  return ulid();
+}
+var SCHEMA_ACCESSORS_KEY = /* @__PURE__ */ Symbol("jsBaoSchemaAccessors");
+var BaseModel = class _BaseModel {
+  static modelName;
+  static listenersMap = /* @__PURE__ */ new Map();
+  // Default document resolution mappings (session-scoped)
+  static modelNameToDefaultDocId = /* @__PURE__ */ new Map();
+  static globalDefaultDocId;
+  static defaultDocChangedListeners = /* @__PURE__ */ new Set();
+  static modelDocMappingChangedListeners = /* @__PURE__ */ new Set();
+  // These were for tracking initialization state, which is now more centralized in ModelRegistry
+  // and the main initializeORM flow. We'll rely on the Model's static `initialize` method.
+  // private static initializedModels: Set<string> = new Set();
+  // private static initializationPromises: Map<string, Promise<void>> = new Map();
+  // Default document constants for legacy mode compatibility
+  static DEFAULT_LEGACY_DOC_ID = "__legacy_default__";
+  // private static readonly DEFAULT_PERMISSION: DocumentPermissionHint = "read-write";
+  // dbInstance will be set per model via its static initialize, but query methods need access.
+  // This will be a single instance shared across all models once initialized.
+  static dbInstance = null;
+  // Multi-document management (now used for both legacy and multi-document modes)
+  static connectedDocuments = /* @__PURE__ */ new Map();
+  static documentYMaps = /* @__PURE__ */ new Map();
+  // Maps docId to YMap for that document
+  // Copy-on-write state management
+  _localChanges = null;
+  _isDirty = false;
+  _isLoadingFromYjs = false;
+  // Flag to distinguish loading vs user changes
+  // StringSet field caching
+  _stringSetFields = /* @__PURE__ */ new Map();
+  // Multi-document instance metadata
+  _metaDocId = null;
+  _metaPermissionHint = null;
+  /**
+   * Returns the document id this instance is associated with, or null if not resolved yet.
+   */
+  getDocumentId() {
+    return this._metaDocId;
+  }
+  // id is now a plain property. Subclasses will define it with @Field.
+  id;
+  type;
+  // This should be the modelName from ModelOptions
+  // Static logging methods
+  static setLogLevel(level) {
+    Logger.setLogLevel(level);
+  }
+  static getLogLevel() {
+    return Logger.getLogLevel();
+  }
+  // ---- Default doc resolution: static APIs ----
+  static setModelDefaultDocumentId(modelName, docId) {
+    const previous = this.modelNameToDefaultDocId.get(modelName);
+    this.modelNameToDefaultDocId.set(modelName, docId);
+    for (const listener of this.modelDocMappingChangedListeners) {
+      try {
+        listener({ modelName, previous, current: docId });
+      } catch {
+      }
+    }
+  }
+  static removeModelDefaultDocumentId(modelName) {
+    const previous = this.modelNameToDefaultDocId.get(modelName);
+    this.modelNameToDefaultDocId.delete(modelName);
+    for (const listener of this.modelDocMappingChangedListeners) {
+      try {
+        listener({ modelName, previous, current: void 0 });
+      } catch {
+      }
+    }
+  }
+  static clearModelDefaultDocumentIds() {
+    const entries = Array.from(this.modelNameToDefaultDocId.entries());
+    this.modelNameToDefaultDocId.clear();
+    for (const [modelName, previous] of entries) {
+      for (const listener of this.modelDocMappingChangedListeners) {
+        try {
+          listener({ modelName, previous, current: void 0 });
+        } catch {
+        }
+      }
+    }
+  }
+  static setGlobalDefaultDocumentId(docId) {
+    const previous = this.globalDefaultDocId;
+    this.globalDefaultDocId = docId;
+    for (const listener of this.defaultDocChangedListeners) {
+      try {
+        listener({ previous, current: docId });
+      } catch {
+      }
+    }
+  }
+  static clearGlobalDefaultDocumentId() {
+    const previous = this.globalDefaultDocId;
+    this.globalDefaultDocId = void 0;
+    for (const listener of this.defaultDocChangedListeners) {
+      try {
+        listener({ previous, current: void 0 });
+      } catch {
+      }
+    }
+  }
+  static getModelDefaultDocumentMapping() {
+    return Object.fromEntries(this.modelNameToDefaultDocId.entries());
+  }
+  static getDocumentIdForModel(modelName) {
+    return this.modelNameToDefaultDocId.get(modelName);
+  }
+  static getGlobalDefaultDocumentId() {
+    return this.globalDefaultDocId;
+  }
+  static onDefaultDocChanged(listener) {
+    this.defaultDocChangedListeners.add(listener);
+    return () => this.defaultDocChangedListeners.delete(listener);
+  }
+  static onModelDocMappingChanged(listener) {
+    this.modelDocMappingChangedListeners.add(listener);
+    return () => this.modelDocMappingChangedListeners.delete(listener);
+  }
+  // Helper used by DocumentManager to clear mappings for a given docId when disconnected
+  static _clearMappingsForDocId(docId) {
+    const toRemove = [];
+    for (const [modelName, mappedDocId] of this.modelNameToDefaultDocId) {
+      if (mappedDocId === docId) {
+        toRemove.push(modelName);
+      }
+    }
+    for (const modelName of toRemove) {
+      this.removeModelDefaultDocumentId(modelName);
+    }
+    if (this.globalDefaultDocId === docId) {
+      this.clearGlobalDefaultDocumentId();
+    }
+  }
+  static attachFieldAccessorsSet(modelClass) {
+    const existing = modelClass[SCHEMA_ACCESSORS_KEY] ?? /* @__PURE__ */ new Set();
+    modelClass[SCHEMA_ACCESSORS_KEY] = existing;
+    return existing;
+  }
+  static attachFieldAccessors(modelClass, fields) {
+    const attached = _BaseModel.attachFieldAccessorsSet(modelClass);
+    const prototype = modelClass.prototype;
+    for (const fieldName of fields.keys()) {
+      if (fieldName === "id") continue;
+      if (attached.has(fieldName)) continue;
+      const existingDescriptor = Object.getOwnPropertyDescriptor(
+        prototype,
+        fieldName
+      );
+      if (existingDescriptor && !existingDescriptor.configurable) {
+        continue;
+      }
+      Object.defineProperty(prototype, fieldName, {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return this.getValue(fieldName);
+        },
+        set(value) {
+          this.setValue(fieldName, value);
+        }
+      });
+      attached.add(fieldName);
+    }
+  }
+  constructor(data = {}) {
+    if (new.target === _BaseModel) {
+      throw new Error("BaseModel cannot be instantiated directly.");
+    }
+    const modelConstructor = this.constructor;
+    const schema = modelConstructor.getSchema();
+    const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
+    if (!schema || !schema.fields) {
+      throw new Error(
+        `[${modelConstructor.name}] Schema not loaded. Ensure the model is properly initialized.`
+      );
+    }
+    if (verboseEnabled) {
+      Logger.verbose(
+        `BaseModel Constructor - ${modelConstructor.name}: Initializing with data:`,
+        data
+      );
+      Logger.verbose(
+        `BaseModel Constructor - ${modelConstructor.name}: Schema fields received:`,
+        schema.fields
+      );
+    }
+    const idFieldOptions = schema.fields.get("id");
+    if (data.id) {
+      this.id = data.id;
+    } else if (idFieldOptions?.autoAssign) {
+      this.id = generateULID();
+    } else if (idFieldOptions?.default) {
+      this.id = typeof idFieldOptions.default === "function" ? idFieldOptions.default() : idFieldOptions.default;
+    } else {
+      throw new Error(
+        `[${modelConstructor.name}] No ID provided and no autoAssign or default configured for id field`
+      );
+    }
+    const isLoadingExistingRecord = data.id && Object.keys(data).length === 1;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[BaseModel Constructor - ${modelConstructor.name}] Is loading existing record: ${isLoadingExistingRecord}, ID: ${this.id}`
+      );
+      Logger.verbose(
+        `[BaseModel Constructor - ${modelConstructor.name}] Connected documents:`,
+        Array.from(modelConstructor.connectedDocuments.keys())
+      );
+    }
+    if (isLoadingExistingRecord) {
+      let recordYMap = void 0;
+      let foundDocId = void 0;
+      for (const [docId] of modelConstructor.connectedDocuments) {
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[BaseModel Constructor - ${modelConstructor.name}] Searching in document: ${docId}`
+          );
+        }
+        const documentYMap = modelConstructor.documentYMaps.get(
+          `${docId}_${schema.options.name}`
+        );
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[BaseModel Constructor - ${modelConstructor.name}] Document YMap found: ${!!documentYMap}`
+          );
+        }
+        if (documentYMap) {
+          const foundRecord = documentYMap.get(this.id);
+          if (verboseEnabled) {
+            Logger.verbose(
+              `[BaseModel Constructor - ${modelConstructor.name}] Record found in document ${docId}: ${!!foundRecord}`
+            );
+          }
+          if (foundRecord) {
+            recordYMap = foundRecord;
+            foundDocId = docId;
+            break;
+          }
+        }
+      }
+      if (recordYMap && foundDocId) {
+        this._isLoadingFromYjs = true;
+        this._isDirty = false;
+        this._localChanges = null;
+        this._metaDocId = foundDocId;
+        const connectedDoc = modelConstructor.connectedDocuments.get(foundDocId);
+        if (connectedDoc) {
+          this._metaPermissionHint = connectedDoc.permissionHint;
+        }
+        if (schema.options && schema.options.name) {
+          this.type = schema.options.name;
+        }
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[BaseModel Constructor - ${modelConstructor.name}] ID INITIALIZED TO:`,
+            this.id
+          );
+        }
+        return;
+      }
+    }
+    this._isLoadingFromYjs = false;
+    if (data && Object.keys(data).length > 0) {
+      for (const [
+        fieldKey,
+        fieldOptions
+      ] of schema.fields.entries()) {
+        if (fieldKey === "id") continue;
+        if (data.hasOwnProperty(fieldKey)) {
+          this.setValue(fieldKey, data[fieldKey]);
+        } else if (fieldOptions.default !== void 0) {
+          const defaultValue = typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
+          this.setValue(fieldKey, defaultValue);
+        }
+      }
+    }
+    if (schema.options && schema.options.name) {
+      this.type = schema.options.name;
+    } else {
+      Logger.warn(
+        `[${modelConstructor.name}] Schema missing options.name, 'type' field may not be set correctly.`
+      );
+    }
+    if (!this.id) {
+      Logger.error(
+        `[BaseModel Constructor - ${modelConstructor.name}] ID is STILL UNDEFINED. Current instance state:`,
+        JSON.stringify(this)
+      );
+      throw new Error(
+        `[${modelConstructor.name}] ID is missing after initialization. Ensure 'id' field is defined in the model's schema with autoAssign:true or a default value, or an id is provided during instantiation.`
+      );
+    }
+    Logger.verbose(
+      `[BaseModel Constructor - ${modelConstructor.name}] ID INITIALIZED TO:`,
+      this.id
+    );
+    return;
+  }
+  // Copy-on-write helper methods
+  ensureLocalChanges() {
+    if (this._localChanges === null) {
+      this._localChanges = {};
+    }
+    return this._localChanges;
+  }
+  hasLocalChange(fieldKey) {
+    return this._localChanges !== null && fieldKey in this._localChanges;
+  }
+  getFromYjs(fieldKey) {
+    const modelConstructor = this.constructor;
+    const schema = modelConstructor.getSchema();
+    const modelName = schema?.options?.name;
+    const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[getFromYjs] Called for field '${fieldKey}' on model ${modelName}, instance ID: ${this.id}`
+      );
+      Logger.verbose(`[getFromYjs] this._metaDocId: ${this._metaDocId}`);
+      Logger.verbose(
+        `[getFromYjs] documentYMaps available: ${!!modelConstructor.documentYMaps}`
+      );
+      Logger.verbose(
+        `[getFromYjs] connectedDocuments available: ${!!modelConstructor.connectedDocuments}`
+      );
+    }
+    let recordYMap = void 0;
+    const docId = this._metaDocId;
+    if (verboseEnabled) {
+      Logger.verbose(`[getFromYjs] Using document ID: ${docId}`);
+    }
+    const documentYMapKey = `${docId}_${modelName}`;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[getFromYjs] Looking for documentYMap with key: ${documentYMapKey}`
+      );
+    }
+    const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
+    if (verboseEnabled) {
+      Logger.verbose(`[getFromYjs] DocumentYMap found: ${!!documentYMap}`);
+    }
+    if (documentYMap) {
+      if (verboseEnabled) {
+        Logger.verbose(
+          `[getFromYjs] DocumentYMap keys: [${Array.from(
+            documentYMap.keys()
+          ).join(", ")}]`
+        );
+      }
+      recordYMap = documentYMap.get(this.id);
+      if (verboseEnabled) {
+        Logger.verbose(
+          `[getFromYjs] RecordYMap found for ID '${this.id}': ${!!recordYMap}`
+        );
+      }
+      if (recordYMap) {
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[getFromYjs] RecordYMap keys: [${Array.from(
+              recordYMap.keys()
+            ).join(", ")}]`
+          );
+        }
+        const fieldValue2 = recordYMap.get(fieldKey);
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[getFromYjs] Field '${fieldKey}' value: ${fieldValue2}`
+          );
+        }
+      }
+    }
+    if (!recordYMap) {
+      if (verboseEnabled) {
+        Logger.verbose(
+          `[getFromYjs] No recordYMap found, falling back to schema defaults`
+        );
+      }
+      const fieldOptions = schema?.fields?.get(fieldKey);
+      if (fieldOptions?.default !== void 0) {
+        const defaultValue = typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[getFromYjs] Returning schema default: ${defaultValue}`
+          );
+        }
+        return defaultValue;
+      }
+      if (verboseEnabled) {
+        Logger.verbose(`[getFromYjs] No schema default, returning undefined`);
+      }
+      return void 0;
+    }
+    const fieldValue = recordYMap.get(fieldKey);
+    if (verboseEnabled) {
+      Logger.verbose(`[getFromYjs] Returning field value: ${fieldValue}`);
+    }
+    return fieldValue;
+  }
+  getValue(fieldKey) {
+    const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[getValue] Called for field '${fieldKey}' on instance ID: ${this.id}`
+      );
+    }
+    const schema = this.constructor.getSchema();
+    const fieldOptions = schema?.fields?.get(fieldKey);
+    if (fieldOptions?.type === "stringset") {
+      if (verboseEnabled) {
+        Logger.verbose(
+          `[getValue] Field '${fieldKey}' is StringSet type, returning StringSet instance`
+        );
+      }
+      return this.getOrCreateStringSet(fieldKey);
+    }
+    if (this.hasLocalChange(fieldKey)) {
+      if (verboseEnabled) {
+        Logger.verbose(
+          `[getValue] Field '${fieldKey}' has local changes: ${this._localChanges[fieldKey]}`
+        );
+      }
+      return this._localChanges[fieldKey];
+    }
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[getValue] Field '${fieldKey}' no local changes, calling getFromYjs`
+      );
+    }
+    const result = this.getFromYjs(fieldKey);
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[getValue] Field '${fieldKey}' returning from getFromYjs: ${result}`
+      );
+    }
+    return result;
+  }
+  setValue(fieldKey, value) {
+    const schema = this.constructor.getSchema();
+    const fieldOptions = schema?.fields?.get(fieldKey);
+    if (fieldOptions?.type === "stringset") {
+      throw new Error(
+        `Cannot directly assign to StringSet field '${fieldKey}'. Use the StringSet methods (add, remove, clear) instead.`
+      );
+    }
+    if (!this._isLoadingFromYjs) {
+    }
+    const changes = this.ensureLocalChanges();
+    changes[fieldKey] = value;
+    this._isDirty = true;
+  }
+  get isDirty() {
+    return this._isDirty;
+  }
+  get hasUnsavedChanges() {
+    return this._localChanges !== null && Object.keys(this._localChanges).length > 0;
+  }
+  clearLocalChanges() {
+    this._localChanges = null;
+    this._isDirty = false;
+  }
+  discardChanges() {
+    this.clearLocalChanges();
+  }
+  // Validation methods
+  validateFieldValue(fieldKey, value) {
+    const schema = this.constructor.getSchema();
+    const fieldOptions = schema.fields.get(fieldKey);
+    if (!fieldOptions) {
+      throw new Error(`Unknown field: ${fieldKey}`);
+    }
+    if (fieldOptions.required && (value === null || value === void 0)) {
+      throw new Error(`Field ${fieldKey} is required`);
+    }
+  }
+  validateBeforeSave() {
+    const schema = this.constructor.getSchema();
+    for (const [fieldKey, fieldOptions] of schema.fields.entries()) {
+      const currentValue = this.getValue(fieldKey);
+      if (fieldOptions.required && (currentValue === null || currentValue === void 0)) {
+        throw new Error(`Field ${fieldKey} is required before save`);
+      }
+      if (fieldOptions.type === "stringset" && currentValue instanceof StringSet) {
+        if (fieldOptions.maxCount && currentValue.size > fieldOptions.maxCount) {
+          throw new Error(
+            `StringSet field '${fieldKey}' exceeds maximum count of ${fieldOptions.maxCount}. Current count: ${currentValue.size}`
+          );
+        }
+        if (fieldOptions.maxLength) {
+          for (const value of currentValue) {
+            if (value.length > fieldOptions.maxLength) {
+              throw new Error(
+                `StringSet field '${fieldKey}' contains a string that exceeds maximum length of ${fieldOptions.maxLength}: "${value}" (length: ${value.length})`
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+  // State inspection helpers
+  getChangedFields() {
+    return this._localChanges ? Object.keys(this._localChanges) : [];
+  }
+  getOriginalValue(fieldKey) {
+    return this.getFromYjs(fieldKey);
+  }
+  getCurrentValue(fieldKey) {
+    return this.getValue(fieldKey);
+  }
+  hasFieldChanged(fieldKey) {
+    return this.hasLocalChange(fieldKey);
+  }
+  // StringSet support methods
+  markStringSetChange(fieldName, operation, value) {
+    const changes = this.ensureLocalChanges();
+    if (!changes[fieldName]) {
+      changes[fieldName] = {
+        type: "stringset",
+        additions: /* @__PURE__ */ new Set(),
+        removals: /* @__PURE__ */ new Set()
+      };
+    }
+    const stringSetChanges = changes[fieldName];
+    if (operation === "clear") {
+      const currentValues = this.getStringSetCurrentValues(fieldName);
+      stringSetChanges.additions.clear();
+      stringSetChanges.removals = new Set(currentValues);
+    } else if (operation === "add" && value) {
+      stringSetChanges.removals.delete(value);
+      stringSetChanges.additions.add(value);
+    } else if (operation === "remove" && value) {
+      stringSetChanges.additions.delete(value);
+      stringSetChanges.removals.add(value);
+    }
+    this._isDirty = true;
+  }
+  getStringSetCurrentValues(fieldName) {
+    const yjsData = this.getFromYjs(fieldName);
+    if (yjsData && typeof yjsData === "object") {
+      return Object.keys(yjsData);
+    }
+    return [];
+  }
+  getStringSetFromYjs(fieldName) {
+    const yjsData = this.getFromYjs(fieldName);
+    if (yjsData && typeof yjsData === "object") {
+      return Object.keys(yjsData);
+    }
+    return [];
+  }
+  getOrCreateStringSet(fieldName) {
+    if (!this._stringSetFields.has(fieldName)) {
+      const initialValues = this.getStringSetFromYjs(fieldName);
+      const pendingChanges = this._localChanges?.[fieldName];
+      let currentValues = new Set(initialValues);
+      if (pendingChanges && pendingChanges.type === "stringset") {
+        for (const addition of pendingChanges.additions) {
+          currentValues.add(addition);
+        }
+        for (const removal of pendingChanges.removals) {
+          currentValues.delete(removal);
+        }
+      }
+      const stringSet = new StringSet(
+        this,
+        fieldName,
+        Array.from(currentValues)
+      );
+      this._stringSetFields.set(fieldName, stringSet);
+    }
+    return this._stringSetFields.get(fieldName);
+  }
+  // Legacy initialize method - removed (explicit document required)
+  static async initialize(_yDoc, _db) {
+    throw new Error(
+      `[${this.name}] initialize(yDoc, db) is no longer supported. Use initializeForDocument(yDoc, db, docId, permission)`
+    );
+  }
+  // New method for multi-document initialization
+  static async initializeForDocument(yDoc, db, docId, permissionHint) {
+    const schema = this.getSchema?.();
+    const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
+    if (!schema || !schema.options || !schema.options.name || !schema.resolvedUniqueConstraints) {
+      throw new Error(
+        `[${this.name}] Model schema is not registered, missing options, or missing resolvedUniqueConstraints. Did you forget to use the @Model decorator or has the schema structure changed?`
+      );
+    }
+    const modelName = schema.options.name;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[${this.name}] Initializing model ${modelName} for document ${docId} (permission: ${permissionHint})...`
+      );
+    }
+    if (!_BaseModel.dbInstance) {
+      _BaseModel.dbInstance = db;
+    }
+    this.connectedDocuments.set(docId, {
+      yDoc,
+      permissionHint
+    });
+    const documentYMap = yDoc.getMap(modelName);
+    this.documentYMaps.set(
+      `${docId}_${modelName}`,
+      documentYMap
+    );
+    const stringSetFieldNames = [];
+    schema.fields.forEach((fieldOptions, fieldName) => {
+      if (fieldOptions?.type === "stringset") {
+        stringSetFieldNames.push(fieldName);
+      }
+    });
+    const documentRecordCount = typeof documentYMap.size === "number" ? documentYMap.size : Array.from(documentYMap.keys()).length;
+    const shouldReindexJunctionTables = stringSetFieldNames.length > 0 && documentRecordCount > 0;
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[${this.name}] Document YMap initialized for ${modelName}/${docId} with keys:`,
+        Array.from(documentYMap.keys())
+      );
+    }
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[${this.name}] Ensuring DB table exists for ${modelName}...`
+      );
+    }
+    await db.createTable(modelName, schema.fields, schema.options);
+    if (stringSetFieldNames.length > 0) {
+      Logger.info(
+        `[${this.name}] Junction table reindex check for ${modelName}/${docId}: found ${stringSetFieldNames.length} StringSet field(s) [${stringSetFieldNames.join(
+          ", "
+        )}] with ${documentRecordCount} record(s) in document. ${shouldReindexJunctionTables ? "Re-indexing junction tables from document data." : "No records to re-index yet; ensuring tables exist."}`
+      );
+      for (const fieldName of stringSetFieldNames) {
+        await db.createStringSetJunctionTable(modelName, fieldName);
+      }
+    }
+    try {
+      await db.deleteByDocumentId(modelName, docId);
+    } catch (error) {
+      Logger.error(
+        `[${this.name}] Error clearing existing data for document ${docId} during initialization:`,
+        error
+      );
+    }
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[${this.name}] Loading initial data from document ${docId} YMap for ${modelName}...`
+      );
+    }
+    const extractStringSetValues = (value) => {
+      if (!value) return [];
+      if (value instanceof Y.Map) {
+        return Array.from(value.entries()).filter(([, isMember]) => Boolean(isMember)).map(([key]) => key);
+      }
+      if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string");
+      }
+      if (typeof value === "object") {
+        return Object.entries(value).filter(([, isMember]) => Boolean(isMember)).map(([key]) => key);
+      }
+      return [];
+    };
+    const junctionInsertCounts = {};
+    await db.withTransaction(async (transactionalOps) => {
+      for (const [recordId, recordData] of documentYMap.entries()) {
+        if (!recordId) continue;
+        let itemData;
+        const stringSetValuesByField = {};
+        if (recordData instanceof Y.Map) {
+          itemData = {};
+          const unknownFields = [];
+          for (const [fieldKey, value] of recordData.entries()) {
+            const fieldOptions = schema.fields.get(fieldKey);
+            if (!fieldOptions) {
+              unknownFields.push(fieldKey);
+              continue;
+            }
+            if (fieldOptions.type === "stringset") {
+              stringSetValuesByField[fieldKey] = extractStringSetValues(value);
+              continue;
+            }
+            if (value !== void 0) {
+              itemData[fieldKey] = value;
+            }
+          }
+          if (unknownFields.length > 0) {
+            Logger.warn(
+              `[${this.name}] Ignoring unknown fields [${unknownFields.join(
+                ", "
+              )}] when loading record ${recordId} from document ${docId}`
+            );
+          }
+        } else {
+          const legacyData = recordData;
+          const filteredData = {};
+          const unknownFields = [];
+          for (const [fieldKey, value] of Object.entries(legacyData)) {
+            const fieldOptions = schema.fields.get(fieldKey);
+            if (!fieldOptions) {
+              unknownFields.push(fieldKey);
+              continue;
+            }
+            if (fieldOptions.type === "stringset") {
+              stringSetValuesByField[fieldKey] = extractStringSetValues(value);
+              continue;
+            }
+            if (value !== void 0) {
+              filteredData[fieldKey] = value;
+            }
+          }
+          if (unknownFields.length > 0) {
+            Logger.warn(
+              `[${this.name}] Ignoring unknown fields [${unknownFields.join(
+                ", "
+              )}] when loading legacy record ${recordId} from document ${docId}`
+            );
+          }
+          itemData = filteredData;
+          Logger.warn(
+            `[${this.name}] Found legacy plain object during document initialization for ${recordId}`
+          );
+        }
+        if (!itemData.id) continue;
+        try {
+          await transactionalOps.insert(modelName, {
+            ...itemData,
+            type: modelName,
+            _meta_doc_id: docId,
+            _meta_permission_hint: permissionHint
+          });
+          for (const [fieldName, values] of Object.entries(
+            stringSetValuesByField
+          )) {
+            if (!values || values.length === 0) continue;
+            try {
+              await db.insertStringSetValues(
+                modelName,
+                fieldName,
+                recordId,
+                values
+              );
+              junctionInsertCounts[fieldName] = (junctionInsertCounts[fieldName] || 0) + values.length;
+            } catch (stringSetError) {
+              Logger.error(
+                `[${this.name}] Error indexing StringSet field ${fieldName} for record ${recordId} in document ${docId}:`,
+                stringSetError
+              );
+              throw stringSetError;
+            }
+          }
+        } catch (error) {
+          if (error instanceof Error && error.message.includes("UNIQUE constraint")) {
+            console.warn(
+              `[${this.name}] Warning: Unique constraint conflict when loading ${recordId} from document ${docId}. This record already exists from another document. Data will still be indexed with document ID for disambiguation.`
+            );
+          } else {
+            Logger.error(
+              `[${this.name}] Error inserting item into db (document ${docId} load for ${modelName}):`,
+              error,
+              itemData
+            );
+          }
+        }
+      }
+    });
+    if (stringSetFieldNames.length > 0) {
+      const totalInserted = Object.values(junctionInsertCounts).reduce(
+        (sum, count) => sum + count,
+        0
+      );
+      const perFieldSummary = Object.entries(junctionInsertCounts).map(([fieldName, count]) => `${fieldName}: ${count}`).join("; ");
+      if (shouldReindexJunctionTables) {
+        Logger.info(
+          `[${this.name}] Junction table reindex summary for ${modelName}/${docId}: ${totalInserted} total value(s) processed${perFieldSummary ? ` (${perFieldSummary})` : ""}.`
+        );
+      } else {
+        Logger.info(
+          `[${this.name}] Junction table reindex summary for ${modelName}/${docId}: no StringSet values to index yet.`
+        );
+      }
+    }
+    Logger.verbose(
+      `[${this.name}] Setting up YMap observer for document ${docId}/${modelName}...`
+    );
+    const buildUniqueKey = (recordData, fields) => {
+      const keyParts = [];
+      for (const field of fields) {
+        const value = recordData instanceof Y.Map ? recordData.get(field) : recordData[field];
+        if (value === null || value === void 0) {
+          return null;
+        }
+        keyParts.push(String(value));
+      }
+      return keyParts.join("|");
+    };
+    const extractItemData = (key, recordData) => {
+      let itemData;
+      if (recordData instanceof Y.Map) {
+        itemData = {};
+        const unknownFields = [];
+        for (const [fieldKey, value] of recordData.entries()) {
+          const fieldOptions = schema.fields.get(fieldKey);
+          if (!fieldOptions) {
+            unknownFields.push(fieldKey);
+            continue;
+          }
+          if (fieldOptions.type === "stringset") {
+            continue;
+          }
+          if (value !== void 0) {
+            itemData[fieldKey] = value;
+          }
+        }
+        if (unknownFields.length > 0) {
+          Logger.warn(
+            `[${this.name}] Ignoring unknown fields [${unknownFields.join(
+              ", "
+            )}] when syncing record ${key} from document ${docId}`
+          );
+        }
+      } else {
+        const unknownFields = [];
+        const filteredData = {};
+        for (const [fieldKey, value] of Object.entries(recordData)) {
+          const fieldOptions = schema.fields.get(fieldKey);
+          if (!fieldOptions) {
+            unknownFields.push(fieldKey);
+            continue;
+          }
+          if (fieldOptions.type === "stringset") {
+            continue;
+          }
+          if (value !== void 0) {
+            filteredData[fieldKey] = value;
+          }
+        }
+        if (unknownFields.length > 0) {
+          Logger.warn(
+            `[${this.name}] Ignoring unknown fields [${unknownFields.join(
+              ", "
+            )}] when syncing legacy record ${key} from document ${docId}`
+          );
+        }
+        itemData = filteredData;
+      }
+      if (!itemData.id) return null;
+      return itemData;
+    };
+    const resolveConflictsForBatch = (candidateRecords) => {
+      if (schema.resolvedUniqueConstraints.length === 0) {
+        return /* @__PURE__ */ new Set();
+      }
+      const recordIdsToDiscard = /* @__PURE__ */ new Set();
+      const recordIdsToKeep = /* @__PURE__ */ new Set();
+      const allRecords = /* @__PURE__ */ new Map();
+      for (const [recordId, recordData] of documentYMap.entries()) {
+        if (recordData && !candidateRecords.has(recordId)) {
+          allRecords.set(recordId, recordData);
+        }
+      }
+      for (const [recordId, recordData] of candidateRecords.entries()) {
+        allRecords.set(recordId, recordData);
+      }
+      for (const constraint of schema.resolvedUniqueConstraints) {
+        const recordsByUniqueKey = /* @__PURE__ */ new Map();
+        for (const [recordId, recordData] of allRecords.entries()) {
+          if (recordIdsToDiscard.has(recordId)) continue;
+          const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+          if (uniqueKey === null) continue;
+          if (!recordsByUniqueKey.has(uniqueKey)) {
+            recordsByUniqueKey.set(uniqueKey, []);
+          }
+          recordsByUniqueKey.get(uniqueKey).push(recordId);
+        }
+        for (const [uniqueKey, recordIds] of recordsByUniqueKey.entries()) {
+          if (recordIds.length <= 1) continue;
+          Logger.warn(
+            `[${this.name}] CRDT conflict detected for unique constraint '${constraint.name}' on key '${uniqueKey.substring(0, 50)}${uniqueKey.length > 50 ? "..." : ""}': ${recordIds.length} records found.`
+          );
+          recordIds.sort();
+          const idToKeep = recordIds[recordIds.length - 1];
+          recordIdsToKeep.add(idToKeep);
+          for (let i = 0; i < recordIds.length - 1; i++) {
+            recordIdsToDiscard.add(recordIds[i]);
+          }
+        }
+      }
+      for (const idToKeep of recordIdsToKeep) {
+        recordIdsToDiscard.delete(idToKeep);
+      }
+      return recordIdsToDiscard;
+    };
+    documentYMap.observe(async (event) => {
+      Logger.verbose(
+        `[${this.name}] Document YMap change detected for ${modelName}/${docId}:`,
+        event
+      );
+      const currentDbInstance = _BaseModel.dbInstance;
+      if (!currentDbInstance) {
+        Logger.error(
+          `[${this.name}] DB instance not available for document YMap observer on ${modelName}/${docId}.`
+        );
+        return;
+      }
+      const isRemoteChange = !event.transaction.local;
+      const remoteAdds = /* @__PURE__ */ new Map();
+      const localAddsAndUpdates = [];
+      for (const [key, change] of event.changes.keys.entries()) {
+        const recordData = documentYMap.get(key);
+        if (change.action === "add" || change.action === "update") {
+          if (!recordData || !key) continue;
+          const itemData = extractItemData(key, recordData);
+          if (!itemData) continue;
+          if (change.action === "add" && recordData instanceof Y.Map) {
+            Logger.verbose(
+              `[${this.name}] Setting up observer on newly added nested YMap for record ${key} in document ${docId}`
+            );
+            this.setupNestedYMapObserverForDocument(
+              key,
+              recordData,
+              docId,
+              permissionHint
+            );
+          }
+          if (isRemoteChange && change.action === "add") {
+            remoteAdds.set(key, { recordData, itemData });
+          } else {
+            localAddsAndUpdates.push({ key, action: change.action, recordData, itemData });
+          }
+        } else if (change.action === "delete") {
+          Logger.verbose(
+            `[${this.name}] Deleting item from db (${modelName}/${docId}):`,
+            key
+          );
+          try {
+            await currentDbInstance.delete(modelName, key);
+          } catch (error) {
+            Logger.error(
+              `[${this.name}] Error deleting item from db (${modelName}/${docId}):`,
+              error,
+              key
+            );
+          }
+        }
+      }
+      for (const { itemData } of localAddsAndUpdates) {
+        try {
+          Logger.verbose(
+            `[${this.name}] Syncing local item to db from document ${docId} (${modelName}):`,
+            itemData
+          );
+          await currentDbInstance.insert(modelName, {
+            ...itemData,
+            type: modelName,
+            _meta_doc_id: docId,
+            _meta_permission_hint: permissionHint
+          });
+        } catch (error) {
+          Logger.error(
+            `[${this.name}] Error syncing local item to db from document ${docId} (${modelName}):`,
+            error,
+            itemData
+          );
+        }
+      }
+      if (remoteAdds.size > 0) {
+        Logger.verbose(
+          `[${this.name}] Processing ${remoteAdds.size} remote add(s) with conflict resolution for ${modelName}/${docId}`
+        );
+        const candidateRecords = /* @__PURE__ */ new Map();
+        for (const [key, { recordData }] of remoteAdds.entries()) {
+          candidateRecords.set(key, recordData);
+        }
+        const idsToDiscard = resolveConflictsForBatch(candidateRecords);
+        if (idsToDiscard.size > 0) {
+          Logger.info(
+            `[${this.name}] Discarding ${idsToDiscard.size} duplicate record(s) from remote sync for ${modelName}/${docId}: ${Array.from(idsToDiscard).join(", ")}`
+          );
+        }
+        for (const [key, { itemData }] of remoteAdds.entries()) {
+          if (idsToDiscard.has(key)) {
+            Logger.verbose(
+              `[${this.name}] Skipping SQLite insert for discarded duplicate: ${key}`
+            );
+            continue;
+          }
+          try {
+            Logger.verbose(
+              `[${this.name}] Syncing remote item to db from document ${docId} (${modelName}):`,
+              itemData
+            );
+            await currentDbInstance.insert(modelName, {
+              ...itemData,
+              type: modelName,
+              _meta_doc_id: docId,
+              _meta_permission_hint: permissionHint
+            });
+          } catch (error) {
+            Logger.error(
+              `[${this.name}] Error syncing remote item to db from document ${docId} (${modelName}):`,
+              error,
+              itemData
+            );
+          }
+        }
+        if (idsToDiscard.size > 0) {
+          yDoc.transact(() => {
+            for (const idToDiscard of idsToDiscard) {
+              const recordData = documentYMap.get(idToDiscard);
+              if (!recordData) continue;
+              for (const constraint of schema.resolvedUniqueConstraints) {
+                const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+                if (uniqueKey === null) continue;
+                const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+                const constraintMap = yDoc.getMap(constraintMapName);
+                const currentIndexValue = constraintMap.get(uniqueKey);
+                if (currentIndexValue === idToDiscard) {
+                  constraintMap.delete(uniqueKey);
+                  Logger.verbose(
+                    `[${this.name}] Removed discarded record ${idToDiscard} from unique index ${constraintMapName}`
+                  );
+                }
+              }
+              documentYMap.delete(idToDiscard);
+              Logger.verbose(
+                `[${this.name}] Removed discarded record ${idToDiscard} from Y.Doc`
+              );
+            }
+          }, `conflict-resolution-${modelName}-${docId}`);
+          yDoc.transact(() => {
+            for (const constraint of schema.resolvedUniqueConstraints) {
+              const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+              const constraintMap = yDoc.getMap(constraintMapName);
+              for (const [recordId, recordData] of documentYMap.entries()) {
+                if (!recordData) continue;
+                const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+                if (uniqueKey === null) continue;
+                const currentIndexValue = constraintMap.get(uniqueKey);
+                if (currentIndexValue !== recordId) {
+                  constraintMap.set(uniqueKey, recordId);
+                  Logger.verbose(
+                    `[${this.name}] Updated unique index ${constraintMapName}['${uniqueKey.substring(0, 30)}...'] to point to ${recordId}`
+                  );
+                }
+              }
+            }
+          }, `update-indexes-${modelName}-${docId}`);
+        }
+      }
+      Logger.verbose(
+        `[${this.name}] Document YMap observation transaction for ${modelName}/${docId} completed.`
+      );
+      this.notifyListeners();
+    });
+    Logger.verbose(
+      `[${this.name}] Setting up observers on existing nested YMaps for ${modelName}/${docId}...`
+    );
+    for (const [recordId, recordData] of documentYMap.entries()) {
+      if (recordData instanceof Y.Map) {
+        Logger.verbose(
+          `[${this.name}] Setting up observer on existing nested YMap for record ${recordId} in document ${docId}`
+        );
+        this.setupNestedYMapObserverForDocument(
+          recordId,
+          recordData,
+          docId,
+          permissionHint
+        );
+      }
+    }
+    Logger.verbose(
+      `[${this.name}] Model ${modelName} initialization complete for document ${docId}.`
+    );
+  }
+  // New method to clean up data for a disconnected document
+  static async cleanupDocumentData(docId) {
+    const modelConstructor = this;
+    const schema = modelConstructor.getSchema?.();
+    if (!schema || !schema.options?.name) {
+      Logger.warn(
+        `[${this.name}] Cannot cleanup document data: Schema not found for model ${this.name}`
+      );
+      return;
+    }
+    const modelName = schema.options.name;
+    Logger.verbose(
+      `[${this.name}] Cleaning up data for document ${docId} from model ${modelName}...`
+    );
+    modelConstructor.connectedDocuments.delete(docId);
+    modelConstructor.documentYMaps.delete(`${docId}_${modelName}`);
+    Logger.verbose(
+      `[${this.name}] Document ${docId} cleanup complete for model ${modelName}.`
+    );
+  }
+  static subscribe(callback) {
+    const schema = this.getSchema?.();
+    const modelTypeKey = schema?.options?.name || this.name.toLowerCase();
+    if (!_BaseModel.listenersMap.has(modelTypeKey)) {
+      _BaseModel.listenersMap.set(modelTypeKey, /* @__PURE__ */ new Set());
+    }
+    const listeners = _BaseModel.listenersMap.get(modelTypeKey);
+    listeners.add(callback);
+    return () => {
+      listeners.delete(callback);
+      if (listeners.size === 0) {
+        _BaseModel.listenersMap.delete(modelTypeKey);
+      }
+    };
+  }
+  static notifyListeners() {
+    const schema = this.getSchema?.();
+    const modelTypeKey = schema?.options?.name || this.name.toLowerCase();
+    const listeners = _BaseModel.listenersMap.get(modelTypeKey);
+    if (!listeners) return;
+    Logger.verbose(
+      `[${this.name}] Notifying ${listeners.size} listeners for ${modelTypeKey}`
+    );
+    listeners.forEach((callback) => {
+      try {
+        callback();
+      } catch (e) {
+        Logger.error("Error in listener callback:", e);
+      }
+    });
+  }
+  /**
+   * Legacy migration method - no longer needed in the new multidoc architecture.
+   * Data migration is now handled during document initialization.
+   */
+  static async migrateToNestedYMaps() {
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options?.name) {
+      throw new Error(
+        `[${this.name}] Cannot migrate: Schema not properly initialized`
+      );
+    }
+    const modelName = schema.options.name;
+    Logger.verbose(
+      `[${modelName}] Migration method called but not needed in multidoc architecture`
+    );
+  }
+  /**
+   * Utility to diff current instance data against YJS nested map data
+   * Returns object with added, modified, and removed fields
+   */
+  _diffWithYjsData() {
+    const debugEnabled = Logger.getLogLevel() >= 4 /* DEBUG */;
+    Logger.debug(
+      `[_diffWithYjsData] Starting diff calculation for ID: ${this.id}`
+    );
+    Logger.debug(
+      `[_diffWithYjsData] hasUnsavedChanges: ${this.hasUnsavedChanges}`
+    );
+    Logger.debug(`[_diffWithYjsData] _localChanges:`, this._localChanges);
+    if (!this.hasUnsavedChanges) {
+      Logger.debug(
+        `[_diffWithYjsData] No unsaved changes, returning empty diff`
+      );
+      return { added: {}, modified: {}, removed: [] };
+    }
+    const modelConstructor = this.constructor;
+    const schema = modelConstructor.getSchema();
+    const modelName = schema.options.name;
+    const docId = this._metaDocId;
+    Logger.debug(`[_diffWithYjsData] modelName: ${modelName}, docId: ${docId}`);
+    if (!docId) {
+      throw new Error(
+        `[${modelName}] Cannot diff with Y.js data: model instance has no document ID`
+      );
+    }
+    if (!modelConstructor.documentYMaps) {
+      throw new Error(
+        `[${modelName}] Multi-document system not initialized. documentYMaps is undefined.`
+      );
+    }
+    const documentYMap = modelConstructor.documentYMaps.get(
+      `${docId}_${modelName}`
+    );
+    Logger.debug(`[_diffWithYjsData] documentYMap found: ${!!documentYMap}`);
+    if (!documentYMap) {
+      throw new Error(
+        `[${modelName}] YMap not found for document '${docId}'. This should not happen.`
+      );
+    }
+    const recordYMap = documentYMap.get(this.id);
+    Logger.debug(`[_diffWithYjsData] recordYMap found: ${!!recordYMap}`);
+    const added = {};
+    const modified = {};
+    const removed = [];
+    if (!recordYMap) {
+      Logger.debug(
+        `[_diffWithYjsData] No existing recordYMap, treating all local changes as 'added'`
+      );
+      if (this._localChanges) {
+        for (const [key, value] of Object.entries(this._localChanges)) {
+          Logger.debug(`[_diffWithYjsData] Adding field '${key}': ${value}`);
+          if (value && value.type === "stringset") {
+            const stringSetData = {};
+            for (const addition of value.additions) {
+              stringSetData[addition] = true;
+            }
+            added[key] = stringSetData;
+          } else {
+            added[key] = value;
+          }
+        }
+      }
+      Logger.debug(`[_diffWithYjsData] Final diff for new record:`, {
+        added,
+        modified: {},
+        removed: []
+      });
+      return { added, modified, removed: [] };
+    }
+    Logger.debug(
+      `[_diffWithYjsData] Existing record found, comparing local changes with Y.js data`
+    );
+    if (debugEnabled) {
+      Logger.debug(
+        `[_diffWithYjsData] Existing recordYMap keys:`,
+        Array.from(recordYMap.keys())
+      );
+    }
+    if (this._localChanges) {
+      for (const [key, localValue] of Object.entries(this._localChanges)) {
+        Logger.debug(
+          `[_diffWithYjsData] Processing field '${key}' with local value: ${localValue}`
+        );
+        if (localValue && localValue.type === "stringset") {
+          const currentYjsData = recordYMap.get(key) || {};
+          const newStringSetData = {
+            ...currentYjsData
+          };
+          for (const addition of localValue.additions) {
+            newStringSetData[addition] = true;
+          }
+          for (const removal of localValue.removals) {
+            delete newStringSetData[removal];
+          }
+          const yjsValue = recordYMap.get(key);
+          if (yjsValue === void 0) {
+            added[key] = newStringSetData;
+          } else if (!this._deepEqual(yjsValue, newStringSetData)) {
+            modified[key] = newStringSetData;
+          }
+        } else {
+          const yjsValue = recordYMap.get(key);
+          Logger.debug(
+            `[_diffWithYjsData] Field '${key}' - Y.js value: ${yjsValue}, local value: ${localValue}`
+          );
+          if (yjsValue === void 0) {
+            Logger.debug(
+              `[_diffWithYjsData] Field '${key}' not in Y.js, adding to 'added'`
+            );
+            added[key] = localValue;
+          } else if (!this._deepEqual(yjsValue, localValue)) {
+            Logger.debug(
+              `[_diffWithYjsData] Field '${key}' different in Y.js, adding to 'modified'`
+            );
+            modified[key] = localValue;
+          } else {
+            Logger.debug(`[_diffWithYjsData] Field '${key}' unchanged`);
+          }
+        }
+      }
+    }
+    Logger.debug(`[_diffWithYjsData] Final diff result:`, {
+      added,
+      modified,
+      removed
+    });
+    Logger.verbose(`[${modelConstructor.name}] Diff for ${this.id}:`, {
+      added: Object.keys(added),
+      modified: Object.keys(modified),
+      removed
+    });
+    return { added, modified, removed };
+  }
+  /**
+   * Deep equality check for comparing field values
+   */
+  _deepEqual(a, b) {
+    if (a === b) return true;
+    if (a == null || b == null) return a === b;
+    if (typeof a !== typeof b) return false;
+    if (typeof a !== "object") return false;
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+    if (Array.isArray(a)) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!this._deepEqual(a[i], b[i])) return false;
+      }
+      return true;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+      if (!keysB.includes(key)) return false;
+      if (!this._deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  static _buildKeyFromValues(fields, keyValues, modelName, constraintName) {
+    if (fields.length === 0) return null;
+    if (fields.length !== keyValues.length) {
+      Logger.warn(
+        `[${modelName}] Constraint '${constraintName}': Mismatch between number of fields (${fields.length}) and values (${keyValues.length}). Cannot build key.`
+      );
+      return null;
+    }
+    if (keyValues.some((v) => v === null || v === void 0)) {
+      return null;
+    }
+    if (fields.length === 1) {
+      return String(keyValues[0]);
+    } else {
+      return JSON.stringify(keyValues);
+    }
+  }
+  _buildUniqueKey(fields, data, modelName, constraintName) {
+    const values = fields.map((f) => data[f]);
+    return this.constructor._buildKeyFromValues(
+      fields,
+      values,
+      modelName,
+      constraintName
+    );
+  }
+  async save(options) {
+    Logger.verbose(
+      `[BaseModel.save()] Method entered. ID: ${this.id}, Model: ${this.constructor.modelName || this.constructor.name}. Timestamp: ${Date.now()}`
+    );
+    Logger.verbose(`[BaseModel.save()] Current 'this' object:`, this);
+    Logger.verbose(`[BaseModel.save()] 'this.id' specifically:`, this.id);
+    Logger.verbose(`[BaseModel.save()] Options:`, options);
+    if (!this._isDirty) {
+      Logger.verbose(
+        `[${this.constructor.name}] No changes to save for ${this.id}`
+      );
+      return;
+    }
+    const modelConstructor = this.constructor;
+    const schema = modelConstructor.getSchema();
+    if (!schema || !schema.options || !schema.fields || !schema.resolvedUniqueConstraints) {
+      throw new Error(
+        `Schema (or resolvedUniqueConstraints) not found or invalid for model ${modelConstructor.name} in save.`
+      );
+    }
+    const modelName = schema.options.name;
+    let targetDocId = null;
+    let targetYDoc = null;
+    let targetYMap = null;
+    let permissionHint = null;
+    const explicitDocId = options?.targetDocument || null;
+    const instanceRememberedDocId = this._metaDocId;
+    const modelDefaultDocId = this.constructor.getDocumentIdForModel(modelName);
+    const globalDefaultDocId = this.constructor.getGlobalDefaultDocumentId();
+    const precedence = [
+      { name: "explicit", value: explicitDocId },
+      { name: "remembered", value: instanceRememberedDocId },
+      { name: "modelDefault", value: modelDefaultDocId },
+      { name: "globalDefault", value: globalDefaultDocId }
+    ];
+    for (const source of precedence) {
+      if (source.value) {
+        targetDocId = source.value;
+        const documentInfo2 = this.constructor.connectedDocuments.get(targetDocId);
+        if (!documentInfo2) {
+          throw new DocumentClosedError(
+            `[${modelName}] Document '${targetDocId}' from '${source.name}' is not connected. Please connect it or provide an open document id.`
+          );
+        }
+        break;
+      }
+    }
+    if (!targetDocId) {
+      throw new DocumentResolutionError(
+        `[${modelName}] Unable to resolve a target document id (no explicit, no remembered, no model default, no global default).`
+      );
+    }
+    const documentInfo = modelConstructor.connectedDocuments.get(targetDocId);
+    if (!documentInfo) {
+      throw new DocumentClosedError(
+        `[${modelName}] Document '${targetDocId}' is not connected. Please connect the document first.`
+      );
+    }
+    targetYDoc = documentInfo.yDoc;
+    permissionHint = documentInfo.permissionHint;
+    targetYMap = modelConstructor.documentYMaps.get(`${targetDocId}_${modelName}`) || null;
+    if (!targetYMap) {
+      throw new Error(
+        `[${modelName}] YMap not found for document '${targetDocId}'. This should not happen.`
+      );
+    }
+    if (permissionHint === "read" && !options?.forceWrite) {
+      throw new Error(
+        `[${modelName}] Cannot save to document '${targetDocId}' with read-only permission. Use forceWrite option to override.`
+      );
+    }
+    if (!targetYDoc) {
+      throw new Error(
+        `[${modelName}] Target Y.Doc not found for document '${targetDocId}'. Ensure document connection has completed.`
+      );
+    }
+    const yDoc = targetYDoc;
+    if (!this.id) {
+      Logger.error(
+        "[BaseModel.save()] ID is undefined before saving! Instance dump:",
+        JSON.stringify(this)
+      );
+      throw new Error("Cannot save item without an id. Ensure id is set.");
+    }
+    this.validateBeforeSave();
+    Logger.debug(`[${modelName}.save] About to get current JS state`);
+    Logger.debug(`[${modelName}.save] _localChanges:`, this._localChanges);
+    Logger.debug(`[${modelName}.save] _isDirty:`, this._isDirty);
+    const dataToSave = this.getCurrentJSState();
+    Logger.debug(
+      `[${modelName}.save] getCurrentJSState() returned:`,
+      dataToSave
+    );
+    await yDoc.transact(async () => {
+      if (!targetYMap) {
+        throw new Error(
+          `[${modelName}] Target YMap not found for save operation`
+        );
+      }
+      let recordYMap = targetYMap.get(this.id);
+      const isUpdate = !!recordYMap;
+      Logger.debug(`[${modelName}.save] isUpdate: ${isUpdate}`);
+      Logger.debug(`[${modelName}.save] recordYMap exists: ${!!recordYMap}`);
+      if (!recordYMap) {
+        recordYMap = new Y.Map();
+        Logger.verbose(
+          `[${modelName}] Creating new nested YMap for record ${this.id} in document ${targetDocId || "legacy"}`
+        );
+        targetYMap.set(this.id, recordYMap);
+        recordYMap.set("id", this.id);
+      }
+      if (!isUpdate || this._metaDocId && this._metaDocId !== targetDocId) {
+        this._metaDocId = targetDocId;
+        this._metaPermissionHint = permissionHint;
+        Logger.debug(`[${modelName}.save] Set _metaDocId to: ${targetDocId}`);
+      }
+      let oldData = null;
+      if (isUpdate) {
+        oldData = {};
+        for (const [key, value] of recordYMap.entries()) {
+          oldData[key] = value;
+        }
+        Logger.verbose(
+          `[${modelName}] Retrieved old data for update:`,
+          oldData
+        );
+        Logger.debug(`[${modelName}.save] oldData:`, oldData);
+      }
+      Logger.debug(`[${modelName}.save] About to calculate diff`);
+      const diff = this._diffWithYjsData();
+      Logger.debug(`[${modelName}.save] Diff result:`, diff);
+      const hasChanges = Object.keys(diff.added).length > 0 || Object.keys(diff.modified).length > 0 || diff.removed.length > 0;
+      Logger.debug(`[${modelName}.save] hasChanges: ${hasChanges}`);
+      if (!hasChanges && isUpdate) {
+        Logger.verbose(
+          `[${modelName}] No changes detected for ${this.id}, skipping save`
+        );
+        Logger.debug(`[${modelName}.save] No changes detected, skipping save`);
+        return;
+      }
+      for (const constraint of schema.resolvedUniqueConstraints) {
+        const newUniqueKey = this._buildUniqueKey(
+          constraint.fields,
+          dataToSave,
+          modelName,
+          constraint.name
+        );
+        Logger.verbose(
+          `[${modelName}] Save Check (Item '${this.id}'): Constraint '${constraint.name}', Built Key: '${newUniqueKey ? newUniqueKey.substring(0, 50) : null}'`
+        );
+        if (newUniqueKey === null) {
+          Logger.verbose(
+            `[${modelName}] Save Check (Item '${this.id}'): Constraint '${constraint.name}' skipped due to null key.`
+          );
+          continue;
+        }
+        const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+        const constraintMap = yDoc.getMap(constraintMapName);
+        Logger.verbose(
+          `[${modelName}] Save Check (Item '${this.id}'): GET from '${constraintMapName}' with Key '${newUniqueKey.substring(
+            0,
+            50
+          )}'`
+        );
+        const existingRecordIdWithNewKey = constraintMap.get(newUniqueKey);
+        Logger.verbose(
+          `[${modelName}] Save Check (Item '${this.id}'): Found Existing ID: '${existingRecordIdWithNewKey}' for Key '${newUniqueKey.substring(
+            0,
+            50
+          )}'`
+        );
+        if (existingRecordIdWithNewKey && existingRecordIdWithNewKey !== this.id) {
+          throw new UniqueConstraintViolationError(
+            `Unique constraint '${constraint.name}' violated for model '${modelName}' on fields [${constraint.fields.join(
+              ", "
+            )}]. Attempted ID: ${this.id}. Value(s) starting with '${newUniqueKey.substring(
+              0,
+              50
+            )}...' already exist for record ID ${existingRecordIdWithNewKey}.`,
+            modelName,
+            constraint.name,
+            constraint.fields,
+            this.id,
+            existingRecordIdWithNewKey
+          );
+        }
+      }
+      if (isUpdate && oldData) {
+        for (const constraint of schema.resolvedUniqueConstraints) {
+          const oldUniqueKey = this._buildUniqueKey(
+            constraint.fields,
+            oldData,
+            modelName,
+            constraint.name
+          );
+          const newUniqueKey = this._buildUniqueKey(
+            constraint.fields,
+            dataToSave,
+            modelName,
+            constraint.name
+          );
+          if (oldUniqueKey !== null && oldUniqueKey !== newUniqueKey) {
+            const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+            const constraintMap = yDoc.getMap(constraintMapName);
+            Logger.verbose(
+              `[${modelName}] Save (update): Deleting old unique key '${oldUniqueKey.substring(
+                0,
+                50
+              )}...' for constraint '${constraint.name}', item ${this.id}`
+            );
+            constraintMap.delete(oldUniqueKey);
+          }
+        }
+      }
+      for (const constraint of schema.resolvedUniqueConstraints) {
+        const newUniqueKey = this._buildUniqueKey(
+          constraint.fields,
+          dataToSave,
+          modelName,
+          constraint.name
+        );
+        if (newUniqueKey !== null) {
+          const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+          const constraintMap = yDoc.getMap(constraintMapName);
+          Logger.verbose(
+            `[${modelName}] Save Set (Item '${this.id}'): SET into '${constraintMapName}' with Key '${newUniqueKey.substring(
+              0,
+              50
+            )}', Value (Item ID) '${this.id}'`
+          );
+          constraintMap.set(newUniqueKey, this.id);
+        }
+      }
+      Logger.debug(
+        `[${modelName}.save] Applying field-level changes for ${this.id}`
+      );
+      Logger.debug(`[${modelName}.save] Diff result:`, diff);
+      for (const [key, value] of Object.entries(diff.added)) {
+        Logger.debug(`[${modelName}.save] Adding field '${key}':`, value);
+        recordYMap.set(key, value);
+      }
+      for (const [key, value] of Object.entries(diff.modified)) {
+        Logger.debug(`[${modelName}.save] Modifying field '${key}':`, value);
+        recordYMap.set(key, value);
+      }
+      for (const key of diff.removed) {
+        Logger.debug(`[${modelName}.save] Removing field '${key}'`);
+        recordYMap.delete(key);
+      }
+      Logger.debug(
+        `[${modelName}.save] After applying changes, recordYMap contents:`,
+        Object.fromEntries(recordYMap.entries())
+      );
+      if (!isUpdate) {
+        if (targetDocId && permissionHint) {
+          modelConstructor.setupNestedYMapObserverForDocument(
+            this.id,
+            recordYMap,
+            targetDocId,
+            permissionHint
+          );
+        } else {
+          modelConstructor.setupNestedYMapObserver(
+            this.id,
+            recordYMap
+          );
+        }
+      } else {
+        if (!recordYMap.has("id")) {
+          Logger.verbose(
+            `[${modelName}] Adding id field '${this.id}' to existing nested YMap`
+          );
+          recordYMap.set("id", this.id);
+        }
+      }
+      Logger.verbose(`[${modelName}] Save completed for ${this.id}`);
+      if (_BaseModel.dbInstance) {
+        Logger.verbose(
+          `[${modelName}] Syncing StringSet changes to database for ${this.id}`
+        );
+        for (const [fieldName, localValue] of Object.entries(
+          this._localChanges || {}
+        )) {
+          if (localValue && localValue.type === "stringset") {
+            const fieldOptions = schema.fields.get(fieldName);
+            if (fieldOptions?.type === "stringset") {
+              if (localValue.additions.size > 0) {
+                await _BaseModel.dbInstance.insertStringSetValues(
+                  modelName,
+                  fieldName,
+                  this.id,
+                  Array.from(localValue.additions)
+                );
+              }
+              if (localValue.removals.size > 0) {
+                await _BaseModel.dbInstance.removeStringSetValues(
+                  modelName,
+                  fieldName,
+                  this.id,
+                  Array.from(localValue.removals)
+                );
+              }
+            }
+          }
+        }
+        Logger.verbose(
+          `[${modelName}] StringSet database sync completed for ${this.id}`
+        );
+      }
+    }, `save-record-${modelName}-${this.id}`);
+    Logger.debug(
+      `[${modelName}.save] About to clear local changes for ${this.id}`
+    );
+    Logger.debug(
+      `[${modelName}.save] _localChanges before clear:`,
+      this._localChanges
+    );
+    this.clearLocalChanges();
+    Logger.debug(
+      `[${modelName}.save] _localChanges after clear:`,
+      this._localChanges
+    );
+    if (Logger.getLogLevel() >= 5 /* VERBOSE */) {
+      Logger.verbose(`[${modelName}.save] Successfully saved ${this.id}`);
+    }
+  }
+  async delete() {
+    const modelConstructor = this.constructor;
+    const schema = modelConstructor.getSchema();
+    if (!schema || !schema.options || !schema.resolvedUniqueConstraints) {
+      throw new Error(
+        `Schema (or resolvedUniqueConstraints) not found or invalid for model ${modelConstructor.name} in delete.`
+      );
+    }
+    const modelName = schema.options.name;
+    if (!this.id) {
+      throw new Error("Cannot delete item without an id.");
+    }
+    let sourceYDoc = null;
+    let sourceYMap = null;
+    let docId = void 0;
+    docId = this._metaDocId ?? void 0;
+    const documentInfo = docId ? modelConstructor.connectedDocuments.get(docId) : void 0;
+    if (!documentInfo) {
+      throw new Error(
+        `[${modelName}] Document '${docId}' is not connected. Cannot delete from disconnected document.`
+      );
+    }
+    sourceYDoc = documentInfo.yDoc;
+    sourceYMap = modelConstructor.documentYMaps.get(`${docId}_${modelName}`) || null;
+    if (!sourceYMap) {
+      throw new Error(
+        `[${modelName}] YMap not found for document '${docId}'. This should not happen.`
+      );
+    }
+    const recordYMap = sourceYMap.get(this.id);
+    if (!recordYMap) {
+      Logger.warn(
+        `[${modelName}] Delete: Item ${this.id} not found in YMap${docId ? ` for document ${docId}` : ""}. Cannot remove from unique constraint maps. Attempting main map deletion only.`
+      );
+      sourceYDoc.transact(() => {
+        sourceYMap.delete(this.id);
+      }, `delete-ghost-record-${modelName}-${this.id}`);
+      return;
+    }
+    const dataToDelete = {};
+    for (const [key, value] of recordYMap.entries()) {
+      dataToDelete[key] = value;
+    }
+    await sourceYDoc.transact(async () => {
+      for (const constraint of schema.resolvedUniqueConstraints) {
+        const uniqueKey = this._buildUniqueKey(
+          constraint.fields,
+          dataToDelete,
+          modelName,
+          constraint.name
+        );
+        if (uniqueKey !== null) {
+          const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+          const constraintMap = sourceYDoc.getMap(constraintMapName);
+          Logger.verbose(
+            `[${modelName}] Delete: Removing unique key '${uniqueKey.substring(
+              0,
+              50
+            )}...' for constraint '${constraint.name}', item ${this.id}${docId ? ` from document ${docId}` : ""}`
+          );
+          constraintMap.delete(uniqueKey);
+        }
+      }
+      Logger.verbose(
+        `[${modelName}] Deleting nested YMap from main YMap: ${this.id}${docId ? ` from document ${docId}` : ""}`
+      );
+      sourceYMap.delete(this.id);
+    }, `delete-record-${modelName}-${this.id}`);
+  }
+  // Get current state combining local changes with Yjs data
+  getCurrentJSState() {
+    const schema = this.constructor.getSchema();
+    if (!schema || !schema.fields) {
+      throw new Error(
+        `Schema not found or invalid for model ${this.constructor.name} in getCurrentJSState.`
+      );
+    }
+    const result = {};
+    Logger.debug(
+      `[getCurrentJSState] Starting for model ${this.constructor.name}, ID: ${this.id}`
+    );
+    for (const fieldKey of schema.fields.keys()) {
+      const value = this.getValue(fieldKey);
+      if (value !== void 0) {
+        const fieldOptions = schema.fields.get(fieldKey);
+        if (fieldOptions?.type === "stringset" && value instanceof StringSet) {
+          result[fieldKey] = value.toArray();
+        } else {
+          result[fieldKey] = value;
+        }
+      }
+    }
+    if (schema.options?.name) {
+      result.type = schema.options.name;
+    }
+    if (this.id !== void 0) {
+      result.id = this.id;
+    }
+    if (this._metaDocId !== null) {
+      result._meta_doc_id = this._metaDocId;
+    }
+    if (this._metaPermissionHint !== null) {
+      result._meta_permission_hint = this._metaPermissionHint;
+    }
+    return result;
+  }
+  // Keep toJSON for backward compatibility, but delegate to getCurrentJSState
+  toJSON() {
+    return this.getCurrentJSState();
+  }
+  static async find(id) {
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options.name)
+      throw new Error("Model not properly initialized for find");
+    const modelName = schema.options.name;
+    Logger.verbose(`[${modelName}] Finding item by id:`, id);
+    const modelConstructor = this;
+    const debugEnabled = Logger.getLogLevel() >= 4 /* DEBUG */;
+    Logger.debug(`[${modelName}.find] Using multi-document system`);
+    if (debugEnabled) {
+      Logger.debug(
+        `[${modelName}.find] Connected documents: [${Array.from(
+          modelConstructor.connectedDocuments.keys()
+        ).join(", ")}]`
+      );
+    }
+    for (const [docId] of modelConstructor.connectedDocuments) {
+      Logger.debug(`[${modelName}.find] Searching in document: ${docId}`);
+      const documentYMapKey = `${docId}_${modelName}`;
+      Logger.debug(
+        `[${modelName}.find] Looking for documentYMap with key: ${documentYMapKey}`
+      );
+      const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
+      Logger.debug(`[${modelName}.find] DocumentYMap found: ${!!documentYMap}`);
+      if (documentYMap) {
+        if (debugEnabled) {
+          Logger.debug(
+            `[${modelName}.find] DocumentYMap keys: [${Array.from(
+              documentYMap.keys()
+            ).join(", ")}]`
+          );
+        }
+        const recordYMap = documentYMap.get(id);
+        Logger.debug(
+          `[${modelName}.find] RecordYMap found for ID '${id}': ${!!recordYMap}`
+        );
+        if (recordYMap) {
+          if (debugEnabled) {
+            Logger.debug(
+              `[${modelName}.find] RecordYMap keys: [${Array.from(
+                recordYMap.keys()
+              ).join(", ")}]`
+            );
+          }
+          Logger.debug(`[${modelName}.find] Creating instance with ID: ${id}`);
+          const instance = new this({ id });
+          Logger.debug(`[${modelName}.find] Setting _metaDocId to: ${docId}`);
+          instance._metaDocId = docId;
+          const connectedDoc = modelConstructor.connectedDocuments.get(docId);
+          if (connectedDoc) {
+            Logger.debug(
+              `[${modelName}.find] Setting _metaPermissionHint to: ${connectedDoc.permissionHint}`
+            );
+            instance._metaPermissionHint = connectedDoc.permissionHint;
+          }
+          Logger.debug(
+            `[${modelName}.find] Returning instance with _metaDocId: ${instance._metaDocId}`
+          );
+          return instance;
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Document-style query API - returns paginated results
+   */
+  static async query(filter = {}, options) {
+    if (!_BaseModel.dbInstance) {
+      const modelNameForError = this.modelName || this.name || "BaseModel";
+      throw new Error(
+        `[${modelNameForError}] Database not initialized for query. Connect at least one document via initJsBao(...).connectDocument or call initializeForDocument(yDoc, db, docId, permissionHint) before running queries.`
+      );
+    }
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options?.name) {
+      throw new Error("Model not properly initialized for query");
+    }
+    const modelName = schema.options.name;
+    Logger.verbose(`[${modelName}] Executing query:`, { filter, options });
+    const hasIncludes = options?.include && options.include.length > 0;
+    const translatorOptions = hasIncludes && options?.projection ? { ...options, projection: void 0 } : options;
+    const translator = new DocumentQueryTranslator(modelName, schema.fields);
+    const translatedQuery = translator.translateFind(filter, translatorOptions);
+    Logger.verbose(`[${modelName}] Translated SQL:`, translatedQuery.sql);
+    Logger.verbose(`[${modelName}] SQL params:`, translatedQuery.params);
+    const results = await _BaseModel.dbInstance.query(
+      translatedQuery.sql,
+      translatedQuery.params
+    );
+    Logger.verbose(`[${modelName}] Query returned ${results.length} results`);
+    if (options?.include && options.include.length > 0) {
+      const { IncludeResolver } = await import("./IncludeResolver-WGSQDMS7.js");
+      const resolver = new IncludeResolver(_BaseModel.dbInstance);
+      await resolver.resolve(results, options.include, 0, modelName);
+    }
+    const requestedLimit = options?.limit;
+    const hasMore = CursorManager.hasMoreResults(
+      requestedLimit,
+      results.length
+    );
+    const isFirstPage = !options?.uniqueStartKey;
+    const cursors = CursorManager.generateResultCursors(
+      results,
+      translatedQuery.sortFields,
+      options?.direction || 1,
+      hasMore,
+      isFirstPage
+    );
+    let transformedData;
+    if (options?.projection && Object.keys(options.projection).length > 0) {
+      transformedData = results.map((row) => {
+        const projected = {};
+        if (row.hasOwnProperty("id")) {
+          projected.id = row.id;
+        }
+        for (const [field, include] of Object.entries(options.projection)) {
+          if (include === 1 && row.hasOwnProperty(field)) {
+            projected[field] = row[field];
+          }
+        }
+        if (row._related) projected._related = row._related;
+        return projected;
+      });
+    } else {
+      const modelConstructor = this;
+      const documentYMaps = modelConstructor.documentYMaps;
+      const connectedDocuments = modelConstructor.connectedDocuments;
+      transformedData = results.map((data) => {
+        let foundRecordYMap;
+        let foundDocId;
+        for (const docId of connectedDocuments.keys()) {
+          const documentYMapKey = `${docId}_${modelName}`;
+          const documentYMap = documentYMaps.get(documentYMapKey);
+          if (documentYMap) {
+            const recordYMap = documentYMap.get(data.id);
+            if (recordYMap) {
+              foundRecordYMap = recordYMap;
+              foundDocId = docId;
+              break;
+            }
+          }
+        }
+        if (!foundRecordYMap || !foundDocId) {
+          Logger.warn(
+            `[${modelName}] Query result item ID ${data.id} not found in any connected document YMap. DB might be out of sync.`
+          );
+          return null;
+        }
+        const instance = new this({ id: data.id });
+        if (instance && typeof instance === "object" && instance instanceof _BaseModel) {
+          instance._metaDocId = foundDocId;
+          instance._metaPermissionHint = "read-write";
+          if (data._related) instance._related = data._related;
+        }
+        return instance;
+      }).filter(Boolean);
+    }
+    return {
+      data: transformedData,
+      nextCursor: cursors.nextCursor,
+      prevCursor: cursors.prevCursor,
+      hasMore
+    };
+  }
+  /**
+   * Main aggregation API - performs grouping, faceting, and statistical operations
+   * @param options Aggregation configuration with groupBy, operations, filter, limit, and sort
+   * @returns Nested object structure with aggregation results
+   *
+   * @example
+   * // Simple facet count
+   * const tagCounts = await Model.aggregate({
+   *   groupBy: ['tags'],
+   *   operations: [{ type: 'count' }]
+   * });
+   * // Result: { red: 15, blue: 8, green: 12 }
+   *
+   * @example
+   * // Multi-dimensional grouping with multiple operations
+   * const categoryStats = await Model.aggregate({
+   *   groupBy: ['category', 'status'],
+   *   operations: [
+   *     { type: 'count' },
+   *     { type: 'sum', field: 'amount' },
+   *     { type: 'avg', field: 'score' }
+   *   ],
+   *   filter: { active: true },
+   *   sort: { field: 'count', direction: 'desc' },
+   *   limit: 10
+   * });
+   *
+   * @example
+   * // StringSet membership grouping
+   * const urgentCounts = await Model.aggregate({
+   *   groupBy: [{ field: 'tags', contains: 'urgent' }],
+   *   operations: [{ type: 'count' }]
+   * });
+   * // Result: { true: 5, false: 23 }
+   */
+  static async aggregate(options) {
+    if (!_BaseModel.dbInstance) {
+      const modelNameForError = this.modelName || this.name || "BaseModel";
+      throw new Error(
+        `[${modelNameForError}] Database not initialized for aggregation. Connect at least one document via initJsBao(...).connectDocument or call initializeForDocument(yDoc, db, docId, permissionHint) before running aggregations.`
+      );
+    }
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options?.name) {
+      throw new Error("Model not properly initialized for aggregation");
+    }
+    const modelName = schema.options.name;
+    Logger.verbose(`[${modelName}] Executing structured aggregation:`, options);
+    for (const operation of options.operations) {
+      if (operation.type !== "count" && !operation.field) {
+        throw new Error(
+          `Operation '${operation.type}' requires a field parameter`
+        );
+      }
+      if (operation.type === "count" && operation.field) {
+        throw new Error(`Operation 'count' should not have a field parameter`);
+      }
+    }
+    for (const groupBy of options.groupBy) {
+      if (typeof groupBy === "string") {
+        if (!schema.fields.has(groupBy)) {
+          throw new Error(`Unknown field '${groupBy}' in groupBy`);
+        }
+      } else {
+        if (!schema.fields.has(groupBy.field)) {
+          throw new Error(
+            `Unknown field '${groupBy.field}' in StringSet membership groupBy`
+          );
+        }
+        const fieldOptions = schema.fields.get(groupBy.field);
+        if (fieldOptions?.type !== "stringset") {
+          throw new Error(
+            `Field '${groupBy.field}' is not a StringSet field but used in membership groupBy`
+          );
+        }
+      }
+    }
+    const aggregationQuery = this.buildAggregationQuery(
+      options,
+      schema,
+      modelName
+    );
+    Logger.verbose(
+      `[${modelName}] Generated aggregation SQL:`,
+      aggregationQuery.sql
+    );
+    Logger.verbose(
+      `[${modelName}] Aggregation params:`,
+      aggregationQuery.params
+    );
+    const results = await _BaseModel.dbInstance.query(
+      aggregationQuery.sql,
+      aggregationQuery.params
+    );
+    Logger.verbose(
+      `[${modelName}] Aggregation returned ${results.length} results`
+    );
+    const processedResult = this.processAggregationResults(
+      results,
+      options,
+      aggregationQuery.aliasMetadata
+    );
+    if (aggregationQuery.aliasMetadata && aggregationQuery.aliasMetadata.length > 0) {
+      const debugMap = {};
+      for (const detail of aggregationQuery.aliasMetadata) {
+        debugMap[detail.alias] = {
+          field: detail.field,
+          contains: detail.contains,
+          originalAlias: detail.originalAlias
+        };
+      }
+      Object.defineProperty(processedResult, "aliasDebugMap", {
+        value: debugMap,
+        enumerable: false,
+        configurable: false,
+        writable: false
+      });
+    }
+    return processedResult;
+  }
+  /**
+   * Build SQL query for structured aggregation
+   */
+  static buildAggregationQuery(options, schema, modelName) {
+    const translator = new DocumentQueryTranslator(modelName, schema.fields);
+    const regularGroupBy = [];
+    const stringSetFacets = [];
+    const stringSetMemberships = [];
+    for (const groupBy of options.groupBy) {
+      if (typeof groupBy === "string") {
+        const fieldOptions = schema.fields.get(groupBy);
+        if (fieldOptions?.type === "stringset") {
+          stringSetFacets.push(groupBy);
+        } else {
+          regularGroupBy.push(groupBy);
+        }
+      } else {
+        stringSetMemberships.push(groupBy);
+      }
+    }
+    if (stringSetFacets.length > 0 && regularGroupBy.length === 0 && stringSetMemberships.length === 0) {
+      return this.buildStringSetFacetQuery(
+        stringSetFacets,
+        options,
+        translator,
+        modelName
+      );
+    } else if (stringSetMemberships.length > 0 || regularGroupBy.length > 0) {
+      return this.buildRegularAggregationQuery(
+        regularGroupBy,
+        stringSetMemberships,
+        options,
+        translator,
+        modelName
+      );
+    } else {
+      throw new Error("Invalid aggregation configuration");
+    }
+  }
+  /**
+   * Get the proper database table name (should match database engine naming)
+   */
+  static getDatabaseTableName(modelName) {
+    return `model_${modelName.toLowerCase()}`;
+  }
+  /**
+   * Get the proper database junction table name for StringSet fields
+   */
+  static getDatabaseJunctionTableName(modelName, fieldName) {
+    return `${this.getDatabaseTableName(modelName)}_${fieldName}`;
+  }
+  static buildMembershipKey(field, contains) {
+    return `${field}::${contains}`;
+  }
+  /**
+   * Build query for StringSet facet counts
+   */
+  static buildStringSetFacetQuery(stringSetFields, options, translator, modelName) {
+    if (stringSetFields.length > 1) {
+      throw new Error(
+        "Multiple StringSet facet fields not supported in single aggregation"
+      );
+    }
+    const fieldName = stringSetFields[0];
+    const junctionTable = this.getDatabaseJunctionTableName(
+      modelName,
+      fieldName
+    );
+    const quotedJunctionTable = quoteIdentifier(junctionTable);
+    const mainTable = this.getDatabaseTableName(modelName);
+    const quotedMainTable = quoteIdentifier(mainTable);
+    const recordIdColumn = `${modelName.toLowerCase()}_id`;
+    const quotedRecordIdColumn = quoteIdentifier(recordIdColumn);
+    const quotedValueColumn = quoteIdentifier("value");
+    const groupKeyAlias = quoteIdentifier("group_key");
+    let sql = `
+      SELECT 
+        ${quotedJunctionTable}.${quotedValueColumn} AS ${groupKeyAlias},
+        COUNT(*) as count
+      FROM ${quotedJunctionTable}
+      INNER JOIN ${quotedMainTable} ON ${quotedJunctionTable}.${quotedRecordIdColumn} = ${quotedMainTable}.${quoteIdentifier(
+      "id"
+    )}
+    `;
+    let params = [];
+    if (options.filter && Object.keys(options.filter).length > 0) {
+      const whereClause = translator.translateFind(options.filter, {});
+      const whereMatch = whereClause.sql.match(
+        /WHERE\s+(.+?)(?:\s+ORDER\s+BY|\s+LIMIT|\s*$)/i
+      );
+      if (whereMatch && whereMatch[1]) {
+        sql += ` WHERE ${whereMatch[1]}`;
+        params = whereClause.params;
+      }
+    }
+    sql += ` GROUP BY ${quotedJunctionTable}.${quotedValueColumn}`;
+    if (options.sort) {
+      const sortField = options.sort.field === "count" ? "COUNT(*)" : quoteIdentifier(options.sort.field);
+      const sqlDirection = options.sort.direction === 1 ? "ASC" : "DESC";
+      sql += ` ORDER BY ${sortField} ${sqlDirection}`;
+    }
+    if (options.limit) {
+      sql += ` LIMIT ${options.limit}`;
+    }
+    return { sql, params };
+  }
+  /**
+   * Build query for regular field aggregation
+   */
+  static buildRegularAggregationQuery(regularGroupBy, stringSetMemberships, options, translator, modelName) {
+    const mainTable = this.getDatabaseTableName(modelName);
+    const quotedMainTable = quoteIdentifier(mainTable);
+    const recordIdColumn = `${modelName.toLowerCase()}_id`;
+    const quotedRecordIdColumn = quoteIdentifier(recordIdColumn);
+    const quotedIdColumn = quoteIdentifier("id");
+    const quotedValueColumn = quoteIdentifier("value");
+    const selectParts = [];
+    const aliasMetadata = [];
+    const usedAliases = /* @__PURE__ */ new Set();
+    for (const field of regularGroupBy) {
+      selectParts.push(`${quotedMainTable}.${quoteIdentifier(field)}`);
+    }
+    for (const membership of stringSetMemberships) {
+      const membershipKey = this.buildMembershipKey(
+        membership.field,
+        membership.contains
+      );
+      const originalAlias = `has_${membership.field}_${membership.contains}`;
+      let aliasPrefix = `has_${membership.field}`;
+      let alias = buildSafeAlias(aliasPrefix, membershipKey);
+      let counter = 1;
+      while (usedAliases.has(alias)) {
+        alias = buildSafeAlias(`${aliasPrefix}_${counter++}`, membershipKey);
+      }
+      usedAliases.add(alias);
+      const quotedAlias = quoteIdentifier(alias);
+      selectParts.push(
+        `CASE WHEN ${quotedAlias}.${quotedRecordIdColumn} IS NOT NULL THEN 'true' ELSE 'false' END AS ${quotedAlias}`
+      );
+      aliasMetadata.push({
+        alias,
+        membershipKey,
+        field: membership.field,
+        contains: membership.contains,
+        originalAlias
+      });
+    }
+    for (const operation of options.operations) {
+      switch (operation.type) {
+        case "count":
+          selectParts.push("COUNT(*) AS count");
+          break;
+        case "sum": {
+          const fieldName = operation.field;
+          selectParts.push(
+            `SUM(${quotedMainTable}.${quoteIdentifier(
+              fieldName
+            )}) AS ${quoteIdentifier(`sum_${fieldName}`)}`
+          );
+          break;
+        }
+        case "avg": {
+          const fieldName = operation.field;
+          selectParts.push(
+            `AVG(${quotedMainTable}.${quoteIdentifier(
+              fieldName
+            )}) AS ${quoteIdentifier(`avg_${fieldName}`)}`
+          );
+          break;
+        }
+        case "min": {
+          const fieldName = operation.field;
+          selectParts.push(
+            `MIN(${quotedMainTable}.${quoteIdentifier(
+              fieldName
+            )}) AS ${quoteIdentifier(`min_${fieldName}`)}`
+          );
+          break;
+        }
+        case "max": {
+          const fieldName = operation.field;
+          selectParts.push(
+            `MAX(${quotedMainTable}.${quoteIdentifier(
+              fieldName
+            )}) AS ${quoteIdentifier(`max_${fieldName}`)}`
+          );
+          break;
+        }
+      }
+    }
+    let sql = `SELECT ${selectParts.join(", ")} FROM ${quotedMainTable}`;
+    aliasMetadata.forEach((detail, index) => {
+      const membership = stringSetMemberships[index];
+      const junctionTable = this.getDatabaseJunctionTableName(
+        modelName,
+        membership.field
+      );
+      const quotedJunctionTable = quoteIdentifier(junctionTable);
+      const quotedAlias = quoteIdentifier(detail.alias);
+      sql += ` LEFT JOIN ${quotedJunctionTable} AS ${quotedAlias} ON ${quotedAlias}.${quotedRecordIdColumn} = ${quotedMainTable}.${quotedIdColumn} AND ${quotedAlias}.${quotedValueColumn} = ?`;
+    });
+    let params = [];
+    for (const membership of stringSetMemberships) {
+      params.push(membership.contains);
+    }
+    if (options.filter && Object.keys(options.filter).length > 0) {
+      const whereClause = translator.translateFind(options.filter, {});
+      const whereMatch = whereClause.sql.match(
+        /WHERE\s+(.+?)(?:\s+ORDER\s+BY|\s+LIMIT|\s*$)/i
+      );
+      if (whereMatch && whereMatch[1]) {
+        sql += ` WHERE ${whereMatch[1]}`;
+        params = params.concat(whereClause.params);
+      }
+    }
+    const groupByParts = [];
+    for (const field of regularGroupBy) {
+      groupByParts.push(`${quotedMainTable}.${quoteIdentifier(field)}`);
+    }
+    aliasMetadata.forEach((detail) => {
+      const quotedAlias = quoteIdentifier(detail.alias);
+      groupByParts.push(`${quotedAlias}.${quotedRecordIdColumn}`);
+    });
+    if (groupByParts.length > 0) {
+      sql += ` GROUP BY ${groupByParts.join(", ")}`;
+    }
+    if (options.sort) {
+      const requestedField = options.sort.field;
+      let sortExpression;
+      if (requestedField === "count") {
+        sortExpression = "COUNT(*)";
+      } else {
+        const membershipDetail = aliasMetadata.find(
+          (detail) => detail.alias === requestedField || detail.originalAlias === requestedField || detail.membershipKey === requestedField
+        );
+        if (membershipDetail) {
+          sortExpression = quoteIdentifier(membershipDetail.alias);
+        } else if (requestedField.startsWith("sum_") || requestedField.startsWith("avg_") || requestedField.startsWith("min_") || requestedField.startsWith("max_")) {
+          sortExpression = quoteIdentifier(requestedField);
+        } else {
+          sortExpression = `${quotedMainTable}.${quoteIdentifier(
+            requestedField
+          )}`;
+        }
+      }
+      const sqlDirection = options.sort.direction === 1 ? "ASC" : "DESC";
+      sql += ` ORDER BY ${sortExpression} ${sqlDirection}`;
+    }
+    if (options.limit) {
+      sql += ` LIMIT ${options.limit}`;
+    }
+    return { sql, params, aliasMetadata };
+  }
+  /**
+   * Process aggregation results into nested structure
+   */
+  static processAggregationResults(results, options, aliasMetadata) {
+    if (results.length === 0) {
+      return {};
+    }
+    const membershipAliasLookup = /* @__PURE__ */ new Map();
+    if (aliasMetadata) {
+      for (const detail of aliasMetadata) {
+        membershipAliasLookup.set(detail.membershipKey, detail.alias);
+        membershipAliasLookup.set(detail.originalAlias, detail.alias);
+      }
+    }
+    if (options.groupBy.length === 1 && typeof options.groupBy[0] === "string" && results[0].hasOwnProperty("group_key")) {
+      const facetResult = {};
+      for (const row of results) {
+        const key = row.group_key;
+        facetResult[key] = {};
+        for (const operation of options.operations) {
+          if (operation.type === "count") {
+            facetResult[key].count = row.count;
+          } else {
+            const operationKey = `${operation.type}_${operation.field}`;
+            facetResult[key][operationKey] = row[operationKey];
+          }
+        }
+        if (options.operations.length === 1 && options.operations[0].type === "count") {
+          facetResult[key] = row.count;
+        }
+      }
+      return facetResult;
+    }
+    const nestedResult = {};
+    for (const row of results) {
+      let current = nestedResult;
+      for (let i = 0; i < options.groupBy.length; i++) {
+        const groupBy = options.groupBy[i];
+        let key;
+        if (typeof groupBy === "string") {
+          key = String(row[groupBy]);
+        } else {
+          const membershipKey = this.buildMembershipKey(
+            groupBy.field,
+            groupBy.contains
+          );
+          const resolvedAlias = membershipAliasLookup.get(membershipKey) || membershipAliasLookup.get(
+            `has_${groupBy.field}_${groupBy.contains}`
+          );
+          if (!resolvedAlias) {
+            throw new Error(
+              `Missing alias metadata for StringSet membership ${groupBy.field}:${groupBy.contains}`
+            );
+          }
+          key = row[resolvedAlias];
+        }
+        if (i === options.groupBy.length - 1) {
+          current[key] = {};
+          for (const operation of options.operations) {
+            if (operation.type === "count") {
+              current[key].count = row.count;
+            } else {
+              const operationKey = `${operation.type}_${operation.field}`;
+              current[key][operationKey] = row[operationKey];
+            }
+          }
+          if (options.operations.length === 1 && options.operations[0].type === "count") {
+            current[key] = row.count;
+          }
+        } else {
+          if (!current[key]) {
+            current[key] = {};
+          }
+          current = current[key];
+        }
+      }
+    }
+    return nestedResult;
+  }
+  /**
+   * Document-style query API - returns single result or null
+   */
+  static async queryOne(filter = {}, options) {
+    const result = await this.query(filter, { ...options, limit: 1 });
+    return result.data.length > 0 ? result.data[0] : null;
+  }
+  /**
+   * Document-style count API
+   */
+  static async count(filter = {}, options) {
+    if (!_BaseModel.dbInstance) {
+      const modelNameForError = this.modelName || this.name || "BaseModel";
+      throw new Error(
+        `[${modelNameForError}] Database not initialized for count. Connect at least one document via initJsBao(...).connectDocument or call initializeForDocument(yDoc, db, docId, permissionHint) before running counts.`
+      );
+    }
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options?.name) {
+      throw new Error("Model not properly initialized for count");
+    }
+    const modelName = schema.options.name;
+    Logger.verbose(`[${modelName}] Executing count:`, { filter, options });
+    const translator = new DocumentQueryTranslator(modelName, schema.fields);
+    const translatedQuery = translator.translateCount(filter, options);
+    Logger.verbose(`[${modelName}] Translated count SQL:`, translatedQuery.sql);
+    Logger.verbose(`[${modelName}] Count SQL params:`, translatedQuery.params);
+    const results = await _BaseModel.dbInstance.query(
+      translatedQuery.sql,
+      translatedQuery.params
+    );
+    const count = results[0]?.count || 0;
+    Logger.verbose(`[${modelName}] Count returned:`, count);
+    return count;
+  }
+  static async findAll() {
+    const schema = this.getSchema?.();
+    if (!schema || !schema.options.name)
+      throw new Error("Model not properly initialized for findAll");
+    const modelName = schema.options.name;
+    const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
+    if (verboseEnabled) {
+      Logger.verbose(`[${modelName}] Finding all items`);
+    }
+    const modelConstructor = this;
+    const allInstances = [];
+    if (modelConstructor.documentYMaps && modelConstructor.connectedDocuments && modelConstructor.connectedDocuments.size > 0) {
+      if (verboseEnabled) {
+        Logger.verbose(`[${modelName}.findAll] Using multi-document system`);
+      }
+      for (const [docId] of modelConstructor.connectedDocuments) {
+        if (verboseEnabled) {
+          Logger.verbose(
+            `[${modelName}.findAll] Searching in document: ${docId}`
+          );
+        }
+        const documentYMapKey = `${docId}_${modelName}`;
+        const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
+        if (documentYMap) {
+          if (verboseEnabled) {
+            Logger.verbose(
+              `[${modelName}.findAll] DocumentYMap found for ${docId}, keys: [${Array.from(
+                documentYMap.keys()
+              ).join(", ")}]`
+            );
+          }
+          for (const [recordId, recordYMap] of documentYMap.entries()) {
+            if (recordYMap instanceof Y.Map) {
+              const instance = new this({ id: recordId });
+              instance._metaDocId = docId;
+              const connectedDoc = modelConstructor.connectedDocuments.get(docId);
+              if (connectedDoc) {
+                instance._metaPermissionHint = connectedDoc.permissionHint;
+              }
+              allInstances.push(instance);
+            } else {
+              Logger.warn(
+                `[${modelName}] Found legacy plain object in document ${docId}, consider migrating data`
+              );
+              allInstances.push(new this(recordYMap));
+            }
+          }
+        }
+      }
+    }
+    if (verboseEnabled) {
+      Logger.verbose(
+        `[${modelName}.findAll] Found ${allInstances.length} total instances`
+      );
+    }
+    return allInstances;
+  }
+  static async findByUnique(constraintName, value) {
+    const modelConstructor = this;
+    const schema = modelConstructor.getSchema();
+    const currentModelName = modelConstructor.modelName || schema?.options?.name || "BaseModel";
+    if (!schema || !schema.options || !schema.resolvedUniqueConstraints) {
+      throw new Error(
+        `[${currentModelName}] Schema or unique constraints not loaded for findByUnique.`
+      );
+    }
+    const constraint = schema.resolvedUniqueConstraints.find(
+      (c) => c.name === constraintName
+    );
+    if (!constraint) {
+      throw new Error(
+        `[${currentModelName}] Unique constraint named '${constraintName}' not found.`
+      );
+    }
+    const keyValues = Array.isArray(value) ? value : [value];
+    const uniqueKeyString = modelConstructor._buildKeyFromValues(
+      constraint.fields,
+      keyValues,
+      currentModelName,
+      constraint.name
+    );
+    if (uniqueKeyString === null) {
+      Logger.verbose(
+        `[${currentModelName}] findByUnique for '${constraintName}': unique key could not be built. Returning null.`
+      );
+      return null;
+    }
+    if (modelConstructor.documentYMaps && modelConstructor.connectedDocuments && modelConstructor.connectedDocuments.size > 0) {
+      Logger.verbose(
+        `[${currentModelName}.findByUnique] Using multi-document system`
+      );
+      for (const [docId] of modelConstructor.connectedDocuments) {
+        const documentInfo = modelConstructor.connectedDocuments.get(docId);
+        if (!documentInfo) continue;
+        const yDoc = documentInfo.yDoc;
+        const constraintMapName2 = `_uniqueIdx_${currentModelName}_${constraint.name}`;
+        const constraintMap2 = yDoc.getMap(constraintMapName2);
+        const recordId2 = constraintMap2.get(uniqueKeyString);
+        if (recordId2) {
+          const documentYMapKey = `${docId}_${currentModelName}`;
+          const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
+          if (documentYMap) {
+            const recordYMap2 = documentYMap.get(recordId2);
+            if (recordYMap2 && recordYMap2 instanceof Y.Map) {
+              const instance = new modelConstructor({
+                id: recordId2
+              });
+              instance._metaDocId = docId;
+              instance._metaPermissionHint = documentInfo.permissionHint;
+              Logger.verbose(
+                `[${currentModelName}.findByUnique] Found record '${recordId2}' in document '${docId}'`
+              );
+              return instance;
+            }
+          }
+        }
+      }
+      Logger.verbose(
+        `[${currentModelName}.findByUnique] Record not found in any connected document`
+      );
+      return null;
+    }
+    const legacyDocId = _BaseModel.DEFAULT_LEGACY_DOC_ID;
+    const legacyDocumentMap = modelConstructor.documentYMaps?.get(legacyDocId);
+    const legacyDocInfo = modelConstructor.connectedDocuments?.get(legacyDocId);
+    if (!legacyDocumentMap || !legacyDocInfo) {
+      throw new Error(
+        `[${currentModelName}] No Y.Doc is connected for this model. Connect a document via initJsBao(...).connectDocument or call initializeForDocument(yDoc, db, docId, permissionHint) before using legacy findByUnique.`
+      );
+    }
+    const constraintMapName = `_uniqueIdx_${currentModelName}_${constraint.name}`;
+    const constraintMap = legacyDocInfo.yDoc.getMap(constraintMapName);
+    const recordId = constraintMap.get(uniqueKeyString);
+    if (!recordId) {
+      return null;
+    }
+    const recordYMap = legacyDocumentMap.get(recordId);
+    if (!recordYMap) {
+      return null;
+    }
+    if (recordYMap instanceof Y.Map) {
+      const instance = new modelConstructor({
+        id: recordId
+      });
+      return instance;
+    } else {
+      return new modelConstructor(recordYMap);
+    }
+  }
+  static async upsertByUnique(constraintName, uniqueLookupValue, dataToUpsert, options) {
+    const modelConstructor = this;
+    const schema = modelConstructor.getSchema();
+    const currentModelName = modelConstructor.modelName || schema?.options?.name || "BaseModel";
+    if (!schema || !schema.options || !schema.resolvedUniqueConstraints) {
+      throw new Error(
+        `[${currentModelName}] Schema or unique constraints not loaded for upsertByUnique.`
+      );
+    }
+    const connectedDocuments = modelConstructor.connectedDocuments;
+    if (!connectedDocuments || connectedDocuments.size === 0) {
+      throw new Error(
+        `[${currentModelName}] No documents are connected. Connect at least one document via initJsBao(...).connectDocument or call initializeForDocument(yDoc, db, docId, permissionHint) before calling upsertByUnique.`
+      );
+    }
+    const constraint = schema.resolvedUniqueConstraints.find(
+      (c) => c.name === constraintName
+    );
+    if (!constraint) {
+      throw new Error(
+        `[${currentModelName}] Unique constraint named '${constraintName}' not found for upsert.`
+      );
+    }
+    const keyValuesForLookup = Array.isArray(uniqueLookupValue) ? uniqueLookupValue : [uniqueLookupValue];
+    constraint.fields.forEach((field, index) => {
+      if (!dataToUpsert.hasOwnProperty(field)) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: dataToUpsert is missing required unique field '${field}' from constraint '${constraintName}'.`
+        );
+      }
+      const dataValue = dataToUpsert[field];
+      const lookupValue = keyValuesForLookup[index];
+      if (dataValue !== lookupValue) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: Mismatch between dataToUpsert.'${field}' (value: ${dataValue}) and uniqueLookupValue for constraint '${constraintName}' (value: ${lookupValue}).`
+        );
+      }
+    });
+    const uniqueKeyString = modelConstructor._buildKeyFromValues(
+      constraint.fields,
+      keyValuesForLookup,
+      currentModelName,
+      constraint.name
+    );
+    if (uniqueKeyString === null) {
+      throw new Error(
+        `[${currentModelName}] upsertByUnique for '${constraintName}': unique key cannot be built due to null/undefined values. Upsert cannot proceed reliably.`
+      );
+    }
+    const constraintMapName = `_uniqueIdx_${currentModelName}_${constraint.name}`;
+    let existingRecord = null;
+    if (connectedDocuments && connectedDocuments.size > 0) {
+      for (const docId of connectedDocuments.keys()) {
+        const docInfo = connectedDocuments.get(docId);
+        if (docInfo) {
+          const constraintMap = docInfo.yDoc.getMap(constraintMapName);
+          const recordId = constraintMap.get(uniqueKeyString);
+          if (recordId) {
+            existingRecord = await modelConstructor.find(
+              recordId
+            );
+            break;
+          }
+        }
+      }
+    } else {
+    }
+    if (options?.objectMustExist) {
+      if (!existingRecord) {
+        throw new RecordNotFoundError(
+          `[${currentModelName}] upsertByUnique (objectMustExist): Record with constraint '${constraintName}' and value(s) starting with '${uniqueKeyString.substring(
+            0,
+            50
+          )}...' not found.`
+        );
+      }
+      Logger.verbose(
+        `[${currentModelName}] upsertByUnique (objectMustExist): Updating existing record ${existingRecord.id}`
+      );
+      Object.assign(existingRecord, dataToUpsert);
+      if (options?.targetDocument) {
+        await existingRecord.save({ targetDocument: options.targetDocument });
+      } else {
+        await existingRecord.save();
+      }
+      return existingRecord;
+    }
+    if (options?.objectMustNotExist) {
+      if (existingRecord) {
+        throw new UniqueConstraintViolationError(
+          `[${currentModelName}] upsertByUnique (objectMustNotExist): Record with constraint '${constraintName}' and value(s) starting with '${uniqueKeyString.substring(
+            0,
+            50
+          )}...' already exists with ID ${existingRecord.id}.`,
+          currentModelName,
+          constraintName,
+          constraint.fields,
+          dataToUpsert.id,
+          existingRecord.id
+        );
+      }
+      Logger.verbose(
+        `[${currentModelName}] upsertByUnique (objectMustNotExist): Creating new record.`
+      );
+      const newInstance = new modelConstructor(
+        dataToUpsert
+      );
+      if (!newInstance.id) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: ID must be provided in dataToUpsert or auto-generated by constructor for new records.`
+        );
+      }
+      if (!options?.targetDocument) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: targetDocument is required when creating new records.`
+        );
+      }
+      await newInstance.save({ targetDocument: options.targetDocument });
+      return newInstance;
+    }
+    if (existingRecord) {
+      Logger.verbose(
+        `[${currentModelName}] upsertByUnique (default): Updating existing record ${existingRecord.id}`
+      );
+      Object.assign(existingRecord, dataToUpsert);
+      if (options?.targetDocument) {
+        await existingRecord.save({ targetDocument: options.targetDocument });
+      } else {
+        await existingRecord.save();
+      }
+      return existingRecord;
+    } else {
+      Logger.verbose(
+        `[${currentModelName}] upsertByUnique (default): Creating new record.`
+      );
+      const newInstance = new modelConstructor(
+        dataToUpsert
+      );
+      if (!newInstance.id) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: ID must be provided in dataToUpsert or auto-generated by constructor for new records.`
+        );
+      }
+      if (!options?.targetDocument) {
+        throw new Error(
+          `[${currentModelName}] upsertByUnique: targetDocument is required when creating new records.`
+        );
+      }
+      await newInstance.save({ targetDocument: options.targetDocument });
+      return newInstance;
+    }
+  }
+  /**
+   * Execute a callback with automatic transaction handling for all modified models
+   */
+  static async withTransaction(callback) {
+    const modifiedModels = /* @__PURE__ */ new Set();
+    const originalSetValue = _BaseModel.prototype.setValue;
+    _BaseModel.prototype.setValue = function(fieldKey, value) {
+      modifiedModels.add(this);
+      return originalSetValue.call(this, fieldKey, value);
+    };
+    try {
+      const result = await callback();
+      if (modifiedModels.size > 0) {
+        Logger.verbose(
+          `[BaseModel] Transaction saving ${modifiedModels.size} modified models`
+        );
+        let yDoc = null;
+        const firstModel = Array.from(modifiedModels)[0];
+        const modelConstructor = firstModel.constructor;
+        if (modelConstructor.connectedDocuments && modelConstructor.connectedDocuments.size > 0) {
+          yDoc = Array.from(modelConstructor.connectedDocuments.values())[0].yDoc;
+        }
+        if (yDoc) {
+          await yDoc.transact(async () => {
+            for (const model of modifiedModels) {
+              if (model.isDirty) {
+                await model.save();
+              }
+            }
+          }, "batch-model-transaction");
+        } else {
+          for (const model of modifiedModels) {
+            if (model.isDirty) {
+              await model.save();
+            }
+          }
+        }
+      }
+      return result;
+    } finally {
+      _BaseModel.prototype.setValue = originalSetValue;
+    }
+  }
+  /**
+   * Sets up deep observation on a nested YMap to sync field-level changes to the database
+   */
+  static setupNestedYMapObserver(recordId, recordYMap) {
+    const modelConstructor = this;
+    const schema = modelConstructor.getSchema();
+    const modelName = schema?.options?.name;
+    if (!modelName) {
+      Logger.error(
+        `[${modelConstructor.name}] Cannot setup nested YMap observer: model name not found`
+      );
+      return;
+    }
+    Logger.verbose(
+      `[${modelName}] Setting up nested YMap observer for record ${recordId}`
+    );
+    recordYMap.observe(async (event) => {
+      Logger.verbose(
+        `[${modelName}] Nested YMap change detected for record ${recordId}:`,
+        event
+      );
+      const currentDbInstance = _BaseModel.dbInstance;
+      if (!currentDbInstance) {
+        Logger.error(
+          `[${modelName}] DB instance not available for nested YMap observer on record ${recordId}`
+        );
+        return;
+      }
+      const updatedData = {};
+      const unknownFields = [];
+      for (const [key, value] of recordYMap.entries()) {
+        const fieldOptions = schema?.fields?.get(key);
+        if (!fieldOptions) {
+          unknownFields.push(key);
+          continue;
+        }
+        if (fieldOptions.type === "stringset") {
+          continue;
+        }
+        if (value !== void 0) {
+          updatedData[key] = value;
+        }
+      }
+      if (unknownFields.length > 0) {
+        Logger.warn(
+          `[${modelName}] Ignoring unknown fields [${unknownFields.join(
+            ", "
+          )}] when syncing nested record ${recordId}`
+        );
+      }
+      if (!updatedData.id) {
+        Logger.warn(
+          `[${modelName}] Nested YMap change for ${recordId} missing id field, skipping DB sync`
+        );
+        return;
+      }
+      try {
+        Logger.verbose(
+          `[${modelName}] Syncing nested YMap changes to database for record ${recordId}:`,
+          updatedData
+        );
+        await currentDbInstance.insert(modelName, {
+          ...updatedData,
+          type: modelName
+        });
+        Logger.verbose(
+          `[${modelName}] Database sync completed for nested YMap changes on record ${recordId}`
+        );
+      } catch (error) {
+        Logger.error(
+          `[${modelName}] Error syncing nested YMap changes to database for record ${recordId}:`,
+          error,
+          updatedData
+        );
+      }
+      modelConstructor.notifyListeners();
+    });
+  }
+  /**
+   * Sets up deep observation on a nested YMap for a specific document to sync field-level changes to the database
+   */
+  static setupNestedYMapObserverForDocument(recordId, recordYMap, docId, permissionHint) {
+    const modelConstructor = this;
+    const schema = modelConstructor.getSchema();
+    const modelName = schema?.options?.name;
+    if (!modelName) {
+      Logger.error(
+        `[${modelConstructor.name}] Cannot setup nested YMap observer: model name not found`
+      );
+      return;
+    }
+    Logger.verbose(
+      `[${modelName}] Setting up nested YMap observer for record ${recordId} in document ${docId}`
+    );
+    recordYMap.observe(async (event) => {
+      Logger.verbose(
+        `[${modelName}] Nested YMap change detected for record ${recordId} in document ${docId}:`,
+        event
+      );
+      const currentDbInstance = _BaseModel.dbInstance;
+      if (!currentDbInstance) {
+        Logger.error(
+          `[${modelName}] DB instance not available for nested YMap observer on record ${recordId} in document ${docId}`
+        );
+        return;
+      }
+      const updatedData = {};
+      const unknownFields = [];
+      for (const [key, value] of recordYMap.entries()) {
+        const fieldOptions = schema?.fields?.get(key);
+        if (!fieldOptions) {
+          unknownFields.push(key);
+          continue;
+        }
+        if (fieldOptions.type === "stringset") {
+          continue;
+        }
+        if (value !== void 0) {
+          updatedData[key] = value;
+        }
+      }
+      if (unknownFields.length > 0) {
+        Logger.warn(
+          `[${modelName}] Ignoring unknown fields [${unknownFields.join(
+            ", "
+          )}] when syncing nested record ${recordId} in document ${docId}`
+        );
+      }
+      if (!updatedData.id) {
+        Logger.warn(
+          `[${modelName}] Nested YMap change for ${recordId} in document ${docId} missing id field, skipping DB sync`
+        );
+        return;
+      }
+      try {
+        Logger.verbose(
+          `[${modelName}] Syncing nested YMap changes to database for record ${recordId} in document ${docId}:`,
+          updatedData
+        );
+        await currentDbInstance.insert(modelName, {
+          ...updatedData,
+          type: modelName,
+          _meta_doc_id: docId,
+          _meta_permission_hint: permissionHint
+        });
+        Logger.verbose(
+          `[${modelName}] Database sync completed for nested YMap changes on record ${recordId} in document ${docId}`
+        );
+      } catch (error) {
+        Logger.error(
+          `[${modelName}] Error syncing nested YMap changes to database for record ${recordId} in document ${docId}:`,
+          error,
+          updatedData
+        );
+      }
+      modelConstructor.notifyListeners();
+    });
+  }
+};
+
+export {
+  StringSet,
+  assertValidIdentifier,
+  quoteIdentifier,
+  DocumentQueryTranslator,
+  LogLevel,
+  Logger,
+  UniqueConstraintViolationError,
+  RecordNotFoundError,
+  generateULID,
+  BaseModel
+};
+//# sourceMappingURL=chunk-6UX3YSCW.js.map