js-bao 0.7.0-alpha.5 → 0.7.0-alpha.7

package/dist/browser.cjs

@@ -1259,11 +1259,71 @@ var init_yjsValues = __esm({
   }
 });
 
+// src/utils/uniqueIndex.ts
+function buildUniqueKey(recordData, fields) {
+  const keyParts = [];
+  for (const field of fields) {
+    const value = recordData instanceof Y2.Map ? recordData.get(field) : recordData[field];
+    if (value === null || value === void 0) {
+      return null;
+    }
+    keyParts.push(String(value));
+  }
+  return keyParts.join("|");
+}
+function uniqueIndexMapName(modelName, constraintName) {
+  return `_uniqueIdx_${modelName}_${constraintName}`;
+}
+function fieldUniqueConstraintName(modelName, fieldName) {
+  return `${modelName}_${fieldName}_unique`;
+}
+function resolveUniqueConstraints(modelName, fields, customConstraints) {
+  const resolved = [];
+  for (const [fieldName, options] of fields.entries()) {
+    if (options.unique) {
+      resolved.push({
+        name: fieldUniqueConstraintName(modelName, fieldName),
+        fields: [fieldName]
+      });
+    }
+  }
+  if (customConstraints) {
+    for (const constraint of customConstraints) {
+      const missingField = constraint.fields.find(
+        (field) => !fields.has(field)
+      );
+      if (missingField) {
+        console.warn(
+          `[defineModelSchema] Unique constraint "${constraint.name}" for model "${modelName}" references unknown field "${missingField}". Skipping.`
+        );
+        continue;
+      }
+      if (resolved.some((item) => item.name === constraint.name)) {
+        console.warn(
+          `[defineModelSchema] Duplicate unique constraint name "${constraint.name}" in model "${modelName}".`
+        );
+      }
+      resolved.push({
+        name: constraint.name,
+        fields: [...constraint.fields]
+      });
+    }
+  }
+  return resolved;
+}
+var Y2;
+var init_uniqueIndex = __esm({
+  "src/utils/uniqueIndex.ts"() {
+    "use strict";
+    Y2 = __toESM(require("yjs"), 1);
+  }
+});
+
 // src/models/writeLifecycle.ts
 function ensureStringSetYMap(rm, fieldName) {
   const nested = rm.get(fieldName);
-  if (nested instanceof Y2.Map) return nested;
-  const fresh = new Y2.Map();
+  if (nested instanceof Y3.Map) return nested;
+  const fresh = new Y3.Map();
   if (nested && typeof nested === "object") {
     for (const [member, marker] of Object.entries(
       nested
@@ -1301,11 +1361,11 @@ function registerFunctionDefaultGenerator(name, fn) {
 function resolveLiteralOrFunctionDefault(rawDefault) {
   return typeof rawDefault === "function" ? rawDefault() : rawDefault;
 }
-var Y2, import_ulid, KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS, UNKNOWN_FUNCTION_DEFAULT;
+var Y3, import_ulid, KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS, UNKNOWN_FUNCTION_DEFAULT;
 var init_writeLifecycle = __esm({
   "src/models/writeLifecycle.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
     import_ulid = require("ulid");
     KNOWN_FIELD_TYPE_MAP = {
       string: true,
@@ -1362,6 +1422,10 @@ function syncModelMeta(yDoc, modelName, schema) {
     synced = /* @__PURE__ */ new Set();
     _syncedCache.set(yDoc, synced);
   }
+  writeModelMeta(yDoc, modelName, schema);
+  synced.add(modelName);
+}
+function writeModelMeta(yDoc, modelName, schema) {
   const meta = yDoc.getMap(`_meta_${modelName}`);
   for (const [fieldName, fieldOpts] of schema.fields.entries()) {
     syncFieldMeta(meta, fieldName, fieldOpts);
@@ -1372,7 +1436,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) {
@@ -1383,19 +1447,18 @@ 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)) {
       syncRelationshipMeta(rels, relName, relConfig);
     }
   }
-  synced.add(modelName);
 }
 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);
@@ -1412,7 +1475,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");
@@ -1422,7 +1485,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)) {
@@ -1437,7 +1500,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")) {
@@ -1453,44 +1516,19 @@ function setIfChanged(map, key, value) {
     map.set(key, value);
   }
 }
-var Y3, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
+var Y4, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y3 = __toESM(require("yjs"), 1);
+    Y4 = __toESM(require("yjs"), 1);
     init_yjsValues();
+    init_uniqueIndex();
     init_writeLifecycle();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
 });
 
-// src/utils/uniqueIndex.ts
-function buildUniqueKey(recordData, fields) {
-  const keyParts = [];
-  for (const field of fields) {
-    const value = recordData instanceof Y4.Map ? recordData.get(field) : recordData[field];
-    if (value === null || value === void 0) {
-      return null;
-    }
-    keyParts.push(String(value));
-  }
-  return keyParts.join("|");
-}
-function uniqueIndexMapName(modelName, constraintName) {
-  return `_uniqueIdx_${modelName}_${constraintName}`;
-}
-function fieldUniqueConstraintName(modelName, fieldName) {
-  return `${modelName}_${fieldName}_unique`;
-}
-var Y4;
-var init_uniqueIndex = __esm({
-  "src/utils/uniqueIndex.ts"() {
-    "use strict";
-    Y4 = __toESM(require("yjs"), 1);
-  }
-});
-
 // src/utils/largeDocuments.ts
 function encodeOverlaySegment(segment) {
   const escaped = segment.replace(/~/g, "~0").replace(/\//g, "~1");
@@ -1767,15 +1805,344 @@ var init_format2OfflineWindow = __esm({
       overdueMs;
       constructor(documentId, status) {
         super(
-          `Document '${documentId}' has not synced for ${Math.floor((status.windowMs + status.overdueMs) / DAY_MS)} days, past its ${status.windowDays}-day offline write window. It stays readable, and writes are accepted again once it syncs.`
+          `Document '${documentId}' has not synced for ${Math.floor((status.windowMs + status.overdueMs) / DAY_MS)} days, past its ${status.windowDays}-day offline write window. It stays readable, and writes are accepted again once it syncs.`
+        );
+        this.name = "DocumentOfflineWindowError";
+        this.documentId = documentId;
+        this.lastSyncAt = status.lastSyncAt;
+        this.windowDays = status.windowDays;
+        this.overdueMs = status.overdueMs;
+      }
+    };
+  }
+});
+
+// src/utils/snapshotChunks.ts
+function parseSnapshotChunkPath(path) {
+  if (!path || typeof path !== "string") return null;
+  const own = CHUNK_PATH_OWN.exec(path);
+  if (own) return { model: own[1], index: Number(own[2]) };
+  const sourced = CHUNK_PATH_SOURCED.exec(path);
+  if (!sourced) return null;
+  return {
+    model: sourced[3],
+    index: Number(sourced[4]),
+    source: { epoch: Number(sourced[1]), buildId: sourced[2] }
+  };
+}
+function resolveChunkOrdinal(entry, index) {
+  return typeof entry.ordinal === "number" ? entry.ordinal : index;
+}
+function collationRank(unit) {
+  if (unit >= 57344) return unit - 2048;
+  if (unit >= 55296) return unit + 8192;
+  return unit;
+}
+function compareRecordIds(left, right) {
+  if (left === right) return 0;
+  const shared = Math.min(left.length, right.length);
+  for (let index = 0; index < shared; index++) {
+    const a = left.charCodeAt(index);
+    const b = right.charCodeAt(index);
+    if (a === b) continue;
+    return collationRank(a) < collationRank(b) ? -1 : 1;
+  }
+  return left.length < right.length ? -1 : left.length > right.length ? 1 : 0;
+}
+function validateSnapshotManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new SnapshotManifestInvalidError("it is not an object");
+  }
+  const kind = manifest.kind;
+  if (kind !== void 0 && kind !== "snapshot") {
+    throw new SnapshotManifestInvalidError(
+      `it is a ${String(kind)} manifest, not a snapshot manifest`
+    );
+  }
+  const version = manifest.version;
+  if (!Number.isInteger(version)) {
+    throw new SnapshotManifestInvalidError(`version ${String(version)} is not an integer`);
+  }
+  if (version > FORMAT2_MANIFEST_VERSION) {
+    throw new SnapshotManifestUnsupportedError(version);
+  }
+  if (version < FORMAT2_MIN_MANIFEST_VERSION) {
+    throw new SnapshotManifestInvalidError(
+      `version ${version} is older than the large-document format (${FORMAT2_MIN_MANIFEST_VERSION})`
+    );
+  }
+  const chunks = manifest.chunks;
+  if (!Array.isArray(chunks)) {
+    throw new SnapshotManifestInvalidError("its chunk list is not an array");
+  }
+  const seenOrdinals = /* @__PURE__ */ new Set();
+  const lastRangeEndPerModel = /* @__PURE__ */ new Map();
+  let rows = 0;
+  let bytes = 0;
+  for (let index = 0; index < chunks.length; index++) {
+    const entry = chunks[index];
+    const where = `chunk ${index} (${entry?.model ?? "?"})`;
+    if (!entry || typeof entry !== "object") {
+      throw new SnapshotManifestInvalidError(`${where} is not an object`);
+    }
+    if (entry.ordinal !== void 0 && !Number.isSafeInteger(entry.ordinal)) {
+      throw new SnapshotManifestInvalidError(
+        `${where} has ordinal ${String(entry.ordinal)}, which is not an integer`
+      );
+    }
+    const ordinal = resolveChunkOrdinal(entry, index);
+    if (!Number.isSafeInteger(ordinal) || ordinal < 0) {
+      throw new SnapshotManifestInvalidError(
+        `${where} resolves to ordinal ${String(ordinal)}, which is not a non-negative integer`
+      );
+    }
+    if (seenOrdinals.has(ordinal)) {
+      throw new SnapshotManifestInvalidError(
+        `${where} shares ordinal ${ordinal} with an earlier chunk`
+      );
+    }
+    seenOrdinals.add(ordinal);
+    if (entry.path !== void 0 && !parseSnapshotChunkPath(entry.path)) {
+      throw new SnapshotManifestInvalidError(
+        `${where} has a path that is not addressable: ${String(entry.path)}`
+      );
+    }
+    if (entry.rows > 0 && compareRecordIds(entry.firstId, entry.lastId) > 0) {
+      throw new SnapshotManifestInvalidError(
+        `${where} spans ${entry.firstId}..${entry.lastId}, which runs backwards`
+      );
+    }
+    if (entry.rows > 0) {
+      const previousEnd = lastRangeEndPerModel.get(entry.model);
+      if (previousEnd !== void 0 && compareRecordIds(entry.firstId, previousEnd) <= 0) {
+        throw new SnapshotManifestInvalidError(
+          `${where} starts at ${entry.firstId}, at or before ${previousEnd} where the previous chunk of ${entry.model} ended`
+        );
+      }
+      lastRangeEndPerModel.set(entry.model, entry.lastId);
+    }
+    rows += Number(entry.rows) || 0;
+    bytes += Number(entry.bytes) || 0;
+  }
+  const totals = manifest.totals;
+  if (!totals || totals.rows !== rows || totals.bytes !== bytes) {
+    throw new SnapshotManifestInvalidError(
+      `its totals say ${totals?.rows}/${totals?.bytes} rows/bytes but its chunks add up to ${rows}/${bytes}`
+    );
+  }
+  validateIngestInfo(manifest.ingest);
+}
+function validateIngestInfo(ingest) {
+  if (ingest === void 0) return;
+  if (!ingest || typeof ingest !== "object" || Array.isArray(ingest)) {
+    throw new SnapshotManifestInvalidError("its ingest block is not an object");
+  }
+  if (typeof ingest.sessionId !== "string" || ingest.sessionId.length === 0) {
+    throw new SnapshotManifestInvalidError(
+      `its ingest block names session ${String(ingest.sessionId)}`
+    );
+  }
+  if (!Number.isSafeInteger(ingest.epoch) || ingest.epoch <= 0) {
+    throw new SnapshotManifestInvalidError(
+      `its ingest block names epoch ${String(ingest.epoch)}, which is not an epoch`
+    );
+  }
+  if (!Array.isArray(ingest.ranges)) {
+    throw new SnapshotManifestInvalidError(
+      "its ingest block's range list is not an array"
+    );
+  }
+  const lastPerModel = /* @__PURE__ */ new Map();
+  for (let index = 0; index < ingest.ranges.length; index++) {
+    const range = ingest.ranges[index];
+    const where = `ingest range ${index} (${range?.model ?? "?"})`;
+    if (!range || typeof range !== "object") {
+      throw new SnapshotManifestInvalidError(`${where} is not an object`);
+    }
+    if (typeof range.model !== "string" || !MODEL_NAME.test(range.model)) {
+      throw new SnapshotManifestInvalidError(
+        `${where} names ${String(range.model)}, which is not a model name`
+      );
+    }
+    if (typeof range.firstId !== "string" || typeof range.lastId !== "string") {
+      throw new SnapshotManifestInvalidError(`${where} has no id bounds`);
+    }
+    if (compareRecordIds(range.firstId, range.lastId) > 0) {
+      throw new SnapshotManifestInvalidError(
+        `${where} spans ${range.firstId}..${range.lastId}, which runs backwards`
+      );
+    }
+    const previous = lastPerModel.get(range.model);
+    if (previous !== void 0 && compareRecordIds(range.firstId, previous) <= 0) {
+      throw new SnapshotManifestInvalidError(
+        `${where} starts at ${range.firstId}, at or before ${previous} where the previous range of ${range.model} ended`
+      );
+    }
+    lastPerModel.set(range.model, range.lastId);
+  }
+}
+function snapshotStringSetFields(manifest, model) {
+  const declared = manifest.schema?.[model]?.stringSetFields;
+  return new Set(Array.isArray(declared) ? declared.map(String) : []);
+}
+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 };
+}
+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 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}`
+    );
+  }
+  if (entry && rows.length > 0) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      if (seen.has(row._id)) {
+        throw new SnapshotChunkIntegrityError(
+          entry.key,
+          `duplicate id ${row._id}`
+        );
+      }
+      seen.add(row._id);
+    }
+    if (rows[0]._id !== entry.firstId) {
+      throw new SnapshotChunkIntegrityError(
+        entry.key,
+        `expected it to begin at ${entry.firstId}, got ${rows[0]._id}`
+      );
+    }
+    if (rows[rows.length - 1]._id !== entry.lastId) {
+      throw new SnapshotChunkIntegrityError(
+        entry.key,
+        `expected it to end at ${entry.lastId}, got ${rows[rows.length - 1]._id}`
+      );
+    }
+  }
+  return rows;
+}
+var FORMAT2_MANIFEST_VERSION, FORMAT2_MIN_MANIFEST_VERSION, INGEST_CHUNK_LIMITS, SnapshotChunkIntegrityError, SnapshotManifestInvalidError, SnapshotManifestUnsupportedError, CHUNK_PATH_OWN, CHUNK_PATH_SOURCED, MODEL_NAME, encoder, decoder, SNAPSHOT_ENCODE_SEGMENT_BYTES;
+var init_snapshotChunks = __esm({
+  "src/utils/snapshotChunks.ts"() {
+    "use strict";
+    FORMAT2_MANIFEST_VERSION = 3;
+    FORMAT2_MIN_MANIFEST_VERSION = 2;
+    INGEST_CHUNK_LIMITS = {
+      /** Stored (compressed) bytes of one chunk. */
+      maxChunkBytes: 8 * 1024 * 1024,
+      /** Decompressed bytes of one chunk — the bound the reader stops at. */
+      maxChunkRawBytes: 16 * 1024 * 1024,
+      /** Lines in one chunk. */
+      maxChunkRows: 5e4,
+      /** Chunks in one session. */
+      maxChunks: 4096,
+      /** Stored bytes across the whole session. */
+      maxTotalBytes: 2 * 1024 * 1024 * 1024
+    };
+    SnapshotChunkIntegrityError = class extends Error {
+      constructor(key, reason) {
+        super(`Snapshot chunk ${key} does not match its manifest entry: ${reason}`);
+        this.key = key;
+        this.reason = reason;
+        this.name = "SnapshotChunkIntegrityError";
+      }
+    };
+    SnapshotManifestInvalidError = class extends Error {
+      code = "SNAPSHOT_MANIFEST_INVALID";
+      constructor(reason) {
+        super(`Snapshot manifest is not valid: ${reason}`);
+        this.name = "SnapshotManifestInvalidError";
+      }
+    };
+    SnapshotManifestUnsupportedError = class extends Error {
+      constructor(manifestVersion, supportedVersion = FORMAT2_MANIFEST_VERSION) {
+        super(
+          `Snapshot manifest is version ${manifestVersion}; this client reads up to version ${supportedVersion}. Upgrade the client library.`
         );
-        this.name = "DocumentOfflineWindowError";
-        this.documentId = documentId;
-        this.lastSyncAt = status.lastSyncAt;
-        this.windowDays = status.windowDays;
-        this.overdueMs = status.overdueMs;
+        this.manifestVersion = manifestVersion;
+        this.supportedVersion = supportedVersion;
+        this.name = "SnapshotManifestUnsupportedError";
       }
+      code = "SNAPSHOT_MANIFEST_UNSUPPORTED";
     };
+    CHUNK_PATH_OWN = /^([A-Za-z][A-Za-z0-9_]*)\/(\d+)$/;
+    CHUNK_PATH_SOURCED = /^(\d+)-([A-Za-z0-9_-]{1,64})\/([A-Za-z][A-Za-z0-9_]*)\/(\d+)$/;
+    MODEL_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+    encoder = new TextEncoder();
+    decoder = new TextDecoder();
+    SNAPSHOT_ENCODE_SEGMENT_BYTES = 64 * 1024;
   }
 });
 
@@ -1918,6 +2285,28 @@ function format2ClientDDL(docId) {
   build_id TEXT NOT NULL,
   ordinal INTEGER NOT NULL,
   PRIMARY KEY (doc_id, build_id, ordinal)
+)`,
+    // #3435 — which base this merged view is on, and whether its load ever
+    // FINISHED. The second half is what makes a partial replacement safe: a
+    // convergence may keep a chunk by marking it rather than fetching it only
+    // when the rows it is keeping are a complete baseline. A client that is
+    // cold, or whose last load was interrupted, has no such guarantee and
+    // takes the full plan (finding 3435-R04).
+    `CREATE TABLE IF NOT EXISTS _snapshot_base (
+  doc_id TEXT PRIMARY KEY,
+  build_id TEXT NOT NULL,
+  epoch INTEGER NOT NULL,
+  complete INTEGER NOT NULL DEFAULT 0
+)`,
+    // #3435 — every bulk-load epoch this document crossed and has not yet
+    // converged past. Durable, because a connected client that followed a
+    // flagged seal onto E+1 has an epoch mark that reads perfectly current:
+    // if the debt lived only in memory, a restart would clear it and the
+    // client would serve rows the server replaced, for good.
+    `CREATE TABLE IF NOT EXISTS _discontinuities (
+  doc_id TEXT NOT NULL,
+  epoch INTEGER NOT NULL,
+  PRIMARY KEY (doc_id, epoch)
 )`
   ];
 }
