wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/archives.cjs

@@ -34,22 +34,25 @@ __export(archive_exports, {
   WikiGraphArchiveExistsError: () => WikiGraphArchiveExistsError,
   WikiGraphArchiveHandle: () => WikiGraphArchiveHandle,
   WikiGraphArchiveManager: () => WikiGraphArchiveManager,
-  createWikiGraphArchiveInspectReport: () => createWikiGraphArchiveInspectReport,
-  resolveWikiGraphArchiveLocation: () => resolveWikiGraphArchiveLocation
+  WikiGraphArchiveOwnershipError: () => WikiGraphArchiveOwnershipError,
+  inspectWikiGraphArchive: () => inspectWikiGraphArchive
 });
 module.exports = __toCommonJS(archive_exports);
 
 // src/archive/archive.ts
-var import_crypto = require("crypto");
-var import_promises3 = require("fs/promises");
+var import_crypto2 = require("crypto");
+var import_promises4 = require("fs/promises");
 var import_os3 = require("os");
-var import_path3 = require("path");
+var import_path5 = require("path");
 var import_stream = require("stream");
-var import_wiki_graph_core5 = require("wiki-graph-core");
+var import_wiki_graph_core7 = require("wiki-graph-core");
 
 // src/conversions.ts
-var import_promises2 = require("fs/promises");
-var import_wiki_graph_core2 = require("wiki-graph-core");
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+var import_promises3 = require("fs/promises");
+var import_path4 = require("path");
+var import_wiki_graph_core3 = require("wiki-graph-core");
 
 // src/llm.ts
 var import_anthropic = require("@ai-sdk/anthropic");
