@loro-dev/loro-repo-client 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,815 @@
1
- # Temporary Holding Version
1
+ # `@loro-dev/loro-repo-client`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Slim TypeScript RPC & real-time subscription SDK (`0.1.0`, wire protocol `2`) for [`@loro-dev/loro-repo-engine`](https://www.npmjs.com/package/@loro-dev/loro-repo-engine), built on [`@loro-dev/json-patch`](https://www.npmjs.com/package/@loro-dev/json-patch) and monotonic `txId` causality.
4
+
5
+ > **Companion packages**
6
+ > - [`@loro-dev/loro-repo-engine`](https://www.npmjs.com/package/@loro-dev/loro-repo-engine) — Prebuilt Rust Node-API engine & `loro-repo` CLI.
7
+ > - [`@loro-dev/json-patch`](https://www.npmjs.com/package/@loro-dev/json-patch) — Pure-JS deterministic JSON Patch engine (`diff`, `apply`, `compact`).
8
+
9
+ ---
10
+
11
+ ## Table of Contents
12
+
13
+ 1. [Architecture & Subpath Entrypoints](#1-architecture--subpath-entrypoints)
14
+ 2. [5-Minute Quick Start](#2-5-minute-quick-start)
15
+ 3. [Host Discovery, Lock Election & Auto-Reconnect](#3-host-discovery-lock-election--auto-reconnect)
16
+ 4. [Complete Electron Main <-> Renderer `MessagePort` Bridge](#4-complete-electron-main---renderer-messageport-bridge)
17
+ 5. [Rooms, Field-Level `DocSchema` & Synthetic `$cid`](#5-rooms-field-level-docschema--synthetic-cid)
18
+ 6. [Reading, Patching, Subpath Subscriptions, `UpdateOrigin` & CAS / Rebase](#6-reading-patching-subpath-subscriptions-updateorigin--cas--rebase)
19
+ 7. [Causal & Version Inspection (`inspectDocCausal`)](#7-causal--version-inspection-inspectdoccausal)
20
+ 8. [Bare `Flock` Key-Value Operations & Workspace `RepoMetaClient`](#8-bare-flock-key-value-operations--workspace-repometaclient)
21
+ 9. [Roost Turn Streams (`roost_stream`)](#9-roost-turn-streams-roost_stream)
22
+ 10. [Cloud Sync, Workspace Stream Routes, `shardUrls`, `aadDomain` & In-Memory Auth](#10-cloud-sync-workspace-stream-routes-shardurls-aaddomain--in-memory-auth)
23
+ 11. [E2EE Protectors (`registerProtector`), Multi-Writer Isolation & Epoch Key Rotation](#11-e2ee-protectors-registerprotector-multi-writer-isolation--epoch-key-rotation)
24
+ 12. [Ephemeral Presence Channels (`presence`, `machine-monitor`)](#12-ephemeral-presence-channels-presence-machine-monitor)
25
+ 13. [Quiet v1 -> v2 Storage Migration (`importRoomState` & `setStreamCheckpoint`)](#13-quiet-v1---v2-storage-migration-importroomstate--setstreamcheckpoint)
26
+ 14. [Complete Error Codes & Remote Health Reference](#14-complete-error-codes--remote-health-reference)
27
+ 15. [Lody Integration FAQ & Common Pitfalls](#15-lody-integration-faq--common-pitfalls)
28
+
29
+ ---
30
+
31
+ ## 1. Architecture & Subpath Entrypoints
32
+
33
+ All SQLite WAL storage, CRDT state machines (`LoroDoc`, `Flock`, `Meta`, `RoostStream`), E2EE outbox serialization, and Durable Streams HTTP/SSE replication run inside **a single Rust engine host** (`@loro-dev/loro-repo-engine`). JS/TS processes never open SQLite files directly or load heavy CRDT WASM heaps; instead they hold lightweight `RepoClient` connections exchanging length-prefixed JSON frames.
34
+
35
+ | Import Path | Target Runtime | Node APIs / `Buffer`? | What It Exports |
36
+ | :--- | :--- | :--- | :--- |
37
+ | **`@loro-dev/loro-repo-client`** | Auto (`browser` condition -> `./browser`; Node/default -> `./browser` + `./node`) | Conditional | Combined exports for Node.js, Electron Main, and modern conditional bundlers. |
38
+ | **`@loro-dev/loro-repo-client/browser`** | Browsers, Electron Renderer, Web Workers, React Native | **Zero `node:*`, zero `Buffer`** | `RepoClient`, `LengthPrefixedByteFramer`, `MAX_FRAME_BYTES`, `createInMemoryTransportPair`, `RepoMetaClient`, `META_ROOM`, `metaOps`, `parseRepoMetaEntries`, `createLodyWorkspaceRoutes`, `LODY_*_DOC_SCHEMA`, `getLodyDocSchemaForId`, `RepoRpcError`, `ProtectError`, `PROTOCOL_VERSION`, and all TypeScript interfaces/unions. |
39
+ | **`@loro-dev/loro-repo-client/node`** | Node.js, Electron Main, `utilityProcess`, CLI / Agent Workers | Yes (`node:net`, `node:fs/promises`) | `ensureEngineHost`, `connectEngine`, `readEngineEndpoint`, `connectSocketTransport`, `connectUnixSocketTransport`, `PROTOCOL_VERSION`. |
40
+
41
+ ```bash
42
+ pnpm add @loro-dev/loro-repo-client @loro-dev/json-patch
43
+ # Add the native engine only in processes that may host or spawn the local daemon:
44
+ pnpm add @loro-dev/loro-repo-engine
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 2. 5-Minute Quick Start
50
+
51
+ ```ts
52
+ import * as addon from "@loro-dev/loro-repo-engine";
53
+ import { ensureEngineHost } from "@loro-dev/loro-repo-client/node";
54
+ import { getLodyDocSchemaForId } from "@loro-dev/loro-repo-client/browser";
55
+
56
+ // 1. Start engine (or attach to existing host if another process already holds files.lock)
57
+ const host = await ensureEngineHost({ addon, dataDir: "/tmp/lody-data" });
58
+ const client = host.client;
59
+
60
+ const ns = "ws-demo";
61
+ const room = { kind: "loro_doc", id: "session-1" } as const;
62
+
63
+ // 2. Create (idempotently ensure) a room with Lody's persisted field-level DocSchema
64
+ await client.createRoom(ns, room, "plaintext", {
65
+ docSchema: getLodyDocSchemaForId(room.id),
66
+ });
67
+
68
+ // 3. Subscribe only to `["history"]` — writes to `["mq"]` or `["session"]` will NOT fire this listener
69
+ const historySub = await client.subscribeDoc(ns, room, ["history"], (value, info) => {
70
+ console.log("history updated:", value, "txId:", info.txId, "origin:", info.origin);
71
+ });
72
+
73
+ // 4. Write scalar metadata + append text via CRDT str_splice
74
+ const ack = await client.applyDocPatch(ns, room, [
75
+ { op: "set", path: ["session"], value: { id: "1", status: "running" } },
76
+ { op: "set", path: ["history"], value: [{ id: "t1", role: "assistant", text: "Hello" }] },
77
+ { op: "str_splice", path: ["history", 0, "text"], at: 5, del: 0, ins: " world!" },
78
+ ]);
79
+
80
+ // 5. Wait until `historySub.currentValue` reflects at least `ack.txId`
81
+ await historySub.whenVisible(ack.txId);
82
+
83
+ // 6. On-demand snapshot read
84
+ const snap = await client.readDoc(ns, room, ["session"]);
85
+ console.log(snap.value, "at roomTxId", snap.roomTxId);
86
+
87
+ await historySub.unsubscribe();
88
+ await host.close();
89
+ ```
90
+
91
+ ---
92
+
93
+ ## 3. Host Discovery, Lock Election & Auto-Reconnect
94
+
95
+ ### `ensureEngineHost` vs `connectEngine` vs `new RepoClient`
96
+
97
+ 1. **`ensureEngineHost({ addon, dataDir, idleMs?, streamsUrl?, maxFrameBytes?, handoffTimeoutMs?, clientOptions? })`** (in `./node`):
98
+ - Checks `addon.engineVersion().protocol === PROTOCOL_VERSION` (`2`), throwing `ENGINE_PROTOCOL_MISMATCH` immediately on skew.
99
+ - Calls `addon.startEngine(...)`. If this process wins `<dataDir>/files.lock`, returns `{ role: "host", endpoint, client, engine, close }`.
100
+ - If another live process already owns `files.lock` (`ENGINE_BUSY`), reads `<dataDir>/engine.json`, verifies `protocol_version === 2`, and connects over the local socket as `{ role: "client", endpoint, client, engine: null, close }` (retrying transient handoffs up to `handoffTimeoutMs`, default `5000` ms).
101
+ - Enables `autoReconnect: true` by default on `client`.
102
+ 2. **`connectEngine(dataDir, options?)`** (in `./node`):
103
+ - Client-only connection without loading `@loro-dev/loro-repo-engine` (ideal for thin agent/CLI worker processes).
104
+ - Pass `waitForEndpointMs: 5000` if the host might still be starting up.
105
+ - Configure `autoReconnect: { initialDelayMs: 25, maxDelayMs: 500, timeoutMs: 15_000 }` (or `false` to fail on disconnect).
106
+ 3. **`new RepoClient(transport, options?)`** (in `.` and `./browser`):
107
+ - Low-level constructor accepting any `RepoTransport` (`connectSocketTransport`, `MessagePort` wrapper, `createInMemoryTransportPair`, etc.).
108
+ - `options.reconnect?: () => Promise<RepoTransport>` enables automatic transport replacement.
109
+ - `options.queueWhileReconnecting?: boolean` (default `true`): RPCs called while `client.connectionState === "reconnecting"` pause via `whenConnected()` and run once reconnected.
110
+
111
+ ### Exact Reconnection Guarantees (Read Carefully!)
112
+
113
+ - **What replays automatically**: When `reconnect` (or `reconnectWith(nextTransport)`) succeeds, `RepoClient` automatically re-registers all `registerProtector` and `registerAuthProvider` handlers **before** re-opening all active `subscribeDoc`, `flockSubscribe`, `ephemeralSubscribe`, and `subscribeRemoteStatus` handles. Active `SubscriptionHandle` listeners receive an update with `info.resetReason = "reconnect"` so UI state syncs cleanly.
114
+ - **What fails immediately**: In-flight RPCs whose wire request had already been sent **before** the old socket dropped are rejected with an error (`"disconnected: ..."`) — **they are never silently re-executed**, so idempotency/retry of interrupted mutations remains under caller control.
115
+ - Watch connection transitions via `client.connectionState` (`"connected" | "reconnecting" | "closed"`) and `client.onConnectionStateChange((state, err) => ...)`.
116
+
117
+ ---
118
+
119
+ ## 4. Complete Electron Main <-> Renderer `MessagePort` Bridge
120
+
121
+ Because `@loro-dev/loro-repo-client/browser` contains **zero `node:*` imports and zero `Buffer` references**, an Electron Renderer process can talk to the Rust engine safely with `contextIsolation: true` and `nodeIntegration: false` by forwarding JSON text frames over a `MessagePort` bridge:
122
+
123
+ ### `main.ts` (Electron Main — connects Main <-> Socket and bridges Renderer `MessagePort`)
124
+
125
+ ```ts
126
+ import { ipcMain, MessageChannelMain, type BrowserWindow, type IpcMainEvent } from "electron";
127
+ import * as addon from "@loro-dev/loro-repo-engine";
128
+ import { ensureEngineHost, connectSocketTransport } from "@loro-dev/loro-repo-client/node";
129
+
130
+ const host = await ensureEngineHost({ addon, dataDir });
131
+
132
+ export function attachRendererBridge(win: BrowserWindow) {
133
+ const connect = async (event: IpcMainEvent) => {
134
+ if (event.sender !== win.webContents || event.senderFrame !== win.webContents.mainFrame) return;
135
+ try {
136
+ const socketTransport = await connectSocketTransport(host.endpoint.socket);
137
+ if (win.isDestroyed()) {
138
+ await socketTransport.close();
139
+ return;
140
+ }
141
+ const { port1: mainPort, port2: rendererPort } = new MessageChannelMain();
142
+ const close = () => {
143
+ mainPort.postMessage({ type: "loro-repo:closed" });
144
+ mainPort.close();
145
+ };
146
+
147
+ mainPort.on("message", (msgEvent) => {
148
+ if (typeof msgEvent.data === "string") {
149
+ try {
150
+ socketTransport.send(msgEvent.data);
151
+ } catch {
152
+ close();
153
+ }
154
+ }
155
+ });
156
+
157
+ const offMsg = socketTransport.onMessage((jsonText) => mainPort.postMessage(jsonText));
158
+ const offClose = socketTransport.onClose(close);
159
+ mainPort.on("close", () => {
160
+ offMsg();
161
+ offClose();
162
+ void socketTransport.close();
163
+ });
164
+
165
+ mainPort.start();
166
+ event.sender.postMessage("loro-repo:port", null, [rendererPort]);
167
+ } catch (error) {
168
+ if (!event.sender.isDestroyed()) {
169
+ event.sender.send("loro-repo:connect-error", String(error));
170
+ }
171
+ }
172
+ };
173
+ ipcMain.on("loro-repo:connect", connect);
174
+ win.once("closed", () => ipcMain.removeListener("loro-repo:connect", connect));
175
+ }
176
+ ```
177
+
178
+ Call `attachRendererBridge(win)` once for each trusted application window, before loading its page. The socket exposes the full local engine API; do not attach this bridge to windows that load untrusted content. `dataDir` is your application's persistent data directory.
179
+
180
+ ### `preload.ts` (transfers the port into the Renderer's main world)
181
+
182
+ `MessagePort` cannot be passed through a `contextBridge` callback. Transfer it with `window.postMessage` instead; expose only the connection request through `contextBridge`.
183
+
184
+ ```ts
185
+ import { contextBridge, ipcRenderer } from "electron";
186
+
187
+ contextBridge.exposeInMainWorld("loroBridge", {
188
+ connect() {
189
+ ipcRenderer.send("loro-repo:connect");
190
+ },
191
+ });
192
+
193
+ ipcRenderer.on("loro-repo:port", (event) => {
194
+ const [port] = event.ports;
195
+ if (port) window.postMessage({ type: "loro-repo:port" }, "*", [port]);
196
+ });
197
+ ipcRenderer.on("loro-repo:connect-error", (_event, message: string) => {
198
+ window.postMessage({ type: "loro-repo:connect-error", message }, "*");
199
+ });
200
+ ```
201
+
202
+ ### `renderer.ts` (Electron Renderer / React — pure `@loro-dev/loro-repo-client/browser`)
203
+
204
+ ```ts
205
+ import { RepoClient, type RepoTransport } from "@loro-dev/loro-repo-client/browser";
206
+
207
+ declare global {
208
+ interface Window {
209
+ loroBridge: { connect(): void };
210
+ }
211
+ }
212
+
213
+ function createMessagePortTransport(port: MessagePort): RepoTransport {
214
+ const msgHandlers = new Set<(jsonText: string) => void>();
215
+ const closeHandlers = new Set<(error?: Error) => void>();
216
+ let closed = false;
217
+
218
+ const closePort = () => {
219
+ if (closed) return;
220
+ closed = true;
221
+ port.close();
222
+ for (const h of [...closeHandlers]) h();
223
+ };
224
+
225
+ port.onmessage = (event) => {
226
+ if (event.data?.type === "loro-repo:closed") {
227
+ closePort();
228
+ return;
229
+ }
230
+ if (typeof event.data === "string") {
231
+ for (const h of [...msgHandlers]) h(event.data);
232
+ }
233
+ };
234
+ port.onmessageerror = () => closePort();
235
+ port.start();
236
+
237
+ return {
238
+ send(jsonText) {
239
+ if (closed) throw new Error("transport closed");
240
+ port.postMessage(jsonText);
241
+ },
242
+ onMessage(handler) {
243
+ msgHandlers.add(handler);
244
+ return () => void msgHandlers.delete(handler);
245
+ },
246
+ onClose(handler) {
247
+ closeHandlers.add(handler);
248
+ return () => void closeHandlers.delete(handler);
249
+ },
250
+ close: async () => closePort(),
251
+ };
252
+ }
253
+
254
+ export async function connectRendererClient(): Promise<RepoClient> {
255
+ const transport = await new Promise<RepoTransport>((resolve, reject) => {
256
+ const cleanup = () => {
257
+ window.removeEventListener("message", receive);
258
+ clearTimeout(timer);
259
+ };
260
+ const receive = (event: MessageEvent) => {
261
+ if (event.source !== window) return;
262
+ if (event.data?.type === "loro-repo:connect-error") {
263
+ cleanup();
264
+ reject(new Error(event.data.message));
265
+ } else if (event.data?.type === "loro-repo:port" && event.ports[0]) {
266
+ cleanup();
267
+ resolve(createMessagePortTransport(event.ports[0]));
268
+ }
269
+ };
270
+ const timer = setTimeout(() => {
271
+ cleanup();
272
+ reject(new Error("Engine bridge connection timed out"));
273
+ }, 5_000);
274
+ window.addEventListener("message", receive);
275
+ window.loroBridge.connect();
276
+ });
277
+ return new RepoClient(transport);
278
+ }
279
+ ```
280
+
281
+ Notice that giving each Renderer its own forwarded `socketTransport` means:
282
+ - Each Renderer's `ephemeralSet(..., { connectionBound: true })` cleans up automatically if that window closes or reloads.
283
+ - Subscription patches (`["history"]`, `["mq"]`) push directly into React without any manual IPC serialization boilerplate.
284
+
285
+ Create one client per Renderer and share it across components; do not call `connectRendererClient()` concurrently. Close it when the page is disposed. This minimal bridge reports disconnects but does not automatically reconnect: to restore subscriptions, obtain a fresh transport and call `client.reconnectWith(transport)`, or supply a `reconnect` factory to `RepoClient`.
286
+
287
+ ---
288
+
289
+ ## 5. Rooms, Field-Level `DocSchema` & Synthetic `$cid`
290
+
291
+ ### The 4 Room Kinds (`RoomKind`)
292
+
293
+ | `room.kind` | Underlying CRDT / Store | Operations | Sync Stream Purpose |
294
+ | :--- | :--- | :--- | :--- |
295
+ | **`"loro_doc"`** | `LoroDoc` (`Map`, `List`, `MovableList`, `Text`, atomic `LoroValue`) | `readDoc`, `applyDocPatch`, `subscribeDoc`, `inspectDocCausal`, `exportLoroRaw`, `importLoroRaw` | `LoroUpdate` / `LoroSnapshot` |
296
+ | **`"flock"`** | Bare `Flock` key-value map (`FlockKey = JsonValue[]`) | `flockGet`, `flockScan`, `flockBatch`, `flockSubscribe` | `FlockUpdate` / `FlockSnapshot` |
297
+ | **`"meta"`** | Namespace catalog (`META_ROOM = { kind: "meta", id: "meta" }`, bare `Flock`) | `client.repoMeta(ns)` or `flock*` RPCs | `FlockUpdate` / `FlockSnapshot` |
298
+ | **`"roost_stream"`** | Cryptographic append/edit/seal turn log (`loro-roost`) | `roostCreateTurn`, `roostEditTurn`, `roostSealTurn`, `roostReadTurns` | Replicated in SQLite `v2_roost_kv` + sync |
299
+
300
+ > Calling `readDoc` / `applyDocPatch` / `subscribeDoc` on a `"flock"` or `"meta"` room rejects with `RepoRpcError("unsupported")`.
301
+
302
+ ### Field-Level `DocSchema` & Lody Presets
303
+
304
+ Without a `docSchema`, JSON writes could turn scalar metadata strings into `LoroText` containers or dynamic JSON blobs into nested `LoroMap`s instead of matching your CRDT schema (`loro-mirror`, mobile/CLI readers). `DocSchema` is **persisted alongside room metadata in SQLite** (or passed on `createRoom` / `applyDocPatch`) and governs every mutation inside Rust:
305
+
306
+ - `roots`: explicit root container kinds (`"map" | "list" | "movable_list" | "text"`).
307
+ - `rules`: ordered `{ pattern, kind }` overrides (`first match wins`), where `pattern` supports literal string keys, `{ key: "*" }` (escaped literal key), `"*"` (any single key/index), `"**"` (zero or more segments), and non-negative integer indices:
308
+ - `"text"` -> `LoroText` container (enables character-level `str_splice`).
309
+ - `"value"` -> atomic `LoroValue` (never creates subcontainers; preserves arbitrary nested config maps as a single atomic unit, like `loro-mirror`'s `schema.Any()`).
310
+ - `"map"` / `"list"` / `"movable_list"` -> corresponding nested Loro container.
311
+ - `defaultObject` (`"map"`), `defaultArray` (`"list"`), `defaultString` (`"value"` keeps scalar metadata like `id`, `role`, `status`, `task` as primitive `LoroValue::String`!).
312
+
313
+ Use Lody's built-in presets directly:
314
+
315
+ ```ts
316
+ import {
317
+ LODY_SESSION_DOC_SCHEMA,
318
+ LODY_SCHEDULE_DOC_SCHEMA,
319
+ LODY_PREVIEW_COMMENT_DOC_SCHEMA,
320
+ LODY_SHORTCUT_DOC_SCHEMA,
321
+ getLodyDocSchemaForId,
322
+ } from "@loro-dev/loro-repo-client/browser";
323
+
324
+ // Auto-matches prefixes: "session-*", "schedule-*", "preview-comment-*", "shortcut-body:*"
325
+ const schema = getLodyDocSchemaForId(room.id);
326
+ await client.createRoom(ns, room, "encrypted", { docSchema: schema });
327
+ ```
328
+
329
+ ### Synthetic `"$cid"` Container Identity (CRITICAL Rules)
330
+
331
+ When `cidPatterns` (e.g. `[["mq", "*"]]` on `LODY_SESSION_DOC_SCHEMA`) matches a `LoroMap` element inside a `list` or `movable_list`:
332
+
333
+ 1. **Reads, subscriptions, and emitted `SubPatch`es inject synthetic `"$cid": "<LoroMap.id>"`** (e.g. `"cid:0@123456:Map"`), letting React lists key items and compute LIS `move` diffs via `@loro-dev/json-patch`!
334
+ 2. **`"$cid"` is NEVER written into the underlying `LoroDoc`**: Any `"$cid"` key echoed back in `set` or `arr_splice` is stripped before touching Loro.
335
+ 3. **Preserve `$cid` vs Replace `$cid` (Exact Mutation Semantics)**:
336
+ - **Updating fields or moving (`set` on `["mq", 0, "task"]` or `move` `["mq", 1] -> ["mq", 0]`)**: Mutates or moves the **existing `LoroMap` container in place**, so `"$cid"` **stays identical**!
337
+ - **Replacing a whole item (`set` on `["mq", 0]` with `{ $cid, task: "..." }` or removing/reinserting it with `arr_splice`)**: Strips any client-supplied `$cid` and allocates a **new `LoroMap` container** (producing a **brand-new `$cid`**)! To edit a queue item in place while preserving its identity, emit field-level `set` patches.
338
+
339
+ **Generic `diff()` output is not automatically a valid engine write.** `@loro-dev/json-patch` operates on projected JSON and does not know your persisted `DocSchema`. Even with `$cid` key extractors, it may emit `str_splice` for a scalar string such as `mq[*].task`. Lody's schema stores that field as an atomic value, so the engine rejects the splice with `invalid_patch`. Use `set` for scalar metadata and `str_splice` only for declared `text` containers. Likewise, edit an atomic object by setting the entire atomic value rather than patching inside it.
340
+
341
+ For example, move a queue entry and edit its scalar task in one batch:
342
+
343
+ ```ts
344
+ await client.applyDocPatch(ns, room, [
345
+ { op: "move", from: ["mq", 1], to: ["mq", 0] },
346
+ { op: "set", path: ["mq", 0, "task"], value: "edited task" },
347
+ ]);
348
+ ```
349
+
350
+ Paths in the second operation address the result of the first operation. In a concurrent editor, protect index-based edits with `cas` or use `rebase` against the snapshot's `roomTxId`. Keyed `diff()` is useful for plain JSON projection updates; using it to generate engine writes requires schema-aware normalization of its output.
351
+
352
+ ---
353
+
354
+ ## 6. Reading, Patching, Subpath Subscriptions, `UpdateOrigin` & CAS / Rebase
355
+
356
+ ### Subpath Subscriptions, `whenVisible` & `UpdateOrigin`
357
+
358
+ ```ts
359
+ const mqSub = await client.subscribeDoc(ns, room, ["mq"], (mqValue, info) => {
360
+ // Fires ONLY when `["mq"]` changed (or on reconnect reset)!
361
+ // `info.origin` is `"local"` for local commits, `"remote"` if any remote frame
362
+ // contributed to this coalesced batch ("remote" is sticky across batching).
363
+ // `info.patch` is rebased relative to `["mq"]` (not document root!).
364
+ renderQueue(mqValue, info.origin);
365
+ });
366
+
367
+ const ack = await client.applyDocPatch(ns, room, [
368
+ { op: "set", path: ["mq", 0, "task"], value: "updated" },
369
+ ], { writer: "member:alice" });
370
+
371
+ // Read-your-writes barrier for this live engine session, even if `["mq"]` wasn't
372
+ // touched or another room in the same namespace wrote `ack.txId`, because
373
+ // the engine pushes per-namespace `Watermark` frames after flushing patches!
374
+ await mqSub.whenVisible(ack.txId);
375
+ ```
376
+
377
+ ### Optimistic Concurrency: `cas` vs `rebase` & `transactCas`
378
+
379
+ - **`{ mode: "cas", expected_room_tx_id }`**: Fails with `RepoRpcError("precondition_failed")` unless the room's current `roomTxId === expected_room_tx_id`. Use for strict compare-and-swap queue transitions or state machines.
380
+ - **`{ mode: "rebase", base_room_tx_id }`**: Rebases your `JsonPatch` at the frontiers of `base_room_tx_id` inside Rust (`apply_json_patch_at`) and merges concurrently with compatible edits; fails with `precondition_failed` only if `base_room_tx_id` was compacted away or is incompatible. Works on `"loro_doc"` rooms (rejected on `"flock"` rooms).
381
+
382
+ ```ts
383
+ // Built-in retry loop (retries up to `maxRetries` = 8 on `"precondition_failed"`)
384
+ const result = await client.transactCas(async () => {
385
+ const snap = await client.readDoc(ns, room, ["mq"]);
386
+ const queue = snap.value as unknown[];
387
+ return client.applyDocPatch(
388
+ ns,
389
+ room,
390
+ [{ op: "arr_splice", path: ["mq"], at: queue.length, del: 0, items: [{ task: "next" }] }],
391
+ {
392
+ writer: "member:alice",
393
+ precondition: { mode: "cas", expected_room_tx_id: snap.roomTxId },
394
+ },
395
+ );
396
+ }, { maxRetries: 8 });
397
+ ```
398
+
399
+ The retry callback may run more than once. Keep external side effects (HTTP requests, payments, notifications) outside it. Append with `arr_splice` rather than replacing the entire queue so existing entries keep their container identity.
400
+
401
+ ### Performance and Lifecycle Budget
402
+
403
+ - **Use small projections.** Subscribe to the subtree displayed by a component rather than the whole document. The initial snapshot and reconnect resets still contain the full selected subtree; subpath subscriptions reduce IPC and JS projection work, not the Rust engine's underlying document size.
404
+ - **Write deltas and batch related edits.** Send related operations in one `applyDocPatch` call (atomic within one room). For streaming output, accumulate short chunks and append with `str_splice`; bound pending work instead of firing an unbounded `Promise.all` or sending one RPC per character. Measure batching latency in your application; there is no universally optimal interval.
405
+ - **Preserve identity.** Use field-level patches and `move` for existing list items, and `arr_splice` for insertion/removal. Avoid repeatedly replacing large arrays or whole documents; this recreates containers and increases diff, serialization, and render work.
406
+ - **Keep callbacks cheap.** Treat `currentValue` and listener values as immutable. Schedule expensive rendering separately, avoid cloning the entire snapshot, and use `info.patch` for incremental consumers. Its paths are relative to the subscribed subtree. Initial snapshots and reconnect resets require replacing your local projection instead of applying a patch.
407
+ - **Bound frame sizes.** IPC's maximum frame body is 64 MiB, including JSON encoding and any base64 expansion; it is a ceiling, not a target payload size. Large snapshots and individual atomic writes must fit. Split independent work across rooms or bounded requests before approaching it.
408
+ - **Separate visibility from replication.** `whenVisible(ack.txId)` confirms local subscription visibility, not cloud upload, backup, or receipt by another device. Use it with an acknowledgement from the same namespace and live engine session. It has no built-in timeout; close/unsubscribe rejects waiters, and reconnect alone cannot guarantee progress for an old transaction ID. Apply an application deadline and reconcile with a new snapshot after disconnect.
409
+ - **Keep ownership explicit.** Share a client within a process, unsubscribe on component teardown, and close it at process shutdown. Closing a managed host with `role === "host"` also stops the engine for all connected processes; use a dedicated host process when short-lived workers must come and go independently.
410
+ - **Handle ambiguous writes.** If a connection drops after sending a mutation, the mutation may already have committed. Read current state or check an application operation ID before retrying an append or increment. Auto-reconnect restores subscriptions and providers, not safe exactly-once mutation delivery.
411
+
412
+ ### Compaction & Raw Escape Hatches
413
+
414
+ - `await client.compactRoom(ns, room, writer?)`: Explicitly folds local oplog entries into a snapshot (`writer` is attributed on encrypted outbox snapshot rows). Note: the engine also auto-compacts every `64` ops.
415
+ - `await client.exportLoroRaw(ns, room)`: Exports raw Loro snapshot bytes (`{ txId, roomTxId, bytes: Uint8Array }`) — **escape hatch for debugging/testing**, normal apps do not need `loro-crdt`.
416
+ - `await client.importLoroRaw(ns, room, bytes, writer?)`: Imports raw Loro update/snapshot bytes and enqueues them for outbound sync under `writer`.
417
+
418
+ ---
419
+
420
+ ## 7. Causal & Version Inspection (`inspectDocCausal`)
421
+
422
+ Inspect underlying CRDT causality without loading `loro-crdt` WASM in JS:
423
+
424
+ ```ts
425
+ const c1 = await client.inspectDocCausal(ns, scheduleRoom, {
426
+ itemIdPaths: [["scheduleAuthorizations", 0]],
427
+ });
428
+ // c1.frontiers -> [{ peer: "12345...", counter: 4 }, ...] (`LoroOpId[]`)
429
+ // c1.version -> { "12345...": 5, ... } (JSON VersionVector)
430
+ // c1.itemIds -> [{ peer: "...", counter: ... } | null] (stable Loro creation OpId!)
431
+
432
+ // Later: detect which root containers received ANY CRDT op since `c1.version`
433
+ // (catches even idempotent/same-value CRDT rewrites that produce an empty JSON diff!)
434
+ const c2 = await client.inspectDocCausal(ns, scheduleRoom, {
435
+ sinceVersion: c1.version,
436
+ });
437
+ // e.g. c2.changedRoots === ["definition", "timeline"]
438
+ ```
439
+
440
+ ---
441
+
442
+ ## 8. Bare `Flock` Key-Value Operations & Workspace `RepoMetaClient`
443
+
444
+ ### Bare `Flock` RPCs (`flockGet`, `flockScan`, `flockBatch`, `flockSubscribe`)
445
+
446
+ Keys are composite JSON tuple arrays (`FlockKey = readonly JsonValue[]`) sorted lexicographically by element:
447
+
448
+ ```ts
449
+ const srRoom = { kind: "flock", id: `${wsId}:sr` } as const;
450
+ await client.createRoom(ns, srRoom, "encrypted");
451
+
452
+ // Atomic batch put/delete (supports `writer` and `precondition`)
453
+ await client.flockBatch(ns, srRoom, [
454
+ { op: "put", key: ["sched", "daily"], value: { enabled: true, cron: "0 9 * * *" } },
455
+ { op: "delete", key: ["sched", "obsolete"] },
456
+ ], { writer: "member:alice" });
457
+
458
+ const single = await client.flockGet(ns, srRoom, ["sched", "daily"]);
459
+ // { txId, roomTxId, found: true, value: { enabled: true, ... } }
460
+
461
+ const page = await client.flockScan(ns, srRoom, {
462
+ prefix: ["sched"],
463
+ limit: 100,
464
+ });
465
+ // { txId, roomTxId, entries: [{ key: ["sched", "daily"], value: ... }] }
466
+
467
+ // Subscribe to live prefix/range updates (`sub.currentValue` is `FlockEntry[]`)
468
+ const flockSub = await client.flockSubscribe(ns, srRoom, { prefix: ["sched"] }, (entries, info) => {
469
+ console.log("matching entries:", entries, "origin:", info.origin);
470
+ });
471
+ ```
472
+
473
+ ### Workspace Metadata (`client.repoMeta(ns)` / `RepoMetaClient`)
474
+
475
+ `RepoMetaClient` manages `{ kind: "meta", id: "meta" }` (`META_ROOM`) using the standard `e`, `m`, `ef`, `efx` tuple layout:
476
+
477
+ ```ts
478
+ const meta = client.repoMeta(ns);
479
+ await meta.ensureRoom("encrypted");
480
+
481
+ // Register or update a document's catalog metadata
482
+ await meta.upsertDoc(
483
+ "session-1",
484
+ { title: "Build Release", updatedAt: Date.now() },
485
+ [], // optional metadata keys to delete
486
+ { writer: "member:alice" },
487
+ );
488
+
489
+ await meta.setDocMeta("session-1", "pinned", true, { writer: "member:alice" });
490
+ await meta.markDocDeleted("session-old", { writer: "member:alice" });
491
+
492
+ // Register a named Flock room with optional TTL expiry (used by file-index `fi:*` rooms)
493
+ await meta.upsertFlock(`${wsId}:fi:mac-1`, Date.now() + 180 * 86_400_000, { writer: "member:alice" });
494
+
495
+ const docRecord = await meta.getDoc("session-1");
496
+ const allDocs = await meta.listDocs();
497
+ const allFlocks = await meta.listFlocks();
498
+
499
+ // Reactive subscription receiving parsed `RepoMetaSnapshot` ({ docs, flocks })
500
+ const metaSub = await meta.subscribe((snap) => {
501
+ console.log("docs:", Object.keys(snap.docs), "flocks:", Object.keys(snap.flocks));
502
+ });
503
+ ```
504
+
505
+ ---
506
+
507
+ ## 9. Roost Turn Streams (`roost_stream`)
508
+
509
+ For structured append/stream/seal conversation turns signed by a 32-byte Ed25519 `writerSeed`:
510
+
511
+ ```ts
512
+ const turnsRoom = { kind: "roost_stream", id: "session-turns" } as const;
513
+ await client.createRoom(ns, turnsRoom, "plaintext");
514
+
515
+ const writerSeed = crypto.getRandomValues(new Uint8Array(32)); // 32-byte Ed25519 seed
516
+
517
+ // 1. Create a turn (`createKey` optional idempotency key)
518
+ const t1 = await client.roostCreateTurn(ns, turnsRoom, writerSeed, {
519
+ role: "assistant",
520
+ text: "Thinking",
521
+ });
522
+ // { txId, turnIdHex, nextSeq }
523
+
524
+ // 2. Append streaming tokens with `expectedNextSeq` optimistic concurrency guard
525
+ const t2 = await client.roostEditTurn(ns, turnsRoom, writerSeed, t1.turnIdHex, t1.nextSeq, [
526
+ { op: "append_text", path: ["text"], text: "... Done!" },
527
+ { op: "set", path: ["status"], value: "complete" },
528
+ ]);
529
+
530
+ // 3. Seal turn permanently (subsequent edits reject)
531
+ await client.roostSealTurn(ns, turnsRoom, writerSeed, t1.turnIdHex, t2.nextSeq);
532
+
533
+ // 4. Read turns
534
+ const { turns } = await client.roostReadTurns(ns, turnsRoom, 50);
535
+ ```
536
+
537
+ Supported `RoostWriteOp` variants: `"set"`, `"remove"`, `"append_text"`, `"splice_text"`.
538
+
539
+ ---
540
+
541
+ ## 10. Cloud Sync, Workspace Stream Routes, `shardUrls`, `aadDomain` & In-Memory Auth
542
+
543
+ ### Configuring Remotes (`configureRemote`), Routing & Sharding
544
+
545
+ ```ts
546
+ import { createLodyWorkspaceRoutes } from "@loro-dev/loro-repo-client/browser";
547
+
548
+ await client.configureRemote(ns, {
549
+ remote_id: "workspace",
550
+ base_url: "https://streams.lody.ai",
551
+ bucket: "lody-app", // Physical Durable Streams bucket (`space` optional for UserSpace)
552
+ encrypted: true, // Enforce LSCE v2 + content-v0 E2EE sealing/opening
553
+ snapshot_zstd: true, // Zstd level-3 compress snapshots prior to E2EE sealing
554
+ // Decouples LSCE `streams-room-aad` logical domain from local SQLite namespace:
555
+ aadDomain: `lody-e2ee:${genesisHex}`,
556
+ routes: createLodyWorkspaceRoutes(wsId, {
557
+ excludePrefixes: ["shortcut-"], // `skip: true` on matching doc prefixes
558
+ excludeFlockPrefixes: ["local-cache:"], // `skip: true` on matching flock prefixes
559
+ fileIndexTtlSeconds: 180 * 86_400, // `Stream-TTL` on `fi:*` and `fis:*` streams (default 180d)
560
+ }),
561
+ shardUrls: {
562
+ bootstrap: [shard0, shard1],
563
+ catchup: [shard0, shard1],
564
+ largePost: [shard0, shard1],
565
+ other: [shard0, shard1],
566
+ presence: [presenceOrigin], // Deterministic FNV-1a routing per streamId
567
+ largePostMinBytes: 65_536, // Route large POST bodies >= 64 KiB to `largePost`
568
+ },
569
+ });
570
+
571
+ const report = await client.syncNamespace(ns, "workspace");
572
+ // { txId, pushedFrames, pulledFrames, blockedRooms }
573
+ ```
574
+
575
+ ### Multi-Remote Splitting with `skip: true`
576
+
577
+ When routing specific rooms (e.g. `shortcut-1`) to an isolated remote with separate auth/ACL, pair `excludePrefixes: ["shortcut-"]` on `"workspace"` with a dedicated remote whose catch-all fallback sets `skip: true`:
578
+
579
+ ```ts
580
+ await client.configureRemote(ns, {
581
+ remote_id: "shortcut:1",
582
+ base_url: "https://shortcuts.lody.ai",
583
+ bucket: "lody-app",
584
+ encrypted: true,
585
+ routes: [
586
+ { kind: "loro_doc", matchExact: "shortcut-1", streamId: `${wsId}:ps:1` },
587
+ { kind: "loro_doc", skip: true },
588
+ { kind: "flock", skip: true },
589
+ { kind: "meta", skip: true },
590
+ ],
591
+ });
592
+ ```
593
+
594
+ Any room matched by `skip: true` produces **zero outbox rows** for that remote.
595
+
596
+ ### In-Memory Bearer Auth Providers (`registerAuthProvider`)
597
+
598
+ > **Zero Secrets on Disk**: Bearer tokens are **never** persisted to SQLite (`v2_remotes` stores URLs/routes/encryption flags only). Even `RemoteConfig.auth_token` stays in process memory only and clears on engine restart.
599
+
600
+ Register a dynamic token provider scoped by `domains` and `remoteIds` (higher `priority` wins):
601
+
602
+ ```ts
603
+ await client.registerAuthProvider({
604
+ domains: [ns], // omit or include "*" for all namespaces
605
+ remoteIds: ["workspace"], // omit or include "*" for all remotes
606
+ priority: 100,
607
+ getToken: async ({ namespace, remoteId, rejectedToken }) => {
608
+ if (rejectedToken) {
609
+ // Engine received HTTP 401 on `rejectedToken` — force refresh once
610
+ return await authSession.refreshBearerToken(rejectedToken);
611
+ }
612
+ return await authSession.getBearerToken();
613
+ },
614
+ });
615
+ ```
616
+
617
+ ---
618
+
619
+ ## 11. E2EE Protectors (`registerProtector`), Multi-Writer Isolation & Epoch Key Rotation
620
+
621
+ ### Concrete-Writer Registration (`writers`)
622
+
623
+ Node and Electron Main/utility processes can use `ContentKeyring` from `@loro-dev/loro-repo-engine` with `contentKeyringRegistration` from `@loro-dev/loro-repo-client/node`. This wraps the engine's Rust `content-v0` implementation; no separate cryptographic adapter is needed. The engine package README includes a standalone runnable keyring demo. Your application still provisions and securely retains genesis, signer seeds and epoch keys, authenticates device admission, and coordinates their distribution. Browser renderers delegate custody to a trusted Node process.
624
+
625
+ The callback format is constrained: `seal` returns provider `header = Uint8Array.of(3)` for an update batch or `Uint8Array.of(4)` for a snapshot, and `sealed` must be a valid signed `content-v0` frame (XChaCha20-Poly1305 plus Ed25519). Arbitrary ciphertext with a custom JSON header is not accepted. The `header` marker does **not** contain an epoch or signer; those are inside the `sealed` frame. Your adapter must validate the signer and authenticated payload, bind the supplied AAD and logical room identity, and preserve snapshot continuation offsets. Treat parsed metadata as untrusted until verification succeeds.
626
+
627
+ For local-first plaintext storage with end-to-end encrypted cloud replication, register `seal`/`open` reverse-IPC handlers per process with **explicit concrete writer IDs**:
628
+
629
+ ```ts
630
+ import { ContentKeyring } from "@loro-dev/loro-repo-engine";
631
+ import { contentKeyringRegistration } from "@loro-dev/loro-repo-client/node";
632
+
633
+ const keyring = new ContentKeyring();
634
+ keyring.configureNamespace(ns, genesis);
635
+ const publicKey = keyring.configureWriterSigner(ns, "member:alice", signerSeed);
636
+ keyring.installEpochKey(ns, epoch, epochKey);
637
+ await client.registerProtector(contentKeyringRegistration(keyring, {
638
+ domains: [ns],
639
+ writers: ["member:alice"],
640
+ priority: 200,
641
+ }));
642
+ ```
643
+
644
+ Here `client` is connected, `ns` is the namespace, and `genesis`, `signerSeed`, and `epochKey` are application-provisioned 32-byte `Uint8Array`s. `epoch` is an integer in `[0, 4294967295]`; the highest installed epoch is used to seal. Clear mutable seed/key buffers after installation. A peer needs matching genesis/epoch keys and `keyring.admitWriterPubkey(ns, publicKey)` for every authenticated sender. The keyring retains old epoch keys for history; reinstalling an epoch with different material fails. `clearNamespace(ns)` drops custody and admission. A restarted process must restore them before syncing; connection reconnect reuses the same keyring object.
645
+
646
+ The adapter converts native failures into sanitized `ProtectError("unknown_key", ...)`, `ProtectError("unauthorized", ...)`, `ProtectError("missing_provider", ...)`, or `ProtectError("invalid_frame", ...)`. A custom protector must preserve these classifications too. On seal, `contextAad` must be incorporated into the protocol's complete additional-data encoding; on open, `additionalData` is already supplied by the engine. Pass requests unchanged to the native keyring. These are not interchangeable byte arrays. For reader-only custody use `{ domains: [ns], readOnly: true }`.
647
+
648
+ - Meanwhile, an Agent worker process connects to the same engine and registers `{ domains: [ns], writers: ["agent:bot-1"], seal, open }`.
649
+ - **Failure Isolation**:
650
+ - If `agent:bot-1` disconnects while its outbox row is unsealed, **`member:alice` writes still seal and sync normally**. Only the agent's queued row shows in `getRemoteStatus` (`health: "protection_blocked"`, `blockedRooms: [{ room, direction: "seal", writer: "agent:bot-1", kind: "missing_provider" }]`).
651
+ - If `open` throws `ProtectError("unknown_key" | "unauthorized" | ...)`, the engine **holds ONLY that room's stream checkpoint** without advancing or dropping frames, while **sibling rooms continue syncing**! Once you admit the device / install the epoch key and call `syncNamespace`, recovery resumes cleanly from the exact held offset.
652
+
653
+ ### Epoch Key Rotation (`paused: true` Drain)
654
+
655
+ Use the remote pause/drain mechanism when coordinating an epoch change:
656
+
657
+ ```ts
658
+ // 1. Pause remote: uploads any ALREADY-sealed rows, holds unsealed rows, pauses pull + ephemeral links
659
+ await client.configureRemote(ns, { ...remoteConfig, paused: true });
660
+
661
+ await client.syncNamespace(ns, remoteConfig.remote_id);
662
+ const [status] = await client.getRemoteStatus(ns, remoteConfig.remote_id);
663
+ if (status.sealedOutbox !== 0 || status.blockedRooms.length !== 0) {
664
+ throw new Error("Resolve drain failures before rotating; leave remote paused");
665
+ }
666
+
667
+ keyring.installEpochKey(ns, nextEpoch, nextEpochKey);
668
+ ```
669
+
670
+ The paused `syncNamespace` waits behind the namespace sync lock, including any in-flight seal callback. A seal completing after pause is discarded. At this point, install the new epoch in **every** reader/writer process and wait for application-level installation acknowledgements from all participants. If any process is unavailable or an acknowledgement is missing, keep the remote paused. Serialize remote configuration changes so another process cannot resume it early. Only after all acknowledgements:
671
+
672
+ ```ts
673
+ await client.configureRemote(ns, { ...remoteConfig, paused: false });
674
+ await client.syncNamespace(ns, remoteConfig.remote_id);
675
+ ```
676
+
677
+ Pausing holds unsealed rows and allows already-sealed rows to upload; it does not revoke ciphertext already produced with an old key. Repeat the pause/drain barrier for every affected remote before changing shared namespace custody. Key distribution, acknowledgements and crash recovery belong to the application; the engine does not provide an automatic distributed coordinator. Retain old epoch keys for historical frames and presealed retries.
678
+
679
+ ---
680
+
681
+ ## 12. Ephemeral Presence Channels (`presence`, `machine-monitor`)
682
+
683
+ Ephemeral channels bypass CRDT SQLite persistence and prioritize low-latency UI responsiveness (outbound `"presence"` frames automatically take wire priority over `"machine-monitor"` and large document `SubPatch` traffic):
684
+
685
+ ```ts
686
+ // Subscribe to all partitions (local + remote peers)
687
+ const sub = await client.ephemeralSubscribe(ns, META_ROOM, "presence", (entries) => {
688
+ console.log("all entries:", entries);
689
+ console.log("merged state:", sub.merged()); // Remote entries sorted by remoteId, local wins last
690
+ console.log("local only:", sub.local());
691
+ });
692
+
693
+ // Publish ephemeral key
694
+ await client.ephemeralSet(ns, META_ROOM, "presence", `cursor:${clientId}`, { x: 120, y: 40 }, {
695
+ connectionBound: true, // Automatically deleted by engine when THIS IPC client disconnects!
696
+ ttlMs: 10_000, // Expires after 10s if not refreshed
697
+ });
698
+
699
+ // Point-in-time read
700
+ const snapshot = await client.ephemeralRead(ns, META_ROOM, "presence");
701
+
702
+ // Explicit delete (`value: null`)
703
+ await client.ephemeralSet(ns, META_ROOM, "presence", `cursor:${clientId}`, null);
704
+ ```
705
+
706
+ ---
707
+
708
+ ## 13. Quiet v1 -> v2 Storage Migration (`importRoomState` & `setStreamCheckpoint`)
709
+
710
+ When migrating existing workspaces without re-uploading old cloud history or re-bootstrapping synced streams:
711
+
712
+ 1. Create each room with its `docSchema` (`getLodyDocSchemaForId(id)`), **before** calling `configureRemote`:
713
+ ```ts
714
+ await client.createRoom(ns, sessionRoom, "encrypted", { docSchema: getLodyDocSchemaForId(sessionRoom.id) });
715
+ await client.createRoom(ns, srRoom, "encrypted");
716
+ await client.createRoom(ns, META_ROOM, "encrypted");
717
+ ```
718
+ 2. Import snapshot + pending incremental bytes:
719
+ - **Clean / already-synced rooms (`enqueueOutbox: false`)**: Loads state locally with `synced` origin — zero outbox rows queued!
720
+ - **Dirty / offline-edited rooms (`enqueueOutbox: true, writer`)**: Imports local edits AND queues an outbox row under `writer` so unsynced local work uploads once remote connects.
721
+ ```ts
722
+ await client.importRoomState(ns, sessionRoom, {
723
+ snapshot: oldDocSnapshotBytes,
724
+ updates: oldDocUpdateDeltas, // optional ordered updates
725
+ enqueueOutbox: false,
726
+ });
727
+ await client.importRoomState(ns, srRoom, {
728
+ snapshot: oldFlock.exportFile(), // v2 Flock binary file bytes
729
+ updates: [new TextEncoder().encode(JSON.stringify(oldFlock.exportJson(sinceVersion)))],
730
+ enqueueOutbox: false,
731
+ });
732
+ await client.importRoomState(ns, dirtyRoom, {
733
+ snapshot: dirtyDocSnapshotBytes,
734
+ enqueueOutbox: true,
735
+ writer: "member:alice",
736
+ });
737
+ ```
738
+ 3. Seed saved Durable Streams offsets so sync resumes incrementally instead of hitting `/bootstrap`:
739
+ ```ts
740
+ await client.setStreamCheckpoint(ns, "workspace", sessionRoom, savedSessionOffset);
741
+ await client.setStreamCheckpoint(ns, "workspace", srRoom, savedSrOffset);
742
+ await client.setStreamCheckpoint(ns, "workspace", META_ROOM, savedMetaOffset);
743
+ ```
744
+ 4. Finally call `await client.configureRemote(ns, workspaceRemote)` and `await client.syncNamespace(ns, "workspace")`.
745
+
746
+ ---
747
+
748
+ ## 14. Complete Error Codes & Remote Health Reference
749
+
750
+ ### Wire RPC Error Codes (`RepoRpcError.code: RepoRpcErrorCode`)
751
+
752
+ | `error.code` | Thrown When & Recommended Handling |
753
+ | :--- | :--- |
754
+ | **`"room_not_found"`** | `readDoc`, `applyDocPatch`, `subscribeDoc`, `flock*`, etc. called on an uncreated room (`ensureRoom` / `createRoom` first). |
755
+ | **`"encryption_policy_mismatch"`** | Attempting to re-create or re-configure an existing room with a different `EncryptionPolicy` (`"plaintext"` vs `"encrypted"`), which is immutable at birth. |
756
+ | **`"protection_blocked"`** | Explicit operation rejected because required E2EE protector key/signer is unavailable. |
757
+ | **`"crypto_auth_failed"`** | Corrupted ciphertext, invalid Ed25519 signature, or tampered AAD (`aadDomain` mismatch). |
758
+ | **`"invalid_patch"`** | Malformed `JsonPatch`, out-of-bounds array index, bad path segment, invalid UTF-16 surrogate split, or DocSchema type mismatch. |
759
+ | **`"invalid_query"`** | Malformed subpath, `flockScan` bounds/prefix, or Roost query argument. |
760
+ | **`"precondition_failed"`** | Optimistic `cas` `expected_room_tx_id` mismatch or incompatible/compacted `rebase` `base_room_tx_id`. Retry via `transactCas`. |
761
+ | **`"storage"`** | SQLite I/O error or schema version mismatch (`v2_meta.schema_version !== 1`). |
762
+ | **`"protocol"`** | Frame size `> MAX_FRAME_BYTES` (`64 MiB`), invalid wire envelope, zstd decompression overflow/corruption, or protocol violation. |
763
+ | **`"unsupported"`** | Operation invalid for that `RoomKind` (e.g., `readDoc` on `"flock"`, `rebase` precondition on `"flock"`). |
764
+ | **`"budget_exceeded"`** | Engine resource or queue budget exceeded. |
765
+
766
+ *(Client-side host helpers in `@loro-dev/loro-repo-client/node` can also throw `Error`s prefixed with `ENGINE_BUSY` or `ENGINE_PROTOCOL_MISMATCH`.)*
767
+
768
+ ### Protector Failure Kinds (`ProtectError.kind: ProtectFailureKind`)
769
+
770
+ | `kind` | Meaning |
771
+ | :--- | :--- |
772
+ | **`"missing_provider"`** | No connected `RepoClient` registered a protector covering `(namespace, writer)`. |
773
+ | **`"unknown_key"`** | Required `EpochKey` (epoch number in frame header) is missing from the local keyring. |
774
+ | **`"unauthorized"`** | Frame signer's Ed25519 public key is not admitted in the keyring's authorized writers ledger. |
775
+ | **`"invalid_frame"`** | Malformed envelope, invalid header/MAC/signature (mapped automatically from arbitrary uncaught errors thrown inside `seal`/`open`). |
776
+
777
+ ### Remote Health States (`RemoteStatus.health: RemoteHealthState`)
778
+
779
+ Monitor live via `getRemoteStatus(ns, remoteId?)` or `subscribeRemoteStatus(ns, cb, remoteId?)`:
780
+
781
+ | `health` | Meaning |
782
+ | :--- | :--- |
783
+ | **`"idle"`** | Configured remote with no active sync work running or pending errors. |
784
+ | **`"catching_up"`** | Actively pushing outbox frames and/or catching up from Durable Streams. |
785
+ | **`"current"`** | Outbox drained (`pendingOutbox === 0`), no blocked rooms, caught up with live stream head. |
786
+ | **`"paused"`** | `remote.paused === true` (e.g. during epoch key rotation). |
787
+ | **`"auth_required"`** | Remote returned `401` and no valid token could be obtained from static config or `registerAuthProvider`. |
788
+ | **`"write_denied"`** | Server returned `403` / permanent write rejection (check `lastError` and ACLs). |
789
+ | **`"protection_blocked"`** | One or more rooms held due to E2EE failure — inspect `status.blockedRooms` (`direction`, `writer`, `kind`, `openFailures`). |
790
+ | **`"retrying"`** | Transient network / `5xx` error backing off automatically before retry. |
791
+
792
+ ---
793
+
794
+ ## 15. Lody Integration FAQ & Common Pitfalls
795
+
796
+ 1. **Q: Do I need `loro-crdt` WASM in Electron Main or Electron Renderer?**
797
+ **No.** All CRDT execution happens natively in Rust (`@loro-dev/loro-repo-engine`). Electron Main & Renderer only need `@loro-dev/loro-repo-client` and `@loro-dev/json-patch`.
798
+ 2. **Q: Why MUST `docSchema` be passed on `session-*`, `schedule-*`, `preview-comment-*`, and `shortcut-body:*`?**
799
+ Without `docSchema`, scalar strings (`session.id`, `mq[*].task`, `history[*].role`) or arbitrary JSON configs could become CRDT containers instead of matching `loro-mirror` / mobile / CLI readers (`map.get("id") === "..."`). Always pass `getLodyDocSchemaForId(room.id)`.
800
+ 3. **Q: Is `"$cid"` persisted inside Loro containers?**
801
+ **No.** `"$cid"` is synthesized dynamically during JSON projection/diffing on `cidPatterns` (e.g. `[["mq", "*"]]`) and stripped before writing to `LoroDoc`. Edit items via field-level `set` (`["mq", 0, "task"]`) rather than whole-element replacement (`["mq", 0]`) to keep `$cid` stable.
802
+ 4. **Q: How should named Flock rooms (`sr`, `wf:workspace`, `mf:*`, `fi:*`, `fis:*`) be named?**
803
+ Use canonical prefixed IDs like `{ kind: "flock", id: `${wsId}:sr` }` and `{ kind: "flock", id: `${wsId}:fi:${machineId}` }`. `createLodyWorkspaceRoutes(wsId)` preserves canonical `{id}` names (and also maps legacy unprefixed names like `"scheduleRegistry"` or `"fi:*"`) so `streamId` and LSCE AAD logical identity match cleanly.
804
+ 5. **Q: Why should `aadDomain` be set explicitly on `RemoteConfig`?**
805
+ If your local SQLite `namespace` (e.g. local test ID or folder slug) differs from Lody's E2EE domain `"lody-e2ee:<genesisHex>"`, setting `aadDomain` ensures `LSCE v2` `streams-room-aad` validates consistently across devices regardless of local SQLite naming.
806
+ 6. **Q: Why did `subscribeDoc` not fire when I edited a path, OR why did `whenVisible(ack.txId)` resolve without firing the listener?**
807
+ If your mutation touched `["session"]` while subscribed to `["mq"]`, the Rust engine suppresses redundant `sub_patch` frames for `["mq"]` and instead emits a `Watermark(ack.txId)` frame — advancing `sub.lastTxId` so `whenVisible(ack.txId)` can resolve without a listener call. This assumes a live connection and an acknowledgement from the same namespace and engine session; it is not a timeout or cloud replication guarantee.
808
+ 7. **Q: Why aren't my local edits synced to a secondary remote (like `shortcut:1`), or why did `shortcut-1` skip `workspace`?**
809
+ Check your `StreamRouteRule` order — first matching rule wins. `skip: true` prevents outbox rows from being enqueued for that remote.
810
+ 8. **Q: Why does a new host start require calling `registerAuthProvider` again?**
811
+ Bearer tokens never touch disk (`v2_remotes` never stores `auth_token`). However, within the same `RepoClient` instance, automatic reconnection (`autoReconnect` / `reconnectWith`) replays `registerAuthProvider` and `registerProtector` automatically!
812
+ 9. **Q: What happens if a `subscribeDoc` listener receives updates while offline and then remote catches up?**
813
+ Local mutations emit `info.origin = "local"`. Remote pulls emit `info.origin = "remote"`, and if batched with other changes before socket flush, `"remote"` is sticky so remote-arrival hooks (`onRemoteUpdate`) always trigger.
814
+ 10. **Q: Can two processes run both `loro-repo` and Lody Stable/Nightly against one `<dataDir>`?**
815
+ Yes — via `ensureEngineHost`, the first process acquires `files.lock`, subsequent processes detect `ENGINE_BUSY`, check `protocolVersion === 2`, and connect over the private socket. If they share mismatched major protocol versions, `ENGINE_PROTOCOL_MISMATCH` fails loudly before touching data.