@brass-build/client 0.1.0 → 0.3.0

package/dist/open-document.js

@@ -8,21 +8,90 @@ import { createPresenceController } from './presence.js';
 import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
 import { brassErrorFromBody } from './api-fetch.js';
 import { fetchWithRetry, RETRY_IDEMPOTENT_WRITE } from './fetch-retry.js';
+import { deadlineForUpload, fetchWithDeadline, OP_WRITE_TIMEOUT_MS, } from './fetch-deadline.js';
 import { BrassError } from './errors.js';
 import { perfStart } from './perf.js';
-import { resolveTailOps } from './tail-ops.js';
-import { opBlobExceedsDurableLimit, opFrameExceedsWsLimit, opBlobNeedsStaging, } from './ws-frame-limit.js';
+import { joinCoverageFloor, snapshotSeqOf } from './join-coverage.js';
+import { declaredTailBytes, resolveTailOps } from './tail-ops.js';
+import { opBlobExceedsDurableLimit, opBlobNeedsStaging, opFrameExceedsWsLimit, } from './ws-frame-limit.js';
+// The terminal frame the platform sends when it clears a document's work
+// status: the work finished and the content is in. The SDK emits the same
+// shape wherever it settles that transition off its own import (a
+// subscribe-time reconcile, a retried pull), so the app cannot tell the two
+// apart. `blocking: false` is what releases the load lock.
+const WORK_READY_STATUS = {
+    message: 'Ready',
+    pending: false,
+    blocking: false,
+};
+const CONTENT_PULL_ATTEMPTS = 5;
+const CONTENT_PULL_BACKOFF_MS = 1000;
+// Pull a document's content in after the platform reports its inbound work
+// finished, retrying a transient fetch failure (a network blip, a dropped
+// presigned download): the platform asserts the content exists, so a silent
+// give-up would leave the doc empty behind a terminal status, reading as "the
+// model never loaded" and invisible in every log. Emits `finalStatus` only
+// once the import lands, so an app re-reading on `onStatus` sees the content.
+// On exhaustion it reports the failure and emits a terminal failure status,
+// which keeps the doc read-only. Returns whether the content is in.
+async function pullContentWithRetry(args) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= CONTENT_PULL_ATTEMPTS; attempt += 1) {
+        try {
+            const outcome = await args.fetchAndImport();
+            if (outcome.ok) {
+                args.doc._emitStatus(args.finalStatus, { contentLoaded: true });
+                return true;
+            }
+            lastError = new Error(outcome.reason);
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+        // A retrying attempt is exceptional, so this warn is quiet in normal
+        // operation and decisive in a bug report; without it a failure here is
+        // undiagnosable from any log.
+        console.warn(`[Brass] document content reload attempt ${attempt}/${CONTENT_PULL_ATTEMPTS} failed (doc ${args.docId}): ${lastError.message}`);
+        if (attempt < CONTENT_PULL_ATTEMPTS) {
+            await new Promise((r) => setTimeout(r, CONTENT_PULL_BACKOFF_MS * attempt));
+        }
+    }
+    const error = new BrassError(`Document content reload failed after ${CONTENT_PULL_ATTEMPTS} attempts: ${lastError?.message ?? 'unknown error'}`, { status: 0 });
+    if (args.reportError)
+        args.reportError(error);
+    else
+        console.error('[Brass]', error);
+    args.doc._emitStatus({
+        message: 'The model could not be loaded. Reload to try again.',
+        pending: false,
+        // The content never arrived, so this terminal status still locks the
+        // doc: an edit here would write into a document holding nothing.
+        blocking: true,
+    });
+    return false;
+}
 // Both join fetches and the `doc_init` frame funnel through this, so a
 // tail op whose bytes spilled to storage is fetched once, here. Every
 // reader downstream then sees the inline shape it already handles, and
 // none of the seq bookkeeping has to learn a second representation.
-async function resolveParsedTailOps(parsed) {
+async function resolveParsedTailOps(parsed, onProgress) {
     if (typeof parsed !== 'object' || parsed === null)
         return;
     const body = parsed;
     if (!Array.isArray(body.tail_ops))
         return;
-    body.tail_ops = await resolveTailOps(body.tail_ops);
+    const tailOps = body.tail_ops;
+    // The whole download, stated before any of it starts. A presigned snapshot
+    // names its decompressed size and each spilled op names its blob's, and both
+    // are fetched over the network with a reader waiting, so the load reports one
+    // figure against their sum. An inline snapshot contributes nothing: its bytes
+    // came with this response.
+    const snapshot = body.snapshot;
+    const snapshotBytes = typeof snapshot?.raw_bytes === 'number' ? snapshot.raw_bytes : 0;
+    const totalBytes = declaredTailBytes(tailOps) + snapshotBytes;
+    body.tail_ops = await resolveTailOps(tailOps, fetch, onProgress === undefined
+        ? undefined
+        : (loadedBytes) => onProgress(loadedBytes, totalBytes > 0 ? totalBytes : null, 'tail'));
 }
 // Map the snake_case wire `drive` block to the public camelCase
 // `DocumentDriveStatus`. `canPush` is derived once here (unbroken, two-way,
@@ -42,7 +111,9 @@ function toDriveStatus(wire) {
         // update) must not be treated as unbroken and offered a push the server
         // would reject. Require an explicit `false` to enable, and an explicit
         // `true` to flag broken. Behaviour is unchanged for today's frames, which
-        // always carry the boolean.
+        // always carry the boolean. Whether the file is written server-side or
+        // from the app's own serializer is a REQUEST SHAPE the push path resolves
+        // for itself, so it says nothing about whether this document can publish.
         canPush: wire.broken === false &&
             mirrorDirection === 'two_way' &&
             (state === 'ahead' || state === 'diverged'),
@@ -56,6 +127,29 @@ function toDriveStatus(wire) {
         itemName: wire.item_name,
         itemUrl: wire.item_url,
         publishing: wire.publishing === true,
+        // Spread rather than assigned, because `exactOptionalPropertyTypes`
+        // separates an absent optional field from one holding `undefined`.
+        ...(wire.source_unreadable !== undefined
+            ? { sourceUnreadable: wire.source_unreadable }
+            : {}),
+    };
+}
+// Map the wire target to the public shape, dropping one that does not carry
+// what a publish needs. A malformed target is skipped rather than failing
+// the open: the document is readable whatever its publish offer says.
+function toPublishTarget(wire) {
+    if (typeof wire !== 'object' || wire === null)
+        return null;
+    const driveName = wire.drive_name;
+    if (typeof driveName !== 'string' || driveName === '')
+        return null;
+    return {
+        driveName,
+        driveType: typeof wire.drive_type === 'string' ? wire.drive_type : '',
+        containerName: typeof wire.container_name === 'string' ? wire.container_name : '',
+        detail: typeof wire.detail === 'string' ? wire.detail : '',
+        publishing: wire.publishing === true,
+        publishFailed: wire.publish_failed === true,
     };
 }
 function isDocOpFrame(frame) {
@@ -67,37 +161,63 @@ function isDocOpFrame(frame) {
         typeof f.op_blob === 'string' &&
         typeof f.seq === 'number');
 }
-function isDocInitFrame(frame) {
+// The frame in the shape its readers act on, or null when it carries nothing
+// they can act on.
+//
+// Gated on the discriminant plus `current_seq`, with the tail degraded entry
+// by entry. Most of what a `doc_init` does is carried by the frame itself
+// rather than by any one entry: `current_seq` is the cursor, the tail's lower
+// edge decides whether the reader re-imports the join, and the frame is the
+// (re)subscribe signal that re-asserts every outstanding op and runs the
+// durability handshake. So an entry whose shape this SDK does not recognise
+// costs the one op it carries, which stays uncovered and is pulled over the
+// HTTP join; refusing the frame over it would cost all of the above.
+//
+// `snapshot_version_vector` is likewise tolerated as absent when it is not a
+// string: the handshake needs a vector it can decode, and skipping the
+// handshake is a smaller loss than dropping the frame that drives it.
+function parseDocInitFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
-        return false;
+        return null;
     const f = frame;
     if (f.type !== 'doc_init' || typeof f.topic !== 'string')
-        return false;
+        return null;
     if (typeof f.current_seq !== 'number')
-        return false;
-    // `snapshot_version_vector` is an optional durability-handshake input, read
-    // defensively at its use site. A present-but-non-string value (a future
-    // server retyping it) is tolerated as absent rather than rejecting the whole
-    // frame, which would silently break the reconnect / durability path.
-    if (!Array.isArray(f.tail_ops))
-        return false;
-    for (const entry of f.tail_ops) {
-        if (typeof entry !== 'object' || entry === null)
-            return false;
-        const e = entry;
-        if (typeof e.seq !== 'number')
-            return false;
-        // A tail op is normally inline here: the server withholds a tail
-        // carrying a signed URL from this frame, because fetching one needs
-        // an await this reader does not have, and sends `current_seq` alone
-        // so the client re-imports the join over HTTP instead. Tolerating
-        // the shape anyway keeps such a frame's `current_seq` usable rather
-        // than dropping the whole frame and with it the resync trigger.
-        if (typeof e.op_blob_b64 !== 'string' && typeof e.op_blob_url !== 'string') {
-            return false;
+        return null;
+    const tailOps = [];
+    if (Array.isArray(f.tail_ops)) {
+        for (const entry of f.tail_ops) {
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const e = entry;
+            // The seq is what places an entry in the sequence the cursors and the
+            // resync trigger are computed from, so an entry without one is not an
+            // entry any reader here can use.
+            if (typeof e.seq !== 'number')
+                continue;
+            tailOps.push(typeof e.op_blob_b64 === 'string'
+                ? { seq: e.seq, op_blob_b64: e.op_blob_b64 }
+                : { seq: e.seq });
         }
     }
-    return true;
+    return {
+        type: 'doc_init',
+        topic: f.topic,
+        current_seq: f.current_seq,
+        tail_ops: tailOps,
+        ...(typeof f.snapshot_seq === 'number' ? { snapshot_seq: f.snapshot_seq } : {}),
+        ...(typeof f.snapshot_version_vector === 'string'
+            ? { snapshot_version_vector: f.snapshot_version_vector }
+            : {}),
+    };
+}
+function isDocCatchUpFrame(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return (f.type === 'doc_catch_up' &&
+        typeof f.topic === 'string' &&
+        typeof f.current_seq === 'number');
 }
 function isOpAckFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
@@ -116,6 +236,59 @@ function isOpRejectedFrame(frame) {
         typeof f.topic === 'string' &&
         typeof f.client_op_id === 'string');
 }
+// Whether re-sending the same op is the right move. Two statuses refuse to
+// write rather than answer about the op, and both leave the row untouched,
+// so the op is still the client's to send: 503 (the store refused on
+// capacity) and 429 (the caller is over the op-write cap, whose window
+// resets). The WS transport reads its own rate refusal the same way, as an
+// `unavailable` the shed recovery re-asserts, and the two transports carry
+// the same ops, so a refusal cannot mean "later" on one and "never" on the
+// other. Every other status is an answer about the op itself and repeats
+// however many times it is sent.
+function opWriteIsRetryable(status) {
+    return status === 503 || status === 429;
+}
+// The HTTP transport's rendering of the same refusal `op_rejected` carries on
+// the socket: the document is full. 507 is the status, and the body's `code`
+// is checked beside it so the classification does not rest on a status a
+// proxy in front of the api could rewrite.
+function isCapacityRefusal(status, parsed) {
+    if (status === 507)
+        return true;
+    return parsed?.code === 'at_capacity';
+}
+// A failure uploading an oversized op's blob to storage. It carries its own
+// type because staging runs strictly BEFORE the op write, so what a replay
+// means differs from a throw out of the write itself: nothing durable exists
+// yet and the op is still the client's to send, where a throw mid-write
+// leaves it unknown whether the row landed.
+class OpStagingError extends Error {
+    name = 'OpStagingError';
+    // The upstream status, or null for a request that drew no answer at all.
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+// Whether staging the blob again is the right move: a status the op write
+// itself replays replays here for the same reason, and a request that drew
+// no answer wrote nothing either.
+function opStagingIsRetryable(err) {
+    return err.status === null || opWriteIsRetryable(err.status);
+}
+function asOpStagingError(err) {
+    if (err instanceof OpStagingError)
+        return err;
+    const status = err instanceof BrassError ? err.status ?? null : null;
+    return new OpStagingError(status, err instanceof Error ? err.message : String(err));
+}
+function isServerUnavailableFrame(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'error' && f.reason === 'unavailable';
+}
 // The message surfaced through the error reporter for a terminal op rejection.
 // Prefers the server's copy; falls back to a generic, actionable line. The
 // local edit already applied but can never persist, so the app's cue is to
@@ -126,6 +299,40 @@ function opRejectedMessage(frame) {
     }
     return 'A change could not be saved and will not be retried. Reload the document to continue.';
 }
+// The one rejection reason that describes the DOCUMENT rather than the op:
+// every later write meets it too, so the app is told once about the document
+// instead of once per refused edit. Matched on the reason string rather than
+// on the message, which is copy and may be reworded.
+const OP_REJECTED_AT_CAPACITY = 'at_capacity';
+// Whether the document refused this write because of its size. The server
+// distinguishes a branch that refuses everything from one that refuses only
+// growth, and picks the wording accordingly; the client does not, because both
+// leave refused work on this copy and nowhere else and the answer to that is
+// the same one.
+function isCapacityRejection(frame) {
+    return frame.reason === OP_REJECTED_AT_CAPACITY;
+}
+// Which refusals describe the WRITER rather than the op. The server reads
+// write authority once, when the connection subscribes, so a refusal on
+// either of these grounds answers every later op the same way: the reader
+// cannot write to this document at all, and the Document says so through
+// `readOnly` instead of letting the app offer edits that keep failing. A
+// refusal about the op itself (too large, a bad topic) leaves the document
+// writable, because the next op may well be accepted.
+//
+// A Map rather than an object literal because the key is a wire string: an
+// object answers for the names it inherits, so a reason reading `constructor`
+// or `toString` would resolve a function and lock the document, which is the
+// opposite of what an unclassified refusal means.
+const READ_ONLY_REJECTION_REASONS = new Map([
+    ['role_denied', 'grant'],
+    ['scope_denied', 'app'],
+]);
+function readOnlyReasonForRejection(frame) {
+    if (typeof frame.reason !== 'string')
+        return null;
+    return READ_ONLY_REJECTION_REASONS.get(frame.reason) ?? null;
+}
 function isDocGoneFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
         return false;
@@ -164,6 +371,25 @@ function isDocStatusFrame(frame) {
     // unvalidated, so this keeps the WS path from being the stricter of the two.
     return typeof st.pending === 'boolean';
 }
+// `message` is typed non-null and rendered verbatim, while the wire gates
+// only on `pending`, so default it here.
+function normalizeWorkStatus(status) {
+    return {
+        ...status,
+        message: typeof status.message === 'string' ? status.message : '',
+    };
+}
+// The opaque work status a join response carries, or `null` when it carries
+// none. Gates on `pending` like `isDocStatusFrame`; the rest is display data
+// read defensively at the use site.
+function parseWorkStatus(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const status = value;
+    if (typeof status.pending !== 'boolean')
+        return null;
+    return normalizeWorkStatus(status);
+}
 function isDocMetaFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
         return false;
@@ -172,6 +398,15 @@ function isDocMetaFrame(frame) {
         typeof f.topic === 'string' &&
         typeof f.name === 'string');
 }
+function isDocDrivePublishFrame(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    if (f.type !== 'doc_drive_publish' || typeof f.topic !== 'string') {
+        return false;
+    }
+    return typeof f.publish === 'object' && f.publish !== null;
+}
 function isDocDriveStatusFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
         return false;
@@ -194,10 +429,10 @@ function isDocOpsDroppedFrame(frame) {
     if (typeof frame !== 'object' || frame === null)
         return false;
     const f = frame;
-    return (f.type === 'doc_ops_dropped' &&
-        typeof f.topic === 'string' &&
-        Array.isArray(f.dropped_seqs) &&
-        typeof f.actor === 'string');
+    // Gate on the discriminant alone. The handler reads no other field, so a
+    // frame whose informational half changed shape (or went away) must still
+    // prompt the durability re-check it is sent for.
+    return f.type === 'doc_ops_dropped' && typeof f.topic === 'string';
 }
 function defaultClientOpIdMinter() {
     const g = globalThis;
@@ -241,6 +476,15 @@ function isSnapshotResponse(body) {
     // snapshot validated structurally in materialise(); a null is fine.
     return true;
 }
+// Fold the join's write verdict into the Document options, so a reader the
+// server will not accept writes from opens read-only instead of learning it
+// from the first refused op. Only ever ADDS the restriction: a caller that
+// asked for a read-only Document keeps it whatever the grant says.
+function readOnlyForGrant(body, options) {
+    if (body.can_edit !== false)
+        return options;
+    return { ...options, readOnly: true, readOnlyReason: 'grant' };
+}
 function isAtVersionResponse(body) {
     if (typeof body !== 'object' || body === null)
         return false;
@@ -285,13 +529,27 @@ export function createOpenDocument(opts) {
         applyClientVersionHeader(headers);
         await applyAppAssertionHeader(headers, opts.getAppAssertion);
         const endFetch = perfStart('open: GET /documents (http + read body)');
-        // Idempotent read: ride out a cold-API transient 5xx / 429 (a 503
-        // while the API scales into a concurrent open burst is the common
-        // one) instead of failing the open on a blip that clears in a second.
+        // Idempotent read: ride out a transient 5xx / 429 instead of failing the
+        // open on something that clears on its own.
+        //
+        // Longer than the default handful of attempts because of what a 503 means
+        // on this route: the document is intact and its storage is busy. Every op
+        // row a document has shares one partition, so the document most likely to
+        // answer 503 is one that was just written hard, which is exactly the
+        // moment a person reloads to see their work. That pressure clears over
+        // tens of seconds, not the one second the default budget spans, and the
+        // cost of giving up early is telling someone their document will not open
+        // when waiting would have opened it.
+        //
+        // A thrown request gets a short budget of its own: it never reached the
+        // API, so the busy partition is not what is wrong, and a blocked origin
+        // or a host that does not resolve answers the seventh attempt as it
+        // answered the first, with the reader watching a loading surface
+        // throughout.
         const response = await fetchWithRetry(() => fetch(url, {
             method: 'GET',
             headers,
-        }));
+        }), { maxAttempts: 7, baseDelayMs: 700, maxNetworkAttempts: 3 });
         const text = await response.text();
         endFetch({ status: response.status, responseChars: text.length });
         let parsed = undefined;
@@ -304,7 +562,7 @@ export function createOpenDocument(opts) {
                 parseFailed = true;
             }
         }
