js-bao 0.5.1 → 0.6.0

package/dist/cloudflare-do.d.ts

@@ -75,6 +75,510 @@ interface ModelOptions {
     relationships?: Record<string, RelationshipConfig>;
 }
 
+/**
+ * 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;
+}
+/** 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;
+};
+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>;
@@ -130,6 +634,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>;
 }
 
@@ -981,6 +1511,18 @@ interface HookResult {
     allow: boolean;
     /** Reason for denial (returned to client as error message) */
     reason?: string;
+    /**
+     * Names of fields the hook wrote onto `ctx.data` that the DO should echo
+     * back to the caller in the write response's `appliedFields`. A `beforeSave`
+     * hook can compute and set fields on `ctx.data` (e.g. app-level triggers that
+     * derive a value from the submitted row); those values are persisted but are
+     * invisible to a caller that rebuilds a change event from its original
+     * submission inputs. Reporting the names here lets the DO read the final
+     * post-hook values back and thread them into `appliedFields` so the caller
+     * can propagate them (#1476). The hook contract stays generic — it names the
+     * fields it applied and does not need to know how the caller uses them.
+     */
+    serverAppliedFieldNames?: string[];
 }
 /** Result from beforeQuery hooks — can inject additional filters */
 interface BeforeQueryResult extends HookResult {
@@ -1107,6 +1649,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -1189,6 +1745,8 @@ interface PatchRequest {
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -1216,12 +1774,46 @@ interface BatchOperation {
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];
@@ -1453,6 +2045,33 @@ declare function createDatabaseDO(config?: DatabaseDOConfig): {
  */
 declare const createDocumentDO: typeof createDatabaseDO;
 
+/**
+ * Decoding for rows read out of the schemaless `records` table.
+ *
+ * A `SELECT` built by `JsonQueryTranslator` comes back in one of two shapes:
+ * the whole record (`_id`, `_type`, `_data`), or — under an inclusion
+ * projection — one column per projected field. Both shapes are turned back
+ * into a record object here, so every reader of the store (the DatabaseDO's
+ * query/get paths, the per-document SQLite projection) hands callers the same
+ * values for the same stored record.
+ */
+/**
+ * Column-alias prefix for a projected field whose value is selected as JSON
+ * text. The prefix marks the column as still-encoded so
+ * {@link parseRecordRow} knows to decode it; field names cannot start with
+ * `_` (the write path rejects them as reserved), so the prefix can never
+ * collide with a real field.
+ */
+declare const PROJECTED_JSON_ALIAS_PREFIX = "_json_";
+/** Column alias under which a projected field's JSON text is selected. */
+declare function projectedJsonAlias(fieldName: string): string;
+/**
+ * Decode one row of a `records` SELECT into a record object: `_id`/`_type`
+ * become `id`/`type`, `_data` is parsed when present, and any projected
+ * column is decoded back to its stored value.
+ */
+declare function parseRecordRow(row: Record<string, any>): Record<string, any>;
+
 /**
  * Cloudflare Worker Router Template
  *
@@ -1558,6 +2177,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).
  */
@@ -1677,6 +2307,176 @@ declare class DocumentQueryTranslator {
     private buildDocumentClause;
 }
 
+interface RegisteredModelInfo {
+    class: typeof BaseModel;
+    options: ModelOptions;
+    fields: Map<string, FieldOptions>;
+}
+declare class ModelRegistry {
+    private static instance;
+    private models;
+    private modelOptions;
+    private activeSessionModels;
+    private dbEngine;
+    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;
+    getModelInfo(modelName: string): RegisteredModelInfo | undefined;
+    getAllRegisteredModelsInfo(): RegisteredModelInfo[];
+    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, 
+    /** #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;
+    clearSessionState(): void;
+    getActiveModels(): Map<string, typeof BaseModel>;
+    private validateSessionModels;
+}
+
+/**
+ * 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;
@@ -1721,19 +2521,59 @@ declare enum LogLevel {
 }
 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;
@@ -1750,6 +2590,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;
@@ -1799,10 +2686,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;
@@ -1837,9 +2738,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
@@ -1919,6 +2899,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;
@@ -1937,14 +2938,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
      */
@@ -2067,4 +3068,185 @@ declare function deterministicIdentifierHash(value: string): string;
  */
 declare function buildSafeAlias(prefix: string, rawDescriptor: string): string;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, buildSafeAlias, checkAutoStampsReservedFields, checkReservedFieldName, clearMetaSyncCache, createDatabaseDO, createDocumentDO, deterministicIdentifierHash, discoverModelNames, discoverSchema, handleRequest, inferFieldType, loadSchemaFromTomlString, registerFunctionDefault, schemaToToml, syncInferredMeta, syncModelMeta };
+/**
+ * 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;
+}
+/** 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;
+}
+/**
+ * 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;
+    };
+}
+/** A chunk's bytes and the manifest entry that describes them. */
+interface EncodedSnapshotChunk {
+    body: Uint8Array;
+    entry: SnapshotChunkEntry;
+}
+/** A chunk that is not the one its manifest entry describes. */
+declare class SnapshotChunkIntegrityError extends Error {
+    readonly key: string;
+    constructor(key: string, reason: string);
+}
+/** A record that cannot be written as one ndjson line. */
+declare class SnapshotRowFormatError extends Error {
+    constructor(model: string, id: string);
+}
+/**
+ * Fields a model declares as stringsets, out of the manifest's schema (D5).
+ *
+ * The manifest carries the schema so a chunk can be materialized before any
+ * document has been discovered from — which is what lets a cold client, and a
+ * server installing an imported artifact, create a model's tables without
+ * replaying anything.
+ */
+declare function snapshotStringSetFields(manifest: Pick<SnapshotManifest, "schema">, model: string): Set<string>;
+/**
+ * What a model declares, out of the manifest's schema (D5).
+ *
+ * A chain carries only what its epochs changed, so for a model no overlay in
+ * it touched the manifest is the ONLY record of what that model declares —
+ * its stringset fields, but also its unique constraints and its query indexes,
+ * which the document installing the chain has to rebuild as the rows land.
+ */
+declare function snapshotDeclaredSchema(manifest: Pick<SnapshotManifest, "schema">, model: string): {
+    stringSetFields: string[];
+    uniqueConstraints: Array<{
+        name: string;
+        fields: string[];
+    }>;
+    indexedFields: Array<{
+        field: string;
+        type: string;
+        unique: boolean;
+    }>;
+    /**
+     * The model's declaration verbatim, when the exporting document had one.
+     *
+     * The three lists are what the STORE acts on; this is what a WRITE acts on
+     * (coercion, defaults, required fields, the contract a strict write is
+     * checked against). An imported document's overlays carry `_meta_` only for
+     * the epochs that changed it, so for every other model this is the only
+     * record of what it declares (#2816).
+     */
+    declaration?: {
+        fields: Record<string, any>;
+        constraints: Record<string, any>;
+    };
+};
+/**
+ * One snapshot row as an overlay entry that REPLACES whatever is there.
+ *
+ * A snapshot row is the whole record, not a patch, so it carries `_replace` —
+ * which is also what clears any stringset members a half-loaded earlier
+ * attempt left behind. Shared by the client's cold load and the server's
+ * install of an imported chain: a row must not come to mean two things.
+ */
+declare function snapshotRowAsOverlayEntry(id: string, data: Record<string, any>, stringSetFields: ReadonlySet<string>): SnapshotOverlayEntry;
+/**
+ * The shape {@link snapshotRowAsOverlayEntry} produces — structurally the
+ * `OverlayRecordEntry` of `largeDocuments.ts`, restated here so the chunk
+ * format does not depend on the overlay module.
+ */
+interface SnapshotOverlayEntry {
+    id: string;
+    fields: Record<string, unknown>;
+    stringSets: Record<string, Record<string, boolean>>;
+    replace: boolean;
+    deleted: boolean;
+}
+/** The uncompressed ndjson body of a chunk. Exported for the loader's tests. */
+declare function snapshotChunkLines(rows: readonly SnapshotRow[]): string;
+/**
+ * Encode one chunk: the rows as gzip ndjson, plus the entry that describes it.
+ *
+ * The digest covers the STORED bytes so a loader can check what it downloaded
+ * without decompressing it first — a corrupted chunk is refused before it can
+ * cost the client the memory of inflating it.
+ */
+declare function encodeSnapshotChunk(input: {
+    key: string;
+    model: string;
+    rows: readonly SnapshotRow[];
+}): Promise<EncodedSnapshotChunk>;
+/**
+ * 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[]>;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, DEFAULT_OVERLAY_TABLES, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type EncodedSnapshotChunk, type Env, type ErrorResponse, Format2CompositeFieldError, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, OVERLAY_KEY_SEPARATOR, OVERLAY_MARKER_DELETED, OVERLAY_MARKER_REPLACE, type OverlayMutation, type OverlayRecordEntry, type OverlaySql, type OverlayTables, PROJECTED_JSON_ALIAS_PREFIX, type ParsedOverlayKey, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SnapshotChunkEntry, SnapshotChunkIntegrityError, type SnapshotManifest, type SnapshotOverlayEntry, type SnapshotRow, SnapshotRowFormatError, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, applyOverlayMutation, assertNoFormat2CompositeFields, buildSafeAlias, checkAutoStampsReservedFields, checkReservedFieldName, clearMetaSyncCache, completeOverlayEntries, createDatabaseDO, createDocumentDO, decodeOverlaySegment, deterministicIdentifierHash, discoverDeclaredModel, discoverModelNames, discoverSchema, encodeOverlayMutation, encodeOverlaySegment, encodeSnapshotChunk, format2StringSetMembers, groupOverlayEntries, handleRequest, inferFieldType, isFormat2StringSetYMap, loadSchemaFromTomlString, materializeOverlayRecord, overlayFieldKey, overlayMarkerKey, overlayMemberKey, parseOverlayKey, parseRecordRow, projectOverlayEntry, projectedJsonAlias, readOverlayRecord, readSnapshotChunk, registerFunctionDefault, schemaToToml, snapshotChunkLines, snapshotDeclaredSchema, snapshotRowAsOverlayEntry, snapshotStringSetFields, syncInferredMeta, syncModelMeta };