js-bao 0.4.2 → 0.5.1

package/dist/browser.cjs

@@ -1183,9 +1183,46 @@ 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/metaSync.ts
 function inferFieldType(value) {
-  if (value instanceof Y.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -1230,7 +1267,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (compoundConstraints.length > 0) {
     let constraints = meta.get("_constraints");
     if (!constraints) {
-      constraints = new Y.Map();
+      constraints = new Y2.Map();
       meta.set("_constraints", constraints);
     }
     for (const constraint of compoundConstraints) {
@@ -1241,7 +1278,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 Y2.Map();
       meta.set("_relationships", rels);
     }
     for (const [relName, relConfig] of Object.entries(relationships)) {
@@ -1253,7 +1290,7 @@ function syncModelMeta(yDoc, modelName, schema) {
 function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   let fieldMeta = metaMap.get(fieldName);
   if (!fieldMeta) {
-    fieldMeta = new Y.Map();
+    fieldMeta = new Y2.Map();
     metaMap.set(fieldName, fieldMeta);
   }
   setIfChanged(fieldMeta, "type", fieldOpts.type);
@@ -1261,6 +1298,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 +1307,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
 function syncConstraintMeta(constraintsMap, constraint) {
   let cMeta = constraintsMap.get(constraint.name);
   if (!cMeta) {
-    cMeta = new Y.Map();
+    cMeta = new Y2.Map();
     constraintsMap.set(constraint.name, cMeta);
   }
   setIfChanged(cMeta, "type", "unique");
@@ -1279,7 +1317,7 @@ function syncConstraintMeta(constraintsMap, constraint) {
 function syncRelationshipMeta(relsMap, relName, relConfig) {
   let relMeta = relsMap.get(relName);
   if (!relMeta) {
-    relMeta = new Y.Map();
+    relMeta = new Y2.Map();
     relsMap.set(relName, relMeta);
   }
   for (const [key, value] of Object.entries(relConfig)) {
@@ -1294,7 +1332,7 @@ function syncInferredMeta(yDoc, modelName, recordData) {
     if (fieldName.startsWith("_")) continue;
     let fieldMeta = meta.get(fieldName);
     if (!fieldMeta) {
-      fieldMeta = new Y.Map();
+      fieldMeta = new Y2.Map();
       meta.set(fieldName, fieldMeta);
     }
     if (!fieldMeta.has("type")) {
@@ -1310,11 +1348,12 @@ function setIfChanged(map, key, value) {
     map.set(key, value);
   }
 }
-var Y, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
+var Y2, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y = __toESM(require("yjs"), 1);
+    Y2 = __toESM(require("yjs"), 1);
+    init_yjsValues();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
@@ -2433,11 +2472,11 @@ __export(BaseModel_exports, {
 function generateULID() {
   return (0, import_ulid.ulid)();
 }
-var Y2, import_ulid, LogLevel, Logger, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
+var Y3, import_ulid, LogLevel, Logger, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
     import_ulid = require("ulid");
     init_StringSet();
     init_documentTypes();
@@ -2445,6 +2484,7 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_yjsValues();
     LogLevel = /* @__PURE__ */ ((LogLevel2) => {
       LogLevel2[LogLevel2["SILENT"] = 0] = "SILENT";
       LogLevel2[LogLevel2["ERROR"] = 1] = "ERROR";
@@ -2953,7 +2993,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 */;
@@ -3034,7 +3097,7 @@ var init_BaseModel = __esm({
       validateBeforeSave() {
         const schema = this.constructor.getSchema();
         for (const [fieldKey, fieldOptions] of schema.fields.entries()) {
-          const currentValue = this.getValue(fieldKey);
+          const currentValue = fieldKey === "id" ? this.id : this.getValue(fieldKey);
           if (fieldOptions.required && (currentValue === null || currentValue === void 0)) {
             throw new Error(`Field ${fieldKey} is required before save`);
           }
@@ -3098,7 +3161,7 @@ var init_BaseModel = __esm({
       }
       getStringSetFromYjs(fieldName) {
         const yjsData = this.getFromYjs(fieldName);
-        if (yjsData instanceof Y2.Map) {
+        if (yjsData instanceof Y3.Map) {
           return Array.from(yjsData.keys());
         }
         if (yjsData && typeof yjsData === "object") {
@@ -3206,7 +3269,7 @@ var init_BaseModel = __esm({
         }
         const extractStringSetValues = (value) => {
           if (!value) return [];
-          if (value instanceof Y2.Map) {
+          if (value instanceof Y3.Map) {
             return Array.from(value.entries()).filter(([, isMember]) => Boolean(isMember)).map(([key]) => key);
           }
           if (Array.isArray(value)) {
@@ -3223,7 +3286,7 @@ var init_BaseModel = __esm({
             if (!recordId) continue;
             let itemData;
             const stringSetValuesByField = {};
-            if (recordData instanceof Y2.Map) {
+            if (recordData instanceof Y3.Map) {
               itemData = {};
               const unknownFields = [];
               for (const [fieldKey, value] of recordData.entries()) {
@@ -3342,7 +3405,7 @@ var init_BaseModel = __esm({
         const buildUniqueKey = (recordData, fields) => {
           const keyParts = [];
           for (const field of fields) {
-            const value = recordData instanceof Y2.Map ? recordData.get(field) : recordData[field];
+            const value = recordData instanceof Y3.Map ? recordData.get(field) : recordData[field];
             if (value === null || value === void 0) {
               return null;
             }
@@ -3352,7 +3415,7 @@ var init_BaseModel = __esm({
         };
         const extractItemData = (key, recordData) => {
           let itemData;
-          if (recordData instanceof Y2.Map) {
+          if (recordData instanceof Y3.Map) {
             itemData = {};
             const unknownFields = [];
             for (const [fieldKey, value] of recordData.entries()) {
@@ -3365,7 +3428,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 +3458,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) {
@@ -3468,7 +3545,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 Y3.Map) {
                 Logger.verbose(
                   `[${this.name}] Setting up observer on newly added nested YMap for record ${key} in document ${docId}`
                 );
@@ -3613,7 +3690,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 Y3.Map) {
             Logger.verbose(
               `[${this.name}] Setting up observer on existing nested YMap for record ${recordId} in document ${docId}`
             );
@@ -3798,6 +3875,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'`
@@ -3835,8 +3917,8 @@ var init_BaseModel = __esm({
        */
       applyStringSetChangeToYMap(recordYMap, fieldName, change) {
         let nested = recordYMap.get(fieldName);
-        if (!(nested instanceof Y2.Map)) {
-          const migrated = new Y2.Map();
+        if (!(nested instanceof Y3.Map)) {
+          const migrated = new Y3.Map();
           if (nested && typeof nested === "object") {
             for (const [member, marker] of Object.entries(
               nested
@@ -4023,6 +4105,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);
@@ -4053,6 +4158,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 +4178,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 Y3.Map();
             Logger.verbose(
               `[${modelName}] Creating new nested YMap for record ${this.id} in document ${targetDocId || "legacy"}`
             );
@@ -5092,7 +5205,7 @@ var init_BaseModel = __esm({
                 );
               }
               for (const [recordId, recordYMap] of documentYMap.entries()) {
-                if (recordYMap instanceof Y2.Map) {
+                if (recordYMap instanceof Y3.Map) {
                   const instance = new this({ id: recordId });
                   instance._metaDocId = docId;
                   const connectedDoc = modelConstructor.connectedDocuments.get(docId);
@@ -5163,7 +5276,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 Y3.Map) {
                   const instance = new modelConstructor({
                     id: recordId2
                   });
@@ -5200,7 +5313,7 @@ var init_BaseModel = __esm({
         if (!recordYMap) {
           return null;
         }
-        if (recordYMap instanceof Y2.Map) {
+        if (recordYMap instanceof Y3.Map) {
           const instance = new modelConstructor({
             id: recordId
           });
@@ -5432,7 +5545,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 Y3.Map) {
             this.observeStringSetMapOnce(value);
           }
         }
@@ -5479,7 +5592,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 +5679,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) {
@@ -6546,7 +6673,8 @@ function attachAndRegisterModel(modelClass, schema) {
 }
 
 // src/utils/yDocSchema.ts
-var Y3 = __toESM(require("yjs"), 1);
+var Y4 = __toESM(require("yjs"), 1);
+init_yjsValues();
 function discoverSchema(yDoc) {
   const models = {};
   const metaNames = /* @__PURE__ */ new Set();
@@ -6580,7 +6708,7 @@ function discoverModelNames(yDoc) {
 function materializeMap(yDoc, key) {
   try {
     const map = yDoc.getMap(key);
-    return map instanceof Y3.Map ? map : null;
+    return map instanceof Y4.Map ? map : null;
   } catch {
     return null;
   }
@@ -6590,11 +6718,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 Y4.Map) {
       constraints = readConstraints(value);
-    } else if (key === "_relationships" && value instanceof Y3.Map) {
+    } else if (key === "_relationships" && value instanceof Y4.Map) {
       relationships = readRelationships(value);
-    } else if (value instanceof Y3.Map) {
+    } else if (value instanceof Y4.Map) {
       fields[key] = readFieldMeta(value);
     }
   }
@@ -6613,6 +6741,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 +6757,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 Y4.Map)) continue;
     if (++sampled > 5) break;
     for (const [fieldName, value] of recordValue.entries()) {
       if (fieldName.startsWith("_")) continue;
@@ -6638,7 +6770,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 +6785,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 Y4.Map)) continue;
     let fields = [];
     const rawFields = value.get("fields");
     if (typeof rawFields === "string") {
@@ -6672,7 +6804,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 Y4.Map)) continue;
     const rel = {};
     for (const [k, v] of value.entries()) {
       rel[k] = v;
@@ -6683,6 +6815,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 +6846,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 +6893,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 +6941,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) {

package/dist/browser.d.cts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -495,6 +519,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * 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.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -922,6 +957,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1010,6 +1046,11 @@ declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSche
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**