js-bao 0.5.0 → 0.5.2

package/dist/browser.cjs

@@ -366,21 +366,36 @@ var init_CursorManager = __esm({
         return fields;
       }
       /**
-       * Build ORDER BY clause from sort specification
+       * Build ORDER BY clause from sort specification.
+       *
+       * `direction` is the pagination direction (1 = forward, -1 = backward).
+       * For backward pagination each field's effective ORDER BY direction is
+       * reversed so the cursor's flipped inequality (built by
+       * `buildPaginationConditions`) returns the page adjacent to the cursor,
+       * not the globally smallest/largest window. Without this,
+       * `field < cursor ... ORDER BY field ASC LIMIT n` returns the n smallest
+       * rows overall instead of the n rows just below the cursor.
+       *
+       * The returned `directions` array carries the *declared* per-field sort
+       * directions (unaffected by `direction`) — `buildPaginationConditions`
+       * needs the declared directions to pick each field's comparison operator.
        */
-      static buildOrderClause(sort, fieldFormatter = (field) => field) {
+      static buildOrderClause(sort, fieldFormatter = (field) => field, direction = 1) {
         const fields = this.extractSortFields(sort);
         const clauses = [];
         const directions = [];
+        const sqlDir = (declared) => {
+          const effective = direction === -1 ? declared === 1 ? -1 : 1 : declared;
+          return effective === 1 ? "ASC" : "DESC";
+        };
         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}`);
+            clauses.push(`${fieldFormatter(field)} ${sqlDir(dir)}`);
             directions.push(dir);
           }
         }
         if (!sort || !sort.hasOwnProperty("id")) {
-          clauses.push(`${fieldFormatter("id")} ASC`);
+          clauses.push(`${fieldFormatter("id")} ${sqlDir(1)}`);
           directions.push(1);
         } else if (sort && sort.hasOwnProperty("id")) {
           directions.push(sort["id"]);
@@ -403,18 +418,27 @@ var init_CursorManager = __esm({
       /**
        * Generate next and previous cursors from result set
        */
-      static generateResultCursors(results, sortFields, _requestedDirection, hasMore, isFirstPage = false) {
+      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);
+          cursors.nextCursor = this.generateCursor(
+            lastResult,
+            sortFields,
+            requestedDirection
+          );
         }
         if (results.length > 0 && !isFirstPage) {
           const firstResult = results[0];
-          cursors.prevCursor = this.generateCursor(firstResult, sortFields, -1);
+          const opposite = requestedDirection === 1 ? -1 : 1;
+          cursors.prevCursor = this.generateCursor(
+            firstResult,
+            sortFields,
+            opposite
+          );
         }
         return cursors;
       }
@@ -547,7 +571,8 @@ var init_DocumentQueryTranslator = __esm({
         const whereClause = this.translateFilter(filter);
         const orderClause = CursorManager.buildOrderClause(
           options?.sort,
-          (field) => this.getQuotedField(field)
+          (field) => this.getQuotedField(field),
+          options?.direction || 1
         );
         const limitClause = this.buildLimitClause(options);
         const paginationClause = this.buildPaginationClause(
@@ -1183,9 +1208,109 @@ var init_DocumentQueryTranslator = __esm({
   }
 });
 
+// src/utils/yjsValues.ts
+function isYjsComposite(value) {
+  return value instanceof Y.Map || value instanceof Y.Array || value instanceof Y.Text;
+}
+function isStringSetYMap(value) {
+  if (!(value instanceof Y.Map)) return false;
+  for (const v of value.values()) {
+    if (v !== true) return false;
+  }
+  return true;
+}
+function normalizeYjsValue(value) {
+  if (value instanceof Y.Text) {
+    return value.toString();
+  }
+  if (value instanceof Y.Map || value instanceof Y.Array) {
+    return value.toJSON();
+  }
+  return value;
+}
+function normalizeYjsValueForStorage(value) {
+  if (value instanceof Y.Text) {
+    return value.toString();
+  }
+  if (value instanceof Y.Map || value instanceof Y.Array) {
+    return JSON.stringify(value.toJSON());
+  }
+  return value;
+}
+var Y;
+var init_yjsValues = __esm({
+  "src/utils/yjsValues.ts"() {
+    "use strict";
+    Y = __toESM(require("yjs"), 1);
+  }
+});
+
+// src/models/writeLifecycle.ts
+function ensureStringSetYMap(rm, fieldName) {
+  const nested = rm.get(fieldName);
+  if (nested instanceof Y2.Map) return nested;
+  const fresh = new Y2.Map();
+  if (nested && typeof nested === "object") {
+    for (const [member, marker] of Object.entries(
+      nested
+    )) {
+      if (Boolean(marker)) fresh.set(member, true);
+    }
+  }
+  rm.set(fieldName, fresh);
+  return fresh;
+}
+function applyStringSetDelta(target, delta) {
+  if (delta.clear) {
+    for (const member of Array.from(target.keys())) target.delete(member);
+  }
+  if (delta.remove) {
+    for (const member of delta.remove) target.delete(String(member));
+  }
+  if (delta.add) {
+    for (const member of delta.add) {
+      const key = String(member);
+      if (target.get(key) !== true) target.set(key, true);
+    }
+  }
+}
+function applyStringSetChange(recordYMap, fieldName, change) {
+  const target = ensureStringSetYMap(recordYMap, fieldName);
+  applyStringSetDelta(target, {
+    add: change.additions,
+    remove: change.removals
+  });
+}
+function registerFunctionDefaultGenerator(name, fn) {
+  FUNCTION_DEFAULT_GENERATORS.set(name, fn);
+}
+function resolveLiteralOrFunctionDefault(rawDefault) {
+  return typeof rawDefault === "function" ? rawDefault() : rawDefault;
+}
+var Y2, import_ulid, KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS, UNKNOWN_FUNCTION_DEFAULT;
+var init_writeLifecycle = __esm({
+  "src/models/writeLifecycle.ts"() {
+    "use strict";
+    Y2 = __toESM(require("yjs"), 1);
+    import_ulid = require("ulid");
+    KNOWN_FIELD_TYPE_MAP = {
+      string: true,
+      number: true,
+      boolean: true,
+      date: true,
+      id: true,
+      stringset: true
+    };
+    KNOWN_FIELD_TYPES = new Set(Object.keys(KNOWN_FIELD_TYPE_MAP));
+    FUNCTION_DEFAULT_GENERATORS = /* @__PURE__ */ new Map();
+    registerFunctionDefaultGenerator("generate_ulid", () => (0, import_ulid.ulid)());
+    UNKNOWN_FUNCTION_DEFAULT = "$unknown_function";
+  }
+});
+
 // src/models/metaSync.ts
 function inferFieldType(value) {
-  if (value instanceof Y.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -1204,7 +1329,10 @@ function encodeDefault(value) {
   if (value === void 0 || value === null) return void 0;
   if (typeof value === "function") {
     const name = KNOWN_FUNCTION_DEFAULTS.get(value);
-    return name ? `$${name}` : "$unknown_function";
+    return name ? `$${name}` : UNKNOWN_FUNCTION_DEFAULT;
+  }
+  if (typeof value === "string" && value.startsWith("$")) {
+    return `$${value}`;
   }
   return value;
 }
@@ -1230,7 +1358,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (compoundConstraints.length > 0) {
     let constraints = meta.get("_constraints");
     if (!constraints) {
-      constraints = new Y.Map();
+      constraints = new Y3.Map();
       meta.set("_constraints", constraints);
     }
     for (const constraint of compoundConstraints) {
@@ -1241,7 +1369,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (relationships && Object.keys(relationships).length > 0) {
     let rels = meta.get("_relationships");
     if (!rels) {
-      rels = new Y.Map();
+      rels = new Y3.Map();
       meta.set("_relationships", rels);
     }
     for (const [relName, relConfig] of Object.entries(relationships)) {
@@ -1253,7 +1381,7 @@ function syncModelMeta(yDoc, modelName, schema) {
 function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   let fieldMeta = metaMap.get(fieldName);
   if (!fieldMeta) {
-    fieldMeta = new Y.Map();
+    fieldMeta = new Y3.Map();
     metaMap.set(fieldName, fieldMeta);
   }
   setIfChanged(fieldMeta, "type", fieldOpts.type);
@@ -1261,6 +1389,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   if (fieldOpts.unique) setIfChanged(fieldMeta, "unique", true);
   if (fieldOpts.required) setIfChanged(fieldMeta, "required", true);
   if (fieldOpts.autoAssign) setIfChanged(fieldMeta, "autoAssign", true);
+  if (fieldOpts.autoStamp) setIfChanged(fieldMeta, "autoStamp", fieldOpts.autoStamp);
   if (fieldOpts.maxLength !== void 0) setIfChanged(fieldMeta, "maxLength", fieldOpts.maxLength);
   if (fieldOpts.maxCount !== void 0) setIfChanged(fieldMeta, "maxCount", fieldOpts.maxCount);
   const encoded = encodeDefault(fieldOpts.default);
@@ -1269,7 +1398,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
 function syncConstraintMeta(constraintsMap, constraint) {
   let cMeta = constraintsMap.get(constraint.name);
   if (!cMeta) {
-    cMeta = new Y.Map();
+    cMeta = new Y3.Map();
     constraintsMap.set(constraint.name, cMeta);
   }
   setIfChanged(cMeta, "type", "unique");
@@ -1279,7 +1408,7 @@ function syncConstraintMeta(constraintsMap, constraint) {
 function syncRelationshipMeta(relsMap, relName, relConfig) {
   let relMeta = relsMap.get(relName);
   if (!relMeta) {
-    relMeta = new Y.Map();
+    relMeta = new Y3.Map();
     relsMap.set(relName, relMeta);
   }
   for (const [key, value] of Object.entries(relConfig)) {
@@ -1294,7 +1423,7 @@ function syncInferredMeta(yDoc, modelName, recordData) {
     if (fieldName.startsWith("_")) continue;
     let fieldMeta = meta.get(fieldName);
     if (!fieldMeta) {
-      fieldMeta = new Y.Map();
+      fieldMeta = new Y3.Map();
       meta.set(fieldName, fieldMeta);
     }
     if (!fieldMeta.has("type")) {
@@ -1310,17 +1439,58 @@ function setIfChanged(map, key, value) {
     map.set(key, value);
   }
 }
-var Y, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
+var Y3, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
+    init_yjsValues();
+    init_writeLifecycle();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
 });
 
+// src/utils/uniqueIndex.ts
+function buildUniqueKey(recordData, fields) {
+  const keyParts = [];
+  for (const field of fields) {
+    const value = recordData instanceof Y4.Map ? recordData.get(field) : recordData[field];
+    if (value === null || value === void 0) {
+      return null;
+    }
+    keyParts.push(String(value));
+  }
+  return keyParts.join("|");
+}
+function uniqueIndexMapName(modelName, constraintName) {
+  return `_uniqueIdx_${modelName}_${constraintName}`;
+}
+function fieldUniqueConstraintName(modelName, fieldName) {
+  return `${modelName}_${fieldName}_unique`;
+}
+var Y4;
+var init_uniqueIndex = __esm({
+  "src/utils/uniqueIndex.ts"() {
+    "use strict";
+    Y4 = __toESM(require("yjs"), 1);
+  }
+});
+
 // src/models/relationshipManager.ts
+function warnIfOrderFieldNullable(modelClass, orderByField, relationshipDescription) {
+  if (ALWAYS_PRESENT_ORDER_FIELDS.has(orderByField)) return;
+  const schema = modelClass.getSchema?.();
+  const fields = schema?.fields;
+  if (!fields || typeof fields.get !== "function") return;
+  const fieldOptions = fields.get(orderByField);
+  if (!fieldOptions) return;
+  if (fieldOptions.required !== true) {
+    Logger.warn(
+      `[RelationshipManager] ${relationshipDescription} orders by '${orderByField}', which is not marked required on ${modelClass.name}. The composite (${orderByField}, id) cursor paginates deterministically, but a row whose '${orderByField}' is actually NULL has no stable cursor position and may drop from the tail. Mark '${orderByField}' as required, or order by a required field such as 'id', to remove the risk. (Full NULL-ordering support is tracked in #1316.)`
+    );
+  }
+}
 function generateRefersToMethod(_sourceModelClass, config, targetModelClass) {
   return async function() {
     const relatedId = this[config.relatedIdField];
@@ -1329,6 +1499,16 @@ function generateRefersToMethod(_sourceModelClass, config, targetModelClass) {
   };
 }
 function generateHasManyMethod(_sourceModelClass, config, targetModelClass, _dbEngine) {
+  const {
+    relatedIdField,
+    orderByField = "id",
+    orderDirection = "ASC"
+  } = config;
+  warnIfOrderFieldNullable(
+    targetModelClass,
+    orderByField,
+    `hasMany(${targetModelClass.name})`
+  );
   return async function(paginationArgs) {
     const {
       limit,
@@ -1336,71 +1516,39 @@ function generateHasManyMethod(_sourceModelClass, config, targetModelClass, _dbE
       beforeCursor,
       direction = "forward"
     } = paginationArgs || {};
-    const {
-      relatedIdField,
-      orderByField = "id",
-      orderDirection = "ASC"
-    } = config;
     const targetSchema = targetModelClass.getSchema();
     if (!targetSchema || !targetSchema.options || !targetSchema.options.name) {
       Logger.error(
         `[RelationshipManager] Target model ${targetModelClass.name} for hasMany relationship has no valid schema name.`
       );
-      return { data: [], nextCursor: null, prevCursor: null };
+      return { data: [], hasMore: false };
     }
-    const filter = { [relatedIdField]: this.id };
+    const forward = direction !== "backward";
+    const cursor = forward ? afterCursor : beforeCursor;
     const queryOptions = {
-      sort: { [orderByField]: orderDirection === "ASC" ? 1 : -1 }
+      sort: { [orderByField]: orderDirection === "ASC" ? 1 : -1 },
+      direction: forward ? 1 : -1
     };
-    if (limit !== void 0) {
-      queryOptions.limit = limit + 1;
-    }
-    if (direction === "forward" && afterCursor) {
-      filter[orderByField] = {
-        [orderDirection === "ASC" ? "$gt" : "$lt"]: afterCursor
-      };
-    } else if (direction === "backward") {
-      if (beforeCursor) {
-        filter[orderByField] = {
-          [orderDirection === "ASC" ? "$lt" : "$gt"]: beforeCursor
-        };
-      }
-      queryOptions.sort = { [orderByField]: orderDirection === "ASC" ? -1 : 1 };
-    }
-    const result = await targetModelClass.query(filter, queryOptions);
-    const results = result.data;
-    let nextCursor = null;
-    let prevCursor = null;
-    const isFirstPage = direction === "forward" && !afterCursor;
-    if (limit !== void 0) {
-      if (direction === "forward") {
-        if (results.length > limit) {
-          nextCursor = results[limit - 1][orderByField];
-          results.pop();
-        }
-        if (results.length > 0 && !isFirstPage) {
-          prevCursor = results[0][orderByField];
-        }
-      } else {
-        if (results.length > limit) {
-          prevCursor = results[limit - 1][orderByField];
-          results.pop();
-        }
-        results.reverse();
-        if (results.length > 0 && beforeCursor) {
-          nextCursor = results[results.length - 1][orderByField];
-        }
-        if (results.length > 0 && !beforeCursor) {
-          if (results.length === limit) {
-            prevCursor = results[0][orderByField];
-          }
-        }
-      }
-    }
-    return { data: results, nextCursor, prevCursor };
+    if (limit !== void 0) queryOptions.limit = limit;
+    if (cursor != null) queryOptions.uniqueStartKey = cursor;
+    return targetModelClass.query(
+      { [relatedIdField]: this.id },
+      queryOptions
+    );
   };
 }
 function generateHasManyThroughMethod(_sourceModelClass, config, targetModelClass, joinModelClass, _dbEngine) {
+  const {
+    joinModelLocalField,
+    joinModelRelatedField,
+    joinModelOrderByField = "id",
+    joinModelOrderDirection = "ASC"
+  } = config;
+  warnIfOrderFieldNullable(
+    joinModelClass,
+    joinModelOrderByField,
+    `hasManyThrough(${targetModelClass.name} via ${joinModelClass.name})`
+  );
   return async function(paginationArgs) {
     const {
       limit,
@@ -1414,87 +1562,42 @@ function generateHasManyThroughMethod(_sourceModelClass, config, targetModelClas
       Logger.error(
         `[RelationshipManager] Join model ${joinModelClass.name} for hasManyThrough relationship has no valid schema name.`
       );
-      return { data: [], nextCursor: null, prevCursor: null };
+      return { data: [], hasMore: false };
     }
     if (!targetSchema || !targetSchema.options || !targetSchema.options.name) {
       Logger.error(
         `[RelationshipManager] Target model ${targetModelClass.name} for hasManyThrough relationship has no valid schema name.`
       );
-      return { data: [], nextCursor: null, prevCursor: null };
+      return { data: [], hasMore: false };
     }
-    const {
-      joinModelLocalField,
-      joinModelRelatedField,
-      joinModelOrderByField = "id",
-      joinModelOrderDirection = "ASC"
-    } = config;
-    const joinFilter = { [joinModelLocalField]: this.id };
+    const forward = direction !== "backward";
+    const cursor = forward ? afterCursor : beforeCursor;
     const joinQueryOptions = {
       sort: {
         [joinModelOrderByField]: joinModelOrderDirection === "ASC" ? 1 : -1
       },
-      projection: { [joinModelRelatedField]: 1, [joinModelOrderByField]: 1 }
+      projection: { [joinModelRelatedField]: 1, [joinModelOrderByField]: 1 },
+      direction: forward ? 1 : -1
     };
-    if (limit !== void 0) {
-      joinQueryOptions.limit = limit + 1;
-    }
-    if (direction === "forward" && afterCursor) {
-      joinFilter[joinModelOrderByField] = {
-        [joinModelOrderDirection === "ASC" ? "$gt" : "$lt"]: afterCursor
-      };
-    } else if (direction === "backward") {
-      if (beforeCursor) {
-        joinFilter[joinModelOrderByField] = {
-          [joinModelOrderDirection === "ASC" ? "$lt" : "$gt"]: beforeCursor
-        };
-      }
-      joinQueryOptions.sort = {
-        [joinModelOrderByField]: joinModelOrderDirection === "ASC" ? -1 : 1
-      };
-    }
+    if (limit !== void 0) joinQueryOptions.limit = limit;
+    if (cursor != null) joinQueryOptions.uniqueStartKey = cursor;
     const joinResult = await joinModelClass.query(
-      joinFilter,
+      { [joinModelLocalField]: this.id },
       joinQueryOptions
     );
-    const joinResults = joinResult.data;
-    let nextCursorFromJoin = null;
-    let prevCursorFromJoin = null;
-    const isFirstPage = direction === "forward" && !afterCursor;
-    if (limit !== void 0) {
-      if (direction === "forward") {
-        if (joinResults.length > limit) {
-          nextCursorFromJoin = joinResults[limit - 1][joinModelOrderByField];
-          joinResults.pop();
-        }
-        if (joinResults.length > 0 && !isFirstPage) {
-          prevCursorFromJoin = joinResults[0][joinModelOrderByField];
-        }
-      } else {
-        if (joinResults.length > limit) {
-          prevCursorFromJoin = joinResults[limit - 1][joinModelOrderByField];
-          joinResults.pop();
-        }
-        joinResults.reverse();
-        if (joinResults.length > 0 && beforeCursor) {
-          nextCursorFromJoin = joinResults[joinResults.length - 1][joinModelOrderByField];
-        }
-        if (joinResults.length > 0 && !beforeCursor) {
-          if (joinResults.length === limit) {
-            prevCursorFromJoin = joinResults[0][joinModelOrderByField];
-          }
-        }
-      }
+    const relatedIds = joinResult.data.map((r) => r[joinModelRelatedField]).filter((id) => id != null && typeof id === "string");
+    let targetData = [];
+    if (relatedIds.length > 0) {
+      const targetResult = await targetModelClass.query({
+        id: { $in: relatedIds }
+      });
+      targetData = targetResult.data;
     }
-    const relatedIds = joinResults.map((r) => r[joinModelRelatedField]).filter((id) => id != null && typeof id === "string");
-    if (relatedIds.length === 0)
-      return { data: [], nextCursor: null, prevCursor: null };
-    const targetResult = await targetModelClass.query({
-      id: { $in: relatedIds }
-    });
     return {
-      data: targetResult.data,
-      nextCursor: nextCursorFromJoin,
-      prevCursor: prevCursorFromJoin
+      data: targetData,
+      nextCursor: joinResult.nextCursor,
+      prevCursor: joinResult.prevCursor,
+      hasMore: joinResult.hasMore
     };
   };
 }
@@ -1618,10 +1721,12 @@ function generateHasManyThroughRemoveMethod(_sourceModelClass, config, _targetMo
     }, `remove-join-${config.joinModel}-${this.id}-${targetId}`);
   };
 }
+var ALWAYS_PRESENT_ORDER_FIELDS;
 var init_relationshipManager = __esm({
   "src/models/relationshipManager.ts"() {
     "use strict";
     init_BaseModel();
+    ALWAYS_PRESENT_ORDER_FIELDS = /* @__PURE__ */ new Set(["id", "type"]);
   }
 });
 
@@ -2392,7 +2497,13 @@ var init_IncludeResolver = __esm({
         }
         return null;
       }
-      /** Apply projection to a single record. */
+      /**
+       * Apply a projection to a single record. Assumes the projection was already
+       * validated upstream (mixed inclusion+exclusion rejected by the translator):
+       * `isInclusion` treats "any value === 1" as inclusion mode. `id` and `type`
+       * are system-identity fields and are always kept in BOTH modes (mirrors the
+       * DatabaseDO `_applyProjection`); `_meta` stays excludable.
+       */
       _applyProjection(record, projection) {
         const fields = Object.entries(projection);
         if (fields.length === 0) return record;
@@ -2411,7 +2522,7 @@ var init_IncludeResolver = __esm({
         } else {
           const result = { ...record };
           for (const [f, v] of fields) {
-            if (v === 0) delete result[f];
+            if (v === 0 && f !== "id" && f !== "type") delete result[f];
           }
           return result;
         }
@@ -2431,20 +2542,23 @@ __export(BaseModel_exports, {
   generateULID: () => generateULID
 });
 function generateULID() {
-  return (0, import_ulid.ulid)();
+  return (0, import_ulid2.ulid)();
 }
-var Y2, import_ulid, LogLevel, Logger, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
+var Y5, import_ulid2, LogLevel, Logger, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
-    import_ulid = require("ulid");
+    Y5 = __toESM(require("yjs"), 1);
+    import_ulid2 = require("ulid");
     init_StringSet();
     init_documentTypes();
     init_DocumentQueryTranslator();
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_writeLifecycle();
+    init_yjsValues();
+    init_uniqueIndex();
     LogLevel = /* @__PURE__ */ ((LogLevel2) => {
       LogLevel2[LogLevel2["SILENT"] = 0] = "SILENT";
       LogLevel2[LogLevel2["ERROR"] = 1] = "ERROR";
@@ -2829,7 +2943,9 @@ var init_BaseModel = __esm({
               this.setValue(fieldKey, data[fieldKey]);
               this._constructorProvidedFields.add(fieldKey);
             } else if (fieldOptions.default !== void 0) {
-              const defaultValue = typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
+              const defaultValue = resolveLiteralOrFunctionDefault(
+                fieldOptions.default
+              );
               this.setValue(fieldKey, defaultValue);
             }
           }
@@ -2953,7 +3069,30 @@ var init_BaseModel = __esm({
         if (verboseEnabled) {
           Logger.verbose(`[getFromYjs] Returning field value: ${fieldValue}`);
         }
-        return fieldValue;
+        return this.normalizeNonStringSetValue(fieldKey, fieldValue, schema, modelName);
+      }
+      /**
+       * Defensive normalization for the read/sync boundary (issue #625).
+       *
+       * Stringset fields are owned by getStringSetFromYjs (which expects the
+       * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+       * through untouched. For any other field, a composite Yjs primitive
+       * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+       * raw: normalize it to its plain-JS projection (toJSON / toString) and
+       * warn, rather than throwing. Scalars pass through unchanged.
+       */
+      normalizeNonStringSetValue(fieldKey, value, schema, modelName) {
+        const fieldOptions = schema?.fields?.get(fieldKey);
+        if (fieldOptions?.type === "stringset") {
+          return value;
+        }
+        if (isYjsComposite(value)) {
+          Logger.warn(
+            `[${modelName ?? this.constructor.name}] Field '${fieldKey}' holds a composite Yjs value (${value?.constructor?.name}) but its declared type is '${fieldOptions?.type ?? "unknown"}'. Normalizing to plain JS \u2014 the writer disagreed with the schema.`
+          );
+          return normalizeYjsValue(value);
+        }
+        return value;
       }
       getValue(fieldKey) {
         const verboseEnabled = Logger.getLogLevel() >= 5 /* VERBOSE */;
@@ -3098,7 +3237,7 @@ var init_BaseModel = __esm({
       }
       getStringSetFromYjs(fieldName) {
         const yjsData = this.getFromYjs(fieldName);
-        if (yjsData instanceof Y2.Map) {
+        if (yjsData instanceof Y5.Map) {
           return Array.from(yjsData.keys());
         }
         if (yjsData && typeof yjsData === "object") {
@@ -3206,7 +3345,7 @@ var init_BaseModel = __esm({
         }
         const extractStringSetValues = (value) => {
           if (!value) return [];
-          if (value instanceof Y2.Map) {
+          if (value instanceof Y5.Map) {
             return Array.from(value.entries()).filter(([, isMember]) => Boolean(isMember)).map(([key]) => key);
           }
           if (Array.isArray(value)) {
@@ -3223,7 +3362,7 @@ var init_BaseModel = __esm({
             if (!recordId) continue;
             let itemData;
             const stringSetValuesByField = {};
-            if (recordData instanceof Y2.Map) {
+            if (recordData instanceof Y5.Map) {
               itemData = {};
               const unknownFields = [];
               for (const [fieldKey, value] of recordData.entries()) {
@@ -3339,20 +3478,10 @@ var init_BaseModel = __esm({
         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 Y2.Map ? recordData.get(field) : recordData[field];
-            if (value === null || value === void 0) {
-              return null;
-            }
-            keyParts.push(String(value));
-          }
-          return keyParts.join("|");
-        };
+        const buildUniqueKey2 = (recordData, fields) => buildUniqueKey(recordData, fields);
         const extractItemData = (key, recordData) => {
           let itemData;
-          if (recordData instanceof Y2.Map) {
+          if (recordData instanceof Y5.Map) {
             itemData = {};
             const unknownFields = [];
             for (const [fieldKey, value] of recordData.entries()) {
@@ -3365,7 +3494,14 @@ var init_BaseModel = __esm({
                 continue;
               }
               if (value !== void 0) {
-                itemData[fieldKey] = value;
+                if (isYjsComposite(value)) {
+                  Logger.warn(
+                    `[${this.name}] Field '${fieldKey}' on record ${key} holds a composite Yjs value (${value?.constructor?.name}) but its declared type is '${fieldOptions.type}'. Normalizing to plain JS before persisting to SQLite.`
+                  );
+                  itemData[fieldKey] = normalizeYjsValueForStorage(value);
+                } else {
+                  itemData[fieldKey] = value;
+                }
               }
             }
             if (unknownFields.length > 0) {
@@ -3388,7 +3524,14 @@ var init_BaseModel = __esm({
                 continue;
               }
               if (value !== void 0) {
-                filteredData[fieldKey] = value;
+                if (isYjsComposite(value)) {
+                  Logger.warn(
+                    `[${this.name}] Field '${fieldKey}' on legacy record ${key} holds a composite Yjs value (${value?.constructor?.name}) but its declared type is '${fieldOptions.type}'. Normalizing to plain JS before persisting to SQLite.`
+                  );
+                  filteredData[fieldKey] = normalizeYjsValueForStorage(value);
+                } else {
+                  filteredData[fieldKey] = value;
+                }
               }
             }
             if (unknownFields.length > 0) {
@@ -3422,7 +3565,7 @@ var init_BaseModel = __esm({
             const recordsByUniqueKey = /* @__PURE__ */ new Map();
             for (const [recordId, recordData] of allRecords.entries()) {
               if (recordIdsToDiscard.has(recordId)) continue;
-              const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+              const uniqueKey = buildUniqueKey2(recordData, constraint.fields);
               if (uniqueKey === null) continue;
               if (!recordsByUniqueKey.has(uniqueKey)) {
                 recordsByUniqueKey.set(uniqueKey, []);
@@ -3468,7 +3611,7 @@ var init_BaseModel = __esm({
               if (!recordData || !key) continue;
               const itemData = extractItemData(key, recordData);
               if (!itemData) continue;
-              if (change.action === "add" && recordData instanceof Y2.Map) {
+              if (change.action === "add" && recordData instanceof Y5.Map) {
                 Logger.verbose(
                   `[${this.name}] Setting up observer on newly added nested YMap for record ${key} in document ${docId}`
                 );
@@ -3566,9 +3709,12 @@ var init_BaseModel = __esm({
                   const recordData = documentYMap.get(idToDiscard);
                   if (!recordData) continue;
                   for (const constraint of schema.resolvedUniqueConstraints) {
-                    const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+                    const uniqueKey = buildUniqueKey2(recordData, constraint.fields);
                     if (uniqueKey === null) continue;
-                    const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+                    const constraintMapName = uniqueIndexMapName(
+                      modelName,
+                      constraint.name
+                    );
                     const constraintMap = yDoc.getMap(constraintMapName);
                     const currentIndexValue = constraintMap.get(uniqueKey);
                     if (currentIndexValue === idToDiscard) {
@@ -3586,11 +3732,14 @@ var init_BaseModel = __esm({
               }, `conflict-resolution-${modelName}-${docId}`);
               yDoc.transact(() => {
                 for (const constraint of schema.resolvedUniqueConstraints) {
-                  const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+                  const constraintMapName = uniqueIndexMapName(
+                    modelName,
+                    constraint.name
+                  );
                   const constraintMap = yDoc.getMap(constraintMapName);
                   for (const [recordId, recordData] of documentYMap.entries()) {
                     if (!recordData) continue;
-                    const uniqueKey = buildUniqueKey(recordData, constraint.fields);
+                    const uniqueKey = buildUniqueKey2(recordData, constraint.fields);
                     if (uniqueKey === null) continue;
                     const currentIndexValue = constraintMap.get(uniqueKey);
                     if (currentIndexValue !== recordId) {
@@ -3613,7 +3762,7 @@ var init_BaseModel = __esm({
           `[${this.name}] Setting up observers on existing nested YMaps for ${modelName}/${docId}...`
         );
         for (const [recordId, recordData] of documentYMap.entries()) {
-          if (recordData instanceof Y2.Map) {
+          if (recordData instanceof Y5.Map) {
             Logger.verbose(
               `[${this.name}] Setting up observer on existing nested YMap for record ${recordId} in document ${docId}`
             );
@@ -3798,6 +3947,11 @@ var init_BaseModel = __esm({
               Logger.debug(
                 `[_diffWithYjsData] Field '${key}' - Y.js value: ${yjsValue}, local value: ${localValue}`
               );
+              if (isYjsComposite(yjsValue)) {
+                Logger.warn(
+                  `[${modelConstructor.name}] Field '${key}' holds a composite Yjs value (${yjsValue?.constructor?.name}) in a non-stringset slot; the local scalar change will overwrite it (last-writer-wins).`
+                );
+              }
               if (yjsValue === void 0) {
                 Logger.debug(
                   `[_diffWithYjsData] Field '${key}' not in Y.js, adding to 'added'`
@@ -3834,26 +3988,7 @@ var init_BaseModel = __esm({
        * if the field hasn't been touched since the wire-format change in #561.
        */
       applyStringSetChangeToYMap(recordYMap, fieldName, change) {
-        let nested = recordYMap.get(fieldName);
-        if (!(nested instanceof Y2.Map)) {
-          const migrated = new Y2.Map();
-          if (nested && typeof nested === "object") {
-            for (const [member, marker] of Object.entries(
-              nested
-            )) {
-              if (Boolean(marker)) migrated.set(member, true);
-            }
-          }
-          recordYMap.set(fieldName, migrated);
-          nested = migrated;
-        }
-        const target = nested;
-        for (const member of change.additions) {
-          target.set(member, true);
-        }
-        for (const member of change.removals) {
-          target.delete(member);
-        }
+        applyStringSetChange(recordYMap, fieldName, change);
       }
       /**
        * Deep equality check for comparing field values
@@ -4023,6 +4158,29 @@ var init_BaseModel = __esm({
           );
           throw new Error("Cannot save item without an id. Ensure id is set.");
         }
+        const preTransactCreateStamps = /* @__PURE__ */ new Set();
+        {
+          const existingRecord = targetYMap.get(this.id);
+          const isNew = !existingRecord;
+          for (const [fieldKey, fieldOptions] of schema.fields.entries()) {
+            const stamp = fieldOptions.autoStamp;
+            if (!stamp) continue;
+            const callerExplicit = this.hasLocalChange(fieldKey);
+            if (callerExplicit) {
+              const localValue = this._localChanges[fieldKey];
+              if (localValue !== null && localValue !== void 0) continue;
+            }
+            if (stamp === "create") {
+              if (!isNew) continue;
+              const persisted = fieldKey === "id" ? this.id : this.getValue(fieldKey);
+              if (persisted !== null && persisted !== void 0) continue;
+            }
+            this[fieldKey] = Date.now();
+            if (stamp === "create") {
+              preTransactCreateStamps.add(fieldKey);
+            }
+          }
+        }
         this.validateBeforeSave();
         Logger.debug(`[${modelName}.save] About to get current JS state`);
         Logger.debug(`[${modelName}.save] _localChanges:`, this._localChanges);
@@ -4032,6 +4190,34 @@ var init_BaseModel = __esm({
           `[${modelName}.save] getCurrentJSState() returned:`,
           dataToSave
         );
+        const uniqueMissConflicts = /* @__PURE__ */ new Map();
+        for (const constraint of schema.resolvedUniqueConstraints) {
+          const newUniqueKey = this._buildUniqueKey(
+            constraint.fields,
+            dataToSave,
+            modelName,
+            constraint.name
+          );
+          if (newUniqueKey === null) {
+            continue;
+          }
+          const constraintMap = yDoc.getMap(
+            uniqueIndexMapName(modelName, constraint.name)
+          );
+          if (!constraintMap.get(newUniqueKey)) {
+            const constraintKeyValues = constraint.fields.map(
+              (field) => dataToSave[field]
+            );
+            const conflictingRecord = await modelConstructor._resolveByUniqueFallback(
+              constraint,
+              constraintKeyValues,
+              { excludeId: this.id }
+            );
+            if (conflictingRecord) {
+              uniqueMissConflicts.set(constraint.name, conflictingRecord.id);
+            }
+          }
+        }
         await yDoc.transact(async () => {
           if (upsertOnConstraint && upsertOnKey) {
             const constraintMapName = `_uniqueIdx_${modelName}_${upsertOnConstraint.name}`;
@@ -4053,6 +4239,14 @@ var init_BaseModel = __esm({
                   }
                 }
               }
+              for (const fieldKey of preTransactCreateStamps) {
+                if (this._localChanges && fieldKey in this._localChanges) {
+                  delete this._localChanges[fieldKey];
+                }
+                if (fieldKey in dataToSave) {
+                  delete dataToSave[fieldKey];
+                }
+              }
             }
           }
           if (!targetYMap) {
@@ -4065,7 +4259,7 @@ var init_BaseModel = __esm({
           Logger.debug(`[${modelName}.save] isUpdate: ${isUpdate}`);
           Logger.debug(`[${modelName}.save] recordYMap exists: ${!!recordYMap}`);
           if (!recordYMap) {
-            recordYMap = new Y2.Map();
+            recordYMap = new Y5.Map();
             Logger.verbose(
               `[${modelName}] Creating new nested YMap for record ${this.id} in document ${targetDocId || "legacy"}`
             );
@@ -4117,7 +4311,10 @@ var init_BaseModel = __esm({
               );
               continue;
             }
-            const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
+            const constraintMapName = uniqueIndexMapName(
+              modelName,
+              constraint.name
+            );
             const constraintMap = yDoc.getMap(constraintMapName);
             Logger.verbose(
               `[${modelName}] Save Check (Item '${this.id}'): GET from '${constraintMapName}' with Key '${newUniqueKey.substring(
@@ -4146,6 +4343,26 @@ var init_BaseModel = __esm({
                 this.id,
                 existingRecordIdWithNewKey
               );
+            } else if (!existingRecordIdWithNewKey) {
+              const conflictingRecordId = uniqueMissConflicts.get(constraint.name);
+              if (conflictingRecordId && conflictingRecordId !== this.id) {
+                Logger.verbose(
+                  `[${modelName}] Save Check (Item '${this.id}'): index miss for '${constraint.name}', but engine fallback found conflicting index-less record ${conflictingRecordId}.`
+                );
+                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 index-less record ID ${conflictingRecordId}.`,
+                  modelName,
+                  constraint.name,
+                  constraint.fields,
+                  this.id,
+                  conflictingRecordId
+                );
+              }
             }
           }
           if (isUpdate && oldData) {
@@ -4489,34 +4706,46 @@ var init_BaseModel = __esm({
         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 requestedLimit = options?.limit;
+        const overFetch = typeof requestedLimit === "number" && requestedLimit > 0;
+        let translatorOptions = hasIncludes && options?.projection ? { ...options, projection: void 0 } : options;
+        if (overFetch) {
+          translatorOptions = {
+            ...translatorOptions || {},
+            limit: requestedLimit + 1
+          };
+        }
         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(
+        let results = await _BaseModel.dbInstance.query(
           translatedQuery.sql,
           translatedQuery.params
         );
         Logger.verbose(`[${modelName}] Query returned ${results.length} results`);
+        let hasMore = false;
+        if (overFetch && results.length > requestedLimit) {
+          hasMore = true;
+          results = results.slice(0, requestedLimit);
+        }
         if (options?.include && options.include.length > 0) {
           const { IncludeResolver: IncludeResolver2 } = await Promise.resolve().then(() => (init_IncludeResolver(), IncludeResolver_exports));
           const resolver = new IncludeResolver2(_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 direction = options?.direction || 1;
         const cursors = CursorManager.generateResultCursors(
           results,
           translatedQuery.sortFields,
-          options?.direction || 1,
+          direction,
           hasMore,
           isFirstPage
         );
+        if (direction === -1) {
+          results.reverse();
+        }
         let transformedData;
         if (options?.projection && Object.keys(options.projection).length > 0) {
           transformedData = results.map((row) => {
@@ -5092,7 +5321,7 @@ var init_BaseModel = __esm({
                 );
               }
               for (const [recordId, recordYMap] of documentYMap.entries()) {
-                if (recordYMap instanceof Y2.Map) {
+                if (recordYMap instanceof Y5.Map) {
                   const instance = new this({ id: recordId });
                   instance._metaDocId = docId;
                   const connectedDoc = modelConstructor.connectedDocuments.get(docId);
@@ -5117,6 +5346,50 @@ var init_BaseModel = __esm({
         }
         return allInstances;
       }
+      /**
+       * Resolve a record by its unique-constraint field values via an engine query.
+       * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+       * entry for a key.
+       *
+       * The index map is a cache over the SQLite projection, not the source of
+       * truth: every record is loaded into the projection on `initializeForDocument`
+       * regardless of index presence, but a record written by a client predating
+       * index maintenance (legacy data) is missing from the index. Such a record
+       * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+       * check. A query over the constraint fields finds it reliably.
+       *
+       * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+       * the document that holds it, via `queryOne`) or `null`. Callers decide
+       * whether to heal the missing index entry (write paths) and do their own
+       * logging — this method never mutates the index, so read paths stay
+       * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+       * constraint field means the record does not participate in the constraint,
+       * so no query runs.
+       */
+      static async _resolveByUniqueFallback(constraint, keyValues, options) {
+        if (!_BaseModel.dbInstance) {
+          return null;
+        }
+        const filter = {};
+        for (let i = 0; i < constraint.fields.length; i++) {
+          const value = keyValues[i];
+          if (value === null || value === void 0) {
+            return null;
+          }
+          filter[constraint.fields[i]] = value;
+        }
+        if (options?.excludeId) {
+          if ("id" in filter) {
+            if (filter.id === options.excludeId) {
+              return null;
+            }
+          } else {
+            filter.id = { $ne: options.excludeId };
+          }
+        }
+        const found = await this.queryOne(filter);
+        return found ?? null;
+      }
       static async findByUnique(constraintName, value) {
         const modelConstructor = this;
         const schema = modelConstructor.getSchema();
@@ -5155,7 +5428,10 @@ var init_BaseModel = __esm({
             const documentInfo = modelConstructor.connectedDocuments.get(docId);
             if (!documentInfo) continue;
             const yDoc = documentInfo.yDoc;
-            const constraintMapName2 = `_uniqueIdx_${currentModelName}_${constraint.name}`;
+            const constraintMapName2 = uniqueIndexMapName(
+              currentModelName,
+              constraint.name
+            );
             const constraintMap2 = yDoc.getMap(constraintMapName2);
             const recordId2 = constraintMap2.get(uniqueKeyString);
             if (recordId2) {
@@ -5163,7 +5439,7 @@ var init_BaseModel = __esm({
               const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
               if (documentYMap) {
                 const recordYMap2 = documentYMap.get(recordId2);
-                if (recordYMap2 && recordYMap2 instanceof Y2.Map) {
+                if (recordYMap2 && recordYMap2 instanceof Y5.Map) {
                   const instance = new modelConstructor({
                     id: recordId2
                   });
@@ -5177,6 +5453,16 @@ var init_BaseModel = __esm({
               }
             }
           }
+          const fallbackRecord = await modelConstructor._resolveByUniqueFallback(
+            constraint,
+            keyValues
+          );
+          if (fallbackRecord) {
+            Logger.verbose(
+              `[${currentModelName}.findByUnique] Index miss for '${constraintName}' resolved via engine fallback to record ${fallbackRecord.id} (legacy index-less record; index left unchanged on read path).`
+            );
+            return fallbackRecord;
+          }
           Logger.verbose(
             `[${currentModelName}.findByUnique] Record not found in any connected document`
           );
@@ -5190,17 +5476,30 @@ var init_BaseModel = __esm({
             `[${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 constraintMapName = uniqueIndexMapName(
+          currentModelName,
+          constraint.name
+        );
         const constraintMap = legacyDocInfo.yDoc.getMap(constraintMapName);
         const recordId = constraintMap.get(uniqueKeyString);
         if (!recordId) {
+          const fallbackRecord = await modelConstructor._resolveByUniqueFallback(
+            constraint,
+            keyValues
+          );
+          if (fallbackRecord) {
+            Logger.verbose(
+              `[${currentModelName}.findByUnique] Index miss for '${constraintName}' resolved via engine fallback to record ${fallbackRecord.id} (legacy index-less record; index left unchanged on read path).`
+            );
+            return fallbackRecord;
+          }
           return null;
         }
         const recordYMap = legacyDocumentMap.get(recordId);
         if (!recordYMap) {
           return null;
         }
-        if (recordYMap instanceof Y2.Map) {
+        if (recordYMap instanceof Y5.Map) {
           const instance = new modelConstructor({
             id: recordId
           });
@@ -5258,7 +5557,10 @@ var init_BaseModel = __esm({
             `[${currentModelName}] upsertByUnique for '${constraintName}': unique key cannot be built due to null/undefined values. Upsert cannot proceed reliably.`
           );
         }
-        const constraintMapName = `_uniqueIdx_${currentModelName}_${constraint.name}`;
+        const constraintMapName = uniqueIndexMapName(
+          currentModelName,
+          constraint.name
+        );
         let existingRecord = null;
         if (connectedDocuments && connectedDocuments.size > 0) {
           for (const docId of connectedDocuments.keys()) {
@@ -5276,6 +5578,33 @@ var init_BaseModel = __esm({
           }
         } else {
         }
+        if (!existingRecord) {
+          const fallbackRecord = await modelConstructor._resolveByUniqueFallback(
+            constraint,
+            keyValuesForLookup
+          );
+          if (fallbackRecord) {
+            existingRecord = fallbackRecord;
+            const healDocId = fallbackRecord._metaDocId;
+            const healDocInfo = healDocId ? connectedDocuments.get(healDocId) : void 0;
+            const canHeal = !!healDocInfo && healDocInfo.permissionHint !== "read";
+            if (healDocInfo && canHeal) {
+              healDocInfo.yDoc.transact(() => {
+                const healMap = healDocInfo.yDoc.getMap(constraintMapName);
+                if (healMap.get(uniqueKeyString) !== fallbackRecord.id) {
+                  healMap.set(uniqueKeyString, fallbackRecord.id);
+                }
+              }, `heal-unique-index-${currentModelName}-${healDocId}`);
+              Logger.verbose(
+                `[${currentModelName}] upsertByUnique: index miss for '${constraintName}' resolved via engine fallback to record ${fallbackRecord.id}; healed missing index entry (legacy index-less record).`
+              );
+            } else {
+              Logger.verbose(
+                `[${currentModelName}] upsertByUnique: index miss for '${constraintName}' resolved via engine fallback to record ${fallbackRecord.id}; skipped index heal (owning document is read-only or not connected).`
+              );
+            }
+          }
+        }
         if (options?.objectMustExist) {
           if (!existingRecord) {
             throw new RecordNotFoundError(
@@ -5432,7 +5761,7 @@ var init_BaseModel = __esm({
         for (const [fieldKey, fieldOptions] of schema.fields) {
           if (fieldOptions?.type !== "stringset") continue;
           const value = recordYMap.get(fieldKey);
-          if (value instanceof Y2.Map) {
+          if (value instanceof Y5.Map) {
             this.observeStringSetMapOnce(value);
           }
         }
@@ -5479,7 +5808,14 @@ var init_BaseModel = __esm({
               continue;
             }
             if (value !== void 0) {
-              updatedData[key] = value;
+              if (isYjsComposite(value)) {
+                Logger.warn(
+                  `[${modelName}] Field '${key}' on record ${recordId} holds a composite Yjs value (${value?.constructor?.name}) but its declared type is '${fieldOptions.type}'. Normalizing to plain JS before persisting to SQLite.`
+                );
+                updatedData[key] = normalizeYjsValueForStorage(value);
+              } else {
+                updatedData[key] = value;
+              }
             }
           }
           if (unknownFields.length > 0) {
@@ -5559,7 +5895,14 @@ var init_BaseModel = __esm({
               continue;
             }
             if (value !== void 0) {
-              updatedData[key] = value;
+              if (isYjsComposite(value)) {
+                Logger.warn(
+                  `[${modelName}] Field '${key}' on record ${recordId} in document ${docId} holds a composite Yjs value (${value?.constructor?.name}) but its declared type is '${fieldOptions.type}'. Normalizing to plain JS before persisting to SQLite.`
+                );
+                updatedData[key] = normalizeYjsValueForStorage(value);
+              } else {
+                updatedData[key] = value;
+              }
             }
           }
           if (unknownFields.length > 0) {
@@ -5685,7 +6028,144 @@ var import_sql4 = __toESM(require("sql.js"), 1);
 init_BaseModel();
 var import_async_mutex = require("async-mutex");
 init_sql();
+
+// src/utils/environment.ts
+function detectEnvironment() {
+  if (typeof process !== "undefined" && process.versions && process.versions.node) {
+    return "node";
+  }
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  if (typeof self !== "undefined" && typeof self.importScripts === "function") {
+    return "browser";
+  }
+  return "unknown";
+}
+function isNode() {
+  return detectEnvironment() === "node";
+}
+function isBrowser() {
+  return detectEnvironment() === "browser";
+}
+async function isNodeModuleAvailable(moduleName) {
+  if (!isNode()) {
+    return false;
+  }
+  try {
+    await import(
+      /* @vite-ignore */
+      moduleName
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+var features = {
+  get hasWebWorkers() {
+    return isBrowser() && typeof Worker !== "undefined";
+  },
+  get hasFileSystem() {
+    return isNode();
+  },
+  get hasWebAssembly() {
+    return typeof WebAssembly !== "undefined";
+  },
+  async hasBetterSqlite3() {
+    return await isNodeModuleAvailable("better-sqlite3");
+  }
+};
+
+// src/engines/SqljsEngine.ts
+var import_meta = {};
 var SQL_WASM_URL = "/sql-wasm.wasm";
+var SQL_WASM_FILENAME = "sql-wasm.wasm";
+async function resolveNodeWasmPath() {
+  if (!isNode()) {
+    return null;
+  }
+  try {
+    const cjsRequire = typeof require !== "undefined" ? require : void 0;
+    if (cjsRequire) {
+      return cjsRequire.resolve("sql.js/dist/sql-wasm.wasm");
+    }
+  } catch {
+  }
+  try {
+    const metaUrl = import_meta.url;
+    if (metaUrl) {
+      const { createRequire } = await import(
+        /* @vite-ignore */
+        "module"
+      );
+      const req = createRequire(metaUrl);
+      return req.resolve("sql.js/dist/sql-wasm.wasm");
+    }
+  } catch {
+  }
+  return null;
+}
+async function preflightNodeWasm(wasmPath) {
+  if (!isNode()) {
+    return;
+  }
+  if (/^[a-z]+:\/\//i.test(wasmPath)) {
+    return;
+  }
+  const { existsSync } = await import(
+    /* @vite-ignore */
+    "fs"
+  );
+  if (!existsSync(wasmPath)) {
+    throw new Error(
+      `[SqljsEngine] sql.js wasm not found at "${wasmPath}". Pass \`locateFile\`/\`wasmURL\` pointing at sql-wasm.wasm, or install \`better-sqlite3\` and use the \`node-sqlite\` engine (see getRecommendedNodeEngine()).`
+    );
+  }
+}
+async function loadSqlJsModule(locateFile) {
+  let abortReject;
+  const toError = (reason) => reason instanceof Error ? reason : new Error(
+    `[SqljsEngine] sql.js aborted during initialization: ${String(
+      reason
+    )}`
+  );
+  const nodeProcess = isNode() && typeof process !== "undefined" ? process : void 0;
+  const onUnhandled = (reason) => {
+    const err = toError(reason);
+    if (/Aborted/.test(err.message) || /Aborted/.test(String(reason))) {
+      abortReject?.(err);
+      return;
+    }
+    if (nodeProcess && nodeProcess.listenerCount("unhandledRejection") === 1) {
+      nodeProcess.removeListener("unhandledRejection", onUnhandled);
+      void Promise.reject(reason);
+    }
+  };
+  if (nodeProcess) {
+    nodeProcess.on("unhandledRejection", onUnhandled);
+  }
+  const abortGuard = new Promise((_resolve, reject) => {
+    abortReject = reject;
+  });
+  abortGuard.catch(() => {
+  });
+  try {
+    const initPromise = (0, import_sql4.default)({
+      locateFile,
+      // Layer 1: emscripten onAbort.
+      onAbort: (reason) => abortReject?.(toError(reason))
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    return await Promise.race([initPromise, abortGuard]);
+  } finally {
+    if (nodeProcess) {
+      setTimeout(() => {
+        nodeProcess.removeListener("unhandledRejection", onUnhandled);
+      }, 0);
+    }
+  }
+}
 var TransactionalSQLJSOperations = class {
   db;
   engine;
@@ -5751,22 +6231,37 @@ var SqljsEngine = class _SqljsEngine {
   }
   async initialize(engineOptions) {
     Logger.info("[SqljsEngine] Initializing SQL.js engine...");
+    const loadingModuleThisCall = !_SqljsEngine.SQL;
     try {
       if (!_SqljsEngine.SQL) {
-        const locateFileConfig = engineOptions?.locateFile || ((_file) => engineOptions?.wasmURL || SQL_WASM_URL);
+        let locateFileConfig;
+        if (engineOptions?.locateFile) {
+          locateFileConfig = engineOptions.locateFile;
+        } else if (engineOptions?.wasmURL) {
+          const url = engineOptions.wasmURL;
+          locateFileConfig = (_file) => url;
+        } else {
+          const nodeWasmPath = await resolveNodeWasmPath();
+          const resolved = nodeWasmPath ?? SQL_WASM_URL;
+          locateFileConfig = (_file) => resolved;
+        }
+        const wasmPath = locateFileConfig(SQL_WASM_FILENAME);
         Logger.debug(
           "[SqljsEngine] Attempting to load SQL.js WASM from:",
-          locateFileConfig("sql-wasm.wasm")
+          wasmPath
         );
-        _SqljsEngine.SQL = await (0, import_sql4.default)({
-          locateFile: locateFileConfig
-        });
+        await preflightNodeWasm(wasmPath);
+        const SQL = await loadSqlJsModule(locateFileConfig);
+        _SqljsEngine.SQL = SQL;
         Logger.info("[SqljsEngine] SQL.js WASM loaded successfully.");
       }
       this.db = new _SqljsEngine.SQL.Database();
       Logger.info("[SqljsEngine] SQL.js Database initialized in memory.");
       this.updateTableNames();
     } catch (error) {
+      if (loadingModuleThisCall) {
+        _SqljsEngine.SQL = null;
+      }
       Logger.error("[SqljsEngine] Error during SQL.js initialization:", error);
       throw error;
     }
@@ -6052,54 +6547,6 @@ var SqljsEngine = class _SqljsEngine {
   }
 };
 
-// src/utils/environment.ts
-function detectEnvironment() {
-  if (typeof process !== "undefined" && process.versions && process.versions.node) {
-    return "node";
-  }
-  if (typeof window !== "undefined" && typeof document !== "undefined") {
-    return "browser";
-  }
-  if (typeof self !== "undefined" && typeof self.importScripts === "function") {
-    return "browser";
-  }
-  return "unknown";
-}
-function isNode() {
-  return detectEnvironment() === "node";
-}
-function isBrowser() {
-  return detectEnvironment() === "browser";
-}
-async function isNodeModuleAvailable(moduleName) {
-  if (!isNode()) {
-    return false;
-  }
-  try {
-    await import(
-      /* @vite-ignore */
-      moduleName
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-var features = {
-  get hasWebWorkers() {
-    return isBrowser() && typeof Worker !== "undefined";
-  },
-  get hasFileSystem() {
-    return isNode();
-  },
-  get hasWebAssembly() {
-    return typeof WebAssembly !== "undefined";
-  },
-  async hasBetterSqlite3() {
-    return await isNodeModuleAvailable("better-sqlite3");
-  }
-};
-
 // src/engines/BrowserDatabaseFactory.ts
 init_BaseModel();
 var BrowserDatabaseFactory = class {
@@ -6410,6 +6857,7 @@ init_StringSet();
 // src/models/schema.ts
 init_BaseModel();
 init_ModelRegistry();
+init_uniqueIndex();
 function defineModelSchema(input) {
   const { name, fields } = input;
   const options = {
@@ -6482,7 +6930,7 @@ function resolveUniqueConstraints(modelName, fields, customConstraints) {
   for (const [fieldName, options] of fields.entries()) {
     if (options.unique) {
       resolved.push({
-        name: `${modelName}_${fieldName}_unique`,
+        name: fieldUniqueConstraintName(modelName, fieldName),
         fields: [fieldName]
       });
     }
@@ -6546,7 +6994,8 @@ function attachAndRegisterModel(modelClass, schema) {
 }
 
 // src/utils/yDocSchema.ts
-var Y3 = __toESM(require("yjs"), 1);
+var Y6 = __toESM(require("yjs"), 1);
+init_yjsValues();
 function discoverSchema(yDoc) {
   const models = {};
   const metaNames = /* @__PURE__ */ new Set();
@@ -6580,7 +7029,7 @@ function discoverModelNames(yDoc) {
 function materializeMap(yDoc, key) {
   try {
     const map = yDoc.getMap(key);
-    return map instanceof Y3.Map ? map : null;
+    return map instanceof Y6.Map ? map : null;
   } catch {
     return null;
   }
@@ -6590,11 +7039,11 @@ function readModelMeta(metaMap) {
   let constraints;
   let relationships;
   for (const [key, value] of metaMap.entries()) {
-    if (key === "_constraints" && value instanceof Y3.Map) {
+    if (key === "_constraints" && value instanceof Y6.Map) {
       constraints = readConstraints(value);
-    } else if (key === "_relationships" && value instanceof Y3.Map) {
+    } else if (key === "_relationships" && value instanceof Y6.Map) {
       relationships = readRelationships(value);
-    } else if (value instanceof Y3.Map) {
+    } else if (value instanceof Y6.Map) {
       fields[key] = readFieldMeta(value);
     }
   }
@@ -6613,6 +7062,10 @@ function readFieldMeta(fieldMap) {
   if (fieldMap.get("unique") === true) field.unique = true;
   if (fieldMap.get("required") === true) field.required = true;
   if (fieldMap.get("autoAssign") === true) field.autoAssign = true;
+  const autoStamp = fieldMap.get("autoStamp");
+  if (typeof autoStamp === "string" && (autoStamp === "create" || autoStamp === "update" || autoStamp === "both")) {
+    field.autoStamp = autoStamp;
+  }
   const def = fieldMap.get("default");
   if (def !== void 0) field.default = def;
   const maxLength = fieldMap.get("maxLength");
@@ -6625,7 +7078,7 @@ function inferModelFromData(dataMap) {
   const fields = {};
   let sampled = 0;
   for (const [_recordId, recordValue] of dataMap.entries()) {
-    if (!(recordValue instanceof Y3.Map)) continue;
+    if (!(recordValue instanceof Y6.Map)) continue;
     if (++sampled > 5) break;
     for (const [fieldName, value] of recordValue.entries()) {
       if (fieldName.startsWith("_")) continue;
@@ -6638,7 +7091,7 @@ function inferModelFromData(dataMap) {
   return { fields };
 }
 function inferTypeFromValue(value) {
-  if (value instanceof Y3.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -6653,7 +7106,7 @@ function inferTypeFromValue(value) {
 function readConstraints(constraintsMap) {
   const out = {};
   for (const [name, value] of constraintsMap.entries()) {
-    if (!(value instanceof Y3.Map)) continue;
+    if (!(value instanceof Y6.Map)) continue;
     let fields = [];
     const rawFields = value.get("fields");
     if (typeof rawFields === "string") {
@@ -6672,7 +7125,7 @@ function readConstraints(constraintsMap) {
 function readRelationships(relsMap) {
   const out = {};
   for (const [name, value] of relsMap.entries()) {
-    if (!(value instanceof Y3.Map)) continue;
+    if (!(value instanceof Y6.Map)) continue;
     const rel = {};
     for (const [k, v] of value.entries()) {
       rel[k] = v;
@@ -6683,6 +7136,7 @@ function readRelationships(relsMap) {
 }
 var CAMEL_TO_SNAKE = {
   autoAssign: "auto_assign",
+  autoStamp: "auto_stamp",
   maxLength: "max_length",
   maxCount: "max_count",
   relatedIdField: "related_id_field",
@@ -6713,6 +7167,7 @@ function schemaToToml(schema) {
       lines.push(`[models.${modelName}.fields.${fieldName}]`);
       lines.push(`type = ${tomlValue(field.type)}`);
       if (field.autoAssign) lines.push("auto_assign = true");
+      if (field.autoStamp) lines.push(`auto_stamp = ${tomlValue(field.autoStamp)}`);
       if (field.indexed) lines.push("indexed = true");
       if (field.unique) lines.push("unique = true");
       if (field.required) lines.push("required = true");
@@ -6759,10 +7214,13 @@ var KNOWN_FIELD_KEYS = /* @__PURE__ */ new Set([
   "unique",
   "required",
   "auto_assign",
+  "auto_stamp",
   "max_length",
   "max_count",
-  "default"
+  "default",
+  "enum"
 ]);
+var VALID_AUTO_STAMP_VALUES = /* @__PURE__ */ new Set(["create", "update", "both"]);
 var KNOWN_MODEL_KEYS = /* @__PURE__ */ new Set([
   "fields",
   "relationships",
@@ -6804,9 +7262,37 @@ function parseFieldOptions(raw, context, strict) {
   if (raw.unique === true) opts.unique = true;
   if (raw.required === true) opts.required = true;
   if (raw.auto_assign === true) opts.autoAssign = true;
+  if (raw.auto_stamp !== void 0) {
+    if (typeof raw.auto_stamp !== "string" || !VALID_AUTO_STAMP_VALUES.has(raw.auto_stamp)) {
+      throw new Error(
+        `${context}: invalid auto_stamp value "${raw.auto_stamp}". Must be one of: ${[
+          ...VALID_AUTO_STAMP_VALUES
+        ].join(", ")}`
+      );
+    }
+    opts.autoStamp = raw.auto_stamp;
+  }
   if (raw.max_length !== void 0) opts.maxLength = raw.max_length;
   if (raw.max_count !== void 0) opts.maxCount = raw.max_count;
   if (raw.default !== void 0) opts.default = raw.default;
+  if (raw.enum !== void 0) {
+    if (raw.type !== "string") {
+      throw new Error(
+        `${context}: \`enum\` is only valid on a "string" field, not "${raw.type}".`
+      );
+    }
+    if (!Array.isArray(raw.enum) || raw.enum.length === 0) {
+      throw new Error(
+        `${context}: \`enum\` must be a non-empty array of strings.`
+      );
+    }
+    if (!raw.enum.every((v) => typeof v === "string")) {
+      throw new Error(
+        `${context}: \`enum\` values must all be strings.`
+      );
+    }
+    opts.enum = [...raw.enum];
+  }
   return opts;
 }
 function requireField(raw, field, context) {