js-bao 0.5.0 → 0.5.1

package/dist/cloudflare-do.cjs

@@ -44,6 +44,21 @@ function assertValidIdentifier(name, context) {
 function quoteIdentifier(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
+function deterministicIdentifierHash(value) {
+  let hash = 0;
+  for (let i = 0; i < value.length; i++) {
+    hash = (hash << 5) - hash + value.charCodeAt(i);
+    hash |= 0;
+  }
+  const positiveHash = hash === 0 ? 0 : Math.abs(hash);
+  return positiveHash.toString(36);
+}
+function buildSafeAlias(prefix, rawDescriptor) {
+  const suffix = deterministicIdentifierHash(rawDescriptor);
+  const candidate = `${prefix}_${suffix}`;
+  assertValidIdentifier(candidate, "Alias generation");
+  return candidate;
+}
 var IDENTIFIER_PATTERN;
 var init_sql = __esm({
   "src/utils/sql.ts"() {
@@ -339,6 +354,22 @@ var init_patterns = __esm({
   }
 });
 
+// src/utils/yjsValues.ts
+function isStringSetYMap(value) {
+  if (!(value instanceof Y.Map)) return false;
+  for (const v of value.values()) {
+    if (v !== true) return false;
+  }
+  return true;
+}
+var Y;
+var init_yjsValues = __esm({
+  "src/utils/yjsValues.ts"() {
+    "use strict";
+    Y = __toESM(require("yjs"), 1);
+  }
+});
+
 // src/models/StringSet.ts
 var init_StringSet = __esm({
   "src/models/StringSet.ts"() {
@@ -366,7 +397,7 @@ var init_DocumentQueryTranslator = __esm({
 
 // src/models/metaSync.ts
 function inferFieldType(value) {
-  if (value instanceof Y2.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -411,7 +442,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (compoundConstraints.length > 0) {
     let constraints = meta.get("_constraints");
     if (!constraints) {
-      constraints = new Y2.Map();
+      constraints = new Y3.Map();
       meta.set("_constraints", constraints);
     }
     for (const constraint of compoundConstraints) {
@@ -422,7 +453,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (relationships && Object.keys(relationships).length > 0) {
     let rels = meta.get("_relationships");
     if (!rels) {
-      rels = new Y2.Map();
+      rels = new Y3.Map();
       meta.set("_relationships", rels);
     }
     for (const [relName, relConfig] of Object.entries(relationships)) {
@@ -434,7 +465,7 @@ function syncModelMeta(yDoc, modelName, schema) {
 function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   let fieldMeta = metaMap.get(fieldName);
   if (!fieldMeta) {
-    fieldMeta = new Y2.Map();
+    fieldMeta = new Y3.Map();
     metaMap.set(fieldName, fieldMeta);
   }
   setIfChanged(fieldMeta, "type", fieldOpts.type);
@@ -442,6 +473,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);
@@ -450,7 +482,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
 function syncConstraintMeta(constraintsMap, constraint) {
   let cMeta = constraintsMap.get(constraint.name);
   if (!cMeta) {
-    cMeta = new Y2.Map();
+    cMeta = new Y3.Map();
     constraintsMap.set(constraint.name, cMeta);
   }
   setIfChanged(cMeta, "type", "unique");
@@ -460,7 +492,7 @@ function syncConstraintMeta(constraintsMap, constraint) {
 function syncRelationshipMeta(relsMap, relName, relConfig) {
   let relMeta = relsMap.get(relName);
   if (!relMeta) {
-    relMeta = new Y2.Map();
+    relMeta = new Y3.Map();
     relsMap.set(relName, relMeta);
   }
   for (const [key, value] of Object.entries(relConfig)) {
@@ -475,7 +507,7 @@ function syncInferredMeta(yDoc, modelName, recordData) {
     if (fieldName.startsWith("_")) continue;
     let fieldMeta = meta.get(fieldName);
     if (!fieldMeta) {
-      fieldMeta = new Y2.Map();
+      fieldMeta = new Y3.Map();
       meta.set(fieldName, fieldMeta);
     }
     if (!fieldMeta.has("type")) {
@@ -491,11 +523,12 @@ function setIfChanged(map, key, value) {
     map.set(key, value);
   }
 }
-var Y2, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
+var Y3, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
+    init_yjsValues();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
@@ -505,11 +538,11 @@ var init_metaSync = __esm({
 function generateULID() {
   return (0, import_ulid2.ulid)();
 }
-var Y3, import_ulid2;
+var Y4, import_ulid2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y3 = __toESM(require("yjs"), 1);
+    Y4 = __toESM(require("yjs"), 1);
     import_ulid2 = require("ulid");
     init_StringSet();
     init_documentTypes();
@@ -517,6 +550,7 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_yjsValues();
     registerFunctionDefault(generateULID, "generate_ulid");
   }
 });
@@ -544,9 +578,13 @@ __export(cloudflare_do_exports, {
   DurableObjectEngine: () => DurableObjectEngine,
   JsonQueryTranslator: () => JsonQueryTranslator,
   JsonSchemaDDL: () => JsonSchemaDDL,
+  buildSafeAlias: () => buildSafeAlias,
+  checkAutoStampsReservedFields: () => checkAutoStampsReservedFields,
+  checkReservedFieldName: () => checkReservedFieldName,
   clearMetaSyncCache: () => clearMetaSyncCache,
   createDatabaseDO: () => createDatabaseDO,
   createDocumentDO: () => createDocumentDO,
+  deterministicIdentifierHash: () => deterministicIdentifierHash,
   discoverModelNames: () => discoverModelNames,
   discoverSchema: () => discoverSchema,
   handleRequest: () => handleRequest,
@@ -2249,6 +2287,50 @@ var JsonQueryTranslator = class {
 init_CursorManager();
 init_sql();
 var import_ulid = require("ulid");
+function checkReservedFieldName(fieldName) {
+  if (fieldName === "id") return null;
+  if (fieldName === "type") {
+    return `Field 'type' is reserved (maps to internal _type column in queries)`;
+  }
+  if (fieldName.startsWith("_")) {
+    return `Field '${fieldName}' is reserved (fields starting with '_' are internal)`;
+  }
+  return null;
+}
+function checkAutoStampsReservedFields(autoStamps) {
+  if (!autoStamps) return null;
+  for (const field of autoStamps.create || []) {
+    const err = checkReservedFieldName(field);
+    if (err) return `autoStamps.create: ${err}`;
+  }
+  for (const field of autoStamps.update || []) {
+    const err = checkReservedFieldName(field);
+    if (err) return `autoStamps.update: ${err}`;
+  }
+  return null;
+}
+function applyAutoStamps(data, autoStamps, isNew) {
+  if (!autoStamps || !data) return;
+  const reservedError = checkAutoStampsReservedFields(autoStamps);
+  if (reservedError) {
+    throw new Error(reservedError);
+  }
+  const now = Date.now();
+  if (isNew && autoStamps.create) {
+    for (const field of autoStamps.create) {
+      if (data[field] === void 0 || data[field] === null) {
+        data[field] = now;
+      }
+    }
+  }
+  if (autoStamps.update) {
+    for (const field of autoStamps.update) {
+      if (data[field] === void 0 || data[field] === null) {
+        data[field] = now;
+      }
+    }
+  }
+}
 function createDatabaseDO(config = {}) {
   const hooks = config.hooks;
   return class DocumentDO {
@@ -2429,7 +2511,15 @@ function createDatabaseDO(config = {}) {
     /** @internal */
     async _handleSave(request, docId) {
       const body = await request.json();
-      const { modelName, data, stringSets, ifNotExists, condition, upsertOn } = body;
+      const {
+        modelName,
+        data,
+        stringSets,
+        ifNotExists,
+        condition,
+        upsertOn,
+        autoStamps
+      } = body;
       let id = body.id;
       if (!modelName || !id && !upsertOn) {
         return this._errorResponse("modelName is required, and either id or upsertOn must be provided", 400);
@@ -2443,6 +2533,12 @@ function createDatabaseDO(config = {}) {
           return this._errorResponse(reservedError, 400);
         }
       }
+      {
+        const autoStampsReservedError = checkAutoStampsReservedFields(autoStamps);
+        if (autoStampsReservedError) {
+          return this._errorResponse(autoStampsReservedError, 400);
+        }
+      }
       if (upsertOn) {
         if (data[upsertOn] === void 0 || data[upsertOn] === null || data[upsertOn] === "") {
           return this._errorResponse(
@@ -2492,8 +2588,9 @@ function createDatabaseDO(config = {}) {
           409
         );
       }
+      const isNew = !this._engine.recordExists(modelName, id);
+      applyAutoStamps(data, autoStamps, isNew);
       if (hooks?.beforeSave) {
-        const isNew = !this._engine.recordExists(modelName, id);
         const ctx = {
           modelName,
           docId,
@@ -2542,7 +2639,7 @@ function createDatabaseDO(config = {}) {
     /** @internal — Partial update: merge provided fields into existing record */
     async _handlePatch(request, docId) {
       const body = await request.json();
-      const { modelName, id, data, stringSets, condition } = body;
+      const { modelName, id, data, stringSets, condition, autoStamps } = body;
       if (!modelName || !id || !data) {
         return this._errorResponse("modelName, id, and data are required", 400);
       }
@@ -2550,6 +2647,12 @@ function createDatabaseDO(config = {}) {
       if (reservedError) {
         return this._errorResponse(reservedError, 400);
       }
+      {
+        const autoStampsReservedError = checkAutoStampsReservedFields(autoStamps);
+        if (autoStampsReservedError) {
+          return this._errorResponse(autoStampsReservedError, 400);
+        }
+      }
       if (!this._engine.recordExists(modelName, id)) {
         return this._errorResponse(`Record ${modelName}/${id} not found`, 404);
       }
@@ -2559,6 +2662,7 @@ function createDatabaseDO(config = {}) {
           409
         );
       }
+      applyAutoStamps(data, autoStamps, false);
       if (hooks?.beforeSave) {
         const ctx = {
           modelName,
@@ -2645,6 +2749,7 @@ function createDatabaseDO(config = {}) {
       const hookDenials = /* @__PURE__ */ new Map();
       const resolvedBatchIds = /* @__PURE__ */ new Map();
       const opErrors = /* @__PURE__ */ new Map();
+      const batchCreatedIds = /* @__PURE__ */ new Set();
       for (let i = 0; i < operations.length; i++) {
         const op = operations[i];
         if (!op.modelName || !op.id && !(op.op === "save" && op.upsertOn) || !op.op) {
@@ -2696,9 +2801,30 @@ function createDatabaseDO(config = {}) {
               400
             );
           }
+          const autoStampsReservedError = checkAutoStampsReservedFields(
+            op.autoStamps
+          );
+          if (autoStampsReservedError) {
+            return this._errorResponse(
+              `Operation ${i}: ${autoStampsReservedError}`,
+              400
+            );
+          }
+          const effectiveId = resolvedBatchIds.get(i) || op.id || "";
+          const isNew = op.op === "save" ? (
+            // Codex P2 #3: also treat the id as not-new if a previous
+            // op in this batch already resolved to a save for the same
+            // model+id. Without this, two saves to the same fresh id
+            // both compute isNew=true against the pre-transaction
+            // database, so a `'create'` autoStamp on the second op
+            // would overwrite the first op's stamp.
+            !batchCreatedIds.has(`${op.modelName}/${effectiveId}`) && !this._engine.recordExists(op.modelName, effectiveId)
+          ) : false;
+          if (op.op === "save" && isNew && effectiveId) {
+            batchCreatedIds.add(`${op.modelName}/${effectiveId}`);
+          }
+          applyAutoStamps(op.data, op.autoStamps, isNew);
           if (hooks?.beforeSave) {
-            const effectiveId = resolvedBatchIds.get(i) || op.id || "";
-            const isNew = op.op === "save" ? !this._engine.recordExists(op.modelName, effectiveId) : false;
             const ctx = {
               modelName: op.modelName,
               docId,
@@ -4059,7 +4185,8 @@ async function handleRequest(request, env) {
 }
 
 // src/utils/yDocSchema.ts
-var Y = __toESM(require("yjs"), 1);
+var Y2 = __toESM(require("yjs"), 1);
+init_yjsValues();
 function discoverSchema(yDoc) {
   const models = {};
   const metaNames = /* @__PURE__ */ new Set();
@@ -4093,7 +4220,7 @@ function discoverModelNames(yDoc) {
 function materializeMap(yDoc, key) {
   try {
     const map = yDoc.getMap(key);
-    return map instanceof Y.Map ? map : null;
+    return map instanceof Y2.Map ? map : null;
   } catch {
     return null;
   }
@@ -4103,11 +4230,11 @@ function readModelMeta(metaMap) {
   let constraints;
   let relationships;
   for (const [key, value] of metaMap.entries()) {
-    if (key === "_constraints" && value instanceof Y.Map) {
+    if (key === "_constraints" && value instanceof Y2.Map) {
       constraints = readConstraints(value);
-    } else if (key === "_relationships" && value instanceof Y.Map) {
+    } else if (key === "_relationships" && value instanceof Y2.Map) {
       relationships = readRelationships(value);
-    } else if (value instanceof Y.Map) {
+    } else if (value instanceof Y2.Map) {
       fields[key] = readFieldMeta(value);
     }
   }
@@ -4126,6 +4253,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");
@@ -4138,7 +4269,7 @@ function inferModelFromData(dataMap) {
   const fields = {};
   let sampled = 0;
   for (const [_recordId, recordValue] of dataMap.entries()) {
-    if (!(recordValue instanceof Y.Map)) continue;
+    if (!(recordValue instanceof Y2.Map)) continue;
     if (++sampled > 5) break;
     for (const [fieldName, value] of recordValue.entries()) {
       if (fieldName.startsWith("_")) continue;
@@ -4151,7 +4282,7 @@ function inferModelFromData(dataMap) {
   return { fields };
 }
 function inferTypeFromValue(value) {
-  if (value instanceof Y.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -4166,7 +4297,7 @@ function inferTypeFromValue(value) {
 function readConstraints(constraintsMap) {
   const out = {};
   for (const [name, value] of constraintsMap.entries()) {
-    if (!(value instanceof Y.Map)) continue;
+    if (!(value instanceof Y2.Map)) continue;
     let fields = [];
     const rawFields = value.get("fields");
     if (typeof rawFields === "string") {
@@ -4185,7 +4316,7 @@ function readConstraints(constraintsMap) {
 function readRelationships(relsMap) {
   const out = {};
   for (const [name, value] of relsMap.entries()) {
-    if (!(value instanceof Y.Map)) continue;
+    if (!(value instanceof Y2.Map)) continue;
     const rel = {};
     for (const [k, v] of value.entries()) {
       rel[k] = v;
@@ -4196,6 +4327,7 @@ function readRelationships(relsMap) {
 }
 var CAMEL_TO_SNAKE = {
   autoAssign: "auto_assign",
+  autoStamp: "auto_stamp",
   maxLength: "max_length",
   maxCount: "max_count",
   relatedIdField: "related_id_field",
@@ -4226,6 +4358,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");
@@ -4349,10 +4482,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",
@@ -4394,9 +4530,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) {
@@ -4520,3 +4684,4 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
 
 // src/cloudflare-do.ts
 init_metaSync();
+init_sql();

package/dist/cloudflare-do.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;
@@ -1023,6 +1047,25 @@ interface SaveRequest {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-call auto-timestamp directives for schemaless writes.
+     *
+     * Each entry is a list of field names to stamp with `Date.now()`
+     * (milliseconds) at the corresponding lifecycle event:
+     *
+     * - `create` — field is stamped only when the record is new
+     *   (no row exists yet for this `modelName` + `id`).
+     * - `update` — field is stamped on every save (create AND update).
+     *
+     * If the caller already provided an explicit value for the field
+     * in `data`, the explicit value wins and the stamp is skipped.
+     * Stamping happens BEFORE the `beforeSave` user hook runs, so user
+     * hooks may still overwrite the stamped value if they wish.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface DeleteRequest {
     modelName: string;
@@ -1131,6 +1174,17 @@ interface PatchRequest {
     data: Record<string, any>;
     stringSets?: Record<string, string[]>;
     condition?: DocumentFilter;
+    /**
+     * Per-call auto-timestamp directives. A patch is always treated as
+     * an update (`isNew === false`), so only the `update` list is
+     * applied; the `create` list is ignored on patch.
+     *
+     * Explicit values in `data` win.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface PatchResponse {
     success: boolean;
@@ -1146,6 +1200,19 @@ interface BatchOperation {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-operation auto-timestamp directives. Same semantics as
+     * `SaveRequest.autoStamps` / `PatchRequest.autoStamps`. Applied
+     * BEFORE the user `beforeSave` hook runs, with explicit values
+     * in `data` always winning.
+     *
+     * For `op: "patch"`, only the `update` list applies (patches are
+     * always treated as updates).
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface BatchRequest {
     operations: BatchOperation[];
@@ -1186,6 +1253,7 @@ interface SchemaFieldInfo {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1207,6 +1275,35 @@ interface SchemaModelInfo {
 interface SchemaResponse {
     models: Record<string, SchemaModelInfo>;
 }
+/**
+ * Return an error message if `fieldName` is a reserved field name
+ * (matches the policy enforced by `_checkReservedFields` on incoming
+ * record data). Returns `null` if the name is acceptable.
+ *
+ * "id" is allowed (stripped before storage in the JSON column).
+ * "type" maps to the internal `_type` column. Any name starting with
+ * "_" is internal.
+ *
+ * @internal
+ */
+declare function checkReservedFieldName(fieldName: string): string | null;
+/**
+ * Validate that none of the field names listed in `autoStamps.create` /
+ * `autoStamps.update` are reserved. Returns an error message on the
+ * first violation, or `null` if everything is acceptable.
+ *
+ * Codex P2 #2: `_checkReservedFields` only inspects the keys already
+ * present in `data`. Without this check, a request such as
+ * `{ autoStamps: { update: ["type"] } }` would pass the data-level
+ * guard and then have `applyAutoStamps` add a reserved key after the
+ * fact, bypassing the protection.
+ *
+ * @internal
+ */
+declare function checkAutoStampsReservedFields(autoStamps: {
+    create?: string[];
+    update?: string[];
+} | undefined): string | null;
 /**
  * Create a Durable Object class for schemaless database storage.
  *
@@ -1432,6 +1529,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1676,6 +1774,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;
@@ -1910,6 +2019,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;
 /**
@@ -1941,4 +2055,16 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, clearMetaSyncCache, createDatabaseDO, createDocumentDO, discoverModelNames, discoverSchema, handleRequest, inferFieldType, loadSchemaFromTomlString, registerFunctionDefault, schemaToToml, syncInferredMeta, syncModelMeta };
+/**
+ * Produce a deterministic, SQL-safe alias suffix derived from arbitrary input.
+ * The resulting string always matches our identifier policy when prefixed with
+ * a valid identifier segment.
+ */
+declare function deterministicIdentifierHash(value: string): string;
+/**
+ * Build a safe alias using a prefix that already conforms to the identifier
+ * policy along with a deterministic hash of the raw descriptor.
+ */
+declare function buildSafeAlias(prefix: string, rawDescriptor: string): string;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, buildSafeAlias, checkAutoStampsReservedFields, checkReservedFieldName, clearMetaSyncCache, createDatabaseDO, createDocumentDO, deterministicIdentifierHash, discoverModelNames, discoverSchema, handleRequest, inferFieldType, loadSchemaFromTomlString, registerFunctionDefault, schemaToToml, syncInferredMeta, syncModelMeta };