wiki-graph-sdk 0.8.3 → 0.9.0

package/dist/index.js

@@ -15,6 +15,8 @@ import {
   assertNoActiveBuildJobConflicts,
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
+  createContinuationCursor,
+  deleteContinuationCursor,
   DirectoryDocument,
   findArchiveObjects,
   formatLocatedWikiGraphUri as formatLocatedWikiGraphUri2,
@@ -41,6 +43,7 @@ import {
   getChapterTree,
   WikiGraph as WikiGraph2,
   WikiGraphArchiveFile as WikiGraphArchiveFile2,
+  WikiGraphDirectoryFile as WikiGraphDirectoryFile2,
   TOC_FILE_VERSION,
   writeWikgArchive,
   ObjectMetadataKind
@@ -1418,6 +1421,9 @@ import {
   resolveWikiGraphLibrary,
   resolveWikiGraphLibraryArchiveFile
 } from "wiki-graph-core";
+function requireWikiGraphArchiveFile(location) {
+  return location.archiveFile;
+}
 var WikiGraphArchiveOwnershipError = class extends Error {
   code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
   constructor(message) {
@@ -1564,11 +1570,12 @@ async function findMatchingMembers(libraries, candidate, candidateIdentity) {
       ...library.isDefault ? {} : { publicId: library.publicId }
     });
     for (const archive of archives) {
-      if (archive.file === void 0) continue;
+      const physical = archive.file ?? archive.directory;
+      if (physical === void 0) continue;
       members.push({
         archive,
         library,
-        memberPath: getNodeResourcePath(archive.file)
+        memberPath: getNodeResourcePath(physical)
       });
     }
   }
@@ -2083,17 +2090,30 @@ function formatLocatedChapterUri(archiveUri, chapter) {
 // src/archive/write.ts
 import {
   WikiGraphArchiveFile,
+  WikiGraphDirectoryFile,
   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 }
-  });
+  const write = async (archiveFile = location.archiveFile) => {
+    const writeOptions = {
+      ...cacheOnly ? {} : { derivedStateKeys: [location.archiveKey, location.archivePath] },
+      ...options.invalidateContinuationCursors === void 0 ? {} : {
+        invalidateContinuationCursors: options.invalidateContinuationCursors
+      },
+      ...options.searchIndexWritebackPolicy === void 0 ? {} : { searchIndexWritebackPolicy: options.searchIndexWritebackPolicy }
+    };
+    if (archiveFile.kind === "directory") {
+      return await new WikiGraphDirectoryFile(archiveFile).write(
+        operation,
+        writeOptions
+      );
+    }
+    return await new WikiGraphArchiveFile(archiveFile).write(
+      operation,
+      writeOptions
+    );
+  };
   if (location.libraryArchiveTarget === void 0 || cacheOnly || options.refreshLibraryIndex === false) {
     return await write();
   }
@@ -2108,6 +2128,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";
@@ -2195,6 +2503,14 @@ var WikiGraphArchiveHandle = class {
   get target() {
     return this.#location.target;
   }
+  async #persistCursor(cursor) {
+    return await this.#runtime.run(
+      async () => await createContinuationCursor(cursor)
+    );
+  }
+  async #releaseCursor(cursor) {
+    await this.#runtime.run(async () => await deleteContinuationCursor(cursor));
+  }
   async inspect(options = {}) {
     return await this.#readDocument(
       async (document) => await inspectWikiGraphArchive(document, {
@@ -2209,7 +2525,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
@@ -2230,9 +2546,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 (isSourceLocatorScopeUri(this.objectUri)) {
         return await listArchiveSourceLocators(document, this.objectUri, {
           ...options.cursor === void 0 ? {} : { cursor: options.cursor },
@@ -2245,6 +2590,53 @@ var WikiGraphArchiveHandle = class {
         ...chapters === void 0 ? {} : { chapters }
       });
     }, options);
+    if (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(
@@ -2433,7 +2825,7 @@ var WikiGraphArchiveHandle = class {
     return await this.#writeDocument(async (document) => {
       const chapterId = await resolveChapterPathReadonly(document, path);
       await assertChapterResetAllowed(
-        this.#location.archiveFile,
+        requireWikiGraphArchiveFile(this.#location),
         chapterId,
         stage
       );
@@ -2521,19 +2913,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 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
@@ -2553,25 +2956,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 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
@@ -2591,6 +3016,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(
@@ -2635,14 +3071,18 @@ var WikiGraphArchiveHandle = class {
     }, options);
   }
   async readCover(options = {}) {
-    const app = new WikiGraph2({});
-    return await this.#runtime.run(
-      async () => await app.openSession(
+    return await this.#runtime.run(async () => {
+      if (this.#location.archiveFile.kind === "directory") {
+        return await this.#readDocument(
+          async (document) => await document.readCover()
+        );
+      }
+      const app = new WikiGraph2({});
+      return await app.openSession(
         this.#location.archiveFile,
         async (archive) => await archive.readCover()
-      ),
-      options.signal
-    );
+      );
+    }, options.signal);
   }
   async replaceMetadata(objectPath, value, options = {}) {
     return await this.#writeDocument(async (document) => {
@@ -2683,9 +3123,11 @@ var WikiGraphArchiveHandle = class {
   }
   async #readDocument(operation, options = {}) {
     return await this.#runtime.run(
-      async () => await new WikiGraphArchiveFile2(this.#location.archiveFile).readDocument(
-        operation
-      ),
+      async () => this.#location.archiveFile.kind === "directory" ? await new WikiGraphDirectoryFile2(
+        this.#location.archiveFile
+      ).readDocument(operation) : await new WikiGraphArchiveFile2(
+        this.#location.archiveFile
+      ).readDocument(operation),
       options.signal
     );
   }
