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

package/dist/browser.cjs

@@ -226,7 +226,30 @@ var init_queryTypes = __esm({
 });
 
 // src/query/CursorManager.ts
-var base64Encode, base64Decode, CursorManager;
+function cursorSortAlias(fieldName) {
+  return `${CURSOR_SORT_ALIAS_PREFIX}${fieldName}`;
+}
+function cursorMintingRecord(row, aliasedFields) {
+  let folded;
+  for (const field of aliasedFields) {
+    const alias = cursorSortAlias(field);
+    if (!Object.prototype.hasOwnProperty.call(row, alias)) continue;
+    folded ??= { ...row };
+    folded[field] = row[alias];
+  }
+  return folded ?? row;
+}
+function stripCursorSortValues(row, aliasedFields) {
+  let stripped;
+  for (const field of aliasedFields) {
+    const alias = cursorSortAlias(field);
+    if (!Object.prototype.hasOwnProperty.call(row, alias)) continue;
+    stripped ??= { ...row };
+    delete stripped[alias];
+  }
+  return stripped ?? row;
+}
+var base64Encode, base64Decode, CURSOR_SORT_ALIAS_PREFIX, CursorManager;
 var init_CursorManager = __esm({
   "src/query/CursorManager.ts"() {
     "use strict";
@@ -249,6 +272,7 @@ var init_CursorManager = __esm({
         throw new Error("No base64 decoding available");
       }
     };
+    CURSOR_SORT_ALIAS_PREFIX = "_cursor:";
     CursorManager = class {
       /**
        * Encode cursor data to base64 string
@@ -292,18 +316,22 @@ var init_CursorManager = __esm({
         }
       }
       /**
-       * Generate cursor from a record and sort specification
+       * Generate cursor from a record and sort specification.
+       *
+       * A sort field the record does not carry — absent, `null`, or `undefined` —
+       * is encoded as an explicit JSON `null` (#3228). Absent and null are
+       * deliberately NOT distinguished: `json_extract` returns SQL NULL for both an
+       * absent path and a stored JSON null, and a per-column table stores an absent
+       * field as a NULL column, so the two are one value at the SQL layer on every
+       * engine. `null` rather than `undefined` because `JSON.stringify` drops a key
+       * whose value is `undefined`, and the payload's shape is the wire contract
+       * the Swift port reads.
        */
       static generateCursor(record, sortFields, direction) {
         const values = {};
         for (const field of sortFields) {
-          if (record.hasOwnProperty(field)) {
-            values[field] = record[field];
-          } else {
-            throw new Error(
-              `Cannot generate cursor: record missing sort field '${field}'`
-            );
-          }
+          const value = Object.prototype.hasOwnProperty.call(record, field) ? record[field] : void 0;
+          values[field] = value === void 0 ? null : value;
         }
         const cursorData = {
           values,
@@ -315,6 +343,28 @@ var init_CursorManager = __esm({
       /**
        * Build SQL pagination conditions based on cursor
        * Uses lexicographic ordering for stable pagination with multiple sort fields
+       *
+       * NULL-aware (#3228). SQLite orders NULL before every value, so absent and
+       * null sort values sit at the FRONT of an ascending output order and at the
+       * TAIL of a descending one — on the Cloudflare DO's SQLite, better-sqlite3
+       * and the Swift client's SQLite alike. That is the ratified ordering
+       * contract, which is why no ORDER BY changes here; what changes is that a
+       * cursor value of null no longer compiles to a comparison against a NULL
+       * bound parameter, which SQLite evaluates as UNKNOWN so the next page matched
+       * nothing. Per level, with the effective operator computed exactly as before:
+       *
+       *   - equality level, null value      → `field IS NULL`      (no parameter)
+       *   - `>` (nulls at the front), value → `field > ?`          (unchanged)
+       *   - `>` (nulls at the front), null  → `field IS NOT NULL`  (no parameter)
+       *   - `<` (nulls at the tail), value  → `(field < ? OR field IS NULL)`
+       *   - `<` (nulls at the tail), null   → the level matches nothing and is
+       *     dropped; the deeper tiebreak levels, whose equality parts are
+       *     `field IS NULL`, carry the walk through the null run.
+       *
+       * `id` is exempt: it is a non-null primary key on every engine, so it never
+       * receives `IS NULL` handling and the default `sort: {id}` pagination SQL
+       * stays byte-identical to what it was. So does every non-null `>` level, so
+       * an ascending page over an old-format cursor compiles exactly as before.
        */
       static buildPaginationConditions(cursor, currentSortFields, sortDirections, requestedDirection, fieldFormatter = (field) => field) {
         if (!this.arraysEqual(cursor.sortFields, currentSortFields)) {
@@ -329,27 +379,46 @@ var init_CursorManager = __esm({
         const params = [];
         const sortFields = cursor.sortFields;
         const direction = requestedDirection;
+        const nullable = (field) => field !== "id";
+        const isNull = (field) => nullable(field) && (cursor.values[field] === null || cursor.values[field] === void 0);
         for (let i = 0; i < sortFields.length; i++) {
           const fieldConditions = [];
           const fieldParams = [];
           for (let j = 0; j < i; j++) {
             const field = sortFields[j];
-            const value = cursor.values[field];
+            if (isNull(field)) {
+              fieldConditions.push(`${fieldFormatter(field)} IS NULL`);
+              continue;
+            }
             fieldConditions.push(`${fieldFormatter(field)} = ?`);
-            fieldParams.push(value);
+            fieldParams.push(cursor.values[field]);
           }
           const currentField = sortFields[i];
           const currentValue = cursor.values[currentField];
+          const currentSql = fieldFormatter(currentField);
           const fieldSortDir = sortDirections[i] ?? 1;
           const forwardOp = fieldSortDir === 1 ? ">" : "<";
           const operator = direction === 1 ? forwardOp : forwardOp === ">" ? "<" : ">";
-          fieldConditions.push(`${fieldFormatter(currentField)} ${operator} ?`);
-          fieldParams.push(currentValue);
+          if (isNull(currentField)) {
+            if (operator === "<") {
+              continue;
+            }
+            fieldConditions.push(`${currentSql} IS NOT NULL`);
+          } else if (operator === "<" && nullable(currentField)) {
+            const disjunction = `${currentSql} < ? OR ${currentSql} IS NULL`;
+            fieldConditions.push(
+              fieldConditions.length > 0 ? `(${disjunction})` : disjunction
+            );
+            fieldParams.push(currentValue);
+          } else {
+            fieldConditions.push(`${currentSql} ${operator} ?`);
+            fieldParams.push(currentValue);
+          }
           const levelCondition = fieldConditions.join(" AND ");
           conditions.push(`(${levelCondition})`);
           params.push(...fieldParams);
         }
-        const sql = `(${conditions.join(" OR ")})`;
+        const sql = conditions.length > 0 ? `(${conditions.join(" OR ")})` : "(1 = 0)";
         return { sql, params };
       }
       /**
@@ -580,7 +649,14 @@ var init_DocumentQueryTranslator = __esm({
           orderClause.fields,
           orderClause.directions
         );
-        const selectClause = this.buildSelectClause(options?.projection);
+        const cursorSortValueFields = this.cursorSortValueFields(
+          options?.projection,
+          orderClause.fields
+        );
+        const selectClause = this.buildSelectClause(
+          options?.projection,
+          cursorSortValueFields
+        );
         let sql = `SELECT ${selectClause} FROM ${this.quotedTableName}`;
         const params = [];
         const conditions = [];
@@ -610,7 +686,8 @@ var init_DocumentQueryTranslator = __esm({
           sql,
           params,
           sortFields: orderClause.fields,
-          sortDirections: orderClause.directions
+          sortDirections: orderClause.directions,
+          cursorSortValueFields
         };
       }
       /**
@@ -999,10 +1076,36 @@ var init_DocumentQueryTranslator = __esm({
             );
         }
       }
+      /**
+       * The sort fields whose values this query has to select under an internal
+       * alias: the ones an INCLUSION projection omits that have a main-table
+       * column (#3228). Stringset fields have no such column — they are populated
+       * post-query — so they are skipped the way the projection skips them.
+       *
+       * Reported on the `TranslatedQuery` so `BaseModel.query` folds and strips
+       * exactly the columns this SELECT added — never a column the caller asked
+       * for, and never a schema field whose name happens to look like an alias.
+       */
+      cursorSortValueFields(projection, sortFields) {
+        if (!projection || Object.keys(projection).length === 0) return [];
+        const included = new Set(
+          Object.entries(projection).filter(([, include]) => include === 1).map(([field]) => field)
+        );
+        if (included.size === 0) return [];
+        return sortFields.filter(
+          (field) => !SYSTEM_FIELDS.has(field) && !included.has(field) && this.schema.has(field) && this.schema.get(field)?.type !== "stringset"
+        );
+      }
       /**
        * Build SELECT clause based on projection
+       *
+       * `aliasedSortFields` names the sort fields this query carries under an
+       * internal alias because the projection omits them
+       * ({@link cursorSortValueFields}, #3228) so the cursor carries the row's real
+       * value rather than a false null; `BaseModel.query` strips those columns
+       * before the rows leave it, so response shapes are unchanged.
        */
-      buildSelectClause(projection) {
+      buildSelectClause(projection, aliasedSortFields) {
         if (!projection || Object.keys(projection).length === 0) {
           return "*";
         }
@@ -1031,6 +1134,13 @@ var init_DocumentQueryTranslator = __esm({
             includeFields.unshift("id");
           }
           const quoted = includeFields.map((field) => this.getQuotedField(field));
+          for (const field of aliasedSortFields ?? []) {
+            quoted.push(
+              `${this.getQuotedField(field)} AS ${quoteIdentifier(
+                cursorSortAlias(field)
+              )}`
+            );
+          }
           return quoted.join(", ");
         } else if (hasExcludes) {
           const allFields = Array.from(this.schema.keys());
@@ -1271,6 +1381,19 @@ function buildUniqueKey(recordData, fields) {
   }
   return keyParts.join("|");
 }
+function removeUniqueIndexEntriesForRecordId(yDoc, modelName, constraintNames, recordId) {
+  let removed = 0;
+  for (const constraintName of constraintNames) {
+    const indexMap = yDoc.getMap(uniqueIndexMapName(modelName, constraintName));
+    for (const key of Array.from(indexMap.keys())) {
+      if (indexMap.get(key) === recordId) {
+        indexMap.delete(key);
+        removed++;
+      }
+    }
+  }
+  return removed;
+}
 function uniqueIndexMapName(modelName, constraintName) {
   return `_uniqueIdx_${modelName}_${constraintName}`;
 }
@@ -1803,6 +1926,15 @@ var init_format2OfflineWindow = __esm({
       lastSyncAt;
       windowDays;
       overdueMs;
+      /**
+       * The same four numbers, under the name the Swift client puts them
+       * (`JsBaoError.details`).
+       *
+       * Additive, beside the properties this error has always carried: an app
+       * running both clients reads one shape, and one that only reads the
+       * properties is unaffected.
+       */
+      details;
       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.`
@@ -1812,6 +1944,12 @@ var init_format2OfflineWindow = __esm({
         this.lastSyncAt = status.lastSyncAt;
         this.windowDays = status.windowDays;
         this.overdueMs = status.overdueMs;
+        this.details = {
+          documentId,
+          lastSyncAt: status.lastSyncAt,
+          windowDays: status.windowDays,
+          overdueMs: status.overdueMs
+        };
       }
     };
   }
@@ -2157,6 +2295,12 @@ function statementsFor(tables) {
   const members = tables.stringSetIndex;
   const statements = {
     deleteRecord: `DELETE FROM ${records} WHERE _type = ? AND _id = ?`,
+    // Every create through the record door carries `_replace`, so this runs
+    // once per record. It is served by the member table's `(_type, _record_id,
+    // field)` index — `idx_ss_type_record_field` on the server,
+    // `idx_<members>_trf` on a client (#3688). Without an index whose second
+    // column is `_record_id` the planner narrows on `_type` alone and this
+    // walks every member row of the model, per record.
     deleteAllMembers: `DELETE FROM ${members} WHERE _type = ? AND _record_id = ?`,
     deleteMember: `DELETE FROM ${members} WHERE _type = ? AND _record_id = ? AND field = ? AND value = ?`,
     insertMember: `INSERT OR IGNORE INTO ${members} (_record_id, _type, field, value) VALUES (?, ?, ?, ?)`,
@@ -2259,7 +2403,13 @@ function format2ClientDDL(docId) {
 )`,
     `CREATE INDEX IF NOT EXISTS idx_${records}_type ON ${records}(_type)`,
     `CREATE INDEX IF NOT EXISTS idx_${stringSetIndex}_tfv ON ${stringSetIndex}(_type, field, value)`,
-    `CREATE INDEX IF NOT EXISTS idx_${stringSetIndex}_tfr ON ${stringSetIndex}(_type, field, _record_id)`,
+    // `_record_id` DIRECTLY after `_type` (#3688): the shared fold's
+    // per-record member delete (`_replace`, and every tombstone) and the
+    // coverage delete both key on that pair, and the retired
+    // `(_type, field, _record_id)` shape left the planner narrowing on `_type`
+    // alone — a walk of the model's whole member table per record. The old
+    // name is dropped in `init()`, not here, so this list stays creation-only.
+    `CREATE INDEX IF NOT EXISTS idx_${stringSetIndex}_trf ON ${stringSetIndex}(_type, _record_id, field)`,
     `CREATE TABLE IF NOT EXISTS _epoch (
   doc_id TEXT PRIMARY KEY,
   epoch INTEGER NOT NULL DEFAULT 0,
@@ -2307,16 +2457,109 @@ function format2ClientDDL(docId) {
   doc_id TEXT NOT NULL,
   epoch INTEGER NOT NULL,
   PRIMARY KEY (doc_id, epoch)
-)`
+)`,
+    // The judgement an epoch move DEFERRED and has not made yet. Durable,
+    // written in the same commit as the epoch mark, because the mark moves
+    // first: without this a restart in between reads as a client that is
+    // perfectly current and whose unacknowledged writes are simply missing
+    // from the overlay, so the bind puts them back by key presence alone and
+    // publishes an offline write recency would have dropped.
+    //
+    // Swift's columns and meanings (`Format2RecordStore.swift`), keyed by
+    // CLIENT as well as document: tabs share this database, sequence spaces
+    // are per client, and a note keyed by document alone would be overwritten
+    // by the second tab and read by a restarted one against sequences that
+    // were never its own.
+    DEFERRED_REPLAY_DDL
   ];
 }
+function toDeferredReplayNote(rows) {
+  if (rows.length === 0) return null;
+  const row = rows[0];
+  return {
+    throughSeq: Number(row.through_seq),
+    fromEpoch: Number(row.from_epoch),
+    toEpoch: Number(row.to_epoch),
+    kind: String(row.kind)
+  };
+}
+function format2DocumentIdFromTableName(table) {
+  const prefix = "records_f2_";
+  if (!table.startsWith(prefix)) return null;
+  const hex = table.slice(prefix.length);
+  if (hex.length === 0 || hex.length % 4 !== 0 || !/^[0-9a-f]+$/.test(hex)) {
+    return null;
+  }
+  let docId = "";
+  for (let at = 0; at < hex.length; at += 4) {
+    docId += String.fromCharCode(parseInt(hex.slice(at, at + 4), 16));
+  }
+  return docId;
+}
+function listTables(sql) {
+  return Array.from(
+    sql.exec("SELECT name FROM sqlite_master WHERE type = 'table'")
+  ).map((row) => String(row.name));
+}
+function tableColumns(sql, table) {
+  try {
+    return Array.from(sql.exec(`PRAGMA table_info(${quote(table)})`)).map(
+      (row) => String(row.name)
+    );
+  } catch {
+    return [];
+  }
+}
+function countRows(sql, table, column, value) {
+  const rows = Array.from(
+    sql.exec(
+      `SELECT count(*) AS n FROM ${quote(table)} WHERE ${quote(column)} = ?`,
+      value
+    )
+  );
+  return rows.length > 0 ? Number(rows[0].n ?? 0) : 0;
+}
+function junctionForeignKeyOf(parent) {
+  const model = parent.startsWith("model_") ? parent.slice("model_".length) : parent;
+  return `${model}_id`;
+}
+function junctionTablesOf(parent, tables, columnsOf) {
+  const found = [];
+  const foreignKey = junctionForeignKeyOf(parent);
+  for (const table of tables) {
+    if (!table.startsWith(`${parent}_`)) continue;
+    const columns = columnsOf.get(table) ?? [];
+    if (!columns.includes("value")) continue;
+    if (columns.includes("_meta_doc_id")) continue;
+    if (!columns.includes(foreignKey)) continue;
+    found.push({ table, foreignKey });
+  }
+  return found;
+}
+function countStoredDocuments(sql) {
+  const found = /* @__PURE__ */ new Set();
+  try {
+    for (const row of sql.exec("SELECT doc_id FROM _epoch")) {
+      found.add(String(row.doc_id));
+    }
+  } catch {
+  }
+  for (const table of listTables(sql)) {
+    const docId = format2DocumentIdFromTableName(table);
+    if (docId !== null) found.add(docId);
+  }
+  return Array.from(found);
+}
+function quote(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
 function normalizeBinding(value) {
   if (value === void 0 || value === null) return null;
   if (typeof value === "boolean") return value ? 1 : 0;
   if (typeof value === "number") return value;
   return String(value);
 }
-var FORMAT2_LEGACY_CLIENT_ID, PENDING_OPS_DDL, Format2ModelNotHydratedError, Format2RecordStore;
+var FORMAT2_LEGACY_CLIENT_ID, PENDING_OPS_DDL, DEFERRED_REPLAY_DDL, Format2ModelNotHydratedError, Format2RecordStore;
 var init_format2RecordStore = __esm({
   "src/models/format2RecordStore.ts"() {
     "use strict";
@@ -2339,6 +2582,15 @@ var init_format2RecordStore = __esm({
   from_client_id TEXT,
   from_seq INTEGER,
   PRIMARY KEY (doc_id, client_id, seq)
+)`;
+    DEFERRED_REPLAY_DDL = `CREATE TABLE IF NOT EXISTS _deferred_replay (
+  doc_id TEXT NOT NULL,
+  client_id TEXT NOT NULL,
+  through_seq INTEGER NOT NULL,
+  from_epoch INTEGER NOT NULL,
+  to_epoch INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  PRIMARY KEY (doc_id, client_id)
 )`;
     Format2ModelNotHydratedError = class extends Error {
       constructor(model, hydrated) {
@@ -2352,7 +2604,7 @@ var init_format2RecordStore = __esm({
       /** Stable across builds, so an app can branch on it rather than on text. */
       code = "FORMAT2_MODEL_NOT_HYDRATED";
     };
-    Format2RecordStore = class {
+    Format2RecordStore = class _Format2RecordStore {
       constructor(sql, docId, clientId) {
         this.sql = sql;
         this.docId = docId;
@@ -2404,6 +2656,9 @@ var init_format2RecordStore = __esm({
       /** Create the local schema. Safe to call on every open. */
       init() {
         for (const ddl of format2ClientDDL(this.docId)) this.sql.exec(ddl);
+        this.sql.exec(
+          `DROP INDEX IF EXISTS idx_${this.tables.stringSetIndex}_tfr`
+        );
         const columns = Array.from(this.sql.exec("PRAGMA table_info(_epoch)")).map(
           (row) => String(row.name)
         );
@@ -2915,6 +3170,34 @@ var init_format2RecordStore = __esm({
             this.docId,
             ...wanted
           );
+          for (const note of this.rows(
+            `SELECT client_id, through_seq, from_epoch, to_epoch, kind
+           FROM _deferred_replay
+          WHERE doc_id = ? AND client_id IN (${placeholders})`,
+            this.docId,
+            ...wanted
+          )) {
+            const from2 = String(note.client_id);
+            const throughSeq = Number(note.through_seq);
+            let covered = 0;
+            for (const op of adopted) {
+              if (op.fromClientId === from2 && op.fromSeq <= throughSeq) {
+                covered = Math.max(covered, op.seq);
+              }
+            }
+            if (covered === 0) continue;
+            this.noteDeferredReplay({
+              throughSeq: covered,
+              fromEpoch: Number(note.from_epoch),
+              toEpoch: Number(note.to_epoch),
+              kind: String(note.kind)
+            });
+          }
+          this.sql.exec(
+            `DELETE FROM _deferred_replay WHERE doc_id = ? AND client_id IN (${placeholders})`,
+            this.docId,
+            ...wanted
+          );
           return adopted;
         });
       }
@@ -2925,11 +3208,91 @@ var init_format2RecordStore = __esm({
           this.docId
         );
       }
-      setEpoch(epoch) {
+      /**
+       * Move the epoch mark, and settle this client's deferred judgement with it
+       * (#3755).
+       *
+       * ONE transaction, which is the Swift contract and the reason the note is
+       * not a second write after the mark: the mark moving without the note is
+       * exactly the state a restart cannot tell from "nothing is owed", and it is
+       * the state this child exists to make unreachable.
+       *
+       * With a note, it is upserted by the widening rule below. WITHOUT one — an
+       * ordinary seal, or the bind's upward bump — an existing note's target is
+       * carried forward to the epoch just joined, so an in-session seal after a
+       * deferral leaves the note current instead of naming an epoch the store has
+       * already passed. A client with no note is untouched.
+       */
+      setEpoch(epoch, options = {}) {
+        this.sql.transaction(() => {
+          this.sql.exec(
+            "UPDATE _epoch SET epoch = ? WHERE doc_id = ?",
+            epoch,
+            this.docId
+          );
+          if (options.deferredReplay) {
+            this.noteDeferredReplay(options.deferredReplay);
+            return;
+          }
+          const clientId = this.clientIdentity();
+          if (clientId === null) return;
+          this.sql.exec(
+            `UPDATE _deferred_replay SET to_epoch = MAX(to_epoch, ?)
+           WHERE doc_id = ? AND client_id = ?`,
+            epoch,
+            this.docId,
+            clientId
+          );
+        });
+      }
+      // ── The deferred judgement (#3755) ────────────────────────────────
+      /**
+       * Record that this client owes a judgement over `note`'s span. Idempotent.
+       *
+       * A second deferral WIDENS the first rather than replacing it (Swift's rule,
+       * `noteDeferredReplay`): `MAX(through_seq)`, `MIN(from_epoch)`,
+       * `MAX(to_epoch)`, so one note covers both debts and neither is forgotten.
+       * `kind` is replaced, because it is not a span.
+       */
+      noteDeferredReplay(note) {
+        this.sql.exec(
+          `INSERT INTO _deferred_replay
+         (doc_id, client_id, through_seq, from_epoch, to_epoch, kind)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(doc_id, client_id) DO UPDATE SET
+         through_seq = MAX(through_seq, ?),
+         from_epoch = MIN(from_epoch, ?),
+         to_epoch = MAX(to_epoch, ?),
+         kind = ?`,
+          this.docId,
+          this.client(),
+          note.throughSeq,
+          note.fromEpoch,
+          note.toEpoch,
+          note.kind,
+          note.throughSeq,
+          note.fromEpoch,
+          note.toEpoch,
+          note.kind
+        );
+      }
+      /** The judgement THIS client owes, or `null`. Never a sibling tab's. */
+      deferredReplay() {
+        return toDeferredReplayNote(
+          this.rows(
+            `SELECT through_seq, from_epoch, to_epoch, kind FROM _deferred_replay
+          WHERE doc_id = ? AND client_id = ?`,
+            this.docId,
+            this.client()
+          )
+        );
+      }
+      /** The judgement has been made: this client's note only. */
+      clearDeferredReplay() {
         this.sql.exec(
-          "UPDATE _epoch SET epoch = ? WHERE doc_id = ?",
-          epoch,
-          this.docId
+          "DELETE FROM _deferred_replay WHERE doc_id = ? AND client_id = ?",
+          this.docId,
+          this.client()
         );
       }
       lastSyncAt() {
@@ -3320,6 +3683,143 @@ var init_format2RecordStore = __esm({
         }
         return doomed.length;
       }
+      // ── Purging one document, or all of them (#3754) ──────────────────
+      /**
+       * Remove every trace of `docId` from the database `sql` runs on.
+       *
+       * The Swift client has had this since #3436 (`Format2RecordStore.purge`);
+       * the JS store had nothing, so `documents.evict`,
+       * `closeDocument({ evictLocal })` and `logout({ wipeLocal })` all left a
+       * large document's rows, its unacknowledged writes and its projected query
+       * rows exactly where they were.
+       *
+       * Static rather than an instance method for the same reason Swift's is: a
+       * purge outlives the store it is about. Nothing here needs the document's
+       * client id, its scope or its hydration state, and constructing an instance
+       * would mean running `init()` — creating the very tables this is about to
+       * drop — on a database that may never have held them.
+       *
+       * ### What is discovered, and why it is not a list
+       *
+       * Every table is found by SHAPE:
+       *
+       * - a `_meta_doc_id` column makes a table a DERIVED query table, one row per
+       *   record of some document;
+       * - a `doc_id` column makes it one of the shared bookkeeping tables
+       *   (`_epoch`, `_pending_ops`, `_client_acks`, `_snapshot_load`,
+       *   `_snapshot_base`, `_discontinuities`, `_query_projection`);
+       * - `records_f2_{hex}` and `stringset_index_f2_{hex}` are the document's own.
+       *
+       * A list would have to be kept in step with every sibling that adds a table
+       * — #3755's `_deferred_replay` is one — and the first one forgotten is local
+       * data left behind with a report saying it was removed. Swift discovers the
+       * derived tables by shape for exactly this reason
+       * (`Format2RecordStore.swift:1370-1379`).
+       *
+       * ### The one ordering that matters
+       *
+       * A projected string-set junction table is `{table}_{field}` with columns
+       * `(id, {model}_id, value)` and NO document column
+       * (`sqliteQueryEngine.ts:213-232`): its rows can only be reached through
+       * their parent's ids. So the member rows go FIRST, keyed off a subquery over
+       * the parents, and the parents after. `deleteByDocumentId` has these the
+       * other way round — it deletes the parent rows and then runs a subquery over
+       * the rows it has just deleted, which matches nothing — so this does not use
+       * it (finding 3754-SO-07; #3756 owns that path).
+       */
+      static purge(sql, docId) {
+        return sql.transaction(() => {
+          const tables = listTables(sql);
+          if (!tables.includes("_epoch")) {
+            return { nothingStored: true, pendingOps: 0, remainingDocuments: 0 };
+          }
+          const pendingOps = tables.includes("_pending_ops") ? countRows(sql, "_pending_ops", "doc_id", docId) : 0;
+          const derived = [];
+          const bookkeeping = [];
+          const columnsOf = /* @__PURE__ */ new Map();
+          for (const table of tables) {
+            const columns = tableColumns(sql, table);
+            columnsOf.set(table, columns);
+            if (columns.includes("_meta_doc_id")) derived.push(table);
+            else if (columns.includes("doc_id")) bookkeeping.push(table);
+          }
+          for (const parent of derived) {
+            for (const junction of junctionTablesOf(parent, tables, columnsOf)) {
+              sql.exec(
+                `DELETE FROM ${quote(junction.table)} WHERE ${quote(
+                  junction.foreignKey
+                )} IN (SELECT ${quote("id")} FROM ${quote(
+                  parent
+                )} WHERE ${quote("_meta_doc_id")} = ?)`,
+                docId
+              );
+              sql.exec(
+                `DELETE FROM ${quote(junction.table)} WHERE ${quote(
+                  junction.foreignKey
+                )} NOT IN (SELECT ${quote("id")} FROM ${quote(parent)})`
+              );
+            }
+          }
+          for (const parent of derived) {
+            sql.exec(
+              `DELETE FROM ${quote(parent)} WHERE ${quote("_meta_doc_id")} = ?`,
+              docId
+            );
+          }
+          for (const table of bookkeeping) {
+            sql.exec(`DELETE FROM ${quote(table)} WHERE ${quote("doc_id")} = ?`, docId);
+          }
+          const own = format2TableNames(docId);
+          sql.exec(`DROP TABLE IF EXISTS ${quote(own.records)}`);
+          sql.exec(`DROP TABLE IF EXISTS ${quote(own.stringSetIndex)}`);
+          return {
+            pendingOps,
+            remainingDocuments: countStoredDocuments(sql).length
+          };
+        });
+      }
+      /** `_pending_ops` rows for `docId`, across every client that wrote one. */
+      static pendingOpCount(sql, docId) {
+        try {
+          return countRows(sql, "_pending_ops", "doc_id", docId);
+        } catch {
+          return 0;
+        }
+      }
+      /** Every large document this database holds, from `_epoch` and from names. */
+      static storedDocuments(sql) {
+        return countStoredDocuments(sql);
+      }
+      /**
+       * Purge every document this database holds except `keep` (#3754).
+       *
+       * Unforced, a document whose store still holds unacknowledged writes is
+       * KEPT and reported: a wipe is not a licence to drop a write the app was
+       * told had been saved. Documents are enumerated from `_epoch` AND from the
+       * `records_f2_%` table names, so a store left behind by a build before this
+       * fix — tables with no `_epoch` row — is reached too (finding R3).
+       */
+      static purgeAll(sql, options = {}) {
+        const keep = new Set(options.keep ?? []);
+        const purged = [];
+        const kept = [];
+        for (const docId of countStoredDocuments(sql)) {
+          if (keep.has(docId)) {
+            kept.push({ docId, reason: "keep" });
+            continue;
+          }
+          if (options.force !== true) {
+            const pendingOps = _Format2RecordStore.pendingOpCount(sql, docId);
+            if (pendingOps > 0) {
+              kept.push({ docId, reason: "pending", pendingOps });
+              continue;
+            }
+          }
+          _Format2RecordStore.purge(sql, docId);
+          purged.push(docId);
+        }
+        return { purged, kept };
+      }
       /**
        * Throw away a merged view that cannot be repaired (#2816, behavior 12).
        *
@@ -3567,6 +4067,18 @@ var init_format2Observer = __esm({
 });
 
 // src/models/format2RecordStoreAsync.ts
+function widenDeferredReplay(held, note, epoch) {
+  if (!note) {
+    return held === null ? null : { ...held, toEpoch: Math.max(held.toEpoch, epoch) };
+  }
+  if (held === null) return { ...note };
+  return {
+    throughSeq: Math.max(held.throughSeq, note.throughSeq),
+    fromEpoch: Math.min(held.fromEpoch, note.fromEpoch),
+    toEpoch: Math.max(held.toEpoch, note.toEpoch),
+    kind: note.kind
+  };
+}
 function isFormat2RecordStoreAsync(value) {
   return value instanceof Format2RecordStoreAsync;
 }
@@ -3872,11 +4384,30 @@ var init_format2RecordStoreAsync = __esm({
         const store = this.direct();
         return store ? store.epoch() : this.mirrored().epoch;
       }
-      setEpoch(epoch) {
+      /**
+       * Move the epoch mark, with the judgement one deferred move owes (#3755).
+       *
+       * The note is settled in the STORE's transaction, not beside it, so a worker
+       * host commits the pair or neither — which is the whole point of the note.
+       */
+      setEpoch(epoch, options = {}) {
         const store = this.direct();
-        if (store) store.setEpoch(epoch);
-        else this.mirrored().epoch = epoch;
-        if (!store) this.sendMark({ kind: "setEpoch", epoch });
+        if (store) {
+          store.setEpoch(epoch, options);
+          return;
+        }
+        const marks = this.mirrored();
+        marks.epoch = epoch;
+        marks.deferredReplay = widenDeferredReplay(
+          marks.deferredReplay,
+          options.deferredReplay,
+          epoch
+        );
+        this.sendMark({
+          kind: "setEpoch",
+          epoch,
+          ...options.deferredReplay ? { deferredReplay: options.deferredReplay } : {}
+        });
       }
       ackedSeq() {
         const store = this.direct();
@@ -3928,6 +4459,39 @@ var init_format2RecordStoreAsync = __esm({
         const store = this.direct();
         return store ? store.discontinuityEpochs() : [...this.mirrored().discontinuityEpochs];
       }
+      /**
+       * The judgement this client owes and has not made (#3755), or `null`.
+       *
+       * Synchronous, because every sequence claim consults it: a frame that
+       * claimed a covered sequence would have the server acknowledge — and this
+       * client prune — a write whose content is on no frame at all.
+       */
+      deferredReplay() {
+        const store = this.direct();
+        return store ? store.deferredReplay() : this.mirrored().deferredReplay;
+      }
+      /** Record that a judgement is owed, durably, before the move it covers. */
+      async noteDeferredReplay(note) {
+        await this.run(
+          "noteDeferredReplay",
+          () => this.host.dispatch({ kind: "noteDeferredReplay", note })
+        );
+        this.refreshMirror({
+          deferredReplay: widenDeferredReplay(
+            this.mirror?.deferredReplay ?? null,
+            note,
+            note.toEpoch
+          )
+        });
+      }
+      /** The judgement has been made: forget the note. */
+      async clearDeferredReplay() {
+        await this.run(
+          "clearDeferredReplay",
+          () => this.host.dispatch({ kind: "clearDeferredReplay" })
+        );
+        this.refreshMirror({ deferredReplay: null });
+      }
       /** Whether the base this view is on finished loading (#3435). */
       baseComplete() {
         const store = this.direct();
@@ -4736,7 +5300,10 @@ function readFormat2StoreMarks(store) {
     // #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
+    baseComplete: store.baseState().base?.complete ?? false,
+    // #3755 — read on the same round trip as the rest, because the claim path
+    // reads it synchronously off the mirror.
+    deferredReplay: store.deferredReplay()
   };
 }
 function dispatchFormat2StoreCommand(store, sql, command) {
@@ -4757,7 +5324,10 @@ function run(store, sql, command) {
       return Number.isFinite(epoch) ? epoch : null;
     }
     case "setEpoch":
-      return store.setEpoch(command.epoch);
+      return store.setEpoch(
+        command.epoch,
+        command.deferredReplay ? { deferredReplay: command.deferredReplay } : {}
+      );
     case "noteSync":
       return store.noteSync(command.at, command.windowDays);
     case "noteOfflineWindow":
@@ -4840,6 +5410,10 @@ function run(store, sql, command) {
       return store.beginBase(command.buildId, command.epoch);
     case "completeBase":
       return store.completeBase(command.buildId);
+    case "noteDeferredReplay":
+      return store.noteDeferredReplay(command.note);
+    case "clearDeferredReplay":
+      return store.clearDeferredReplay();
     case "noteDiscontinuity":
       return store.noteDiscontinuity(command.epoch);
     case "clearDiscontinuities":
@@ -4853,6 +5427,22 @@ function run(store, sql, command) {
       forgetQueryProjection(sql, store.documentId());
       return void 0;
     }
+    case "purge": {
+      const docId = store.documentId();
+      return sql.transaction(() => {
+        const pendingOps = Format2RecordStore.pendingOpCount(sql, docId);
+        if (!command.force && pendingOps > 0) {
+          return { purged: false, reason: "pending", pendingOps };
+        }
+        const report = Format2RecordStore.purge(sql, docId);
+        return {
+          purged: true,
+          ...report.nothingStored ? { nothingStored: true } : {},
+          pendingOps: report.pendingOps,
+          remainingDocuments: report.remainingDocuments
+        };
+      });
+    }
     case "projectionMark": {
       if (command.op === "is") {
         return command.model === void 0 ? false : queryProjectionIsCurrent(sql, command.docId, command.model);
@@ -4876,6 +5466,7 @@ function run(store, sql, command) {
 var init_format2StoreDispatcher = __esm({
   "src/models/format2StoreDispatcher.ts"() {
     "use strict";
+    init_format2RecordStore();
     init_format2QueryProjection();
   }
 });
@@ -5216,6 +5807,14 @@ var init_OrmContext = __esm({
       globalDefaultDocId = void 0;
       defaultDocChangedListeners = /* @__PURE__ */ new Set();
       modelDocMappingChangedListeners = /* @__PURE__ */ new Set();
+      /**
+       * Told when a local write on a large document was refused because the
+       * document is past its offline window (#3758).
+       *
+       * Per instance, like every other listener set here (#3039): two `initJsBao`
+       * instances in one process must not hear each other's refusals.
+       */
+      format2WriteRefusedListeners = /* @__PURE__ */ new Set();
       /**
        * Format-2 ("large document", #2816) record stores by document id.
        *
@@ -5523,6 +6122,35 @@ var init_OrmContext = __esm({
         this.modelDocMappingChangedListeners.add(listener);
         return () => this.modelDocMappingChangedListeners.delete(listener);
       }
+      /** Hear every write this instance's documents refuse past their window. */
+      onFormat2WriteRefused(listener) {
+        this.format2WriteRefusedListeners.add(listener);
+        return () => this.format2WriteRefusedListeners.delete(listener);
+      }
+      /**
+       * Tell them, and swallow what they throw.
+       *
+       * A listener is application code, and a write's outcome is decided by the
+       * window and not by whoever was listening: a handler that throws must
+       * neither change what the write throws nor stop the next handler
+       * (#3758, behavior 6).
+       *
+       * Over a SNAPSHOT of the set, so one report reaches each listener exactly
+       * once however the handlers subscribe and unsubscribe while it is being
+       * delivered. A `Set` visits an element re-added during its own iteration,
+       * so a handler that resubscribes itself would otherwise hear the same
+       * refusal again — and one that does so unconditionally would loop for ever,
+       * never letting the write's rejection reach its caller (finding 3758-C02).
+       */
+      reportFormat2WriteRefused(event) {
+        for (const listener of [...this.format2WriteRefusedListeners]) {
+          if (!this.format2WriteRefusedListeners.has(listener)) continue;
+          try {
+            listener(event);
+          } catch {
+          }
+        }
+      }
       /** Drop the model→document defaults that point at a disconnected document. */
       clearMappingsForDocId(docId) {
         const toRemove = [];
@@ -5588,6 +6216,7 @@ var init_OrmContext = __esm({
         this.globalDefaultDocId = void 0;
         this.defaultDocChangedListeners.clear();
         this.modelDocMappingChangedListeners.clear();
+        this.format2WriteRefusedListeners.clear();
         this.format2Documents.clear();
         this.format2Transitions.clear();
         this.documentIndexingWork.clear();
@@ -7125,6 +7754,41 @@ var init_BaseModel = __esm({
           resolveOrmContext(this).getFormat2StoreAsync(docId)?.assertReadable();
         }
       }
+      /**
+       * The one gate every local write on a large document passes (#3758).
+       *
+       * Two doors reach it — `save()` and `delete()` — and both have to refuse
+       * for the same reasons, report the same way and throw the same error. Two
+       * copies of "report, log, then throw" is two chances for them to drift, so
+       * the sequence is stated once, here, mirroring the single boundary Swift
+       * keeps in `Format2WritePath`.
+       *
+       * Runs BEFORE anything is planned or committed, so a refused write leaves
+       * no merged row and no pending op behind; the report reaches the listeners
+       * synchronously, before the rejection reaches the caller.
+       */
+      static assertFormat2Writable(docId, modelName, recordId, store) {
+        store.assertReadable();
+        try {
+          assertWithinOfflineWindow(docId, store);
+        } catch (error) {
+          if (!(error instanceof DocumentOfflineWindowError)) throw error;
+          Logger.warn(
+            "[format2] write refused: past the offline window \u2014",
+            docId,
+            modelName,
+            recordId,
+            error.code
+          );
+          resolveOrmContext(this).reportFormat2WriteRefused({
+            documentId: docId,
+            model: modelName,
+            recordId,
+            error
+          });
+          throw error;
+        }
+      }
       /**
        * Build an instance already holding its merged-view row (#3429).
        *
@@ -8923,8 +9587,12 @@ var init_BaseModel = __esm({
         }
         const format2Store = modelConstructor.getFormat2StoreAsync(targetDocId);
         if (format2Store) {
-          format2Store.assertReadable();
-          assertWithinOfflineWindow(targetDocId, format2Store);
+          this.constructor.assertFormat2Writable(
+            targetDocId,
+            modelName,
+            this.id,
+            format2Store
+          );
           const target = await this.constructor.resolveFormat2Target(
             targetDocId,
             modelName,
@@ -9698,8 +10366,12 @@ var init_BaseModel = __esm({
         sourceYMap = modelConstructor.documentYMaps.get(`${docId}_${modelName}`) || null;
         const format2Store = modelConstructor.getFormat2StoreAsync(docId);
         if (format2Store) {
-          format2Store.assertReadable();
-          assertWithinOfflineWindow(docId, format2Store);
+          modelConstructor.assertFormat2Writable(
+            docId,
+            modelName,
+            this.id,
+            format2Store
+          );
           const target = await modelConstructor.resolveFormat2Target(
             docId,
             modelName,
@@ -9724,10 +10396,18 @@ var init_BaseModel = __esm({
         }
         const recordYMap = sourceYMap.get(this.id);
         if (!recordYMap) {
-          Logger.warn(
-            `[${modelName}] Delete: Item ${this.id} not found in YMap${docId ? ` for document ${docId}` : ""}. Cannot remove from unique constraint maps. Attempting main map deletion only.`
-          );
           sourceYDoc.transact(() => {
+            const removed = removeUniqueIndexEntriesForRecordId(
+              sourceYDoc,
+              modelName,
+              schema.resolvedUniqueConstraints.map((c) => c.name),
+              this.id
+            );
+            if (removed > 0) {
+              Logger.verbose(
+                `[${modelName}] Delete: Item ${this.id} not found in YMap${docId ? ` for document ${docId}` : ""}; removed ${removed} unique-index entr${removed === 1 ? "y" : "ies"} still naming it.`
+              );
+            }
             sourceYMap.delete(this.id);
           }, `delete-ghost-record-${modelName}-${this.id}`);
           return;
@@ -9747,6 +10427,7 @@ var init_BaseModel = __esm({
             if (uniqueKey !== null) {
               const constraintMapName = `_uniqueIdx_${modelName}_${constraint.name}`;
               const constraintMap = sourceYDoc.getMap(constraintMapName);
+              if (constraintMap.get(uniqueKey) !== this.id) continue;
               Logger.verbose(
                 `[${modelName}] Delete: Removing unique key '${uniqueKey.substring(
                   0,
@@ -10016,13 +10697,17 @@ var init_BaseModel = __esm({
         }
         const isFirstPage = !options?.uniqueStartKey;
         const direction = options?.direction || 1;
+        const aliasedSortFields = translatedQuery.cursorSortValueFields ?? [];
         const cursors = CursorManager.generateResultCursors(
-          results,
+          results.map((row) => cursorMintingRecord(row, aliasedSortFields)),
           translatedQuery.sortFields,
           direction,
           hasMore,
           isFirstPage
         );
+        results = results.map(
+          (row) => stripCursorSortValues(row, aliasedSortFields)
+        );
         if (direction === -1) {
           results.reverse();
         }
@@ -10794,24 +11479,25 @@ var init_BaseModel = __esm({
               constraint.name
             );
             const constraintMap2 = yDoc.getMap(constraintMapName2);
-            const recordId2 = constraintMap2.get(uniqueKeyString);
+            const documentYMapKey = `${docId}_${currentModelName}`;
+            const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
+            const recordId2 = modelConstructor._readableUniqueOwner(
+              documentYMap,
+              constraintMap2,
+              constraint,
+              uniqueKeyString,
+              currentModelName
+            );
             if (recordId2) {
-              const documentYMapKey = `${docId}_${currentModelName}`;
-              const documentYMap = modelConstructor.documentYMaps.get(documentYMapKey);
-              if (documentYMap) {
-                const recordYMap2 = documentYMap.get(recordId2);
-                if (recordYMap2 && recordYMap2 instanceof Y7.Map) {
-                  const instance = new modelConstructor({
-                    id: recordId2
-                  });
-                  instance._metaDocId = docId;
-                  instance._metaPermissionHint = documentInfo.permissionHint;
-                  Logger.verbose(
-                    `[${currentModelName}.findByUnique] Found record '${recordId2}' in document '${docId}'`
-                  );
-                  return instance;
-                }
-              }
+              const instance = new modelConstructor({
+                id: recordId2
+              });
+              instance._metaDocId = docId;
+              instance._metaPermissionHint = documentInfo.permissionHint;
+              Logger.verbose(
+                `[${currentModelName}.findByUnique] Found record '${recordId2}' in document '${docId}'`
+              );
+              return instance;
             }
           }
           const fallbackRecord = await modelConstructor._resolveByUniqueFallback(
@@ -10842,7 +11528,13 @@ var init_BaseModel = __esm({
           constraint.name
         );
         const constraintMap = legacyDocInfo.yDoc.getMap(constraintMapName);
-        const recordId = constraintMap.get(uniqueKeyString);
+        const recordId = modelConstructor._readableUniqueOwner(
+          legacyDocumentMap,
+          constraintMap,
+          constraint,
+          uniqueKeyString,
+          currentModelName
+        );
         if (!recordId) {
           const fallbackRecord = await modelConstructor._resolveByUniqueFallback(
             constraint,
@@ -10928,7 +11620,13 @@ var init_BaseModel = __esm({
             const docInfo = connectedDocuments.get(docId);
             if (docInfo) {
               const constraintMap = docInfo.yDoc.getMap(constraintMapName);
-              const recordId = constraintMap.get(uniqueKeyString);
+              const recordId = modelConstructor._readableUniqueOwner(
+                modelConstructor.documentYMaps?.get(`${docId}_${currentModelName}`),
+                constraintMap,
+                constraint,
+                uniqueKeyString,
+                currentModelName
+              );
               if (recordId) {
                 existingRecord = await modelConstructor.find(
                   recordId
@@ -11394,6 +12092,7 @@ __export(browser_exports, {
   completeOverlayEntries: () => completeOverlayEntries,
   configuredOfflineWindowDays: () => configuredOfflineWindowDays,
   createModelClass: () => createModelClass,
+  decideDeferredReplay: () => decideDeferredReplay,
   decodeFormat2StoreError: () => decodeFormat2StoreError,
   defineModelSchema: () => defineModelSchema,
   detectEnvironment: () => detectEnvironment,
@@ -11409,6 +12108,7 @@ __export(browser_exports, {
   followEpoch: () => followEpoch,
   format2ClientDDL: () => format2ClientDDL,
   format2EpochDocName: () => format2EpochDocName,
+  format2EpochDocPrefix: () => format2EpochDocPrefix,
   format2StringSetMembers: () => format2StringSetMembers,
   format2TableNames: () => format2TableNames,
   generateULID: () => generateULID,
@@ -11548,11 +12248,35 @@ var DatabaseEngine = class {
    */
   format2StoredEpoch;
   /**
-   * The engine that holds `docIds`' derived query tables for `modelName`.
+   * Remove one large document's local data, and the store holding it when
+   * nothing else is in there.
    *
-   * An engine whose large documents' query tables live apart from the
-   * ordinary documents' — the browser's worker-hosted engine — answers with
-   * the engine to run the statement on, or refuses a scope that would need
+   * An engine whose store lives somewhere only it can reach — the browser's
+   * worker-hosted pool — implements this; engines whose SQLite is synchronous
+   * and local leave it undefined and the in-process path purges through
+   * `createFormat2Sql()` instead. Either way the doors an app sees
+   * (`documents.evict`, `closeDocument({ evictLocal })`,
+   * `logout({ wipeLocal })`) remove the same things.
+   *
+   * `scope` is what the store is namespaced by beside the document, passed by
+   * the caller rather than remembered here: a purge at logout is about the
+   * user who is signing OUT, and an engine that outlives the sign-in would
+   * otherwise resolve the wrong store.
+   */
+  format2Purge;
+  /**
+   * Remove every large document's local data within one scope, except `keep`.
+   *
+   * Reaches documents this session never opened, and stores left behind before
+   * a purge existed — neither of which has anything in memory naming it.
+   */
+  format2PurgeAll;
+  /**
+   * The engine that holds `docIds`' derived query tables for `modelName`.
+   *
+   * An engine whose large documents' query tables live apart from the
+   * ordinary documents' — the browser's worker-hosted engine — answers with
+   * the engine to run the statement on, or refuses a scope that would need
    * both. Engines with one database for everything leave it undefined and
    * `BaseModel` uses the engine itself.
    */
@@ -12720,6 +13444,8 @@ var Format2NamespaceAttachment = class {
    */
   hiding = false;
   leaderRelease = null;
+  /** Set by a `retire` that succeeded: the pool's VFS is paused (#3754). */
+  hasRetired = false;
   election = null;
   electionQueued = false;
   broker = null;
@@ -12783,6 +13509,39 @@ var Format2NamespaceAttachment = class {
   holders(docId) {
     return this.send(FORMAT2_WORKER_CHANNEL, { kind: "holders", docId });
   }
+  /**
+   * Remove `docId`'s rows from the pool's store (#3754).
+   *
+   * Goes out on whatever this tab is attached to, leader or follower: the
+   * command touches rows, not the pool, and the worker refuses it while any
+   * session of the document is registered from any port.
+   */
+  purge(docId, force) {
+    return this.send(FORMAT2_WORKER_CHANNEL, { kind: "purge", docId, force });
+  }
+  /**
+   * Ask the worker to give up the pool, so its directory may be removed
+   * (#3754).
+   *
+   * Refused while any session on any document exists. On `retired: true` the
+   * database is closed, the VFS paused and the pool lock released BEFORE the
+   * reply, so the caller may remove the directory the moment it reads it — and
+   * it still holds the leader lock while it does, which is what stops a
+   * re-elected tab installing into a directory that is about to go.
+   */
+  async retire() {
+    const reply = await this.send(FORMAT2_WORKER_CHANNEL, { kind: "retire" });
+    if (reply.retired) this.hasRetired = true;
+    return reply;
+  }
+  /** Whether this attachment's worker has given up its pool (#3754). */
+  get retired() {
+    return this.hasRetired;
+  }
+  /** Whether this tab holds the namespace's leader lock right now (#3754). */
+  get leads() {
+    return this.attachment?.role === "leader" && (this.options.locks === null || this.leaderRelease !== null);
+  }
   release(docId, clientId, wipeIfLast) {
     return this.send(FORMAT2_WORKER_CHANNEL, {
       kind: "release",
@@ -13307,7 +14066,7 @@ var Format2NamespaceAttachment = class {
    * lifecycle step-down above never consults it, because a frozen page would
    * never reach the end of it.
    */
-  async destroy() {
+  async destroy(options = {}) {
     if (this.destroyed) return;
     const current = this.attachment;
     const leaving = Array.from(this.sessions);
@@ -13324,7 +14083,9 @@ var Format2NamespaceAttachment = class {
     this.attachment = null;
     for (const session of leaving) session.detach();
     if (current?.role === "leader") this.sayBye();
-    if (current) {
+    if (current && options.alreadyRetired) {
+      current.handle.terminate();
+    } else if (current) {
       try {
         await current.handle.close(this.options.closeBoundMs);
       } catch (error) {
@@ -13527,6 +14288,42 @@ function observeFormat2Lifecycle(target, handlers) {
 function format2ClientLockName(namespace, clientId) {
   return `${namespace.lockName}:client:${encodePart(clientId)}`;
 }
+function format2DocumentLockName(namespace, docId) {
+  return `${namespace.lockName}:doc:${encodePart(docId)}`;
+}
+function format2PoolDirectory(poolName) {
+  return `.${poolName}`;
+}
+function format2StoreNamespacePrefix(scope = {}) {
+  const parts = [scope.server ?? "", scope.app ?? "", scope.user ?? ""];
+  return parts.some((part) => part !== "") ? PREFIX + parts.map(encodePart).join("-") + "-" : PREFIX;
+}
+function format2DocumentIdFromPoolName(poolName, scope = {}) {
+  const prefix = format2StoreNamespacePrefix(scope);
+  if (!poolName.startsWith(prefix)) return null;
+  const encoded = poolName.slice(prefix.length);
+  if (encoded.length === 0 || encoded.includes("-")) return null;
+  const bytes = [];
+  for (let at = 0; at < encoded.length; ) {
+    if (encoded[at] === "_") {
+      const hex = encoded.slice(at + 1, at + 3);
+      if (!/^[0-9a-f]{2}$/.test(hex)) return null;
+      bytes.push(parseInt(hex, 16));
+      at += 3;
+      continue;
+    }
+    if (!/^[A-Za-z0-9]$/.test(encoded[at])) return null;
+    bytes.push(encoded.charCodeAt(at));
+    at += 1;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      new Uint8Array(bytes)
+    );
+  } catch {
+    return null;
+  }
+}
 var PREFIX = "js-bao-format2-";
 function encodePart(value) {
   let out = "";
@@ -13593,6 +14390,8 @@ var OpfsEngine = class {
   destroyed = false;
   /** Fires on `destroy()`: no open in progress spawns another worker. */
   teardown = new AbortController();
+  /** The OPFS root, once something has asked for it (#3754). */
+  resolvedRoot = null;
   constructor(options = {}, internals = {}) {
     this.internals = { ...options.internals ?? {}, ...internals };
     this.mirror = new SqljsEngine({
@@ -13692,10 +14491,18 @@ var OpfsEngine = class {
    */
   async createFormat2StoreHost(docId, options = {}) {
     const namespace = format2StoreNamespace(docId, options.scope ?? {});
+    const documentHeld = await this.holdShared(
+      format2DocumentLockName(namespace, docId)
+    );
+    if (documentHeld) this.presence.add(documentHeld);
+    const releaseDocument = () => {
+      if (documentHeld && this.presence.delete(documentHeld)) documentHeld();
+    };
     let entry;
     try {
       entry = await this.ensureWorker(docId, options.scope);
     } catch (error) {
+      releaseDocument();
       const reason = error?.message ?? String(error);
       Logger.error(
         `[OpfsEngine] ${docId}: the worker could not open its store: ${reason}`
@@ -13708,6 +14515,7 @@ var OpfsEngine = class {
       host = entry.attachment.serveStore(docId, clientId);
       await host.dispatch({ kind: "storedEpoch" });
     } catch (error) {
+      releaseDocument();
       const reason = error?.message ?? String(error);
       Logger.error(
         `[OpfsEngine] ${docId}: the worker could not open its store: ${reason}`
@@ -13720,9 +14528,10 @@ var OpfsEngine = class {
     else this.docs.set(docId, { entry, sessions: 1 });
     const held = clientId ? this.holdPresence(format2ClientLockName(namespace, clientId)) : null;
     if (held) this.presence.add(held);
-    const releasePresence = held ? () => {
-      if (this.presence.delete(held)) held();
-    } : null;
+    const releasePresence = () => {
+      if (held && this.presence.delete(held)) held();
+      releaseDocument();
+    };
     const engine = this;
     const closeOnce = async (closeOptions) => {
       const routing2 = engine.docs.get(docId);
@@ -13730,7 +14539,7 @@ var OpfsEngine = class {
         entry.docIds.delete(docId);
         engine.docs.delete(docId);
       }
-      releasePresence?.();
+      releasePresence();
       return host.close(closeOptions);
     };
     let closing = null;
@@ -13766,6 +14575,368 @@ var OpfsEngine = class {
       return null;
     }
   }
+  // ── Removing a document's store, and the pool holding it (#3754) ──
+  /**
+   * Remove `docId`'s local data, and its pool's directory once it holds
+   * nothing else.
+   *
+   * The namespace is ALWAYS built from the `scope` the caller passed — there is
+   * no cache of "which namespace did I last use for this document". This engine
+   * outlives a sign-in, and the open path re-reads the scope every time, so a
+   * remembered namespace would let user B's evict resolve user A's pool while
+   * leaving B's alone (finding 3754-SO-06).
+   *
+   * Everything below happens under the document's presence lock, taken
+   * EXCLUSIVE with `ifAvailable`: it never waits, so a document another tab has
+   * open is refused rather than blocking, and holding it across the data purge,
+   * the retire and the removal is what stops a tab opening into a half-purged
+   * store (edge E14 — its shared request simply waits).
+   */
+  async format2Purge(docId, options) {
+    if (this.destroyed) {
+      throw new DocumentClosedError(
+        `[format2] The opfs engine was destroyed; '${docId}' cannot be purged.`
+      );
+    }
+    await this.ensureRoot();
+    const namespace = format2StoreNamespace(docId, options.scope ?? {});
+    if (this.docs.has(docId)) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: held (this tab has it open).`
+      );
+      return { purged: false, reason: "held" };
+    }
+    const taken = await this.withExclusive(
+      format2DocumentLockName(namespace, docId),
+      () => this.purgeUnderDocumentLock(
+        docId,
+        namespace,
+        options.scope ?? {},
+        options.force
+      )
+    );
+    if (!taken.got) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: held (another tab holds its presence lock, so it still has the document open).`
+      );
+      return { purged: false, reason: "held", presence: true };
+    }
+    return taken.value;
+  }
+  /**
+   * Remove every large document of one scope except `keep` (#3754).
+   *
+   * Driven by the OPFS root's ENTRIES rather than by anything in memory, which
+   * is the only thing that reaches a document this session never opened and a
+   * pool left behind before a purge existed (finding R3). A scoped prefix ends
+   * in the separator and no encoded part contains one, so it can match neither
+   * another scope's pool nor an unscoped one (edge E4).
+   */
+  async format2PurgeAll(options) {
+    if (this.destroyed) {
+      throw new DocumentClosedError(
+        "[format2] The opfs engine was destroyed; its pools cannot be swept."
+      );
+    }
+    await this.ensureRoot();
+    const scope = options.scope ?? {};
+    const prefix = format2PoolDirectory(format2StoreNamespacePrefix(scope));
+    const keepDirectories = new Set(
+      (options.keep ?? []).map(
+        (id) => format2PoolDirectory(format2StoreNamespace(id, scope).poolName)
+      )
+    );
+    const removed = [];
+    const skipped = [];
+    for (const directory of await this.listPoolDirectories(prefix)) {
+      if (keepDirectories.has(directory)) {
+        skipped.push({ pool: directory, reason: "keep" });
+        continue;
+      }
+      const poolName = directory.slice(1);
+      const docId = format2DocumentIdFromPoolName(poolName, scope);
+      if (docId === null) {
+        skipped.push({ pool: directory, reason: "unrecognized" });
+        continue;
+      }
+      const result = await this.format2Purge(docId, {
+        force: options.force,
+        scope
+      });
+      if (result.purged && result.poolRemoved) {
+        removed.push(directory);
+        continue;
+      }
+      const reason = result.purged ? "kept-pool" : result.reason;
+      skipped.push({ pool: directory, reason });
+      Logger.warn(
+        `[OpfsEngine] the sweep skipped the pool '${directory}': ${reason}.`
+      );
+    }
+    Logger.info(
+      `[OpfsEngine] large-document sweep removed ${removed.length} pool(s), skipped ${skipped.length}.`
+    );
+    return { removed, skipped };
+  }
+  /**
+   * The purge itself, with this tab holding the document lock exclusively.
+   *
+   * Three cases, and what they have in common is that no removal is EVER
+   * decided on this engine's own bookkeeping: `entry.docIds` and
+   * `routing.sessions` say what THIS tab serves, while the worker's session map
+   * says what every tab does (finding 3754-SO-03).
+   */
+  async purgeUnderDocumentLock(docId, namespace, scope, force) {
+    const existing = this.workers.get(namespace.poolName);
+    const attached = existing && !existing.attachment.died ? existing : null;
+    if (!attached) {
+      return this.purgeWithoutAttachment(docId, namespace, scope, force);
+    }
+    return this.purgeThroughAttachment(docId, namespace, attached, force);
+  }
+  /** No attachment for the namespace: what is on disk decides what happens. */
+  async purgeWithoutAttachment(docId, namespace, scope, force) {
+    const directory = format2PoolDirectory(namespace.poolName);
+    const root = this.opfsRoot();
+    if (root) {
+      const present = await this.directoryExists(root, directory);
+      if (!present) {
+        Logger.info(
+          `[OpfsEngine] ${docId}: nothing stored locally (no pool directory).`
+        );
+        return { purged: true, nothingStored: true, poolRemoved: false };
+      }
+      if (force) {
+        const under = await this.withExclusive(
+          namespace.lockName,
+          () => this.removePoolDirectory(namespace, docId, null)
+        );
+        if (under.got && under.value) {
+          return { purged: true, poolRemoved: true, pendingOps: 0 };
+        }
+        if (under.got) {
+          Logger.warn(
+            `[OpfsEngine] ${docId}: its pool directory could not be removed directly, so its store is purged through a worker instead.`
+          );
+        }
+      }
+    }
+    let entry;
+    try {
+      entry = await this.ensureWorker(docId, scope);
+    } catch (error) {
+      const reason = error?.message ?? String(error);
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: unreachable \u2014 another tab leads its pool and no port was offered (${reason}).`
+      );
+      return { purged: false, reason: "unreachable" };
+    }
+    return this.purgeThroughAttachment(docId, namespace, entry, force);
+  }
+  /** An attachment for the namespace: the worker decides, then the leader acts. */
+  async purgeThroughAttachment(docId, namespace, entry, force) {
+    let reply;
+    try {
+      reply = await entry.attachment.purge(docId, force);
+    } catch (error) {
+      const reason = error?.message ?? String(error);
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: unreachable (${reason}).`
+      );
+      return { purged: false, reason: "unreachable" };
+    }
+    if (!reply.purged) {
+      if (reply.reason === "pending") {
+        Logger.warn(
+          `[OpfsEngine] ${docId}: purge refused: ${reply.pendingOps ?? 0} unacknowledged write(s); purge with force to drop them.`
+        );
+        return {
+          purged: false,
+          reason: "pending",
+          pendingOps: reply.pendingOps ?? 0
+        };
+      }
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: held by ${reply.holders ?? 0} session(s) on the pool's worker.`
+      );
+      return { purged: false, reason: "held", holders: reply.holders };
+    }
+    Logger.info(
+      `[OpfsEngine] ${docId}: local store purged (${reply.pendingOps} unacknowledged write(s) dropped, ${reply.remainingDocuments} document(s) left in the pool).`
+    );
+    if (reply.remainingDocuments > 0) {
+      Logger.debug(
+        `[OpfsEngine] ${docId}: its pool still holds ${reply.remainingDocuments} document(s), so its directory stays.`
+      );
+      return { ...purgedReport(reply), poolRemoved: false };
+    }
+    if (!entry.attachment.leads) {
+      Logger.debug(
+        `[OpfsEngine] ${docId}: another tab leads its pool, so its directory is left to that tab.`
+      );
+      return { ...purgedReport(reply), poolRemoved: false };
+    }
+    let retired;
+    try {
+      retired = await entry.attachment.retire();
+    } catch (error) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: its pool could not be retired (${error?.message ?? String(error)}), so its directory stays.`
+      );
+      return { ...purgedReport(reply), poolRemoved: false };
+    }
+    if (!retired.retired) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: its pool was not retired \u2014 ${retired.holders} session(s) on its worker still hold a document open, so its directory stays.`
+      );
+      return { ...purgedReport(reply), poolRemoved: false };
+    }
+    const poolRemoved = await this.removePoolDirectory(namespace, docId, entry);
+    this.workers.delete(namespace.poolName);
+    this.attachments.delete(entry.attachment);
+    await entry.attachment.destroy({ alreadyRetired: true }).catch(() => {
+    });
+    return { ...purgedReport(reply), poolRemoved };
+  }
+  /**
+   * Remove one pool's OPFS directory. The ONLY caller of `removeEntry`.
+   *
+   * Refuses unless this tab holds the namespace's leader lock and the
+   * document's presence lock exclusively, and unless the namespace has no
+   * attachment still serving it — a directory whose sync access handles are
+   * still held cannot be removed anyway (`NoModificationAllowedError`,
+   * measured), and one that could be would be taken from under a tab that is
+   * reading it.
+   *
+   * Answers whether the directory went; a failure is a warn and a `false`, not
+   * a throw, because the DATA is already gone by this point and a caller that
+   * treated the whole purge as failed would report it wrongly.
+   */
+  async removePoolDirectory(namespace, docId, entry) {
+    const directory = format2PoolDirectory(namespace.poolName);
+    if (this.destroyed) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: the engine was destroyed while its purge was in flight, so '${directory}' is left on disk.`
+      );
+      return false;
+    }
+    const root = this.opfsRoot();
+    if (!root) {
+      Logger.debug(
+        `[OpfsEngine] ${docId}: no OPFS root is configured, so '${directory}' is left on disk; its rows are gone.`
+      );
+      return false;
+    }
+    if (entry && !entry.attachment.leads) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: this tab no longer leads its pool, so '${directory}' is left on disk; its rows are gone.`
+      );
+      return false;
+    }
+    if (entry && !entry.attachment.retired) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: its worker has not paused its VFS, so '${directory}' is left on disk.`
+      );
+      return false;
+    }
+    try {
+      await root.removeEntry(directory, { recursive: true });
+      Logger.info(
+        `[OpfsEngine] ${docId}: removed its pool directory '${directory}'.`
+      );
+      return true;
+    } catch (error) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: could not remove its pool directory '${directory}': ${error?.message ?? String(error)}`
+      );
+      return false;
+    }
+  }
+  /** `navigator.storage.getDirectory()`'s handle, or `null` where there is none. */
+  opfsRoot() {
+    if (this.internals.opfsRoot !== void 0) return this.internals.opfsRoot;
+    return this.resolvedRoot;
+  }
+  /**
+   * Resolve `navigator.storage.getDirectory()` once, if this platform has it.
+   *
+   * Awaited at the top of every purge rather than in the constructor: an engine
+   * is built before anybody has asked it for anything, and a rejected promise
+   * kept on a field would be an unhandled rejection in every app that never
+   * purges.
+   */
+  async ensureRoot() {
+    if (this.internals.opfsRoot !== void 0 || this.resolvedRoot) return;
+    const storage = globalThis.navigator?.storage;
+    if (!storage || typeof storage.getDirectory !== "function") return;
+    try {
+      this.resolvedRoot = await storage.getDirectory();
+    } catch (error) {
+      Logger.debug(
+        `[OpfsEngine] the OPFS root could not be opened: ${error?.message ?? String(error)}`
+      );
+    }
+  }
+  /** Whether `name` is a directory of the root, without creating it. */
+  async directoryExists(root, name) {
+    try {
+      await root.getDirectoryHandle(name, { create: false });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Every directory of the root beginning with `prefix`. */
+  async listPoolDirectories(prefix) {
+    const root = this.opfsRoot();
+    if (!root) {
+      Logger.debug(
+        "[OpfsEngine] no OPFS root is configured, so no pool directory can be listed or removed."
+      );
+      return [];
+    }
+    const found = [];
+    try {
+      for await (const name of root.keys()) {
+        if (name.startsWith(prefix)) found.push(name);
+      }
+    } catch (error) {
+      Logger.warn(
+        `[OpfsEngine] the OPFS root could not be listed: ${error?.message ?? String(error)}`
+      );
+    }
+    return found;
+  }
+  /**
+   * Hold `name` exclusively for the length of `run`, or say it could not be.
+   *
+   * `ifAvailable`, so it never waits: a purge that queued behind a tab with the
+   * document open would sit there for as long as that tab lives.
+   */
+  async withExclusive(name, run2) {
+    const locks = this.locks();
+    if (!locks) return { got: true, value: await run2() };
+    let outcome = { got: false };
+    let failure = null;
+    await Promise.resolve(
+      locks.request(name, { mode: "exclusive", ifAvailable: true }, async (lock) => {
+        if (lock === null) return void 0;
+        try {
+          outcome = { got: true, value: await run2() };
+        } catch (error) {
+          outcome = { got: true };
+          failure = error;
+        }
+        return void 0;
+      })
+    ).catch((error) => {
+      Logger.warn(
+        `[OpfsEngine] the lock '${name}' could not be taken: ${error?.message ?? String(error)}`
+      );
+    });
+    if (failure) throw failure;
+    return outcome;
+  }
   /** `navigator.locks`, unless a test handed one in. `null` means none. */
   locks() {
     if (this.internals.locks !== void 0) return this.internals.locks;
@@ -13786,7 +14957,7 @@ var OpfsEngine = class {
    * queued is withdrawn. A presence lock left held says a client is still here
    * when its writes are sitting in the log waiting to be adopted.
    */
-  holdPresence(name) {
+  holdPresence(name, mode = "exclusive") {
     const locks = this.locks();
     if (!locks) return null;
     let release = null;
@@ -13795,7 +14966,7 @@ var OpfsEngine = class {
     void Promise.resolve(
       locks.request(
         name,
-        { mode: "exclusive", ...withdraw ? { signal: withdraw.signal } : {} },
+        { mode, ...withdraw ? { signal: withdraw.signal } : {} },
         () => new Promise((resolve) => {
           if (done) resolve();
           else release = resolve;
@@ -13809,6 +14980,35 @@ var OpfsEngine = class {
       withdraw?.abort();
     };
   }
+  /**
+   * Hold `name` SHARED, waiting for the grant, and answer the release (#3754).
+   *
+   * Unlike {@link holdPresence}, which fires the request off and returns at
+   * once, this waits: the caller's next act is to open a pool, and a purge that
+   * holds this name exclusively is in the middle of emptying that pool. Waiting
+   * here is what turns a race into an ordering.
+   */
+  async holdShared(name) {
+    const locks = this.locks();
+    if (!locks) return null;
+    let release = null;
+    let done = false;
+    await new Promise((granted) => {
+      void Promise.resolve(
+        locks.request(name, { mode: "shared" }, () => {
+          granted();
+          return new Promise((resolve) => {
+            if (done) resolve();
+            else release = resolve;
+          });
+        })
+      ).catch(() => granted());
+    });
+    return () => {
+      done = true;
+      release?.();
+    };
+  }
   /** Whether somebody holds `name` right now. Never waits. */
   async probeLock(name) {
     const locks = this.locks();
@@ -13980,6 +15180,14 @@ var OpfsEngine = class {
     });
   }
 };
+function purgedReport(reply) {
+  return {
+    purged: true,
+    ...reply.nothingStored ? { nothingStored: true } : {},
+    pendingOps: reply.pendingOps,
+    remainingDocuments: reply.remainingDocuments
+  };
+}
 function withinBound2(promise, boundMs) {
   let timer;
   const bound = new Promise((resolve) => {
@@ -14408,6 +15616,22 @@ function sameOverlayValue(a, b) {
   if (a === null || a === void 0) return b === null || b === void 0;
   return JSON.stringify(a) === JSON.stringify(b);
 }
+function decideDeferredReplay(note, epoch, ackedSeq) {
+  if (!note || note.kind !== "ordinary") return { kind: "none" };
+  let resolved = note;
+  let clamped = false;
+  if (note.toEpoch > epoch) {
+    if (note.fromEpoch >= epoch) {
+      return { kind: "clear", reason: "never-completed", note };
+    }
+    resolved = { ...note, toEpoch: epoch };
+    clamped = true;
+  }
+  if (resolved.throughSeq <= ackedSeq) {
+    return { kind: "clear", reason: "acknowledged", note: resolved };
+  }
+  return { kind: "honour", note: resolved, clamped };
+}
 function restorePendingOverlay(doc, store, verdicts, options = {}) {
   const result = {
     restored: [],
@@ -14415,9 +15639,10 @@ function restorePendingOverlay(doc, store, verdicts, options = {}) {
     deferred: []
   };
   const defer = options.deferAtOrBelowEpoch ?? 0;
+  const deferThrough = options.deferThroughSeq ?? 0;
   const missing = [];
   for (const op of store.pendingOps()) {
-    if (defer > 0 && op.baseEpoch > 0 && op.baseEpoch <= defer) {
+    if (defer > 0 && op.baseEpoch > 0 && op.baseEpoch <= defer || deferThrough > 0 && op.seq <= deferThrough) {
       result.deferred.push(op.seq);
       continue;
     }
@@ -14451,17 +15676,71 @@ function statePendingOps(doc, ops, options = {}) {
       (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}`))
-  );
+  const owned = /* @__PURE__ */ new Map();
+  const laterKeys = /* @__PURE__ */ new Map();
+  const lifecycle = /* @__PURE__ */ new Map();
+  for (const op of [...options.later ?? []].sort((a, b) => a.seq - b.seq)) {
+    const key = `${op.model} ${op.recordId}`;
+    let fields = owned.get(key);
+    if (!fields) owned.set(key, fields = /* @__PURE__ */ new Set());
+    for (const field of op.fields) fields.add(field);
+    let keys = laterKeys.get(key);
+    if (!keys) laterKeys.set(key, keys = /* @__PURE__ */ new Set());
+    for (const [written] of op.mutation ? encodeOverlayMutation(op.mutation) : []) {
+      keys.add(written);
+    }
+    lifecycle.set(key, op.op);
+  }
+  const stated = [];
+  for (const op of [...ops].sort((a, b) => a.seq - b.seq)) {
+    if (op.mutation === null) continue;
+    const key = `${op.model} ${op.recordId}`;
+    const now = lifecycle.get(key);
+    if (op.op === "delete") {
+      if (suppressed.has(key) || now !== void 0 && now !== "delete") {
+        continue;
+      }
+      stated.push({ op, mutation: op.mutation });
+      continue;
+    }
+    if (now === "delete") {
+      continue;
+    }
+    const later = owned.get(key);
+    if (later === void 0) {
+      stated.push({ op, mutation: op.mutation });
+      continue;
+    }
+    const narrowed = withoutFields(op.mutation, later);
+    if (narrowed === null) continue;
+    stated.push({ op, mutation: narrowed, keep: laterKeys.get(key) });
+  }
   if (stated.length === 0) return 0;
   doc.transact(() => {
-    for (const op of stated) {
-      applyOverlayMutation(doc.getMap(op.model), op.mutation);
+    for (const { op, mutation, keep } of stated) {
+      applyOverlayMutation(doc.getMap(op.model), mutation, { keep });
     }
   });
   return stated.length;
 }
+function withoutFields(mutation, owned) {
+  const fields = Object.fromEntries(
+    Object.entries(mutation.fields ?? {}).filter(([field]) => !owned.has(field))
+  );
+  const deltas = Object.fromEntries(
+    Object.entries(mutation.stringSetDeltas ?? {}).filter(
+      ([field]) => !owned.has(field)
+    )
+  );
+  if (mutation.kind !== "create" && Object.keys(fields).length === 0 && Object.keys(deltas).length === 0) {
+    return null;
+  }
+  return {
+    ...mutation,
+    ...mutation.fields === void 0 ? {} : { fields },
+    ...mutation.stringSetDeltas === void 0 ? {} : { stringSetDeltas: deltas }
+  };
+}
 
 // src/models/format2SnapshotLoader.ts
 init_snapshotChunks();
@@ -14775,17 +16054,21 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
       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) {
+      const owedJudgement = await this.settleDeferredReplay(docId, store);
+      const restored = restorePendingOverlay(yDoc, store, verdicts, {
+        ...deferAtOrBelowEpoch > 0 ? { deferAtOrBelowEpoch } : {},
+        ...owedJudgement ? { deferThroughSeq: owedJudgement.throughSeq } : {}
+      });
+      if (restored.deferred.length > 0 && deferAtOrBelowEpoch > 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}.`
         );
       }
+      if (restored.deferred.length > 0 && owedJudgement) {
+        Logger.warn(
+          `[format2] ${docId} is holding ${restored.deferred.length} unacknowledged write(s) off its overlay until the deferred judgement of epochs ${owedJudgement.fromEpoch}..${owedJudgement.toEpoch} has run.`
+        );
+      }
       const adoptedWasRestored = verdicts !== void 0 && restored.restored.some((seq) => verdicts.has(seq));
       if (adoptedWasRestored) {
         foldFormat2Overlay(
@@ -14809,6 +16092,47 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
       store.onReattached(() => this.revalidateQueryTables(docId, store))
     );
   }
+  /**
+   * Settle what a deferred judgement means for THIS bind (#3755).
+   *
+   * Returns the note whose covered writes must stay off the overlay, or `null`
+   * when there is nothing to honour. The decision is
+   * {@link decideDeferredReplay}'s, so the bind and the resumed judgement read
+   * one note the same way.
+   *
+   * The clamp is deliberately NOT written back: `noteDeferredReplay` widens,
+   * so it could not narrow a target, and the decision is a pure function of the
+   * row and the store's epoch — every later reader reaches the same answer. A
+   * note that is CLEARED is cleared durably, because that is a fact about the
+   * debt rather than a reading of it.
+   */
+  async settleDeferredReplay(docId, store) {
+    const decision = decideDeferredReplay(
+      store.deferredReplay(),
+      store.epoch(),
+      store.ackedSeq()
+    );
+    if (decision.kind === "none") return null;
+    if (decision.kind === "clear") {
+      if (decision.reason === "acknowledged") {
+        Logger.debug(
+          `[format2] ${docId}: the deferred judgement of epochs ${decision.note.fromEpoch}..${decision.note.toEpoch} is settled: every covered write was acknowledged through sequence ${decision.note.throughSeq}.`
+        );
+      } else {
+        Logger.warn(
+          `[format2] ${docId}: a deferred-replay note names epoch ${decision.note.toEpoch}, but this store is on ${store.epoch()} and nothing was deferred below it; the move never completed, restoring as usual.`
+        );
+      }
+      await store.clearDeferredReplay();
+      return null;
+    }
+    if (decision.clamped) {
+      Logger.debug(
+        `[format2] ${docId}: a later deferred move was interrupted, so the judgement this bind owes is clamped to the epoch this store reached: ${store.deferredReplay()?.fromEpoch}..${store.deferredReplay()?.toEpoch} \u2192 ${decision.note.fromEpoch}..${decision.note.toEpoch}.`
+      );
+    }
+    return decision.note;
+  }
   /**
    * Rebuild whatever the query tables lost while this tab was off the worker
    * (#3431, finding 3431-R12).
@@ -15452,6 +16776,8 @@ function withinBound3(promise, boundMs) {
 
 // src/models/format2Sync.ts
 init_OrmContext();
+init_format2RecordStore();
+init_logger();
 function format2StoredEpoch(engine, docId, ctx) {
   if (!docId) return null;
   const bound = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
@@ -15488,6 +16814,82 @@ async function format2StoredEpochAsync(engine, docId, ctx, scope) {
   }
   return format2StoredEpoch(engine, docId, ctx);
 }
+async function format2Purge(engine, docId, options, ctx) {
+  if (!docId) return { purged: false, reason: "held" };
+  const bound = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
+  if (bound) {
+    Logger.warn(
+      `[format2] ${docId}: its local store is open in this instance, so it was not purged; close the document first.`
+    );
+    return { purged: false, reason: "held" };
+  }
+  const force = options.force === true;
+  if (engine?.format2Purge) {
+    return engine.format2Purge(docId, { force, scope: options.scope });
+  }
+  const sql = engine?.createFormat2Sql?.();
+  if (!sql) {
+    return { purged: true, nothingStored: true, pendingOps: 0, remainingDocuments: 0 };
+  }
+  return purgeThroughStore(sql, docId, force);
+}
+function purgeThroughStore(sql, docId, force) {
+  return sql.transaction(() => {
+    const pendingOps = Format2RecordStore.pendingOpCount(sql, docId);
+    if (!force && pendingOps > 0) {
+      Logger.warn(
+        `[format2] ${docId}: not purged \u2014 its local store holds ${pendingOps} unacknowledged write(s). Purge with force to drop them.`
+      );
+      return { purged: false, reason: "pending", pendingOps };
+    }
+    const report = Format2RecordStore.purge(sql, docId);
+    Logger.info(
+      `[format2] ${docId}: local store purged (${report.pendingOps} unacknowledged write(s) dropped, ${report.remainingDocuments} document(s) left in the store).`
+    );
+    return {
+      purged: true,
+      ...report.nothingStored ? { nothingStored: true } : {},
+      pendingOps: report.pendingOps,
+      remainingDocuments: report.remainingDocuments
+    };
+  });
+}
+async function format2PurgeAll(engine, options, ctx) {
+  const force = options.force === true;
+  if (engine?.format2PurgeAll) {
+    return engine.format2PurgeAll({
+      ...options.keep ? { keep: options.keep } : {},
+      force,
+      scope: options.scope
+    });
+  }
+  const sql = engine?.createFormat2Sql?.();
+  if (!sql) return { removed: [], skipped: [], purged: [] };
+  const context = ctx ?? getDefaultOrmContext();
+  const keep = new Set(options.keep ?? []);
+  const purged = [];
+  const skipped = [];
+  for (const docId of Format2RecordStore.storedDocuments(sql)) {
+    if (keep.has(docId)) {
+      skipped.push({ pool: docId, reason: "keep" });
+      continue;
+    }
+    if (context.getFormat2StoreAsync(docId)) {
+      Logger.warn(
+        `[format2] ${docId}: skipped by the local-store sweep \u2014 it is open in this instance.`
+      );
+      skipped.push({ pool: docId, reason: "held" });
+      continue;
+    }
+    const result = purgeThroughStore(sql, docId, force);
+    if (result.purged) purged.push(docId);
+    else skipped.push({ pool: docId, reason: result.reason });
+  }
+  Logger.info(
+    `[format2] local-store sweep purged ${purged.length} document(s), skipped ${skipped.length}.`
+  );
+  return { removed: [], skipped, purged };
+}
 function format2SyncMarks(docId, ctx) {
   const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
   if (!store) return null;
@@ -15497,7 +16899,8 @@ function format2SyncMarks(docId, ctx) {
     epoch: store.epoch(),
     clockOffsetKnown: store.clockOffsetKnown(),
     discontinuityEpochs: store.discontinuityEpochs(),
-    baseComplete: store.baseComplete()
+    baseComplete: store.baseComplete(),
+    deferredReplay: store.deferredReplay()
   };
 }
 function format2NoteEpoch(docId, epoch, ctx) {
@@ -15509,11 +16912,21 @@ function format2NoteEpoch(docId, epoch, ctx) {
 function format2PendingOps(docId, ctx) {
   return (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId)?.pendingOps() ?? [];
 }
-function format2SetEpoch(docId, epoch, ctx) {
+function format2SetEpoch(docId, epoch, ctx, deferredReplay) {
   const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
   if (!store) return;
   if (!Number.isInteger(epoch) || epoch <= 0) return;
-  store.setEpoch(epoch);
+  store.setEpoch(epoch, deferredReplay ? { deferredReplay } : {});
+}
+async function format2NoteDeferredReplay(docId, note, ctx) {
+  const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
+  if (!store) return;
+  await store.noteDeferredReplay(note);
+}
+async function format2ClearDeferredReplay(docId, ctx) {
+  const store = (ctx ?? getDefaultOrmContext()).getFormat2StoreAsync(docId);
+  if (!store) return;
+  await store.clearDeferredReplay();
 }
 function format2HoldWrites(docId, run2, ctx) {
   return (ctx ?? getDefaultOrmContext()).holdFormat2Writes(docId, run2);
@@ -16088,17 +17501,42 @@ async function initJsBaoCore(options, getEngine) {
         ormContext,
         options.largeDocumentStoreScope?.() ?? void 0
       ),
+      // #3754 — the three doors that remove a large document's local data.
+      // The scope defaults to what an open would use and is otherwise the
+      // caller's: at logout it names the user who is signing OUT, which this
+      // engine no longer has any way to work out for itself.
+      format2Purge: (docId, purgeOptions) => format2Purge(
+        dbEngine,
+        docId,
+        {
+          force: purgeOptions?.force,
+          scope: purgeOptions?.scope ?? options.largeDocumentStoreScope?.() ?? void 0
+        },
+        ormContext
+      ),
+      format2PurgeAll: (purgeOptions) => format2PurgeAll(
+        dbEngine,
+        {
+          ...purgeOptions?.keep ? { keep: purgeOptions.keep } : {},
+          force: purgeOptions?.force,
+          scope: purgeOptions?.scope ?? options.largeDocumentStoreScope?.() ?? void 0
+        },
+        ormContext
+      ),
       format2Acknowledge: (docId, maxContiguousSeq) => format2Acknowledge(docId, maxContiguousSeq, ormContext),
       format2NoteEpoch: (docId, epoch) => format2NoteEpoch(docId, epoch, ormContext),
       format2NoteSync: (docId, at, windowDays) => format2NoteSync(docId, at, windowDays, ormContext),
       format2NoteWindow: (docId, windowDays) => format2NoteWindow(docId, windowDays, ormContext),
+      format2OnWriteRefused: (listener) => ormContext.onFormat2WriteRefused(listener),
       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),
+      format2NoteDeferredReplay: (docId, note) => format2NoteDeferredReplay(docId, note, ormContext),
+      format2ClearDeferredReplay: (docId) => format2ClearDeferredReplay(docId, ormContext),
       format2NarrowPendingOps: (docId, ops) => format2NarrowPendingOps(docId, ops, ormContext),
       format2PendingOps: (docId) => format2PendingOps(docId, ormContext),
-      format2SetEpoch: (docId, epoch) => format2SetEpoch(docId, epoch, ormContext),
+      format2SetEpoch: (docId, epoch, deferredReplay) => format2SetEpoch(docId, epoch, ormContext, deferredReplay),
       format2HoldWrites: (docId, run2) => format2HoldWrites(docId, run2, ormContext),
       format2RebindEpochDocument: docManager.rebindEpochDocument.bind(docManager),
       format2ApplySealedOverlay: docManager.applySealedOverlay.bind(docManager),
@@ -16775,8 +18213,11 @@ init_format2Observer();
 
 // src/models/format2EpochHandoff.ts
 init_largeDocuments();
+function format2EpochDocPrefix(docId) {
+  return `${docId}@`;
+}
 function format2EpochDocName(docId, epoch) {
-  return `${docId}@${epoch}`;
+  return `${format2EpochDocPrefix(docId)}${epoch}`;
 }
 function carryUnackedOverlay(ops, readOverlay, options = {}) {
   const suppressed = new Set(
@@ -16924,6 +18365,19 @@ async function followEpoch(host, nextEpoch, options = {}) {
     const owedOps = host.pendingOps();
     const readSealed = (model, recordId) => readOverlayRecord(sealed.getMap(model), recordId);
     const owedOverlay = defer ? snapshotOwedOverlay(owedOps, readSealed) : null;
+    const owedNote = defer && owedOps.length > 0 && host.noteDeferredReplay ? {
+      throughSeq: Math.max(...owedOps.map((op) => op.seq)),
+      fromEpoch: current,
+      toEpoch: nextEpoch,
+      kind: "ordinary"
+    } : null;
+    if (owedNote && host.noteDeferredReplay) {
+      try {
+        await host.noteDeferredReplay(owedNote);
+      } catch {
+        return { moved: false, reason: "note-refused" };
+      }
+    }
     let carried = [];
     if (!defer) {
       const owed = resolveReplay ? resolveReplay(owedOps) : { ops: owedOps, suppressDeletes: [] };
@@ -16944,7 +18398,10 @@ async function followEpoch(host, nextEpoch, options = {}) {
     await host.install(
       fresh,
       nextEpoch,
-      defer ? { restorePending: false } : void 0
+      defer ? {
+        restorePending: false,
+        ...owedNote ? { deferredReplay: owedNote } : {}
+      } : void 0
     );
     await host.resync();
     if (!defer) {