js-bao 0.5.2 → 0.6.0

package/dist/client.d.cts

@@ -75,6 +75,357 @@ 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}.
+ */
+
+/** 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;
+}
+/** 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>>;
+}
+
+/**
+ * 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>>;
+}
+
+/**
+ * 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 +481,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>;
 }
 
@@ -321,6 +698,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$1 {
     field: string;
     contains: string;
@@ -365,19 +912,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;
@@ -394,6 +981,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;
@@ -443,10 +1077,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;
@@ -481,9 +1129,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$1): 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
@@ -602,14 +1329,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
      */