wiki-graph-sdk 0.8.4 → 0.9.1

package/dist/index.js

@@ -11,7 +11,9 @@ import { Readable as Readable2 } from "stream";
 import {
   addChapter,
   applyChapterTree,
-  assertArchiveIndexArtifactsReady,
+  assertArchiveQueryReady,
+  resolveIndexedArchiveChapterScope,
+  ensureWikiGraphArchiveSchemaCurrent,
   assertNoActiveBuildJobConflicts,
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
@@ -43,6 +45,7 @@ import {
   getChapterTree,
   WikiGraph as WikiGraph2,
   WikiGraphArchiveFile as WikiGraphArchiveFile2,
+  WikiGraphDirectoryFile as WikiGraphDirectoryFile2,
   TOC_FILE_VERSION,
   writeWikgArchive,
   ObjectMetadataKind
@@ -161,6 +164,15 @@ var NodeFile = class {
     this.name = name;
   }
   path;
+  async getPhysicalIdentity() {
+    const value = await fsPromises.stat(this.path).catch((error) => {
+      if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+        return void 0;
+      throw error;
+    });
+    if (value === void 0) return void 0;
+    return `${value.dev}:${value.ino}`;
+  }
   kind = "file";
   [NODE_RESOURCE_KIND] = "file";
   identity;
@@ -285,6 +297,15 @@ var NodeDirectory = class _NodeDirectory {
     this.name = pathModule.basename(path);
   }
   path;
+  async getPhysicalIdentity() {
+    const value = await fsPromises.stat(this.path).catch((error) => {
+      if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+        return void 0;
+      throw error;
+    });
+    if (value === void 0) return void 0;
+    return `${value.dev}:${value.ino}`;
+  }
   kind = "directory";
   [NODE_RESOURCE_KIND] = "directory";
   identity;
@@ -294,8 +315,10 @@ var NodeDirectory = class _NodeDirectory {
     const file = new NodeFile(pathModule.join(this.path, name));
     try {
       return (await fsPromises.stat(file.path)).isFile() ? file : void 0;
-    } catch {
-      return void 0;
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+        return void 0;
+      throw error;
     }
   }
   async getLastModified() {
@@ -313,8 +336,10 @@ var NodeDirectory = class _NodeDirectory {
     const directory = new _NodeDirectory(pathModule.join(this.path, name));
     try {
       return (await fsPromises.stat(directory.path)).isDirectory() ? directory : void 0;
-    } catch {
-      return void 0;
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+        return void 0;
+      throw error;
     }
   }
   async list() {
@@ -438,14 +463,23 @@ async function openNativeNodeDatabase(file, flags) {
     });
   });
 }
