@xtrable-ltd/nanoesis 0.1.31 → 0.1.33

package/dist/{chunk-GFQT7BYP.js → chunk-P6NDWIKK.js}

@@ -144,24 +144,51 @@ function parseSortFile(raw) {
 }
 
 // ../engine/src/store/blob-store.ts
+function isConditionalBlobStore(store) {
+  const candidate = store;
+  return typeof candidate.getVersioned === "function" && typeof candidate.putConditional === "function";
+}
 var InMemoryBlobStore = class {
   blobs = /* @__PURE__ */ new Map();
+  /** Per-key version, bumped on every write, so {@link putConditional} can detect a
+   *  concurrent overwrite the same way an ETag does on a real store. */
+  versions = /* @__PURE__ */ new Map();
+  nextVersion = 1;
   constructor(initial) {
     if (initial === void 0) return;
     const encoder = new TextEncoder();
     for (const [key, value] of Object.entries(initial)) {
-      this.blobs.set(key, copy(typeof value === "string" ? encoder.encode(value) : value));
+      this.set(key, copy(typeof value === "string" ? encoder.encode(value) : value));
     }
   }
+  set(key, bytes) {
+    this.blobs.set(key, bytes);
+    const version = this.nextVersion;
+    this.nextVersion += 1;
+    this.versions.set(key, version);
+    return version;
+  }
   async get(key) {
     const value = this.blobs.get(key);
     return value === void 0 ? void 0 : copy(value);
   }
   async put(key, bytes) {
-    this.blobs.set(key, copy(bytes));
+    this.set(key, copy(bytes));
   }
   async delete(key) {
     this.blobs.delete(key);
+    this.versions.delete(key);
+  }
+  async getVersioned(key) {
+    const value = this.blobs.get(key);
+    if (value === void 0) return void 0;
+    return { bytes: copy(value), version: String(this.versions.get(key)) };
+  }
+  async putConditional(key, bytes, expected) {
+    const current = this.versions.get(key);
+    const currentTag = current === void 0 ? null : String(current);
+    if (currentTag !== expected) return void 0;
+    return String(this.set(key, copy(bytes)));
   }
 };
 function copy(bytes) {
@@ -218,6 +245,59 @@ function buildRedirects(rules, liveUrls) {
   return { path: OUTPUT_PATH, contents };
 }
 
+// ../engine/src/content/source.ts
+var NotFoundError = class extends Error {
+  constructor(path) {
+    super(`No such file in content source: ${path}`);
+    this.path = path;
+    this.name = "NotFoundError";
+  }
+  path;
+};
+function normalizePath(path) {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+var InMemoryContentSource = class {
+  files;
+  constructor(files) {
+    this.files = new Map(Object.entries(files).map(([key, value]) => [normalizePath(key), value]));
+  }
+  async readText(path) {
+    const value = this.files.get(normalizePath(path));
+    if (value === void 0) throw new NotFoundError(path);
+    return typeof value === "string" ? value : new TextDecoder().decode(value);
+  }
+  async readBytes(path) {
+    const value = this.files.get(normalizePath(path));
+    if (value === void 0) throw new NotFoundError(path);
+    return typeof value === "string" ? new TextEncoder().encode(value) : value;
+  }
+  async exists(path) {
+    const target = normalizePath(path);
+    if (target === "") return true;
+    if (this.files.has(target)) return true;
+    const prefix = `${target}/`;
+    for (const key of this.files.keys()) {
+      if (key.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+  async list(dir) {
+    const base = normalizePath(dir);
+    const prefix = base === "" ? "" : `${base}/`;
+    const entries = /* @__PURE__ */ new Map();
+    for (const key of this.files.keys()) {
+      if (prefix !== "" && !key.startsWith(prefix)) continue;
+      const rest = key.slice(prefix.length);
+      if (rest === "") continue;
+      const slash = rest.indexOf("/");
+      if (slash === -1) entries.set(rest, "file");
+      else entries.set(rest.slice(0, slash), "dir");
+    }
+    return [...entries].map(([name, kind]) => ({ name, kind })).sort((a, b) => a.name.localeCompare(b.name));
+  }
+};
+
 // ../engine/src/content/loader.ts
 var SORT_FILE = "_sort.json";
 var REDIRECTS_FILE = "_redirects.json";
@@ -249,10 +329,8 @@ async function loadDir(source, dirPath, slug, treePath) {
       if (entry.name === SORT_FILE || entry.name === REDIRECTS_FILE || entry.name === SITE_CONFIG_FILE || !entry.name.endsWith(ITEM_EXT))
         continue;
       const childSlug = entry.name.slice(0, -ITEM_EXT.length);
-      childMap.set(
-        childSlug,
-        await loadItem(source, join(dirPath, entry.name), childSlug, treePath)
-      );
+      const item = await loadItemIfPresent(source, join(dirPath, entry.name), childSlug, treePath);
+      if (item !== void 0) childMap.set(childSlug, item);
     } else {
       if (entry.name === ASSETS_DIR) continue;
       const childPath = join(treePath, entry.name);
@@ -273,6 +351,14 @@ async function loadDir(source, dirPath, slug, treePath) {
     ...sort.defaultTemplate !== void 0 && { defaultTemplate: sort.defaultTemplate }
   };
 }
+async function loadItemIfPresent(source, filePath, slug, parentPath2) {
+  try {
+    return await loadItem(source, filePath, slug, parentPath2);
+  } catch (error) {
+    if (error instanceof NotFoundError) return void 0;
+    throw error;
+  }
+}
 async function loadItem(source, filePath, slug, parentPath2) {
   const raw = await source.readText(filePath);
   try {
@@ -352,7 +438,11 @@ async function loadComponentFiles(source, componentsDir, extension) {
         await walk(full);
       } else if (entry.name.endsWith(suffix)) {
         const key = entry.name.slice(0, -suffix.length).toLowerCase();
-        map.set(key, await source.readText(full));
+        try {
+          map.set(key, await source.readText(full));
+        } catch (error) {
+          if (!(error instanceof NotFoundError)) throw error;
+        }
       }
     }
   };
@@ -810,6 +900,9 @@ function emptyIndex() {
 async function loadIndex(store) {
   const live = parseIndex(await store.get(INDEX_KEY));
   if (live !== void 0) return live;
+  return recoverFromBackups(store);
+}
+async function recoverFromBackups(store) {
   let best;
   for (let slot = 0; slot < BACKUP_RING_SIZE; slot += 1) {
     const candidate = parseIndex(await store.get(backupKey(slot)));
@@ -819,6 +912,18 @@ async function loadIndex(store) {
   }
   return best ?? emptyIndex();
 }
+async function loadIndexVersioned(store) {
+  const live = await store.getVersioned(INDEX_KEY);
+  if (live === void 0) return { index: await recoverFromBackups(store), version: null };
+  const parsed = parseIndex(live.bytes);
+  return { index: parsed ?? await recoverFromBackups(store), version: live.version };
+}
+async function saveIndexConditional(store, prev, nextKeys) {
+  await store.put(backupKey(prev.index.version % BACKUP_RING_SIZE), serialize2(prev.index));
+  const next = freezeIndex(prev.index.version + 1, nextKeys);
+  const version = await store.putConditional(INDEX_KEY, serialize2(next), prev.version);
+  return version === void 0 ? void 0 : { index: next, version };
+}
 async function saveIndex(store, prev, nextKeys) {
   await store.put(backupKey(prev.version % BACKUP_RING_SIZE), serialize2(prev));
   const next = freezeIndex(prev.version + 1, nextKeys);
@@ -916,6 +1021,47 @@ var IndexedStore = class {
       }
     })();
   }
+  /**
+   * Apply a key-set change to the index and persist it (DESIGN §11d). `mutate` receives the
+   * current key set and adds/removes in place; it must be a pure function of that set (it can
+   * be re-run on a fresh read), because on a store with the optimistic-concurrency capability
+   * this runs as a compare-and-set retry loop: read the live index + version, apply `mutate`,
+   * write only if the version is unchanged, and retry on a conflict. This is what stops a
+   * second host instance's blind overwrite from evicting a key this one just added
+   * (NANOESIS-MCP-ISSUES Issue 1). A store without the capability keeps the single-writer
+   * path, correct under the in-process {@link mutationLock} alone. Either way an unchanged key
+   * set writes nothing (overwriting an existing item stays a single blob `put`).
+   *
+   * Callers do their blob writes/deletes first (content-first, §11d) and pass only the
+   * resulting index delta here, so a failed blob op never advances the index.
+   */
+  async commitIndex(mutate) {
+    const store = this.store;
+    if (isConditionalBlobStore(store)) {
+      for (let attempt = 0; attempt < MAX_INDEX_CAS_ATTEMPTS; attempt += 1) {
+        const current = await loadIndexVersioned(store);
+        const keys2 = new Set(current.index.keys);
+        mutate(keys2);
+        if (sameKeySet(keys2, current.index.keys)) {
+          this.index = current.index;
+          return;
+        }
+        const saved = await saveIndexConditional(store, current, [...keys2]);
+        if (saved !== void 0) {
+          this.index = saved.index;
+          return;
+        }
+      }
+      throw new Error(
+        "content index: too many concurrent modifications; retry the operation (the index could not be saved after repeated conflicts)"
+      );
+    }
+    const index = await this.loaded();
+    const keys = new Set(index.keys);
+    mutate(keys);
+    if (sameKeySet(keys, index.keys)) return;
+    this.index = await saveIndex(this.store, index, [...keys]);
+  }
   async list(dir) {
     return childrenOf((await this.loaded()).keys, dir);
   }
@@ -924,7 +1070,7 @@ var IndexedStore = class {
   }
   async readBytes(path) {
     const bytes = await this.store.get(path);
-    if (bytes === void 0) throw new Error(`No such file in content source: ${path}`);
+    if (bytes === void 0) throw new NotFoundError(path);
     return bytes;
   }
   async exists(path) {
@@ -965,8 +1111,8 @@ var IndexedStore = class {
         schemaDelta = computeSchemaDelta(oldFields, newFields);
         const destructive = schemaDelta.removed.length > 0 || schemaDelta.typeChanged.some((change) => change.destructive);
         if (destructive) {
-          const index2 = await this.loaded();
-          const siblings = index2.keys.filter((k) => k.startsWith(`${stampCandidate.dir}/`) && k.endsWith(".html")).map((k) => k.slice(stampCandidate.dir.length + 1, -".html".length));
+          const index = await this.loaded();
+          const siblings = index.keys.filter((k) => k.startsWith(`${stampCandidate.dir}/`) && k.endsWith(".html")).map((k) => k.slice(stampCandidate.dir.length + 1, -".html".length));
           const version = nextVersionNumber(siblings);
           stampDecision = {
             snapshotPath: `${stampCandidate.dir}/${stampCandidate.name}@v${version}.html`,
@@ -976,22 +1122,13 @@ var IndexedStore = class {
         }
       }
       await this.store.put(target, bytes);
-      const index = await this.loaded();
-      let nextIndex = index;
-      if (!nextIndex.keys.includes(target)) {
-        nextIndex = await saveIndex(this.store, nextIndex, [...nextIndex.keys, target]);
-      }
       let stamped;
       let stampIncomplete;
+      let snapshotToIndex;
       if (stampDecision !== void 0) {
         try {
           await this.store.put(stampDecision.snapshotPath, stampDecision.bytes);
-          if (!nextIndex.keys.includes(stampDecision.snapshotPath)) {
-            nextIndex = await saveIndex(this.store, nextIndex, [
-              ...nextIndex.keys,
-              stampDecision.snapshotPath
-            ]);
-          }
+          snapshotToIndex = stampDecision.snapshotPath;
           stamped = {
             name: stampCandidate.name,
             version: stampDecision.version,
@@ -1001,7 +1138,10 @@ var IndexedStore = class {
           stampIncomplete = true;
         }
       }
-      this.index = nextIndex;
+      await this.commitIndex((keys) => {
+        keys.add(target);
+        if (snapshotToIndex !== void 0) keys.add(snapshotToIndex);
+      });
       let parseDiagnostics;
       if (isContentItemPath(target)) {
         parseDiagnostics = contentParseDiagnosticsFor(bytes);
@@ -1037,11 +1177,7 @@ var IndexedStore = class {
       const version = nextVersionNumber(siblings);
       const snapshotPath = `${dir}/${name}@v${version}.html`;
       await this.store.put(snapshotPath, bytes);
-      if (!index.keys.includes(snapshotPath)) {
-        this.index = await saveIndex(this.store, index, [...index.keys, snapshotPath]);
-      } else {
-        this.index = index;
-      }
+      await this.commitIndex((keys) => keys.add(snapshotPath));
       return { name, version, snapshotPath };
     });
   }
@@ -1061,8 +1197,11 @@ var IndexedStore = class {
         return;
       }
       await Promise.all(removed.map((k) => this.store.delete(k)));
-      const remaining = index.keys.filter((k) => k !== target && !k.startsWith(prefix));
-      this.index = await saveIndex(this.store, index, remaining);
+      await this.commitIndex((keys) => {
+        for (const k of [...keys]) {
+          if (k === target || k.startsWith(prefix)) keys.delete(k);
+        }
+      });
     });
   }
   /**
@@ -1099,8 +1238,10 @@ var IndexedStore = class {
         await this.store.delete(move.from);
       }
       const movedFrom = new Set(moves.map((move) => move.from));
-      const next = index.keys.filter((k) => !movedFrom.has(k)).concat(moves.map((m) => m.to));
-      this.index = await saveIndex(this.store, index, next);
+      await this.commitIndex((keys) => {
+        for (const from2 of movedFrom) keys.delete(from2);
+        for (const move of moves) keys.add(move.to);
+      });
       return { ok: true };
     });
   }
@@ -1143,6 +1284,12 @@ function contentParseDiagnosticsFor(bytes) {
     return void 0;
   }
 }
+var MAX_INDEX_CAS_ATTEMPTS = 50;
+function sameKeySet(set, sorted) {
+  if (set.size !== sorted.length) return false;
+  for (const key of sorted) if (!set.has(key)) return false;
+  return true;
+}
 function guarded(key) {
   if (key === "" || key.startsWith(RESERVED_PREFIX)) {
     throw new Error(`Refusing to mutate a reserved key: ${key === "" ? "(root)" : key}`);
@@ -1174,51 +1321,6 @@ function pathExists(keys, path) {
   return keys.some((key) => key.startsWith(prefix));
 }
 
-// ../engine/src/content/source.ts
-function normalizePath(path) {
-  return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
-}
-var InMemoryContentSource = class {
-  files;
-  constructor(files) {
-    this.files = new Map(Object.entries(files).map(([key, value]) => [normalizePath(key), value]));
-  }
-  async readText(path) {
-    const value = this.files.get(normalizePath(path));
-    if (value === void 0) throw new Error(`No such file in content source: ${path}`);
-    return typeof value === "string" ? value : new TextDecoder().decode(value);
-  }
-  async readBytes(path) {
-    const value = this.files.get(normalizePath(path));
-    if (value === void 0) throw new Error(`No such file in content source: ${path}`);
-    return typeof value === "string" ? new TextEncoder().encode(value) : value;
-  }
-  async exists(path) {
-    const target = normalizePath(path);
-    if (target === "") return true;
-    if (this.files.has(target)) return true;
-    const prefix = `${target}/`;
-    for (const key of this.files.keys()) {
-      if (key.startsWith(prefix)) return true;
-    }
-    return false;
-  }
-  async list(dir) {
-    const base = normalizePath(dir);
-    const prefix = base === "" ? "" : `${base}/`;
-    const entries = /* @__PURE__ */ new Map();
-    for (const key of this.files.keys()) {
-      if (prefix !== "" && !key.startsWith(prefix)) continue;
-      const rest = key.slice(prefix.length);
-      if (rest === "") continue;
-      const slash = rest.indexOf("/");
-      if (slash === -1) entries.set(rest, "file");
-      else entries.set(rest.slice(0, slash), "dir");
-    }
-    return [...entries].map(([name, kind]) => ({ name, kind })).sort((a, b) => a.name.localeCompare(b.name));
-  }
-};
-
 // ../engine/src/url/references.ts
 var REFERENCE_PREFIX = "ref:";
 function referenceTarget(value) {
@@ -2802,6 +2904,9 @@ async function validateSite(source) {
   }
   const shellRequiredFields = shellAnalysis?.requiredFields ?? [];
   const shellConstraints = shellAnalysis?.constraints ?? /* @__PURE__ */ new Map();
+  const shellFieldNames = new Set(
+    documentShell !== void 0 ? deriveFields(documentShell, components).map((f) => f.name) : []
+  );
   const diagnostics = [];
   const add = (severity, code, message, path) => {
     diagnostics.push({ severity, code, message, ...path !== void 0 && { path } });
@@ -2970,7 +3075,9 @@ async function validateSite(source) {
     if (!isVersionedTemplateName(templateName)) {
       const expectedFields = expectedFieldsFor(templateName);
       const itemFieldNames = Object.keys(node.item.fields);
-      const orphans = itemFieldNames.filter((name) => !expectedFields.has(name));
+      const orphans = itemFieldNames.filter(
+        (name) => !expectedFields.has(name) && !shellFieldNames.has(name)
+      );
       if (orphans.length > 0) {
         add(
           "warning",
@@ -3212,13 +3319,20 @@ async function publishSite(source, sink, options = {}) {
   );
   const byPath = /* @__PURE__ */ new Map();
   for (const artifact of [...stamped, ...passthrough]) byPath.set(artifact.path, artifact);
+  const everything = [...byPath.values()];
+  const pages = everything.filter((artifact) => artifact.path.endsWith(".html"));
+  const resources = everything.filter((artifact) => !artifact.path.endsWith(".html"));
   const uploadTotal = byPath.size;
   let uploaded = 0;
-  await mapWithConcurrency([...byPath.values()], writeConcurrency, async (artifact) => {
-    await sink.write(artifact.path, artifact.contents, cacheControlFor(artifact));
-    uploaded += 1;
-    onProgress?.({ phase: "upload", written: uploaded, total: uploadTotal });
-  });
+  const writeGroup = async (group) => {
+    await mapWithConcurrency(group, writeConcurrency, async (artifact) => {
+      await sink.write(artifact.path, artifact.contents, cacheControlFor(artifact));
+      uploaded += 1;
+      onProgress?.({ phase: "upload", written: uploaded, total: uploadTotal });
+    });
+  };
+  await writeGroup(resources);
+  await writeGroup(pages);
   if (purge !== noopPurgeService) onProgress?.({ phase: "purge" });
   await purge.purgeAll();
   onProgress?.({ phase: "done", written: uploadTotal, summary });
@@ -3472,9 +3586,12 @@ export {
   ContentParseError,
   parseContentItem,
   parseSortFile,
+  isConditionalBlobStore,
   InMemoryBlobStore,
   parseRedirects,
   buildRedirects,
+  NotFoundError,
+  InMemoryContentSource,
   DEFAULT_DIRS,
   loadContentTree,
   loadRedirects,
@@ -3504,10 +3621,11 @@ export {
   RESERVED_PREFIX,
   emptyIndex,
   loadIndex,
+  loadIndexVersioned,
+  saveIndexConditional,
   saveIndex,
   reconcileIndex,
   IndexedStore,
-  InMemoryContentSource,
   analyzeTemplate,
   pendingMigrations,
   bestFitSnapshot,

package/dist/editor-api.d.ts

@@ -222,7 +222,12 @@ interface EditorConfig {
     readonly prebuild?: PreBuildHook | (() => Promise<PreBuildHook | undefined>);
     /** Admin diagnostics/self-heal; defaults to {@link buildDefaultDiagnostics}. */
     readonly diagnostics?: DiagnosticRegistry;
-    /** Clear the website before republishing (default true). Needs `website.wipe`. */
+    /**
+     * Whether a publish clears pages the new build no longer emits (default true). A
+     * `prune`-capable website does this as a post-publish orphan sweep (overwrite-in-place,
+     * zero downtime); a wipe-only website clears up front instead. Set false to never delete
+     * (overwrite-only, stale pages linger). Names `wipeBeforePublish` for back-compat.
+     */
     readonly wipeBeforePublish?: boolean;
 }
 /** A wired editor: mount {@link handleApi} at `/api/*` and call {@link publish} to go live. */
@@ -244,12 +249,13 @@ interface Editor {
  * Wire a complete nanoesis editor from a storage pair, a login, and a few optional
  * capabilities. This is the whole integration surface (DESIGN §11c): everything that used
  * to be hand-assembled per host, the content index over the store, the publish source/sink,
- * index reconcile, the wipe-before-publish, and the {@link ApiDeps} bag, is built here, so
+ * index reconcile, the orphan sweep, and the {@link ApiDeps} bag, is built here, so
  * internals (`IndexedStore`, `ArtifactSink`, reconcile plumbing) never reach the adopter.
  *
- * `publish()` validates **before** it wipes: an invalid site returns its errors and never
- * touches the live files, so a failed publish can never blank the website (the footgun the
- * old "host wipes, then publishes" wiring carried).
+ * `publish()` validates **first**: an invalid site returns its errors and never touches the
+ * live files. A `prune`-capable website then overwrites every artifact in place and sweeps
+ * the orphans afterwards, so a publish never blanks the live site, not even for the upload
+ * window (the footgun the old "host wipes, then publishes" wiring carried).
  */
 declare function createEditor(config: EditorConfig): Editor;
 /**

package/dist/editor-api.js

@@ -21,8 +21,8 @@ import {
   serveEditorAsset,
   templateSnapshotIntegrityDiagnostic,
   templateSuffixConflictDiagnostic
-} from "./chunk-BCWZRKMF.js";
-import "./chunk-GFQT7BYP.js";
+} from "./chunk-C3QPGXG5.js";
+import "./chunk-P6NDWIKK.js";
 export {
   FileBrandingStore,
   InMemoryBrandingStore,

package/dist/index.d.ts

@@ -158,6 +158,37 @@ interface BlobStore {
     /** Remove `key`. Deleting an absent key is a no-op (idempotent). */
     delete(key: string): Promise<void>;
 }
+/**
+ * Optional optimistic-concurrency capability a {@link BlobStore} may also implement
+ * (DESIGN §11d). It exists for exactly one blob: the content index, which is mutated by
+ * read-modify-write. With a single writer the in-process mutex on `IndexedStore` is enough,
+ * but a horizontally-scaled host (e.g. Azure Consumption spinning a second instance under
+ * load) runs two writers against one index blob, and a blind overwrite there loses updates,
+ * one instance's `saveIndex` evicts a key the other just added, though its content blob is
+ * fine (the "files exist but missing from the index" churn, NANOESIS-MCP-ISSUES Issue 1).
+ *
+ * When a store implements this, `IndexedStore` performs a compare-and-set on the index:
+ * read the current version, re-apply its key delta, write only if the version is unchanged,
+ * and retry on a conflict. A store without it (a `Map`, a folder) keeps the blind path,
+ * single-process hosts neither need nor pay for the capability. It is therefore an *optional*
+ * add-on, like {@link Storage.wipe}: the minimal adopter surface stays get/put/delete.
+ */
+interface ConditionalBlobStore {
+    /** The bytes at `key` plus an opaque version tag (e.g. an ETag), or `undefined` if absent. */
+    getVersioned(key: string): Promise<{
+        bytes: Uint8Array;
+        version: string;
+    } | undefined>;
+    /**
+     * Write `key` only if its current version matches `expected` (or, when `expected` is
+     * `null`, only if the key does not yet exist). Resolves to the new version on success, or
+     * `undefined` when the precondition failed because another writer got there first, the
+     * signal for the caller to re-read and retry. A non-precondition failure still rejects.
+     */
+    putConditional(key: string, bytes: Uint8Array, expected: string | null): Promise<string | undefined>;
+}
+/** Whether a {@link BlobStore} also offers the optimistic-concurrency capability. */
+declare function isConditionalBlobStore(store: BlobStore): store is BlobStore & ConditionalBlobStore;
 /**
  * The single storage contract an adopter implements (DESIGN §11c): a {@link BlobStore}
  * (get/put/delete) plus an optional {@link wipe}. The same shape backs both the editor's
@@ -173,6 +204,17 @@ interface Storage extends BlobStore {
      * (and so cannot clear itself) omits it; the publish then only overwrites.
      */
     wipe?(): Promise<void>;
+    /**
+     * Optional: delete every key **not** in `keep`, leaving the kept keys untouched. The
+     * zero-downtime alternative to {@link wipe} for a published website: the host overwrites
+     * every artifact in place (each key flips old→new atomically, so no URL is ever missing),
+     * then calls `prune` with the just-written path set to sweep only the orphans, pages that
+     * no longer exist. Unlike `wipe` (clear *before* the upload, blanking the live site for the
+     * whole write), `prune` runs *after* a successful upload and only removes what the new
+     * publish did not write. A store that cannot enumerate omits it; the host falls back to
+     * `wipe`, or to overwrite-only when neither is available.
+     */
+    prune?(keep: ReadonlySet<string>): Promise<void>;
 }
 /**
  * In-memory {@link BlobStore} backed by a plain map, the test double the engine's
@@ -180,12 +222,22 @@ interface Storage extends BlobStore {
  * interchangeable). It copies bytes in and out, so a caller can never mutate stored
  * data by holding on to a buffer.
  */
-declare class InMemoryBlobStore implements BlobStore {
+declare class InMemoryBlobStore implements BlobStore, ConditionalBlobStore {
     private readonly blobs;
+    /** Per-key version, bumped on every write, so {@link putConditional} can detect a
+     *  concurrent overwrite the same way an ETag does on a real store. */
+    private readonly versions;
+    private nextVersion;
     constructor(initial?: Readonly<Record<string, Uint8Array | string>>);
+    private set;
     get(key: string): Promise<Uint8Array | undefined>;
     put(key: string, bytes: Uint8Array): Promise<void>;
     delete(key: string): Promise<void>;
+    getVersioned(key: string): Promise<{
+        bytes: Uint8Array;
+        version: string;
+    } | undefined>;
+    putConditional(key: string, bytes: Uint8Array, expected: string | null): Promise<string | undefined>;
 }
 
 /**
@@ -195,6 +247,17 @@ declare class InMemoryBlobStore implements BlobStore {
  * relative to the site root (e.g. "content/blog/post.json").
  */
 type EntryKind = 'file' | 'dir';
+/**
+ * Thrown by a {@link ContentSource} read when the path does not exist, as opposed to a
+ * real I/O failure (a network error, a permission error). Loaders catch *this* to tell
+ * index drift (a key the index lists but whose blob is gone) apart from an error they must
+ * not swallow: a listed-but-missing item is skipped, a genuine read failure still
+ * propagates. Carries the requested path for diagnostics.
+ */
+declare class NotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
 interface DirEntry {
     readonly name: string;
     readonly kind: EntryKind;
@@ -874,6 +937,28 @@ declare function emptyIndex(): ContentIndex;
  * but cannot be enumerated until something rewrites the index).
  */
 declare function loadIndex(store: BlobStore): Promise<ContentIndex>;
+/** The index paired with the live index blob's version tag, for a compare-and-set save
+ *  (DESIGN §11d). `version` is `null` when no live index blob exists yet, so the first save
+ *  creates it (`putConditional` with `expected: null`). */
+interface VersionedIndex {
+    readonly index: ContentIndex;
+    readonly version: string | null;
+}
+/**
+ * Load the index together with the version tag needed to write it back safely under
+ * optimistic concurrency. A present-but-corrupt live blob recovers from the backup ring but
+ * keeps the live version, so the next {@link saveIndexConditional} overwrites the corrupt
+ * copy rather than failing forever; an absent live blob recovers read-only with `version:
+ * null`.
+ */
+declare function loadIndexVersioned(store: BlobStore & ConditionalBlobStore): Promise<VersionedIndex>;
+/**
+ * Compare-and-set save (DESIGN §11d): back up the index being replaced (best-effort,
+ * unconditional), then write the new index *only if* the live version still matches the one
+ * read in `prev`. Returns the new {@link VersionedIndex} on success, or `undefined` when a
+ * concurrent writer won the race, the caller re-reads and re-applies its delta, then retries.
+ */
+declare function saveIndexConditional(store: BlobStore & ConditionalBlobStore, prev: VersionedIndex, nextKeys: readonly string[]): Promise<VersionedIndex | undefined>;
 /**
  * Write a new index whose keys are `nextKeys`, backing up the one it replaces first
  * (DESIGN §11d). The previous index goes into its ring slot (`version % ring`, oldest
@@ -943,6 +1028,21 @@ declare class IndexedStore implements WorkingStore {
     /** The index, loaded once on first need and cached (mutations replace the cached copy). */
     private loaded;
     private serializeMutation;
+    /**
+     * Apply a key-set change to the index and persist it (DESIGN §11d). `mutate` receives the
+     * current key set and adds/removes in place; it must be a pure function of that set (it can
+     * be re-run on a fresh read), because on a store with the optimistic-concurrency capability
+     * this runs as a compare-and-set retry loop: read the live index + version, apply `mutate`,
+     * write only if the version is unchanged, and retry on a conflict. This is what stops a
+     * second host instance's blind overwrite from evicting a key this one just added
+     * (NANOESIS-MCP-ISSUES Issue 1). A store without the capability keeps the single-writer
+     * path, correct under the in-process {@link mutationLock} alone. Either way an unchanged key
+     * set writes nothing (overwriting an existing item stays a single blob `put`).
+     *
+     * Callers do their blob writes/deletes first (content-first, §11d) and pass only the
+     * resulting index delta here, so a failed blob op never advances the index.
+     */
+    private commitIndex;
     list(dir: string): Promise<readonly DirEntry[]>;
     readText(path: string): Promise<string>;
     readBytes(path: string): Promise<Uint8Array>;
@@ -1870,4 +1970,4 @@ declare function createDiagnosticRegistry(): DiagnosticRegistry;
 
 declare const workingStoreRoundTripDiagnostic: Diagnostic;
 
-export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, CACHE_IMMUTABLE, CACHE_REVALIDATE, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type MigrationResolution, type PageEntry, type PendingMigrationItem, type PendingMigrations, type PreBuildHook, type Principal, type ProgressReporter, type ProgressSummary, type PublishOptions, type PublishPlan, type PublishProgress, type PublishResource, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type RepairArgs, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type SchemaDelta, type SchemaFieldRef, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type StampDecision, type StampRecord, type Storage, type TemplateAnalysis, type TemplateKind, type TokenContext, type TokenRef, type TreeNode, type TypeChange, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, applyMigration, baseTemplateName, bestFitSnapshot, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, cacheControlFor, canEdit, compilePage, compileSite, compileTemplate, computeSchemaDelta, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, detectStamp, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isDestructiveTypeChange, isFieldType, isReservedVersionedPath, isVersionedTemplateName, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, nextVersionNumber, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, pendingMigrations, planPublish, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, snapshotName, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, versionNumber, wholeValueToken, workingStoreRoundTripDiagnostic };
+export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, CACHE_IMMUTABLE, CACHE_REVALIDATE, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ConditionalBlobStore, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type MigrationResolution, NotFoundError, type PageEntry, type PendingMigrationItem, type PendingMigrations, type PreBuildHook, type Principal, type ProgressReporter, type ProgressSummary, type PublishOptions, type PublishPlan, type PublishProgress, type PublishResource, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type RepairArgs, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type SchemaDelta, type SchemaFieldRef, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type StampDecision, type StampRecord, type Storage, type TemplateAnalysis, type TemplateKind, type TokenContext, type TokenRef, type TreeNode, type TypeChange, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type VersionedIndex, type WorkingStore, analyzeTemplate, applyMigration, baseTemplateName, bestFitSnapshot, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, cacheControlFor, canEdit, compilePage, compileSite, compileTemplate, computeSchemaDelta, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, detectStamp, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isConditionalBlobStore, isDestructiveTypeChange, isFieldType, isReservedVersionedPath, isVersionedTemplateName, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadIndexVersioned, loadRedirects, loadSiteConfig, loadTemplate, nextVersionNumber, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, pendingMigrations, planPublish, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, saveIndexConditional, slugify, snapshotName, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, versionNumber, wholeValueToken, workingStoreRoundTripDiagnostic };