js-bao 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -96,10 +96,28 @@ interface DatabaseConfig {
 }
 
 type DocumentPermissionHint = "read" | "read-write";
+/**
+ * Per-document storage format (#2816). `1` (or absent) is the legacy "one
+ * Y.Doc" document; `2` is a large document whose Y.Doc holds only the current
+ * epoch's overlay and whose merged `records` table is the document.
+ */
+type DocumentFormat = 1 | 2;
+interface ConnectDocumentOptions {
+    documentFormat?: DocumentFormat;
+    /**
+     * The epoch a large document is on, as the caller understands it (#2816).
+     *
+     * The record store is created following epoch 0, which the open path reads
+     * as "this database holds no document" — so a bind without the mark makes a
+     * client that has the document look like one that never did.
+     */
+    epoch?: number;
+}
 interface ConnectedDocument {
     docId: string;
     yDoc: Y.Doc;
     permissionHint: DocumentPermissionHint;
+    documentFormat?: DocumentFormat;
 }
 interface SaveOptions {
     targetDocument?: string;
@@ -107,7 +125,7 @@ interface SaveOptions {
     upsertOn?: string;
 }
 interface DocumentManager {
-    connectDocument(docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint): Promise<void>;
+    connectDocument(docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint, options?: ConnectDocumentOptions): Promise<void>;
     disconnectDocument(docId: string): Promise<void>;
     getConnectedDocuments(): Map<string, ConnectedDocument>;
     isDocumentConnected(docId: string): boolean;
@@ -217,6 +235,549 @@ interface PaginationOptions {
     direction?: "forward" | "backward";
 }
 
+/**
+ * Shared format-2 ("large document", #2816) primitives.
+ *
+ * A format-2 document is no longer "one Y.Doc": the authoritative document is
+ * a persisted SQLite `records` table on both ends, and the Y.Doc shrinks to a
+ * bounded per-epoch **state overlay** of the records/fields touched during the
+ * current epoch. This module owns the overlay's on-the-wire shape so the
+ * client write points, the client observer, the server projector, the
+ * materializer and the snapshot builder all encode and decode it identically.
+ *
+ * ## Encoding — flat field-level keys (sponsor amendment, 2026-08-21)
+ *
+ * Each model map holds FLAT entries, not one nested `Y.Map` per record:
+ *
+ * ```
+ * ⟨recordId⟩/⟨field⟩            → value      ordinary field (`null` = unset)
+ * ⟨recordId⟩/⟨field⟩/⟨member⟩   → true|false stringset member / tombstone (D3)
+ * ⟨recordId⟩/_replace           → true       discard the base row
+ * ⟨recordId⟩/_deleted           → true|false record tombstone
+ * ```
+ *
+ * The nested layout cannot work under epochs: two clients that both touch a
+ * record ABSENT from the current epoch each mint a fresh `Y.Map` at the same
+ * model-map key, and Yjs resolves that parent-key conflict as last-writer-wins,
+ * silently dropping the loser's fields. With flat keys, concurrency resolves
+ * per field key, so a concurrent create-vs-patch merges to the union of fields
+ * with LWW only on genuinely colliding fields.
+ *
+ * The record's LOGICAL overlay content is unchanged from the approved design —
+ * consumers group a record's keys back into a fields object plus markers via
+ * {@link groupOverlayEntries} and apply the record-level rules in
+ * {@link materializeOverlayRecord}.
+ */
+
+/** Separator between the record-id, field and member segments of an overlay key. */
+declare const OVERLAY_KEY_SEPARATOR = "/";
+/** Marker key: the create discards the base row and writes exactly its fields. */
+declare const OVERLAY_MARKER_REPLACE = "_replace";
+/** Marker key: the record is deleted (a bare Yjs key delete is invisible). */
+declare const OVERLAY_MARKER_DELETED = "_deleted";
+/**
+ * Escape one overlay-key segment so the key stays unambiguous.
+ *
+ * Record ids are ULIDs and always safe, but field and member names are user
+ * data: they may contain the separator, the escape character, or start with the
+ * `_` that marks a marker key. Escaping is RFC 6901-flavored:
+ *
+ * - `~` → `~0`
+ * - `/` → `~1`
+ * - a LEADING `_` → `~2` (so a field literally named `_replace` can never be
+ *   read back as the `_replace` marker, which is written unescaped)
+ */
+declare function encodeOverlaySegment(segment: string): string;
+/** Inverse of {@link encodeOverlaySegment}. */
+declare function decodeOverlaySegment(segment: string): string;
+/** Overlay key for an ordinary field of a record. */
+declare function overlayFieldKey(recordId: string, field: string): string;
+/** Overlay key for one stringset member of a record's field. */
+declare function overlayMemberKey(recordId: string, field: string, member: string): string;
+/** Overlay key for a record-level marker (written unescaped, by construction). */
+declare function overlayMarkerKey(recordId: string, marker: string): string;
+/** The parts an overlay key decodes to, or `null` when it is not an overlay key. */
+interface ParsedOverlayKey {
+    recordId: string;
+    field?: string;
+    member?: string;
+    marker?: string;
+}
+/** Decode an overlay key back into its parts; `null` when it is malformed. */
+declare function parseOverlayKey(key: string): ParsedOverlayKey | null;
+/** One record's overlay content, regrouped from its flat keys. */
+interface OverlayRecordEntry {
+    id: string;
+    /** Touched ordinary fields. A `null` value is an explicit unset (RFC 7396). */
+    fields: Record<string, unknown>;
+    /** Touched stringset members per field: `member → true` add, `false` tombstone. */
+    stringSets: Record<string, Record<string, boolean>>;
+    /** The create discarded the base row. */
+    replace: boolean;
+    /** The record is tombstoned. */
+    deleted: boolean;
+}
+/**
+ * Regroup a model map's flat overlay entries into one {@link OverlayRecordEntry}
+ * per record. Accepts anything iterable of `[key, value]` — a `Y.Map`'s
+ * `entries()`, an array of observed changes, or a decoded snapshot.
+ */
+declare function groupOverlayEntries(entries: Iterable<readonly [string, unknown]>): Map<string, OverlayRecordEntry>;
+/** Anything that can enumerate a model map's overlay keys. */
+interface OverlayEntrySource {
+    entries(): Iterable<readonly [string, unknown]> | IterableIterator<any>;
+}
+/**
+ * Read ONE record's complete overlay entry out of a model map.
+ *
+ * A delta fold — projecting exactly the keys an update touched — is right for
+ * a patch, which merges over the stored row. It is wrong for `_replace`: that
+ * marker discards the row entirely, so the record has to be rebuilt from every
+ * overlay key it currently has, not just the ones the arriving update carried.
+ * Concurrency is where the two differ: when one client patches a record while
+ * another deletes and re-creates it, Yjs merges their keys per key, and the
+ * update carrying `_replace` names only its own — folding it alone would drop
+ * the concurrent patch that the overlay itself still holds.
+ *
+ * Costs a walk of the model map, which is bounded by the epoch rotation
+ * threshold. Use {@link completeOverlayEntries} when several records need
+ * rebuilding: it pays that walk ONCE for all of them.
+ */
+declare function readOverlayRecord(modelMap: OverlayEntrySource, recordId: string): OverlayRecordEntry;
+/**
+ * Complete the entries of a delta fold that need the record's whole overlay.
+ *
+ * Applied by both the server's projector and the client's observer, so the
+ * authoritative table and the local merged view fold an update identically.
+ *
+ * Every create carries `_replace`, so this sits on the hot write path: the
+ * model map is walked ONCE per call however many records were replaced. A walk
+ * per replaced record would make one bulk create quadratic in the number of
+ * records it writes.
+ */
+declare function completeOverlayEntries(modelMap: OverlayEntrySource, entries: Map<string, OverlayRecordEntry>): Map<string, OverlayRecordEntry>;
+/**
+ * Materialize one record: `base ⊕ overlay`, the operation that turns
+ * `S_E ⊕ D_E` into the authoritative `records` row.
+ *
+ * - a `_deleted` tombstone materializes to `null` (delete the row);
+ * - `_replace` discards `base` entirely and writes exactly the overlay's
+ *   fields, so a delete-then-re-create cannot resurrect base fields the
+ *   re-created record omitted;
+ * - an ordinary field merges RFC 7396-style, with an explicit `null` removing
+ *   the key;
+ * - stringset member keys apply as add/remove deltas over the base members.
+ *
+ * Applying an overlay is idempotent and order-free at the record level, so a
+ * torn read during a snapshot build is corrected by the next overlay.
+ */
+declare function materializeOverlayRecord(base: Record<string, unknown> | null | undefined, overlay: OverlayRecordEntry): Record<string, unknown> | null;
+/** A record mutation expressed in overlay terms, before it is encoded to keys. */
+interface OverlayMutation {
+    id: string;
+    /**
+     * `create` writes `_replace` (the id is absent from the merged view) and
+     * clears any prior `_deleted`; `patch` touches only the named fields;
+     * `delete` writes the `_deleted` tombstone.
+     */
+    kind: "create" | "patch" | "delete";
+    /** Ordinary field values; `null` is an explicit unset. */
+    fields?: Record<string, unknown>;
+    /** Per-field stringset deltas: `member → true` add, `false` remove (D3). */
+    stringSetDeltas?: Record<string, Record<string, boolean>>;
+}
+/**
+ * Encode a mutation into the flat overlay entries it writes. Returned as
+ * `[key, value]` pairs so callers can apply them to a `Y.Map`, ship them, or
+ * assert on them without a Y.Doc.
+ */
+declare function encodeOverlayMutation(mutation: OverlayMutation): Array<[string, unknown]>;
+/** Apply {@link encodeOverlayMutation}'s entries to a model map in one place. */
+declare function applyOverlayMutation(modelMap: Y.Map<any>, mutation: OverlayMutation): void;
+/**
+ * A composite (`Y.Map` / `Y.Array` / `Y.Text`) value written into a field slot
+ * of a format-2 document (D4). Format 2 rejects these instead of normalizing
+ * them, which is what lets the overlay encode field values as plain JSON.
+ */
+declare class Format2CompositeFieldError extends Error {
+    readonly modelName: string;
+    readonly recordId: string;
+    readonly field: string;
+    constructor(modelName: string, recordId: string, field: string);
+}
+/**
+ * D4: reject a Yjs composite in a field slot on a format-2 write path. Plain
+ * values pass untouched, including stringset arrays and `{$add}`/`{$remove}`
+ * delta objects — only Yjs instances are rejected.
+ */
+declare function assertNoFormat2CompositeFields(modelName: string, recordId: string, fields: Record<string, unknown> | undefined | null): void;
+/**
+ * D3, format-scoped: the tombstone-aware stringset discriminator. A format-2
+ * stringset `Y.Map` may carry `false` for a removed member, which the legacy
+ * (#625) discriminator deliberately rejects — widening it globally would
+ * reclassify legacy all-boolean composites and break the "format 1 unchanged"
+ * contract, so legacy paths keep {@link isStringSetYMap} untouched.
+ *
+ * Safe here because D4 guarantees no composite field values exist on format-2
+ * documents.
+ */
+declare function isFormat2StringSetYMap(value: unknown): value is Y.Map<any>;
+/** Members of a tombstone-aware stringset map: the `true` entries only. */
+declare function format2StringSetMembers(value: unknown): string[];
+
+/**
+ * Fold a format-2 epoch overlay into a `records` table (#2816).
+ *
+ * Shared by BOTH ends: the Durable Object's authoritative table and the
+ * client's local merged view fold the overlay with this one implementation, so
+ * "what the server says the record is" and "what the client reads back" cannot
+ * drift.
+ *
+ * On a format-2 document the SQLite `records` table is the document — the
+ * Y.Doc holds only the current epoch's overlay. Every applied update therefore
+ * has to reach `records` in the same transaction boundary as the update-log
+ * row, for a document that may be 2GB. That rules out read-modify-write of the
+ * record: this module expresses each overlay entry as one merge-upsert whose
+ * RFC 7396 semantics SQLite's `json_patch` already implements (an explicit
+ * `null` deletes the key), plus incremental `stringset_index` maintenance for
+ * the member deltas.
+ *
+ * The semantics are pinned against the shared JS materializer
+ * (`materializeOverlayRecord`), which is what the client's merged view folds
+ * with — the two must never drift.
+ */
+
+/**
+ * The slice of Cloudflare's `SqlStorage` this module needs. `exec` returns an
+ * iterable cursor of rows; a plain array satisfies it too, which is what the
+ * hermetic tests bind.
+ */
+interface OverlaySql {
+    exec(query: string, ...bindings: unknown[]): Iterable<Record<string, any>>;
+}
+/**
+ * Which tables the fold writes to.
+ *
+ * The Durable Object hosts exactly one document, so it uses the default names.
+ * A CLIENT database can hold several connected documents at once, and the
+ * merged view of one must never be readable as another's — so the client
+ * passes per-document table names (see `format2TableNames`). The STATEMENTS
+ * stay this module's single implementation either way; only the table names
+ * differ, which is what keeps the two ends from drifting.
+ */
+interface OverlayTables {
+    records: string;
+    stringSetIndex: string;
+}
+/** The Durable Object's tables: one document per DO, so no scoping needed. */
+declare const DEFAULT_OVERLAY_TABLES: OverlayTables;
+/**
+ * Project one record's overlay entry into `records` + `stringset_index`.
+ *
+ * Callers pass the entry for the keys the update TOUCHED, not the record's
+ * whole overlay: materialization is a fold, so `row ⊕ delta` over the stored
+ * row is the same record as replaying the epoch from its base.
+ */
+declare function projectOverlayEntry(sql: OverlaySql, modelName: string, entry: OverlayRecordEntry, tables?: OverlayTables): void;
+
+/**
+ * The client-side record store for format-2 (large) documents (#2816).
+ *
+ * A format-2 client no longer reads records out of Y.Maps: the epoch doc holds
+ * only what the current epoch touched, so the merged `records` view is the
+ * document. The existing `StorageProvider` cannot serve that — it is an async
+ * key-value API with no query and no multi-table transaction.
+ *
+ * This store defines the contract instead:
+ *
+ * - **reads** come from `records` (folded with the same `projectOverlayEntry`
+ *   the Durable Object uses, so the two views cannot drift);
+ * - **writes** commit the merged row and the `_pending_ops` entry in ONE
+ *   transaction — the commit barrier a `save()` resolves behind, which is what
+ *   makes read-your-writes true and makes a crash immediately after the save
+ *   non-lossy;
+ * - **`_pending_ops`** are pruned only at or below the server's `update.ack`
+ *   high-water mark, never on `ws.send`;
+ * - `_epoch` and `_snapshot_load` carry the epoch the client is following and
+ *   the chunks a cold load has already completed.
+ *
+ * It is deliberately synchronous over an injected SQL executor: better-sqlite3
+ * (Node) drives it directly, and the worker-hosted OPFS engine drives it inside
+ * its worker, where a single round-trip commits the whole transaction.
+ *
+ * ## Document scoping
+ *
+ * Unlike the Durable Object — one document per DO — a client database can hold
+ * several connected documents at once, so every table here is scoped to ONE
+ * document: `records`/`stringset_index` get per-document names, and the
+ * bookkeeping tables carry a `doc_id` column in their primary key. Without
+ * that, two open large documents would read each other's records and one
+ * document's `update.ack` would prune the other's unsynced writes.
+ */
+
+/** A SQL executor that can also run a set of statements as one atomic commit. */
+interface Format2StoreSql extends OverlaySql {
+    transaction<T>(fn: () => T): T;
+}
+/**
+ * Per-document names for the merged view's tables.
+ *
+ * The document id is hex-encoded rather than sanitized: a lossy mapping could
+ * land two documents on the same tables, which is exactly the mixing this
+ * scoping exists to prevent.
+ */
+declare function format2TableNames(docId: string): OverlayTables;
+/**
+ * The local schema one format-2 document owns.
+ *
+ * `records`/`stringset_index` keep the DO's column shape and primary keys —
+ * the shared fold in `overlaySql.ts` writes both ends — under per-document
+ * names. The bookkeeping tables are shared across documents and scoped by
+ * `doc_id` instead.
+ */
+declare function format2ClientDDL(docId: string): string[];
+/** One durable record of a local write, replayed if it is never acked. */
+interface PendingOp {
+    seq: number;
+    model: string;
+    recordId: string;
+    op: "create" | "patch" | "delete";
+    /** Field names the op touched — the unit amended-D1 conflict detection works on. */
+    fields: string[];
+    /** Epoch the op was written against, for recency-aware replay. */
+    baseEpoch: number;
+    /** Server-offset-corrected wall clock at write time. */
+    ts: number;
+    /**
+     * The overlay mutation this op wrote, so the write can be reproduced from
+     * the durable log alone — see {@link Format2RecordStore.commitLocalWrite}.
+     * `null` only for a row written by a build that did not record it.
+     */
+    mutation: OverlayMutation | null;
+}
+type PendingOpInput = Omit<PendingOp, "seq" | "mutation"> & {
+    seq?: number;
+};
+/**
+ * A model this device did not hydrate, used as if it had (#2816,
+ * Precondition B's fallback).
+ *
+ * A capped load leaves a model out because the device has no room for it. The
+ * records it does hold of that model afterwards — whatever a later overlay
+ * happens to touch — are not the model, they are a handful of recently
+ * changed rows, and answering a query from them would be wrong in the way
+ * that is hardest to notice. So the store refuses instead: the model is
+ * UNAVAILABLE on this device, which is a thing an app can handle, rather than
+ * nearly empty, which is not.
+ */
+declare class Format2ModelNotHydratedError extends Error {
+    readonly model: string;
+    /** The models this device did load. */
+    readonly hydrated: string[];
+    /** Stable across builds, so an app can branch on it rather than on text. */
+    readonly code = "FORMAT2_MODEL_NOT_HYDRATED";
+    constructor(model: string, 
+    /** The models this device did load. */
+    hydrated: string[]);
+}
+declare class Format2RecordStore {
+    private readonly sql;
+    private readonly docId;
+    /** This document's merged-view tables (never another document's). */
+    private readonly tables;
+    /** Models this device holds, or `null` for the whole document. */
+    private scope;
+    /** Whether {@link scope} has been read from `_epoch` yet. */
+    private scopeLoaded;
+    constructor(sql: Format2StoreSql, docId: string);
+    /** Create the local schema. Safe to call on every open. */
+    init(): void;
+    /**
+     * Record which models this device holds (#2816, Precondition B's fallback).
+     *
+     * `null` — the normal case — is "the whole document". A list is what a
+     * capped cold load leaves behind: the plan
+     * {@link planSnapshotHydration} made, persisted so it outlives the load. It
+     * has to be durable, because a restart reconnects and starts folding the
+     * epoch overlay again, and without the scope that fold would quietly
+     * repopulate a skipped model with the handful of records the epoch touched.
+     */
+    setHydrationScope(models: readonly string[] | null): void;
+    /** The models this device holds, or `null` when it holds the document. */
+    hydrationScope(): string[] | null;
+    /** Whether this device holds `modelName` at all. */
+    isHydrated(modelName: string): boolean;
+    /** Refuse a model this device does not hold, rather than answering partly. */
+    private assertHydrated;
+    read(modelName: string, recordId: string): Record<string, any> | null;
+    readAll(modelName: string): Array<Record<string, any>>;
+    /**
+     * The id of the first record whose fields all match — the merged-view answer
+     * to `upsertOn` resolution and to an optimistic unique-constraint check. A
+     * base-only holder is found here and nowhere in the epoch doc, which is the
+     * whole point.
+     */
+    findIdByFields(modelName: string, fields: string[], values: unknown[]): string | null;
+    findIdByField(modelName: string, field: string, value: unknown): string | null;
+    /**
+     * Every record id a model holds in the merged view, ids only.
+     *
+     * The derived query tables are rebuilt from this on connect, and a rebuild
+     * has no reason to carry each record's whole `_data` through memory on the
+     * way.
+     */
+    recordIds(modelName: string): string[];
+    /**
+     * One PAGE of a model's record ids, in id order, after `after`.
+     *
+     * The whole-model list above is a JavaScript array of every id, which on the
+     * documents this epic exists for is millions of strings held at once —
+     * before a single row has been projected. A keyset page costs the same per
+     * row and bounds what is resident, so walking a model is a walk rather than
+     * an allocation (#2816).
+     */
+    recordIdsAfter(modelName: string, after: string | null, limit: number): string[];
+    /**
+     * Fold an overlay entry that arrived from the server.
+     *
+     * A model outside this device's hydration scope is DROPPED here rather than
+     * folded: the device declined that model because it has no room for it, and
+     * a row of it landing anyway would turn "this model is not held here" into
+     * "this model holds one record" — a merged view that reads like the document
+     * and is not it.
+     */
+    applyRemote(modelName: string, entry: OverlayRecordEntry): void;
+    /**
+     * Run `fn` as ONE commit. A catch-up fold of a whole overlay is a single
+     * transaction rather than one per record — the difference between one commit
+     * and thousands.
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Commit a LOCAL write: the merged row, the pending op, and the OVERLAY
+     * MUTATION that op stands for all land together, or none of them does.
+     * The returned sequence is what an `update.ack` later prunes against.
+     *
+     * The mutation is stored, not just the field names it touched, because the
+     * merged row cannot reproduce it: materializing a row loses the difference
+     * between a patch and a `_replace` create, turns an explicit `null` unset
+     * into an absent key, and drops stringset member tombstones. Those shapes
+     * survive only in the overlay — and the overlay's own persistence is a Yjs
+     * update flushed asynchronously AFTER this commit, so a crash in between
+     * would otherwise leave a pending op whose write nothing could reconstruct:
+     * the client would claim its sequence on the next catch-up frame, be acked
+     * for a write it never sent, and drop it.
+     */
+    commitLocalWrite(modelName: string, mutation: OverlayMutation, pending: PendingOpInput): number;
+    /** The next local sequence: one past the highest ever issued. */
+    nextSeq(): number;
+    /**
+     * The highest sequence this client has ever committed locally — what an
+     * outbound update frame claims, and what an `update.ack` has to reach before
+     * the document has nothing unsynced left.
+     */
+    highestLocalSeq(): number;
+    pendingOps(): PendingOp[];
+    /**
+     * Prune at or below the server's contiguous-sequence high-water mark.
+     * A lower (out-of-order or replayed) ack never lowers the mark and never
+     * resurrects a pruned op.
+     */
+    prunePendingOps(maxContiguousSeq: number): void;
+    ackedSeq(): number;
+    epoch(): number;
+    setEpoch(epoch: number): void;
+    lastSyncAt(): number | null;
+    setLastSyncAt(at: number): void;
+    /**
+     * The offline write window this document is held to (#2816, behavior 18),
+     * as the server last reported it — the deployment default until one has.
+     */
+    offlineWindowDays(): number;
+    /**
+     * Record that this client was in touch with the server, and (when the
+     * server said so) the window it is held to.
+     *
+     * Persisted together because the session that enforces the window is the one
+     * that cannot ask for it: a client that starts offline reads both back out
+     * of its own database.
+     */
+    noteSync(at: number, windowDays?: number | null): void;
+    /**
+     * Record the window without claiming a sync (#2816, behavior 18).
+     *
+     * The handshake carries the window whatever else it says, including to a
+     * client that is behind by whole epochs and cannot act on the rest of the
+     * frame. Taking the number is right there; moving the mark it is measured
+     * FROM is not — a frame is proof of contact, not proof that this client's
+     * merged view is the room's state, and a document past its window would
+     * become writable again on the strength of a handshake whose catch-up then
+     * failed.
+     */
+    noteOfflineWindow(windowDays: number | null | undefined): void;
+    /**
+     * How far this client's clock is behind the server's, in milliseconds
+     * (#2816, behavior 17).
+     *
+     * Zero until one has been measured — which is why {@link clockOffsetKnown}
+     * exists separately: a measured zero and never having measured are the same
+     * number and very different facts, and the replay resolver refuses to call a
+     * write "clearly older" on the second.
+     */
+    clockOffset(): number;
+    /** Whether the offset above was ever measured against a server. */
+    clockOffsetKnown(): boolean;
+    /** Record the offset measured against server time while connected. */
+    noteClockOffset(offsetMs: number): void;
+    /** Now, on the server's clock as far as this client can tell. */
+    correctedNow(now?: number): number;
+    /**
+     * Forget specific pending ops (#2816, behavior 17).
+     *
+     * The one caller is a replay whose recency resolution DROPPED them: the
+     * online write won, so the op must never be replayed — and leaving it in the
+     * log would have the next epoch move carry it anyway, and would report the
+     * document as holding unsynced changes for good. The merged row it wrote
+     * stays: it is what the client is showing, and the next update from the
+     * server corrects it.
+     */
+    forgetPendingOps(seqs: number[]): void;
+    /**
+     * Rewrite pending ops that survived a replay resolution only in PART
+     * (#2816, behavior 17).
+     *
+     * The same caller as {@link forgetPendingOps}, for the ops it narrowed
+     * rather than dropped: a patch that touched two fields, one of which an
+     * online write clearly beat. The row must be rewritten to the surviving
+     * delta — its field list AND the mutation it stands for — because the
+     * mutation is what the restore path puts back on the overlay after a crash,
+     * and putting the whole one back would resurrect exactly the field this
+     * resolution decided against.
+     */
+    narrowPendingOps(ops: Array<Pick<PendingOp, "seq" | "fields" | "mutation">>): void;
+    completedChunks(buildId: string): string[];
+    markChunkComplete(buildId: string, chunkKey: string): void;
+    /**
+     * Throw away a merged view that cannot be repaired (#2816, behavior 12).
+     *
+     * The one caller is a client whose sealed-overlay chain was refused: the
+     * rows it holds are the state of an epoch the room has left behind, and no
+     * available artifact turns them into the current state. It reloads from a
+     * base snapshot instead — and a snapshot is a set of rows, not a diff, so
+     * loading it over these would leave behind every record deleted since. The
+     * chunk marks go with them: a mark whose rows are gone is exactly what makes
+     * a resumed load skip a chunk and finish incomplete.
+     *
+     * What survives is what this client owes the server. Unacknowledged writes
+     * are replayed onto the epoch it lands on, and the acked high-water mark
+     * keeps their sequences from colliding with fresh ones — dropping either
+     * would lose writes the app has already been told were saved.
+     */
+    discardMergedView(): void;
+    private rows;
+    private scalar;
+}
+
 interface ITransactionalDatabaseOperations {
     insert(modelName: string, data: any): Promise<void>;
     delete(modelName: string, id: string): Promise<void>;
@@ -272,6 +833,32 @@ declare abstract class DatabaseEngine {
      */
     deleteByDocumentId(_modelName: string, _docId: string): Promise<void>;
     getTableName(_modelName: string): string;
+    /**
+     * A SYNCHRONOUS SQL executor over this engine's database, used by the
+     * large-document (format 2) record store. That store commits a merged
+     * record row and its pending-operation entry as one transaction — the
+     * barrier a `save()` resolves behind — which the async `query()` API cannot
+     * express. Engines whose underlying SQLite is synchronous (better-sqlite3,
+     * SQL.js) provide it; anything else leaves it undefined and cannot host a
+     * large document.
+     */
+    createFormat2Sql?: () => Format2StoreSql;
+    /**
+     * Whether what {@link createFormat2Sql} writes survives this process.
+     *
+     * On a large document the merged record view IS the document: the Y.Doc
+     * holds one epoch's overlay, and everything else — including a record a
+     * `save()` has already resolved, and the pending write that still owes it to
+     * the server — lives only in this store. An engine whose database is in
+     * memory therefore cannot host one: a reload does not cost a cache, it costs
+     * the document and the writes nobody has acknowledged yet.
+     *
+     * The platform is asked separately about its storage quota; this answers the
+     * half only the engine knows. An engine that does not implement it is taken
+     * at the platform's word, which is what keeps hosts with storage of their
+     * own — a worker handed a file store, a test — working unchanged.
+     */
+    format2StorageIsDurable?: () => boolean;
     withTransaction<T>(_callback: (operations: ITransactionalDatabaseOperations) => Promise<T>): Promise<T>;
 }
 
@@ -432,6 +1019,129 @@ declare class DocumentQueryTranslator {
     private buildDocumentClause;
 }
 
+/**
+ * The binding state one ORM instance owns (#3039).
+ *
+ * Everything here used to live as `BaseModel` statics, so two `initJsBao`
+ * instances in one process shared one engine, one set of connected documents,
+ * one set of `subscribe()` listeners and one default-document mapping. The
+ * static surface survives as accessors that resolve the acting class's
+ * context; the state itself lives here, one per instance.
+ *
+ * Deliberately imports NOTHING at runtime: `BaseModel` reaches for this module
+ * during its own evaluation, so a value import of `ModelRegistry` (which
+ * imports `BaseModel`) would be a cycle that bites at module-init time.
+ */
+declare class OrmContext {
+    /** Declared before the field that reads it: static initialization is ordered. */
+    private static instanceCounter;
+    /**
+     * Which instance this is, for diagnostics. A process holding several clients
+     * needs a way to say WHICH one a warning is about, so every context takes the
+     * next number as it is created and keeps it for its lifetime.
+     */
+    readonly instanceId: number;
+    /** The engine this instance's models read and write through. */
+    dbEngine: DatabaseEngine | null;
+    connectedDocuments: Map<string, {
+        yDoc: Y.Doc;
+        permissionHint: DocumentPermissionHint;
+    }>;
+    /** `docId_modelName` → the Y.Map that document holds for that model. */
+    documentYMaps: Map<string, Y.Map<any>>;
+    /** `subscribe()` callbacks, by model name. */
+    listenersMap: Map<string, Set<() => void>>;
+    modelNameToDefaultDocId: Map<string, string>;
+    globalDefaultDocId: string | undefined;
+    defaultDocChangedListeners: Set<(payload: {
+        previous?: string;
+        current?: string;
+    }) => void>;
+    modelDocMappingChangedListeners: Set<(payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void>;
+    /** Format-2 ("large document", #2816) record stores by document id. */
+    format2Documents: Map<string, Format2RecordStore>;
+    /** Format-2 epoch moves in flight (#2816). */
+    format2Transitions: Map<string, Promise<void>>;
+    /**
+     * Nested-Y.Map stringset fields this context has already observed. Per
+     * context, not global: a Y.Doc reconnected to a fresh instance has to be
+     * observed again by that instance, and a global guard would silently
+     * suppress it.
+     */
+    observedStringSetMaps: WeakSet<Y.Map<any>>;
+    /**
+     * The registry this instance's schema lookups use. `null` on the standing
+     * default context, where callers fall back to the global singleton.
+     */
+    modelRegistry: ModelRegistry | null;
+    /** Model classes routed to this context. */
+    boundModels: Set<any>;
+    /** True once {@link destroy} has run; bound classes keep pointing here. */
+    destroyed: boolean;
+    /** Yjs `unobserve` thunks by owning document id. */
+    private observerDisposers;
+    /** Teardown the owner (the document manager) registers for `destroy()`. */
+    private teardownHooks;
+    private static readonly NO_DOCUMENT_KEY;
+    /**
+     * Record how to remove an observer this context installed. Every `observe()`
+     * in the ORM pairs with one of these: without it a torn-down instance's
+     * callbacks keep firing on a Y.Doc that outlives it.
+     */
+    registerObserverDisposer(docId: string | null | undefined, dispose: () => void): void;
+    /** Remove every observer this context installed for `docId`. */
+    disposeObserversForDocument(docId: string): void;
+    private disposeAllObservers;
+    /** Run `hook` as part of `destroy()` (the format-2 binding registers here). */
+    onDestroy(hook: () => void | Promise<void>): void;
+    /** The record store for `docId`, or `null` when the document is format 1. */
+    getFormat2Store(docId: string | null | undefined): Format2RecordStore | null;
+    /**
+     * The epoch move a write to `docId` has to wait out (#2816, behavior 10), or
+     * `null` when none is in flight.
+     */
+    format2WritesHeld(docId: string | null | undefined): Promise<void> | null;
+    /** Run an epoch move with `docId`'s local writes held back (#2816). */
+    holdFormat2Writes<T>(docId: string, run: () => Promise<T>): Promise<T>;
+    /** Notify `subscribe()` callbacks registered on this context for `modelName`. */
+    notifyListeners(modelName: string, log?: (message: string) => void, onError?: (error: unknown) => void): void;
+    setModelDefaultDocumentId(modelName: string, docId: string): void;
+    removeModelDefaultDocumentId(modelName: string): void;
+    clearModelDefaultDocumentIds(): void;
+    setGlobalDefaultDocumentId(docId: string): void;
+    clearGlobalDefaultDocumentId(): void;
+    getModelDefaultDocumentMapping(): Record<string, string>;
+    getDocumentIdForModel(modelName: string): string | undefined;
+    getGlobalDefaultDocumentId(): string | undefined;
+    onDefaultDocChanged(listener: (payload: {
+        previous?: string;
+        current?: string;
+    }) => void): () => void;
+    onModelDocMappingChanged(listener: (payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void): () => void;
+    /** Drop the model→document defaults that point at a disconnected document. */
+    clearMappingsForDocId(docId: string): void;
+    private announceDefaultDoc;
+    private announceModelDocMapping;
+    /**
+     * Tear this instance down: observers off, engine destroyed, state cleared.
+     *
+     * Deliberately does NOT unbind its model classes. They keep resolving this
+     * context, whose engine is now null, so an operation through them throws the
+     * ordinary not-initialized error instead of silently landing on whatever
+     * other instance happens to be live (#3039, behavior 7). Only a later
+     * `initJsBao` may rebind a class whose context is destroyed.
+     */
+    destroy(): Promise<void>;
+}
+
 interface StringSetMembership {
     field: string;
     contains: string;
@@ -500,19 +1210,59 @@ declare class RecordNotFoundError extends Error {
 declare function generateULID(): string;
 declare class BaseModel implements StringSetChangeTracker {
     static modelName?: string;
-    private static listenersMap;
-    private static modelNameToDefaultDocId;
-    private static globalDefaultDocId;
-    private static defaultDocChangedListeners;
-    private static modelDocMappingChangedListeners;
+    /**
+     * The ORM instance this class is bound to (#3039), set by `initJsBao`.
+     *
+     * Read through the static prototype chain by {@link resolveOrmContext}, so a
+     * subclass inherits its parent's binding. Never reassigned by `destroy()`:
+     * a destroyed instance's classes keep pointing at their tombstone rather
+     * than falling back to a surviving instance.
+     */
+    static _ormContext?: OrmContext;
+    /**
+     * Every field below is per-ORM-instance state (#3039). The accessors keep
+     * the static surface consumers (and this file's own call sites) already use
+     * while the state itself lives on the acting class's {@link OrmContext}.
+     */
+    protected static get listenersMap(): Map<string, Set<() => void>>;
+    protected static set listenersMap(value: Map<string, Set<() => void>>);
+    protected static get modelNameToDefaultDocId(): Map<string, string>;
+    protected static set modelNameToDefaultDocId(value: Map<string, string>);
+    protected static get globalDefaultDocId(): string | undefined;
+    protected static set globalDefaultDocId(value: string | undefined);
+    protected static get defaultDocChangedListeners(): Set<(payload: {
+        previous?: string;
+        current?: string;
+    }) => void>;
+    protected static get modelDocMappingChangedListeners(): Set<(payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void>;
     private static readonly DEFAULT_LEGACY_DOC_ID;
-    protected static dbInstance: DatabaseEngine | null;
-    protected static connectedDocuments: Map<string, {
+    protected static get dbInstance(): DatabaseEngine | null;
+    protected static set dbInstance(value: DatabaseEngine | null);
+    protected static get connectedDocuments(): Map<string, {
         yDoc: Y.Doc;
         permissionHint: DocumentPermissionHint;
     }>;
-    protected static documentYMaps: Map<string, Y.Map<any>>;
-    private static _observedStringSetMaps;
+    protected static set connectedDocuments(value: Map<string, {
+        yDoc: Y.Doc;
+        permissionHint: DocumentPermissionHint;
+    }>);
+    protected static get documentYMaps(): Map<string, Y.Map<any>>;
+    protected static set documentYMaps(value: Map<string, Y.Map<any>>);
+    /**
+     * Format-2 ("large document", #2816) documents by id, each with the record
+     * store that holds its merged view. Presence in this map IS format-2-ness on
+     * the client: a document without an entry takes the legacy path unchanged.
+     */
+    private static get format2Documents();
+    /**
+     * Large documents whose epoch overlay is being replaced right now (#2816,
+     * behavior 10), each with the promise that settles when the move is done.
+     */
+    protected static get format2Transitions(): Map<string, Promise<void>>;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -529,6 +1279,53 @@ declare class BaseModel implements StringSetChangeTracker {
     type: string;
     static setLogLevel(level: LogLevel): void;
     static getLogLevel(): LogLevel;
+    /**
+     * Mark a connected document as format 2 and bind the record store that holds
+     * its merged view. Called by `connectDocument(..., { documentFormat: 2 })`.
+     */
+    static registerFormat2Document(docId: string, store: Format2RecordStore): void;
+    static unregisterFormat2Document(docId: string): void;
+    /**
+     * Drop every format-2 binding. Called when the whole runtime is reset: the
+     * stores run over the engine's SQL executor, so one left behind would answer
+     * reads out of a destroyed database.
+     */
+    static clearFormat2Documents(): void;
+    /** The record store for `docId`, or `null` when the document is format 1. */
+    static getFormat2Store(docId: string | null | undefined): Format2RecordStore | null;
+    static isFormat2Document(docId: string | null | undefined): boolean;
+    /**
+     * Run an epoch move with `docId`'s local writes held back (#2816,
+     * behavior 10).
+     *
+     * A move replaces the document's overlay: the sealed Y.Doc is destroyed once
+     * the fresh one is bound. A write that resolved its target document before
+     * the move and lands its overlay entry after would land it in the doomed
+     * doc — and it could never be recovered, because `_pending_ops` records
+     * which fields a write touched, not the values it wrote. A write that starts
+     * during the move therefore waits here and resolves the document again on
+     * the other side. (Concurrent moves are serialized for the same reason.)
+     */
+    static holdFormat2Writes<T>(docId: string, run: () => Promise<T>): Promise<T>;
+    /**
+     * The move a write to `docId` has to wait out, or `null` when none is in
+     * flight — which is every write on every document but the one being rotated.
+     */
+    static format2WritesHeld(docId: string | null | undefined): Promise<void> | null;
+    /**
+     * The record store, Y.Doc and model map a format-2 write should land on,
+     * having waited out any epoch move in flight (#2816, behavior 10).
+     *
+     * Resolves to the callers' own values in the overwhelmingly common case that
+     * no move is running, so an ordinary write pays one map lookup. When a move
+     * IS running, the write waits for it and the freshly bound overlay — and its
+     * rebuilt store — are what it lands on.
+     */
+    static resolveFormat2Target(docId: string, modelName: string, store: Format2RecordStore, yDoc: Y.Doc, modelYMap: Y.Map<any>): Promise<{
+        store: Format2RecordStore;
+        yDoc: Y.Doc;
+        modelYMap: Y.Map<any>;
+    }>;
     static setModelDefaultDocumentId(modelName: string, docId: string): void;
     static removeModelDefaultDocumentId(modelName: string): void;
     static clearModelDefaultDocumentIds(): void;
@@ -578,10 +1375,24 @@ declare class BaseModel implements StringSetChangeTracker {
     hasFieldChanged(fieldKey: string): boolean;
     markStringSetChange(fieldName: string, operation: "add" | "remove" | "clear", value?: string): void;
     private getStringSetCurrentValues;
+    /** The schema default for a field, or `undefined` when it has none. */
+    private schemaDefaultFor;
     private getStringSetFromYjs;
     private getOrCreateStringSet;
     static initialize(_yDoc: Y.Doc, _db: DatabaseEngine): Promise<void>;
-    static initializeForDocument(yDoc: Y.Doc, db: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint): Promise<void>;
+    /**
+     * Initialize this model for a connected document.
+     *
+     * `documentFormat` (#2816) decides where the records come from. On a legacy
+     * document the Y.Map IS the records, so this loads them into the query
+     * tables and observes the map. On a format-2 document the Y.Map is an epoch
+     * OVERLAY of flat `recordId/field` entries — walking it as records would
+     * read a scalar (or a `null` unset) as a record and mint junk rows, and
+     * observing it would run every overlay change through the legacy
+     * record-shaped path. There the tables are prepared here and hydrated and
+     * observed by `Format2DocumentBinding` from the merged view instead.
+     */
+    static initializeForDocument(yDoc: Y.Doc, db: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint, documentFormat?: 1 | 2): Promise<void>;
     static cleanupDocumentData(docId: string): Promise<void>;
     static subscribe(callback: () => void): () => void;
     protected static notifyListeners(): void;
@@ -616,9 +1427,88 @@ declare class BaseModel implements StringSetChangeTracker {
     protected static _buildKeyFromValues(fields: string[], keyValues: any[], modelName: string, constraintName: string): string | null;
     protected _buildUniqueKey(fields: string[], data: Record<string, any>, modelName: string, constraintName: string): string | null;
     save(options?: SaveOptions): Promise<void>;
+    /**
+     * Save onto a format-2 (large) document (#2816).
+     *
+     * The record is NOT written as a nested `Y.Map`: the epoch doc carries flat
+     * field-level overlay entries, and the merged `records` view is what reads
+     * come from. Existence, `upsertOn` and uniqueness are therefore resolved
+     * against that view, not against the doc, which is what makes a base-only
+     * record patchable instead of silently re-created.
+     *
+     * The merged row and the `_pending_ops` entry commit TOGETHER and BEFORE the
+     * overlay lands in the Y.Doc: that ordering is the commit barrier a resolved
+     * `save()` stands behind, and it keeps a crash in between recoverable (the
+     * durable pending op replays the write) rather than divergent.
+     */
+    private saveFormat2;
+    /**
+     * Mirror one merged-view row into the engine's per-model query tables, so
+     * `query()` / `aggregate()` answer from the same state `find()` does. The
+     * merged view remains the source; this is its derived query projection, and
+     * it is awaited so a resolved save is immediately queryable.
+     */
+    /**
+     * Project one merged-view row into the engine's per-model query tables, so
+     * `query()` / `aggregate()` answer from the same state `find()` does. The
+     * merged view stays the source; this is its derived query projection.
+     *
+     * Called (awaited) by the local write path — which is what makes a resolved
+     * save immediately queryable — and enqueued by the overlay observer for
+     * updates that arrive from the sync layer.
+     */
+    static projectFormat2Record(docId: string, recordId: string, 
+    /**
+     * `notify: false` withholds the listener notification, for a caller
+     * projecting many records at once (#2816): hydrating a model would
+     * otherwise tell every subscriber once per record, which on a large
+     * document is a re-render per row of the document.
+     */
+    options?: {
+        notify?: boolean;
+    }): Promise<void>;
+    /**
+     * Remove a PAGE of records from the query tables, without consulting the
+     * merged view (#2816).
+     *
+     * The discard path: the rows are erased BEFORE the merged view is thrown
+     * away, because the view is the only place that still names them. Projecting
+     * would re-insert them — the record is still there at that point.
+     */
+    static deleteFormat2QueryRows(recordIds: readonly string[]): Promise<void>;
+    /**
+     * Project a PAGE of merged-view rows into the query tables (#2816).
+     *
+     * The hydration path: one notification for the page rather than one per
+     * record, because a model being hydrated has no intermediate states worth
+     * telling anyone about — and on a large document the per-record version is a
+     * subscriber callback per row of the document.
+     */
+    static projectFormat2Records(docId: string, recordIds: readonly string[]): Promise<void>;
     delete(): Promise<void>;
+    /**
+     * Delete from a format-2 (large) document (#2816): a `_deleted` tombstone in
+     * the overlay plus the merged-view removal, committed with its pending op
+     * before the overlay lands, exactly as `saveFormat2` orders its write.
+     */
+    private deleteFormat2;
     protected getCurrentJSState(): Record<string, any>;
     protected toJSON(): Record<string, any>;
+    /**
+     * Refuse a read through a class whose ORM instance has been destroyed
+     * (#3039, the tombstone).
+     *
+     * `query()`, `count()` and `aggregate()` already refuse: they read the
+     * engine, which a destroyed instance has nulled. The readers that walk the
+     * connected documents instead — `find`, `findAll`, `findByUnique` — would
+     * walk maps `destroy()` emptied and report absence, which a caller cannot
+     * tell apart from a database that genuinely holds no such record. So they
+     * say so instead.
+     *
+     * Only a DESTROYED context is refused. A class that was never bound still
+     * reads as empty before any `initJsBao`, exactly as it always has.
+     */
+    private static assertInstanceAlive;
     static find<T extends BaseModel>(this: new (...args: any[]) => T, id: string): Promise<T | null>;
     /**
      * Document-style query API - returns paginated results
@@ -698,6 +1588,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -716,14 +1627,14 @@ declare class BaseModel implements StringSetChangeTracker {
      * member arrives via Y.applyUpdate, or a local per-member set/delete).
      * Idempotent — re-calling on the same Y.Map is a no-op.
      */
-    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>, docId?: string | null): void;
     /**
      * Walk the schema's stringset fields on `recordYMap` and observe any nested
      * Y.Map values. Called from observer setup and from the parent observer body
      * so newly-arrived stringset Y.Maps (local migration or remote create) get
      * an observer too.
      */
-    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any, docId?: string | null): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */
@@ -745,8 +1656,23 @@ declare class ModelRegistry {
     private modelOptions;
     private activeSessionModels;
     private dbEngine;
-    private constructor();
+    constructor();
     static getInstance(): ModelRegistry;
+    /**
+     * A registry for ONE `initJsBao` instance (#3039).
+     *
+     * The global singleton stays the registration target for
+     * `attachAndRegisterModel` / `createModelClass`; this is the per-instance
+     * view the ORM actually resolves schemas through, so two clients that
+     * register different models under the same name no longer overwrite each
+     * other's include translation and relationship validation.
+     *
+     * With explicit `models`, only those classes are in it. With `models`
+     * 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.
+     */
+    static createInstanceRegistry(modelClasses?: (typeof BaseModel)[]): ModelRegistry;
     registerModel(modelClass: any, options: ModelOptions, fields: Map<string, FieldOptions>): void;
     getModelClass(name: string): typeof BaseModel | undefined;
     getModelOptions(name: string): ModelOptions | undefined;
@@ -755,7 +1681,9 @@ declare class ModelRegistry {
     private getModelNameFromClass;
     setExplicitModelsForSession(modelClasses?: (typeof BaseModel)[]): void;
     initializeAll(yDoc: Y.Doc, dbEngine: DatabaseEngine): Promise<void>;
-    initializeAllForDocument(yDoc: Y.Doc, dbEngine: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint): Promise<void>;
+    initializeAllForDocument(yDoc: Y.Doc, dbEngine: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint, 
+    /** #2816 — `2` prepares the tables without reading the Y.Map as records. */
+    documentFormat?: 1 | 2): Promise<void>;
     removeDocumentData(docId: string, dbEngine: DatabaseEngine): Promise<void>;
     initializeRelationships(): Promise<void>;
     private addPrototypeMethod;
@@ -764,48 +1692,579 @@ declare class ModelRegistry {
     private validateSessionModels;
 }
 
-interface InitJsBaoOptions {
-    databaseConfig: DatabaseConfig;
-    /**
-     * Optional array of model classes to initialize.
-     * If not provided, the ORM will rely on models being registered
-     * via attachAndRegisterModel (assuming they have been imported by the application).
-     */
-    models?: (typeof BaseModel)[];
+/**
+ * The on-the-wire shape of a snapshot chunk (#2816, Phase 4).
+ *
+ * Shared by BOTH ends, like the overlay fold: the Durable Object writes these
+ * bytes and the client materializes them, so one implementation encodes,
+ * verifies and decodes them. A snapshot that meant something slightly
+ * different on the two ends would put records into a client's authoritative
+ * table that the server never wrote — silently, because on a format-2 document
+ * there is no whole-document comparison left to catch it.
+ *
+ * ## Why chunks, and why they are verified
+ *
+ * A 2GB document cannot be one object: the load has to survive a dropped
+ * connection, report progress, and let a model answer queries before the rest
+ * has arrived. So a snapshot is a set of per-model gzip ndjson chunks plus a
+ * manifest naming each one's row count and digest, and a chunk is checked
+ * against its entry BEFORE it is decoded — a mismatch is a typed refusal the
+ * loader retries on, cheaper than inflating bytes that are already wrong.
+ *
+ * ## The line format
+ *
+ * One `⟨id⟩\t⟨_data JSON verbatim⟩` line per record. Verbatim matters: the
+ * data comes out of SQLite's `json_patch` and goes straight back into the
+ * other end's `records` table, so re-serializing it here would be a chance to
+ * round a number the server stored exactly. Compact JSON has no raw newline or
+ * tab in it, and a row that somehow held one is refused rather than written —
+ * it would come back as two records, or as one with its tail lost.
+ */
+/** One row of the authoritative `records` table. */
+interface SnapshotRow {
+    _type: string;
+    _id: string;
+    _data: string;
 }
-interface InitJsBaoResult {
-    dbEngine: DatabaseEngine;
-    modelRegistry: ModelRegistry;
-    connectDocument: (docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint) => Promise<void>;
-    disconnectDocument: (docId: string) => Promise<void>;
-    getConnectedDocuments: () => Map<string, ConnectedDocument>;
-    isDocumentConnected: (docId: string) => boolean;
-    onDocumentConnectionChange: (callback: DocumentConnectionCallback) => () => void;
-    addDocumentModelMapping: (modelName: string, docId: string) => void;
-    removeDocumentModelMapping: (modelName: string) => void;
-    clearDocumentModelMappings: () => void;
-    setDefaultDocumentId: (docId: string) => void;
-    clearDefaultDocumentId: () => void;
-    getDocumentModelMapping: () => Record<string, string>;
-    getDocumentIdForModel: (modelName: string) => string | undefined;
-    getDefaultDocumentId: () => string | undefined;
-    onDefaultDocChanged: (listener: (payload: {
-        previous?: string;
-        current?: string;
-    }) => void) => () => void;
-    onModelDocMappingChanged: (listener: (payload: {
-        modelName: string;
-        previous?: string;
-        current?: string;
-    }) => void) => () => void;
+/** What the manifest says about one chunk: enough to verify it standalone. */
+interface SnapshotChunkEntry {
+    /** R2 key, inside the document's own `{appId}/{docId}/` prefix. */
+    key: string;
+    /** The model whose records this chunk holds. */
+    model: string;
+    /** Stored (compressed) length, so a Range loader knows what it is owed. */
+    bytes: number;
+    /**
+     * Uncompressed ndjson length.
+     *
+     * What the rows actually cost once they are somewhere other than a gzip
+     * stream — which is the number a device deciding whether it can hold this
+     * document needs. Compressed length is not a proxy for it: highly
+     * compressible JSON is exactly the shape these chunks hold. Optional
+     * because a manifest written before it was recorded carries none.
+     */
+    rawBytes?: number;
+    rows: number;
+    firstId: string;
+    lastId: string;
+    /** Hex SHA-256 of the STORED bytes — checkable before decompressing. */
+    sha256: string;
 }
 /**
- * Initializes the js-bao system with multi-document support.
- * Sets up the database engine and prepares for document connections.
+ * What one build wrote: the chunks, and everything a loader needs before the
+ * first of them lands.
+ *
+ * `epoch` is the epoch this snapshot is a BASE for — the state as of that
+ * epoch's start, give or take the torn read the overlays after it repair. The
+ * schema (D5) travels with it so a client can create a model's tables without
+ * a document to discover them from.
+ */
+interface SnapshotManifest {
+    version: 2;
+    epoch: number;
+    buildId: string;
+    createdAt: number;
+    schema: Record<string, unknown>;
+    chunks: SnapshotChunkEntry[];
+    totals: {
+        rows: number;
+        bytes: number;
+    };
+}
+/**
+ * Read a chunk back, verified against its manifest entry when one is offered.
+ *
+ * The builder round-trips its own bytes and has nothing to verify against; the
+ * loader always passes the entry, which is what makes a truncated or swapped
+ * chunk a typed refusal rather than records the server never wrote.
+ */
+declare function readSnapshotChunk(body: Uint8Array, descriptor: SnapshotChunkEntry | {
+    model: string;
+}): Promise<SnapshotRow[]>;
+
+/**
+ * The cold load of a large document (#2816, behavior 15).
+ *
+ * A new or evicted client does not replay a document's history — on a format-2
+ * document there is none to replay — it streams the chunks of the latest base
+ * snapshot into its own `records` table and then applies the overlays sealed
+ * after it. This module is the first half: manifest in, merged view out.
+ *
+ * What makes it usable on a real device rather than only in principle:
+ *
+ * - **Resumable.** Each chunk's rows and its `_snapshot_load` mark are written
+ *   in ONE commit, so an interrupted load has no half-applied chunk and a
+ *   resume downloads only what is missing. On a multi-hundred-MB document that
+ *   is the difference between a load that eventually finishes and one that
+ *   starts over every time the connection drops.
+ * - **Verified.** A chunk goes straight into the authoritative table, so a
+ *   truncated or swapped one would write records the server never had, with no
+ *   whole-document comparison left to notice. The digest is checked before
+ *   anything is applied and a bad chunk is re-fetched; a chunk that stays bad
+ *   ends the load rather than completing a wrong one.
+ * - **Progressive.** A model is answerable as soon as ITS chunks are in, and
+ *   progress is reported per chunk — a load that reports only at the end is
+ *   indistinguishable from a hang.
+ * - **Bounded by the device.** A load may be capped to the models a platform
+ *   that cannot hold the whole document has room for (Precondition B's
+ *   fallback, see `format2StorageCapability`); a capped-out model's chunks are
+ *   never fetched, so the cap is bandwidth saved as well as space.
+ *
+ * Materialization goes through `applyRemote`, the same fold an overlay entry
+ * takes, so a snapshot cannot come to mean something an overlay does not.
+ */
+
+/** A chunk that did not become the bytes the manifest describes, twice. */
+declare class SnapshotLoadIntegrityError extends Error {
+    readonly chunk: SnapshotChunkEntry;
+    readonly cause: unknown;
+    constructor(chunk: SnapshotChunkEntry, cause: unknown);
+}
+/** How far a load has got. */
+interface SnapshotLoadProgress {
+    /** Rows materialized so far, including a resumed run's earlier ones. */
+    rows: number;
+    totalRows: number;
+    chunks: number;
+    totalChunks: number;
+    /** The model the chunk just applied belongs to. */
+    model: string;
+}
+/** What a finished load did. */
+interface SnapshotLoadResult {
+    rows: number;
+    chunks: number;
+    /** Chunks a previous attempt had already committed. */
+    resumed: number;
+    /** Chunks that had to be fetched twice because the first copy was wrong. */
+    refetched: number;
+    models: string[];
+    /**
+     * Models the snapshot carries that this load left behind, because the
+     * device could not hold them (#2816, Precondition B's fallback).
+     */
+    skipped: string[];
+}
+/**
+ * Where one chunk is read from, WITHIN the grant for its build.
+ *
+ * `{model}/{index}` — not a key and not a path: the client never learns an R2
+ * key, and the download route derives the object from the grant plus exactly
+ * these two values.
+ */
+declare function snapshotChunkPath(chunk: SnapshotChunkEntry): string;
+/**
+ * Load a snapshot's chunks into the client's merged view.
+ *
+ * Chunks are applied in manifest order, which is `(model, id)` order — so a
+ * model's chunks are contiguous and it can be reported ready as soon as its
+ * last one lands.
+ */
+declare function loadFormat2Snapshot(options: {
+    store: Format2RecordStore;
+    manifest: SnapshotManifest;
+    /** Read one chunk's bytes; the caller owns the transport and the grant. */
+    fetchChunk(chunk: SnapshotChunkEntry): Promise<Uint8Array>;
+    onProgress?(progress: SnapshotLoadProgress): void;
+    /**
+     * A model whose last chunk has landed. Awaited: "ready" has to mean
+     * QUERYABLE, and the caller may have derived tables to hydrate before it
+     * can honestly say so.
+     */
+    onModelReady?(model: string): void | Promise<void>;
+    /** Re-fetches allowed for a chunk that arrives corrupt. Default 1. */
+    retries?: number;
+    /**
+     * The models to hydrate, from {@link planSnapshotHydration} — omitted to
+     * take the whole snapshot.
+     *
+     * A model outside the cap is not fetched at all, so a device that cannot
+     * hold the document does not spend its bandwidth on the part it will drop.
+     */
+    models?: readonly string[];
+}): Promise<SnapshotLoadResult>;
+
+/**
+ * What the transport needs to know about a format-2 document's local writes
+ * (#2816, behavior 9).
+ *
+ * The client transport (`JsBaoClient`) owns the socket but not the record
+ * store, and the ORM owns the store but not the socket. These two functions
+ * are the whole boundary between them: the transport stamps an outbound update
+ * frame with the sequences below, and hands back the server's
+ * `update.ack {maxContiguousSeq}` — the only thing that may prune a durable
+ * `_pending_ops` row.
+ *
+ * A document that is not format 2 has no marks, and both functions say so
+ * rather than inventing zeroes, so the legacy path stays exactly as it was.
+ */
+
+interface Format2SyncMarks {
+    /** Highest sequence this client has committed locally. */
+    highestLocalSeq: number;
+    /** Highest sequence the server has confirmed durable. */
+    ackedSeq: number;
+    /** The epoch this document's overlay belongs to; `0` before it learns one. */
+    epoch: number;
+    /**
+     * Whether this client ever measured its clock against the server's (#2816,
+     * behavior 17). Without it, a replay refuses to call an offline write
+     * "clearly older" than an online one.
+     */
+    clockOffsetKnown: boolean;
+}
+
+/**
+ * Whether this platform can hold this document (#2816, Precondition B's
+ * fallback).
+ *
+ * A cold load streams a base snapshot straight into the local record store,
+ * chunk by chunk, and on the documents this epic exists for that is minutes of
+ * writing. Precondition B is the case where the store underneath cannot take
+ * it: a browser engine with no persistent VFS at all, or one whose origin
+ * quota is well under the document — Safari/iPadOS OPFS, whose measurement is
+ * what gates enabling the OPFS engine there.
+ *
+ * The design ships this check regardless of how that measurement lands,
+ * because the failure it prevents is the quiet one. Without it a load starts,
+ * writes for ten minutes, and throws on the chunk that crosses the quota,
+ * leaving a `records` table holding some of the document — which the client
+ * will nonetheless answer queries from, since the merged view IS the document
+ * on format 2. A partial merged view is not a slower document, it is a wrong
+ * one.
+ *
+ * So the decision is taken before the first chunk is fetched, from what the
+ * platform reports:
+ *
+ * - **no persistent store** → typed refusal. A view that evaporates when the
+ *   tab closes cannot be the authoritative copy of anything.
+ * - **quota the whole snapshot does not fit in** → hydrate the models the app
+ *   configured as the ones worth keeping, and say which were dropped. A device
+ *   that can hold the hot models is more useful than one that holds nothing.
+ * - **quota not even those fit in** → typed refusal, never a partial load
+ *   reported as a whole one.
+ * - **no quota reported** → hydrate everything. Refusing on ignorance would
+ *   take format 2 away from every engine without a quota API, and the platforms
+ *   that do not answer are the ones with room.
+ *
+ * The plan it returns is what {@link loadFormat2Snapshot} is given: the cap is
+ * enforced by not fetching the skipped models' chunks at all, so it is bytes
+ * not transferred, not just bytes not stored.
+ */
+
+/**
+ * How much local space a chunk's UNCOMPRESSED ndjson takes once materialized.
+ *
+ * The rows land as SQLite rows plus their indexes, so the number is above one.
+ * Two is deliberately pessimistic: the cost of over-estimating is hydrating
+ * fewer models than a device could have held, and the cost of
+ * under-estimating is the mid-load failure this module exists to prevent.
+ */
+declare const SNAPSHOT_STORAGE_EXPANSION = 2;
+/**
+ * What a chunk's STORED bytes are assumed to inflate to when its manifest does
+ * not say.
+ *
+ * Only a manifest written before the uncompressed length was recorded needs
+ * this. It is high because the guess must not be optimistic: gzipped ndjson of
+ * repetitive JSON records routinely compresses by an order of magnitude, and
+ * treating the compressed size as a proxy for the materialized one is exactly
+ * how a device approves a document it cannot hold.
+ */
+declare const SNAPSHOT_COMPRESSED_EXPANSION = 8;
+/**
+ * What one chunk is expected to cost in the local store once materialized.
+ *
+ * From the uncompressed length the manifest carries, because the compressed
+ * length says more about how repetitive the data is than about how much room
+ * it needs.
+ */
+declare function estimateMaterializedBytes(chunk: SnapshotChunkEntry): number;
+/** What the platform says about the store a merged view would live in. */
+interface StorageCapability {
+    /** Whether what is written survives the tab or app going away. */
+    persistent: boolean;
+    /** Bytes this origin may keep, or `null` when the platform will not say. */
+    quotaBytes: number | null;
+    /** Bytes the origin already holds — other documents included. Default 0. */
+    usedBytes?: number;
+    /**
+     * Whether a PLATFORM storage API answered, as opposed to there having been
+     * none to ask.
+     *
+     * The difference matters when the engine underneath is in memory. A browser
+     * that reports an origin-private file system is describing the platform, not
+     * this session's database, so "persistent" from it plus a volatile engine is
+     * a claim that is simply wrong — and the load is refused. A host with no
+     * storage API at all (Node, a worker with its own store) was never claiming
+     * anything: it chose the database it passed, so an in-memory one is its
+     * decision to make, and it is warned rather than refused.
+     */
+    probed?: boolean;
+}
+/** A device that cannot hold the document, said so before the load begins. */
+declare class Format2StorageCapabilityError extends Error {
+    /** `not-persistent`: nothing survives. `over-quota`: not enough room. */
+    readonly reason: "not-persistent" | "over-quota";
+    /**
+     * Materialized bytes the refused hydration would have needed, or `0` when
+     * nothing has been measured — the bind refuses before there is a manifest
+     * to measure, and on a document that may have no snapshot at all.
+     */
+    readonly requiredBytes: number;
+    /** Bytes the platform offered, or `null` when it reported no quota. */
+    readonly availableBytes: number | null;
+    /** The configured models this was measured against; empty when uncapped. */
+    readonly models: string[];
+    /** Stable across builds, so an app can branch on it rather than on text. */
+    readonly code = "FORMAT2_STORAGE_UNAVAILABLE";
+    constructor(
+    /** `not-persistent`: nothing survives. `over-quota`: not enough room. */
+    reason: "not-persistent" | "over-quota", 
+    /**
+     * Materialized bytes the refused hydration would have needed, or `0` when
+     * nothing has been measured — the bind refuses before there is a manifest
+     * to measure, and on a document that may have no snapshot at all.
+     */
+    requiredBytes: number, 
+    /** Bytes the platform offered, or `null` when it reported no quota. */
+    availableBytes: number | null, 
+    /** The configured models this was measured against; empty when uncapped. */
+    models: string[]);
+}
+/** Which models a cold load should hydrate on this device. */
+interface HydrationPlan {
+    /** `full` took the whole snapshot; `capped` left models behind. */
+    kind: "full" | "capped";
+    /** Models to hydrate, in the manifest's order. */
+    models: string[];
+    /** Models the snapshot carries that this device is not taking. */
+    skipped: string[];
+    /** Materialized bytes the plan is expected to cost. */
+    bytes: number;
+}
+/**
+ * What the platform underneath will let a merged view keep.
+ *
+ * `persistent` is "there is a durable store to put it in", not "the user
+ * granted persistence": an origin whose data is evictable still holds the
+ * document until it is evicted, and a client that has been evicted cold-loads
+ * again. What it cannot survive is having nowhere to write at all — which on
+ * the browser means no origin-private file system, the platform Precondition B
+ * measures.
+ *
+ * A host that knows better (a worker with its own VFS, a test) passes a
+ * capability of its own instead of calling this.
+ */
+declare function probeStorageCapability(nav?: unknown): Promise<StorageCapability>;
+/**
+ * Decide what to hydrate before the load starts.
+ *
+ * Throws {@link Format2StorageCapabilityError} when the device cannot hold
+ * even the configured models — the app is told, rather than the load being
+ * started and abandoned partway through.
+ */
+declare function planSnapshotHydration(input: {
+    manifest: SnapshotManifest;
+    capability: StorageCapability;
+    /**
+     * The models to keep when the whole document will not fit — the app's
+     * statement of what is worth the space it has. Ignored when everything fits:
+     * this is a fallback for a device that cannot take the document, not a
+     * permanent narrowing of it.
+     */
+    models?: readonly string[];
+    /**
+     * Chunk keys a previous attempt already committed (`_snapshot_load`). Their
+     * rows are already on the device, so they are what it has to make room for
+     * only once.
+     */
+    completedChunks?: Iterable<string>;
+}): HydrationPlan;
+
+interface InitJsBaoOptions {
+    databaseConfig: DatabaseConfig;
+    /**
+     * Optional array of model classes to initialize.
+     * If not provided, the ORM will rely on models being registered
+     * via attachAndRegisterModel (assuming they have been imported by the application).
+     *
+     * Either way the instance takes a SNAPSHOT of the models at this moment: a
+     * class registered globally afterwards belongs to no live instance until the
+     * next `initJsBao` picks it up. That is the session semantics this call has
+     * always had; with per-instance state (#3039) it is worth saying out loud,
+     * because a late registration now has several instances it could mean.
+     */
+    models?: (typeof BaseModel)[];
+    /**
+     * What this device can hold of a large document, and what to keep when it
+     * cannot hold all of it (#2816, Precondition B's fallback).
+     *
+     * `capability` overrides the platform probe — a host that owns its own store
+     * knows better than `navigator.storage` does. `models` is the app's
+     * statement of which models are worth the space when the document does not
+     * fit; with none configured, a device short of space is refused rather than
+     * loaded arbitrarily.
+     */
+    largeDocumentStorage?: {
+        capability?: StorageCapability;
+        models?: string[];
+    };
+}
+interface InitJsBaoResult {
+    dbEngine: DatabaseEngine;
+    modelRegistry: ModelRegistry;
+    /**
+     * Which instance this is. The first-wins warning a shared model class
+     * produces names the instance that keeps the class and the one that loses
+     * it by this number, so a process holding several clients can tell them
+     * apart.
+     */
+    instanceId: number;
+    /**
+     * Tear THIS ORM instance down (#3039): its observers are removed, its engine
+     * destroyed and its state cleared, without touching any other instance.
+     *
+     * Its model classes are deliberately not unbound — they keep resolving this
+     * (now destroyed) instance, so an operation through them throws the ordinary
+     * not-initialized error instead of silently landing on a surviving client's
+     * database.
+     */
+    destroy: () => Promise<void>;
+    connectDocument: (docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint, options?: ConnectDocumentOptions) => Promise<void>;
+    disconnectDocument: (docId: string) => Promise<void>;
+    /**
+     * Format-2 (#2816) durable-acknowledgement marks for `docId`, or `null`
+     * when it is a legacy document. The transport stamps an outbound frame
+     * with these and prunes through `format2Acknowledge`.
+     */
+    format2SyncMarks: (docId: string) => Format2SyncMarks | null;
+    /**
+     * The epoch `docId`'s own RECORD DATABASE says it follows, readable before
+     * the document is bound (#2816). `0` when this database follows none —
+     * whatever the client's metadata claims — and `null` when the engine cannot
+     * be asked.
+     */
+    format2StoredEpoch: (docId: string) => number | null;
+    format2Acknowledge: (docId: string, maxContiguousSeq: number) => void;
+    /** Record the epoch a connection joined, for a document with no mark yet. */
+    format2NoteEpoch: (docId: string, epoch: number) => void;
+    /**
+     * Record that `docId` was in touch with the server, and the offline window
+     * the server reported (#2816, behavior 18). Past that window without a sync
+     * the document refuses local writes and keeps serving reads.
+     */
+    format2NoteSync: (docId: string, at: number, windowDays?: number) => void;
+    /**
+     * Record the offline window the handshake reported, without claiming a sync
+     * (#2816, behavior 18) — a frame is proof of contact, not proof that this
+     * client's merged view is the room's state.
+     */
+    format2NoteWindow: (docId: string, windowDays?: number) => void;
+    /**
+     * Resolves once the query tables have caught up with the merged view
+     * (#2816). `find()` reads the merged view, which a fold updates
+     * synchronously; `query()` reads the derived tables, which the projection
+     * queue updates after it — so an update from the room counts as applied only
+     * once this settles.
+     */
+    whenFormat2ProjectionSettled: () => Promise<void>;
+    /** Record the clock offset measured against a server frame (#2816). */
+    format2NoteClockOffset: (docId: string, offsetMs: number) => void;
+    /** Forget the pending ops a recency resolution dropped (#2816). */
+    format2ForgetPendingOps: (docId: string, seqs: number[]) => void;
+    /**
+     * Rewrite the pending ops a recency resolution narrowed (#2816): the durable
+     * log records the surviving delta, so a crash before the replay is
+     * acknowledged cannot put the dropped field back.
+     */
+    format2NarrowPendingOps: (docId: string, ops: Array<Pick<PendingOp, "seq" | "fields" | "mutation">>) => void;
+    /**
+     * The unacknowledged local writes of `docId` — what a client carries onto
+     * the next epoch's overlay when it follows a seal (#2816, behavior 10).
+     */
+    format2PendingOps: (docId: string) => PendingOp[];
+    /** Move the epoch mark after the new epoch's overlay has been installed. */
+    format2SetEpoch: (docId: string, epoch: number) => void;
+    /**
+     * Run an epoch move with `docId`'s local writes held back: a write that
+     * landed on the sealed overlay after what is owed had been read off it would
+     * go down with that document (#2816, behavior 10).
+     */
+    format2HoldWrites: <T>(docId: string, run: () => Promise<T>) => Promise<T>;
+    /**
+     * Re-point a connected large document at the next epoch's overlay, without
+     * disconnecting it — a rotation must not drop model→document mappings.
+     */
+    format2RebindEpochDocument: (docId: string, yDoc: Y.Doc, options?: {
+        restorePending?: boolean;
+    }) => Promise<void>;
+    /**
+     * Fold one sealed epoch's archived overlay into `docId`'s merged view — the
+     * step a client behind by whole epochs repeats per archive to catch up
+     * (#2816, behavior 12).
+     */
+    format2ApplySealedOverlay: (docId: string, update: Uint8Array) => Promise<void>;
+    /**
+     * Throw away a large document's merged view before it is rebuilt from a
+     * base — what a client does when the sealed-overlay chain that would have
+     * caught it up cannot be trusted (#2816, behavior 12).
+     */
+    format2DiscardMergedView: (docId: string) => Promise<void>;
+    /**
+     * Fold a large document's open-epoch overlay into its merged view again —
+     * the step that finishes a cold load, since a base snapshot's rows replace
+     * what the open epoch had already contributed (#2816, behavior 15).
+     */
+    format2RefoldOverlay: (docId: string) => Promise<void>;
+    /** Materialize a base snapshot into a large document's merged view (#2816). */
+    format2LoadSnapshot: (docId: string, manifest: SnapshotManifest, fetchChunk: (chunk: SnapshotChunkEntry) => Promise<Uint8Array>, callbacks?: {
+        onProgress?: (progress: SnapshotLoadProgress) => void;
+        onModelReady?: (model: string) => void | Promise<void>;
+    }) => Promise<SnapshotLoadResult>;
+    getConnectedDocuments: () => Map<string, ConnectedDocument>;
+    isDocumentConnected: (docId: string) => boolean;
+    onDocumentConnectionChange: (callback: DocumentConnectionCallback) => () => void;
+    addDocumentModelMapping: (modelName: string, docId: string) => void;
+    removeDocumentModelMapping: (modelName: string) => void;
+    clearDocumentModelMappings: () => void;
+    setDefaultDocumentId: (docId: string) => void;
+    clearDefaultDocumentId: () => void;
+    getDocumentModelMapping: () => Record<string, string>;
+    getDocumentIdForModel: (modelName: string) => string | undefined;
+    getDefaultDocumentId: () => string | undefined;
+    onDefaultDocChanged: (listener: (payload: {
+        previous?: string;
+        current?: string;
+    }) => void) => () => void;
+    onModelDocMappingChanged: (listener: (payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void) => () => void;
+}
+
+/**
+ * Initializes the js-bao system with multi-document support.
+ * Sets up the database engine and prepares for document connections.
+ *
+ * Every call returns its OWN instance: its own engine, model registry,
+ * connected documents, default-document mappings and `subscribe()` listeners.
+ * Nothing written through one instance is observable through another, and an
+ * instance can be torn down on its own through the returned `destroy()`.
+ *
+ * Model classes bind first-wins. A class handed to a second live `initJsBao`
+ * keeps routing to the instance it was bound to; the second call warns and
+ * carries on. Give each client its own model classes — as the `schemaToml`
+ * path already does — when they must be isolated.
  */
 declare function initJsBao(options: InitJsBaoOptions): Promise<InitJsBaoResult>;
 /**
- * Function to reset the initialization state, primarily for testing or hot-reloading scenarios.
+ * Reset the initialization state, primarily for testing or hot-reloading.
+ *
+ * Destroys EVERY live instance — engines included — leaves their model classes
+ * pointing at the instance that is gone rather than at a survivor, and stands a
+ * fresh default context up in their place.
  */
 declare function resetJsBao(): Promise<void>;
 
@@ -988,6 +2447,17 @@ interface DiscoveredSchema {
  * just a Y.Doc.
  */
 declare function discoverSchema(yDoc: Y.Doc): DiscoveredSchema;
+/**
+ * The schema ONE model DECLARES, read from its `_meta_<model>` map alone.
+ *
+ * `discoverSchema` walks every top-level map, and falls back to inferring a
+ * schema from record data for models without metadata. A caller that only
+ * needs one model's declaration — a format-2 document's projector deciding
+ * which fields are unique or indexed (#2816), on a write path that runs for
+ * every update — pays neither: the meta map is small and epoch-independent,
+ * and a model that declares nothing simply has no declaration.
+ */
+declare function discoverDeclaredModel(yDoc: Y.Doc, modelName: string): DiscoveredModel | undefined;
 /**
  * List model names that have data in the YDoc (non-`_` prefixed top-level maps).
  */
@@ -1002,6 +2472,41 @@ declare function discoverModelNames(yDoc: Y.Doc): string[];
  */
 declare function schemaToToml(schema: DiscoveredSchema): string;
 
+/**
+ * Unique-constraint index helpers (shared CRDT contract).
+ *
+ * js-bao enforces unique constraints inside the Yjs document, not via a SQL
+ * `UNIQUE`. Each constraint has a `_uniqueIdx_<model>_<constraint>` map
+ * (uniqueKey -> surviving recordId) and a document observer that
+ * deterministically discards duplicate losers. Both the client write path and
+ * the server-direct write path (`mutateRecord` in js-bao-wss) must derive the
+ * key and the index map name the SAME way, or a server-written record would
+ * not be seen by the client-side resolver. These helpers are the single source
+ * of truth for that derivation so neither side keeps a parallel copy.
+ */
+
+/**
+ * Build the unique-constraint key for a record over the given fields.
+ *
+ * Mirrors the document-observer conflict resolver: a `null`/`undefined` value
+ * in any field means the record does not participate in the constraint (returns
+ * `null`); otherwise the per-field `String()` values joined by `"|"`. This is
+ * the key the `_uniqueIdx_*` map is read/written with during conflict
+ * resolution, so it is the key the resolver treats as authoritative.
+ */
+declare function buildUniqueKey(recordData: Y.Map<any> | Record<string, any>, fields: string[]): string | null;
+/**
+ * Name of the Yjs map that indexes a unique constraint within a document:
+ * `_uniqueIdx_<model>_<constraint>` mapping uniqueKey -> surviving recordId.
+ */
+declare function uniqueIndexMapName(modelName: string, constraintName: string): string;
+/**
+ * The constraint name js-bao assigns to a single-field `unique: true` field
+ * (see `resolveUniqueConstraints` in models/schema.ts). Compound constraints
+ * keep their author-given name instead.
+ */
+declare function fieldUniqueConstraintName(modelName: string, fieldName: string): string;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -1038,4 +2543,790 @@ declare function dumpYDocToPlain(yDoc: Y.Doc, options?: DumpOptions): PlainYDoc;
  */
 declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
-export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, createModelClass, defineModelSchema, discoverModelNames, discoverSchema, dumpYDocToPlain, generateULID, inferFieldType, initJsBao, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };
+/**
+ * The client's epoch-doc observer for format-2 documents (#2816).
+ *
+ * The epoch Y.Doc is no longer the read model — it is a bounded overlay of
+ * this epoch's changes. Whatever lands in it (a peer's update applied by the
+ * sync layer, or this client's own write) has to be folded into the local
+ * merged `records` view, which is what reads come from.
+ *
+ * The observer rides the Yjs transaction for the same reason the server's
+ * projector does: `Transaction.changed` names precisely the overlay keys an
+ * update touched, so a remote update costs one merge-upsert per touched record
+ * instead of a walk of a document that may be 2GB.
+ */
+
+/** Whether a top-level key names an application model map. */
+declare function isFormat2ModelMap(key: string): boolean;
+/**
+ * Fold every overlay change on `doc` into `store`. Returns the unsubscribe
+ * function — a client calls it when the epoch is sealed and it switches to the
+ * next epoch's document.
+ */
+declare function observeFormat2Overlay(doc: Y.Doc, store: Format2RecordStore, 
+/**
+ * Called after each folded record, so the host can refresh derived state
+ * (the per-model query projection) for exactly what changed.
+ */
+onApplied?: (modelName: string, recordId: string) => void): () => void;
+
+/**
+ * Following a seal onto a fresh overlay (#2816, behavior 10 — client half).
+ *
+ * When the room seals epoch E it replaces its overlay with an empty one, so a
+ * client's further DELTAS against the sealed overlay cannot be integrated
+ * there. The obvious answer — resync the whole document — is the wrong one on
+ * a large document: a state-complete sync of the sealed overlay would seed
+ * E+1 with everything E held, the new epoch would re-cross the rotation
+ * threshold at once, and the overlay would never actually be bounded. That is
+ * precisely why automatic rotation stayed opt-in until this path existed.
+ *
+ * What a client actually owes the new epoch is narrow: the writes the server
+ * has not acknowledged. Everything acknowledged is already in the server's
+ * `records` table — the sealed overlay was archived and folded — and in the
+ * client's own merged view, so re-sending it buys nothing and costs an epoch.
+ *
+ * The owed writes are carried as OVERLAY entries taken from the sealed
+ * document rather than rebuilt from the merged view, because the overlay is
+ * the only place their exact shape survives: an explicit `null` unset, a
+ * stringset member tombstone, and the difference between a patch and a
+ * `_replace` create all vanish once a row has been materialized.
+ *
+ * They are restricted to the fields the unacked ops touched, so replaying them
+ * cannot clobber a peer's concurrent write to another field of the same
+ * record. A create is the exception: `_replace` discards the base row, so it
+ * is carried whole or not at all.
+ */
+
+/**
+ * The name a client's persisted overlay is stored under.
+ *
+ * Epoch-scoped so a restart restores the CURRENT epoch's overlay — which still
+ * holds its unacked writes — and never a sealed one, whose content the server
+ * has already folded away. It also bounds what an IndexedDB reset costs: one
+ * epoch to re-sync, not the whole document.
+ */
+declare function format2EpochDocName(docId: string, epoch: number): string;
+/** One record's owed overlay, ready to be written on the new epoch's document. */
+interface CarriedOverlay {
+    model: string;
+    entry: OverlayRecordEntry;
+}
+/** Reads a record's whole overlay entry out of the epoch being left behind. */
+type OverlayReader = (model: string, recordId: string) => OverlayRecordEntry;
+/**
+ * The overlay a client carries into the next epoch: one entry per record its
+ * unacked ops touched, in the local order those ops were written.
+ *
+ * `ops` is the durable `_pending_ops` log — already exactly the unacked ones,
+ * since an `update.ack` prunes at its contiguous high-water mark.
+ */
+declare function carryUnackedOverlay(ops: PendingOp[], readOverlay: OverlayReader, options?: {
+    /**
+     * Records whose tombstone must not travel (#2816, behavior 17): the
+     * client's own delete lost to a write made online after it, and the
+     * lifecycle carryRecord reads off the overlay still records that delete.
+     */
+    suppressDeletes?: Array<{
+        model: string;
+        recordId: string;
+    }>;
+}): CarriedOverlay[];
+/**
+ * Write a carried entry's flat keys onto the new epoch's model map.
+ *
+ * Encoded here rather than through `encodeOverlayMutation` because a carried
+ * entry is already an overlay — its explicit nulls, its member tombstones and
+ * its markers travel verbatim, with no mutation semantics re-derived on top.
+ */
+declare function writeCarriedOverlay(modelMap: Y.Map<any>, entry: OverlayRecordEntry): void;
+
+/**
+ * Switching a connected client's write target across a rotation (#2816,
+ * behavior 10 — client half).
+ *
+ * Sealing epoch E leaves the room writing to an empty overlay. Everything a
+ * client sends afterwards from its E document is a Yjs DELTA whose causal
+ * dependencies the new overlay does not have, so it is parked rather than
+ * integrated — which is why a client has to move to E+1 too.
+ *
+ * Moving means a FRESH document, not a resync of the old one. A state-complete
+ * sync of the sealed overlay would seed E+1 with everything E held: the new
+ * epoch would re-cross the rotation threshold immediately, and rotation would
+ * never bound anything. The only thing worth carrying across is what the
+ * server has not acknowledged — see `format2EpochHandoff`.
+ *
+ * The orchestration lives behind a host interface because the pieces it moves
+ * belong to three different owners (the document manager holds the Y.Doc and
+ * its persistence, the ORM holds the record store, the transport holds the
+ * socket) and because the ordering — carry, install, resync — is the behavior.
+ */
+
+/** What following a seal needs from the client that owns the document. */
+interface EpochRotationHost {
+    /** The overlay the client writes to now, or `null` when it holds none. */
+    overlayDoc(): Y.Doc | null;
+    /** The epoch the client is on; `0` when it has never followed one. */
+    epoch(): number;
+    /** The durable, still-unacknowledged local writes, oldest first. */
+    pendingOps(): PendingOp[];
+    /**
+     * Decide which of those writes still stand (#2816, behavior 17).
+     *
+     * Set only by a client that is REJOINING after being away: the sealed
+     * overlays it just applied say which records and fields were written online
+     * meanwhile, so an offline write can be dropped where it clearly lost rather
+     * than silently overwriting the newer value. A client following an ordinary
+     * seal has nothing to resolve — it was there the whole time — and leaves
+     * this unset, which carries every unacked write exactly as before.
+     */
+    resolveReplay?(ops: PendingOp[]): {
+        ops: PendingOp[];
+        suppressDeletes: Array<{
+            model: string;
+            recordId: string;
+        }>;
+    };
+    /**
+     * Drop whatever outbound frames are still queued for this document.
+     *
+     * They are deltas against the overlay the room has just replaced, so it
+     * cannot integrate them: it withholds the acknowledgement for the whole
+     * frame they are merged into — including any fresh write that rode along —
+     * and asks for a resync. Nothing is lost by dropping them, because their
+     * content is either already durable or recorded in `_pending_ops`, which is
+     * exactly what this move carries across.
+     */
+    discardQueuedFrames(): void;
+    /**
+     * Adopt `doc` as the overlay for `epoch`: rebind the readers, re-point the
+     * persistence at the epoch-scoped name, and record the new mark.
+     *
+     * `restorePending: false` asks the bind NOT to write the unacknowledged
+     * writes back into the document. Set only by a returning client's deferred
+     * move: those writes have not been resolved yet, and restoring them here
+     * would put them in the epoch's own Y.Map keys before the epoch's content
+     * arrives — the very race the deferral exists to avoid.
+     */
+    install(doc: Y.Doc, epoch: number, options?: {
+        restorePending?: boolean;
+    }): Promise<void>;
+    /** Sync the fresh overlay with the room, which pushes what was carried. */
+    resync(): Promise<void>;
+    /**
+     * Run the move with this document's local writes held back.
+     *
+     * The move destroys the sealed overlay once the fresh one is bound, so a
+     * write that slipped in between reading what is owed and rebinding the
+     * readers would land its overlay entry in the doomed document — and could
+     * never be recovered, since `_pending_ops` records which fields a write
+     * touched, not the values. Optional so a host that owns no writes (a test
+     * driving the state machine) need not provide one.
+     */
+    hold?<T>(run: () => Promise<T>): Promise<T>;
+}
+/** Why a client did or did not move. */
+type EpochRotationOutcome = {
+    moved: true;
+    epoch: number;
+    carried: number;
+    /**
+     * The replay this move DEFERRED (#2816, behavior 17).
+     *
+     * Present only on a returning client's move: the owed writes have been
+     * read off the sealed overlay but not resolved or written anywhere,
+     * because the epoch being joined is open and its own content — the rest
+     * of the online side of every conflict — arrives on the sync this move
+     * asked for. The caller runs this once that has landed; it resolves
+     * against the evidence by then complete, and writes the survivors onto
+     * the live overlay. Returns how many records it carried.
+     */
+    completeReplay?: () => Promise<number>;
+} | {
+    moved: false;
+    reason: 
+    /** Not a large document — nothing here applies. */
+    "not-large"
+    /** The client has never followed an epoch; it simply joins this one. */
+     | "adopted"
+    /** A duplicate or late notice of an epoch already left behind. */
+     | "already-current"
+    /** Epochs were missed: catching up is the fast-forward path's job. */
+     | "behind";
+};
+/**
+ * Move the client onto `nextEpoch`.
+ *
+ * Only ever moves one epoch forward from where the client is. A larger jump
+ * means the client missed seals — its merged view is behind by whole sealed
+ * overlays, which have to be applied in order before it may write again, so it
+ * is reported rather than papered over.
+ */
+declare function followEpoch(host: EpochRotationHost, nextEpoch: number, options?: {
+    /**
+     * Allow a move of more than one epoch.
+     *
+     * Only ever set by the fast-forward path (behavior 12), which has just
+     * applied every sealed overlay in between: the epochs are no longer
+     * missing, so the jump skips nothing. Without that, a jump means the
+     * client's merged view has holes in it and the move is refused.
+     */
+    allowJump?: boolean;
+    /**
+     * Hold the owed writes back until the epoch being joined has been synced
+     * (#2816, behavior 17).
+     *
+     * Honored only where there is something to resolve — a returning client
+     * with a conflict ledger, i.e. a host that supplies `resolveReplay`. A
+     * client that was present through the seal has no online side to compare
+     * with, so it carries at once exactly as before.
+     */
+    deferCarry?: boolean;
+}): Promise<EpochRotationOutcome>;
+
+/**
+ * Catching a client up on the sealed overlays it missed (#2816, behavior 12).
+ *
+ * A client that was away while the room rotated is behind by whole epochs: its
+ * merged view is missing every write since it left, and its own overlay
+ * belongs to an epoch the room archived. It does NOT need the document back,
+ * though. The sealed overlays between the epoch it holds and the one the room
+ * is on are exactly the changes it missed, so applying them in order — each a
+ * bounded, rotation-sized artifact — converges its merged view on the server's
+ * `records` table without a base ever crossing the wire.
+ *
+ * Two halves, deliberately separate:
+ *
+ * - {@link planFastForward} decides whether the chain can be trusted, from the
+ *   handshake alone and before anything is downloaded. A gap, a pruned
+ *   archive, or an epoch flagged `baseDiscontinuity` all mean the sum of the
+ *   overlays is not the document, and the honest answer is to reload from a
+ *   snapshot rather than converge on a state that never existed.
+ * - {@link applyFastForward} runs the plan. It knows nothing about record
+ *   stores or sockets: the host fetches an archive and folds a decoded overlay,
+ *   which is what makes the ordering testable without either.
+ *
+ * The epoch mark is the caller's to move, and only after the whole chain has
+ * landed: applying an overlay is idempotent at the record level, so a chain
+ * that fails halfway is simply run again.
+ */
+
+/** One sealed epoch as the handshake describes it. */
+interface SealedEpochChainEntry {
+    epoch: number;
+    /** Reserved (#2816): the next base is not this epoch's overlay applied. */
+    baseDiscontinuity?: boolean;
+    /**
+     * Whatever the host needs to read this epoch's archive, opaque here. Absent
+     * when retention has already pruned it.
+     */
+    download?: unknown;
+}
+/** One archive to apply. */
+interface FastForwardStep {
+    epoch: number;
+    download: unknown;
+}
+/** Why a chain cannot be trusted. */
+type FastForwardRefusal = 
+/** The chain skips an epoch: the client cannot know what happened in it. */
+"gap"
+/** An epoch declares its base is not the previous overlay applied. */
+ | "discontinuity"
+/** The archive is gone — pruned once a snapshot covered it. */
+ | "unavailable";
+type FastForwardPlan = {
+    kind: "none";
+    reason: "current" | "adopt";
+} | {
+    kind: "apply";
+    from: number;
+    to: number;
+    steps: FastForwardStep[];
+} | {
+    kind: "reload";
+    reason: FastForwardRefusal;
+    epoch: number;
+};
+/**
+ * Decide how a client on `current` reaches `target`.
+ *
+ * The chain runs from the epoch the client HOLDS, not from the one after it:
+ * writes landed in that epoch after this client went away, and its archive is
+ * the only place they exist now. The target epoch itself is open — the client
+ * reaches that one by syncing, as it always did.
+ */
+declare function planFastForward(options: {
+    current: number;
+    target: number;
+    sealed: SealedEpochChainEntry[];
+}): FastForwardPlan;
+/** What running a plan needs from the client around it. */
+interface FastForwardHost {
+    /** Read one sealed epoch's archived overlay. */
+    fetchArchive(step: FastForwardStep): Promise<Uint8Array>;
+    /**
+     * Fold one decoded overlay into the merged view. Awaited, so a host whose
+     * store commits asynchronously cannot have two epochs in flight at once.
+     */
+    applyOverlay(doc: Y.Doc, epoch: number): void | Promise<void>;
+    /** Called after each epoch lands, for progress reporting. */
+    onEpochApplied?(epoch: number, index: number, total: number): void;
+}
+/** What the whole catch-up needs, beyond reading and folding archives. */
+interface FastForwardRunHost extends FastForwardHost {
+    /**
+     * Run the catch-up with this document's local writes held back.
+     *
+     * A save that resolved its target before the catch-up and lands during it
+     * would write into an overlay the move is about to replace — and
+     * `_pending_ops` records which fields a write touched, not the values, so
+     * nothing could reconstruct it.
+     */
+    hold<T>(run: () => Promise<T>): Promise<T>;
+    /**
+     * Move onto `target`: install a fresh overlay for it, carrying whatever the
+     * server has not acknowledged, and resync. Called only once the whole chain
+     * has landed, so the jump is no longer a jump over anything unknown.
+     */
+    move(target: number): Promise<void>;
+}
+/** How a catch-up ended. */
+type FastForwardResult = {
+    outcome: "none";
+    reason: "current" | "adopt";
+} | {
+    outcome: "caught-up";
+    applied: number[];
+    epoch: number;
+} | {
+    outcome: "reload";
+    /** `failed` is a verified chain that could not be read. */
+    reason: FastForwardRefusal | "failed";
+    epoch: number;
+    /**
+     * What stopped a `failed` chain. A document that quietly stops syncing
+     * is the hardest kind of bug to diagnose, so the cause travels with the
+     * refusal instead of being swallowed.
+     */
+    error?: unknown;
+};
+/**
+ * Verify the chain, apply it, and move onto the room's epoch.
+ *
+ * The order is the behavior: nothing is downloaded until the chain is known to
+ * be complete, and the epoch is not moved until every archive in it has been
+ * folded. A chain that fails halfway leaves the client exactly where it was —
+ * behind, readable, and told to reload — rather than half-caught-up on an
+ * epoch it would then write into.
+ */
+declare function runFastForward(host: FastForwardRunHost, options: {
+    current: number;
+    target: number;
+    sealed: SealedEpochChainEntry[];
+}): Promise<FastForwardResult>;
+/**
+ * Apply a verified chain, oldest epoch first, and report what landed.
+ *
+ * Strictly sequential: overlays are state deltas over one another, so applying
+ * a later one before an earlier one would let a stale value win. A failure
+ * propagates with the epochs before it already folded — harmless, because the
+ * caller has not moved the epoch mark and re-applying is idempotent.
+ */
+declare function applyFastForward(plan: Extract<FastForwardPlan, {
+    kind: "apply";
+}>, host: FastForwardHost): Promise<number[]>;
+
+/**
+ * Opening a large document with nothing local to start from (#2816,
+ * behavior 15).
+ *
+ * A fresh client is not "behind": it holds no overlay, so there is nothing to
+ * catch up from and the fast-forward planner rightly says "adopt". Under
+ * epochs that is not enough. The epoch it would adopt holds only the changes
+ * since the last rotation — everything older lives in the server's `records`
+ * table and in the base snapshot in R2 — so a client that just joined would
+ * show an almost-empty document, and, because a create is decided against the
+ * merged view, would `_replace` records that still exist.
+ *
+ * So a cold start on a document that has ever rotated rebuilds a base first:
+ *
+ * - the latest completed snapshot, then the overlays sealed since — one base
+ *   plus a bounded chain, whatever the document's age;
+ * - or, before any build has completed, the sealed overlays from the very
+ *   first epoch, which retention keeps precisely until a snapshot covers them;
+ * - or nothing, when neither is available — which is reported rather than
+ *   papered over, because opening a document with holes in it is worse than
+ *   not opening it.
+ */
+
+/** How a document with no local state should be opened. */
+type ColdStartPlan = 
+/** The document already follows an epoch: the catch-up path owns it. */
+{
+    kind: "catch-up";
+}
+/** Nothing was ever archived — the current overlay IS the document. */
+ | {
+    kind: "join";
+}
+/** Materialize this snapshot, then apply the overlays sealed since. */
+ | {
+    kind: "snapshot";
+    base: number;
+}
+/** No snapshot yet: the sealed chain from `base` is the document. */
+ | {
+    kind: "overlays";
+    base: number;
+}
+/** Neither a base nor a complete chain is available. */
+ | {
+    kind: "unavailable";
+    reason: "no-base";
+};
+/**
+ * Decide how to open a document the client has no epoch mark for.
+ *
+ * A snapshot is preferred whenever the client can chain forward from it: one
+ * base plus the overlays after it, rather than replaying every epoch since the
+ * document was created — the cost this epic exists to remove. When the chain
+ * above the snapshot is broken but the whole chain from the first epoch is
+ * intact, that chain is used instead; it says the same thing, more expensively.
+ */
+declare function planColdStart(input: {
+    /** The epoch this client's overlay belongs to; 0 when it has none. */
+    held: number;
+    /** The epoch the room reports. */
+    reported: number;
+    sealed: readonly SealedEpochChainEntry[];
+    /** The newest completed snapshot the handshake offered, if any. */
+    snapshot?: {
+        epoch: number;
+    } | null;
+}): ColdStartPlan;
+/** What running a plan does to the document around it. */
+interface ColdStartHost {
+    /**
+     * Adopt the reported epoch as the one this document now follows.
+     *
+     * Two callers: the document where nothing was ever archived (the overlay IS
+     * the document), and the end of a successful rebuild. The second is not
+     * optional bookkeeping — the mark is what a later open reads to tell "this
+     * client holds the document as of epoch E" from "this client holds nothing".
+     * Without it a client that has just streamed a whole base presents as fresh
+     * again on its next handshake and rebuilds from the same base.
+     */
+    join(): void | Promise<void>;
+    /**
+     * Throw away a merged view that cannot be repaired, keeping the writes this
+     * client still owes the server.
+     */
+    discard(): void | Promise<void>;
+    /** Materialize the base snapshot for `base`. */
+    loadSnapshot(base: number): Promise<void>;
+    /**
+     * Apply the sealed overlays from `base` on and move onto the room's epoch.
+     * Returns whether the document ended up current.
+     */
+    applyChain(base: number): Promise<boolean>;
+    /** Run the ordinary catch-up for a document that is merely behind. */
+    catchUp(): Promise<boolean>;
+    /**
+     * Join the epoch the room is on, if the rebuild has not already.
+     *
+     * Needed because the base a refused client rebuilds from is usually the
+     * epoch the room is ON — a snapshot built after the last seal has nothing
+     * sealed above it — so the chain is empty and moves nothing. The document
+     * would then keep an overlay belonging to the epoch it was rebuilt out of:
+     * never joining, and blind to every write made since.
+     */
+    land(): Promise<boolean>;
+    /**
+     * Fold the OPEN epoch's overlay over the base that was just installed.
+     *
+     * A base snapshot is a set of rows, not a diff: every row it carries
+     * REPLACES what the merged view held for that record. The open epoch's
+     * overlay — the changes since the base was cut — is the one part of the
+     * document that does not arrive through the rebuild at all: this client
+     * syncs it as an ordinary Y.Doc, before the load, during it, or after. So
+     * whatever of it had already been folded is overwritten by the load, and a
+     * patch or a delete made in the open epoch would come back as the base's
+     * older row.
+     *
+     * Folding it again at the end costs one walk of a bounded overlay and is
+     * idempotent (overlay entries are state, not operations), which is why it is
+     * done unconditionally rather than only when a race is suspected.
+     */
+    refoldOverlay?(): void | Promise<void>;
+    /**
+     * Report a base that could not be read. A document that quietly stops
+     * opening is the hardest kind of bug to diagnose, so the cause is handed
+     * back rather than swallowed here.
+     */
+    onLoadFailed?(error: unknown): void;
+}
+/**
+ * Run a rebuild plan, and say whether the document came out current.
+ *
+ * `stale` is the whole difference between the two callers. A client opening a
+ * document for the first time has nothing to throw away — and throwing away
+ * anyway would destroy the chunk marks an interrupted load resumes from, which
+ * on a multi-hundred-megabyte base means starting over on every dropped
+ * connection. A client whose sealed-overlay chain was REFUSED does: its rows
+ * are an epoch the room left behind, and a snapshot loaded over them would
+ * leave behind every record deleted since (#2816, behavior 12's close-out).
+ */
+declare function runColdStart(host: ColdStartHost, plan: ColdStartPlan, options?: {
+    stale?: boolean;
+}): Promise<boolean>;
+
+/**
+ * Replaying what a client wrote while it was away (#2816, behavior 17 —
+ * amended D1, recency-aware).
+ *
+ * A client reconnecting into a later epoch replays its unacknowledged writes
+ * onto the epoch it lands on. Doing that unconditionally — the original D1 —
+ * silently overwrites whatever anyone else wrote in between, including writes
+ * made days after the offline one. Doing it with per-field timestamps would
+ * mean stamping every field of every record, in the overlay, in `records` and
+ * in every snapshot chunk, for a case that is rare by construction.
+ *
+ * Neither is necessary, because the client already holds both halves of the
+ * evidence by the time it replays:
+ *
+ * - WHAT was written online: the sealed overlays it applies while catching up
+ *   are precisely the touched records and fields of the epochs it missed;
+ * - WHEN: an epoch's window runs from the previous epoch's seal to its own,
+ *   and the open epoch's ends now.
+ *
+ * So each op's own `ts` — stamped with the client's server-offset-corrected
+ * clock — is placed against the window of the epoch that touched the same
+ * field. Clearly after it, the offline write wins. Clearly before it, the
+ * online write wins and the offline one is DROPPED AND SURFACED rather than
+ * silently applied. Inside the window the order is genuinely unknown, so the
+ * offline write wins and is surfaced too.
+ *
+ * Two rules are not recency-gated:
+ *
+ * - a patch is never replayed onto a record deleted meanwhile — resurrecting
+ *   a deleted record is worse than losing an edit to it, whatever the clock
+ *   says (a re-create is different: `_replace` states the record exists, so it
+ *   is resolved on recency like any other write);
+ * - an op whose base-epoch chain is unavailable (retention pruned it) cannot
+ *   be checked at all, so it falls back to plain offline-wins — surfaced as
+ *   unverifiable rather than silently trusted.
+ *
+ * And nothing is ever dropped on a clock this client has no reason to trust:
+ * with no measured server offset, "clearly older" degrades to the ambiguous
+ * case, which keeps the write.
+ */
+
+/** What one epoch did to one record, from that epoch's sealed overlay. */
+interface RecordTouch {
+    /** The epoch, for reporting which write the offline one raced. */
+    epoch: number;
+    fields: Set<string>;
+    deleted: boolean;
+    /** A `_replace` create: it replaced the whole row, so it touched every field. */
+    replaced: boolean;
+}
+/** The window an epoch's writes fall in: `[start, end]`, inclusive. */
+interface EpochWindow {
+    /** The previous epoch's seal, or `null` when it is not known. */
+    start: number | null;
+    /** This epoch's seal, or `null` while it is still open. */
+    end: number | null;
+}
+/**
+ * What the sealed overlays a catch-up applied say about the online side.
+ *
+ * Built as the chain is applied — the overlays are already decoded there — so
+ * conflict detection costs one walk of artifacts the client was downloading
+ * anyway.
+ */
+declare class OfflineConflictLedger {
+    /** Latest touch per record per epoch, newest epoch last. */
+    private readonly touches;
+    private readonly sealedAt;
+    private readonly notedEpochs;
+    /** Record the seal times the handshake reported. */
+    noteSealTimes(times: Array<{
+        epoch: number;
+        sealedAt: number | null | undefined;
+    }>): void;
+    /** Note one record's overlay entry from `epoch`. */
+    noteEntry(epoch: number, model: string, entry: OverlayRecordEntry): void;
+    /** Note everything one sealed epoch's decoded overlay touched. */
+    noteOverlay(epoch: number, doc: Y.Doc): void;
+    /**
+     * Whether every epoch from `from` up to (but not including) `to` was applied
+     * through this ledger — the chain an op's conflicts would have to be in.
+     */
+    covers(from: number, to: number): boolean;
+    /** The window `epoch`'s writes fall in; `end` is `null` while it is open. */
+    window(epoch: number, currentEpoch: number): EpochWindow;
+    /** The latest epoch after `afterEpoch` that touched `field` of a record. */
+    conflictFor(model: string, recordId: string, field: string, afterEpoch: number): RecordTouch | null;
+    /** The latest epoch after `afterEpoch` that touched a record at all. */
+    recordConflict(model: string, recordId: string, afterEpoch: number): RecordTouch | null;
+    /** The latest epoch after `afterEpoch` that DELETED a record. */
+    deletedAfter(model: string, recordId: string, afterEpoch: number): RecordTouch | null;
+}
+/** What the app is told about an offline write that did not simply apply. */
+interface OfflineReplayNotice {
+    model: string;
+    recordId: string;
+    /** Absent for a whole-record outcome (a delete, or a dropped patch). */
+    field?: string;
+    op: PendingOp["op"];
+    outcome: "dropped" | "kept-ambiguous";
+    reason: "outdated" | "record-deleted" | "in-window" | "unverifiable";
+    /** The epoch whose write it raced; `0` when there was no chain to check. */
+    epoch: number;
+    /** The offline write's own time, as the client stamped it. */
+    ts: number;
+}
+/** A record whose carried overlay must NOT bring its tombstone along. */
+interface SuppressedDelete {
+    model: string;
+    recordId: string;
+}
+/** What the epoch handoff replays, after recency has had its say. */
+interface OfflineReplayPlan {
+    /** The surviving ops, in the client's original local order. */
+    ops: PendingOp[];
+    suppressedDeletes: SuppressedDelete[];
+    notices: OfflineReplayNotice[];
+    /**
+     * Ops that survived in PART — the durable `_pending_ops` row still records
+     * the whole write and has to be rewritten to what survived.
+     *
+     * Narrowing an op in memory is not enough. The row carries the mutation the
+     * write made, so a crash before the server acknowledges the replay would
+     * have the restore path put the WHOLE mutation back on the overlay,
+     * including the field this resolution just decided the online side had won.
+     * The write that lost would come back — quietly, and only on the machines
+     * that crashed at the wrong moment.
+     */
+    narrowed: PendingOp[];
+    /**
+     * Whether a dropped write leaves this client's merged view unable to state
+     * the record correctly (#2816, behavior 17).
+     *
+     * A dropped DELETE is the case: the row was removed locally when the delete
+     * was written, and the online writes folded on top of that absence created
+     * the record again from their own fields alone. The fields the delete
+     * removed live only in the base and the epochs before it, so no artifact
+     * this client still holds can restore them — the merged view has to be
+     * rebuilt from a base before the delete is abandoned.
+     */
+    rebuildRequired: boolean;
+}
+/**
+ * Decide what a reconnecting client replays onto the epoch it landed on.
+ *
+ * Ops are returned in their original local order — a later op of the same
+ * record must not overtake an earlier one — with their `fields` narrowed to
+ * what survived. An op that lost everything is absent entirely.
+ */
+declare function resolveOfflineReplay(options: {
+    ops: PendingOp[];
+    ledger: OfflineConflictLedger;
+    /** The epoch being replayed onto (its window ends now). */
+    currentEpoch: number;
+    now: number;
+    /** Whether the op timestamps were corrected against server time. */
+    clockOffsetKnown?: boolean;
+}): OfflineReplayPlan;
+
+/**
+ * The offline write window of a large document (#2816, behavior 18).
+ *
+ * A format-2 client writes while it is offline: the write lands in the merged
+ * view immediately and waits in `_pending_ops` for the reconnect that replays
+ * it onto whatever epoch the room has reached. What makes that replay
+ * resolvable is the sealed-overlay chain back to the epoch the op was written
+ * against — and retention releases an overlay once a snapshot covers it and it
+ * is older than the window W. So a client that has been away longer than W is
+ * writing against a past the server can no longer reconcile it with.
+ *
+ * Past the window the document is READ-ONLY rather than a growing pile of
+ * writes that will be resolved by guesswork: local writes are refused with a
+ * typed error, reads keep answering out of the merged view the client already
+ * holds, and a sync restores writes immediately. Nothing already acked is
+ * touched, and a refused write leaves nothing behind — no merged row, no
+ * pending op — so the refusal cannot itself become a write that replays later.
+ *
+ * The window is the server's number (the same per-app W retention prunes
+ * archives by), delivered on `epoch.info` and persisted locally: the session
+ * that has to enforce it is by definition the one that cannot ask.
+ */
+/** The window a deployment gets when it configures nothing. */
+declare const DEFAULT_OFFLINE_WINDOW_DAYS = 7;
+/**
+ * The range the window is clamped to — the same 1–14 days as overlay
+ * retention, because the archive chain is exactly what an offline write is
+ * replayed across.
+ */
+declare const MIN_OFFLINE_WINDOW_DAYS = 1;
+declare const MAX_OFFLINE_WINDOW_DAYS = 14;
+/**
+ * Read a configured window, clamped, with the default for anything
+ * unparseable.
+ *
+ * Clamped rather than refused for the same reason retention clamps: the
+ * alternative to a usable number here is a client that either never goes
+ * read-only or goes read-only immediately, and both are worse than a number
+ * that is merely not the one someone typed.
+ */
+declare function configuredOfflineWindowDays(raw: unknown): number;
+/** Where a document stands relative to its offline write window. */
+interface OfflineWindowStatus {
+    /** Whether a local write may be accepted now. */
+    writable: boolean;
+    /** The sync this is measured from, or `null` when none was ever recorded. */
+    lastSyncAt: number | null;
+    windowDays: number;
+    windowMs: number;
+    /** How far PAST the window the client is; `0` while it is inside it. */
+    overdueMs: number;
+}
+/**
+ * Decide the window from the mark the client persisted.
+ *
+ * A client with no mark is writable: the window measures time since the last
+ * sync, and treating "no mark yet" as "infinitely stale" would strand a
+ * freshly loaded document in read-only with no way out. The mark is written
+ * the first time the client hears from the server, which is before it can
+ * possibly be a week behind.
+ */
+declare function offlineWindowStatus(input: {
+    lastSyncAt: number | null | undefined;
+    windowDays?: number | null;
+    now?: number;
+}): OfflineWindowStatus;
+/** Raised for a local write on a document past its offline window. */
+declare class DocumentOfflineWindowError extends Error {
+    readonly code = "DOCUMENT_OFFLINE_WINDOW_EXPIRED";
+    readonly documentId: string;
+    readonly lastSyncAt: number | null;
+    readonly windowDays: number;
+    readonly overdueMs: number;
+    constructor(documentId: string, status: OfflineWindowStatus);
+}
+/** The window each large-document write is checked against. */
+interface OfflineWindowSource {
+    lastSyncAt(): number | null;
+    offlineWindowDays(): number;
+}
+/**
+ * The one gate every format-2 local write passes.
+ *
+ * Checked BEFORE anything is committed, so a refused write leaves neither a
+ * merged row nor a pending op behind.
+ */
+declare function assertWithinOfflineWindow(documentId: string, source: OfflineWindowSource, now?: number): void;
+
+export { BaseModel, type CarriedOverlay, type ColdStartHost, type ColdStartPlan, type ConnectedDocument, DEFAULT_OFFLINE_WINDOW_DAYS, DEFAULT_OVERLAY_TABLES, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, DocumentOfflineWindowError, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type EpochRotationHost, type EpochRotationOutcome, type EpochWindow, type FastForwardHost, type FastForwardPlan, type FastForwardRefusal, type FastForwardResult, type FastForwardRunHost, type FastForwardStep, type FieldOptions, Format2CompositeFieldError, Format2ModelNotHydratedError, Format2RecordStore, Format2StorageCapabilityError, type Format2StoreSql, type HydrationPlan, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, MAX_OFFLINE_WINDOW_DAYS, MIN_OFFLINE_WINDOW_DAYS, type ModelConstructor, type ModelOptions, ModelRegistry, OVERLAY_KEY_SEPARATOR, OVERLAY_MARKER_DELETED, OVERLAY_MARKER_REPLACE, OfflineConflictLedger, type OfflineReplayNotice, type OfflineReplayPlan, type OfflineWindowStatus, type OverlayMutation, type OverlayReader, type OverlayRecordEntry, type OverlaySql, type OverlayTables, type PaginatedResult, type PaginationOptions, type ParsedOverlayKey, type PendingOp, type PendingOpInput, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, SNAPSHOT_COMPRESSED_EXPANSION, SNAPSHOT_STORAGE_EXPANSION, type SaveOptions, type SealedEpochChainEntry, type SnapshotChunkEntry, SnapshotLoadIntegrityError, type SnapshotLoadProgress, type SnapshotLoadResult, type SnapshotManifest, type SnapshotRow, type StorageCapability, StringSet, type SuppressedDelete, UniqueConstraintViolationError, applyFastForward, applyOverlayMutation, assertNoFormat2CompositeFields, assertWithinOfflineWindow, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, buildUniqueKey, carryUnackedOverlay, clearMetaSyncCache, completeOverlayEntries, configuredOfflineWindowDays, createModelClass, decodeOverlaySegment, defineModelSchema, discoverDeclaredModel, discoverModelNames, discoverSchema, dumpYDocToPlain, encodeOverlayMutation, encodeOverlaySegment, estimateMaterializedBytes, fieldUniqueConstraintName, followEpoch, format2ClientDDL, format2EpochDocName, format2StringSetMembers, format2TableNames, generateULID, groupOverlayEntries, inferFieldType, initJsBao, isFormat2ModelMap, isFormat2StringSetYMap, loadFormat2Snapshot, loadSchemaFromToml, loadSchemaFromTomlString, materializeOverlayRecord, observeFormat2Overlay, offlineWindowStatus, overlayFieldKey, overlayMarkerKey, overlayMemberKey, parseOverlayKey, planColdStart, planFastForward, planSnapshotHydration, probeStorageCapability, projectOverlayEntry, readOverlayRecord, readSnapshotChunk, registerFunctionDefault, resetJsBao, resolveOfflineReplay, runColdStart, runFastForward, schemaToToml, snapshotChunkPath, summarizePlainYDoc, syncInferredMeta, syncModelMeta, uniqueIndexMapName, writeCarriedOverlay };