-async function openNodeZip(file) {
+async function openNodeZip(file, options = {}) {
   const path = getBrandedNodeResourcePath(file, "file");
   if (path === void 0) {
     throw new TypeError("The Node ZIP adapter requires a NodeFile");
   }
-  const zipFile = await new Promise((resolve4, reject) => {
-    yauzl.open(
-      path,
+  const handle = await fsPromises.open(path, "r");
+  let size;
+  try {
+    size = (await handle.stat()).size;
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+  const open2 = () => new Promise((resolve4, reject) => {
+    yauzl.fromRandomAccessReader(
+      new NodeZipSource(handle),
+      size,
       { autoClose: false, lazyEntries: true },
       (error, opened) => {
         if (error || opened === void 0)
@@ -454,63 +488,192 @@ async function openNodeZip(file) {
       }
     );
   });
-  const entries = await new Promise(
-    (resolve4, reject) => {
-      const discovered = /* @__PURE__ */ new Map();
-      const rejectAndClose = (error) => {
-        zipFile.close();
-        reject(
-          error instanceof Error ? error : new Error("Cannot scan ZIP central directory")
-        );
-      };
-      const resolveEntries = () => {
-        zipFile.off("error", rejectAndClose);
-        resolve4(discovered);
-      };
-      zipFile.on("entry", (entry) => {
-        if (!entry.fileName.endsWith("/")) {
-          discovered.set(entry.fileName, entry);
-        }
-        zipFile.readEntry();
-      });
-      zipFile.once("error", rejectAndClose);
-      zipFile.once("end", resolveEntries);
-      zipFile.readEntry();
-    }
-  );
+  try {
+    (await open2()).close();
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
   let closed = false;
+  let pending = Promise.resolve();
+  let closing;
+  const run = (operation) => {
+    if (closed)
+      return Promise.reject(new Error("Cannot read a closed ZIP archive"));
+    const result = pending.then(async () => {
+      const zip = await open2();
+      try {
+        return await operation(zip);
+      } finally {
+        zip.close();
+      }
+    });
+    pending = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  };
+  const withEntry = (name, operation) => run(async (zip) => {
+    let exact;
+    let alias;
+    let aliasCollision = false;
+    await scanNodeZip(zip, (entry) => {
+      if (entry.fileName === name) exact = entry;
+      if (normalizeNodeZipName(entry.fileName) === name) {
+        if (alias !== void 0 && alias.fileName !== entry.fileName)
+          aliasCollision = true;
+        alias = entry;
+      }
+    });
+    if ((exact === void 0 || options.entryNameMode === "normalized") && aliasCollision) {
+      let bestPosition = -1;
+      const candidates = await open2();
+      try {
+        await scanNodeZip(candidates, async (entry) => {
+          if (normalizeNodeZipName(entry.fileName) !== name) return;
+          const probe = await open2();
+          let position = 0;
+          try {
+            await scanNodeZip(probe, (candidate) => {
+              if (candidate.fileName === entry.fileName) return false;
+              position++;
+            });
+          } finally {
+            probe.close();
+          }
+          if (position >= bestPosition) {
+            bestPosition = position;
+            alias = entry;
+          }
+        });
+        return await operation(candidates, alias);
+      } finally {
+        candidates.close();
+      }
+    }
+    return await operation(
+      zip,
+      options.entryNameMode === "normalized" ? alias : exact ?? alias
+    );
+  });
   return {
     close: () => {
-      if (!closed) zipFile.close();
       closed = true;
-      return Promise.resolve();
+      closing ??= pending.then(() => handle.close());
+      return closing;
     },
-    copyEntry: async (name, target) => {
-      if (closed) throw new Error("Cannot read a closed ZIP archive");
-      const entry = entries.get(name);
+    copyEntry: (name, target) => withEntry(name, async (zip, entry) => {
       if (entry === void 0) return false;
-      await copyNodeZipEntry(zipFile, entry, target);
+      await copyNodeZipEntry(zip, entry, target);
       return true;
-    },
-    getEntrySize: (name) => {
-      if (closed) throw new Error("Cannot read a closed ZIP archive");
-      return Promise.resolve(entries.get(name)?.uncompressedSize);
-    },
-    listEntries: () => Promise.resolve([...entries.keys()]),
-    readEntryRange: async (name, offset, length) => {
-      if (closed) throw new Error("Cannot read a closed ZIP archive");
-      const entry = entries.get(name);
+    }),
+    getEntrySize: (name) => withEntry(
+      name,
+      (_zip, entry) => Promise.resolve(entry?.uncompressedSize)
+    ),
+    listEntries: () => run(async (zip) => {
+      const names = /* @__PURE__ */ new Set();
+      await scanNodeZip(zip, (entry) => {
+        names.add(entry.fileName);
+      });
+      return [...names];
+    }),
+    readEntryRange: (name, offset, length) => withEntry(name, async (zip, entry) => {
       if (entry === void 0) return void 0;
-      return await readNodeZipEntryRange(zipFile, entry, offset, length);
-    },
-    readEntry: async (name) => {
-      if (closed) throw new Error("Cannot read a closed ZIP archive");
-      const entry = entries.get(name);
+      return await readNodeZipEntryRange(zip, entry, offset, length);
+    }),
+    readEntry: (name) => withEntry(name, async (zip, entry) => {
       if (entry === void 0) return void 0;
-      return await readNodeZipEntry(zipFile, entry);
-    }
+      return await readNodeZipEntry(zip, entry);
+    })
   };
 }
+var NodeZipSource = class extends yauzl.RandomAccessReader {
+  constructor(handle) {
+    super();
+    this.handle = handle;
+  }
+  handle;
+  read(buffer, offset, length, position, callback) {
+    const read2 = (written) => {
+      if (written === length) {
+        callback(null);
+        return;
+      }
+      fs.read(
+        this.handle.fd,
+        buffer,
+        offset + written,
+        length - written,
+        position + written,
+        (error, bytesRead) => {
+          if (error) callback(error);
+          else if (bytesRead === 0)
+            callback(new Error("Unexpected end of ZIP file"));
+          else read2(written + bytesRead);
+        }
+      );
+    };
+    read2(0);
+  }
+  _readStreamForRange(start, end) {
+    const handle = this.handle;
+    return Readable.from(
+      (async function* () {
+        for (let position = start; position < end; ) {
+          const buffer = Buffer.allocUnsafe(
+            Math.min(64 * 1024, end - position)
+          );
+          const { bytesRead } = await handle.read(
+            buffer,
+            0,
+            buffer.length,
+            position
+          );
+          if (bytesRead === 0) return;
+          position += bytesRead;
+          yield buffer.subarray(0, bytesRead);
+        }
+      })()
+    );
+  }
+};
+function normalizeNodeZipName(name) {
+  const normalized = name.replaceAll("\\", "/").trim().split("/").filter((part) => part !== "" && part !== ".").join("/");
+  return normalized.split("/").includes("..") ? void 0 : normalized;
+}
+async function scanNodeZip(zip, visit) {
+  await new Promise((resolve4, reject) => {
+    const cleanup = () => {
+      zip.off("entry", onEntry);
+      zip.off("end", onEnd);
+      zip.off("error", onError);
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve4();
+    };
+    const onEntry = (entry) => {
+      void Promise.resolve().then(() => entry.fileName.endsWith("/") ? void 0 : visit(entry)).then((keepReading) => {
+        if (keepReading === false) onEnd();
+        else zip.readEntry();
+      }).catch(
+        (error) => onError(
+          error instanceof Error ? error : new Error("Cannot scan ZIP", { cause: error })
+        )
+      );
+    };
+    zip.on("entry", onEntry);
+    zip.once("end", onEnd);
+    zip.once("error", onError);
+    zip.readEntry();
+  });
+}
 async function copyNodeZipEntry(zipFile, entry, target) {
   const writer = await target.openWriter();
   try {
@@ -1409,17 +1572,32 @@ function resolveWikiGraphRuntimePath(path) {
 
 // src/archive/target.ts
 import { realpath, stat as stat2 } from "fs/promises";
-import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute3, join as join3, relative, resolve as resolve3 } from "path";
+import { basename as basename2, dirname as dirname2, join as join3, resolve as resolve3 } from "path";
 import {
   formatLocatedWikiGraphUri,
   formatWikiGraphLibraryUri,
-  listWikiGraphLibraries,
-  listWikiGraphLibraryArchives,
+  findWikiGraphLibraryByPhysicalIdentity,
+  findWikiGraphLibraryArchivePhysicalAliases,
   parseLocatedWikiGraphUri,
   parseWikiGraphLibraryUri,
   resolveWikiGraphLibrary,
-  resolveWikiGraphLibraryArchiveFile
+  resolveWikiGraphLibraryArchiveFile,
+  isWikiGraphSchemaVersionError,
+  WikiGraphSchemaVersionError
 } from "wiki-graph-core";
+function rethrowArchiveSchemaError(error, target) {
+  if (isWikiGraphSchemaVersionError(error) && error.target.kind === "archive") {
+    throw new WikiGraphSchemaVersionError(
+      target.kind === "standalone" ? { kind: "archive", path: resolveWikiGraphRuntimePath(target.path) } : { kind: "library", uri: target.uri.split("/arc/")[0] },
+      error.actualVersion,
+      error.supportedVersion
+    );
+  }
+  throw error;
+}
+function requireWikiGraphArchiveFile(location) {
+  return location.archiveFile;
+}
 var WikiGraphArchiveOwnershipError = class extends Error {
   code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
   constructor(message) {
@@ -1437,12 +1615,7 @@ async function assertStandaloneWikiGraphArchivePath(inputPath) {
   const path = resolveWikiGraphRuntimePath(inputPath);
   const candidate = await canonicalPath(path);
   const candidateIdentity = await readFileIdentity(path);
-  const libraries = await listWikiGraphLibraries();
-  const matches = await findMatchingMembers(
-    libraries,
-    candidate,
-    candidateIdentity
-  );
+  const matches = await findMatchingMembers(candidate, candidateIdentity);
   if (matches.length > 0) {
     const match = requireUnambiguousManagedMatch(path, matches);
     throw new WikiGraphArchiveOwnershipError(
@@ -1451,15 +1624,26 @@ async function assertStandaloneWikiGraphArchivePath(inputPath) {
       )}: ${path}. Use the library UUID URI ${match.archive.uri} instead.`
     );
   }
-  for (const library of libraries) {
-    const rootPath = getNodeResourcePath(library.folder);
-    const root = await canonicalPath(rootPath);
-    if (!isWithin(root, candidate)) continue;
-    throw new WikiGraphArchiveOwnershipError(
-      `Standalone archive path belongs to registered library ${formatWikiGraphLibraryUri(
-        library.isDefault ? void 0 : library.publicId
-      )}: ${path}. Scan the library, then address the archive by its library UUID URI.`
+  const ancestors = /* @__PURE__ */ new Set();
+  for (const start of [candidate, resolve3(path)]) {
+    for (let parent = dirname2(start); ; parent = dirname2(parent)) {
+      ancestors.add(parent);
+      if (dirname2(parent) === parent) break;
+    }
+  }
+  for (const parent of ancestors) {
+    const identity = await readFileIdentity(parent);
+    const library = await findWikiGraphLibraryByPhysicalIdentity(
+      identity,
+      new NodeDirectory(parent).identity
     );
+    if (library !== void 0) {
+      throw new WikiGraphArchiveOwnershipError(
+        `Standalone archive path belongs to registered library ${formatWikiGraphLibraryUri(
+          library.isDefault ? void 0 : library.publicId
+        )}: ${path}. Scan the library, then address the archive by its library UUID URI.`
+      );
+    }
   }
   return path;
 }
@@ -1477,11 +1661,7 @@ async function resolveWikiGraphArchiveTarget(file) {
   const path = getNodeResourcePath(file);
   const candidate = await canonicalPath(path);
   const candidateIdentity = await readFileIdentity(path);
-  const matches = await findMatchingMembers(
-    await listWikiGraphLibraries(),
-    candidate,
-    candidateIdentity
-  );
+  const matches = await findMatchingMembers(candidate, candidateIdentity);
   if (matches.length > 0) {
     const match = requireUnambiguousManagedMatch(path, matches);
     return { kind: "library", uri: match.archive.uri };
@@ -1547,47 +1727,35 @@ function withObjectUri(archiveLocator, objectUri) {
 async function canonicalPath(path) {
   try {
     return await realpath(path);
-  } catch {
+  } catch (error) {
+    if (!(typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")))
+      throw error;
     const absolute = resolve3(path);
     const parent = dirname2(absolute);
     return parent === absolute ? absolute : join3(await canonicalPath(parent), basename2(absolute));
   }
 }
-function isWithin(root, candidate) {
-  const child = relative(root, candidate);
-  return child === "" || !child.startsWith("..") && !isAbsolute3(child);
-}
-async function findMatchingMembers(libraries, candidate, candidateIdentity) {
+async function findMatchingMembers(candidate, candidateIdentity) {
+  if (candidateIdentity === void 0) return [];
+  const archives = await findWikiGraphLibraryArchivePhysicalAliases(candidateIdentity);
   const members = [];
-  for (const library of libraries) {
-    const archives = await listWikiGraphLibraryArchives({
-      isDefault: library.isDefault,
-      kind: "scope",
-      ...library.isDefault ? {} : { publicId: library.publicId }
-    });
-    for (const archive of archives) {
-      if (archive.file === void 0) continue;
+  for (const archive of archives) {
+    const parsed = parseWikiGraphLibraryUri(archive.libraryUri);
+    const library = await resolveWikiGraphLibrary(parsed);
+    const physical = archive.file ?? archive.directory;
+    if (library !== void 0 && physical !== void 0)
       members.push({
         archive,
         library,
-        memberPath: getNodeResourcePath(archive.file)
+        memberPath: getNodeResourcePath(physical)
       });
-    }
   }
   const exact = [];
   for (const member of members) {
-    if (await canonicalPath(member.memberPath) === candidate) {
+    if (await canonicalPath(member.memberPath) === candidate)
       exact.push(member);
-    }
   }
-  if (exact.length > 0 || candidateIdentity === void 0) return exact;
-  const identityMatches = [];
-  for (const member of members) {
-    if (await readFileIdentity(member.memberPath) === candidateIdentity) {
-      identityMatches.push(member);
-    }
-  }
-  return identityMatches;
+  return exact.length > 0 ? exact : members;
 }
 function requireUnambiguousManagedMatch(path, matches) {
   if (matches.length === 1) return matches[0];
@@ -1599,8 +1767,10 @@ async function readFileIdentity(path) {
   try {
     const value = await stat2(path);
     return `${value.dev}:${value.ino}`;
-  } catch {
-    return void 0;
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+      return void 0;
+    throw error;
   }
 }
 
@@ -1662,11 +1832,15 @@ var WikiGraphConversionManager = class {
       if (!("path" in options.input)) {
         throw new Error("wikg input requires a file path.");
       }
+      const inputPath = options.input.path;
       await app.openSession(
-        new NodeFile(
-          await assertStandaloneWikiGraphArchivePath(options.input.path)
-        ),
+        new NodeFile(await assertStandaloneWikiGraphArchivePath(inputPath)),
         write
+      ).catch(
+        (error) => rethrowArchiveSchemaError(error, {
+          kind: "standalone",
+          path: inputPath
+        })
       );
     } else if ("stream" in options.input) {
       await app.digestTextStreamSession(
@@ -2085,17 +2259,36 @@ function formatLocatedChapterUri(archiveUri, chapter) {
 // src/archive/write.ts
 import {
   WikiGraphArchiveFile,
+  WikiGraphDirectoryFile,
   writeWikiGraphLibraryArchive
 } from "wiki-graph-core";
 async function writeWikiGraphArchiveLocation(location, operation, options = {}) {
   const cacheOnly = options.searchIndexWritebackPolicy === "cache";
-  const write = async (archiveFile = location.archiveFile) => await new WikiGraphArchiveFile(archiveFile).write(operation, {
-    ...cacheOnly ? {} : { derivedStateKeys: [location.archiveKey, location.archivePath] },
-    ...options.invalidateContinuationCursors === void 0 ? {} : {
-      invalidateContinuationCursors: options.invalidateContinuationCursors
-    },
-    ...options.searchIndexWritebackPolicy === void 0 ? {} : { searchIndexWritebackPolicy: options.searchIndexWritebackPolicy }
-  });
+  const write = async (archiveFile = location.archiveFile) => {
+    if (cacheOnly) {
+      return await new WikiGraphArchiveFile(archiveFile).readDocument(
+        operation,
+        { searchIndexWritebackPolicy: "cache" }
+      );
+    }
+    const writeOptions = {
+      ...cacheOnly ? {} : { derivedStateKeys: [location.archiveKey, location.archivePath] },
+      ...options.invalidateContinuationCursors === void 0 ? {} : {
+        invalidateContinuationCursors: options.invalidateContinuationCursors
+      },
+      ...options.searchIndexWritebackPolicy === void 0 ? {} : { searchIndexWritebackPolicy: options.searchIndexWritebackPolicy }
+    };
+    if (archiveFile.kind === "directory") {
+      return await new WikiGraphDirectoryFile(archiveFile).write(
+        operation,
+        writeOptions
+      );
+    }
+    return await new WikiGraphArchiveFile(archiveFile).write(
+      operation,
+      writeOptions
+    );
+  };
   if (location.libraryArchiveTarget === void 0 || cacheOnly || options.refreshLibraryIndex === false) {
     return await write();
   }
@@ -2453,10 +2646,15 @@ var WikiGraphArchiveManager = class {
     }, options.signal);
   }
   async open(target, options = {}) {
-    const location = await this.#runtime.run(
-      async () => await resolveWikiGraphArchiveLocation(target),
-      options.signal
-    );
+    const location = await this.#runtime.run(async () => {
+      const location2 = await resolveWikiGraphArchiveLocation(target);
+      try {
+        await ensureWikiGraphArchiveSchemaCurrent(location2.archiveFile);
+      } catch (error) {
+        rethrowArchiveSchemaError(error, target);
+      }
+      return location2;
+    }, options.signal);
     return new WikiGraphArchiveHandle(this.#runtime, location);
   }
 };
@@ -2507,15 +2705,11 @@ var WikiGraphArchiveHandle = class {
       options.queryMode,
       options.signal
     );
-    const result = await this.#writeDocument(
+    const result = await this.#readDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
         });
-        await ensureArchiveSearchIndex(document, {
-          ...chapters === void 0 ? {} : { chapters },
-          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
-        });
         return await findArchiveObjects(document, query, {
           ...withoutOperationAndScope(options),
           archiveKey: this.archiveKey,
@@ -2524,7 +2718,6 @@ var WikiGraphArchiveHandle = class {
         });
       },
       {
-        searchIndexWritebackPolicy: "cache",
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
@@ -2629,6 +2822,7 @@ var WikiGraphArchiveHandle = class {
       async (document) => {
         const chapters = await this.#resolveScope(document, options);
         await ensureArchiveSearchIndex(document, {
+          rebuild: true,
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
@@ -2807,7 +3001,7 @@ var WikiGraphArchiveHandle = class {
     return await this.#writeDocument(async (document) => {
       const chapterId = await resolveChapterPathReadonly(document, path);
       await assertChapterResetAllowed(
-        this.#location.archiveFile,
+        requireWikiGraphArchiveFile(this.#location),
         chapterId,
         stage
       );
@@ -2918,15 +3112,11 @@ var WikiGraphArchiveHandle = class {
       options.queryMode,
       options.signal
     );
-    const result = await this.#writeDocument(
+    const result = await this.#readDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
         });
-        await ensureArchiveSearchIndex(document, {
-          ...chapters === void 0 ? {} : { chapters },
-          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
-        });
         return await listRelatedArchiveObjects(document, objectUri, {
           ...withoutOperation(options),
           ...embeddingProvider === void 0 ? {} : { embeddingProvider },
@@ -2934,7 +3124,6 @@ var WikiGraphArchiveHandle = class {
         });
       },
       {
-        searchIndexWritebackPolicy: "cache",
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
@@ -2978,15 +3167,11 @@ var WikiGraphArchiveHandle = class {
       options.queryMode,
       options.signal
     );
-    const result = await this.#writeDocument(
+    const result = await this.#readDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
         });
-        await ensureArchiveSearchIndex(document, {
-          ...chapters === void 0 ? {} : { chapters },
-          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
-        });
         return await listArchiveEvidence(document, objectUri, {
           ...withoutOperation(options),
           ...embeddingProvider === void 0 ? {} : { embeddingProvider },
@@ -2994,7 +3179,6 @@ var WikiGraphArchiveHandle = class {
         });
       },
       {
-        searchIndexWritebackPolicy: "cache",
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
@@ -3053,14 +3237,18 @@ var WikiGraphArchiveHandle = class {
     }, options);
   }
   async readCover(options = {}) {
-    const app = new WikiGraph2({});
-    return await this.#runtime.run(
-      async () => await app.openSession(
+    return await this.#runtime.run(async () => {
+      if (this.#location.archiveFile.kind === "directory") {
+        return await this.#readDocument(
+          async (document) => await document.readCover()
+        );
+      }
+      const app = new WikiGraph2({});
+      return await app.openSession(
         this.#location.archiveFile,
         async (archive) => await archive.readCover()
-      ),
-      options.signal
-    );
+      );
+    }, options.signal);
   }
   async replaceMetadata(objectPath, value, options = {}) {
     return await this.#writeDocument(async (document) => {
@@ -3101,10 +3289,14 @@ var WikiGraphArchiveHandle = class {
   }
   async #readDocument(operation, options = {}) {
     return await this.#runtime.run(
-      async () => await new WikiGraphArchiveFile2(this.#location.archiveFile).readDocument(
-        operation
-      ),
+      async () => this.#location.archiveFile.kind === "directory" ? await new WikiGraphDirectoryFile2(
+        this.#location.archiveFile
+      ).readDocument(operation) : await new WikiGraphArchiveFile2(
+        this.#location.archiveFile
+      ).readDocument(operation),
       options.signal
+    ).catch(
+      (error) => rethrowArchiveSchemaError(error, this.#location.target)
     );
   }
   async #writeDocument(operation, options = {}) {
@@ -3116,33 +3308,32 @@ var WikiGraphArchiveHandle = class {
           searchIndexWritebackPolicy: options.searchIndexWritebackPolicy
         }
       });
-    }, options.signal);
+    }, options.signal).catch(
+      (error) => rethrowArchiveSchemaError(error, this.#location.target)
+    );
   }
   async #resolveScope(document, options) {
     if (options.chapters !== void 0) return options.chapters;
     return (await resolveArchiveScope(document, this.objectUri, options.depth))?.chapterIds;
   }
   async #resolveQueryChapters(document, options, capabilities) {
-    const chapters = await this.#resolveScope(document, options);
+    const parsed = parseChapterScopePath(this.objectUri);
+    const chapters = options.chapters ?? (parsed === void 0 || parsed.kind === "collection" && options.depth === void 0 ? void 0 : await resolveIndexedArchiveChapterScope(
+      document,
+      parsed.kind === "chapter" ? parsed.chapterPath : void 0,
+      options.depth
+    ));
     const coverageOptions = {
       ...chapters === void 0 ? {} : { chapters },
       ...capabilities.embeddingProvider === void 0 ? {} : { embeddingProvider: capabilities.embeddingProvider },
       requireEmbeddingProvider: true,
       ...options.queryMode === void 0 ? {} : { queryMode: options.queryMode }
     };
-    if (options.skipUnindexed !== true) {
-      await assertArchiveIndexArtifactsReady(document, coverageOptions);
-      return chapters;
-    }
-    const queryable = await listArchiveQueryableChapterIds(document, {
-      ...coverageOptions
+    await assertArchiveQueryReady(document, {
+      ...coverageOptions,
+      ...options.skipUnindexed === void 0 ? {} : { skipUnindexed: options.skipUnindexed }
     });
-    if (queryable.length === 0) {
-      throw new Error(
-        "Wiki Graph query is not ready. No chapters in this scope have a current FTS artifact or source embedding artifact."
-      );
-    }
-    return queryable;
+    return chapters;
   }
   async #resolveQueryEmbeddingProvider(queryMode, signal) {
     if (queryMode === "fts") return void 0;
@@ -3161,6 +3352,10 @@ var WikiGraphArchiveHandle = class {
 async function ensureArchiveSearchIndex(document, options = {}) {
   const scope = options.chapters === void 0 ? {} : { chapters: options.chapters };
   if (await isArchiveSearchIndexCurrent2(document, scope)) return;
+  if (options.rebuild !== true)
+    throw new Error(
+      "Archive search index is missing or dirty. Run `wg <archive-uri>/index sync` explicitly before querying."
+    );
   await rebuildArchiveSearchIndex(document, void 0, {
     ...scope,
     ...options.embeddingProvider === void 0 ? {} : { embeddingProvider: options.embeddingProvider }
@@ -3506,7 +3701,8 @@ import {
   listWikiGraphLibraryObjects,
   readContinuationCursor,
   resolveWikiGraphLibraryQueryTargetById,
-  WikiGraphArchiveFile as WikiGraphArchiveFile3
+  WikiGraphArchiveFile as WikiGraphArchiveFile3,
+  WikiGraphDirectoryFile as WikiGraphDirectoryFile3
 } from "wiki-graph-core";
 var WikiGraphContinuationManager = class {
   #runtime;
@@ -3556,53 +3752,54 @@ async function continueArchiveCursor(cursor, limit) {
   const location = await resolveWikiGraphArchiveLocation(
     archiveTargetFromLogicalLocator(getCursorArchivePath(cursor))
   );
-  return await new WikiGraphArchiveFile3(location.archiveFile).readDocument(
-    async (document) => {
-      switch (cursor.kind) {
-        case "source-locators":
-          return await listArchiveSourceLocators2(document, cursor.targetUri, {
-            cursor: cursor.cursor,
-            limit
-          });
-        case "collection":
-          return await listArchiveCollection2(
-            document,
-            createCollectionOptions(cursor, limit)
-          );
-        case "search":
-          return await findArchiveObjects2(
-            document,
-            cursor.query ?? "",
-            await createFindOptions(cursor, limit)
-          );
-        case "evidence":
-          return await listArchiveEvidence2(document, cursor.targetUri, {
-            ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
-            cursor: cursor.cursor,
-            limit,
-            order: cursor.order,
-            ...cursor.query === void 0 ? {} : { query: cursor.query },
-            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
-            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
-            ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
-            ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
-          });
-        case "related":
-          return await listRelatedArchiveObjects2(document, cursor.targetUri, {
-            ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
-            cursor: cursor.cursor,
-            ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
-            limit,
-            order: cursor.order,
-            ...cursor.query === void 0 ? {} : { query: cursor.query },
-            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
-            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
-            ...cursor.role === void 0 ? {} : { role: cursor.role },
-            ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
-            ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
-          });
-      }
+  const read2 = async (document) => {
+    switch (cursor.kind) {
+      case "source-locators":
+        return await listArchiveSourceLocators2(document, cursor.targetUri, {
+          cursor: cursor.cursor,
+          limit
+        });
+      case "collection":
+        return await listArchiveCollection2(
+          document,
+          createCollectionOptions(cursor, limit)
+        );
+      case "search":
+        return await findArchiveObjects2(
+          document,
+          cursor.query ?? "",
+          await createFindOptions(cursor, limit)
+        );
+      case "evidence":
+        return await listArchiveEvidence2(document, cursor.targetUri, {
+          ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
+          cursor: cursor.cursor,
+          limit,
+          order: cursor.order,
+          ...cursor.query === void 0 ? {} : { query: cursor.query },
+          ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
+          ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
+          ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
+        });
+      case "related":
+        return await listRelatedArchiveObjects2(document, cursor.targetUri, {
+          ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
+          cursor: cursor.cursor,
+          ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
+          limit,
+          order: cursor.order,
+          ...cursor.query === void 0 ? {} : { query: cursor.query },
+          ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
+          ...cursor.role === void 0 ? {} : { role: cursor.role },
+          ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
+          ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
+        });
     }
+  };
+  return await (location.archiveFile.kind === "directory" ? new WikiGraphDirectoryFile3(location.archiveFile).readDocument(read2) : new WikiGraphArchiveFile3(location.archiveFile).readDocument(read2)).catch(
+    (error) => rethrowArchiveSchemaError(error, location.target)
   );
 }
 async function continueLibraryCursor(cursor, limit) {
@@ -4491,7 +4688,7 @@ var WikiGraphJobManager = class {
       return {
         job: await this.#backend.add({
           ...options,
-          archive: location.archiveFile
+          archive: requireWikiGraphArchiveFile(location)
         }),
         target: location.target
       };
@@ -4523,7 +4720,9 @@ var WikiGraphJobManager = class {
         ...options.activeOnly === void 0 ? {} : { activeOnly: options.activeOnly },
         ...options.all === void 0 ? {} : { all: options.all },
         ...options.archive === void 0 ? {} : {
-          archive: (await resolveWikiGraphArchiveLocation(options.archive)).archiveFile
+          archive: requireWikiGraphArchiveFile(
+            await resolveWikiGraphArchiveLocation(options.archive)
+          )
         }
       };
       const jobs = await this.#backend.list(normalized);
@@ -4548,7 +4747,7 @@ var WikiGraphJobManager = class {
               archiveJobs[0].archive
             );
             const chapters = await new WikiGraphArchiveFile6(
-              location.archiveFile
+              requireWikiGraphArchiveFile(location)
             ).readDocument(async (document) => await listChapters3(document));
             const chaptersById = new Map(
               chapters.map((chapter) => [chapter.chapterId, chapter])
@@ -4591,7 +4790,7 @@ var WikiGraphJobManager = class {
           await validateQueueTargetConfig(target, llmJSON);
           const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
           const candidates = await new WikiGraphArchiveFile6(
-            location.archiveFile
+            requireWikiGraphArchiveFile(location)
           ).readDocument(async (document) => {
             const chapters = await listChapters3(document);
             const selected = await selectQueueChapters(
@@ -4635,7 +4834,7 @@ var WikiGraphJobManager = class {
                 chapter: candidate.chapter,
                 job: await this.#createHandle(
                   await this.#backend.add({
-                    archive: location.archiveFile,
+                    archive: requireWikiGraphArchiveFile(location),
                     boost: options.boost ?? false,
                     chapterId: candidate.chapter.chapterId,
                     ...llmJSON === void 0 ? {} : { llmJSON },
@@ -4666,7 +4865,7 @@ var WikiGraphJobManager = class {
       await validateQueueTargetConfig(target, llmJSON);
       const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
       const candidates = await new WikiGraphArchiveFile6(
-        location.archiveFile
+        requireWikiGraphArchiveFile(location)
       ).readDocument(async (document) => {
         const chapters = await listChapters3(document);
         const selected = await selectQueueChapters(document, chapters, options);
@@ -4996,6 +5195,7 @@ function forwardAbort(source, target) {
 // src/libraries.ts
 import {
   addWikiGraphLibraryArchive,
+  ensureWikiGraphArchiveSchemaCurrent as ensureWikiGraphArchiveSchemaCurrent2,
   assertWikiGraphLibrarySchemaCurrent,
   cleanWikiGraphLibraryIndex,
   clearWikiGraphLibraryMetadata,
@@ -5009,8 +5209,8 @@ import {
   getWikiGraphLibraryArchive,
   getWikiGraphLibraryMetadata,
   listRelatedWikiGraphLibraryObjects as listRelatedWikiGraphLibraryObjects2,
-  listWikiGraphLibraries as listWikiGraphLibraries2,
-  listWikiGraphLibraryArchives as listWikiGraphLibraryArchives2,
+  listWikiGraphLibraries,
+  listWikiGraphLibraryArchives,
   listWikiGraphLibraryArchiveMembers as listWikiGraphLibraryArchiveMembers2,
   listWikiGraphLibraryEvidence as listWikiGraphLibraryEvidence2,
   listWikiGraphLibraryObjects as listWikiGraphLibraryObjects2,
@@ -5028,9 +5228,12 @@ import {
   replaceWikiGraphLibraryMetadata,
   resolveWikiGraphLibrary as resolveWikiGraphLibrary2,
   scanWikiGraphLibrary,
-  withWikiGraphLibraryLock
+  withWikiGraphLibraryLock,
+  writeWikgArchive as writeWikgArchive2
 } from "wiki-graph-core";
-import { mkdir as mkdir3 } from "fs/promises";
+import { mkdir as mkdir3, mkdtemp as mkdtemp2, rm as rm4 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join5 } from "path";
 async function resolveQueryEmbeddingProvider(queryMode) {
   if (queryMode === "fts") return void 0;
   const provider = await createConfiguredEmbeddingProvider();
@@ -5120,10 +5323,28 @@ var WikiGraphLibraryManager = class {
         async () => {
           throwIfAborted(options.signal);
           const archive = await getWikiGraphLibraryArchive(parsedTarget);
-          const file = requireReadableLibraryArchiveFile(archive);
-          const reader = await file.openReader();
+          const source = requireReadableLibraryArchiveFile(archive);
+          await ensureWikiGraphArchiveSchemaCurrent2(source).catch(
+            (error) => rethrowArchiveSchemaError(error, {
+              kind: "library",
+              uri: archive.uri
+            })
+          );
+          let temporaryDirectory;
+          let reader;
           let active = true;
           try {
+            const file = source.kind === "directory" ? await (async () => {
+              temporaryDirectory = await mkdtemp2(
+                join5(tmpdir2(), "wikigraph-library-read-")
+              );
+              const output = new NodeFile(
+                join5(temporaryDirectory, "archive.wikg")
+              );
+              await writeWikgArchive2(source, output);
+              return output;
+            })() : source;
+            reader = await file.openReader();
             const content = {
               mediaType: "application/vnd.wiki-graph.archive",
               size: reader.size,
@@ -5140,7 +5361,12 @@ var WikiGraphLibraryManager = class {
             );
           } finally {
             active = false;
-            await reader.close();
+            try {
+              await reader?.close();
+            } finally {
+              if (temporaryDirectory !== void 0)
+                await rm4(temporaryDirectory, { force: true, recursive: true });
+            }
           }
         },
         options.signal === void 0 ? {} : { signal: options.signal }
@@ -5450,7 +5676,7 @@ var WikiGraphLibraryManager = class {
   }
   async list() {
     const records = await this.#runtime.run(
-      async () => await listWikiGraphLibraries2()
+      async () => await listWikiGraphLibraries()
     );
     return records.map((record) => new WikiGraphLibrary(this.#runtime, record));
   }
@@ -5473,7 +5699,7 @@ var WikiGraphLibrary = class {
   async archives() {
     const target = requireLibraryTarget(this.uri);
     return (await this.#runtime.run(
-      async () => await listWikiGraphLibraryArchives2(target)
+      async () => await listWikiGraphLibraryArchives(target)
     )).map(toArchiveSnapshot);
   }
   async scan() {
@@ -5502,7 +5728,7 @@ function toLibrarySnapshot(record) {
   };
 }
 function toArchiveSnapshot(record) {
-  const { file: _file, ...snapshot } = record;
+  const { file: _file, directory: _directory, ...snapshot } = record;
   return snapshot;
 }
 function toScanSnapshot(result) {
@@ -5535,12 +5761,12 @@ function requireReadableLibraryArchiveFile(archive) {
       `Wiki Graph library archive has a conflict and cannot be read: ${archive.uri}`
     );
   }
-  if (archive.file === void 0) {
+  if (archive.file === void 0 && archive.directory === void 0) {
     throw new Error(
       `Wiki Graph library archive is unavailable: ${archive.uri}`
     );
   }
-  return archive.file;
+  return archive.file ?? archive.directory;
 }
 var ARCHIVE_STREAM_CHUNK_SIZE = 64 * 1024;
 function createCallbackScopedArchiveStream(reader, isActive, signal) {
@@ -5645,7 +5871,9 @@ var WikiGraphMaintenanceManager = class {
         return await upgradeWikiGraphMaintenanceTarget({
           file: new NodeFile(path),
           kind: "archive"
-        });
+        }).catch(
+          (error) => rethrowArchiveSchemaError(error, { kind: "standalone", path })
+        );
       },
       void 0,
       { skipHomeBootstrap: target.kind === "home" }
@@ -5674,7 +5902,6 @@ function defaultWikgOutputPath(inputPath) {
 import { ensureWikiGraphHomeSchemaCurrent } from "wiki-graph-core";
 var WikiGraphSDK = class {
   #context;
-  #homeReady;
   archives;
   conversions;
   config;
@@ -5705,13 +5932,7 @@ var WikiGraphSDK = class {
     throwIfAborted2(signal);
     const runWithContext = async () => await withWikiGraphSDKRuntimeContext(this.#context, async () => {
       if (options.skipHomeBootstrap !== true) {
-        this.#homeReady ??= ensureWikiGraphHomeSchemaCurrent().catch(
-          (error) => {
-            this.#homeReady = void 0;
-            throw error;
-          }
-        );
-        await this.#homeReady;
+        await ensureWikiGraphHomeSchemaCurrent();
       }
       return await operation();
     });
@@ -5742,6 +5963,8 @@ import {
   LLMPaymentRequiredError,
   WIKI_GRAPH_URI_PREFIX,
   WikiGraphError,
+  WikiGraphSchemaVersionError as WikiGraphSchemaVersionError2,
+  isWikiGraphSchemaVersionError as isWikiGraphSchemaVersionError2,
   formatError as formatError3,
   formatLocatedChapterResourceUri,
   formatLocatedChapterSourceCollectionUri,
@@ -5798,6 +6021,7 @@ export {
   WikiGraphLibraryManager,
   WikiGraphMaintenanceManager,
   WikiGraphSDK,
+  WikiGraphSchemaVersionError2 as WikiGraphSchemaVersionError,
   buildSearchIndexEmbeddingProvider,
   buildWikiGraphLLMOptions,
   clearLocalConfigSection,
@@ -5840,6 +6064,7 @@ export {
   isSourceLocatorScopeUri2 as isSourceLocatorScopeUri,
   isWikiGraphJobUri,
   isWikiGraphLibraryUri,
+  isWikiGraphSchemaVersionError2 as isWikiGraphSchemaVersionError,
   isWikiGraphUri,
   iterateItems,
   iteratePages,