@brass-build/client 0.4.1 → 0.5.0

package/dist/open-document.js

@@ -3,18 +3,91 @@
 // Cold-load contract: `Document.openFromSnapshot` must stay within 2x of
 // raw Loro import at 50k entities, so the materialisation path adds no
 // full-snapshot logging or deep cloning of decoded bytes.
+import { awaitSeal } from './staged-seal.js';
 import { DEFAULT_STREAM_NAME, Document, } from './documents.js';
 import { ensureWasmReady } from './wasm-runtime.js';
 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 { randomToken } from './documents-namespace.js';
+import { fetchWithRetry, RETRY_IDEMPOTENT_WRITE, RETRY_WRITE_503, } 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 { SealedContent } from './sealed-store.js';
 import { joinCoverageFloor, snapshotSeqOf } from './join-coverage.js';
+import { parseInputStatusNudge } from './inputs.js';
+import { TEMPORARY_INPUTS_RUNTIME } from './inputs-status.js';
+import { setJoinStamp } from './join-stamp.js';
+import { storeClaimSecret } from './guest-link.js';
+import { base64ToBytes, decodeJoinContent, joinEncoding, } from './join-content.js';
 import { declaredTailBytes, resolveTailOps } from './tail-ops.js';
+import { SEALED_ACCEPT } from './sealed-store.js';
 import { opBlobExceedsDurableLimit, opBlobNeedsStaging, opFrameExceedsWsLimit, } from './ws-frame-limit.js';
