@loro-dev/streams-crdt 0.15.0 → 0.16.0

package/dist/{stream-id-CggbAC6b.js → stream-id-DwQujw_H.js}

@@ -261,27 +261,29 @@ var PayloadProtectionRuntime = class {
 		}
 		return out;
 	}
-	async encodeSnapshot(snapshot) {
+	async encodeSnapshot(snapshot, continuationOffset) {
+		checkContinuationOffset(continuationOffset);
 		if (this.writePolicy === "plaintext") return snapshot;
-		return await this.sealPayload("snapshot", snapshot);
+		return await this.sealPayload("snapshot", snapshot, continuationOffset);
 	}
-	async decodeSnapshot(snapshot) {
-		if (isEncryptedEnvelope(snapshot)) return await this.openPayload("snapshot", snapshot);
+	async decodeSnapshot(snapshot, continuationOffset) {
+		checkContinuationOffset(continuationOffset);
+		if (isEncryptedEnvelope(snapshot)) return await this.openPayload("snapshot", snapshot, continuationOffset);
 		this.assertPlaintextAllowed("snapshot");
 		return snapshot;
 	}
-	async sealPayload(kind, plaintext) {
-		return await this.sealProviderPayload(kind, plaintext);
+	async sealPayload(kind, plaintext, continuationOffset) {
+		return await this.sealProviderPayload(kind, plaintext, continuationOffset);
 	}
-	async openPayload(expectedKind, envelope) {
+	async openPayload(expectedKind, envelope, continuationOffset) {
 		const version = envelope[4];
-		if (version === PROVIDER_ENVELOPE_VERSION) return await this.openProviderPayload(expectedKind, envelope);
+		if (version === PROVIDER_ENVELOPE_VERSION) return await this.openProviderPayload(expectedKind, envelope, continuationOffset);
 		throw new PayloadProtectionError("invalid_envelope", `unsupported streams-crdt protected payload envelope version '${String(version)}'`);
 	}
-	async sealProviderPayload(kind, plaintext) {
+	async sealProviderPayload(kind, plaintext, continuationOffset) {
 		const provider = this.provider;
 		if (provider == null) throw new PayloadProtectionError("encrypt_failed", "provider-backed E2EE writes require a provider");
-		const context = createProviderContext(kind);
+		const context = createProviderContext(kind, continuationOffset);
 		let authenticatedHeader;
 		let additionalDataCalls = 0;
 		let result;
@@ -314,12 +316,12 @@ var PayloadProtectionRuntime = class {
 			throw new PayloadProtectionError(reason, payloadProtectionFailureMessage(reason));
 		}
 	}
-	async openProviderPayload(expectedKind, envelope) {
+	async openProviderPayload(expectedKind, envelope, continuationOffset) {
 		const parsed = parseProviderEnvelope(envelope);
 		if (parsed.kind !== expectedKind) throw new PayloadProtectionError("wrong_payload_kind", `expected ${expectedKind} payload, got ${parsed.kind}`);
 		const provider = this.provider;
 		if (provider == null) throw new PayloadProtectionError("missing_read_key", "provider-backed E2EE reads require a provider");
-		const context = createProviderContext(parsed.kind);
+		const context = createProviderContext(parsed.kind, continuationOffset);
 		try {
 			const plaintext = await provider.open({
 				sealed: parsed.sealed,
@@ -370,13 +372,26 @@ function payloadProtectionFailureMessage(reason) {
 function isEncryptedEnvelope(payload) {
 	return payload.byteLength >= MAGIC.byteLength && MAGIC.every((byte, index) => payload[index] === byte);
 }
-function createProviderContext(kind) {
+function createProviderContext(kind, continuationOffset) {
+	if (kind === "snapshot") {
+		checkContinuationOffset(continuationOffset);
+		return {
+			protocol: PAYLOAD_PROTECTION_PROTOCOL,
+			version: PROVIDER_ENVELOPE_VERSION,
+			kind,
+			continuationOffset
+		};
+	}
 	return {
 		protocol: PAYLOAD_PROTECTION_PROTOCOL,
 		version: PROVIDER_ENVELOPE_VERSION,
 		kind
 	};
 }
+/** Opaque offset token only. Not a timestamp, Org, bucket, or role. */
+function checkContinuationOffset(value) {
+	if (typeof value !== "string" || value.length === 0 || value.length > 1024 || value === "now") throw new PayloadProtectionError("invalid_envelope", "invalid continuation offset");
+}
 function createProviderEnvelopeHeader(kind, providerHeader) {
 	const normalizedHeader = normalizeProviderHeader(providerHeader);
 	const header = new Uint8Array(PROVIDER_PREFIX_BYTES + normalizedHeader.byteLength);
@@ -1083,11 +1098,13 @@ var StreamsTransportClient = class {
 	async bootstrap(signal, timeoutMode = "default") {
 		const result = await (timeoutMode === "initial" ? this.initialSyncClient : this.client).bootstrap({ signal });
 		if (!result.ok) throw this.toTransportFailure(result.result);
-		const snapshot = result.result.snapshotOffset === "-1" ? new Uint8Array() : result.result.snapshot?.body ?? new Uint8Array();
+		const snapshotOffset = result.result.snapshotOffset;
+		const snapshot = snapshotOffset === "-1" ? new Uint8Array() : result.result.snapshot?.body ?? new Uint8Array();
 		return {
 			nextOffset: result.result.nextOffset,
 			upToDate: result.result.upToDate,
 			snapshot,
+			snapshotOffset,
 			updates: result.result.updates.flatMap((part) => decodeMultipartPartItems(part.body)),
 			streamCursor: result.result.cursor
 		};
@@ -1265,14 +1282,14 @@ var StreamsTransportClient = class {
 	}
 	async fetchAuthorized(input, init, timeoutMs, phase) {
 		const requestUrl = this.routeRequestUrl(input, init);
-		const firstToken = await this.resolveToken({ reason: "request" });
+		const firstToken = this.authProvider == null ? void 0 : await withTokenTimeout(this.resolveToken({ reason: "request" }), timeoutMs, phase);
 		const firstResponse = await this.fetchWithTimeout(requestUrl, {
 			...init,
 			headers: this.attachAuthorization(init.headers, firstToken)
 		}, timeoutMs, phase);
 		if (this.authProvider == null || firstResponse.status !== 401 && firstResponse.status !== 403) return firstResponse;
 		await firstResponse.body?.cancel().catch(() => {});
-		const refreshedToken = await this.refreshTokenAfterFailure(firstResponse.status, firstToken);
+		const refreshedToken = await this.refreshTokenAfterFailure(firstResponse.status, firstToken, timeoutMs, phase);
 		return this.fetchWithTimeout(requestUrl, {
 			...init,
 			headers: this.attachAuthorization(init.headers, refreshedToken)
@@ -1299,16 +1316,25 @@ var StreamsTransportClient = class {
 	async resolveToken(context) {
 		return await this.authProvider?.(context);
 	}
-	async refreshTokenAfterFailure(status, previousToken) {
+	async refreshTokenAfterFailure(status, previousToken, timeoutMs, phase) {
 		if (this.authProvider == null) return;
-		if (this.authRefreshInFlight == null) this.authRefreshInFlight = this.resolveToken({
-			reason: "unauthorized",
-			status,
-			previousToken
-		}).finally(() => {
-			this.authRefreshInFlight = void 0;
-		});
-		return await this.authRefreshInFlight;
+		if (this.authRefreshInFlight == null) {
+			const inFlight = this.resolveToken({
+				reason: "unauthorized",
+				status,
+				previousToken
+			}).finally(() => {
+				if (this.authRefreshInFlight === inFlight) this.authRefreshInFlight = void 0;
+			});
+			this.authRefreshInFlight = inFlight;
+		}
+		const inFlight = this.authRefreshInFlight;
+		try {
+			return await withTokenTimeout(inFlight, timeoutMs, phase);
+		} catch (error) {
+			if (error instanceof TimeoutError && this.authRefreshInFlight === inFlight) this.authRefreshInFlight = void 0;
+			throw error;
+		}
 	}
 	attachAuthorization(base, token) {
 		const headers = new Headers(base);
@@ -1502,8 +1528,26 @@ function parseRetryAfterMs(value) {
 	const delta = parsed - Date.now();
 	return delta > 0 ? delta : void 0;
 }
+async function withTokenTimeout(promise, timeoutMs, phase) {
+	if (!(timeoutMs > 0)) return await promise;
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				reject(new TimeoutError(phase, timeoutMs));
+			}, timeoutMs);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 //#endregion
 //#region src/ephemeral-runtime.ts
+/**
+* Superseded entries are skipped lazily; once they outnumber live entries
+* (and exceed this floor) the queue is rebuilt so it stays O(live entries).
+*/
+const PENDING_LOCAL_REBUILD_MIN_SUPERSEDED = 64;
 function createNoopAdapter() {
 	return {
 		emptyVersion: () => ({}),
@@ -1624,6 +1668,11 @@ var EphemeralStreamCrdt = class {
 			writeStatus: "connecting",
 			statusListeners: /* @__PURE__ */ new Set(),
 			pendingLocal: new Deque(),
+			pendingLocalByKey: /* @__PURE__ */ new Map(),
+			pendingLocalSuperseded: 0,
+			pendingLocalCount: 0,
+			lastChainId: 0,
+			liveChains: 0,
 			syncWaiters: [],
 			flushingLocal: false,
 			retryAttempt: 0,
@@ -1674,15 +1723,17 @@ var EphemeralStreamCrdt = class {
 				return state.status;
 			},
 			get pendingLocalCount() {
-				return state.pendingLocal.length;
+				return state.pendingLocalCount;
 			},
 			onStatusChange: (listener) => this.onStatusChange(state, listener),
 			waitUntilSynced: async () => {
 				if (state.closed) throw closedSubscriptionError();
-				const remaining = state.pendingLocal.length;
+				const remaining = state.liveChains;
+				const lastChainId = state.lastChainId;
 				if (remaining === 0) return;
 				return new Promise((resolve, reject) => {
 					state.syncWaiters.push({
+						lastChainId,
 						remaining,
 						resolve,
 						reject
@@ -1812,7 +1863,33 @@ var EphemeralStreamCrdt = class {
 	}
 	enqueueLocal(state, update) {
 		if (state.closed || update == null || update.byteLength === 0) return;
-		state.pendingLocal.pushBack(update);
+		const key = this.localUpdateKey(update);
+		const previous = key == null ? void 0 : state.pendingLocalByKey.get(key);
+		let chainId;
+		if (previous == null) {
+			state.lastChainId += 1;
+			state.liveChains += 1;
+			chainId = state.lastChainId;
+		} else chainId = previous.chainId;
+		const entry = {
+			update,
+			key,
+			count: 1,
+			chainId,
+			superseded: false,
+			inFlight: false
+		};
+		if (previous != null) {
+			previous.superseded = true;
+			previous.update = null;
+			entry.count += previous.count;
+			previous.count = 0;
+			state.pendingLocalSuperseded += 1;
+		}
+		if (key != null) state.pendingLocalByKey.set(key, entry);
+		state.pendingLocal.pushBack(entry);
+		state.pendingLocalCount += 1;
+		this.maybeRebuildPendingLocal(state);
 		if (state.writeStatus !== "connecting") this.flushPendingLocal(state);
 	}
 	async flushPendingLocal(state) {
@@ -1820,42 +1897,94 @@ var EphemeralStreamCrdt = class {
 		state.flushingLocal = true;
 		try {
 			while (!state.closed) {
-				const update = state.pendingLocal.peekFront();
-				if (update == null) return;
 				let attempt = 0;
-				while (!state.closed) try {
-					await this.client.appendEphemeralUpdate(update);
-					state.pendingLocal.popFront();
-					this.notifySyncWaiters(state, 1);
-					this.setWriteStatus(state, "ok");
-					break;
-				} catch (error) {
-					const classified = classifyFetchError(error);
-					if (!classified.retriable || isAuthOrProtocolError(error)) {
-						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error(`ephemeral append failed: ${classified.code}`));
-						this.setWriteStatus(state, "error");
-						return;
-					}
-					if (attempt >= this.reconnectConfig.maxAttempts) {
-						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error("ephemeral append retry budget exhausted"));
-						this.setWriteStatus(state, "error");
-						return;
+				while (!state.closed) {
+					const entry = this.nextPendingLocal(state);
+					if (entry == null) return;
+					try {
+						await this.client.appendEphemeralUpdate(entry.update);
+						state.pendingLocal.popFront();
+						state.pendingLocalCount -= entry.count;
+						state.liveChains -= 1;
+						this.notifyChainAcknowledged(state, entry.chainId);
+						this.setWriteStatus(state, "ok");
+						break;
+					} catch (error) {
+						const classified = classifyFetchError(error);
+						if (!classified.retriable || isAuthOrProtocolError(error)) {
+							this.rejectSyncWaiters(state, /* @__PURE__ */ new Error(`ephemeral append failed: ${classified.code}`));
+							this.setWriteStatus(state, "error");
+							return;
+						}
+						if (attempt >= this.reconnectConfig.maxAttempts) {
+							this.rejectSyncWaiters(state, /* @__PURE__ */ new Error("ephemeral append retry budget exhausted"));
+							this.setWriteStatus(state, "error");
+							return;
+						}
+						this.setWriteStatus(state, "reconnecting");
+						const delay = computeRetryDelay(attempt, this.reconnectConfig);
+						attempt += 1;
+						await sleep(delay, state.retrySleepController.signal);
 					}
-					this.setWriteStatus(state, "reconnecting");
-					const delay = computeRetryDelay(attempt, this.reconnectConfig);
-					attempt += 1;
-					await sleep(delay, state.retrySleepController.signal);
 				}
 			}
 		} finally {
 			state.flushingLocal = false;
 		}
 	}
-	notifySyncWaiters(state, flushedCount) {
+	localUpdateKey(update) {
+		const adaptor = this.adaptor;
+		if (adaptor.localUpdateKey == null) return;
+		try {
+			return adaptor.localUpdateKey(update) ?? void 0;
+		} catch (error) {
+			this.logError("ephemeral local update key lookup failed", error);
+			return;
+		}
+	}
+	/**
+	* Pops superseded entries off the head and returns the next entry to send,
+	* marking it in-flight so later same-key updates queue behind it.
+	*/
+	nextPendingLocal(state) {
+		for (;;) {
+			const head = state.pendingLocal.peekFront();
+			if (head == null) return;
+			if (head.superseded) {
+				state.pendingLocal.popFront();
+				state.pendingLocalSuperseded -= 1;
+				continue;
+			}
+			if (!head.inFlight) {
+				head.inFlight = true;
+				if (head.key != null && state.pendingLocalByKey.get(head.key) === head) state.pendingLocalByKey.delete(head.key);
+			}
+			return head;
+		}
+	}
+	/** Drops superseded markers once they dominate the queue (amortized O(1)). */
+	maybeRebuildPendingLocal(state) {
+		if (state.pendingLocalSuperseded < PENDING_LOCAL_REBUILD_MIN_SUPERSEDED || state.pendingLocalSuperseded * 2 <= state.pendingLocal.length) return;
+		const live = state.pendingLocal.toArray().filter((entry) => !entry.superseded);
+		state.pendingLocal.clear();
+		for (const entry of live) state.pendingLocal.pushBack(entry);
+		state.pendingLocalSuperseded = 0;
+	}
+	/**
+	* Completes waiters that tracked `chainId`. Each chain is acknowledged
+	* exactly once (its entry is never superseded after it goes in flight), so
+	* a waiter resolves only after every chain live at call time has had its
+	* latest value acknowledged.
+	*/
+	notifyChainAcknowledged(state, chainId) {
 		let i = 0;
 		while (i < state.syncWaiters.length) {
 			const waiter = state.syncWaiters[i];
-			waiter.remaining -= flushedCount;
+			if (chainId > waiter.lastChainId) {
+				i += 1;
+				continue;
+			}
+			waiter.remaining -= 1;
 			if (waiter.remaining <= 0) {
 				state.syncWaiters.splice(i, 1);
 				waiter.resolve();
@@ -2066,11 +2195,32 @@ function createInitialRemoteCursor(input) {
 }
 //#endregion
 //#region src/transport-cursor.ts
+const MAX_SPANS_IN_MESSAGE = 8;
+/**
+* Renders a bounded summary of unresolved spans for the error message, so a
+* caller's error log names the author(s) whose ops are missing from the
+* stream without the caller having to unwrap `error.unresolved` itself.
+*/
+function formatUnresolvedSpans(unresolved) {
+	if (unresolved.length === 0) return "";
+	const shown = unresolved.slice(0, MAX_SPANS_IN_MESSAGE).map((span) => `${span.peer}@[${span.start}..${span.end})`).join(", ");
+	const suffix = unresolved.length > MAX_SPANS_IN_MESSAGE ? `, +${unresolved.length - MAX_SPANS_IN_MESSAGE} more` : "";
+	return ` (missing deps for ${unresolved.length} span(s): ${shown}${suffix})`;
+}
 var CrdtApplyIncompleteError = class extends Error {
 	unresolved;
-	constructor(unresolved) {
-		super("CRDT apply incomplete: unresolved remote updates remain");
+	/**
+	* The volatile server version at the moment apply failed: everything the
+	* server delivered that the local doc actually applied (success spans
+	* only — pending spans never advance it). `exportUpdates(appliedVersion)`
+	* is therefore exactly "the ops this replica holds that the server does
+	* not", which is what the join-time salvage append publishes.
+	*/
+	appliedVersion;
+	constructor(unresolved, appliedVersion) {
+		super(`CRDT apply incomplete: unresolved remote updates remain${formatUnresolvedSpans(unresolved)}`);
 		this.unresolved = unresolved;
+		this.appliedVersion = appliedVersion;
 	}
 };
 function isApplyOutcome(value) {
@@ -2098,12 +2248,29 @@ var TransportCursorManager = class {
 	isCursorComplete(cursor) {
 		return !this.incompleteCursors.has(cursor);
 	}
-	async applyBootstrapPayload(cursor, snapshot, updates, nextOffset, upToDate = false) {
+	/**
+	* Marks `cursor` incomplete without an apply.
+	*
+	* The `CrdtApplyIncompleteError` throw path discards its candidate cursor
+	* BEFORE the usual WeakMap marking, so a caller's retained cursor keeps
+	* whatever completeness it had. For a caught-up live room the first
+	* poisoned event typically arrives with `up_to_date=true`, so the retained
+	* cursor still reads "complete" for the whole wedge — leaving the degraded
+	* local flush unengaged and the snapshot-upload clean gate open, exactly
+	* the two consumers keyed on this marking. The read loop calls this when
+	* it catches the error so the room's incomplete state is visible on the
+	* cursor it actually holds.
+	*/
+	markCursorIncomplete(cursor, unresolved) {
+		this.incompleteCursors.set(cursor, unresolved);
+	}
+	async applyBootstrapPayload(cursor, snapshot, updates, nextOffset, upToDate = false, snapshotOffset = "-1") {
 		let nextVersion = cursor.serverLowerBoundVersion;
 		let complete = true;
 		let unresolved = [];
 		if (snapshot.byteLength > 0) {
-			const outcome = normalizeApplyReturn(await this.adapter.applySnapshot(this.decodeSnapshot == null ? snapshot : await this.decodeSnapshot(snapshot)));
+			if (typeof snapshotOffset !== "string" || snapshotOffset.length === 0 || snapshotOffset.length > 1024 || snapshotOffset === "now" || snapshotOffset === "-1") throw new Error("bootstrap snapshot offset does not match an admitted continuation");
+			const outcome = normalizeApplyReturn(await this.adapter.applySnapshot(this.decodeSnapshot == null ? snapshot : await this.decodeSnapshot(snapshot, snapshotOffset)));
 			nextVersion = outcome.version;
 			complete = outcome.complete;
 			unresolved = outcome.unresolved ?? [];
@@ -2121,9 +2288,9 @@ var TransportCursorManager = class {
 			serverLowerBoundVersion: nextVersion
 		}, "bootstrap", complete, unresolved, upToDate);
 	}
-	async applyBootstrapItems(cursor, items, nextOffset, upToDate = false) {
+	async applyBootstrapItems(cursor, items, nextOffset, upToDate = false, snapshotOffset = "-1") {
 		const snapshot = items[0] ?? new Uint8Array();
-		return await this.applyBootstrapPayload(cursor, snapshot, items.slice(1), nextOffset, upToDate);
+		return await this.applyBootstrapPayload(cursor, snapshot, items.slice(1), nextOffset, upToDate, snapshotOffset);
 	}
 	async applyRemoteItems(cursor, items, nextOffset) {
 		return await this.applyRemotePayload(cursor, [...items], nextOffset, "remote", void 0);
@@ -2171,7 +2338,7 @@ var TransportCursorManager = class {
 	}
 	async finalizeCursor(cursor, source, complete, unresolved, upToDate) {
 		if (!complete) {
-			if (upToDate) throw new CrdtApplyIncompleteError(unresolved);
+			if (upToDate) throw new CrdtApplyIncompleteError(unresolved, cursor.serverLowerBoundVersion);
 			this.incompleteCursors.set(cursor, unresolved);
 			return cursor;
 		}
@@ -2287,7 +2454,7 @@ var TransportSnapshotManager = class {
 			if (tailBytes <= snapshotBytes) return;
 			if (tailBytes - snapshotBytes < config.minBytesSinceRemoteSnapshot) return;
 			const snapshot = this.adapter.exportSnapshot();
-			await this.putSnapshotAt(state.cursor.nextOffset, this.encodeSnapshot == null ? snapshot : await this.encodeSnapshot(snapshot));
+			await this.putSnapshotAt(state.cursor.nextOffset, this.encodeSnapshot == null ? snapshot : await this.encodeSnapshot(snapshot, state.cursor.nextOffset));
 		} catch (error) {
 			this.logError("snapshot upload failed", error);
 		}
@@ -2326,6 +2493,7 @@ function createJoinState(cursor, liveMode = "sse") {
 		pendingLocal: new Deque(),
 		flushingLocal: false,
 		retryAttempt: 0,
+		incompleteRecoveryAttempt: 0,
 		retrySleepController: new AbortController(),
 		readLoopRunning: false,
 		readErrorRetryAttempt: 0,
@@ -2468,16 +2636,16 @@ var StreamsCrdt = class StreamsCrdt {
 	}
 	composeSnapshotDecoder(payloadProtection, decompressSnapshot) {
 		if (payloadProtection == null && decompressSnapshot == null) return;
-		return async (snapshot) => {
-			const clearSnapshot = payloadProtection == null ? snapshot : await payloadProtection.decodeSnapshot(snapshot);
+		return async (snapshot, continuationOffset) => {
+			const clearSnapshot = payloadProtection == null ? snapshot : await payloadProtection.decodeSnapshot(snapshot, continuationOffset);
 			return decompressSnapshot == null ? clearSnapshot : await decompressSnapshot(clearSnapshot);
 		};
 	}
 	composeSnapshotEncoder(payloadProtection, compressSnapshot) {
 		if (payloadProtection == null && compressSnapshot == null) return;
-		return async (snapshot) => {
+		return async (snapshot, continuationOffset) => {
 			const compressedSnapshot = compressSnapshot == null ? snapshot : await compressSnapshot(snapshot);
-			return payloadProtection == null ? compressedSnapshot : await payloadProtection.encodeSnapshot(compressedSnapshot);
+			return payloadProtection == null ? compressedSnapshot : await payloadProtection.encodeSnapshot(compressedSnapshot, continuationOffset);
 		};
 	}
 	/**
@@ -2586,7 +2754,7 @@ var StreamsCrdt = class StreamsCrdt {
 			await this.adapter.flushLocalExports?.();
 			const cursor = await this.syncOnce("sync");
 			const rawSnapshot = this.adapter.exportSnapshot();
-			const snapshot = this.encodeSnapshot == null ? rawSnapshot : await this.encodeSnapshot(rawSnapshot);
+			const snapshot = this.encodeSnapshot == null ? rawSnapshot : await this.encodeSnapshot(rawSnapshot, cursor.nextOffset);
 			await this.client.putSnapshotAt(cursor.nextOffset, snapshot);
 			return {
 				ok: true,
@@ -2909,7 +3077,13 @@ var StreamsCrdt = class StreamsCrdt {
 	async startJoin(state) {
 		try {
 			state.requestController ??= new AbortController();
-			const joined = await this.performInitialJoinSync(state.liveMode, state.requestController?.signal);
+			let joined;
+			try {
+				joined = await this.performInitialJoinSync(state.liveMode, state.requestController?.signal);
+			} catch (error) {
+				if (!(error instanceof CrdtApplyIncompleteError) || state.closed || !await this.salvageLocalBacklogOnIncompleteInitialSync(state, error)) throw error;
+				joined = await this.performInitialJoinSync(state.liveMode, state.requestController?.signal);
+			}
 			state.cursor = joined.cursor;
 			state.streamCursor = joined.streamCursor;
 			state.liveMode = joined.liveMode;
@@ -2941,6 +3115,65 @@ var StreamsCrdt = class StreamsCrdt {
 			throw error;
 		}
 	}
+	/**
+	* Join-time salvage for a stream whose head cannot be fully applied
+	* (apply_incomplete at `up_to_date`, even after bootstrap): before the
+	* join surfaces the error, durably append everything this replica holds
+	* that the server does not.
+	*
+	* Why this exists: the dual-author wedge is usually two-sided — the stream
+	* is missing some author's ops, and a replica that HOLDS those ops (e.g.
+	* received out-of-band over a local data plane) may itself be unable to
+	* complete the join because of a second gap. The regular join-time export
+	* runs only AFTER a successful initial sync, so without this salvage such
+	* a replica can never publish the healing ops, and its own backlog from a
+	* previous process run stays local for as long as the stream stays
+	* poisoned.
+	*
+	* `error.appliedVersion` advances only from success spans, so
+	* `exportUpdates(appliedVersion)` is exactly "ops this replica holds that
+	* the server does not" — the failed initial sync already imported
+	* everything the server DOES have, so the delta cannot re-append
+	* server-known data. Cursor safety is untouched: the append is write-only
+	* style (producer-acked, no read catch-up, no durable-cursor save), and
+	* the retried initial sync re-derives its cursor from the server.
+	*
+	* Returns `true` when anything was durably appended; the caller then
+	* retries the initial sync once. Best-effort: a salvage failure logs and
+	* returns `false` so the original apply-incomplete error is what callers
+	* observe.
+	*/
+	async salvageLocalBacklogOnIncompleteInitialSync(state, error) {
+		const appliedVersion = error.appliedVersion;
+		if (appliedVersion == null) return false;
+		try {
+			const appended = await this.enqueueExclusive(async () => {
+				let didAppend = false;
+				const frozen = this.frozenLocalAppend;
+				if (frozen != null) {
+					const ack = await this.appendFrozenLocalBatchRemote(frozen);
+					this.commitProducerAck(ack.producerAck);
+					didAppend = true;
+				}
+				await this.adapter.flushLocalExports?.();
+				const localBatch = this.exportUpdates(appliedVersion);
+				if (localBatch.batch != null) {
+					const appendedBatch = await this.appendLocalBatchRemote({
+						...state.cursor,
+						serverLowerBoundVersion: appliedVersion
+					}, localBatch.batch, void 0, "direct");
+					this.commitProducerAck(appendedBatch.producerAck);
+					didAppend = true;
+				}
+				return didAppend;
+			});
+			if (appended) this.logDebug("join salvage appended local backlog", { streamUrl: this.streamUrl });
+			return appended;
+		} catch (salvageError) {
+			this.logError("join salvage append failed", salvageError, { streamUrl: this.streamUrl });
+			return false;
+		}
+	}
 	async syncOnce(operation, parentSignal) {
 		let cursor = (await this.finalizeDirectLocalAppendIfNeeded(await this.resolveInitialRemoteState(operation, parentSignal))).cursor;
 		const localBatch = this.exportUpdates(cursor.serverLowerBoundVersion);
@@ -2955,8 +3188,11 @@ var StreamsCrdt = class StreamsCrdt {
 		let liveMode = preferredLiveMode;
 		const exportedLocal = this.exportUpdates(localExportRefVersion);
 		localExportRefVersion = exportedLocal.nextRefVersion;
-		if (exportedLocal.batch != null) {
-			const committed = await this.appendLocalBatchDurably(cursor, exportedLocal.batch, void 0, "direct", streamCursor);
+		const exportedBatch = exportedLocal.batch;
+		if (exportedBatch != null) {
+			const appendCursor = cursor;
+			const appendStreamCursor = streamCursor;
+			const committed = await this.enqueueExclusive(() => this.appendLocalBatchDurably(appendCursor, exportedBatch, void 0, "direct", appendStreamCursor));
 			cursor = committed.cursor;
 			streamCursor = committed.streamCursor;
 		}
@@ -3044,7 +3280,7 @@ var StreamsCrdt = class StreamsCrdt {
 	async bootstrapState(cursor, options = {}) {
 		const cursorManager = options.cursorManager ?? this.cursorManager;
 		const result = await this.client.bootstrap(options.signal, options.timeoutMode);
-		let saved = await cursorManager.applyBootstrapPayload(cursor, result.snapshot, result.updates, result.nextOffset, result.upToDate);
+		let saved = await cursorManager.applyBootstrapPayload(cursor, result.snapshot, result.updates, result.nextOffset, result.upToDate, result.snapshotOffset);
 		let bootstrapCursor = result.streamCursor;
 		if (!result.upToDate) {
 			const caughtUp = await this.catchupOrGone(saved, {
@@ -3116,7 +3352,8 @@ var StreamsCrdt = class StreamsCrdt {
 			};
 		}
 	}
-	async recoverLiveIncompleteRemoteApply(state) {
+	async recoverLiveIncompleteRemoteApply(state, error) {
+		this.cursorManager.markCursorIncomplete(state.cursor, error.unresolved);
 		try {
 			const bootstrapped = await this.bootstrapState({
 				...state.cursor,
@@ -3126,6 +3363,7 @@ var StreamsCrdt = class StreamsCrdt {
 			state.cursor = bootstrapped.cursor;
 			state.streamCursor = bootstrapped.streamCursor;
 			state.retryAttempt = 0;
+			state.incompleteRecoveryAttempt = 0;
 			state.lastError = void 0;
 			this.setReadSubStatus(state, "ok");
 			if (state.pendingLocal.length > 0) this.flushPendingLocal(state);
@@ -3137,7 +3375,10 @@ var StreamsCrdt = class StreamsCrdt {
 				code: classified.code
 			});
 			state.lastError = toTransportError(error);
+			if (state.pendingLocal.length > 0) this.flushPendingLocal(state);
 			if (classified.retriable && !isAuthOrProtocolError(error)) {
+				state.incompleteRecoveryAttempt += 1;
+				state.retryAttempt = Math.max(state.retryAttempt, state.incompleteRecoveryAttempt);
 				this.setReadSubStatus(state, "reconnecting");
 				return "retry";
 			}
@@ -3613,7 +3854,7 @@ var StreamsCrdt = class StreamsCrdt {
 				if (state.closed) return;
 				if (error instanceof CrdtApplyIncompleteError) {
 					if (capturedController?.signal.aborted && state.requestController === capturedController) state.requestController = new AbortController();
-					const recovery = await this.recoverLiveIncompleteRemoteApply(state);
+					const recovery = await this.recoverLiveIncompleteRemoteApply(state, error);
 					if (recovery === "recovered") continue;
 					if (recovery === "terminal") return;
 					if (await this.awaitReadRetryBackoff(state, error)) continue;
@@ -3647,7 +3888,7 @@ var StreamsCrdt = class StreamsCrdt {
 					const flushError = abortReason instanceof Error ? abortReason : error;
 					if (flushError instanceof CrdtApplyIncompleteError) {
 						if (state.requestController === capturedController) state.requestController = new AbortController();
-						const recovery = await this.recoverLiveIncompleteRemoteApply(state);
+						const recovery = await this.recoverLiveIncompleteRemoteApply(state, flushError);
 						if (recovery === "recovered") continue;
 						if (recovery === "terminal") return;
 						if (await this.awaitReadRetryBackoff(state, flushError)) continue;
@@ -3742,10 +3983,15 @@ var StreamsCrdt = class StreamsCrdt {
 	* `"error"` write status (with `lastWriteError` set) and then retries via
 	* this flush's own backoff timer (`maybeScheduleWriteRetry`) — it does not
 	* depend on a future local op to re-trigger the flush.
+	*
+	* While the cursor is incomplete (unresolved remote spans), the flush
+	* degrades to an append-only mode instead of pausing: batches still reach
+	* the server, but read progress, durable-cursor saves, and snapshot
+	* scheduling stay untouched. See the inline comment in the incomplete
+	* branch and specs/loro-pending.md "Local Append Rules".
 	*/
 	async flushPendingLocal(state) {
 		if (state.flushingLocal || state.closed) return;
-		if (!this.cursorManager.isCursorComplete(state.cursor)) return;
 		this.clearWriteRetryTimer(state);
 		state.flushingLocal = true;
 		try {
@@ -3754,16 +4000,23 @@ var StreamsCrdt = class StreamsCrdt {
 				if (drained == null) return;
 				let attempts = 0;
 				while (!state.closed) try {
-					state.cursor = await this.enqueueExclusive(async () => this.appendLocalBatch(state.cursor, drained.batch, drained.count, state.streamCursor));
-					const committedStreamCursor = this.consumeCommittedLocalStreamCursor();
-					if (committedStreamCursor != null) state.streamCursor = committedStreamCursor;
-					const committedCount = this.consumeCommittedPendingCount() ?? drained.count;
+					let committedCount;
+					if (this.cursorManager.isCursorComplete(state.cursor)) {
+						state.cursor = await this.enqueueExclusive(async () => this.appendLocalBatch(state.cursor, drained.batch, drained.count, state.streamCursor));
+						const committedStreamCursor = this.consumeCommittedLocalStreamCursor();
+						if (committedStreamCursor != null) state.streamCursor = committedStreamCursor;
+						committedCount = this.consumeCommittedPendingCount() ?? drained.count;
+						this.snapshotManager.schedule(state);
+					} else {
+						const appended = await this.enqueueExclusive(async () => this.appendLocalBatchRemote(state.cursor, drained.batch, drained.count, "pending"));
+						this.commitProducerAck(appended.producerAck);
+						committedCount = appended.pendingCount ?? drained.count;
+					}
 					for (let i = 0; i < committedCount; i += 1) state.pendingLocal.popFront();
 					this.notifySyncWaiters(state, committedCount);
 					state.flushHeadBatchOnly = false;
 					state.lastWriteError = void 0;
 					this.setWriteSubStatus(state, "ok");
-					this.snapshotManager.schedule(state);
 					break;
 				} catch (error) {
 					if (isPayloadTooLargeError(error) && drained.count > 1 && this.abandonPendingFrozenLocalAppend()) {
@@ -3857,12 +4110,15 @@ var StreamsCrdt = class StreamsCrdt {
 		for (const waiter of state.syncWaiters.splice(0)) waiter.reject(error);
 	}
 	async saveRemoteCursor(cursor, source) {
-		return await persistRemoteCursor({
+		const saved = await persistRemoteCursor({
 			remoteCursorStore: this.remoteCursorStore,
 			cursor,
 			source,
 			beforeRemoteCursorSave: this.beforeRemoteCursorSave
 		});
+		const state = this.joinState;
+		if (state != null && !state.closed) state.incompleteRecoveryAttempt = 0;
+		return saved;
 	}
 	setReadSubStatus(state, sub) {
 		if (sub === "ok") state.readErrorRetryAttempt = 0;
@@ -3945,4 +4201,4 @@ function isValidRillId(id) {
 //#endregion
 export { createInitialRemoteCursor as a, PayloadProtectionError as c, IndexedDbRemoteCursorStore as i, StreamsCrdt as n, EphemeralStreamCrdt as o, InMemoryRemoteCursorStore as r, LocalAppendFailedError as s, isValidRillId as t };
 
-//# sourceMappingURL=stream-id-CggbAC6b.js.map
+//# sourceMappingURL=stream-id-DwQujw_H.js.map