@loro-dev/streams-crdt 0.16.1 → 0.16.2

package/README.md

@@ -81,15 +81,35 @@ if (!result.ok && result.error.retryable) {
 
 #### Surfacing errors to end users
 
+For wrappers such as Loro Repo and diagnostic sinks, forward `error.context`,
+`error.code` and the explicit `error.retryable`. `TransportErrorContext` is an
+additive optional safe projection: source, CRDT operation, failing stage,
+original client discriminator, request operation and available timeout budget,
+elapsed duration, HTTP status, bounded request ID and allowlisted network code.
+Do not forward the whole error as a diagnostic object: legacy message, body,
+cause, headers and URL metadata may contain application secrets.
+
+Source/stage are recorded at the actual fetch, cursor load/save, durability
+hook, CRDT apply/export and payload encode/decode boundaries. Local TypeError is
+`internal_error` with `retryable: false`; fetch-thrown ordinary Error is
+`network_error`. This identifies the observed boundary, not the root cause of
+a bug inside custom fetch. Unobserved provenance is explicitly `unknown`.
+Initial-sync hard deadlines retain `initial_sync_timeout`, their own budget and
+`source: "deadline"`. See the implemented
+[safe error contract](../../specs/streams-error-context.md) for exact semantics,
+security bounds and the Loro Repo integration still required downstream.
+
 HTTP-derived variants (`server_error`, `auth_failed`, `protocol_error`,
-`stream_not_found`, `gone`) carry the response details so apps can show
-actionable messages without parsing the `message` string:
+`stream_not_found`, `gone`) retain legacy response details. Prefer numeric status
+and the safe correlation ID for UI/diagnostics; response bodies and arbitrary
+messages need application-specific handling:
 
 ```ts
 const err = result.error;
 if (err.code === "server_error") {
-  toast.error(`Server error ${err.status}${err.requestId ? ` (req: ${err.requestId})` : ""}`);
-  console.error("backend body:", err.body);
+  const requestId = err.context?.requestId;
+  toast.error(`Server error ${err.status}${requestId ? ` (req: ${requestId})` : ""}`);
+  console.error("Streams failure:", err.context);
   // err.retryAfterMs may suggest a backoff if the server set Retry-After.
 }
 ```

package/dist/flock.d.ts

@@ -1,4 +1,4 @@
-import { $ as WriteOnlyAppendResult, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportJoinParams, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSyncSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportSnapshotUploadSuccess, Y as TransportRoomStatus, Z as TransportSubscription, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as RemoteCursor, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as createInitialRemoteCursor, d as E2eeOptions, et as BeforeRemoteCursorSaveContext, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as IndexedDbRemoteCursorStoreOptions, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, m as E2eeReadPolicy, n as PayloadProtectionError, nt as InMemoryRemoteCursorStore, o as CrdtAdapter, ot as RemoteCursorSaveSource, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as IndexedDbRemoteCursorStore, s as CrdtApplyOutcome, st as RemoteCursorStore, t as isValidRillId, tt as BeforeRemoteCursorSaveHook, u as CrdtUpdateBatch, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./stream-id-DEOH5LmQ.js";
+import { $ as TransportStage, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportErrorContext, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSnapshotUploadSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportOperation, Y as TransportJoinParams, Z as TransportRoomStatus, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as InMemoryRemoteCursorStore, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as RemoteCursor, d as E2eeOptions, dt as createInitialRemoteCursor, et as TransportSubscription, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as BeforeRemoteCursorSaveHook, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, lt as RemoteCursorSaveSource, m as E2eeReadPolicy, n as PayloadProtectionError, nt as WriteOnlyAppendResult, o as CrdtAdapter, ot as IndexedDbRemoteCursorStore, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as BeforeRemoteCursorSaveContext, s as CrdtApplyOutcome, st as IndexedDbRemoteCursorStoreOptions, t as isValidRillId, tt as TransportSyncSuccess, u as CrdtUpdateBatch, ut as RemoteCursorStore, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./shared-C5Dyx541.js";
 import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 } from "@loro-dev/flock-wasm";
 
 //#region src/flock.d.ts
@@ -7,5 +7,5 @@ import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 }
  */
 declare function createFlockAdapter(flock: Flock): CrdtAdapter<VersionVector$1>;
 //#endregion
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, type ExportBundle, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, type VersionVector, WriteOnlyAppendResult, createFlockAdapter, createInitialRemoteCursor, isValidRillId };
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, type ExportBundle, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportErrorContext, TransportJoinParams, TransportOperation, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportStage, TransportSubscription, TransportSyncSuccess, type VersionVector, WriteOnlyAppendResult, createFlockAdapter, createInitialRemoteCursor, isValidRillId };
 //# sourceMappingURL=flock.d.ts.map

