wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/archives.js

@@ -4,9 +4,9 @@ globalThis.__WIKIGRAPH_DATA_DIR__ ??= __WIKIGRAPH_RESOLVE__(__WIKIGRAPH_FILE_URL
 
 // src/archive/archive.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { link, mkdtemp, rename as rename2, rm as rm3, stat as stat2 } from "fs/promises";
+import { link, mkdtemp, rename as rename2, rm as rm3, stat as stat3 } from "fs/promises";
 import { tmpdir } from "os";
-import { basename as basename2, dirname as dirname2, join as join3 } from "path";
+import { basename as basename4, dirname as dirname3, join as join4 } from "path";
 import { Readable as Readable2 } from "stream";
 import {
   addChapter,
@@ -15,9 +15,8 @@ import {
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
   DirectoryDocument,
-  finalizeWikiGraphLibraryArchiveWrite,
   findArchiveObjects,
-  formatLocatedWikiGraphUri,
+  formatLocatedWikiGraphUri as formatLocatedWikiGraphUri2,
   isArchiveSearchIndexCurrent as isArchiveSearchIndexCurrent2,
   isSourceLocatorScopeUri,
   listArchiveCollection,
@@ -28,30 +27,29 @@ import {
   listRelatedArchiveObjects,
   moveChapter,
   packArchiveContext,
-  parseLocatedWikiGraphUri,
-  parseWikiGraphLibraryUri,
+  parseLocatedWikiGraphUri as parseLocatedWikiGraphUri2,
   readArchivePage,
   readSearchIndexCapabilityStatus,
-  readWikiGraphLibraryIndexState,
   rebuildArchiveSearchIndex,
-  rebuildWikiGraphLibraryIndex,
   removeChapter,
   resetChapter,
   resolveChapterPathReadonly,
-  resolveWikiGraphLibraryArchiveFile,
   setChapterSource,
   setChapterSummary,
   setChapterTitle,
   getChapterTree,
   WikiGraph as WikiGraph2,
-  WikiGraphArchiveFile,
+  WikiGraphArchiveFile as WikiGraphArchiveFile2,
   TOC_FILE_VERSION,
   writeWikgArchive,
   ObjectMetadataKind
 } from "wiki-graph-core";
 
 // src/conversions.ts
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
 import { rm as rm2 } from "fs/promises";
+import { basename as basename3 } from "path";
 import {
   WikiGraph
 } from "wiki-graph-core";
@@ -380,42 +378,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();
       });
     });
   }
@@ -429,10 +427,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);
     });
   });
 }
@@ -441,19 +439,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();
@@ -463,7 +461,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve3(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -573,12 +571,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);
@@ -709,11 +707,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 = {
@@ -1266,6 +1264,173 @@ function resolveWikiGraphRuntimePath(path) {
   return isAbsolute2(path) ? path : resolve2(context.cwd, 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 {
+  formatLocatedWikiGraphUri,
+  formatWikiGraphLibraryUri,
+  listWikiGraphLibraries,
+  listWikiGraphLibraryArchives,
+  parseLocatedWikiGraphUri,
+  parseWikiGraphLibraryUri,
+  resolveWikiGraphLibrary,
+  resolveWikiGraphLibraryArchiveFile
+} from "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 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 ${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 ${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: formatLocatedWikiGraphUri(path, target.objectUri),
+    target: normalized
+  };
+}
+async function resolveLibraryLocation(target) {
+  const parsedLocated = parseLocatedWikiGraphUri(target.uri);
+  const archiveUri = parsedLocated.archivePath ?? target.uri;
+  const parsed = parseWikiGraphLibraryUri(archiveUri);
+  if (parsed?.kind !== "archive") {
+    throw new WikiGraphArchiveOwnershipError(
+      `Library archive target must be a UUID archive URI: ${target.uri}`
+    );
+  }
+  await resolveWikiGraphLibrary(parsed);
+  const archiveFile = await 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 realpath(path);
+  } catch {
+    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) {
+  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;
+      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 stat2(path);
+    return `${value.dev}:${value.ino}`;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/conversions.ts
 var WikiGraphConversionManager = class {
   #runtime;
@@ -1280,6 +1445,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."
@@ -1298,7 +1466,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") {
@@ -1306,7 +1484,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) {
@@ -1331,16 +1511,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 }
     };
   }
 };
