wiki-graph-sdk 0.7.1 → 0.8.1

package/dist/index.js

@@ -4,20 +4,20 @@ 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 basename3, 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,
   applyChapterTree,
+  assertArchiveIndexArtifactsReady,
   assertNoActiveBuildJobConflicts,
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
   DirectoryDocument,
-  finalizeWikiGraphLibraryArchiveWrite,
   findArchiveObjects,
-  formatLocatedWikiGraphUri,
+  formatLocatedWikiGraphUri as formatLocatedWikiGraphUri2,
   isArchiveSearchIndexCurrent as isArchiveSearchIndexCurrent2,
   isSourceLocatorScopeUri,
   listArchiveCollection,
@@ -28,23 +28,19 @@ 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
@@ -54,7 +50,7 @@ import {
 import { createHash } from "crypto";
 import { createReadStream } from "fs";
 import { rm as rm2 } from "fs/promises";
-import { basename as basename2 } from "path";
+import { basename as basename3 } from "path";
 import {
   WikiGraph
 } from "wiki-graph-core";
@@ -383,42 +379,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();
       });
     });
   }
@@ -432,10 +428,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);
     });
   });
 }
@@ -444,19 +440,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();
@@ -466,7 +462,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve3(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -576,12 +572,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);
@@ -712,11 +708,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 = {
@@ -870,12 +866,16 @@ function getWikiGraphSDKRuntimeContext() {
   return runtimeContext.getStore() ?? {
     cwd: process.cwd(),
     env: process.env,
-    envPolicy: "production"
+    envPolicy: "production",
+    providers: {}
   };
 }
 function getWikiGraphSDKStateDir() {
   return getWikiGraphSDKRuntimeContext().stateDir;
 }
+function getWikiGraphSDKProviders() {
+  return getWikiGraphSDKRuntimeContext().providers ?? {};
+}
 
 // src/local-config.ts
 import { join as join2 } from "path";
@@ -1176,8 +1176,8 @@ var inlineLLMConfigSchema = z.object({
 });
 async function loadWikiGraphRuntimeConfig(options) {
   const [embedding, localLLM, concurrent, wikimedia, wikispine] = await Promise.all([
-    readLocalConfigSection("embeddings"),
-    readLocalConfigSection("llm"),
+    options?.skipEmbeddingConfig === true ? Promise.resolve({}) : readLocalConfigSection("embeddings"),
+    options?.skipLLMConfig === true ? Promise.resolve({}) : readLocalConfigSection("llm"),
     readLocalConfigSection("concurrent"),
     readLocalConfigSection("wikimedia"),
     readLocalConfigSection("wikispine")
@@ -1373,6 +1373,14 @@ function formatError2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/providers.ts
+function resolveWikiGraphLLMJSON(options) {
+  if (options.llm !== void 0 && options.llmJSON !== void 0) {
+    throw new Error("Pass either llm or llmJSON, not both.");
+  }
+  return options.llm === void 0 ? options.llmJSON : JSON.stringify(options.llm);
+}
+
 // src/runtime-path.ts
 import { homedir as homedir3 } from "os";
 import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
@@ -1385,6 +1393,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;
@@ -1409,23 +1614,33 @@ var WikiGraphConversionManager = class {
     }
     const requiresDigest = options.input.format !== "wikg";
     const requiresLLM = requiresDigest && targetStage !== "planned" && targetStage !== "sourced";
+    const llmJSON = resolveWikiGraphLLMJSON(options);
+    const injectedLLM = llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
     const config = await loadWikiGraphRuntimeConfig({
-      ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
+      ...llmJSON === void 0 ? {} : { llmJSON },
+      ...injectedLLM === void 0 ? {} : { skipLLMConfig: true },
+      ...getWikiGraphSDKProviders().embedding === void 0 ? {} : { skipEmbeddingConfig: true }
     });
     const app = new WikiGraph({
       ...options.verbose === true ? { verbose: true } : {},
-      ...requiresLLM ? { llm: buildWikiGraphLLMOptions(config) } : {}
+      ...requiresLLM ? {
+        llm: injectedLLM === void 0 ? buildWikiGraphLLMOptions(config) : { streamProvider: injectedLLM }
+      } : {}
     });
     const documentDirectory = await prepareDigestDirectory(
       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);
     };
@@ -1434,7 +1649,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) {
@@ -1477,6 +1694,7 @@ var WikiGraphConversionManager = class {
     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,
@@ -1493,7 +1711,8 @@ 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.");
@@ -1522,7 +1741,7 @@ async function resolveSourceArtifact(input) {
   return {
     digest: hash.digest("hex"),
     mediaType: "application/epub+zip",
-    name: basename2(path)
+    name: basename3(path)
   };
 }
 function isNodeErrorCode(error, code) {
@@ -1538,6 +1757,21 @@ function countTocChapters(items) {
   }
   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 {
@@ -1706,6 +1940,8 @@ function createOpenAICompatibleName2(baseURL) {
 
 // src/query-runtime.ts
 async function createConfiguredEmbeddingProvider() {
+  const injected = getWikiGraphSDKProviders().embedding;
+  if (injected !== void 0) return injected;
   const config = await readWikiGraphEmbeddingConfig();
   if (config.provider === void 0 || config.model === void 0 || config.provider === "openai-compatible" && config.baseURL === void 0 || config.provider === "openai" && config.baseURL !== void 0) {
     return void 0;
@@ -1734,499 +1970,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 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/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"
-      };
-    })
-  );
+  return selected;
 }
-async function readSummaryWords(document, chapterId) {
-  return await document.readDatabase(
-    async (database) => await database.queryOne(
-      `
-          SELECT COALESCE(SUM(words_count), 0) AS words
-          FROM text_sentence_records
-          WHERE kind = 2
-            ${chapterId === void 0 ? "" : "AND chapter_id = ?"}
-        `,
-      chapterId === void 0 ? void 0 : [chapterId],
-      (row) => Number(row.words)
-    ) ?? 0
-  );
+function byChapterId(coverage) {
+  return new Map(coverage.map((item) => [item.serialId, item]));
 }
-async function readIndexArtifactCoverage(document, kind, chapterId) {
-  const coverage = await document.indexArtifacts.listCoverage(kind);
-  return chapterId === void 0 ? coverage : coverage.filter((item) => item.serialId === chapterId);
-}
-function filterChaptersByCurrentIndexArtifact(chapters, coverage) {
-  const currentChapterIds = new Set(
-    coverage.filter((item) => item.current).map((item) => item.serialId)
-  );
-  return chapters.filter((chapter) => currentChapterIds.has(chapter.chapterId));
-}
-function createInspectCoverage(covered, total) {
-  const coveredWords = sumWords(covered);
-  const totalWords = sumWords(total);
+function inspectArtifact(kind, coverage) {
   return {
-    coveredChapters: covered.length,
-    coveredWords,
-    percent: formatPercent(coveredWords, totalWords),
-    totalChapters: total.length,
-    totalWords
+    current: coverage?.current === true,
+    exists: coverage?.sourceRevision !== void 0,
+    kind,
+    ...coverage?.sourceRevision === void 0 ? {} : { sourceRevision: coverage.sourceRevision }
   };
 }
-function formatRetrievalGuidance(input) {
-  if (input.sourceWords === 0 || input.contentChapters.length === 0) {
-    return [
-      "Source content: empty.",
-      "Add source text before using query coverage or graph-based retrieval."
-    ];
-  }
-  const lines = [
-    input.queryReady ? `Query: available; local index cache is ${input.indexCacheCurrent ? "current" : "missing or outdated and can be synced from artifacts"}.` : "Query: unavailable until every content chapter has a current FTS or source embedding artifact."
-  ];
-  lines.push(
-    formatObjectSearchGuidance(
-      "Reading Graph object retrieval",
-      input.readingGraphCovered,
-      input.contentChapters
-    )
-  );
-  lines.push(
-    formatObjectSearchGuidance(
-      "Entity/triple retrieval",
-      input.knowledgeGraphCovered,
-      input.contentChapters
+async function readSummaryWords(document) {
+  const rows = await document.readDatabase(
+    async (database) => await database.queryAll(
+      `
+        SELECT chapter_id, COALESCE(SUM(words_count), 0) AS words
+        FROM text_sentence_records
+        WHERE kind = 2
+        GROUP BY chapter_id
+      `,
+      void 0,
+      (row) => ({
+        chapterId: Number(row.chapter_id),
+        words: Number(row.words)
+      })
     )
   );
-  return lines;
-}
-function formatObjectSearchGuidance(label, covered, total) {
-  const coveredWords = sumWords(covered);
-  const totalWords = sumWords(total);
-  const ratio = totalWords === 0 ? 0 : coveredWords / totalWords;
-  const coverage = formatPercent(coveredWords, totalWords);
-  if (ratio >= 1) {
-    return `${label}: covers all source content; it can represent the full scope for object retrieval.`;
-  }
-  if (ratio >= 0.9) {
-    return `${label}: covers ${coverage}; use it as the main path, but source --query is needed for uncovered content.`;
-  }
-  if (ratio >= 0.5) {
-    return `${label}: covers ${coverage}; use it as leads, not as a full-scope substitute for source --query.`;
-  }
-  return `${label}: covers ${coverage}; build missing graph coverage before relying on object retrieval.`;
-}
-function createInspectImprovements(input) {
-  const improvements = [];
-  if (input.contentChapters.length === 0) {
-    improvements.push({
-      kind: "add-source",
-      recommendation: "No source content is available yet; add or import source text before graph or summary generation.",
-      title: "Add source content"
-    });
-    return improvements;
-  }
-  if (input.queryBlockedChapters.length > 0) {
-    improvements.push({
-      kind: "build",
-      missingChapters: input.queryBlockedChapters.length,
-      missingWords: sumWords(input.queryBlockedChapters),
-      recommendation: "Build local FTS artifacts to make this scope queryable. This does not call a provider.",
-      task: "index-fts",
-      title: "Enable query with local FTS"
-    });
-  } else if (!input.indexCacheCurrent) {
-    improvements.push({
-      kind: "sync-index",
-      recommendation: "Sync the index cache from chapter index artifacts so query starts without a lazy cache rebuild.",
-      title: "Sync index cache"
-    });
-  }
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.readingGraphCovered,
-      planningModel: input.planningModel,
-      task: "reading-graph",
-      title: "Complete Reading Graph coverage",
-      total: input.contentChapters
-    })
-  );
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.knowledgeGraphCovered,
-      planningModel: input.planningModel,
-      task: "knowledge-graph",
-      title: "Complete Knowledge Graph coverage",
-      total: input.contentChapters
-    })
-  );
-  improvements.push(
-    ...createGraphImprovement({
-      concurrent: input.concurrent,
-      covered: input.summaryCovered,
-      planningModel: input.planningModel,
-      task: "reading-summary",
-      title: "Complete Summary coverage",
-      total: input.contentChapters
-    })
-  );
-  return improvements;
-}
-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.";
+  return new Map(rows.map((row) => [row.chapterId, row.words]));
 }
-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
@@ -2246,13 +2113,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),
-        `.${basename3(path)}.${randomUUID2()}.tmp.wikg`
+      const outputPath = join4(
+        dirname3(path),
+        `.${basename4(path)}.${randomUUID2()}.tmp.wikg`
       );
       try {
         if (options.importPath === void 0) {
@@ -2277,15 +2144,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);
@@ -2308,14 +2175,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 }
       }),