-        await resolveParsedTailOps(parsed);
+        await resolveParsedTailOps(parsed, options?.onSnapshotProgress);
         return { status: response.status, parsed, parseFailed };
     }
     // `GET /documents/{docId}/at/{version}`: read-only materialization at a
@@ -430,35 +688,45 @@ export function createOpenDocument(opts) {
     // key the op write names. The PUT carries no Brass headers: the URL is
     // signed, and an extra header falls outside that signature.
     async function stageOpBlob(docId, opBlobB64, token) {
-        const headers = {
-            authorization: `Bearer ${token}`,
-            'content-type': 'application/json',
-        };
-        applyClientVersionHeader(headers);
-        await applyAppAssertionHeader(headers, opts.getAppAssertion);
-        const mint = await fetch(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops/upload`, { method: 'POST', headers, body: '{}' });
-        if (!mint.ok) {
-            const text = await mint.text();
-            let parsed = undefined;
+        // Everything in here happens before the op write, so every failure it
+        // can take is tagged as one: what the tag buys the writer is the right
+        // to send the op again, which a failure of the write itself does not
+        // carry.
+        try {
+            const headers = {
+                authorization: `Bearer ${token}`,
+                'content-type': 'application/json',
+            };
+            applyClientVersionHeader(headers);
+            await applyAppAssertionHeader(headers, opts.getAppAssertion);
+            const mint = await fetchWithDeadline(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops/upload`, { method: 'POST', headers, body: '{}' }, OP_WRITE_TIMEOUT_MS);
+            let minted = undefined;
             try {
-                parsed = text ? JSON.parse(text) : undefined;
+                minted = mint.text ? JSON.parse(mint.text) : undefined;
             }
             catch {
-                parsed = undefined;
+                minted = undefined;
             }
-            throw brassErrorFromBody(mint.status, parsed);
-        }
-        const body = (await mint.json());
-        if (typeof body.upload_key !== 'string' || typeof body.url !== 'string') {
-            throw new BrassError('Malformed op upload response', { status: 500 });
+            if (!mint.ok) {
+                throw brassErrorFromBody(mint.status, minted);
+            }
+            const body = (minted ?? {});
+            if (typeof body.upload_key !== 'string' || typeof body.url !== 'string') {
+                throw new BrassError('Malformed op upload response', { status: 500 });
+            }
+            const endUpload = perfStart('op: PUT staged op blob');
+            const put = await fetchWithDeadline(body.url, { method: 'PUT', body: opBlobB64 }, deadlineForUpload(opBlobB64.length));
+            endUpload({ status: put.status, opChars: opBlobB64.length });
+            if (!put.ok) {
+                throw new BrassError('Could not upload the update', {
+                    status: put.status,
+                });
+            }
+            return body.upload_key;
         }
-        const endUpload = perfStart('op: PUT staged op blob');
-        const put = await fetch(body.url, { method: 'PUT', body: opBlobB64 });
-        endUpload({ status: put.status, opChars: opBlobB64.length });
-        if (!put.ok) {
-            throw new BrassError('Could not upload the update', { status: put.status });
+        catch (err) {
+            throw asOpStagingError(err);
         }
-        return body.upload_key;
     }
     async function postDocumentOp(docId, branchId, opBlobB64, clientOpId, token) {
         const headers = {
@@ -475,7 +743,7 @@ export function createOpenDocument(opts) {
             stagedKey = await stageOpBlob(docId, opBlobB64, token);
         }
         const endFetch = perfStart('op: POST /documents/{id}/ops');
-        const response = await fetch(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops`, {
+        const response = await fetchWithDeadline(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops`, {
             method: 'POST',
             headers,
             body: JSON.stringify({
@@ -485,12 +753,14 @@ export function createOpenDocument(opts) {
                 branch_id: branchId,
                 client_op_id: clientOpId,
             }),
-        });
-        const text = await response.text();
+        }, 
+        // An op under the staging threshold travels inline, so this request
+        // carries the blob and its deadline has to allow for sending it.
+        deadlineForUpload(stagedKey === undefined ? opBlobB64.length : 0));
         endFetch({ status: response.status, opChars: opBlobB64.length });
         let parsed = undefined;
         try {
-            parsed = text ? JSON.parse(text) : undefined;
+            parsed = response.text ? JSON.parse(response.text) : undefined;
         }
         catch {
             parsed = undefined;
@@ -638,7 +908,9 @@ export function createOpenDocument(opts) {
                 status: 500,
             });
         }
-        const doc = await materialise(parsed);
+        // A stream's write authority is the document's, so the line opens
+        // read-only for the same reader the document opens read-only for.
+        const doc = await materialise(parsed, readOnlyForGrant(parsed, undefined));
         // A stream line materializes at a historical seq the same way the
         // default line does, so the parent's version preview can bring this
         // stream to a point in time (`doc.stream(name)._previewAt(seq)`). The
@@ -649,7 +921,8 @@ export function createOpenDocument(opts) {
         // line (see the comments there); scoped per line because each stream
         // has its own seq space.
         let currentSeq = Math.max(parsed.tail_ops.reduce((acc, entry) => (entry.seq > acc ? entry.seq : acc), 0), typeof parsed.current_seq === 'number' ? parsed.current_seq : 0);
-        let coveredSeq = typeof parsed.current_seq === 'number' ? parsed.current_seq : 0;
+        const lineTailSeqs = parsed.tail_ops.map((entry) => entry.seq);
+        let coveredSeq = joinCoverageFloor(snapshotSeqOf(parsed.snapshot_seq, lineTailSeqs, typeof parsed.current_seq === 'number' ? parsed.current_seq : 0), lineTailSeqs);
         const coverageParked = new Set();
         const advanceCoverage = (seq) => {
             if (seq <= coveredSeq)
@@ -660,50 +933,79 @@ export function createOpenDocument(opts) {
                 coveredSeq += 1;
             }
         };
+        const raiseCoverage = (floor) => {
+            if (floor > coveredSeq)
+                coveredSeq = floor;
+            for (const seq of coverageParked) {
+                if (seq <= coveredSeq)
+                    coverageParked.delete(seq);
+            }
+            while (coverageParked.has(coveredSeq + 1)) {
+                coverageParked.delete(coveredSeq + 1);
+                coveredSeq += 1;
+            }
+        };
         for (const entry of parsed.tail_ops)
             advanceCoverage(entry.seq);
-        // Reconnect-across-compaction recovery: re-import the line's join.
-        // Loro imports are idempotent, so re-applying over live state is a
-        // clean merge.
-        const resyncFromSnapshot = () => {
-            void (async () => {
-                try {
-                    const t = await requireToken();
-                    const res = await fetchSnapshot(docId, { branch: lineId }, t);
-                    if (res.status < 200 || res.status >= 300)
-                        return;
-                    if (!isSnapshotResponse(res.parsed))
-                        return;
-                    const snap = res.parsed.snapshot;
-                    if (snap !== null) {
-                        const bytes = snap.kind === 'inline'
-                            ? base64ToBytes(snap.data_b64)
-                            : await fetchPresignedSnapshot(snap.url);
-                        doc._applySnapshot(bytes);
-                    }
-                    for (const entry of res.parsed.tail_ops) {
-                        doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
-                        if (entry.seq > currentSeq)
-                            currentSeq = entry.seq;
-                        advanceCoverage(entry.seq);
-                    }
-                    const joined = res.parsed.current_seq;
-                    if (typeof joined === 'number') {
-                        if (joined > currentSeq)
+        // Re-import the line's join: the reconnect-across-compaction recovery,
+        // and the answer to a catch-up prompt. Loro imports are idempotent, so
+        // re-applying over live state is a clean merge.
+        //
+        // Coalesced and delivery-honest for the same reasons the default line
+        // is: a prompt during a fetch is the only notice of that op the line
+        // gets, and a join's `current_seq` names seqs whose rows the tail query
+        // could not see yet.
+        let lineResyncRun = null;
+        let lineResyncAgain = false;
+        const runLineResync = async () => {
+            try {
+                do {
+                    lineResyncAgain = false;
+                    try {
+                        const t = await requireToken();
+                        const res = await fetchSnapshot(docId, { branch: lineId }, t);
+                        if (res.status < 200 || res.status >= 300)
+                            continue;
+                        if (!isSnapshotResponse(res.parsed))
+                            continue;
+                        const snap = res.parsed.snapshot;
+                        if (snap !== null) {
+                            const bytes = snap.kind === 'inline'
+                                ? base64ToBytes(snap.data_b64)
+                                : await fetchPresignedSnapshot(snap.url);
+                            doc._applySnapshot(bytes);
+                        }
+                        const seqs = [];
+                        for (const entry of res.parsed.tail_ops) {
+                            doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
+                            if (entry.seq > currentSeq)
+                                currentSeq = entry.seq;
+                            seqs.push(entry.seq);
+                        }
+                        const joined = res.parsed.current_seq;
+                        if (typeof joined === 'number' && joined > currentSeq) {
                             currentSeq = joined;
-                        if (joined > coveredSeq) {
-                            coveredSeq = joined;
-                            for (const seq of coverageParked) {
-                                if (seq <= coveredSeq)
-                                    coverageParked.delete(seq);
-                            }
                         }
+                        raiseCoverage(joinCoverageFloor(snapshotSeqOf(res.parsed.snapshot_seq, seqs, currentSeq), seqs));
+                        for (const seq of seqs)
+                            advanceCoverage(seq);
                     }
-                }
-                catch {
-                    // Best-effort; the next doc_init retries.
-                }
-            })();
+                    catch {
+                        // Best-effort; the next prompt or doc_init retries.
+                    }
+                } while (lineResyncAgain);
+            }
+            finally {
+                lineResyncRun = null;
+            }
+        };
+        const resyncFromSnapshot = () => {
+            if (lineResyncRun !== null) {
+                lineResyncAgain = true;
+                return lineResyncRun;
+            }
+            lineResyncRun = runLineResync();
+            return lineResyncRun;
         };
         // Write an op the socket cannot carry. The op stays one commit and
         // one seq; only the transport differs, and the response carries the
@@ -712,11 +1014,23 @@ export function createOpenDocument(opts) {
             const token = await requireToken();
             const { status, parsed: opResult } = await postDocumentOp(docId, lineId, opBlobB64, clientOpId, token);
             if (status < 200 || status >= 300) {
-                return { ok: false, message: opWriteFailureMessage(status, opResult) };
+                return {
+                    ok: false,
+                    message: opWriteFailureMessage(status, opResult),
+                    retryable: opWriteIsRetryable(status),
+                    atCapacity: isCapacityRefusal(status, opResult),
+                    // The route answers 403 when the caller's grant carries no write
+                    // access, which is the HTTP face of the socket's `role_denied`.
+                    ...(status === 403 ? { readOnly: 'grant' } : {}),
+                };
             }
             const seq = opResult?.seq;
             if (typeof seq !== 'number') {
-                return { ok: false, message: 'The server did not report a version for this change.' };
+                return {
+                    ok: false,
+                    message: 'The server did not report a version for this change.',
+                    retryable: false,
+                };
             }
             return { ok: true, seq };
         };
@@ -750,17 +1064,27 @@ export function createOpenDocument(opts) {
         if (!isSnapshotResponse(parsed)) {
             throw new BrassError('Malformed document snapshot response', { status: 500 });
         }
-        const doc = await materialise(parsed, options?.documentOptions, options?.onSnapshotProgress);
+        const doc = await materialise(parsed, readOnlyForGrant(parsed, options?.documentOptions), options?.onSnapshotProgress);
         // Populate `doc.status` from the join before the first `doc_status` frame
         // (a stub opened mid-hydration returns `snapshot: null` + a `pending`
         // status).
         if (parsed.status !== undefined)
             doc._emitStatus(parsed.status);
+        // Whether this app is the one to serialize the document, which is what
+        // decides whether a push carries bytes. Answered by the server for the
+        // caller's own app and only on the join, since the fanout frame is one
+        // payload for every subscriber and has no caller to answer for.
+        doc._setExportRunsHere(parsed.calling_app_exports === true);
         // Seed `doc.driveStatus` from the join before the first
         // `doc_drive_status` frame.
         if (parsed.drive !== undefined) {
             doc._emitDriveStatus(toDriveStatus(parsed.drive));
         }
+        else {
+            // Only for a document that mirrors nothing: a mirror publishes through
+            // its link, and `_emitDriveStatus` clears any targets anyway.
+            doc._setPublishTarget(toPublishTarget(parsed.drive_publish_target));
+        }
         // Highest seq seen; later `doc_op` / `op_ack` frames advance it. Kept in
         // a closure, not on the Document: it is a transport concern, not CRDT
         // state.
@@ -771,9 +1095,14 @@ export function createOpenDocument(opts) {
         // then can't tell "caught up" from "missed ops since compacted into the
         // snapshot". The floor never overestimates, so the `doc_init` resync
         // check always detects such a hole (at worst a transient out-of-order
-        // arrival costs one idempotent re-fetch). Seeded from the consistent-read
-        // join's `current_seq`.
-        let coveredSeq = typeof parsed.current_seq === 'number' ? parsed.current_seq : 0;
+        // arrival costs one idempotent re-fetch).
+        //
+        // Seeded from what this join DELIVERED, which is its snapshot plus the
+        // unbroken run of tail seqs above it, never from `current_seq`: a join
+        // read while someone writes in bulk reports a counter above the rows it
+        // could see, and seeding from the counter opens the document already
+        // claiming ops it does not hold.
+        let coveredSeq = joinCoverageFloor(snapshotSeqOf(parsed.snapshot_seq, parsed.tail_ops.map((entry) => entry.seq), typeof parsed.current_seq === 'number' ? parsed.current_seq : 0), parsed.tail_ops.map((entry) => entry.seq));
         // Seqs applied above the floor, parked until the gap below fills.
         const coverageParked = new Set();
         const drainCoverage = () => {
@@ -788,9 +1117,11 @@ export function createOpenDocument(opts) {
             coverageParked.add(seq);
             drainCoverage();
         };
-        // Mark everything at or below `floor` covered (a full consistent join was
-        // imported). Also steps the floor past any abandoned server-side seq
-        // (allocated, never written) that `advanceCoverage` would stall under.
+        // Mark everything at or below `floor` covered. The caller owes the
+        // guarantee that goes with it: every seq under `floor` is applied, or
+        // folded into a snapshot this doc imported. Coverage is what retires a
+        // catch-up prompt, so a floor taken from anything looser than that is a
+        // reader quietly deciding it holds ops nobody sent it.
         const raiseCoverage = (floor) => {
             if (floor > coveredSeq)
                 coveredSeq = floor;
@@ -859,14 +1190,34 @@ export function createOpenDocument(opts) {
                 if (entry.seq > maxTailSeq)
                     maxTailSeq = entry.seq;
             }
-            // Raise both cursors so the floor reflects the import (this clears a
-            // detected missed-compaction hole).
             const fetchedSeq = typeof result.parsed.current_seq === 'number'
                 ? result.parsed.current_seq
                 : maxTailSeq;
             if (fetchedSeq > currentSeq)
                 currentSeq = fetchedSeq;
-            raiseCoverage(fetchedSeq);
+            // Coverage moves to what this response DELIVERED, not to the head it
+            // reported. The two differ exactly when it matters: the head is the
+            // branch's seq counter, bumped when a seq is handed out rather than
+            // when its row is written, so a join read during a bulk write names
+            // ops the tail query could not see. Crediting the head marks those
+            // seqs covered, and the prompts that would fetch them then short
+            // circuit, which is a reader left permanently short of a write it
+            // watched land.
+            //
+            // The cost is that a seq allocated and never written (a failed op
+            // write leaves a hole rather than a duplicate) now stalls the floor
+            // under it. That resolves at the next compaction, which folds the tail
+            // past the hole and raises `snapshot_seq` over it; until then the gap
+            // pull's own budget is what stops the reader asking forever.
+            const tailSeqs = sortedTail.map((entry) => entry.seq);
+            // A snapshot only counts as a floor once its bytes are in: a shape this
+            // pin does not decode leaves `snapshot_seq` describing content the doc
+            // never received, and the tail alone is then what it holds.
+            if (snapshotBytes !== null || result.parsed.snapshot === null) {
+                raiseCoverage(joinCoverageFloor(snapshotSeqOf(result.parsed.snapshot_seq, tailSeqs, fetchedSeq), tailSeqs));
+            }
+            for (const seq of tailSeqs)
+                advanceCoverage(seq);
             endPerf({
                 ok: true,
                 snapshotBytes: snapshotBytes?.byteLength ?? 0,
@@ -897,90 +1248,106 @@ export function createOpenDocument(opts) {
             }
             return out;
         };
-        let resyncInFlight = false;
-        const resyncFromSnapshot = () => {
-            if (resyncInFlight)
-                return;
-            resyncInFlight = true;
-            void (async () => {
-                try {
-                    const outcome = await refetchAndImport();
-                    if (!outcome.ok) {
-                        console.error('Brass: document resync after reconnect failed; state may lag until the next reconnect or reload');
+        // Coalesced, not skipped. A prompt that lands while a join is in flight
+        // is a statement that the document has moved past what that join can
+        // possibly carry, so dropping it loses the only notice this reader gets:
+        // the server posts each prompt once, and a passive reader has no ack or
+        // op of its own to notice the shortfall from. A bulk write is a run of
+        // prompts (every op past the frame bound takes the HTTP route and
+        // prompts each subscriber), and under a plain skip-if-in-flight the
+        // whole run collapses into the one or two joins that happened not to be
+        // busy, which is a reader stranded partway through a write it watched.
+        //
+        // `resyncAgain` is a flag rather than a queue because a join reads the
+        // whole document: one more pass answers every prompt that arrived during
+        // this one. The loop therefore runs at most one extra fetch after the
+        // last prompt, and settles when the writer stops.
+        //
+        // The returned promise settles when the last pass this call is
+        // responsible for has landed, so a caller deciding whether the reader is
+        // still short reads the floor after the work rather than during it.
+        let resyncRun = null;
+        let resyncAgain = false;
+        const runResync = async () => {
+            try {
+                do {
+                    resyncAgain = false;
+                    try {
+                        const outcome = await refetchAndImport();
+                        if (!outcome.ok) {
+                            console.error('Brass: document resync after reconnect failed; state may lag until the next reconnect or reload');
+                        }
                     }
-                }
-                catch (err) {
-                    console.error('Brass: document resync after reconnect failed; state may lag until the next reconnect or reload', err);
-                }
-                finally {
-                    resyncInFlight = false;
-                }
-            })();
+                    catch (err) {
+                        console.error('Brass: document resync after reconnect failed; state may lag until the next reconnect or reload', err);
+                    }
+                } while (resyncAgain);
+            }
+            finally {
+                resyncRun = null;
+            }
+        };
+        const resyncFromSnapshot = () => {
+            if (resyncRun !== null) {
+                resyncAgain = true;
+                return resyncRun;
+            }
+            resyncRun = runResync();
+            return resyncRun;
         };
         // When a doc opened mid-load finishes, pull the now-available content
         // into the live doc so it appears without the app reopening. Only ever
         // called on the server's authoritative `reload` hint, so it never has to
         // tell success from failure: a failure carries no `reload`, so no racy
         // read and no loop against a failed hydration.
-        //
-        // A failed fetch here is transient (network, dropped presigned download)
-        // and is retried with backoff: a silent give-up would strand the doc
-        // empty-but-editable, reading as "the model never loaded" and invisible
-        // in every log. On exhaustion the failure is reported and the terminal
-        // status is an honest failure, not the server's success copy.
         let reloadInFlight = false;
-        const RELOAD_ATTEMPTS = 5;
-        const RELOAD_BACKOFF_MS = 1000;
+        let reconcileInFlight = false;
+        // A terminal frame that lands while the subscribe-time reconcile is still
+        // fetching waits for it: two concurrent imports each clear the undo stack
+        // and race their terminal emits, and dropping the frame would leave a
+        // reconcile that read the row too early sitting on the pending overlay.
+        let deferredReload = null;
+        // Armed when the pull below gives up. The work is terminal server-side, so
+        // no further status frame arrives, and later ops are causally dependent on
+        // a snapshot this client never imported (Loro buffers them and the doc
+        // stays empty), so the next frame on the topic drives one more attempt.
+        let retryPullOnNextFrame = false;
         const reloadAfterHydration = (finalStatus) => {
             if (reloadInFlight)
                 return;
+            if (reconcileInFlight) {
+                deferredReload = finalStatus;
+                return;
+            }
             reloadInFlight = true;
             void (async () => {
-                let lastError = null;
-                for (let attempt = 1; attempt <= RELOAD_ATTEMPTS; attempt += 1) {
-                    try {
-                        const outcome = await refetchAndImport();
-                        if (outcome.ok) {
-                            reloadInFlight = false;
-                            // Emit the terminal status AFTER the import settles, so an app
-                            // re-reading on `onStatus` sees the content present and (with
-                            // `readOnly` now false) clears its loading overlay.
-                            doc._emitStatus(finalStatus);
-                            return;
-                        }
-                        lastError = new Error(outcome.reason);
-                    }
-                    catch (err) {
-                        lastError = err instanceof Error ? err : new Error(String(err));
-                    }
-                    // A retrying attempt is exceptional, so this warn is quiet in
-                    // normal operation and decisive in a bug report; without it a
-                    // failure here is undiagnosable from any log.
-                    console.warn(`[Brass] document content reload attempt ${attempt}/${RELOAD_ATTEMPTS} failed (doc ${docId}): ${lastError.message}`);
-                    if (attempt < RELOAD_ATTEMPTS) {
-                        await new Promise((r) => setTimeout(r, RELOAD_BACKOFF_MS * attempt));
-                    }
-                }
-                reloadInFlight = false;
-                const error = new BrassError(`Document content reload failed after ${RELOAD_ATTEMPTS} attempts: ${lastError?.message ?? 'unknown error'}`, { status: 0 });
-                if (opts.reportError)
-                    opts.reportError(error);
-                else
-                    console.error('[Brass]', error);
-                doc._emitStatus({
-                    message: 'The model could not be loaded. Reload to try again.',
-                    pending: false,
+                const imported = await pullContentWithRetry({
+                    doc,
+                    docId,
+                    finalStatus,
+                    fetchAndImport: refetchAndImport,
+                    ...(opts.reportError ? { reportError: opts.reportError } : {}),
                 });
+                reloadInFlight = false;
+                retryPullOnNextFrame = !imported;
             })();
         };
+        // Evidence the document moved on the server after a give-up: one more
+        // pull, which on success imports the content and releases the lock the
+        // failed terminal status left in place.
+        const retryContentPull = () => {
+            if (!retryPullOnNextFrame)
+                return;
+            retryPullOnNextFrame = false;
+            reloadAfterHydration(WORK_READY_STATUS);
+        };
         // Reconcile a pending open once the live subscription exists. The
         // terminal `doc_status` frame is best-effort: if hydration finishes
-        // before this client's SUB# row exists, the fan-out finds no subscriber
+        // before this client's subscription record exists, the fan-out finds no subscriber
         // and drops the frame, stranding the app on the pending overlay. `doc_init`
-        // is posted only after the SUB# row is written, so one re-fetch here
+        // is posted only after the subscription record is written, so one re-fetch here
         // closes the gap for a completion that landed before the row existed.
         // Only a pending open pays the extra fetch.
-        let reconcileInFlight = false;
         const reconcileStatusOnInit = () => {
             const current = doc.status;
             if (!current || !current.pending)
@@ -989,6 +1356,7 @@ export function createOpenDocument(opts) {
                 return;
             reconcileInFlight = true;
             void (async () => {
+                let settled = false;
                 try {
                     const outcome = await refetchAndImport();
                     if (!outcome.ok)
@@ -997,10 +1365,15 @@ export function createOpenDocument(opts) {
                     // fan-out delivers the terminal frame when the work finishes.
                     if (outcome.status?.pending)
                         return;
-                    // Terminal. A present status is a failure (server message,
-                    // pending:false); an absent status is success. On success retain
-                    // the last server message and flip pending so the overlay clears.
-                    doc._emitStatus(outcome.status ?? { message: current.message, pending: false });
+                    settled = true;
+                    // Terminal. A status the server still holds is a failure (success
+                    // clears the row), and its absence is the success this import just
+                    // pulled the content for, reported as the same terminal frame the
+                    // platform sends on that transition.
+                    if (outcome.status)
+                        doc._emitStatus(outcome.status);
+                    else
+                        doc._emitStatus(WORK_READY_STATUS, { contentLoaded: true });
                 }
                 catch {
                     // Best-effort; the live fan-out remains the primary path when
@@ -1008,6 +1381,12 @@ export function createOpenDocument(opts) {
                 }
                 finally {
                     reconcileInFlight = false;
+                    const deferred = deferredReload;
+                    deferredReload = null;
+                    // A settled reconcile imported the content itself, so the held
+                    // frame has nothing left to pull.
+                    if (deferred && !settled)
+                        reloadAfterHydration(deferred);
                 }
             })();
         };
@@ -1019,13 +1398,22 @@ export function createOpenDocument(opts) {
             const token = await requireToken();
             const { status, parsed: opResult } = await postDocumentOp(docId, parsed.branch_id, opBlobB64, clientOpId, token);
             if (status < 200 || status >= 300) {
-                return { ok: false, message: opWriteFailureMessage(status, opResult) };
+                return {
+                    ok: false,
+                    message: opWriteFailureMessage(status, opResult),
+                    retryable: opWriteIsRetryable(status),
+                    atCapacity: isCapacityRefusal(status, opResult),
+                    // The route answers 403 when the caller's grant carries no write
+                    // access, which is the HTTP face of the socket's `role_denied`.
+                    ...(status === 403 ? { readOnly: 'grant' } : {}),
+                };
             }
             const seq = opResult?.seq;
             if (typeof seq !== 'number') {
                 return {
                     ok: false,
                     message: 'The server did not report a version for this change.',
+                    retryable: false,
                 };
             }
             return { ok: true, seq };
@@ -1043,6 +1431,10 @@ export function createOpenDocument(opts) {
                     ? { requestedBranchId: options.branch }
                     : {}),
                 ...(options?.stream !== undefined ? { requestedStream: options.stream } : {}),
+                ...(options?.documentOptions !== undefined
+                    ? { documentOptions: options.documentOptions }
+                    : {}),
+                ...(opts.identity !== undefined ? { identity: opts.identity } : {}),
                 wsClient: opts.wsClient,
                 postOversizedOp,
                 newClientOpId: opts.newClientOpId ?? defaultClientOpIdMinter,
@@ -1057,6 +1449,7 @@ export function createOpenDocument(opts) {
                 refetchDurableFrontier,
                 reloadAfterHydration,
                 reconcileStatusOnInit,
+                onDocumentMoved: retryContentPull,
             });
         }
         // `doc._checkoutVersion(v)` calls back here to materialise historical
@@ -1081,6 +1474,7 @@ export function createOpenDocument(opts) {
                 await uploader(doc, image, width, height);
             });
         }
+        doc._setThumbnailVersion(parsed.thumbnail?.version ?? null);
         if (opts.checkpointCreator) {
             const creator = opts.checkpointCreator;
             doc.setCheckpointCreator(() => creator(doc));
@@ -1189,6 +1583,11 @@ export function createOpenDocument(opts) {
                 parseFailed = true;
             }
         }
+        // A tail op whose bytes spilled to storage arrives as a signed URL, and
+        // a guest join carries them exactly as a signed-in one does. The URL
+        // carries its own signature, so an anonymous reader fetches it with the
+        // same call. Resolving here is what lets `materialise` see one shape.
+        await resolveParsedTailOps(parsed);
         return { status: response.status, parsed, parseFailed };
     }
     // `GET /links/{token}/streams`: the anonymous stream manifest, the guest
@@ -1242,7 +1641,7 @@ export function createOpenDocument(opts) {
         // The link's grant decides read vs write. An `editor` link is anonymous
         // EDIT: a live Document (not read-only) whose local mutations ship over
         // the same token-authenticated socket, with the server admitting the
-        // op-write because the guest's SUB# row carries `role: editor`. A
+        // op-write because the guest's subscription record carries `role: editor`. A
         // `viewer` link (the default) is read-only: mutate throws and only
         // inbound frames apply.
         const canEdit = b.link_role === 'editor';
@@ -1256,7 +1655,20 @@ export function createOpenDocument(opts) {
         // sees the title (the signed-in open gets this from `finalise`).
         if (typeof b.name === 'string')
             doc._setName(b.name);
-        wireGuestTransport(doc, b.doc_id, b.branch_id, canEdit);
+        // A link opened while the platform is still preparing the document
+        // carries the same opaque work status the signed-in join does, and the
+        // guest's own topic delivers the phases after it. Seeded before the
+        // transport so the app renders the wait rather than an empty document.
+        const linkStatus = parseWorkStatus(b.status);
+        if (linkStatus)
+            doc._emitStatus(linkStatus);
+        // An edit link's writes fail the same ways a member's do (a shed the
+        // budget outlived, a link revoked mid-edit), and the app hears those
+        // through the same channel it hears a member's, so the reporter is
+        // wired here as `finalise` wires it for a signed-in open.
+        if (opts.reportError)
+            doc.setErrorReporter(opts.reportError);
+        wireGuestTransport(doc, token, b.doc_id, b.branch_id, canEdit);
         // Streams: a guest resolves `doc.stream(name)` through the token
         // routes. `list` hits the anonymous manifest; `openLine` joins the
         // line read/write exactly like the default stream above, over the same
@@ -1284,7 +1696,9 @@ export function createOpenDocument(opts) {
                     snapshot: lb.snapshot,
                     tail_ops: lb.tail_ops,
                 }, { readOnly: !canEdit });
-                wireGuestTransport(inner, lb.doc_id, lb.branch_id, canEdit);
+                if (opts.reportError)
+                    inner.setErrorReporter(opts.reportError);
+                wireGuestTransport(inner, token, lb.doc_id, lb.branch_id, canEdit);
                 return inner;
             },
             create: () => {
@@ -1295,68 +1709,263 @@ export function createOpenDocument(opts) {
         });
         return doc;
     };
+    // Write a guest's op over HTTP: `POST /links/{token}/ops`, the anonymous
+    // counterpart of `POST /documents/{docId}/ops`. Sends NO Authorization
+    // header (the token is the credential) and names the line the guest
+    // opened, which is the branch its socket topic is scoped to.
+    async function postLinkOp(token, lineId, opBlobB64, clientOpId) {
+        const response = await fetch(`${baseUrl}/links/${encodeURIComponent(token)}/ops`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                op_blob: opBlobB64,
+                branch_id: lineId,
+                client_op_id: clientOpId,
+            }),
+        });
+        const text = await response.text();
+        let parsed = undefined;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        return { status: response.status, parsed };
+    }
     // Wire a guest Document (the default stream or a stream line) to the
     // token-authenticated socket. Inbound frames (`doc_init` / `doc_op`)
     // apply for both link kinds; an edit link ALSO wires the outbound path
     // (`op_ack` resolves the outstanding-op tracker, `setLocalOpHook` ships
-    // each local commit as an `op` frame). Best-effort (no resync / durability
+    // each local commit). Best-effort on the read side (no resync / durability
     // handshake, which need a signed-in token); a guest that misses ops
-    // re-opens. Patches `close` to detach, mirroring `wireDocTransport`, so
-    // `Document` stays free of WS knowledge. A no-op with no WS client (a
-    // snapshot-only guest).
-    function wireGuestTransport(doc, docId, lineId, canEdit) {
+    // re-opens. The WRITE side answers a refusal the way the signed-in
+    // transport does, because a guest editor's edit is the same person's work
+    // as a member's and the same two things can happen to it: a frame the
+    // socket cannot carry takes the HTTP route, and a capacity shed is
+    // re-asserted on the shared backoff and reported once the budget is out.
+    // Patches `close` to detach, mirroring `wireDocTransport`, so `Document`
+    // stays free of WS knowledge. A no-op with no WS client (a snapshot-only
+    // guest).
+    function wireGuestTransport(doc, token, docId, lineId, canEdit) {
         const wsClient = opts.wsClient;
         if (!wsClient)
             return;
         const topic = `doc:${docId}:${lineId}`;
+        // Ops on the socket awaiting an answer, keyed by `client_op_id`. An
+        // `unavailable` shed names no op, so re-asserting one needs the frames
+        // in hand. Scoped to what the socket carried: an op that took the HTTP
+        // write must never reach the socket, and that write re-asserts itself.
+        const outstanding = new Map();
+        let shedRounds = 0;
+        let shedTimer = null;
+        function clearShedRecovery() {
+            if (shedTimer !== null) {
+                clearTimeout(shedTimer);
+                shedTimer = null;
+            }
+            shedRounds = 0;
+        }
+        // Every outstanding op is dead: drop the tracker entries and tell the
+        // Document, which stops counting them in `savingCount` and reports each
+        // through the error channel the app reads. The ids are taken first
+        // because `_failOutstandingOp` re-enters app code.
+        function failAllOutstanding(message) {
+            const clientOpIds = [...outstanding.keys()];
+            outstanding.clear();
+            for (const clientOpId of clientOpIds) {
+                doc._failOutstandingOp(clientOpId, message);
+            }
+        }
+        // Put every op still awaiting an answer back on the wire. The client
+        // DROPS an op frame it cannot send right now rather than buffering one
+        // (`ownsFrameRetry` below), so this is the only thing that carries a
+        // shed or reconnect-orphaned op across the window, and it is also what
+        // keeps a frame from being written twice: a copy the client held would
+        // flush on the `subscribed` ack while this re-asserts on the `doc_init`
+        // behind it, and the server allocates a fresh seq per send.
+        const resendAllOutstanding = () => {
+            for (const frame of outstanding.values())
+                wsClient.send(frame);
+        };
+        const onServerUnavailable = () => {
+            if (outstanding.size === 0)
+                return;
+            if (shedTimer !== null)
+                return;
+            shedRounds += 1;
+            if (shedRounds > UNAVAILABLE_MAX_ROUNDS) {
+                clearShedRecovery();
+                failAllOutstanding(UNAVAILABLE_GIVE_UP_MESSAGE);
+                return;
+            }
+            shedTimer = setTimeout(() => {
+                shedTimer = null;
+                resendAllOutstanding();
+            }, unavailableDelayMs(shedRounds));
+            shedTimer.unref?.();
+        };
         const unsub = wsClient.subscribe(topic, (frame) => {
-            if (isDocInitFrame(frame)) {
-                for (const entry of frame.tail_ops) {
+            const init = parseDocInitFrame(frame);
+            if (init) {
+                for (const entry of init.tail_ops) {
                     if (entry.op_blob_b64 === undefined)
                         continue;
                     doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
                 }
+                // `doc_init` follows every `subscribed` ack, so this is the point
+                // the topic can carry frames again. A fresh connection also returns
+                // the shed budget to full: this re-assert is the round a pending
+                // one would have run.
+                clearShedRecovery();
+                resendAllOutstanding();
+                return;
             }
-            else if (isDocOpFrame(frame)) {
+            if (isDocOpFrame(frame)) {
                 doc.applyRemoteOp(base64ToBytes(frame.op_blob));
             }
             else if (isDocGoneFrame(frame)) {
                 // The server fans `doc_gone` to EVERY subscriber on the branched
-                // content topic, guest-link connections included (`fanoutDocGone` /
-                // `fanoutBranchGone`), on a soft-delete / move of the opened doc.
+                // content topic, guest-link connections included, on a soft-delete /
+                // move of the opened doc.
                 // Without this branch the guest keeps showing removed content and
                 // `doc.onGone(...)` never fires; for an edit link the next local op
-                // would ship onto the evicted SUB# row and bounce as a misleading
-                // `forbidden`. Mark the doc gone (mapping the reason like the
-                // signed-in transport); the guest path has no resend / reverify
-                // timers to drain.
+                // would ship onto the evicted subscription record and bounce as a misleading
+                // `forbidden`. Drop the shed recovery first so nothing re-asserts an
+                // op onto an evicted subscription record, then mark the doc gone (mapping the
+                // reason like the signed-in transport).
+                clearShedRecovery();
+                outstanding.clear();
                 doc._markGone(goneReasonOf(frame));
             }
+            else if (isDocStatusFrame(frame)) {
+                // A guest can open a document whose inbound work is still running,
+                // and hydration writes a SNAPSHOT rather than ops, so nothing on the
+                // op stream would ever fill the view in. Same split as the signed-in
+                // transport: the `reload` hint pulls the content and emits the
+                // terminal status after the import, and anything else renders.
+                const status = normalizeWorkStatus(frame.status);
+                if (frame.reload)
+                    pullGuestContent(doc, token, lineId, status);
+                else
+                    doc._emitStatus(status);
+            }
+            else if (isDocMetaFrame(frame)) {
+                // `_setName` de-dupes, so a re-emit of the current name is a no-op.
+                doc._setName(frame.name);
+            }
             else if (canEdit && isOpAckFrame(frame)) {
+                outstanding.delete(frame.client_op_id);
                 doc.resolveOutstandingOp(frame.client_op_id);
+                // The server is durably accepting writes again, so the shed budget
+                // starts over. A round already scheduled still runs: the ops it
+                // re-asserts are the ones this ack did not cover.
+                shedRounds = 0;
+            }
+            else if (canEdit && isServerUnavailableFrame(frame)) {
+                onServerUnavailable();
             }
             else if (canEdit && isOpRejectedFrame(frame)) {
-                // A guest edit the server terminally rejected. No resend tracker here
-                // (guest transport is best-effort), so just fail the op on the doc so
-                // "could not be saved" surfaces instead of a stuck saving count.
+                // Terminal, not transient: stop re-asserting this op (retrying
+                // would only draw the same rejection) and fail it on the Document
+                // so "could not be saved" surfaces instead of a stuck saving count.
+                // A refusal naming the writer (an edit link downgraded or revoked
+                // while the guest had it open) turns the Document read-only, the
+                // same way it does for a signed-in reader.
+                outstanding.delete(frame.client_op_id);
+                if (isCapacityRejection(frame))
+                    doc._markAtCapacity();
+                const readOnly = readOnlyReasonForRejection(frame);
+                if (readOnly !== null)
+                    doc._markReadOnly(readOnly);
                 doc._failOutstandingOp(frame.client_op_id, opRejectedMessage(frame));
             }
-        });
+        }, 
+        // The guest owns its outstanding ops: `resendAllOutstanding` on the
+        // `doc_init` behind every `subscribed` ack IS this topic's
+        // re-assertion, so the client drops an op frame it cannot send now
+        // rather than buffering a second copy of it.
+        { ownsFrameRetry: true });
+        // An op the socket cannot carry, written over HTTP on the same policy
+        // the signed-in path runs: refuse locally what no write can hold, and
+        // re-assert a capacity refusal on the shared backoff before reporting it.
+        async function writeOversizedGuestOp(opBlobB64, clientOpId) {
+            // Yield before any outcome resolves the op. The hook's caller records
+            // the outstanding op AFTER the hook returns, and an async function body
+            // runs synchronously up to its first await, so an exit taken inline
+            // would find nothing tracked and leave the entry behind with
+            // `savingCount` stuck above zero.
+            await Promise.resolve();
+            // Both sizes are known here, so refuse without spending a round trip
+            // on a blob that can only come back 400.
+            if (opBlobExceedsDurableLimit(opBlobB64)) {
+                doc._failOutstandingOp(clientOpId, TOO_LARGE_MESSAGE);
+                return;
+            }
+            if (opBlobNeedsStaging(opBlobB64)) {
+                doc._failOutstandingOp(clientOpId, LINK_OP_TOO_LARGE_MESSAGE);
+                return;
+            }
+            let status = 0;
+            let parsed = undefined;
+            for (let round = 0; round <= UNAVAILABLE_MAX_ROUNDS; round += 1) {
+                if (round > 0) {
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(resolve, unavailableDelayMs(round));
+                        timer.unref?.();
+                    });
+                }
+                try {
+                    ({ status, parsed } = await postLinkOp(token, lineId, opBlobB64, clientOpId));
+                }
+                catch (err) {
+                    // A throw leaves it unknown whether the handler ran, and this op
+                    // carries no idempotency the server dedupes on, so replaying it
+                    // could double-apply.
+                    doc._failOutstandingOp(clientOpId, err instanceof Error ? err.message : String(err));
+                    return;
+                }
+                if (status >= 200 && status < 300)
+                    break;
+                if (!opWriteIsRetryable(status))
+                    break;
+            }
+            if (status < 200 || status >= 300) {
+                doc._failOutstandingOp(clientOpId, opWriteIsRetryable(status)
+                    ? UNAVAILABLE_GIVE_UP_MESSAGE
+                    : opWriteFailureMessage(status, parsed));
+                return;
+            }
+            doc.resolveOutstandingOp(clientOpId);
+        }
         if (canEdit) {
             const minter = opts.newClientOpId ?? defaultClientOpIdMinter;
             doc.setLocalOpHook((opBlob) => {
                 const clientOpId = minter();
-                wsClient.send({
+                const opBlobB64 = bytesToBase64(opBlob);
+                const sendFrame = {
                     type: 'op',
                     topic,
-                    op_blob: bytesToBase64(opBlob),
+                    op_blob: opBlobB64,
                     client_op_id: clientOpId,
-                });
+                };
+                // A frame past the transport's cap is not delivered and takes the
+                // connection down with it, so it must never reach the socket: a
+                // guest's document, presence and every other op ride that one
+                // connection. `mutate` batches to a budget well above what a frame
+                // carries, so an ordinary bulk edit arrives here.
+                if (opFrameExceedsWsLimit(sendFrame)) {
+                    void writeOversizedGuestOp(opBlobB64, clientOpId);
+                    return clientOpId;
+                }
+                outstanding.set(clientOpId, sendFrame);
+                wsClient.send(sendFrame);
                 return clientOpId;
             });
         }
         const originalClose = doc.close.bind(doc);
         doc.close = () => {
+            clearShedRecovery();
             try {
                 unsub();
             }
@@ -1366,13 +1975,71 @@ export function createOpenDocument(opts) {
             originalClose();
         };
     }
+    // Guest documents with a content pull running, so a repeated terminal frame
+    // does not stack a second pull on one document.
+    const guestPullInFlight = new WeakSet();
+    function pullGuestContent(doc, token, lineId, finalStatus) {
+        if (guestPullInFlight.has(doc))
+            return;
+        guestPullInFlight.add(doc);
+        void (async () => {
+            await pullContentWithRetry({
+                doc,
+                docId: doc.id ?? '',
+                finalStatus,
+                fetchAndImport: () => importLinkView(doc, token, lineId),
+                ...(opts.reportError ? { reportError: opts.reportError } : {}),
+            });
+            guestPullInFlight.delete(doc);
+        })();
+    }
+    // Re-read the link view and import it into the live guest Document: the
+    // anonymous counterpart of the signed-in `refetchAndImport`, over the same
+    // envelope. Named on the line the guest opened, which is the line its topic
+    // is scoped to.
+    async function importLinkView(doc, token, lineId) {
+        const result = await fetchLinkView(token, lineId);
+        if (result.status < 200 || result.status >= 300) {
+            return { ok: false, reason: `link view returned ${result.status}` };
+        }
+        const b = result.parsed;
+        if (!Array.isArray(b.tail_ops)) {
+            return { ok: false, reason: 'malformed link view response' };
+        }
+        const snap = b.snapshot;
+        let snapshotBytes = null;
+        if (snap !== null && snap !== undefined && snap.kind === 'inline') {
+            snapshotBytes = base64ToBytes(snap.data_b64);
+        }
+        else if (snap !== null && snap !== undefined && snap.kind === 'presigned') {
+            try {
+                snapshotBytes = await fetchPresignedSnapshot(snap.url);
+            }
+            catch (err) {
+                const status = err instanceof BrassError ? err.status ?? 0 : 0;
+                return {
+                    ok: false,
+                    reason: status > 0
+                        ? `presigned snapshot fetch returned ${status}`
+                        : `presigned snapshot fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        if (snapshotBytes)
+            doc._applySnapshot(snapshotBytes);
+        const tail = b.tail_ops;
+        for (const entry of [...tail].sort((x, y) => x.seq - y.seq)) {
+            doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
+        }
+        return { ok: true };
+    }
     // Strict open: a 404 propagates as `BrassError`. A `version` option
     // diverts to the read-only at-version path.
     const open = async (docId, options) => {
         // Cache hit: return the parked Document. Its subscription stayed alive
         // while parked, and the UndoController + outstanding-op map survived, so
         // undo works as if the user never switched away.
-        const parked = takeParkedDocument(docId, options);
+        const parked = takeParkedDocument(docId, options, opts.identity?.() ?? null);
         if (parked) {
             parked._resume();
             return parked;
@@ -1438,6 +2105,13 @@ export function createOpenDocument(opts) {
 // state to keep. Module-scoped so it persists across factory invocations in
 // one process; keys are app-supplied so no cross-app leak within a tab.
 const PARK_CACHE_CAPACITY = 4;
+function documentOptionsSig(options) {
+    return JSON.stringify([
+        options?.rootKey ?? null,
+        options?.readOnly ?? null,
+        options?.undo ?? null,
+    ]);
+}
 const parkedDocs = new Map();
 function parkCacheKey(docId, branchId, streamName) {
     // Skip caching when the branch is unknown: the next open() may resolve to
@@ -1451,7 +2125,23 @@ function parkCacheKey(docId, branchId, streamName) {
     // caller's document out from under it.
     return `${docId}/${branchId}/${streamName ?? DEFAULT_STREAM_NAME}`;
 }
+function evictParked(entry) {
+    if (!entry)
+        return;
+    parkedDocs.delete(entry.key);
+    try {
+        entry.teardown();
+    }
+    catch {
+        // Teardown errors must not strand the cache; the evicted Doc is gone
+        // from the user's perspective either way.
+    }
+}
 function parkDocument(entry) {
+    // One Document per key: whatever sat here is unreachable the moment this
+    // entry replaces it, so it is torn down rather than left holding a live
+    // subscription nothing can close.
+    evictParked(parkedDocs.get(entry.key));
     parkedDocs.set(entry.key, entry);
     // Map iteration is insertion order, so evicting the front entry is LRU
     // (a newly parked entry is the most-recent; a hit removes the entry
@@ -1460,18 +2150,10 @@ function parkDocument(entry) {
         const oldestKey = parkedDocs.keys().next().value;
         if (oldestKey === undefined)
             break;
-        const oldest = parkedDocs.get(oldestKey);
-        parkedDocs.delete(oldestKey);
-        try {
-            oldest?.teardown();
-        }
-        catch {
-            // Teardown errors must not strand the cache; the evicted Doc is gone
-            // from the user's perspective either way.
-        }
+        evictParked(parkedDocs.get(oldestKey));
     }
 }
-function takeParkedDocument(docId, options) {
+function takeParkedDocument(docId, options, identity) {
     if (options?.version !== undefined)
         return null;
     const key = parkCacheKey(docId, options?.branch, options?.stream);
@@ -1480,22 +2162,36 @@ function takeParkedDocument(docId, options) {
     const entry = parkedDocs.get(key);
     if (!entry)
         return null;
+    // A Document the server evicted while it was parked describes a document
+    // that is no longer there, one built from different `documentOptions` is
+    // not the Document this caller asked for, and one opened for a different
+    // person is not this caller's to read. All three take the fresh open, which
+    // for the last is the request that establishes the new caller may have it;
+    // the parked copy goes with its subscription.
+    if (entry.doc._goneReason !== null ||
+        entry.optionsSig !== documentOptionsSig(options?.documentOptions) ||
+        entry.identity !== identity) {
+        evictParked(entry);
+        return null;
+    }
     parkedDocs.delete(key);
     return entry.doc;
 }
-// Test-only: drop the parking cache. Used by unit tests that need
-// a clean slate between cases.
-export function _resetParkCacheForTesting() {
+/** Retire every parked Document. The client calls this as an identity leaves
+ *  the page, so what the previous person opened is torn down rather than left
+ *  resident for the rest of the tab's life.
+ *  @internal */
+export function clearParkedDocuments() {
     for (const entry of parkedDocs.values()) {
-        try {
-            entry.teardown();
-        }
-        catch {
-            // ignore
-        }
+        evictParked(entry);
     }
     parkedDocs.clear();
 }
+// Test-only: drop the parking cache. Used by unit tests that need
+// a clean slate between cases.
+export function _resetParkCacheForTesting() {
+    clearParkedDocuments();
+}
 // Wire the WS transport onto a materialised Document. Three pieces:
 //   1. WS subscribe on the doc topic; the server sends `doc_op` (other
 //      clients' edits) and `op_ack` (our ops), topic-scoped so the
@@ -1519,17 +2215,76 @@ export const PERIODIC_REVERIFY_INTERVAL_MS = 5 * 60_000;
 // delay is an op the server will not send again. Exported for the
 // fake-timer test.
 export const MISSED_OP_RESYNC_DELAY_MS = 2_000;
+// Per-op resend backoff: 1.5s, ~1.6x per attempt, to a 30s ceiling. The
+// ceiling keeps a doc on a dead connection from hammering; the
+// reconnect-driven resend (`resendAllOutstanding`) fires the instant
+// `doc_init` arrives, so the ceiling never delays recovery past the next
+// reconnect. Exported for the fake-timer tests.
+export const RESEND_BASE_DELAY_MS = 1_500;
+export const RESEND_MAX_DELAY_MS = 30_000;
+// How long the oldest op on the socket may go unacked before its resend
+// timer spends an attempt even though the connection is answering other
+// ops. See `scheduleResend` for what this bounds and why only the oldest op
+// reaches it.
+//
+// The value sits above every latency a working connection produces. Acks
+// measured on a deployed environment run 175 ms at p99 and 1.6 s at their
+// worst, and an op whose own backoff has grown to `RESEND_MAX_DELAY_MS` is
+// still well inside this, so a queue that is merely slow never reaches it and
+// the timer keeps re-arming free. Sitting above the backoff ceiling is also
+// what makes this value, rather than the backoff, the interval a forced
+// resend is paced at: the timer fires several times inside one window, and
+// the first expiry past the window is the one that spends.
+//
+// What a false positive costs bounds the risk of setting it at all: one
+// duplicate op per document per window, which is a Loro no-op on import. The
+// failure this replaces is unbounded in the other direction, an op the
+// server never received and nothing ever sends again.
+// Exported for the fake-timer tests.
+export const RESEND_FORCE_CEILING_MS = 60_000;
+// Server-shed recovery policy, driven by `unavailable` error frames. The
+// frame names no op, so a round re-asserts every outstanding op at once and
+// any further frame arriving before that round runs is part of the same shed
+// batch: coalescing them is what keeps N shed ops from fanning out into N
+// rounds of N resends. Backoff is 1s doubling to a 30s ceiling, so the budget
+// spans roughly a minute and a half of sustained shedding. An `op_ack` (the
+// server taking writes again) or a reconnect returns the budget to full.
+//
+// Module-scoped because both transports answer a shed on it: the signed-in
+// one, the HTTP write for an op past the frame cap, and the guest-link one.
+// A shed costs an edit the same nothing whoever wrote it and whichever
+// transport carried it.
+const UNAVAILABLE_MAX_ROUNDS = 6;
+const UNAVAILABLE_BASE_DELAY_MS = 1000;
+const UNAVAILABLE_MAX_DELAY_MS = 30_000;
+const UNAVAILABLE_GIVE_UP_MESSAGE = 'The server could not store this change, and re-sending it did not ' +
+    'help. Reload the document to continue from the last saved state.';
+// Reported for every op left behind when the server ends this document's
+// subscription (it refused the subscribe, or evicted it again after the one
+// silent re-subscribe a connection grants). The ops can never be acked on a
+// subscription that is over, and a fresh one arrives only with a fresh open,
+// so the app's cue is to reload.
+const SUBSCRIPTION_ENDED_MESSAGE = 'The live connection to this document ended, so this change was not ' +
+    'saved. Reload the document to continue from the last saved state.';
+/** How long the Nth (1-based) recovery round waits before re-asserting. */
+function unavailableDelayMs(round) {
+    return Math.min(UNAVAILABLE_BASE_DELAY_MS * Math.pow(2, round - 1), UNAVAILABLE_MAX_DELAY_MS);
+}
 // A mutation carrying many records commits as it goes, so the only write
 // that reaches this is one record nothing can split.
 const TOO_LARGE_MESSAGE = 'This record is too large to save. A single record must fit in one ' +
     'update; store the bulk of it as a file instead, or split it across ' +
     'several records.';
+// What a guest hears for an op no request body can carry. A signed-in
+// editor stages such an op to storage first; that route is behind the
+// sign-in gate, so the anonymous tier writes ops that fit one request.
+const LINK_OP_TOO_LARGE_MESSAGE = 'This change is too large to save over a shared link. Sign in to the ' +
+    'document to make a change this size.';
 function wireDocTransport(args) {
     const topic = `doc:${args.docId}:${args.branchId}`;
-    // Per-op retry tracker. The op-write endpoint sometimes returns
-    // `{"message": "Internal server error"}` without reaching the handler
-    // (burst input against a cold-started server giving up before scale-up).
-    // That frame has no `type`, so the multiplexer drops it,
+    // Per-op retry tracker. The op-write endpoint can answer with an untyped
+    // error frame instead of reaching the handler. That frame has no `type`, so
+    // the multiplexer drops it,
     // leaving the op stuck in `Document._outstandingByClientId` and the
     // actor's lamport stream with a gap that blocks other subscribers' Loro
     // imports from converging (Loro requires per-actor causal contiguity).
@@ -1541,7 +2296,130 @@ function wireDocTransport(args) {
     // retry lands the dependent chain converges everywhere. `doc.savingCount`
     // stays above zero until the `op_ack` lands (the "Saving…" surface); there
     // is no give-up to surface because the SDK keeps trying.
+    // When each op this transport shipped was first committed, keyed the same
+    // way the tracker is. The tracker itself carries no commit time (its
+    // `dispatchedAt` restarts on every resend, which is the right basis for
+    // deciding a resend and the wrong one for reporting how long a reader has
+    // been waiting), and an op past the frame cap is never in the tracker at
+    // all. Entries are dropped as their op settles, so the map's size is the
+    // work outstanding on either transport.
+    const opStartedAt = new Map();
+    // Reconnects the socket had made when this transport last saw a
+    // `doc_init`. The frame itself is not a reconnect signal: it rides every
+    // `subscribed` ack, including the opening one and the silent re-subscribe
+    // a connection grants after a mid-stream eviction, neither of which
+    // involved the socket dropping. A report keyed off the frame therefore
+    // fires when nothing is wrong, which is the fault this latch exists to
+    // avoid, so it is keyed off the socket instead.
+    let docInitReconnectCount = null;
     const outstandingResends = new Map();
+    // How many bytes of op frames may be on the socket unacked at once.
+    //
+    // The transport drops the connection when a client pushes at it hard
+    // enough, and it takes everything multiplexed onto that socket with it;
+    // every op then goes unacked, the reconnect re-asserts them, and that
+    // burst drops the connection again, so nothing is ever persisted.
+    // Measured against one write, a client pushing 26 frames in 320 ms lost
+    // the socket where one spreading 90 frames over 5.3 s did not, so what
+    // this bounds is the RATE rather than any one frame's size.
+    //
+    // Which shape reaches it is worth knowing before tuning it. A bulk write
+    // does not: `mutate` batches to a budget far above what a frame carries,
+    // so its ops take the HTTP write and never enter this queue. What does is
+    // an app issuing many separate mutations that each land under the frame
+    // cap, a drag loop or a per-row import, where the op count is set by how
+    // often the app calls rather than by how much it writes.
+    //
+    // A byte budget rather than a rate is what makes this self-tuning: sends
+    // resume as acks land, so the client goes exactly as fast as the server
+    // is answering and no faster, whatever that speed turns out to be. The
+    // budget is generous enough to keep several ops in flight, so an ack's
+    // round trip is not serialised into the write.
+    const IN_FLIGHT_BUDGET_BYTES = 256 * 1024;
+    // Ops committed but not yet on the socket, oldest first.
+    const sendQueue = [];
+    let inFlightBytes = 0;
+    /** Put an op on the socket if the budget allows, else queue it. */
+    function dispatchOp(clientOpId) {
+        const entry = outstandingResends.get(clientOpId);
+        if (!entry || entry.inFlight > 0)
+            return;
+        const size = entry.frame.op_blob.length;
+        // An op larger than the whole budget goes on its own rather than
+        // waiting for room that can never appear.
+        if (inFlightBytes > 0 && inFlightBytes + size > IN_FLIGHT_BUDGET_BYTES) {
+            if (!entry.queued) {
+                entry.queued = true;
+                entry.dispatchedAt = 0;
+                sendQueue.push(clientOpId);
+            }
+            return;
+        }
+        entry.queued = false;
+        entry.inFlight = size;
+        entry.dispatchedAt = Date.now();
+        inFlightBytes += size;
+        args.wsClient.send(entry.frame);
+        scheduleResend(clientOpId);
+    }
+    /** The oldest op currently on the socket, which is the one a gap blocks
+     *  the rest of this actor's stream behind. Map order is commit order, and
+     *  an op waiting on the in-flight budget carries no timer, so the first
+     *  dispatched entry is that op. */
+    function isOldestDispatchedOp(clientOpId) {
+        for (const [id, entry] of outstandingResends) {
+            if (entry.dispatchedAt === 0)
+                continue;
+            return id === clientOpId;
+        }
+        return false;
+    }
+    /** Send whatever the freed budget now has room for. */
+    function drainSendQueue() {
+        while (sendQueue.length > 0) {
+            const next = sendQueue[0];
+            const entry = outstandingResends.get(next);
+            // An op acked, rejected or abandoned while queued leaves its id behind;
+            // dropping it here is what keeps `forgetOp` off a queue scan.
+            if (!entry || !entry.queued) {
+                sendQueue.shift();
+                continue;
+            }
+            const size = entry.frame.op_blob.length;
+            if (inFlightBytes > 0 && inFlightBytes + size > IN_FLIGHT_BUDGET_BYTES) {
+                return;
+            }
+            sendQueue.shift();
+            entry.queued = false;
+            dispatchOp(next);
+        }
+    }
+    /** Drop one op from the tracker, returning its budget. */
+    function forgetOp(clientOpId) {
+        const entry = outstandingResends.get(clientOpId);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        inFlightBytes -= entry.inFlight;
+        entry.inFlight = 0;
+        entry.queued = false;
+        outstandingResends.delete(clientOpId);
+        opStartedAt.delete(clientOpId);
+        drainSendQueue();
+    }
+    /** Drop every tracked op and reset the budget with them. */
+    function forgetAllOps() {
+        for (const [clientOpId, entry] of outstandingResends) {
+            clearTimeout(entry.timer);
+            // Only the ops this tracker holds. An op past the frame cap is
+            // travelling over HTTP and is not in here, so clearing the whole
+            // timing map would report it settled while its write is still going.
+            opStartedAt.delete(clientOpId);
+        }
+        outstandingResends.clear();
+        sendQueue.length = 0;
+        inFlightBytes = 0;
+    }
     // Ops this client is writing over HTTP, and the highest seq a catch-up
     // prompt named while one was in flight.
     //
@@ -1564,44 +2442,388 @@ function wireDocTransport(args) {
         const seq = heldCatchUpSeq;
         heldCatchUpSeq = 0;
         if (seq > 0 && args.getCoveredSeq() < seq)
-            args.resyncFromSnapshot?.();
-    }
-    // Backoff: 1.5s, ~1.6x per attempt, ceiling 30s. The ceiling keeps a doc
-    // on a dead connection from hammering; the reconnect-driven resend below
-    // fires the instant `doc_init` arrives, so the ceiling never delays
-    // recovery past the next reconnect.
-    const RESEND_BASE_DELAY_MS = 1500;
-    const RESEND_MAX_DELAY_MS = 30_000;
+            pullJoin();
+    }
+    // Pull the join, and ask again if it left the reader short.
+    //
+    // A join read while a peer writes in bulk is a torn cut: the branch's seq
+    // counter has run ahead of the op rows, so the response reports a head it
+    // could not deliver the tail for. The reader applies what arrived and its
+    // floor lands below that head, and nothing re-sends the difference. So
+    // whatever the reader still lacks after an import is a hole it has to ask
+    // about itself, which is what a passive reader has instead of the `doc_op`
+    // and `op_ack` frames a writing client arms its checks from.
+    function pullJoin() {
+        void Promise.resolve(args.resyncFromSnapshot?.()).then(() => {
+            scheduleGapCheck();
+        }, () => {
+            // `resyncFromSnapshot` reports its own failures and resolves; a
+            // rejection is a caller that does not, and asking again is still the
+            // right move.
+            scheduleGapCheck();
+        });
+    }
+    // Re-import the join for ops this client cannot bridge to from what it
+    // holds, deferring the judgement while one of its own HTTP writes is still
+    // in flight. Shared by the catch-up prompt and by the reconnect handshake,
+    // which reaches the same conclusion off its tail.
+    // Re-import when the durable frontier names an author whose changes never
+    // came through the op stream. Separate from the coverage check because it
+    // answers a different question: not "did I miss an op" but "did what I hold
+    // stop being how this document is stored".
+    function maybeResyncPastRewrite(vectorB64) {
+        if (!vectorB64)
+            return;
+        let unseen = false;
+        try {
+            unseen = args.doc._snapshotHasUnseenAuthor(base64ToBytes(vectorB64));
+        }
+        catch {
+            return;
+        }
+        if (unseen)
+            pullJoin();
+    }
+    function resyncPastSeq(seq) {
+        if (httpOpWritesInFlight > 0) {
+            if (seq > heldCatchUpSeq)
+                heldCatchUpSeq = seq;
+            return;
+        }
+        pullJoin();
+    }
     function resendDelayMs(attempts) {
         const grown = RESEND_BASE_DELAY_MS * Math.pow(1.6, attempts - 1);
         return Math.min(grown, RESEND_MAX_DELAY_MS);
     }
+    // When this connection last proved it was working: any `op_ack`, from any
+    // op on this topic.
+    //
+    // What this timer is for is a server that answered NOTHING, which is a
+    // real case (an op frame can draw the opaque `{"message":"Internal server
+    // error"}` reply the multiplexer drops). What it must not read as silence
+    // is an ack that is merely behind, because with many ops in flight one
+    // op's latency is the queue's depth times its service time, not evidence
+    // about that op. Resending on that reading writes the op a second time,
+    // which deepens the queue, which slows the next ack, which fires more
+    // resends.
+    //
+    // Measured on a 500,000-element write: the same content went through in
+    // 1,320 op writes on a run whose acks stayed under 375 ms, and in 3,600 on
+    // a run whose acks reached 1,615 ms, just past this backoff's first step.
+    // The extra writes are durable duplicates, so they inflate the document's
+    // history, and every later compaction pays for them: the run that tripled
+    // its ops left a tail compaction could not absorb inside its memory, and
+    // the document stopped opening.
+    //
+    // So the timer fires on silence rather than on slowness: an ack that
+    // arrived after this op's timer was armed re-arms it without spending an
+    // attempt, within the bound `forceResendDue` puts on how long one op may
+    // ride that evidence.
+    let lastAckAt = 0;
     function scheduleResend(clientOpId) {
         const entry = outstandingResends.get(clientOpId);
         if (!entry)
             return;
+        entry.armedAt = Date.now();
         entry.timer = setTimeout(() => {
             const current = outstandingResends.get(clientOpId);
             if (!current)
                 return;
+            const forced = forceResendDue(clientOpId, current);
+            if (lastAckAt >= current.armedAt && !forced) {
+                scheduleResend(clientOpId);
+                return;
+            }
+            // A forced resend is the transport concluding this op was lost, which
+            // is the one condition here the server cannot infer, so it is what the
+            // report is pinned to.
+            if (forced)
+                reportSyncHealth('op_stuck');
             current.attempts += 1;
+            current.dispatchedAt = Date.now();
             args.wsClient.send(current.frame);
             scheduleResend(clientOpId);
         }, resendDelayMs(entry.attempts));
     }
+    // The one case where an answering connection is still evidence this op was
+    // lost: it is the oldest op on the socket and it has been there longer than
+    // any working connection takes to answer.
+    //
+    // The evidence `lastAckAt` carries is that the connection is working, not
+    // that it received this op, so an app committing faster than the backoff
+    // supplies that evidence continuously and a dropped op would re-arm free
+    // forever. The server's copy of the document then stops at the gap (Loro
+    // requires per-actor causal contiguity, so every later op is stored and
+    // never applied), the tracker entry never reaches a terminal state, and the
+    // app is told nothing.
+    //
+    // Ack ORDER cannot stand in for that evidence. Acks overtake heavily: 24
+    // ops sent back to back on a deployed environment came back with 10 of 23
+    // adjacent pairs out of send order, and the op sent first was acked 23rd. A
+    // rule reading a later op's ack as proof this one was skipped re-sends ops
+    // that are merely in flight, which is the write-it-twice failure the gate
+    // above exists to prevent.
+    //
+    // Restricting this to the oldest dispatched op is what keeps the traffic
+    // bounded and is sufficient. Bounded: one op per ceiling window however
+    // many ops are outstanding, which matters because this resend hands the
+    // frame straight to `wsClient.send` and so spends none of the in-flight
+    // budget, and a simultaneous round of them is the burst that drops the
+    // socket. Sufficient: the gap at the oldest op is what holds the rest of
+    // this actor's stream unapplied, and an op behind it becomes the oldest in
+    // its turn as the ops in front retire.
+    function forceResendDue(clientOpId, entry) {
+        if (entry.dispatchedAt === 0)
+            return false;
+        if (Date.now() - entry.dispatchedAt <= RESEND_FORCE_CEILING_MS)
+            return false;
+        return isOldestDispatchedOp(clientOpId);
+    }
+    // What this transport knows about its own sync, for a reader whose save
+    // is taking longer than it should. Everything here is closure state the
+    // transport already keeps; collecting it costs a walk of the outstanding
+    // ops, so it is safe to call from a render.
+    function collectDiagnostics() {
+        const now = Date.now();
+        let oldestClientOpId = null;
+        let oldestStartedAt = 0;
+        // Insertion order is commit order, so the first entry is the oldest.
+        for (const [clientOpId, startedAt] of opStartedAt) {
+            oldestClientOpId = clientOpId;
+            oldestStartedAt = startedAt;
+            break;
+        }
+        return {
+            unackedOps: opStartedAt.size,
+            oldestUnackedMs: oldestClientOpId === null ? 0 : Math.max(0, now - oldestStartedAt),
+            oldestClientOpId,
+            reconnects: args.wsClient.reconnectCount ?? 0,
+            lastAckAgeMs: lastAckAt === 0 ? null : Math.max(0, now - lastAckAt),
+            inFlightBytes,
+            httpOpsInFlight: httpOpWritesInFlight,
+            healRounds: divergenceHealRound,
+            hidden: args.wsClient.pageHidden ?? false,
+        };
+    }
+    // Push the same picture to the server, so an incident on a device with no
+    // console attached leaves a record an operator can find. Sent on the
+    // conditions the client can recognise and the server cannot, each of
+    // which is already bounded by the machinery that detects it: a forced
+    // resend fires at most once per ceiling window, a reconnect is one
+    // socket, and a heal round is one push. The server drops the excess
+    // anyway.
+    //
+    // Fire-and-forget by design. The frame carries no `client_op_id` of its
+    // own and draws no reply, so it never joins the outstanding-op tracker
+    // and a report cannot become one more thing a stuck document is waiting
+    // on.
+    function reportSyncHealth(reason) {
+        // Only worth sending while the socket can carry it. Held through an
+        // outage, a report flushes on the re-subscribe describing state from
+        // before the outage, and it arrives on the new connection ahead of the
+        // accurate one the reconnect itself produces, so the stale figures are
+        // what the server's one-per-connection budget accepts.
+        if (args.wsClient.connected === false)
+            return;
+        const d = collectDiagnostics();
+        args.wsClient.send({
+            type: 'client_report',
+            topic,
+            client_report: {
+                reason,
+                unacked_ops: d.unackedOps,
+                oldest_unacked_ms: d.oldestUnackedMs,
+                ...(d.oldestClientOpId === null
+                    ? {}
+                    : { oldest_client_op_id: d.oldestClientOpId }),
+                reconnects: d.reconnects,
+                last_ack_age_ms: d.lastAckAgeMs,
+                in_flight_bytes: d.inFlightBytes,
+                http_ops_in_flight: d.httpOpsInFlight,
+                heal_rounds: d.healRounds,
+                hidden: d.hidden,
+            },
+        });
+    }
+    args.doc._setDiagnosticsProvider(collectDiagnostics);
     // Resend every outstanding op now and restart its backoff. Called on
     // reconnect (`doc_init`): a dropped-and-restored connection is the most
     // common reason an op went unacked, and the backoff may have grown to its
     // ceiling while the socket was down, so re-asserting immediately is the
     // fast recovery path.
     function resendAllOutstanding() {
+        // Nothing is on the wire any more, whether this follows a reconnect or a
+        // shed, so the budget starts empty and every op re-enters through it.
+        // Sending them all at once is what turns one dropped connection into a
+        // loop that never persists anything: the burst that lost the socket is
+        // exactly the burst the reconnect would repeat.
+        inFlightBytes = 0;
+        sendQueue.length = 0;
+        // Insertion order is the order the ops were committed in, so a round
+        // re-asserts them oldest-first.
         for (const [clientOpId, entry] of outstandingResends) {
             clearTimeout(entry.timer);
             entry.attempts += 1;
-            args.wsClient.send(entry.frame);
-            scheduleResend(clientOpId);
+            entry.inFlight = 0;
+            entry.queued = false;
+            dispatchOp(clientOpId);
         }
     }
+    let unavailableRounds = 0;
+    let unavailableTimer = null;
+    function clearUnavailableRecovery() {
+        if (unavailableTimer !== null) {
+            clearTimeout(unavailableTimer);
+            unavailableTimer = null;
+        }
+        unavailableRounds = 0;
+    }
+    // Every outstanding op is dead: drop the tracker entries and tell the
+    // Document, which stops counting them in `savingCount` and reports each
+    // through the error channel the app reads (`Brass.onError`). The ids are
+    // taken first because `_failOutstandingOp` re-enters app code.
+    //
+    // Dropping the ops is what opens the divergence, so the heal is armed here
+    // rather than at the call site: the local doc keeps the abandoned ops and
+    // keeps accepting edits that depend on them, and only the handshake can
+    // hand the server the slice it needs to apply any of it.
+    function failAllOutstanding(message) {
+        const clientOpIds = [...outstandingResends.keys()];
+        forgetAllOps();
+        for (const clientOpId of clientOpIds) {
+            args.doc._failOutstandingOp(clientOpId, message);
+        }
+        if (clientOpIds.length > 0) {
+            divergenceHealRound = 0;
+            scheduleDivergenceHeal();
+        }
+    }
+    // One op is dead: report it and arm the heal, for the same reason
+    // `failAllOutstanding` does. The op stays applied locally and every edit
+    // made after it depends on it, so the server holds a stream it can store
+    // and never apply, and its own escape for an op nothing can apply is to
+    // discard it. Most refusals do not change that: the handshake pushes
+    // whatever slice the durable frontier is missing and splits it under the
+    // frame cap, so it heals the dependents even where the op itself is
+    // irreducibly too large to re-send.
+    //
+    // `healable: false` is for the refusal where pushing again is asking the
+    // same question. A full document refuses every op whatever its size, so
+    // the handshake's own chunks come back refused, and the counter reset
+    // below turns that into a loop rather than a bounded retry. What recovers
+    // that document is the periodic re-verify, once the server can take a
+    // write at all.
+    // A refusal the heal cannot work around leaves the writer holding a change
+    // that reached no database and no other reader, so the writer is the only
+    // copy of the document that shows it. Left editable it reads as applied: the
+    // element is on screen, the count includes it, every later edit builds on
+    // it, and a reader who opens the document sees none of it. Nothing local
+    // removes it either, because a CRDT merges rather than replaces and an undo
+    // inverts an operation instead of discarding it, so the only state holding
+    // exactly what is durable is one built from the server.
+    //
+    // Stopping the divergence and resolving it are separated, because they cost
+    // different things and doing them in one silent step is what made a refusal
+    // read as the platform losing work. Stopping is free and immediate:
+    // `readOnly` turns true, which closes an app's existing edit gate, so the
+    // copy cannot drift further. Resolving discards the refused work and swaps
+    // the document under whoever was working in it, so the user is told first
+    // and the reload follows their acknowledgement.
+    //
+    // The telling is the SDK's job rather than each app's. A copy left showing a
+    // change nothing else has is the failure being closed, so an app that
+    // renders no surface for this cannot be the reason a user stays on one.
+    //
+    // Once per document. The first refusal is what diverged this copy, so the
+    // later ones describe the same state and have nothing to add.
+    let lockedForRefusal = false;
+    function lockForUnhealableRefusal(message) {
+        if (lockedForRefusal)
+            return;
+        lockedForRefusal = true;
+        // Torn down in the order the `doc_gone` handler uses, and for the same
+        // reason: every one of these keeps working against a copy that is now
+        // read-only, and the resync push in particular would re-offer the refused
+        // op this exists to stop.
+        forgetAllOps();
+        clearUnavailableRecovery();
+        if (reverifyTimer !== null) {
+            clearInterval(reverifyTimer);
+            reverifyTimer = null;
+        }
+        clearDivergenceHeal();
+        if (gapTimer !== null) {
+            clearTimeout(gapTimer);
+            gapTimer = null;
+        }
+        args.doc._markReadOnly('unsaved');
+        // The user is told by the SDK, not by each app, because an app that
+        // renders nothing is exactly the case this has to cover: a document that
+        // reloaded and a document that reloaded for a reason look the same
+        // otherwise. `alert` holds the main thread until it is acknowledged, so
+        // the reason cannot be missed and the reload lands on a page the user
+        // is looking at. A browser that suppresses the dialog returns from it
+        // immediately, which reloads rather than skipping, and a caller outside
+        // a browser (a worker, a test) has nobody to tell and does the same.
+        //
+        // The reload survives a dialog that throws, which is the one way telling
+        // the user could cost them the fix: `alert` is a page-global an app is
+        // free to replace, and the copy this leaves behind is the diverged one
+        // the reload exists to discard.
+        try {
+            if (typeof alert === 'function')
+                alert(message);
+        }
+        catch {
+            // Told or not, the copy is resolved.
+        }
+        args.doc.reload();
+    }
+    function failOpTerminally(clientOpId, message, opts = {}) {
+        // Read before `_failOutstandingOp`, which clears the id from the
+        // resync-push set on its way out.
+        const wasHealPush = args.doc._isResyncPushOp(clientOpId);
+        opStartedAt.delete(clientOpId);
+        // A refusal the heal cannot answer is about the document, so it answers
+        // every op in flight the same way and is reported once, by the lock. Per
+        // op, a bulk write's outstanding ops each produce an identical error, so
+        // the reader watches the same message arrive dozens of times before the
+        // one dialog that explains it.
+        args.doc._failOutstandingOp(clientOpId, message, {
+            report: opts.report ?? true,
+        });
+        if (opts.healable === false) {
+            lockForUnhealableRefusal(message);
+            return;
+        }
+        // Restart the backoff only for a failure the heal did not itself
+        // produce. A refused heal chunk that zeroed the round count would keep
+        // the bound from ever binding: each round pushes, each push is refused,
+        // and each refusal buys another round. Leaving the count alone lets the
+        // rounds run out the way an unanswered handshake already does.
+        if (!wasHealPush)
+            divergenceHealRound = 0;
+        scheduleDivergenceHeal();
+    }
+    function onServerUnavailable() {
+        if (outstandingResends.size === 0)
+            return;
+        if (unavailableTimer !== null)
+            return;
+        unavailableRounds += 1;
+        if (unavailableRounds > UNAVAILABLE_MAX_ROUNDS) {
+            clearUnavailableRecovery();
+            failAllOutstanding(UNAVAILABLE_GIVE_UP_MESSAGE);
+            return;
+        }
+        const delay = unavailableDelayMs(unavailableRounds);
+        unavailableTimer = setTimeout(() => {
+            unavailableTimer = null;
+            resendAllOutstanding();
+        }, delay);
+        unavailableTimer.unref?.();
+    }
     // Durability handshake, run on every `doc_init`. The persisted version
     // vector + durable tail ops define the durable frontier; if the local doc
     // holds CRDT knowledge beyond it (an op acked then discarded by the
@@ -1613,7 +2835,12 @@ function wireDocTransport(args) {
     function maybeResyncPush(snapshotVersionVectorB64, durableTailBlobs) {
         if (!snapshotVersionVectorB64)
             return;
-        args.doc.maybeResyncPush(base64ToBytes(snapshotVersionVectorB64), durableTailBlobs);
+        const outcome = args.doc.maybeResyncPush(base64ToBytes(snapshotVersionVectorB64), durableTailBlobs);
+        // Reported here as well as from the re-verify, or the record holds only
+        // the heals that took the slower route and an operator reading it cannot
+        // tell that the ordinary reconnect handshake is missing from the set.
+        if (outcome === 'pushed')
+            reportSyncHealth('divergence_healed');
     }
     // Re-fetch the durable frontier from the HTTP join and run the handshake.
     // Shared by the `doc_ops_dropped` prompt path and the periodic re-verify:
@@ -1630,66 +2857,217 @@ function wireDocTransport(args) {
     let reverifyAgain = false;
     // Armed after the subscription is wired, cleared on `doc_gone` and teardown.
     let reverifyTimer = null;
+    // The last run's verdict, so a caller healing a known divergence can tell a
+    // finished handshake from one that fetched nothing.
     async function reverifyDurability() {
         if (reverifyInFlight) {
             reverifyAgain = true;
-            return;
+            return 'in-flight';
         }
         reverifyInFlight = true;
+        let outcome = 'no-fetch';
         try {
             do {
                 reverifyAgain = false;
                 try {
                     const frontier = await args.refetchDurableFrontier?.();
                     if (frontier && frontier.snapshotVersionVector) {
-                        args.doc.maybeResyncPush(base64ToBytes(frontier.snapshotVersionVector), frontier.tailBlobs);
+                        outcome = args.doc.maybeResyncPush(base64ToBytes(frontier.snapshotVersionVector), frontier.tailBlobs);
+                        // The handshake having work to do means the server's copy was
+                        // behind this client's, which is the state a lost op leaves and
+                        // which nothing on the server side reports.
+                        if (outcome === 'pushed')
+                            reportSyncHealth('divergence_healed');
                     }
                 }
                 catch {
                     // Best-effort: a failed re-fetch defers the check to the next tick
                     // or reconnect's `doc_init` handshake. Swallowed so the timer's
                     // fire-and-forget never surfaces an unhandled rejection and one
-                    // failed tick does not wedge the loop guard.
+                    // failed tick does not wedge the loop guard. The `no-fetch` verdict
+                    // is what keeps a divergence heal asking.
+                    outcome = 'no-fetch';
                 }
             } while (reverifyAgain);
         }
         finally {
             reverifyInFlight = false;
         }
+        return outcome;
+    }
+    // Divergence heal. Giving up on an op leaves the local doc holding CRDT
+    // knowledge the server does not, and Loro requires per-actor causal
+    // contiguity, so every op the app writes afterwards reaches the server as
+    // causally unapplyable and stays that way until the missing slice arrives.
+    // The server's own escape for an op nothing can apply is to discard it, so
+    // the window between the give-up and the next handshake is a window where
+    // the app writes into a document that keeps none of it.
+    //
+    // The periodic re-verify would eventually close that window, but on its own
+    // schedule: a bulk write finishes and the reader reloads well inside one
+    // tick. A give-up is the moment the client knows it has diverged, so it
+    // drives the handshake itself, and keeps driving it on a backoff until one
+    // run reports the durable frontier covering the local doc. The first delay
+    // is not zero because the give-up follows sustained shedding, so the fetch
+    // this schedules would join the burst it is recovering from.
+    const DIVERGENCE_HEAL_BASE_DELAY_MS = 2_000;
+    const DIVERGENCE_HEAL_MAX_DELAY_MS = 30_000;
+    // Roughly four minutes of attempts, after which the periodic re-verify is
+    // the remaining backstop and the tab has long since reported the failure.
+    const DIVERGENCE_HEAL_MAX_ROUNDS = 12;
+    let divergenceHealRound = 0;
+    let divergenceHealTimer = null;
+    function scheduleDivergenceHeal() {
+        if (divergenceHealTimer !== null)
+            return;
+        if (divergenceHealRound >= DIVERGENCE_HEAL_MAX_ROUNDS)
+            return;
+        divergenceHealRound += 1;
+        const delay = Math.min(DIVERGENCE_HEAL_BASE_DELAY_MS * Math.pow(2, divergenceHealRound - 1), DIVERGENCE_HEAL_MAX_DELAY_MS);
+        divergenceHealTimer = setTimeout(() => {
+            divergenceHealTimer = null;
+            void reverifyDurability().then((outcome) => {
+                // `covered` is the only verdict that proves the hole is closed. A
+                // push that just went out is not yet durable, so the next round
+                // re-checks it rather than assuming its acks land, and the backoff
+                // it comes back on is what keeps a push settling from being polled.
+                if (outcome !== 'covered')
+                    scheduleDivergenceHeal();
+                else
+                    divergenceHealRound = 0;
+            });
+        }, delay);
+        divergenceHealTimer.unref?.();
+    }
+    function clearDivergenceHeal() {
+        if (divergenceHealTimer !== null) {
+            clearTimeout(divergenceHealTimer);
+            divergenceHealTimer = null;
+        }
+        divergenceHealRound = 0;
     }
     // A coverage floor below the highest seq seen records ops this client
     // applied nothing for, and the server posts each op once, so nothing
     // re-sends them. Pull the join instead, after a delay long enough for an
     // out-of-order arrival to close the hole itself.
+    //
+    // The delay is only meaningful against the hole this check was ARMED on,
+    // which is why the seq it waits to reach is captured here rather than read
+    // again when it fires. Holes are the ordinary state of a client that is
+    // writing: acks overtake heavily, so the newest acked seq sits above the
+    // contiguous floor almost continuously, and each such hole closes as the ack
+    // below it lands. Asking on expiry whether ANY hole exists reads a
+    // brand-new one, opened by ops sent since, as the original persisting, and a
+    // client that keeps writing always has one. That answer costs a join
+    // re-import, which discards the undo and redo stacks, so the reader loses
+    // their history every couple of seconds while nothing is wrong.
+    //
+    // Rounds that move nothing back off and then stop, and any advance in the
+    // floor starts the budget over. What separates the two cases is exactly
+    // that: a hole left by a write still in flight fills as the rows land, so
+    // each pull delivers more and earns the next one, while a seq the server
+    // allocated and never wrote (a failed op write leaves a hole rather than a
+    // duplicate) delivers nothing however often it is asked for. Without the
+    // budget that second hole is a join re-import every couple of seconds for
+    // the life of the tab, each one discarding the reader's undo history. It
+    // clears at the next compaction, which folds the tail past the hole.
+    const GAP_PULL_MAX_ROUNDS = 6;
+    const GAP_PULL_MAX_DELAY_MS = 30_000;
     let gapTimer = null;
+    let gapPullRounds = 0;
+    let gapPullFloor = -1;
     function scheduleGapCheck() {
         if (gapTimer !== null)
             return;
-        if (args.getCoveredSeq() >= args.getCurrentSeq())
+        const awaited = args.getCurrentSeq();
+        const floor = args.getCoveredSeq();
+        if (floor >= awaited) {
+            gapPullRounds = 0;
+            return;
+        }
+        if (floor > gapPullFloor)
+            gapPullRounds = 0;
+        if (gapPullRounds >= GAP_PULL_MAX_ROUNDS)
             return;
+        gapPullRounds += 1;
+        gapPullFloor = floor;
+        const delay = Math.min(MISSED_OP_RESYNC_DELAY_MS * Math.pow(2, gapPullRounds - 1), GAP_PULL_MAX_DELAY_MS);
         gapTimer = setTimeout(() => {
             gapTimer = null;
-            if (args.getCoveredSeq() >= args.getCurrentSeq())
+            // Covered up to where the hole was: it closed on its own, whatever has
+            // been sent since. Anything newer arms its own check.
+            if (args.getCoveredSeq() >= awaited) {
+                gapPullRounds = 0;
                 return;
-            args.resyncFromSnapshot?.();
-        }, MISSED_OP_RESYNC_DELAY_MS);
+            }
+            pullJoin();
+        }, delay);
         gapTimer.unref?.();
     }
+    // The server ended this subscription: it refused the subscribe (a revoked
+    // grant), or evicted it again after the one silent re-subscribe a
+    // connection grants. The client detaches this transport from the topic as
+    // it reports that, so no ack, no fanout and no reconnect reaches it again.
+    //
+    // Everything the transport is waiting on is therefore dead. The ops it
+    // holds can never be acked, and re-sending them puts frames on a
+    // subscription the server has refused while `savingCount` climbs and the
+    // app hears nothing, so they are failed here and every later edit fails
+    // the same way: the app reads one actionable error per unsaved change and
+    // its cue to reload, rather than a document that looks like it is saving
+    // forever. The ids are taken before the reports because
+    // `_failOutstandingOp` re-enters app code.
+    let subscriptionEnded = false;
+    function endSubscription() {
+        if (subscriptionEnded)
+            return;
+        subscriptionEnded = true;
+        const clientOpIds = [...outstandingResends.keys()];
+        forgetAllOps();
+        clearUnavailableRecovery();
+        // The heal and the gap pull both work through this transport, so they
+        // are stopped rather than armed: what they would push or fetch has no
+        // subscription left to travel on.
+        clearDivergenceHeal();
+        if (reverifyTimer !== null) {
+            clearInterval(reverifyTimer);
+            reverifyTimer = null;
+        }
+        if (gapTimer !== null) {
+            clearTimeout(gapTimer);
+            gapTimer = null;
+        }
+        for (const clientOpId of clientOpIds) {
+            args.doc._failOutstandingOp(clientOpId, SUBSCRIPTION_ENDED_MESSAGE);
+        }
+    }
     // 1. Subscribe to the doc topic. Frame routing:
     //    - `doc_init`: bridge the join-vs-fanout race. Ops committed between
     //      the HTTP join (T0) and the WS subscribe (T1) miss the HTTP tail and
-    //      can race the SUB# row so the first `doc_op` fanout may arrive BEFORE
+    //      can race the subscription record so the first `doc_op` fanout may arrive BEFORE
     //      doc_init (separate server invocations, no wire ordering). tail_ops
     //      apply unconditionally: filtering on `seq > currentSeq` would mask
     //      tail_ops a racing `doc_op` inflated the cursor past, leaving lamport
     //      gaps Loro cannot converge across (re-applying is an idempotent
     //      no-op).
+    //    - `doc_catch_up`: the document moved past this client's coverage on
+    //      an op the socket could not carry; re-import the join and nothing
+    //      more (see the branch).
     //    - `doc_op`: apply, advance cursor.
     //    - `op_ack`: resolve the outstanding-op tracker, advance cursor, cancel
     //      that op's resend timer.
     //    - everything else: handled by `BrassWsClient`.
     const unsub = args.wsClient.subscribe(topic, (frame) => {
-        if (isDocInitFrame(frame)) {
+        const init = parseDocInitFrame(frame);
+        if (init) {
+            // Recorded as the frame arrives rather than after the tail applies.
+            // Importing a tail op can throw, and the client swallows it, so a
+            // latch written further down would stay behind and read the NEXT
+            // reconnect as the opening subscribe, suppressing the report this
+            // exists to make.
+            const reconnects = args.wsClient.reconnectCount ?? 0;
+            const socketDropped = docInitReconnectCount !== null && reconnects > docInitReconnectCount;
+            docInitReconnectCount = reconnects;
             // Resync check BEFORE applying. The tail covers (snapshot_seq,
             // current_seq]; if the coverage floor sits below the tail's lower edge
             // (or below current_seq when the tail is empty), ops in between were
@@ -1697,16 +3075,23 @@ function wireDocTransport(args) {
             // this tail or future fanout, so re-import the join's snapshot. The
             // initial subscribe never trips this (the floor was just seeded), so
             // the cost is paid only on a reconnect that crossed a compaction.
-            const minTailSeq = frame.tail_ops.reduce((acc, entry) => (acc === null || entry.seq < acc ? entry.seq : acc), null);
-            const snapshotFloor = minTailSeq !== null ? minTailSeq - 1 : frame.current_seq;
+            const snapshotFloor = snapshotSeqOf(init.snapshot_seq, init.tail_ops.map((entry) => entry.seq), init.current_seq);
             const needsResync = args.getCoveredSeq() < snapshotFloor;
             const tailBlobs = [];
-            for (const entry of frame.tail_ops) {
+            // Whether the frame's own entries can describe the durable frontier.
+            // An entry the server withheld the bytes of still NAMES an op the
+            // server holds, so a frontier folded from the inline entries alone
+            // reports every withheld op as missing from the server. See the
+            // handshake call below.
+            let tailComplete = true;
+            for (const entry of init.tail_ops) {
                 // An op with no inline bytes is deliberately left uncovered: it
                 // has not been applied, so marking it covered would retire the
                 // very resync that fetches it.
-                if (entry.op_blob_b64 === undefined)
+                if (entry.op_blob_b64 === undefined) {
+                    tailComplete = false;
                     continue;
+                }
                 const blob = base64ToBytes(entry.op_blob_b64);
                 tailBlobs.push(blob);
                 args.doc.applyRemoteOp(blob);
@@ -1714,31 +3099,111 @@ function wireDocTransport(args) {
                     args.setCurrentSeq(entry.seq);
                 args.advanceCoveredSeq(entry.seq);
             }
-            if (frame.current_seq > args.getCurrentSeq()) {
-                args.setCurrentSeq(frame.current_seq);
+            // The frame also has to ACCOUNT for every seq the head names, not
+            // merely carry bytes for the entries it lists. The server drops an
+            // oversized or spilled tail from this frame ENTIRELY rather than
+            // listing it byte-less (`document.tail.dropped`), so an empty tail on
+            // a branch whose head sits above its snapshot is not a branch with
+            // nothing in flight: it is the whole tail withheld. Measured on a
+            // real document: snapshot_seq 565, current_seq 1089, 524 ops dropped
+            // from the frame and every one of them already imported by the HTTP
+            // join, so a frontier folded from this frame alone sat 524 ops behind
+            // the local doc and pushed them back on every open.
+            if (typeof init.snapshot_seq === 'number' &&
+                tailBlobs.length < init.current_seq - init.snapshot_seq) {
+                tailComplete = false;
+            }
+            if (init.current_seq > args.getCurrentSeq()) {
+                args.setCurrentSeq(init.current_seq);
             }
             if (needsResync) {
-                if (httpOpWritesInFlight > 0) {
-                    if (frame.current_seq > heldCatchUpSeq)
-                        heldCatchUpSeq = frame.current_seq;
-                }
-                else {
-                    args.resyncFromSnapshot?.();
-                }
+                resyncPastSeq(init.current_seq);
+            }
+            else {
+                // A frame that named a head it did not carry the tail for leaves
+                // the reader short with nothing further coming: the server drops an
+                // oversized or spilled tail from this frame and posts each op once.
+                // For a reader that never writes, this and the catch-up prompt are
+                // the only two places a gap gets noticed at all.
+                scheduleGapCheck();
             }
             // `doc_init` is the reconnect signal the retry-forever recovery hangs
             // off: re-assert every outstanding op and run the durability handshake
             // now, so a client holding work the server lost re-asserts it on
-            // reconnect rather than waiting out the per-op backoff.
+            // reconnect rather than waiting out the per-op backoff. A fresh
+            // connection also returns the shed budget to full: this re-assert is
+            // the round the pending one would have run.
+            clearUnavailableRecovery();
+            // A reconnect, rather than the initial subscribe: the socket dropped
+            // while this document held work, which is the condition the server
+            // has no way to see. The first `doc_init` arrives on the opening
+            // subscribe, and an app that writes as soon as it opens already has
+            // ops outstanding by then, so reporting on every `doc_init` would
+            // fire routinely on a healthy first open and train a reader of the
+            // log to discount the event.
+            //
+            // Before the round rather than after, so the counters describe the
+            // work the reconnect found rather than the work it has just put back
+            // on the wire.
+            if (socketDropped && outstandingResends.size > 0) {
+                reportSyncHealth('reconnected_unsaved');
+            }
             resendAllOutstanding();
-            // Tolerate a non-string vector (a future retyping) as absent: the
-            // handshake is skipped, but the frame still delivers.
-            maybeResyncPush(typeof frame.snapshot_version_vector === 'string'
-                ? frame.snapshot_version_vector
-                : undefined, tailBlobs);
-            // Posted after the SUB# row exists, so this is the safe point to
+            // The handshake needs the WHOLE durable tail, and this frame carries
+            // it only when every entry came inline. A spilled op is named here
+            // with its bytes withheld, and the HTTP join the reader already ran
+            // resolves and imports it, so a frontier built from the inline
+            // entries alone sits behind the local doc by exactly the ops that
+            // spilled, and the handshake pushes the reader's copy of the server's
+            // own tail back at it. On a branch at capacity every chunk is refused
+            // and reported, which is an error on screen for someone who only
+            // reopened the document; on any other branch it lands, writing a
+            // second durable copy of every spilled op and growing the document
+            // toward the ceiling on each open. `reverifyDurability` fetches
+            // through `fetchSnapshot`, which resolves spilled entries, so the
+            // frontier it diffs against is complete.
+            if (tailComplete) {
+                maybeResyncPush(init.snapshot_version_vector, tailBlobs);
+            }
+            else {
+                void reverifyDurability();
+            }
+            // The tail has applied, so every author this client can hear from is
+            // in its doc. An author left in the durable frontier is one whose
+            // changes exist only inside the snapshot, which is the platform having
+            // rewritten how the document stores what it stores. A client cannot
+            // undo across that: its stack inverts the operations it made, and the
+            // values those operations wrote have moved, so an undo would remove
+            // nothing and report success. Re-import instead, which drops both
+            // stacks and leaves the reader on fresh state with undo honestly
+            // unavailable.
+            //
+            // Coverage does not catch this on its own, and the case it misses is
+            // the ordinary one: the fold runs on a branch nobody has open, so the
+            // client that returns to it missed no ops and has no gap to notice.
+            if (!needsResync)
+                maybeResyncPastRewrite(init.snapshot_version_vector);
+            // Posted after the subscription record exists, so this is the safe point to
             // reconcile a pending open whose terminal status frame was dropped.
             args.reconcileStatusOnInit?.();
+            args.onDocumentMoved?.();
+            return;
+        }
+        if (isDocCatchUpFrame(frame)) {
+            // The document moved past what this client can bridge to, so pull the
+            // join. Nothing else: the prompt describes the document rather than
+            // this subscription, and every subscriber gets one on each op the
+            // socket could not carry. Re-asserting outstanding ops here writes a
+            // second durable copy of each of them (the server allocates a fresh
+            // seq per send) for every such op any writer makes, and cancelling
+            // the shed recovery here parks a shed op on its per-op backoff
+            // instead of the schedule the shed armed.
+            if (frame.current_seq > args.getCurrentSeq()) {
+                args.setCurrentSeq(frame.current_seq);
+            }
+            if (args.getCoveredSeq() < frame.current_seq) {
+                resyncPastSeq(frame.current_seq);
+            }
             return;
         }
         if (isDocOpFrame(frame)) {
@@ -1753,20 +3218,28 @@ function wireDocTransport(args) {
                 args.setCurrentSeq(frame.seq);
             args.advanceCoveredSeq(frame.seq);
             scheduleGapCheck();
+            args.onDocumentMoved?.();
             return;
         }
         if (isOpAckFrame(frame)) {
+            // Evidence the connection is working through its queue, which is what
+            // the resend timers read to tell a slow ack from a silent server.
+            lastAckAt = Date.now();
             args.doc.resolveOutstandingOp(frame.client_op_id);
             args.setCurrentSeq(frame.seq);
             args.advanceCoveredSeq(frame.seq);
             // An ack for a local op sits above any remote op this client never
             // received, so the user's own next edit is a second chance to notice.
             scheduleGapCheck();
-            const pending = outstandingResends.get(frame.client_op_id);
-            if (pending) {
-                clearTimeout(pending.timer);
-                outstandingResends.delete(frame.client_op_id);
-            }
+            forgetOp(frame.client_op_id);
+            // The server is durably accepting writes again, so the shed budget
+            // starts over. A round already scheduled still runs: the ops it
+            // re-asserts are the ones this ack did not cover.
+            unavailableRounds = 0;
+            return;
+        }
+        if (isServerUnavailableFrame(frame)) {
+            onServerUnavailable();
             return;
         }
         if (isOpRejectedFrame(frame)) {
@@ -1774,29 +3247,52 @@ function wireDocTransport(args) {
             // draw the same rejection forever and pin `savingCount`) and fail it on
             // the Document so the app hears "could not be saved" instead of a silent
             // wedge. Scoped to this one op; the topic subscription stays live.
-            const pending = outstandingResends.get(frame.client_op_id);
-            if (pending) {
-                clearTimeout(pending.timer);
-                outstandingResends.delete(frame.client_op_id);
-            }
-            args.doc._failOutstandingOp(frame.client_op_id, opRejectedMessage(frame));
+            forgetOp(frame.client_op_id);
+            // The flip is the one moment the refusal is worth reporting: every op
+            // in flight draws the same sentence, and a bulk write has as many of
+            // those as it has unacked writes.
+            const atCapacity = isCapacityRejection(frame);
+            const firstCapacityRefusal = atCapacity && args.doc._markAtCapacity();
+            // A refusal that names the writer rather than the op applies to
+            // every op this reader will send, so it turns the whole Document
+            // read-only before the failure is reported: the app's own
+            // `doc.readOnly` gate then disables the editor in the same tick the
+            // reader hears why, rather than letting them keep typing into a
+            // surface nothing will save.
+            const readOnly = readOnlyReasonForRejection(frame);
+            if (readOnly !== null)
+                args.doc._markReadOnly(readOnly);
+            // NO capacity refusal is healable, whichever kind it is. The refused
+            // work sits on this copy and nowhere else, and the heal is the only
+            // thing that could place it: when it runs out of rounds it stops
+            // silently, so a copy the handshake could not settle is one showing
+            // work that a reload will not, with nothing said. Both kinds therefore
+            // lock, tell and reload, which is what the server's own wording for
+            // each of them already promises.
+            //
+            // The other refusals here stay healable: the handshake splits the
+            // slice under the frame cap, which is what reaches the dependents of
+            // an op that is itself too large to re-send.
+            failOpTerminally(frame.client_op_id, opRejectedMessage(frame), {
+                healable: !atCapacity,
+                report: !atCapacity || firstCapacityRefusal,
+            });
             return;
         }
         if (isDocGoneFrame(frame)) {
             // Cancel every resend timer FIRST so a doc that was saving when delete
             // landed stops re-trying ops the server will only reject as `forbidden`
-            // (the SUB# row was evicted at fanout). Draining before the `_markGone`
+            // (the subscription record was evicted at fanout). Draining before the `_markGone`
             // listeners keeps the lifecycle observably clean.
-            for (const pending of outstandingResends.values()) {
-                clearTimeout(pending.timer);
-            }
-            outstandingResends.clear();
+            forgetAllOps();
+            clearUnavailableRecovery();
             // Stop re-verifying durability against an evicted doc: a resync push
             // would only bounce as `forbidden`, and a gap pull would only 404.
             if (reverifyTimer !== null) {
                 clearInterval(reverifyTimer);
                 reverifyTimer = null;
             }
+            clearDivergenceHeal();
             if (gapTimer !== null) {
                 clearTimeout(gapTimer);
                 gapTimer = null;
@@ -1805,13 +3301,7 @@ function wireDocTransport(args) {
             return;
         }
         if (isDocStatusFrame(frame)) {
-            // The validator gates only on `pending`; default `message` here so a
-            // message-less status still carries a valid `DocumentWorkStatus`
-            // (`message` is typed non-null and rendered verbatim).
-            const status = {
-                ...frame.status,
-                message: typeof frame.status.message === 'string' ? frame.status.message : '',
-            };
+            const status = normalizeWorkStatus(frame.status);
             // `reload` is the server's authoritative "succeeded, content ready"
             // hint: pull the content in and emit the terminal status only AFTER the
             // import lands, so an app re-reading on `onStatus` sees content present.
@@ -1835,6 +3325,14 @@ function wireDocTransport(args) {
             args.doc._emitDriveStatus(toDriveStatus(frame.drive));
             return;
         }
+        if (isDocDrivePublishFrame(frame)) {
+            args.doc._emitPublishState({
+                publishing: frame.publish.publishing === true,
+                failed: frame.publish.failed === true,
+                detail: typeof frame.publish.detail === 'string' ? frame.publish.detail : null,
+            });
+            return;
+        }
         if (isDocOpsDroppedFrame(frame)) {
             // Prompt durability re-check: the discard sealed a new snapshot, so
             // re-fetch the moved frontier and run the handshake now instead of at
@@ -1844,8 +3342,14 @@ function wireDocTransport(args) {
             void reverifyDurability();
             return;
         }
-        // Unknown frame: ignore, so server-side schema growth doesn't break older
-        // SDK builds.
+        // Unknown frame: ignore, so server-side schema growth doesn't break
+        // older SDK builds.
+    }, {
+        // `resendAllOutstanding` on the `doc_init` that follows every
+        // `subscribed` ack IS this topic's re-assertion, so the client drops an
+        // op frame it cannot send now rather than buffering a second copy.
+        ownsFrameRetry: true,
+        onEnded: endSubscription,
     });
     // Arm the periodic durability re-verify (the long-lived-tab backstop).
     // `unref` so the interval never keeps a Node host alive (no-op in the
@@ -1859,6 +3363,22 @@ function wireDocTransport(args) {
     //    tracker so a silently-dropped server response triggers a retry.
     args.doc.setLocalOpHook((opBlob) => {
         const clientOpId = args.newClientOpId();
+        // Nothing carries an op once the subscription is over, so it is failed
+        // instead of tracked: an entry nothing can ack pins `savingCount` and
+        // its resends reach a topic the server refused. The caller records the
+        // entry AFTER this hook returns, so the failure waits a microtask for
+        // there to be one to fail.
+        //
+        // Taken before the op is timed, because this path fails the op through
+        // the Document directly rather than through `failOpTerminally`, so a
+        // timing entry written here is one nothing ever drops.
+        if (subscriptionEnded) {
+            void Promise.resolve().then(() => {
+                args.doc._failOutstandingOp(clientOpId, SUBSCRIPTION_ENDED_MESSAGE);
+            });
+            return clientOpId;
+        }
+        opStartedAt.set(clientOpId, Date.now());
         const opBlobB64 = bytesToBase64(opBlob);
         const sendFrame = {
             type: 'op',
@@ -1876,14 +3396,18 @@ function wireDocTransport(args) {
             void writeOversizedOp(opBlobB64, clientOpId);
             return clientOpId;
         }
-        args.wsClient.send(sendFrame);
         outstandingResends.set(clientOpId, {
             frame: sendFrame,
             attempts: 1,
-            // Placeholder, overwritten immediately below.
+            // Placeholders, overwritten by `dispatchOp` and `scheduleResend` once
+            // the op is actually on the socket.
             timer: setTimeout(() => undefined, 0),
+            armedAt: 0,
+            dispatchedAt: 0,
+            inFlight: 0,
+            queued: false,
         });
-        scheduleResend(clientOpId);
+        dispatchOp(clientOpId);
         return clientOpId;
     });
     async function writeOversizedOp(opBlobB64, clientOpId) {
@@ -1907,32 +3431,68 @@ function wireDocTransport(args) {
         // The size is known here, so refuse without spending a round trip on a
         // blob that can only come back 400.
         if (opBlobExceedsDurableLimit(opBlobB64)) {
-            args.doc._failOutstandingOp(clientOpId, TOO_LARGE_MESSAGE);
+            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE);
             return;
         }
         if (!args.postOversizedOp) {
-            args.doc._failOutstandingOp(clientOpId, TOO_LARGE_MESSAGE);
+            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE);
             return;
         }
+        // An oversized op is deliberately kept out of `outstandingResends` (a
+        // frame past the cap must never reach the socket), so the shed recovery
+        // that re-asserts the tracker cannot reach this one. It runs its own
+        // round of the same policy instead, on the same budget and backoff, so a
+        // capacity refusal costs an op the same nothing whichever transport
+        // carried it.
         let result;
-        try {
-            result = await args.postOversizedOp(opBlobB64, clientOpId);
+        for (let round = 0; round <= UNAVAILABLE_MAX_ROUNDS; round += 1) {
+            if (round > 0) {
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, unavailableDelayMs(round));
+                    timer.unref?.();
+                });
+            }
+            try {
+                result = await args.postOversizedOp(opBlobB64, clientOpId);
+            }
+            catch (err) {
+                result = {
+                    ok: false,
+                    message: err instanceof Error ? err.message : String(err),
+                    // Staging the blob runs strictly before the op write, so a failure
+                    // there wrote nothing and the op is still the client's to send: it
+                    // is priced the way the write prices its own refusals. Any other
+                    // throw leaves it unknown whether the handler ran, and this op
+                    // carries no idempotency the server dedupes on, so replaying it
+                    // could double-apply.
+                    retryable: err instanceof OpStagingError && opStagingIsRetryable(err),
+                };
+            }
+            if (result.ok || !result.retryable)
+                break;
         }
-        catch (err) {
-            result = {
-                ok: false,
-                message: err instanceof Error ? err.message : String(err),
-            };
+        if (result === undefined) {
+            opStartedAt.delete(clientOpId);
+            return;
         }
         if (!result.ok) {
             // Terminal for this op, the same way `op_rejected` is: the local
             // commit stays applied but never persists, so the app hears about it
-            // instead of watching `savingCount` sit above zero forever.
-            args.doc._failOutstandingOp(clientOpId, result.message);
+            // instead of watching `savingCount` sit above zero forever. A refusal
+            // about the writer turns the Document read-only first, so the app's
+            // own gate closes the editor as the reader is told why.
+            const firstCapacityRefusal = result.atCapacity === true && args.doc._markAtCapacity();
+            if (result.readOnly)
+                args.doc._markReadOnly(result.readOnly);
+            failOpTerminally(clientOpId, result.retryable ? UNAVAILABLE_GIVE_UP_MESSAGE : result.message, {
+                healable: result.atCapacity !== true,
+                report: result.atCapacity !== true || firstCapacityRefusal,
+            });
             return;
         }
         // Same bookkeeping an `op_ack` does: resolve the outstanding entry and
         // advance both cursors past the seq the server allocated.
+        opStartedAt.delete(clientOpId);
         args.doc.resolveOutstandingOp(clientOpId);
         args.setCurrentSeq(result.seq);
         args.advanceCoveredSeq(result.seq);
@@ -1985,14 +3545,13 @@ function wireDocTransport(args) {
             clearInterval(reverifyTimer);
             reverifyTimer = null;
         }
+        clearDivergenceHeal();
         if (gapTimer !== null) {
             clearTimeout(gapTimer);
             gapTimer = null;
         }
-        for (const entry of outstandingResends.values()) {
-            clearTimeout(entry.timer);
-        }
-        outstandingResends.clear();
+        forgetAllOps();
+        clearUnavailableRecovery();
         originalClose();
     };
     args.doc.close = () => {
@@ -2006,15 +3565,39 @@ function wireDocTransport(args) {
         // (its lifecycle is the parent Document's). Keying on the REQUESTED branch
         // (not the resolved one) keeps park and take symmetric; a default-branch
         // open has no requested branch and so skips the cache.
-        const cacheKey = args.doc.readOnly || args.parkable === false
-            ? null
-            : parkCacheKey(args.docId, args.requestedBranchId, args.requestedStream);
+        //
+        // A doc with work still running skips it too: parking clears the status
+        // listeners, and the SDK's own waiters on that work (the import runner
+        // waits for the phase that produces the file it imports) are keyed to
+        // this instance, so a reopen would hand back a Document whose wait can
+        // never fire. A fresh open re-attaches everything.
+        //
+        // So does one the server has evicted. `takeParkedDocument` refuses such an
+        // entry, so parking it buys nothing and costs everything parking keeps
+        // alive: the topic subscription (which goes on delivering every op of a
+        // document nobody is reading) and the LoroDoc's heap, until some later
+        // open or eviction reaches that key. A move is the case that makes this
+        // routine rather than terminal, because the session follows it by
+        // reopening the same id, so the evicted copy is retired on every move.
+        const parkable = !args.doc.readOnly &&
+            args.parkable !== false &&
+            args.doc.status?.pending !== true &&
+            args.doc._goneReason === null;
+        const cacheKey = parkable
+            ? parkCacheKey(args.docId, args.requestedBranchId, args.requestedStream)
+            : null;
         if (cacheKey === null) {
             fullTeardown();
             return;
         }
         args.doc._suspend();
-        parkDocument({ doc: args.doc, teardown: fullTeardown, key: cacheKey });
+        parkDocument({
+            doc: args.doc,
+            teardown: fullTeardown,
+            key: cacheKey,
+            optionsSig: documentOptionsSig(args.documentOptions),
+            identity: args.identity?.() ?? null,
+        });
     };
 }
 /**