js-bao-wss-client 2.2.0-alpha.10 → 2.2.0-alpha.11

package/README.md

@@ -3052,7 +3052,7 @@ await client.me.update({
   avatarUrl: null,
 });
 
-// Upload avatar image (stored in R2, proxied through the API)
+// Upload avatar image (stored by the platform, proxied through the API)
 const imageBlob = await fetch("/path/to/image.png").then((r) => r.blob());
 const { avatarUrl } = await client.me.uploadAvatar(imageBlob, "image/png");
 console.log("New avatar URL:", avatarUrl);

package/dist/JsBaoClient.d.ts

@@ -7,6 +7,7 @@ import { LogLevel } from "./internal/logger";
 import { type SubscribeOptions } from "./internal/databaseSubscriptions";
 import { type StorageConfig, type YjsPersistenceFactory } from "./internal/storage/index.js";
 import { type WorkflowStatusSlice } from "./internal/workflowSlice";
+import { type WorkflowRunError, type WorkflowRunErrorWire } from "./internal/workflowRunError";
 import { BlobManager } from "./internal/blobManager";
 import { type AnalyticsEventInput } from "./internal/analyticsQueue";
 import { type GoogleClientsConfig } from "./internal/authController";
@@ -57,7 +58,7 @@ export type { ReasoningOptions, LlmChatOptions } from "./api/llmApi";
 export type { AnalyticsEventInput } from "./internal/analyticsQueue";
 export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
 export type { DocumentBlobContext, BlobUploadSourceOptions, BlobUploadResult, BlobListResult, BlobUploadStatus, BlobReadOptions, BlobPrefetchOptions, BlobProxyUrlOptions, BlobDisposition, } from "./internal/blobManager";
-export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI } from "./api/documentsApi";
+export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI, DocumentIngestsAPI, DocumentSnapshotsAPI, } from "./api/documentsApi";
 export type { DatabasesAPI } from "./api/databasesApi";
 export type { CollectionsAPI } from "./api/collectionsApi";
 export type { GeminiAPI } from "./api/geminiApi";
