wiki-graph-sdk 0.8.2 → 0.8.4

package/dist/index.cjs

@@ -31,6 +31,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  ArchiveCollectionPage: () => ArchiveCollectionPage,
+  ArchiveEvidencePage: () => ArchiveEvidencePage,
+  ArchiveFindPage: () => ArchiveFindPage,
+  ArchiveRelatedPage: () => ArchiveRelatedPage,
+  ArchiveSourceLocatorPage: () => ArchiveSourceLocatorPage,
   DANGEROUS_RUNTIME_ENV_NAMES: () => DANGEROUS_RUNTIME_ENV_NAMES,
   DEFAULT_EXTRACTION_PROMPT: () => import_wiki_graph_core10.DEFAULT_EXTRACTION_PROMPT,
   DEFAULT_GENERATION_JOB_CONCURRENCY: () => DEFAULT_GENERATION_JOB_CONCURRENCY,
@@ -38,6 +43,7 @@ __export(src_exports, {
   DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT: () => import_wiki_graph_core10.DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT,
   LLMPaymentRequiredError: () => import_wiki_graph_core19.LLMPaymentRequiredError,
   LOCAL_CONFIG_SECTIONS: () => LOCAL_CONFIG_SECTIONS,
+  LibraryBucketPage: () => LibraryBucketPage,
   NodeDirectory: () => NodeDirectory,
   NodeFile: () => NodeFile,
   WIKI_GRAPH_URI_PREFIX: () => import_wiki_graph_core19.WIKI_GRAPH_URI_PREFIX,
@@ -58,11 +64,19 @@ __export(src_exports, {
   buildSearchIndexEmbeddingProvider: () => buildSearchIndexEmbeddingProvider,
   buildWikiGraphLLMOptions: () => buildWikiGraphLLMOptions,
   clearLocalConfigSection: () => clearLocalConfigSection,
+  createArchiveCollectionPage: () => createArchiveCollectionPage,
+  createArchiveEvidencePage: () => createArchiveEvidencePage,
+  createArchiveFindPage: () => createArchiveFindPage,
+  createArchiveRelatedPage: () => createArchiveRelatedPage,
+  createArchiveSourceLocatorPage: () => createArchiveSourceLocatorPage,
+  createCursor: () => createCursor,
   createEntryRuntimeContext: () => createEntryRuntimeContext,
   createGenerationPerformanceHints: () => createGenerationPerformanceHints,
+  createLibraryBucketPage: () => createLibraryBucketPage,
   createNodeTemplateEnvironment: () => createNodeTemplateEnvironment,
   createNodeWikiGraphPlatform: () => createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage: () => createNodeWikiGraphStorage,
+  createPageCursor: () => createPageCursor,
   createStageLLM: () => createStageLLM,
   createWikiGraphSDK: () => createWikiGraphSDK,
   deleteLocalConfigValue: () => deleteLocalConfigValue,
@@ -90,6 +104,8 @@ __export(src_exports, {
   isWikiGraphJobUri: () => import_wiki_graph_core19.isWikiGraphJobUri,
   isWikiGraphLibraryUri: () => import_wiki_graph_core19.isWikiGraphLibraryUri,
   isWikiGraphUri: () => import_wiki_graph_core19.isWikiGraphUri,
+  iterateItems: () => iterateItems,
+  iteratePages: () => iteratePages,
   loadRequiredStageConfig: () => loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig: () => loadWikiGraphRuntimeConfig,
   maskLocalConfigSection: () => maskLocalConfigSection,
@@ -129,7 +145,7 @@ module.exports = __toCommonJS(src_exports);
 
 // src/archive/archive.ts
 var import_crypto2 = require("crypto");
-var import_promises4 = require("fs/promises");
+var import_promises5 = require("fs/promises");
 var import_os3 = require("os");
 var import_path5 = require("path");
 var import_stream = require("stream");
@@ -138,7 +154,7 @@ var import_wiki_graph_core7 = require("wiki-graph-core");
 // src/conversions.ts
 var import_crypto = require("crypto");
 var import_fs = require("fs");
-var import_promises3 = require("fs/promises");
+var import_promises4 = require("fs/promises");
 var import_path4 = require("path");
 var import_wiki_graph_core3 = require("wiki-graph-core");
 
@@ -964,13 +980,15 @@ function getWikiGraphSDKRuntimeContext() {
   };
 }
 function getWikiGraphSDKStateDir() {
-  return getWikiGraphSDKRuntimeContext().stateDir;
+  const context = getWikiGraphSDKRuntimeContext();
+  return context.host?.stateDir ?? context.stateDir;
 }
 function getWikiGraphSDKProviders() {
   return getWikiGraphSDKRuntimeContext().providers ?? {};
 }
 
 // src/local-config.ts
+var import_promises2 = require("fs/promises");
 var import_path = require("path");
 var import_os = require("os");
 var LOCAL_CONFIG_SECTIONS = [
@@ -1071,13 +1089,10 @@ function validateLocalConfigSection(section, value) {
   }
 }
 async function withLocalConfigDatabase(operation) {
+  const stateDir = getWikiGraphSDKStateDir() ?? (0, import_path.join)((0, import_os.homedir)(), ".wikigraph");
+  await (0, import_promises2.mkdir)(stateDir, { recursive: true });
   const database = await (0, import_wiki_graph_core.openSharedStateDatabase)(
-    new NodeFile(
-      (0, import_path.join)(
-        getWikiGraphSDKStateDir() ?? (0, import_path.join)((0, import_os.homedir)(), ".wikigraph"),
-        "core.sqlite"
-      )
-    ),
+    new NodeFile((0, import_path.join)(stateDir, "core.sqlite")),
     LOCAL_CONFIG_SCHEMA_SQL
   );
   try {
@@ -1487,7 +1502,7 @@ function resolveWikiGraphRuntimePath(path) {
 }
 
 // src/archive/target.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_path3 = require("path");
 var import_wiki_graph_core2 = require("wiki-graph-core");
 var WikiGraphArchiveOwnershipError = class extends Error {
@@ -1616,7 +1631,7 @@ function withObjectUri(archiveLocator, objectUri) {
 }
 async function canonicalPath(path) {
   try {
-    return await (0, import_promises2.realpath)(path);
+    return await (0, import_promises3.realpath)(path);
   } catch {
     const absolute = (0, import_path3.resolve)(path);
     const parent = (0, import_path3.dirname)(absolute);
@@ -1667,7 +1682,7 @@ function requireUnambiguousManagedMatch(path, matches) {
 }
 async function readFileIdentity(path) {
   try {
-    const value = await (0, import_promises2.stat)(path);
+    const value = await (0, import_promises3.stat)(path);
     return `${value.dev}:${value.ino}`;
   } catch {
     return void 0;
@@ -1791,7 +1806,7 @@ async function prepareDigestDirectory(path, required) {
   if (!required || normalized === void 0 || normalized === "")
     return void 0;
   const resolved = resolveWikiGraphRuntimePath(normalized);
-  await (0, import_promises3.rm)(resolved, { force: true, recursive: true });
+  await (0, import_promises4.rm)(resolved, { force: true, recursive: true });
   return new NodeDirectory(resolved);
 }
 async function writeArchive(archive, path, format) {
@@ -2172,6 +2187,294 @@ async function writeWikiGraphArchiveLocation(location, operation, options = {})
   });
 }
 
+// src/pages.ts
+function createCursor(implementation) {
+  let released = false;
+  const assertLive = () => {
+    if (released) throw new Error("Cursor has been released.");
+  };
+  return {
+    pageClass: implementation.pageClass,
+    async next(options = {}) {
+      assertLive();
+      return await implementation.next(options);
+    },
+    async token() {
+      assertLive();
+      return await implementation.token();
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      await implementation.release?.();
+    }
+  };
+}
+function createPageCursor(implementation) {
+  let token;
+  return createCursor({
+    pageClass: implementation.pageClass,
+    next: async (options) => await implementation.next(implementation.rawCursor, options),
+    token: async () => {
+      token ??= await implementation.createToken(implementation.rawCursor);
+      return token;
+    },
+    release: async () => {
+      if (token !== void 0) await implementation.releaseToken?.(token);
+      token = void 0;
+    }
+  });
+}
+async function* iteratePages(firstPage, options = {}) {
+  let page = firstPage;
+  while (true) {
+    yield page;
+    const cursor = page.nextCursor();
+    if (cursor === null) return;
+    try {
+      const nextPage = await cursor.next(options);
+      await cursor.release();
+      page = nextPage;
+    } catch (error) {
+      await cursor.release();
+      throw error;
+    }
+  }
+}
+async function* iterateItems(firstPage, options = {}) {
+  for await (const page of iteratePages(firstPage, options)) {
+    yield* page;
+  }
+}
+
+// src/result-pages.ts
+var ArchiveFindPage = class _ArchiveFindPage {
+  result;
+  chapters;
+  items;
+  lens;
+  lensHint;
+  limit;
+  match;
+  rawNextCursor;
+  order;
+  query;
+  terms;
+  types;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.result = result;
+    this.chapters = result.chapters;
+    this.items = result.items;
+    this.lens = result.lens;
+    this.lensHint = result.lensHint;
+    this.limit = result.limit;
+    this.match = result.match;
+    this.rawNextCursor = result.nextCursor;
+    this.order = result.order;
+    this.query = result.query;
+    this.terms = result.terms;
+    this.types = result.types;
+    this.#cursor = cursor;
+  }
+  static pageClass = _ArchiveFindPage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+var ArchiveCollectionPage = class _ArchiveCollectionPage {
+  result;
+  chapters;
+  ids;
+  items;
+  limit;
+  rawNextCursor;
+  order;
+  types;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.result = result;
+    this.chapters = result.chapters;
+    this.ids = result.ids;
+    this.items = result.items;
+    this.limit = result.limit;
+    this.rawNextCursor = result.nextCursor;
+    this.order = result.order;
+    this.types = result.types;
+    this.#cursor = cursor;
+  }
+  static pageClass = _ArchiveCollectionPage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+var ArchiveEvidencePage = class _ArchiveEvidencePage {
+  result;
+  items;
+  limit;
+  rawNextCursor;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.result = result;
+    this.items = result.items;
+    this.limit = result.limit;
+    this.rawNextCursor = result.nextCursor;
+    this.#cursor = cursor;
+  }
+  static pageClass = _ArchiveEvidencePage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+var ArchiveRelatedPage = class _ArchiveRelatedPage {
+  result;
+  items;
+  limit;
+  rawNextCursor;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.result = result;
+    this.items = result.items;
+    this.limit = result.limit;
+    this.rawNextCursor = result.nextCursor;
+    this.#cursor = cursor;
+  }
+  static pageClass = _ArchiveRelatedPage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+var ArchiveSourceLocatorPage = class _ArchiveSourceLocatorPage {
+  result;
+  items;
+  limit;
+  rawNextCursor;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.result = result;
+    this.items = result.items;
+    this.limit = result.limit;
+    this.rawNextCursor = result.nextCursor;
+    this.#cursor = cursor;
+  }
+  static pageClass = _ArchiveSourceLocatorPage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+function createArchiveFindPage(result, next, createToken, releaseToken) {
+  return new ArchiveFindPage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: ArchiveFindPage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+function createArchiveCollectionPage(result, next, createToken, releaseToken) {
+  return new ArchiveCollectionPage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: ArchiveCollectionPage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+function createArchiveEvidencePage(result, next, createToken, releaseToken) {
+  return new ArchiveEvidencePage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: ArchiveEvidencePage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+function createArchiveRelatedPage(result, next, createToken, releaseToken) {
+  return new ArchiveRelatedPage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: ArchiveRelatedPage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+function createArchiveSourceLocatorPage(result, next, createToken, releaseToken) {
+  return new ArchiveSourceLocatorPage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: ArchiveSourceLocatorPage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+var LibraryBucketPage = class _LibraryBucketPage {
+  id;
+  items;
+  rawNextCursor;
+  query;
+  terms;
+  types;
+  #cursor;
+  constructor(result, cursor = null) {
+    this.id = result.id;
+    this.items = result.items;
+    this.rawNextCursor = result.nextCursor;
+    this.query = result.query;
+    this.terms = result.terms;
+    this.types = result.types;
+    this.#cursor = cursor;
+  }
+  static pageClass = _LibraryBucketPage;
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
+  nextCursor() {
+    return this.#cursor;
+  }
+};
+function createLibraryBucketPage(result, next, createToken, releaseToken) {
+  return new LibraryBucketPage(
+    result,
+    result.nextCursor === null ? null : createPageCursor({
+      pageClass: LibraryBucketPage,
+      rawCursor: result.nextCursor,
+      next,
+      createToken,
+      releaseToken
+    })
+  );
+}
+
 // src/archive/archive.ts
 var WikiGraphArchiveExistsError = class extends Error {
   code = "WIKI_GRAPH_ARCHIVE_EXISTS";
@@ -2209,10 +2512,10 @@ var WikiGraphArchiveManager = class {
           });
         }
         if (options.replace === true) {
-          await (0, import_promises4.rename)(outputPath, path);
+          await (0, import_promises5.rename)(outputPath, path);
         } else {
           try {
-            await (0, import_promises4.link)(outputPath, path);
+            await (0, import_promises5.link)(outputPath, path);
           } catch (error) {
             if (isNodeEEXISTError(error)) {
               throw new WikiGraphArchiveExistsError(path);
@@ -2222,7 +2525,7 @@ var WikiGraphArchiveManager = class {
         }
         return { locatedUri: (0, import_wiki_graph_core7.formatLocatedWikiGraphUri)(path), path };
       } finally {
-        await (0, import_promises4.rm)(outputPath, { force: true, recursive: true });
+        await (0, import_promises5.rm)(outputPath, { force: true, recursive: true });
       }
     }, options.signal);
   }
@@ -2259,6 +2562,14 @@ var WikiGraphArchiveHandle = class {
   get target() {
     return this.#location.target;
   }
+  async #persistCursor(cursor) {
+    return await this.#runtime.run(
+      async () => await (0, import_wiki_graph_core7.createContinuationCursor)(cursor)
+    );
+  }
+  async #releaseCursor(cursor) {
+    await this.#runtime.run(async () => await (0, import_wiki_graph_core7.deleteContinuationCursor)(cursor));
+  }
   async inspect(options = {}) {
     return await this.#readDocument(
       async (document) => await inspectWikiGraphArchive(document, {
@@ -2273,7 +2584,7 @@ var WikiGraphArchiveHandle = class {
       options.queryMode,
       options.signal
     );
-    return await this.#writeDocument(
+    const result = await this.#writeDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
@@ -2294,9 +2605,38 @@ var WikiGraphArchiveHandle = class {
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
+    return createArchiveFindPage(
+      result,
+      async (cursor, nextOptions) => await this.search(query, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => this.#persistCursor({
+        archiveKey: this.archiveKey,
+        archivePath: this.path,
+        chapters: options.chapters ?? null,
+        cursor,
+        format: "json",
+        indexScope: this.indexScope,
+        kind: "search",
+        ...options.backlinks === void 0 ? {} : { backlinks: options.backlinks },
+        ...options.evidenceLimit === void 0 ? {} : { evidenceLimit: options.evidenceLimit },
+        ...options.match === void 0 ? {} : { match: options.match },
+        ...options.order === void 0 ? {} : { order: options.order },
+        query,
+        ...options.queryMode === void 0 ? {} : { queryMode: options.queryMode },
+        ...options.skipUnindexed === void 0 ? {} : { skipUnindexed: options.skipUnindexed },
+        ...options.sourceContext === void 0 ? {} : { sourceContext: options.sourceContext },
+        ...options.triplePattern === void 0 ? {} : { triplePattern: options.triplePattern },
+        types: options.types ?? null
+      }),
+      (token) => this.#releaseCursor(token)
+    );
   }
   async list(options = {}) {
-    return await this.#readDocument(async (document) => {
+    const result = await this.#readDocument(async (document) => {
       if ((0, import_wiki_graph_core7.isSourceLocatorScopeUri)(this.objectUri)) {
         return await (0, import_wiki_graph_core7.listArchiveSourceLocators)(document, this.objectUri, {
           ...options.cursor === void 0 ? {} : { cursor: options.cursor },
@@ -2309,6 +2649,53 @@ var WikiGraphArchiveHandle = class {
         ...chapters === void 0 ? {} : { chapters }
       });
     }, options);
+    if ((0, import_wiki_graph_core7.isSourceLocatorScopeUri)(this.objectUri)) {
+      return createArchiveSourceLocatorPage(
+        result,
+        async (cursor, nextOptions) => await this.list({
+          ...options,
+          cursor,
+          ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+          ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+        }),
+        (cursor) => this.#persistCursor({
+          archiveKey: this.archiveKey,
+          archivePath: this.path,
+          cursor,
+          format: "json",
+          indexScope: this.indexScope,
+          kind: "source-locators",
+          targetUri: this.objectUri
+        }),
+        (token) => this.#releaseCursor(token)
+      );
+    }
+    return createArchiveCollectionPage(
+      result,
+      async (cursor, nextOptions) => await this.list({
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => this.#persistCursor({
+        archiveKey: this.archiveKey,
+        archivePath: this.path,
+        ...options.backlinks === void 0 ? {} : { backlinks: options.backlinks },
+        chapters: options.chapters ?? null,
+        cursor,
+        ...options.evidenceLimit === void 0 ? {} : { evidenceLimit: options.evidenceLimit },
+        format: "json",
+        ids: options.ids ?? null,
+        indexScope: this.indexScope,
+        kind: "collection",
+        order: options.order ?? "doc-asc",
+        ...options.sourceContext === void 0 ? {} : { sourceContext: options.sourceContext },
+        ...options.triplePattern === void 0 ? {} : { triplePattern: options.triplePattern },
+        types: options.types ?? null
+      }),
+      (token) => this.#releaseCursor(token)
+    );
   }
   async ensureSearchIndex(options = {}) {
     const embeddingProvider = await this.#runtime.run(
@@ -2585,19 +2972,30 @@ var WikiGraphArchiveHandle = class {
       if (options.queryMode !== void 0) {
         throw new Error("`queryMode` requires `query`.");
       }
-      return await this.#readDocument(async (document) => {
+      const result2 = await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await (0, import_wiki_graph_core7.listRelatedArchiveObjects)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
       }, options);
+      return createArchiveRelatedPage(
+        result2,
+        async (cursor, nextOptions) => await this.related(objectUri, {
+          ...options,
+          cursor,
+          ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+          ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+        }),
+        (cursor) => Promise.resolve(cursor),
+        () => Promise.resolve()
+      );
     }
     const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
       options.queryMode,
       options.signal
     );
-    return await this.#writeDocument(
+    const result = await this.#writeDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
@@ -2617,25 +3015,47 @@ var WikiGraphArchiveHandle = class {
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
+    return createArchiveRelatedPage(
+      result,
+      async (cursor, nextOptions) => await this.related(objectUri, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   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 result2 = await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await (0, import_wiki_graph_core7.listArchiveEvidence)(document, objectUri, {
           ...withoutOperation(options),
           ...chapters === void 0 ? {} : { chapters }
         });
       }, options);
+      return createArchiveEvidencePage(
+        result2,
+        async (cursor, nextOptions) => await this.evidence(objectUri, {
+          ...options,
+          cursor,
+          ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+          ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+        }),
+        (cursor) => Promise.resolve(cursor),
+        () => Promise.resolve()
+      );
     }
     const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
       options.queryMode,
       options.signal
     );
-    return await this.#writeDocument(
+    const result = await this.#writeDocument(
       async (document) => {
         const chapters = await this.#resolveQueryChapters(document, options, {
           embeddingProvider
@@ -2655,6 +3075,17 @@ var WikiGraphArchiveHandle = class {
         ...options.signal === void 0 ? {} : { signal: options.signal }
       }
     );
+    return createArchiveEvidencePage(
+      result,
+      async (cursor, nextOptions) => await this.evidence(objectUri, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async pack(objectUri = this.objectUri, budget = 5e3, options = {}) {
     return await this.#readDocument(
@@ -2843,7 +3274,7 @@ function selectChapterSubtree(chapters, rootChapterId, depth) {
   );
 }
 async function createEmptyArchiveFile(path) {
-  const directoryPath = await (0, import_promises4.mkdtemp)(
+  const directoryPath = await (0, import_promises5.mkdtemp)(
     (0, import_path5.join)((0, import_os3.tmpdir)(), "wikigraph-archive-write-")
   );
   try {
@@ -2858,7 +3289,7 @@ async function createEmptyArchiveFile(path) {
     }
     await (0, import_wiki_graph_core7.writeWikgArchive)(directory, new NodeFile(path));
   } finally {
-    await (0, import_promises4.rm)(directoryPath, { force: true, recursive: true });
+    await (0, import_promises5.rm)(directoryPath, { force: true, recursive: true });
   }
 }
 function isNodeEEXISTError(error) {
@@ -2866,7 +3297,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await (0, import_promises4.stat)(path);
+    await (0, import_promises5.stat)(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -3642,19 +4073,40 @@ function prepareWikiGraphSDKHost(host) {
   (0, import_platform2.installWikiGraphPlatform)(host.platform);
 }
 function assertWikiGraphSDKHostOptions(options) {
-  if (options.host?.storage !== void 0 && options.stateDir !== void 0) {
+  if (options.host?.storage !== void 0 && options.host.stateDir === void 0) {
     throw new TypeError(
-      "Wiki Graph SDK host.storage and stateDir cannot be used together."
+      "Wiki Graph SDK host.storage requires host.stateDir so SDK configuration cannot fall back to the default user state directory."
+    );
+  }
+  if (options.stateDir !== void 0 && (options.host?.stateDir !== void 0 || options.host?.storage !== void 0)) {
+    throw new TypeError(
+      "Wiki Graph SDK host state/storage and top-level stateDir cannot be used together. Put the state directory in host.stateDir when providing host.storage."
     );
   }
 }
 async function withWikiGraphSDKHost(options, operation) {
-  assertWikiGraphSDKHostOptions(options);
-  prepareWikiGraphSDKHost(options.host);
-  if (options.host?.storage !== void 0) {
-    return await (0, import_platform2.withWikiGraphStorage)(options.host.storage, operation);
+  const current = getWikiGraphSDKRuntimeContext();
+  const effective = {
+    ...options.host === void 0 ? current.host === void 0 ? {} : { host: current.host } : { host: options.host },
+    ...options.stateDir === void 0 ? current.stateDir === void 0 ? {} : { stateDir: current.stateDir } : { stateDir: options.stateDir }
+  };
+  assertWikiGraphSDKHostOptions(effective);
+  prepareWikiGraphSDKHost(effective.host);
+  const runWithContext = async () => await withWikiGraphSDKRuntimeContext(
+    {
+      ...current,
+      ...effective.host === void 0 ? {} : { host: effective.host },
+      ...effective.stateDir === void 0 ? {} : { stateDir: effective.stateDir }
+    },
+    operation
+  );
+  if (effective.host?.storage !== void 0) {
+    return await (0, import_platform2.withWikiGraphStorage)(effective.host.storage, runWithContext);
   }
-  return await withNodeWikiGraphStorage(options.stateDir, operation);
+  return await withNodeWikiGraphStorage(
+    effective.host?.stateDir ?? effective.stateDir,
+    runWithContext
+  );
 }
 
 // src/worker.ts
@@ -4556,7 +5008,7 @@ function forwardAbort(source, target) {
 
 // src/libraries.ts
 var import_wiki_graph_core16 = require("wiki-graph-core");
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 async function resolveQueryEmbeddingProvider(queryMode) {
   if (queryMode === "fts") return void 0;
   const provider = await createConfiguredEmbeddingProvider();
@@ -4575,7 +5027,7 @@ var WikiGraphLibraryManager = class {
   async create(folder) {
     const record = await this.#runtime.run(async () => {
       const path = resolveWikiGraphRuntimePath(folder);
-      await (0, import_promises5.mkdir)(path);
+      await (0, import_promises6.mkdir)(path);
       return await (0, import_wiki_graph_core16.createWikiGraphLibrary)({ folder: new NodeDirectory(path) });
     });
     return new WikiGraphLibrary(this.#runtime, record);
@@ -4761,7 +5213,7 @@ var WikiGraphLibraryManager = class {
     );
   }
   async search(target, query, options = {}) {
-    return await this.#runtime.run(async () => {
+    const result = await this.#runtime.run(async () => {
       const embeddingProvider = await resolveQueryEmbeddingProvider(
         options.queryMode
       );
@@ -4774,9 +5226,70 @@ var WikiGraphLibraryManager = class {
         }
       );
     });
+    return createArchiveFindPage(
+      result,
+      async (cursor, nextOptions) => await this.search(target, query, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
+  }
+  async searchBuckets(target, query, options) {
+    const result = await this.#runtime.run(async () => {
+      const embeddingProvider = await resolveQueryEmbeddingProvider(
+        options.queryMode
+      );
+      return await (0, import_wiki_graph_core16.findWikiGraphLibraryObjectBuckets)(
+        requireLibraryTarget(target),
+        query,
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
+    return {
+      buckets: result.buckets.map(
+        (bucket) => createLibraryBucketPage(
+          bucket,
+          async (cursor, nextOptions) => await this.continueSearchBucket(target, cursor, {
+            ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit }
+          }),
+          (cursor) => Promise.resolve(cursor),
+          () => Promise.resolve()
+        )
+      ),
+      query: result.query
+    };
+  }
+  async continueSearchBucket(target, cursor, options = {}) {
+    const result = await this.#runtime.run(async () => {
+      const embeddingProvider = await resolveQueryEmbeddingProvider(void 0);
+      return await (0, import_wiki_graph_core16.continueWikiGraphLibraryObjectBucket)(
+        requireLibraryTarget(target),
+        cursor,
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
+    return createLibraryBucketPage(
+      result,
+      async (nextCursor, nextOptions) => await this.continueSearchBucket(target, nextCursor, {
+        ...options,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit }
+      }),
+      (cursor2) => Promise.resolve(cursor2),
+      () => Promise.resolve()
+    );
   }
   async searchArchiveMembers(target, query, options = {}) {
-    return await this.#runtime.run(async () => {
+    const result = await this.#runtime.run(async () => {
       const embeddingProvider = await resolveQueryEmbeddingProvider(
         options.queryMode
       );
@@ -4789,22 +5302,53 @@ var WikiGraphLibraryManager = class {
         }
       );
     });
+    return createArchiveFindPage(
+      result,
+      async (cursor, nextOptions) => await this.searchArchiveMembers(target, query, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async objects(target, options = {}) {
-    return await this.#runtime.run(
+    const result = await this.#runtime.run(
       async () => await (0, import_wiki_graph_core16.listWikiGraphLibraryObjects)(
         requireLibraryTarget(target),
         options
       )
     );
+    return createArchiveCollectionPage(
+      result,
+      async (cursor, nextOptions) => await this.objects(target, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async archiveMembers(target, options = {}) {
-    return await this.#runtime.run(
+    const result = await this.#runtime.run(
       async () => await (0, import_wiki_graph_core16.listWikiGraphLibraryArchiveMembers)(
         requireLibraryTarget(target),
         options
       )
     );
+    return createArchiveCollectionPage(
+      result,
+      async (cursor, nextOptions) => await this.archiveMembers(target, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async page(target, objectUri, options = {}) {
     return await this.#runtime.run(
@@ -4820,7 +5364,7 @@ var WikiGraphLibraryManager = class {
     );
   }
   async related(target, objectUri, options = {}) {
-    return await this.#runtime.run(async () => {
+    const result = await this.#runtime.run(async () => {
       if (options.query === void 0 && options.queryMode !== void 0) {
         throw new Error("`queryMode` requires `query`.");
       }
@@ -4834,9 +5378,20 @@ var WikiGraphLibraryManager = class {
         }
       );
     });
+    return createArchiveRelatedPage(
+      result,
+      async (cursor, nextOptions) => await this.related(target, objectUri, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async evidence(target, objectUri, options = {}) {
-    return await this.#runtime.run(async () => {
+    const result = await this.#runtime.run(async () => {
       if (options.query === void 0 && options.queryMode !== void 0) {
         throw new Error("`queryMode` requires `query`.");
       }
@@ -4850,6 +5405,17 @@ var WikiGraphLibraryManager = class {
         }
       );
     });
+    return createArchiveEvidencePage(
+      result,
+      async (cursor, nextOptions) => await this.evidence(target, objectUri, {
+        ...options,
+        cursor,
+        ...nextOptions.limit === void 0 ? {} : { limit: nextOptions.limit },
+        ...nextOptions.signal === void 0 ? {} : { signal: nextOptions.signal }
+      }),
+      (cursor) => Promise.resolve(cursor),
+      () => Promise.resolve()
+    );
   }
   async pack(target, objectUri, budget = 5e3) {
     return await this.#runtime.run(
@@ -5149,6 +5715,11 @@ function createWikiGraphSDK(options = {}) {
 var import_wiki_graph_core19 = require("wiki-graph-core");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArchiveCollectionPage,
+  ArchiveEvidencePage,
+  ArchiveFindPage,
+  ArchiveRelatedPage,
+  ArchiveSourceLocatorPage,
   DANGEROUS_RUNTIME_ENV_NAMES,
   DEFAULT_EXTRACTION_PROMPT,
   DEFAULT_GENERATION_JOB_CONCURRENCY,
@@ -5156,6 +5727,7 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT,
   LLMPaymentRequiredError,
   LOCAL_CONFIG_SECTIONS,
+  LibraryBucketPage,
   NodeDirectory,
   NodeFile,
   WIKI_GRAPH_URI_PREFIX,
@@ -5176,11 +5748,19 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   buildSearchIndexEmbeddingProvider,
   buildWikiGraphLLMOptions,
   clearLocalConfigSection,
+  createArchiveCollectionPage,
+  createArchiveEvidencePage,
+  createArchiveFindPage,
+  createArchiveRelatedPage,
+  createArchiveSourceLocatorPage,
+  createCursor,
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
+  createLibraryBucketPage,
   createNodeTemplateEnvironment,
   createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
+  createPageCursor,
   createStageLLM,
   createWikiGraphSDK,
   deleteLocalConfigValue,
@@ -5208,6 +5788,8 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   isWikiGraphJobUri,
   isWikiGraphLibraryUri,
   isWikiGraphUri,
+  iterateItems,
+  iteratePages,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,