package/dist/flock.js

@@ -1,4 +1,4 @@
-import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-BERJQKYV.js";
+import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-Dlnc1PNH.js";
 import { Flock } from "@loro-dev/flock-wasm";
 //#region src/flock.ts
 function isAfter(entry, current) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as WriteOnlyAppendResult, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportJoinParams, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSyncSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportSnapshotUploadSuccess, Y as TransportRoomStatus, Z as TransportSubscription, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as RemoteCursor, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as createInitialRemoteCursor, d as E2eeOptions, et as BeforeRemoteCursorSaveContext, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as IndexedDbRemoteCursorStoreOptions, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, m as E2eeReadPolicy, n as PayloadProtectionError, nt as InMemoryRemoteCursorStore, o as CrdtAdapter, ot as RemoteCursorSaveSource, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as IndexedDbRemoteCursorStore, s as CrdtApplyOutcome, st as RemoteCursorStore, t as isValidRillId, tt as BeforeRemoteCursorSaveHook, u as CrdtUpdateBatch, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./stream-id-DEOH5LmQ.js";
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, isValidRillId };
+import { $ as TransportStage, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportErrorContext, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSnapshotUploadSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportOperation, Y as TransportJoinParams, Z as TransportRoomStatus, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as InMemoryRemoteCursorStore, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as RemoteCursor, d as E2eeOptions, dt as createInitialRemoteCursor, et as TransportSubscription, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as BeforeRemoteCursorSaveHook, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, lt as RemoteCursorSaveSource, m as E2eeReadPolicy, n as PayloadProtectionError, nt as WriteOnlyAppendResult, o as CrdtAdapter, ot as IndexedDbRemoteCursorStore, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as BeforeRemoteCursorSaveContext, s as CrdtApplyOutcome, st as IndexedDbRemoteCursorStoreOptions, t as isValidRillId, tt as TransportSyncSuccess, u as CrdtUpdateBatch, ut as RemoteCursorStore, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./shared-C5Dyx541.js";
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportErrorContext, TransportJoinParams, TransportOperation, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportStage, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, isValidRillId };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-BERJQKYV.js";
+import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-Dlnc1PNH.js";
 export { PayloadProtectionError as E2eeError, PayloadProtectionError, EphemeralStreamCrdt, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, LocalAppendFailedError, StreamsCrdt, createInitialRemoteCursor, isValidRillId };

package/dist/loro.d.ts

