@doubling/compound-sync 1.12.3 → 1.12.4

package/README.md

@@ -42,6 +42,19 @@ Compound Sync watches a local folder and your Compound workspace simultaneously.
   Shared with Me/          -- files shared with you (read-only)
 ```
 
+## Hidden sync metadata
+
+The daemon maintains per-machine state under your sync folder (dotfiles and
+directories, not uploaded to Compound):
+
+| Path | Purpose |
+| ---- | ------- |
+| `.compound-sync/manifest.json` | Maps synced paths to Firestore file IDs (startup reconcile) |
+| `.compound-sync-state.json` | Content-hash baseline for push/pull decisions |
+| `.compound-yjs-binding/` | Offline Yjs merge state per file |
+
+Do not edit these by hand. See [docs/features/sync/local-metadata.md](../docs/features/sync/local-metadata.md).
+
 ## Running
 
 After setup, start syncing with:
@@ -116,6 +129,10 @@ npm test
 - **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.
 
+### Logging convention
+
+Org-scoped output: `  [${orgId}] [tag] message`. Use `console.warn` for recoverable issues, `console.error` for failures. Tags like `[local scan]` and `[manifest reconcile]` identify subsystems.
+
 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

package/manifest.js

@@ -0,0 +1,127 @@
+// Per-machine sync manifest (DOU-55).
+//
+// Maps `scope:docPath` → Firestore fileId so the daemon can reconcile
+// local disk vs cloud on startup (e.g. web deletes while offline must
+// remove local orphans instead of re-uploading them).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MANIFEST_DIR = '.compound-sync';
+const MANIFEST_FILE = 'manifest.json';
+const FLUSH_DEBOUNCE_MS = 500;
+
+export function manifestPath(localPath) {
+  return path.join(localPath, MANIFEST_DIR, MANIFEST_FILE);
+}
+
+function normalizeEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (typeof raw.fileId !== 'string' || !raw.fileId) return null;
+  if (typeof raw.contentHash !== 'string' || !raw.contentHash) return null;
+  return {
+    fileId: raw.fileId,
+    contentHash: raw.contentHash,
+    lastSyncedAt: typeof raw.lastSyncedAt === 'string' ? raw.lastSyncedAt : new Date().toISOString(),
+  };
+}
+
+export function loadManifest(localPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath(localPath), 'utf8'));
+    if (parsed && typeof parsed === 'object' && parsed.entries && typeof parsed.entries === 'object') {
+      const entries = {};
+      for (const [key, raw] of Object.entries(parsed.entries)) {
+        const entry = normalizeEntry(raw);
+        if (entry) {
+          entries[key] = entry;
+        } else {
+          console.error(`[sync-manifest] dropped invalid entry for ${key}`);
+        }
+      }
+      return { version: parsed.version ?? 1, entries };
+    }
+  } catch {
+    // Missing or corrupt file reads as empty so first run can't crash sync.
+  }
+  return { version: 1, entries: {} };
+}
+
+/**
+ * Persists the in-memory manifest state to disk.
+ *
+ * PERFORMANCE & SAFETY NOTES:
+ * 1. Atomic Writes: We write to `.compound-sync/manifest.json.tmp` first,
+ *    then use `fs.renameSync` to overwrite the actual manifest. This ensures
+ *    that if the daemon crashes mid-write, we do not corrupt the JSON.
+ * 2. Unsorted Keys: We do not sort the object keys before calling
+ *    `JSON.stringify()`. Sorting requires significant CPU overhead for large
+ *    workspaces. The in-memory object map is the source of truth; disk
+ *    order does not matter.
+ * 3. Synchronous I/O: All disk operations use `*Sync` APIs. A flush blocks
+ *    the Node event loop briefly; see docs/features/sync/sync-manifest-design.md.
+ *
+ * @param {string} localPath - Sync folder root
+ * @param {Object} manifestState - The current in-memory manifest dictionary
+ */
+export function saveManifest(localPath, manifestState) {
+  const finalPath = manifestPath(localPath);
+  const tmpPath = path.join(path.dirname(finalPath), 'manifest.json.tmp');
+  try {
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    fs.writeFileSync(tmpPath, JSON.stringify(manifestState));
+    fs.renameSync(tmpPath, finalPath);
+  } catch (err) {
+    console.error(
+      `[sync-manifest] failed to persist manifest at ${finalPath}: ${err && err.message}`,
+    );
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (cleanupErr) {
+      // A leftover .tmp is ignored on load (only the canonical path is read).
+      // ENOENT means the tmp never landed or rename already consumed it.
+      if (cleanupErr?.code !== 'ENOENT') {
+        console.error(
+          `[sync-manifest] failed to remove temp manifest ${tmpPath}: ${cleanupErr && cleanupErr.message}`,
+        );
+      }
+    }
+  }
+}
+
+export function createManifestStore(localPath, { debounceMs = FLUSH_DEBOUNCE_MS } = {}) {
+  const state = loadManifest(localPath);
+  let timer = null;
+
+  function scheduleFlush() {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      saveManifest(localPath, state);
+    }, debounceMs);
+  }
+
+  return {
+    upsertEntry(trackingKey, entry) {
+      state.entries[trackingKey] = entry;
+      scheduleFlush();
+    },
+    removeEntry(trackingKey) {
+      delete state.entries[trackingKey];
+      scheduleFlush();
+    },
+    getEntry(trackingKey) {
+      return state.entries[trackingKey] ?? null;
+    },
+    getState() {
+      return state;
+    },
+    flush() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      saveManifest(localPath, state);
+    },
+  };
+}

package/org-sync.js

@@ -37,6 +37,8 @@ import {
 } from './paths.js';
 import { TeamRegistry } from './team-registry.js';
 import { loadSyncState, saveSyncState } from './sync-state.js';
+import { createManifestStore } from './manifest.js';
+import { shouldPersistLocalSyncState } from './push-outcome.js';
 import { FirestoreUpdateStore } from './yjs-firestore-update-store.js';
 import { YjsFileBinding } from './yjs-file-binding.js';
 import {
@@ -93,6 +95,7 @@ export async function startOrgSync({
   // dotfile in the synced folder (ignored by the watcher), so it travels
   // with the folder and needs no extra wiring from the caller.
   const STATE_PATH = statePath ?? path.join(LOCAL_PATH, '.compound-sync-state.json');
+  const manifestStore = createManifestStore(LOCAL_PATH);
 
   // Teardown handles: every onSnapshot unsub plus the chokidar watcher.
   const unsubscribers = [];
@@ -321,8 +324,8 @@ export async function startOrgSync({
     }
   }
 
-  // Static (user-level) folders. Team folders are created per-team by
-  // setupTeam below as soon as the registry sees each teamspace.
+  // Static (user-level) folders. Team folders are mkdir'd by setupTeam,
+  // which runs after manifest reconcile (see startup ordering below).
   function ensureFolderStructure() {
     const privatePath = path.join(LOCAL_PATH, PRIVATE_FOLDER);
     if (!fs.existsSync(privatePath)) fs.mkdirSync(privatePath, { recursive: true });
@@ -376,6 +379,11 @@ export async function startOrgSync({
         setBaseline(trackingKey, lastSyncedHash.get(prevKnown.trackingKey));
         deleteBaseline(prevKnown.trackingKey);
       }
+      const manifestEntry = manifestStore.getEntry(prevKnown.trackingKey);
+      if (manifestEntry) {
+        manifestStore.removeEntry(prevKnown.trackingKey);
+        manifestStore.upsertEntry(trackingKey, manifestEntry);
+      }
       const binding = bindings.get(fileId);
       if (binding && bindingsByPath.get(prevKnown.localPath) === binding) {
         bindingsByPath.delete(prevKnown.localPath);
@@ -412,6 +420,7 @@ export async function startOrgSync({
       }
       lastKnownUpdate.delete(trackingKey);
       deleteBaseline(trackingKey);
+      manifestStore.removeEntry(trackingKey);
       knownPaths.delete(fileId);
       await disposeBinding(change.doc.id, localFilePath);
       return;
@@ -538,8 +547,9 @@ export async function startOrgSync({
   }
 
   // Set up per-team resources: mkdir the local folder, register the
-  // Firestore listener for that team's files. Wired into the
-  // TeamRegistry; called once per teamspace as it appears.
+  // Firestore listener for that team's files. On startup, called once
+  // per bootstrapped team after reconcile; thereafter via TeamRegistry
+  // when the live teams-collection listener reports add/modify/remove.
   setupTeam = (teamId, teamData) => {
     const teamFolder = teamFolderName(teamData.name);
     const teamPath = path.join(LOCAL_PATH, teamFolder);
@@ -558,35 +568,287 @@ export async function startOrgSync({
     console.log(`  [${orgId}]   Listening: ${teamFolder}`);
   };
 
-  // Live listener on the teams collection. Initial snapshot bootstraps
-  // the known teamspaces; subsequent changes pick up new/renamed/
-  // removed teamspaces without restarting the daemon. We await the
-  // first snapshot so the local watcher sees a populated teamIdsByName
-  // before it tries to route any addDir/add events.
-  let teamsUnsub = null;
-  await new Promise((resolve, reject) => {
-    let firstSnapshotResolved = false;
-    teamsUnsub = onSnapshot(collection(db, `orgs/${orgId}/teams`), (snapshot) => {
-      snapshot.docChanges().forEach((change) => {
-        teamRegistry.applyChange({
-          type: change.type,
-          id: change.doc.id,
-          data: change.doc.data(),
-        });
-      });
-      if (!firstSnapshotResolved) {
-        firstSnapshotResolved = true;
-        console.log(`  [${orgId}] Teams: ${teamRegistry.names().join(', ') || 'none'}`);
-        resolve();
+  // Bootstrap team metadata synchronously so manifest reconcile can
+  // query team-scoped cloud files before any file onSnapshot handlers
+  // run (DOU-55). Populating teamIdsByName here also lets chokidar
+  // route local paths once the watcher starts. Per-team file listeners
+  // and the live teams-collection onSnapshot are wired after reconcile
+  // completes so their initial snapshots cannot race with startup cleanup.
+  const teamsSnap = await getDocs(collection(db, `orgs/${orgId}/teams`));
+  for (const teamDoc of teamsSnap.docs) {
+    teamRegistry.bootstrap(teamDoc.id, teamDoc.data());
+  }
+  console.log(`  [${orgId}] Teams: ${teamRegistry.names().join(', ') || 'none'}`);
+
+  function trackingKeyFromDocData(data) {
+    return `${data.scope || 'team'}:${data.path}`;
+  }
+
+  // Paths the daemon does not scan or sync. Add checks here as needed
+  // (extensions, .compoundignore, etc.).
+  function shouldSkipLocalPath(name, rel) {
+    if (name.startsWith('.') || name === 'node_modules') return true;
+    if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) return true;
+    if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) return true;
+    return false;
+  }
+
+  function walkLocalSyncableFiles(absDir, files) {
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch (err) {
+      const rel = path.relative(LOCAL_PATH, absDir) || '.';
+      console.warn(`  [${orgId}] [local scan] could not read directory ${rel}: ${err.message}`);
+      return;
+    }
+    for (const ent of entries) {
+      const abs = path.join(absDir, ent.name);
+      const rel = path.relative(LOCAL_PATH, abs);
+      if (shouldSkipLocalPath(ent.name, rel)) continue;
+      if (ent.isDirectory()) {
+        walkLocalSyncableFiles(abs, files);
+      } else if (ent.isFile()) {
+        files.push(abs);
       }
-    }, (err) => {
-      console.error(`  [${orgId}] Teams listener error:`, err);
-      if (!firstSnapshotResolved) {
-        firstSnapshotResolved = true;
-        reject(err);
+    }
+  }
+
+  function collectLocalSyncableFiles() {
+    const files = [];
+    walkLocalSyncableFiles(LOCAL_PATH, files);
+    return files;
+  }
+
+  function readLocalFilePayload(filePath) {
+    const rel = path.relative(LOCAL_PATH, filePath);
+    const ext = extFromPath(rel);
+    const mimeType = mimeTypeFromExt(ext);
+    const data = isTextMimeType(mimeType)
+      ? fs.readFileSync(filePath, 'utf-8')
+      : fs.readFileSync(filePath);
+    return { data, mimeType, contentHash: computeContentHash(data) };
+  }
+
+  async function pushLocalFileAtPath(filePath) {
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      return;
+    }
+    if (!stat.isFile() || stat.size > maxUploadBytes) return;
+    const { data, mimeType } = readLocalFilePayload(filePath);
+    await pushToFirestore(filePath, data, mimeType, stat.mtime.toISOString());
+  }
+
+  // Sync local cleanup during startup manifest reconcile. Runs before
+  // Firestore listeners and Yjs bindings are wired, so no async cloud or
+  // binding teardown is needed here.
+  function deleteLocalReconcile(localFilePath, fileId, trackingKey) {
+    suppressLocal.add(localFilePath);
+    if (fs.existsSync(localFilePath)) {
+      console.log(`  [${orgId}] [manifest reconcile] DELETE local ${path.relative(LOCAL_PATH, localFilePath)}`);
+      fs.unlinkSync(localFilePath);
+    }
+    lastKnownUpdate.delete(trackingKey);
+    deleteBaseline(trackingKey);
+    manifestStore.removeEntry(trackingKey);
+    if (fileId) {
+      knownPaths.delete(fileId);
+    }
+    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+  }
+
+  async function deleteRemoteReconcile(cloudData, trackingKey) {
+    const scope = cloudData.scope || 'team';
+    const teamId = cloudData.teamId;
+    const docPath = cloudData.path;
+    const result = await deleteFileFromCloud({
+      filesRef,
+      storage,
+      orgId,
+      userId,
+      scope,
+      teamId,
+      docPath,
+    });
+    if (result.action === 'deleted') {
+      console.log(`  [${orgId}] [manifest reconcile] DELETE cloud ${docPath}`);
+    }
+    manifestStore.removeEntry(trackingKey);
+  }
+
+  function localPathForCloudData(data) {
+    if (!data?.path) return null;
+    if (data.scope === 'private') {
+      if (data.ownerId === userId) {
+        return path.join(LOCAL_PATH, PRIVATE_FOLDER, data.path);
       }
+      return path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER, data.path);
+    }
+    if (data.scope === 'team' && data.teamId) {
+      const team = teamRegistry.get(data.teamId);
+      if (!team?.name) return null;
+      return path.join(LOCAL_PATH, teamFolderName(team.name), data.path);
+    }
+    return null;
+  }
+
+  async function fetchCloudFilesByKey() {
+    const cloudByKey = new Map();
+
+    function ingestDoc(d) {
+      const data = d.data();
+      if (data.type === 'folder' || !data.path) return;
+      const key = trackingKeyFromDocData(data);
+      cloudByKey.set(key, { fileId: d.id, data });
+    }
+
+    for (const [teamId] of teamRegistry.entries()) {
+      const teamSnap = await getDocs(query(
+        filesRef,
+        where('scope', '==', 'team'),
+        where('teamId', '==', teamId),
+      ));
+      teamSnap.docs.forEach(ingestDoc);
+    }
+
+    if (userId) {
+      const privateSnap = await getDocs(query(
+        filesRef,
+        where('scope', '==', 'private'),
+        where('ownerId', '==', userId),
+      ));
+      privateSnap.docs.forEach(ingestDoc);
+
+      const sharedSnap = await getDocs(query(
+        filesRef,
+        where('scope', '==', 'private'),
+        where('sharedWith', 'array-contains', userId),
+      ));
+      sharedSnap.docs.forEach(ingestDoc);
+    }
+
+    return cloudByKey;
+  }
+
+  // Runs after team metadata is loaded but before any file listeners or
+  // chokidar. See docs/features/sync/sync-manifest-design.md.
+  async function reconcileManifestOnStartup() {
+    console.log(`  [${orgId}] Reconciling local manifest...`);
+    const cloudByKey = await fetchCloudFilesByKey();
+
+    const localByKey = new Map();
+    for (const filePath of collectLocalSyncableFiles()) {
+      const { scope, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
+      if (!docPath) continue;
+      localByKey.set(`${scope}:${docPath}`, filePath);
+    }
+
+    // Bootstrap manifest entries for files already in sync before DOU-55.
+    for (const [key, cloud] of cloudByKey) {
+      if (manifestStore.getEntry(key)) continue;
+      const localFilePath = localByKey.get(key);
+      if (!localFilePath || !fs.existsSync(localFilePath)) continue;
+      try {
+        const { contentHash } = readLocalFilePayload(localFilePath);
+        if (contentHash === cloud.data.contentHash) {
+          manifestStore.upsertEntry(key, {
+            fileId: cloud.fileId,
+            contentHash,
+            lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
+          });
+        }
+      } catch {
+        // skip unreadable locals
+      }
+    }
+
+    const allKeys = new Set([
+      ...Object.keys(manifestStore.getState().entries),
+      ...localByKey.keys(),
+      ...cloudByKey.keys(),
+    ]);
+
+    for (const trackingKey of allKeys) {
+      const entry = manifestStore.getEntry(trackingKey);
+      let localFilePath = localByKey.get(trackingKey) ?? null;
+      const cloud = cloudByKey.get(trackingKey) ?? null;
+      if (!localFilePath && cloud) {
+        localFilePath = localPathForCloudData(cloud.data);
+      }
+      const onDisk = !!(localFilePath && fs.existsSync(localFilePath));
+
+      if (entry && onDisk && !cloud) {
+        let localHash;
+        try {
+          ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
+        } catch {
+          localHash = null;
+        }
+        if (localHash === null) {
+          console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
+        } else if (entry.contentHash && localHash !== entry.contentHash) {
+          await pushLocalFileAtPath(localFilePath);
+        } else {
+          deleteLocalReconcile(localFilePath, entry.fileId, trackingKey);
+        }
+      } else if (!entry && onDisk && !cloud) {
+        const baselineHash = lastSyncedHash.get(trackingKey);
+        let localHash;
+        try {
+          ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
+        } catch {
+          localHash = null;
+        }
+        if (localHash === null) {
+          console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
+        } else if (baselineHash && localHash === baselineHash) {
+          deleteLocalReconcile(localFilePath, null, trackingKey);
+        } else {
+          await pushLocalFileAtPath(localFilePath);
+        }
+      } else if (entry && !onDisk && cloud) {
+        await deleteRemoteReconcile(cloud.data, trackingKey);
+      } else if ((entry || cloud) && onDisk && cloud) {
+        manifestStore.upsertEntry(trackingKey, {
+          fileId: cloud.fileId,
+          contentHash: cloud.data.contentHash,
+          lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
+        });
+      } else if (!entry && onDisk && cloud) {
+        manifestStore.upsertEntry(trackingKey, {
+          fileId: cloud.fileId,
+          contentHash: cloud.data.contentHash,
+          lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
+        });
+      }
+    }
+
+    manifestStore.flush();
+    console.log(`  [${orgId}] Manifest reconcile complete.`);
+  }
+
+  await reconcileManifestOnStartup();
+
+  // Wire per-team file listeners and the live teams-collection watcher
+  // after reconcile so initial onSnapshot deliveries cannot race with
+  // startup cleanup (DOU-55). applyChange on the live listener picks
+  // up teamspaces created/renamed/removed after daemon start without
+  // restarting sync.
+  for (const [teamId, teamData] of teamRegistry.entries()) {
+    setupTeam(teamId, teamData);
+  }
+  const teamsUnsub = onSnapshot(collection(db, `orgs/${orgId}/teams`), (snapshot) => {
+    snapshot.docChanges().forEach((change) => {
+      teamRegistry.applyChange({
+        type: change.type,
+        id: change.doc.id,
+        data: change.doc.data(),
+      });
     });
-  });
+  }, (err) => console.error(`  [${orgId}] Teams listener error:`, err));
   unsubscribers.push(teamsUnsub);
 
   function startFirestoreListeners() {
@@ -637,9 +899,10 @@ export async function startOrgSync({
   }
 
   // DOU-217 helper: does a doc with this path + matching contentHash
-  // exist in Firestore right now? Used to verify a baseline entry
-  // before trusting it (so a stale baseline can't silently suppress
-  // re-upload of a file whose Firestore doc was deleted out-of-band).
+  // exist in Firestore right now? Startup reconcile (DOU-55) handles
+  // manifest-present orphans; this check covers the runtime push path
+  // when chokidar re-emits a file whose baseline still matches but the
+  // Firestore doc is gone (e.g. corrupt/missing manifest).
   async function firestoreDocExists({ scope, teamId, docPath, contentHash }) {
     let q;
     if (scope === 'private') {
@@ -675,12 +938,10 @@ export async function startOrgSync({
     // a genuine content change proceeds.
     //
     // DOU-217: trust the baseline ONLY after verifying the Firestore
-    // doc actually exists. The baseline is persisted across daemon
-    // restarts, so a doc deleted out-of-band (web delete the daemon
-    // missed while offline, manual cleanup, etc.) leaves a permanently
-    // stale entry that would silently suppress re-upload forever.
-    // Verifying via a single indexed read per touch is cheap; if the
-    // doc is gone, clear the baseline and fall through to push.
+    // doc actually exists. DOU-55 startup reconcile deletes local orphans
+    // when the manifest records a remote delete; this guard applies when
+    // pushToFirestore runs at runtime (chokidar add/change) and the
+    // baseline would otherwise suppress re-upload forever.
     const contentHash = computeContentHash(data);
     if (lastSyncedHash.get(trackingKey) === contentHash) {
       if (await firestoreDocExists({ scope, teamId, docPath, contentHash })) {
@@ -718,8 +979,16 @@ export async function startOrgSync({
     // Record the synced content baseline whenever local matches the
     // server (created/updated, or already-equal noop), so the pull side
     // can tell "local unchanged" from "local edited" by content.
-    if (result.action === 'created' || result.action === 'updated' || result.action === 'noop') {
+    if (shouldPersistLocalSyncState(result)) {
       setBaseline(trackingKey, contentHash);
+      if (result.fileId) {
+        manifestStore.upsertEntry(trackingKey, {
+          fileId: result.fileId,
+          contentHash,
+          lastSyncedAt: now,
+        });
+        manifestStore.flush();
+      }
     } else if (result.action === 'skipped-stale') {
       // The server copy is genuinely newer; clear the pre-set marker so
       // its firestore -> local snapshot is allowed through to update the
@@ -756,6 +1025,7 @@ export async function startOrgSync({
 
     if (result.action === 'deleted') {
       console.log(`  [${orgId}] [local → firestore] DELETE ${docPath} (${scope})`);
+      manifestStore.removeEntry(trackingKey);
     }
   }
 
@@ -971,6 +1241,7 @@ export async function startOrgSync({
     // is still running" guarantee on the resolved promise.
     async stop() {
       stoppedRef.value = true;
+      manifestStore.flush();
       for (const unsub of unsubscribers) {
         try { unsub(); } catch (e) { /* ignore */ }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubling/compound-sync",
-  "version": "1.12.3",
+  "version": "1.12.4",
   "description": "Bidirectional sync between Compound and local markdown files",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
     "sync.js",
     "org-sync.js",
     "sync-state.js",
+    "manifest.js",
+    "push-outcome.js",
     "config.js",
     "paths.js",
     "paths.d.ts",
@@ -31,8 +33,8 @@
     "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 files-helpers.test.js",
-    "test:integration": "node --import tsx --test --test-timeout=180000 files-push-create-private.test.js files-push-create-team.test.js files-push-update-private.test.js files-push-binary.test.js files-push-staleness.test.js files-push-storage-fail.test.js files-push-no-content.test.js files-push-stamps.test.js files-push-folder.test.js files-delete.test.js files-delete-folder.test.js files-read-blob.test.js org-sync-local-edit.test.js org-sync-file-ops.test.js org-sync-mtime.test.js org-sync-rename.test.js org-sync-yjs-pull.test.js org-sync-yjs-push.test.js org-sync-cold-start.test.js org-sync-special-chars.test.js org-sync-copy.test.js two-user-happy-paths.test.js two-user-yjs-convergence.test.js files-concurrency-folder-create.test.js files-concurrency-file-create.test.js files-concurrency-file-delete.test.js files-concurrency-folder-delete.test.js",
+    "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 manifest.test.js push-outcome.test.js yjs-file-binding.test.js yjs-binding-state.test.js files-helpers.test.js",
+    "test:integration": "node --import tsx --test --test-timeout=180000 files-push-create-private.test.js files-push-create-team.test.js files-push-update-private.test.js files-push-binary.test.js files-push-staleness.test.js files-push-storage-fail.test.js files-push-no-content.test.js files-push-stamps.test.js files-push-folder.test.js files-delete.test.js files-delete-folder.test.js files-read-blob.test.js org-sync-local-edit.test.js org-sync-file-ops.test.js org-sync-mtime.test.js org-sync-rename.test.js org-sync-yjs-pull.test.js org-sync-yjs-push.test.js org-sync-cold-start.test.js org-sync-startup-ordering.test.js org-sync-manifest-reconcile.test.js org-sync-special-chars.test.js org-sync-copy.test.js two-user-happy-paths.test.js two-user-yjs-convergence.test.js files-concurrency-folder-create.test.js files-concurrency-file-create.test.js files-concurrency-file-delete.test.js files-concurrency-folder-delete.test.js",
     "test:integration:emulator": "USE_EMULATOR=true firebase emulators:exec --only firestore,storage,auth 'npm run test:integration'",
     "test": "npm run test:unit && npm run test:integration"
   },

package/push-outcome.js

@@ -0,0 +1,10 @@
+// Whether a pushFileToCloud result should update local sync artifacts
+// (content baseline + manifest). Partial uploads (Firestore OK, blob
+// failed) must not be recorded as successfully synced.
+
+export function shouldPersistLocalSyncState(result) {
+  if (result.storageError) return false;
+  return result.action === 'created'
+    || result.action === 'updated'
+    || result.action === 'noop';
+}

package/team-registry.js

@@ -26,6 +26,18 @@ export class TeamRegistry {
     this.onTeardown = onTeardown;
   }
 
+  // Register a team in-memory without wiring listeners. Used during
+  // startup so manifest reconcile can resolve team-scoped paths before
+  // any file onSnapshot handlers run (DOU-55 ordering).
+  bootstrap(teamId, teamData) {
+    if (this.teams.has(teamId)) return false;
+    this.teams.set(teamId, teamData);
+    if (teamData && teamData.name) {
+      this.teamIdsByName.set(teamData.name, teamId);
+    }
+    return true;
+  }
+
   // Idempotently register a team. Safe to call with the same team
   // multiple times; only the first call triggers onSetup.
   add(teamId, teamData) {