@@ -1353,11 +1546,67 @@ async function prepareDigestDirectory(path, required) {
   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 = createHash("sha256");
+  try {
+    for await (const chunk of 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: basename3(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
 import {
@@ -1529,489 +1778,130 @@ import {
   isArchiveSearchIndexCurrent,
   listChapters
 } from "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)
-    }
-  };
-}
-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":
-      return {
-        cacheableInputTokenPerWord: 45,
-        inputTokenPerWord: 55,
-        maxSecondsPerCall: 25,
-        minSecondsPerCall: 10,
-        outputTokenPerWord: 4,
-        secondsPerWord: 0.01,
-        wordsPerCall: 110
-      };
-  }
-}
-
-// 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),
+async function inspectWikiGraphArchive(document, options) {
+  const [allChapters, indexCacheCurrent, summaryWords, ...coverage] = await Promise.all([
+    listChapters(document),
     isArchiveSearchIndexCurrent(document),
-    loadWikiGraphRuntimeConfig(),
-    readIndexArtifactCoverage(document, "fts", options.chapterId),
-    readIndexArtifactCoverage(document, "embedding-source", options.chapterId),
-    readIndexArtifactCoverage(document, "embedding-summary", options.chapterId)
+    readSummaryWords(document),
+    document.indexArtifacts.listCoverage("fts"),
+    document.indexArtifacts.listCoverage("embedding-source"),
+    document.indexArtifacts.listCoverage("embedding-summary")
   ]);
-  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 chapters = selectChapters(allChapters, options.chapterId);
+  const coverageByKind = {
+    fts: byChapterId(coverage[0]),
+    sourceEmbedding: byChapterId(coverage[1]),
+    summaryEmbedding: byChapterId(coverage[2])
   };
-  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 inspections = await Promise.all(
+    chapters.map(async (chapter) => {
+      const serial = await document.serials.getById(chapter.chapterId);
+      return {
+        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
+      };
+    })
   );
-  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."
-  };
-}
-function createInspectChapterReference(archiveUri, chapter) {
-  return {
-    chapterId: chapter.chapterId,
-    locatedUri: formatInspectLocatedChapterUri(archiveUri, chapter),
-    title: chapter.title,
-    uri: chapter.uri
+    uri: selected === void 0 || options.chapterId === void 0 ? options.archiveUri : formatLocatedChapterUri(options.archiveUri, selected.chapter)
   };
 }
-function formatInspectLocatedChapterUri(archiveUri, chapter) {
-  return `${archiveUri.replace(/\/+$/u, "")}/${chapter.uri.replace(/^wikg:\/\//u, "")}`;
-}
-async function readInspectChapters(document, chapterId) {
-  const chapters = chapterId === void 0 ? await listChapters(document) : (await 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"
-      };
-    })
-  );
-}
-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
-  );
-}
-async function readIndexArtifactCoverage(document, kind, chapterId) {
-  const coverage = await document.indexArtifacts.listCoverage(kind);
-  return chapterId === void 0 ? coverage : coverage.filter((item) => item.serialId === chapterId);
+  return selected;
 }
-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 byChapterId(coverage) {
+  return new Map(coverage.map((item) => [item.serialId, item]));
 }
