@loro-dev/streams-crdt 0.14.1 → 0.15.1

package/dist/{stream-id-CEp4zEQJ.js → stream-id-BygPTNvQ.js}

@@ -208,59 +208,51 @@ const MAGIC = new Uint8Array([
 	67,
 	69
 ]);
-const ENVELOPE_VERSION = 1;
-const SUITE_AES_256_GCM = 1;
+const PROVIDER_ENVELOPE_VERSION = 2;
+const PAYLOAD_PROTECTION_PROTOCOL = "loro-streams-crdt-payload-protection";
 const UPDATE_BATCH_KIND = 1;
 const SNAPSHOT_KIND = 2;
-const AES_GCM_NONCE_BYTES = 12;
-const HEADER_BYTES = 10;
-const AES_GCM_TAG_BITS = 128;
-const RAW_AES_256_KEY_BYTES = 32;
-const textEncoder$1 = new TextEncoder();
-const textDecoder = new TextDecoder();
+const PROVIDER_PREFIX_BYTES = 10;
+const MAX_PROVIDER_HEADER_BYTES = 512;
+const MAX_PROVIDER_SEAL_OVERHEAD_BYTES = 4 * 1024;
+const providerAadDomain = new TextEncoder().encode(`${PAYLOAD_PROTECTION_PROTOCOL}/v2\0`);
 var PayloadProtectionError = class extends Error {
 	reason;
-	keyId;
-	constructor(reason, message, options = {}) {
-		super(message, options.cause == null ? void 0 : { cause: options.cause });
+	constructor(reason, message = payloadProtectionFailureMessage(reason)) {
+		super(message);
 		this.name = "PayloadProtectionError";
 		this.reason = reason;
-		this.keyId = options.keyId;
+	}
+};
+var ProviderSealContractError = class extends PayloadProtectionError {
+	constructor(message) {
+		super("encrypt_failed", message);
+		this.name = "ProviderSealContractError";
 	}
 };
 var PayloadProtectionRuntime = class {
 	readPolicy;
 	writePolicy;
-	scope;
-	writeKey;
-	readKeys;
-	importedWriteKey;
-	importedReadKeys = /* @__PURE__ */ new Map();
+	provider;
 	constructor(options) {
 		this.readPolicy = options.readPolicy;
 		this.writePolicy = options.writePolicy;
-		this.scope = options.scope;
-		this.writeKey = options.writeKey;
-		this.readKeys = options.readKeys;
+		this.provider = options.provider;
 	}
 	async encodeUpdateItems(clearUpdates) {
 		if (this.writePolicy === "plaintext") return clearUpdates;
-		return [await this.encryptPayload("update_batch", encodeItems(clearUpdates))];
+		return [await this.sealPayload("update_batch", encodeItems(clearUpdates))];
 	}
 	measureEncodedUpdateItemsByteLength(clearUpdates) {
 		if (this.writePolicy === "plaintext") return encodedItemsByteLength(clearUpdates);
-		const writeKey = this.writeKey;
-		if (writeKey == null || this.scope == null) throw new PayloadProtectionError("encrypt_failed", "E2EE write encryption requires encryption.writeKey and encryption.scope");
-		const clearBatchBytes = encodedItemsByteLength(clearUpdates);
-		const keyIdBytes = textEncoder$1.encode(writeKey.id);
-		if (keyIdBytes.byteLength === 0 || keyIdBytes.byteLength > 255) throw new PayloadProtectionError("encrypt_failed", "E2EE key id must be 1..255 UTF-8 bytes", { keyId: writeKey.id });
-		return 4 + (HEADER_BYTES + keyIdBytes.byteLength + AES_GCM_NONCE_BYTES + clearBatchBytes + AES_GCM_TAG_BITS / 8);
+		if (this.provider == null) throw new PayloadProtectionError("encrypt_failed", "provider-backed E2EE writes require a provider");
+		return 4 + PROVIDER_PREFIX_BYTES + encodedItemsByteLength(clearUpdates) + this.provider.maxSealOverheadBytes;
 	}
 	async decodeUpdateItems(wireItems) {
 		const out = [];
 		for (const item of wireItems) {
 			if (isEncryptedEnvelope(item)) {
-				const clearBatch = await this.decryptPayload("update_batch", item);
+				const clearBatch = await this.openPayload("update_batch", item);
 				out.push(...decodeItems(clearBatch));
 				continue;
 			}
@@ -271,75 +263,76 @@ var PayloadProtectionRuntime = class {
 	}
 	async encodeSnapshot(snapshot) {
 		if (this.writePolicy === "plaintext") return snapshot;
-		return await this.encryptPayload("snapshot", snapshot);
+		return await this.sealPayload("snapshot", snapshot);
 	}
 	async decodeSnapshot(snapshot) {
-		if (isEncryptedEnvelope(snapshot)) return await this.decryptPayload("snapshot", snapshot);
+		if (isEncryptedEnvelope(snapshot)) return await this.openPayload("snapshot", snapshot);
 		this.assertPlaintextAllowed("snapshot");
 		return snapshot;
 	}
-	async encryptPayload(kind, plaintext) {
-		const writeKey = this.writeKey;
-		if (writeKey == null || this.scope == null) throw new PayloadProtectionError("encrypt_failed", "E2EE write encryption requires encryption.writeKey and encryption.scope");
+	async sealPayload(kind, plaintext) {
+		return await this.sealProviderPayload(kind, plaintext);
+	}
+	async openPayload(expectedKind, envelope) {
+		const version = envelope[4];
+		if (version === PROVIDER_ENVELOPE_VERSION) return await this.openProviderPayload(expectedKind, envelope);
+		throw new PayloadProtectionError("invalid_envelope", `unsupported streams-crdt protected payload envelope version '${String(version)}'`);
+	}
+	async sealProviderPayload(kind, plaintext) {
+		const provider = this.provider;
+		if (provider == null) throw new PayloadProtectionError("encrypt_failed", "provider-backed E2EE writes require a provider");
+		const context = createProviderContext(kind);
+		let authenticatedHeader;
+		let additionalDataCalls = 0;
+		let result;
 		try {
-			const key = await (this.importedWriteKey ??= importAesGcmKey(writeKey.key));
-			const nonce = createNonce();
-			return concatBytes(createEnvelopeHeader(kind, writeKey.id, nonce), new Uint8Array(await getSubtleCrypto().encrypt({
-				name: "AES-GCM",
-				iv: toArrayBuffer(nonce),
-				tagLength: AES_GCM_TAG_BITS,
-				additionalData: toArrayBuffer(createAad({
-					kind,
-					keyId: writeKey.id,
-					scope: this.scope
-				}))
-			}, key, toArrayBuffer(plaintext))));
-		} catch (error) {
-			if (error instanceof PayloadProtectionError) throw error;
-			throw new PayloadProtectionError("encrypt_failed", "failed to encrypt streams-crdt payload", {
-				keyId: writeKey.id,
-				cause: error
+			result = await provider.seal({
+				plaintext,
+				context,
+				additionalData: (header) => {
+					additionalDataCalls += 1;
+					if (additionalDataCalls !== 1) throw new ProviderSealContractError("payload protection provider must request additionalData exactly once");
+					authenticatedHeader = normalizeProviderHeader(header).slice();
+					return createProviderAad(createProviderEnvelopeHeader(kind, authenticatedHeader));
+				}
 			});
+		} catch (error) {
+			if (error instanceof ProviderSealContractError) throw error;
+			const reason = error instanceof PayloadProtectionError ? error.reason : "encrypt_failed";
+			throw new PayloadProtectionError(reason, payloadProtectionFailureMessage(reason));
 		}
-	}
-	async decryptPayload(expectedKind, envelope) {
-		const parsed = parseEnvelope(envelope);
-		if (parsed.kind !== expectedKind) throw new PayloadProtectionError("wrong_payload_kind", `expected ${expectedKind} payload, got ${parsed.kind}`, { keyId: parsed.keyId });
-		if (this.scope == null) throw new PayloadProtectionError("missing_read_key", "E2EE read decryption requires encryption.scope", { keyId: parsed.keyId });
-		const key = await this.getReadKey(parsed.keyId);
 		try {
-			return new Uint8Array(await getSubtleCrypto().decrypt({
-				name: "AES-GCM",
-				iv: toArrayBuffer(parsed.nonce),
-				tagLength: AES_GCM_TAG_BITS,
-				additionalData: toArrayBuffer(createAad({
-					kind: parsed.kind,
-					keyId: parsed.keyId,
-					scope: this.scope
-				}))
-			}, key, toArrayBuffer(parsed.ciphertext)));
+			const returnedHeader = normalizeProviderHeader(result.header);
+			if (additionalDataCalls !== 1) throw new ProviderSealContractError("payload protection provider must request additionalData exactly once");
+			if (authenticatedHeader == null || !equalBytes(authenticatedHeader, returnedHeader)) throw new ProviderSealContractError("payload protection provider must authenticate the exact header it returns");
+			if (!(result.sealed instanceof Uint8Array) || result.sealed.byteLength === 0) throw new ProviderSealContractError("payload protection provider returned empty or invalid sealed bytes");
+			if (returnedHeader.byteLength + result.sealed.byteLength - plaintext.byteLength > provider.maxSealOverheadBytes) throw new ProviderSealContractError("payload protection provider exceeded maxSealOverheadBytes");
+			return concatBytes(createProviderEnvelopeHeader(kind, returnedHeader), result.sealed);
 		} catch (error) {
-			throw new PayloadProtectionError("decrypt_failed", "failed to decrypt streams-crdt payload", {
-				keyId: parsed.keyId,
-				cause: error
-			});
+			if (error instanceof ProviderSealContractError) throw error;
+			const reason = error instanceof PayloadProtectionError ? error.reason : "encrypt_failed";
+			throw new PayloadProtectionError(reason, payloadProtectionFailureMessage(reason));
 		}
 	}
-	async getReadKey(keyId) {
-		const cached = this.importedReadKeys.get(keyId);
-		if (cached != null) return await cached;
-		const imported = importAesGcmKey((await this.resolveReadKey(keyId)).key);
-		this.importedReadKeys.set(keyId, imported);
-		return await imported;
-	}
-	async resolveReadKey(keyId) {
-		for (const key of await this.resolveReadKeys()) if (key.id === keyId) return key;
-		throw new PayloadProtectionError("missing_read_key", `missing read key for protected streams-crdt payload '${keyId}'`, { keyId });
-	}
-	async resolveReadKeys() {
-		const readKeys = typeof this.readKeys === "function" ? await this.readKeys() : this.readKeys;
-		if (readKeys != null) return readKeys;
-		return this.writeKey == null ? [] : [this.writeKey];
+	async openProviderPayload(expectedKind, envelope) {
+		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);
+		try {
+			const plaintext = await provider.open({
+				sealed: parsed.sealed,
+				header: parsed.header,
+				context,
+				additionalData: createProviderAad(parsed.authenticatedHeader)
+			});
+			if (!(plaintext instanceof Uint8Array)) throw new PayloadProtectionError("decrypt_failed", "payload protection provider returned invalid plaintext bytes");
+			return plaintext;
+		} catch (error) {
+			const reason = error instanceof PayloadProtectionError ? error.reason : "decrypt_failed";
+			throw new PayloadProtectionError(reason, payloadProtectionFailureMessage(reason));
+		}
 	}
 	assertPlaintextAllowed(label) {
 		if (this.readPolicy === "allow-plaintext") return;
@@ -352,62 +345,74 @@ function normalizePayloadProtection(options, label = "payloadProtection") {
 	const writePolicy = options.writePolicy ?? "encrypt";
 	if (readPolicy !== "encrypted-only" && readPolicy !== "allow-plaintext") throw new Error(`${label}.readPolicy must be encrypted-only or allow-plaintext`);
 	if (writePolicy !== "encrypt" && writePolicy !== "plaintext") throw new Error(`${label}.writePolicy must be encrypt or plaintext`);
-	const encryption = options.encryption;
-	if (encryption != null && encryption.scope == null) throw new Error(`${label}.encryption.scope is required when encryption is configured`);
-	if (writePolicy === "encrypt" && encryption?.writeKey == null) throw new Error(`${label}.encryption.writeKey is required when writePolicy is encrypt`);
-	if (writePolicy === "encrypt" && encryption?.scope == null) throw new Error(`${label}.encryption.scope is required when writePolicy is encrypt`);
-	validateKey(encryption?.writeKey, `${label}.encryption.writeKey`);
-	const readKeys = normalizeReadKeys(encryption?.readKeys, `${label}.encryption.readKeys`);
+	const provider = options.provider;
+	if (provider != null && (typeof provider.seal !== "function" || typeof provider.open !== "function" || !Number.isSafeInteger(provider.maxSealOverheadBytes) || provider.maxSealOverheadBytes < 0 || provider.maxSealOverheadBytes > MAX_PROVIDER_SEAL_OVERHEAD_BYTES)) throw new Error(`${label}.provider must implement seal()/open() and declare maxSealOverheadBytes as a safe integer from 0 through ${MAX_PROVIDER_SEAL_OVERHEAD_BYTES}`);
+	if (writePolicy === "encrypt" && provider == null) throw new Error(`${label}.provider is required when writePolicy is encrypt`);
 	return new PayloadProtectionRuntime({
 		readPolicy,
 		writePolicy,
-		scope: encryption?.scope,
-		writeKey: encryption?.writeKey,
-		readKeys
+		provider
 	});
 }
 function isPayloadProtectionError(error) {
 	return error instanceof PayloadProtectionError;
 }
+function payloadProtectionFailureMessage(reason) {
+	switch (reason) {
+		case "plaintext_forbidden": return "plaintext payload rejected by protected-read policy";
+		case "missing_read_key": return "protected payload key is unavailable";
+		case "decrypt_failed": return "protected payload authentication failed";
+		case "invalid_envelope": return "invalid protected payload envelope";
+		case "wrong_payload_kind": return "protected payload kind mismatch";
+		case "encrypt_failed": return "protected payload sealing failed";
+	}
+}
 function isEncryptedEnvelope(payload) {
 	return payload.byteLength >= MAGIC.byteLength && MAGIC.every((byte, index) => payload[index] === byte);
 }
-function createEnvelopeHeader(kind, keyId, nonce) {
-	const keyIdBytes = textEncoder$1.encode(keyId);
-	if (keyIdBytes.byteLength === 0 || keyIdBytes.byteLength > 255) throw new PayloadProtectionError("encrypt_failed", "E2EE key id must be 1..255 UTF-8 bytes", { keyId });
-	if (nonce.byteLength !== AES_GCM_NONCE_BYTES) throw new PayloadProtectionError("encrypt_failed", `AES-GCM nonce must be ${AES_GCM_NONCE_BYTES} bytes`, { keyId });
-	const header = new Uint8Array(HEADER_BYTES + keyIdBytes.byteLength + nonce.byteLength);
+function createProviderContext(kind) {
+	return {
+		protocol: PAYLOAD_PROTECTION_PROTOCOL,
+		version: PROVIDER_ENVELOPE_VERSION,
+		kind
+	};
+}
+function createProviderEnvelopeHeader(kind, providerHeader) {
+	const normalizedHeader = normalizeProviderHeader(providerHeader);
+	const header = new Uint8Array(PROVIDER_PREFIX_BYTES + normalizedHeader.byteLength);
+	const view = new DataView(header.buffer);
 	header.set(MAGIC, 0);
-	header[4] = ENVELOPE_VERSION;
+	header[4] = PROVIDER_ENVELOPE_VERSION;
 	header[5] = encodeKind(kind);
-	header[6] = SUITE_AES_256_GCM;
-	header[7] = keyIdBytes.byteLength;
-	header[8] = nonce.byteLength;
+	view.setUint16(6, normalizedHeader.byteLength, false);
+	header[8] = 0;
 	header[9] = 0;
-	header.set(keyIdBytes, HEADER_BYTES);
-	header.set(nonce, HEADER_BYTES + keyIdBytes.byteLength);
+	header.set(normalizedHeader, PROVIDER_PREFIX_BYTES);
 	return header;
 }
-function parseEnvelope(payload) {
-	if (!isEncryptedEnvelope(payload) || payload.byteLength < HEADER_BYTES) throw new PayloadProtectionError("invalid_envelope", "invalid streams-crdt encrypted payload envelope");
-	const version = payload[4];
-	const suite = payload[6];
-	const keyIdLen = payload[7] ?? 0;
-	const nonceLen = payload[8] ?? 0;
-	const reserved = payload[9];
-	if (version !== ENVELOPE_VERSION || suite !== SUITE_AES_256_GCM || nonceLen !== AES_GCM_NONCE_BYTES || reserved !== 0) throw new PayloadProtectionError("invalid_envelope", "unsupported streams-crdt encrypted payload envelope");
-	const kind = decodeKind(payload[5]);
-	const keyIdStart = HEADER_BYTES;
-	const nonceStart = keyIdStart + keyIdLen;
-	const ciphertextStart = nonceStart + nonceLen;
-	if (keyIdLen === 0 || payload.byteLength <= ciphertextStart) throw new PayloadProtectionError("invalid_envelope", "truncated streams-crdt encrypted payload envelope");
+function parseProviderEnvelope(payload) {
+	if (!isEncryptedEnvelope(payload) || payload.byteLength < PROVIDER_PREFIX_BYTES) throw new PayloadProtectionError("invalid_envelope", "invalid streams-crdt provider payload envelope");
+	const providerHeaderLength = new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint16(6, false);
+	if (payload[4] !== PROVIDER_ENVELOPE_VERSION || providerHeaderLength === 0 || providerHeaderLength > MAX_PROVIDER_HEADER_BYTES || payload[8] !== 0 || payload[9] !== 0) throw new PayloadProtectionError("invalid_envelope", "unsupported streams-crdt provider payload envelope");
+	const headerEnd = PROVIDER_PREFIX_BYTES + providerHeaderLength;
+	if (payload.byteLength <= headerEnd) throw new PayloadProtectionError("invalid_envelope", "truncated streams-crdt provider payload envelope");
 	return {
-		kind,
-		keyId: textDecoder.decode(payload.slice(keyIdStart, nonceStart)),
-		nonce: payload.slice(nonceStart, ciphertextStart),
-		ciphertext: payload.slice(ciphertextStart)
+		kind: decodeKind(payload[5]),
+		header: payload.slice(PROVIDER_PREFIX_BYTES, headerEnd),
+		authenticatedHeader: payload.slice(0, headerEnd),
+		sealed: payload.slice(headerEnd)
 	};
 }
+function normalizeProviderHeader(header) {
+	if (!(header instanceof Uint8Array) || header.byteLength === 0 || header.byteLength > MAX_PROVIDER_HEADER_BYTES) throw new ProviderSealContractError(`payload protection provider header must be 1..${MAX_PROVIDER_HEADER_BYTES} bytes`);
+	return header;
+}
+function equalBytes(left, right) {
+	return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+function createProviderAad(authenticatedHeader) {
+	return concatBytes(providerAadDomain, authenticatedHeader);
+}
 function encodeKind(kind) {
 	return kind === "update_batch" ? UPDATE_BATCH_KIND : SNAPSHOT_KIND;
 }
@@ -416,74 +421,18 @@ function decodeKind(encoded) {
 	if (encoded === SNAPSHOT_KIND) return "snapshot";
 	throw new PayloadProtectionError("invalid_envelope", "unsupported streams-crdt encrypted payload kind");
 }
-function createNonce() {
-	const nonce = new Uint8Array(AES_GCM_NONCE_BYTES);
-	getCrypto().getRandomValues(nonce);
-	return nonce;
-}
-function createAad(input) {
-	return textEncoder$1.encode(JSON.stringify({
-		keyId: input.keyId,
-		kind: input.kind,
-		protocol: "loro-streams-crdt-payload-protection",
-		scope: normalizeScope(input.scope),
-		suite: "aes_256_gcm",
-		version: ENVELOPE_VERSION
-	}));
-}
-function normalizeScope(scope) {
-	return typeof scope === "string" ? scope : `bucket:${scope.bucketId}\nstream:${scope.streamId}`;
-}
-function concatBytes(left, right) {
-	const out = new Uint8Array(left.byteLength + right.byteLength);
-	out.set(left);
-	out.set(right, left.byteLength);
+function concatBytes(...parts) {
+	const out = new Uint8Array(parts.reduce((length, part) => length + part.byteLength, 0));
+	let cursor = 0;
+	for (const part of parts) {
+		out.set(part, cursor);
+		cursor += part.byteLength;
+	}
 	return out;
 }
 function encodedItemsByteLength(items) {
 	return items.reduce((sum, item) => sum + 4 + item.byteLength, 0);
 }
-async function importAesGcmKey(key) {
-	if (isCryptoKey(key)) return key;
-	validateRawKey(key);
-	return await getSubtleCrypto().importKey("raw", toArrayBuffer(key), "AES-GCM", false, ["encrypt", "decrypt"]);
-}
-function toArrayBuffer(bytes) {
-	return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
-}
-function validateKey(key, label) {
-	if (key == null) return;
-	if (key.id.trim().length === 0) throw new Error(`${label}.id must be non-empty`);
-	if (key.key instanceof Uint8Array) validateRawKey(key.key);
-}
-function normalizeReadKeys(readKeys, label) {
-	if (readKeys == null) return;
-	if (typeof readKeys === "function") return async () => {
-		const resolved = await readKeys();
-		validateKeys(resolved, label);
-		return resolved;
-	};
-	validateKeys(readKeys, label);
-	return readKeys;
-}
-function validateKeys(keys, label) {
-	for (const [index, key] of keys.entries()) validateKey(key, `${label}[${index}]`);
-}
-function isCryptoKey(key) {
-	return typeof CryptoKey !== "undefined" && key instanceof CryptoKey;
-}
-function validateRawKey(key) {
-	if (key.byteLength !== RAW_AES_256_KEY_BYTES) throw new Error(`E2EE raw AES-GCM keys must be ${RAW_AES_256_KEY_BYTES} bytes`);
-}
-function getCrypto() {
-	if (globalThis.crypto == null) throw new PayloadProtectionError("encrypt_failed", "Web Crypto is unavailable in this runtime");
-	return globalThis.crypto;
-}
-function getSubtleCrypto() {
-	const subtle = getCrypto().subtle;
-	if (subtle == null) throw new PayloadProtectionError("encrypt_failed", "SubtleCrypto is unavailable in this runtime");
-	return subtle;
-}
 //#endregion
 //#region src/transport-internal.ts
 function createProducerId() {
@@ -844,8 +793,7 @@ function toTransportError(error) {
 		code: "payload_protection_error",
 		retryable: false,
 		reason: error.reason,
-		keyId: error.keyId,
-		message: error.message
+		message: payloadProtectionFailureMessage(error.reason)
 	};
 	if (error instanceof TypeError) return {
 		code: "network_error",
@@ -2118,11 +2066,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) {
@@ -2150,6 +2119,22 @@ var TransportCursorManager = class {
 	isCursorComplete(cursor) {
 		return !this.incompleteCursors.has(cursor);
 	}
+	/**
+	* 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) {
 		let nextVersion = cursor.serverLowerBoundVersion;
 		let complete = true;
@@ -2223,7 +2208,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;
 		}
@@ -2378,6 +2363,7 @@ function createJoinState(cursor, liveMode = "sse") {
 		pendingLocal: new Deque(),
 		flushingLocal: false,
 		retryAttempt: 0,
+		incompleteRecoveryAttempt: 0,
 		retrySleepController: new AbortController(),
 		readLoopRunning: false,
 		readErrorRetryAttempt: 0,
@@ -2480,11 +2466,9 @@ var StreamsCrdt = class StreamsCrdt {
 		this.debug = options.debug ?? false;
 		this.beforeRemoteCursorSave = composeBeforeRemoteCursorSaveHooks(options.beforeRemoteCursorSave, ...options.beforeRemoteCursorSaveHooks ?? []);
 		const snapshotCodec = normalizeSnapshotCodec(options.snapshotCodec);
-		if (options.e2ee != null && options.payloadProtection != null) throw new Error("Specify only one of e2ee or payloadProtection");
-		const payloadProtectionOption = options.e2ee ?? options.payloadProtection;
-		const payloadProtectionLabel = options.e2ee != null ? "e2ee" : "payloadProtection";
-		const payloadProtection = normalizePayloadProtection(payloadProtectionOption, payloadProtectionLabel);
-		if (payloadProtection?.writePolicy === "plaintext" && options.snapshotUpload != null && options.snapshotUpload.enabled !== false) throw new Error(`snapshotUpload is not supported when ${payloadProtectionLabel}.writePolicy is plaintext`);
+		if (options.payloadProtectionRequired === true && options.e2ee == null) throw new Error("payloadProtectionRequired is true but this room has no e2ee config");
+		const payloadProtection = normalizePayloadProtection(options.e2ee, "e2ee");
+		if (payloadProtection?.writePolicy === "plaintext" && options.snapshotUpload != null && options.snapshotUpload.enabled !== false) throw new Error("snapshotUpload is not supported when e2ee.writePolicy is plaintext");
 		const snapshotUploadConfig = normalizeSnapshotUploadConfig(options.snapshotUpload);
 		this.decodeSnapshot = this.composeSnapshotDecoder(payloadProtection, snapshotCodec?.decompress);
 		this.encodeSnapshot = this.composeSnapshotEncoder(payloadProtection, snapshotCodec?.compress);
@@ -2963,7 +2947,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;
@@ -2995,6 +2985,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);
@@ -3009,8 +3058,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;
 		}
@@ -3170,7 +3222,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,
@@ -3180,6 +3233,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);
@@ -3191,7 +3245,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";
 			}
@@ -3667,7 +3724,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;
@@ -3701,7 +3758,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;
@@ -3796,10 +3853,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 {
@@ -3808,16 +3870,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()) {
@@ -3911,12 +3980,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;
@@ -3987,33 +4059,16 @@ var StreamsCrdt = class StreamsCrdt {
 //#region src/stream-id.ts
 const MAX_STREAM_ID_BYTES = 512;
 const textEncoder = new TextEncoder();
-const DEFAULT_BASE_URL = "https://streams-api.loro.dev";
 function utf8ByteLength(value) {
 	return textEncoder.encode(value).byteLength;
 }
 /**
-* Validates a stream id accepted by `createStreamUrl()`.
+* Validates a Durable Streams stream id.
 */
 function isValidRillId(id) {
-	return id.length > 0 && utf8ByteLength(id) <= MAX_STREAM_ID_BYTES && !id.includes("/") && !id.includes("\0") && !id.includes("..");
-}
-/**
-* Validates a bucket id accepted by `createStreamUrl()`.
-*/
-function isValidBucketId(id) {
-	return isValidRillId(id);
-}
-/**
-* Builds a Durable Streams HTTP URL for one `(bucketId, streamId)` pair.
-*/
-function createStreamUrl(input) {
-	const baseUrl = (input.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/g, "");
-	if (!isValidBucketId(input.bucketId)) throw new Error(`invalid bucketId: ${JSON.stringify(input.bucketId)} (must be non-empty UTF-8, <= ${MAX_STREAM_ID_BYTES} bytes, and exclude "/", "\\0", "..")`);
-	if (!isValidRillId(input.streamId)) throw new Error(`invalid streamId: ${JSON.stringify(input.streamId)} (must be non-empty UTF-8, <= ${MAX_STREAM_ID_BYTES} bytes, and exclude "/", "\\0", "..")`);
-	const streamId = input.streamId;
-	return `${baseUrl}/ds/${encodeURIComponent(input.bucketId)}/${encodeURIComponent(streamId)}`;
+	return id.length > 0 && utf8ByteLength(id) <= MAX_STREAM_ID_BYTES && id !== "." && !id.includes("/") && !id.includes("\0") && !id.includes("..");
 }
 //#endregion
-export { InMemoryRemoteCursorStore as a, EphemeralStreamCrdt as c, StreamsCrdt as i, LocalAppendFailedError as l, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t, PayloadProtectionError as u };
+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-CEp4zEQJ.js.map
+//# sourceMappingURL=stream-id-BygPTNvQ.js.map