js-bao 0.5.1 → 0.6.0

package/dist/cloudflare-do.js

@@ -229,21 +229,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"]);
@@ -266,18 +281,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;
       }
@@ -329,6 +353,9 @@ var init_patterns = __esm({
 
 // src/utils/yjsValues.ts
 import * as Y from "yjs";
+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()) {
@@ -367,8 +394,33 @@ var init_DocumentQueryTranslator = __esm({
   }
 });
 
-// src/models/metaSync.ts
+// src/models/writeLifecycle.ts
 import * as Y3 from "yjs";
+import { ulid as ulid2 } from "ulid";
+function registerFunctionDefaultGenerator(name, fn) {
+  FUNCTION_DEFAULT_GENERATORS.set(name, fn);
+}
+var KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS, UNKNOWN_FUNCTION_DEFAULT;
+var init_writeLifecycle = __esm({
+  "src/models/writeLifecycle.ts"() {
+    "use strict";
+    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", () => ulid2());
+    UNKNOWN_FUNCTION_DEFAULT = "$unknown_function";
+  }
+});
+
+// src/models/metaSync.ts
+import * as Y4 from "yjs";
 function inferFieldType(value) {
   if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
@@ -389,7 +441,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;
 }
@@ -415,7 +470,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (compoundConstraints.length > 0) {
     let constraints = meta.get("_constraints");
     if (!constraints) {
-      constraints = new Y3.Map();
+      constraints = new Y4.Map();
       meta.set("_constraints", constraints);
     }
     for (const constraint of compoundConstraints) {
@@ -426,7 +481,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (relationships && Object.keys(relationships).length > 0) {
     let rels = meta.get("_relationships");
     if (!rels) {
-      rels = new Y3.Map();
+      rels = new Y4.Map();
       meta.set("_relationships", rels);
     }
     for (const [relName, relConfig] of Object.entries(relationships)) {
@@ -438,7 +493,7 @@ function syncModelMeta(yDoc, modelName, schema) {
 function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   let fieldMeta = metaMap.get(fieldName);
   if (!fieldMeta) {
-    fieldMeta = new Y3.Map();
+    fieldMeta = new Y4.Map();
     metaMap.set(fieldName, fieldMeta);
   }
   setIfChanged(fieldMeta, "type", fieldOpts.type);
@@ -455,7 +510,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
 function syncConstraintMeta(constraintsMap, constraint) {
   let cMeta = constraintsMap.get(constraint.name);
   if (!cMeta) {
-    cMeta = new Y3.Map();
+    cMeta = new Y4.Map();
     constraintsMap.set(constraint.name, cMeta);
   }
   setIfChanged(cMeta, "type", "unique");
@@ -465,7 +520,7 @@ function syncConstraintMeta(constraintsMap, constraint) {
 function syncRelationshipMeta(relsMap, relName, relConfig) {
   let relMeta = relsMap.get(relName);
   if (!relMeta) {
-    relMeta = new Y3.Map();
+    relMeta = new Y4.Map();
     relsMap.set(relName, relMeta);
   }
   for (const [key, value] of Object.entries(relConfig)) {
@@ -480,7 +535,7 @@ function syncInferredMeta(yDoc, modelName, recordData) {
     if (fieldName.startsWith("_")) continue;
     let fieldMeta = meta.get(fieldName);
     if (!fieldMeta) {
-      fieldMeta = new Y3.Map();
+      fieldMeta = new Y4.Map();
       meta.set(fieldName, fieldMeta);
     }
     if (!fieldMeta.has("type")) {
@@ -501,16 +556,537 @@ var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
     init_yjsValues();
+    init_writeLifecycle();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
 });
 
+// src/utils/uniqueIndex.ts
+import * as Y5 from "yjs";
+function fieldUniqueConstraintName(modelName, fieldName) {
+  return `${modelName}_${fieldName}_unique`;
+}
+var init_uniqueIndex = __esm({
+  "src/utils/uniqueIndex.ts"() {
+    "use strict";
+  }
+});
+
+// src/utils/largeDocuments.ts
+import * as Y6 from "yjs";
+function encodeOverlaySegment(segment) {
+  const escaped = segment.replace(/~/g, "~0").replace(/\//g, "~1");
+  return escaped.startsWith("_") ? `~2${escaped.slice(1)}` : escaped;
+}
+function decodeOverlaySegment(segment) {
+  const withUnderscore = segment.startsWith("~2") ? `_${segment.slice(2)}` : segment;
+  return withUnderscore.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function overlayFieldKey(recordId, field) {
+  return `${encodeOverlaySegment(recordId)}${OVERLAY_KEY_SEPARATOR}${encodeOverlaySegment(field)}`;
+}
+function overlayMemberKey(recordId, field, member) {
+  return `${overlayFieldKey(recordId, field)}${OVERLAY_KEY_SEPARATOR}${encodeOverlaySegment(member)}`;
+}
+function overlayMarkerKey(recordId, marker) {
+  return `${encodeOverlaySegment(recordId)}${OVERLAY_KEY_SEPARATOR}${marker}`;
+}
+function parseOverlayKey(key) {
+  const parts = key.split(OVERLAY_KEY_SEPARATOR);
+  if (parts.length === 2) {
+    const [rawId, rawSecond] = parts;
+    const recordId = decodeOverlaySegment(rawId);
+    if (OVERLAY_MARKERS.has(rawSecond)) return { recordId, marker: rawSecond };
+    return { recordId, field: decodeOverlaySegment(rawSecond) };
+  }
+  if (parts.length === 3) {
+    return {
+      recordId: decodeOverlaySegment(parts[0]),
+      field: decodeOverlaySegment(parts[1]),
+      member: decodeOverlaySegment(parts[2])
+    };
+  }
+  return null;
+}
+function emptyEntry(id) {
+  return { id, fields: {}, stringSets: {}, replace: false, deleted: false };
+}
+function groupOverlayEntries(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, value] of entries) {
+    const parsed = parseOverlayKey(key);
+    if (!parsed) continue;
+    let entry = out.get(parsed.recordId);
+    if (!entry) {
+      entry = emptyEntry(parsed.recordId);
+      out.set(parsed.recordId, entry);
+    }
+    if (parsed.marker === OVERLAY_MARKER_REPLACE) {
+      entry.replace = value === true;
+    } else if (parsed.marker === OVERLAY_MARKER_DELETED) {
+      entry.deleted = value === true;
+    } else if (parsed.member !== void 0) {
+      const field = parsed.field;
+      (entry.stringSets[field] ||= {})[parsed.member] = value === true;
+    } else if (parsed.field !== void 0) {
+      entry.fields[parsed.field] = value;
+    }
+  }
+  return out;
+}
+function readOverlayRecord(modelMap, recordId) {
+  return collectOverlayRecords(modelMap, /* @__PURE__ */ new Set([recordId])).get(recordId);
+}
+function completeOverlayEntries(modelMap, entries) {
+  const rebuild = /* @__PURE__ */ new Set();
+  for (const [id, entry] of entries) {
+    if (!entry.replace || entry.deleted) continue;
+    rebuild.add(id);
+  }
+  if (rebuild.size === 0) return entries;
+  for (const [id, entry] of collectOverlayRecords(modelMap, rebuild)) {
+    entries.set(id, entry);
+  }
+  return entries;
+}
+function collectOverlayRecords(modelMap, recordIds) {
+  const wanted = /* @__PURE__ */ new Map();
+  for (const id of recordIds) wanted.set(encodeOverlaySegment(id), id);
+  const own = /* @__PURE__ */ new Map();
+  for (const [key, value] of modelMap.entries()) {
+    if (typeof key !== "string") continue;
+    const separator = key.indexOf(OVERLAY_KEY_SEPARATOR);
+    if (separator <= 0) continue;
+    const id = wanted.get(key.slice(0, separator));
+    if (id === void 0) continue;
+    if (!parseOverlayKey(key)) continue;
+    const keys = own.get(id);
+    if (keys) keys.push([key, value]);
+    else own.set(id, [[key, value]]);
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const id of recordIds) {
+    out.set(id, groupOverlayEntries(own.get(id) ?? []).get(id) ?? emptyEntry(id));
+  }
+  return out;
+}
+function baseMembers(value) {
+  if (Array.isArray(value)) return value.filter((v) => typeof v === "string");
+  if (value && typeof value === "object") {
+    return Object.entries(value).filter(([, present]) => Boolean(present)).map(([member]) => member);
+  }
+  return [];
+}
+function materializeOverlayRecord(base, overlay) {
+  if (overlay.deleted) return null;
+  const out = overlay.replace ? {} : { ...base ?? {} };
+  for (const [field, value] of Object.entries(overlay.fields)) {
+    if (value === null) delete out[field];
+    else out[field] = value;
+  }
+  for (const [field, members] of Object.entries(overlay.stringSets)) {
+    const current = overlay.replace ? [] : baseMembers(out[field]);
+    const next = current.slice();
+    for (const [member, present] of Object.entries(members)) {
+      const at = next.indexOf(member);
+      if (present && at === -1) next.push(member);
+      else if (!present && at !== -1) next.splice(at, 1);
+    }
+    out[field] = next;
+  }
+  out.id = overlay.id;
+  return out;
+}
+function encodeOverlayMutation(mutation) {
+  const { id, kind } = mutation;
+  const entries = [];
+  if (kind === "delete") {
+    entries.push([overlayMarkerKey(id, OVERLAY_MARKER_DELETED), true]);
+    return entries;
+  }
+  if (kind === "create") {
+    entries.push([overlayMarkerKey(id, OVERLAY_MARKER_REPLACE), true]);
+    entries.push([overlayMarkerKey(id, OVERLAY_MARKER_DELETED), false]);
+  }
+  for (const [field, value] of Object.entries(mutation.fields ?? {})) {
+    entries.push([overlayFieldKey(id, field), value === void 0 ? null : value]);
+  }
+  for (const [field, members] of Object.entries(mutation.stringSetDeltas ?? {})) {
+    for (const [member, present] of Object.entries(members)) {
+      entries.push([overlayMemberKey(id, field, member), present]);
+    }
+  }
+  return entries;
+}
+function applyOverlayMutation(modelMap, mutation) {
+  if (mutation.kind === "create") {
+    clearStaleRecordOverlay(modelMap, mutation.id);
+  }
+  for (const [key, value] of encodeOverlayMutation(mutation)) {
+    modelMap.set(key, value);
+  }
+}
+function clearStaleRecordOverlay(modelMap, recordId) {
+  if (!modelMap.has(overlayMarkerKey(recordId, OVERLAY_MARKER_DELETED))) return;
+  const prefix = `${encodeOverlaySegment(recordId)}${OVERLAY_KEY_SEPARATOR}`;
+  const stale = [];
+  for (const key of modelMap.keys()) {
+    if (key.startsWith(prefix)) stale.push(key);
+  }
+  for (const key of stale) modelMap.delete(key);
+}
+function assertNoFormat2CompositeFields(modelName, recordId, fields) {
+  if (!fields) return;
+  for (const [field, value] of Object.entries(fields)) {
+    if (isYjsComposite(value)) {
+      throw new Format2CompositeFieldError(modelName, recordId, field);
+    }
+  }
+}
+function isFormat2StringSetYMap(value) {
+  if (!(value instanceof Y6.Map)) return false;
+  for (const member of value.values()) {
+    if (member !== true && member !== false) return false;
+  }
+  return true;
+}
+function format2StringSetMembers(value) {
+  if (!(value instanceof Y6.Map)) return [];
+  return Array.from(value.entries()).filter(([, present]) => present === true).map(([member]) => member);
+}
+var OVERLAY_KEY_SEPARATOR, OVERLAY_MARKER_REPLACE, OVERLAY_MARKER_DELETED, OVERLAY_MARKERS, Format2CompositeFieldError;
+var init_largeDocuments = __esm({
+  "src/utils/largeDocuments.ts"() {
+    "use strict";
+    init_yjsValues();
+    OVERLAY_KEY_SEPARATOR = "/";
+    OVERLAY_MARKER_REPLACE = "_replace";
+    OVERLAY_MARKER_DELETED = "_deleted";
+    OVERLAY_MARKERS = /* @__PURE__ */ new Set([
+      OVERLAY_MARKER_REPLACE,
+      OVERLAY_MARKER_DELETED
+    ]);
+    Format2CompositeFieldError = class extends Error {
+      modelName;
+      recordId;
+      field;
+      constructor(modelName, recordId, field) {
+        super(
+          `Composite field values are not supported on large documents (format 2): ${modelName}.${field} (id=${recordId})`
+        );
+        this.name = "Format2CompositeFieldError";
+        this.modelName = modelName;
+        this.recordId = recordId;
+        this.field = field;
+      }
+    };
+  }
+});
+
+// src/models/OrmContext.ts
+var OrmContext, defaultOrmContext, liveOrmContexts;
+var init_OrmContext = __esm({
+  "src/models/OrmContext.ts"() {
+    "use strict";
+    OrmContext = class _OrmContext {
+      /** Declared before the field that reads it: static initialization is ordered. */
+      static instanceCounter = 0;
+      /**
+       * Which instance this is, for diagnostics. A process holding several clients
+       * needs a way to say WHICH one a warning is about, so every context takes the
+       * next number as it is created and keeps it for its lifetime.
+       */
+      instanceId = ++_OrmContext.instanceCounter;
+      /** The engine this instance's models read and write through. */
+      dbEngine = null;
+      connectedDocuments = /* @__PURE__ */ new Map();
+      /** `docId_modelName` → the Y.Map that document holds for that model. */
+      documentYMaps = /* @__PURE__ */ new Map();
+      /** `subscribe()` callbacks, by model name. */
+      listenersMap = /* @__PURE__ */ new Map();
+      // Default-document resolution
+      modelNameToDefaultDocId = /* @__PURE__ */ new Map();
+      globalDefaultDocId = void 0;
+      defaultDocChangedListeners = /* @__PURE__ */ new Set();
+      modelDocMappingChangedListeners = /* @__PURE__ */ new Set();
+      /** Format-2 ("large document", #2816) record stores by document id. */
+      format2Documents = /* @__PURE__ */ new Map();
+      /** Format-2 epoch moves in flight (#2816). */
+      format2Transitions = /* @__PURE__ */ new Map();
+      /**
+       * Nested-Y.Map stringset fields this context has already observed. Per
+       * context, not global: a Y.Doc reconnected to a fresh instance has to be
+       * observed again by that instance, and a global guard would silently
+       * suppress it.
+       */
+      observedStringSetMaps = /* @__PURE__ */ new WeakSet();
+      /**
+       * The registry this instance's schema lookups use. `null` on the standing
+       * default context, where callers fall back to the global singleton.
+       */
+      modelRegistry = null;
+      /** Model classes routed to this context. */
+      boundModels = /* @__PURE__ */ new Set();
+      /** True once {@link destroy} has run; bound classes keep pointing here. */
+      destroyed = false;
+      /** Yjs `unobserve` thunks by owning document id. */
+      observerDisposers = /* @__PURE__ */ new Map();
+      /** Teardown the owner (the document manager) registers for `destroy()`. */
+      teardownHooks = /* @__PURE__ */ new Set();
+      static NO_DOCUMENT_KEY = "__no_document__";
+      /**
+       * Record how to remove an observer this context installed. Every `observe()`
+       * in the ORM pairs with one of these: without it a torn-down instance's
+       * callbacks keep firing on a Y.Doc that outlives it.
+       */
+      registerObserverDisposer(docId, dispose) {
+        const key = docId ?? _OrmContext.NO_DOCUMENT_KEY;
+        const list = this.observerDisposers.get(key);
+        if (list) list.push(dispose);
+        else this.observerDisposers.set(key, [dispose]);
+      }
+      /** Remove every observer this context installed for `docId`. */
+      disposeObserversForDocument(docId) {
+        const list = this.observerDisposers.get(docId);
+        if (!list) return;
+        this.observerDisposers.delete(docId);
+        for (const dispose of list) {
+          try {
+            dispose();
+          } catch {
+          }
+        }
+      }
+      disposeAllObservers() {
+        const buckets = Array.from(this.observerDisposers.values());
+        this.observerDisposers.clear();
+        for (const list of buckets) {
+          for (const dispose of list) {
+            try {
+              dispose();
+            } catch {
+            }
+          }
+        }
+      }
+      /** Run `hook` as part of `destroy()` (the format-2 binding registers here). */
+      onDestroy(hook) {
+        this.teardownHooks.add(hook);
+      }
+      /** The record store for `docId`, or `null` when the document is format 1. */
+      getFormat2Store(docId) {
+        if (!docId) return null;
+        return this.format2Documents.get(docId) ?? null;
+      }
+      /**
+       * The epoch move a write to `docId` has to wait out (#2816, behavior 10), or
+       * `null` when none is in flight.
+       */
+      format2WritesHeld(docId) {
+        if (!docId) return null;
+        return this.format2Transitions.get(docId) ?? null;
+      }
+      /** Run an epoch move with `docId`'s local writes held back (#2816). */
+      async holdFormat2Writes(docId, run) {
+        const inFlight = this.format2Transitions.get(docId);
+        if (inFlight) await inFlight.catch(() => {
+        });
+        let release;
+        const held = new Promise((resolve) => {
+          release = resolve;
+        });
+        this.format2Transitions.set(docId, held);
+        try {
+          return await run();
+        } finally {
+          if (this.format2Transitions.get(docId) === held) {
+            this.format2Transitions.delete(docId);
+          }
+          release();
+        }
+      }
+      /** Notify `subscribe()` callbacks registered on this context for `modelName`. */
+      notifyListeners(modelName, log, onError) {
+        const listeners = this.listenersMap.get(modelName);
+        if (!listeners) return;
+        log?.(`Notifying ${listeners.size} listeners for ${modelName}`);
+        listeners.forEach((callback) => {
+          try {
+            callback();
+          } catch (e) {
+            onError?.(e);
+          }
+        });
+      }
+      // ---- Default-document resolution (the `BaseModel` statics delegate here) ----
+      setModelDefaultDocumentId(modelName, docId) {
+        const previous = this.modelNameToDefaultDocId.get(modelName);
+        this.modelNameToDefaultDocId.set(modelName, docId);
+        this.announceModelDocMapping(modelName, previous, docId);
+      }
+      removeModelDefaultDocumentId(modelName) {
+        const previous = this.modelNameToDefaultDocId.get(modelName);
+        this.modelNameToDefaultDocId.delete(modelName);
+        this.announceModelDocMapping(modelName, previous, void 0);
+      }
+      clearModelDefaultDocumentIds() {
+        const entries = Array.from(this.modelNameToDefaultDocId.entries());
+        this.modelNameToDefaultDocId.clear();
+        for (const [modelName, previous] of entries) {
+          this.announceModelDocMapping(modelName, previous, void 0);
+        }
+      }
+      setGlobalDefaultDocumentId(docId) {
+        const previous = this.globalDefaultDocId;
+        this.globalDefaultDocId = docId;
+        this.announceDefaultDoc(previous, docId);
+      }
+      clearGlobalDefaultDocumentId() {
+        const previous = this.globalDefaultDocId;
+        this.globalDefaultDocId = void 0;
+        this.announceDefaultDoc(previous, void 0);
+      }
+      getModelDefaultDocumentMapping() {
+        return Object.fromEntries(this.modelNameToDefaultDocId.entries());
+      }
+      getDocumentIdForModel(modelName) {
+        return this.modelNameToDefaultDocId.get(modelName);
+      }
+      getGlobalDefaultDocumentId() {
+        return this.globalDefaultDocId;
+      }
+      onDefaultDocChanged(listener) {
+        this.defaultDocChangedListeners.add(listener);
+        return () => this.defaultDocChangedListeners.delete(listener);
+      }
+      onModelDocMappingChanged(listener) {
+        this.modelDocMappingChangedListeners.add(listener);
+        return () => this.modelDocMappingChangedListeners.delete(listener);
+      }
+      /** Drop the model→document defaults that point at a disconnected document. */
+      clearMappingsForDocId(docId) {
+        const toRemove = [];
+        for (const [modelName, mappedDocId] of this.modelNameToDefaultDocId) {
+          if (mappedDocId === docId) toRemove.push(modelName);
+        }
+        for (const modelName of toRemove) {
+          this.removeModelDefaultDocumentId(modelName);
+        }
+        if (this.globalDefaultDocId === docId) {
+          this.clearGlobalDefaultDocumentId();
+        }
+      }
+      announceDefaultDoc(previous, current) {
+        for (const listener of this.defaultDocChangedListeners) {
+          try {
+            listener({ previous, current });
+          } catch {
+          }
+        }
+      }
+      announceModelDocMapping(modelName, previous, current) {
+        for (const listener of this.modelDocMappingChangedListeners) {
+          try {
+            listener({ modelName, previous, current });
+          } catch {
+          }
+        }
+      }
+      /**
+       * Tear this instance down: observers off, engine destroyed, state cleared.
+       *
+       * Deliberately does NOT unbind its model classes. They keep resolving this
+       * context, whose engine is now null, so an operation through them throws the
+       * ordinary not-initialized error instead of silently landing on whatever
+       * other instance happens to be live (#3039, behavior 7). Only a later
+       * `initJsBao` may rebind a class whose context is destroyed.
+       */
+      async destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.disposeAllObservers();
+        const hooks = Array.from(this.teardownHooks);
+        this.teardownHooks.clear();
+        for (const hook of hooks) {
+          try {
+            await hook();
+          } catch {
+          }
+        }
+        const engine = this.dbEngine;
+        this.dbEngine = null;
+        if (engine) {
+          try {
+            await engine.destroy();
+          } catch {
+          }
+        }
+        this.connectedDocuments.clear();
+        this.documentYMaps.clear();
+        this.listenersMap.clear();
+        this.modelNameToDefaultDocId.clear();
+        this.globalDefaultDocId = void 0;
+        this.defaultDocChangedListeners.clear();
+        this.modelDocMappingChangedListeners.clear();
+        this.format2Documents.clear();
+        this.format2Transitions.clear();
+        this.observedStringSetMaps = /* @__PURE__ */ new WeakSet();
+        liveOrmContexts.delete(this);
+        if (defaultOrmContext === this) {
+          defaultOrmContext = new _OrmContext();
+        }
+      }
+    };
+    defaultOrmContext = new OrmContext();
+    liveOrmContexts = /* @__PURE__ */ new Set();
+  }
+});
+
+// src/models/format2QueryProjection.ts
+var FORMAT2_QUERY_PROJECTION_DDL;
+var init_format2QueryProjection = __esm({
+  "src/models/format2QueryProjection.ts"() {
+    "use strict";
+    FORMAT2_QUERY_PROJECTION_DDL = `
+CREATE TABLE IF NOT EXISTS _query_projection (
+  doc_id TEXT NOT NULL,
+  model TEXT NOT NULL,
+  PRIMARY KEY (doc_id, model)
+)`.trim();
+  }
+});
+
+// src/models/format2Observer.ts
+import * as Y7 from "yjs";
+var init_format2Observer = __esm({
+  "src/models/format2Observer.ts"() {
+    "use strict";
+    init_largeDocuments();
+  }
+});
+
+// src/models/format2ClientWrite.ts
+var init_format2ClientWrite = __esm({
+  "src/models/format2ClientWrite.ts"() {
+    "use strict";
+  }
+});
+
+// src/models/format2OfflineWindow.ts
+var DAY_MS;
+var init_format2OfflineWindow = __esm({
+  "src/models/format2OfflineWindow.ts"() {
+    "use strict";
+    DAY_MS = 24 * 60 * 60 * 1e3;
+  }
+});
+
 // src/models/BaseModel.ts
-import * as Y4 from "yjs";
-import { ulid as ulid2 } from "ulid";
+import * as Y8 from "yjs";
+import { ulid as ulid3 } from "ulid";
 function generateULID() {
-  return ulid2();
+  return ulid3();
 }
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
@@ -521,7 +1097,15 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_writeLifecycle();
     init_yjsValues();
+    init_uniqueIndex();
+    init_largeDocuments();
+    init_OrmContext();
+    init_format2QueryProjection();
+    init_format2Observer();
+    init_format2ClientWrite();
+    init_format2OfflineWindow();
     registerFunctionDefault(generateULID, "generate_ulid");
   }
 });
@@ -540,6 +1124,7 @@ var init_ModelRegistry = __esm({
     "use strict";
     init_BaseModel();
     init_relationshipManager();
+    init_format2QueryProjection();
   }
 });
 
@@ -575,6 +1160,32 @@ var DatabaseEngine = class {
   getTableName(_modelName) {
     throw new Error("Method not implemented.");
   }
+  /**
+   * A SYNCHRONOUS SQL executor over this engine's database, used by the
+   * large-document (format 2) record store. That store commits a merged
+   * record row and its pending-operation entry as one transaction — the
+   * barrier a `save()` resolves behind — which the async `query()` API cannot
+   * express. Engines whose underlying SQLite is synchronous (better-sqlite3,
+   * SQL.js) provide it; anything else leaves it undefined and cannot host a
+   * large document.
+   */
+  createFormat2Sql;
+  /**
+   * Whether what {@link createFormat2Sql} writes survives this process.
+   *
+   * On a large document the merged record view IS the document: the Y.Doc
+   * holds one epoch's overlay, and everything else — including a record a
+   * `save()` has already resolved, and the pending write that still owes it to
+   * the server — lives only in this store. An engine whose database is in
+   * memory therefore cannot host one: a reload does not cost a cache, it costs
+   * the document and the writes nobody has acknowledged yet.
+   *
+   * The platform is asked separately about its storage quota; this answers the
+   * half only the engine knows. An engine that does not implement it is taken
+   * at the platform's word, which is what keeps hosts with storage of their
+   * own — a worker handed a file store, a test — working unchanged.
+   */
+  format2StorageIsDurable;
   // Transaction support
   async withTransaction(_callback) {
     throw new Error("Method not implemented.");
@@ -1551,6 +2162,45 @@ var DurableObjectEngine = class extends JsonSchemaEngine {
 init_queryTypes();
 init_CursorManager();
 init_sql();
+
+// src/query/recordRow.ts
+var PROJECTED_JSON_ALIAS_PREFIX = "_json_";
+function projectedJsonAlias(fieldName) {
+  return `${PROJECTED_JSON_ALIAS_PREFIX}${fieldName}`;
+}
+function parseRecordRow(row) {
+  const { _id, _type, _data, ...rest } = row;
+  let parsed = {};
+  if (_data) {
+    try {
+      parsed = JSON.parse(_data);
+    } catch (e) {
+      console.warn("Failed to parse _data:", e);
+    }
+  }
+  return { id: _id, type: _type, ...parsed, ...decodeProjectedColumns(rest) };
+}
+function decodeProjectedColumns(columns) {
+  const decoded = {};
+  for (const [column, value] of Object.entries(columns)) {
+    if (!column.startsWith(PROJECTED_JSON_ALIAS_PREFIX)) {
+      decoded[column] = value;
+      continue;
+    }
+    decoded[column.slice(PROJECTED_JSON_ALIAS_PREFIX.length)] = parseJsonColumn(value);
+  }
+  return decoded;
+}
+function parseJsonColumn(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+// src/query/JsonQueryTranslator.ts
 init_patterns();
 var SYSTEM_FIELDS = /* @__PURE__ */ new Set(["id", "type"]);
 var JsonQueryTranslator = class {
@@ -1595,7 +2245,8 @@ var JsonQueryTranslator = class {
     const whereClause = this.translateFilter(filter);
     const orderClause = CursorManager.buildOrderClause(
       options?.sort,
-      (field) => this.getFieldSql(field)
+      (field) => this.getFieldSql(field),
+      options?.direction || 1
     );
     const limitClause = this.buildLimitClause(options);
     const paginationClause = this.buildPaginationClause(
@@ -1868,8 +2519,11 @@ var JsonQueryTranslator = class {
         };
       case "$ne":
         this.validateFieldValue(fieldName, value);
+        if (value === null || value === void 0) {
+          return { sql: `${fieldSql} IS NOT NULL`, params: [] };
+        }
         return {
-          sql: `${fieldSql} != ?`,
+          sql: `(${fieldSql} IS NULL OR ${fieldSql} != ?)`,
           params: [this.convertValueForSQLite(value)]
         };
       case "$gt":
@@ -1952,12 +2606,23 @@ var JsonQueryTranslator = class {
         if (value.length === 0) {
           return { sql: "", params: [] };
         }
-        const ninPlaceholders = value.map(() => "?").join(",");
-        const convertedNinValues = value.map(
+        const ninHasNull = value.some((v) => v === null || v === void 0);
+        const ninValues = value.filter((v) => v !== null && v !== void 0);
+        const ninPlaceholders = ninValues.map(() => "?").join(",");
+        const convertedNinValues = ninValues.map(
           (v) => this.convertValueForSQLite(v)
         );
+        if (ninHasNull) {
+          if (ninValues.length === 0) {
+            return { sql: `${fieldSql} IS NOT NULL`, params: [] };
+          }
+          return {
+            sql: `(${fieldSql} IS NOT NULL AND ${fieldSql} NOT IN (${ninPlaceholders}))`,
+            params: convertedNinValues
+          };
+        }
         return {
-          sql: `${fieldSql} NOT IN (${ninPlaceholders})`,
+          sql: `(${fieldSql} IS NULL OR ${fieldSql} NOT IN (${ninPlaceholders}))`,
           params: convertedNinValues
         };
       case "$exists":
@@ -2046,7 +2711,7 @@ var JsonQueryTranslator = class {
       for (const field of includeFields) {
         if (field === "id" || field === "type") continue;
         selectParts.push(
-          `json_extract(_data, '$.${field}') AS ${quoteIdentifier(field)}`
+          `_data -> '$.${field}' AS ${quoteIdentifier(projectedJsonAlias(field))}`
         );
       }
       return selectParts.join(", ");
@@ -2233,6 +2898,13 @@ var JsonQueryTranslator = class {
 init_CursorManager();
 init_sql();
 import { ulid } from "ulid";
+var AtomicBatchAbort = class extends Error {
+  constructor(failedIndex) {
+    super(`atomic batch aborted at operation ${failedIndex}`);
+    this.failedIndex = failedIndex;
+    this.name = "AtomicBatchAbort";
+  }
+};
 function checkReservedFieldName(fieldName) {
   if (fieldName === "id") return null;
   if (fieldName === "type") {
@@ -2277,6 +2949,35 @@ function applyAutoStamps(data, autoStamps, isNew) {
     }
   }
 }
+function collectAppliedStamps(data, autoStamps, isNew) {
+  if (!autoStamps || !data) return void 0;
+  const stamps = {};
+  const take = (fields) => {
+    if (!fields) return;
+    for (const field of fields) {
+      const value = data[field];
+      if (typeof value === "number" && Number.isFinite(value)) {
+        stamps[field] = value;
+      }
+    }
+  };
+  if (isNew) take(autoStamps.create);
+  take(autoStamps.update);
+  return Object.keys(stamps).length > 0 ? stamps : void 0;
+}
+function collectAppliedValues(data, fieldNames) {
+  if (!data || !fieldNames || fieldNames.length === 0) return void 0;
+  const out = {};
+  for (const name of fieldNames) {
+    const value = data[name];
+    if (value !== void 0) out[name] = value;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function mergeAppliedFields(stamps, applied) {
+  if (!stamps && !applied) return void 0;
+  return { ...stamps ?? {}, ...applied ?? {} };
+}
 function createDatabaseDO(config = {}) {
   const hooks = config.hooks;
   return class DocumentDO {
@@ -2434,6 +3135,16 @@ function createDatabaseDO(config = {}) {
         hasMore,
         isFirstPage
       );
+      if (options?.projection && Object.keys(options.projection).length > 0) {
+        const isExclusion = Object.values(options.projection).some(
+          (v) => v === 0
+        );
+        if (isExclusion) {
+          data = data.map(
+            (rec) => this._applyProjection(rec, options.projection)
+          );
+        }
+      }
       const response = {
         data,
         hasMore,
@@ -2536,6 +3247,7 @@ function createDatabaseDO(config = {}) {
       }
       const isNew = !this._engine.recordExists(modelName, id);
       applyAutoStamps(data, autoStamps, isNew);
+      let hookAppliedNames;
       if (hooks?.beforeSave) {
         const ctx = {
           modelName,
@@ -2551,6 +3263,7 @@ function createDatabaseDO(config = {}) {
         if (!result.allow) {
           return this._errorResponse(result.reason || "Save denied", 403);
         }
+        hookAppliedNames = result.serverAppliedFieldNames;
       }
       const existingForUnique = this._engine.execSqlSync(
         "SELECT _data FROM records WHERE _id = ? AND _type = ?",
@@ -2580,6 +3293,11 @@ function createDatabaseDO(config = {}) {
       }
       this._engine.trackModelFields(modelName, data);
       const response = { success: true, id };
+      const appliedFields = mergeAppliedFields(
+        collectAppliedStamps(data, autoStamps, isNew),
+        collectAppliedValues(data, hookAppliedNames)
+      );
+      if (appliedFields) response.appliedFields = appliedFields;
       return Response.json(response);
     }
     /** @internal — Partial update: merge provided fields into existing record */
@@ -2609,6 +3327,7 @@ function createDatabaseDO(config = {}) {
         );
       }
       applyAutoStamps(data, autoStamps, false);
+      let hookAppliedNames;
       if (hooks?.beforeSave) {
         const ctx = {
           modelName,
@@ -2624,6 +3343,7 @@ function createDatabaseDO(config = {}) {
         if (!result.allow) {
           return this._errorResponse(result.reason || "Save denied", 403);
         }
+        hookAppliedNames = result.serverAppliedFieldNames;
       }
       const existing = this._engine.execSqlSync(
         "SELECT _data FROM records WHERE _id = ? AND _type = ?",
@@ -2647,6 +3367,11 @@ function createDatabaseDO(config = {}) {
       }
       this._engine.trackModelFields(modelName, data);
       const response = { success: true, id };
+      const appliedFields = mergeAppliedFields(
+        collectAppliedStamps(data, autoStamps, false),
+        collectAppliedValues(data, hookAppliedNames)
+      );
+      if (appliedFields) response.appliedFields = appliedFields;
       return Response.json(response);
     }
     /** @internal */
@@ -2688,7 +3413,7 @@ function createDatabaseDO(config = {}) {
     /** @internal — Execute multiple save/patch/delete operations in a single transaction */
     async _handleBatch(request, docId) {
       const body = await request.json();
-      const { operations } = body;
+      const { operations, atomic = false } = body;
       if (!operations || !Array.isArray(operations) || operations.length === 0) {
         return this._errorResponse("operations array is required and must not be empty", 400);
       }
@@ -2696,6 +3421,8 @@ function createDatabaseDO(config = {}) {
       const resolvedBatchIds = /* @__PURE__ */ new Map();
       const opErrors = /* @__PURE__ */ new Map();
       const batchCreatedIds = /* @__PURE__ */ new Set();
+      const batchIsNew = /* @__PURE__ */ new Map();
+      const batchAppliedNames = /* @__PURE__ */ new Map();
       for (let i = 0; i < operations.length; i++) {
         const op = operations[i];
         if (!op.modelName || !op.id && !(op.op === "save" && op.upsertOn) || !op.op) {
@@ -2769,6 +3496,7 @@ function createDatabaseDO(config = {}) {
           if (op.op === "save" && isNew && effectiveId) {
             batchCreatedIds.add(`${op.modelName}/${effectiveId}`);
           }
+          batchIsNew.set(i, isNew);
           applyAutoStamps(op.data, op.autoStamps, isNew);
           if (hooks?.beforeSave) {
             const ctx = {
@@ -2784,6 +3512,8 @@ function createDatabaseDO(config = {}) {
             const result = await hooks.beforeSave(ctx);
             if (!result.allow) {
               hookDenials.set(i, result.reason || "Save denied");
+            } else if (result.serverAppliedFieldNames) {
+              batchAppliedNames.set(i, result.serverAppliedFieldNames);
             }
           }
         } else if (op.op === "delete") {
@@ -2832,205 +3562,263 @@ function createDatabaseDO(config = {}) {
       }
       const results = [];
       const fieldsToTrack = [];
-      this._engine.transactionSync(() => {
-        for (let i = 0; i < operations.length; i++) {
-          const op = operations[i];
-          if (hookDenials.has(i)) {
-            const effectiveId = resolvedBatchIds.get(i) || op.id || "";
-            results.push({
-              success: false,
-              id: effectiveId,
-              error: hookDenials.get(i)
-            });
-            continue;
-          }
-          if (opErrors.has(i)) {
-            results.push({
-              success: false,
-              id: op.id || "",
-              error: opErrors.get(i)
-            });
-            continue;
-          }
-          const conditionId = resolvedBatchIds.get(i) || op.id;
-          if (op.condition && !this._checkCondition(op.modelName, conditionId, op.condition)) {
-            results.push({
-              success: false,
-              id: conditionId,
-              error: `Condition not met for ${op.modelName}/${conditionId}`
-            });
-            continue;
-          }
-          if (op.op === "save") {
-            let opId = resolvedBatchIds.get(i) || op.id;
-            if (op.ifNotExists && this._engine.recordExists(op.modelName, opId)) {
-              results.push({
-                success: false,
-                id: opId,
-                error: `Record ${op.modelName}/${opId} already exists`
+      const pushFailure = (index, failure) => {
+        results.push({
+          success: false,
+          id: failure.id,
+          error: failure.error,
+          status: failure.status,
+          code: failure.code
+        });
+        if (atomic) throw new AtomicBatchAbort(index);
+      };
+      try {
+        this._engine.transactionSync(() => {
+          for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            if (hookDenials.has(i)) {
+              const effectiveId = resolvedBatchIds.get(i) || op.id || "";
+              pushFailure(i, {
+                id: effectiveId,
+                error: hookDenials.get(i),
+                status: 403,
+                code: "HOOK_DENIED"
               });
               continue;
             }
-            if (op.data) {
-              const existingForUnique = this._engine.execSqlSync(
-                "SELECT _data FROM records WHERE _id = ? AND _type = ?",
-                [opId, op.modelName]
-              );
-              let dataForUnique = op.data;
-              if (existingForUnique.length > 0) {
-                const existingData = JSON.parse(existingForUnique[0]._data);
-                dataForUnique = { ...existingData, ...op.data };
-              }
-              const violation = this._engine.checkUniqueConstraints(
-                op.modelName,
-                opId,
-                dataForUnique
-              );
-              if (violation) {
-                results.push({
-                  success: false,
+            if (opErrors.has(i)) {
+              pushFailure(i, {
+                id: op.id || "",
+                error: opErrors.get(i),
+                status: 400,
+                code: "VALIDATION_ERROR"
+              });
+              continue;
+            }
+            const conditionId = resolvedBatchIds.get(i) || op.id;
+            if (op.condition && !this._checkCondition(op.modelName, conditionId, op.condition)) {
+              pushFailure(i, {
+                id: conditionId,
+                error: `Condition not met for ${op.modelName}/${conditionId}`,
+                status: 409,
+                code: "CONDITION_NOT_MET"
+              });
+              continue;
+            }
+            if (op.op === "save") {
+              let opId = resolvedBatchIds.get(i) || op.id;
+              if (op.ifNotExists && this._engine.recordExists(op.modelName, opId)) {
+                pushFailure(i, {
                   id: opId,
-                  error: violation
+                  error: `Record ${op.modelName}/${opId} already exists`,
+                  status: 409,
+                  code: "ALREADY_EXISTS"
                 });
                 continue;
               }
-            }
-            if (op.stringSets && Object.keys(op.stringSets).length > 0) {
-              const { id: _id, ...fieldsForJson } = op.data;
-              const jsonFields = { ...fieldsForJson, ...op.stringSets };
-              const dataJson = JSON.stringify(jsonFields);
-              this._engine.execSqlSync(
-                "INSERT INTO records (_id, _type, _data) VALUES (?, ?, ?) ON CONFLICT(_type, _id) DO UPDATE SET _data = json_patch(records._data, excluded._data)",
-                [opId, op.modelName, dataJson]
-              );
-              for (const [fieldName, values] of Object.entries(op.stringSets)) {
-                this._engine.execSqlSync(
-                  "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ? AND field = ?",
-                  [op.modelName, opId, fieldName]
+              if (op.data) {
+                const existingForUnique = this._engine.execSqlSync(
+                  "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+                  [opId, op.modelName]
                 );
-                for (const value of values) {
-                  this._engine.execSqlSync(
-                    "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
-                    [opId, op.modelName, fieldName, value]
-                  );
+                let dataForUnique = op.data;
+                if (existingForUnique.length > 0) {
+                  const existingData = JSON.parse(existingForUnique[0]._data);
+                  dataForUnique = { ...existingData, ...op.data };
                 }
-              }
-            } else {
-              const { id: _id, ...fieldsForJson } = op.data;
-              const dataJson = JSON.stringify(fieldsForJson);
-              this._engine.execSqlSync(
-                "INSERT INTO records (_id, _type, _data) VALUES (?, ?, ?) ON CONFLICT(_type, _id) DO UPDATE SET _data = json_patch(records._data, excluded._data)",
-                [opId, op.modelName, dataJson]
-              );
-            }
-            if (op.data) fieldsToTrack.push({ modelName: op.modelName, data: op.data });
-            results.push({ success: true, id: opId });
-          } else if (op.op === "patch") {
-            if (!this._engine.recordExists(op.modelName, op.id)) {
-              results.push({
-                success: false,
-                id: op.id,
-                error: `Record ${op.modelName}/${op.id} not found`
-              });
-              continue;
-            }
-            if (op.data) {
-              const existing = this._engine.execSqlSync(
-                "SELECT _data FROM records WHERE _id = ? AND _type = ?",
-                [op.id, op.modelName]
-              );
-              if (existing.length > 0) {
-                const existingData = JSON.parse(existing[0]._data);
-                const mergedData = { ...existingData, ...op.data };
                 const violation = this._engine.checkUniqueConstraints(
                   op.modelName,
-                  op.id,
-                  mergedData
+                  opId,
+                  dataForUnique
                 );
                 if (violation) {
-                  results.push({
-                    success: false,
-                    id: op.id,
-                    error: violation
+                  pushFailure(i, {
+                    id: opId,
+                    error: violation,
+                    status: 409,
+                    code: "UNIQUE_VIOLATION"
                   });
                   continue;
                 }
               }
-            }
-            const found = this._engine.patchRecordRaw(
-              op.modelName,
-              op.id,
-              op.data,
-              op.stringSets
-            );
-            if (!found) {
-              results.push({
-                success: false,
-                id: op.id,
-                error: `Record ${op.modelName}/${op.id} not found`
-              });
-            } else {
+              if (op.stringSets && Object.keys(op.stringSets).length > 0) {
+                const { id: _id, ...fieldsForJson } = op.data;
+                const jsonFields = { ...fieldsForJson, ...op.stringSets };
+                const dataJson = JSON.stringify(jsonFields);
+                this._engine.execSqlSync(
+                  "INSERT INTO records (_id, _type, _data) VALUES (?, ?, ?) ON CONFLICT(_type, _id) DO UPDATE SET _data = json_patch(records._data, excluded._data)",
+                  [opId, op.modelName, dataJson]
+                );
+                for (const [fieldName, values] of Object.entries(op.stringSets)) {
+                  this._engine.execSqlSync(
+                    "DELETE FROM stringset_index WHERE _type = ? AND _record_id = ? AND field = ?",
+                    [op.modelName, opId, fieldName]
+                  );
+                  for (const value of values) {
+                    this._engine.execSqlSync(
+                      "INSERT OR IGNORE INTO stringset_index (_record_id, _type, field, value) VALUES (?, ?, ?, ?)",
+                      [opId, op.modelName, fieldName, value]
+                    );
+                  }
+                }
+              } else {
+                const { id: _id, ...fieldsForJson } = op.data;
+                const dataJson = JSON.stringify(fieldsForJson);
+                this._engine.execSqlSync(
+                  "INSERT INTO records (_id, _type, _data) VALUES (?, ?, ?) ON CONFLICT(_type, _id) DO UPDATE SET _data = json_patch(records._data, excluded._data)",
+                  [opId, op.modelName, dataJson]
+                );
+              }
               if (op.data) fieldsToTrack.push({ modelName: op.modelName, data: op.data });
+              const saveResult = { success: true, id: opId };
+              const saveApplied = mergeAppliedFields(
+                collectAppliedStamps(
+                  op.data,
+                  op.autoStamps,
+                  batchIsNew.get(i) ?? false
+                ),
+                collectAppliedValues(op.data, batchAppliedNames.get(i))
+              );
+              if (saveApplied) saveResult.appliedFields = saveApplied;
+              results.push(saveResult);
+            } else if (op.op === "patch") {
+              if (!this._engine.recordExists(op.modelName, op.id)) {
+                pushFailure(i, {
+                  id: op.id,
+                  error: `Record ${op.modelName}/${op.id} not found`,
+                  status: 404,
+                  code: "NOT_FOUND"
+                });
+                continue;
+              }
+              if (op.data) {
+                const existing = this._engine.execSqlSync(
+                  "SELECT _data FROM records WHERE _id = ? AND _type = ?",
+                  [op.id, op.modelName]
+                );
+                if (existing.length > 0) {
+                  const existingData = JSON.parse(existing[0]._data);
+                  const mergedData = { ...existingData, ...op.data };
+                  const violation = this._engine.checkUniqueConstraints(
+                    op.modelName,
+                    op.id,
+                    mergedData
+                  );
+                  if (violation) {
+                    pushFailure(i, {
+                      id: op.id,
+                      error: violation,
+                      status: 409,
+                      code: "UNIQUE_VIOLATION"
+                    });
+                    continue;
+                  }
+                }
+              }
+              const found = this._engine.patchRecordRaw(
+                op.modelName,
+                op.id,
+                op.data,
+                op.stringSets
+              );
+              if (!found) {
+                pushFailure(i, {
+                  id: op.id,
+                  error: `Record ${op.modelName}/${op.id} not found`,
+                  status: 404,
+                  code: "NOT_FOUND"
+                });
+              } else {
+                if (op.data) fieldsToTrack.push({ modelName: op.modelName, data: op.data });
+                const patchResult = {
+                  success: true,
+                  id: op.id
+                };
+                const patchApplied = mergeAppliedFields(
+                  collectAppliedStamps(op.data, op.autoStamps, false),
+                  collectAppliedValues(op.data, batchAppliedNames.get(i))
+                );
+                if (patchApplied) patchResult.appliedFields = patchApplied;
+                results.push(patchResult);
+              }
+            } else if (op.op === "delete") {
+              this._engine.execSqlSync(
+                "DELETE FROM records WHERE _id = ? AND _type = ?",
+                [op.id, op.modelName]
+              );
+              this._engine.execSqlSync(
+                "DELETE FROM stringset_index WHERE _record_id = ? AND _type = ?",
+                [op.id, op.modelName]
+              );
+              results.push({ success: true, id: op.id });
+            } else if (op.op === "increment") {
+              const newValues = this._engine.incrementFieldsRaw(
+                op.modelName,
+                op.id,
+                op.fields
+              );
+              if (!newValues) {
+                pushFailure(i, {
+                  id: op.id,
+                  error: `Record ${op.modelName}/${op.id} not found`,
+                  status: 404,
+                  code: "NOT_FOUND"
+                });
+              } else {
+                results.push({ success: true, id: op.id, values: newValues });
+              }
+            } else if (op.op === "addToSet") {
+              if (!this._engine.recordExists(op.modelName, op.id)) {
+                pushFailure(i, {
+                  id: op.id,
+                  error: `Record ${op.modelName}/${op.id} not found`,
+                  status: 404,
+                  code: "NOT_FOUND"
+                });
+                continue;
+              }
+              this._engine.addToStringSetsRaw(
+                op.modelName,
+                op.id,
+                op.stringSets
+              );
+              results.push({ success: true, id: op.id });
+            } else if (op.op === "removeFromSet") {
+              if (!this._engine.recordExists(op.modelName, op.id)) {
+                pushFailure(i, {
+                  id: op.id,
+                  error: `Record ${op.modelName}/${op.id} not found`,
+                  status: 404,
+                  code: "NOT_FOUND"
+                });
+                continue;
+              }
+              this._engine.removeFromStringSetsRaw(
+                op.modelName,
+                op.id,
+                op.stringSets
+              );
               results.push({ success: true, id: op.id });
             }
-          } else if (op.op === "delete") {
-            this._engine.execSqlSync(
-              "DELETE FROM records WHERE _id = ? AND _type = ?",
-              [op.id, op.modelName]
-            );
-            this._engine.execSqlSync(
-              "DELETE FROM stringset_index WHERE _record_id = ? AND _type = ?",
-              [op.id, op.modelName]
-            );
-            results.push({ success: true, id: op.id });
-          } else if (op.op === "increment") {
-            const newValues = this._engine.incrementFieldsRaw(
-              op.modelName,
-              op.id,
-              op.fields
-            );
-            if (!newValues) {
-              results.push({
-                success: false,
-                id: op.id,
-                error: `Record ${op.modelName}/${op.id} not found`
-              });
-            } else {
-              results.push({ success: true, id: op.id, values: newValues });
-            }
-          } else if (op.op === "addToSet") {
-            if (!this._engine.recordExists(op.modelName, op.id)) {
-              results.push({
-                success: false,
-                id: op.id,
-                error: `Record ${op.modelName}/${op.id} not found`
-              });
-              continue;
-            }
-            this._engine.addToStringSetsRaw(
-              op.modelName,
-              op.id,
-              op.stringSets
-            );
-            results.push({ success: true, id: op.id });
-          } else if (op.op === "removeFromSet") {
-            if (!this._engine.recordExists(op.modelName, op.id)) {
-              results.push({
-                success: false,
-                id: op.id,
-                error: `Record ${op.modelName}/${op.id} not found`
-              });
-              continue;
-            }
-            this._engine.removeFromStringSetsRaw(
-              op.modelName,
-              op.id,
-              op.stringSets
-            );
-            results.push({ success: true, id: op.id });
           }
+        });
+      } catch (err) {
+        if (err instanceof AtomicBatchAbort) {
+          const failed = results[err.failedIndex];
+          const failedOp = operations[err.failedIndex];
+          console.warn(
+            `[js-bao batch] atomic rollback: operation ${err.failedIndex} (${failedOp?.op}) failed \u2014 ${failed?.error ?? "unknown error"}`
+          );
+          const errorBody = {
+            error: `Operation ${err.failedIndex} (${failedOp?.op}) failed: ${failed?.error ?? "unknown error"}`,
+            failedIndex: err.failedIndex,
+            op: failedOp?.op,
+            code: failed?.code
+          };
+          return Response.json(errorBody, { status: failed?.status ?? 409 });
         }
-      });
+        throw err;
+      }
       for (const entry of fieldsToTrack) {
         this._engine.trackModelFields(entry.modelName, entry.data);
       }
@@ -3400,6 +4188,18 @@ function createDatabaseDO(config = {}) {
         }
         return facetResult;
       }
+      if (aggOptions.groupBy.length === 0) {
+        const row = results[0];
+        const flat = {};
+        for (const op of aggOptions.operations) {
+          if (op.type === "count") {
+            flat.count = row.count;
+          } else {
+            flat[`${op.type}_${op.field}`] = row[`${op.type}_${op.field}`];
+          }
+        }
+        return flat;
+      }
       const nestedResult = {};
       const aliasLookup = /* @__PURE__ */ new Map();
       for (const entry of aliasMap) {
@@ -3727,16 +4527,7 @@ function createDatabaseDO(config = {}) {
     }
     /** @internal */
     _parseRow(row) {
-      const { _id, _type, _data, ...rest } = row;
-      let parsed = {};
-      if (_data) {
-        try {
-          parsed = JSON.parse(_data);
-        } catch (e) {
-          console.warn("Failed to parse _data:", e);
-        }
-      }
-      return { id: _id, type: _type, ...parsed, ...rest };
+      return parseRecordRow(row);
     }
     // ─── Include (Related Data Loading) ──────────────────────────────
     /** @internal — Validate an IncludeSpec, returning an error message or null */
@@ -3866,8 +4657,9 @@ function createDatabaseDO(config = {}) {
         spec.filter,
         { projection: spec.projection }
       );
+      const relatedProjected = spec.projection ? related.map((r) => this._applyProjection(r, spec.projection)) : related;
       const lookupMap = /* @__PURE__ */ new Map();
-      for (const r of related) {
+      for (const r of relatedProjected) {
         lookupMap.set(r.id, r);
       }
       for (const rec of records) {
@@ -3900,8 +4692,9 @@ function createDatabaseDO(config = {}) {
         spec.filter,
         { projection: spec.projection }
       );
+      const targetsProjected = spec.projection ? targets.map((t) => this._applyProjection(t, spec.projection)) : targets;
       const targetLookup = /* @__PURE__ */ new Map();
-      for (const t of targets) {
+      for (const t of targetsProjected) {
         targetLookup.set(t.id, t);
       }
       for (const rec of records) {
@@ -4045,6 +4838,14 @@ function createDatabaseDO(config = {}) {
       return allResults;
     }
     /** @internal — Apply projection to a single record */
+    // Apply a projection to a single record. Assumes the projection has
+    // already been validated upstream (JsonQueryTranslator.validateProjection /
+    // buildSelectClause reject mixed inclusion+exclusion): `isInclusion` treats
+    // "any value === 1" as inclusion mode, so an unvalidated mixed projection
+    // would silently ignore the excludes. `id` and `type` are system-identity
+    // fields and are always kept in BOTH modes (a record without its `id` is
+    // unusable downstream). `_meta` is NOT forced — an explicit `{ _meta: 0 }`
+    // is honored.
     _applyProjection(record, projection) {
       const fields = Object.entries(projection);
       if (fields.length === 0) return record;
@@ -4063,7 +4864,7 @@ function createDatabaseDO(config = {}) {
       } 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;
       }
@@ -4154,6 +4955,12 @@ function discoverSchema(yDoc) {
   }
   return { models };
 }
+function discoverDeclaredModel(yDoc, modelName) {
+  const key = `_meta_${modelName}`;
+  if (!yDoc.share.has(key)) return void 0;
+  const map = materializeMap(yDoc, key);
+  return map ? readModelMeta(map) : void 0;
+}
 function discoverModelNames(yDoc) {
   const names = [];
   for (const key of yDoc.share.keys()) {
@@ -4341,6 +5148,7 @@ import { parse as parseToml } from "smol-toml";
 // src/models/schema.ts
 init_BaseModel();
 init_ModelRegistry();
+init_uniqueIndex();
 function defineModelSchema(input) {
   const { name, fields } = input;
   const options = {
@@ -4383,7 +5191,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]
       });
     }
@@ -4631,24 +5439,302 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
 // src/cloudflare-do.ts
 init_metaSync();
 init_sql();
+init_largeDocuments();
+
+// src/utils/overlaySql.ts
+init_sql();
+var DEFAULT_OVERLAY_TABLES = {
+  records: "records",
+  stringSetIndex: "stringset_index"
+};
+var statementCache = /* @__PURE__ */ new Map();
+function statementsFor(tables) {
+  const cacheKey = `${tables.records}\0${tables.stringSetIndex}`;
+  const cached = statementCache.get(cacheKey);
+  if (cached) return cached;
+  assertValidIdentifier(tables.records, "overlay records table");
+  assertValidIdentifier(tables.stringSetIndex, "overlay stringset table");
+  const records = tables.records;
+  const members = tables.stringSetIndex;
+  const statements = {
+    deleteRecord: `DELETE FROM ${records} WHERE _type = ? AND _id = ?`,
+    deleteAllMembers: `DELETE FROM ${members} WHERE _type = ? AND _record_id = ?`,
+    deleteMember: `DELETE FROM ${members} WHERE _type = ? AND _record_id = ? AND field = ? AND value = ?`,
+    insertMember: `INSERT OR IGNORE INTO ${members} (_record_id, _type, field, value) VALUES (?, ?, ?, ?)`,
+    selectMembers: `SELECT value FROM ${members} WHERE _type = ? AND _record_id = ? AND field = ? ORDER BY rowid`,
+    mergeUpsert: `
+INSERT INTO ${records} (_id, _type, _data)
+VALUES (?, ?, json_patch('{}', ?))
+ON CONFLICT(_type, _id) DO UPDATE SET
+  _data = json_patch(${records}._data, ?)`.trim(),
+    replaceUpsert: `
+INSERT INTO ${records} (_id, _type, _data)
+VALUES (?, ?, json_patch('{}', ?))
+ON CONFLICT(_type, _id) DO UPDATE SET
+  _data = json_patch('{}', ?)`.trim()
+  };
+  statementCache.set(cacheKey, statements);
+  return statements;
+}
+function projectOverlayEntry(sql, modelName, entry, tables = DEFAULT_OVERLAY_TABLES) {
+  const id = entry.id;
+  const {
+    deleteRecord: DELETE_RECORD,
+    deleteAllMembers: DELETE_ALL_MEMBERS,
+    deleteMember: DELETE_MEMBER,
+    insertMember: INSERT_MEMBER,
+    selectMembers: SELECT_MEMBERS,
+    mergeUpsert: MERGE_UPSERT,
+    replaceUpsert: REPLACE_UPSERT
+  } = statementsFor(tables);
+  if (entry.deleted) {
+    sql.exec(DELETE_RECORD, modelName, id);
+    sql.exec(DELETE_ALL_MEMBERS, modelName, id);
+    return;
+  }
+  const touchedFields = Object.keys(entry.fields);
+  const touchedSets = Object.keys(entry.stringSets);
+  if (!entry.replace && touchedFields.length === 0 && touchedSets.length === 0) {
+    return;
+  }
+  if (entry.replace) {
+    sql.exec(DELETE_ALL_MEMBERS, modelName, id);
+  }
+  const patch = { ...entry.fields, id };
+  for (const [field, members] of Object.entries(entry.stringSets)) {
+    for (const [member, present] of Object.entries(members)) {
+      if (present) sql.exec(INSERT_MEMBER, id, modelName, field, member);
+      else sql.exec(DELETE_MEMBER, modelName, id, field, member);
+    }
+    const rows = Array.from(sql.exec(SELECT_MEMBERS, modelName, id, field));
+    patch[field] = rows.map((row) => row.value);
+  }
+  const patchJson = JSON.stringify(patch);
+  sql.exec(
+    entry.replace ? REPLACE_UPSERT : MERGE_UPSERT,
+    id,
+    modelName,
+    patchJson,
+    patchJson
+  );
+}
+
+// src/utils/snapshotChunks.ts
+var SnapshotChunkIntegrityError = class extends Error {
+  constructor(key, reason) {
+    super(`Snapshot chunk ${key} does not match its manifest entry: ${reason}`);
+    this.key = key;
+    this.name = "SnapshotChunkIntegrityError";
+  }
+};
+var SnapshotRowFormatError = class extends Error {
+  constructor(model, id) {
+    super(
+      `Record ${model}/${id} cannot be written to a snapshot chunk: its id or data contains a newline or tab, which the line format reserves`
+    );
+    this.name = "SnapshotRowFormatError";
+  }
+};
+function snapshotStringSetFields(manifest, model) {
+  const declared = manifest.schema?.[model]?.stringSetFields;
+  return new Set(Array.isArray(declared) ? declared.map(String) : []);
+}
+function snapshotDeclaredSchema(manifest, model) {
+  const declared = manifest.schema?.[model] ?? {};
+  const list = (value) => Array.isArray(value) ? value : [];
+  const declaration = declared.declaration && typeof declared.declaration === "object" ? {
+    fields: declared.declaration.fields ?? {},
+    constraints: declared.declaration.constraints ?? {}
+  } : void 0;
+  return {
+    ...declaration ? { declaration } : {},
+    stringSetFields: list(declared.stringSetFields).map(String),
+    uniqueConstraints: list(declared.uniqueConstraints).filter(
+      (constraint) => constraint?.name && Array.isArray(constraint.fields) && constraint.fields.length > 0
+    ).map((constraint) => ({
+      name: String(constraint.name),
+      fields: constraint.fields.map(String)
+    })),
+    indexedFields: list(declared.indexedFields).filter((index) => index?.field).map((index) => ({
+      field: String(index.field),
+      type: String(index.type || "string"),
+      unique: !!index.unique
+    }))
+  };
+}
+function snapshotRowAsOverlayEntry(id, data, stringSetFields) {
+  const fields = {};
+  const stringSets = {};
+  for (const [field, value] of Object.entries(data)) {
+    if (field === "id") continue;
+    if (stringSetFields.has(field) && Array.isArray(value)) {
+      const members = {};
+      for (const member of value) members[String(member)] = true;
+      stringSets[field] = members;
+      continue;
+    }
+    fields[field] = value;
+  }
+  return { id, fields, stringSets, replace: true, deleted: false };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function assertLineSafe(row) {
+  if (/[\n\r\t]/.test(row._id) || /[\n\r\t]/.test(row._data)) {
+    throw new SnapshotRowFormatError(row._type, row._id);
+  }
+}
+function snapshotChunkLines(rows) {
+  let body = "";
+  for (const row of rows) {
+    assertLineSafe(row);
+    body += `${row._id}	${row._data}
+`;
+  }
+  return body;
+}
+async function gzip(bytes) {
+  return await collect(
+    new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"))
+  );
+}
+async function gunzip(bytes) {
+  return await collect(
+    new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"))
+  );
+}
+async function collect(stream) {
+  const parts = [];
+  let total = 0;
+  const reader = stream.getReader();
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    parts.push(value);
+    total += value.byteLength;
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.byteLength;
+  }
+  return out;
+}
+async function sha256Hex(bytes) {
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function encodeSnapshotChunk(input) {
+  const lines = encoder.encode(snapshotChunkLines(input.rows));
+  const body = await gzip(lines);
+  return {
+    body,
+    entry: {
+      key: input.key,
+      model: input.model,
+      bytes: body.byteLength,
+      rawBytes: lines.byteLength,
+      rows: input.rows.length,
+      firstId: input.rows.length > 0 ? input.rows[0]._id : "",
+      lastId: input.rows.length > 0 ? input.rows[input.rows.length - 1]._id : "",
+      sha256: await sha256Hex(body)
+    }
+  };
+}
+async function readSnapshotChunk(body, descriptor) {
+  const entry = "sha256" in descriptor ? descriptor : null;
+  if (entry) {
+    if (body.byteLength !== entry.bytes) {
+      throw new SnapshotChunkIntegrityError(
+        entry.key,
+        `expected ${entry.bytes} bytes, got ${body.byteLength}`
+      );
+    }
+    const digest = await sha256Hex(body);
+    if (digest !== entry.sha256) {
+      throw new SnapshotChunkIntegrityError(
+        entry.key,
+        `expected sha256 ${entry.sha256}, got ${digest}`
+      );
+    }
+  }
+  const text = decoder.decode(await gunzip(body));
+  const rows = [];
+  for (const line of text.split("\n")) {
+    if (line.length === 0) continue;
+    const tab = line.indexOf("	");
+    if (tab < 0) {
+      throw new SnapshotChunkIntegrityError(
+        entry?.key ?? descriptor.model,
+        "a line carries no id/data separator"
+      );
+    }
+    rows.push({
+      _type: descriptor.model,
+      _id: line.slice(0, tab),
+      _data: line.slice(tab + 1)
+    });
+  }
+  if (entry && rows.length !== entry.rows) {
+    throw new SnapshotChunkIntegrityError(
+      entry.key,
+      `expected ${entry.rows} rows, got ${rows.length}`
+    );
+  }
+  return rows;
+}
 export {
+  DEFAULT_OVERLAY_TABLES,
   DurableObjectEngine,
+  Format2CompositeFieldError,
   JsonQueryTranslator,
   JsonSchemaDDL,
+  OVERLAY_KEY_SEPARATOR,
+  OVERLAY_MARKER_DELETED,
+  OVERLAY_MARKER_REPLACE,
+  PROJECTED_JSON_ALIAS_PREFIX,
+  SnapshotChunkIntegrityError,
+  SnapshotRowFormatError,
+  applyOverlayMutation,
+  assertNoFormat2CompositeFields,
   buildSafeAlias,
   checkAutoStampsReservedFields,
   checkReservedFieldName,
   clearMetaSyncCache,
+  completeOverlayEntries,
   createDatabaseDO,
   createDocumentDO,
+  decodeOverlaySegment,
   deterministicIdentifierHash,
+  discoverDeclaredModel,
   discoverModelNames,
   discoverSchema,
+  encodeOverlayMutation,
+  encodeOverlaySegment,
+  encodeSnapshotChunk,
+  format2StringSetMembers,
+  groupOverlayEntries,
   handleRequest,
   inferFieldType,
+  isFormat2StringSetYMap,
   loadSchemaFromTomlString,
+  materializeOverlayRecord,
+  overlayFieldKey,
+  overlayMarkerKey,
+  overlayMemberKey,
+  parseOverlayKey,
+  parseRecordRow,
+  projectOverlayEntry,
+  projectedJsonAlias,
+  readOverlayRecord,
+  readSnapshotChunk,
   registerFunctionDefault,
   schemaToToml,
+  snapshotChunkLines,
+  snapshotDeclaredSchema,
+  snapshotRowAsOverlayEntry,
+  snapshotStringSetFields,
   syncInferredMeta,
   syncModelMeta
 };