@@ -3074,7 +3516,7 @@ function parseProvider(value) {
 
 // src/continuations.ts
 import {
-  createContinuationCursor,
+  createContinuationCursor as createContinuationCursor2,
   findArchiveObjects as findArchiveObjects2,
   findWikiGraphLibraryArchiveMembers,
   findWikiGraphLibraryObjects,
@@ -3088,7 +3530,8 @@ import {
   listWikiGraphLibraryObjects,
   readContinuationCursor,
   resolveWikiGraphLibraryQueryTargetById,
-  WikiGraphArchiveFile as WikiGraphArchiveFile3
+  WikiGraphArchiveFile as WikiGraphArchiveFile3,
+  WikiGraphDirectoryFile as WikiGraphDirectoryFile3
 } from "wiki-graph-core";
 var WikiGraphContinuationManager = class {
   #runtime;
@@ -3104,7 +3547,7 @@ var WikiGraphContinuationManager = class {
   async create(context, cursor) {
     if (cursor === null || cursor === void 0) return null;
     return await this.#runtime.run(
-      async () => await createContinuationCursor(
+      async () => await createContinuationCursor2(
         createContinuationPayload(context, cursor)
       )
     );
@@ -3138,54 +3581,53 @@ async function continueArchiveCursor(cursor, limit) {
   const location = await resolveWikiGraphArchiveLocation(
     archiveTargetFromLogicalLocator(getCursorArchivePath(cursor))
   );
-  return await new WikiGraphArchiveFile3(location.archiveFile).readDocument(
-    async (document) => {
-      switch (cursor.kind) {
-        case "source-locators":
-          return await listArchiveSourceLocators2(document, cursor.targetUri, {
-            cursor: cursor.cursor,
-            limit
-          });
-        case "collection":
-          return await listArchiveCollection2(
-            document,
-            createCollectionOptions(cursor, limit)
-          );
-        case "search":
-          return await findArchiveObjects2(
-            document,
-            cursor.query ?? "",
-            await createFindOptions(cursor, limit)
-          );
-        case "evidence":
-          return await listArchiveEvidence2(document, cursor.targetUri, {
-            ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
-            cursor: cursor.cursor,
-            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 }
-          });
-        case "related":
-          return await listRelatedArchiveObjects2(document, cursor.targetUri, {
-            ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
-            cursor: cursor.cursor,
-            ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
-            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 }
-          });
-      }
+  const read = async (document) => {
+    switch (cursor.kind) {
+      case "source-locators":
+        return await listArchiveSourceLocators2(document, cursor.targetUri, {
+          cursor: cursor.cursor,
+          limit
+        });
+      case "collection":
+        return await listArchiveCollection2(
+          document,
+          createCollectionOptions(cursor, limit)
+        );
+      case "search":
+        return await findArchiveObjects2(
+          document,
+          cursor.query ?? "",
+          await createFindOptions(cursor, limit)
+        );
+      case "evidence":
+        return await listArchiveEvidence2(document, cursor.targetUri, {
+          ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
+          cursor: cursor.cursor,
+          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 }
+        });
+      case "related":
+        return await listRelatedArchiveObjects2(document, cursor.targetUri, {
+          ...cursor.chapters === null ? {} : { chapters: cursor.chapters },
+          cursor: cursor.cursor,
+          ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
+          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 }
+        });
     }
-  );
+  };
+  return location.archiveFile.kind === "directory" ? await new WikiGraphDirectoryFile3(location.archiveFile).readDocument(read) : await new WikiGraphArchiveFile3(location.archiveFile).readDocument(read);
 }
 async function continueLibraryCursor(cursor, limit) {
   const embeddingProvider = cursor.kind === "evidence" || cursor.kind === "related" ? await resolveCursorEmbeddingProvider(cursor) : void 0;
@@ -3297,7 +3739,7 @@ function getCursorArchivePath(cursor) {
 }
 async function persistResultCursor(cursor, result) {
   if (result.nextCursor === null) return result;
-  const nextCursor = await createContinuationCursor({
+  const nextCursor = await createContinuationCursor2({
     ...cursor,
     cursor: result.nextCursor
   });
@@ -4073,7 +4515,7 @@ var WikiGraphJobManager = class {
       return {
         job: await this.#backend.add({
           ...options,
-          archive: location.archiveFile
+          archive: requireWikiGraphArchiveFile(location)
         }),
         target: location.target
       };
@@ -4105,7 +4547,9 @@ var WikiGraphJobManager = class {
         ...options.activeOnly === void 0 ? {} : { activeOnly: options.activeOnly },
         ...options.all === void 0 ? {} : { all: options.all },
         ...options.archive === void 0 ? {} : {
-          archive: (await resolveWikiGraphArchiveLocation(options.archive)).archiveFile
+          archive: requireWikiGraphArchiveFile(
+            await resolveWikiGraphArchiveLocation(options.archive)
+          )
         }
       };
       const jobs = await this.#backend.list(normalized);
@@ -4130,7 +4574,7 @@ var WikiGraphJobManager = class {
               archiveJobs[0].archive
             );
             const chapters = await new WikiGraphArchiveFile6(
-              location.archiveFile
+              requireWikiGraphArchiveFile(location)
             ).readDocument(async (document) => await listChapters3(document));
             const chaptersById = new Map(
               chapters.map((chapter) => [chapter.chapterId, chapter])
@@ -4173,7 +4617,7 @@ var WikiGraphJobManager = class {
           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
+            requireWikiGraphArchiveFile(location)
           ).readDocument(async (document) => {
             const chapters = await listChapters3(document);
             const selected = await selectQueueChapters(
@@ -4217,7 +4661,7 @@ var WikiGraphJobManager = class {
                 chapter: candidate.chapter,
                 job: await this.#createHandle(
                   await this.#backend.add({
-                    archive: location.archiveFile,
+                    archive: requireWikiGraphArchiveFile(location),
                     boost: options.boost ?? false,
                     chapterId: candidate.chapter.chapterId,
                     ...llmJSON === void 0 ? {} : { llmJSON },
@@ -4248,7 +4692,7 @@ var WikiGraphJobManager = class {
       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
+        requireWikiGraphArchiveFile(location)
       ).readDocument(async (document) => {
         const chapters = await listChapters3(document);
         const selected = await selectQueueChapters(document, chapters, options);
@@ -4581,9 +5025,11 @@ import {
   assertWikiGraphLibrarySchemaCurrent,
   cleanWikiGraphLibraryIndex,
   clearWikiGraphLibraryMetadata,
+  continueWikiGraphLibraryObjectBucket,
   createWikiGraphLibrary,
   deleteWikiGraphLibraryMetadataKey,
   findWikiGraphLibraryObjects as findWikiGraphLibraryObjects2,
+  findWikiGraphLibraryObjectBuckets,
   findWikiGraphLibraryArchiveMembers as findWikiGraphLibraryArchiveMembers2,
   formatWikiGraphLibraryUri as formatWikiGraphLibraryUri2,
   getWikiGraphLibraryArchive,
@@ -4608,9 +5054,12 @@ import {
   replaceWikiGraphLibraryMetadata,
   resolveWikiGraphLibrary as resolveWikiGraphLibrary2,
   scanWikiGraphLibrary,
-  withWikiGraphLibraryLock
+  withWikiGraphLibraryLock,
+  writeWikgArchive as writeWikgArchive2
 } from "wiki-graph-core";
-import { mkdir as mkdir3 } from "fs/promises";
+import { mkdir as mkdir3, mkdtemp as mkdtemp2, rm as rm4 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join5 } from "path";
 async function resolveQueryEmbeddingProvider(queryMode) {
   if (queryMode === "fts") return void 0;
   const provider = await createConfiguredEmbeddingProvider();
@@ -4700,7 +5149,18 @@ var WikiGraphLibraryManager = class {
         async () => {
           throwIfAborted(options.signal);
           const archive = await getWikiGraphLibraryArchive(parsedTarget);
-          const file = requireReadableLibraryArchiveFile(archive);
+          const source = requireReadableLibraryArchiveFile(archive);
+          let temporaryDirectory;
+          const file = source.kind === "directory" ? await (async () => {
+            temporaryDirectory = await mkdtemp2(
+              join5(tmpdir2(), "wikigraph-library-read-")
+            );
+            const output = new NodeFile(
+              join5(temporaryDirectory, "archive.wikg")
+            );
+            await writeWikgArchive2(source, output);
+            return output;
+          })() : source;
           const reader = await file.openReader();
           let active = true;
           try {
@@ -4721,6 +5181,8 @@ var WikiGraphLibraryManager = class {
           } finally {
             active = false;
             await reader.close();
+            if (temporaryDirectory !== void 0)
+              await rm4(temporaryDirectory, { force: true, recursive: true });
           }
         },
         options.signal === void 0 ? {} : { signal: options.signal }
@@ -4815,7 +5277,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
       );
@@ -4828,9 +5290,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 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 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
       );
@@ -4843,22 +5366,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 listWikiGraphLibraryObjects2(
         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 listWikiGraphLibraryArchiveMembers2(
         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(
@@ -4874,7 +5428,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`.");
       }
@@ -4888,9 +5442,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`.");
       }
@@ -4904,6 +5469,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(
@@ -4968,7 +5544,7 @@ function toLibrarySnapshot(record) {
   };
 }
 function toArchiveSnapshot(record) {
-  const { file: _file, ...snapshot } = record;
+  const { file: _file, directory: _directory, ...snapshot } = record;
   return snapshot;
 }
 function toScanSnapshot(result) {
@@ -5001,12 +5577,12 @@ function requireReadableLibraryArchiveFile(archive) {
       `Wiki Graph library archive has a conflict and cannot be read: ${archive.uri}`
     );
   }
-  if (archive.file === void 0) {
+  if (archive.file === void 0 && archive.directory === void 0) {
     throw new Error(
       `Wiki Graph library archive is unavailable: ${archive.uri}`
     );
   }
-  return archive.file;
+  return archive.file ?? archive.directory;
 }
 var ARCHIVE_STREAM_CHUNK_SIZE = 64 * 1024;
 function createCallbackScopedArchiveStream(reader, isActive, signal) {
@@ -5234,6 +5810,11 @@ import {
   requireLocatedObjectUri
 } from "wiki-graph-core";
 export {
+  ArchiveCollectionPage,
+  ArchiveEvidencePage,
+  ArchiveFindPage,
+  ArchiveRelatedPage,
+  ArchiveSourceLocatorPage,
   DANGEROUS_RUNTIME_ENV_NAMES,
   DEFAULT_EXTRACTION_PROMPT,
   DEFAULT_GENERATION_JOB_CONCURRENCY,
@@ -5241,6 +5822,7 @@ export {
   DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT,
   LLMPaymentRequiredError,
   LOCAL_CONFIG_SECTIONS,
+  LibraryBucketPage,
   NodeDirectory,
   NodeFile,
   WIKI_GRAPH_URI_PREFIX,
@@ -5261,11 +5843,19 @@ export {
   buildSearchIndexEmbeddingProvider,
   buildWikiGraphLLMOptions,
   clearLocalConfigSection,
+  createArchiveCollectionPage,
+  createArchiveEvidencePage,
+  createArchiveFindPage,
+  createArchiveRelatedPage,
+  createArchiveSourceLocatorPage,
+  createCursor,
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
+  createLibraryBucketPage,
   createNodeTemplateEnvironment,
   createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
+  createPageCursor,
   createStageLLM,
   createWikiGraphSDK,
   deleteLocalConfigValue,
@@ -5293,6 +5883,8 @@ export {
   isWikiGraphJobUri,
   isWikiGraphLibraryUri,
   isWikiGraphUri,
+  iterateItems,
+  iteratePages,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,