wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/index.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 = {
@@ -1382,6 +1380,203 @@ 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;
+}
+function archiveTargetFromLogicalLocator(locator, objectUri) {
+  if (locator.startsWith("wikg://lib/")) {
+    return { kind: "library", uri: withObjectUri(locator, objectUri) };
+  }
+  return {
+    kind: "standalone",
+    path: locator,
+    ...objectUri === void 0 ? {} : { objectUri }
+  };
+}
+async function resolveWikiGraphArchiveTarget(file) {
+  const path = getNodeResourcePath(file);
+  const candidate = await canonicalPath(path);
+  const candidateIdentity = await readFileIdentity(path);
+  const matches = await findMatchingMembers(
+    await listWikiGraphLibraries(),
+    candidate,
+    candidateIdentity
+  );
+  if (matches.length > 0) {
+    const match = requireUnambiguousManagedMatch(path, matches);
+    return { kind: "library", uri: match.archive.uri };
+  }
+  return { kind: "standalone", path: getNodeResourcePath(file) };
+}
+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
+  };
+}
+function withObjectUri(archiveLocator, objectUri) {
+  if (objectUri === void 0) return archiveLocator;
+  const path = objectUri.replace(/^wikg:\/\//u, "");
+  return `${archiveLocator.replace(/\/$/u, "")}/${path}`;
+}
+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;
@@ -1396,6 +1591,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."
@@ -1414,7 +1612,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") {
@@ -1422,7 +1630,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) {
@@ -1447,16 +1657,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 }
     };
   }
 };
@@ -1469,11 +1692,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 {
@@ -1670,499 +1949,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
+async function inspectWikiGraphArchive(document, options) {
+  const [allChapters, indexCacheCurrent, summaryWords, ...coverage] = await Promise.all([
+    listChapters(document),
+    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])
+  };
+  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 callBatches = Math.ceil(calls / effectiveConcurrency);
-  const wordSeconds = words * profile.secondsPerWord;
+  const selected = inspections[0];
   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)
-    }
+    archiveUri: options.archiveUri,
+    chapters: inspections,
+    localIndexCache: { current: indexCacheCurrent },
+    scope: options.chapterId === void 0 ? { type: "archive" } : { chapterId: options.chapterId, type: "chapter" },
+    uri: selected === void 0 || options.chapterId === void 0 ? options.archiveUri : formatLocatedChapterUri(options.archiveUri, selected.chapter)
   };
 }
-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
-    });
+function selectChapters(chapters, chapterId) {
+  if (chapterId === void 0) return chapters;
+  const selected = chapters.filter(
+    (chapter) => chapter.chapterId === chapterId
+  );
+  if (selected.length === 0) {
+    throw new Error(`Chapter ${chapterId} does not exist.`);
   }
-  return hints;
+  return selected;
 }
-function formatGenerationPlanningModel(llm) {
-  if (llm?.model === void 0) {
-    return "not configured";
-  }
-  return llm.provider === void 0 ? llm.model : `${llm.provider}/${llm.model}`;
+function byChapterId(coverage) {
+  return new Map(coverage.map((item) => [item.serialId, item]));
 }
-function formatGenerationPlanningDuration(seconds) {
-  if (seconds < 60) {
-    return `${seconds}s`;
-  }
-  const minutes = Math.round(seconds / 60);
-  if (minutes < 60) {
-    return `${minutes}m`;
-  }
-  return `${Math.round(minutes / 60)}h`;
+function inspectArtifact(kind, coverage) {
+  return {
+    current: coverage?.current === true,
+    exists: coverage?.sourceRevision !== void 0,
+    kind,
+    ...coverage?.sourceRevision === void 0 ? {} : { sourceRevision: coverage.sourceRevision }
+  };
 }
-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
-      };
+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 new Map(rows.map((row) => [row.chapterId, row.words]));
+}
+function formatLocatedChapterUri(archiveUri, chapter) {
+  return `${archiveUri.replace(/\/+$/u, "")}/${chapter.uri.replace(/^wikg:\/\//u, "")}`;
+}
+
+// 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();
   }
-}
-
-// 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),
-    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
-    )
-  });
-  return {
-    archiveUri,
-    uri: scopeUri,
-    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
-  };
-}
-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(
-    (chapter) => chapter.chapterId === chapterId
-  );
-  if (chapterId !== void 0 && chapters.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);
-}
-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);
-  return {
-    coveredChapters: covered.length,
-    coveredWords,
-    percent: formatPercent(coveredWords, totalWords),
-    totalChapters: total.length,
-    totalWords
-  };
-}
-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
-    )
-  );
-  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;
-}
-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 formatPercent(numerator, denominator) {
-  if (denominator === 0) {
-    return "n/a";
-  }
-  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
@@ -2182,13 +2092,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) {
@@ -2213,15 +2123,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);
@@ -2244,14 +2154,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 }
       }),