+export function acceptFromUploadTypes(body) {
+    const wire = body;
+    const tokens = new Set();
+    for (const type of Array.isArray(wire?.import_types) ? wire.import_types : []) {
+        for (const list of [type.extensions, type.content_types]) {
+            if (!Array.isArray(list))
+                continue;
+            for (const token of list)
+                if (typeof token === 'string' && token !== '')
+                    tokens.add(token);
+        }
+    }
+    return {
+        accept: [...tokens].join(','),
+        maxBytes: typeof wire?.max_bytes === 'number' ? wire.max_bytes : Number.POSITIVE_INFINITY,
+    };
+}
+function parseMintedAnonymousDocument(parsed) {
+    const minted = parsed;
+    const expiresAt = typeof minted?.expires_at === 'string' ? new Date(minted.expires_at) : null;
+    if (typeof minted?.doc_id !== 'string' ||
+        typeof minted.link_token !== 'string' ||
+        expiresAt === null ||
+        Number.isNaN(expiresAt.getTime())) {
+        throw new BrassError('Malformed anonymous document response', { status: 500 });
+    }
+    return {
+        docId: minted.doc_id,
+        linkToken: minted.link_token,
+        expiresAt,
+        ...(typeof minted.claim_secret === 'string' ? { claimSecret: minted.claim_secret } : {}),
+    };
+}
+async function readJsonBody(response) {
+    const text = await response.text();
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// PUT a file to a presigned URL. Through XHR where there is one, which is
+// the browser API that reports upload progress.
+function putFile(url, file, onProgress) {
+    const failed = (status) => new BrassError('The file could not be uploaded.', { status: status || 503 });
+    if (typeof XMLHttpRequest === 'undefined') {
+        return fetch(url, { method: 'PUT', body: file }).then((r) => {
+            if (!r.ok)
+                throw failed(r.status);
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open('PUT', url);
+        xhr.upload.onprogress = (e) => {
+            if (e.lengthComputable)
+                onProgress?.(e.loaded, e.total);
+        };
+        xhr.onload = () => (xhr.status >= 200 && xhr.status < 300 ? resolve() : reject(failed(xhr.status)));
+        xhr.onerror = () => reject(failed(0));
+        xhr.send(file);
+    });
+}
 // 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
@@ -25,6 +98,15 @@ const WORK_READY_STATUS = {
     pending: false,
     blocking: false,
 };
+// How long an edit waits on a client that has never opened a socket before
+// the document tells the reader it is not saved. Timed from the first waiting
+// edit rather than counted in failed handshakes, because a network that
+// swallows the upgrade can hold one attempt open with no failure to count.
+// The socket starts connecting when the document opens, so by the time this
+// expires it has had at least this long, which is several times a slow
+// mobile handshake, and a network that refuses upgrades outright has failed
+// four or five of them under the reconnect backoff (1s, 2s, 4s).
+export const NEVER_OPENED_NOTICE_MS = 10_000;
 const CONTENT_PULL_ATTEMPTS = 5;
 const CONTENT_PULL_BACKOFF_MS = 1000;
 // Pull a document's content in after the platform reports its inbound work
@@ -95,8 +177,7 @@ async function resolveParsedTailOps(parsed, onProgress) {
         : (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,
-// and ahead/diverged) so apps don't re-derive it.
+// `DocumentDriveStatus`. `canPush` is the server's `publishable`.
 function toDriveStatus(wire) {
     const state = wire.tracking_state;
     // Only an explicit `import_only` restricts publishing; a frame omitting the
@@ -107,21 +188,14 @@ function toDriveStatus(wire) {
         driveType: wire.drive_type,
         driveName: wire.drive_name,
         state,
-        // `broken` gates the Publish affordance, so read it explicitly rather
-        // than by truthiness: a frame that OMITS it (a future partial drive
-        // 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. 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'),
+        // Only an explicit `true` offers a publish, so a frame that omits the
+        // field never offers one the server would refuse.
+        canPush: wire.publishable === true,
         label: wire.tracking_label,
         detail: wire.tracking_detail,
         broken: wire.broken === true,
         pushReplacesRemote: wire.push_replaces_remote,
+        keepsPriorVersions: wire.keeps_prior_versions === true,
         mirrorDirection,
         ref: wire.tracking_ref,
         refUpdatedAt: wire.tracking_ref_updated_at,
@@ -151,6 +225,7 @@ function toPublishTarget(wire) {
         detail: typeof wire.detail === 'string' ? wire.detail : '',
         publishing: wire.publishing === true,
         publishFailed: wire.publish_failed === true,
+        unpublishable: wire.unpublishable === true,
     };
 }
 function isDocOpFrame(frame) {
@@ -210,6 +285,7 @@ function parseDocInitFrame(frame) {
         ...(typeof f.snapshot_version_vector === 'string'
             ? { snapshot_version_vector: f.snapshot_version_vector }
             : {}),
+        ...(typeof f.import_seq === 'number' ? { import_seq: f.import_seq } : {}),
     };
 }
 function isDocCatchUpFrame(frame) {
@@ -258,6 +334,21 @@ function isCapacityRefusal(status, parsed) {
         return true;
     return parsed?.code === 'at_capacity';
 }
+// The refusal of an op built on a version of the line that a new version's
+// import has since replaced. It is about the copy rather than the op: no
+// resend or heal can place an op naming the replaced version's containers, so
+// the copy reopens, as it does on `doc_gone` `moved`.
+const OP_REJECTED_MOVED = 'moved';
+// The document still holds only its uploaded file. Every op meets the same
+// refusal until the import lands, so a smaller or later push cannot place
+// the refused work and the heal is not armed: the copy locks and reloads.
+const OP_REJECTED_NOT_IMPORTED = 'not_imported';
+function isNotImportedRefusal(parsed) {
+    return parsed?.code === OP_REJECTED_NOT_IMPORTED;
+}
+function isMovedRefusal(parsed) {
+    return parsed?.code === OP_REJECTED_MOVED;
+}
 // 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
@@ -298,7 +389,7 @@ function opRejectedMessage(frame) {
     if (typeof frame.message === 'string' && frame.message !== '') {
         return frame.message;
     }
-    return 'A change could not be saved and will not be retried. Reload the document to continue.';
+    return 'A change could not be saved and will not be retried. Reload 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
@@ -454,16 +545,6 @@ function bytesToBase64(bytes) {
     }
     return btoa(bin);
 }
-// Uses `atob` (present in modern browsers, Node 20+, and jsdom) rather than
-// Node-only `Buffer`, which would force a browser-bundle polyfill.
-function base64ToBytes(b64) {
-    const bin = atob(b64);
-    const bytes = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++) {
-        bytes[i] = bin.charCodeAt(i);
-    }
-    return bytes;
-}
 function isSnapshotResponse(body) {
     if (typeof body !== 'object' || body === null)
         return false;
@@ -477,14 +558,145 @@ function isSnapshotResponse(body) {
     // snapshot validated structurally in materialise(); a null is fine.
     return true;
 }
+/**
+ * The body a join answered with, or the error it is.
+ *
+ * Every open starts here: check the status, then check the shape. Both
+ * failures are open-time and neither is recoverable by the caller, so they
+ * throw rather than returning, and the shape check is what stops a response
+ * the server changed out from under a pinned SDK being read as an empty
+ * document. `describe` names the response in the message, since a reader
+ * debugging one wants to know which route answered.
+ */
+function unwrapJoinResponse(result, isShape, describe) {
+    const { status, parsed, parseFailed } = result;
+    if (status < 200 || status >= 300) {
+        throw brassErrorFromBody(status, parseFailed ? undefined : parsed);
+    }
+    if (!isShape(parsed)) {
+        throw new BrassError(`Malformed document ${describe} response`, {
+            status: 500,
+        });
+    }
+    return parsed;
+}
 // 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.
+/** The longest one pause between joins of a converting document. The wait
+ *  itself has no bound, because a slow conversion is still a healthy one:
+ *  each join is answered with what is left of it, and a conversion that
+ *  cannot finish ends as `at_capacity`, which stops the wait. */
+const CONVERSION_MAX_DELAY_MS = 60_000;
+/** The shortest pause, so a server answering without holding the join is not
+ *  asked again in a tight loop. */
+const CONVERSION_MIN_DELAY_MS = 250;
+const CONVERSION_POLL_MIN_MS = 1_000;
+const CONVERSION_POLL_MAX_MS = 5_000;
+/** Joins in a row that may fail outright while a conversion is awaited. */
+const CONVERSION_JOIN_FAILURES = 5;
+// How often a reader's open waiting on an import reads the work status, as
+// the backstop for a terminal frame it did not hear.
+const IMPORT_WAIT_POLL_MIN_MS = 2_000;
+const IMPORT_WAIT_POLL_MAX_MS = 15_000;
+const OPEN_SUPERSEDED_MESSAGE = 'This open was replaced by another';
+// How long an open waits on the platform's work (a conversion, an import)
+// before it rejects. Above the longest the platform itself takes to end that
+// work either way: an import is two runs of the hydration worker (one retry)
+// before the platform marks it failed, about 32 minutes, and a conversion is
+// three compaction runs before it is marked full, about 18. A wait past this
+// is work the platform has stopped reporting on.
+// Exported for the fake-timer tests.
+export const OPEN_WAIT_CEILING_MS = 40 * 60 * 1000;
+const OPEN_WAIT_EXPIRED_MESSAGE = 'This is taking too long to open. Reload to try again.';
+const IMPORT_FAILED_MESSAGE = 'This file could not be imported';
+/** How long the server holds a writable join for a conversion, less a margin,
+ *  so a join sent this long before the conversion is expected is held until
+ *  it lands. */
+const CONVERSION_HOLD_MS = 10_000;
+/** When to send the next held join, given how long the conversion is
+ *  expected to take from now. */
+function heldJoinDelay(retryAfterMs) {
+    return Math.min(Math.max(CONVERSION_MIN_DELAY_MS, retryAfterMs - CONVERSION_HOLD_MS), CONVERSION_MAX_DELAY_MS);
+}
+/** Whether a response is the join's retryable refusal for a conversion,
+ *  which names its own wait, so the caller paces it rather than a backoff. */
+async function namesConversionWait(response) {
+    if (response.status !== 503)
+        return false;
+    try {
+        const body = (await response.clone().json());
+        return typeof body.retry_after_ms === 'number';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Work a join reports that the open waits out before it resolves: pending work
+ * that locks readers, such as the platform importing the file or a new
+ * version of it.
+ */
+function pendingImportWork(join) {
+    if (join.status !== 200 || join.parseFailed)
+        return null;
+    const parsed = join.parsed;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    if (typeof parsed.doc_id !== 'string' || typeof parsed.branch_id !== 'string')
+        return null;
+    const status = parseWorkStatus(parsed.status);
+    if (status === null || !status.pending || status.blocking === false)
+        return null;
+    return { status, topic: `doc:${parsed.doc_id}:${parsed.branch_id}` };
+}
+/**
+ * The error an open rejects with when the file's import failed and the
+ * document holds nothing from it, or `null`.
+ */
+function failedImportOf(join) {
+    if (join.status !== 200 || join.parseFailed)
+        return null;
+    const parsed = join.parsed;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const status = parseWorkStatus(parsed.status);
+    if (status === null || status.pending || status.blocking !== true)
+        return null;
+    // An import lands at seq 1 or later, so seq 0 is a document no import has
+    // filled.
+    const empty = parsed.awaits_import === true ||
+        typeof parsed.current_seq !== 'number' ||
+        parsed.current_seq <= 0;
+    if (!empty)
+        return null;
+    return new BrassError(status.message !== '' ? status.message : IMPORT_FAILED_MESSAGE, {
+        status: 0,
+    });
+}
+/** Why a writable join refused, or `null` for one that served or failed some
+ *  other way. */
+function joinRefusalOf(join) {
+    const body = typeof join.parsed === 'object' && join.parsed !== null
+        ? join.parsed
+        : {};
+    if (join.status === 503 && typeof body.retry_after_ms === 'number' && body.retry_after_ms >= 0) {
+        return { kind: 'converting', retryAfterMs: body.retry_after_ms };
+    }
+    if (join.status === 507 && body.code === 'at_capacity') {
+        return typeof body.error === 'string' ? { kind: 'at_capacity', error: body.error } : { kind: 'at_capacity' };
+    }
+    return null;
+}
 function readOnlyForGrant(body, options) {
     if (body.can_edit !== false)
         return options;
-    return { ...options, readOnly: true, readOnlyReason: 'grant' };
+    return {
+        ...options,
+        readOnly: true,
+        readOnlyReason: body.read_only_reason === 'not_imported' ? 'not_imported' : 'grant',
+    };
 }
 function isAtVersionResponse(body) {
     if (typeof body !== 'object' || body === null)
@@ -509,7 +721,112 @@ export function createOpenDocument(opts) {
     // here rather than threading it through each call site is what keeps a
     // fourth one from silently dropping it.
     const consented = new Set();
+    const SESSION = { kind: 'session' };
+    function inputsRuntimeFor(credential, docId) {
+        switch (credential.kind) {
+            case 'session':
+                return opts.inputsRuntime ? opts.inputsRuntime(docId) : null;
+            case 'link':
+                return {
+                    readKey: (key, query) => getWithLink(credential.token, `/documents/${encodeURIComponent(docId)}/inputs/${encodeURIComponent(key)}`, query),
+                };
+            case 'temporary':
+                return TEMPORARY_INPUTS_RUNTIME;
+        }
+    }
+    // The join, the op write and the work-status read, through whichever
+    // credential the document was opened with.
+    // `rejoin` marks a read for a document this page already has open, which a
+    // link meters apart from opens.
+    async function joinAs(credential, docId, options, { rejoin = true } = {}) {
+        return credential.kind === 'session'
+            ? fetchSnapshot(docId, options, await requireToken())
+            : fetchLinkView(credential.token, options ?? {}, undefined, { rejoin });
+    }
+    async function postOpAs(credential, docId, lineId, opBlobB64, clientOpId, base) {
+        if (credential.kind === 'session') {
+            return postDocumentOp(docId, lineId, opBlobB64, clientOpId, await requireToken(), base);
+        }
+        return postLinkOp(credential.token, docId, lineId, opBlobB64, clientOpId, base);
+    }
+    async function readStatusAs(credential, docId) {
+        const headers = {};
+        let url;
+        if (credential.kind === 'session') {
+            headers['authorization'] = `Bearer ${await requireToken()}`;
+            applyClientVersionHeader(headers);
+            await applyAppAssertionHeader(headers, opts.getAppAssertion);
+            url = `${baseUrl}/documents/${encodeURIComponent(docId)}`;
+        }
+        else {
+            Object.assign(headers, await linkViewHeaders());
+            url = `${baseUrl}/links/${encodeURIComponent(credential.token)}/view?app_id=${encodeURIComponent(opts.appId)}&rejoin=1`;
+        }
+        const response = await fetch(url, { method: 'GET', headers });
+        if (!response.ok) {
+            throw new BrassError(`document read returned ${response.status}`, { status: response.status });
+        }
+        return response.json();
+    }
+    function wsClientFor(credential) {
+        return credential.kind === 'session' ? opts.wsClient : (opts.linkWsClient?.(credential.token) ?? opts.wsClient);
+    }
+    async function materialiseAs(credential, ...args) {
+        const doc = await materialise(...args);
+        doc._setInputsRuntime(inputsRuntimeFor(credential, args[0].doc_id));
+        return doc;
+    }
+    // A join. One that will write and takes nothing else waits while the
+    // platform converts the document: the join is refused with how long is
+    // left, and asked again then, for as long as that takes. The open's
+    // progress sink hears `preparing` on each wait, and its `false` ends the
+    // wait with a rejection.
     async function fetchSnapshot(docId, options, token) {
+        if (opensReadOnly(options)) {
+            return joinOnce(docId, options, token);
+        }
+        // The first join spends the token the caller holds; a re-join after a
+        // long wait asks for a current one.
+        let held = token;
+        return waitWhileConverting(async () => {
+            const t = held ?? (await requireToken());
+            held = null;
+            return joinOnce(docId, options, t);
+        }, options?.onSnapshotProgress);
+    }
+    async function waitWhileConverting(join, progress) {
+        const deadline = Date.now() + OPEN_WAIT_CEILING_MS;
+        let answer = await join();
+        let failures = 0;
+        for (;;) {
+            const refused = joinRefusalOf(answer);
+            if (refused?.kind !== 'converting')
+                return answer;
+            if (progress?.(0, null, 'preparing') === false) {
+                throw new BrassError(OPEN_SUPERSEDED_MESSAGE, { status: 0 });
+            }
+            if (Date.now() >= deadline)
+                throw new BrassError(OPEN_WAIT_EXPIRED_MESSAGE, { status: 0 });
+            let delay = refused.retryAfterMs === undefined ? CONVERSION_POLL_MIN_MS : heldJoinDelay(refused.retryAfterMs);
+            for (;;) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                try {
+                    answer = await join();
+                    failures = 0;
+                    break;
+                }
+                catch (err) {
+                    // The document is known to exist and to be converting, so a join
+                    // that fails outright is the connection rather than the answer.
+                    failures += 1;
+                    if (failures >= CONVERSION_JOIN_FAILURES)
+                        throw err;
+                    delay = Math.min(CONVERSION_POLL_MIN_MS * 2 ** (failures - 1), CONVERSION_POLL_MAX_MS);
+                }
+            }
+        }
+    }
+    async function joinOnce(docId, options, token) {
         const search = new URLSearchParams();
         search.set('include', 'snapshot');
         if (options?.filter !== undefined) {
@@ -525,16 +842,34 @@ export function createOpenDocument(opts) {
             consented.add(docId);
         if (consented.has(docId))
             search.set('accept_schema_conflict', '1');
-        const url = `${baseUrl}/documents/${encodeURIComponent(docId)}?${search.toString()}`;
-        const headers = { authorization: `Bearer ${token}` };
-        applyClientVersionHeader(headers);
-        await applyAppAssertionHeader(headers, opts.getAppAssertion);
-        const endFetch = perfStart('open: GET /documents (http + read body)');
+        // A caller that will not write asks for the document as it is stored. It
+        // matters on a document the platform holds as a record set: serving one
+        // to a reader is the point of storing one, and serving it to a writer
+        // means converting it to a CRDT first, which the server does and this
+        // reader has no reason to wait for.
+        if (opensReadOnly(options))
+            search.set('intent', 'read');
+        return sendJoin(`/documents/${encodeURIComponent(docId)}`, search, {
+            headers: await memberHeaders(token),
+            perf: 'open: GET /documents (http + read body)',
+            ...(options?.onSnapshotProgress !== undefined ? { progress: options.onSnapshotProgress } : {}),
+        });
+    }
+    // Every join's request: the stored frames this build decodes (a client that
+    // does not name them is served the CRDT), the answer parsed, and its
+    // spilled tail ops resolved. A reader holding a CRDT names the frames too:
+    // the line as stored is the cheapest answer to serve it, and `applyJoin`
+    // takes either form in place.
+    async function sendJoin(path, search, { headers, perf, progress, }) {
+        search.set('accept', SEALED_ACCEPT);
+        const qs = search.toString();
+        const url = `${baseUrl}${path}${qs ? `?${qs}` : ''}`;
+        const endFetch = perf !== undefined ? perfStart(perf) : null;
         // 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. A
+        // on a join: the document is intact and its storage is busy. A
         // document's own writes contend with each other, so the one 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
@@ -547,12 +882,16 @@ export function createOpenDocument(opts) {
         // 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 response = await fetchWithRetry(() => fetch(url, { method: 'GET', ...(headers !== undefined ? { headers } : {}) }), {
+            maxAttempts: 7,
+            baseDelayMs: 700,
+            maxNetworkAttempts: 3,
+            // A conversion's refusal says how long to wait, and the caller waits
+            // that long rather than this backoff's second or two.
+            isFinal: namesConversionWait,
+        });
         const text = await response.text();
-        endFetch({ status: response.status, responseChars: text.length });
+        endFetch?.({ status: response.status, responseChars: text.length });
         let parsed = undefined;
         let parseFailed = false;
         if (text) {
@@ -563,39 +902,24 @@ export function createOpenDocument(opts) {
                 parseFailed = true;
             }
         }
-        await resolveParsedTailOps(parsed, options?.onSnapshotProgress);
+        // A tail op whose bytes spilled to storage arrives as a signed URL, which
+        // carries its own signature, so a guest resolves it as a member does.
+        await resolveParsedTailOps(parsed, progress);
         return { status: response.status, parsed, parseFailed };
     }
+    async function memberHeaders(token) {
+        const headers = { authorization: `Bearer ${token}` };
+        applyClientVersionHeader(headers);
+        await applyAppAssertionHeader(headers, opts.getAppAssertion);
+        return headers;
+    }
     // `GET /documents/{docId}/at/{version}`: read-only materialization at a
-    // historical version. Same auth + parse shape as `fetchSnapshot`.
+    // historical version.
     async function fetchAtVersion(docId, version, branch, token) {
         const search = new URLSearchParams();
         if (branch !== undefined)
             search.set('branch', branch);
-        const qs = search.toString();
-        const url = `${baseUrl}/documents/${encodeURIComponent(docId)}` +
-            `/at/${encodeURIComponent(String(version))}` +
-            (qs ? `?${qs}` : '');
-        const headers = { authorization: `Bearer ${token}` };
-        applyClientVersionHeader(headers);
-        await applyAppAssertionHeader(headers, opts.getAppAssertion);
-        const response = await fetch(url, {
-            method: 'GET',
-            headers,
-        });
-        const text = await response.text();
-        let parsed = undefined;
-        let parseFailed = false;
-        if (text) {
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parseFailed = true;
-            }
-        }
-        await resolveParsedTailOps(parsed);
-        return { status: response.status, parsed, parseFailed };
+        return sendJoin(`/documents/${encodeURIComponent(docId)}/at/${encodeURIComponent(String(version))}`, search, { headers: await memberHeaders(token) });
     }
     // The historical-materialise fetcher `doc._checkoutVersion(v)` calls back
     // to, shared by the default Document and each opened stream line (both
@@ -615,28 +939,7 @@ export function createOpenDocument(opts) {
                     status: 500,
                 });
             }
-            let snapshotBytes = null;
-            const snap = result.parsed.snapshot;
-            if (snap !== null) {
-                if (snap.kind === 'inline') {
-                    snapshotBytes = base64ToBytes(snap.data_b64);
-                }
-                else if (snap.kind === 'presigned') {
-                    const snapResponse = await fetch(snap.url, { method: 'GET' });
-                    if (!snapResponse.ok) {
-                        throw new BrassError('Presigned snapshot fetch failed', {
-                            status: snapResponse.status,
-                        });
-                    }
-                    const buf = await snapResponse.arrayBuffer();
-                    snapshotBytes = new Uint8Array(buf);
-                }
-                else {
-                    // A delivery kind this build does not implement; refuse rather than
-                    // preview an empty version (same rationale as `materialise`).
-                    throw snapshotKindTooNewError();
-                }
-            }
+            const content = await decodeJoinContent(result.parsed.snapshot, (url) => fetchPresignedSnapshot(url));
             const tailOpBlobs = result.parsed.tail_ops.map((entry) => base64ToBytes(entry.op_blob_b64));
             const rawSeqs = result.parsed.stream_seqs;
             let streamSeqs;
@@ -650,7 +953,7 @@ export function createOpenDocument(opts) {
                     streamSeqs = parsed;
             }
             return {
-                snapshotBytes,
+                content,
                 tailOpBlobs,
                 effectiveVersion: result.parsed.effective_version,
                 ...(streamSeqs ? { streamSeqs } : {}),
@@ -674,9 +977,9 @@ export function createOpenDocument(opts) {
             return serverMessage;
         }
         if (status === 403)
-            return 'You do not have permission to edit this document.';
+            return 'You do not have permission to make changes here.';
         if (status === 404)
-            return 'This document is no longer available.';
+            return 'This is no longer available.';
         return `This change could not be saved (${status}).`;
     }
     // Write one op over HTTP. The socket carries an op only up to its own
@@ -686,21 +989,25 @@ export function createOpenDocument(opts) {
     // outstanding tracker and re-asserts it, and a blind replay would write a
     // second stored copy of the same edit.
     // Mint a presigned PUT and upload the blob to it, returning the staging
-    // key the op write names. The PUT carries no Brass headers: the URL is
+    // key the op write names. A share link mints on the same route with the
+    // link as the credential. The PUT carries no Brass headers: the URL is
     // signed, and an extra header falls outside that signature.
-    async function stageOpBlob(docId, opBlobB64, token) {
+    async function stageOpBlob(docId, opBlobB64, credential) {
         // 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);
+            const headers = { 'content-type': 'application/json' };
+            if ('link' in credential) {
+                headers['authorization'] = `Link ${credential.link}`;
+            }
+            else {
+                headers['authorization'] = `Bearer ${credential.bearer}`;
+                applyClientVersionHeader(headers);
+                await applyAppAssertionHeader(headers, opts.getAppAssertion);
+            }
+            const mint = await fetchWithDeadline(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops/upload`, { method: 'POST', headers, body: JSON.stringify({ byte_size: opBlobB64.length }) }, OP_WRITE_TIMEOUT_MS);
             let minted = undefined;
             try {
                 minted = mint.text ? JSON.parse(mint.text) : undefined;
@@ -729,7 +1036,7 @@ export function createOpenDocument(opts) {
             throw asOpStagingError(err);
         }
     }
-    async function postDocumentOp(docId, branchId, opBlobB64, clientOpId, token) {
+    async function postDocumentOp(docId, branchId, opBlobB64, clientOpId, token, base = {}) {
         const headers = {
             authorization: `Bearer ${token}`,
             'content-type': 'application/json',
@@ -741,7 +1048,7 @@ export function createOpenDocument(opts) {
         // through a request body.
         let stagedKey;
         if (opBlobNeedsStaging(opBlobB64)) {
-            stagedKey = await stageOpBlob(docId, opBlobB64, token);
+            stagedKey = await stageOpBlob(docId, opBlobB64, { bearer: token });
         }
         const endFetch = perfStart('op: POST /documents/{id}/ops');
         const response = await fetchWithDeadline(`${baseUrl}/documents/${encodeURIComponent(docId)}/ops`, {
@@ -753,6 +1060,7 @@ export function createOpenDocument(opts) {
                     : { upload_key: stagedKey }),
                 branch_id: branchId,
                 client_op_id: clientOpId,
+                ...base,
             }),
         }, 
         // An op under the staging threshold travels inline, so this request
@@ -902,20 +1210,19 @@ export function createOpenDocument(opts) {
     // checkpoints / commands, and no park cache; a stream's extra cost
     // over its content is one join + one subscribe, which is what keeps
     // per-stream opens proportional to what an app touches.
-    async function openStreamLine(docId, lineId) {
-        const token = await requireToken();
-        const { status, parsed, parseFailed } = await fetchSnapshot(docId, { branch: lineId }, token);
-        if (status < 200 || status >= 300) {
-            throw brassErrorFromBody(status, parseFailed ? undefined : parsed);
-        }
-        if (!isSnapshotResponse(parsed)) {
-            throw new BrassError('Malformed document snapshot response', {
-                status: 500,
-            });
-        }
+    async function openStreamLine(docId, lineId, 
+    // The parent document's open, whose read intent every line of it shares.
+    parentOptions, credential = SESSION) {
+        const lineOptions = rejoinOptions(lineId, parentOptions);
+        const result = await joinAs(credential, docId, lineOptions, { rejoin: false });
+        const parsed = unwrapJoinResponse(result, isSnapshotResponse, 'snapshot');
         // 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));
+        // read-only for the same reader the document opens read-only for, and for
+        // a caller who asked for a read-only document.
+        const asked = parentOptions?.documentOptions;
+        const doc = await materialiseAs(credential, parsed, readOnlyForGrant(parsed, asked?.readOnly === true
+            ? { readOnly: true, readOnlyReason: asked.readOnlyReason ?? 'snapshot' }
+            : 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
@@ -967,26 +1274,18 @@ export function createOpenDocument(opts) {
                 do {
                     lineResyncAgain = false;
                     try {
-                        const t = await requireToken();
-                        const res = await fetchSnapshot(docId, { branch: lineId }, t);
+                        const res = await joinAs(credential, docId, lineOptions);
                         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 applied = await applyJoin(doc, res.parsed, (url) => fetchPresignedSnapshot(url));
+                        if (applied.kind !== 'applied')
+                            return;
+                        const seqs = applied.tailSeqs;
+                        for (const seq of seqs)
+                            if (seq > currentSeq)
+                                currentSeq = seq;
                         const joined = res.parsed.current_seq;
                         if (typeof joined === 'number' && joined > currentSeq) {
                             currentSeq = joined;
@@ -1016,14 +1315,16 @@ export function createOpenDocument(opts) {
         // one seq; only the transport differs, and the response carries the
         // seq an `op_ack` would have.
         const postOversizedOp = async (opBlobB64, clientOpId) => {
-            const token = await requireToken();
-            const { status, parsed: opResult } = await postDocumentOp(docId, lineId, opBlobB64, clientOpId, token);
+            const { status, parsed: opResult } = await postOpAs(credential, docId, lineId, opBlobB64, clientOpId, baseImportSeqField(doc));
             if (status < 200 || status >= 300) {
                 return {
                     ok: false,
                     message: opWriteFailureMessage(status, opResult),
                     retryable: opWriteIsRetryable(status),
                     atCapacity: isCapacityRefusal(status, opResult),
+                    ...(isMovedRefusal(opResult) ? { moved: true } : {}),
+                    ...(isNotImportedRefusal(opResult) ? { notImported: true } : {}),
+                    ...(status === 413 ? { tooLarge: true } : {}),
                     // 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' } : {}),
@@ -1039,13 +1340,31 @@ export function createOpenDocument(opts) {
             }
             return { ok: true, seq };
         };
-        if (opts.wsClient) {
+        // The durability handshake's ground truth for this line, read from the
+        // line's own join so the diff is against this stream's frontier.
+        const refetchDurableFrontier = async () => {
+            const res = await joinAs(credential, docId, lineOptions);
+            if (res.status < 200 || res.status >= 300)
+                return null;
+            if (!isSnapshotResponse(res.parsed))
+                return null;
+            const out = {
+                tailBlobs: res.parsed.tail_ops.map((entry) => base64ToBytes(entry.op_blob_b64)),
+            };
+            if (typeof res.parsed.snapshot_version_vector === 'string') {
+                out.snapshotVersionVector = res.parsed.snapshot_version_vector;
+            }
+            return out;
+        };
+        const lineWsClient = wsClientFor(credential);
+        if (lineWsClient) {
             wireDocTransport({
                 doc,
                 docId,
                 branchId: lineId,
-                wsClient: opts.wsClient,
+                wsClient: lineWsClient,
                 postOversizedOp,
+                refetchDurableFrontier,
                 newClientOpId: opts.newClientOpId ?? defaultClientOpIdMinter,
                 getCurrentSeq: () => currentSeq,
                 setCurrentSeq: (next) => {
@@ -1062,20 +1381,399 @@ export function createOpenDocument(opts) {
         }
         return doc;
     }
-    async function finalise(docId, snapshot, options) {
-        const { status, parsed, parseFailed } = snapshot;
-        if (status < 200 || status >= 300) {
-            throw brassErrorFromBody(status, parseFailed ? undefined : parsed);
+    /**
+     * A snapshot-only open: the ordinary join, materialised read-only, with no
+     * transport wired.
+     *
+     * It reads the JOIN rather than the at-version route even though the two
+     * envelopes match, because the join is what serves a record set as itself.
+     * The at-version route materialises a LoroDoc to replay a tail onto, so it
+     * converts a record set before answering; a reader asking for the document
+     * as it stands has no tail to replay and would pay that conversion for
+     * nothing.
+     *
+     * `readOnly` is what the caller asked for rather than a fact about their
+     * grant, which is why it carries its own reason: an app that disables its
+     * editor on `doc.readOnly` is right to, and the message a refused `mutate`
+     * throws should say the caller opened a snapshot rather than blame a
+     * permission they may well hold.
+     */
+    async function openSnapshotOnly(snapshot, options) {
+        const parsed = unwrapJoinResponse(snapshot, isSnapshotResponse, 'snapshot');
+        return openParsedSnapshot(parsed, options);
+    }
+    async function openParsedSnapshot(parsed, options) {
+        // The grant's own reason wins where there is one. A viewer who asks for a
+        // snapshot cannot edit either way, and telling them to reopen without
+        // asking for one would be advice that does not work: the refusal has to
+        // name the limit they actually have.
+        const byGrant = readOnlyForGrant(parsed, options.documentOptions);
+        const doc = await materialiseAs(SESSION, parsed, {
+            ...byGrant,
+            readOnly: true,
+            readOnlyReason: byGrant?.readOnlyReason ?? 'snapshot',
+        }, options.onSnapshotProgress, { emptyAsFrozen: true });
+        // What one load brought: the point it was taken at, fixed until the next
+        // load. A live open's provider is the transport's cursor and a
+        // version-pinned one answers from its checkout, so this is what makes
+        // `doc.currentSeq` mean the same thing on all three: the version the
+        // reader is looking at. The change notice compares the document's head
+        // against it.
+        const takeLoad = (load) => {
+            const takenAt = load.current_seq;
+            if (typeof takenAt === 'number')
+                doc.setCurrentSeqProvider(() => takenAt);
+            // Work the join reported over the content it served: work that does not
+            // lock readers (a push), or a new version's import that failed and left
+            // the content in place. A join carries a status only while work is in
+            // flight, so one with none after a pending load is the work having ended.
+            if (load.status !== undefined)
+                doc._emitStatus(load.status);
+            else if (doc._workStatusNow?.pending === true)
+                doc._emitStatus(WORK_READY_STATUS, { contentLoaded: true });
+            doc._setImportReport(importReportOf(load));
+            setJoinStamp(doc, load.updated_at);
+            setJoinedName(doc, load);
+            watchFrom(load);
+        };
+        // An import is stored frozen, so a frozen open of a file nobody has
+        // imported yet runs the app's importer the way an editable open does.
+        doc._awaitsImport = parsed.awaits_import === true;
+        if (opts.sourceBlobFetcher) {
+            const fetcher = opts.sourceBlobFetcher;
+            doc.setSourceBlobFetcher(() => fetcher(doc));
         }
-        if (!isSnapshotResponse(parsed)) {
-            throw new BrassError('Malformed document snapshot response', { status: 500 });
+        // A document's other streams open as frozen copies of their own lines,
+        // read the same way and watched on their own topics.
+        doc.setOpenedStreamName(options.stream ?? DEFAULT_STREAM_NAME);
+        if (opts.streamProvider) {
+            const provider = opts.streamProvider;
+            const docId = parsed.doc_id;
+            const openedBranchId = parsed.stream_branch_id ?? parsed.branch_id;
+            doc.setStreamRuntime({
+                list: async () => (await provider.list(docId, openedBranchId)).streams,
+                create: () => Promise.reject(new Error('A read-only copy cannot create a stream.')),
+                openLine: (lineId) => openFrozen(docId, frozenLineOptions(lineId)),
+            });
+        }
+        const ws = opts.wsClient;
+        const watchFrom = (load) => {
+            if (!ws)
+                return;
+            const topic = `doc:${load.doc_id}:${load.branch_id}`;
+            const at = typeof load.current_seq === 'number' ? load.current_seq : 0;
+            // The copy reports the work that was in flight when it loaded, through to
+            // its outcome, and nothing that starts afterwards: later work describes a
+            // version of the document this copy does not hold.
+            let following = load.status?.pending === true;
+            doc._setChangeNotice((fire) => ws.subscribe(topic, (frame) => {
+                if (following && isDocStatusFrame(frame)) {
+                    const status = normalizeWorkStatus(frame.status);
+                    if (!status.pending)
+                        following = false;
+                    doc._emitStatus(status);
+                    doc._settleChangeNotice();
+                }
+                if (frameMovesDocument(frame, at))
+                    fire();
+            }, {
+                notice: true,
+                onSubscribed: ({ currentSeq }) => {
+                    if (currentSeq !== undefined && currentSeq > at)
+                        fire();
+                    // Work that ends between the join and this subscribe sent its
+                    // frame to nobody, and may or may not have moved the seq, so a
+                    // copy taken mid-work asks the row whether it is still running.
+                    if (load.status?.pending !== true)
+                        return;
+                    void readFrozenWorkStatus(load.doc_id).then((now) => {
+                        if (now === 'unread' || now?.pending === true)
+                            return;
+                        doc._emitStatus(now ?? { pending: false, message: '' });
+                        fire();
+                    });
+                },
+            }));
+        };
+        takeLoad(parsed);
+        // A frozen copy loads again only when the app asks. The join keeps the
+        // open's read intent and names the stored frames whatever the copy holds
+        // now, and the result applies in place (`applyJoin`) under the same
+        // handles, switching between frozen content and a CRDT when the line has.
+        const openedId = parsed.doc_id;
+        //
+        // A reload follows the open's rule: it waits out an import in flight and
+        // loads what the import landed, and rejects (keeping what the copy holds)
+        // when the import failed with nothing landed or the file is one only
+        // another app imports. The open's progress sink belongs to the open, so
+        // the reload's wait reports to none.
+        const { onSnapshotProgress: _openProgress, ...reloadOptions } = options;
+        doc._setFrozenReloader(async () => {
+            const join = () => paceFrozen(async () => fetchSnapshot(openedId, reloadOptions, await requireToken()));
+            const snapshot = await joinPastWork(openedId, reloadOptions, await join(), join);
+            const load = unwrapJoinResponse(snapshot, isSnapshotResponse, 'snapshot');
+            const applied = await applyJoin(doc, load, (url) => fetchPresignedSnapshot(url));
+            if (applied.kind !== 'reloaded')
+                takeLoad(load);
+        });
+        return doc;
+    }
+    // The row's work status as it is now, without a snapshot, or 'unread' when
+    // the read fails.
+    async function readFrozenWorkStatus(docId) {
+        const now = await readWorkStatus(docId);
+        return now === 'gone' ? 'unread' : now;
+    }
+    // As `readFrozenWorkStatus`, with 'gone' for a document the caller can no
+    // longer read (403 / 404).
+    async function readWorkStatus(docId) {
+        try {
+            const token = await requireToken();
+            const headers = { authorization: `Bearer ${token}` };
+            applyClientVersionHeader(headers);
+            await applyAppAssertionHeader(headers, opts.getAppAssertion);
+            const response = await fetch(`${baseUrl}/documents/${encodeURIComponent(docId)}`, {
+                method: 'GET',
+                headers,
+            });
+            if (response.status === 403 || response.status === 404)
+                return 'gone';
+            if (!response.ok)
+                return 'unread';
+            const body = (await response.json());
+            return parseWorkStatus(body.status);
+        }
+        catch {
+            return 'unread';
+        }
+    }
+    // An open joins past an import the join reports (`pendingImportWork`): it
+    // waits for the import to end and joins again, so it resolves with what the
+    // import landed, and rejects when the import failed with nothing landed.
+    async function joinPastWork(docId, options, first, join) {
+        const deadline = Date.now() + OPEN_WAIT_CEILING_MS;
+        let answer = first;
+        for (;;) {
+            const work = pendingImportWork(answer);
+            if (work === null) {
+                const failed = failedImportOf(answer);
+                if (failed !== null)
+                    throw failed;
+                return answer;
+            }
+            await waitForWorkToEnd(docId, work.topic, work.status, deadline, options?.onSnapshotProgress);
+            answer = await join();
+        }
+    }
+    // Resolves once the work ends: a terminal `doc_status` frame on the
+    // document's topic, or a status read that finds it ended (on subscribe, and
+    // on a backing-off poll for a frame that never arrives). Rejects when the
+    // progress sink says a newer open superseded this one, and at `deadline`.
+    async function waitForWorkToEnd(docId, topic, status, deadline, progress) {
+        const superseded = () => progress?.(0, null, 'importing', status.message) === false;
+        if (superseded())
+            throw new BrassError(OPEN_SUPERSEDED_MESSAGE, { status: 0 });
+        const ended = (now) => !now.pending || now.blocking === false;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            let timer = null;
+            let unsubscribe = null;
+            const expiry = setTimeout(() => end(new BrassError(OPEN_WAIT_EXPIRED_MESSAGE, { status: 0 })), Math.max(0, deadline - Date.now()));
+            const end = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                clearTimeout(expiry);
+                unsubscribe?.();
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            const check = async () => {
+                const now = await readWorkStatus(docId);
+                if (now === 'unread')
+                    return;
+                // A document the caller lost is left to the next join to report.
+                if (now === 'gone' || now === null || ended(now))
+                    end();
+            };
+            let delay = IMPORT_WAIT_POLL_MIN_MS;
+            const poll = () => {
+                timer = setTimeout(() => {
+                    timer = null;
+                    if (settled)
+                        return;
+                    if (superseded()) {
+                        end(new BrassError(OPEN_SUPERSEDED_MESSAGE, { status: 0 }));
+                        return;
+                    }
+                    void check().finally(() => {
+                        if (settled)
+                            return;
+                        delay = Math.min(delay * 2, IMPORT_WAIT_POLL_MAX_MS);
+                        poll();
+                    });
+                }, delay);
+            };
+            if (opts.wsClient) {
+                unsubscribe = opts.wsClient.subscribe(topic, (frame) => {
+                    if (isDocStatusFrame(frame) && ended(normalizeWorkStatus(frame.status)))
+                        end();
+                }, { notice: true, onSubscribed: () => void check() });
+            }
+            poll();
+        });
+    }
+    // A frozen open: a snapshot that watches for the document moving once a
+    // listener asks it to. A set is opened as a loop over its ids, so joins
+    // are paced here, which is what keeps such a loop fast without letting it
+    // flood the api. The pace covers the join alone: the content download
+    // goes to storage rather than the api, and holding a lane through it
+    // leaves the next join waiting on bytes the api is not serving.
+    async function openFrozen(docId, options) {
+        const join = () => paceFrozen(async () => fetchSnapshot(docId, options, await requireToken()));
+        // The wait sits outside the pace, which covers a join and not the time
+        // between two of them.
+        const snapshot = await joinPastWork(docId, options, await join(), join);
+        return openSnapshotOnly(snapshot, options);
+    }
+    const paceFrozen = createPacer(FROZEN_OPEN_LANES);
+    // What a signed-in open reaches beyond the transport.
+    function wireSessionCapabilities(doc, docId, parsed, options) {
+        // `doc._checkoutVersion(v)` calls back here to materialise historical
+        // state, leaving the live subscription untouched.
+        doc.setCheckoutFetcher(makeCheckoutFetcher());
+        // Wire the branch provider + populate the initial list, so the
+        // toolbar's branch chip can name the branch on the next subscribe
+        // tick. Branch management is hosted; this list feeds the SDK's own
+        // chrome, not an app method.
+        if (opts.branchProvider) {
+            doc.setBranchProvider(opts.branchProvider);
+            void doc._refreshBranches().catch(() => {
+                // Best-effort: a failure leaves the chip unnamed until a hosted
+                // branch action refreshes the list.
+            });
+        }
+        // `doc.useCanvas(canvas)` captures + uploads after each local commit; the
+        // doc handles debounce + readOnly gating internally.
+        if (opts.thumbnailUploader) {
+            const uploader = opts.thumbnailUploader;
+            doc.setThumbnailUploader(async (image, width, height, version) => {
+                await uploader(doc, image, width, height, version);
+            });
+        }
+        doc._setThumbnailVersion(parsed.thumbnail?.version ?? null);
+        if (opts.checkpointCreator) {
+            const creator = opts.checkpointCreator;
+            doc.setCheckpointCreator((anchor) => creator(doc, anchor));
+        }
+        if (opts.drivePusher) {
+            const pusher = opts.drivePusher;
+            doc.setDrivePusher((input) => pusher(doc, input));
+        }
+        // `doc.resolveDrive()` opens the hosted resolution surface and, when it
+        // names a document to switch onto, re-opens onto it via the same
+        // `openSiblingDoc` path the `history` fork uses.
+        const hostedForResolve = opts.hostedUiProvider;
+        const resolveSurface = hostedForResolve?.driveResolve;
+        if (hostedForResolve && resolveSurface) {
+            doc.setDriveResolver(async () => {
+                const docId = doc.id;
+                if (docId === null)
+                    return null;
+                const result = await resolveSurface(docId);
+                if (result?.newDocId && hostedForResolve.openSiblingDoc) {
+                    await hostedForResolve.openSiblingDoc(result.newDocId, {});
+                }
+                return result;
+            });
+        }
+        if (opts.sourceBlobFetcher) {
+            const fetcher = opts.sourceBlobFetcher;
+            doc.setSourceBlobFetcher(() => fetcher(doc));
         }
-        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).
+        setJoinStamp(doc, parsed.updated_at);
+        setJoinedName(doc, parsed);
+        const poster = opts.provisionalInputsPoster;
+        if (poster)
+            doc._setProvisionalInputsPoster((post, o) => poster(docId, post, o));
+        doc.setOpenedStreamName(options?.stream ?? DEFAULT_STREAM_NAME);
+        // Streams: manifest list/create over HTTP plus the per-line open
+        // (join + WS subscribe). Bound to the BRANCH this Document opened on,
+        // which is not the line it materialized when the open named a stream: a
+        // manifest belongs to a branch and a line owns none, so binding to the
+        // line would leave `doc.stream(name)` resolving against nothing.
+        if (opts.streamProvider) {
+            const provider = opts.streamProvider;
+            const openedBranchId = parsed.stream_branch_id ?? parsed.branch_id;
+            doc.setStreamRuntime({
+                list: async () => (await provider.list(docId, openedBranchId)).streams,
+                create: (name) => provider.create(docId, openedBranchId, name),
+                openLine: (lineId) => openStreamLine(docId, lineId, options),
+            });
+        }
+        // Hosted-UI provider backing the doc's built-in `history` / `details` /
+        // `share` / `delete` commands.
+        if (opts.hostedUiProvider) {
+            doc.setHostedUiProvider(opts.hostedUiProvider);
+            const refreshName = opts.hostedUiProvider.refreshName;
+            if (refreshName && docId) {
+                void refreshName(docId).then((name) => {
+                    if (name !== null)
+                        doc._setName(name);
+                });
+            }
+        }
+    }
+    // What a share link's open reaches beyond the transport: the routes that
+    // take the link as the credential, and the link's own stream manifest.
+    function wireLinkCapabilities(doc, docId, parsed, credential, options, writes) {
+        const { token } = credential;
+        setJoinStamp(doc, parsed.updated_at);
+        setJoinedName(doc, parsed);
+        doc.setOpenedStreamName(options?.stream ?? DEFAULT_STREAM_NAME);
+        if (writes) {
+            doc.setCheckpointCreator(async (anchor) => {
+                const version = anchor?.version ?? doc.currentSeq;
+                if (version === null) {
+                    throw new BrassError('createCheckpoint: the document has no resolved version yet', { status: 400 });
+                }
+                const res = await postWithLink(token, `/documents/${encodeURIComponent(docId)}/checkpoints`, {
+                    version,
+                    ...(doc.branchId !== null ? { branch_id: doc.branchId } : {}),
+                });
+                return res.checkpoint;
+            });
+        }
+        doc.setStreamRuntime({
+            list: () => fetchLinkStreamManifest(token),
+            openLine: (lineId) => openStreamLine(docId, lineId, options, credential),
+            create: async (name) => {
+                if (!writes) {
+                    throw new BrassError('A shared-link guest cannot create streams.', { status: 403 });
+                }
+                const info = await postWithLink(token, `/documents/${encodeURIComponent(docId)}/streams`, { name, branch_id: parsed.branch_id });
+                return { name: info.name, format: info.format, line_id: info.line_id, created_at: '', created_by: '' };
+            },
+        });
+    }
+    async function finalise(docId, snapshot, options, credential = SESSION) {
+        const parsed = unwrapJoinResponse(snapshot, isSnapshotResponse, 'snapshot');
+        // A caller who asked for a read-only document is told so in the words for
+        // that, not a share link's.
+        const asked = options?.documentOptions;
+        const doc = await materialiseAs(credential, parsed, readOnlyForGrant(parsed, asked?.readOnly === true && asked.readOnlyReason === undefined
+            ? { ...asked, readOnlyReason: 'snapshot' }
+            : asked), options?.onSnapshotProgress);
+        // Populate `doc.status` from the join before the first `doc_status` frame.
         if (parsed.status !== undefined)
             doc._emitStatus(parsed.status);
+        doc._setImportReport(importReportOf(parsed));
+        setJoinStamp(doc, parsed.updated_at);
+        doc._awaitsImport = parsed.awaits_import === true;
         // 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
@@ -1148,12 +1846,13 @@ export function createOpenDocument(opts) {
         // snapshot / ops are no-ops in Loro.
         const refetchAndImport = async () => {
             const endPerf = perfStart('doc: content reload (fetch + import)');
-            const token = await requireToken();
             // Refetch the branch this doc was opened on, not the default. `parsed`
             // is the opened-branch join, so its `branch_id` is authoritative;
             // dropping it would import the default branch's snapshot + tail into a
             // doc open on another branch and silently merge the wrong CRDT state.
-            const result = await fetchSnapshot(docId, { branch: parsed.branch_id }, token);
+            // The open's read intent too: a reader who opened a record set as one
+            // re-joins as one, rather than as a writer whose join converts it.
+            const result = await joinAs(credential, docId, rejoinOptions(parsed.branch_id, options));
             if (result.status < 200 || result.status >= 300) {
                 endPerf({ ok: false, joinStatus: result.status });
                 return { ok: false, reason: `join fetch returned ${result.status}` };
@@ -1162,39 +1861,35 @@ export function createOpenDocument(opts) {
                 endPerf({ ok: false, joinStatus: result.status });
                 return { ok: false, reason: 'malformed join response' };
             }
-            const snap = result.parsed.snapshot;
-            let snapshotBytes = null;
-            if (snap !== null && snap.kind === 'inline') {
-                snapshotBytes = base64ToBytes(snap.data_b64);
-            }
-            else if (snap !== null && snap.kind === 'presigned') {
+            doc._awaitsImport = result.parsed.awaits_import === true;
+            let applied;
+            try {
                 // Stream through the same progress sink the initial open uses, so the
                 // session surfaces "Downloading... NN%" instead of sitting on the
                 // last server phase.
-                try {
-                    snapshotBytes = await fetchPresignedSnapshot(snap.url, options?.onSnapshotProgress);
-                }
-                catch (err) {
-                    const status = err instanceof BrassError ? err.status ?? 0 : 0;
-                    endPerf({ ok: false, snapshotStatus: status });
-                    return {
-                        ok: false,
-                        reason: status > 0
-                            ? `presigned snapshot fetch returned ${status}`
-                            : `presigned snapshot fetch failed: ${err instanceof Error ? err.message : String(err)}`,
-                    };
-                }
+                applied = await applyJoin(doc, result.parsed, (url) => fetchPresignedSnapshot(url, options?.onSnapshotProgress));
+            }
+            catch (err) {
+                const status = err instanceof BrassError ? err.status ?? 0 : 0;
+                endPerf({ ok: false, snapshotStatus: status });
+                return {
+                    ok: false,
+                    reason: status > 0
+                        ? `snapshot read returned ${status}`
+                        : `snapshot read failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
             }
-            if (snapshotBytes)
-                doc._applySnapshot(snapshotBytes);
-            const sortedTail = [...result.parsed.tail_ops].sort((a, b) => a.seq - b.seq);
+            if (applied.kind !== 'applied') {
+                endPerf({ ok: true, joinStatus: result.status, reloaded: applied.kind === 'reloaded' });
+                return { ok: true, status: result.parsed.status };
+            }
+            const tailSeqs = applied.tailSeqs;
             let maxTailSeq = 0;
-            for (const entry of sortedTail) {
-                doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
-                if (entry.seq > currentSeq)
-                    currentSeq = entry.seq;
-                if (entry.seq > maxTailSeq)
-                    maxTailSeq = entry.seq;
+            for (const seq of tailSeqs) {
+                if (seq > currentSeq)
+                    currentSeq = seq;
+                if (seq > maxTailSeq)
+                    maxTailSeq = seq;
             }
             const fetchedSeq = typeof result.parsed.current_seq === 'number'
                 ? result.parsed.current_seq
@@ -1215,19 +1910,13 @@ export function createOpenDocument(opts) {
             // 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));
-            }
+            raiseCoverage(joinCoverageFloor(snapshotSeqOf(result.parsed.snapshot_seq, tailSeqs, fetchedSeq), tailSeqs));
             for (const seq of tailSeqs)
                 advanceCoverage(seq);
             endPerf({
                 ok: true,
-                snapshotBytes: snapshotBytes?.byteLength ?? 0,
-                tailOps: sortedTail.length,
+                snapshotBytes: applied.content.kind === 'crdt' ? applied.content.bytes.byteLength : 0,
+                tailOps: tailSeqs.length,
             });
             return { ok: true, status: result.parsed.status };
         };
@@ -1237,10 +1926,9 @@ export function createOpenDocument(opts) {
         // nothing (the handshake only needs the frontier to diff against), so it
         // is one cheap JSON round-trip.
         const refetchDurableFrontier = async () => {
-            const token = await requireToken();
             // Same-branch as `refetchAndImport`: the durability handshake must diff
             // against the opened branch's frontier, not the default branch's.
-            const result = await fetchSnapshot(docId, { branch: parsed.branch_id }, token);
+            const result = await joinAs(credential, docId, rejoinOptions(parsed.branch_id, options));
             if (result.status < 200 || result.status >= 300)
                 return null;
             if (!isSnapshotResponse(result.parsed))
@@ -1338,6 +2026,49 @@ export function createOpenDocument(opts) {
                 retryPullOnNextFrame = !imported;
             })();
         };
+        // The row's work status as it is now, read without a snapshot, for a
+        // frame whose claim about the row needs checking.
+        const readWorkStatus = async () => {
+            const body = (await readStatusAs(credential, docId));
+            return parseWorkStatus(body.status);
+        };
+        // A `pending` frame that would take a settled document back to loading is
+        // checked against the row before it locks anything. A frame is the
+        // stream's view of the row at the time of that write, delivered after the
+        // stream's own lag, while the reconcile above reads the row directly: a
+        // client that reconciles between a hydration's last phase write and the
+        // stream delivering it has already imported the content when that
+        // phase's frame arrives, and applying it locks a document whose work is
+        // done. An importer that ran off the reconcile's own ready status then
+        // writes into that lock and is refused. Progress inside a run the
+        // document already shows as pending applies without a read; only the
+        // regression from settled to pending pays one, and that one read answers
+        // for every frame that arrives while it is out. A read that fails applies
+        // the frame, since locking is the side that loses nothing.
+        let pendingVerifyInFlight = false;
+        const verifyPendingStatus = (status) => {
+            if (pendingVerifyInFlight)
+                return;
+            pendingVerifyInFlight = true;
+            void (async () => {
+                let current = 'unread';
+                try {
+                    current = await readWorkStatus();
+                }
+                catch {
+                    // Unread: the frame stands.
+                }
+                finally {
+                    pendingVerifyInFlight = false;
+                }
+                if (current === 'unread') {
+                    doc._emitStatus(status);
+                }
+                else if (current !== null && current.pending) {
+                    doc._emitStatus(current);
+                }
+            })();
+        };
         // 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.
@@ -1347,15 +2078,15 @@ export function createOpenDocument(opts) {
             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 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 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.
+        // Reconcile pending work once the live subscription exists (a resubscribe
+        // while work runs). The terminal `doc_status` frame is best-effort: if the
+        // work finishes while this client has no subscription record, the fan-out
+        // finds no subscriber and drops the frame, stranding the app on the pending
+        // overlay. `doc_init` is posted only after the subscription record is
+        // written, so one re-fetch here closes the gap. Only a pending document
+        // pays the extra fetch.
         const reconcileStatusOnInit = () => {
-            const current = doc.status;
+            const current = doc._workStatusNow;
             if (!current || !current.pending)
                 return;
             if (reconcileInFlight || reloadInFlight)
@@ -1401,14 +2132,16 @@ export function createOpenDocument(opts) {
         // `op_ack` would have. Targets the branch this doc was opened on, the
         // same branch the transport's topic is scoped to.
         const postOversizedOp = async (opBlobB64, clientOpId) => {
-            const token = await requireToken();
-            const { status, parsed: opResult } = await postDocumentOp(docId, parsed.branch_id, opBlobB64, clientOpId, token);
+            const { status, parsed: opResult } = await postOpAs(credential, docId, parsed.branch_id, opBlobB64, clientOpId, baseImportSeqField(doc));
             if (status < 200 || status >= 300) {
                 return {
                     ok: false,
                     message: opWriteFailureMessage(status, opResult),
                     retryable: opWriteIsRetryable(status),
                     atCapacity: isCapacityRefusal(status, opResult),
+                    ...(isMovedRefusal(opResult) ? { moved: true } : {}),
+                    ...(isNotImportedRefusal(opResult) ? { notImported: true } : {}),
+                    ...(status === 413 ? { tooLarge: true } : {}),
                     // 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' } : {}),
@@ -1424,7 +2157,8 @@ export function createOpenDocument(opts) {
             }
             return { ok: true, seq };
         };
-        if (opts.wsClient) {
+        const docWsClient = wsClientFor(credential);
+        if (docWsClient) {
             wireDocTransport({
                 doc,
                 docId,
@@ -1441,7 +2175,10 @@ export function createOpenDocument(opts) {
                     ? { documentOptions: options.documentOptions }
                     : {}),
                 ...(opts.identity !== undefined ? { identity: opts.identity } : {}),
-                wsClient: opts.wsClient,
+                // A link's open is parked under nobody, and a frozen copy hears
+                // whole-document notices rather than joining the room.
+                ...(credential.kind === 'session' ? {} : { parkable: false, skipPresence: options?.frozen === true }),
+                wsClient: docWsClient,
                 postOversizedOp,
                 newClientOpId: opts.newClientOpId ?? defaultClientOpIdMinter,
                 getCurrentSeq: () => currentSeq,
@@ -1455,88 +2192,14 @@ export function createOpenDocument(opts) {
                 refetchDurableFrontier,
                 reloadAfterHydration,
                 reconcileStatusOnInit,
+                verifyPendingStatus,
                 onDocumentMoved: retryContentPull,
             });
         }
-        // `doc._checkoutVersion(v)` calls back here to materialise historical
-        // state, leaving the live subscription untouched.
-        doc.setCheckoutFetcher(makeCheckoutFetcher());
-        // Wire the branch provider + populate the initial list, so the
-        // toolbar's branch chip can name the branch on the next subscribe
-        // tick. Branch management is hosted; this list feeds the SDK's own
-        // chrome, not an app method.
-        if (opts.branchProvider) {
-            doc.setBranchProvider(opts.branchProvider);
-            void doc._refreshBranches().catch(() => {
-                // Best-effort: a failure leaves the chip unnamed until a hosted
-                // branch action refreshes the list.
-            });
-        }
-        // `doc.useCanvas(canvas)` captures + uploads after each local commit; the
-        // doc handles debounce + readOnly gating internally.
-        if (opts.thumbnailUploader) {
-            const uploader = opts.thumbnailUploader;
-            doc.setThumbnailUploader(async (image, width, height) => {
-                await uploader(doc, image, width, height);
-            });
-        }
-        doc._setThumbnailVersion(parsed.thumbnail?.version ?? null);
-        if (opts.checkpointCreator) {
-            const creator = opts.checkpointCreator;
-            doc.setCheckpointCreator(() => creator(doc));
-        }
-        if (opts.drivePusher) {
-            const pusher = opts.drivePusher;
-            doc.setDrivePusher((input) => pusher(doc, input));
-        }
-        // `doc.resolveDrive()` opens the hosted resolution surface and, when it
-        // mints a new mirror doc (take-source / keep-both), re-opens onto it via
-        // the same `openSiblingDoc` path the `history` fork uses.
-        const hostedForResolve = opts.hostedUiProvider;
-        const resolveSurface = hostedForResolve?.driveResolve;
-        if (hostedForResolve && resolveSurface) {
-            doc.setDriveResolver(async () => {
-                const docId = doc.id;
-                if (docId === null)
-                    return null;
-                const result = await resolveSurface(docId);
-                if (result?.newDocId && hostedForResolve.openSiblingDoc) {
-                    await hostedForResolve.openSiblingDoc(result.newDocId, {});
-                }
-                return result;
-            });
-        }
-        if (opts.sourceBlobFetcher) {
-            const fetcher = opts.sourceBlobFetcher;
-            doc.setSourceBlobFetcher(() => fetcher(doc));
-        }
-        doc.setOpenedStreamName(options?.stream ?? DEFAULT_STREAM_NAME);
-        // Streams: manifest list/create over HTTP plus the per-line open
-        // (join + WS subscribe). Bound to the BRANCH this Document opened on,
-        // which is not the line it materialized when the open named a stream: a
-        // manifest belongs to a branch and a line owns none, so binding to the
-        // line would leave `doc.stream(name)` resolving against nothing.
-        if (opts.streamProvider) {
-            const provider = opts.streamProvider;
-            const openedBranchId = parsed.stream_branch_id ?? parsed.branch_id;
-            doc.setStreamRuntime({
-                list: async () => (await provider.list(docId, openedBranchId)).streams,
-                create: (name) => provider.create(docId, openedBranchId, name),
-                openLine: (lineId) => openStreamLine(docId, lineId),
-            });
-        }
-        // Hosted-UI provider backing the doc's built-in `history` / `details` /
-        // `share` / `delete` commands.
-        if (opts.hostedUiProvider) {
-            doc.setHostedUiProvider(opts.hostedUiProvider);
-            const refreshName = opts.hostedUiProvider.refreshName;
-            if (refreshName && docId) {
-                void refreshName(docId).then((name) => {
-                    if (name !== null)
-                        doc._setName(name);
-                });
-            }
-        }
+        if (credential.kind === 'session')
+            wireSessionCapabilities(doc, docId, parsed, options);
+        else
+            wireLinkCapabilities(doc, docId, parsed, credential, options, doc.readOnly !== true);
         if (opts.reportError)
             doc.setErrorReporter(opts.reportError);
         // No socket on a document the caller can write to: the write path reaches
@@ -1553,16 +2216,8 @@ export function createOpenDocument(opts) {
     // through `documentOptions` and `wireDocTransport` is skipped (a frozen
     // point has no live op stream).
     async function openAtVersion(docId, version, options, token) {
-        const { status, parsed, parseFailed } = await fetchAtVersion(docId, version, options.branch, token);
-        if (status < 200 || status >= 300) {
-            throw brassErrorFromBody(status, parseFailed ? undefined : parsed);
-        }
-        if (!isAtVersionResponse(parsed)) {
-            throw new BrassError('Malformed document at-version response', {
-                status: 500,
-            });
-        }
-        return materialise({
+        const parsed = unwrapJoinResponse(await fetchAtVersion(docId, version, options.branch, token), isAtVersionResponse, 'at-version');
+        return materialiseAs(SESSION, {
             doc_id: docId,
             branch_id: parsed.branch_id,
             snapshot: parsed.snapshot,
@@ -1577,30 +2232,46 @@ export function createOpenDocument(opts) {
     // Sends NO Authorization header (the token is the credential), so it must
     // not go through the auth-bearing `fetchSnapshot`. The server returns the
     // same snapshot + tail_ops envelope, member-stripped and read-only.
-    async function fetchLinkView(token, branch) {
+    async function fetchLinkView(token, 
+    // The line, and whether this guest will write. A view link's reader never
+    // does, and an edit link's may, which is the same question the
+    // authenticated join asks with `intent=read` and decides the same thing:
+    // whether a document the platform stores frozen is served as it stands or
+    // converted first.
+    join, progress, { rejoin = false } = {}) {
+        const once = () => linkViewOnce(token, join, rejoin);
+        // An edit link's guest waits out a conversion as a member's editable open
+        // does.
+        return opensReadOnly(join) ? once() : waitWhileConverting(once, progress);
+    }
+    async function linkViewOnce(token, join, rejoin) {
         const search = new URLSearchParams();
         search.set('include', 'snapshot');
-        if (branch !== undefined)
-            search.set('branch', branch);
-        const url = `${baseUrl}/links/${encodeURIComponent(token)}/view?${search.toString()}`;
-        const response = await fetchWithRetry(() => fetch(url, { method: 'GET' }));
-        const text = await response.text();
-        let parsed = undefined;
-        let parseFailed = false;
-        if (text) {
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parseFailed = true;
-            }
+        search.set('app_id', opts.appId);
+        if (rejoin)
+            search.set('rejoin', '1');
+        const headers = await linkViewHeaders();
+        // A person signed in here who reaches the document on their own opens it
+        // as themselves, with their own role and identity.
+        if (!rejoin && headers['authorization'] !== undefined)
+            search.set('as_member', '1');
+        if (join.branch !== undefined)
+            search.set('branch', join.branch);
+        if (opensReadOnly(join))
+            search.set('intent', 'read');
+        return sendJoin(`/links/${encodeURIComponent(token)}/view`, search, { headers });
+    }
+    // A link open carries no credential unless the person signed in on this
+    // link page, in which case it carries theirs.
+    async function linkViewHeaders() {
+        const headers = {};
+        applyClientVersionHeader(headers);
+        const credential = (await opts.getLinkCredential?.()) ?? null;
+        if (credential !== null) {
+            headers['authorization'] = `Bearer ${credential.accessToken}`;
+            headers['x-brass-app-assertion'] = credential.appAssertion;
         }
-        // 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 };
+        return headers;
     }
     // `GET /links/{token}/streams`: the anonymous stream manifest, the guest
     // counterpart of the signed-in streams list. No Authorization header (the
@@ -1608,7 +2279,9 @@ export function createOpenDocument(opts) {
     // `doc.stream(name)` resolves against.
     async function fetchLinkStreamManifest(token) {
         const url = `${baseUrl}/links/${encodeURIComponent(token)}/streams`;
-        const response = await fetchWithRetry(() => fetch(url, { method: 'GET' }));
+        const headers = {};
+        applyClientVersionHeader(headers);
+        const response = await fetchWithRetry(() => fetch(url, { method: 'GET', headers }));
         const text = await response.text();
         if (response.status < 200 || response.status >= 300) {
             let parsed = undefined;
@@ -1639,102 +2312,57 @@ export function createOpenDocument(opts) {
             ]
             : []);
     }
-    const openByLink = async (token, options) => {
-        const { status, parsed, parseFailed } = await fetchLinkView(token, options?.branch);
-        if (status < 200 || status >= 300) {
-            throw brassErrorFromBody(status, parseFailed ? undefined : parsed);
+    const openByLink = async (token, asked) => {
+        const options = withReadIntent(asked);
+        const view = await fetchLinkView(token, rejoinOptions(options?.branch, options), options?.onSnapshotProgress);
+        if (view.status < 200 || view.status >= 300) {
+            throw brassErrorFromBody(view.status, view.parseFailed ? undefined : view.parsed);
         }
-        const b = parsed;
-        if (typeof b.doc_id !== 'string' ||
-            typeof b.branch_id !== 'string' ||
-            !Array.isArray(b.tail_ops)) {
+        const b = view.parsed;
+        if (typeof b.doc_id !== 'string') {
             throw new BrassError('Malformed link view response', { status: 500 });
         }
-        // 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 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';
-        const doc = await materialise({
-            doc_id: b.doc_id,
-            branch_id: b.branch_id,
-            snapshot: b.snapshot,
-            tail_ops: b.tail_ops,
-        }, { ...options?.documentOptions, readOnly: !canEdit }, options?.onSnapshotProgress);
-        // The view carries the document's display name; set it so the guest
-        // sees the title (the signed-in open gets this from `finalise`).
-        if (typeof b.name === 'string')
-            doc._setName(b.name);
-        // 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
-        // token-authenticated socket. `create` is refused (a guest cannot mint
-        // a line). Absent when there is no WS client (a snapshot-only guest),
-        // matching the default stream having no live transport there.
-        doc.setStreamRuntime({
-            list: () => fetchLinkStreamManifest(token),
-            openLine: async (lineId) => {
-                const view = await fetchLinkView(token, lineId);
-                if (view.status < 200 || view.status >= 300) {
-                    throw brassErrorFromBody(view.status, view.parseFailed ? undefined : view.parsed);
-                }
-                const lb = view.parsed;
-                if (typeof lb.doc_id !== 'string' ||
-                    typeof lb.branch_id !== 'string' ||
-                    !Array.isArray(lb.tail_ops)) {
-                    throw new BrassError('Malformed link stream view response', {
-                        status: 500,
-                    });
-                }
-                const inner = await materialise({
-                    doc_id: lb.doc_id,
-                    branch_id: lb.branch_id,
-                    snapshot: lb.snapshot,
-                    tail_ops: lb.tail_ops,
-                }, { readOnly: !canEdit });
-                if (opts.reportError)
-                    inner.setErrorReporter(opts.reportError);
-                wireGuestTransport(inner, token, lb.doc_id, lb.branch_id, canEdit);
-                return inner;
-            },
-            create: () => {
-                throw new BrassError('A shared-link guest cannot create streams.', {
-                    status: 403,
-                });
-            },
-        });
+        if (b.opens_as_member === true) {
+            return (opts.openAsMember ?? open)(b.doc_id, asked);
+        }
+        // The link's grant decides read vs write; the view answers `can_edit`
+        // as the member join does, so a view link reads as a viewer's grant.
+        const canEdit = b.link_role === 'editor' && b.can_edit !== false;
+        const askedToRead = canEdit && opensReadOnly(options);
+        const linkOptions = {
+            ...options,
+            documentOptions: askedToRead
+                ? { ...options?.documentOptions, readOnly: true, readOnlyReason: 'snapshot' }
+                : canEdit
+                    ? { ...options?.documentOptions }
+                    : { ...options?.documentOptions, readOnly: true, readOnlyReason: 'link' },
+        };
+        // A document minted without an account names when the platform removes
+        // it; every other link carries neither key.
+        const expiresAt = anonymousExpiry(b);
+        const credential = expiresAt !== null ? { kind: 'temporary', token } : { kind: 'link', token };
+        const doc = await finalise(b.doc_id, view, linkOptions, credential);
+        if (expiresAt !== null) {
+            doc._setExpiresAt(expiresAt);
+            // A document the visitor started from a file is imported by this app
+            // in this page, so it reads its file through the link as a member's
+            // import reads it through the document.
+            const imports = guestImports(token, b.doc_id);
+            doc.setSourceBlobFetcher(() => imports.sourceBlob());
+            doc._awaitsImport = canEdit && b.awaits_import === true;
+        }
         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,
-            }),
+    // A read through a route a member's open reads, with the link as the
+    // credential. A 404 answers null, as the session's reads of the same
+    // routes do.
+    async function getWithLink(token, path, query) {
+        const search = new URLSearchParams(query).toString();
+        const response = await fetch(`${baseUrl}${search ? `${path}?${search}` : path}`, {
+            headers: { authorization: `Link ${token}` },
         });
+        if (response.status === 404)
+            return null;
         const text = await response.text();
         let parsed = undefined;
         try {
@@ -1743,316 +2371,77 @@ export function createOpenDocument(opts) {
         catch {
             parsed = undefined;
         }
-        return { status: response.status, parsed };
+        if (response.status < 200 || response.status >= 300) {
+            throw brassErrorFromBody(response.status, parsed);
+        }
+        return 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). Best-effort on the read side (no resync / durability
-    // handshake, which need a signed-in token); a guest that misses ops
-    // 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) {
-            // No socket: a write would change local state and reach no server, so
-            // the document reports the first one instead of discarding it quietly.
-            if (canEdit)
-                doc.markTransportUnavailable();
-            return;
+    // A write through a route a member's open writes, with the link as the
+    // credential. Resolves the parsed body, or rejects with the server's
+    // refusal.
+    async function postWithLink(token, path, body) {
+        const response = await fetch(`${baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Link ${token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await response.text();
+        let parsed = undefined;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
         }
-        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) => {
-            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;
-            }
-            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, 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 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)) {
-                // 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();
-                const opBlobB64 = bytesToBase64(opBlob);
-                const sendFrame = {
-                    type: 'op',
-                    topic,
-                    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;
-            });
+        catch {
+            parsed = undefined;
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw brassErrorFromBody(response.status, parsed);
         }
-        const originalClose = doc.close.bind(doc);
-        doc.close = () => {
-            clearShedRecovery();
-            try {
-                unsub();
-            }
-            catch {
-                // Already detached; closing the Document is what matters.
-            }
-            originalClose();
-        };
+        return parsed;
     }
-    // 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)}`,
-                };
-            }
+    // 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. An op past
+    // what a request body carries is staged first, as a member's is.
+    async function postLinkOp(token, docId, lineId, opBlobB64, clientOpId, base = {}) {
+        const stagedKey = opBlobNeedsStaging(opBlobB64)
+            ? await stageOpBlob(docId, opBlobB64, { link: token })
+            : undefined;
+        const headers = { 'content-type': 'application/json' };
+        applyClientVersionHeader(headers);
+        const response = await fetch(`${baseUrl}/links/${encodeURIComponent(token)}/ops`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                ...(stagedKey === undefined ? { op_blob: opBlobB64 } : { upload_key: stagedKey }),
+                branch_id: lineId,
+                client_op_id: clientOpId,
+                ...base,
+            }),
+        });
+        const text = await response.text();
+        let parsed = undefined;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
         }
-        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));
+        catch {
+            parsed = undefined;
         }
-        return { ok: true };
+        return { status: response.status, parsed };
     }
     // Strict open: a 404 propagates as `BrassError`. A `version` option
     // diverts to the read-only at-version path.
-    const open = async (docId, options) => {
+    const open = async (docId, asked) => {
+        if (asked?.frozen === true && asked.readOnly === false) {
+            throw new TypeError('openDocumentById: a frozen copy is read-only, so `readOnly: false` cannot apply');
+        }
+        const requested = withReadIntent(asked);
+        const options = requested?.frozen === true ? frozenOptions(requested) : requested;
+        if (requested?.frozen === true)
+            return openFrozen(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.
@@ -2068,11 +2457,40 @@ export function createOpenDocument(opts) {
             endTotal({ docId, path: 'at-version' });
             return atVersion;
         }
-        const snapshot = await fetchSnapshot(docId, options, token);
+        // An editable open waits until the document takes edits. One that never
+        // will is refused terminally, and is then read as a reader would read it.
+        // An import the platform runs holds every open until it lands, the file's
+        // first import or a new version's, so the open resolves with its content.
+        let snapshot = await fetchSnapshot(docId, options, token);
+        snapshot = await joinPastWork(docId, options, snapshot, async () => fetchSnapshot(docId, options, await requireToken()));
+        const refused = joinRefusalOf(snapshot);
+        if (refused?.kind === 'at_capacity') {
+            const held = await openTooLarge(docId, options, refused.error);
+            endTotal({ docId, path: 'read-only:at_capacity' });
+            return held;
+        }
         const opened = await finalise(docId, snapshot, options);
         endTotal({ docId });
         return opened;
     };
+    // A writable open of a document too large to edit, joined again as a
+    // reader and shown read-only.
+    async function openTooLarge(docId, options, error) {
+        const readOptions = {
+            ...options,
+            documentOptions: {
+                ...options?.documentOptions,
+                readOnly: true,
+                readOnlyReason: 'too_large',
+            },
+        };
+        const snapshot = await fetchSnapshot(docId, readOptions, await requireToken());
+        const doc = await finalise(docId, snapshot, readOptions);
+        doc._markAtCapacity();
+        if (error !== undefined)
+            doc._emitStatus({ message: error, pending: false, blocking: false });
+        return doc;
+    }
     // Create a doc and return it fully editable. Two round trips (POST to
     // create + obtain the doc_id, then `open(docId)`); they aren't fused
     // because the create response is metadata-only and the open path already
@@ -2109,7 +2527,239 @@ export function createOpenDocument(opts) {
             : undefined;
         return open(result.docId, openOptions);
     };
-    return { open, create, createDocumentId, openByLink };
+    // The mint's answer is the claim secret's only copy, so it is kept as it
+    // arrives, in the browser that made the document.
+    const rememberClaimSecret = (minted) => {
+        if (minted.claimSecret !== undefined) {
+            storeClaimSecret(opts.appId, minted.linkToken, minted.claimSecret, minted.expiresAt);
+        }
+        return minted;
+    };
+    const mintAnonymousDocument = async (args) => {
+        const body = { app_id: opts.appId };
+        if (args.name !== undefined)
+            body['name'] = args.name;
+        const headers = {
+            'content-type': 'application/json',
+        };
+        applyClientVersionHeader(headers);
+        // No idempotency key on this route, so a replay could mint twice;
+        // only the gateway's own 503 (the handler never ran) is replayed.
+        const response = await fetchWithRetry(() => fetch(`${baseUrl}/anonymous-documents`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        }), { policy: RETRY_WRITE_503, baseDelayMs: 250 });
+        const text = await response.text();
+        let parsed = undefined;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw brassErrorFromBody(response.status, parsed);
+        }
+        return rememberClaimSecret(parseMintedAnonymousDocument(parsed));
+    };
+    // The unauthenticated JSON calls a visitor's file-started document makes.
+    const postAnonymous = async (path, body) => {
+        const headers = { 'content-type': 'application/json' };
+        applyClientVersionHeader(headers);
+        const response = await fetchWithRetry(() => fetch(`${baseUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        }), { policy: RETRY_WRITE_503, baseDelayMs: 250 });
+        const parsed = await readJsonBody(response);
+        if (response.status < 200 || response.status >= 300) {
+            throw brassErrorFromBody(response.status, parsed);
+        }
+        return parsed;
+    };
+    const anonymousUploadTypes = async () => {
+        const headers = {};
+        applyClientVersionHeader(headers);
+        // `refusal=body` answers an app's refusal of signed-out use in a 200 body,
+        // which keeps an expected answer out of the visitor's console.
+        const response = await fetchWithRetry(() => fetch(`${baseUrl}/anonymous-documents/upload-types?app_id=${encodeURIComponent(opts.appId)}&refusal=body`, { headers }), { policy: RETRY_WRITE_503, baseDelayMs: 250 });
+        const parsed = await readJsonBody(response);
+        if (response.status < 200 || response.status >= 300) {
+            throw brassErrorFromBody(response.status, parsed);
+        }
+        const body = parsed;
+        const offersNew = body?.offers_new !== false;
+        if (body?.refusal !== undefined) {
+            return { offersNew, refusal: brassErrorFromBody(409, body.refusal) };
+        }
+        return { offersNew, accept: acceptFromUploadTypes(parsed) };
+    };
+    const mintAnonymousDocumentFromFile = async (args) => {
+        const minted = (await postAnonymous('/anonymous-documents/upload-url', {
+            app_id: opts.appId,
+            file_name: args.file.name,
+            byte_size: args.file.size,
+        }));
+        if (typeof minted?.upload_url !== 'string' || typeof minted.upload_key !== 'string') {
+            throw new BrassError('Malformed upload response', { status: 500 });
+        }
+        await putFile(minted.upload_url, args.file, args.onUploadProgress);
+        const body = {
+            app_id: opts.appId,
+            upload_key: minted.upload_key,
+            file_name: args.file.name,
+        };
+        if (args.name !== undefined)
+            body['name'] = args.name;
+        return rememberClaimSecret(parseMintedAnonymousDocument(await postAnonymous('/anonymous-documents/from-upload', body)));
+    };
+    // One client id per page, which is what holds a claim across the calls
+    // of one import (the signed-in namespace keeps its own).
+    const guestImportClientId = randomToken();
+    const guestImports = (token, docId) => {
+        const base = `${baseUrl}/documents/${encodeURIComponent(docId)}`;
+        const call = async (method, path, body) => {
+            const headers = { authorization: `Link ${token}` };
+            if (body !== undefined)
+                headers['content-type'] = 'application/json';
+            applyClientVersionHeader(headers);
+            const response = await fetchWithRetry(() => fetch(`${base}${path}`, {
+                method,
+                headers,
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            }), { policy: RETRY_WRITE_503, baseDelayMs: 250 });
+            const parsed = await readJsonBody(response);
+            if (response.status < 200 || response.status >= 300) {
+                throw brassErrorFromBody(response.status, parsed);
+            }
+            return parsed;
+        };
+        return {
+            claimImport: () => call('POST', '/import-claim', {
+                client_id: guestImportClientId,
+                stages: true,
+            }),
+            async stageImport(bundle) {
+                const staged = await call('POST', '/import-complete/upload', { byte_size: bundle.byteLength });
+                const put = await fetch(staged.url, {
+                    method: 'PUT',
+                    body: bundle.buffer.slice(bundle.byteOffset, bundle.byteOffset + bundle.byteLength),
+                });
+                if (!put.ok) {
+                    throw new BrassError('Uploading the import failed', { status: put.status });
+                }
+                return staged.upload_key;
+            },
+            completeImport: async (report, uploadKey) => awaitSeal(await call('POST', '/import-complete', {
+                client_id: guestImportClientId,
+                ...(report !== undefined ? { report } : {}),
+                upload_key: uploadKey,
+            }), (sealId) => call('GET', `/seals/${encodeURIComponent(sealId)}`)),
+            failImport: (message) => call('POST', '/import-failed', {
+                client_id: guestImportClientId,
+                message,
+            }),
+            sourceBlob: () => call('GET', '/source-blob'),
+        };
+    };
+    const claimAnonymousDocument = async (docId, args) => {
+        const token = await requireToken();
+        const body = {
+            link_token: args.linkToken,
+            claim_secret: args.claimSecret,
+        };
+        if (args.destination !== undefined)
+            body['destination'] = args.destination;
+        if (args.name !== undefined)
+            body['name'] = args.name;
+        const headers = {
+            authorization: `Bearer ${token}`,
+            'content-type': 'application/json',
+        };
+        applyClientVersionHeader(headers);
+        await applyAppAssertionHeader(headers, opts.getAppAssertion);
+        const response = await fetchWithRetry(() => fetch(`${baseUrl}/documents/${encodeURIComponent(docId)}/claim`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        }), { policy: RETRY_WRITE_503, baseDelayMs: 250 });
+        const text = await response.text();
+        let parsed = undefined;
+        let parseFailed = false;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parseFailed = true;
+            }
+        }
+        if (response.status >= 200 && response.status < 300) {
+            return { kind: 'claimed', record: selectionFromDetail(parsed) };
+        }
+        if (response.status === 409 && !parseFailed) {
+            const code = parsed?.code;
+            if (code === 'destination_required')
+                return { kind: 'needs-destination' };
+            if (code === 'no_organization')
+                return { kind: 'needs-organization' };
+        }
+        throw brassErrorFromBody(response.status, parseFailed ? undefined : parsed);
+    };
+    return {
+        open,
+        create,
+        createDocumentId,
+        openByLink,
+        mintAnonymousDocument,
+        anonymousUploadTypes,
+        mintAnonymousDocumentFromFile,
+        guestImports,
+        claimAnonymousDocument,
+    };
+}
+// The claimed document in the picker's shape, read off the claim's
+// `DocumentDetail` answer; null when a field the shape needs is missing.
+function selectionFromDetail(parsed) {
+    const d = parsed;
+    if (!d || typeof d !== 'object')
+        return null;
+    const str = (key) => typeof d[key] === 'string' ? d[key] : null;
+    const docId = str('doc_id');
+    const organizationId = str('organization_id');
+    const name = str('name');
+    const createdAt = str('created_at');
+    const updatedAt = str('updated_at');
+    const role = d['role'];
+    const projectId = d['project_id'];
+    if (docId === null ||
+        organizationId === null ||
+        name === null ||
+        createdAt === null ||
+        updatedAt === null ||
+        (role !== 'owner' && role !== 'editor' && role !== 'viewer') ||
+        (projectId !== null && typeof projectId !== 'string')) {
+        return null;
+    }
+    return {
+        doc_id: docId,
+        organization_id: organizationId,
+        project_id: projectId ?? null,
+        role,
+        name,
+        created_at: createdAt,
+        updated_at: updatedAt,
+    };
+}
+// The expiry a link view carries for a document minted without an account,
+// or null for every other link.
+function anonymousExpiry(body) {
+    if (body.anonymous !== true || typeof body.expires_at !== 'string') {
+        return null;
+    }
+    const at = new Date(body.expires_at);
+    return Number.isNaN(at.getTime()) ? null : at;
 }
 // Per-process parking cache for opened Documents. `doc.close()` does NOT
 // free the LoroDoc / UndoController; it parks the Document keyed on
@@ -2172,8 +2822,15 @@ function parkDocument(entry) {
     }
 }
 function takeParkedDocument(docId, options, identity) {
+    // A parked Document is a live, writable session with its subscription still
+    // alive. Neither pinned open may take one: it would hand back a document
+    // that receives ops and accepts writes, which is the opposite of what both
+    // asked for. Parking itself already refuses them (`!doc.readOnly`), so this
+    // is the other half of that.
     if (options?.version !== undefined)
         return null;
+    if (options?.frozen === true)
+        return null;
     const key = parkCacheKey(docId, options?.branch, options?.stream);
     if (!key)
         return null;
@@ -2209,6 +2866,23 @@ export function clearParkedDocuments() {
 // a clean slate between cases.
 export function _resetParkCacheForTesting() {
     clearParkedDocuments();
+    subscriptionEndedAt.clear();
+}
+// When each doc topic last had its subscription ended by the server, so a
+// copy re-opened after one ends for good on a second inside the window. The
+// re-open asks the HTTP join, and a socket gate that keeps refusing what the
+// join admits would otherwise re-open the document in a loop.
+const SUBSCRIPTION_ENDED_REOPEN_WINDOW_MS = 60_000;
+const subscriptionEndedAt = new Map();
+function endedReasonFor(topic) {
+    const now = Date.now();
+    for (const [key, at] of subscriptionEndedAt) {
+        if (now - at >= SUBSCRIPTION_ENDED_REOPEN_WINDOW_MS)
+            subscriptionEndedAt.delete(key);
+    }
+    const recent = subscriptionEndedAt.has(topic);
+    subscriptionEndedAt.set(topic, now);
+    return recent ? 'deleted' : 'moved';
 }
 // Wire the WS transport onto a materialised Document. Three pieces:
 //   1. WS subscribe on the doc topic; the server sends `doc_op` (other
@@ -2260,6 +2934,16 @@ export const RESEND_MAX_DELAY_MS = 30_000;
 // server never received and nothing ever sends again.
 // Exported for the fake-timer tests.
 export const RESEND_FORCE_CEILING_MS = 60_000;
+// How long one op may go unacked on the socket before the reader is told,
+// through `status`, that their changes are not saved. A server that answers
+// an op anonymously every time (an error frame naming no op) draws a resend
+// per backoff step, or a forced one per ceiling window, forever, while
+// `savingCount` stays above zero with nothing on screen saying why. Three
+// ceiling windows is past any loss a resend recovers from, since a lost op
+// is answered on its first forced resend. The notice changes nothing about
+// how the op is resent, and clears itself once nothing is waiting.
+// Exported for the fake-timer tests.
+export const UNANSWERED_OP_NOTICE_MS = 3 * RESEND_FORCE_CEILING_MS;
 // 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
@@ -2276,14 +2960,7 @@ 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.';
+    'help. Reload 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);
@@ -2293,13 +2970,37 @@ function unavailableDelayMs(round) {
 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}`;
+    // A remote op over frozen content means the document is now a CRDT. The
+    // re-join keeps the open's read intent and is served that CRDT, which
+    // `applyJoin` swaps in under the same handles. A run that leaves the
+    // document on frozen content (the join failed, or the document is showing
+    // a version) falls back to the reload. Ops arriving during the run ask the
+    // resync for another pass rather than starting a second upgrade.
+    const resync = args.resyncFromSnapshot;
+    if (resync !== undefined) {
+        let upgradeRun = null;
+        args.doc._setStorageUpgrader(() => {
+            if (upgradeRun !== null) {
+                void Promise.resolve(resync()).catch(() => { });
+                return;
+            }
+            upgradeRun = (async () => {
+                try {
+                    await resync();
+                }
+                catch {
+                    // Judged by what the document holds afterwards.
+                }
+                const doc = args.doc;
+                if (doc._holdsRecordSet() && !doc._isClosed && doc._goneReason === null)
+                    doc._reopen();
+            })().finally(() => {
+                upgradeRun = null;
+            });
+        });
+    }
     // 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,
@@ -2376,6 +3077,8 @@ function wireDocTransport(args) {
         entry.queued = false;
         entry.inFlight = size;
         entry.dispatchedAt = Date.now();
+        if (entry.firstDispatchedAt === 0)
+            entry.firstDispatchedAt = entry.dispatchedAt;
         inFlightBytes += size;
         args.wsClient.send(entry.frame);
         scheduleResend(clientOpId);
@@ -2548,6 +3251,10 @@ function wireDocTransport(args) {
             const current = outstandingResends.get(clientOpId);
             if (!current)
                 return;
+            if (current.firstDispatchedAt !== 0 &&
+                Date.now() - current.firstDispatchedAt > UNANSWERED_OP_NOTICE_MS) {
+                args.doc._showConnectionNotice('unanswered');
+            }
             const forced = forceResendDue(clientOpId, current);
             if (lastAckAt >= current.armedAt && !forced) {
                 scheduleResend(clientOpId);
@@ -2665,6 +3372,26 @@ function wireDocTransport(args) {
         });
     }
     args.doc._setDiagnosticsProvider(collectDiagnostics);
+    // A network that refuses WebSocket upgrades opens the document over HTTP
+    // and then carries none of its edits: they apply locally and queue, and the
+    // reconnect loop reports only after its full budget (about five minutes),
+    // so a reload inside that window loses them with nothing said. When edits
+    // have waited `NEVER_OPENED_NOTICE_MS` on a client that has never opened a
+    // socket, the document says so on `status`. Never-opened rather than
+    // currently-closed, because a connection that has worked recovers through
+    // the resend machinery and a drop there is ordinarily brief.
+    let neverOpenedTimer = null;
+    function armNeverOpenedNotice() {
+        if (neverOpenedTimer !== null || args.wsClient.everOpened !== false)
+            return;
+        neverOpenedTimer = setTimeout(() => {
+            neverOpenedTimer = null;
+            if (args.wsClient.everOpened !== false || outstandingResends.size === 0)
+                return;
+            args.doc._showConnectionNotice();
+        }, NEVER_OPENED_NOTICE_MS);
+        neverOpenedTimer.unref?.();
+    }
     // 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
@@ -2723,15 +3450,18 @@ function wireDocTransport(args) {
     // 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.
+    // frame cap, so it heals the dependents of an op a transient refusal
+    // dropped.
     //
     // `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.
+    // write at all. An op too large for any transport this writer has is the
+    // same: a split runs between changes, never inside one, so the slice the
+    // handshake would push still carries the whole op, and every edit after it
+    // waits on an op the server will never hold.
     // 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
@@ -2808,7 +3538,27 @@ function wireDocTransport(args) {
         catch {
             // Told or not, the copy is resolved.
         }
-        args.doc.reload();
+        args.doc._reopen();
+    }
+    function markGone(reason) {
+        // 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 subscription record was evicted at fanout). Draining before the `_markGone`
+        // listeners keeps the lifecycle observably clean.
+        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;
+        }
+        args.doc._markGone(reason);
     }
     function failOpTerminally(clientOpId, message, opts = {}) {
         // Read before `_failOutstandingOp`, which clears the id from the
@@ -2854,6 +3604,22 @@ function wireDocTransport(args) {
         }, delay);
         unavailableTimer.unref?.();
     }
+    // The ops the durability handshake leaves to this transport: those still
+    // queued behind the in-flight budget, and those first sent too recently for
+    // their resend timer to have doubted them. An op past its first resend step
+    // is fair game for the handshake, since the resend path does not promise it
+    // arrives.
+    function deliveringOpBlobs() {
+        const now = Date.now();
+        const blobs = [];
+        for (const entry of outstandingResends.values()) {
+            if (entry.firstDispatchedAt === 0 ||
+                now - entry.firstDispatchedAt < RESEND_BASE_DELAY_MS) {
+                blobs.push(base64ToBytes(entry.frame.op_blob));
+            }
+        }
+        return blobs;
+    }
     // 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
@@ -2865,7 +3631,7 @@ function wireDocTransport(args) {
     function maybeResyncPush(snapshotVersionVectorB64, durableTailBlobs) {
         if (!snapshotVersionVectorB64)
             return;
-        const outcome = args.doc.maybeResyncPush(base64ToBytes(snapshotVersionVectorB64), durableTailBlobs);
+        const outcome = args.doc.maybeResyncPush(base64ToBytes(snapshotVersionVectorB64), durableTailBlobs, deliveringOpBlobs());
         // 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.
@@ -2902,7 +3668,7 @@ function wireDocTransport(args) {
                 try {
                     const frontier = await args.refetchDurableFrontier?.();
                     if (frontier && frontier.snapshotVersionVector) {
-                        outcome = args.doc.maybeResyncPush(base64ToBytes(frontier.snapshotVersionVector), frontier.tailBlobs);
+                        outcome = args.doc.maybeResyncPush(base64ToBytes(frontier.snapshotVersionVector), frontier.tailBlobs, deliveringOpBlobs());
                         // 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.
@@ -3030,46 +3796,30 @@ function wireDocTransport(args) {
                 gapPullRounds = 0;
                 return;
             }
-            pullJoin();
+            // The head can be this client's own op still being written over HTTP,
+            // so the judgement waits for that write as a catch-up prompt does.
+            resyncPastSeq(awaited);
         }, 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.
+    // The server ended this subscription: it refused the subscribe (access
+    // that ended between the HTTP join and the subscribe, which no eviction can
+    // reach because no subscription row exists yet), 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.
+    // That is the same fact a `doc_gone` reports, so the copy ends the same
+    // way: `moved`, which a session answers by re-opening the id, so the
+    // current gate re-admits a reader who still reaches the document and
+    // refuses one who does not. A second end inside the window is `deleted`,
+    // which ends the copy without the re-open.
     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);
-        }
+        markGone(endedReasonFor(topic));
     }
     // 1. Subscribe to the doc topic. Frame routing:
     //    - `doc_init`: bridge the join-vs-fanout race. Ops committed between
@@ -3090,12 +3840,21 @@ function wireDocTransport(args) {
     const unsub = args.wsClient.subscribe(topic, (frame) => {
         const init = parseDocInitFrame(frame);
         if (init) {
+            // A new version replaced the line while this copy was away (the
+            // `doc_gone` naming it went to a socket that was down). Its tail is
+            // the new version's, and nothing this copy holds or would re-assert
+            // applies to it, so it reopens before applying or resending anything.
+            if (importSeqMoved(args.doc, init.import_seq)) {
+                markGone('moved');
+                return;
+            }
             // 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 wasSubscribed = docInitReconnectCount !== null;
             const socketDropped = docInitReconnectCount !== null && reconnects > docInitReconnectCount;
             docInitReconnectCount = reconnects;
             // Resync check BEFORE applying. The tail covers (snapshot_seq,
@@ -3179,6 +3938,10 @@ function wireDocTransport(args) {
                 reportSyncHealth('reconnected_unsaved');
             }
             resendAllOutstanding();
+            // A nudge posted while the topic was down is gone, so every status
+            // this document holds asks what moved since its revision.
+            if (wasSubscribed)
+                args.doc._inputStatusNudged(null, null);
             // 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
@@ -3255,7 +4018,7 @@ function wireDocTransport(args) {
             // 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.doc.resolveOutstandingOp(frame.client_op_id, frame.seq);
             args.setCurrentSeq(frame.seq);
             args.advanceCoveredSeq(frame.seq);
             // An ack for a local op sits above any remote op this client never
@@ -3278,6 +4041,13 @@ function wireDocTransport(args) {
             // 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.
             forgetOp(frame.client_op_id);
+            // A new version replaced the line under this copy. Not healable and
+            // not this op's alone: every op it holds names the replaced version,
+            // so the copy reopens, which drops them all.
+            if (frame.reason === OP_REJECTED_MOVED) {
+                markGone('moved');
+                return;
+            }
             // 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.
@@ -3304,30 +4074,13 @@ function wireDocTransport(args) {
             // 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,
+                healable: !atCapacity && frame.reason !== OP_REJECTED_NOT_IMPORTED,
                 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 subscription record was evicted at fanout). Draining before the `_markGone`
-            // listeners keeps the lifecycle observably clean.
-            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;
-            }
-            args.doc._markGone(goneReasonOf(frame));
+            markGone(goneReasonOf(frame));
             return;
         }
         if (isDocStatusFrame(frame)) {
@@ -3340,6 +4093,12 @@ function wireDocTransport(args) {
             if (frame.reload && args.reloadAfterHydration) {
                 args.reloadAfterHydration(status);
             }
+            else if (status.pending &&
+                status.blocking !== false &&
+                args.doc._workStatusNow?.pending !== true &&
+                args.verifyPendingStatus) {
+                args.verifyPendingStatus(status);
+            }
             else {
                 args.doc._emitStatus(status);
             }
@@ -3350,6 +4109,13 @@ function wireDocTransport(args) {
             args.doc._setName(frame.name);
             return;
         }
+        const nudge = parseInputStatusNudge(frame);
+        if (nudge !== null) {
+            // The frame names the key and its new revision alone; the status
+            // fetches what moved.
+            args.doc._inputStatusNudged(nudge.key, nudge.rev);
+            return;
+        }
         if (isDocDriveStatusFrame(frame)) {
             // The signal de-dupes a no-op re-emit, so forwarding every frame is safe.
             args.doc._emitDriveStatus(toDriveStatus(frame.drive));
@@ -3393,21 +4159,6 @@ 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 = {
@@ -3415,6 +4166,7 @@ function wireDocTransport(args) {
             topic,
             op_blob: opBlobB64,
             client_op_id: clientOpId,
+            ...baseImportSeqField(args.doc),
         };
         // A frame past the transport's cap is not delivered and takes the
         // connection down with it, so it must never reach the socket OR the
@@ -3436,8 +4188,10 @@ function wireDocTransport(args) {
             dispatchedAt: 0,
             inFlight: 0,
             queued: false,
+            firstDispatchedAt: 0,
         });
         dispatchOp(clientOpId);
+        armNeverOpenedNotice();
         return clientOpId;
     });
     async function writeOversizedOp(opBlobB64, clientOpId) {
@@ -3461,11 +4215,11 @@ 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)) {
-            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE);
+            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE, { healable: false });
             return;
         }
         if (!args.postOversizedOp) {
-            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE);
+            failOpTerminally(clientOpId, TOO_LARGE_MESSAGE, { healable: false });
             return;
         }
         // An oversized op is deliberately kept out of `outstandingResends` (a
@@ -3505,6 +4259,11 @@ function wireDocTransport(args) {
             opStartedAt.delete(clientOpId);
             return;
         }
+        if (!result.ok && result.moved === true) {
+            opStartedAt.delete(clientOpId);
+            markGone('moved');
+            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
@@ -3515,7 +4274,9 @@ function wireDocTransport(args) {
             if (result.readOnly)
                 args.doc._markReadOnly(result.readOnly);
             failOpTerminally(clientOpId, result.retryable ? UNAVAILABLE_GIVE_UP_MESSAGE : result.message, {
-                healable: result.atCapacity !== true,
+                healable: result.atCapacity !== true &&
+                    result.notImported !== true &&
+                    result.tooLarge !== true,
                 report: result.atCapacity !== true || firstCapacityRefusal,
             });
             return;
@@ -3523,7 +4284,7 @@ function wireDocTransport(args) {
         // 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.doc.resolveOutstandingOp(clientOpId, result.seq);
         args.setCurrentSeq(result.seq);
         args.advanceCoveredSeq(result.seq);
     }
@@ -3575,6 +4336,10 @@ function wireDocTransport(args) {
             clearInterval(reverifyTimer);
             reverifyTimer = null;
         }
+        if (neverOpenedTimer !== null) {
+            clearTimeout(neverOpenedTimer);
+            neverOpenedTimer = null;
+        }
         clearDivergenceHeal();
         if (gapTimer !== null) {
             clearTimeout(gapTimer);
@@ -3611,7 +4376,7 @@ function wireDocTransport(args) {
         // 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._workStatusNow?.pending !== true &&
             args.doc._goneReason === null;
         const cacheKey = parkable
             ? parkCacheKey(args.docId, args.requestedBranchId, args.requestedStream)
@@ -3682,10 +4447,186 @@ async function fetchPresignedSnapshot(url, onProgress) {
 // legible upgrade prompt (rendered verbatim through `session.error`), never an
 // empty document: treating an unreadable snapshot as "no snapshot" would let
 // the user edit and overwrite content that is actually there.
-function snapshotKindTooNewError() {
-    return new BrassError('This document needs a newer version of this app. Update to the latest @brass-build/client to open it.', { status: 426 });
+/** Whether the server names a head above the seq its snapshot was sealed at,
+ *  which is state the payload has not delivered. Read beside `tail_ops`, so a
+ *  response that dropped its tail entries for budget is still seen as having
+ *  one rather than as a document that stops at its base. A server that sends
+ *  neither seq answers by its entries alone, which is all it ever had. */
+function coversMoreThanSnapshot(body) {
+    const { current_seq: current, snapshot_seq: sealed } = body;
+    return current !== undefined && sealed !== undefined && current > sealed;
+}
+/** The open with its top-level `readOnly` folded into `documentOptions`,
+ *  which is where every path below reads the intent from. The top-level
+ *  value wins over `documentOptions.readOnly` when both are set. */
+function withReadIntent(options) {
+    if (options?.readOnly === undefined)
+        return options;
+    const { readOnly, ...rest } = options;
+    const { readOnly: _alias, ...documentOptions } = rest.documentOptions ?? {};
+    return {
+        ...rest,
+        documentOptions: readOnly ? { ...documentOptions, readOnly: true } : documentOptions,
+    };
+}
+/** Whether this open will never write: the caller asked for a snapshot, or
+ *  for a read-only Document. The grant is not consulted, because a caller who
+ *  may edit and says nothing is one that may edit. */
+function opensReadOnly(options) {
+    return options?.frozen === true || options?.documentOptions?.readOnly === true;
+}
+/** The options every re-join of `branch` sends, a member's and a guest's
+ *  alike: the line it names, and the read intent of the open it serves, so a
+ *  document opened read-only is re-joined read-only and one opened to write
+ *  is re-joined to write. */
+function rejoinOptions(branch, open) {
+    const base = branch !== undefined ? { branch } : {};
+    return opensReadOnly(open) ? { ...base, documentOptions: { readOnly: true } } : base;
+}
+/**
+ * Apply a re-join to an open document: the reload, a line's resync and a
+ * guest's pull all end here.
+ *
+ * CRDT content over a CRDT document merges in place. Over frozen content it is
+ * a storage upgrade (`Document._upgradeStorage`), and frozen content sealed at
+ * another seq replaces the frozen content; both keep the app's handles and
+ * their subscribers. Frozen content served to a CRDT document, or content the
+ * document cannot take in place, reloads it.
+ */
+// The seal of frozen content that holds nothing yet: no join's seq matches it.
+const NO_SEAL = -1;
+// The `import_seq` each CRDT copy was opened at. A new version's import
+// replaces a line's content with a CRDT authored by the same pinned peer as
+// the one it replaces, so merging the new content into an old copy dedupes it
+// away and leaves the old copy's ops pointing at containers the line no
+// longer has. A copy that sees the line under a different import reopens
+// instead, and names its base on every op so the server refuses one that
+// raced the import (`moved`).
+const openedImportSeq = new WeakMap();
+function recordImportSeq(doc, importSeq) {
+    if (typeof importSeq === 'number')
+        openedImportSeq.set(doc, importSeq);
+}
+function importSeqMoved(doc, importSeq) {
+    const base = openedImportSeq.get(doc);
+    return base !== undefined && typeof importSeq === 'number' && importSeq !== base;
+}
+function baseImportSeqField(doc) {
+    const base = openedImportSeq.get(doc);
+    return base === undefined ? {} : { base_import_seq: base };
+}
+async function applyJoin(doc, body, fetchBody) {
+    // Decided off the wire's own statement of the encoding, so content the
+    // document will not keep is never downloaded.
+    const encoding = joinEncoding(body.snapshot);
+    // Frozen content replaces a reader's CRDT rather than merging into it, so a
+    // new version's import is taken in place below.
+    const replacesCrdt = encoding === 'frozen' && !doc._holdsRecordSet();
+    if (!replacesCrdt && importSeqMoved(doc, body.import_seq)) {
+        doc._reopen();
+        return { kind: 'reloaded' };
+    }
+    if (doc._holdsRecordSet()) {
+        const tail = [...body.tail_ops].sort((a, b) => a.seq - b.seq);
+        const tailSeqs = tail.map((entry) => entry.seq);
+        if (encoding === 'frozen') {
+            const held = doc._frozenSealSeq;
+            const sameSeal = held === null || body.snapshot_seq === undefined || held === body.snapshot_seq;
+            if (tail.length === 0 && sameSeal)
+                return { kind: 'unchanged' };
+            if (tail.length === 0 && !coversMoreThanSnapshot(body)) {
+                const content = await decodeJoinContent(body.snapshot, fetchBody);
+                if (content.kind === 'frozen' &&
+                    doc._replaceSealedContent(content.content, body.snapshot_seq ?? null)) {
+                    return { kind: 'applied', content, tailSeqs };
+                }
+            }
+            doc._reopen();
+            return { kind: 'reloaded' };
+        }
+        const content = await decodeJoinContent(body.snapshot, fetchBody);
+        await ensureWasmReady();
+        const upgraded = doc._upgradeStorage(content.kind === 'crdt' ? content.bytes : null, tail.map((entry) => base64ToBytes(entry.op_blob_b64)));
+        if (!upgraded) {
+            doc._reopen();
+            return { kind: 'reloaded' };
+        }
+        return { kind: 'applied', content, tailSeqs };
+    }
+    // A line a reader holds as a CRDT and the server now stores frozen (a new
+    // version of its file was imported over it) is taken as stored, in place.
+    // An editable open asks as a writer and is never served frozen content.
+    if (encoding === 'frozen') {
+        if (doc._openMode !== 'edit' &&
+            body.tail_ops.length === 0 &&
+            !coversMoreThanSnapshot(body)) {
+            const content = await decodeJoinContent(body.snapshot, fetchBody);
+            if (content.kind === 'frozen' &&
+                doc._downgradeStorage(content.content, body.snapshot_seq ?? null)) {
+                openedImportSeq.delete(doc);
+                return { kind: 'applied', content, tailSeqs: [] };
+            }
+        }
+        doc._reopen();
+        return { kind: 'reloaded' };
+    }
+    const content = await decodeJoinContent(body.snapshot, fetchBody);
+    if (content.kind === 'crdt')
+        doc._applySnapshot(content.bytes);
+    const tail = [...body.tail_ops].sort((a, b) => a.seq - b.seq);
+    for (const entry of tail)
+        doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
+    return { kind: 'applied', content, tailSeqs: tail.map((entry) => entry.seq) };
 }
-async function materialise(body, documentOptions, onSnapshotProgress) {
+async function materialise(body, documentOptions, onSnapshotProgress, 
+// A frozen copy of a document whose import has not landed yet starts as
+// empty frozen content sealed at nothing, so the reload that follows the
+// import asks for the content as stored and swaps it in place, where an
+// empty CRDT would ask the server to convert the line for it.
+{ emptyAsFrozen = false } = {}) {
+    const endFetch = perfStart('open: snapshot fetch + decode');
+    const content = await decodeJoinContent(body.snapshot, (url) => fetchPresignedSnapshot(url, onSnapshotProgress));
+    endFetch({ kind: content.kind });
+    if (content.kind === 'none' && emptyAsFrozen && body.tail_ops.length === 0) {
+        return Document.openFromSealedContent(SealedContent.fromJSON({}), {
+            ...documentOptions,
+            readOnly: true,
+            readOnlyReason: documentOptions?.readOnlyReason ?? 'snapshot',
+            docId: body.doc_id,
+            branchId: body.branch_id,
+            frozenSeal: NO_SEAL,
+        });
+    }
+    // Frozen content is read with no CRDT engine: no engine is built and the
+    // WASM is not waited on.
+    //
+    // It is served to a reader and never to a writer. Converting it to a CRDT
+    // is the SERVER's, because the conversion's output depends on the paging
+    // constants, the mutation batching budget and loro's encoding, and two
+    // clients on different builds would produce documents that merge into each
+    // other with no error and no agreement. The tail is empty for the same
+    // reason: the conversion is what makes a branch writable, so the ops it
+    // takes are authored after it and against the converted document.
+    if (content.kind === 'frozen') {
+        // Frozen content with state above it is a document the server should not
+        // have been able to build, and the content alone is the document as it
+        // stood before those ops. Refused rather than read, because nothing here
+        // would say so.
+        if (body.tail_ops.length > 0 || coversMoreThanSnapshot(body)) {
+            throw new BrassError('This could not be opened: its stored records do not ' +
+                'account for every change made to it. Reopen it in a moment.', { status: 500 });
+        }
+        return Document.openFromSealedContent(content.content, {
+            ...documentOptions,
+            // A property of the content, which holds no op log for an edit to be
+            // written into.
+            readOnly: true,
+            readOnlyReason: documentOptions?.readOnlyReason ?? 'snapshot',
+            docId: body.doc_id,
+            branchId: body.branch_id,
+            ...(body.snapshot_seq !== undefined ? { frozenSeal: body.snapshot_seq } : {}),
+        });
+    }
     // Constructing the document is the first thing in this package that runs the
     // WASM, and `Brass.init` only starts the fetch, so this is where it is
     // waited on. Usually it resolved during the auth round-trip and this costs
@@ -3700,28 +4641,13 @@ async function materialise(body, documentOptions, onSnapshotProgress) {
         branchId: body.branch_id,
     };
     let doc;
-    const snap = body.snapshot;
-    if (snap === null) {
+    if (content.kind === 'none') {
         doc = Document.create(optionsWithId);
     }
-    else if (snap.kind === 'inline') {
-        const endDecode = perfStart('open: base64 decode (inline snapshot)');
-        const bytes = base64ToBytes(snap.data_b64);
-        endDecode({ base64Chars: snap.data_b64.length, snapshotBytes: bytes.byteLength });
-        const endImport = perfStart('open: loro import (inline snapshot)');
-        doc = Document.openFromSnapshot(bytes, optionsWithId);
-        endImport({ snapshotBytes: bytes.byteLength });
-    }
-    else if (snap.kind === 'presigned') {
-        const endPresigned = perfStart('open: presigned snapshot fetch');
-        const bytes = await fetchPresignedSnapshot(snap.url, onSnapshotProgress);
-        endPresigned({ snapshotBytes: bytes.byteLength });
-        const endImport = perfStart('open: loro import (presigned snapshot)');
-        doc = Document.openFromSnapshot(bytes, optionsWithId);
-        endImport({ snapshotBytes: bytes.byteLength });
-    }
     else {
-        throw snapshotKindTooNewError();
+        const endImport = perfStart('open: loro import');
+        doc = Document.openFromSnapshot(content.bytes, optionsWithId);
+        endImport({ snapshotBytes: content.bytes.byteLength });
     }
     // Apply tail ops in seq order. The server delivers them sorted; we sort
     // defensively (Loro dedupes by lamport, so out-of-order is safe) rather
@@ -3732,8 +4658,93 @@ async function materialise(body, documentOptions, onSnapshotProgress) {
         doc.applyRemoteOp(base64ToBytes(entry.op_blob_b64));
     }
     endTail({ count: tail.length });
+    recordImportSeq(doc, body.import_seq);
     // `doc.id` is non-null at runtime (stamped above); the cast closes the type
     // gap without weakening the class's `string | null` signature.
     return doc;
 }
+/** How many frozen opens run at once. */
+export const FROZEN_OPEN_LANES = 8;
+/** Runs at most `lanes` of the tasks handed to it at once, in the order given. */
+export function createPacer(lanes) {
+    let running = 0;
+    const waiting = [];
+    return (task) => new Promise((resolve, reject) => {
+        const start = () => {
+            running += 1;
+            task()
+                .then(resolve, reject)
+                .finally(() => {
+                running -= 1;
+                waiting.shift()?.();
+            });
+        };
+        if (running < lanes)
+            start();
+        else
+            waiting.push(start);
+    });
+}
+function frozenOptions(options) {
+    // Reading as data: a schema this app did not declare is read rather than
+    // refused, since nothing written through this copy can misread it.
+    return {
+        ...options,
+        acceptSchemaConflict: true,
+        documentOptions: { ...options.documentOptions, readOnly: true },
+    };
+}
+// A stream line opened for a frozen copy: the same reading as the copy
+// itself, of the line its manifest names.
+function frozenLineOptions(lineId) {
+    return {
+        branch: lineId,
+        frozen: true,
+        acceptSchemaConflict: true,
+        documentOptions: { readOnly: true },
+    };
+}
+function importReportOf(parsed) {
+    const report = parsed.import_report;
+    return report !== null && typeof report === 'object' && Array.isArray(report.findings)
+        ? report
+        : null;
+}
+/**
+ * Whether a frame on a document's topic says the document moved past the
+ * point a frozen copy was taken at: a later op, work that locked the
+ * document finishing (an import landing or failing), or the document going.
+ */
+export function frameMovesDocument(frame, takenAt) {
+    if (frame === null || typeof frame !== 'object')
+        return false;
+    const f = frame;
+    switch (f.type) {
+        // The server fans a `doc_op` out to every subscriber but the writer's
+        // connection, so an edit made through another copy on this page's socket
+        // reaches the topic only as that copy's `op_ack`.
+        case 'doc_op':
+        case 'op_ack':
+            return typeof f.seq === 'number' && f.seq > takenAt;
+        case 'doc_init':
+        case 'doc_catch_up':
+            return typeof f.current_seq === 'number' && f.current_seq > takenAt;
+        case 'doc_status':
+            // `reload` is work that replaced the content (an import landing); a
+            // terminal status still blocking is work that failed.
+            return (f.reload === true ||
+                (f.status?.pending === false && f.status.blocking !== false));
+        case 'doc_gone':
+            return true;
+        default:
+            return false;
+    }
+}
+// The document's name as the join that opened it read it, so a copy opened by
+// id carries it from its first frame as a session open does.
+function setJoinedName(doc, parsed) {
+    const name = parsed.name;
+    if (typeof name === 'string')
+        doc._setName(name);
+}
 //# sourceMappingURL=open-document.js.map