js-bao 0.7.0-alpha.6 → 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.
        *
@@ -5225,6 +5824,19 @@ var init_OrmContext = __esm({
       format2Documents = /* @__PURE__ */ new Map();
       /** Format-2 epoch moves in flight (#2816). */
       format2Transitions = /* @__PURE__ */ new Map();
+      /**
+       * This instance's document observers' database writes that have not finished
+       * yet, by document id (#3023).
+       *
+       * A Yjs observer fires synchronously with the update but writes to the
+       * database asynchronously, so an update that has been APPLIED to a document
+       * is not yet QUERYABLE. Whoever needs the difference — an `open()` that
+       * promises its caller the synced records — waits on
+       * {@link whenDocumentIndexed}. Per instance, not process-wide: two clients
+       * holding the same document id write to their own engines, and neither
+       * should be held up by the other's writes.
+       */
+      documentIndexingWork = /* @__PURE__ */ new Map();
       /**
        * Who this ORM instance is in a format-2 store's unacknowledged-write log
        * (#3431).
@@ -5402,6 +6014,56 @@ var init_OrmContext = __esm({
           release();
         }
       }
+      /**
+       * Record one observer's asynchronous write of `docId` (#3023), so a caller
+       * that needs the document queryable can wait for it. Failures are the
+       * observer's own to log; a tracked promise never rejects, because the point
+       * of the barrier is only to know when the write is over.
+       *
+       * A destroyed context tracks nothing: its observers are already inert, and a
+       * torn-down instance must not leave a barrier that never drains.
+       */
+      trackDocumentIndexing(docId, work) {
+        if (this.destroyed) return;
+        let inFlight = this.documentIndexingWork.get(docId);
+        if (!inFlight) {
+          inFlight = /* @__PURE__ */ new Set();
+          this.documentIndexingWork.set(docId, inFlight);
+        }
+        const pending = work.catch(() => {
+        }).then(() => {
+          inFlight.delete(pending);
+          if (inFlight.size === 0 && this.documentIndexingWork.get(docId) === inFlight) {
+            this.documentIndexingWork.delete(docId);
+          }
+        });
+        inFlight.add(pending);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this instance's query
+       * tables (#3023). Answers `true` when the work drained, `false` when it gave
+       * up waiting — the caller owns the logging, because this module holds no
+       * runtime imports.
+       *
+       * An update applied to the Y.Doc is visible to a reader of the document
+       * immediately, but the query tables only catch up when the observers' writes
+       * land. An `open()` that waited for the initial sync waits for this too —
+       * otherwise it resolves on the sync signal and the caller's first `query()`
+       * sees a partly-written table.
+       *
+       * A write can enqueue more work (a nested map observed as it arrives), so
+       * this drains in passes rather than once, and gives up after enough of them
+       * that only a document under continuous change could still be busy — a
+       * barrier is not a reason to hang.
+       */
+      async whenDocumentIndexed(docId) {
+        for (let pass = 0; pass < 50; pass++) {
+          const inFlight = this.documentIndexingWork.get(docId);
+          if (!inFlight || inFlight.size === 0) return true;
+          await Promise.all([...inFlight]);
+        }
+        return false;
+      }
       /** Notify `subscribe()` callbacks registered on this context for `modelName`. */
       notifyListeners(modelName, log, onError) {
         const listeners = this.listenersMap.get(modelName);
@@ -5460,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 = [];
@@ -5525,8 +6216,10 @@ 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();
         this.observedStringSetMaps = /* @__PURE__ */ new WeakSet();
         liveOrmContexts.delete(this);
         if (defaultOrmContext === this) {
@@ -5897,6 +6590,10 @@ var init_ModelRegistry = __esm({
        * undefined the legacy session semantics are kept exactly: the global
        * registry is SNAPSHOT at init time, so a model registered afterwards is not
        * silently adopted by an already-running instance.
+       *
+       * The one way a running instance's registry grows is {@link adoptModel},
+       * behind `registerModel` on the init result (#3615): an EXPLICIT call on the
+       * instance the app means, not a relaxation of the snapshot rule.
        */
       static createInstanceRegistry(modelClasses) {
         const registry = new _ModelRegistry();
@@ -5920,6 +6617,64 @@ var init_ModelRegistry = __esm({
         registry.setExplicitModelsForSession(modelClasses);
         return registry;
       }
+      /**
+       * The name `modelClass` may be adopted under on THIS instance, or a refusal
+       * that names what to change (#3615).
+       *
+       * Both checks are made before anything is mutated, so a registration that
+       * cannot go through leaves the registry exactly as it was.
+       */
+      assertAdoptable(modelClass, instanceId) {
+        const schema = modelClass?.getSchema?.();
+        const modelName = modelClass?.modelName ?? schema?.options?.name;
+        if (!modelName || !schema?.options?.name || !schema?.resolvedUniqueConstraints) {
+          throw new Error(
+            `[initJsBao] Cannot register a model class with no name. Build it with defineModelSchema and attachAndRegisterModel (or createModelClass) so it carries a static modelName and a schema with resolvedUniqueConstraints.`
+          );
+        }
+        const existing = this.models.get(modelName);
+        if (existing && existing !== modelClass) {
+          throw new Error(
+            `[initJsBao] Model '${modelName}' is already registered on js-bao instance #${instanceId} with a different class. Register the existing class, or give the new model a different name.`
+          );
+        }
+        return modelName;
+      }
+      /**
+       * Adopt `modelClass` into THIS instance's registry at runtime (#3615).
+       *
+       * The counterpart to the snapshot rule on
+       * {@link ModelRegistry.createInstanceRegistry}: an instance grows only where
+       * the app says so, and the global singleton is deliberately not touched —
+       * registering here makes the model visible to this instance and to no other.
+       *
+       * Returns `{ added: false }` when the very same class is already ACTIVE on
+       * this instance, which is what makes a repeat `registerModel` a no-op rather
+       * than a warning about overwriting. Active, not merely present: an instance
+       * built with `models: []` carries the whole global registry in `models` with
+       * nothing active, and a class only the backing snapshot holds has neither
+       * been validated for this session nor bound to its context, so it still has
+       * an adoption to go through.
+       */
+      adoptModel(modelClass, options = {}) {
+        const modelName = this.assertAdoptable(modelClass, options.instanceId);
+        if (this.getActiveModels().get(modelName) === modelClass) {
+          return { added: false };
+        }
+        const candidate = new Map(this.getActiveModels());
+        candidate.set(modelName, modelClass);
+        this.validateModels(candidate);
+        const schema = modelClass.getSchema?.();
+        this.models.set(modelName, modelClass);
+        if (schema?.options) this.modelOptions.set(modelName, schema.options);
+        if (this.activeSessionModels) {
+          this.activeSessionModels.set(modelName, modelClass);
+        }
+        Logger.debug(
+          `[ModelRegistry] Model "${modelName}" adopted by instance #${options.instanceId} at runtime.`
+        );
+        return { added: true };
+      }
       registerModel(modelClass, options, fields) {
         if (!options.name) {
           throw new Error(
@@ -6122,7 +6877,8 @@ var init_ModelRegistry = __esm({
         Logger.debug(`[ModelRegistry] Data removal complete for document ${docId}`);
       }
       // New method to initialize relationships
-      async initializeRelationships() {
+      async initializeRelationships(fallbackDbEngine) {
+        if (!this.dbEngine && fallbackDbEngine) this.dbEngine = fallbackDbEngine;
         if (!this.dbEngine) {
           console.error(
             "[ModelRegistry] DB engine not available for initializing relationships. Ensure initializeAll has been called."
@@ -6274,7 +7030,16 @@ var init_ModelRegistry = __esm({
         return this.activeSessionModels || this.models;
       }
       validateSessionModels() {
-        const activeModels = this.getActiveModels();
+        this.validateModels(this.getActiveModels());
+      }
+      /**
+       * Every relationship of `activeModels` names a model that is also in it.
+       *
+       * Taken as an argument rather than read off the registry so a runtime
+       * adoption can be validated against what the instance WOULD hold before it
+       * holds it (#3615).
+       */
+      validateModels(activeModels) {
         if (!activeModels || activeModels.size === 0) {
           return;
         }
@@ -6726,6 +7491,14 @@ var init_IncludeResolver = __esm({
 function generateULID() {
   return (0, import_ulid2.ulid)();
 }
+function reindexFailure(modelConstructor, modelName, recordId, docId, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const failure = new Error(
+    `[${modelConstructor.name}] Error re-indexing ${modelName}/${recordId} of document ${docId}: ${message}`
+  );
+  failure.cause = error;
+  return failure;
+}
 var Y7, import_ulid2, FORMAT2_ROW_PAGE, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
@@ -6982,21 +7755,56 @@ var init_BaseModel = __esm({
         }
       }
       /**
-       * Build an instance already holding its merged-view row (#3429).
+       * The one gate every local write on a large document passes (#3758).
        *
-       * Every format-2 read path goes through this, so an instance a read produced
-       * never has to go back for its own values: the row it was found by IS its
-       * cache entry, shared with every other live instance of that record.
+       * 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 format2Instance(ctor, store, modelName, docId, recordId, row) {
-        const entry = store.entryFor(modelName, recordId);
-        entry.row = row;
-        entry.loaded = true;
-        const instance = new ctor({ id: recordId });
-        instance._format2Row = entry;
-        instance._format2Unresolved = false;
-        instance._isLoadingFromYjs = true;
-        instance._isDirty = false;
+      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).
+       *
+       * Every format-2 read path goes through this, so an instance a read produced
+       * never has to go back for its own values: the row it was found by IS its
+       * cache entry, shared with every other live instance of that record.
+       */
+      static format2Instance(ctor, store, modelName, docId, recordId, row) {
+        const entry = store.entryFor(modelName, recordId);
+        entry.row = row;
+        entry.loaded = true;
+        const instance = new ctor({ id: recordId });
+        instance._format2Row = entry;
+        instance._format2Unresolved = false;
+        instance._isLoadingFromYjs = true;
+        instance._isDirty = false;
         instance._localChanges = null;
         instance._metaDocId = docId;
         instance._metaPermissionHint = resolveOrmContext(this).connectedDocuments.get(docId)?.permissionHint ?? "read-write";
@@ -7598,19 +8406,31 @@ var init_BaseModel = __esm({
         if (fieldOptions?.default === void 0) return void 0;
         return typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
       }
-      getStringSetFromYjs(fieldName) {
-        const yjsData = this.getFromYjs(fieldName);
-        if (yjsData instanceof Y7.Map) {
-          return Array.from(yjsData.keys());
+      /**
+       * The members of a stringset as it is STORED, in stored order.
+       *
+       * Static and value-only so that the two readers of a stored stringset — the
+       * instance's `getStringSetFromYjs`, which feeds the value a save builds its
+       * unique key from, and `_readableUniqueOwner`, which rebuilds another
+       * record's key from the map — cannot drift apart (#3252).
+       */
+      static _stringSetMembersFromStored(stored) {
+        if (stored instanceof Y7.Map) {
+          return Array.from(stored.keys());
         }
-        if (Array.isArray(yjsData)) {
-          return yjsData.filter((member) => typeof member === "string");
+        if (Array.isArray(stored)) {
+          return stored.filter((member) => typeof member === "string");
         }
-        if (yjsData && typeof yjsData === "object") {
-          return Object.keys(yjsData).filter((k) => Boolean(yjsData[k]));
+        if (stored && typeof stored === "object") {
+          return Object.keys(stored).filter((k) => Boolean(stored[k]));
         }
         return [];
       }
+      getStringSetFromYjs(fieldName) {
+        return this.constructor._stringSetMembersFromStored(
+          this.getFromYjs(fieldName)
+        );
+      }
       getOrCreateStringSet(fieldName) {
         if (!this._stringSetFields.has(fieldName)) {
           const initialValues = this.getStringSetFromYjs(fieldName);
@@ -7639,6 +8459,30 @@ var init_BaseModel = __esm({
           `[${this.name}] initialize(yDoc, db) is no longer supported. Use initializeForDocument(yDoc, db, docId, permission)`
         );
       }
+      /**
+       * Record one observer's asynchronous write of `docId` on this class's ORM
+       * instance (#3023), so a caller that needs the document queryable can wait
+       * for it. The observers themselves track through the context they captured
+       * at install time; this static is for callers that only hold a model class.
+       */
+      static trackDocumentIndexing(docId, work) {
+        resolveOrmContext(this).trackDocumentIndexing(docId, work);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this class's instance
+       * of the query tables (#3023). See
+       * {@link OrmContext.whenDocumentIndexed} — an `open()` that waited for the
+       * initial sync waits for this too, otherwise it resolves on the sync signal
+       * and the caller's first `query()` sees a partly-written table.
+       */
+      static async whenDocumentIndexed(docId) {
+        const drained = await resolveOrmContext(this).whenDocumentIndexed(docId);
+        if (!drained) {
+          Logger.warn(
+            `[BaseModel] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+          );
+        }
+      }
       /**
        * Initialize this model for a connected document.
        *
@@ -7985,7 +8829,7 @@ var init_BaseModel = __esm({
           return recordIdsToDiscard;
         };
         const observerContext = resolveOrmContext(this);
-        const documentYMapObserver = async (event) => {
+        const indexDocumentYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${this.name}] Document YMap change detected for ${modelName}/${docId}:`,
@@ -8154,6 +8998,12 @@ var init_BaseModel = __esm({
           );
           observerContext.notifyListeners(modelName);
         };
+        const documentYMapObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexDocumentYMapChange(event)
+          );
+        };
         documentYMap.observe(documentYMapObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -8179,6 +9029,116 @@ var init_BaseModel = __esm({
           `[${this.name}] Model ${modelName} initialization complete for document ${docId}.`
         );
       }
+      /**
+       * Re-index ONE record of a document from its current Y.Map state (#3615).
+       *
+       * A legacy document's initial load walks the Y.Map before the permanent
+       * observers are installed, so an update that lands in that window reaches
+       * Yjs and misses the query tables. For a document connected long ago — which
+       * is exactly what a model registered at runtime is initialized against —
+       * that window is open on a live document. `registerModel` collects the
+       * record ids touched while it runs and brings each of them here afterwards,
+       * writing the same row the permanent per-record observer would have written.
+       *
+       * A record the window DELETED is deleted here for the same reason.
+       *
+       * A storage failure REJECTS rather than being logged and passed over, the
+       * way the permanent observers' writes are: this write is part of what a
+       * registration promises before it resolves, so swallowing it would resolve a
+       * registration whose query tables are missing the very updates this call
+       * exists to catch, and mark the pair complete so no retry would repair it.
+       */
+      static async reindexDocumentRecord(docId, recordId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed) return;
+        const documentYMap = modelConstructor.documentYMaps.get(
+          `${docId}_${modelName}`
+        );
+        if (!documentYMap) return;
+        const engine = ctx.dbEngine ? await modelConstructor.queryEngineFor([docId], modelName) : null;
+        if (!engine) return;
+        const recordData = documentYMap.get(recordId);
+        if (recordData === void 0 || recordData === null) {
+          try {
+            await engine.delete(modelName, recordId);
+          } catch (error) {
+            throw reindexFailure(
+              modelConstructor,
+              modelName,
+              recordId,
+              docId,
+              error
+            );
+          }
+          ctx.notifyListeners(modelName);
+          return;
+        }
+        const entries = recordData instanceof Y7.Map ? Array.from(recordData.entries()) : Object.entries(recordData);
+        const rowData = {};
+        for (const [fieldKey, value] of entries) {
+          const fieldOptions = schema.fields?.get(fieldKey);
+          if (!fieldOptions || fieldOptions.type === "stringset") continue;
+          if (value === void 0) continue;
+          rowData[fieldKey] = isYjsComposite(value) ? normalizeYjsValueForStorage(value) : value;
+        }
+        if (!rowData.id) return;
+        const permissionHint = modelConstructor.connectedDocuments.get(docId)?.permissionHint ?? "read-write";
+        try {
+          await engine.insert(modelName, {
+            ...rowData,
+            type: modelName,
+            _meta_doc_id: docId,
+            _meta_permission_hint: permissionHint
+          });
+        } catch (error) {
+          throw reindexFailure(
+            modelConstructor,
+            modelName,
+            recordId,
+            docId,
+            error
+          );
+        }
+        ctx.notifyListeners(modelName);
+      }
+      /**
+       * Withdraw ONE document's registration of this model (#3615).
+       *
+       * A `registerModel` that fails part-way through a document keeps the class
+       * registered, because retrying is the recovery. This is what keeps that
+       * half-finished pair from LOOKING finished in the meantime: without the
+       * Y.Map mapping a save raises the same `YMap not found` an unregistered
+       * model raises, instead of writing into a document whose observers were
+       * never installed, and clearing the rows the failed load managed to write
+       * keeps a query from answering out of a document nothing is watching. The
+       * retry's `initializeForDocument` publishes both again.
+       *
+       * `connectedDocuments` is deliberately left alone: it is the CONTEXT's map,
+       * shared by every model on the instance, so the document itself is still
+       * connected for everything else.
+       */
+      static async withdrawDocumentRegistration(docId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        modelConstructor.documentYMaps.delete(`${docId}_${modelName}`);
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed || !ctx.dbEngine) return;
+        try {
+          const engine = await modelConstructor.queryEngineFor([docId], modelName);
+          await engine.deleteByDocumentId(modelName, docId);
+        } catch (error) {
+          Logger.warn(
+            `[${modelConstructor.name}] Could not clear ${modelName} rows of document ${docId} while withdrawing an incomplete registration:`,
+            error
+          );
+        }
+      }
       // New method to clean up data for a disconnected document
       static async cleanupDocumentData(docId) {
         const modelConstructor = this;
@@ -8437,6 +9397,48 @@ var init_BaseModel = __esm({
           constraintName
         );
       }
+      /**
+       * The record that READABLY owns `uniqueKey` under `constraint` in one
+       * document's model map, or `null`.
+       *
+       * The `_uniqueIdx_` map is a cache over the records, not the record store,
+       * and the two can disagree (#3252): a replica can hold an index entry for a
+       * record whose structs have not landed yet, or an entry a field change or
+       * delete left behind. `save()` used to take the entry at its word, so the
+       * app saw a `query` that returned no row for a value and a save refused for
+       * that same value — the index knew a row nothing else could read.
+       *
+       * An entry counts only when its owner is readable: the record map exists
+       * under that id in `modelYMap`, and the key built from the record's stored
+       * fields is `uniqueKey`. Anything else is a stale entry, and the caller
+       * treats it as an index miss — the engine fallback decides, exactly as it
+       * does for a missing entry — so the write that follows lands and rewrites
+       * the entry to the record that really holds the value.
+       *
+       * "The key built from the record's stored fields" has to mean the key that
+       * record's own save built, so the stored value is read the way the save
+       * read it: a stringset is stored as a nested Y.Map of its members but keyed
+       * as the array `getCurrentJSState` puts in `dataToSave` (finding 3252-01).
+       * Comparing the raw Y.Map would call every readable owner of a unique
+       * stringset stale and let a duplicate straight through the constraint.
+       */
+      static _readableUniqueOwner(modelYMap, constraintMap, constraint, uniqueKey, modelName) {
+        const ownerId = constraintMap.get(uniqueKey);
+        if (!ownerId) return null;
+        const recordYMap = modelYMap?.get(ownerId);
+        if (!(recordYMap instanceof Y7.Map)) return null;
+        const fields = this.getSchema?.()?.fields;
+        const heldKey = this._buildKeyFromValues(
+          constraint.fields,
+          constraint.fields.map((field) => {
+            const stored = recordYMap.get(field);
+            return fields?.get(field)?.type === "stringset" ? this._stringSetMembersFromStored(stored) : stored;
+          }),
+          modelName,
+          constraint.name
+        );
+        return heldKey === uniqueKey ? ownerId : null;
+      }
       /**
        * The connected format-2 document that holds this instance's record, for an
        * instance the constructor could not resolve (#3429, finding 3429-03).
@@ -8585,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,
@@ -8634,7 +9640,14 @@ var init_BaseModel = __esm({
           const constraintMap = yDoc.getMap(
             uniqueIndexMapName(modelName, constraint.name)
           );
-          if (!constraintMap.get(newUniqueKey)) {
+          const readableOwner = modelConstructor._readableUniqueOwner(
+            targetYMap,
+            constraintMap,
+            constraint,
+            newUniqueKey,
+            modelName
+          );
+          if (!readableOwner) {
             const constraintKeyValues = constraint.fields.map(
               (field) => dataToSave[field]
             );
@@ -8652,7 +9665,13 @@ var init_BaseModel = __esm({
           if (upsertOnConstraint && upsertOnKey) {
             const constraintMapName = `_uniqueIdx_${modelName}_${upsertOnConstraint.name}`;
             const constraintMap = yDoc.getMap(constraintMapName);
-            const existingId = constraintMap.get(upsertOnKey);
+            const existingId = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              upsertOnConstraint,
+              upsertOnKey,
+              modelName
+            );
             if (existingId) {
               if (this._constructorProvidedId && this.id !== existingId) {
                 throw new Error(
@@ -8752,7 +9771,13 @@ var init_BaseModel = __esm({
                 50
               )}'`
             );
-            const existingRecordIdWithNewKey = constraintMap.get(newUniqueKey);
+            const existingRecordIdWithNewKey = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              constraint,
+              newUniqueKey,
+              modelName
+            );
             Logger.verbose(
               `[${modelName}] Save Check (Item '${this.id}'): Found Existing ID: '${existingRecordIdWithNewKey}' for Key '${newUniqueKey.substring(
                 0,
@@ -9341,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,
@@ -9367,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;
@@ -9390,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,
@@ -9659,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();
         }
@@ -10437,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(
@@ -10485,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,
@@ -10571,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
@@ -10890,7 +11945,7 @@ var init_BaseModel = __esm({
         );
         modelConstructor.attachStringSetObserversToRecord(recordYMap, schema, docId);
         const observerContext = resolveOrmContext(modelConstructor);
-        const recordObserver = async (event) => {
+        const indexNestedYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${modelName}] Nested YMap change detected for record ${recordId} in document ${docId}:`,
@@ -10966,6 +12021,12 @@ var init_BaseModel = __esm({
           }
           observerContext.notifyListeners(modelName);
         };
+        const recordObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexNestedYMapChange(event)
+          );
+        };
         recordYMap.observe(recordObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -11031,6 +12092,7 @@ __export(browser_exports, {
   completeOverlayEntries: () => completeOverlayEntries,
   configuredOfflineWindowDays: () => configuredOfflineWindowDays,
   createModelClass: () => createModelClass,
+  decideDeferredReplay: () => decideDeferredReplay,
   decodeFormat2StoreError: () => decodeFormat2StoreError,
   defineModelSchema: () => defineModelSchema,
   detectEnvironment: () => detectEnvironment,
@@ -11041,10 +12103,12 @@ __export(browser_exports, {
   encodeOverlayMutation: () => encodeOverlayMutation,
   estimateMaterializedBytes: () => estimateMaterializedBytes,
   features: () => features,
+  findReservedFieldNameInToml: () => findReservedFieldNameInToml,
   foldFormat2Overlay: () => foldFormat2Overlay,
   followEpoch: () => followEpoch,
   format2ClientDDL: () => format2ClientDDL,
   format2EpochDocName: () => format2EpochDocName,
+  format2EpochDocPrefix: () => format2EpochDocPrefix,
   format2StringSetMembers: () => format2StringSetMembers,
   format2TableNames: () => format2TableNames,
   generateULID: () => generateULID,
@@ -11183,6 +12247,30 @@ var DatabaseEngine = class {
    * as "follows no epoch".
    */
   format2StoredEpoch;
+  /**
+   * Remove one large document's local data, and the store holding it when
+   * nothing else is in there.
+   *
+   * 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`.
    *
@@ -12356,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;
@@ -12419,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",
@@ -12943,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);
@@ -12960,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) {
@@ -13163,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 = "";
@@ -13229,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({
@@ -13328,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}`
@@ -13344,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}`
@@ -13356,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);
@@ -13366,7 +14539,7 @@ var OpfsEngine = class {
         entry.docIds.delete(docId);
         engine.docs.delete(docId);
       }
-      releasePresence?.();
+      releasePresence();
       return host.close(closeOptions);
     };
     let closing = null;
@@ -13402,73 +14575,464 @@ var OpfsEngine = class {
       return null;
     }
   }
-  /** `navigator.locks`, unless a test handed one in. `null` means none. */
-  locks() {
-    if (this.internals.locks !== void 0) return this.internals.locks;
-    const locks = globalThis.navigator?.locks;
-    return locks && typeof locks.request === "function" ? locks : null;
-  }
+  // ── Removing a document's store, and the pool holding it (#3754) ──
   /**
-   * Hold `name` until the returned function is called.
+   * Remove `docId`'s local data, and its pool's directory once it holds
+   * nothing else.
    *
-   * The release is SYNCHRONOUS on purpose: resolving the callback's promise is
-   * what frees a Web Lock, and a page being torn down gets one task to do it
-   * in — nothing it awaits afterwards will run.
+   * 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).
    *
-   * A release can arrive BEFORE the grant does: a lock manager queues the
-   * callback as a task, and a document opened and closed inside one task never
-   * gets there. The release is therefore remembered, not merely delivered —
-   * the callback resolves at once when it finally runs, and a request still
-   * 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.
+   * 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).
    */
-  holdPresence(name) {
-    const locks = this.locks();
-    if (!locks) return null;
-    let release = null;
-    let done = false;
-    const withdraw = typeof AbortController === "function" ? new AbortController() : null;
-    void Promise.resolve(
-      locks.request(
-        name,
-        { mode: "exclusive", ...withdraw ? { signal: withdraw.signal } : {} },
-        () => new Promise((resolve) => {
-          if (done) resolve();
-          else release = resolve;
-        })
+  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
       )
-    ).catch(() => {
-    });
-    return () => {
-      done = true;
-      release?.();
-      withdraw?.abort();
-    };
-  }
-  /** Whether somebody holds `name` right now. Never waits. */
-  async probeLock(name) {
-    const locks = this.locks();
-    if (!locks) return false;
-    try {
-      return await locks.request(
-        name,
-        { ifAvailable: true },
-        (lock) => lock === null
+    );
+    if (!taken.got) {
+      Logger.warn(
+        `[OpfsEngine] ${docId}: purge refused: held (another tab holds its presence lock, so it still has the document open).`
       );
-    } catch {
-      return false;
+      return { purged: false, reason: "held", presence: true };
     }
+    return taken.value;
   }
   /**
-   * The engine holding `docIds`' rows of `modelName` (Decision R).
-   *
-   * All ordinary → the mirror. One side only → that side. A scope spanning
-   * both an ordinary and a large document (or two large documents) is probed
-   * with one `LIMIT 1` existence query per side: exactly one side holding
-   * rows answers; both is refused with `Format2QueryScopeError`; neither
-   * answers empty from a side that HAS the model's table — the mirror only
-   * sees a model's table once an ordinary document connected, so two large
-   * documents with no rows yet are answered from one of their workers.
+   * 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;
+    const locks = globalThis.navigator?.locks;
+    return locks && typeof locks.request === "function" ? locks : null;
+  }
+  /**
+   * Hold `name` until the returned function is called.
+   *
+   * The release is SYNCHRONOUS on purpose: resolving the callback's promise is
+   * what frees a Web Lock, and a page being torn down gets one task to do it
+   * in — nothing it awaits afterwards will run.
+   *
+   * A release can arrive BEFORE the grant does: a lock manager queues the
+   * callback as a task, and a document opened and closed inside one task never
+   * gets there. The release is therefore remembered, not merely delivered —
+   * the callback resolves at once when it finally runs, and a request still
+   * 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, mode = "exclusive") {
+    const locks = this.locks();
+    if (!locks) return null;
+    let release = null;
+    let done = false;
+    const withdraw = typeof AbortController === "function" ? new AbortController() : null;
+    void Promise.resolve(
+      locks.request(
+        name,
+        { mode, ...withdraw ? { signal: withdraw.signal } : {} },
+        () => new Promise((resolve) => {
+          if (done) resolve();
+          else release = resolve;
+        })
+      )
+    ).catch(() => {
+    });
+    return () => {
+      done = true;
+      release?.();
+      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();
+    if (!locks) return false;
+    try {
+      return await locks.request(
+        name,
+        { ifAvailable: true },
+        (lock) => lock === null
+      );
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * The engine holding `docIds`' rows of `modelName` (Decision R).
+   *
+   * All ordinary → the mirror. One side only → that side. A scope spanning
+   * both an ordinary and a large document (or two large documents) is probed
+   * with one `LIMIT 1` existence query per side: exactly one side holding
+   * rows answers; both is refused with `Format2QueryScopeError`; neither
+   * answers empty from a side that HAS the model's table — the mirror only
+   * sees a model's table once an ordinary document connected, so two large
+   * documents with no rows yet are answered from one of their workers.
    *
    * A document whose worker died is refused with `DocumentClosedError`, the
    * error its store already raises: the rows exist and nobody serves them.
@@ -13616,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) => {
@@ -14044,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: [],
@@ -14051,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;
     }
@@ -14087,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();
@@ -14411,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(
@@ -14445,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).
@@ -14664,6 +16352,31 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
    * hydration scope; an uncapped one answers with the models this instance
    * registered, which is every model whose rows could be here.
    */
+  /**
+   * Hydrate ONE model's derived query tables for a bound large document
+   * (#3615).
+   *
+   * What a model registered on a running instance needs: the merged view
+   * already holds its rows — the fold and the overlay observer are keyed by
+   * the model name the overlay carries, not by the registry — but the derived
+   * tables `query()` reads were never built, because the model was not in the
+   * registry when the document was connected.
+   *
+   * Forced, because the point is a rebuild: whatever mark a previous session
+   * left says nothing about tables this instance has never projected into.
+   */
+  async hydrateModel(docId, modelName) {
+    const store = this.opened.get(docId);
+    if (!store) return;
+    if (!store.isHydrated(modelName)) {
+      Logger.warn(
+        `[DocumentManager] Large document ${docId} does not hold model '${modelName}' on this device (its hydration scope excludes it), so the query tables for '${modelName}' were not hydrated. Reads of '${modelName}' on ${docId} answer as they do for any model this device declined.`
+      );
+      return;
+    }
+    await this.hydrateQueryTables(docId, store, { only: modelName });
+    await this.whenProjectionSettled();
+  }
   localModels(docId) {
     const store = this.ormContext.getFormat2StoreAsync(docId);
     if (!store) return null;
@@ -15063,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);
@@ -15099,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;
@@ -15108,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) {
@@ -15120,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);
@@ -15199,12 +17001,70 @@ var DocumentManagerImpl = class {
   modelRegistry;
   /** The ORM instance this manager belongs to (#3039). */
   ormContext;
+  /**
+   * The registration gate (#3615).
+   *
+   * `connectDocument` finishes its model loop BEFORE it publishes the document
+   * in `connectedDocuments`, so a registration that read the map in that
+   * interval would miss the document while its own loop had already run —
+   * leaving it connected with no table, no rows and no observer for the new
+   * model. Registrations therefore run one at a time on this chain; a connect,
+   * a rebind and a disconnect wait for it at entry, and a registration waits
+   * for the connects that got in before it ({@link activeConnects}) before it
+   * reads the map. Connects of different documents that no registration
+   * overlaps still run concurrently, as they always have.
+   */
+  registrationChain = Promise.resolve();
+  /** Connects past the gate and not yet published — what a registration waits for. */
+  activeConnects = /* @__PURE__ */ new Set();
+  /**
+   * The `(model, document)` pairs whose initialization for this instance
+   * COMPLETED (#3615).
+   *
+   * Registry membership alone cannot say it: a document-level failure leaves
+   * the class registered but that document unusable, and `initializeForDocument`
+   * clears a document's rows and installs a fresh observer on every run, so a
+   * blanket retry would wipe the documents that had succeeded and double their
+   * observers. A retry resumes with the pairs that are not in here.
+   */
+  runtimeInitialized = /* @__PURE__ */ new Map();
+  /**
+   * Pass the registration gate, then run `work` as an in-flight connect
+   * (#3615).
+   *
+   * The re-read after the await is what closes the window: a registration
+   * publishes its chain synchronously when it is called, so a caller that
+   * waited on the chain it saw first has to check whether another one was
+   * queued behind it. Joining {@link activeConnects} happens with no await in
+   * between, so nothing can slip between the check and the join.
+   */
+  async enterConnect(work) {
+    for (; ; ) {
+      const chain = this.registrationChain;
+      await chain;
+      if (this.registrationChain === chain) break;
+    }
+    let settle;
+    const ticket = new Promise((resolve) => settle = resolve);
+    this.activeConnects.add(ticket);
+    try {
+      return await work();
+    } finally {
+      this.activeConnects.delete(ticket);
+      settle();
+    }
+  }
   async connectDocument(docId, yDoc, permissionHint, options) {
+    return this.enterConnect(
+      () => this.connectDocumentInner(docId, yDoc, permissionHint, options)
+    );
+  }
+  async connectDocumentInner(docId, yDoc, permissionHint, options) {
     if (this.connectedDocuments.has(docId)) {
       console.warn(
         `[DocumentManager] Document ${docId} is already connected. Disconnecting old version.`
       );
-      await this.disconnectDocument(docId);
+      await this.disconnectDocumentInner(docId);
     }
     const documentFormat = options?.documentFormat ?? 1;
     const connectedDoc = {
@@ -15231,6 +17091,9 @@ var DocumentManagerImpl = class {
       await this.format2.connect(docId, yDoc, options?.epoch);
     }
     this.connectedDocuments.set(docId, connectedDoc);
+    for (const modelName of this.modelRegistry.getActiveModels().keys()) {
+      this.markRuntimeInitialized(modelName, docId);
+    }
     this.notifyConnectionChange({
       type: "connect",
       docId,
@@ -15249,6 +17112,11 @@ var DocumentManagerImpl = class {
    * models read and write through is exchanged.
    */
   async rebindEpochDocument(docId, yDoc, options = {}) {
+    return this.enterConnect(
+      () => this.rebindEpochDocumentInner(docId, yDoc, options)
+    );
+  }
+  async rebindEpochDocumentInner(docId, yDoc, options = {}) {
     const connected = this.connectedDocuments.get(docId);
     if (!connected) {
       throw new Error(
@@ -15363,6 +17231,9 @@ var DocumentManagerImpl = class {
     return await this.format2.recordPresence(docId, records);
   }
   async disconnectDocument(docId) {
+    return this.enterConnect(() => this.disconnectDocumentInner(docId));
+  }
+  async disconnectDocumentInner(docId) {
     const connectedDoc = this.connectedDocuments.get(docId);
     if (!connectedDoc) {
       Logger.warn(`[DocumentManager] Document ${docId} is not connected`);
@@ -15379,6 +17250,9 @@ var DocumentManagerImpl = class {
       wipeModels ? { wipeIfLastModels: wipeModels } : {}
     );
     this.connectedDocuments.delete(docId);
+    for (const docIds of this.runtimeInitialized.values()) {
+      docIds.delete(docId);
+    }
     this.ormContext.disposeObserversForDocument(docId);
     this.ormContext.clearMappingsForDocId(docId);
     this.notifyConnectionChange({
@@ -15389,10 +17263,150 @@ var DocumentManagerImpl = class {
       `[DocumentManager] Document ${docId} disconnected successfully`
     );
   }
+  markRuntimeInitialized(modelName, docId) {
+    let docIds = this.runtimeInitialized.get(modelName);
+    if (!docIds) {
+      docIds = /* @__PURE__ */ new Set();
+      this.runtimeInitialized.set(modelName, docIds);
+    }
+    docIds.add(docId);
+  }
+  /**
+   * Add a model to this running instance (#3615). See
+   * {@link InitJsBaoResult.registerModel}.
+   */
+  async registerModel(modelClass) {
+    const previous = this.registrationChain;
+    let release;
+    this.registrationChain = new Promise((resolve) => release = resolve);
+    try {
+      await previous;
+      while (this.activeConnects.size > 0) {
+        await Promise.all(Array.from(this.activeConnects));
+      }
+      await this.runRegistration(modelClass);
+    } finally {
+      release();
+    }
+  }
+  async runRegistration(modelClass) {
+    if (this.ormContext.destroyed) {
+      throw new Error(
+        `[initJsBao] Cannot register model on destroyed js-bao instance #${this.ormContext.instanceId}. Create a new instance with initJsBao.`
+      );
+    }
+    const modelName = this.modelRegistry.assertAdoptable(
+      modelClass,
+      this.ormContext.instanceId
+    );
+    const boundTo = modelClass?._ormContext;
+    if (boundTo && boundTo !== this.ormContext && !boundTo.destroyed) {
+      throw new Error(
+        `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${boundTo.instanceId}. Give instance #${this.ormContext.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
+      );
+    }
+    const { added } = this.modelRegistry.adoptModel(modelClass, {
+      instanceId: this.ormContext.instanceId
+    });
+    bindModelClass(this.ormContext, modelName, modelClass, "throw");
+    let didDocumentWork = false;
+    for (const connected of Array.from(this.connectedDocuments.values())) {
+      if (this.runtimeInitialized.get(modelName)?.has(connected.docId)) {
+        continue;
+      }
+      didDocumentWork = true;
+      try {
+        await this.initializeModelForConnectedDocument(
+          modelClass,
+          modelName,
+          connected
+        );
+      } catch (error) {
+        await modelClass.withdrawDocumentRegistration(connected.docId);
+        const message = error instanceof Error ? error.message : String(error);
+        const wrapped = new Error(
+          `[initJsBao] registerModel('${modelName}') failed on document ${connected.docId}; registration is incomplete and can be retried: ` + message
+        );
+        wrapped.cause = error;
+        throw wrapped;
+      }
+      this.markRuntimeInitialized(modelName, connected.docId);
+    }
+    if (added || didDocumentWork) {
+      await this.modelRegistry.initializeRelationships(this.dbEngine);
+    }
+  }
+  /**
+   * Initialize one model for one already-connected document (#3615).
+   *
+   * The legacy half carries the window `initializeForDocument` leaves open: it
+   * loads the Y.Map as records in an asynchronous transaction and installs its
+   * observers afterwards, which on a document the app connected long ago is a
+   * live document still receiving peer updates. A temporary deep observer
+   * collects the record ids touched while that runs; once the instance's
+   * indexing for the document has drained, each of them is written from its
+   * CURRENT state, so the call resolves with the query tables holding every
+   * update that arrived before it did.
+   */
+  async initializeModelForConnectedDocument(modelClass, modelName, connected) {
+    const { docId, yDoc, permissionHint } = connected;
+    const documentFormat = connected.documentFormat ?? 1;
+    if (documentFormat === 2) {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        2
+      );
+      await this.format2.hydrateModel(docId, modelName);
+      return;
+    }
+    const touched = /* @__PURE__ */ new Set();
+    const documentYMap = yDoc.getMap(modelName);
+    const collect2 = (events) => {
+      for (const event of events) {
+        if (event.target === documentYMap) {
+          for (const key of event.changes.keys.keys()) touched.add(key);
+        } else if (event.path.length > 0) {
+          touched.add(String(event.path[0]));
+        }
+      }
+    };
+    documentYMap.observeDeep(collect2);
+    try {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        1
+      );
+      await this.whenDocumentIndexed(docId);
+      for (const recordId of touched) {
+        await modelClass.reindexDocumentRecord(docId, recordId);
+      }
+    } finally {
+      documentYMap.unobserveDeep(collect2);
+    }
+  }
   /** Resolves once every enqueued query-projection refresh has been applied. */
   whenFormat2ProjectionSettled() {
     return this.format2.whenProjectionSettled();
   }
+  /**
+   * Resolves once THIS instance's query tables have caught up with `docId`
+   * (#3023). Scoped to the instance's own context, so a second client holding
+   * the same document id never waits on this one's writes.
+   */
+  async whenDocumentIndexed(docId) {
+    const drained = await this.ormContext.whenDocumentIndexed(docId);
+    if (!drained) {
+      Logger.warn(
+        `[DocumentManager] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+      );
+    }
+  }
   getConnectedDocuments() {
     return new Map(this.connectedDocuments);
   }
@@ -15420,22 +17434,33 @@ var DocumentManagerImpl = class {
 };
 function bindSessionModels(ctx, registry) {
   for (const [modelName, modelClass] of registry.getActiveModels()) {
-    const current = modelClass?._ormContext;
-    if (current === ctx) continue;
-    if (!current || current.destroyed) {
-      Object.defineProperty(modelClass, "_ormContext", {
-        value: ctx,
-        writable: true,
-        configurable: true,
-        enumerable: false
-      });
-      ctx.boundModels.add(modelClass);
-      continue;
-    }
-    console.warn(
-      `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+    bindModelClass(ctx, modelName, modelClass, "warn");
+  }
+}
+function bindModelClass(ctx, modelName, modelClass, onLiveConflict) {
+  const current = modelClass?._ormContext;
+  if (current === ctx) {
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (!current || current.destroyed) {
+    Object.defineProperty(modelClass, "_ormContext", {
+      value: ctx,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (onLiveConflict === "throw") {
+    throw new Error(
+      `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${current.instanceId}. Give instance #${ctx.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
     );
   }
+  console.warn(
+    `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+  );
 }
 async function initJsBaoCore(options, getEngine) {
   const { databaseConfig, models: modelClasses } = options;
@@ -15464,6 +17489,7 @@ async function initJsBaoCore(options, getEngine) {
       destroy: () => ormContext.destroy(),
       connectDocument: docManager.connectDocument.bind(docManager),
       disconnectDocument: docManager.disconnectDocument.bind(docManager),
+      registerModel: docManager.registerModel.bind(docManager),
       format2SyncMarks: (docId) => format2SyncMarks(docId, ormContext),
       format2StoredEpoch: (docId) => format2StoredEpoch(dbEngine, docId, ormContext),
       // The pre-bind epoch read opens the same pool the bind will, so it needs
@@ -15475,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),
@@ -15496,6 +17547,7 @@ async function initJsBaoCore(options, getEngine) {
       // queue updates after it). The transport awaits it before an update
       // from the room counts as applied.
       whenFormat2ProjectionSettled: docManager.whenFormat2ProjectionSettled.bind(docManager),
+      whenDocumentIndexed: docManager.whenDocumentIndexed.bind(docManager),
       format2LoadSnapshot: docManager.loadSnapshot.bind(docManager),
       format2LocalModels: (docId) => docManager.localModels(docId),
       format2RecordPresence: (docId, records) => docManager.recordPresence(docId, records),
@@ -15899,6 +17951,26 @@ function schemaToToml(schema) {
 
 // src/models/tomlLoader.ts
 var import_smol_toml = require("smol-toml");
+
+// src/utils/reservedFields.ts
+function checkReservedFieldName(fieldName) {
+  if (fieldName === "id") return null;
+  if (fieldName === "type") {
+    return `Field 'type' is reserved (maps to internal _type column in queries)`;
+  }
+  if (fieldName.startsWith("_")) {
+    return `Field '${fieldName}' is reserved (fields starting with '_' are internal)`;
+  }
+  return null;
+}
+var ReservedFieldNameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReservedFieldNameError";
+  }
+};
+
+// src/models/tomlLoader.ts
 var VALID_FIELD_TYPES = /* @__PURE__ */ new Set([
   "string",
   "number",
@@ -16045,6 +18117,7 @@ function parseRelationship(raw, context, strict) {
 }
 function loadSchemaFromTomlString(tomlString, options = {}) {
   const strict = options.strict !== false;
+  const rejectReserved = options.rejectReservedFieldNames === true;
   const parsed = (0, import_smol_toml.parse)(tomlString);
   const models = parsed.models;
   if (!models || typeof models !== "object") {
@@ -16061,11 +18134,14 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
     const fields = {};
     if (modelDef.fields) {
       for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
-        fields[fieldName] = parseFieldOptions(
-          fieldDef,
-          `[models.${modelName}.fields.${fieldName}]`,
-          strict
-        );
+        const context = `[models.${modelName}.fields.${fieldName}]`;
+        if (rejectReserved) {
+          const reserved = checkReservedFieldName(fieldName);
+          if (reserved) {
+            throw new ReservedFieldNameError(`${context}: ${reserved}`);
+          }
+        }
+        fields[fieldName] = parseFieldOptions(fieldDef, context, strict);
       }
     }
     let relationships;
@@ -16112,6 +18188,18 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
   }
   return schemas;
 }
+function findReservedFieldNameInToml(tomlString) {
+  try {
+    loadSchemaFromTomlString(tomlString, {
+      strict: false,
+      rejectReservedFieldNames: true
+    });
+    return null;
+  } catch (error) {
+    if (error instanceof ReservedFieldNameError) return error.message;
+    return null;
+  }
+}
 
 // src/browser.ts
 init_metaSync();
@@ -16125,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(
@@ -16274,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: [] };
@@ -16294,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) {