@@ -2552,7 +2465,7 @@ var WikiGraphArchiveHandle = class {
         objectUri,
         async (wikimediaOptions) => await this.#readDocument(
           async (document) => await readArchivePage(document, objectUri, {
-            ...withoutOperation(options),
+            ...options,
             ...wikimediaOptions
           }),
           options
@@ -2698,7 +2611,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
@@ -2706,17 +2619,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) {
@@ -2736,52 +2645,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;
@@ -2820,18 +2684,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);
@@ -2853,7 +2708,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -2959,12 +2814,13 @@ async function assertChapterResetAllowed(archive, chapterId, stage) {
 // src/wikispine.ts
 import { spawn } from "child_process";
 var nodeWikispineCommandRunner = {
-  run: async ({ args, command, input, onStdout, signal }) => await new Promise((resolve3, reject) => {
+  run: async ({ args, command, input, onStdout, signal }) => await new Promise((resolve4, reject) => {
     signal?.throwIfAborted();
     const child = spawn(command, [...args], {
       stdio: ["pipe", "pipe", "pipe"]
     });
     const stderr = [];
+    let stdoutQueue = Promise.resolve();
     let settled = false;
     const settle = (operation) => {
       if (settled) return;
@@ -2980,14 +2836,15 @@ var nodeWikispineCommandRunner = {
     child.stdout.setEncoding("utf8");
     child.stdout.on("data", (chunk) => {
       if (settled) return;
-      try {
-        onStdout(chunk);
-      } catch (error) {
+      child.stdout.pause();
+      stdoutQueue = stdoutQueue.then(async () => await onStdout(chunk)).then(() => {
+        child.stdout.resume();
+      }).catch((error) => {
         child.kill();
         settle(
           () => reject(error instanceof Error ? error : new Error(String(error)))
         );
-      }
+      });
     });
     child.stderr.on("data", (chunk) => stderr.push(chunk));
     child.on("error", (error) => {
@@ -2998,12 +2855,14 @@ var nodeWikispineCommandRunner = {
       );
     });
     child.on("close", (exitCode) => {
-      settle(
-        () => resolve3({
-          exitCode,
-          stderr: Buffer.concat(stderr).toString("utf8")
-        })
-      );
+      void stdoutQueue.then(() => {
+        settle(
+          () => resolve4({
+            exitCode,
+            stderr: Buffer.concat(stderr).toString("utf8")
+          })
+        );
+      });
     });
     child.stdin.end(input);
   })
@@ -3135,7 +2994,7 @@ import {
   listWikiGraphLibraryObjects,
   readContinuationCursor,
   resolveWikiGraphLibraryQueryTargetById,
-  WikiGraphArchiveFile as WikiGraphArchiveFile2
+  WikiGraphArchiveFile as WikiGraphArchiveFile3
 } from "wiki-graph-core";
 var WikiGraphContinuationManager = class {
   #runtime;
@@ -3182,9 +3041,9 @@ var WikiGraphContinuationManager = class {
 };
 async function continueArchiveCursor(cursor, limit) {
   const location = await resolveWikiGraphArchiveLocation(
-    getCursorArchivePath(cursor)
+    archiveTargetFromLogicalLocator(getCursorArchivePath(cursor))
   );
-  return await new WikiGraphArchiveFile2(location.archiveFile).readDocument(
+  return await new WikiGraphArchiveFile3(location.archiveFile).readDocument(
     async (document) => {
       switch (cursor.kind) {
         case "source-locators":
@@ -3439,14 +3298,14 @@ import {
   getChapterDetails,
   openWikimediaResolver as openWikimediaResolver2,
   recordBuildJobInputRevision,
-  WikiGraphArchiveFile as WikiGraphArchiveFile3,
+  WikiGraphArchiveFile as WikiGraphArchiveFile5,
   WikiGraphScope,
   withLoggingContext
 } from "wiki-graph-core";
 import {
-  applyChapterJobArtifactFile as applyChapterJobArtifactFile2,
+  applyChapterJobArtifactFile as applyChapterJobArtifactFile3,
   createLocalChapterJobFileExecutor as createLocalChapterJobFileExecutor2,
-  writeChapterJobInputFile as writeChapterJobInputFile2
+  writeChapterJobInputFile as writeChapterJobInputFile3
 } from "wiki-graph-core/worker";
 
 // src/stage.ts
@@ -3484,14 +3343,145 @@ async function loadRequiredStageConfig(options) {
   return config;
 }
 
+// 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 formatGenerationPlanningDuration(seconds) {
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  return `${Math.round(minutes / 60)}h`;
+}
+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/worker.ts
 import {
-  runBuildJobWorker as runCoreBuildJobWorker
+  applyChapterJobArtifactFile,
+  runBuildJobWorker as runCoreBuildJobWorker,
+  writeChapterJobInputFile
 } from "wiki-graph-core/worker";
 import {
-  applyChapterJobArtifactFile,
+  resolveChapterPathReadonly as resolveChapterPathReadonly2,
+  WikiGraphArchiveFile as WikiGraphArchiveFile4
+} from "wiki-graph-core";
+import {
+  applyChapterJobArtifactFile as applyChapterJobArtifactFile2,
   createLocalChapterJobFileExecutor,
-  writeChapterJobInputFile
+  writeChapterJobInputFile as writeChapterJobInputFile2
 } from "wiki-graph-core/worker";
 async function runBuildJobWorker(options) {
   installNodeWikiGraphPlatform();
@@ -3531,7 +3521,7 @@ async function executeBuildJob(job, reporter, context) {
       let stage = await readChapterStage(job);
       if (stage === "sourced") {
         await executeStep(job, "reading-graph", execution, reporter, context, {
-          ...execution.extractionPrompt === void 0 ? {} : { extractionPrompt: execution.extractionPrompt }
+          ...execution.extractionPrompt === void 0 ? {} : { prompt: execution.extractionPrompt }
         });
         stage = await readChapterStage(job);
       }
@@ -3564,8 +3554,8 @@ async function executeBuildJob(job, reporter, context) {
       }
     }
     await executeStep(job, job.target, execution, reporter, context, {
-      ...job.target === "reading-graph" ? { extractionPrompt: execution.extractionPrompt } : {},
-      ...job.target === "knowledge-graph" ? { policyPrompt: execution.knowledgeGraphPrompt } : {}
+      ...job.target === "reading-graph" ? { prompt: execution.extractionPrompt } : {},
+      ...job.target === "knowledge-graph" ? { prompt: execution.knowledgeGraphPrompt } : {}
     });
   } finally {
     await execution.close();
@@ -3580,10 +3570,10 @@ async function executeStep(job, kind, execution, reporter, context, inputOptions
   const stepWorkspace = await resetStepWorkspace(job.workspace, kind);
   const inputFile = await stepWorkspace.createFile("input.jsonl");
   const outputWorkspace = await stepWorkspace.createDirectory("output");
-  const revision = await new WikiGraphArchiveFile3(job.archive).readDocument(
+  const revision = await new WikiGraphArchiveFile5(job.archive).readDocument(
     async (document) => {
       await getChapterDetails(document, job.chapterId);
-      return await writeChapterJobInputFile2(
+      return await writeChapterJobInputFile3(
         document,
         job.chapterId,
         kind,
@@ -3622,16 +3612,23 @@ async function executeStep(job, kind, execution, reporter, context, inputOptions
     total: 1,
     unit: "item"
   });
-  await new WikiGraphArchiveFile3(job.archive).write(async (document) => {
-    assertJobStillRunning(await getBuildJob(job.jobId));
-    await applyChapterJobArtifactFile2(
-      document,
-      job.chapterId,
-      kind,
-      revision,
-      result.artifactFile
-    );
-  });
+  const target = await resolveWikiGraphArchiveTarget(job.archive);
+  const resolvedLocation = await resolveWikiGraphArchiveLocation(target);
+  const location = target.kind === "standalone" ? { ...resolvedLocation, archiveFile: job.archive } : resolvedLocation;
+  await writeWikiGraphArchiveLocation(
+    location,
+    async (document) => {
+      assertJobStillRunning(await getBuildJob(job.jobId));
+      await applyChapterJobArtifactFile3(
+        document,
+        job.chapterId,
+        kind,
+        revision,
+        result.artifactFile
+      );
+    },
+    { invalidateContinuationCursors: true }
+  );
   await reporter.updatePhase({
     done: 1,
     phase: "committing",
@@ -3670,6 +3667,10 @@ async function openJobExecutor(job, config, signal, reporter) {
       llmRequest: requireValue(
         request,
         "Local Wikimedia resolution requires an LLM."
+      ),
+      llmModelId: requireValue(
+        stageConfig?.llm?.model,
+        "Local Wikimedia resolution requires an LLM model."
       )
     } : {
       endpoint: config.wikimedia.endpoint,
@@ -3707,12 +3708,12 @@ async function resetStepWorkspace(workspace, kind) {
   return await workspace.createDirectory(name);
 }
 async function readChapterStage(job) {
-  return await new WikiGraphArchiveFile3(job.archive).readDocument(
+  return await new WikiGraphArchiveFile5(job.archive).readDocument(
     async (document) => (await getChapterDetails(document, job.chapterId)).stage
   );
 }
 async function assertCurrentFtsArtifact(job) {
-  await new WikiGraphArchiveFile3(job.archive).readDocument(async (document) => {
+  await new WikiGraphArchiveFile5(job.archive).readDocument(async (document) => {
     const revision = await document.serials.getRevision(job.chapterId);
     const artifact = await document.indexArtifacts.get(job.chapterId, "fts");
     if (artifact?.sourceRevision !== revision) {
@@ -3816,7 +3817,7 @@ import {
   boostBuildJob,
   cancelBuildJob,
   cleanBuildJobs,
-  formatLocatedChapterUri,
+  formatLocatedChapterUri as formatLocatedChapterUri2,
   getBuildJob as getBuildJob2,
   listBuildJobs,
   listChapters as listChapters3,
@@ -3825,8 +3826,9 @@ import {
   resolveBuildJobId,
   resumeBuildJob,
   updateBuildJobTarget,
-  resolveChapterPathReadonly as resolveChapterPathReadonly2,
-  WikiGraphArchiveFile as WikiGraphArchiveFile4
+  withArchiveBuildJobCreationLock,
+  resolveChapterPathReadonly as resolveChapterPathReadonly3,
+  WikiGraphArchiveFile as WikiGraphArchiveFile6
 } from "wiki-graph-core";
 var TERMINAL_STATES = /* @__PURE__ */ new Set(["canceled", "failed", "succeeded"]);
 var TERMINAL_EVENT_GRACE_READS = 3;
@@ -3871,20 +3873,24 @@ var WikiGraphJobManager = class {
     this.#backend = backend;
   }
   async create(options) {
-    const job = await this.#runtime.run(
-      async () => await this.#backend.add({
-        ...options,
-        archive: typeof options.archive === "string" ? new NodeFile(resolveWikiGraphRuntimePath(options.archive)) : options.archive
-      })
-    );
-    return this.#createHandle(job);
+    const resolved = await this.#runtime.run(async () => {
+      const location = await resolveWikiGraphArchiveLocation(options.archive);
+      return {
+        job: await this.#backend.add({
+          ...options,
+          archive: location.archiveFile
+        }),
+        target: location.target
+      };
+    });
+    return await this.#createHandle(resolved.job, resolved.target);
   }
   async clean() {
     return await this.#runtime.run(async () => await cleanBuildJobs());
   }
   async get(jobId) {
-    return this.#createHandle(
-      await this.#runtime.run(async () => await this.#backend.get(jobId))
+    return await this.#runtime.run(
+      async () => await this.#createHandle(await this.#backend.get(jobId))
     );
   }
   async resolveId(reference) {
@@ -3893,23 +3899,25 @@ var WikiGraphJobManager = class {
     );
   }
   async list(options = {}) {
-    const jobs = await this.#runtime.run(async () => {
+    return await this.#runtime.run(async () => {
       const normalized = {
         ...options.activeOnly === void 0 ? {} : { activeOnly: options.activeOnly },
         ...options.all === void 0 ? {} : { all: options.all },
         ...options.archive === void 0 ? {} : {
-          archive: typeof options.archive === "string" ? new NodeFile(resolveWikiGraphRuntimePath(options.archive)) : options.archive
+          archive: (await resolveWikiGraphArchiveLocation(options.archive)).archiveFile
         }
       };
-      return await this.#backend.list(normalized);
+      const jobs = await this.#backend.list(normalized);
+      return await Promise.all(
+        jobs.map(async (job) => await this.#createHandle(job))
+      );
     });
-    return jobs.map((job) => this.#createHandle(job));
   }
   async resolveChapters(jobs) {
     return await this.#runtime.run(async () => {
       const jobsByArchive = /* @__PURE__ */ new Map();
       for (const job of jobs) {
-        const archivePath = getBuildJobArchivePath(job);
+        const archivePath = getJobArchiveLocator(job);
         const grouped = jobsByArchive.get(archivePath) ?? [];
         grouped.push(job);
         jobsByArchive.set(archivePath, grouped);
@@ -3917,8 +3925,11 @@ var WikiGraphJobManager = class {
       const entries = (await Promise.all(
         [...jobsByArchive].map(async ([archivePath, archiveJobs]) => {
           try {
-            const chapters = await new WikiGraphArchiveFile4(
-              new NodeFile(archivePath)
+            const location = await resolveWikiGraphArchiveLocation(
+              archiveJobs[0].archive
+            );
+            const chapters = await new WikiGraphArchiveFile6(
+              location.archiveFile
             ).readDocument(async (document) => await listChapters3(document));
             const chaptersById = new Map(
               chapters.map((chapter) => [chapter.chapterId, chapter])
@@ -3929,7 +3940,7 @@ var WikiGraphJobManager = class {
                 [
                   job.jobId,
                   {
-                    locatedUri: formatLocatedChapterUri(
+                    locatedUri: formatLocatedChapterUri2(
                       archivePath,
                       chapter.path
                     ),
@@ -3953,62 +3964,78 @@ var WikiGraphJobManager = class {
   async enqueue(options) {
     return await this.#runtime.run(async () => {
       const location = await resolveWikiGraphArchiveLocation(options.archive);
-      const target = options.target ?? "reading-summary";
-      await validateQueueTargetConfig(target, options.llmJSON);
-      const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
-      const candidates = await new WikiGraphArchiveFile4(
-        location.archiveFile
-      ).readDocument(async (document) => {
-        const chapters = await listChapters3(document);
-        const selected = await selectQueueChapters(document, chapters, options);
-        const checked = await Promise.all(
-          selected.map(async (chapter) => ({
-            chapter,
-            reason: await readQueueReadinessReason(document, chapter, target)
-          }))
-        );
-        return checked;
-      });
-      const created = [];
-      const skipped = [];
-      for (const candidate of candidates) {
-        if (candidate.reason !== void 0) {
-          if (selectedExplicitly && candidates.length === 1) {
-            throw new Error(
-              formatQueueReadinessError(
-                candidate.chapter,
-                target,
-                candidate.reason
-              )
+      return await withArchiveBuildJobCreationLock(
+        location.archiveFile,
+        async () => {
+          const target = options.target ?? "reading-summary";
+          await validateQueueTargetConfig(target, options.llmJSON);
+          const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
+          const candidates = await new WikiGraphArchiveFile6(
+            location.archiveFile
+          ).readDocument(async (document) => {
+            const chapters = await listChapters3(document);
+            const selected = await selectQueueChapters(
+              document,
+              chapters,
+              options
             );
-          }
-          skipped.push({
-            chapter: candidate.chapter,
-            reason: candidate.reason
-          });
-          continue;
-        }
-        try {
-          created.push({
-            chapter: candidate.chapter,
-            job: await this.create({
-              archive: location.archiveFile,
-              boost: options.boost ?? false,
-              chapterId: candidate.chapter.chapterId,
-              ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON },
-              ...options.prompt === void 0 ? {} : { prompt: options.prompt },
-              target
-            })
-          });
-        } catch (error) {
-          if (selectedExplicitly && candidates.length === 1) throw error;
-          skipped.push({
-            chapter: candidate.chapter,
-            reason: error instanceof Error ? error.message : String(error)
+            const checked = await Promise.all(
+              selected.map(async (chapter) => ({
+                chapter,
+                reason: await readQueueReadinessReason(
+                  document,
+                  chapter,
+                  target
+                )
+              }))
+            );
+            return checked;
           });
+          const created = [];
+          const skipped = [];
+          for (const candidate of candidates) {
+            if (candidate.reason !== void 0) {
+              if (selectedExplicitly && candidates.length === 1) {
+                throw new Error(
+                  formatQueueReadinessError(
+                    candidate.chapter,
+                    target,
+                    candidate.reason
+                  )
+                );
+              }
+              skipped.push({
+                chapter: candidate.chapter,
+                reason: candidate.reason
+              });
+              continue;
+            }
+            try {
+              created.push({
+                chapter: candidate.chapter,
+                job: await this.#createHandle(
+                  await this.#backend.add({
+                    archive: location.archiveFile,
+                    boost: options.boost ?? false,
+                    chapterId: candidate.chapter.chapterId,
+                    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON },
+                    ...options.prompt === void 0 ? {} : { prompt: options.prompt },
+                    target
+                  }),
+                  location.target
+                )
+              });
+            } catch (error) {
+              if (selectedExplicitly && candidates.length === 1) throw error;
+              skipped.push({
+                chapter: candidate.chapter,
+                reason: error instanceof Error ? error.message : String(error)
+              });
+            }
+          }
+          return { created, skipped };
         }
-      }
-      return { created, skipped };
+      );
     });
   }
   async planEnqueue(options) {
@@ -4017,7 +4044,7 @@ var WikiGraphJobManager = class {
       const target = options.target ?? "reading-summary";
       await validateQueueTargetConfig(target, options.llmJSON);
       const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
-      const candidates = await new WikiGraphArchiveFile4(
+      const candidates = await new WikiGraphArchiveFile6(
         location.archiveFile
       ).readDocument(async (document) => {
         const chapters = await listChapters3(document);
@@ -4054,34 +4081,39 @@ var WikiGraphJobManager = class {
     this.#subscriptions.add(controller);
     return () => this.#subscriptions.delete(controller);
   }
-  #createHandle(snapshot) {
-    return new WikiGraphJob(this, this.#runtime, this.#backend, snapshot);
+  async #createHandle(snapshot, target) {
+    const legacy = snapshot;
+    const resolvedTarget = target ?? (snapshot.archive === void 0 ? archiveTargetFromLogicalLocator(legacy.archivePath ?? "unknown.wikg") : await resolveWikiGraphArchiveTarget(snapshot.archive));
+    return new WikiGraphJob(
+      this,
+      this.#runtime,
+      this.#backend,
+      snapshot,
+      cloneWikiGraphArchiveTarget(resolvedTarget)
+    );
   }
 };
-function getBuildJobArchivePath(job) {
-  const record = job;
-  if (record.archive !== void 0) {
-    return getNodeResourcePath(record.archive);
-  }
-  if (typeof record.archivePath === "string") return record.archivePath;
-  throw new TypeError("Build job is missing archive");
+function getJobArchiveLocator(job) {
+  return job.archive.kind === "library" ? job.archive.uri : job.archive.path;
 }
 var WikiGraphJob = class {
   #manager;
   #runtime;
   #backend;
+  #archiveTarget;
   #snapshot;
-  constructor(manager, runtime, backend, snapshot) {
+  constructor(manager, runtime, backend, snapshot, archiveTarget) {
     this.#manager = manager;
     this.#runtime = runtime;
     this.#backend = backend;
     this.#snapshot = snapshot;
+    this.#archiveTarget = archiveTarget;
   }
   get id() {
     return this.#snapshot.jobId;
   }
   get snapshot() {
-    return this.#snapshot;
+    return toPublicJobSnapshot(this.#snapshot, this.#archiveTarget);
   }
   async status() {
     return await this.#update(async () => await this.#backend.get(this.id));
@@ -4108,7 +4140,8 @@ var WikiGraphJob = class {
     let cursor = 0;
     let job = this.#snapshot;
     if (options.from === "now") {
-      job = await this.status();
+      await this.status();
+      job = this.#snapshot;
       const chunk = await this.#readEventChunkSafely(job, cursor);
       const events = chunk.events;
       cursor = chunk.cursor;
@@ -4128,7 +4161,8 @@ var WikiGraphJob = class {
         yield event;
       }
       if (sawTerminalEvent) return;
-      job = await this.status();
+      await this.status();
+      job = this.#snapshot;
       if (isTerminalState(job.state)) {
         terminalReadsWithoutEvent += 1;
         if (terminalReadsWithoutEvent >= TERMINAL_EVENT_GRACE_READS) return;
@@ -4165,7 +4199,7 @@ var WikiGraphJob = class {
   }
   async #update(operation) {
     this.#snapshot = await this.#runtime.run(operation);
-    return this.#snapshot;
+    return this.snapshot;
   }
   async #readEventChunk(job, cursor) {
     return await this.#runtime.run(async () => {
@@ -4184,6 +4218,54 @@ var WikiGraphJob = class {
     }
   }
 };
+function toPublicJobSnapshot(job, archive) {
+  const legacy = job;
+  return {
+    archive: cloneWikiGraphArchiveTarget(archive),
+    archiveKey: archive.kind === "library" ? archive.uri : job.archiveKey,
+    ...getJobResourcePath(job.cache, legacy.cachePath) === void 0 ? {} : { cachePath: getJobResourcePath(job.cache, legacy.cachePath) },
+    chapterId: job.chapterId,
+    createdAt: job.createdAt,
+    ...job.currentStep === void 0 ? {} : { currentStep: job.currentStep },
+    ...job.errorJSON === void 0 ? {} : { errorJSON: job.errorJSON },
+    ...getJobResourcePath(job.events, legacy.eventsPath) === void 0 ? {} : { eventsPath: getJobResourcePath(job.events, legacy.eventsPath) },
+    ...job.finishedAt === void 0 ? {} : { finishedAt: job.finishedAt },
+    jobId: job.jobId,
+    ...job.inputRevision === void 0 ? {} : { inputRevision: job.inputRevision },
+    ...getJobResourcePath(job.log, legacy.logPath) === void 0 ? {} : { logPath: getJobResourcePath(job.log, legacy.logPath) },
+    ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON },
+    ...job.ownerId === void 0 ? {} : { ownerId: job.ownerId },
+    ...job.prompt === void 0 ? {} : { prompt: job.prompt },
+    queueRank: job.queueRank,
+    ...job.readingSummaryStartedAt === void 0 ? {} : { readingSummaryStartedAt: job.readingSummaryStartedAt },
+    state: job.state,
+    target: job.target,
+    updatedAt: job.updatedAt,
+    ...getJobResourcePath(job.workspace, legacy.workspacePath) === void 0 ? {} : {
+      workspacePath: getJobResourcePath(
+        job.workspace,
+        legacy.workspacePath
+      )
+    }
+  };
+}
+function cloneWikiGraphArchiveTarget(target) {
+  return target.kind === "library" ? Object.freeze({ kind: "library", uri: target.uri }) : Object.freeze({
+    kind: "standalone",
+    path: target.path,
+    ...target.objectUri === void 0 ? {} : { objectUri: target.objectUri }
+  });
+}
+function getJobResourcePath(resource, legacy) {
+  if (resource === void 0) return legacy;
+  try {
+    return getNodeResourcePath(resource);
+  } catch {
+    const identity = resource.identity;
+    if (typeof identity === "string") return identity;
+    throw new TypeError("Expected a Node File or Directory resource");
+  }
+}
 async function selectQueueChapters(document, chapters, options) {
   const ids = options.chapterIds ?? (options.chapterId === void 0 ? void 0 : [options.chapterId]);
   if (ids !== void 0) {
@@ -4194,7 +4276,7 @@ async function selectQueueChapters(document, chapters, options) {
   if (options.chapterPath === void 0) {
     return options.depth === void 0 ? chapters : chapters.filter((chapter) => chapter.depth <= options.depth);
   }
-  const rootId = await resolveChapterPathReadonly2(
+  const rootId = await resolveChapterPathReadonly3(
     document,
     options.chapterPath
   );
@@ -4259,14 +4341,14 @@ function formatQueueReadinessError(chapter, target, reason) {
 }
 async function wait(milliseconds, signal) {
   if (signal?.aborted === true) return;
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     let settled = false;
     const complete = () => {
       if (settled) return;
       settled = true;
       clearTimeout(timeout);
       signal?.removeEventListener("abort", complete);
-      resolve3();
+      resolve4();
     };
     const timeout = setTimeout(complete, milliseconds);
     signal?.addEventListener("abort", complete, { once: true });
@@ -4297,12 +4379,12 @@ import {
   deleteWikiGraphLibraryMetadataKey,
   findWikiGraphLibraryObjects as findWikiGraphLibraryObjects2,
   findWikiGraphLibraryArchiveMembers as findWikiGraphLibraryArchiveMembers2,
-  formatWikiGraphLibraryUri,
+  formatWikiGraphLibraryUri as formatWikiGraphLibraryUri2,
   getWikiGraphLibraryArchive,
   getWikiGraphLibraryMetadata,
   listRelatedWikiGraphLibraryObjects as listRelatedWikiGraphLibraryObjects2,
-  listWikiGraphLibraries,
-  listWikiGraphLibraryArchives,
+  listWikiGraphLibraries as listWikiGraphLibraries2,
+  listWikiGraphLibraryArchives as listWikiGraphLibraryArchives2,
   listWikiGraphLibraryArchiveMembers as listWikiGraphLibraryArchiveMembers2,
   listWikiGraphLibraryEvidence as listWikiGraphLibraryEvidence2,
   listWikiGraphLibraryObjects as listWikiGraphLibraryObjects2,
@@ -4310,14 +4392,15 @@ import {
   packWikiGraphLibraryContext,
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri2,
   putWikiGraphLibraryMetadata,
-  readWikiGraphLibraryIndexState as readWikiGraphLibraryIndexState2,
+  readWikiGraphLibraryIndexState,
   readWikiGraphLibraryPage,
-  rebuildWikiGraphLibraryIndex as rebuildWikiGraphLibraryIndex2,
+  rebuildWikiGraphLibraryIndex,
   rebindWikiGraphLibrary,
   removeWikiGraphLibrary,
   removeWikiGraphLibraryArchive,
+  replaceWikiGraphLibraryArchive,
   replaceWikiGraphLibraryMetadata,
-  resolveWikiGraphLibrary,
+  resolveWikiGraphLibrary as resolveWikiGraphLibrary2,
   scanWikiGraphLibrary
 } from "wiki-graph-core";
 import { mkdir as mkdir2 } from "fs/promises";
@@ -4334,22 +4417,24 @@ var WikiGraphLibraryManager = class {
     });
     return new WikiGraphLibrary(this.#runtime, record);
   }
-  async get(uri = formatWikiGraphLibraryUri()) {
+  async get(uri = formatWikiGraphLibraryUri2()) {
     const target = requireLibraryTarget(uri);
     const record = await this.#runtime.run(
-      async () => await resolveWikiGraphLibrary(target)
+      async () => await resolveWikiGraphLibrary2(target)
     );
     return new WikiGraphLibrary(this.#runtime, record);
   }
   async addArchive(options) {
-    return await this.#runtime.run(
-      async () => await addWikiGraphLibraryArchive({
-        inputFile: new NodeFile(
-          resolveWikiGraphRuntimePath(options.inputPath)
-        ),
-        target: requireLibraryTarget(options.target),
-        ...options.to === void 0 ? {} : { to: options.to }
-      })
+    return toArchiveSnapshot(
+      await this.#runtime.run(
+        async () => await addWikiGraphLibraryArchive({
+          inputFile: new NodeFile(
+            await assertStandaloneWikiGraphArchivePath(options.inputPath)
+          ),
+          target: requireLibraryTarget(options.target),
+          ...options.to === void 0 ? {} : { to: options.to }
+        })
+      )
     );
   }
   async assertCurrent(target) {
@@ -4358,51 +4443,78 @@ var WikiGraphLibraryManager = class {
     );
   }
   async rebind(target, folder) {
-    return await this.#runtime.run(
-      async () => await rebindWikiGraphLibrary({
-        folder: new NodeDirectory(resolveWikiGraphRuntimePath(folder)),
-        target: requireLibraryTarget(target)
-      })
+    return toScanSnapshot(
+      await this.#runtime.run(
+        async () => await rebindWikiGraphLibrary({
+          folder: new NodeDirectory(resolveWikiGraphRuntimePath(folder)),
+          target: requireLibraryTarget(target)
+        })
+      )
     );
   }
   async remove(target) {
-    return await this.#runtime.run(
-      async () => await removeWikiGraphLibrary(requireLibraryTarget(target))
+    return toLibrarySnapshot(
+      await this.#runtime.run(
+        async () => await removeWikiGraphLibrary(requireLibraryTarget(target))
+      )
     );
   }
   async scan(target) {
-    return await this.#runtime.run(
-      async () => await scanWikiGraphLibrary(requireLibraryTarget(target))
+    return toScanSnapshot(
+      await this.#runtime.run(
+        async () => await scanWikiGraphLibrary(requireLibraryTarget(target))
+      )
     );
   }
   async getArchive(target) {
-    return await this.#runtime.run(
-      async () => await getWikiGraphLibraryArchive(requireLibraryTarget(target))
+    return toArchiveSnapshot(
+      await this.#runtime.run(
+        async () => await getWikiGraphLibraryArchive(requireLibraryTarget(target))
+      )
     );
   }
   async moveArchive(options) {
-    return await this.#runtime.run(
-      async () => await moveWikiGraphLibraryArchive({
-        target: requireLibraryTarget(options.target),
-        to: options.to
-      })
+    return toArchiveSnapshot(
+      await this.#runtime.run(
+        async () => await moveWikiGraphLibraryArchive({
+          target: requireLibraryTarget(options.target),
+          to: options.to
+        })
+      )
     );
   }
   async removeArchive(target) {
-    return await this.#runtime.run(
-      async () => await removeWikiGraphLibraryArchive({
-        target: requireLibraryTarget(target)
+    return toArchiveSnapshot(
+      await this.#runtime.run(
+        async () => await removeWikiGraphLibraryArchive({
+          target: requireLibraryTarget(target)
+        })
+      )
+    );
+  }
+  async replaceArchive(options) {
+    return toArchiveSnapshot(
+      await this.#runtime.run(async () => {
+        const target = requireLibraryTarget(options.target);
+        const current = await getWikiGraphLibraryArchive(target);
+        return await replaceWikiGraphLibraryArchive({
+          additionalDerivedStateKeys: current.file === void 0 ? [] : [getNodeResourcePath(current.file)],
+          inputFile: new NodeFile(
+            await assertStandaloneWikiGraphArchivePath(options.inputPath)
+          ),
+          target
+        });
       })
     );
   }
   async indexState(target) {
     return await this.#runtime.run(
-      async () => await readWikiGraphLibraryIndexState2(requireLibraryTarget(target))
+      async () => await readWikiGraphLibraryIndexState(requireLibraryTarget(target))
     );
   }
   async rebuildIndex(target, onProgress) {
     return await this.#runtime.run(
-      async () => await rebuildWikiGraphLibraryIndex2(
+      async () => await rebuildWikiGraphLibraryIndex(
         requireLibraryTarget(target),
         onProgress
       )
@@ -4499,7 +4611,8 @@ var WikiGraphLibraryManager = class {
           objectUri,
           { ...options, ...wikimediaOptions }
         )
-      )
+      ),
+      options.signal
     );
   }
   async related(target, objectUri, options = {}) {
@@ -4531,7 +4644,7 @@ var WikiGraphLibraryManager = class {
   }
   async list() {
     const records = await this.#runtime.run(
-      async () => await listWikiGraphLibraries()
+      async () => await listWikiGraphLibraries2()
     );
     return records.map((record) => new WikiGraphLibrary(this.#runtime, record));
   }
@@ -4544,32 +4657,54 @@ var WikiGraphLibrary = class {
     this.#record = record;
   }
   get snapshot() {
-    return this.#record;
+    return toLibrarySnapshot(this.#record);
   }
   get uri() {
-    return formatWikiGraphLibraryUri(
+    return formatWikiGraphLibraryUri2(
       this.#record.isDefault ? void 0 : this.#record.publicId
     );
   }
   async archives() {
     const target = requireLibraryTarget(this.uri);
-    return await this.#runtime.run(
-      async () => await listWikiGraphLibraryArchives(target)
-    );
+    return (await this.#runtime.run(
+      async () => await listWikiGraphLibraryArchives2(target)
+    )).map(toArchiveSnapshot);
   }
   async scan() {
     const target = requireLibraryTarget(this.uri);
-    return await this.#runtime.run(
-      async () => await scanWikiGraphLibrary(target)
+    return toScanSnapshot(
+      await this.#runtime.run(async () => await scanWikiGraphLibrary(target))
     );
   }
   async remove() {
     const target = requireLibraryTarget(this.uri);
-    return await this.#runtime.run(
-      async () => await removeWikiGraphLibrary(target)
+    return toLibrarySnapshot(
+      await this.#runtime.run(async () => await removeWikiGraphLibrary(target))
     );
   }
 };
+function toLibrarySnapshot(record) {
+  const compatible = record;
+  return {
+    id: record.id,
+    publicId: record.publicId,
+    uri: record.uri,
+    folderPath: compatible.folderPath ?? (record.folder === void 0 ? "" : getNodeResourcePath(record.folder)),
+    isDefault: record.isDefault,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  };
+}
+function toArchiveSnapshot(record) {
+  const { file: _file, ...snapshot } = record;
+  return snapshot;
+}
+function toScanSnapshot(result) {
+  return {
+    ...result.library === void 0 ? {} : { library: toLibrarySnapshot(result.library) },
+    archives: result.archives.map(toArchiveSnapshot)
+  };
+}
 function requireLibraryTarget(value) {
   if (typeof value !== "string") return value;
   const target = parseWikiGraphLibraryUri2(value);
@@ -4585,7 +4720,7 @@ import {
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri3,
   upgradeWikiGraphMaintenanceTarget
 } from "wiki-graph-core";
-import { basename as basename3 } from "path";
+import { basename as basename5 } from "path";
 var WikiGraphMaintenanceManager = class {
   #runtime;
   constructor(runtime) {
@@ -4609,7 +4744,7 @@ var WikiGraphMaintenanceManager = class {
             target: parsed
           });
         }
-        const path = resolveWikiGraphRuntimePath(target.path);
+        const path = await assertStandaloneWikiGraphArchivePath(target.path);
         return await upgradeWikiGraphMaintenanceTarget({
           file: new NodeFile(path),
           kind: "archive"
@@ -4625,7 +4760,7 @@ var WikiGraphMaintenanceManager = class {
       const resolvedOutputPath = resolveWikiGraphRuntimePath(outputPath);
       await migrateLegacySdpubToWikg(
         new NodeFile(resolvedInputPath),
-        new NodeFile(resolvedOutputPath, basename3(resolvedOutputPath))
+        new NodeFile(resolvedOutputPath, basename5(resolvedOutputPath))
       );
       return {
         inputPath: resolvedInputPath,
@@ -4707,16 +4842,16 @@ import {
   formatError as formatError3,
   formatLocatedChapterResourceUri,
   formatLocatedChapterSourceCollectionUri,
-  formatLocatedChapterUri as formatLocatedChapterUri2,
-  formatLocatedWikiGraphUri as formatLocatedWikiGraphUri2,
+  formatLocatedChapterUri as formatLocatedChapterUri3,
+  formatLocatedWikiGraphUri as formatLocatedWikiGraphUri3,
   formatWikiGraphCommandUri,
-  formatWikiGraphLibraryUri as formatWikiGraphLibraryUri2,
+  formatWikiGraphLibraryUri as formatWikiGraphLibraryUri3,
   isSourceLocatorScopeUri as isSourceLocatorScopeUri2,
   isWikiGraphLibraryUri,
   parseChapterPath,
   parseChapterTreeInput,
   parseChapterUriPath,
-  parseLocatedWikiGraphUri as parseLocatedWikiGraphUri2,
+  parseLocatedWikiGraphUri as parseLocatedWikiGraphUri3,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri4,
   parseWikiGraphUriSyntax
@@ -4735,6 +4870,7 @@ export {
   WikiGraphArchiveExistsError,
   WikiGraphArchiveHandle,
   WikiGraphArchiveManager,
+  WikiGraphArchiveOwnershipError,
   WikiGraphConfigManager,
   WikiGraphContinuationManager,
   WikiGraphConversionManager,
@@ -4753,7 +4889,6 @@ export {
   createNodeTemplateEnvironment,
   createNodeWikiGraphStorage,
   createStageLLM,
-  createWikiGraphArchiveInspectReport,
   createWikiGraphSDK,
   deleteLocalConfigValue,
   embedQueryText,
@@ -4764,13 +4899,14 @@ export {
   formatGenerationPlanningModel,
   formatLocatedChapterResourceUri,
   formatLocatedChapterSourceCollectionUri,
-  formatLocatedChapterUri2 as formatLocatedChapterUri,
-  formatLocatedWikiGraphUri2 as formatLocatedWikiGraphUri,
+  formatLocatedChapterUri3 as formatLocatedChapterUri,
+  formatLocatedWikiGraphUri3 as formatLocatedWikiGraphUri,
   formatWikiGraphCommandUri,
-  formatWikiGraphLibraryUri2 as formatWikiGraphLibraryUri,
+  formatWikiGraphLibraryUri3 as formatWikiGraphLibraryUri,
   getNodeResourcePath,
   getWikiGraphSDKRuntimeContext,
   getWikiGraphSDKStateDir,
+  inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri2 as isSourceLocatorScopeUri,
   isWikiGraphLibraryUri,
@@ -4784,7 +4920,7 @@ export {
   parseChapterTreeInput,
   parseChapterUriPath,
   parseLocalConfigSection,
-  parseLocatedWikiGraphUri2 as parseLocatedWikiGraphUri,
+  parseLocatedWikiGraphUri3 as parseLocatedWikiGraphUri,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri4 as parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -4797,7 +4933,6 @@ export {
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,
-  resolveWikiGraphArchiveLocation,
   resolveWikispineConfig,
   runWikiGraphQueueWorker,
   validateLocalConfigSection,