@@ -74,7 +75,7 @@ export type { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 export type { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 export type { CronTriggersAPI } from "./api/cronTriggersApi";
 export type { CronTriggerInfo, CreateCronTriggerParams, UpdateCronTriggerParams, CronTriggerListResult, ObjectStatus, } from "./api/cronTriggersApi";
-export type { CreateDocumentOptions, CreateOfflineOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, } from "./api/documentsApi";
+export type { CreateDocumentOptions, CreateOfflineOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, DocumentIngestSession, DocumentIngestChunkUpload, DocumentIngestChunkUploadResult, DocumentIngestPage, DocumentSnapshotBuild, DocumentSnapshotPage, } from "./api/documentsApi";
 export type { CreateDatabaseParams, UpdateDatabaseParams } from "./api/databasesApi";
 export type { CreateCollectionParams, UpdateCollectionParams, GrantCollectionGroupPermissionParams, ListCollectionsOptions, } from "./api/collectionsApi";
 export type { ListResult } from "./api/listResult";
@@ -94,7 +95,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, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionWaitForResult, } from "./api/functionsApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionWaitForResult, FunctionRun, FunctionRunError, FunctionRunErrorCode, FunctionRunSettled, FunctionRunSlice, FunctionRunStatus, FunctionRunStatusValue, FunctionRunTerminalStatus, FunctionWaitOptions, } 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";
@@ -425,10 +426,14 @@ export interface JsBaoClientOptions {
     /**
      * The local query engine. Default `{ type: "sqljs" }`, in memory. A web app
      * that opens large documents passes `{ type: "opfs", options: { workerURL?,
-     * locateFile? } }`: format-1 documents keep the SQL.js mirror and each large
-     * document gets a worker-hosted store that survives a reload. Needs js-bao
-     * 0.7.0 or newer; with an older js-bao the client throws
-     * `OPFS_ENGINE_UNAVAILABLE`.
+     * brokerURL?, locateFile? } }`: format-1 documents keep the SQL.js mirror
+     * and each large document gets a worker-hosted store that survives a
+     * reload. `brokerURL` points at a small SharedWorker (`js-bao/format2-broker`)
+     * that lets several tabs of the same app share one document's store — one
+     * tab hosts the engine, the others reach it through a port the broker hands
+     * over; without it, a second tab opening the same large document is
+     * refused. Needs js-bao 0.7.0 or newer (0.8.0 for `brokerURL`); with an
+     * older js-bao the client throws `OPFS_ENGINE_UNAVAILABLE`.
      */
     databaseConfig?: DatabaseConfig;
     /**
@@ -518,9 +523,8 @@ export interface SyncEvent {
  * It also fires with `state: "error"` when an open document cannot be kept
  * in sync:
  *
- * - a remote update for it arrives but cannot be applied — when downloading
- *   a large update from R2 is rejected (401/403), which leaves the document
- *   behind the server;
+ * - a remote update for it arrives but cannot be fetched or applied, which
+ *   leaves the document behind the server;
  * - its sync handshake goes unanswered for the whole handshake budget
  *   (`sync.handshakeTimeoutMs`, default 10s), so what the app is rendering
  *   has stopped converging. The client keeps retrying underneath, at a
@@ -1370,7 +1374,20 @@ export type WorkflowStatusValue = "queued" | "running" | "apply_pending" | "appl
 export interface WorkflowStatusResult<O = any> {
     status: WorkflowStatusValue;
     output?: O;
-    error?: string;
+    /**
+     * Why the run failed, exactly as the server sent it.
+     *
+     * An OBJECT for every failed durable run, `null` on a read that has not
+     * failed, and a string on the older form. Branch on {@link failure}
+     * instead — it says the same thing whichever form arrived.
+     */
+    error?: WorkflowRunErrorWire | null;
+    /**
+     * The same error, normalized: `message` always, `name` when the wire carried
+     * one, and any remaining keys under `details`. Additive, and `undefined`
+     * when the run did not fail or the field was not one the client could read.
+     */
+    failure?: WorkflowRunError;
     /** Why the run did not run, when `status === "skipped"`. */
     skipReason?: WorkflowRunSkipReason;
     run?: WorkflowRun;
@@ -1384,6 +1401,7 @@ export interface WorkflowStatusResult<O = any> {
     slice?: WorkflowStatusSlice;
 }
 export type { WorkflowStatusSlice };
+export type { WorkflowRunError, WorkflowRunErrorWire };
 /** Options for claiming a workflow apply */
 export interface ClaimApplyOptions {
     workflowKey: string;
@@ -1513,8 +1531,17 @@ export interface WaitForWorkflowResult {
     status: WaitForWorkflowStatus;
     /** Final output of the run, when available. */
     output?: any;
-    /** Error message when `status === "failed"`. */
-    error?: string;
+    /**
+     * Why the run failed, exactly as it arrived — an object from a status read,
+     * a string from the terminal `workflowStatus` frame.
+     */
+    error?: WorkflowRunErrorWire | null;
+    /**
+     * The same error, normalized. Present on a `failed` result whichever path
+     * settled the wait, so a caller reporting a failure does not have to know
+     * which one did.
+     */
+    failure?: WorkflowRunError;
     /** Why the run did not run, when `status === "skipped"`. */
     skipReason?: WorkflowRunSkipReason;
 }
@@ -1588,6 +1615,19 @@ export interface EvictAllLocalOptions {
 export interface DocumentSnapshotLoadEvent {
     documentId: string;
     phase: "started" | "progress" | "model" | "loaded";
+    /**
+     * What this load IS.
+     *
+     * `"load"` installs a base whole — a cold start, or a rebuild. `"converge"`
+     * replaces only the ranges a bulk load touched and keeps the rest, which is
+     * why it also reports {@link chunksReused}.
+     */
+    mode?: "load" | "converge";
+    /**
+     * Chunks a convergence kept rather than fetched, on the `loaded` phase of a
+     * `"converge"` load. The saving the whole design exists for.
+     */
+    chunksReused?: number;
     /** The epoch the snapshot is a base for. */
     epoch: number;
     rows: number;
@@ -1892,6 +1932,25 @@ export declare class JsBaoClient extends Observable<any> {
     private jsBaoWhenFormat2ProjectionSettled;
     private jsBaoFormat2NoteClockOffset;
     private jsBaoFormat2ForgetPendingOps;
+    /**
+     * #3435, behavior 18 — record durably that this document crossed a bulk
+     * load's discontinuity. A client that followed the flagged seal and then
+     * restarted reads its epoch mark as current, so the convergence it owes has
+     * to be written somewhere that outlives the process.
+     */
+    private jsBaoFormat2NoteDiscontinuity;
+    /** #3435 — the convergence landed: forget what it reconciled. */
+    private jsBaoFormat2ClearDiscontinuities;
+    /**
+     * #3435 — the models this client holds rows of, which is the inventory a
+     * convergence plan decides its whole-model prunes against.
+     */
+    private jsBaoFormat2LocalModels;
+    /**
+     * #3435, behavior 21 — whether each of these records is in the merged view
+     * once a convergence has landed. The fact an owed write is judged against.
+     */
+    private jsBaoFormat2RecordPresence;
     /**
      * #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,
@@ -1971,8 +2030,71 @@ export declare class JsBaoClient extends Observable<any> {
      * goes down with that document (#2816, behavior 10).
      */
     private jsBaoFormat2HoldWrites;
+    /**
+     * Documents whose writes this client is already holding.
+     *
+     * The ORM's hold is a barrier, not a lock a holder may take twice: it waits
+     * for the transition in flight before raising its own, so a hold taken
+     * INSIDE one waits for itself. That is reachable since #3435 — a convergence
+     * holds writes for its whole run and completes the deferred replay within
+     * it, and that replay's own move takes the hold again — so the client tracks
+     * what it is holding and re-enters rather than deadlocking. Re-entering is
+     * the correct answer as well as the safe one: writes are already held.
+     */
+    private readonly format2HeldWrites;
     /** Documents currently moving to a new epoch, so a repeat notice waits. */
     private readonly format2Rotations;
+    /**
+     * Bulk-load epochs each document crossed and has not converged past (#3435),
+     * ascending — the in-memory face of the store's `_discontinuities` table.
+     *
+     * Kept here as well as durably because the decisions that read it run on
+     * frames: a seal, a `snapshot.ready` and a handshake all ask "does this
+     * document owe a convergence?" and none of them may wait on a store that may
+     * not be bound yet.
+     */
+    private readonly format2Discontinuities;
+    /**
+     * The replay a flagged seal deferred, per document (#3435, behavior 18).
+     *
+     * Unlike #2816's held replay this carries NO timer. The ordinary hold
+     * replays what it owes when the sync it waits for never lands, which is the
+     * right fallback for a rotation; here it would publish exactly the writes
+     * the classification exists to drop. It waits for the convergence, however
+     * long that takes, and the writes stay durable in `_pending_ops` meanwhile.
+     */
+    private readonly format2ConvergenceReplays;
+    /**
+     * What a landed convergence found for the owed records (#3435,
+     * behavior 21), set only while the deferred replay is running.
+     *
+     * The replay resolves through `resolveReplay`, which `followEpoch` calls at
+     * completion time rather than at the seal — so this is where the answer the
+     * classification needs, which did not exist when the move was made, is put
+     * within its reach.
+     */
+    private readonly format2IngestReplays;
+    /**
+     * The sequences one convergence's replay has already judged (#3435,
+     * finding 3435-SO-05), held only while it runs.
+     *
+     * Every rotation crossed before the convergence deferred its own copy of
+     * what was owed at the time, and they are replayed in order. The same write
+     * therefore arrives more than once, already settled: it must not be carried
+     * twice, and the application must not hear about it twice.
+     */
+    private readonly format2JudgedReplays;
+    /**
+     * The bulk-load boundary a landed convergence reconciled, and the ranges it
+     * knows the artifact touched (#3435, finding FROZEN-02).
+     *
+     * Kept so the presence question can be asked AGAIN, as late as possible. A
+     * returning client converges on the base, then folds the chain above it,
+     * then moves — and a record the artifact deleted may have been re-created in
+     * one of those archives. An answer taken off the base alone would call it
+     * absent and drop a write that still stands.
+     */
+    private readonly format2ConvergedBoundaries;
     /**
      * The freshest artifact grants each large document has been given (#2816).
      *
@@ -2001,6 +2123,23 @@ export declare class JsBaoClient extends Observable<any> {
      * sent. See `format2RequireReload`.
      */
     private readonly format2StaleEpochs;
+    /**
+     * Large documents whose handshake on THIS connection has not been answered.
+     *
+     * #3435, finding 3435-R05's third door. `sendSyncStep1` flushes a
+     * document's queued local updates before it sends the handshake frame, and
+     * `epoch.info` is where a returning client finds out that a bulk load stands
+     * between what it holds and the room. So a large document that has just sent
+     * its handshake holds those writes: publishing them first would put an owed
+     * write onto the post-ingest epoch before anything could classify it, and
+     * the presence read that classifies it would then be reading this client's
+     * own replay instead of the bulk load's result.
+     *
+     * They are HELD, not dropped — queued in memory and durable in
+     * `_pending_ops`, exactly as the stale-epoch hold beside it leaves them —
+     * and released once the handshake has been answered.
+     */
+    private readonly format2AwaitingHandshake;
     /** Outbound sequences per large document: queued, sent, acknowledged. */
     private readonly format2Ack;
     private jsBaoAddDocumentModelMapping;
@@ -2895,6 +3034,18 @@ export declare class JsBaoClient extends Observable<any> {
      * resynced: see `format2RequireReload`.
      */
     private followEpochSeal;
+    /**
+     * Run `work` in this document's one queue of epoch moves, catch-ups and
+     * convergences (#3435, finding FROZEN-04).
+     *
+     * The queue is what keeps a convergence from replacing rows while a move
+     * rebinds the overlay under it. Reading the promise in flight and only THEN
+     * installing one's own is not a queue: two callers waiting on the same
+     * predecessor both see it settle and both go, and the second overwrites the
+     * first's entry so nothing after them waits for it either. The link is made
+     * here, synchronously, before anything is awaited.
+     */
+    private format2Serialize;
     /**
      * The epoch a large document is on (#2816, behavior 10).
      *
@@ -2967,6 +3118,39 @@ export declare class JsBaoClient extends Observable<any> {
      * has been rebuilt — so the jump is no longer a jump over anything unknown.
      */
     private format2MoveOnto;
+    /**
+     * Record a bulk load's discontinuity, in memory and durably (#3435,
+     * behavior 18).
+     *
+     * Both, because the two answer different questions. The durable row is what
+     * a restarted client reads at its bind; the in-memory list is what the very
+     * next frame on THIS connection reads, before any store has been bound.
+     */
+    private format2NoteDiscontinuity;
+    /**
+     * Run `run` with this document's local writes held back, once.
+     *
+     * The ORM's hold drains what is in flight and then raises a barrier the next
+     * hold waits on, so taking it from inside itself waits forever. Every hold
+     * this client takes goes through here, and one taken while this client is
+     * already holding the same document simply runs: the writes it exists to
+     * exclude are excluded already, by the hold above it.
+     */
+    private format2WithWriteHold;
+    /**
+     * Keep the sequences a deferred carry withheld off every claim (#3435,
+     * finding 3435-SO-06).
+     *
+     * The lowest of them is the floor: the server's acknowledgement mark is
+     * contiguous, so nothing above a withheld sequence can be acknowledged
+     * anyway, and a frame claiming it would only invite the prune this exists to
+     * prevent.
+     */
+    private format2WithholdSequences;
+    /** The withheld writes have been replayed: their sequences may travel. */
+    private format2ReleaseWithheldSequences;
+    /** The highest bulk-load epoch this document has not converged past (#3435). */
+    private format2HighestDiscontinuity;
     /**
      * Hold a returning client's replay until the epoch it joined has synced
      * (#2816, behavior 17).
@@ -3058,6 +3242,114 @@ export declare class JsBaoClient extends Observable<any> {
      * merged view (#2816, behavior 15).
      */
     private format2LoadSnapshot;
+    /**
+     * Run a convergence in the same queue as this document's epoch moves and
+     * catch-ups (#3435, behavior 20).
+     *
+     * A convergence swaps whole ranges of the merged view; a seal arriving
+     * halfway through would rebind the overlay underneath it, and a catch-up
+     * would fold archives into rows that are being replaced. One at a time,
+     * exactly as #2816 serializes the rest.
+     */
+    private format2ScheduleConvergence;
+    /**
+     * Make this document's merged view the ingested table plus every write since
+     * (#3435, behavior 19).
+     *
+     * The order is the behavior:
+     *
+     * 1. the manifest, validated before a chunk moves — a malformed `ingest`
+     *    block leaves the document held rather than half-replaced (edge E5);
+     * 2. the plan, partial only where keeping rows is provably sound;
+     * 3. the load, replacing each fetched chunk's coverage;
+     * 4. the overlays SEALED between the base's epoch and this client's, which
+     *    the replacement just wrote over (finding 3435-R03);
+     * 5. the open epoch's overlay, refolded over the rows that moved;
+     * 6. the pending writes, classified against what is now present, and only
+     *    then published (finding 3435-R05);
+     * 7. the discontinuities, forgotten — this view has converged past them.
+     */
+    private format2Converge;
+    /**
+     * The artifact ranges a PARTIAL convergence may plan against, or `null` for
+     * the full plan (#3435, behavior 19, findings 3435-R04 and R07).
+     *
+     * Four conditions, and the reason any of them failed is logged rather than
+     * left to be inferred from a chunk count:
+     *
+     * - the local base FINISHED loading, so the rows a kept chunk vouches for
+     *   are a complete baseline rather than however far a load got;
+     * - exactly one bulk load was crossed, since only the latest one's ranges
+     *   are in this manifest and nothing names what an earlier one touched;
+     * - the base is that bulk load's OWN build, which its `ingest.epoch` says;
+     * - the chain is applied through E — this client followed the flagged seal,
+     *   so its rows are the pre-ingest table plus every overlay up to the swap.
+     */
+    private format2ConvergencePlanInput;
+    /**
+     * Fold the overlays sealed from `from` through `to` back over the ranges a
+     * convergence replaced (#3435, finding 3435-R03).
+     *
+     * A connected client already holds these writes — it was there when they
+     * were made — but the base it just installed is a torn read cut before some
+     * of them, so the replaced ranges lost them. The archives are the only copy,
+     * and the grants for them are asked for exactly as a returning client's are.
+     */
+    private format2RefoldSealedSince;
+    /** Forget the discontinuities a landed convergence reconciled (#3435). */
+    private format2ClearDiscontinuities;
+    /**
+     * Judge the writes a flagged seal held, now that the ingested ranges are in
+     * (#3435, behavior 21, finding 3435-R05).
+     *
+     * Presence is read HERE, between the refolds and the replay: before the
+     * refolds it would be a statement about a half-replaced view, and after the
+     * replay it would be the client reading back its own writes.
+     *
+     * `touched` decides how far the question reaches. With the artifact's own
+     * ranges in hand only the owed records inside one can have raced the bulk
+     * load, so only those are asked about and everything else follows the
+     * ordinary recency rules. Without them — the full plan, or more than one
+     * boundary crossed — nothing names what moved, so every owed write is asked
+     * about and classified by presence alone (finding 3435-R07).
+     */
+    private format2SettleConvergenceReplay;
+    /**
+     * The owed writes a RESTART left for the convergence to judge (#3435,
+     * finding FROZEN-01).
+     *
+     * The same test the bind made when it kept them off the overlay: this
+     * document's own epoch is already above the bulk load's discontinuity, so
+     * this client followed the flagged seal itself and its unacknowledged
+     * writes were made against the table the load replaced. A client still on a
+     * pre-load epoch is not in this case — its writes are on the overlay it is
+     * bound to and are carried, and judged, by the move it makes next.
+     */
+    private format2RestoredOwed;
+    /**
+     * What a landed convergence found for the records this document still owes
+     * writes on (#3435, behavior 21).
+     *
+     * `touched` decides how far the question reaches. With the artifact's own
+     * ranges in hand only the owed records inside one can have raced the bulk
+     * load, so only those are asked about and everything else follows the
+     * ordinary recency rules. Without them — the full plan, or more than one
+     * boundary crossed — nothing names what moved, so every owed write is asked
+     * about and classified by presence alone (finding 3435-R07).
+     */
+    private format2IngestReplayInput;
+    /**
+     * Ask the presence question again, of the document as it stands now (#3435,
+     * finding FROZEN-02).
+     *
+     * A convergence answers it off the base it has just installed, which is the
+     * earliest moment it can be answered and not the truest one: the chain above
+     * that base is applied afterwards, and a record the artifact deleted can have
+     * been re-created in one of those archives. Re-read immediately before the
+     * replay that uses it, the answer is about the document this client is
+     * actually joining. A no-op where no convergence has landed.
+     */
+    private format2RefreshIngestReplayInput;
     /**
      * Read a snapshot build through the ONE grant the handshake minted for it.
      *
@@ -3185,6 +3477,24 @@ export declare class JsBaoClient extends Observable<any> {
      * nothing of its local state may go out (see `format2RequireReload`).
      */
     private format2NeedsReload;
+    /**
+     * Hold every open large document's queued writes until its own handshake on
+     * this connection has been answered (#3435).
+     *
+     * Every document that could have a queue is covered, not only the ones that
+     * have one now: a write made between the socket opening and the handshake
+     * being answered would otherwise go out on the debounce timer.
+     */
+    private format2HoldWritesUntilHandshake;
+    /**
+     * Let a large document's queued writes go, now that its handshake has been
+     * answered (#3435).
+     *
+     * A document that still owes a catch-up or a convergence is held again the
+     * moment the flush looks, by `format2NeedsReload` — this only lifts the
+     * hold that was about not knowing what the room had to say.
+     */
+    private format2ReleaseHandshakeHold;
     /**
      * Run the catch-up a document owes, now that its merged view exists
      * (#2816, behavior 12).
@@ -3196,6 +3506,62 @@ export declare class JsBaoClient extends Observable<any> {
      * told to reload.
      */
     private format2SettleOwedCatchUp;
+    /**
+     * Take the bulk loads the STORE remembers, at the bind (#3435, behavior 24,
+     * finding 3435-SO-04).
+     *
+     * `_discontinuities` outlives the process; the in-memory list does not, and
+     * the handshake cannot fill it in for a client that followed the flagged
+     * seal itself — that client's epoch mark is the room's own, so the chain's
+     * flagged entry is one it reads as already behind it. Without this, a
+     * restart between the seal and the announcement leaves a document serving
+     * pre-bulk-load rows under a mark that says it is current, for good.
+     *
+     * Raising the debt is what keeps the document silent until it converges; the
+     * entry is the last handshake's, so the chain and the base it names are the
+     * ones the convergence needs.
+     */
+    private format2AdoptDurableDiscontinuities;
+    /**
+     * Record every bulk load that stands between what this client holds and the
+     * room (#3435, behaviors 22 and 23).
+     *
+     * Two sources, neither of which covers the other:
+     *
+     * - the store's own `_discontinuities`, which is all a client that followed
+     *   a flagged seal and then restarted has left — its epoch mark reads as the
+     *   room's current one, so nothing about the handshake says it is behind;
+     * - the handshake's chain, which is how a client that was AWAY when the swap
+     *   happened finds out about it at all.
+     *
+     * A flagged epoch this client is already PAST is not recorded: it converged
+     * on that bulk load's base and cleared its own record of it, and the chain
+     * goes on reporting the epoch as flagged for ever.
+     */
+    private format2NoteHandshakeDiscontinuities;
+    /**
+     * Adopt the epoch of the base a convergence just installed (#3435,
+     * finding 3435-SO-03).
+     *
+     * The same statement a cold start's `join` makes, at the one other place a
+     * document's rows become a whole base it never held: durably, because a mark
+     * written only in memory leaves a client that has just streamed a base
+     * presenting as fresh again on its next handshake, and in the transport's
+     * ledger, because the chain and the move that follow read the epoch from
+     * there.
+     */
+    private format2AdoptConvergedEpoch;
+    /**
+     * Bring a document that owes a convergence up to date, or hold it (#3435,
+     * behaviors 22 and 23).
+     *
+     * Returns `true` when the merged view has converged and the caller may go on
+     * to the ordinary chain and move; `false` when the document is HELD — the
+     * base it needs does not exist yet, so it keeps serving reads and waits for
+     * the announcement, which is the intent's rule and the opposite of what
+     * #2816 did here.
+     */
+    private format2ConvergeOwed;
     /**
      * Claim sequences that appeared AFTER the handshake had already run (#3431).
      *