js-bao-wss-client 2.2.0-alpha.0 → 2.2.0-alpha.2

package/dist/JsBaoClient.d.ts

@@ -1,6 +1,6 @@
 import { Observable } from "lib0/observable";
 import * as Y from "yjs";
-import { DatabaseConfig } from "js-bao";
+import { initJsBao, DatabaseConfig } from "js-bao";
 import type { DiscoveredSchema } from "js-bao";
 import type { TypedModelConstructor } from "./types/typed-model-constructor";
 import { LogLevel } from "./internal/logger";
@@ -11,6 +11,7 @@ import { type AnalyticsEventInput } from "./internal/analyticsQueue";
 import { type GoogleClientsConfig } from "./internal/authController";
 import { type RequestOptions } from "./internal/httpClient";
 import { type DocumentPermission as DocumentAccessLevel, type LocalDocumentEntry, type LocalMetadataEntry, type DocumentDebugSnapshot } from "./internal/documentManager";
+import { type OfflineReplayNotice } from "js-bao";
 import { DocumentsAPI, DocumentContext, type DocumentInfo, type ResolveAliasParams, type CreateDocumentOptions } from "./api/documentsApi";
 import { type CacheFacade } from "./api/cacheFacade";
 import { MeAPI } from "./api/meApi";
@@ -22,6 +23,7 @@ import { DatabasesAPI } from "./api/databasesApi";
 import { GroupsAPI } from "./api/groupsApi";
 import { CronTriggersAPI } from "./api/cronTriggersApi";
 import { LocksAPI } from "./api/locksApi";