@@ -2752,6 +3141,185 @@ var init_format2RecordStore = __esm({
           ordinal
         );
       }
+      // ── The base this view is on, and the bulk loads it owes (#3435) ───
+      /**
+       * Which base the merged view is on, and which bulk-load epochs it has
+       * crossed and not yet converged past.
+       *
+       * One read, because the two are one decision: a convergence may keep a
+       * chunk by marking it only when the base it is keeping rows from is
+       * complete AND exactly one discontinuity stands between it and the
+       * announced base.
+       */
+      baseState() {
+        const rows = this.rows(
+          "SELECT build_id, epoch, complete FROM _snapshot_base WHERE doc_id = ?",
+          this.docId
+        );
+        return {
+          base: rows.length > 0 ? {
+            buildId: String(rows[0].build_id),
+            epoch: Number(rows[0].epoch),
+            complete: Boolean(Number(rows[0].complete))
+          } : null,
+          discontinuities: this.discontinuityEpochs()
+        };
+      }
+      /** Every unconverged bulk-load epoch, ascending. */
+      discontinuityEpochs() {
+        return this.rows(
+          "SELECT epoch FROM _discontinuities WHERE doc_id = ? ORDER BY epoch",
+          this.docId
+        ).map((row) => Number(row.epoch));
+      }
+      /**
+       * Start loading `buildId` as this view's base.
+       *
+       * The load marks of OTHER builds go in the same transaction. They are
+       * progress on a load nothing will ever finish, and a device that later came
+       * back to that build would skip chunks whose rows this base has replaced.
+       * One transaction because the row and the marks describe one thing: what
+       * this view is being made into.
+       */
+      beginBase(buildId, epoch) {
+        this.sql.transaction(() => {
+          this.sql.exec(
+            `INSERT INTO _snapshot_base (doc_id, build_id, epoch, complete)
+           VALUES (?, ?, ?, 0)
+         ON CONFLICT(doc_id) DO UPDATE SET build_id = ?, epoch = ?, complete = 0`,
+            this.docId,
+            buildId,
+            epoch,
+            buildId,
+            epoch
+          );
+          this.sql.exec(
+            "DELETE FROM _snapshot_load WHERE doc_id = ? AND build_id <> ?",
+            this.docId,
+            buildId
+          );
+        });
+      }
+      /** The load of `buildId` finished: this view is a complete baseline. */
+      completeBase(buildId) {
+        this.sql.exec(
+          "UPDATE _snapshot_base SET complete = 1 WHERE doc_id = ? AND build_id = ?",
+          this.docId,
+          buildId
+        );
+      }
+      /** Record a bulk-load epoch this document crossed. Idempotent. */
+      noteDiscontinuity(epoch) {
+        this.sql.exec(
+          "INSERT OR IGNORE INTO _discontinuities (doc_id, epoch) VALUES (?, ?)",
+          this.docId,
+          epoch
+        );
+      }
+      /** Forget every crossed epoch at or below `through`: converged past them. */
+      clearDiscontinuities(through) {
+        this.sql.exec(
+          "DELETE FROM _discontinuities WHERE doc_id = ? AND epoch <= ?",
+          this.docId,
+          through
+        );
+      }
+      /**
+       * Replace one chunk's COVERAGE with its rows, in one commit (#3435,
+       * behavior 11; finding 3435-R01).
+       *
+       * The atomic range replacement the design doc requires, and the reason it
+       * is one store method rather than a delete followed by {@link applyChunk}.
+       * Two tabs share this database and each run their own loader over the same
+       * plan. With the delete committed apart from the insert, this interleaving
+       * loses the chunk permanently: the first holder deletes, inserts and marks;
+       * the second then deletes the same coverage and its `applyChunk` skips the
+       * insert because the chunk is already marked. The rows are gone under a mark
+       * that says they landed, and nothing ever fetches them again.
+       *
+       * So the mark check, the coverage delete, the insert and the mark are one
+       * transaction, and a chunk another holder already landed changes nothing.
+       *
+       * The bounds are `(after, through]`, a null bound open, compared by the
+       * TABLE's collation. That is SQLite's `BINARY` — UTF-8 byte order — which is
+       * what `compareRecordIds` models and what the manifest's ranges were cut in.
+       * A JavaScript `<` would disagree with both wherever an id mixes a
+       * three-byte character with a supplementary one.
+       */
+      replaceChunk(modelName, coverage, entries, buildId, ordinal) {
+        let applied = 0;
+        let removed = 0;
+        let skipped = false;
+        this.sql.transaction(() => {
+          if (this.chunkIsComplete(buildId, ordinal)) {
+            skipped = true;
+            return;
+          }
+          if (!this.isHydrated(modelName)) {
+            return;
+          }
+          removed = this.deleteCoverage(modelName, coverage);
+          for (const entry of entries) {
+            projectOverlayEntry(this.sql, modelName, entry, this.tables);
+            applied++;
+          }
+          this.markChunkComplete(buildId, ordinal);
+        });
+        return { applied, removed, skipped };
+      }
+      /**
+       * Delete up to `limit` rows of one model's range, and say whether that was
+       * the last of them (#3435, behavior 11a).
+       *
+       * Paged because pruning a whole model of a multi-hundred-megabyte document
+       * in one statement is the invocation-length failure the rest of this design
+       * avoids; idempotent between two holders because it only ever deletes what
+       * is there. Used for a whole-model prune — a model the new base does not
+       * carry at all — and nothing else: a chunk's range is replaced by
+       * {@link replaceChunk}, atomically, for the reason above.
+       */
+      deleteRange(modelName, after, through, limit) {
+        if (!this.isHydrated(modelName)) return { removed: 0, done: true };
+        let removed = 0;
+        this.sql.transaction(() => {
+          removed = this.deleteCoverage(modelName, { after, through }, limit);
+        });
+        return { removed, done: removed < limit };
+      }
+      /**
+       * Delete a model's rows over `(after, through]` and their stringset
+       * members, up to `limit` rows. Callers hold the transaction.
+       */
+      deleteCoverage(modelName, coverage, limit) {
+        const bounds = [];
+        const bindings = [modelName];
+        if (coverage.after !== null) {
+          bounds.push("_id > ?");
+          bindings.push(coverage.after);
+        }
+        if (coverage.through !== null) {
+          bounds.push("_id <= ?");
+          bindings.push(coverage.through);
+        }
+        const where = ["_type = ?", ...bounds].join(" AND ");
+        const doomed = this.rows(
+          `SELECT _id FROM ${this.tables.records} WHERE ${where} ORDER BY _id` + (limit === void 0 ? "" : " LIMIT ?"),
+          ...limit === void 0 ? bindings : [...bindings, limit]
+        ).map((row) => String(row._id));
+        for (const id of doomed) {
+          this.sql.exec(
+            `DELETE FROM ${this.tables.stringSetIndex} WHERE _type = ? AND _record_id = ?`,
+            modelName,
+            id
+          );
+          this.sql.exec(
+            `DELETE FROM ${this.tables.records} WHERE _type = ? AND _id = ?`,
+            modelName,
+            id
+          );
+        }
+        return doomed.length;
+      }
       /**
        * Throw away a merged view that cannot be repaired (#2816, behavior 12).
        *
@@ -2773,6 +3341,7 @@ var init_format2RecordStore = __esm({
           this.sql.exec(`DELETE FROM ${this.tables.records}`);
           this.sql.exec(`DELETE FROM ${this.tables.stringSetIndex}`);
           this.sql.exec("DELETE FROM _snapshot_load WHERE doc_id = ?", this.docId);
+          this.sql.exec("DELETE FROM _snapshot_base WHERE doc_id = ?", this.docId);
         });
       }
       // ── helpers ───────────────────────────────────────────────────────
@@ -3008,6 +3577,7 @@ var init_format2RecordStoreAsync = __esm({
     init_BaseModel();
     init_documentTypes();
     init_format2OfflineWindow();
+    init_snapshotChunks();
     init_format2RecordStore();
     init_format2RowCache();
     init_format2Observer();
@@ -3346,6 +3916,23 @@ var init_format2RecordStoreAsync = __esm({
         const store = this.direct();
         return store ? store.hydrationScope() : this.mirrored().hydrationScope;
       }
+      /**
+       * The bulk-load epochs this document crossed and has not converged past
+       * (#3435), ascending.
+       *
+       * Synchronous because the transport asks it at the bind, in the same breath
+       * as the epoch mark, to decide whether the handshake it is holding means a
+       * catch-up or a convergence.
+       */
+      discontinuityEpochs() {
+        const store = this.direct();
+        return store ? store.discontinuityEpochs() : [...this.mirrored().discontinuityEpochs];
+      }
+      /** Whether the base this view is on finished loading (#3435). */
+      baseComplete() {
+        const store = this.direct();
+        return store ? store.baseState().base?.complete ?? false : this.mirrored().baseComplete;
+      }
       isHydrated(model) {
         const scope = this.hydrationScope();
         return scope === null || scope.includes(model);
@@ -3566,6 +4153,122 @@ var init_format2RecordStoreAsync = __esm({
       completedChunks(buildId) {
         return this.host.dispatch({ kind: "completedChunks", buildId });
       }
+      /**
+       * Replace one chunk's coverage with its rows, atomically (#3435).
+       *
+       * The live cache entries the write could have moved are re-read afterwards:
+       * the command DELETES a range as well as inserting, so an entry inside that
+       * range may name a record that no longer exists, and the ids it removed do
+       * not cross the boundary.
+       *
+       * The range is the bound, not the whole cache. A convergence replaces named
+       * ranges of named models precisely so that everything else keeps its rows —
+       * including the chunks it kept, which are the saving the design exists for —
+       * and a blanket invalidation would tell every live instance of every model
+       * that its record is gone, with `loaded` set so nothing reads it back
+       * (finding 3435-C03).
+       */
+      async replaceChunk(model, coverage, entries, buildId, ordinal) {
+        const reply = await this.run(
+          "replaceChunk",
+          () => this.host.dispatch({
+            kind: "replaceChunk",
+            model,
+            coverage,
+            entries: [...entries],
+            buildId,
+            ordinal
+          })
+        );
+        if (!reply.skipped) {
+          await this.refreshRange(
+            model,
+            coverage,
+            entries.map((entry) => entry.id)
+          );
+        }
+        return reply;
+      }
+      /** One page of a whole-model prune (#3435). */
+      async deleteRange(model, after, through, limit) {
+        const reply = await this.run(
+          "deleteRange",
+          () => this.host.dispatch({ kind: "deleteRange", model, after, through, limit })
+        );
+        if (reply.removed > 0) {
+          await this.refreshRange(model, { after, through }, []);
+        }
+        return reply;
+      }
+      /**
+       * Re-read the live entries a range write could have moved (#3435).
+       *
+       * One model, one range, plus whatever the write inserted — a record outside
+       * both is exactly what the plan kept, and its instances go on answering. The
+       * bound is `compareRecordIds`, the collation the store deleted the range
+       * under, so the two agree about which ids the write covered.
+       */
+      async refreshRange(model, coverage, written) {
+        const covered = (id) => (coverage.after === null || compareRecordIds(id, coverage.after) > 0) && (coverage.through === null || compareRecordIds(id, coverage.through) <= 0);
+        const ids = new Set(this.cache.liveIds(model).filter(covered));
+        for (const id of written) {
+          if (this.cache.peek(model, id)) ids.add(id);
+        }
+        if (ids.size === 0) return;
+        await this.refreshRows(model, [...ids]);
+      }
+      /** Which base this view is on, and which bulk loads it owes (#3435). */
+      baseState() {
+        return this.host.dispatch({ kind: "baseState" });
+      }
+      async beginBase(buildId, epoch) {
+        await this.run(
+          "beginBase",
+          () => this.host.dispatch({ kind: "beginBase", buildId, epoch })
+        );
+        this.refreshMirror({ baseComplete: false });
+      }
+      async completeBase(buildId) {
+        await this.run(
+          "completeBase",
+          () => this.host.dispatch({ kind: "completeBase", buildId })
+        );
+        this.refreshMirror({ baseComplete: true });
+      }
+      async noteDiscontinuity(epoch) {
+        await this.run(
+          "noteDiscontinuity",
+          () => this.host.dispatch({ kind: "noteDiscontinuity", epoch })
+        );
+        const held = this.mirror?.discontinuityEpochs;
+        if (held && !held.includes(epoch)) {
+          this.refreshMirror({
+            discontinuityEpochs: [...held, epoch].sort((a, b) => a - b)
+          });
+        }
+      }
+      async clearDiscontinuities(through) {
+        await this.run(
+          "clearDiscontinuities",
+          () => this.host.dispatch({ kind: "clearDiscontinuities", through })
+        );
+        const held = this.mirror?.discontinuityEpochs;
+        if (held) {
+          this.refreshMirror({
+            discontinuityEpochs: held.filter((epoch) => epoch > through)
+          });
+        }
+      }
+      /**
+       * Keep the synchronous mirror in step with a durable change.
+       *
+       * A no-op where the store runs in this thread: there the store IS the
+       * mirror, and a copy would go stale the moment anything wrote through it.
+       */
+      refreshMirror(patch) {
+        if (!this.mirror) return;
+        this.mirror = { ...this.mirror, ...patch };
+      }
       async discardMergedView() {
         await this.run(
           "discardMergedView",
@@ -4029,7 +4732,11 @@ function readFormat2StoreMarks(store) {
     clockOffset: store.clockOffset(),
     clockOffsetKnown: store.clockOffsetKnown(),
     hydrationScope: store.hydrationScope(),
-    pendingOps: store.pendingOps()
+    pendingOps: store.pendingOps(),
+    // #3435 — the two facts a document that crossed a bulk load has to know
+    // at bind, before it decides what the handshake means.
+    discontinuityEpochs: store.discontinuityEpochs(),
+    baseComplete: store.baseState().base?.complete ?? false
   };
 }
 function dispatchFormat2StoreCommand(store, sql, command) {
@@ -4112,6 +4819,31 @@ function run(store, sql, command) {
       };
     case "completedChunks":
       return store.completedChunks(command.buildId);
+    case "replaceChunk":
+      return store.replaceChunk(
+        command.model,
+        command.coverage,
+        command.entries,
+        command.buildId,
+        command.ordinal
+      );
+    case "deleteRange":
+      return store.deleteRange(
+        command.model,
+        command.after,
+        command.through,
+        command.limit
+      );
+    case "baseState":
+      return store.baseState();
+    case "beginBase":
+      return store.beginBase(command.buildId, command.epoch);
+    case "completeBase":
+      return store.completeBase(command.buildId);
+    case "noteDiscontinuity":
+      return store.noteDiscontinuity(command.epoch);
+    case "clearDiscontinuities":
+      return store.clearDiscontinuities(command.through);
     case "foreignClients":
       return store.foreignClientIds();
     case "adoptPendingOps":
@@ -4493,6 +5225,19 @@ var init_OrmContext = __esm({
       format2Documents = /* @__PURE__ */ new Map();
       /** Format-2 epoch moves in flight (#2816). */
       format2Transitions = /* @__PURE__ */ new Map();
+      /**
+       * This instance's document observers' database writes that have not finished
+       * yet, by document id (#3023).
+       *
+       * A Yjs observer fires synchronously with the update but writes to the
+       * database asynchronously, so an update that has been APPLIED to a document
+       * is not yet QUERYABLE. Whoever needs the difference — an `open()` that
+       * promises its caller the synced records — waits on
+       * {@link whenDocumentIndexed}. Per instance, not process-wide: two clients
+       * holding the same document id write to their own engines, and neither
+       * should be held up by the other's writes.
+       */
+      documentIndexingWork = /* @__PURE__ */ new Map();
       /**
        * Who this ORM instance is in a format-2 store's unacknowledged-write log
        * (#3431).
@@ -4670,6 +5415,56 @@ var init_OrmContext = __esm({
           release();
         }
       }
+      /**
+       * Record one observer's asynchronous write of `docId` (#3023), so a caller
+       * that needs the document queryable can wait for it. Failures are the
+       * observer's own to log; a tracked promise never rejects, because the point
+       * of the barrier is only to know when the write is over.
+       *
+       * A destroyed context tracks nothing: its observers are already inert, and a
+       * torn-down instance must not leave a barrier that never drains.
+       */
+      trackDocumentIndexing(docId, work) {
+        if (this.destroyed) return;
+        let inFlight = this.documentIndexingWork.get(docId);
+        if (!inFlight) {
+          inFlight = /* @__PURE__ */ new Set();
+          this.documentIndexingWork.set(docId, inFlight);
+        }
+        const pending = work.catch(() => {
+        }).then(() => {
+          inFlight.delete(pending);
+          if (inFlight.size === 0 && this.documentIndexingWork.get(docId) === inFlight) {
+            this.documentIndexingWork.delete(docId);
+          }
+        });
+        inFlight.add(pending);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this instance's query
+       * tables (#3023). Answers `true` when the work drained, `false` when it gave
+       * up waiting — the caller owns the logging, because this module holds no
+       * runtime imports.
+       *
+       * An update applied to the Y.Doc is visible to a reader of the document
+       * immediately, but the query tables only catch up when the observers' writes
+       * land. An `open()` that waited for the initial sync waits for this too —
+       * otherwise it resolves on the sync signal and the caller's first `query()`
+       * sees a partly-written table.
+       *
+       * A write can enqueue more work (a nested map observed as it arrives), so
+       * this drains in passes rather than once, and gives up after enough of them
+       * that only a document under continuous change could still be busy — a
+       * barrier is not a reason to hang.
+       */
+      async whenDocumentIndexed(docId) {
+        for (let pass = 0; pass < 50; pass++) {
+          const inFlight = this.documentIndexingWork.get(docId);
+          if (!inFlight || inFlight.size === 0) return true;
+          await Promise.all([...inFlight]);
+        }
+        return false;
+      }
       /** Notify `subscribe()` callbacks registered on this context for `modelName`. */
       notifyListeners(modelName, log, onError) {
         const listeners = this.listenersMap.get(modelName);
@@ -4795,6 +5590,7 @@ var init_OrmContext = __esm({
         this.modelDocMappingChangedListeners.clear();
         this.format2Documents.clear();
         this.format2Transitions.clear();
+        this.documentIndexingWork.clear();
         this.observedStringSetMaps = /* @__PURE__ */ new WeakSet();
         liveOrmContexts.delete(this);
         if (defaultOrmContext === this) {
@@ -5165,6 +5961,10 @@ var init_ModelRegistry = __esm({
        * undefined the legacy session semantics are kept exactly: the global
        * registry is SNAPSHOT at init time, so a model registered afterwards is not
        * silently adopted by an already-running instance.
+       *
+       * The one way a running instance's registry grows is {@link adoptModel},
+       * behind `registerModel` on the init result (#3615): an EXPLICIT call on the
+       * instance the app means, not a relaxation of the snapshot rule.
        */
       static createInstanceRegistry(modelClasses) {
         const registry = new _ModelRegistry();
@@ -5188,6 +5988,64 @@ var init_ModelRegistry = __esm({
         registry.setExplicitModelsForSession(modelClasses);
         return registry;
       }
+      /**
+       * The name `modelClass` may be adopted under on THIS instance, or a refusal
+       * that names what to change (#3615).
+       *
+       * Both checks are made before anything is mutated, so a registration that
+       * cannot go through leaves the registry exactly as it was.
+       */
+      assertAdoptable(modelClass, instanceId) {
+        const schema = modelClass?.getSchema?.();
+        const modelName = modelClass?.modelName ?? schema?.options?.name;
+        if (!modelName || !schema?.options?.name || !schema?.resolvedUniqueConstraints) {
+          throw new Error(
+            `[initJsBao] Cannot register a model class with no name. Build it with defineModelSchema and attachAndRegisterModel (or createModelClass) so it carries a static modelName and a schema with resolvedUniqueConstraints.`
+          );
+        }
+        const existing = this.models.get(modelName);
+        if (existing && existing !== modelClass) {
+          throw new Error(
+            `[initJsBao] Model '${modelName}' is already registered on js-bao instance #${instanceId} with a different class. Register the existing class, or give the new model a different name.`
+          );
+        }
+        return modelName;
+      }
+      /**
+       * Adopt `modelClass` into THIS instance's registry at runtime (#3615).
+       *
+       * The counterpart to the snapshot rule on
+       * {@link ModelRegistry.createInstanceRegistry}: an instance grows only where
+       * the app says so, and the global singleton is deliberately not touched —
+       * registering here makes the model visible to this instance and to no other.
+       *
+       * Returns `{ added: false }` when the very same class is already ACTIVE on
+       * this instance, which is what makes a repeat `registerModel` a no-op rather
+       * than a warning about overwriting. Active, not merely present: an instance
+       * built with `models: []` carries the whole global registry in `models` with
+       * nothing active, and a class only the backing snapshot holds has neither
+       * been validated for this session nor bound to its context, so it still has
+       * an adoption to go through.
+       */
+      adoptModel(modelClass, options = {}) {
+        const modelName = this.assertAdoptable(modelClass, options.instanceId);
+        if (this.getActiveModels().get(modelName) === modelClass) {
+          return { added: false };
+        }
+        const candidate = new Map(this.getActiveModels());
+        candidate.set(modelName, modelClass);
+        this.validateModels(candidate);
+        const schema = modelClass.getSchema?.();
+        this.models.set(modelName, modelClass);
+        if (schema?.options) this.modelOptions.set(modelName, schema.options);
+        if (this.activeSessionModels) {
+          this.activeSessionModels.set(modelName, modelClass);
+        }
+        Logger.debug(
+          `[ModelRegistry] Model "${modelName}" adopted by instance #${options.instanceId} at runtime.`
+        );
+        return { added: true };
+      }
       registerModel(modelClass, options, fields) {
         if (!options.name) {
           throw new Error(
@@ -5390,7 +6248,8 @@ var init_ModelRegistry = __esm({
         Logger.debug(`[ModelRegistry] Data removal complete for document ${docId}`);
       }
       // New method to initialize relationships
-      async initializeRelationships() {
+      async initializeRelationships(fallbackDbEngine) {
+        if (!this.dbEngine && fallbackDbEngine) this.dbEngine = fallbackDbEngine;
         if (!this.dbEngine) {
           console.error(
             "[ModelRegistry] DB engine not available for initializing relationships. Ensure initializeAll has been called."
@@ -5542,7 +6401,16 @@ var init_ModelRegistry = __esm({
         return this.activeSessionModels || this.models;
       }
       validateSessionModels() {
-        const activeModels = this.getActiveModels();
+        this.validateModels(this.getActiveModels());
+      }
+      /**
+       * Every relationship of `activeModels` names a model that is also in it.
+       *
+       * Taken as an argument rather than read off the registry so a runtime
+       * adoption can be validated against what the instance WOULD hold before it
+       * holds it (#3615).
+       */
+      validateModels(activeModels) {
         if (!activeModels || activeModels.size === 0) {
           return;
         }
@@ -5994,6 +6862,14 @@ var init_IncludeResolver = __esm({
 function generateULID() {
   return (0, import_ulid2.ulid)();
 }
+function reindexFailure(modelConstructor, modelName, recordId, docId, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const failure = new Error(
+    `[${modelConstructor.name}] Error re-indexing ${modelName}/${recordId} of document ${docId}: ${message}`
+  );
+  failure.cause = error;
+  return failure;
+}
 var Y7, import_ulid2, FORMAT2_ROW_PAGE, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
@@ -6866,19 +7742,31 @@ var init_BaseModel = __esm({
         if (fieldOptions?.default === void 0) return void 0;
         return typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
       }
-      getStringSetFromYjs(fieldName) {
-        const yjsData = this.getFromYjs(fieldName);
-        if (yjsData instanceof Y7.Map) {
-          return Array.from(yjsData.keys());
+      /**
+       * The members of a stringset as it is STORED, in stored order.
+       *
+       * Static and value-only so that the two readers of a stored stringset — the
+       * instance's `getStringSetFromYjs`, which feeds the value a save builds its
+       * unique key from, and `_readableUniqueOwner`, which rebuilds another
+       * record's key from the map — cannot drift apart (#3252).
+       */
+      static _stringSetMembersFromStored(stored) {
+        if (stored instanceof Y7.Map) {
+          return Array.from(stored.keys());
         }
-        if (Array.isArray(yjsData)) {
-          return yjsData.filter((member) => typeof member === "string");
+        if (Array.isArray(stored)) {
+          return stored.filter((member) => typeof member === "string");
         }
-        if (yjsData && typeof yjsData === "object") {
-          return Object.keys(yjsData).filter((k) => Boolean(yjsData[k]));
+        if (stored && typeof stored === "object") {
+          return Object.keys(stored).filter((k) => Boolean(stored[k]));
         }
         return [];
       }
+      getStringSetFromYjs(fieldName) {
+        return this.constructor._stringSetMembersFromStored(
+          this.getFromYjs(fieldName)
+        );
+      }
       getOrCreateStringSet(fieldName) {
         if (!this._stringSetFields.has(fieldName)) {
           const initialValues = this.getStringSetFromYjs(fieldName);
@@ -6907,6 +7795,30 @@ var init_BaseModel = __esm({
           `[${this.name}] initialize(yDoc, db) is no longer supported. Use initializeForDocument(yDoc, db, docId, permission)`
         );
       }
+      /**
+       * Record one observer's asynchronous write of `docId` on this class's ORM
+       * instance (#3023), so a caller that needs the document queryable can wait
+       * for it. The observers themselves track through the context they captured
+       * at install time; this static is for callers that only hold a model class.
+       */
+      static trackDocumentIndexing(docId, work) {
+        resolveOrmContext(this).trackDocumentIndexing(docId, work);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this class's instance
+       * of the query tables (#3023). See
+       * {@link OrmContext.whenDocumentIndexed} — an `open()` that waited for the
+       * initial sync waits for this too, otherwise it resolves on the sync signal
+       * and the caller's first `query()` sees a partly-written table.
+       */
+      static async whenDocumentIndexed(docId) {
+        const drained = await resolveOrmContext(this).whenDocumentIndexed(docId);
+        if (!drained) {
+          Logger.warn(
+            `[BaseModel] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+          );
+        }
+      }
       /**
        * Initialize this model for a connected document.
        *
@@ -7253,7 +8165,7 @@ var init_BaseModel = __esm({
           return recordIdsToDiscard;
         };
         const observerContext = resolveOrmContext(this);
-        const documentYMapObserver = async (event) => {
+        const indexDocumentYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${this.name}] Document YMap change detected for ${modelName}/${docId}:`,
@@ -7422,6 +8334,12 @@ var init_BaseModel = __esm({
           );
           observerContext.notifyListeners(modelName);
         };
+        const documentYMapObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexDocumentYMapChange(event)
+          );
+        };
         documentYMap.observe(documentYMapObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -7447,6 +8365,116 @@ var init_BaseModel = __esm({
           `[${this.name}] Model ${modelName} initialization complete for document ${docId}.`
         );
       }
+      /**
+       * Re-index ONE record of a document from its current Y.Map state (#3615).
+       *
+       * A legacy document's initial load walks the Y.Map before the permanent
+       * observers are installed, so an update that lands in that window reaches
+       * Yjs and misses the query tables. For a document connected long ago — which
+       * is exactly what a model registered at runtime is initialized against —
+       * that window is open on a live document. `registerModel` collects the
+       * record ids touched while it runs and brings each of them here afterwards,
+       * writing the same row the permanent per-record observer would have written.
+       *
+       * A record the window DELETED is deleted here for the same reason.
+       *
+       * A storage failure REJECTS rather than being logged and passed over, the
+       * way the permanent observers' writes are: this write is part of what a
+       * registration promises before it resolves, so swallowing it would resolve a
+       * registration whose query tables are missing the very updates this call
+       * exists to catch, and mark the pair complete so no retry would repair it.
+       */
+      static async reindexDocumentRecord(docId, recordId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed) return;
+        const documentYMap = modelConstructor.documentYMaps.get(
+          `${docId}_${modelName}`
+        );
+        if (!documentYMap) return;
+        const engine = ctx.dbEngine ? await modelConstructor.queryEngineFor([docId], modelName) : null;
+        if (!engine) return;
+        const recordData = documentYMap.get(recordId);
+        if (recordData === void 0 || recordData === null) {
+          try {
+            await engine.delete(modelName, recordId);
+          } catch (error) {
+            throw reindexFailure(
+              modelConstructor,
+              modelName,
+              recordId,
+              docId,
+              error
+            );
+          }
+          ctx.notifyListeners(modelName);
+          return;
+        }
+        const entries = recordData instanceof Y7.Map ? Array.from(recordData.entries()) : Object.entries(recordData);
+        const rowData = {};
+        for (const [fieldKey, value] of entries) {
+          const fieldOptions = schema.fields?.get(fieldKey);
+          if (!fieldOptions || fieldOptions.type === "stringset") continue;
+          if (value === void 0) continue;
+          rowData[fieldKey] = isYjsComposite(value) ? normalizeYjsValueForStorage(value) : value;
+        }
+        if (!rowData.id) return;
+        const permissionHint = modelConstructor.connectedDocuments.get(docId)?.permissionHint ?? "read-write";
+        try {
+          await engine.insert(modelName, {
+            ...rowData,
+            type: modelName,
+            _meta_doc_id: docId,
+            _meta_permission_hint: permissionHint
+          });
+        } catch (error) {
+          throw reindexFailure(
+            modelConstructor,
+            modelName,
+            recordId,
+            docId,
+            error
+          );
+        }
+        ctx.notifyListeners(modelName);
+      }
+      /**
+       * Withdraw ONE document's registration of this model (#3615).
+       *
+       * A `registerModel` that fails part-way through a document keeps the class
+       * registered, because retrying is the recovery. This is what keeps that
+       * half-finished pair from LOOKING finished in the meantime: without the
+       * Y.Map mapping a save raises the same `YMap not found` an unregistered
+       * model raises, instead of writing into a document whose observers were
+       * never installed, and clearing the rows the failed load managed to write
+       * keeps a query from answering out of a document nothing is watching. The
+       * retry's `initializeForDocument` publishes both again.
+       *
+       * `connectedDocuments` is deliberately left alone: it is the CONTEXT's map,
+       * shared by every model on the instance, so the document itself is still
+       * connected for everything else.
+       */
+      static async withdrawDocumentRegistration(docId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        modelConstructor.documentYMaps.delete(`${docId}_${modelName}`);
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed || !ctx.dbEngine) return;
+        try {
+          const engine = await modelConstructor.queryEngineFor([docId], modelName);
+          await engine.deleteByDocumentId(modelName, docId);
+        } catch (error) {
+          Logger.warn(
+            `[${modelConstructor.name}] Could not clear ${modelName} rows of document ${docId} while withdrawing an incomplete registration:`,
+            error
+          );
+        }
+      }
       // New method to clean up data for a disconnected document
       static async cleanupDocumentData(docId) {
         const modelConstructor = this;
@@ -7702,8 +8730,50 @@ var init_BaseModel = __esm({
           fields,
           values,
           modelName,
-          constraintName
+          constraintName
+        );
+      }
+      /**
+       * The record that READABLY owns `uniqueKey` under `constraint` in one
+       * document's model map, or `null`.
+       *
+       * The `_uniqueIdx_` map is a cache over the records, not the record store,
+       * and the two can disagree (#3252): a replica can hold an index entry for a
+       * record whose structs have not landed yet, or an entry a field change or
+       * delete left behind. `save()` used to take the entry at its word, so the
+       * app saw a `query` that returned no row for a value and a save refused for
+       * that same value — the index knew a row nothing else could read.
+       *
+       * An entry counts only when its owner is readable: the record map exists
+       * under that id in `modelYMap`, and the key built from the record's stored
+       * fields is `uniqueKey`. Anything else is a stale entry, and the caller
+       * treats it as an index miss — the engine fallback decides, exactly as it
+       * does for a missing entry — so the write that follows lands and rewrites
+       * the entry to the record that really holds the value.
+       *
+       * "The key built from the record's stored fields" has to mean the key that
+       * record's own save built, so the stored value is read the way the save
+       * read it: a stringset is stored as a nested Y.Map of its members but keyed
+       * as the array `getCurrentJSState` puts in `dataToSave` (finding 3252-01).
+       * Comparing the raw Y.Map would call every readable owner of a unique
+       * stringset stale and let a duplicate straight through the constraint.
+       */
+      static _readableUniqueOwner(modelYMap, constraintMap, constraint, uniqueKey, modelName) {
+        const ownerId = constraintMap.get(uniqueKey);
+        if (!ownerId) return null;
+        const recordYMap = modelYMap?.get(ownerId);
+        if (!(recordYMap instanceof Y7.Map)) return null;
+        const fields = this.getSchema?.()?.fields;
+        const heldKey = this._buildKeyFromValues(
+          constraint.fields,
+          constraint.fields.map((field) => {
+            const stored = recordYMap.get(field);
+            return fields?.get(field)?.type === "stringset" ? this._stringSetMembersFromStored(stored) : stored;
+          }),
+          modelName,
+          constraint.name
         );
+        return heldKey === uniqueKey ? ownerId : null;
       }
       /**
        * The connected format-2 document that holds this instance's record, for an
@@ -7902,7 +8972,14 @@ var init_BaseModel = __esm({
           const constraintMap = yDoc.getMap(
             uniqueIndexMapName(modelName, constraint.name)
           );
-          if (!constraintMap.get(newUniqueKey)) {
+          const readableOwner = modelConstructor._readableUniqueOwner(
+            targetYMap,
+            constraintMap,
+            constraint,
+            newUniqueKey,
+            modelName
+          );
+          if (!readableOwner) {
             const constraintKeyValues = constraint.fields.map(
               (field) => dataToSave[field]
             );
@@ -7920,7 +8997,13 @@ var init_BaseModel = __esm({
           if (upsertOnConstraint && upsertOnKey) {
             const constraintMapName = `_uniqueIdx_${modelName}_${upsertOnConstraint.name}`;
             const constraintMap = yDoc.getMap(constraintMapName);
-            const existingId = constraintMap.get(upsertOnKey);
+            const existingId = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              upsertOnConstraint,
+              upsertOnKey,
+              modelName
+            );
             if (existingId) {
               if (this._constructorProvidedId && this.id !== existingId) {
                 throw new Error(
@@ -8020,7 +9103,13 @@ var init_BaseModel = __esm({
                 50
               )}'`
             );
-            const existingRecordIdWithNewKey = constraintMap.get(newUniqueKey);
+            const existingRecordIdWithNewKey = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              constraint,
+              newUniqueKey,
+              modelName
+            );
             Logger.verbose(
               `[${modelName}] Save Check (Item '${this.id}'): Found Existing ID: '${existingRecordIdWithNewKey}' for Key '${newUniqueKey.substring(
                 0,
@@ -10158,7 +11247,7 @@ var init_BaseModel = __esm({
         );
         modelConstructor.attachStringSetObserversToRecord(recordYMap, schema, docId);
         const observerContext = resolveOrmContext(modelConstructor);
-        const recordObserver = async (event) => {
+        const indexNestedYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${modelName}] Nested YMap change detected for record ${recordId} in document ${docId}:`,
@@ -10234,6 +11323,12 @@ var init_BaseModel = __esm({
           }
           observerContext.notifyListeners(modelName);
         };
+        const recordObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexNestedYMapChange(event)
+          );
+        };
         recordYMap.observe(recordObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -10265,6 +11360,7 @@ __export(browser_exports, {
   Format2RecordStoreAsync: () => Format2RecordStoreAsync,
   Format2RowCache: () => Format2RowCache,
   Format2StorageCapabilityError: () => Format2StorageCapabilityError,
+  INGEST_CHUNK_LIMITS: () => INGEST_CHUNK_LIMITS,
   InProcessFormat2StoreHost: () => InProcessFormat2StoreHost,
   LogLevel: () => LogLevel,
   Logger: () => Logger,
@@ -10308,6 +11404,8 @@ __export(browser_exports, {
   encodeOverlayMutation: () => encodeOverlayMutation,
   estimateMaterializedBytes: () => estimateMaterializedBytes,
   features: () => features,
+  findReservedFieldNameInToml: () => findReservedFieldNameInToml,
+  foldFormat2Overlay: () => foldFormat2Overlay,
   followEpoch: () => followEpoch,
   format2ClientDDL: () => format2ClientDDL,
   format2EpochDocName: () => format2EpochDocName,
@@ -10330,6 +11428,7 @@ __export(browser_exports, {
   loadSchemaFromTomlString: () => loadSchemaFromTomlString,
   materializeOverlayRecord: () => materializeOverlayRecord,
   observeFormat2Overlay: () => observeFormat2Overlay,
+  offlineReplayRecordKey: () => offlineReplayRecordKey,
   offlineWindowStatus: () => offlineWindowStatus,
   overlayFieldKey: () => overlayFieldKey,
   overlayMarkerKey: () => overlayMarkerKey,
@@ -10338,6 +11437,7 @@ __export(browser_exports, {
   parseSnapshotChunkPath: () => parseSnapshotChunkPath,
   planColdStart: () => planColdStart,
   planFastForward: () => planFastForward,
+  planRangeReplacement: () => planRangeReplacement,
   planSnapshotHydration: () => planSnapshotHydration,
   probeStorageCapability: () => probeStorageCapability,
   projectOverlayEntry: () => projectOverlayEntry,
@@ -10353,6 +11453,8 @@ __export(browser_exports, {
   schemaToToml: () => schemaToToml,
   serveFormat2StoreHost: () => serveFormat2StoreHost,
   snapshotChunkPath: () => snapshotChunkPath,
+  statePendingOps: () => statePendingOps,
+  suppressSupersededKeys: () => suppressSupersededKeys,
   syncInferredMeta: () => syncInferredMeta,
   syncModelMeta: () => syncModelMeta,
   validateSnapshotManifest: () => validateSnapshotManifest,
@@ -10966,387 +12068,135 @@ var SqljsEngine = class _SqljsEngine extends SqliteQueryEngineBase {
       throw error;
     }
   }
-  /** The open connection, once the wasm has loaded. */
-  async connection() {
-    await this.readyPromise;
-    if (!this.db || !this.sync) throw new Error("SQL.js not initialized");
-    return this.sync;
-  }
-  async withTransaction(callback) {
-    await this.readyPromise;
-    if (!this.db)
-      throw new Error("SQL.js Database instance not available for transaction");
-    let transactionStartedHere = false;
-    await this.mutex.runExclusive(async () => {
-      if (this.numOpenTransactions === 0) {
-        if (!this.db) throw new Error("SQL.js DB not available for BEGIN");
-        this.db.run("BEGIN TRANSACTION");
-        transactionStartedHere = true;
-      }
-      this.numOpenTransactions++;
-    });
-    const transactionalOps = new TransactionalSQLJSOperations(this.db, this);
-    try {
-      const result = await callback(transactionalOps);
-      await this.mutex.runExclusive(async () => {
-        this.numOpenTransactions--;
-        if (this.numOpenTransactions === 0) {
-          if (!this.db) throw new Error("SQL.js DB not available for COMMIT");
-          this.db.run("COMMIT");
-        }
-      });
-      return result;
-    } catch (error) {
-      Logger.error("[SqljsEngine] Error in transaction, rolling back:", error);
-      await this.mutex.runExclusive(async () => {
-        if (this.db && this.numOpenTransactions > 0 && transactionStartedHere) {
-          try {
-            if (!this.db)
-              throw new Error("SQL.js DB not available for ROLLBACK");
-            this.db.run("ROLLBACK");
-          } catch (rollbackError) {
-            Logger.error("[SqljsEngine] Error during ROLLBACK:", rollbackError);
-          }
-        }
-        this.numOpenTransactions = 0;
-      });
-      throw error;
-    }
-  }
-  /**
-   * Synchronous executor for the format-2 record store (#2816). SQL.js has no
-   * savepoints exposed here, so nesting reuses the open transaction rather
-   * than issuing a second BEGIN.
-   */
-  /**
-   * SQL.js is an in-memory database (#2816): `new SQL.Database()` and nothing
-   * behind it. It can host a large document's merged view for the life of a
-   * page, and cannot BE one — a reload would take the document and every write
-   * the server has not acknowledged with it. Until the worker-hosted OPFS
-   * engine lands, saying so is what turns that into a typed refusal before a
-   * cold load starts writing, instead of a document that quietly evaporates.
-   */
-  format2StorageIsDurable() {
-    return false;
-  }
-  createFormat2Sql() {
-    if (!this.db) {
-      throw new Error(
-        "[SqljsEngine] SQL.js not initialized; await ensureReady() before creating the format-2 executor"
-      );
-    }
-    const db = this.db;
-    let depth = 0;
-    return {
-      exec(query, ...bindings) {
-        const stmt = db.prepare(query);
-        try {
-          if (bindings.length > 0) stmt.bind(bindings);
-          const rows = [];
-          while (stmt.step()) rows.push(stmt.getAsObject());
-          return rows;
-        } finally {
-          stmt.free();
-        }
-      },
-      transaction(fn) {
-        if (depth > 0) return fn();
-        depth++;
-        db.run("BEGIN TRANSACTION");
-        try {
-          const result = fn();
-          db.run("COMMIT");
-          return result;
-        } catch (error) {
-          db.run("ROLLBACK");
-          throw error;
-        } finally {
-          depth--;
-        }
-      }
-    };
-  }
-  async close() {
-    await this.readyPromise;
-    if (this.db) {
-      this.db.close();
-      this.db = null;
-      this.sync = null;
-      _SqljsEngine.SQL = null;
-    }
-  }
-  async getTableSchema(_tableName) {
-    return void 0;
-  }
-  async destroy() {
-    if (this.db) {
-      this.db.close();
-      Logger.info("[SqljsEngine] Database closed.");
-    }
-  }
-  getLastErrorMessage() {
-    return void 0;
-  }
-};
-
-// src/engines/opfs/OpfsEngine.ts
-init_logger();
-init_sql();
-
-// src/utils/snapshotChunks.ts
-var FORMAT2_MANIFEST_VERSION = 3;
-var FORMAT2_MIN_MANIFEST_VERSION = 2;
-var SnapshotChunkIntegrityError = class extends Error {
-  constructor(key, reason) {
-    super(`Snapshot chunk ${key} does not match its manifest entry: ${reason}`);
-    this.key = key;
-    this.reason = reason;
-    this.name = "SnapshotChunkIntegrityError";
-  }
-};
-var SnapshotManifestInvalidError = class extends Error {
-  code = "SNAPSHOT_MANIFEST_INVALID";
-  constructor(reason) {
-    super(`Snapshot manifest is not valid: ${reason}`);
-    this.name = "SnapshotManifestInvalidError";
-  }
-};
-var SnapshotManifestUnsupportedError = class extends Error {
-  constructor(manifestVersion, supportedVersion = FORMAT2_MANIFEST_VERSION) {
-    super(
-      `Snapshot manifest is version ${manifestVersion}; this client reads up to version ${supportedVersion}. Upgrade the client library.`
-    );
-    this.manifestVersion = manifestVersion;
-    this.supportedVersion = supportedVersion;
-    this.name = "SnapshotManifestUnsupportedError";
-  }
-  code = "SNAPSHOT_MANIFEST_UNSUPPORTED";
-};
-var CHUNK_PATH_OWN = /^([A-Za-z][A-Za-z0-9_]*)\/(\d+)$/;
-var CHUNK_PATH_SOURCED = /^(\d+)-([A-Za-z0-9_-]{1,64})\/([A-Za-z][A-Za-z0-9_]*)\/(\d+)$/;
-function parseSnapshotChunkPath(path) {
-  if (!path || typeof path !== "string") return null;
-  const own = CHUNK_PATH_OWN.exec(path);
-  if (own) return { model: own[1], index: Number(own[2]) };
-  const sourced = CHUNK_PATH_SOURCED.exec(path);
-  if (!sourced) return null;
-  return {
-    model: sourced[3],
-    index: Number(sourced[4]),
-    source: { epoch: Number(sourced[1]), buildId: sourced[2] }
-  };
-}
-function resolveChunkOrdinal(entry, index) {
-  return typeof entry.ordinal === "number" ? entry.ordinal : index;
-}
-function collationRank(unit) {
-  if (unit >= 57344) return unit - 2048;
-  if (unit >= 55296) return unit + 8192;
-  return unit;
-}
-function compareRecordIds(left, right) {
-  if (left === right) return 0;
-  const shared = Math.min(left.length, right.length);
-  for (let index = 0; index < shared; index++) {
-    const a = left.charCodeAt(index);
-    const b = right.charCodeAt(index);
-    if (a === b) continue;
-    return collationRank(a) < collationRank(b) ? -1 : 1;
-  }
-  return left.length < right.length ? -1 : left.length > right.length ? 1 : 0;
-}
-function validateSnapshotManifest(manifest) {
-  if (!manifest || typeof manifest !== "object") {
-    throw new SnapshotManifestInvalidError("it is not an object");
-  }
-  const version = manifest.version;
-  if (!Number.isInteger(version)) {
-    throw new SnapshotManifestInvalidError(`version ${String(version)} is not an integer`);
-  }
-  if (version > FORMAT2_MANIFEST_VERSION) {
-    throw new SnapshotManifestUnsupportedError(version);
-  }
-  if (version < FORMAT2_MIN_MANIFEST_VERSION) {
-    throw new SnapshotManifestInvalidError(
-      `version ${version} is older than the large-document format (${FORMAT2_MIN_MANIFEST_VERSION})`
-    );
-  }
-  const chunks = manifest.chunks;
-  if (!Array.isArray(chunks)) {
-    throw new SnapshotManifestInvalidError("its chunk list is not an array");
-  }
-  const seenOrdinals = /* @__PURE__ */ new Set();
-  const lastRangeEndPerModel = /* @__PURE__ */ new Map();
-  let rows = 0;
-  let bytes = 0;
-  for (let index = 0; index < chunks.length; index++) {
-    const entry = chunks[index];
-    const where = `chunk ${index} (${entry?.model ?? "?"})`;
-    if (!entry || typeof entry !== "object") {
-      throw new SnapshotManifestInvalidError(`${where} is not an object`);
-    }
-    if (entry.ordinal !== void 0 && !Number.isSafeInteger(entry.ordinal)) {
-      throw new SnapshotManifestInvalidError(
-        `${where} has ordinal ${String(entry.ordinal)}, which is not an integer`
-      );
-    }
-    const ordinal = resolveChunkOrdinal(entry, index);
-    if (!Number.isSafeInteger(ordinal) || ordinal < 0) {
-      throw new SnapshotManifestInvalidError(
-        `${where} resolves to ordinal ${String(ordinal)}, which is not a non-negative integer`
-      );
-    }
-    if (seenOrdinals.has(ordinal)) {
-      throw new SnapshotManifestInvalidError(
-        `${where} shares ordinal ${ordinal} with an earlier chunk`
-      );
-    }
-    seenOrdinals.add(ordinal);
-    if (entry.path !== void 0 && !parseSnapshotChunkPath(entry.path)) {
-      throw new SnapshotManifestInvalidError(
-        `${where} has a path that is not addressable: ${String(entry.path)}`
-      );
-    }
-    if (entry.rows > 0 && compareRecordIds(entry.firstId, entry.lastId) > 0) {
-      throw new SnapshotManifestInvalidError(
-        `${where} spans ${entry.firstId}..${entry.lastId}, which runs backwards`
-      );
-    }
-    if (entry.rows > 0) {
-      const previousEnd = lastRangeEndPerModel.get(entry.model);
-      if (previousEnd !== void 0 && compareRecordIds(entry.firstId, previousEnd) <= 0) {
-        throw new SnapshotManifestInvalidError(
-          `${where} starts at ${entry.firstId}, at or before ${previousEnd} where the previous chunk of ${entry.model} ended`
-        );
-      }
-      lastRangeEndPerModel.set(entry.model, entry.lastId);
-    }
-    rows += Number(entry.rows) || 0;
-    bytes += Number(entry.bytes) || 0;
-  }
-  const totals = manifest.totals;
-  if (!totals || totals.rows !== rows || totals.bytes !== bytes) {
-    throw new SnapshotManifestInvalidError(
-      `its totals say ${totals?.rows}/${totals?.bytes} rows/bytes but its chunks add up to ${rows}/${bytes}`
-    );
+  /** The open connection, once the wasm has loaded. */
+  async connection() {
+    await this.readyPromise;
+    if (!this.db || !this.sync) throw new Error("SQL.js not initialized");
+    return this.sync;
   }
-}
-function snapshotStringSetFields(manifest, model) {
-  const declared = manifest.schema?.[model]?.stringSetFields;
-  return new Set(Array.isArray(declared) ? declared.map(String) : []);
-}
-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;
+  async withTransaction(callback) {
+    await this.readyPromise;
+    if (!this.db)
+      throw new Error("SQL.js Database instance not available for transaction");
+    let transactionStartedHere = false;
+    await this.mutex.runExclusive(async () => {
+      if (this.numOpenTransactions === 0) {
+        if (!this.db) throw new Error("SQL.js DB not available for BEGIN");
+        this.db.run("BEGIN TRANSACTION");
+        transactionStartedHere = true;
+      }
+      this.numOpenTransactions++;
+    });
+    const transactionalOps = new TransactionalSQLJSOperations(this.db, this);
+    try {
+      const result = await callback(transactionalOps);
+      await this.mutex.runExclusive(async () => {
+        this.numOpenTransactions--;
+        if (this.numOpenTransactions === 0) {
+          if (!this.db) throw new Error("SQL.js DB not available for COMMIT");
+          this.db.run("COMMIT");
+        }
+      });
+      return result;
+    } catch (error) {
+      Logger.error("[SqljsEngine] Error in transaction, rolling back:", error);
+      await this.mutex.runExclusive(async () => {
+        if (this.db && this.numOpenTransactions > 0 && transactionStartedHere) {
+          try {
+            if (!this.db)
+              throw new Error("SQL.js DB not available for ROLLBACK");
+            this.db.run("ROLLBACK");
+          } catch (rollbackError) {
+            Logger.error("[SqljsEngine] Error during ROLLBACK:", rollbackError);
+          }
+        }
+        this.numOpenTransactions = 0;
+      });
+      throw error;
     }
-    fields[field] = value;
-  }
-  return { id, fields, stringSets, replace: true, deleted: false };
-}
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
-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;
+  /**
+   * Synchronous executor for the format-2 record store (#2816). SQL.js has no
+   * savepoints exposed here, so nesting reuses the open transaction rather
+   * than issuing a second BEGIN.
+   */
+  /**
+   * SQL.js is an in-memory database (#2816): `new SQL.Database()` and nothing
+   * behind it. It can host a large document's merged view for the life of a
+   * page, and cannot BE one — a reload would take the document and every write
+   * the server has not acknowledged with it. Until the worker-hosted OPFS
+   * engine lands, saying so is what turns that into a typed refusal before a
+   * cold load starts writing, instead of a document that quietly evaporates.
+   */
+  format2StorageIsDurable() {
+    return false;
   }
-  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 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}`
+  createFormat2Sql() {
+    if (!this.db) {
+      throw new Error(
+        "[SqljsEngine] SQL.js not initialized; await ensureReady() before creating the format-2 executor"
       );
     }
+    const db = this.db;
+    let depth = 0;
+    return {
+      exec(query, ...bindings) {
+        const stmt = db.prepare(query);
+        try {
+          if (bindings.length > 0) stmt.bind(bindings);
+          const rows = [];
+          while (stmt.step()) rows.push(stmt.getAsObject());
+          return rows;
+        } finally {
+          stmt.free();
+        }
+      },
+      transaction(fn) {
+        if (depth > 0) return fn();
+        depth++;
+        db.run("BEGIN TRANSACTION");
+        try {
+          const result = fn();
+          db.run("COMMIT");
+          return result;
+        } catch (error) {
+          db.run("ROLLBACK");
+          throw error;
+        } finally {
+          depth--;
+        }
+      }
+    };
   }
-  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"
-      );
+  async close() {
+    await this.readyPromise;
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+      this.sync = null;
+      _SqljsEngine.SQL = null;
     }
-    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}`
-    );
+  async getTableSchema(_tableName) {
+    return void 0;
   }
-  if (entry && rows.length > 0) {
-    const seen = /* @__PURE__ */ new Set();
-    for (const row of rows) {
-      if (seen.has(row._id)) {
-        throw new SnapshotChunkIntegrityError(
-          entry.key,
-          `duplicate id ${row._id}`
-        );
-      }
-      seen.add(row._id);
-    }
-    if (rows[0]._id !== entry.firstId) {
-      throw new SnapshotChunkIntegrityError(
-        entry.key,
-        `expected it to begin at ${entry.firstId}, got ${rows[0]._id}`
-      );
-    }
-    if (rows[rows.length - 1]._id !== entry.lastId) {
-      throw new SnapshotChunkIntegrityError(
-        entry.key,
-        `expected it to end at ${entry.lastId}, got ${rows[rows.length - 1]._id}`
-      );
+  async destroy() {
+    if (this.db) {
+      this.db.close();
+      Logger.info("[SqljsEngine] Database closed.");
     }
   }
-  return rows;
-}
+  getLastErrorMessage() {
+    return void 0;
+  }
+};
+
+// src/engines/opfs/OpfsEngine.ts
+init_logger();
+init_sql();
 
 // src/models/format2StorageCapability.ts
+init_snapshotChunks();
 var SNAPSHOT_STORAGE_EXPANSION = 2;
 var SNAPSHOT_COMPRESSED_EXPANSION = 8;
 function estimateMaterializedBytes(chunk) {
@@ -13558,10 +14408,19 @@ function sameOverlayValue(a, b) {
   if (a === null || a === void 0) return b === null || b === void 0;
   return JSON.stringify(a) === JSON.stringify(b);
 }
-function restorePendingOverlay(doc, store, verdicts) {
-  const result = { restored: [], unreproducible: [] };
+function restorePendingOverlay(doc, store, verdicts, options = {}) {
+  const result = {
+    restored: [],
+    unreproducible: [],
+    deferred: []
+  };
+  const defer = options.deferAtOrBelowEpoch ?? 0;
   const missing = [];
   for (const op of store.pendingOps()) {
+    if (defer > 0 && op.baseEpoch > 0 && op.baseEpoch <= defer) {
+      result.deferred.push(op.seq);
+      continue;
+    }
     const verdict = verdicts?.get(op.seq);
     if (verdict === "carried" || verdict === "superseded") continue;
     if (verdict === void 0 && overlayCarries(doc, op)) continue;
@@ -13586,8 +14445,27 @@ function restorePendingOverlay(doc, store, verdicts) {
   }, FORMAT2_LOCAL_WRITE_ORIGIN);
   return result;
 }
+function statePendingOps(doc, ops, options = {}) {
+  const suppressed = new Set(
+    (options.suppressDeletes ?? []).map(
+      (entry) => `${entry.model} ${entry.recordId}`
+    )
+  );
+  const stated = [...ops].sort((a, b) => a.seq - b.seq).filter(
+    (op) => op.mutation !== null && !(op.op === "delete" && suppressed.has(`${op.model} ${op.recordId}`))
+  );
+  if (stated.length === 0) return 0;
+  doc.transact(() => {
+    for (const op of stated) {
+      applyOverlayMutation(doc.getMap(op.model), op.mutation);
+    }
+  });
+  return stated.length;
+}
 
 // src/models/format2SnapshotLoader.ts
+init_snapshotChunks();
+var PRUNE_PAGE_ROWS = 500;
 var SnapshotLoadIncompleteError = class extends Error {
   constructor(buildId, missing, passes) {
     super(
@@ -13629,6 +14507,7 @@ async function loadFormat2Snapshot(options) {
   const { store, manifest } = options;
   const retries = options.retries ?? 1;
   validateSnapshotManifest(manifest);
+  await store.beginBase(manifest.buildId, manifest.epoch);
   const already = new Set(await store.completedChunks(manifest.buildId));
   const ordinals = new Map(
     manifest.chunks.map((chunk, index) => [chunk, resolveChunkOrdinal(chunk, index)])
@@ -13636,7 +14515,20 @@ async function loadFormat2Snapshot(options) {
   await store.setHydrationScope(options.models ? [...options.models] : null);
   const cap = options.models;
   const wanted = (model) => cap === void 0 || cap.includes(model);
-  const selected = manifest.chunks.filter((chunk) => wanted(chunk.model));
+  const plan = options.plan;
+  const coverages = new Map(
+    plan?.fetch.map((entry) => [entry.chunk, entry.coverage]) ?? []
+  );
+  const keptChunks = new Set(plan?.keep ?? []);
+  const selected = (plan ? [...plan.fetch.map((entry) => entry.chunk), ...plan.keep].sort(
+    (a, b) => manifest.chunks.indexOf(a) - manifest.chunks.indexOf(b)
+  ) : manifest.chunks).filter((chunk) => wanted(chunk.model));
+  const announcedTouched = /* @__PURE__ */ new Set();
+  const announceTouched = async (model) => {
+    if (announcedTouched.has(model)) return;
+    announcedTouched.add(model);
+    await options.onModelTouched?.(model);
+  };
   const totalChunks = selected.length;
   const totalRows = selected.reduce((total, chunk) => total + chunk.rows, 0);
   const models = [];
@@ -13657,6 +14549,14 @@ async function loadFormat2Snapshot(options) {
     );
     if (!models.includes(chunk.model)) models.push(chunk.model);
   }
+  for (const model of plan?.pruneModels ?? []) {
+    await announceTouched(model);
+    for (; ; ) {
+      const page = await store.deleteRange(model, null, null, PRUNE_PAGE_ROWS);
+      if (page.done) break;
+    }
+    await options.onModelReady?.(model);
+  }
   const applyOne = async (chunk, outstanding) => {
     let decoded = null;
     let lastError = null;
@@ -13673,14 +14573,27 @@ async function loadFormat2Snapshot(options) {
     }
     if (!decoded) throw new SnapshotLoadIntegrityError(chunk, lastError);
     const stringSetFields = snapshotStringSetFields(manifest, chunk.model);
-    await store.applyChunk(
-      chunk.model,
-      decoded.map(
-        (row) => rowAsEntry(row._id, JSON.parse(row._data), stringSetFields)
-      ),
-      manifest.buildId,
-      ordinals.get(chunk)
+    const coverage = coverages.get(chunk);
+    const entries = decoded.map(
+      (row) => rowAsEntry(row._id, JSON.parse(row._data), stringSetFields)
     );
+    if (coverage) {
+      await announceTouched(chunk.model);
+      await store.replaceChunk(
+        chunk.model,
+        coverage,
+        entries,
+        manifest.buildId,
+        ordinals.get(chunk)
+      );
+    } else {
+      await store.applyChunk(
+        chunk.model,
+        entries,
+        manifest.buildId,
+        ordinals.get(chunk)
+      );
+    }
     chunks++;
     rows += decoded.length;
     options.onProgress?.({
@@ -13692,6 +14605,7 @@ async function loadFormat2Snapshot(options) {
     });
     if (outstanding === 0) await options.onModelReady?.(chunk.model);
   };
+  let reused = 0;
   for (const chunk of selected) {
     const outstanding = (remainingPerModel.get(chunk.model) ?? 1) - 1;
     remainingPerModel.set(chunk.model, outstanding);
@@ -13702,6 +14616,14 @@ async function loadFormat2Snapshot(options) {
       if (outstanding === 0) await options.onModelReady?.(chunk.model);
       continue;
     }
+    if (keptChunks.has(chunk)) {
+      await store.applyChunk(chunk.model, [], manifest.buildId, ordinals.get(chunk));
+      reused++;
+      chunks++;
+      rows += chunk.rows;
+      if (outstanding === 0) await options.onModelReady?.(chunk.model);
+      continue;
+    }
     await applyOne(chunk, outstanding);
   }
   const repaired = /* @__PURE__ */ new Set();
@@ -13723,6 +14645,7 @@ async function loadFormat2Snapshot(options) {
       repaired.add(chunk.model);
     }
   }
+  await store.completeBase(manifest.buildId);
   return {
     rows,
     chunks,
@@ -13730,7 +14653,8 @@ async function loadFormat2Snapshot(options) {
     refetched,
     models,
     skipped,
-    repaired: [...repaired]
+    repaired: [...repaired],
+    reused
   };
 }
 
@@ -13848,7 +14772,20 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
     await store.whenBatchesSettled();
     if (options.restorePending !== false) {
       const verdicts = await this.adoptOrphanedWrites(docId, yDoc, store);
-      const restored = restorePendingOverlay(yDoc, store, verdicts);
+      const crossed = store.discontinuityEpochs();
+      const boundary = crossed.length > 0 ? crossed[crossed.length - 1] : 0;
+      const deferAtOrBelowEpoch = boundary > 0 && store.epoch() > boundary ? boundary : 0;
+      const restored = restorePendingOverlay(
+        yDoc,
+        store,
+        verdicts,
+        deferAtOrBelowEpoch > 0 ? { deferAtOrBelowEpoch } : {}
+      );
+      if (restored.deferred.length > 0) {
+        Logger.warn(
+          `[DocumentManager] ${docId} is holding ${restored.deferred.length} unacknowledged write(s) off its overlay until it has converged on the bulk load at epoch ${deferAtOrBelowEpoch}.`
+        );
+      }
       const adoptedWasRestored = verdicts !== void 0 && restored.restored.some((seq) => verdicts.has(seq));
       if (adoptedWasRestored) {
         foldFormat2Overlay(
@@ -14044,27 +14981,119 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
       );
     }
     const hydrated = /* @__PURE__ */ new Set();
+    const replacement = callbacks.plan;
+    const touchedModels = /* @__PURE__ */ new Set();
     const result = await loadFormat2Snapshot({
       ...plan.kind === "capped" ? { models: plan.models } : {},
       store,
       manifest,
       fetchChunk,
+      ...replacement ? { plan: replacement } : {},
       onProgress: callbacks.onProgress,
+      onModelTouched: async (model) => {
+        touchedModels.add(model);
+        await store.forgetQueryProjection(model);
+        await this.clearQueryRows(docId, store, model);
+        await callbacks.onModelTouched?.(model);
+      },
       onModelReady: async (model) => {
-        await this.hydrateQueryTables(docId, store, { only: model });
-        await this.whenProjectionSettled();
+        const owed = replacement !== void 0 && !touchedModels.has(model) && !await store.queryProjectionIsCurrent(model);
+        if (owed) {
+          await this.clearQueryRows(docId, store, model);
+        }
+        if (!replacement || touchedModels.has(model) || owed) {
+          await this.hydrateQueryTables(docId, store, { only: model });
+          await this.whenProjectionSettled();
+        }
         hydrated.add(model);
         await callbacks.onModelReady?.(model);
       }
     });
-    await this.hydrateQueryTables(docId, store, { except: hydrated });
-    await this.whenProjectionSettled();
+    if (!replacement) {
+      await this.hydrateQueryTables(docId, store, { except: hydrated });
+      await this.whenProjectionSettled();
+    }
     for (const model of result.repaired) {
       await this.hydrateQueryTables(docId, store, { only: model });
       await this.whenProjectionSettled();
     }
     return result;
   }
+  /**
+   * The models this client holds rows of for `docId` (#3435).
+   *
+   * The convergence planner needs an inventory, not a cap: a model the new
+   * base has no chunk of is pruned whole, and `null` — "the whole document" —
+   * cannot say which models those are. A capped device answers with its
+   * hydration scope; an uncapped one answers with the models this instance
+   * registered, which is every model whose rows could be here.
+   */
+  /**
+   * Hydrate ONE model's derived query tables for a bound large document
+   * (#3615).
+   *
+   * What a model registered on a running instance needs: the merged view
+   * already holds its rows — the fold and the overlay observer are keyed by
+   * the model name the overlay carries, not by the registry — but the derived
+   * tables `query()` reads were never built, because the model was not in the
+   * registry when the document was connected.
+   *
+   * Forced, because the point is a rebuild: whatever mark a previous session
+   * left says nothing about tables this instance has never projected into.
+   */
+  async hydrateModel(docId, modelName) {
+    const store = this.opened.get(docId);
+    if (!store) return;
+    if (!store.isHydrated(modelName)) {
+      Logger.warn(
+        `[DocumentManager] Large document ${docId} does not hold model '${modelName}' on this device (its hydration scope excludes it), so the query tables for '${modelName}' were not hydrated. Reads of '${modelName}' on ${docId} answer as they do for any model this device declined.`
+      );
+      return;
+    }
+    await this.hydrateQueryTables(docId, store, { only: modelName });
+    await this.whenProjectionSettled();
+  }
+  localModels(docId) {
+    const store = this.ormContext.getFormat2StoreAsync(docId);
+    if (!store) return null;
+    const scope = store.hydrationScope();
+    if (scope !== null) return [...scope];
+    const registered = [...this.modelRegistry.getActiveModels().keys()];
+    return registered.length > 0 ? registered : null;
+  }
+  /**
+   * Whether each of these records is in the merged view (#3435, behavior 21).
+   *
+   * What a convergence classifies its owed writes against. Read in one pass
+   * per model, and only AFTER the ranges have been replaced and the overlays
+   * refolded: before that, "absent" says nothing about what the bulk load did.
+   *
+   * `null` for a record of a model this device does not hold — no fact is
+   * better than a wrong one, and the caller decides what a missing verdict
+   * means.
+   */
+  async recordPresence(docId, records) {
+    const store = this.ormContext.getFormat2StoreAsync(docId);
+    if (!store) return records.map(() => null);
+    const byModel = /* @__PURE__ */ new Map();
+    records.forEach((record, index) => {
+      const list = byModel.get(record.model);
+      if (list) list.push(index);
+      else byModel.set(record.model, [index]);
+    });
+    const answers = records.map(() => null);
+    for (const [model, indexes] of byModel) {
+      if (!store.isHydrated(model)) continue;
+      const rows = await store.readMany(
+        model,
+        indexes.map((index) => records[index].id)
+      );
+      indexes.forEach((index, position) => {
+        answers[index] = rows[position] !== null;
+      });
+    }
+    return answers;
+  }
   /**
    * Release `docId`. Safe on a document that was never format 2.
    *
@@ -14248,6 +15277,32 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
    * holds. The sweep after it (`except`) and an ordinary connect honor the
    * mark.
    */
+  /**
+   * Delete one model's derived query rows for this document, a page at a time
+   * (#3435).
+   *
+   * The clear half of clear-then-project. Paged from the record store while
+   * the rows are still there, which is the same reason and the same shape as
+   * the discard path: after a range replacement nothing names the records it
+   * removed, and `hydrateQueryTables` only ever projects records that EXIST.
+   */
+  async clearQueryRows(docId, store, modelName) {
+    const modelClass = this.modelRegistry.getModelClass(modelName);
+    if (!modelClass) return;
+    if (!store.isHydrated(modelName)) return;
+    let after = null;
+    for (; ; ) {
+      const page = await store.recordIdsAfter(
+        modelName,
+        after,
+        QUERY_HYDRATION_PAGE_ROWS
+      );
+      if (page.length === 0) break;
+      await modelClass.deleteFormat2QueryRows(docId, page);
+      after = page[page.length - 1];
+      if (page.length < QUERY_HYDRATION_PAGE_ROWS) break;
+    }
+  }
   async hydrateQueryTables(docId, store, scope = {}) {
     for (const [, modelClass] of this.modelRegistry.getActiveModels()) {
       const modelName = modelClass.getSchema?.()?.options?.name;
@@ -14440,7 +15495,9 @@ function format2SyncMarks(docId, ctx) {
     highestLocalSeq: store.highestLocalSeq(),
     ackedSeq: store.ackedSeq(),
     epoch: store.epoch(),
-    clockOffsetKnown: store.clockOffsetKnown()
+    clockOffsetKnown: store.clockOffsetKnown(),
+    discontinuityEpochs: store.discontinuityEpochs(),
+    baseComplete: store.baseComplete()
   };
 }
 function format2NoteEpoch(docId, epoch, ctx) {
@@ -14483,6 +15540,17 @@ function format2NoteClockOffset(docId, offsetMs, ctx) {
   if (!store) return;
   store.noteClockOffset(offsetMs);
 }
+async function format2NoteDiscontinuity(docId, epoch, ctx) {
+  const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
+  if (!store) return;
+  if (!Number.isInteger(epoch) || epoch <= 0) return;
+  await store.noteDiscontinuity(epoch);
+}
+async function format2ClearDiscontinuities(docId, through, ctx) {
+  const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
+  if (!store) return;
+  await store.clearDiscontinuities(through);
+}
 function format2ForgetPendingOps(docId, seqs, ctx) {
   const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
   if (!store) return;
@@ -14520,12 +15588,70 @@ var DocumentManagerImpl = class {
   modelRegistry;
   /** The ORM instance this manager belongs to (#3039). */
   ormContext;
+  /**
+   * The registration gate (#3615).
+   *
+   * `connectDocument` finishes its model loop BEFORE it publishes the document
+   * in `connectedDocuments`, so a registration that read the map in that
+   * interval would miss the document while its own loop had already run —
+   * leaving it connected with no table, no rows and no observer for the new
+   * model. Registrations therefore run one at a time on this chain; a connect,
+   * a rebind and a disconnect wait for it at entry, and a registration waits
+   * for the connects that got in before it ({@link activeConnects}) before it
+   * reads the map. Connects of different documents that no registration
+   * overlaps still run concurrently, as they always have.
+   */
+  registrationChain = Promise.resolve();
+  /** Connects past the gate and not yet published — what a registration waits for. */
+  activeConnects = /* @__PURE__ */ new Set();
+  /**
+   * The `(model, document)` pairs whose initialization for this instance
+   * COMPLETED (#3615).
+   *
+   * Registry membership alone cannot say it: a document-level failure leaves
+   * the class registered but that document unusable, and `initializeForDocument`
+   * clears a document's rows and installs a fresh observer on every run, so a
+   * blanket retry would wipe the documents that had succeeded and double their
+   * observers. A retry resumes with the pairs that are not in here.
+   */
+  runtimeInitialized = /* @__PURE__ */ new Map();
+  /**
+   * Pass the registration gate, then run `work` as an in-flight connect
+   * (#3615).
+   *
+   * The re-read after the await is what closes the window: a registration
+   * publishes its chain synchronously when it is called, so a caller that
+   * waited on the chain it saw first has to check whether another one was
+   * queued behind it. Joining {@link activeConnects} happens with no await in
+   * between, so nothing can slip between the check and the join.
+   */
+  async enterConnect(work) {
+    for (; ; ) {
+      const chain = this.registrationChain;
+      await chain;
+      if (this.registrationChain === chain) break;
+    }
+    let settle;
+    const ticket = new Promise((resolve) => settle = resolve);
+    this.activeConnects.add(ticket);
+    try {
+      return await work();
+    } finally {
+      this.activeConnects.delete(ticket);
+      settle();
+    }
+  }
   async connectDocument(docId, yDoc, permissionHint, options) {
+    return this.enterConnect(
+      () => this.connectDocumentInner(docId, yDoc, permissionHint, options)
+    );
+  }
+  async connectDocumentInner(docId, yDoc, permissionHint, options) {
     if (this.connectedDocuments.has(docId)) {
       console.warn(
         `[DocumentManager] Document ${docId} is already connected. Disconnecting old version.`
       );
-      await this.disconnectDocument(docId);
+      await this.disconnectDocumentInner(docId);
     }
     const documentFormat = options?.documentFormat ?? 1;
     const connectedDoc = {
@@ -14552,6 +15678,9 @@ var DocumentManagerImpl = class {
       await this.format2.connect(docId, yDoc, options?.epoch);
     }
     this.connectedDocuments.set(docId, connectedDoc);
+    for (const modelName of this.modelRegistry.getActiveModels().keys()) {
+      this.markRuntimeInitialized(modelName, docId);
+    }
     this.notifyConnectionChange({
       type: "connect",
       docId,
@@ -14570,6 +15699,11 @@ var DocumentManagerImpl = class {
    * models read and write through is exchanged.
    */
   async rebindEpochDocument(docId, yDoc, options = {}) {
+    return this.enterConnect(
+      () => this.rebindEpochDocumentInner(docId, yDoc, options)
+    );
+  }
+  async rebindEpochDocumentInner(docId, yDoc, options = {}) {
     const connected = this.connectedDocuments.get(docId);
     if (!connected) {
       throw new Error(
@@ -14666,7 +15800,27 @@ var DocumentManagerImpl = class {
       this.largeDocumentStorage
     );
   }
+  /**
+   * The models this instance holds rows of for `docId` (#3435) — the inventory
+   * a convergence plan decides its prunes against.
+   */
+  localModels(docId) {
+    const connected = this.connectedDocuments.get(docId);
+    if (!connected || connected.documentFormat !== 2) return null;
+    return this.format2.localModels(docId);
+  }
+  /** Whether each record is in `docId`'s merged view (#3435, behavior 21). */
+  async recordPresence(docId, records) {
+    const connected = this.connectedDocuments.get(docId);
+    if (!connected || connected.documentFormat !== 2) {
+      return records.map(() => null);
+    }
+    return await this.format2.recordPresence(docId, records);
+  }
   async disconnectDocument(docId) {
+    return this.enterConnect(() => this.disconnectDocumentInner(docId));
+  }
+  async disconnectDocumentInner(docId) {
     const connectedDoc = this.connectedDocuments.get(docId);
     if (!connectedDoc) {
       Logger.warn(`[DocumentManager] Document ${docId} is not connected`);
@@ -14683,6 +15837,9 @@ var DocumentManagerImpl = class {
       wipeModels ? { wipeIfLastModels: wipeModels } : {}
     );
     this.connectedDocuments.delete(docId);
+    for (const docIds of this.runtimeInitialized.values()) {
+      docIds.delete(docId);
+    }
     this.ormContext.disposeObserversForDocument(docId);
     this.ormContext.clearMappingsForDocId(docId);
     this.notifyConnectionChange({
@@ -14693,10 +15850,150 @@ var DocumentManagerImpl = class {
       `[DocumentManager] Document ${docId} disconnected successfully`
     );
   }
+  markRuntimeInitialized(modelName, docId) {
+    let docIds = this.runtimeInitialized.get(modelName);
+    if (!docIds) {
+      docIds = /* @__PURE__ */ new Set();
+      this.runtimeInitialized.set(modelName, docIds);
+    }
+    docIds.add(docId);
+  }
+  /**
+   * Add a model to this running instance (#3615). See
+   * {@link InitJsBaoResult.registerModel}.
+   */
+  async registerModel(modelClass) {
+    const previous = this.registrationChain;
+    let release;
+    this.registrationChain = new Promise((resolve) => release = resolve);
+    try {
+      await previous;
+      while (this.activeConnects.size > 0) {
+        await Promise.all(Array.from(this.activeConnects));
+      }
+      await this.runRegistration(modelClass);
+    } finally {
+      release();
+    }
+  }
+  async runRegistration(modelClass) {
+    if (this.ormContext.destroyed) {
+      throw new Error(
+        `[initJsBao] Cannot register model on destroyed js-bao instance #${this.ormContext.instanceId}. Create a new instance with initJsBao.`
+      );
+    }
+    const modelName = this.modelRegistry.assertAdoptable(
+      modelClass,
+      this.ormContext.instanceId
+    );
+    const boundTo = modelClass?._ormContext;
+    if (boundTo && boundTo !== this.ormContext && !boundTo.destroyed) {
+      throw new Error(
+        `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${boundTo.instanceId}. Give instance #${this.ormContext.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
+      );
+    }
+    const { added } = this.modelRegistry.adoptModel(modelClass, {
+      instanceId: this.ormContext.instanceId
+    });
+    bindModelClass(this.ormContext, modelName, modelClass, "throw");
+    let didDocumentWork = false;
+    for (const connected of Array.from(this.connectedDocuments.values())) {
+      if (this.runtimeInitialized.get(modelName)?.has(connected.docId)) {
+        continue;
+      }
+      didDocumentWork = true;
+      try {
+        await this.initializeModelForConnectedDocument(
+          modelClass,
+          modelName,
+          connected
+        );
+      } catch (error) {
+        await modelClass.withdrawDocumentRegistration(connected.docId);
+        const message = error instanceof Error ? error.message : String(error);
+        const wrapped = new Error(
+          `[initJsBao] registerModel('${modelName}') failed on document ${connected.docId}; registration is incomplete and can be retried: ` + message
+        );
+        wrapped.cause = error;
+        throw wrapped;
+      }
+      this.markRuntimeInitialized(modelName, connected.docId);
+    }
+    if (added || didDocumentWork) {
+      await this.modelRegistry.initializeRelationships(this.dbEngine);
+    }
+  }
+  /**
+   * Initialize one model for one already-connected document (#3615).
+   *
+   * The legacy half carries the window `initializeForDocument` leaves open: it
+   * loads the Y.Map as records in an asynchronous transaction and installs its
+   * observers afterwards, which on a document the app connected long ago is a
+   * live document still receiving peer updates. A temporary deep observer
+   * collects the record ids touched while that runs; once the instance's
+   * indexing for the document has drained, each of them is written from its
+   * CURRENT state, so the call resolves with the query tables holding every
+   * update that arrived before it did.
+   */
+  async initializeModelForConnectedDocument(modelClass, modelName, connected) {
+    const { docId, yDoc, permissionHint } = connected;
+    const documentFormat = connected.documentFormat ?? 1;
+    if (documentFormat === 2) {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        2
+      );
+      await this.format2.hydrateModel(docId, modelName);
+      return;
+    }
+    const touched = /* @__PURE__ */ new Set();
+    const documentYMap = yDoc.getMap(modelName);
+    const collect2 = (events) => {
+      for (const event of events) {
+        if (event.target === documentYMap) {
+          for (const key of event.changes.keys.keys()) touched.add(key);
+        } else if (event.path.length > 0) {
+          touched.add(String(event.path[0]));
+        }
+      }
+    };
+    documentYMap.observeDeep(collect2);
+    try {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        1
+      );
+      await this.whenDocumentIndexed(docId);
+      for (const recordId of touched) {
+        await modelClass.reindexDocumentRecord(docId, recordId);
+      }
+    } finally {
+      documentYMap.unobserveDeep(collect2);
+    }
+  }
   /** Resolves once every enqueued query-projection refresh has been applied. */
   whenFormat2ProjectionSettled() {
     return this.format2.whenProjectionSettled();
   }
+  /**
+   * Resolves once THIS instance's query tables have caught up with `docId`
+   * (#3023). Scoped to the instance's own context, so a second client holding
+   * the same document id never waits on this one's writes.
+   */
+  async whenDocumentIndexed(docId) {
+    const drained = await this.ormContext.whenDocumentIndexed(docId);
+    if (!drained) {
+      Logger.warn(
+        `[DocumentManager] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+      );
+    }
+  }
   getConnectedDocuments() {
     return new Map(this.connectedDocuments);
   }
@@ -14724,22 +16021,33 @@ var DocumentManagerImpl = class {
 };
 function bindSessionModels(ctx, registry) {
   for (const [modelName, modelClass] of registry.getActiveModels()) {
-    const current = modelClass?._ormContext;
-    if (current === ctx) continue;
-    if (!current || current.destroyed) {
-      Object.defineProperty(modelClass, "_ormContext", {
-        value: ctx,
-        writable: true,
-        configurable: true,
-        enumerable: false
-      });
-      ctx.boundModels.add(modelClass);
-      continue;
-    }
-    console.warn(
-      `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+    bindModelClass(ctx, modelName, modelClass, "warn");
+  }
+}
+function bindModelClass(ctx, modelName, modelClass, onLiveConflict) {
+  const current = modelClass?._ormContext;
+  if (current === ctx) {
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (!current || current.destroyed) {
+    Object.defineProperty(modelClass, "_ormContext", {
+      value: ctx,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (onLiveConflict === "throw") {
+    throw new Error(
+      `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${current.instanceId}. Give instance #${ctx.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
     );
   }
+  console.warn(
+    `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+  );
 }
 async function initJsBaoCore(options, getEngine) {
   const { databaseConfig, models: modelClasses } = options;
@@ -14768,6 +16076,7 @@ async function initJsBaoCore(options, getEngine) {
       destroy: () => ormContext.destroy(),
       connectDocument: docManager.connectDocument.bind(docManager),
       disconnectDocument: docManager.disconnectDocument.bind(docManager),
+      registerModel: docManager.registerModel.bind(docManager),
       format2SyncMarks: (docId) => format2SyncMarks(docId, ormContext),
       format2StoredEpoch: (docId) => format2StoredEpoch(dbEngine, docId, ormContext),
       // The pre-bind epoch read opens the same pool the bind will, so it needs
@@ -14785,6 +16094,8 @@ async function initJsBaoCore(options, getEngine) {
       format2NoteWindow: (docId, windowDays) => format2NoteWindow(docId, windowDays, ormContext),
       format2NoteClockOffset: (docId, offsetMs) => format2NoteClockOffset(docId, offsetMs, ormContext),
       format2ForgetPendingOps: (docId, seqs) => format2ForgetPendingOps(docId, seqs, ormContext),
+      format2NoteDiscontinuity: (docId, epoch) => format2NoteDiscontinuity(docId, epoch, ormContext),
+      format2ClearDiscontinuities: (docId, through) => format2ClearDiscontinuities(docId, through, ormContext),
       format2NarrowPendingOps: (docId, ops) => format2NarrowPendingOps(docId, ops, ormContext),
       format2PendingOps: (docId) => format2PendingOps(docId, ormContext),
       format2SetEpoch: (docId, epoch) => format2SetEpoch(docId, epoch, ormContext),
@@ -14798,7 +16109,10 @@ async function initJsBaoCore(options, getEngine) {
       // queue updates after it). The transport awaits it before an update
       // from the room counts as applied.
       whenFormat2ProjectionSettled: docManager.whenFormat2ProjectionSettled.bind(docManager),
+      whenDocumentIndexed: docManager.whenDocumentIndexed.bind(docManager),
       format2LoadSnapshot: docManager.loadSnapshot.bind(docManager),
+      format2LocalModels: (docId) => docManager.localModels(docId),
+      format2RecordPresence: (docId, records) => docManager.recordPresence(docId, records),
       getConnectedDocuments: docManager.getConnectedDocuments.bind(docManager),
       isDocumentConnected: docManager.isDocumentConnected.bind(docManager),
       onDocumentConnectionChange: docManager.onConnectionChange.bind(docManager),
@@ -14958,40 +16272,6 @@ function createModelClass(config) {
   attachAndRegisterModel(GeneratedModel, schema);
   return GeneratedModel;
 }
-function resolveUniqueConstraints(modelName, fields, customConstraints) {
-  const resolved = [];
-  for (const [fieldName, options] of fields.entries()) {
-    if (options.unique) {
-      resolved.push({
-        name: fieldUniqueConstraintName(modelName, fieldName),
-        fields: [fieldName]
-      });
-    }
-  }
-  if (customConstraints) {
-    for (const constraint of customConstraints) {
-      const missingField = constraint.fields.find(
-        (field) => !fields.has(field)
-      );
-      if (missingField) {
-        console.warn(
-          `[defineModelSchema] Unique constraint "${constraint.name}" for model "${modelName}" references unknown field "${missingField}". Skipping.`
-        );
-        continue;
-      }
-      if (resolved.some((item) => item.name === constraint.name)) {
-        console.warn(
-          `[defineModelSchema] Duplicate unique constraint name "${constraint.name}" in model "${modelName}".`
-        );
-      }
-      resolved.push({
-        name: constraint.name,
-        fields: [...constraint.fields]
-      });
-    }
-  }
-  return resolved;
-}
 function attachSchemaToClass(modelClass, schema) {
   modelClass.schema = schema;
   modelClass.modelName = schema.options.name;
@@ -15233,6 +16513,26 @@ function schemaToToml(schema) {
 
 // src/models/tomlLoader.ts
 var import_smol_toml = require("smol-toml");
+
+// src/utils/reservedFields.ts
+function checkReservedFieldName(fieldName) {
+  if (fieldName === "id") return null;
+  if (fieldName === "type") {
+    return `Field 'type' is reserved (maps to internal _type column in queries)`;
+  }
+  if (fieldName.startsWith("_")) {
+    return `Field '${fieldName}' is reserved (fields starting with '_' are internal)`;
+  }
+  return null;
+}
+var ReservedFieldNameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReservedFieldNameError";
+  }
+};
+
+// src/models/tomlLoader.ts
 var VALID_FIELD_TYPES = /* @__PURE__ */ new Set([
   "string",
   "number",
@@ -15379,6 +16679,7 @@ function parseRelationship(raw, context, strict) {
 }
 function loadSchemaFromTomlString(tomlString, options = {}) {
   const strict = options.strict !== false;
+  const rejectReserved = options.rejectReservedFieldNames === true;
   const parsed = (0, import_smol_toml.parse)(tomlString);
   const models = parsed.models;
   if (!models || typeof models !== "object") {
@@ -15395,11 +16696,14 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
     const fields = {};
     if (modelDef.fields) {
       for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
-        fields[fieldName] = parseFieldOptions(
-          fieldDef,
-          `[models.${modelName}.fields.${fieldName}]`,
-          strict
-        );
+        const context = `[models.${modelName}.fields.${fieldName}]`;
+        if (rejectReserved) {
+          const reserved = checkReservedFieldName(fieldName);
+          if (reserved) {
+            throw new ReservedFieldNameError(`${context}: ${reserved}`);
+          }
+        }
+        fields[fieldName] = parseFieldOptions(fieldDef, context, strict);
       }
     }
     let relationships;
@@ -15446,6 +16750,18 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
   }
   return schemas;
 }
+function findReservedFieldNameInToml(tomlString) {
+  try {
+    loadSchemaFromTomlString(tomlString, {
+      strict: false,
+      rejectReservedFieldNames: true
+    });
+    return null;
+  } catch (error) {
+    if (error instanceof ReservedFieldNameError) return error.message;
+    return null;
+  }
+}
 
 // src/browser.ts
 init_metaSync();
@@ -15542,6 +16858,49 @@ function writeCarriedOverlay(modelMap, entry) {
     }
   }
 }
+function suppressSupersededKeys(carried, later) {
+  if (later.length === 0 || carried.length === 0) return carried;
+  const fields = /* @__PURE__ */ new Map();
+  const revived = /* @__PURE__ */ new Set();
+  for (const op of later) {
+    const key = `${op.model} ${op.recordId}`;
+    let owned = fields.get(key);
+    if (!owned) fields.set(key, owned = /* @__PURE__ */ new Set());
+    for (const field of op.fields) owned.add(field);
+    if (op.op !== "delete") revived.add(key);
+  }
+  const kept = [];
+  for (const { model, entry } of carried) {
+    const key = `${model} ${entry.id}`;
+    const owned = fields.get(key);
+    if (owned === void 0) {
+      kept.push({ model, entry });
+      continue;
+    }
+    if (entry.deleted) {
+      if (!revived.has(key)) kept.push({ model, entry });
+      continue;
+    }
+    const survivingFields = Object.fromEntries(
+      Object.entries(entry.fields).filter(([field]) => !owned.has(field))
+    );
+    const survivingSets = Object.fromEntries(
+      Object.entries(entry.stringSets).filter(([field]) => !owned.has(field))
+    );
+    if (!entry.replace && Object.keys(survivingFields).length === 0 && Object.keys(survivingSets).length === 0) {
+      continue;
+    }
+    kept.push({
+      model,
+      entry: {
+        ...entry,
+        fields: survivingFields,
+        stringSets: survivingSets
+      }
+    });
+  }
+  return kept;
+}
 
 // src/models/format2EpochRotation.ts
 var Y10 = __toESM(require("yjs"), 1);
@@ -15613,10 +16972,15 @@ async function writeDeferredReplay(host, ops, owedOverlay, resolveReplay) {
   const live = host.overlayDoc();
   if (!live) return 0;
   const owed = resolveReplay(ops);
-  const carried = carryUnackedOverlay(
-    owed.ops,
-    (model, recordId) => owedOverlay.get(`${model} ${recordId}`) ?? readOverlayRecord(live.getMap(model), recordId),
-    { suppressDeletes: owed.suppressDeletes }
+  const held = new Set(ops.map((op) => op.seq));
+  const later = host.pendingOps().filter((op) => !held.has(op.seq));
+  const carried = suppressSupersededKeys(
+    carryUnackedOverlay(
+      owed.ops,
+      (model, recordId) => owedOverlay.get(`${model} ${recordId}`) ?? readOverlayRecord(live.getMap(model), recordId),
+      { suppressDeletes: owed.suppressDeletes }
+    ),
+    later
   );
   if (carried.length === 0) return 0;
   live.transact(() => {
@@ -15640,18 +17004,22 @@ function planFastForward(options) {
   if (target <= current) return { kind: "none", reason: "current" };
   const byEpoch = /* @__PURE__ */ new Map();
   for (const entry of options.sealed) byEpoch.set(entry.epoch, entry);
+  const discontinuities = options.sealed.filter(
+    (entry) => entry.baseDiscontinuity && entry.epoch >= current && entry.epoch < target
+  ).map((entry) => entry.epoch).sort((a, b) => a - b);
+  const last = discontinuities.length > 0 ? discontinuities[0] : target - 1;
   const steps = [];
-  for (let epoch = current; epoch < target; epoch++) {
+  for (let epoch = current; epoch <= last; epoch++) {
     const entry = byEpoch.get(epoch);
     if (!entry) return { kind: "reload", reason: "gap", epoch };
-    if (entry.baseDiscontinuity) {
-      return { kind: "reload", reason: "discontinuity", epoch };
-    }
     if (entry.download === void 0 || entry.download === null) {
       return { kind: "reload", reason: "unavailable", epoch };
     }
     steps.push({ epoch, download: entry.download });
   }
+  if (discontinuities.length > 0) {
+    return { kind: "converge", from: current, discontinuities, steps };
+  }
   return { kind: "apply", from: current, to: target, steps };
 }
 async function runFastForward(host, options) {
@@ -15660,6 +17028,14 @@ async function runFastForward(host, options) {
   if (plan.kind === "reload") {
     return { outcome: "reload", reason: plan.reason, epoch: plan.epoch };
   }
+  if (plan.kind === "converge") {
+    return {
+      outcome: "converge",
+      from: plan.from,
+      discontinuities: plan.discontinuities,
+      steps: plan.steps
+    };
+  }
   let applied;
   try {
     applied = await host.hold(() => applyFastForward(plan, host));
@@ -15697,6 +17073,10 @@ async function applyFastForward(plan, host) {
 }
 
 // src/models/format2ColdStart.ts
+function isGranted(sealed, epoch) {
+  const entry = sealed.find((each) => each.epoch === epoch);
+  return !!entry && entry.download !== void 0 && entry.download !== null;
+}
 function chainIsWhole(sealed, from, to) {
   const byEpoch = /* @__PURE__ */ new Map();
   for (const entry of sealed) byEpoch.set(entry.epoch, entry);
@@ -15722,6 +17102,15 @@ function planColdStart(input) {
   if (first === 1 && chainIsWhole(sealed, 1, reported)) {
     return { kind: "overlays", base: 1 };
   }
+  const start = Number.isInteger(base) && base > 0 ? base : 1;
+  const discontinuities = sealed.filter(
+    (entry) => entry.baseDiscontinuity && entry.epoch >= start && entry.epoch < reported
+  ).map((entry) => entry.epoch);
+  if (discontinuities.length > 0 && // Whole and granted up to the first flagged epoch, and no further: past it
+  // the base that is coming covers everything.
+  chainIsWhole(sealed, start, discontinuities[0]) && isGranted(sealed, discontinuities[0])) {
+    return { kind: "await-base", discontinuities };
+  }
   return { kind: "unavailable", reason: "no-base" };
 }
 async function runColdStart(host, plan, options = {}) {
@@ -15733,6 +17122,8 @@ async function runColdStart(host, plan, options = {}) {
       return true;
     case "unavailable":
       return false;
+    case "await-base":
+      return false;
     case "snapshot":
     case "overlays": {
       if (options.stale) await host.discard();
@@ -15753,11 +17144,69 @@ async function runColdStart(host, plan, options = {}) {
   }
 }
 
+// src/models/format2RangeReplacement.ts
+init_snapshotChunks();
+function planRangeReplacement(options) {
+  const { manifest, touched } = options;
+  const scope = options.localModels;
+  const inScope = (model) => scope === null || scope.includes(model);
+  const perModel = /* @__PURE__ */ new Map();
+  for (const chunk of manifest.chunks) {
+    if (!inScope(chunk.model)) continue;
+    const list = perModel.get(chunk.model);
+    if (list) list.push(chunk);
+    else perModel.set(chunk.model, [chunk]);
+  }
+  const touchedPerModel = /* @__PURE__ */ new Map();
+  for (const range of touched?.ranges ?? []) {
+    const list = touchedPerModel.get(range.model);
+    if (list) list.push(range);
+    else touchedPerModel.set(range.model, [range]);
+  }
+  const fetch = [];
+  const keep = [];
+  const order = new Map(manifest.chunks.map((chunk, index) => [chunk, index]));
+  for (const [model, chunks] of perModel) {
+    const ranges = touchedPerModel.get(model) ?? [];
+    for (let index = 0; index < chunks.length; index++) {
+      const chunk = chunks[index];
+      const coverage = {
+        after: index === 0 ? null : chunks[index - 1].lastId,
+        through: index === chunks.length - 1 ? null : chunk.lastId
+      };
+      if (touched === null || ranges.some((range) => meets(coverage, range))) {
+        fetch.push({ chunk, coverage });
+      } else {
+        keep.push(chunk);
+      }
+    }
+  }
+  fetch.sort((a, b) => order.get(a.chunk) - order.get(b.chunk));
+  keep.sort((a, b) => order.get(a) - order.get(b));
+  const absent = /* @__PURE__ */ new Set();
+  for (const model of scope ?? []) absent.add(model);
+  for (const model of touchedPerModel.keys()) {
+    if (inScope(model)) absent.add(model);
+  }
+  const pruneModels = [...absent].filter((model) => !perModel.has(model)).sort();
+  return { fetch, keep, pruneModels, full: touched === null };
+}
+function meets(coverage, range) {
+  if (coverage.through !== null && compareRecordIds(range.firstId, coverage.through) > 0) {
+    return false;
+  }
+  if (coverage.after !== null && compareRecordIds(range.lastId, coverage.after) <= 0) {
+    return false;
+  }
+  return true;
+}
+
 // src/models/format2OfflineReplay.ts
 var Y12 = __toESM(require("yjs"), 1);
 init_largeDocuments();
 init_format2Observer();
 var recordKey = (model, recordId) => `${model}\0${recordId}`;
+var offlineReplayRecordKey = recordKey;
 var OfflineConflictLedger = class {
   /** Latest touch per record per epoch, newest epoch last. */
   touches = /* @__PURE__ */ new Map();
@@ -15900,6 +17349,40 @@ function resolveOfflineReplay(options) {
   };
   for (const op of [...options.ops].sort((a, b) => a.seq - b.seq)) {
     const base = { model: op.model, recordId: op.recordId, op: op.op, ts: op.ts };
+    const ingest = options.ingest;
+    if (ingest && op.baseEpoch <= ingest.through) {
+      const presence = ingest.records.get(recordKey(op.model, op.recordId));
+      const verdict = presence ?? (ingest.scope === "all" ? "present" : void 0);
+      if (verdict === "present") {
+        ops.push(op);
+        notices.push({
+          ...base,
+          outcome: "kept-ambiguous",
+          reason: "bulkIngest",
+          epoch: ingest.through
+        });
+        continue;
+      }
+      if (verdict === "absent") {
+        if (op.op === "create") {
+          ops.push(op);
+          notices.push({
+            ...base,
+            outcome: "kept-ambiguous",
+            reason: "bulkIngest",
+            epoch: ingest.through
+          });
+          continue;
+        }
+        notices.push({
+          ...base,
+          outcome: "dropped",
+          reason: "bulkIngest",
+          epoch: ingest.through
+        });
+        continue;
+      }
+    }
     if (!ledger.covers(op.baseEpoch, currentEpoch)) {
       ops.push(op);
       notices.push({
@@ -16021,8 +17504,10 @@ function resolveOfflineReplay(options) {
 
 // src/browser.ts
 init_format2OfflineWindow();
+init_snapshotChunks();
 
 // src/utils/snapshotPartition.ts
+init_snapshotChunks();
 var DEFAULT_SNAPSHOT_PARTITION = {
   minBytes: 6 * 1024 * 1024,
   maxBytes: 12 * 1024 * 1024,
@@ -16188,6 +17673,19 @@ var SnapshotPartitioner = class {
   get pendingBytes() {
     return this.bufferBytes;
   }
+  /**
+   * Whether the buffer is a below-minimum range being carried forward (#3433).
+   *
+   * An incremental build walks only the ranges that changed, so it has to know
+   * when a range it re-cut closed short and merged into its SUCCESSOR: that
+   * successor is then part of the walk too, and cannot be reused by reference.
+   * Reading it off the partitioner rather than inferring it from the emitted
+   * chunks keeps one answer to "did this boundary move", in the object that
+   * decided it.
+   */
+  get carriedTail() {
+    return this.merging;
+  }
   take(count) {
     const taken = count === void 0 ? this.buffer : this.buffer.slice(0, count);
     const rest = count === void 0 ? [] : this.buffer.slice(count);