@@ -1,4 +1,4 @@
-import { $ as WriteOnlyAppendResult, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportJoinParams, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSyncSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportSnapshotUploadSuccess, Y as TransportRoomStatus, Z as TransportSubscription, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as RemoteCursor, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as createInitialRemoteCursor, d as E2eeOptions, et as BeforeRemoteCursorSaveContext, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as IndexedDbRemoteCursorStoreOptions, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, m as E2eeReadPolicy, n as PayloadProtectionError, nt as InMemoryRemoteCursorStore, o as CrdtAdapter, ot as RemoteCursorSaveSource, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as IndexedDbRemoteCursorStore, s as CrdtApplyOutcome, st as RemoteCursorStore, t as isValidRillId, tt as BeforeRemoteCursorSaveHook, u as CrdtUpdateBatch, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./stream-id-DEOH5LmQ.js";
+import { $ as TransportStage, A as PayloadProtectionProviderConfig, B as StreamsAuthProvider, C as LocalSyncStats, D as PayloadProtectionOpenInput, E as PayloadProtectionKind, F as Result, G as TransportCreateStreamSuccess, H as StreamsCrdtShardUrlsOptions, I as SnapshotCodec, J as TransportErrorContext, K as TransportDeleteStreamSuccess, L as SnapshotTransformHook, M as PayloadProtectionSealInput, N as PayloadProtectionSealResult, O as PayloadProtectionOptions, P as PayloadProtectionWritePolicy, Q as TransportSnapshotUploadSuccess, R as SnapshotUploadOptions, S as JsonValue, T as PayloadProtectionFailureReason, U as TransportCatchupParams, V as StreamsCrdtOptions, W as TransportCatchupSuccess, X as TransportOperation, Y as TransportJoinParams, Z as TransportRoomStatus, _ as EphemeralStreamCrdtOptions, a as StreamsCrdt, at as InMemoryRemoteCursorStore, b as IsolatedCrdtAdapter, c as CrdtApplyReturn, ct as RemoteCursor, d as E2eeOptions, dt as createInitialRemoteCursor, et as TransportSubscription, f as E2eeProvider, g as EphemeralStreamAdaptor, h as E2eeWritePolicy, i as EphemeralStreamCrdt, it as BeforeRemoteCursorSaveHook, j as PayloadProtectionReadPolicy, k as PayloadProtectionProvider, l as CrdtUnresolvedSpan, lt as RemoteCursorSaveSource, m as E2eeReadPolicy, n as PayloadProtectionError, nt as WriteOnlyAppendResult, o as CrdtAdapter, ot as IndexedDbRemoteCursorStore, p as E2eeProviderConfig, q as TransportError, r as LocalAppendFailedError, rt as BeforeRemoteCursorSaveContext, s as CrdtApplyOutcome, st as IndexedDbRemoteCursorStoreOptions, t as isValidRillId, tt as TransportSyncSuccess, u as CrdtUpdateBatch, ut as RemoteCursorStore, v as EphemeralStreamJoinParams, w as PayloadProtectionContext, x as JsonObject, y as EphemeralStreamSubscription, z as StreamsAuthContext } from "./shared-C5Dyx541.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/loro.d.ts
@@ -39,5 +39,5 @@ declare function loroEphemeralUpdateKey(update: Uint8Array): string | undefined;
 declare function EphemeralStoreAdaptor(store: LoroEphemeralStoreLike): EphemeralStreamAdaptor;
 declare const createLoroEphemeralStoreAdaptor: typeof EphemeralStoreAdaptor;
 //#endregion
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStoreAdaptor, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, LoroEphemeralStoreLike, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createLoroDocAdapter, createLoroEphemeralStoreAdaptor, isValidRillId, loroEphemeralUpdateKey };
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeOptions, E2eeProvider, E2eeProviderConfig, E2eeReadPolicy, E2eeWritePolicy, EphemeralStoreAdaptor, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LocalAppendFailedError, LocalSyncStats, LoroEphemeralStoreLike, PayloadProtectionContext, PayloadProtectionFailureReason, PayloadProtectionKind, PayloadProtectionOpenInput, PayloadProtectionOptions, PayloadProtectionProvider, PayloadProtectionProviderConfig, PayloadProtectionReadPolicy, PayloadProtectionSealInput, PayloadProtectionSealResult, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportErrorContext, TransportJoinParams, TransportOperation, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportStage, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createLoroDocAdapter, createLoroEphemeralStoreAdaptor, isValidRillId, loroEphemeralUpdateKey };
 //# sourceMappingURL=loro.d.ts.map

package/dist/loro.js

