canopycms 0.0.61 → 0.0.62

package/dist/content-store.js

@@ -4,6 +4,7 @@ import matter from 'gray-matter';
 import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
 import { atomicWriteFile } from './utils/atomic-write.js';
 import { withLock } from './utils/async-mutex.js';
+import { ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from './utils/content-write-lock.js';
 import { findBodyFieldName } from './utils/body-field.js';
 import { ContentIdIndex, extractIdFromFilename, extractSlugFromFilename, extractEntryTypeFromFilename, resolveCollectionPath, } from './content-id-index.js';
 import { registerContentIndexForInvalidation } from './content-index-registry.js';
@@ -41,11 +42,71 @@ export class ContentStoreError extends Error {
  * Indicates a cross-process concurrent write — the caller should reload and retry.
  */
 export class ContentConflictError extends Error {
-    constructor() {
-        super('Content was modified by another editor');
+    constructor(message = 'Content was modified by another editor') {
+        super(message);
         this.name = 'ContentConflictError';
     }
 }
+/**
+ * [SYNC-C1] Thrown when a mutation could not take the branch's cross-host
+ * content-write lock within its bounded wait -- in practice, the worker is
+ * mid-rebase on this branch's working tree (utils/content-write-lock.ts).
+ *
+ * A `ContentConflictError` subclass so every existing 409 mapping keeps
+ * working unchanged; the distinct type exists so the API can surface THIS
+ * message ("the branch is busy, retry") instead of the generic "modified by
+ * another editor", which would be actively misleading. The default wording
+ * covers writer-vs-writer contention too, which this lock also produces --
+ * see ContentWriteLockBusyError.
+ */
+export class BranchSyncingError extends ContentConflictError {
+    constructor(message) {
+        super(message);
+        this.name = 'BranchSyncingError';
+    }
+}
+/**
+ * [F1] Thrown when a save's content ID is carried by MORE THAN ONE file in
+ * the branch's content tree -- the duplicate-ID state `ContentIdIndex`
+ * quarantines (see its "Duplicate-ID quarantine" section).
+ *
+ * Why refuse rather than write: with two files sharing one ID, "this entry"
+ * is ambiguous, and every way of proceeding is worse than stopping.
+ * Following the index would mutate (and, via the slug-change cleanup, DELETE)
+ * a file the caller never addressed -- the data-loss bug this class exists to
+ * prevent. Writing only the addressed file would succeed silently into a file
+ * that is invisible to every ID-based lookup (reads-by-id, references,
+ * listings all resolve to the OTHER copy) and that the repair action later
+ * archives away, so the editor's work would appear to evaporate with no error
+ * anywhere. Refusing mutates nothing under any interleaving, and says what is
+ * wrong and who can fix it.
+ *
+ * A `ContentConflictError` subclass so every existing 409 mapping keeps
+ * working; the distinct type exists so the API can surface THIS message
+ * rather than the generic "modified by another editor", which would send the
+ * editor into a reload-and-retry loop that cannot succeed.
+ */
+export class DuplicateContentIdError extends ContentConflictError {
+    constructor(contentId, paths) {
+        const sorted = Array.from(new Set(paths)).sort();
+        super(
+        // Names the STATE, not an action. The repair-content-duplicates
+        // endpoint exists but nothing in the editor renders it, so telling an
+        // editor "an admin can run X" sent them to an admin who could neither
+        // run X nor see that the branch was affected. Say what is true; the
+        // admin panel's read-only duplicate list (SystemHealthPanel) is the
+        // diagnosis half, and the repair UI is tracked in
+        // .claude/future-tasks/duplicate-content-id-repair-ui.md.
+        `Content ID ${contentId} is on more than one file (${sorted
+            .map((p) => `"${p}"`)
+            .join(' and ')}), so this save was refused rather than risk overwriting or ` +
+            `deleting the wrong one. An administrator needs to resolve the duplicate on the ` +
+            `server before this entry can be saved.`);
+        this.name = 'DuplicateContentIdError';
+        this.contentId = contentId;
+        this.paths = sorted;
+    }
+}
 /**
  * Get the default entry type from a collection's entries array.
  * Returns the entry marked as default, or the first one, or undefined if no entries.
@@ -95,10 +156,41 @@ export class ContentStore {
         this.contentRootName = options.contentRootName || 'content';
         this.indexFreshnessIntervalMs =
             options.indexFreshnessIntervalMs ?? DEFAULT_INDEX_FRESHNESS_INTERVAL_MS;
+        this.contentWriteLockWaitMs =
+            options.contentWriteLockWaitMs ?? DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS;
         this.schemaIndex = new Map(flatSchema.map((item) => [item.logicalPath, item]));
         this._idIndex = new ContentIdIndex(this.root);
         registerContentIndexForInvalidation(this.root, this);
     }
+    /**
+     * [SYNC-C1] Run a working-tree mutation under the branch's cross-host
+     * content-write lock (utils/content-write-lock.ts), on top of the
+     * in-process locks the callee takes for itself.
+     *
+     * The in-process mutex serializes writers inside ONE process; it says
+     * nothing about the EC2 worker rebasing this same tree on shared EFS, which
+     * destroys an in-flight save (`checkout --theirs` overwrites it and the
+     * rebase then reports success; `rebase --abort` hard-resets it). This is the
+     * layer that actually excludes the two.
+     *
+     * Reads deliberately do NOT take it -- an extra EFS round-trip per read is
+     * not an acceptable cost, and reads cannot be destroyed by a rebase.
+     *
+     * Acquisition order is always content lock -> `withLock`, never the reverse,
+     * so the two cannot deadlock.
+     */
+    async withContentWriteExclusion(fn) {
+        try {
+            return await withContentWriteLock(this.root, fn, this.contentWriteLockWaitMs);
+        }
+        catch (err) {
+            // Translate at the boundary, after the bounded wait -- never inside the
+            // acquire loop, which would disable its ELOCKED retry predicate.
+            if (err instanceof ContentWriteLockBusyError)
+                throw new BranchSyncingError(err.message);
+            throw err;
+        }
+    }
     /**
      * Mark the ID index stale so the next idIndex() access rebuilds it from disk.
      *
@@ -222,27 +314,33 @@ export class ContentStore {
         return true;
     }
     /**
-     * Find the file in `dir` whose filename embeds `id`.
-     * Returns its root-relative path, or null if no such file (or no such dir).
+     * Every file in `dir` whose filename embeds `id`, as root-relative paths
+     * (empty when there is no such file, or no such dir).
+     *
+     * [F1] Returns ALL matches, not the first: more than one match is a
+     * duplicate-ID pair, and callers must be able to tell that apart from a
+     * clean single hit rather than silently picking whichever one `readdir()`
+     * happened to yield first.
      */
-    async findEntryPathById(dir, id) {
+    async findEntryPathsById(dir, id) {
         let entries;
         try {
             entries = await fs.readdir(dir, { withFileTypes: true });
         }
         catch (err) {
             if (isNodeError(err) && err.code === 'ENOENT')
-                return null;
+                return [];
             throw err;
         }
+        const matches = [];
         for (const entry of entries) {
             if (entry.isDirectory())
                 continue;
             if (extractIdFromFilename(entry.name) === id) {
-                return path.relative(this.root, path.join(dir, entry.name));
+                matches.push(path.relative(this.root, path.join(dir, entry.name)));
             }
         }
-        return null;
+        return matches.sort();
     }
     /**
      * Get all schema items for iteration.
@@ -609,141 +707,222 @@ export class ContentStore {
         // re-acquire under the current key. Bounded: each flip requires another
         // mutator to have completed in the gap; the cap only guards pathological
         // scheduling.
-        const RETRY_KEY = Symbol('retry-with-new-lock-key');
-        for (let attempt = 0; attempt < 10; attempt++) {
-            const outcome = await withLock(lockKey, async () => {
-                // Re-resolve inside the lock: ground truth after acquisition. A
-                // concurrent renameEntry() may have moved this entry between the
-                // pre-pass above and acquiring this lock.
-                const inLock = await this.buildPaths(schemaItem, slug, {
-                    entryTypeName,
-                    existingId,
-                });
-                const currentKey = this.entryLockKey(schemaItem, slug, inLock);
-                if (currentKey !== lockKey) {
-                    lockKey = currentKey;
-                    return RETRY_KEY;
-                }
-                const { absolutePath, relativePath, id } = inLock;
-                await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-                // OCC: if caller supplied a version token, reject stale writes
-                if (input.expectedVersion !== undefined) {
-                    try {
-                        const existing = await fs.stat(absolutePath);
-                        if (existing.mtimeMs !== input.expectedVersion) {
-                            throw new ContentConflictError();
+        // [SYNC-C1] Cross-host exclusion against the worker's rebase loop wraps
+        // the WHOLE reclassification loop: one acquisition per call, and no
+        // window between attempts where a rebase could start.
+        return this.withContentWriteExclusion(async () => {
+            const RETRY_KEY = Symbol('retry-with-new-lock-key');
+            for (let attempt = 0; attempt < 10; attempt++) {
+                const outcome = await withLock(lockKey, async () => {
+                    // Re-resolve inside the lock: ground truth after acquisition. A
+                    // concurrent renameEntry() may have moved this entry between the
+                    // pre-pass above and acquiring this lock.
+                    const inLock = await this.buildPaths(schemaItem, slug, {
+                        entryTypeName,
+                        existingId,
+                    });
+                    const currentKey = this.entryLockKey(schemaItem, slug, inLock);
+                    if (currentKey !== lockKey) {
+                        lockKey = currentKey;
+                        return RETRY_KEY;
+                    }
+                    const { absolutePath, relativePath, id } = inLock;
+                    // [F1] Duplicate-ID guard. INVARIANT: a write must never remove or
+                    // modify a file it did not address. The post-write index-repair
+                    // step below deletes the ID's previously-indexed path when it
+                    // differs from the one being written ("the slug changed"); that is
+                    // only sound while an ID identifies exactly one file. When a
+                    // duplicate-ID pair is on disk (ContentIdIndex's quarantine, from
+                    // rename-crash debris or a merge) the quarantined file is still
+                    // addressable by collection+slug -- buildPaths() resolves slugs by
+                    // directory scan and knows nothing about the quarantine -- so a
+                    // save to it used to resolve the index to the OTHER file and unlink
+                    // that one: a different document, silently deleted, with the write
+                    // reporting success. Refuse instead (see DuplicateContentIdError).
+                    //
+                    // Runs before any mutation, so a refusal leaves the tree exactly as
+                    // it was. Two independent detections, because neither alone covers
+                    // everything:
+                    //   1. the index's own quarantine record -- catches a duplicate
+                    //      whose other copy lives in a different directory, and the
+                    //      ID-addressed (existingId) shape where the target is a fresh
+                    //      third path; needs the index to have scanned the duplicate.
+                    //   2. disk-verified ambiguity -- both the file we are about to
+                    //      write AND the indexed location exist right now. This one
+                    //      does not depend on index freshness at all, which is what
+                    //      makes the common (slug-addressed) save safe even against an
+                    //      index built before the duplicate landed.
+                    // Neither fires for the ordinary slug-change save of a
+                    // non-duplicated entry: there the indexed path exists but the
+                    // target does not (it is about to be created), so the cleanup
+                    // below still removes exactly the file the caller relocated.
+                    if (id) {
+                        const guardIndex = this._idIndex;
+                        const indexedPath = guardIndex.findById(id)?.relativePath ?? null;
+                        if (indexedPath && indexedPath !== relativePath) {
+                            const quarantined = guardIndex.getDuplicateFor(id);
+                            const bothOnDisk = (await filePathExists(absolutePath)) &&
+                                (await filePathExists(path.join(this.root, indexedPath)));
+                            if (quarantined || bothOnDisk) {
+                                throw new DuplicateContentIdError(id, [
+                                    indexedPath,
+                                    relativePath,
+                                    ...(quarantined?.droppedPaths ?? []),
+                                    ...(quarantined ? [quarantined.keptPath] : []),
+                                ]);
+                            }
                         }
                     }
-                    catch (err) {
-                        if (err instanceof ContentConflictError)
-                            throw err;
-                        if (isNodeError(err) && err.code === 'ENOENT') {
-                            // File doesn't exist yet — first write, skip version check
+                    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+                    // OCC: undefined means no opinion (skip entirely, back-compat blind
+                    // write). A number means "must match this mtime" (stale-write
+                    // rejection). `null` means "must NOT exist yet" — the create-intent
+                    // guard: without this, a create request against a slug that already
+                    // has content falls through to an ordinary blind overwrite (August
+                    // 2026 baseline review, Critical finding). This is the authoritative
+                    // check — it runs inside the per-entry lock against a fresh stat, so
+                    // it holds even if a caller's own pre-write existence check (e.g. the
+                    // API layer's `documentExists`) went stale under concurrency.
+                    if (input.expectedVersion !== undefined) {
+                        try {
+                            const existing = await fs.stat(absolutePath);
+                            if (input.expectedVersion === null) {
+                                throw new ContentConflictError('An entry with this slug already exists');
+                            }
+                            if (existing.mtimeMs !== input.expectedVersion) {
+                                throw new ContentConflictError();
+                            }
                         }
-                        else {
-                            throw err;
+                        catch (err) {
+                            if (err instanceof ContentConflictError)
+                                throw err;
+                            if (isNodeError(err) && err.code === 'ENOENT') {
+                                // File doesn't exist yet: for a numeric expectedVersion this is
+                                // the existing "first write, skip version check" back-compat
+                                // behavior; for expectedVersion === null this is the success
+                                // case (create-only correctly finds no collision) — either way,
+                                // proceed with the write.
+                            }
+                            else {
+                                throw err;
+                            }
                         }
                     }
-                }
-                // Existence guard (cross-process): the caller asserts this entry already
-                // exists (existingId), so if no file is at the path we are about to
-                // write, this store's index may be stale — another process may have
-                // renamed the entry. Recreating a renamed entry's old path would leave
-                // two files with the same embedded ID and poison every subsequent index
-                // rebuild (ID collision). The directory listing is authoritative on this
-                // host: if the ID's actual on-disk location differs from what our index
-                // believes, fail with a conflict so the caller reloads fresh state.
-                // (An intentional slug-change save passes: the index and the directory
-                // agree on the entry's current — old-slug — path. External deletes also
-                // pass: the ID is nowhere on disk, so recreating is last-writer-wins.)
-                //
-                // indexedRelPath reads the LIVE index synchronously — NOT idIndex() —
-                // because idIndex() would run a full rescan while holding the entry
-                // lock if invalidateIndex() fired between the pre-lock warm-up above
-                // and here. The live index may then be stale, but staleness only errs
-                // toward throwing ContentConflictError: actualRelPath comes from the
-                // fresh in-lock directory scan just below (ground truth), so a stale
-                // indexedRelPath can only turn agree->disagree (spurious conflict,
-                // which the caller already handles by reloading), never
-                // disagree->agree. Fail-closed, never fail-open.
-                if (existingId && !(await filePathExists(absolutePath))) {
-                    const actualRelPath = await this.findEntryPathById(path.dirname(absolutePath), existingId);
-                    const indexedRelPath = this._idIndex.findById(existingId)?.relativePath ?? null;
-                    if (actualRelPath !== null && actualRelPath !== indexedRelPath) {
-                        throw new ContentConflictError();
-                    }
-                }
-                // Serialize content string
-                let content;
-                if (input.format === 'json') {
-                    content = `${JSON.stringify(input.data ?? {}, null, 2)}\n`;
-                }
-                else if (input.format === 'yaml') {
-                    content = yamlStringify(input.data ?? {});
-                }
-                else {
-                    content = matter.stringify(input.body, input.data ?? {});
-                }
-                await atomicWriteFile(absolutePath, content);
-                // Update the ID index after a successful write. Look up and mutate the
-                // LIVE index in one synchronous window (no awaits in between): a
-                // concurrent rebuild may have swapped in a fresh instance since the
-                // pre-write snapshot, and updates must land where future lookups go.
-                const liveIndex = this._idIndex;
-                let staleOldAbsPath = null;
-                if (id) {
-                    const existing = liveIndex.findById(id);
-                    if (existing) {
-                        if (existing.relativePath !== relativePath) {
-                            // Slug changed — remember the orphaned old path to delete below
-                            staleOldAbsPath = path.join(this.root, existing.relativePath);
-                            liveIndex.updatePath(existing.id, relativePath);
+                    // Existence guard (cross-process): the caller asserts this entry already
+                    // exists (existingId), so if no file is at the path we are about to
+                    // write, this store's index may be stale — another process may have
+                    // renamed the entry. Recreating a renamed entry's old path would leave
+                    // two files with the same embedded ID and poison every subsequent index
+                    // rebuild (ID collision). The directory listing is authoritative on this
+                    // host: if the ID's actual on-disk location differs from what our index
+                    // believes, fail with a conflict so the caller reloads fresh state.
+                    // (An intentional slug-change save passes: the index and the directory
+                    // agree on the entry's current — old-slug — path. External deletes also
+                    // pass: the ID is nowhere on disk, so recreating is last-writer-wins.)
+                    //
+                    // indexedRelPath reads the LIVE index synchronously — NOT idIndex() —
+                    // because idIndex() would run a full rescan while holding the entry
+                    // lock if invalidateIndex() fired between the pre-lock warm-up above
+                    // and here. The live index may then be stale, but staleness only errs
+                    // toward throwing ContentConflictError: actualRelPath comes from the
+                    // fresh in-lock directory scan just below (ground truth), so a stale
+                    // indexedRelPath can only turn agree->disagree (spurious conflict,
+                    // which the caller already handles by reloading), never
+                    // disagree->agree. Fail-closed, never fail-open.
+                    if (existingId && !(await filePathExists(absolutePath))) {
+                        const actualRelPaths = await this.findEntryPathsById(path.dirname(absolutePath), existingId);
+                        // [F1] Two files in the target directory carry this ID -- a
+                        // duplicate the index has not scanned yet (the guard above asks
+                        // the index; this asks the directory). Which one a single-match
+                        // scan returns is readdir-order-dependent, so it could 409 or
+                        // pass at random, and passing meant the cleanup below unlinked
+                        // one of two indistinguishable documents. Refuse deterministically.
+                        if (actualRelPaths.length > 1) {
+                            throw new DuplicateContentIdError(existingId, actualRelPaths);
+                        }
+                        const actualRelPath = actualRelPaths[0] ?? null;
+                        const indexedRelPath = this._idIndex.findById(existingId)?.relativePath ?? null;
+                        if (actualRelPath !== null && actualRelPath !== indexedRelPath) {
+                            throw new ContentConflictError();
                         }
                     }
+                    // Serialize content string
+                    let content;
+                    if (input.format === 'json') {
+                        content = `${JSON.stringify(input.data ?? {}, null, 2)}\n`;
+                    }
+                    else if (input.format === 'yaml') {
+                        content = yamlStringify(input.data ?? {});
+                    }
                     else {
-                        liveIndex.add({
-                            type: 'entry',
-                            relativePath,
-                            collection: collectionPath,
-                            slug: slug || undefined,
+                        content = matter.stringify(input.body, input.data ?? {});
+                    }
+                    await atomicWriteFile(absolutePath, content);
+                    // Update the ID index after a successful write. Look up and mutate the
+                    // LIVE index in one synchronous window (no awaits in between): a
+                    // concurrent rebuild may have swapped in a fresh instance since the
+                    // pre-write snapshot, and updates must land where future lookups go.
+                    const liveIndex = this._idIndex;
+                    let staleOldAbsPath = null;
+                    if (id) {
+                        const existing = liveIndex.findById(id);
+                        if (existing) {
+                            if (existing.relativePath !== relativePath) {
+                                // Slug changed — remember the orphaned old path to delete
+                                // below. Safe ONLY because the [F1] guard above has already
+                                // established that this ID is not on two files: without it
+                                // this line deletes a document the caller never addressed
+                                // (see DuplicateContentIdError). Do not move, weaken or skip
+                                // that guard while this unlink exists.
+                                staleOldAbsPath = path.join(this.root, existing.relativePath);
+                                liveIndex.updatePath(existing.id, relativePath);
+                            }
+                        }
+                        else {
+                            liveIndex.add({
+                                type: 'entry',
+                                relativePath,
+                                collection: collectionPath,
+                                slug: slug || undefined,
+                            });
+                        }
+                    }
+                    if (staleOldAbsPath) {
+                        await fs.unlink(staleOldAbsPath).catch((err) => {
+                            if (!isNodeError(err) || err.code !== 'ENOENT')
+                                throw err;
                         });
                     }
-                }
-                if (staleOldAbsPath) {
-                    await fs.unlink(staleOldAbsPath).catch((err) => {
-                        if (!isNodeError(err) || err.code !== 'ENOENT')
-                            throw err;
-                    });
-                }
-                await this.recordOwnMutation(liveIndex);
-                const afterStat = await fs.stat(absolutePath);
-                const base = {
-                    collection: schemaItem.logicalPath,
-                    collectionName: schemaItem.name,
-                    relativePath,
-                    absolutePath,
-                    version: afterStat.mtimeMs,
-                };
-                if (input.format === 'json') {
-                    return { ...base, format: 'json', data: input.data ?? {} };
-                }
-                if (input.format === 'yaml') {
-                    return { ...base, format: 'yaml', data: input.data ?? {} };
-                }
-                return {
-                    ...base,
-                    format: input.format,
-                    data: input.data ?? {},
-                    body: input.body,
-                    bodyFieldName: findBodyFieldName(fields),
-                };
-            });
-            if (typeof outcome !== 'symbol')
-                return outcome;
-        }
-        // Ten completed foreign mutations landed in our acquisition gaps in a
-        // row — treat as contention and let the caller reload + retry.
-        throw new ContentConflictError();
+                    await this.recordOwnMutation(liveIndex);
+                    const afterStat = await fs.stat(absolutePath);
+                    const base = {
+                        collection: schemaItem.logicalPath,
+                        collectionName: schemaItem.name,
+                        relativePath,
+                        absolutePath,
+                        version: afterStat.mtimeMs,
+                    };
+                    if (input.format === 'json') {
+                        return { ...base, format: 'json', data: input.data ?? {} };
+                    }
+                    if (input.format === 'yaml') {
+                        return { ...base, format: 'yaml', data: input.data ?? {} };
+                    }
+                    return {
+                        ...base,
+                        format: input.format,
+                        data: input.data ?? {},
+                        body: input.body,
+                        bodyFieldName: findBodyFieldName(fields),
+                    };
+                });
+                if (typeof outcome !== 'symbol')
+                    return outcome;
+            }
+            // Ten completed foreign mutations landed in our acquisition gaps in a
+            // row — treat as contention and let the caller reload + retry.
+            throw new ContentConflictError();
+        });
     }
     /**
      * Read an entry by its ID (UUID).
@@ -883,40 +1062,43 @@ export class ContentStore {
         // the key this slug would resolve to. Re-derive the key from the in-lock
         // ground truth and retry under the corrected key on mismatch, bounded to
         // rule out only pathological scheduling.
-        const RETRY_KEY = Symbol('retry-with-new-lock-key');
-        for (let attempt = 0; attempt < 10; attempt++) {
-            const outcome = await withLock(lockKey, async () => {
-                // Re-resolve inside the lock: ground truth after acquisition. If a
-                // concurrent renameEntry() moved this slug away in the meantime,
-                // buildPaths() no longer finds it here (inLock.existed is false) --
-                // the entry genuinely isn't at this slug anymore, so we fall through
-                // to the unlink below on a freshly generated (nonexistent) path,
-                // preserving the original ENOENT-throwing behavior.
-                const inLock = await this.buildPaths(collection, slug);
-                const currentKey = this.entryLockKey(collection, slug, inLock);
-                if (currentKey !== lockKey) {
-                    lockKey = currentKey;
-                    return RETRY_KEY;
-                }
-                const { absolutePath, relativePath } = inLock;
-                // Delete file
-                await fs.unlink(absolutePath);
-                // Remove from the LIVE index — lookup and mutation in one synchronous
-                // window, since a concurrent rebuild may swap instances across awaits.
-                const liveIndex = this._idIndex;
-                const id = liveIndex.findByPath(relativePath);
-                if (id) {
-                    liveIndex.remove(id);
-                }
-                await this.recordOwnMutation(liveIndex);
-                return undefined;
-            });
-            if (outcome !== RETRY_KEY)
-                return;
-        }
-        // Ten completed foreign mutations landed in our acquisition gaps in a
-        // row — treat as contention and let the caller reload + retry.
-        throw new ContentConflictError();
+        // [SYNC-C1] See write()'s call to withContentWriteExclusion.
+        return this.withContentWriteExclusion(async () => {
+            const RETRY_KEY = Symbol('retry-with-new-lock-key');
+            for (let attempt = 0; attempt < 10; attempt++) {
+                const outcome = await withLock(lockKey, async () => {
+                    // Re-resolve inside the lock: ground truth after acquisition. If a
+                    // concurrent renameEntry() moved this slug away in the meantime,
+                    // buildPaths() no longer finds it here (inLock.existed is false) --
+                    // the entry genuinely isn't at this slug anymore, so we fall through
+                    // to the unlink below on a freshly generated (nonexistent) path,
+                    // preserving the original ENOENT-throwing behavior.
+                    const inLock = await this.buildPaths(collection, slug);
+                    const currentKey = this.entryLockKey(collection, slug, inLock);
+                    if (currentKey !== lockKey) {
+                        lockKey = currentKey;
+                        return RETRY_KEY;
+                    }
+                    const { absolutePath, relativePath } = inLock;
+                    // Delete file
+                    await fs.unlink(absolutePath);
+                    // Remove from the LIVE index — lookup and mutation in one synchronous
+                    // window, since a concurrent rebuild may swap instances across awaits.
+                    const liveIndex = this._idIndex;
+                    const id = liveIndex.findByPath(relativePath);
+                    if (id) {
+                        liveIndex.remove(id);
+                    }
+                    await this.recordOwnMutation(liveIndex);
+                    return undefined;
+                });
+                if (outcome !== RETRY_KEY)
+                    return;
+            }
+            // Ten completed foreign mutations landed in our acquisition gaps in a
+            // row — treat as contention and let the caller reload + retry.
+            throw new ContentConflictError();
+        });
     }
     /**
      * Rename an entry by changing its slug (middle segment of filename).
@@ -976,102 +1158,105 @@ export class ContentStore {
         // On either mismatch, release and retry under the corrected keys rather
         // than renaming the wrong entry under the stale lock -- bounded to rule
         // out only pathological scheduling.
-        const RETRY_KEY = Symbol('retry-with-new-lock-key');
-        for (let attempt = 0; attempt < 10; attempt++) {
-            const outcome = await withLocks([sourceLockKey, destLockKey], async () => {
-                // Re-resolve inside the lock: ground truth after acquisition.
-                const inLock = await this.buildPaths(collection, currentSlug);
-                if (!inLock.existed) {
-                    // Entry genuinely isn't at this slug anymore (e.g. deleted) --
-                    // matches the original access()-based NOT_FOUND behavior.
-                    throw new ContentStoreError(`Entry not found: ${currentSlug}`, 'NOT_FOUND');
-                }
-                const currentSourceKey = this.entryLockKey(collection, currentSlug, inLock);
-                // The dest create-key is purely slug-derived and can't actually
-                // change across attempts, but recompute for uniformity with the
-                // source side.
-                const currentDestKey = this.createLockKey(collection, safeNewSlug);
-                if (currentSourceKey !== sourceLockKey || inLock.id !== sourceId) {
-                    sourceLockKey = currentSourceKey;
+        // [SYNC-C1] See write()'s call to withContentWriteExclusion.
+        return this.withContentWriteExclusion(async () => {
+            const RETRY_KEY = Symbol('retry-with-new-lock-key');
+            for (let attempt = 0; attempt < 10; attempt++) {
+                const outcome = await withLocks([sourceLockKey, destLockKey], async () => {
+                    // Re-resolve inside the lock: ground truth after acquisition.
+                    const inLock = await this.buildPaths(collection, currentSlug);
+                    if (!inLock.existed) {
+                        // Entry genuinely isn't at this slug anymore (e.g. deleted) --
+                        // matches the original access()-based NOT_FOUND behavior.
+                        throw new ContentStoreError(`Entry not found: ${currentSlug}`, 'NOT_FOUND');
+                    }
+                    const currentSourceKey = this.entryLockKey(collection, currentSlug, inLock);
+                    // The dest create-key is purely slug-derived and can't actually
+                    // change across attempts, but recompute for uniformity with the
+                    // source side.
+                    const currentDestKey = this.createLockKey(collection, safeNewSlug);
+                    if (currentSourceKey !== sourceLockKey || inLock.id !== sourceId) {
+                        sourceLockKey = currentSourceKey;
+                        destLockKey = currentDestKey;
+                        sourceId = inLock.id;
+                        return RETRY_KEY;
+                    }
                     destLockKey = currentDestKey;
-                    sourceId = inLock.id;
-                    return RETRY_KEY;
-                }
-                destLockKey = currentDestKey;
-                const { absolutePath: currentPath, relativePath: currentRelPath } = inLock;
-                // Extract entry type name and extension from current filename
-                const currentFilename = path.basename(currentPath);
-                const parts = currentFilename.split('.');
-                if (parts.length < 4) {
-                    throw new ContentStoreError(`Invalid entry filename format: ${currentFilename}`, 'VALIDATION');
-                }
-                const entryTypeName = parts[0];
-                const contentId = parts[parts.length - 2];
-                const ext = `.${parts[parts.length - 1]}`;
-                // Build new filename with new slug
-                const newFilename = `${entryTypeName}.${safeNewSlug}.${contentId}${ext}`;
-                const parentDir = path.dirname(currentPath);
-                const newPath = path.join(parentDir, newFilename);
-                // Check if any file with the new slug already exists (regardless of ID)
-                // This catches same-slug-different-ID conflicts that link() alone cannot prevent
-                try {
-                    const entries = await fs.readdir(parentDir, { withFileTypes: true });
-                    for (const entry of entries) {
-                        if (entry.isDirectory())
-                            continue;
-                        const existingSlug = extractSlugFromFilename(entry.name, entryTypeName);
-                        if (existingSlug === safeNewSlug) {
-                            throw new ContentStoreError(`Entry with slug "${safeNewSlug}" already exists in collection "${collectionPath}"`, 'VALIDATION');
+                    const { absolutePath: currentPath, relativePath: currentRelPath } = inLock;
+                    // Extract entry type name and extension from current filename
+                    const currentFilename = path.basename(currentPath);
+                    const parts = currentFilename.split('.');
+                    if (parts.length < 4) {
+                        throw new ContentStoreError(`Invalid entry filename format: ${currentFilename}`, 'VALIDATION');
+                    }
+                    const entryTypeName = parts[0];
+                    const contentId = parts[parts.length - 2];
+                    const ext = `.${parts[parts.length - 1]}`;
+                    // Build new filename with new slug
+                    const newFilename = `${entryTypeName}.${safeNewSlug}.${contentId}${ext}`;
+                    const parentDir = path.dirname(currentPath);
+                    const newPath = path.join(parentDir, newFilename);
+                    // Check if any file with the new slug already exists (regardless of ID)
+                    // This catches same-slug-different-ID conflicts that link() alone cannot prevent
+                    try {
+                        const entries = await fs.readdir(parentDir, { withFileTypes: true });
+                        for (const entry of entries) {
+                            if (entry.isDirectory())
+                                continue;
+                            const existingSlug = extractSlugFromFilename(entry.name, entryTypeName);
+                            if (existingSlug === safeNewSlug) {
+                                throw new ContentStoreError(`Entry with slug "${safeNewSlug}" already exists in collection "${collectionPath}"`, 'VALIDATION');
+                            }
                         }
                     }
-                }
-                catch (err) {
-                    if (err instanceof ContentStoreError)
+                    catch (err) {
+                        if (err instanceof ContentStoreError)
+                            throw err;
+                        // Ignore filesystem errors (e.g. ENOENT if parent dir doesn't exist)
+                    }
+                    // Use link()+unlink() instead of rename() so a concurrent cross-process rename to the
+                    // exact same destination path fails with EEXIST rather than silently overwriting.
+                    //
+                    // Tradeoff: this is a two-step operation, not a single atomic syscall. If unlink()
+                    // fails after a successful link() (e.g. a transient EFS error), both the old and new
+                    // slug files will exist pointing at the same inode. The ID index will reflect the new
+                    // path, so subsequent reads work, but the orphaned source file will persist until the
+                    // next rename or deletion of that entry. This is an acceptable tradeoff: the EEXIST
+                    // protection on link() prevents silent data loss on concurrent renames, and the
+                    // partial-failure case is detectable and recoverable. Note: write()/delete()/
+                    // renameEntry() now lock on content ID (see idLockKey()), so a concurrent write() or
+                    // delete() targeting this same entry is fully serialized against this rename and
+                    // cannot observe this partial-failure window; only a genuinely separate process
+                    // acting directly on the filesystem without going through this store could.
+                    try {
+                        await fs.link(currentPath, newPath);
+                    }
+                    catch (err) {
+                        if (isNodeError(err) && err.code === 'EEXIST') {
+                            throw new ContentStoreError(`Entry with slug "${safeNewSlug}" already exists in collection "${collectionPath}"`, 'VALIDATION');
+                        }
                         throw err;
-                    // Ignore filesystem errors (e.g. ENOENT if parent dir doesn't exist)
-                }
-                // Use link()+unlink() instead of rename() so a concurrent cross-process rename to the
-                // exact same destination path fails with EEXIST rather than silently overwriting.
-                //
-                // Tradeoff: this is a two-step operation, not a single atomic syscall. If unlink()
-                // fails after a successful link() (e.g. a transient EFS error), both the old and new
-                // slug files will exist pointing at the same inode. The ID index will reflect the new
-                // path, so subsequent reads work, but the orphaned source file will persist until the
-                // next rename or deletion of that entry. This is an acceptable tradeoff: the EEXIST
-                // protection on link() prevents silent data loss on concurrent renames, and the
-                // partial-failure case is detectable and recoverable. Note: write()/delete()/
-                // renameEntry() now lock on content ID (see idLockKey()), so a concurrent write() or
-                // delete() targeting this same entry is fully serialized against this rename and
-                // cannot observe this partial-failure window; only a genuinely separate process
-                // acting directly on the filesystem without going through this store could.
-                try {
-                    await fs.link(currentPath, newPath);
-                }
-                catch (err) {
-                    if (isNodeError(err) && err.code === 'EEXIST') {
-                        throw new ContentStoreError(`Entry with slug "${safeNewSlug}" already exists in collection "${collectionPath}"`, 'VALIDATION');
                     }
-                    throw err;
-                }
-                await fs.unlink(currentPath);
-                // Update the LIVE index — lookup and mutation in one synchronous window,
-                // since a concurrent rebuild may swap instances across awaits.
-                const newRelativePath = path.relative(this.root, newPath);
-                const liveIndex = this._idIndex;
-                const entryId = liveIndex.findByPath(currentRelPath);
-                if (entryId) {
-                    liveIndex.updatePath(entryId, newRelativePath);
-                }
-                await this.recordOwnMutation(liveIndex);
-                // Return new logical path
-                return { newPath: `${collectionPath}/${safeNewSlug}` };
-            });
-            if (typeof outcome !== 'symbol')
-                return outcome;
-        }
-        // Ten completed foreign mutations landed in our acquisition gaps in a
-        // row — treat as contention and let the caller reload + retry.
-        throw new ContentConflictError();
+                    await fs.unlink(currentPath);
+                    // Update the LIVE index — lookup and mutation in one synchronous window,
+                    // since a concurrent rebuild may swap instances across awaits.
+                    const newRelativePath = path.relative(this.root, newPath);
+                    const liveIndex = this._idIndex;
+                    const entryId = liveIndex.findByPath(currentRelPath);
+                    if (entryId) {
+                        liveIndex.updatePath(entryId, newRelativePath);
+                    }
+                    await this.recordOwnMutation(liveIndex);
+                    // Return new logical path
+                    return { newPath: `${collectionPath}/${safeNewSlug}` };
+                });
+                if (typeof outcome !== 'symbol')
+                    return outcome;
+            }
+            // Ten completed foreign mutations landed in our acquisition gaps in a
+            // row — treat as contention and let the caller reload + retry.
+            throw new ContentConflictError();
+        });
     }
     /**
      * List all entries in a collection tree (including subcollections).