@@ -2323,13 +2193,15 @@ var WikiGraphArchiveHandle = class {
     );
   }
   async search(query, options = {}) {
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
@@ -2616,7 +2488,7 @@ var WikiGraphArchiveHandle = class {
         objectUri,
         async (wikimediaOptions) => await this.#readDocument(
           async (document) => await readArchivePage(document, objectUri, {
-            ...withoutOperation(options),
+            ...options,
             ...wikimediaOptions
           }),
           options
@@ -2627,6 +2499,9 @@ var WikiGraphArchiveHandle = class {
   }
   async related(objectUri = this.objectUri, options = {}) {
     if (options.query === void 0) {
+      if (options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await listRelatedArchiveObjects(document, objectUri, {
@@ -2635,19 +2510,22 @@ var WikiGraphArchiveHandle = class {
         });
       }, options);
     }
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
         return await listRelatedArchiveObjects(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2659,6 +2537,9 @@ var WikiGraphArchiveHandle = class {
   }
   async evidence(objectUri = this.objectUri, options = {}) {
     if (options.query === void 0) {
+      if (options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await listArchiveEvidence(document, objectUri, {
@@ -2667,19 +2548,22 @@ var WikiGraphArchiveHandle = class {
         });
       }, options);
     }
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
         return await listArchiveEvidence(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2713,6 +2597,24 @@ var WikiGraphArchiveHandle = class {
       return meta;
     }, options);
   }
+  async setArchiveTitle(title, options = {}) {
+    const normalized = title?.trim() ?? null;
+    if (title !== null && normalized === "") {
+      throw new Error("Archive title cannot be empty.");
+    }
+    return await this.#writeDocument(async (document) => {
+      if (normalized === null) {
+        await document.metadata.deleteKey("", "title");
+      } else {
+        await document.metadata.put(
+          { kind: ObjectMetadataKind.Archive, objectPath: "" },
+          "title",
+          normalized
+        );
+      }
+      return normalized;
+    }, options);
+  }
   async readCover(options = {}) {
     const app = new WikiGraph2({});
     return await this.#runtime.run(
@@ -2762,7 +2664,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
@@ -2770,28 +2672,33 @@ 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) {
     if (options.chapters !== void 0) return options.chapters;
     return (await resolveArchiveScope(document, this.objectUri, options.depth))?.chapterIds;
   }
-  async #resolveQueryChapters(document, options) {
+  async #resolveQueryChapters(document, options, capabilities) {
     const chapters = await this.#resolveScope(document, options);
-    if (options.skipUnindexed !== true) return chapters;
+    const coverageOptions = {
+      ...chapters === void 0 ? {} : { chapters },
+      ...capabilities.embeddingProvider === void 0 ? {} : { embeddingProvider: capabilities.embeddingProvider },
+      requireEmbeddingProvider: true,
+      ...options.queryMode === void 0 ? {} : { queryMode: options.queryMode }
+    };
+    if (options.skipUnindexed !== true) {
+      await assertArchiveIndexArtifactsReady(document, coverageOptions);
+      return chapters;
+    }
     const queryable = await listArchiveQueryableChapterIds(document, {
-      ...chapters === void 0 ? {} : { chapters }
+      ...coverageOptions
     });
     if (queryable.length === 0) {
       throw new Error(
@@ -2800,52 +2707,20 @@ 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
+  async #resolveQueryEmbeddingProvider(queryMode, signal) {
+    if (queryMode === "fts") return void 0;
+    const provider = await this.#runtime.run(
+      createConfiguredEmbeddingProvider,
+      signal
+    );
+    if (queryMode === "embedding" && provider === void 0) {
+      throw new Error(
+        "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
       );
-      if (state.status !== "missing") {
-        await rebuildWikiGraphLibraryIndex(this.#location.libraryDirtyTarget);
-      }
-    } catch (error) {
-      onError?.(error);
     }
+    return provider;
   }
 };
-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;
@@ -2884,18 +2759,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);
@@ -2917,7 +2783,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -3023,12 +2889,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;
@@ -3044,14 +2911,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) => {
@@ -3062,12 +2930,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);
   })