+import { FunctionsAPI } from "./api/functionsApi";
 import { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 import { RuleSetsAPI } from "./api/ruleSetsApi";
 import { BlobBucketsAPI } from "./api/blobBucketsApi";
@@ -91,6 +93,7 @@ export type { DocumentDebugSnapshot, DocumentPermission, LocalDocumentEntry, Loc
 export type { LogLevel } from "./internal/logger";
 export type { RequestOptions } from "./internal/httpClient";
 export type { LocksAPI } from "./api/locksApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, } from "./api/functionsApi";
 export type { LockHandle, LockContention, AcquireResponse, AcquireOptions, BlockingAcquireOptions, ReleaseResult, RenewResult, LockStatus, LockListEntry, LockListResult, } from "./api/locksApi";
 export type { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 export type { ResourceMetadataReadResult, ResourceMetadataWriteResult, ResourceMetadataBatchRequestItem, ResourceMetadataBatchParams, ResourceMetadataBatchCategoryResult, ResourceMetadataBatchResourceResult, ResourceMetadataBatchResult, ResourceMetadataListEntry, ResourceMetadataListResult, ResourceMetadataDeleteResult, ResourceMetadataResolveParams, ResourceMetadataResolveResult, } from "./api/resourceMetadataApi";
@@ -410,6 +413,27 @@ export interface JsBaoClientOptions {
         enabled?: boolean;
     };
     databaseConfig?: DatabaseConfig;
+    /**
+     * What this device may keep of a large document.
+     *
+     * Loading a large document materializes its records into local storage. On a
+     * platform whose quota will not take the whole document, `models` names the
+     * ones worth the space — the rest are left unloaded, and the models named
+     * are queryable as usual. With none configured, a device short of space is
+     * refused with a typed error rather than loaded arbitrarily, and a platform
+     * with no durable storage at all is always refused.
+     *
+     * `capability` overrides the platform probe, for a host that owns its own
+     * store and knows what it can hold.
+     */
+    largeDocumentStorage?: {
+        capability?: {
+            persistent: boolean;
+            quotaBytes: number | null;
+            usedBytes?: number;
+        };
+        models?: string[];
+    };
     storageConfig?: StorageConfig;
     /**
      * Custom Yjs persistence factory for document storage.
@@ -488,6 +512,21 @@ export interface DocumentSyncStateChangedEvent {
     documentId: string;
     state: "syncing" | "synced" | "stale" | "error";
 }
+/**
+ * Payload of the `documentOfflineWritesResolved` event
+ * (`client.on("documentOfflineWritesResolved", ...)`).
+ *
+ * Fired when a large document that was away replays what it wrote offline and
+ * some of it did not simply apply: a write the online side clearly beat is
+ * DROPPED, and one whose order cannot be established is applied but reported.
+ * Silence means every offline write replayed cleanly.
+ */
+export interface DocumentOfflineWritesResolvedEvent {
+    documentId: string;
+    /** The epoch the writes were replayed onto. */
+    epoch: number;
+    notices: OfflineReplayNotice[];
+}
 /**
  * Options for `client.syncMetadata()`. Controls whether the sync covers all
  * of the user's document metadata or a single document (`scope` /
@@ -1481,6 +1520,35 @@ export interface EvictAllLocalOptions {
  * handler)`: the handler's argument type is `JsBaoEvents[name]`. See each
  * payload interface for when its event fires.
  */
+/**
+ * How a large document's base snapshot load is going.
+ *
+ * A cold open of a large document streams a base of up to gigabytes before the
+ * document is usable, which can take minutes. An app with nothing to show for
+ * that is indistinguishable from one that has hung, so the load reports itself:
+ * `started` once the manifest is in hand (which is where `totalRows` comes
+ * from, so a progress bar exists before the first chunk lands), `progress` per
+ * chunk, `model` as each model becomes queryable, and `loaded` at the end.
+ */
+export interface DocumentSnapshotLoadEvent {
+    documentId: string;
+    phase: "started" | "progress" | "model" | "loaded";
+    /** The epoch the snapshot is a base for. */
+    epoch: number;
+    rows: number;
+    totalRows: number;
+    chunks: number;
+    totalChunks: number;
+    /** The model the event concerns, when it concerns one. */
+    model?: string;
+}
+/**
+ * Every event the client emits, mapped to the payload its listener receives.
+ *
+ * `client.on(name, handler)` is typed from this map, so the handler's argument
+ * is the payload type listed here — pick the event you want and follow the
+ * link to see what it carries.
+ */
 export interface JsBaoEvents {
     error: {
         error: unknown;
@@ -1516,9 +1584,11 @@ export interface JsBaoEvents {
     documentOpened: DocumentEvent;
     documentMetadataChanged: DocumentMetadataChangedEvent;
     documentSyncStateChanged: DocumentSyncStateChangedEvent;
+    documentOfflineWritesResolved: DocumentOfflineWritesResolvedEvent;
     permission: PermissionEvent;
     sync: SyncEvent;
     awareness: AwarenessEvent;
+    "document:snapshot-load": DocumentSnapshotLoadEvent;
     "blobs:upload-progress": BlobUploadProgressEvent;
     "blobs:upload-completed": BlobUploadCompletedEvent;
     "blobs:upload-failed": BlobUploadFailedEvent;
@@ -1703,9 +1773,162 @@ export declare class JsBaoClient extends Observable<any> {
     private jwtPersistenceCleared;
     private docOpensInFlight;
     private dbReady;
+    /**
+     * This client's own js-bao instance (#3039), destroyed with the client.
+     *
+     * Was impossible while `initJsBao` memoized one process-wide instance:
+     * tearing it down would have taken every other client's engine with it.
+     */
+    private jsBaoInstance;
     private jsBaoConnectDoc;
     private jsBaoDisconnectDoc;
     private jsBaoIsDocumentConnected;
+    /**
+     * #2816, behavior 9 — the ORM side of format-2's durable acknowledgement:
+     * the sequences a document's local writes have reached, and the prune the
+     * server's `update.ack` authorizes. `null` on a legacy document.
+     */
+    private jsBaoFormat2SyncMarks;
+    private jsBaoFormat2Acknowledge;
+    /**
+     * #2816 — the epoch a document's own RECORD DATABASE says it follows,
+     * readable before the ORM binds the document. `0` when that database holds
+     * no document whatever the client's metadata claims; `null` when the engine
+     * cannot be asked, which is not evidence either way.
+     */
+    private jsBaoFormat2StoredEpoch;
+    private jsBaoFormat2NoteEpoch;
+    /**
+     * #2816, behavior 18 — record that a document was in touch with the server,
+     * and the offline window the server reported. Past that window without a
+     * sync the ORM refuses local writes and keeps serving reads.
+     */
+    private jsBaoFormat2NoteSync;
+    /**
+     * #2816, behavior 18 — record the offline window the handshake reported,
+     * without claiming a sync. The number is the server's whatever else the
+     * frame says; the mark it is measured from has to be earned.
+     */
+    private jsBaoFormat2NoteWindow;
+    /**
+     * #2816 — resolves once a large document's derived query tables have caught
+     * up with its merged view. Awaited before an update from the room counts as
+     * applied, so `find()` and `query()` never answer from different epochs.
+     */
+    private jsBaoWhenFormat2ProjectionSettled;
+    private jsBaoFormat2NoteClockOffset;
+    private jsBaoFormat2ForgetPendingOps;
+    /**
+     * #2816, behavior 17 — rewrite the pending ops a replay resolution narrowed.
+     * A write that survived only in part must be recorded as the surviving part,
+     * or the restore path would put the whole one back after a crash.
+     */
+    private jsBaoFormat2NarrowPendingOps;
+    /**
+     * What the sealed overlays of a catch-up said was written online, per
+     * document (#2816, behavior 17). Built while the chain is applied — those
+     * artifacts are the online side of every conflict — and consumed by the move
+     * that replays this client's offline writes onto the epoch it landed on.
+     */
+    /**
+     * A returning client's replay, held until the epoch it joined has synced
+     * (#2816, behavior 17). Keyed by document; the timer is the fallback for a
+     * sync that never completes.
+     */
+    private readonly format2PendingReplays;
+    /**
+     * The last `epoch.info` this client acted on, per document — what a rebuild
+     * started outside the handshake needs to plan itself (#2816).
+     */
+    private readonly format2LastHandshakes;
+    private readonly format2ConflictLedgers;
+    /**
+     * Documents already being rebuilt because an offline delete lost (#2816,
+     * behavior 17).
+     *
+     * The rebuild replays the same resolution when it lands, and it would reach
+     * the same conclusion — so without this the document would ask to be rebuilt
+     * out of the rebuild, forever. Cleared once the move it was rebuilt for has
+     * gone through.
+     */
+    private readonly format2RebuildingForDrop;
+    /**
+     * The last sync note per document, kept in memory for the same reason the
+     * epoch mark is: `epoch.info` arrives before the ORM binds the document, so
+     * there is no record store to write it into yet. It is written through the
+     * first time one exists.
+     */
+    private readonly format2SyncNotes;
+    /**
+     * #2816, behavior 10 — what a client owes the next epoch, and the mark it
+     * moves once that epoch's overlay is installed.
+     */
+    private jsBaoFormat2PendingOps;
+    private jsBaoFormat2SetEpoch;
+    private jsBaoFormat2RebindEpochDocument;
+    /**
+     * Folds one sealed epoch's archived overlay into the document's merged view
+     * — the step a client behind by whole epochs repeats per archive to catch up
+     * (#2816, behavior 12).
+     */
+    private jsBaoFormat2ApplySealedOverlay;
+    /**
+     * Throws away a merged view whose sealed-overlay chain was refused, so a
+     * base snapshot can be loaded over nothing rather than over the state of an
+     * epoch the room has left behind (#2816, behavior 12).
+     */
+    private jsBaoFormat2DiscardMergedView;
+    /**
+     * Folds the open epoch's overlay into the merged view again — the step that
+     * finishes a cold load, because a base snapshot's rows REPLACE whatever the
+     * open epoch had already contributed through the ordinary sync (#2816,
+     * behavior 15).
+     */
+    private jsBaoFormat2RefoldOverlay;
+    /**
+     * Materializes a base snapshot into the document's merged view — how a
+     * client with no local state opens a document that has rotated (#2816,
+     * behavior 15).
+     */
+    private jsBaoFormat2LoadSnapshot;
+    /**
+     * Runs an epoch move with the document's local writes held back: a write
+     * that lands on the sealed overlay after what is owed has been read off it
+     * goes down with that document (#2816, behavior 10).
+     */
+    private jsBaoFormat2HoldWrites;
+    /** Documents currently moving to a new epoch, so a repeat notice waits. */
+    private readonly format2Rotations;
+    /**
+     * The freshest artifact grants each large document has been given (#2816).
+     *
+     * A grant lives an hour and a base snapshot can take longer, so a load that
+     * outlives its signatures asks for new ones and keeps going; this is where
+     * the answer lands.
+     */
+    private readonly format2Grants;
+    /** Reads parked on a grant refresh, woken by the room's answer. */
+    private readonly format2GrantWaiters;
+    /**
+     * The epoch each large document's connection reported. `epoch.info` arrives
+     * during the handshake, before the ORM has built the record store that holds
+     * the mark durably, so the transport remembers it until then.
+     */
+    private readonly format2EpochMarks;
+    /**
+     * Large documents that learned they are behind before the ORM had bound
+     * them: the catch-up needs the merged view, so it is owed here and runs at
+     * the bind. They stay silent until it has (#2816, behavior 12).
+     */
+    private readonly format2OwedCatchUps;
+    /**
+     * Large documents stopped on a superseded epoch: their overlay belongs to an
+     * epoch the room has left behind, so nothing of their local state may be
+     * sent. See `format2RequireReload`.
+     */
+    private readonly format2StaleEpochs;
+    /** Outbound sequences per large document: queued, sent, acknowledged. */
+    private readonly format2Ack;
     private jsBaoAddDocumentModelMapping;
     private jsBaoRemoveDocumentModelMapping;
     private readonly localUpdateOrigin;
@@ -1794,6 +2017,11 @@ export declare class JsBaoClient extends Observable<any> {
     /** Sub-API for the named lock API (acquire/release/renew/status/list).
      * @group Sub-APIs */
     locks: LocksAPI;
+    /**
+     * Server functions, available as `client.functions`. Invokes code an app's
+     * team authored and pushed with `primitive config push`.
+     */
+    functions: FunctionsAPI;
     /** Sub-API for reading and writing typed resource metadata (single + batch).
      * @group Sub-APIs */
     resourceMetadata: ResourceMetadataAPI;
@@ -2039,6 +2267,14 @@ export declare class JsBaoClient extends Observable<any> {
     /** Get the global admin app ID.
      * @group Configuration */
     getGlobalAdminAppId(): string;
+    /**
+     * Build this client's js-bao instance.
+     *
+     * A seam, not an extension point: the constructor starts initialization
+     * without awaiting it, so the destroy/init race has no other place a test
+     * can hold the instance back from.
+     */
+    protected createJsBaoInstance(options: Parameters<typeof initJsBao>[0]): Promise<Awaited<ReturnType<typeof initJsBao>>>;
     private initializeJsBao;
     private _syncKvUserId;
     private getAuthPersistenceContext;
@@ -2327,6 +2563,332 @@ export declare class JsBaoClient extends Observable<any> {
      * background refresh or an interactive sign-in takes.
      */
     private handleWsAuthChallenge;
+    /**
+     * A large document's write is durable (#2816, behavior 9).
+     *
+     * The server sends this only after the update-log row and the inline
+     * projection committed together, so this is the one event that may prune
+     * `_pending_ops` — and the one that may report the document as having
+     * nothing unsynced left.
+     */
+    private handleUpdateAck;
+    /**
+     * Move a large document onto the epoch that replaced the sealed one
+     * (#2816, behavior 10).
+     *
+     * Serialized per document: a seal is broadcast to every connection, and a
+     * late frame can draw an `epoch.resync` on top of it, so the same move can
+     * be asked for more than once. Running them concurrently would race two
+     * swaps of the same document's overlay.
+     *
+     * A client that cannot follow — it missed whole epochs, so its merged view
+     * is behind by sealed overlays it never applied — is STOPPED rather than
+     * resynced: see `format2RequireReload`.
+     */
+    private followEpochSeal;
+    /**
+     * The epoch a large document is on (#2816, behavior 10).
+     *
+     * The record store is the durable home of the mark, but it is built when the
+     * ORM binds the document — after `epoch.info` has already been and gone. The
+     * document's persisted metadata carries the same mark and IS loaded before
+     * the handshake, so it answers in between; without it a restarted client
+     * would read the connection's own report back as its current epoch and
+     * conclude it was up to date whatever epoch its overlay really belongs to.
+     * Whichever source answered is written through to the store the first time
+     * one exists.
+     */
+    /**
+     * Check a large document's epoch mark against its records, before the open
+     * believes either (#2816).
+     *
+     * The mark is in the client's document metadata; the document is in the
+     * record database. Those are two stores, and they can part company — an
+     * in-memory merged view that a reload emptied, a database file replaced or
+     * evicted, a store the app rebuilt. When the record database says it follows
+     * no epoch, the mark is a claim with nothing behind it: left in place, this
+     * client opens an empty document, reports itself current, and plans its next
+     * save as a create that replaces a record the server still holds. Dropped,
+     * it is simply a client with nothing local, and rebuilds from a base.
+     *
+     * Returns what the record database said, for the local-copy decision:
+     * `null` means it could not be asked, which is not evidence either way.
+     */
+    private format2ReconcileEpochMark;
+    private format2Epoch;
+    /**
+     * The epoch this client believes a document is on, for the BIND (#2816).
+     *
+     * The record store is created following epoch 0, and 0 is what "this
+     * database holds no document" means to the open path — so the store has to
+     * be told at the moment it is made, from what the client already knows: its
+     * own durable mark, and the epoch a connection reported and this client
+     * accepted (a client that is BEHIND notes nothing, so it cannot claim the
+     * room's epoch here before the overlays it missed have landed).
+     *
+     * `undefined` when it knows of none, which leaves the store saying so.
+     */
+    private format2KnownEpoch;
+    /**
+     * Catch a large document up on the sealed overlays it missed (#2816,
+     * behavior 12).
+     *
+     * A client that was away while the room rotated is behind by whole epochs.
+     * It does not need the document back: the sealed overlays between the epoch
+     * it holds and the one the room is on ARE the changes it missed, so applying
+     * them in order — each bounded by the rotation threshold — brings its merged
+     * view to the server's `records` state with no base on the wire.
+     *
+     * Serialized with the epoch moves for the same document: a seal arriving
+     * mid-catch-up would otherwise swap the overlay underneath it.
+     *
+     * Returns `ok` when the document is on the room's epoch afterwards. When it
+     * is not, `refused` says whether the CHAIN was the problem — a hole, a
+     * discontinuity, or an archive retention pruned — as opposed to a download
+     * that merely failed. Only the first is worth rebuilding from a base for;
+     * the second is worth retrying.
+     */
+    private format2CatchUp;
+    /**
+     * Move this document onto `epoch` (#2816, behaviors 10/12).
+     *
+     * Installs a fresh overlay for that epoch carrying whatever is still
+     * unacknowledged, and resyncs on it. Only ever called once the document's
+     * merged view is the room's state again — after a chain has landed or a base
+     * has been rebuilt — so the jump is no longer a jump over anything unknown.
+     */
+    private format2MoveOnto;
+    /**
+     * Hold a returning client's replay until the epoch it joined has synced
+     * (#2816, behavior 17).
+     *
+     * The sync itself is the trigger — `syncComplete` is the room saying this
+     * document now holds the epoch — but a sync that never completes must not
+     * strand what this client owes: the timer states the writes anyway, which is
+     * the plain offline-wins fallback the spec keeps for evidence that cannot be
+     * had. Either way the writes are durable in `_pending_ops` the whole time.
+     */
+    private format2HoldReplay;
+    /** Forget a held replay's timer, without running it. */
+    private format2ClearHeldReplay;
+    /**
+     * State a returning client's owed writes on the epoch it joined, now that
+     * the epoch's own content is here (#2816, behavior 17).
+     *
+     * The order is the behavior: what the open epoch holds is noted as conflict
+     * evidence FIRST, so the resolution the replay runs sees the whole online
+     * side — the sealed overlays the catch-up applied and the epoch it landed
+     * on. Only then is the same dropped-delete question asked of it: a delete
+     * this epoch's writes beat leaves a record whose other fields live only in a
+     * base, so that document is rebuilt rather than settled on a row it cannot
+     * state.
+     */
+    private format2SettlePendingReplay;
+    /**
+     * The sealed-epoch chain `epoch.info` described, parsed once.
+     *
+     * The frame is untrusted input, so an entry without a whole epoch number is
+     * dropped rather than turned into `NaN` — a hole in the chain is refused by
+     * the planner, which is the safe outcome; a `NaN` link would not be.
+     */
+    private format2SealedChain;
+    /**
+     * Open a large document the client has no local state for (#2816,
+     * behavior 15).
+     *
+     * A fresh client is not behind — it holds no overlay at all — but on a
+     * document that has rotated, the epoch it would join carries only the recent
+     * changes. So it rebuilds a base first: the latest snapshot when the room
+     * offered one, or the sealed overlays from the first epoch while no build
+     * has completed yet. Either way the sealed overlays after that base are
+     * applied on top, and the move onto the room's epoch resyncs the current
+     * one — so the merged view ends up as the server's `records` table.
+     *
+     * Returns `ok: false` when the document cannot be rebuilt, which stops it
+     * rather than opening a document with holes in it.
+     */
+    private format2ColdStart;
+    /**
+     * Rebuild a large document whose sealed-overlay chain was refused (#2816,
+     * behavior 12's close-out).
+     *
+     * A hole in the chain, an epoch declaring a discontinuous base, or an
+     * archive retention has pruned all mean the same thing: nothing available
+     * turns this client's rows into the room's current state. It is therefore in
+     * the position of a client with no local state — so it plans as one, and
+     * discards the view it cannot repair before loading the base over it. Before
+     * a snapshot loader existed this was a dead stop; it is now a reload.
+     */
+    private format2RebuildFromBase;
+    /** How this document should be rebuilt, from the epoch it counts as holding. */
+    private format2PlanRebuild;
+    /** Run a rebuild plan against this document. */
+    private format2RunRebuild;
+    /**
+     * Fold the open epoch's overlay over the base a cold load just installed
+     * (#2816, behavior 15).
+     *
+     * The open epoch is the part of the document the rebuild does not carry: it
+     * arrives as an ordinary Y.Doc sync, on no schedule relative to the load,
+     * and every snapshot row REPLACES what the merged view held for its record.
+     * So a record patched or deleted in the open epoch comes back as the base's
+     * older row unless the overlay is folded once more at the end — which is
+     * idempotent, an overlay entry being state rather than an operation.
+     */
+    private format2RefoldOverlay;
+    /**
+     * Throw away a merged view a refused chain left beyond repair.
+     *
+     * The rows belong to an epoch the room has left behind, and the base about
+     * to be loaded over them is a set of rows rather than a diff — every record
+     * deleted since would otherwise survive the reload.
+     */
+    private format2DiscardMergedView;
+    /**
+     * Materialize the base snapshot the handshake offered into this document's
+     * merged view (#2816, behavior 15).
+     */
+    private format2LoadSnapshot;
+    /**
+     * Read a snapshot build through the ONE grant the handshake minted for it.
+     *
+     * `{path}` is the manifest and `{path}/{model}/{n}` is a chunk of the same
+     * build (behavior 14). The client never learns an R2 key: it knows a signed
+     * path and, from the manifest, which chunks that build holds.
+     */
+    private format2SnapshotSource;
+    /**
+     * Read one sealed epoch's archived overlay.
+     *
+     * The handshake hands out an origin-relative path carrying an expiring
+     * signature for exactly that artifact (behavior 14) — the room is a Durable
+     * Object and has no reliable idea which host this client reached it through,
+     * while this client knows exactly. No key, and no other credential: the
+     * signature IS the authorization.
+     */
+    private format2FetchArchive;
+    /**
+     * Ask the room for fresh artifact grants, mid-load (#2816).
+     *
+     * The reply is deliberately not an `epoch.info`: that frame is the
+     * handshake, and answering one would re-run the cold-start/catch-up decision
+     * on a document that is in the middle of being rebuilt. This asks for
+     * signatures and nothing else.
+     *
+     * Resolves with what arrived, or `null` when nothing did within the window —
+     * the caller then repeats its read with the grant it already had, which
+     * fails and is reported, rather than waiting on a socket that may be gone.
+     */
+    private format2RefreshGrants;
+    /**
+     * Stop a large document whose overlay belongs to an epoch the room has left
+     * behind (#2816, behavior 10).
+     *
+     * Everything this client could send from here is stale: its overlay holds
+     * epoch-E state the room archived, folded into `records`, and has since
+     * written past. A state-complete sync of it would not fill a gap — it would
+     * overwrite newer authoritative values with older ones, and re-create rows
+     * that were deleted epochs ago. So the document stops syncing and stops
+     * pushing, keeps answering reads from its merged view, and says so with a
+     * typed error. Applying the sealed overlays in between is the fast-forward
+     * path (behavior 12); reloading from a snapshot is Phase 4. Until one of
+     * those exists this is a hard stop, exactly as the plan specifies.
+     */
+    private format2RequireReload;
+    /**
+     * Record that a large document is in touch with the server (#2816,
+     * behavior 18).
+     *
+     * Kept in memory as well as written through, because `epoch.info` — where
+     * the window is reported — arrives before the ORM binds the document and
+     * therefore before there is a record store to persist it into. The note is
+     * flushed at the bind, exactly as the epoch mark is.
+     */
+    private format2NoteSync;
+    /**
+     * Wait for a large document's derived query tables to catch up with its
+     * merged view (#2816).
+     *
+     * Only for format-2 documents: a legacy document has neither a merged view
+     * nor a projection queue, and its update path is unchanged. A failure to
+     * settle is the ORM's to report — it has already logged and withdrawn the
+     * projection mark — and must not turn an applied update into an error here.
+     */
+    private format2SettleProjection;
+    /**
+     * Record the offline window the room reported, without claiming a sync
+     * (#2816, behavior 18).
+     *
+     * `epoch.info` carries the window to every client that reaches the room,
+     * including one that is behind by whole epochs — and that client's merged
+     * view is NOT the room's state until its catch-up has run. Taking the mark
+     * here would hand a document past its window its writes back on the strength
+     * of a handshake whose catch-up then failed: it would go on recording
+     * durable pending ops against a past nothing can reconcile them with. So the
+     * number is taken and the mark is left to be earned, by a catch-up that
+     * lands or by a document that was current all along.
+     */
+    private format2NoteWindow;
+    /**
+     * Measure this client's clock against the room's, and remember when each
+     * sealed epoch ended (#2816, behavior 17).
+     *
+     * Both come off `epoch.info`, and both are needed later than it: the offset
+     * stamps every local write, and the seal times bound the epochs a replay
+     * compares an offline write with.
+     */
+    private format2NoteClock;
+    /**
+     * Resolve what a returning client still owes against what was written while
+     * it was away (#2816, behavior 17, amended D1).
+     *
+     * Used only where a ledger exists — a catch-up has just folded the sealed
+     * overlays that ARE the online side of every conflict. A write the online
+     * side clearly beat is dropped, forgotten from `_pending_ops` so no later
+     * move carries it, and reported; one whose order cannot be established is
+     * kept and reported. A client that was simply present through a seal has no
+     * ledger and carries everything, exactly as before.
+     */
+    private format2ResolveReplay;
+    /**
+     * Whether joining `epoch` would abandon an offline write this client cannot
+     * take back (#2816, behavior 17).
+     *
+     * Asked BEFORE the move, and answered by running the same resolution the
+     * move will run — it reads nothing and writes nothing, so asking twice costs
+     * only the comparison. The one case is a dropped delete: the record it
+     * removed is not in any artifact this client still holds, so the merged view
+     * has to come from a base again before the delete may be forgotten.
+     *
+     * Answers false once a rebuild for this document is already under way, or
+     * the rebuild would ask to be rebuilt out of itself.
+     */
+    private format2ReplayRequiresRebuild;
+    /**
+     * Write a held note through, once the document's store exists.
+     *
+     * A note with no time is a window this client was told about while it was
+     * still behind: the number lands, the mark does not.
+     */
+    private format2FlushSyncNote;
+    /**
+     * Whether a large document is stopped on a superseded epoch, in which case
+     * nothing of its local state may go out (see `format2RequireReload`).
+     */
+    private format2NeedsReload;
+    /**
+     * Run the catch-up a document owes, now that its merged view exists
+     * (#2816, behavior 12).
+     *
+     * Called at the ORM bind and whenever a connection reports a later epoch on
+     * an already-bound document. A document whose chain is REFUSED — a hole, a
+     * discontinuity, a pruned archive — is rebuilt from the latest base instead
+     * of stopped; only a document that cannot be rebuilt either is stopped and
+     * told to reload.
+     */
+    private format2SettleOwedCatchUp;
+    /** The pieces `followEpoch` moves, wired to this client's owners. */
+    private format2RotationHost;
     private handleWebSocketMessage;
     private handleWebSocketClose;
     private handleWebSocketError;
@@ -2995,6 +3557,20 @@ export declare class JsBaoClient extends Observable<any> {
      * the wire on exactly the sessions where storage was slow or unavailable.
      */
     private _primeLocalOnlyFromLocalMetadata;
+    /**
+     * The format of a document being opened (#2816).
+     *
+     * A large document keeps its records in a persisted merged view and uses its
+     * Y.Doc only as an epoch overlay, so js-bao has to be told at connect time —
+     * an app should not have to carry that. The format is chosen at creation and
+     * never migrated, so a locally cached answer is permanently valid and the
+     * server is only asked when nothing local knows (and the answer is then kept
+     * for the next open, which may be offline).
+     *
+     * `resolveDocumentFormat` never rejects: a document nothing knows about
+     * opens as legacy, exactly as it does today.
+     */
+    private _resolveDocumentFormat;
     private _putMetadataToIdb;
     private _deleteMetadataFromIdb;
     private _enforceRetentionPolicy;