-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
+import {
+  WikiGraphArchiveFile,
+  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 }
+  });
+  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 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
@@ -2031,13 +1921,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 = join3(
-        dirname2(path),
-        `.${basename2(path)}.${randomUUID2()}.tmp.wikg`
+      const outputPath = join4(
+        dirname3(path),
+        `.${basename4(path)}.${randomUUID2()}.tmp.wikg`
       );
       try {
         if (options.importPath === void 0) {
@@ -2062,15 +1952,15 @@ var WikiGraphArchiveManager = class {
             throw error;
           }
         }
-        return { locatedUri: formatLocatedWikiGraphUri(path), path };
+        return { locatedUri: formatLocatedWikiGraphUri2(path), path };
       } finally {
         await rm3(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);
@@ -2093,14 +1983,17 @@ var WikiGraphArchiveHandle = class {
     return this.#location.locatedUri;
   }
   get objectUri() {
-    return parseLocatedWikiGraphUri(this.#location.locatedUri).objectUri ?? "wikg://";
+    return parseLocatedWikiGraphUri2(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 }
       }),
@@ -2401,7 +2294,7 @@ var WikiGraphArchiveHandle = class {
         objectUri,
         async (wikimediaOptions) => await this.#readDocument(
           async (document) => await readArchivePage(document, objectUri, {
-            ...withoutOperation(options),
+            ...options,
             ...wikimediaOptions
           }),
           options
@@ -2547,7 +2440,7 @@ var WikiGraphArchiveHandle = class {
   }
   async #readDocument(operation, options = {}) {
     return await this.#runtime.run(
-      async () => await new WikiGraphArchiveFile(this.#location.archiveFile).readDocument(
+      async () => await new WikiGraphArchiveFile2(this.#location.archiveFile).readDocument(
         operation
       ),
       options.signal
@@ -2555,17 +2448,13 @@ var WikiGraphArchiveHandle = class {
   }
   async #writeDocument(operation, options = {}) {
     return await this.#runtime.run(async () => {
-      const result = await new 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) {
@@ -2585,52 +2474,7 @@ var WikiGraphArchiveHandle = class {
     }
     return queryable;
   }
-  async #refreshLibraryIndex(onError) {
-    if (this.#location.libraryDirtyTarget === void 0) return;
-    if (this.#location.libraryArchiveTarget !== void 0) {
-      await finalizeWikiGraphLibraryArchiveWrite({
-        target: this.#location.libraryArchiveTarget
-      });
-    }
-    try {
-      const state = await readWikiGraphLibraryIndexState(
-        this.#location.libraryDirtyTarget
-      );
-      if (state.status !== "missing") {
-        await rebuildWikiGraphLibraryIndex(this.#location.libraryDirtyTarget);
-      }
-    } catch (error) {
-      onError?.(error);
-    }
-  }
 };
-async function resolveWikiGraphArchiveLocation(uriOrPath) {
-  if (!uriOrPath.startsWith("wikg://")) {
-    return createPathLocation(resolveWikiGraphRuntimePath(uriOrPath));
-  }
-  const parsed = parseLocatedWikiGraphUri(uriOrPath);
-  const portableArchiveLocator = parsed.archivePath ?? uriOrPath;
-  const archiveLocator = portableArchiveLocator.startsWith("wikg://lib/") ? portableArchiveLocator : resolveWikiGraphRuntimePath(portableArchiveLocator);
-  const libraryArchiveTarget = archiveLocator.startsWith("wikg://lib/") ? parseWikiGraphLibraryUri(archiveLocator) : void 0;
-  const archiveFile = libraryArchiveTarget?.kind === "archive" ? await 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: formatLocatedWikiGraphUri(archivePath, parsed.objectUri)
-  };
-}
 async function ensureArchiveSearchIndex(document, options = {}) {
   const scope = options.chapters === void 0 ? {} : { chapters: options.chapters };
   if (await isArchiveSearchIndexCurrent2(document, scope)) return;
@@ -2669,18 +2513,9 @@ 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: formatLocatedWikiGraphUri(path)
-  };
-}
 async function createEmptyArchiveFile(path) {
   const directoryPath = await mkdtemp(
-    join3(tmpdir(), "wikigraph-archive-write-")
+    join4(tmpdir(), "wikigraph-archive-write-")
   );
   try {
     const directory = new NodeDirectory(directoryPath);
@@ -2702,7 +2537,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -2808,7 +2643,7 @@ export {
   WikiGraphArchiveExistsError,
   WikiGraphArchiveHandle,
   WikiGraphArchiveManager,
-  createWikiGraphArchiveInspectReport,
-  resolveWikiGraphArchiveLocation
+  WikiGraphArchiveOwnershipError,
+  inspectWikiGraphArchive
 };
 //# sourceMappingURL=archives.js.map