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

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");
@@ -1779,6 +1817,335 @@ var init_format2OfflineWindow = __esm({
   }
 });
 
+// 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.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;
+  }
+});
+
 // src/utils/overlaySql.ts
 function statementsFor(tables) {
   const cacheKey = `${tables.records}\0${tables.stringSetIndex}`;
@@ -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);
@@ -3545,26 +4132,142 @@ var init_format2RecordStoreAsync = __esm({
           (ops) => ops.commitLocalWrite(model, mutation, pending)
         );
       }
-      async applyChunk(model, entries, buildId, ordinal) {
-        const reply = await this.run(
-          "applyChunk",
-          () => this.host.dispatch({
-            kind: "applyChunk",
-            model,
-            entries: [...entries],
-            buildId,
-            ordinal
-          })
+      async applyChunk(model, entries, buildId, ordinal) {
+        const reply = await this.run(
+          "applyChunk",
+          () => this.host.dispatch({
+            kind: "applyChunk",
+            model,
+            entries: [...entries],
+            buildId,
+            ordinal
+          })
+        );
+        for (const entry of entries) {
+          if (this.cache.peek(model, entry.id)) {
+            await this.refreshRows(model, [entry.id]);
+          }
+        }
+        return reply.applied;
+      }
+      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 })
         );
-        for (const entry of entries) {
-          if (this.cache.peek(model, entry.id)) {
-            await this.refreshRows(model, [entry.id]);
-          }
+        const held = this.mirror?.discontinuityEpochs;
+        if (held && !held.includes(epoch)) {
+          this.refreshMirror({
+            discontinuityEpochs: [...held, epoch].sort((a, b) => a - b)
+          });
         }
-        return reply.applied;
       }
-      completedChunks(buildId) {
-        return this.host.dispatch({ kind: "completedChunks", buildId });
+      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(
@@ -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":
@@ -10265,6 +10997,7 @@ __export(browser_exports, {
   Format2RecordStoreAsync: () => Format2RecordStoreAsync,
   Format2RowCache: () => Format2RowCache,
   Format2StorageCapabilityError: () => Format2StorageCapabilityError,
+  INGEST_CHUNK_LIMITS: () => INGEST_CHUNK_LIMITS,
   InProcessFormat2StoreHost: () => InProcessFormat2StoreHost,
   LogLevel: () => LogLevel,
   Logger: () => Logger,
@@ -10308,6 +11041,7 @@ __export(browser_exports, {
   encodeOverlayMutation: () => encodeOverlayMutation,
   estimateMaterializedBytes: () => estimateMaterializedBytes,
   features: () => features,
+  foldFormat2Overlay: () => foldFormat2Overlay,
   followEpoch: () => followEpoch,
   format2ClientDDL: () => format2ClientDDL,
   format2EpochDocName: () => format2EpochDocName,
@@ -10330,6 +11064,7 @@ __export(browser_exports, {
   loadSchemaFromTomlString: () => loadSchemaFromTomlString,
   materializeOverlayRecord: () => materializeOverlayRecord,
   observeFormat2Overlay: () => observeFormat2Overlay,
+  offlineReplayRecordKey: () => offlineReplayRecordKey,
   offlineWindowStatus: () => offlineWindowStatus,
   overlayFieldKey: () => overlayFieldKey,
   overlayMarkerKey: () => overlayMarkerKey,
@@ -10338,6 +11073,7 @@ __export(browser_exports, {
   parseSnapshotChunkPath: () => parseSnapshotChunkPath,
   planColdStart: () => planColdStart,
   planFastForward: () => planFastForward,
+  planRangeReplacement: () => planRangeReplacement,
   planSnapshotHydration: () => planSnapshotHydration,
   probeStorageCapability: () => probeStorageCapability,
   projectOverlayEntry: () => projectOverlayEntry,
@@ -10353,6 +11089,8 @@ __export(browser_exports, {
   schemaToToml: () => schemaToToml,
   serveFormat2StoreHost: () => serveFormat2StoreHost,
   snapshotChunkPath: () => snapshotChunkPath,
+  statePendingOps: () => statePendingOps,
+  suppressSupersededKeys: () => suppressSupersededKeys,
   syncInferredMeta: () => syncInferredMeta,
   syncModelMeta: () => syncModelMeta,
   validateSnapshotManifest: () => validateSnapshotManifest,
@@ -11046,307 +11784,55 @@ var SqljsEngine = class _SqljsEngine extends SqliteQueryEngineBase {
           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}`
-    );
-  }
-}
-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 };
-}
-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;
-  }
-  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}`
-      );
-    }
+          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 +14044,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 +14081,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 +14143,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 +14151,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 +14185,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 +14209,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 +14241,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 +14252,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 +14281,7 @@ async function loadFormat2Snapshot(options) {
       repaired.add(chunk.model);
     }
   }
+  await store.completeBase(manifest.buildId);
   return {
     rows,
     chunks,
@@ -13730,7 +14289,8 @@ async function loadFormat2Snapshot(options) {
     refetched,
     models,
     skipped,
-    repaired: [...repaired]
+    repaired: [...repaired],
+    reused
   };
 }
 
@@ -13848,7 +14408,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 +14617,94 @@ 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.
+   */
+  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 +14888,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 +15106,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 +15151,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;
@@ -14666,6 +15345,23 @@ 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) {
     const connectedDoc = this.connectedDocuments.get(docId);
     if (!connectedDoc) {
@@ -14785,6 +15481,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),
@@ -14799,6 +15497,8 @@ async function initJsBaoCore(options, getEngine) {
       // from the room counts as applied.
       whenFormat2ProjectionSettled: docManager.whenFormat2ProjectionSettled.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 +15658,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;
@@ -15542,6 +16208,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 +16322,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 +16354,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 +16378,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 +16423,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 +16452,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 +16472,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 +16494,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 +16699,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 +16854,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 +17023,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);