@@ -1,4 +1,4 @@
-import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-BERJQKYV.js";
+import { a as createInitialRemoteCursor, c as PayloadProtectionError, i as IndexedDbRemoteCursorStore, n as StreamsCrdt, o as EphemeralStreamCrdt, r as InMemoryRemoteCursorStore, s as LocalAppendFailedError, t as isValidRillId } from "./stream-id-Dlnc1PNH.js";
 import { LoroDoc, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 //#region src/loro.ts
 function batchImportUpdates(doc, updates) {

package/dist/{stream-id-DEOH5LmQ.d.ts → shared-C5Dyx541.d.ts}

@@ -1,3 +1,5 @@
+import { StreamErrorContext, StreamRequestOperation } from "@loro-dev/streams-client";
+
 //#region src/checkpoint.d.ts
 /**
  * Persisted replay progress for one stream.
@@ -186,14 +188,24 @@ type Result<T, E> = {
  * Live subscription state exposed by `join()`.
  */
 type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
+type TransportOperation = "sync" | "join" | "catchup" | "create" | "delete" | "upload" | "snapshot" | "live" | "unknown";
+type TransportStage = "bootstrap" | "catch_up" | "upload" | "cursor_load" | "cursor_save" | "cursor_delete" | "durability_hook" | "crdt_apply" | "crdt_export" | "payload_encode" | "payload_decode" | "initial_sync" | "unknown";
+/** Safe diagnostics only. Source/stage describe observed boundaries, not root cause. */
+type TransportErrorContext = Omit<StreamErrorContext, "source" | "operation" | "originalCode"> & {
+  readonly source: StreamErrorContext["source"] | "cursor_store" | "crdt" | "durability_hook" | "payload_protection" | "deadline";
+  readonly operation: TransportOperation;
+  readonly stage: TransportStage;
+  readonly requestOperation?: StreamRequestOperation;
+  readonly originalCode: StreamErrorContext["originalCode"] | TransportError["code"];
+};
 /**
  * Discriminated error union for `createStream()`, `deleteStream()`, `sync()`,
  * `join()`, and `appendWriteOnly()`.
  *
  * Every variant has a `code` discriminator and a `retryable: boolean`. Variants
  * that originate from an HTTP response also carry `status`, `message`, and
- * (when the server sent one) the raw response `body` so applications can
- * surface backend diagnostics directly to end users.
+ * (when the server sent one) the legacy raw response `body`. Use `context` for
+ * safe diagnostics rather than forwarding arbitrary messages/bodies/causes.
  *
  * Codes:
  * - `stream_not_found` — 404; the target stream does not exist. Create it first.
@@ -210,7 +222,7 @@ type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
  * - `gone` — 410; persisted cursor is no longer valid. Bootstrap from scratch.
  * - `apply_incomplete` — a CRDT adapter could not fully apply remote data.
  * - `server_error` — 5xx or 429; transient backend failure, retry with backoff.
- * - `internal_error` — local adapter/runtime failure (not from the network).
+ * - `internal_error` — local/unmarked exception; consult context for provenance.
  * - `unknown` — uncategorized error.
  * - `payload_protection_error` — payload encryption/decryption failed.
  *
@@ -224,7 +236,10 @@ type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
  * return after a single attempt — applications decide whether to retry based
  * on the `retryable` flag.
  */
-type TransportError =
+type TransportError = {
+  readonly context?: TransportErrorContext;
+} & TransportErrorDetails;
+type TransportErrorDetails =
 /**
  * The target stream does not exist on the server. Use
  * `transport.createStream()` to create it (or pass `createIfMissing: true`
@@ -253,8 +268,8 @@ type TransportError =
  * The user-supplied auth callback threw. Treated as transient because the
  * callback typically fetches a token from a backend that may flake. The
  * live read/write loops retry these automatically. `cause` is the original
- * thrown value — surface its message to logs but treat the failure as
- * retryable from the runtime's point of view.
+ * thrown value retained for compatibility; it may contain secrets. Use
+ * `context` for safe diagnostics and treat the failure as retryable.
  *
  * For "user is permanently logged out" cases, return `undefined` from the
  * auth callback instead of throwing — that lets the request go out with
@@ -365,8 +380,9 @@ type TransportError =
   readonly retryAfterMs?: number;
 }
 /**
- * The CRDT adapter or local runtime threw an unexpected error (not a
- * network failure). Indicates a bug; not retried automatically.
+ * A local or unmarked exception was classified as internal. This alone
+ * does not establish its root cause; consult `context` for provenance.
+ * Operation-level results report retryable: false.
  */
 | {
   readonly code: "internal_error";
@@ -1403,5 +1419,5 @@ declare class PayloadProtectionError extends Error {
  */
 declare function isValidRillId(id: string): boolean;
 //#endregion
-export { WriteOnlyAppendResult as $, PayloadProtectionProviderConfig as A, StreamsAuthProvider as B, LocalSyncStats as C, PayloadProtectionOpenInput as D, PayloadProtectionKind as E, Result as F, TransportCreateStreamSuccess as G, StreamsCrdtShardUrlsOptions as H, SnapshotCodec as I, TransportJoinParams as J, TransportDeleteStreamSuccess as K, SnapshotTransformHook as L, PayloadProtectionSealInput as M, PayloadProtectionSealResult as N, PayloadProtectionOptions as O, PayloadProtectionWritePolicy as P, TransportSyncSuccess as Q, SnapshotUploadOptions as R, JsonValue as S, PayloadProtectionFailureReason as T, TransportCatchupParams as U, StreamsCrdtOptions as V, TransportCatchupSuccess as W, TransportSnapshotUploadSuccess as X, TransportRoomStatus as Y, TransportSubscription as Z, EphemeralStreamCrdtOptions as _, StreamsCrdt as a, RemoteCursor as at, IsolatedCrdtAdapter as b, CrdtApplyReturn as c, createInitialRemoteCursor as ct, E2eeOptions as d, BeforeRemoteCursorSaveContext as et, E2eeProvider as f, EphemeralStreamAdaptor as g, E2eeWritePolicy as h, EphemeralStreamCrdt as i, IndexedDbRemoteCursorStoreOptions as it, PayloadProtectionReadPolicy as j, PayloadProtectionProvider as k, CrdtUnresolvedSpan as l, E2eeReadPolicy as m, PayloadProtectionError as n, InMemoryRemoteCursorStore as nt, CrdtAdapter as o, RemoteCursorSaveSource as ot, E2eeProviderConfig as p, TransportError as q, LocalAppendFailedError as r, IndexedDbRemoteCursorStore as rt, CrdtApplyOutcome as s, RemoteCursorStore as st, isValidRillId as t, BeforeRemoteCursorSaveHook as tt, CrdtUpdateBatch as u, EphemeralStreamJoinParams as v, PayloadProtectionContext as w, JsonObject as x, EphemeralStreamSubscription as y, StreamsAuthContext as z };
-//# sourceMappingURL=stream-id-DEOH5LmQ.d.ts.map
+export { TransportStage as $, PayloadProtectionProviderConfig as A, StreamsAuthProvider as B, LocalSyncStats as C, PayloadProtectionOpenInput as D, PayloadProtectionKind as E, Result as F, TransportCreateStreamSuccess as G, StreamsCrdtShardUrlsOptions as H, SnapshotCodec as I, TransportErrorContext as J, TransportDeleteStreamSuccess as K, SnapshotTransformHook as L, PayloadProtectionSealInput as M, PayloadProtectionSealResult as N, PayloadProtectionOptions as O, PayloadProtectionWritePolicy as P, TransportSnapshotUploadSuccess as Q, SnapshotUploadOptions as R, JsonValue as S, PayloadProtectionFailureReason as T, TransportCatchupParams as U, StreamsCrdtOptions as V, TransportCatchupSuccess as W, TransportOperation as X, TransportJoinParams as Y, TransportRoomStatus as Z, EphemeralStreamCrdtOptions as _, StreamsCrdt as a, InMemoryRemoteCursorStore as at, IsolatedCrdtAdapter as b, CrdtApplyReturn as c, RemoteCursor as ct, E2eeOptions as d, createInitialRemoteCursor as dt, TransportSubscription as et, E2eeProvider as f, EphemeralStreamAdaptor as g, E2eeWritePolicy as h, EphemeralStreamCrdt as i, BeforeRemoteCursorSaveHook as it, PayloadProtectionReadPolicy as j, PayloadProtectionProvider as k, CrdtUnresolvedSpan as l, RemoteCursorSaveSource as lt, E2eeReadPolicy as m, PayloadProtectionError as n, WriteOnlyAppendResult as nt, CrdtAdapter as o, IndexedDbRemoteCursorStore as ot, E2eeProviderConfig as p, TransportError as q, LocalAppendFailedError as r, BeforeRemoteCursorSaveContext as rt, CrdtApplyOutcome as s, IndexedDbRemoteCursorStoreOptions as st, isValidRillId as t, TransportSyncSuccess as tt, CrdtUpdateBatch as u, RemoteCursorStore as ut, EphemeralStreamJoinParams as v, PayloadProtectionContext as w, JsonObject as x, EphemeralStreamSubscription as y, StreamsAuthContext as z };
+//# sourceMappingURL=shared-C5Dyx541.d.ts.map