js-bao 0.5.2 → 0.6.1

package/dist/cloudflare-do.cjs

@@ -379,6 +379,9 @@ var init_patterns = __esm({
 });
 
 // src/utils/yjsValues.ts
+function isYjsComposite(value) {
+  return value instanceof Y.Map || value instanceof Y.Array || value instanceof Y.Text;
+}
 function isStringSetYMap(value) {
   if (!(value instanceof Y.Map)) return false;
   for (const v of value.values()) {
@@ -599,15 +602,525 @@ var init_uniqueIndex = __esm({
   }
 });
 
+// src/utils/largeDocuments.ts
+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 Y6, OVERLAY_KEY_SEPARATOR, OVERLAY_MARKER_REPLACE, OVERLAY_MARKER_DELETED, OVERLAY_MARKERS, Format2CompositeFieldError;
+var init_largeDocuments = __esm({
+  "src/utils/largeDocuments.ts"() {
+    "use strict";
+    Y6 = __toESM(require("yjs"), 1);
+    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
+var Y7;
+var init_format2Observer = __esm({
+  "src/models/format2Observer.ts"() {
+    "use strict";
+    Y7 = __toESM(require("yjs"), 1);
+    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
 function generateULID() {
   return (0, import_ulid3.ulid)();
 }
-var Y6, import_ulid3;
+var Y8, import_ulid3;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y6 = __toESM(require("yjs"), 1);
+    Y8 = __toESM(require("yjs"), 1);
     import_ulid3 = require("ulid");
     init_StringSet();
     init_documentTypes();
@@ -618,6 +1131,12 @@ var init_BaseModel = __esm({
     init_writeLifecycle();
     init_yjsValues();
     init_uniqueIndex();
+    init_largeDocuments();
+    init_OrmContext();
+    init_format2QueryProjection();
+    init_format2Observer();
+    init_format2ClientWrite();
+    init_format2OfflineWindow();
     registerFunctionDefault(generateULID, "generate_ulid");
   }
 });
@@ -636,32 +1155,63 @@ var init_ModelRegistry = __esm({
     "use strict";
     init_BaseModel();
     init_relationshipManager();
+    init_format2QueryProjection();
   }
 });
 
 // src/cloudflare-do.ts
 var cloudflare_do_exports = {};
 __export(cloudflare_do_exports, {
+  DEFAULT_OVERLAY_TABLES: () => DEFAULT_OVERLAY_TABLES,
   DurableObjectEngine: () => DurableObjectEngine,
+  Format2CompositeFieldError: () => Format2CompositeFieldError,
   JsonQueryTranslator: () => JsonQueryTranslator,
   JsonSchemaDDL: () => JsonSchemaDDL,
+  OVERLAY_KEY_SEPARATOR: () => OVERLAY_KEY_SEPARATOR,
+  OVERLAY_MARKER_DELETED: () => OVERLAY_MARKER_DELETED,
+  OVERLAY_MARKER_REPLACE: () => OVERLAY_MARKER_REPLACE,
   PROJECTED_JSON_ALIAS_PREFIX: () => PROJECTED_JSON_ALIAS_PREFIX,
+  SnapshotChunkIntegrityError: () => SnapshotChunkIntegrityError,
+  SnapshotRowFormatError: () => SnapshotRowFormatError,
+  applyOverlayMutation: () => applyOverlayMutation,
+  assertNoFormat2CompositeFields: () => assertNoFormat2CompositeFields,
   buildSafeAlias: () => buildSafeAlias,
   checkAutoStampsReservedFields: () => checkAutoStampsReservedFields,
   checkReservedFieldName: () => checkReservedFieldName,
   clearMetaSyncCache: () => clearMetaSyncCache,
+  completeOverlayEntries: () => completeOverlayEntries,
   createDatabaseDO: () => createDatabaseDO,
   createDocumentDO: () => createDocumentDO,
+  decodeOverlaySegment: () => decodeOverlaySegment,
   deterministicIdentifierHash: () => deterministicIdentifierHash,
+  discoverDeclaredModel: () => discoverDeclaredModel,
   discoverModelNames: () => discoverModelNames,
   discoverSchema: () => discoverSchema,
+  encodeOverlayMutation: () => encodeOverlayMutation,
+  encodeOverlaySegment: () => encodeOverlaySegment,
+  encodeSnapshotChunk: () => encodeSnapshotChunk,
+  format2StringSetMembers: () => format2StringSetMembers,
+  groupOverlayEntries: () => groupOverlayEntries,
   handleRequest: () => handleRequest,
   inferFieldType: () => inferFieldType,
+  isFormat2StringSetYMap: () => isFormat2StringSetYMap,
   loadSchemaFromTomlString: () => loadSchemaFromTomlString,
+  materializeOverlayRecord: () => materializeOverlayRecord,
+  overlayFieldKey: () => overlayFieldKey,
+  overlayMarkerKey: () => overlayMarkerKey,
+  overlayMemberKey: () => overlayMemberKey,
+  parseOverlayKey: () => parseOverlayKey,
   parseRecordRow: () => parseRecordRow,
+  projectOverlayEntry: () => projectOverlayEntry,
   projectedJsonAlias: () => projectedJsonAlias,
+  readOverlayRecord: () => readOverlayRecord,
+  readSnapshotChunk: () => readSnapshotChunk,
   registerFunctionDefault: () => registerFunctionDefault,
   schemaToToml: () => schemaToToml,
+  snapshotChunkLines: () => snapshotChunkLines,
+  snapshotDeclaredSchema: () => snapshotDeclaredSchema,
+  snapshotRowAsOverlayEntry: () => snapshotRowAsOverlayEntry,
+  snapshotStringSetFields: () => snapshotStringSetFields,
   syncInferredMeta: () => syncInferredMeta,
   syncModelMeta: () => syncModelMeta
 });
@@ -699,6 +1249,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.");
@@ -2032,8 +2608,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":
@@ -2116,12 +2695,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":
@@ -4454,6 +5044,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()) {
@@ -4932,3 +5528,248 @@ 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;
+}