wiki-graph-sdk 0.8.3 → 0.9.0

package/README.md

@@ -78,6 +78,11 @@ Job event subscriptions observe durable work without coupling observation to
 cancellation. Call `job.cancel()` explicitly to cancel a job; unsubscribing
 only stops the current listener.
 
+`libraries.searchBuckets()` projects one shared search session into typed,
+independently paginated buckets. Continue one bucket with
+`libraries.continueSearchBucket()`; sibling cursors remain unchanged. The
+existing `libraries.search()` API keeps its sequential single-cursor result.
+
 Services that receive chapter job artifacts as files can apply an ordered,
 lazy sequence through the Node delivery boundary without importing Core:
 

package/dist/archives.cjs

@@ -1273,6 +1273,9 @@ function resolveWikiGraphRuntimePath(path) {
 var import_promises3 = require("fs/promises");
 var import_path3 = require("path");
 var import_wiki_graph_core2 = require("wiki-graph-core");
+function requireWikiGraphArchiveFile(location) {
+  return location.archiveFile;
+}
 var WikiGraphArchiveOwnershipError = class extends Error {
   code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
   constructor(message) {
@@ -1389,11 +1392,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)
       });
     }
   }
@@ -1879,13 +1883,25 @@ function formatLocatedChapterUri(archiveUri, chapter) {
 var import_wiki_graph_core6 = require("wiki-graph-core");
 async function writeWikiGraphArchiveLocation(location, operation, options = {}) {
   const cacheOnly = options.searchIndexWritebackPolicy === "cache";
-  const write = async (archiveFile = location.archiveFile) => await new import_wiki_graph_core6.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 import_wiki_graph_core6.WikiGraphDirectoryFile(archiveFile).write(
+        operation,
+        writeOptions
+      );
+    }
+    return await new import_wiki_graph_core6.WikiGraphArchiveFile(archiveFile).write(
+      operation,
+      writeOptions
+    );
+  };
   if (location.libraryArchiveTarget === void 0 || cacheOnly || options.refreshLibraryIndex === false) {
     return await write();
   }
@@ -1900,6 +1916,236 @@ 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;
+    }
+  });
+}
+
+// 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
+    })
+  );
+}
+
 // src/archive/archive.ts
 var WikiGraphArchiveExistsError = class extends Error {
   code = "WIKI_GRAPH_ARCHIVE_EXISTS";
@@ -1987,6 +2233,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, {
@@ -2001,7 +2255,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
@@ -2022,9 +2276,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 },
@@ -2037,6 +2320,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(
@@ -2225,7 +2555,7 @@ var WikiGraphArchiveHandle = class {
     return await this.#writeDocument(async (document) => {
       const chapterId = await (0, import_wiki_graph_core7.resolveChapterPathReadonly)(document, path);
       await assertChapterResetAllowed(
-        this.#location.archiveFile,
+        requireWikiGraphArchiveFile(this.#location),
         chapterId,
         stage
       );
@@ -2313,19 +2643,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
@@ -2345,25 +2686,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
@@ -2383,6 +2746,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(
@@ -2427,14 +2801,18 @@ var WikiGraphArchiveHandle = class {
     }, options);
   }
   async readCover(options = {}) {
-    const app = new import_wiki_graph_core7.WikiGraph({});
-    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 import_wiki_graph_core7.WikiGraph({});
+      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) => {
@@ -2475,9 +2853,11 @@ var WikiGraphArchiveHandle = class {
   }
   async #readDocument(operation, options = {}) {
     return await this.#runtime.run(
-      async () => await new import_wiki_graph_core7.WikiGraphArchiveFile(this.#location.archiveFile).readDocument(
-        operation
-      ),
+      async () => this.#location.archiveFile.kind === "directory" ? await new import_wiki_graph_core7.WikiGraphDirectoryFile(
+        this.#location.archiveFile
+      ).readDocument(operation) : await new import_wiki_graph_core7.WikiGraphArchiveFile(
+        this.#location.archiveFile
+      ).readDocument(operation),
       options.signal
     );
   }