@@ -3199,7 +3069,7 @@ import {
   listWikiGraphLibraryObjects,
   readContinuationCursor,
   resolveWikiGraphLibraryQueryTargetById,
-  WikiGraphArchiveFile as WikiGraphArchiveFile2
+  WikiGraphArchiveFile as WikiGraphArchiveFile3
 } from "wiki-graph-core";
 var WikiGraphContinuationManager = class {
   #runtime;
@@ -3245,10 +3115,11 @@ var WikiGraphContinuationManager = class {
   }
 };
 async function continueArchiveCursor(cursor, limit) {
+  const embeddingProvider = cursor.kind === "evidence" || cursor.kind === "related" ? await resolveCursorEmbeddingProvider(cursor) : void 0;
   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":
@@ -3274,6 +3145,8 @@ async function continueArchiveCursor(cursor, limit) {
             limit,
             order: cursor.order,
             ...cursor.query === void 0 ? {} : { query: cursor.query },
+            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
             ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
             ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
           });
@@ -3285,6 +3158,8 @@ async function continueArchiveCursor(cursor, limit) {
             limit,
             order: cursor.order,
             ...cursor.query === void 0 ? {} : { query: cursor.query },
+            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
             ...cursor.role === void 0 ? {} : { role: cursor.role },
             ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
             ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
@@ -3294,6 +3169,7 @@ async function continueArchiveCursor(cursor, limit) {
   );
 }
 async function continueLibraryCursor(cursor, limit) {
+  const embeddingProvider = cursor.kind === "evidence" || cursor.kind === "related" ? await resolveCursorEmbeddingProvider(cursor) : void 0;
   if (cursor.kind === "source-locators") {
     throw new Error(
       "Source locator cursors do not use the aggregate library index."
@@ -3330,6 +3206,8 @@ async function continueLibraryCursor(cursor, limit) {
         limit,
         order: cursor.order,
         ...cursor.query === void 0 ? {} : { query: cursor.query },
+        ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+        ...embeddingProvider === void 0 ? {} : { embeddingProvider },
         ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
         ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
       });
@@ -3343,6 +3221,8 @@ async function continueLibraryCursor(cursor, limit) {
           limit,
           order: cursor.order,
           ...cursor.query === void 0 ? {} : { query: cursor.query },
+          ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...cursor.role === void 0 ? {} : { role: cursor.role },
           ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
           ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
@@ -3367,7 +3247,7 @@ function createCollectionOptions(cursor, limit) {
   };
 }
 async function createFindOptions(cursor, limit) {
-  const embeddingProvider = await createConfiguredEmbeddingProvider();
+  const embeddingProvider = await resolveCursorEmbeddingProvider(cursor);
   return {
     archiveKey: cursor.archiveKey,
     ...cursor.backlinks === void 0 ? {} : { backlinks: cursor.backlinks },
@@ -3375,6 +3255,7 @@ async function createFindOptions(cursor, limit) {
     cursor: cursor.cursor,
     ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
     limit,
+    ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
     ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
     ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext },
     ...cursor.triplePattern === void 0 ? {} : { triplePattern: cursor.triplePattern },
@@ -3424,6 +3305,7 @@ function createContinuationPayload(context, cursor) {
         kind: "evidence",
         order: context.order ?? "doc-asc",
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
         targetUri: requireTargetUri(context, "Evidence")
@@ -3440,6 +3322,7 @@ function createContinuationPayload(context, cursor) {
         kind: "related",
         order: context.order ?? "doc-asc",
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.role === void 0 ? {} : { role: context.role },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
@@ -3476,6 +3359,7 @@ function createContinuationPayload(context, cursor) {
         kind: "search",
         ...createLibraryQueryPayload(context),
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
         ...context.triplePattern === void 0 ? {} : { triplePattern: context.triplePattern },
@@ -3483,6 +3367,17 @@ function createContinuationPayload(context, cursor) {
       };
   }
 }
+async function resolveCursorEmbeddingProvider(cursor) {
+  if (cursor.kind !== "search" && cursor.query === void 0) return void 0;
+  if (cursor.queryMode === "fts") return void 0;
+  const provider = await createConfiguredEmbeddingProvider();
+  if (cursor.queryMode === "embedding" && provider === void 0) {
+    throw new Error(
+      "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
+    );
+  }
+  return provider;
+}
 function requireTargetUri(context, label) {
   if (context.targetUri !== void 0) return context.targetUri;
   throw new Error(`${label} continuation cursors require a target URI.`);
@@ -3503,14 +3398,14 @@ import {
   getChapterDetails,
   openWikimediaResolver as openWikimediaResolver2,
   recordBuildJobInputRevision,
-  WikiGraphArchiveFile as WikiGraphArchiveFile4,
+  WikiGraphArchiveFile as WikiGraphArchiveFile5,
   WikiGraphScope,
   withLoggingContext
 } from "wiki-graph-core";
 import {
   applyChapterJobArtifactFile as applyChapterJobArtifactFile3,
   createLocalChapterJobFileExecutor as createLocalChapterJobFileExecutor2,
-  writeChapterJobInputFile as writeChapterJobInputFile2
+  writeChapterJobInputFile as writeChapterJobInputFile3
 } from "wiki-graph-core/worker";
 
 // src/stage.ts
@@ -3523,7 +3418,10 @@ import {
 import { createDefaultWikiGraphSampling } from "wiki-graph-core";
 import { LLM } from "wiki-graph-core";
 function createStageLLM(config, options) {
-  const llmOptions = buildWikiGraphLLMOptions(config);
+  const llmOptions = options?.provider === void 0 ? buildWikiGraphLLMOptions(config) : {
+    ...config.concurrent?.request === void 0 ? {} : { concurrent: config.concurrent.request },
+    streamProvider: options.provider
+  };
   return new LLM({
     sampling: createDefaultWikiGraphSampling({
       ...llmOptions.temperature === void 0 ? {} : { temperature: llmOptions.temperature },
@@ -3537,10 +3435,13 @@ function createStageLLM(config, options) {
   });
 }
 async function loadRequiredStageConfig(options) {
+  const injected = options.llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
   const config = await loadWikiGraphRuntimeConfig({
-    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
+    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON },
+    ...options.llmJSON === void 0 && injected !== void 0 ? { skipLLMConfig: true } : {},
+    ...getWikiGraphSDKProviders().embedding === void 0 ? {} : { skipEmbeddingConfig: true }
   });
-  if (config.llm?.provider === void 0 || config.llm.model === void 0) {
+  if (injected === void 0 && (config.llm?.provider === void 0 || config.llm.model === void 0)) {
     throw new Error(
       "Missing LLM configuration. Set --llm for one run, or configure `wikg://local/config/llm` with provider and model."
     );
@@ -3548,16 +3449,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 {
   applyChapterJobArtifactFile,
-  runBuildJobWorker as runCoreBuildJobWorker
+  runBuildJobWorker as runCoreBuildJobWorker,
+  writeChapterJobInputFile
 } from "wiki-graph-core/worker";
-import { WikiGraphArchiveFile as WikiGraphArchiveFile3 } from "wiki-graph-core";
+import {
+  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();
@@ -3570,7 +3600,11 @@ async function runBuildJobWorker(options) {
 
 // src/default-worker.ts
 async function runWikiGraphQueueWorker(options = {}) {
-  const config = await loadWikiGraphRuntimeConfig();
+  const providers = getWikiGraphSDKProviders();
+  const config = await loadWikiGraphRuntimeConfig({
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...providers.llm === void 0 ? {} : { skipLLMConfig: true }
+  });
   await runBuildJobWorker({
     concurrency: config.concurrent?.job ?? DEFAULT_GENERATION_JOB_CONCURRENCY,
     executeJob: async (job, reporter, context) => {
@@ -3579,12 +3613,16 @@ async function runWikiGraphQueueWorker(options = {}) {
         async () => await executeBuildJob(job, reporter, context)
       );
     },
+    ...options.idleTimeoutMs === void 0 ? {} : { idleTimeoutMs: options.idleTimeoutMs },
     ...options.signal === void 0 ? {} : { signal: options.signal }
   });
 }
 async function executeBuildJob(job, reporter, context) {
+  const providers = getWikiGraphSDKProviders();
   const config = await loadWikiGraphRuntimeConfig({
-    ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON }
+    ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON },
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...job.llmJSON === void 0 && providers.llm !== void 0 ? { skipLLMConfig: true } : {}
   });
   const execution = await openJobExecutor(
     job,
@@ -3646,10 +3684,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 WikiGraphArchiveFile4(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,
@@ -3688,16 +3726,23 @@ async function executeStep(job, kind, execution, reporter, context, inputOptions
     total: 1,
     unit: "item"
   });
-  await new WikiGraphArchiveFile4(job.archive).write(async (document) => {
-    assertJobStillRunning(await getBuildJob(job.jobId));
-    await applyChapterJobArtifactFile3(
-      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",
@@ -3712,12 +3757,17 @@ async function openJobExecutor(job, config, signal, reporter) {
   const stageConfig = generation ? await loadRequiredStageConfig({
     ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON }
   }) : void 0;
+  const injectedLLM = job.llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
   const llm = stageConfig === void 0 ? void 0 : createStageLLM(stageConfig, {
     cacheDirectory: job.cache,
     logDirectory: job.log,
     onTokenUsage: async (usage) => {
       await reporter.addTokenUsage(usage);
-    }
+    },
+    onStreamProgress: async ({ outputCharacters }) => {
+      await reporter.addOutputCharacters(outputCharacters);
+    },
+    ...injectedLLM === void 0 ? {} : { provider: injectedLLM }
   });
   const promptSource = job.prompt ?? stageConfig?.prompt;
   const wikispine = job.target === "knowledge-graph" ? requireKnowledgeGraphWikispineConfig(config) : void 0;
@@ -3736,6 +3786,10 @@ async function openJobExecutor(job, config, signal, reporter) {
       llmRequest: requireValue(
         request,
         "Local Wikimedia resolution requires an LLM."
+      ),
+      llmModelId: requireValue(
+        stageConfig?.llm?.model ?? injectedLLM?.model,
+        "Local Wikimedia resolution requires an LLM model."
       )
     } : {
       endpoint: config.wikimedia.endpoint,
@@ -3743,7 +3797,7 @@ async function openJobExecutor(job, config, signal, reporter) {
       token: config.wikimedia.token
     }
   );
-  const embeddingProvider = job.target === "index-embedding-source" || job.target === "index-embedding-summary" ? buildSearchIndexEmbeddingProvider(requireEmbeddingConfig(config)) : void 0;
+  const embeddingProvider = job.target === "index-embedding-source" || job.target === "index-embedding-summary" ? getWikiGraphSDKProviders().embedding ?? buildSearchIndexEmbeddingProvider(requireEmbeddingConfig(config)) : void 0;
   return {
     async close() {
       await wikimediaResolver?.close();
@@ -3773,12 +3827,12 @@ async function resetStepWorkspace(workspace, kind) {
   return await workspace.createDirectory(name);
 }
 async function readChapterStage(job) {
-  return await new WikiGraphArchiveFile4(job.archive).readDocument(
+  return await new WikiGraphArchiveFile5(job.archive).readDocument(
     async (document) => (await getChapterDetails(document, job.chapterId)).stage
   );
 }
 async function assertCurrentFtsArtifact(job) {
-  await new WikiGraphArchiveFile4(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) {
@@ -3882,7 +3936,7 @@ import {
   boostBuildJob,
   cancelBuildJob,
   cleanBuildJobs,
-  formatLocatedChapterUri,
+  formatLocatedChapterUri as formatLocatedChapterUri2,
   getBuildJob as getBuildJob2,
   listBuildJobs,
   listChapters as listChapters3,
@@ -3891,8 +3945,9 @@ import {
   resolveBuildJobId,
   resumeBuildJob,
   updateBuildJobTarget,
-  resolveChapterPathReadonly as resolveChapterPathReadonly2,
-  WikiGraphArchiveFile as WikiGraphArchiveFile5
+  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;
@@ -3937,20 +3992,30 @@ 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 runWorker(options = {}) {
+    await this.#runtime.run(
+      async () => await runWikiGraphQueueWorker(options),
+      options.signal
+    );
+  }
   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) {
@@ -3959,23 +4024,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);
@@ -3983,8 +4050,11 @@ var WikiGraphJobManager = class {
       const entries = (await Promise.all(
         [...jobsByArchive].map(async ([archivePath, archiveJobs]) => {
           try {
-            const chapters = await new WikiGraphArchiveFile5(
-              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])
@@ -3995,7 +4065,7 @@ var WikiGraphJobManager = class {
                 [
                   job.jobId,
                   {
-                    locatedUri: formatLocatedChapterUri(
+                    locatedUri: formatLocatedChapterUri2(
                       archivePath,
                       chapter.path
                     ),
@@ -4018,72 +4088,90 @@ var WikiGraphJobManager = class {
   }
   async enqueue(options) {
     return await this.#runtime.run(async () => {
+      const llmJSON = resolveWikiGraphLLMJSON(options);
       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 WikiGraphArchiveFile5(
-        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, 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,
+                    ...llmJSON === void 0 ? {} : { 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) {
     return await this.#runtime.run(async () => {
+      const llmJSON = resolveWikiGraphLLMJSON(options);
       const location = await resolveWikiGraphArchiveLocation(options.archive);
       const target = options.target ?? "reading-summary";
-      await validateQueueTargetConfig(target, options.llmJSON);
+      await validateQueueTargetConfig(target, llmJSON);
       const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
-      const candidates = await new WikiGraphArchiveFile5(
+      const candidates = await new WikiGraphArchiveFile6(
         location.archiveFile
       ).readDocument(async (document) => {
         const chapters = await listChapters3(document);
@@ -4120,34 +4208,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));
@@ -4174,7 +4267,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;
@@ -4194,7 +4288,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;
@@ -4231,7 +4326,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 () => {
@@ -4250,6 +4345,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) {
@@ -4260,7 +4403,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
   );
@@ -4271,12 +4414,15 @@ async function selectQueueChapters(document, chapters, options) {
   );
 }
 async function validateQueueTargetConfig(target, llmJSON) {
+  const providers = getWikiGraphSDKProviders();
   const config = target === "knowledge-graph" || target === "reading-graph" || target === "reading-summary" ? await loadRequiredStageConfig({
     ...llmJSON === void 0 ? {} : { llmJSON }
   }) : await loadWikiGraphRuntimeConfig({
-    ...llmJSON === void 0 ? {} : { llmJSON }
+    ...llmJSON === void 0 ? {} : { llmJSON },
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...llmJSON === void 0 && providers.llm !== void 0 ? { skipLLMConfig: true } : {}
   });
-  if ((target === "index-embedding-source" || target === "index-embedding-summary") && config.embedding === void 0) {
+  if ((target === "index-embedding-source" || target === "index-embedding-summary") && config.embedding === void 0 && providers.embedding === void 0) {
     throw new Error(
       "Missing embeddings configuration. Configure `wikg://local/config/embeddings` before queueing embedding index artifact jobs."
     );
@@ -4325,14 +4471,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 });
@@ -4363,12 +4509,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,
@@ -4376,17 +4522,29 @@ import {
   packWikiGraphLibraryContext,
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri2,
   putWikiGraphLibraryMetadata,
-  readWikiGraphLibraryIndexState as readWikiGraphLibraryIndexState2,
+  readWikiGraphLibraryIndexState,
   readWikiGraphLibraryPage,
-  rebuildWikiGraphLibraryIndex as rebuildWikiGraphLibraryIndex2,
+  rebuildWikiGraphLibraryIndex,
   rebindWikiGraphLibrary,
   removeWikiGraphLibrary,
   removeWikiGraphLibraryArchive,
+  replaceWikiGraphLibraryArchive,
   replaceWikiGraphLibraryMetadata,
-  resolveWikiGraphLibrary,
-  scanWikiGraphLibrary
+  resolveWikiGraphLibrary as resolveWikiGraphLibrary2,
+  scanWikiGraphLibrary,
+  withWikiGraphLibraryLock
 } from "wiki-graph-core";
 import { mkdir as mkdir2 } from "fs/promises";
+async function resolveQueryEmbeddingProvider(queryMode) {
+  if (queryMode === "fts") return void 0;
+  const provider = await createConfiguredEmbeddingProvider();
+  if (queryMode === "embedding" && provider === void 0) {
+    throw new Error(
+      "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
+    );
+  }
+  return provider;
+}
 var WikiGraphLibraryManager = class {
   #runtime;
   constructor(runtime) {
@@ -4400,22 +4558,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) {
@@ -4424,51 +4584,115 @@ 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 readArchive(target, consume, options = {}) {
+    return await this.#runtime.run(async () => {
+      const parsedTarget = requireLibraryArchiveTarget(target);
+      const library = await resolveWikiGraphLibrary2(parsedTarget);
+      return await withWikiGraphLibraryLock(
+        library.id,
+        "read",
+        async () => {
+          throwIfAborted(options.signal);
+          const archive = await getWikiGraphLibraryArchive(parsedTarget);
+          const file = requireReadableLibraryArchiveFile(archive);
+          const reader = await file.openReader();
+          let active = true;
+          try {
+            const content = {
+              mediaType: "application/vnd.wiki-graph.archive",
+              size: reader.size,
+              stream: createCallbackScopedArchiveStream(
+                reader,
+                () => active,
+                options.signal
+              ),
+              uri: archive.uri
+            };
+            return await runAbortableCallback(
+              async () => await consume(content),
+              options.signal
+            );
+          } finally {
+            active = false;
+            await reader.close();
+          }
+        },
+        options.signal === void 0 ? {} : { signal: options.signal }
+      );
+    }, options.signal);
+  }
   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
       )
@@ -4516,7 +4740,9 @@ var WikiGraphLibraryManager = class {
   }
   async search(target, query, options = {}) {
     return await this.#runtime.run(async () => {
-      const embeddingProvider = await createConfiguredEmbeddingProvider();
+      const embeddingProvider = await resolveQueryEmbeddingProvider(
+        options.queryMode
+      );
       return await findWikiGraphLibraryObjects2(
         requireLibraryTarget(target),
         query,
@@ -4529,7 +4755,9 @@ var WikiGraphLibraryManager = class {
   }
   async searchArchiveMembers(target, query, options = {}) {
     return await this.#runtime.run(async () => {
-      const embeddingProvider = await createConfiguredEmbeddingProvider();
+      const embeddingProvider = await resolveQueryEmbeddingProvider(
+        options.queryMode
+      );
       return await findWikiGraphLibraryArchiveMembers2(
         requireLibraryTarget(target),
         query,
@@ -4565,26 +4793,41 @@ var WikiGraphLibraryManager = class {
           objectUri,
           { ...options, ...wikimediaOptions }
         )
-      )
+      ),
+      options.signal
     );
   }
   async related(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await listRelatedWikiGraphLibraryObjects2(
+    return await this.#runtime.run(async () => {
+      if (options.query === void 0 && options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
+      const embeddingProvider = options.query === void 0 ? void 0 : await resolveQueryEmbeddingProvider(options.queryMode);
+      return await listRelatedWikiGraphLibraryObjects2(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async evidence(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await listWikiGraphLibraryEvidence2(
+    return await this.#runtime.run(async () => {
+      if (options.query === void 0 && options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
+      const embeddingProvider = options.query === void 0 ? void 0 : await resolveQueryEmbeddingProvider(options.queryMode);
+      return await listWikiGraphLibraryEvidence2(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async pack(target, objectUri, budget = 5e3) {
     return await this.#runtime.run(
@@ -4597,7 +4840,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));
   }
@@ -4610,32 +4853,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);
@@ -4644,6 +4909,97 @@ function requireLibraryTarget(value) {
   }
   return target;
 }
+function requireLibraryArchiveTarget(value) {
+  const target = requireLibraryTarget(value);
+  if (target.kind !== "archive" || target.archivePublicId === void 0 || target.objectUri !== void 0) {
+    throw new TypeError("Expected a Wiki Graph library archive URI.");
+  }
+  return target;
+}
+function requireReadableLibraryArchiveFile(archive) {
+  if (!archive.exists || archive.status === "missing") {
+    throw new Error(`Wiki Graph library archive is missing: ${archive.uri}`);
+  }
+  if (archive.status === "conflict") {
+    throw new Error(
+      `Wiki Graph library archive has a conflict and cannot be read: ${archive.uri}`
+    );
+  }
+  if (archive.file === void 0) {
+    throw new Error(
+      `Wiki Graph library archive is unavailable: ${archive.uri}`
+    );
+  }
+  return archive.file;
+}
+var ARCHIVE_STREAM_CHUNK_SIZE = 64 * 1024;
+function createCallbackScopedArchiveStream(reader, isActive, signal) {
+  let consumed = false;
+  return {
+    [Symbol.asyncIterator]() {
+      assertArchiveReadSessionActive(isActive, signal);
+      if (consumed) {
+        throw new Error(
+          "The library archive stream has already been consumed."
+        );
+      }
+      consumed = true;
+      let offset = 0;
+      let finished = false;
+      return {
+        async next() {
+          if (finished) return { done: true, value: void 0 };
+          assertArchiveReadSessionActive(isActive, signal);
+          if (offset >= reader.size) {
+            finished = true;
+            return { done: true, value: void 0 };
+          }
+          const length = Math.min(
+            ARCHIVE_STREAM_CHUNK_SIZE,
+            reader.size - offset
+          );
+          const chunk = await reader.read(offset, length);
+          assertArchiveReadSessionActive(isActive, signal);
+          offset += chunk.byteLength;
+          return { done: false, value: chunk };
+        },
+        return() {
+          finished = true;
+          return Promise.resolve({ done: true, value: void 0 });
+        }
+      };
+    }
+  };
+}
+function assertArchiveReadSessionActive(isActive, signal) {
+  if (!isActive()) {
+    throw new Error(
+      "The library archive stream cannot be read after its callback has finished."
+    );
+  }
+  throwIfAborted(signal);
+}
+async function runAbortableCallback(operation, signal) {
+  if (signal === void 0) return await operation();
+  throwIfAborted(signal);
+  let rejectAbort;
+  const aborted = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => rejectAbort(abortReason(signal));
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await Promise.race([operation(), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted === true) throw abortReason(signal);
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
 
 // src/maintenance.ts
 import {
@@ -4651,7 +5007,7 @@ import {
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri3,
   upgradeWikiGraphMaintenanceTarget
 } from "wiki-graph-core";
-import { basename as basename4 } from "path";
+import { basename as basename5 } from "path";
 var WikiGraphMaintenanceManager = class {
   #runtime;
   constructor(runtime) {
@@ -4675,7 +5031,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"
@@ -4691,7 +5047,7 @@ var WikiGraphMaintenanceManager = class {
       const resolvedOutputPath = resolveWikiGraphRuntimePath(outputPath);
       await migrateLegacySdpubToWikg(
         new NodeFile(resolvedInputPath),
-        new NodeFile(resolvedOutputPath, basename4(resolvedOutputPath))
+        new NodeFile(resolvedOutputPath, basename5(resolvedOutputPath))
       );
       return {
         inputPath: resolvedInputPath,
@@ -4722,6 +5078,7 @@ var WikiGraphSDK = class {
       cwd: options.cwd ?? process.cwd(),
       env: { ...process.env, ...options.env },
       envPolicy: options.envPolicy ?? "production",
+      providers: { ...options.providers },
       ...options.stateDir === void 0 ? {} : { stateDir: options.stateDir }
     };
     this.archives = new WikiGraphArchiveManager(this);
@@ -4733,7 +5090,7 @@ var WikiGraphSDK = class {
     this.maintenance = new WikiGraphMaintenanceManager(this);
   }
   async run(operation, signal, options = {}) {
-    throwIfAborted(signal);
+    throwIfAborted2(signal);
     const runWithContext = async () => await withWikiGraphSDKRuntimeContext(this.#context, async () => {
       if (options.skipHomeBootstrap !== true) {
         this.#homeReady ??= ensureWikiGraphHomeSchemaCurrent().catch(
@@ -4750,14 +5107,14 @@ var WikiGraphSDK = class {
       this.#context.stateDir,
       runWithContext
     );
-    throwIfAborted(signal);
+    throwIfAborted2(signal);
     return result;
   }
   close() {
     this.jobs.close();
   }
 };
-function throwIfAborted(signal) {
+function throwIfAborted2(signal) {
   if (signal?.aborted !== true) return;
   throw signal.reason instanceof Error ? signal.reason : new Error("The Wiki Graph SDK operation was aborted.");
 }
@@ -4773,16 +5130,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
@@ -4801,6 +5158,7 @@ export {
   WikiGraphArchiveExistsError,
   WikiGraphArchiveHandle,
   WikiGraphArchiveManager,
+  WikiGraphArchiveOwnershipError,
   WikiGraphConfigManager,
   WikiGraphContinuationManager,
   WikiGraphConversionManager,
@@ -4819,7 +5177,6 @@ export {
   createNodeTemplateEnvironment,
   createNodeWikiGraphStorage,
   createStageLLM,
-  createWikiGraphArchiveInspectReport,
   createWikiGraphSDK,
   deleteLocalConfigValue,
   embedQueryText,
@@ -4830,13 +5187,15 @@ export {
   formatGenerationPlanningModel,
   formatLocatedChapterResourceUri,
   formatLocatedChapterSourceCollectionUri,
-  formatLocatedChapterUri2 as formatLocatedChapterUri,
-  formatLocatedWikiGraphUri2 as formatLocatedWikiGraphUri,
+  formatLocatedChapterUri3 as formatLocatedChapterUri,
+  formatLocatedWikiGraphUri3 as formatLocatedWikiGraphUri,
   formatWikiGraphCommandUri,
-  formatWikiGraphLibraryUri2 as formatWikiGraphLibraryUri,
+  formatWikiGraphLibraryUri3 as formatWikiGraphLibraryUri,
   getNodeResourcePath,
+  getWikiGraphSDKProviders,
   getWikiGraphSDKRuntimeContext,
   getWikiGraphSDKStateDir,
+  inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri2 as isSourceLocatorScopeUri,
   isWikiGraphLibraryUri,
@@ -4850,7 +5209,7 @@ export {
   parseChapterTreeInput,
   parseChapterUriPath,
   parseLocalConfigSection,
-  parseLocatedWikiGraphUri2 as parseLocatedWikiGraphUri,
+  parseLocatedWikiGraphUri3 as parseLocatedWikiGraphUri,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri4 as parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -4863,7 +5222,7 @@ export {
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,
-  resolveWikiGraphArchiveLocation,
+  resolveWikiGraphLLMJSON,
   resolveWikispineConfig,
   runWikiGraphQueueWorker,
   validateLocalConfigSection,