@@ -369,42 +372,42 @@ var NodeDatabaseConnection = class {
   }
   database;
   async close() {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.close((error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
   async execute(sql) {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.exec(sql, (error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
   async queryAll(sql, params = []) {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.all(sql, [...params], (error, rows) => {
         if (error) reject(error);
-        else resolve3(rows);
+        else resolve4(rows);
       });
     });
   }
   async queryOne(sql, params = []) {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.get(sql, [...params], (error, row) => {
         if (error) reject(error);
-        else resolve3(row);
+        else resolve4(row);
       });
     });
   }
   async run(sql, params = []) {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.run(sql, [...params], (error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
@@ -418,10 +421,10 @@ async function openNativeNodeDatabase(file, flags) {
   if (path === void 0) {
     throw new TypeError("The Node database adapter requires a NodeFile");
   }
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const database = new nodeSqlite3.Database(path, flags, (error) => {
       if (error) reject(error);
-      else resolve3(database);
+      else resolve4(database);
     });
   });
 }
@@ -430,19 +433,19 @@ async function openNodeZip(file) {
   if (path === void 0) {
     throw new TypeError("The Node ZIP adapter requires a NodeFile");
   }
-  const zipFile = await new Promise((resolve3, reject) => {
+  const zipFile = await new Promise((resolve4, reject) => {
     yauzl.open(
       path,
       { autoClose: false, lazyEntries: true },
       (error, opened) => {
         if (error || opened === void 0)
           reject(error ?? new Error("Cannot open ZIP"));
-        else resolve3(opened);
+        else resolve4(opened);
       }
     );
   });
   const entries = await new Promise(
-    (resolve3, reject) => {
+    (resolve4, reject) => {
       const discovered = /* @__PURE__ */ new Map();
       const rejectAndClose = (error) => {
         zipFile.close();
@@ -452,7 +455,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve3(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -562,12 +565,12 @@ async function collectDecodedNodeStreamRange(input, offset, length) {
   return Buffer.concat(chunks, collected);
 }
 async function openNodeZipEntryStream(zipFile, entry, options) {
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const callback = (error, opened) => {
       if (error || opened === void 0) {
         reject(error ?? new Error(`Cannot read ZIP entry: ${entry.fileName}`));
       } else {
-        resolve3(opened);
+        resolve4(opened);
       }
     };
     if (options === void 0) zipFile.openReadStream(entry, callback);
@@ -698,11 +701,11 @@ async function writeNodeStream(input, writer) {
   );
 }
 async function collectNodeStream(input) {
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const chunks = [];
     input.on("data", (chunk) => chunks.push(chunk));
     input.once("error", reject);
-    input.once("end", () => resolve3(Buffer.concat(chunks)));
+    input.once("end", () => resolve4(Buffer.concat(chunks)));
   });
 }
 var nodeWikiGraphPlatform = {
@@ -1255,6 +1258,164 @@ function resolveWikiGraphRuntimePath(path) {
   return (0, import_path2.isAbsolute)(path) ? path : (0, import_path2.resolve)(context.cwd, path);
 }
 
+// src/archive/target.ts
+var import_promises2 = require("fs/promises");
+var import_path3 = require("path");
+var import_wiki_graph_core2 = require("wiki-graph-core");
+var WikiGraphArchiveOwnershipError = class extends Error {
+  code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "WikiGraphArchiveOwnershipError";
+  }
+};
+async function resolveWikiGraphArchiveLocation(target) {
+  if (target.kind === "standalone") {
+    return await resolveStandaloneLocation(target);
+  }
+  return await resolveLibraryLocation(target);
+}
+async function assertStandaloneWikiGraphArchivePath(inputPath) {
+  const path = resolveWikiGraphRuntimePath(inputPath);
+  const candidate = await canonicalPath(path);
+  const candidateIdentity = await readFileIdentity(path);
+  const libraries = await (0, import_wiki_graph_core2.listWikiGraphLibraries)();
+  const matches = await findMatchingMembers(
+    libraries,
+    candidate,
+    candidateIdentity
+  );
+  if (matches.length > 0) {
+    const match = requireUnambiguousManagedMatch(path, matches);
+    throw new WikiGraphArchiveOwnershipError(
+      `Standalone archive path belongs to registered library ${(0, import_wiki_graph_core2.formatWikiGraphLibraryUri)(
+        match.library.isDefault ? void 0 : match.library.publicId
+      )}: ${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 ${(0, import_wiki_graph_core2.formatWikiGraphLibraryUri)(
+        library.isDefault ? void 0 : library.publicId
+      )}: ${path}. Scan the library, then address the archive by its library UUID URI.`
+    );
+  }
+  return path;
+}
+async function resolveStandaloneLocation(target) {
+  if (target.path.startsWith("wikg://lib/")) {
+    throw new WikiGraphArchiveOwnershipError(
+      `A library archive URI cannot be used as a standalone path: ${target.path}`
+    );
+  }
+  const path = await assertStandaloneWikiGraphArchivePath(target.path);
+  const normalized = {
+    kind: "standalone",
+    path,
+    ...target.objectUri === void 0 ? {} : { objectUri: target.objectUri }
+  };
+  return {
+    archiveFile: new NodeFile(path),
+    archiveKey: path,
+    archivePath: path,
+    indexScope: { archiveKey: path, archivePath: path, kind: "archive-index" },
+    locatedUri: (0, import_wiki_graph_core2.formatLocatedWikiGraphUri)(path, target.objectUri),
+    target: normalized
+  };
+}
+async function resolveLibraryLocation(target) {
+  const parsedLocated = (0, import_wiki_graph_core2.parseLocatedWikiGraphUri)(target.uri);
+  const archiveUri = parsedLocated.archivePath ?? target.uri;
+  const parsed = (0, import_wiki_graph_core2.parseWikiGraphLibraryUri)(archiveUri);
+  if (parsed?.kind !== "archive") {
+    throw new WikiGraphArchiveOwnershipError(
+      `Library archive target must be a UUID archive URI: ${target.uri}`
+    );
+  }
+  await (0, import_wiki_graph_core2.resolveWikiGraphLibrary)(parsed);
+  const archiveFile = await (0, import_wiki_graph_core2.resolveWikiGraphLibraryArchiveFile)(archiveUri);
+  const normalized = {
+    kind: "library",
+    uri: target.uri
+  };
+  return {
+    archiveFile,
+    archiveKey: archiveUri,
+    archivePath: archiveUri,
+    indexScope: {
+      archiveKey: archiveUri,
+      archivePath: archiveUri,
+      kind: "archive-index"
+    },
+    libraryArchiveTarget: parsed,
+    locatedUri: target.uri,
+    publicArchiveUri: archiveUri,
+    target: normalized
+  };
+}
+async function canonicalPath(path) {
+  try {
+    return await (0, import_promises2.realpath)(path);
+  } catch {
+    const absolute = (0, import_path3.resolve)(path);
+    const parent = (0, import_path3.dirname)(absolute);
+    return parent === absolute ? absolute : (0, import_path3.join)(await canonicalPath(parent), (0, import_path3.basename)(absolute));
+  }
+}
+function isWithin(root, candidate) {
+  const child = (0, import_path3.relative)(root, candidate);
+  return child === "" || !child.startsWith("..") && !(0, import_path3.isAbsolute)(child);
+}
+async function findMatchingMembers(libraries, candidate, candidateIdentity) {
+  const members = [];
+  for (const library of libraries) {
+    const archives = await (0, import_wiki_graph_core2.listWikiGraphLibraryArchives)({
+      isDefault: library.isDefault,
+      kind: "scope",
+      ...library.isDefault ? {} : { publicId: library.publicId }
+    });
+    for (const archive of archives) {
+      if (archive.file === void 0) continue;
+      members.push({
+        archive,
+        library,
+        memberPath: getNodeResourcePath(archive.file)
+      });
+    }
+  }
+  const exact = [];
+  for (const member of members) {
+    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;
+}
+function requireUnambiguousManagedMatch(path, matches) {
+  if (matches.length === 1) return matches[0];
+  throw new WikiGraphArchiveOwnershipError(
+    `Archive file identity is ambiguous across managed archives: ${path}. Use an explicit library UUID URI (${matches.map((match) => match.archive.uri).join(", ")}).`
+  );
+}
+async function readFileIdentity(path) {
+  try {
+    const value = await (0, import_promises2.stat)(path);
+    return `${value.dev}:${value.ino}`;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/conversions.ts
 var WikiGraphConversionManager = class {
   #runtime;
@@ -1269,6 +1430,9 @@ var WikiGraphConversionManager = class {
     if (options.targetStage !== void 0 && options.output.format !== "wikg") {
       throw new Error("targetStage is only supported for wikg output.");
     }
+    if (options.output.format === "pcex") {
+      throw new Error("pcex is supported only as a conversion input.");
+    }
     if (options.targetStage !== void 0 && options.input.format === "wikg") {
       throw new Error(
         "targetStage is only supported when creating a wikg archive."
@@ -1279,7 +1443,7 @@ var WikiGraphConversionManager = class {
     const config = await loadWikiGraphRuntimeConfig({
       ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
     });
-    const app = new import_wiki_graph_core2.WikiGraph({
+    const app = new import_wiki_graph_core3.WikiGraph({
       ...options.verbose === true ? { verbose: true } : {},
       ...requiresLLM ? { llm: buildWikiGraphLLMOptions(config) } : {}
     });
@@ -1287,7 +1451,17 @@ var WikiGraphConversionManager = class {
       options.digestDirectory,
       requiresDigest
     );
+    let chapterCount;
+    let chapterPaths;
     const write = async (archive) => {
+      if (requiresDigest) await options.onSourceImported?.();
+      if (typeof archive.readToc === "function") {
+        const toc = await archive.readToc();
+        chapterCount = toc === void 0 ? void 0 : countTocChapters(toc.items);
+        if (options.output.format === "wikg") {
+          chapterPaths = toc === void 0 ? [] : collectTocChapterPaths(toc.items);
+        }
+      }
       await writeArchive(archive, options.output.path, options.output.format);
     };
     if (options.input.format === "wikg") {
@@ -1295,7 +1469,9 @@ var WikiGraphConversionManager = class {
         throw new Error("wikg input requires a file path.");
       }
       await app.openSession(
-        new NodeFile(resolveWikiGraphRuntimePath(options.input.path)),
+        new NodeFile(
+          await assertStandaloneWikiGraphArchivePath(options.input.path)
+        ),
         write
       );
     } else if ("stream" in options.input) {
@@ -1320,16 +1496,29 @@ var WikiGraphConversionManager = class {
       };
       if (options.input.format === "epub") {
         await app.digestEpubSession(digestOptions, write);
+      } else if (options.input.format === "pcex") {
+        await app.digestPcexSession(
+          {
+            ...digestOptions,
+            pdfDigest: options.input.sourcePdf.digest,
+            ...options.input.sourcePdf.name === void 0 ? {} : { pdfName: options.input.sourcePdf.name }
+          },
+          write
+        );
       } else if (options.input.format === "markdown") {
         await app.digestMarkdownSession(digestOptions, write);
       } else {
         await app.digestTxtSession(digestOptions, write);
       }
     }
+    const sourceArtifact = await resolveSourceArtifact(options.input);
     return {
+      ...chapterCount === void 0 ? {} : { chapterCount },
+      ...chapterPaths === void 0 ? {} : { chapterPaths },
       inputFormat: options.input.format,
       outputFormat: options.output.format,
-      outputPath: options.output.path
+      outputPath: options.output.path,
+      ...sourceArtifact === void 0 ? {} : { sourceArtifact }
     };
   }
 };
@@ -1338,18 +1527,74 @@ async function prepareDigestDirectory(path, required) {
   if (!required || normalized === void 0 || normalized === "")
     return void 0;
   const resolved = resolveWikiGraphRuntimePath(normalized);
-  await (0, import_promises2.rm)(resolved, { force: true, recursive: true });
+  await (0, import_promises3.rm)(resolved, { force: true, recursive: true });
   return new NodeDirectory(resolved);
 }
 async function writeArchive(archive, path, format) {
-  const file = new NodeFile(resolveWikiGraphRuntimePath(path));
+  const outputPath = format === "wikg" ? await assertStandaloneWikiGraphArchivePath(path) : resolveWikiGraphRuntimePath(path);
+  const file = new NodeFile(outputPath);
   if (format === "epub") await archive.exportEpub(file);
   else if (format === "wikg") await archive.saveAs(file);
+  else if (format === "pcex") throw new Error("pcex output is not supported.");
   else await archive.exportText(file);
 }
+async function resolveSourceArtifact(input) {
+  if (!("path" in input) || input.format === "wikg") return void 0;
+  if (input.format === "pcex") {
+    return {
+      digest: input.sourcePdf.digest.trim().toLowerCase(),
+      mediaType: "application/pdf",
+      ...input.sourcePdf.name === void 0 ? {} : { name: input.sourcePdf.name }
+    };
+  }
+  if (input.format !== "epub") return void 0;
+  const path = resolveWikiGraphRuntimePath(input.path);
+  const hash = (0, import_crypto.createHash)("sha256");
+  try {
+    for await (const chunk of (0, import_fs.createReadStream)(path)) {
+      hash.update(chunk);
+    }
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) return void 0;
+    throw error;
+  }
+  return {
+    digest: hash.digest("hex"),
+    mediaType: "application/epub+zip",
+    name: (0, import_path4.basename)(path)
+  };
+}
+function isNodeErrorCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function countTocChapters(items) {
+  let count = 0;
+  for (const item of items) {
+    if (item.serialId !== void 0) count += 1;
+    count += countTocChapters(
+      item.children
+    );
+  }
+  return count;
+}
+function collectTocChapterPaths(items, ancestorKeys = []) {
+  const paths = [];
+  for (const item of items) {
+    const key = item.key ?? `chapter-${item.serialId ?? "group"}`;
+    const chapterPath = [...ancestorKeys, key];
+    if (item.serialId !== void 0) paths.push(chapterPath.join("/"));
+    paths.push(
+      ...collectTocChapterPaths(
+        item.children,
+        chapterPath
+      )
+    );
+  }
+  return paths;
+}
 
 // src/query-runtime.ts
-var import_wiki_graph_core3 = require("wiki-graph-core");
+var import_wiki_graph_core4 = require("wiki-graph-core");
 
 // src/embedding.ts
 var import_ai = require("ai");
@@ -1497,7 +1742,7 @@ async function createConfiguredEmbeddingProvider() {
 async function withConfiguredWikimediaResolver(objectUri, operation) {
   if (!objectUri.endsWith("/wikipage")) return await operation({});
   const config = await loadWikiGraphRuntimeConfig();
-  const resolver = await (0, import_wiki_graph_core3.openWikimediaResolver)(
+  const resolver = await (0, import_wiki_graph_core4.openWikimediaResolver)(
     config.wikimedia === void 0 ? { kind: "local" } : {
       endpoint: config.wikimedia.endpoint,
       kind: "remote",
@@ -1512,490 +1757,128 @@ async function withConfiguredWikimediaResolver(objectUri, operation) {
 }
 
 // src/archive/inspect.ts
-var import_wiki_graph_core4 = require("wiki-graph-core");
-
-// src/planning.ts
-var DEFAULT_GENERATION_JOB_CONCURRENCY = 3;
-var DEFAULT_GENERATION_REQUEST_CONCURRENCY = 6;
-function planGenerationTask(task, words, chapters, concurrent, model) {
-  const profile = getGenerationPlanningProfile(task);
-  const calls = Math.max(chapters, Math.ceil(words / profile.wordsPerCall));
-  const effectiveConcurrency = Math.max(
-    1,
-    task === "reading-graph" ? 1 : concurrent.request
-  );
-  const callBatches = Math.ceil(calls / effectiveConcurrency);
-  const wordSeconds = words * profile.secondsPerWord;
-  return {
-    model,
-    timeSeconds: {
-      max: Math.ceil(callBatches * profile.maxSecondsPerCall + wordSeconds),
-      min: Math.ceil(callBatches * profile.minSecondsPerCall + wordSeconds)
-    },
-    tokens: {
-      cacheableInput: Math.ceil(words * profile.cacheableInputTokenPerWord),
-      input: Math.ceil(words * profile.inputTokenPerWord),
-      output: Math.ceil(words * profile.outputTokenPerWord)
-    }
+var import_wiki_graph_core5 = require("wiki-graph-core");
+async function inspectWikiGraphArchive(document, options) {
+  const [allChapters, indexCacheCurrent, summaryWords, ...coverage] = await Promise.all([
+    (0, import_wiki_graph_core5.listChapters)(document),
+    (0, import_wiki_graph_core5.isArchiveSearchIndexCurrent)(document),
+    readSummaryWords(document),
+    document.indexArtifacts.listCoverage("fts"),
+    document.indexArtifacts.listCoverage("embedding-source"),
+    document.indexArtifacts.listCoverage("embedding-summary")
+  ]);
+  const chapters = selectChapters(allChapters, options.chapterId);
+  const coverageByKind = {
+    fts: byChapterId(coverage[0]),
+    sourceEmbedding: byChapterId(coverage[1]),
+    summaryEmbedding: byChapterId(coverage[2])
   };
-}
-function createGenerationPerformanceHints(input) {
-  if (!input.hasJobWork) {
-    return [];
-  }
-  const hints = [];
-  const recommendedRequest = input.concurrent.request < 4 ? DEFAULT_GENERATION_REQUEST_CONCURRENCY : input.concurrent.request < 8 ? 8 : void 0;
-  if (input.hasRequestWork && recommendedRequest !== void 0) {
-    hints.push({
-      configKey: "request",
-      configValue: recommendedRequest,
-      current: input.concurrent.request,
-      kind: "request",
-      message: "LLM request concurrency can often be higher. Use at least 4; 6-8 is usually faster when the provider allows it.",
-      recommended: recommendedRequest
-    });
-  }
-  if (input.concurrent.job < 4 && input.chapters > 1) {
-    hints.push({
-      configKey: "job",
-      configValue: 4,
-      current: input.concurrent.job,
-      kind: "job",
-      message: "Multiple chapters need work and job concurrency is below 4. Raising it lets chapter jobs run in parallel.",
-      recommended: 4
-    });
-  }
-  return hints;
-}
-function formatGenerationPlanningModel(llm) {
-  if (llm?.model === void 0) {
-    return "not configured";
-  }
-  return llm.provider === void 0 ? llm.model : `${llm.provider}/${llm.model}`;
-}
-function getGenerationPlanningProfile(task) {
-  switch (task) {
-    case "index-fts":
-      return {
-        cacheableInputTokenPerWord: 0,
-        inputTokenPerWord: 0,
-        maxSecondsPerCall: 1,
-        minSecondsPerCall: 0,
-        outputTokenPerWord: 0,
-        secondsPerWord: 5e-4,
-        wordsPerCall: 1e5
-      };
-    case "index-embedding-source":
-    case "index-embedding-summary":
-      return {
-        cacheableInputTokenPerWord: 0,
-        inputTokenPerWord: 0,
-        maxSecondsPerCall: 10,
-        minSecondsPerCall: 1,
-        outputTokenPerWord: 0,
-        secondsPerWord: 2e-3,
-        wordsPerCall: 1e4
-      };
-    case "knowledge-graph":
-      return {
-        cacheableInputTokenPerWord: 60,
-        inputTokenPerWord: 80,
-        maxSecondsPerCall: 35,
-        minSecondsPerCall: 15,
-        outputTokenPerWord: 25,
-        secondsPerWord: 0.02,
-        wordsPerCall: 35
-      };
-    case "reading-graph":
-      return {
-        cacheableInputTokenPerWord: 20,
-        inputTokenPerWord: 25,
-        maxSecondsPerCall: 45,
-        minSecondsPerCall: 15,
-        outputTokenPerWord: 4,
-        secondsPerWord: 0.01,
-        wordsPerCall: 160
-      };
-    case "reading-summary":
+  const inspections = await Promise.all(
+    chapters.map(async (chapter) => {
+      const serial = await document.serials.getById(chapter.chapterId);
       return {
-        cacheableInputTokenPerWord: 45,
-        inputTokenPerWord: 55,
-        maxSecondsPerCall: 25,
-        minSecondsPerCall: 10,
-        outputTokenPerWord: 4,
-        secondsPerWord: 0.01,
-        wordsPerCall: 110
+        capabilities: {
+          knowledgeGraph: {
+            completed: serial?.knowledgeGraphReady === true
+          },
+          readingGraph: { completed: serial?.topologyReady === true },
+          readingSummary: { completed: chapter.stage === "summarized" }
+        },
+        chapter,
+        indexes: {
+          fts: inspectArtifact(
+            "fts",
+            coverageByKind.fts.get(chapter.chapterId)
+          ),
+          sourceEmbedding: inspectArtifact(
+            "embedding-source",
+            coverageByKind.sourceEmbedding.get(chapter.chapterId)
+          ),
+          summaryEmbedding: inspectArtifact(
+            "embedding-summary",
+            coverageByKind.summaryEmbedding.get(chapter.chapterId)
+          )
+        },
+        revision: serial?.revision ?? 0,
+        summaryWords: summaryWords.get(chapter.chapterId) ?? 0
       };
-  }
-}
-
-// src/archive/inspect.ts
-async function createWikiGraphArchiveInspectReport(document, options) {
-  const { archiveUri } = options;
-  const [
-    chapters,
-    summaryWords,
-    indexCacheCurrent,
-    config,
-    ftsArtifactCoverage,
-    sourceEmbeddingArtifactCoverage,
-    summaryEmbeddingArtifactCoverage
-  ] = await Promise.all([
-    readInspectChapters(document, options.chapterId),
-    readSummaryWords(document, options.chapterId),
-    (0, import_wiki_graph_core4.isArchiveSearchIndexCurrent)(document),
-    loadWikiGraphRuntimeConfig(),
-    readIndexArtifactCoverage(document, "fts", options.chapterId),
-    readIndexArtifactCoverage(document, "embedding-source", options.chapterId),
-    readIndexArtifactCoverage(document, "embedding-summary", options.chapterId)
-  ]);
-  const selectedChapter = options.chapterId === void 0 ? void 0 : chapters[0];
-  const scopeUri = selectedChapter === void 0 ? archiveUri : formatInspectLocatedChapterUri(archiveUri, selectedChapter);
-  const concurrent = {
-    job: config.concurrent?.job ?? DEFAULT_GENERATION_JOB_CONCURRENCY,
-    request: config.concurrent?.request ?? DEFAULT_GENERATION_REQUEST_CONCURRENCY
-  };
-  const planningModel = formatGenerationPlanningModel(config.llm);
-  const contentChapters = chapters.filter(
-    (chapter) => chapter.stage !== "planned"
-  );
-  const sourceWords = sumWords(contentChapters);
-  const readingGraphCovered = contentChapters.filter(
-    (chapter) => chapter.readingGraphReady
-  );
-  const knowledgeGraphCovered = contentChapters.filter(
-    (chapter) => chapter.knowledgeGraphReady
-  );
-  const summaryCovered = contentChapters.filter(
-    (chapter) => chapter.summaryReady
-  );
-  const ftsArtifactCovered = filterChaptersByCurrentIndexArtifact(
-    contentChapters,
-    ftsArtifactCoverage
-  );
-  const sourceEmbeddingArtifactCovered = filterChaptersByCurrentIndexArtifact(
-    contentChapters,
-    sourceEmbeddingArtifactCoverage
-  );
-  const summaryEmbeddingArtifactCovered = filterChaptersByCurrentIndexArtifact(
-    contentChapters,
-    summaryEmbeddingArtifactCoverage
-  );
-  const queryBlockedContentChapters = contentChapters.filter(
-    (chapter) => !ftsArtifactCovered.includes(chapter) && !sourceEmbeddingArtifactCovered.includes(chapter)
-  );
-  const queryBlockedChapters = queryBlockedContentChapters.map(
-    (chapter) => createInspectChapterReference(archiveUri, chapter)
+    })
   );
-  const queryReady = queryBlockedChapters.length === 0;
-  const improvements = createInspectImprovements({
-    concurrent,
-    contentChapters,
-    indexCacheCurrent,
-    planningModel,
-    queryBlockedChapters: queryBlockedContentChapters,
-    summaryCovered,
-    knowledgeGraphCovered,
-    readingGraphCovered
-  });
-  const performanceHints = createGenerationPerformanceHints({
-    chapters: Math.max(
-      0,
-      ...improvements.map((improvement) => improvement.missingChapters ?? 0)
-    ),
-    concurrent,
-    hasJobWork: improvements.some(
-      (improvement) => improvement.planning !== void 0
-    ),
-    hasRequestWork: improvements.some(
-      (improvement) => improvement.planning !== void 0
-    )
-  });
+  const selected = inspections[0];
   return {
-    archiveUri,
-    uri: scopeUri,
+    archiveUri: options.archiveUri,
+    chapters: inspections,
+    localIndexCache: { current: indexCacheCurrent },
     scope: options.chapterId === void 0 ? { type: "archive" } : { chapterId: options.chapterId, type: "chapter" },
-    content: {
-      chapters: {
-        content: contentChapters.length,
-        planned: chapters.length - contentChapters.length,
-        total: chapters.length
-      },
-      sourceWords,
-      summaryWords
-    },
-    localIndexCache: {
-      current: indexCacheCurrent,
-      ...!queryReady ? {
-        blockedBy: "missing-search-artifacts",
-        impact: "The cache cannot be built until every content chapter has a current FTS or source embedding artifact."
-      } : indexCacheCurrent ? {} : {
-        impact: "The next archive query may need to sync index cache first.",
-        resource: "local CPU/disk time only; no provider calls."
-      },
-      status: !queryReady ? "blocked" : indexCacheCurrent ? "current" : "missing-or-outdated",
-      syncAvailable: queryReady && !indexCacheCurrent
-    },
-    coverage: {
-      ftsIndexArtifact: createInspectCoverage(
-        ftsArtifactCovered,
-        contentChapters
-      ),
-      knowledgeGraph: createInspectCoverage(
-        knowledgeGraphCovered,
-        contentChapters
-      ),
-      readingGraph: createInspectCoverage(readingGraphCovered, contentChapters),
-      summary: createInspectCoverage(summaryCovered, contentChapters),
-      sourceEmbeddingIndexArtifact: createInspectCoverage(
-        sourceEmbeddingArtifactCovered,
-        contentChapters
-      ),
-      summaryEmbeddingIndexArtifact: createInspectCoverage(
-        summaryEmbeddingArtifactCovered,
-        contentChapters
-      )
-    },
-    query: {
-      ready: queryReady
-    },
-    searchArtifacts: {
-      blockedChapters: queryBlockedChapters,
-      ...!queryReady ? {
-        resource: "local CPU/disk time only; no provider calls."
-      } : {},
-      ready: queryReady,
-      status: queryReady ? "ready" : "incomplete"
-    },
-    retrievalGuidance: formatRetrievalGuidance({
-      indexCacheCurrent,
-      knowledgeGraphCovered,
-      readingGraphCovered,
-      contentChapters,
-      queryReady,
-      sourceWords
-    }),
-    improvements,
-    performanceHints,
-    summaryCoverageNote: "Summary coverage means a current summary artifact exists for the chapter; it does not guarantee that every source topic is represented in the summary text."
+    uri: selected === void 0 || options.chapterId === void 0 ? options.archiveUri : formatLocatedChapterUri(options.archiveUri, selected.chapter)
   };
 }
-function createInspectChapterReference(archiveUri, chapter) {
-  return {
-    chapterId: chapter.chapterId,
-    locatedUri: formatInspectLocatedChapterUri(archiveUri, chapter),
-    title: chapter.title,
-    uri: chapter.uri
-  };
-}
-function formatInspectLocatedChapterUri(archiveUri, chapter) {
-  return `${archiveUri.replace(/\/+$/u, "")}/${chapter.uri.replace(/^wikg:\/\//u, "")}`;
-}
-async function readInspectChapters(document, chapterId) {
-  const chapters = chapterId === void 0 ? await (0, import_wiki_graph_core4.listChapters)(document) : (await (0, import_wiki_graph_core4.listChapters)(document)).filter(
+function selectChapters(chapters, chapterId) {
+  if (chapterId === void 0) return chapters;
+  const selected = chapters.filter(
     (chapter) => chapter.chapterId === chapterId
   );
-  if (chapterId !== void 0 && chapters.length === 0) {
+  if (selected.length === 0) {
     throw new Error(`Chapter ${chapterId} does not exist.`);
   }
-  return await Promise.all(
-    chapters.map(async (chapter) => {
-      const serial = await document.serials.getById(chapter.chapterId);
-      return {
-        ...chapter,
-        knowledgeGraphReady: serial?.knowledgeGraphReady === true,
-        readingGraphReady: serial?.topologyReady === true,
-        summaryReady: chapter.stage === "summarized"
-      };
-    })
-  );
+  return selected;
 }
-async function readSummaryWords(document, chapterId) {
-  return await document.readDatabase(
-    async (database) => await database.queryOne(
-      `
-          SELECT COALESCE(SUM(words_count), 0) AS words
-          FROM text_sentence_records
-          WHERE kind = 2
-            ${chapterId === void 0 ? "" : "AND chapter_id = ?"}
-        `,
-      chapterId === void 0 ? void 0 : [chapterId],
-      (row) => Number(row.words)
-    ) ?? 0
-  );
+function byChapterId(coverage) {
+  return new Map(coverage.map((item) => [item.serialId, item]));
 }
-async function readIndexArtifactCoverage(document, kind, chapterId) {
-  const coverage = await document.indexArtifacts.listCoverage(kind);
-  return chapterId === void 0 ? coverage : coverage.filter((item) => item.serialId === chapterId);
-}
-function filterChaptersByCurrentIndexArtifact(chapters, coverage) {
-  const currentChapterIds = new Set(
-    coverage.filter((item) => item.current).map((item) => item.serialId)
-  );
-  return chapters.filter((chapter) => currentChapterIds.has(chapter.chapterId));
-}
-function createInspectCoverage(covered, total) {
-  const coveredWords = sumWords(covered);
-  const totalWords = sumWords(total);
+function inspectArtifact(kind, coverage) {
   return {
-    coveredChapters: covered.length,
-    coveredWords,
-    percent: formatPercent(coveredWords, totalWords),
-    totalChapters: total.length,
-    totalWords
+    current: coverage?.current === true,
+    exists: coverage?.sourceRevision !== void 0,
+    kind,
+    ...coverage?.sourceRevision === void 0 ? {} : { sourceRevision: coverage.sourceRevision }
   };
 }
-function formatRetrievalGuidance(input) {
-  if (input.sourceWords === 0 || input.contentChapters.length === 0) {
-    return [
-      "Source content: empty.",
-      "Add source text before using query coverage or graph-based retrieval."
-    ];
-  }
-  const lines = [
-    input.queryReady ? `Query: available; local index cache is ${input.indexCacheCurrent ? "current" : "missing or outdated and can be synced from artifacts"}.` : "Query: unavailable until every content chapter has a current FTS or source embedding artifact."
-  ];
-  lines.push(
-    formatObjectSearchGuidance(
-      "Reading Graph object retrieval",
-      input.readingGraphCovered,
-      input.contentChapters
-    )
-  );
-  lines.push(
-    formatObjectSearchGuidance(
-      "Entity/triple retrieval",
-      input.knowledgeGraphCovered,
-      input.contentChapters
+async function readSummaryWords(document) {
+  const rows = await document.readDatabase(
+    async (database) => await database.queryAll(
+      `
+        SELECT chapter_id, COALESCE(SUM(words_count), 0) AS words
+        FROM text_sentence_records
+        WHERE kind = 2
+        GROUP BY chapter_id
+      `,
+      void 0,
+      (row) => ({
+        chapterId: Number(row.chapter_id),
+        words: Number(row.words)
+      })
     )
   );
-  return lines;
-}
-function formatObjectSearchGuidance(label, covered, total) {
-  const coveredWords = sumWords(covered);
-  const totalWords = sumWords(total);
-  const ratio = totalWords === 0 ? 0 : coveredWords / totalWords;
-  const coverage = formatPercent(coveredWords, totalWords);
-  if (ratio >= 1) {
-    return `${label}: covers all source content; it can represent the full scope for object retrieval.`;
-  }
-  if (ratio >= 0.9) {
-    return `${label}: covers ${coverage}; use it as the main path, but source --query is needed for uncovered content.`;
-  }
-  if (ratio >= 0.5) {
-    return `${label}: covers ${coverage}; use it as leads, not as a full-scope substitute for source --query.`;
-  }
-  return `${label}: covers ${coverage}; build missing graph coverage before relying on object retrieval.`;
-}
-function createInspectImprovements(input) {
-  const improvements = [];
-  if (input.contentChapters.length === 0) {
-    improvements.push({
-      kind: "add-source",
-      recommendation: "No source content is available yet; add or import source text before graph or summary generation.",
-      title: "Add source content"
-    });
-    return improvements;
-  }
-  if (input.queryBlockedChapters.length > 0) {
-    improvements.push({
-      kind: "build",
-      missingChapters: input.queryBlockedChapters.length,
-      missingWords: sumWords(input.queryBlockedChapters),
-      recommendation: "Build local FTS artifacts to make this scope queryable. This does not call a provider.",
-      task: "index-fts",
-      title: "Enable query with local FTS"
-    });
-  } else if (!input.indexCacheCurrent) {
-    improvements.push({
-      kind: "sync-index",
-      recommendation: "Sync the index cache from chapter index artifacts so query starts without a lazy cache rebuild.",
-      title: "Sync index cache"
-    });
-  }
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.readingGraphCovered,
-      planningModel: input.planningModel,
-      task: "reading-graph",
-      title: "Complete Reading Graph coverage",
-      total: input.contentChapters
-    })
-  );
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.knowledgeGraphCovered,
-      planningModel: input.planningModel,
-      task: "knowledge-graph",
-      title: "Complete Knowledge Graph coverage",
-      total: input.contentChapters
-    })
-  );
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.summaryCovered,
-      planningModel: input.planningModel,
-      task: "reading-summary",
-      title: "Complete Summary coverage",
-      total: input.contentChapters
-    })
-  );
-  return improvements;
+  return new Map(rows.map((row) => [row.chapterId, row.words]));
 }
-function createGraphImprovement(input) {
-  const coveredIds = new Set(input.covered.map((chapter) => chapter.chapterId));
-  const missing = input.total.filter(
-    (chapter) => !coveredIds.has(chapter.chapterId)
-  );
-  if (missing.length === 0) {
-    return [];
-  }
-  const missingWords = sumWords(missing);
-  return [
-    {
-      kind: "build",
-      missingChapters: missing.length,
-      missingWords,
-      planning: planGenerationTask(
-        input.task,
-        missingWords,
-        missing.length,
-        input.concurrent,
-        input.planningModel
-      ),
-      recommendation: formatImprovementRecommendation(
-        input.covered,
-        input.total,
-        missingWords
-      ),
-      task: input.task,
-      title: input.title
-    }
-  ];
-}
-function formatImprovementRecommendation(covered, total, missingWords) {
-  const totalWords = sumWords(total);
-  const coveredWords = sumWords(covered);
-  if (totalWords === 0) {
-    return "No source content is available.";
-  }
-  if (total.length === 1 || coveredWords / totalWords >= 0.9 || missingWords <= 1e3) {
-    return "Queue the full scope to finish the remaining gap.";
-  }
-  return "Queue selected chapters first if only part of the scope matters.";
-}
-function sumWords(chapters) {
-  return chapters.reduce((total, chapter) => total + chapter.words, 0);
+function formatLocatedChapterUri(archiveUri, chapter) {
+  return `${archiveUri.replace(/\/+$/u, "")}/${chapter.uri.replace(/^wikg:\/\//u, "")}`;
 }
-function formatPercent(numerator, denominator) {
-  if (denominator === 0) {
-    return "n/a";
+
+// src/archive/write.ts
+var import_wiki_graph_core6 = require("wiki-graph-core");
+async function writeWikiGraphArchiveLocation(location, operation, options = {}) {
+  const cacheOnly = options.searchIndexWritebackPolicy === "cache";
+  const write = async (archiveFile = location.archiveFile) => await new import_wiki_graph_core6.WikiGraphArchiveFile(archiveFile).write(operation, {
+    ...cacheOnly ? {} : { derivedStateKeys: [location.archiveKey, location.archivePath] },
+    ...options.invalidateContinuationCursors === void 0 ? {} : {
+      invalidateContinuationCursors: options.invalidateContinuationCursors
+    },
+    ...options.searchIndexWritebackPolicy === void 0 ? {} : { searchIndexWritebackPolicy: options.searchIndexWritebackPolicy }
+  });
+  if (location.libraryArchiveTarget === void 0 || cacheOnly || options.refreshLibraryIndex === false) {
+    return await write();
   }
-  const percent = numerator / denominator * 100;
-  return `${Number.isInteger(percent) ? percent.toFixed(0) : percent.toFixed(1)}%`;
+  return await (0, import_wiki_graph_core6.writeWikiGraphLibraryArchive)({
+    additionalDerivedStateKeys: [location.archiveKey, location.archivePath],
+    ...options.invalidateContinuationCursors === void 0 ? {} : {
+      invalidateContinuationCursors: options.invalidateContinuationCursors
+    },
+    ...options.onIndexSyncError === void 0 ? {} : { onIndexSyncError: options.onIndexSyncError },
+    operation: async (archiveFile) => await write(archiveFile),
+    target: location.libraryArchiveTarget
+  });
 }
 
 // src/archive/archive.ts
@@ -2015,13 +1898,13 @@ var WikiGraphArchiveManager = class {
   }
   async create(options) {
     return await this.#runtime.run(async () => {
-      const path = resolveWikiGraphRuntimePath(options.path);
+      const path = await assertStandaloneWikiGraphArchivePath(options.path);
       if (options.replace !== true && await nodePathExists(path)) {
         throw new WikiGraphArchiveExistsError(path);
       }
-      const outputPath = (0, import_path3.join)(
-        (0, import_path3.dirname)(path),
-        `.${(0, import_path3.basename)(path)}.${(0, import_crypto.randomUUID)()}.tmp.wikg`
+      const outputPath = (0, import_path5.join)(
+        (0, import_path5.dirname)(path),
+        `.${(0, import_path5.basename)(path)}.${(0, import_crypto2.randomUUID)()}.tmp.wikg`
       );
       try {
         if (options.importPath === void 0) {
@@ -2035,10 +1918,10 @@ var WikiGraphArchiveManager = class {
           });
         }
         if (options.replace === true) {
-          await (0, import_promises3.rename)(outputPath, path);
+          await (0, import_promises4.rename)(outputPath, path);
         } else {
           try {
-            await (0, import_promises3.link)(outputPath, path);
+            await (0, import_promises4.link)(outputPath, path);
           } catch (error) {
             if (isNodeEEXISTError(error)) {
               throw new WikiGraphArchiveExistsError(path);
@@ -2046,15 +1929,15 @@ var WikiGraphArchiveManager = class {
             throw error;
           }
         }
-        return { locatedUri: (0, import_wiki_graph_core5.formatLocatedWikiGraphUri)(path), path };
+        return { locatedUri: (0, import_wiki_graph_core7.formatLocatedWikiGraphUri)(path), path };
       } finally {
-        await (0, import_promises3.rm)(outputPath, { force: true, recursive: true });
+        await (0, import_promises4.rm)(outputPath, { force: true, recursive: true });
       }
     }, options.signal);
   }
-  async open(uriOrPath, options = {}) {
+  async open(target, options = {}) {
     const location = await this.#runtime.run(
-      async () => await resolveWikiGraphArchiveLocation(uriOrPath),
+      async () => await resolveWikiGraphArchiveLocation(target),
       options.signal
     );
     return new WikiGraphArchiveHandle(this.#runtime, location);
@@ -2077,14 +1960,17 @@ var WikiGraphArchiveHandle = class {
     return this.#location.locatedUri;
   }
   get objectUri() {
-    return (0, import_wiki_graph_core5.parseLocatedWikiGraphUri)(this.#location.locatedUri).objectUri ?? "wikg://";
+    return (0, import_wiki_graph_core7.parseLocatedWikiGraphUri)(this.#location.locatedUri).objectUri ?? "wikg://";
   }
   get path() {
     return this.#location.archivePath;
   }
+  get target() {
+    return this.#location.target;
+  }
   async inspect(options = {}) {
     return await this.#readDocument(
-      async (document) => await createWikiGraphArchiveInspectReport(document, {
+      async (document) => await inspectWikiGraphArchive(document, {
         archiveUri: this.#location.publicArchiveUri ?? this.locatedUri,
         ...options.chapterId === void 0 ? {} : { chapterId: options.chapterId }
       }),
@@ -2103,7 +1989,7 @@ var WikiGraphArchiveHandle = class {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
-        return await (0, import_wiki_graph_core5.findArchiveObjects)(document, query, {
+        return await (0, import_wiki_graph_core7.findArchiveObjects)(document, query, {
           ...withoutOperationAndScope(options),
           archiveKey: this.archiveKey,
           ...chapters === void 0 ? {} : { chapters },
@@ -2118,14 +2004,14 @@ var WikiGraphArchiveHandle = class {
   }
   async list(options = {}) {
     return await this.#readDocument(async (document) => {
-      if ((0, import_wiki_graph_core5.isSourceLocatorScopeUri)(this.objectUri)) {
-        return await (0, import_wiki_graph_core5.listArchiveSourceLocators)(document, this.objectUri, {
+      if ((0, import_wiki_graph_core7.isSourceLocatorScopeUri)(this.objectUri)) {
+        return await (0, import_wiki_graph_core7.listArchiveSourceLocators)(document, this.objectUri, {
           ...options.cursor === void 0 ? {} : { cursor: options.cursor },
           ...options.limit === void 0 ? {} : { limit: options.limit }
         });
       }
       const chapters = await this.#resolveScope(document, options);
-      return await (0, import_wiki_graph_core5.listArchiveCollection)(document, {
+      return await (0, import_wiki_graph_core7.listArchiveCollection)(document, {
         ...withoutOperationAndScope(options),
         ...chapters === void 0 ? {} : { chapters }
       });
@@ -2153,8 +2039,8 @@ var WikiGraphArchiveHandle = class {
   async getSearchIndexStatus(options = {}) {
     return await this.#readDocument(
       async (document) => ({
-        capabilities: await (0, import_wiki_graph_core5.readSearchIndexCapabilityStatus)(document),
-        current: await (0, import_wiki_graph_core5.isArchiveSearchIndexCurrent)(document)
+        capabilities: await (0, import_wiki_graph_core7.readSearchIndexCapabilityStatus)(document),
+        current: await (0, import_wiki_graph_core7.isArchiveSearchIndexCurrent)(document)
       }),
       options
     );
@@ -2162,14 +2048,14 @@ var WikiGraphArchiveHandle = class {
   async syncSearchIndex(options = {}) {
     const rebuilt = await this.#writeDocument(
       async (document) => {
-        const scope = options.skipUnindexed === true ? { chapters: await (0, import_wiki_graph_core5.listArchiveQueryableChapterIds)(document) } : {};
+        const scope = options.skipUnindexed === true ? { chapters: await (0, import_wiki_graph_core7.listArchiveQueryableChapterIds)(document) } : {};
         if (scope.chapters?.length === 0) {
           throw new Error(
             "Wiki Graph index cache is not ready. No chapters have a current FTS artifact or source embedding artifact."
           );
         }
-        if (await (0, import_wiki_graph_core5.isArchiveSearchIndexCurrent)(document, scope)) return false;
-        await (0, import_wiki_graph_core5.rebuildArchiveSearchIndex)(document, options.onProgress, scope);
+        if (await (0, import_wiki_graph_core7.isArchiveSearchIndexCurrent)(document, scope)) return false;
+        await (0, import_wiki_graph_core7.rebuildArchiveSearchIndex)(document, options.onProgress, scope);
         return true;
       },
       {
@@ -2178,7 +2064,7 @@ var WikiGraphArchiveHandle = class {
       }
     );
     await this.#runtime.run(
-      async () => await (0, import_wiki_graph_core5.deleteArchiveSearchSessions)(this.path),
+      async () => await (0, import_wiki_graph_core7.deleteArchiveSearchSessions)(this.path),
       options.signal
     );
     return { rebuilt };
@@ -2201,21 +2087,21 @@ var WikiGraphArchiveHandle = class {
       }
     );
     await this.#runtime.run(
-      async () => await (0, import_wiki_graph_core5.deleteArchiveSearchSessions)(this.path),
+      async () => await (0, import_wiki_graph_core7.deleteArchiveSearchSessions)(this.path),
       options.signal
     );
     return status;
   }
   async listChapters(options = {}) {
     return await this.#readDocument(
-      async (document) => await (0, import_wiki_graph_core5.listChapters)(document),
+      async (document) => await (0, import_wiki_graph_core7.listChapters)(document),
       options
     );
   }
   async getChapter(path, options = {}) {
     return await this.#readDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
-      return requireChapter(await (0, import_wiki_graph_core5.listChapters)(document), chapterId);
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
+      return requireChapter(await (0, import_wiki_graph_core7.listChapters)(document), chapterId);
     }, options);
   }
   async addChapter(options) {
@@ -2224,17 +2110,17 @@ var WikiGraphArchiveHandle = class {
         document,
         options.parentPath
       );
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobConflicts)({
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobConflicts)({
         archive: this.#location.archiveFile,
         operation: "Adding chapter",
         scope: { kind: "archive" }
       });
-      let details = await (0, import_wiki_graph_core5.addChapter)(document, {
+      let details = await (0, import_wiki_graph_core7.addChapter)(document, {
         ...parentChapterId === void 0 ? {} : { parentChapterId },
         ...options.title === void 0 ? {} : { title: options.title }
       });
       if (options.source !== void 0) {
-        details = await (0, import_wiki_graph_core5.setChapterSource)(
+        details = await (0, import_wiki_graph_core7.setChapterSource)(
           document,
           details.chapterId,
           asTextStream(options.source)
@@ -2245,7 +2131,7 @@ var WikiGraphArchiveHandle = class {
   }
   async getChapterArtifact(path, kind) {
     return await this.#readDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
       const [artifact, revision] = await Promise.all([
         document.indexArtifacts.get(chapterId, kind),
         document.serials.getRevision(chapterId)
@@ -2268,25 +2154,25 @@ var WikiGraphArchiveHandle = class {
   }
   async deleteChapterArtifact(path, kind) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
       await document.indexArtifacts.delete(chapterId, kind);
       return { chapterId, deleted: true, kind };
     });
   }
   async moveChapter(path, options) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
       const [afterChapterId, beforeChapterId, parentChapterId] = await Promise.all([
         resolveOptionalChapterPath(document, options.afterPath),
         resolveOptionalChapterPath(document, options.beforePath),
         resolveOptionalChapterPath(document, options.parentPath)
       ]);
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobConflicts)({
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobConflicts)({
         archive: this.#location.archiveFile,
         operation: "Moving chapter",
         scope: { kind: "archive" }
       });
-      return await (0, import_wiki_graph_core5.moveChapter)(document, chapterId, {
+      return await (0, import_wiki_graph_core7.moveChapter)(document, chapterId, {
         ...afterChapterId === void 0 ? {} : { afterChapterId },
         ...beforeChapterId === void 0 ? {} : { beforeChapterId },
         ...parentChapterId === void 0 ? {} : { parentChapterId },
@@ -2298,35 +2184,35 @@ var WikiGraphArchiveHandle = class {
   }
   async removeChapter(path, recursive = false) {
     await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobConflicts)({
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobConflicts)({
         archive: this.#location.archiveFile,
         operation: "Removing chapter",
         scope: { kind: "archive" }
       });
-      await (0, import_wiki_graph_core5.removeChapter)(document, chapterId, { recursive });
+      await (0, import_wiki_graph_core7.removeChapter)(document, chapterId, { recursive });
     });
   }
   async resetChapter(path, stage) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
       await assertChapterResetAllowed(
         this.#location.archiveFile,
         chapterId,
         stage
       );
-      return await (0, import_wiki_graph_core5.resetChapter)(document, chapterId, stage);
+      return await (0, import_wiki_graph_core7.resetChapter)(document, chapterId, stage);
     });
   }
   async setChapterSource(path, source, options = {}) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
         archive: this.#location.archiveFile,
         chapterIds: [chapterId],
         operation: "Setting chapter source"
       });
-      return await (0, import_wiki_graph_core5.setChapterSource)(
+      return await (0, import_wiki_graph_core7.setChapterSource)(
         document,
         chapterId,
         asTextStream(source),
@@ -2336,43 +2222,43 @@ var WikiGraphArchiveHandle = class {
   }
   async setChapterSummary(path, summary) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
         archive: this.#location.archiveFile,
         chapterIds: [chapterId],
         operation: "Setting chapter summary",
         requiresTarget: "reading-summary"
       });
-      return await (0, import_wiki_graph_core5.setChapterSummary)(document, chapterId, summary);
+      return await (0, import_wiki_graph_core7.setChapterSummary)(document, chapterId, summary);
     });
   }
   async setChapterTitle(path, title) {
     return await this.#writeDocument(async (document) => {
-      const chapterId = await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
-      await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+      const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
+      await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
         archive: this.#location.archiveFile,
         chapterIds: [chapterId],
         operation: "Setting chapter title"
       });
-      return await (0, import_wiki_graph_core5.setChapterTitle)(document, chapterId, title);
+      return await (0, import_wiki_graph_core7.setChapterTitle)(document, chapterId, title);
     });
   }
   async getChapterTree() {
     return await this.#readDocument(
-      async (document) => await (0, import_wiki_graph_core5.getChapterTree)(document)
+      async (document) => await (0, import_wiki_graph_core7.getChapterTree)(document)
     );
   }
   async applyChapterTree(tree, options = {}) {
     return await this.#writeDocument(
       async (document) => {
         if (options.dryRun !== true) {
-          await (0, import_wiki_graph_core5.assertNoActiveBuildJobConflicts)({
+          await (0, import_wiki_graph_core7.assertNoActiveBuildJobConflicts)({
             archive: this.#location.archiveFile,
             operation: "Changing chapter tree",
             scope: { kind: "archive" }
           });
         }
-        return await (0, import_wiki_graph_core5.applyChapterTree)(document, tree, {
+        return await (0, import_wiki_graph_core7.applyChapterTree)(document, tree, {
           dryRun: options.dryRun ?? false
         });
       },
@@ -2384,8 +2270,8 @@ var WikiGraphArchiveHandle = class {
       async () => await withConfiguredWikimediaResolver(
         objectUri,
         async (wikimediaOptions) => await this.#readDocument(
-          async (document) => await (0, import_wiki_graph_core5.readArchivePage)(document, objectUri, {
-            ...withoutOperation(options),
+          async (document) => await (0, import_wiki_graph_core7.readArchivePage)(document, objectUri, {
+            ...options,
             ...wikimediaOptions
           }),
           options
@@ -2398,7 +2284,7 @@ var WikiGraphArchiveHandle = class {
     if (options.query === void 0) {
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
-        return await (0, import_wiki_graph_core5.listRelatedArchiveObjects)(document, objectUri, {
+        return await (0, import_wiki_graph_core7.listRelatedArchiveObjects)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
@@ -2415,7 +2301,7 @@ var WikiGraphArchiveHandle = class {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
-        return await (0, import_wiki_graph_core5.listRelatedArchiveObjects)(document, objectUri, {
+        return await (0, import_wiki_graph_core7.listRelatedArchiveObjects)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
@@ -2430,7 +2316,7 @@ var WikiGraphArchiveHandle = class {
     if (options.query === void 0) {
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
-        return await (0, import_wiki_graph_core5.listArchiveEvidence)(document, objectUri, {
+        return await (0, import_wiki_graph_core7.listArchiveEvidence)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
@@ -2447,7 +2333,7 @@ var WikiGraphArchiveHandle = class {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
-        return await (0, import_wiki_graph_core5.listArchiveEvidence)(document, objectUri, {
+        return await (0, import_wiki_graph_core7.listArchiveEvidence)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
@@ -2460,7 +2346,7 @@ var WikiGraphArchiveHandle = class {
   }
   async pack(objectUri = this.objectUri, budget = 5e3, options = {}) {
     return await this.#readDocument(
-      async (document) => await (0, import_wiki_graph_core5.packArchiveContext)(document, objectUri, budget),
+      async (document) => await (0, import_wiki_graph_core7.packArchiveContext)(document, objectUri, budget),
       options
     );
   }
@@ -2483,7 +2369,7 @@ var WikiGraphArchiveHandle = class {
     }, options);
   }
   async readCover(options = {}) {
-    const app = new import_wiki_graph_core5.WikiGraph({});
+    const app = new import_wiki_graph_core7.WikiGraph({});
     return await this.#runtime.run(
       async () => await app.openSession(
         this.#location.archiveFile,
@@ -2531,7 +2417,7 @@ var WikiGraphArchiveHandle = class {
   }
   async #readDocument(operation, options = {}) {
     return await this.#runtime.run(
-      async () => await new import_wiki_graph_core5.WikiGraphArchiveFile(this.#location.archiveFile).readDocument(
+      async () => await new import_wiki_graph_core7.WikiGraphArchiveFile(this.#location.archiveFile).readDocument(
         operation
       ),
       options.signal
@@ -2539,17 +2425,13 @@ var WikiGraphArchiveHandle = class {
   }
   async #writeDocument(operation, options = {}) {
     return await this.#runtime.run(async () => {
-      const result = await new import_wiki_graph_core5.WikiGraphArchiveFile(
-        this.#location.archiveFile
-      ).write(operation, {
+      return await writeWikiGraphArchiveLocation(this.#location, operation, {
+        ...options.onIndexSyncError === void 0 ? {} : { onIndexSyncError: options.onIndexSyncError },
+        ...options.refreshLibraryIndex === void 0 ? {} : { refreshLibraryIndex: options.refreshLibraryIndex },
         ...options.searchIndexWritebackPolicy === void 0 ? {} : {
           searchIndexWritebackPolicy: options.searchIndexWritebackPolicy
         }
       });
-      if (options.refreshLibraryIndex !== false) {
-        await this.#refreshLibraryIndex(options.onIndexSyncError);
-      }
-      return result;
     }, options.signal);
   }
   async #resolveScope(document, options) {
@@ -2559,7 +2441,7 @@ var WikiGraphArchiveHandle = class {
   async #resolveQueryChapters(document, options) {
     const chapters = await this.#resolveScope(document, options);
     if (options.skipUnindexed !== true) return chapters;
-    const queryable = await (0, import_wiki_graph_core5.listArchiveQueryableChapterIds)(document, {
+    const queryable = await (0, import_wiki_graph_core7.listArchiveQueryableChapterIds)(document, {
       ...chapters === void 0 ? {} : { chapters }
     });
     if (queryable.length === 0) {
@@ -2569,56 +2451,11 @@ var WikiGraphArchiveHandle = class {
     }
     return queryable;
   }
-  async #refreshLibraryIndex(onError) {
-    if (this.#location.libraryDirtyTarget === void 0) return;
-    if (this.#location.libraryArchiveTarget !== void 0) {
-      await (0, import_wiki_graph_core5.finalizeWikiGraphLibraryArchiveWrite)({
-        target: this.#location.libraryArchiveTarget
-      });
-    }
-    try {
-      const state = await (0, import_wiki_graph_core5.readWikiGraphLibraryIndexState)(
-        this.#location.libraryDirtyTarget
-      );
-      if (state.status !== "missing") {
-        await (0, import_wiki_graph_core5.rebuildWikiGraphLibraryIndex)(this.#location.libraryDirtyTarget);
-      }
-    } catch (error) {
-      onError?.(error);
-    }
-  }
 };
-async function resolveWikiGraphArchiveLocation(uriOrPath) {
-  if (!uriOrPath.startsWith("wikg://")) {
-    return createPathLocation(resolveWikiGraphRuntimePath(uriOrPath));
-  }
-  const parsed = (0, import_wiki_graph_core5.parseLocatedWikiGraphUri)(uriOrPath);
-  const portableArchiveLocator = parsed.archivePath ?? uriOrPath;
-  const archiveLocator = portableArchiveLocator.startsWith("wikg://lib/") ? portableArchiveLocator : resolveWikiGraphRuntimePath(portableArchiveLocator);
-  const libraryArchiveTarget = archiveLocator.startsWith("wikg://lib/") ? (0, import_wiki_graph_core5.parseWikiGraphLibraryUri)(archiveLocator) : void 0;
-  const archiveFile = libraryArchiveTarget?.kind === "archive" ? await (0, import_wiki_graph_core5.resolveWikiGraphLibraryArchiveFile)(archiveLocator) : new NodeFile(archiveLocator);
-  const archivePath = getNodeResourcePath(archiveFile);
-  return {
-    archiveFile,
-    archiveKey: archivePath,
-    archivePath,
-    indexScope: { archiveKey: archivePath, archivePath, kind: "archive-index" },
-    ...libraryArchiveTarget?.kind === "archive" ? {
-      libraryArchiveTarget,
-      libraryDirtyTarget: {
-        isDefault: libraryArchiveTarget.isDefault,
-        kind: "scope",
-        ...libraryArchiveTarget.publicId === void 0 ? {} : { publicId: libraryArchiveTarget.publicId }
-      },
-      publicArchiveUri: portableArchiveLocator
-    } : {},
-    locatedUri: (0, import_wiki_graph_core5.formatLocatedWikiGraphUri)(archivePath, parsed.objectUri)
-  };
-}
 async function ensureArchiveSearchIndex(document, options = {}) {
   const scope = options.chapters === void 0 ? {} : { chapters: options.chapters };
-  if (await (0, import_wiki_graph_core5.isArchiveSearchIndexCurrent)(document, scope)) return;
-  await (0, import_wiki_graph_core5.rebuildArchiveSearchIndex)(document, void 0, {
+  if (await (0, import_wiki_graph_core7.isArchiveSearchIndexCurrent)(document, scope)) return;
+  await (0, import_wiki_graph_core7.rebuildArchiveSearchIndex)(document, void 0, {
     ...scope,
     ...options.embeddingProvider === void 0 ? {} : { embeddingProvider: options.embeddingProvider }
   });
@@ -2628,10 +2465,10 @@ async function resolveArchiveScope(document, objectUri, depth) {
   if (parsed === void 0 || parsed.kind === "collection" && depth === void 0) {
     return void 0;
   }
-  const chapters = await (0, import_wiki_graph_core5.listChapters)(document);
+  const chapters = await (0, import_wiki_graph_core7.listChapters)(document);
   const entries = parsed.kind === "collection" ? chapters.filter((chapter) => chapter.depth <= depth) : selectChapterSubtree(
     chapters,
-    await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, parsed.chapterPath),
+    await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, parsed.chapterPath),
     depth
   );
   return { chapterIds: entries.map((entry) => entry.chapterId), entries };
@@ -2653,32 +2490,23 @@ function selectChapterSubtree(chapters, rootChapterId, depth) {
     (chapter) => chapter.chapterId === root.chapterId || chapter.path.startsWith(prefix) && (depth === void 0 || chapter.depth - root.depth <= depth)
   );
 }
-function createPathLocation(path) {
-  return {
-    archiveFile: new NodeFile(path),
-    archiveKey: path,
-    archivePath: path,
-    indexScope: { archiveKey: path, archivePath: path, kind: "archive-index" },
-    locatedUri: (0, import_wiki_graph_core5.formatLocatedWikiGraphUri)(path)
-  };
-}
 async function createEmptyArchiveFile(path) {
-  const directoryPath = await (0, import_promises3.mkdtemp)(
-    (0, import_path3.join)((0, import_os3.tmpdir)(), "wikigraph-archive-write-")
+  const directoryPath = await (0, import_promises4.mkdtemp)(
+    (0, import_path5.join)((0, import_os3.tmpdir)(), "wikigraph-archive-write-")
   );
   try {
     const directory = new NodeDirectory(directoryPath);
-    const document = await import_wiki_graph_core5.DirectoryDocument.open(directory);
+    const document = await import_wiki_graph_core7.DirectoryDocument.open(directory);
     try {
       await document.openSession(async (openedDocument) => {
-        await openedDocument.writeToc({ items: [], version: import_wiki_graph_core5.TOC_FILE_VERSION });
+        await openedDocument.writeToc({ items: [], version: import_wiki_graph_core7.TOC_FILE_VERSION });
       });
     } finally {
       await document.release();
     }
-    await (0, import_wiki_graph_core5.writeWikgArchive)(directory, new NodeFile(path));
+    await (0, import_wiki_graph_core7.writeWikgArchive)(directory, new NodeFile(path));
   } finally {
-    await (0, import_promises3.rm)(directoryPath, { force: true, recursive: true });
+    await (0, import_promises4.rm)(directoryPath, { force: true, recursive: true });
   }
 }
 function isNodeEEXISTError(error) {
@@ -2686,7 +2514,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await (0, import_promises3.stat)(path);
+    await (0, import_promises4.stat)(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -2698,13 +2526,13 @@ function isNodeENOENTError(error) {
 }
 function parseObjectMetadataTarget(objectPath) {
   if (objectPath === "") {
-    return { kind: import_wiki_graph_core5.ObjectMetadataKind.Archive, objectPath };
+    return { kind: import_wiki_graph_core7.ObjectMetadataKind.Archive, objectPath };
   }
   const chapter = /^chapter\/([1-9][0-9]*)(?:\/.*)?$/u.exec(objectPath);
   if (chapter?.[1] !== void 0) {
     return {
       chapterId: Number(chapter[1]),
-      kind: import_wiki_graph_core5.ObjectMetadataKind.Chapter,
+      kind: import_wiki_graph_core7.ObjectMetadataKind.Chapter,
       objectPath
     };
   }
@@ -2712,7 +2540,7 @@ function parseObjectMetadataTarget(objectPath) {
   if (chunk?.[1] !== void 0) {
     return {
       chunkId: Number(chunk[1]),
-      kind: import_wiki_graph_core5.ObjectMetadataKind.Chunk,
+      kind: import_wiki_graph_core7.ObjectMetadataKind.Chunk,
       objectPath
     };
   }
@@ -2720,7 +2548,7 @@ function parseObjectMetadataTarget(objectPath) {
   if (entity?.[1] !== void 0) {
     return {
       entityQid: entity[1],
-      kind: import_wiki_graph_core5.ObjectMetadataKind.Entity,
+      kind: import_wiki_graph_core7.ObjectMetadataKind.Entity,
       objectPath
     };
   }
@@ -2729,14 +2557,14 @@ function parseObjectMetadataTarget(objectPath) {
   );
   if (triple?.[1] !== void 0) {
     return {
-      kind: import_wiki_graph_core5.ObjectMetadataKind.Triple,
+      kind: import_wiki_graph_core7.ObjectMetadataKind.Triple,
       objectPath,
       tripleObjectQid: triple[3],
       triplePredicate: decodeURIComponent(triple[2]),
       tripleSubjectQid: triple[1]
     };
   }
-  return { kind: import_wiki_graph_core5.ObjectMetadataKind.Object, objectPath };
+  return { kind: import_wiki_graph_core7.ObjectMetadataKind.Object, objectPath };
 }
 function withoutOperation(options) {
   const { signal: _signal, ...rest } = options;
@@ -2752,7 +2580,7 @@ function withoutOperationAndScope(options) {
   return rest;
 }
 async function resolveOptionalChapterPath(document, path) {
-  return path === void 0 ? void 0 : await (0, import_wiki_graph_core5.resolveChapterPathReadonly)(document, path);
+  return path === void 0 ? void 0 : await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
 }
 function requireChapter(chapters, chapterId) {
   const chapter = chapters.find((entry) => entry.chapterId === chapterId);
@@ -2766,7 +2594,7 @@ function asTextStream(text) {
 }
 async function assertChapterResetAllowed(archive, chapterId, stage) {
   if (stage === "planned") {
-    await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+    await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
       archive,
       chapterIds: [chapterId],
       operation: "Resetting chapter to planned"
@@ -2774,14 +2602,14 @@ async function assertChapterResetAllowed(archive, chapterId, stage) {
     return;
   }
   if (stage === "sourced") {
-    await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+    await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
       archive,
       chapterIds: [chapterId],
       operation: "Resetting chapter graph",
       requiresTarget: "reading-graph"
     });
   }
-  await (0, import_wiki_graph_core5.assertNoActiveBuildJobs)({
+  await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
     archive,
     chapterIds: [chapterId],
     operation: "Resetting chapter summary",
@@ -2793,7 +2621,7 @@ async function assertChapterResetAllowed(archive, chapterId, stage) {
   WikiGraphArchiveExistsError,
   WikiGraphArchiveHandle,
   WikiGraphArchiveManager,
-  createWikiGraphArchiveInspectReport,
-  resolveWikiGraphArchiveLocation
+  WikiGraphArchiveOwnershipError,
+  inspectWikiGraphArchive
 });
 //# sourceMappingURL=archives.cjs.map