@doubling/compound-sync 1.10.4 → 1.11.1

package/README.md

@@ -14,6 +14,16 @@ That's it. A browser window will open for sign-in (Google or email/password), th
 
 - [Node.js](https://nodejs.org/) (v18 or later)
 
+### TLS certificates
+
+On Node 22+ the daemon auto-detects the OS system certificate store (`/etc/ssl/cert.pem` on macOS, `/etc/ssl/certs/ca-certificates.crt` or `/etc/pki/tls/certs/ca-bundle.crt` on Linux) and re-execs itself with `NODE_EXTRA_CA_CERTS` set; otherwise `fetch()` to Google Identity / Firebase Auth endpoints fails with `auth/network-request-failed` because Node's bundled CA store doesn't match what those services use.
+
+If you're behind a corporate proxy with custom roots, set `NODE_EXTRA_CA_CERTS` explicitly to your bundle and the daemon will use that instead:
+
+```bash
+NODE_EXTRA_CA_CERTS=/path/to/corporate-bundle.pem npx @doubling/compound-sync
+```
+
 ## What it does
 
 Compound Sync watches a local folder and your Compound workspace simultaneously. Changes in either direction are synced automatically:
@@ -95,6 +105,19 @@ npm run test:integration
 npm test
 ```
 
+### TypeScript conventions (DOU-181)
+
+`sync/` is being migrated to TypeScript file-by-file. The conventions:
+
+- **Source layout: in-place.** Each `.ts` file emits `.js`, `.d.ts`, and source maps as siblings via `tsc` with `outDir: "."`. The emitted `.js` is a gitignored build artifact, never edited by hand; the `.ts` is the source.
+- **Imports always use the `.js` extension** (NodeNext convention). At runtime: in dev/test the `tsx` loader maps `./paths.js` to `./paths.ts` so source runs without a build step; in production the compiled `paths.js` exists alongside and resolves directly.
+- **Dev (no build needed):** `npm run sync` runs through `node --import tsx`, so `.ts` files load on demand.
+- **CI / publish:** `npm run build` compiles every `.ts` source to its `.js` sibling. `prepack` runs build automatically before `npm publish` so the npm tarball ships compiled JS. The desktop staging script also runs `npm run -w sync build` before copying.
+- **Typecheck:** `npm run typecheck` (alias for `tsc --noEmit`) at the workspace level, or at repo root `npm run typecheck` which runs web + sync together.
+- **Strictness:** `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`. No `any`. No `// @ts-ignore`. If a third-party module lacks types, declare its shape in a `.d.ts` or PR types upstream.
+
+Phase 1 migrated `paths.js` to `paths.ts` as proof of pattern. Phase 3 ([[DOU-183]]) migrates the remaining source files; everything in `sync/` will be `.ts` by the end.
+
 ### Publishing to npm
 
 After making changes to the sync daemon, publish a new version:

package/files.js

@@ -291,13 +291,6 @@ export async function pushFileToCloud({
   mimeType,
   now = new Date().toISOString(),
   localModifiedAt = null,
-  // The contentHash this caller saw as "current" when it last pulled.
-  // If the existing remote doc has a different contentHash, another
-  // writer landed an edit in the meantime; we refuse to overwrite and
-  // return action='conflict' so the caller can write a conflict copy
-  // and pull the new remote state. Undefined disables the check (used
-  // for create-from-nothing where no baseline exists).
-  expectedRemoteHash = undefined,
 }) {
   if (scope === 'shared-with-me' || scope === 'shared-by-me') {
     return { action: 'skipped', reason: 'shared-scope' };
@@ -379,23 +372,6 @@ export async function pushFileToCloud({
       && (existing.parentId == null ? null : existing.parentId) === parentId) {
     return { action: 'noop', fileId: docSnap.id };
   }
-  // Compare-and-swap (DOU-167): if the caller passed a baseline of
-  // what they last saw as current, refuse the push when the remote
-  // has moved on. The daemon will write the proposed local content
-  // to a sibling conflict file and pull the new remote state into
-  // the live path. Without this guard, a stale push silently
-  // overwrites another user's freshly-saved edits (data loss).
-  if (
-    expectedRemoteHash !== undefined &&
-    existing.contentHash !== expectedRemoteHash
-  ) {
-    return {
-      action: 'conflict',
-      fileId: docSnap.id,
-      remoteHash: existing.contentHash,
-      remoteData: { id: docSnap.id, ...existing },
-    };
-  }
   // Last-write-wins: never let an older local file overwrite a newer
   // server edit. The caller (sync daemon) passes the local file's mtime;
   // if the server doc was updated more recently, leave it for the

package/org-sync.js

@@ -37,6 +37,11 @@ import {
 } from './paths.js';
 import { TeamRegistry } from './team-registry.js';
 import { loadSyncState, saveSyncState } from './sync-state.js';
+import { FirestoreUpdateStore } from './yjs-firestore-update-store.js';
+import { YjsFileBinding } from './yjs-file-binding.js';
+import {
+  loadBindingState, saveBindingState, deleteBindingState,
+} from './yjs-binding-state.js';
 
 const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 
@@ -106,6 +111,122 @@ export async function startOrgSync({
   function setBaseline(key, hash) { lastSyncedHash.set(key, hash); persistBaseline(); }
   function deleteBaseline(key) { lastSyncedHash.delete(key); persistBaseline(); }
   const suppressLocal = new Set();
+
+  // Per-file Yjs bindings, created on first sight of a text file
+  // (DOU-178 PR 3). The binding owns the live Y.Doc that mirrors
+  // orgs/.../yupdates and the debounced disk flush. We keep two
+  // indexes: by fileId (so handleFirestoreChange can dispose on
+  // 'removed' and re-use across events) and by local path (so the
+  // chokidar handler can route disk edits into the binding without
+  // re-resolving the fileId).
+  const bindings = new Map();
+  const bindingsByPath = new Map();
+
+  // DOU-205: per-fileId record of the most recently observed Firestore
+  // metadata (local path + tracking key). Used to detect renames /
+  // moves on subsequent 'modified' snapshot events: when the file
+  // doc's path changes server-side (via the web rename UI), the local
+  // path computed from the new data also changes, and this map lets
+  // the handler relocate the local file in place (fs.renameSync,
+  // which preserves Obsidian's inode-level tracking) rather than
+  // leaving the old file orphaned at its previous location.
+  const knownPaths = new Map();
+
+  // Track which fileIds already have a binding (or one being set
+  // up) so we never double-create. `stoppedRef` is read by the
+  // background retry loops so they can abandon work after sync.stop.
+  // `pendingPromises` lets stop() await any in-flight setup before
+  // returning so the next test's clearFirestore does not race
+  // dangling onSnapshot streams.
+  const pendingBindings = new Set();
+  const pendingPromises = new Set();
+  const stoppedRef = { value: false };
+
+  // Fire-and-forget binding setup. Returns nothing because the
+  // common shape "ensureBinding then read its ytext" runs straight
+  // into a race: the daemon's onSnapshot fires on Alice's own
+  // optimistic write before the file doc is server-committed, and
+  // the Firestore rules engine evaluates the yupdates/yjs nested
+  // rule via a server-side get() against the parent files/{id}
+  // doc. That get() sees no doc and returns null, so binding.start
+  // fails with permission-denied; the right behavior is to retry
+  // until the commit propagates, not to block handleFirestoreChange
+  // for seconds. Callers fall back to the blob path while the
+  // binding is still being set up; once it lands in
+  // bindings/bindingsByPath, subsequent events take the Yjs path.
+  function ensureBinding(fileId, localFilePath) {
+    if (bindings.has(fileId) || pendingBindings.has(fileId)) return;
+    pendingBindings.add(fileId);
+    const onDiskWrite = (text) => {
+      suppressLocal.add(localFilePath);
+      ensureDir(localFilePath);
+      fs.writeFileSync(localFilePath, text, 'utf-8');
+      setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+    };
+    // DOU-209: persist the Y.Doc binary state after every stable
+    // change so the next daemon restart has the right baseline to
+    // merge offline disk edits without losing offline web edits.
+    const onDocStateChange = (encoded) => saveBindingState(LOCAL_PATH, fileId, encoded);
+    // DOU-209: feed the binding's startup-merge with the daemon's
+    // last view (initialDocState) and the current disk content. If
+    // they diverge, the binding applies the diff as Yjs ops so disk-
+    // side offline edits survive the cloud-side replay.
+    const initialDocState = loadBindingState(LOCAL_PATH, fileId);
+    let currentDiskText = null;
+    try {
+      if (fs.existsSync(localFilePath)) {
+        currentDiskText = fs.readFileSync(localFilePath, 'utf-8');
+      }
+    } catch (err) {
+      console.error(`  [${orgId}] could not read ${localFilePath} for binding setup: ${err && err.message}`);
+    }
+    const setupPromise = (async () => {
+      // Retry binding.start on permission-denied. See note above
+      // about the optimistic-write race with the nested-rule get().
+      // YjsProvider rejects double-start, so each retry needs a
+      // fresh binding (and a fresh provider underneath it).
+      for (let attempt = 0; attempt < 8; attempt++) {
+        if (stoppedRef.value) return;
+        const store = new FirestoreUpdateStore(db, orgId, fileId);
+        const binding = new YjsFileBinding(store, {
+          onDiskWrite, onDocStateChange, initialDocState, currentDiskText,
+        });
+        try {
+          await binding.start();
+          if (stoppedRef.value) {
+            await binding.stop().catch(() => {});
+            return;
+          }
+          bindings.set(fileId, binding);
+          bindingsByPath.set(localFilePath, binding);
+          return;
+        } catch (err) {
+          if (stoppedRef.value) return;
+          if (err?.code !== 'permission-denied' || attempt === 7) {
+            console.error(`  [${orgId}] Yjs binding setup failed for ${fileId}: ${err && err.message}`);
+            return;
+          }
+          await new Promise((r) => setTimeout(r, 150 * (attempt + 1)));
+        }
+      }
+    })().finally(() => {
+      pendingBindings.delete(fileId);
+      pendingPromises.delete(setupPromise);
+    });
+    pendingPromises.add(setupPromise);
+  }
+
+  async function disposeBinding(fileId, localFilePath) {
+    const binding = bindings.get(fileId);
+    if (!binding) return;
+    bindings.delete(fileId);
+    if (localFilePath) bindingsByPath.delete(localFilePath);
+    await binding.stop();
+    // DOU-209: drop the per-file Y.Doc state so deleted files don't
+    // accumulate stale binding-state blobs under .compound-yjs-binding/.
+    deleteBindingState(LOCAL_PATH, fileId);
+  }
+
   // Per-team Firestore-listener unsubscribe handles, keyed by teamId.
   const teamUnsubscribers = new Map();
   // Hoisted forward-decl: setupTeam closes over handleFirestoreChange,
@@ -188,6 +309,48 @@ export async function startOrgSync({
     const trackingKey = `${data.scope || 'team'}:${docPath}`;
     const isFolder = data.type === 'folder';
 
+    // DOU-205: rename / move detection. On a 'modified' snapshot for
+    // a fileId we've seen before, if the computed local path differs
+    // from what we last recorded, the server's path field has
+    // changed. Move the local file in place (fs.renameSync preserves
+    // Obsidian's inode tracking so notes don't lose their metadata,
+    // backlinks, or recent-files entries) and migrate the tracking
+    // maps from the old key to the new. We do this before the
+    // freshness check below because the rename happens irrespective
+    // of whether the content changed in the same update.
+    const fileId = change.doc.id;
+    const prevKnown = knownPaths.get(fileId);
+    if (change.type === 'modified' && prevKnown && prevKnown.localPath !== localFilePath) {
+      suppressLocal.add(prevKnown.localPath);
+      suppressLocal.add(localFilePath);
+      try {
+        if (fs.existsSync(prevKnown.localPath)) {
+          ensureDir(localFilePath);
+          fs.renameSync(prevKnown.localPath, localFilePath);
+          console.log(`  [${orgId}] [firestore → local] RENAME ${prevKnown.localPath} -> ${localFilePath}`);
+        }
+      } catch (err) {
+        console.error(`  [${orgId}] [firestore → local] RENAME failed: ${err && err.message}`);
+      }
+      if (lastKnownUpdate.has(prevKnown.trackingKey)) {
+        lastKnownUpdate.set(trackingKey, lastKnownUpdate.get(prevKnown.trackingKey));
+        lastKnownUpdate.delete(prevKnown.trackingKey);
+      }
+      if (lastSyncedHash.has(prevKnown.trackingKey)) {
+        setBaseline(trackingKey, lastSyncedHash.get(prevKnown.trackingKey));
+        deleteBaseline(prevKnown.trackingKey);
+      }
+      const binding = bindings.get(fileId);
+      if (binding && bindingsByPath.get(prevKnown.localPath) === binding) {
+        bindingsByPath.delete(prevKnown.localPath);
+        bindingsByPath.set(localFilePath, binding);
+      }
+      setTimeout(() => {
+        suppressLocal.delete(prevKnown.localPath);
+        suppressLocal.delete(localFilePath);
+      }, 1000);
+    }
+
     if (change.type === 'removed') {
       if (isFolder) {
         // Best-effort directory removal. The daemon's own file-delete
@@ -213,9 +376,27 @@ export async function startOrgSync({
       }
       lastKnownUpdate.delete(trackingKey);
       deleteBaseline(trackingKey);
+      knownPaths.delete(fileId);
+      await disposeBinding(change.doc.id, localFilePath);
       return;
     }
 
+    // Record (or refresh) the per-fileId path so the next 'modified'
+    // event can detect a rename / move by comparing against this.
+    knownPaths.set(fileId, { localPath: localFilePath, trackingKey });
+
+    // Kick off Yjs binding setup for text files. Fire-and-forget so
+    // a slow start (retrying past the rules-engine race on a fresh
+    // doc) does not stall the legacy blob pull. Once the binding is
+    // registered, future events take the Yjs path; until then the
+    // blob path still keeps disk in sync.
+    if (!isFolder) {
+      const ext = extFromPath(docPath);
+      const extDerivedMime = mimeTypeFromExt(ext);
+      const isText = isTextMimeType(data.mimeType) || isTextMimeType(extDerivedMime);
+      if (isText) ensureBinding(change.doc.id, localFilePath);
+    }
+
     const remoteUpdated = data.updatedAt || data.createdAt || '';
     const lastKnown = lastKnownUpdate.get(trackingKey);
     if (lastKnown && lastKnown >= remoteUpdated) return;
@@ -282,6 +463,23 @@ export async function startOrgSync({
     // markers) can apply.
     const extDerivedMime = mimeTypeFromExt(ext);
     const isText = isTextMimeType(data.mimeType) || isTextMimeType(extDerivedMime);
+
+    // Yjs path (DOU-178 PR 3): if a binding for this file is already
+    // up and carries non-empty ytext, the debounced flush owns the
+    // disk write and the legacy blob pull is skipped. Bindings that
+    // are still being set up, or that loaded empty ytext (pre-Yjs
+    // files), fall through to the blob path; PR 4 retires the blob
+    // path entirely.
+    if (isText) {
+      const binding = bindings.get(change.doc.id);
+      if (binding && binding.ytext.length > 0) {
+        lastKnownUpdate.set(trackingKey, remoteUpdated);
+        setBaseline(trackingKey, data.contentHash);
+        setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+        return;
+      }
+    }
+
     // Storage rules require the Firestore doc to exist before they
     // authorize a blob upload, so writers must create the doc first
     // and upload second. That leaves a window where the metadata is
@@ -425,12 +623,6 @@ export async function startOrgSync({
     // duplicate doc). Pre-setting it suppresses the echo.
     lastKnownUpdate.set(trackingKey, now);
 
-    // Baseline = what we last saw as the remote contentHash for this
-    // path. pushFileToCloud uses it as a compare-and-swap precondition
-    // (DOU-167): if the remote has moved past this baseline, refuse
-    // the push and surface the conflict to the caller.
-    const baseline = lastSyncedHash.get(trackingKey);
-
     const result = await pushFileToCloud({
       filesRef,
       storage,
@@ -443,7 +635,6 @@ export async function startOrgSync({
       mimeType,
       now,
       localModifiedAt,
-      expectedRemoteHash: baseline,
     });
 
     // Record the synced content baseline whenever local matches the
@@ -456,21 +647,6 @@ export async function startOrgSync({
       // its firestore -> local snapshot is allowed through to update the
       // local file.
       lastKnownUpdate.delete(trackingKey);
-    } else if (result.action === 'conflict') {
-      // Another writer landed an edit in the gap between our last sync
-      // and this push. Preserve the user's would-be push as a sibling
-      // conflict copy, pull the new remote state into the live file,
-      // and advance the baseline so the next push (or further edits)
-      // can proceed against the new ground truth.
-      const conflictPath = writeConflictCopy(filePath, data);
-      await pullRemoteIntoLocal(result.remoteData, filePath);
-      setBaseline(trackingKey, result.remoteHash);
-      lastKnownUpdate.delete(trackingKey);
-      console.log(
-        `  [${orgId}] [local → firestore] CONFLICT ${docPath}: ` +
-        `remote changed; local saved to ${path.basename(conflictPath)}`,
-      );
-      return;
     }
 
     if (result.action === 'created') {
@@ -485,38 +661,6 @@ export async function startOrgSync({
     }
   }
 
-  /** Write the proposed (rejected) push to a sibling conflict file.
-   * Returns the new path. Suppresses chokidar so the conflict file's
-   * creation doesn't trigger its own push. */
-  function writeConflictCopy(filePath, data) {
-    const parsed = path.parse(filePath);
-    const ts = new Date().toISOString().replace(/[:.]/g, '-');
-    const conflictPath = path.join(parsed.dir, `${parsed.name}.conflict-${ts}${parsed.ext}`);
-    suppressLocal.add(conflictPath);
-    fs.writeFileSync(conflictPath, data);
-    setTimeout(() => suppressLocal.delete(conflictPath), 1000);
-    return conflictPath;
-  }
-
-  /** Pull the remote blob into the live local path after a conflict.
-   * Uses suppressLocal so chokidar doesn't re-emit the write. */
-  async function pullRemoteIntoLocal(remoteData, localFilePath) {
-    const ext = extFromPath(remoteData.path);
-    const extDerivedMime = mimeTypeFromExt(ext);
-    const isText = isTextMimeType(remoteData.mimeType) || isTextMimeType(extDerivedMime);
-    suppressLocal.add(localFilePath);
-    const blobReadArgs = { storage, orgId, fileId: remoteData.id, ext };
-    const retryOpts = { expectedHash: remoteData.contentHash };
-    if (isText) {
-      const content = await readBlobWithRetry(() => readBlobAsText(blobReadArgs), retryOpts);
-      fs.writeFileSync(localFilePath, content || '', 'utf-8');
-    } else {
-      const bytes = await readBlobWithRetry(() => readBlob(blobReadArgs), retryOpts);
-      fs.writeFileSync(localFilePath, bytes);
-    }
-    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-  }
-
   async function deleteFromFirestore(filePath) {
     const { scope, teamId, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
     const trackingKey = `${scope}:${docPath}`;
@@ -623,8 +767,21 @@ export async function startOrgSync({
       ? fs.readFileSync(filePath, 'utf-8')
       : fs.readFileSync(filePath);
     const localModifiedAt = stat.mtime.toISOString();
+
+    // Yjs path (DOU-178 PR 3): route text edits into the binding so
+    // the disk delta is published as a yupdate (preserving concurrent
+    // web edits via fast-diff). The binding only exists once the
+    // Firestore listener has seen the file; for the very first
+    // local-only save the binding hasn't been created yet, and the
+    // blob path is still the only writer. Subsequent saves go through
+    // both paths until PR 4 retires the blob upload.
+    if (isTextMimeType(mimeType)) {
+      const binding = bindingsByPath.get(filePath);
+      if (binding) binding.applyDiskText(data);
+    }
+
     pushToFirestore(filePath, data, mimeType, localModifiedAt).catch(err =>
-      console.error(`  [${orgId}] Push error: ${err.message}`)
+      console.error(`  [${orgId}] Push error for ${rel}: ${err.message}`)
     );
   }
 
@@ -671,7 +828,8 @@ export async function startOrgSync({
     watcher.on('change', filePath => handleLocalChange(filePath));
     watcher.on('unlink', filePath => {
       if (suppressLocal.has(filePath)) return;
-      deleteFromFirestore(filePath).catch(err => console.error(`  [${orgId}] Delete error: ${err.message}`));
+      const rel = path.relative(LOCAL_PATH, filePath);
+      deleteFromFirestore(filePath).catch(err => console.error(`  [${orgId}] Delete error for ${rel}: ${err.message}`));
     });
     watcher.on('addDir', dirPath => handleLocalDirAdded(dirPath));
     watcher.on('unlinkDir', dirPath => handleLocalDirRemoved(dirPath));
@@ -697,6 +855,7 @@ export async function startOrgSync({
     // Tear down all listeners and the watcher. Returns the watcher's
     // close() promise so callers/tests can await full shutdown.
     stop() {
+      stoppedRef.value = true;
       for (const unsub of unsubscribers) {
         try { unsub(); } catch (e) { /* ignore */ }
       }
@@ -704,7 +863,15 @@ export async function startOrgSync({
         try { unsub(); } catch (e) { /* ignore */ }
       }
       teamUnsubscribers.clear();
-      return watcher ? watcher.close() : Promise.resolve();
+      const setupDrain = Promise.all([...pendingPromises]);
+      const bindingDrain = setupDrain.then(() => Promise.all(
+        [...bindings.values()].map((b) => b.stop().catch(() => {})),
+      )).then(() => {
+        bindings.clear();
+        bindingsByPath.clear();
+      });
+      const watcherClose = watcher ? watcher.close() : Promise.resolve();
+      return Promise.all([bindingDrain, watcherClose]).then(() => undefined);
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubling/compound-sync",
-  "version": "1.10.4",
+  "version": "1.11.1",
   "description": "Bidirectional sync between Compound and local markdown files",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "sync-state.js",
     "config.js",
     "paths.js",
+    "paths.d.ts",
     "files.js",
     "folder-chain.js",
     "storage-helpers.js",
@@ -19,21 +20,33 @@
     "auth-persistence.js",
     "pre-mint-app-check.js",
     "setup-auth-with-pre-mint.js",
+    "yjs-firestore-update-store.js",
+    "yjs-provider.js",
+    "yjs-file-binding.js",
+    "yjs-binding-state.js",
     "README.md"
   ],
   "scripts": {
-    "sync": "node sync.js",
-    "test:unit": "node --test config.test.js paths.test.js storage-helpers.test.js folder-chain.test.js team-registry.test.js auth-persistence.test.js pre-mint-app-check.test.js setup-auth-with-pre-mint.test.js sync-state.test.js",
-    "test:integration": "firebase emulators:exec --only firestore,storage 'node --test --test-concurrency=1 files.test.js org-sync.test.js two-user-sync.test.js'",
+    "sync": "node --import tsx ./sync.js",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "test:unit": "node --import tsx --test config.test.js paths.test.js storage-helpers.test.js folder-chain.test.js team-registry.test.js auth-persistence.test.js pre-mint-app-check.test.js setup-auth-with-pre-mint.test.js sync-state.test.js yjs-file-binding.test.js yjs-binding-state.test.js",
+    "test:integration": "firebase emulators:exec --only firestore,storage 'node --import tsx --test --test-concurrency=1 files.test.js org-sync.test.js two-user-sync.test.js'",
     "test": "npm run test:unit && npm run test:integration"
   },
   "dependencies": {
+    "chokidar": "^5.0.0",
+    "fast-diff": "^1.3.0",
     "firebase": "^12.14.0",
-    "chokidar": "^5.0.0"
+    "yjs": "^13.6.31"
   },
   "devDependencies": {
     "@firebase/rules-unit-testing": "^5.0.1",
-    "firebase-tools": "^15.0.0"
+    "@types/node": "^26.0.0",
+    "firebase-tools": "^15.20.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
   },
   "publishConfig": {
     "access": "public"

package/paths.d.ts

@@ -0,0 +1,12 @@
+export declare const PRIVATE_FOLDER = "Private";
+export declare const SHARED_WITH_ME_FOLDER = "Shared with Me";
+export declare const SHARED_BY_ME_FOLDER = "Shared by Me";
+export type Scope = 'team' | 'private' | 'shared-with-me' | 'shared-by-me';
+export interface ScopedDocPath {
+    scope: Scope;
+    teamId?: string;
+    docPath: string;
+}
+export declare function teamFolderName(teamName: string): string;
+export declare function scopeFromLocalPath(filePath: string, localPath: string, teamIdsByName: Map<string, string>): ScopedDocPath;
+//# sourceMappingURL=paths.d.ts.map

package/paths.js

@@ -5,48 +5,43 @@
 // expected to be swapped if/when authorization moves to a Zanzibar-
 // style relationship model. Keep this module's interface narrow so the
 // swap stays localized.
-
 import path from 'node:path';
-
 export const PRIVATE_FOLDER = 'Private';
 export const SHARED_WITH_ME_FOLDER = 'Shared with Me';
 export const SHARED_BY_ME_FOLDER = 'Shared by Me';
 const TEAMSPACE_SUFFIX = ' Teamspace';
-
 export function teamFolderName(teamName) {
-  return teamName + TEAMSPACE_SUFFIX;
+    return teamName + TEAMSPACE_SUFFIX;
 }
-
 // Given an absolute file path within one of the daemon's local sync
 // roots, return { scope, teamId?, docPath }. The caller passes the
-// matching localPath root and the team-name → team-id map.
+// matching localPath root and the team-name -> team-id map.
 export function scopeFromLocalPath(filePath, localPath, teamIdsByName) {
-  const rel = path.relative(localPath, filePath);
-
-  if (rel.startsWith(PRIVATE_FOLDER + path.sep)) {
-    return {
-      scope: 'private',
-      docPath: rel.slice(PRIVATE_FOLDER.length + 1),
-    };
-  }
-  if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) {
-    return {
-      scope: 'shared-with-me',
-      docPath: rel.slice(SHARED_WITH_ME_FOLDER.length + 1),
-    };
-  }
-  if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) {
-    return {
-      scope: 'shared-by-me',
-      docPath: rel.slice(SHARED_BY_ME_FOLDER.length + 1),
-    };
-  }
-
-  const parts = rel.split(path.sep);
-  const folderName = parts[0];
-  const teamName = folderName.endsWith(TEAMSPACE_SUFFIX)
-    ? folderName.slice(0, -TEAMSPACE_SUFFIX.length)
-    : folderName;
-  const teamId = teamIdsByName.get(teamName);
-  return { scope: 'team', teamId, docPath: parts.slice(1).join('/') };
+    const rel = path.relative(localPath, filePath);
+    if (rel.startsWith(PRIVATE_FOLDER + path.sep)) {
+        return {
+            scope: 'private',
+            docPath: rel.slice(PRIVATE_FOLDER.length + 1),
+        };
+    }
+    if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) {
+        return {
+            scope: 'shared-with-me',
+            docPath: rel.slice(SHARED_WITH_ME_FOLDER.length + 1),
+        };
+    }
+    if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) {
+        return {
+            scope: 'shared-by-me',
+            docPath: rel.slice(SHARED_BY_ME_FOLDER.length + 1),
+        };
+    }
+    const parts = rel.split(path.sep);
+    const folderName = parts[0] ?? '';
+    const teamName = folderName.endsWith(TEAMSPACE_SUFFIX)
+        ? folderName.slice(0, -TEAMSPACE_SUFFIX.length)
+        : folderName;
+    const teamId = teamIdsByName.get(teamName);
+    return { scope: 'team', teamId, docPath: parts.slice(1).join('/') };
 }
+//# sourceMappingURL=paths.js.map

package/storage-helpers.js

@@ -81,6 +81,8 @@ const EXT_TO_MIME = {
   webp: 'image/webp',
   svg: 'image/svg+xml',
   bmp: 'image/bmp',
+  heic: 'image/heic',
+  heif: 'image/heif',
   mp3: 'audio/mpeg',
   wav: 'audio/wav',
   mp4: 'video/mp4',

package/sync.js

@@ -16,6 +16,43 @@
  *        node sync.js --help
  */
 
+// DOU-208: Node 22+ ships its own CA bundle and does not consult the
+// macOS system trust store. Without NODE_EXTRA_CA_CERTS pointing at
+// /etc/ssl/cert.pem, fetch() to securetoken.googleapis.com fails
+// with a bare `fetch failed`, which Firebase Auth then surfaces as
+// auth/network-request-failed. The web e2e harness's run-emulator.js
+// already does this for child processes; here we need it for our own
+// process. NODE_EXTRA_CA_CERTS is read at startup, so setting it on
+// process.env after init is a no-op — instead, re-exec ourselves
+// with the env var set when missing. The child inherits stdio +
+// argv; we exit with its status. No-op when already set (the user
+// or a wrapper explicitly chose a different bundle).
+import { spawnSync as __dou208_spawnSync } from 'node:child_process';
+import { existsSync as __dou208_existsSync } from 'node:fs';
+if (!process.env.NODE_EXTRA_CA_CERTS) {
+  const __dou208_candidates = process.platform === 'darwin'
+    ? ['/etc/ssl/cert.pem']
+    : process.platform === 'linux'
+      ? ['/etc/ssl/certs/ca-certificates.crt', '/etc/pki/tls/certs/ca-bundle.crt']
+      : [];
+  for (const __dou208_candidate of __dou208_candidates) {
+    if (__dou208_existsSync(__dou208_candidate)) {
+      const __dou208_result = __dou208_spawnSync(
+        process.execPath,
+        process.argv.slice(1),
+        {
+          stdio: 'inherit',
+          env: { ...process.env, NODE_EXTRA_CA_CERTS: __dou208_candidate },
+        },
+      );
+      process.exit(__dou208_result.status ?? 1);
+    }
+  }
+  // No candidate found (Windows, unusual Linux distro): fall through
+  // and let Node's bundled CA bundle handle TLS. The user can still
+  // set NODE_EXTRA_CA_CERTS manually for corporate cert chains.
+}
+
 import { initializeApp } from 'firebase/app';
 import { getAuth, initializeAuth, signInWithEmailAndPassword, signInWithCredential, GoogleAuthProvider } from 'firebase/auth';
 import {

package/yjs-binding-state.js

@@ -0,0 +1,61 @@
+// Per-file Y.Doc binary state persistence (DOU-209).
+//
+// On daemon restart we need to merge offline edits made on disk with
+// offline edits made via the web. Yjs converges deterministically when
+// both sides apply their ops to a common baseline. The daemon's last
+// view of the file (== ytext at last write, == disk content at last
+// write) is that baseline. Persisting the Y.Doc binary state per file
+// lets the daemon restore that baseline on startup so:
+//   1. ytext == lastDisk after restore
+//   2. fast-diff(ytext, currentDisk) gives positions valid in ytext
+//   3. cloud yupdates apply on top via CRDT merge (idempotent for ops
+//      already in the loaded state, additive for new cloud ops).
+//
+// Storage layout: one file per Y.Doc, keyed by fileId, under
+// `<localPath>/.compound-yjs-binding/<fileId>.yjs`. The binary blob is
+// the output of Y.encodeStateAsUpdate(doc); the daemon applies it via
+// Y.applyUpdate(doc, blob) on restore.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const STATE_DIR = '.compound-yjs-binding';
+
+function statePathFor(localPath, fileId) {
+  return path.join(localPath, STATE_DIR, `${fileId}.yjs`);
+}
+
+// Load the encoded Y.Doc state for a file. Returns null if no state
+// exists yet (first run, or this fileId hasn't been synced before) or
+// if the file is unreadable for any reason (corruption, permissions).
+// Treating unreadable as "no state" is safe: the binding falls back to
+// its first-run behavior, which writes ytext to disk on initial flush.
+export function loadBindingState(localPath, fileId) {
+  try {
+    return fs.readFileSync(statePathFor(localPath, fileId));
+  } catch {
+    return null;
+  }
+}
+
+// Persist the encoded Y.Doc state for a file. Atomic via write-to-tmp +
+// rename so a crash mid-write can't leave a half-written .yjs file that
+// would corrupt the next startup. Best-effort: a failed save costs us a
+// cold-start reconciliation next launch, never data.
+export function saveBindingState(localPath, fileId, encoded) {
+  const finalPath = statePathFor(localPath, fileId);
+  const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    fs.writeFileSync(tmpPath, encoded);
+    fs.renameSync(tmpPath, finalPath);
+  } catch {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+}
+
+// Best-effort cleanup when a file is deleted from the workspace, so
+// stale .yjs blobs don't accumulate. Failing to delete is not fatal.
+export function deleteBindingState(localPath, fileId) {
+  try { fs.unlinkSync(statePathFor(localPath, fileId)); } catch { /* ignore */ }
+}

package/yjs-file-binding.js

@@ -0,0 +1,236 @@
+// YjsFileBinding: per-file glue that keeps a local Markdown file
+// converged with the per-file Y.Doc that lives in Firestore.
+//
+// Two directions, both flowing through the Y.Doc:
+//   cloud -> disk: provider applies remote yupdates to ytext; an
+//     observer debounces the resulting text into a single disk write
+//     so a burst of web keystrokes coalesces into one fs.writeFile.
+//   disk -> cloud: when the local file changes, caller invokes
+//     applyDiskText(newText); we diff against ytext (fast-diff for a
+//     char-level edit script) and apply inserts/deletes in one
+//     transaction so the provider's local-update listener emits a
+//     single yupdate carrying just the changed regions, preserving
+//     concurrent web edits to unrelated regions.
+//
+// Disk I/O is injected via onDiskWrite so tests can record without
+// touching the filesystem and so the daemon can plumb its existing
+// suppressLocal set (avoids the disk write feeding back through
+// chokidar as a fake user edit).
+
+import * as Y from 'yjs';
+import fastDiff from 'fast-diff';
+import { YjsProvider } from './yjs-provider.js';
+
+export class YjsFileBinding {
+  constructor(store, {
+    debounceMs = 300, onDiskWrite, onDocStateChange,
+    initialDocState = null, currentDiskText = null,
+  }) {
+    if (!onDiskWrite) throw new Error('YjsFileBinding: onDiskWrite is required');
+    this.doc = new Y.Doc();
+    this.ytext = this.doc.getText('content');
+    this.store = store;
+    this.provider = new YjsProvider(this.doc, store);
+    this.debounceMs = debounceMs;
+    this.onDiskWrite = onDiskWrite;
+    // Called after every Y.Doc mutation reaches a stable state, with
+    // the encoded Y.Doc binary state. The daemon persists this to
+    // disk so the next startup can restore the baseline and merge
+    // offline disk edits without losing offline cloud edits (DOU-209).
+    this.onDocStateChange = onDocStateChange ?? null;
+    // Restore options for offline-merge (DOU-209).
+    this.initialDocState = initialDocState;
+    this.currentDiskText = currentDiskText;
+    this.flushTimer = null;
+    this.lastDiskText = null;
+    this.observer = null;
+    this.stopped = false;
+  }
+
+  async start() {
+    // DOU-209: offline-merge startup. Three-step process that turns the
+    // daemon's restart into a deterministic CRDT merge:
+    //
+    //   1. Restore Y.Doc from the daemon's last-saved binary state (if
+    //      any). After this, ytext equals what disk was at the daemon's
+    //      last write. This is the common ancestor for any divergence
+    //      that happened while the daemon was offline.
+    //   2. If the current disk content differs from the restored ytext,
+    //      the difference is disk-only edits made during downtime.
+    //      Apply them as Y.Doc operations (positions are valid in the
+    //      restored ytext since restored-ytext == lastDisk == fast-diff
+    //      input).
+    //   3. provider.loadInitial() pulls cloud's yupdates on top. Y.applyUpdate
+    //      is idempotent (Yjs's state-vector dedup), so already-known
+    //      ops are no-ops. Only NEW cloud ops (offline web edits) take
+    //      effect. They CRDT-merge with the disk ops from step 2.
+    //
+    // Without step 1, fast-diff(post-loadInitial-ytext, currentDisk)
+    // treats web's offline insertions as "things present in ytext but
+    // missing from disk" and DELETES them. That's the bug this fixes.
+    // Seed lastDiskText from the disk content we observed at construction
+    // time so the initial flush is a no-op when ytext already matches
+    // what's on disk. Without this, the binding's initial flush always
+    // wrote ytext to disk on startup, which clobbered any content the
+    // daemon's legacy contentHash + Storage blob pull (the fallthrough
+    // path in handleFirestoreChange) may have written first for non-Yjs
+    // cloud edits. Regression case: "after restart, pulls a web edit
+    // made while stopped despite a fresh local mtime" in
+    // sync/org-sync.test.js.
+    this.lastDiskText = this.currentDiskText;
+
+    if (this.initialDocState) {
+      Y.applyUpdate(this.doc, this.initialDocState);
+    }
+
+    // Disk-merge ops emitted below need to reach the store so other
+    // clients see the offline disk edits. The provider's local-update
+    // handler isn't attached yet (it's wired in startSubscription,
+    // which we can't call until after loadInitial), so we capture the
+    // updates synchronously here and push them after the subscription
+    // is set up. Capture by Y.Doc 'update' event with a 'disk' origin
+    // filter so we only grab the ops from our own _applyTextDiff and
+    // not anything spurious.
+    //
+    // The disk-merge is only safe when we have an `initialDocState`:
+    // that gives ytext a known baseline (the daemon's last view of the
+    // file) before we diff against currentDiskText, so fast-diff
+    // positions are valid AND the resulting ops are scoped to JUST the
+    // disk-only changes. Without a baseline, applying currentDiskText
+    // as fresh inserts on top of an empty ytext would then collide
+    // with whatever loadInitial pulls from the cloud: Yjs would see
+    // both the daemon's "fresh insert" and the cloud's "original
+    // insert" as concurrent ops, producing duplicated content. So on
+    // first contact (no saved state) we skip the disk merge and let
+    // loadInitial + initial flush behave the same as before DOU-209.
+    const capturedDiskUpdates = [];
+    if (this.initialDocState && this.currentDiskText != null) {
+      const restored = this.ytext.toString();
+      if (this.currentDiskText !== restored) {
+        const captureHandler = (update, origin) => {
+          if (origin === 'disk') capturedDiskUpdates.push(update);
+        };
+        this.doc.on('update', captureHandler);
+        // Same diff-and-apply shape as applyDiskText, but we call the
+        // internal helper directly: applyDiskText is the live-chokidar
+        // path and also touches lastDiskText / _emitDocState in ways
+        // that aren't appropriate during the startup-merge phase.
+        this._applyTextDiff(restored, this.currentDiskText);
+        this.doc.off('update', captureHandler);
+      }
+    }
+
+    // DOU-204: two-phase provider start. Phase 1 loads snapshot +
+    // initial updates without subscribing. We then attach the
+    // Y.Text observer that drives the debounced disk write. Phase 2
+    // subscribes to remote updates; the first listener fire is the
+    // initial query result (re-applies the already-loaded docs
+    // idempotently), and any update that lands after loadInitial
+    // routes through the now-attached observer instead of mutating
+    // Y.Text silently between provider.start and observer attach.
+    await this.provider.loadInitial();
+    this.observer = () => {
+      if (this.stopped) return;
+      if (this.flushTimer) clearTimeout(this.flushTimer);
+      this.flushTimer = setTimeout(() => this._flushNow(), this.debounceMs);
+    };
+    this.ytext.observe(this.observer);
+    this.provider.startSubscription();
+
+    // Push the disk-side updates captured above so the store records
+    // the offline disk edits and other clients receive them. Y.applyUpdate
+    // is idempotent so the daemon's own subscription echo (when the
+    // store fires its own append back through subscribeUpdates) is a
+    // no-op on our local Y.Doc.
+    for (const update of capturedDiskUpdates) {
+      try { await this.store.appendUpdate(update); }
+      catch (err) { console.error('YjsFileBinding: disk-merge appendUpdate failed:', err && err.message); }
+    }
+
+    // Initial flush: ytext may be non-empty after replay (file has
+    // existing Yjs state). Writes the loaded content to disk so the
+    // local file is up-to-date the moment the binding is wired in.
+    if (this.ytext.length > 0) this._flushNow();
+    // Persist the merged baseline so the next restart has the right
+    // anchor (the binding's state right now == disk after the flush
+    // above; future disk-side edits should diff against this state).
+    this._emitDocState();
+  }
+
+  _applyTextDiff(fromText, toText) {
+    if (fromText === toText) return;
+    const diffs = fastDiff(fromText, toText);
+    this.doc.transact(() => {
+      let idx = 0;
+      for (const [op, str] of diffs) {
+        if (op === 0) {
+          idx += str.length;
+        } else if (op === 1) {
+          this.ytext.insert(idx, str);
+          idx += str.length;
+        } else {
+          this.ytext.delete(idx, str.length);
+        }
+      }
+    }, 'disk');
+  }
+
+  _emitDocState() {
+    if (this.stopped || !this.onDocStateChange) return;
+    try {
+      this.onDocStateChange(Y.encodeStateAsUpdate(this.doc));
+    } catch (err) {
+      console.error('YjsFileBinding: onDocStateChange failed:', err && err.message);
+    }
+  }
+
+  // Sync flush used by both the debounced observer and the final
+  // drain in stop().
+  _flushNow() {
+    if (this.stopped) return;
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    const text = this.ytext.toString();
+    if (text === this.lastDiskText) return;
+    this.lastDiskText = text;
+    this.onDiskWrite(text);
+    // The disk now matches ytext: snapshot the Y.Doc state so the next
+    // restart has the right baseline for offline-merge (DOU-209).
+    this._emitDocState();
+  }
+
+  // The local disk file changed (chokidar). Diff against the current
+  // ytext and apply as a sequence of inserts/deletes inside one
+  // transaction. Using a distinct origin ('disk') keeps the provider's
+  // local-update listener pushing the resulting yupdate to Firestore.
+  applyDiskText(newText) {
+    if (this.stopped) return;
+    const oldText = this.ytext.toString();
+    if (oldText === newText) return;
+    this._applyTextDiff(oldText, newText);
+    // Suppress the debounced echo: lastDiskText now matches the disk
+    // content the caller just observed, so the observer's pending
+    // flush is a no-op.
+    this.lastDiskText = newText;
+    // Snapshot the Y.Doc state so the next restart's baseline includes
+    // this disk-originated edit (DOU-209).
+    this._emitDocState();
+  }
+
+  async stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.observer) {
+      this.ytext.unobserve(this.observer);
+      this.observer = null;
+    }
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.provider.stop();
+    this.doc.destroy();
+  }
+}

package/yjs-firestore-update-store.js

@@ -0,0 +1,117 @@
+// FirestoreUpdateStore: Firestore-backed store for per-file Yjs
+// CRDT updates. Ported from web/src/yjs/firestore-update-store.ts so
+// the published @doubling/compound-sync package does not reach into
+// the web source tree. Keep the API identical to the web copy; a
+// follow-up will unify the two into a shared workspace package once
+// PR 4 finishes retiring the legacy blob path.
+
+import {
+  collection,
+  doc,
+  addDoc,
+  getDoc,
+  getDocs,
+  setDoc,
+  query,
+  where,
+  orderBy,
+  onSnapshot,
+  serverTimestamp,
+  writeBatch,
+  Bytes,
+  Timestamp,
+} from 'firebase/firestore';
+
+function formatId(createdAt, docId) {
+  return `${createdAt.toMillis().toString().padStart(16, '0')}_${docId}`;
+}
+
+function parseTimestampFromId(id) {
+  return Timestamp.fromMillis(Number(id.split('_')[0]));
+}
+
+export class FirestoreUpdateStore {
+  constructor(db, orgId, fileId) {
+    this.updatesCol = collection(db, 'orgs', orgId, 'files', fileId, 'yupdates');
+    this.snapshotDoc = doc(db, 'orgs', orgId, 'files', fileId, 'yjs', 'state');
+  }
+
+  async loadSnapshot() {
+    const snap = await getDoc(this.snapshotDoc);
+    if (!snap.exists()) return null;
+    const data = snap.data();
+    return {
+      state: data.state.toUint8Array(),
+      baselineId: data.baselineId ?? null,
+    };
+  }
+
+  async loadUpdatesAfter(baselineId) {
+    const q =
+      baselineId === null
+        ? query(this.updatesCol, orderBy('createdAt', 'asc'))
+        : query(
+            this.updatesCol,
+            where('createdAt', '>', parseTimestampFromId(baselineId)),
+            orderBy('createdAt', 'asc'),
+          );
+    const snap = await getDocs(q);
+    return snap.docs
+      .map((d) => {
+        const data = d.data();
+        if (!data.createdAt) return null;
+        return { id: formatId(data.createdAt, d.id), update: data.update.toUint8Array() };
+      })
+      .filter((r) => r !== null);
+  }
+
+  async appendUpdate(update) {
+    const docRef = await addDoc(this.updatesCol, {
+      update: Bytes.fromUint8Array(update),
+      createdAt: serverTimestamp(),
+    });
+    const fresh = await getDoc(docRef);
+    const data = fresh.data();
+    if (!data || !data.createdAt) {
+      throw new Error('FirestoreUpdateStore.appendUpdate: createdAt unresolved');
+    }
+    return { id: formatId(data.createdAt, docRef.id), update };
+  }
+
+  subscribeUpdates(onUpdate) {
+    const q = query(this.updatesCol, orderBy('createdAt', 'asc'));
+    // includeMetadataChanges + emitted-id dedup: see the web copy for
+    // the full rationale. Skipping pending writes alone drops the
+    // server-ack delivery because that fire is metadata-only.
+    const emitted = new Set();
+    return onSnapshot(q, { includeMetadataChanges: true }, (snap) => {
+      for (const change of snap.docChanges({ includeMetadataChanges: true })) {
+        if (change.type !== 'added' && change.type !== 'modified') continue;
+        const data = change.doc.data();
+        if (!data.createdAt) continue;
+        if (emitted.has(change.doc.id)) continue;
+        emitted.add(change.doc.id);
+        onUpdate({
+          id: formatId(data.createdAt, change.doc.id),
+          update: data.update.toUint8Array(),
+        });
+      }
+    });
+  }
+
+  async saveSnapshotAndCompact(state, newBaselineId) {
+    const baselineTs = parseTimestampFromId(newBaselineId);
+    await setDoc(this.snapshotDoc, {
+      state: Bytes.fromUint8Array(state),
+      baselineId: newBaselineId,
+      baselineCreatedAt: baselineTs,
+      updatedAt: serverTimestamp(),
+    });
+    const q = query(this.updatesCol, where('createdAt', '<=', baselineTs));
+    const stale = await getDocs(q);
+    if (stale.empty) return;
+    const batch = writeBatch(this.snapshotDoc.firestore);
+    for (const d of stale.docs) batch.delete(d.ref);
+    await batch.commit();
+  }
+}

package/yjs-provider.js

@@ -0,0 +1,85 @@
+// YjsProvider: binds a Y.Doc to an UpdateStore. Ported from
+// web/src/yjs/provider.ts; see that file for the full design notes
+// (echo handling, snapshot replay, compaction semantics, two-phase
+// start lifecycle from DOU-204). API kept identical so the two copies
+// can be unified into a shared workspace package in a follow-up.
+
+import * as Y from 'yjs';
+
+export class YjsProvider {
+  constructor(doc, store) {
+    this.doc = doc;
+    this.store = store;
+    this.unsubscribeStore = null;
+    this.updateHandler = null;
+    this.loaded = false;
+    this.subscribed = false;
+    this.stopped = false;
+  }
+
+  /** Phase 1: snapshot + initial updates → Y.Doc. No remote
+   * subscription yet. Callers that intend to attach a Y.Text observer
+   * (e.g. a disk-write debouncer here, yCollab on the web) should
+   * install that observer between `loadInitial()` and
+   * `startSubscription()` so the first remote update routes through
+   * to it instead of mutating Y.Text silently in the gap (DOU-204). */
+  async loadInitial() {
+    if (this.loaded) throw new Error('YjsProvider.loadInitial() called twice');
+    this.loaded = true;
+
+    const snapshot = await this.store.loadSnapshot();
+    if (snapshot) Y.applyUpdate(this.doc, snapshot.state, this);
+
+    const initial = await this.store.loadUpdatesAfter(snapshot?.baselineId ?? null);
+    for (const record of initial) Y.applyUpdate(this.doc, record.update, this);
+  }
+
+  /** Phase 2: subscribe to remote updates and push local Y.Doc
+   * mutations back to the store. */
+  startSubscription() {
+    if (!this.loaded) throw new Error('YjsProvider.startSubscription() before loadInitial()');
+    if (this.subscribed) throw new Error('YjsProvider.startSubscription() called twice');
+    this.subscribed = true;
+
+    this.unsubscribeStore = this.store.subscribeUpdates((record) => {
+      if (this.stopped) return;
+      Y.applyUpdate(this.doc, record.update, this);
+    });
+
+    this.updateHandler = (update, origin) => {
+      if (this.stopped) return;
+      if (origin === this) return;
+      this.store.appendUpdate(update).catch((err) => {
+        console.error('YjsProvider: appendUpdate failed:', err && err.message);
+      });
+    };
+    this.doc.on('update', this.updateHandler);
+  }
+
+  /** Convenience: load + subscribe in one call. Use only when no
+   * view-layer observer needs to attach between the phases. */
+  async start() {
+    await this.loadInitial();
+    this.startSubscription();
+  }
+
+  stop() {
+    this.stopped = true;
+    if (this.unsubscribeStore) {
+      this.unsubscribeStore();
+      this.unsubscribeStore = null;
+    }
+    if (this.updateHandler) {
+      this.doc.off('update', this.updateHandler);
+      this.updateHandler = null;
+    }
+  }
+
+  async compact() {
+    const state = Y.encodeStateAsUpdate(this.doc);
+    const records = await this.store.loadUpdatesAfter(null);
+    const last = records[records.length - 1];
+    if (!last) return;
+    await this.store.saveSnapshotAndCompact(state, last.id);
+  }
+}