okf-search-native 0.5.1 → 0.7.0

package/README.md

@@ -61,13 +61,41 @@ Use the path and line numbers to open the source, and the heading and snippet
 to display a preview. Results contain at most one hit per document, ordered by
 relevance. See the [complete result shape](https://github.com/robhowley/okf-search/blob/main/packages/okf-search-native/API.md#results).
 
-**Open once and reuse the handle.** Opening reads and indexes the collection
-into memory; every new `openOkf` call rebuilds it. The handle does not watch
-files, write changes to disk, or persist the index. Reopen to pick up filesystem
-changes.
+## Open and reuse an index
+
+Without options, `openOkf` reads and indexes the collection in memory. The
+handle does not watch files or write source files. Without a cache, call
+`openOkf` again to pick up source filesystem changes.
+
+To reuse a native snapshot across processes, pass a filesystem `cachePath`:
+
+```js
+import { openOkf } from "okf-search-native";
+
+const cachePath = "./.cache/knowledge.okf";
+const index = await openOkf("./knowledge", { cachePath });
+
+index.ingest({
+  path: "runbooks/new.md",
+  markdown: "---\ntype: runbook\n---\nNew material.\n",
+});
+await index.save(cachePath);
+```
+
+- **First open:** a missing cache is built from `root`; parent directories are
+  created, and the complete cache is published before `openOkf` resolves.
+- **Later open:** an existing cache is loaded without reading or requiring
+  `root`; saved document paths stay unchanged.
+- **Failures:** an existing directory, dangling link, unreadable, corrupt, or
+  incompatible cache destination rejects instead of silently rebuilding from
+  `root`. Damaged contents report `ERR_OKF_CACHE_INVALID`; unsupported cache
+  metadata reports `ERR_OKF_CACHE_INCOMPATIBLE`.
+- **No cache:** without `cachePath`, the handle stays in memory and creates no
+  cache artifacts. `cachePath` is a cache-file path, not a Markdown identity.
 
 `openOkf` recursively reads lowercase `.md` files, excluding files named exactly
-`index.md` or `log.md`.
+`index.md` or `log.md`. See the [persistence contract](https://github.com/robhowley/okf-search/blob/main/packages/okf-search-native/API.md#persistence)
+for writer exclusion, snapshot timing, and filesystem caveats.
 
 ## Already have Markdown strings?
 
@@ -130,6 +158,29 @@ Use relative `.md` paths, such as `runbooks/restart.md`. If preparation of a
 replacement fails, the existing document remains searchable.
 See [update results and path rules](https://github.com/robhowley/okf-search/blob/main/packages/okf-search-native/API.md#update-and-reuse-the-handle).
 
+## Save a snapshot
+
+`save(path)` explicitly writes the current handle state. It is available on
+handles from both `openOkf` and `createOkfSearch`:
+
+```js
+import { createOkfSearch } from "okf-search-native";
+
+const index = createOkfSearch([
+  { path: "notes/one.md", markdown: "---\ntype: note\n---\nOne.\n" },
+]);
+
+await index.save("./.cache/notes.okf");
+```
+
+`save` captures one consistent snapshot before returning its promise and
+resolves after atomic publication. Mutations made after capture require another
+save. Concurrent writers to one destination reject with
+`ERR_OKF_CACHE_BUSY`; independent handles are not merged. A failed save does
+not replace a previous complete cache or poison a healthy handle. See the
+[full persistence contract](https://github.com/robhowley/okf-search/blob/main/packages/okf-search-native/API.md#persistence)
+for locking, reader visibility, and filesystem caveats.
+
 ## Check documents and handle failures
 
 Documents with valid OKF metadata are **strict**. Some metadata problems make
@@ -172,6 +223,45 @@ console.log(index.listTypes());
 console.log(index.listDegradedDocuments());
 ```
 
+## Performance benchmarks
+
+Measured on 13,692 Markdown documents (59.57 MiB of source text), using the public
+`openOkf` and `search` APIs.
+
+### Default search options
+
+Fuzzy matching is disabled by default; final-term prefix matching remains enabled.
+
+| Metric | [okf-minisearch][benchmark-minisearch] | [okf-search-native][benchmark-native] |
+| --- | ---: | ---: |
+| Median `openOkf` time | 20.40 s | 1.57 s |
+| Warm query p50 | 10.45 ms | 1.38 ms |
+| Warm query p95 | 86.81 ms | 2.38 ms |
+| Warm query p99 | 95.64 ms | 2.45 ms |
+| Reported index storage¹ | 200.37 MiB | 80.75 MiB |
+| Median post-open RSS | 2,235 MiB | 527 MiB |
+
+### Fuzzy matching enabled
+
+The same queries and defaults, changing only the search call to:
+
+```ts
+index.search(query, { fuzzy: true });
+```
+
+| Metric | [okf-minisearch][benchmark-minisearch] | [okf-search-native][benchmark-native] |
+| --- | ---: | ---: |
+| Warm query p50 | 14.36 ms | 7.96 ms |
+| Warm query p95 | 87.36 ms | 14.12 ms |
+| Warm query p99 | 96.71 ms | 15.00 ms |
+
+¹ MiniSearch reports serialized JSON bytes; native reports in-memory Tantivy
+index-file bytes. These are different storage representations, not equivalent RAM
+measurements. Native storage can vary with background merges.
+
+[benchmark-minisearch]: https://github.com/robhowley/okf-search/blob/31d5da38d9502a85101c670729ca1a9646ad3a32/packages/okf-minisearch/package.json
+[benchmark-native]: https://github.com/robhowley/okf-search/blob/c187a764b10682919805714faf51d54bf53eb133/packages/okf-search-native/package.json
+
 ## Reference and development
 
 - [API reference](https://github.com/robhowley/okf-search/blob/main/packages/okf-search-native/API.md): options, return values, errors, and index statistics.

package/dist/index.cjs

@@ -55,6 +55,14 @@ function message(code, path, field) {
       return `Cannot parse OKF concept: ${subject}`;
     case "ERR_OKF_FIELD":
       return `Invalid OKF field: ${subject}`;
+    case "ERR_OKF_CACHE_INVALID":
+      return `Invalid OKF cache: ${subject}`;
+    case "ERR_OKF_CACHE_INCOMPATIBLE":
+      return `Incompatible OKF cache: ${subject}`;
+    case "ERR_OKF_WRITE":
+      return `Cannot write OKF cache: ${subject}`;
+    case "ERR_OKF_CACHE_BUSY":
+      return `OKF cache is busy: ${subject}`;
     case "ERR_OKF_INDEX_UNUSABLE":
       return path === "<index>" ? "Search index is permanently unusable and must be rebuilt" : `Search index failed while mutating ${path}; this OkfSearch handle is permanently unusable and must be rebuilt`;
     case "ERR_OKF_UNSUPPORTED":
@@ -69,10 +77,10 @@ function throwNativeError(error, path) {
   if (!NATIVE_MARKER.test(message2)) throw error;
   if (typeof error === "object" && error !== null && "code" in error && "path" in error) {
     const detail = error;
-    if (detail.code === "ERR_OKF_FIELD" || detail.code === "ERR_OKF_PARSE" || detail.code === "ERR_OKF_READ") {
+    if (isNativeStructuredCode(detail.code) && typeof detail.path === "string") {
       throw new OkfError(detail.code, detail.path, {
         ...detail.field === void 0 ? {} : { field: detail.field },
-        ...detail.cause === void 0 ? {} : { cause: new Error(String(detail.cause)) }
+        ...detail.cause === void 0 ? {} : { cause: new Error(detail.cause) }
       });
     }
   }
@@ -82,6 +90,9 @@ function throwNativeError(error, path) {
   const sanitized = message2.replace(NATIVE_MARKER, "").trim();
   throw INVALID_SEARCH_OPTIONS_MARKER.test(message2) ? new TypeError(sanitized) : new Error(sanitized || "Native OKF search failed");
 }
+function isNativeStructuredCode(code) {
+  return code === "ERR_OKF_READ" || code === "ERR_OKF_PARSE" || code === "ERR_OKF_FIELD" || code === "ERR_OKF_CACHE_INVALID" || code === "ERR_OKF_CACHE_INCOMPATIBLE" || code === "ERR_OKF_WRITE" || code === "ERR_OKF_CACHE_BUSY" || code === "ERR_OKF_INDEX_UNUSABLE";
+}
 function nativeMessage(error) {
   const message2 = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "message")?.value : void 0;
   return typeof message2 === "string" ? message2 : "";
@@ -111,6 +122,8 @@ function sanitizeSearchOptions(options = {}) {
   const asOf = validateAsOf(asOfValue);
   const limitValue = options.limit;
   const limit = validateLimit(limitValue);
+  const snippetLengthValue = options.snippetLength;
+  const snippetLength = validateSnippetLength(snippetLengthValue);
   const matchValue = options.match;
   const match = validateMatch(matchValue);
   const fieldsValue = options.fields;
@@ -125,6 +138,9 @@ function sanitizeSearchOptions(options = {}) {
   if (limitValue !== void 0) {
     native.limit = limit;
   }
+  if (snippetLength !== void 0) {
+    native.snippetLength = snippetLength;
+  }
   if (where !== void 0) {
     native.where = where;
   }
@@ -171,6 +187,17 @@ function validateLimit(value) {
   }
   return limit;
 }
+function validateSnippetLength(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(
+      "options.snippetLength must be a finite positive integer"
+    );
+  }
+  return value;
+}
 function validateMatch(value) {
   if (value !== void 0 && value !== "any" && value !== "all") {
     throw new TypeError(
@@ -368,18 +395,29 @@ function wrapNative(native) {
       throw unusableError;
     }
   };
+  const translateNativeFailure = (path, error) => {
+    if (nativeMessage(error).match(POISON_MARKER)) {
+      const nativePath = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "path")?.value : void 0;
+      const failurePath = typeof nativePath === "string" ? nativePath : path;
+      unusableError ??= new OkfError("ERR_OKF_INDEX_UNUSABLE", failurePath);
+      throw unusableError;
+    }
+    throwNativeError(error, path);
+  };
   const callNative = (path, call) => {
     assertUsable();
     try {
       return call();
     } catch (error) {
-      if (nativeMessage(error).match(POISON_MARKER)) {
-        const nativePath = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "path")?.value : void 0;
-        const failurePath = typeof nativePath === "string" ? nativePath : path;
-        unusableError ??= new OkfError("ERR_OKF_INDEX_UNUSABLE", failurePath);
-        throw unusableError;
-      }
-      throwNativeError(error, path);
+      return translateNativeFailure(path, error);
+    }
+  };
+  const callNativeAsync = async (path, call) => {
+    assertUsable();
+    try {
+      return await call();
+    } catch (error) {
+      return translateNativeFailure(path, error);
     }
   };
   return {
@@ -387,6 +425,9 @@ function wrapNative(native) {
       assertUsable();
       return copyIndexStats(callNative("<index>", () => native.indexStats()));
     },
+    async save(path) {
+      await callNativeAsync("<index>", () => native.save(path));
+    },
     ingest(input) {
       callNative("<index>", () => native.assertUsable());
       const snapshot = snapshotInput(input);
@@ -491,9 +532,10 @@ function compare(left, right) {
 
 // packages/okf-search-native/src/open-okf.ts
 var import_native2 = require("../native.cjs");
-async function openOkf(root) {
+async function openOkf(root, options) {
+  const cachePath = options?.cachePath;
   try {
-    return wrapNative(await import_native2.NativeOkfSearch.openRaw(root));
+    return wrapNative(await import_native2.NativeOkfSearch.openRaw(root, cachePath));
   } catch (error) {
     throwNativeError(error, "<index>");
   }

package/dist/index.d.cts

@@ -63,8 +63,11 @@ interface OkfDocumentInput {
     path: string;
     markdown: string;
 }
+interface OkfOpenOptions {
+    readonly cachePath?: string;
+}
 type OkfDiagnosticCode = "ERR_OKF_PARSE" | "ERR_OKF_FIELD";
-type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
+type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_CACHE_INVALID" | "ERR_OKF_CACHE_INCOMPATIBLE" | "ERR_OKF_WRITE" | "ERR_OKF_CACHE_BUSY" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
 interface OkfDiagnostic {
     code: OkfDiagnosticCode;
     path: string;
@@ -134,6 +137,8 @@ type OkfIngestResult = {
 type OkfSearchField = "resource" | "title" | "heading" | "description" | "tags" | "type" | "sources" | "body";
 interface OkfSearchOptions {
     limit?: number;
+    /** Maximum section-text window in UTF-16 code units, like String.length. */
+    snippetLength?: number;
     where?: {
         types?: readonly string[];
         tagsAny?: readonly string[];
@@ -163,6 +168,7 @@ interface OkfSearchHit {
 }
 interface OkfSearch {
     indexStats(): OkfIndexStats;
+    save(path: string): Promise<void>;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -184,9 +190,9 @@ declare class OkfError extends Error {
     constructor(code: OkfErrorCode, path: string, options?: OkfErrorOptions);
 }
 
-declare function openOkf(root: string): Promise<OkfSearch>;
+declare function openOkf(root: string, options?: OkfOpenOptions): Promise<OkfSearch>;
 
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfOpenOptions, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.d.mts

@@ -63,8 +63,11 @@ interface OkfDocumentInput {
     path: string;
     markdown: string;
 }
+interface OkfOpenOptions {
+    readonly cachePath?: string;
+}
 type OkfDiagnosticCode = "ERR_OKF_PARSE" | "ERR_OKF_FIELD";
-type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
+type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_CACHE_INVALID" | "ERR_OKF_CACHE_INCOMPATIBLE" | "ERR_OKF_WRITE" | "ERR_OKF_CACHE_BUSY" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
 interface OkfDiagnostic {
     code: OkfDiagnosticCode;
     path: string;
@@ -134,6 +137,8 @@ type OkfIngestResult = {
 type OkfSearchField = "resource" | "title" | "heading" | "description" | "tags" | "type" | "sources" | "body";
 interface OkfSearchOptions {
     limit?: number;
+    /** Maximum section-text window in UTF-16 code units, like String.length. */
+    snippetLength?: number;
     where?: {
         types?: readonly string[];
         tagsAny?: readonly string[];
@@ -163,6 +168,7 @@ interface OkfSearchHit {
 }
 interface OkfSearch {
     indexStats(): OkfIndexStats;
+    save(path: string): Promise<void>;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -184,9 +190,9 @@ declare class OkfError extends Error {
     constructor(code: OkfErrorCode, path: string, options?: OkfErrorOptions);
 }
 
-declare function openOkf(root: string): Promise<OkfSearch>;
+declare function openOkf(root: string, options?: OkfOpenOptions): Promise<OkfSearch>;
 
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfOpenOptions, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.d.ts

@@ -63,8 +63,11 @@ interface OkfDocumentInput {
     path: string;
     markdown: string;
 }
+interface OkfOpenOptions {
+    readonly cachePath?: string;
+}
 type OkfDiagnosticCode = "ERR_OKF_PARSE" | "ERR_OKF_FIELD";
-type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
+type OkfErrorCode = "ERR_OKF_READ" | "ERR_OKF_PARSE" | "ERR_OKF_FIELD" | "ERR_OKF_CACHE_INVALID" | "ERR_OKF_CACHE_INCOMPATIBLE" | "ERR_OKF_WRITE" | "ERR_OKF_CACHE_BUSY" | "ERR_OKF_INDEX_UNUSABLE" | "ERR_OKF_UNSUPPORTED";
 interface OkfDiagnostic {
     code: OkfDiagnosticCode;
     path: string;
@@ -134,6 +137,8 @@ type OkfIngestResult = {
 type OkfSearchField = "resource" | "title" | "heading" | "description" | "tags" | "type" | "sources" | "body";
 interface OkfSearchOptions {
     limit?: number;
+    /** Maximum section-text window in UTF-16 code units, like String.length. */
+    snippetLength?: number;
     where?: {
         types?: readonly string[];
         tagsAny?: readonly string[];
@@ -163,6 +168,7 @@ interface OkfSearchHit {
 }
 interface OkfSearch {
     indexStats(): OkfIndexStats;
+    save(path: string): Promise<void>;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -184,9 +190,9 @@ declare class OkfError extends Error {
     constructor(code: OkfErrorCode, path: string, options?: OkfErrorOptions);
 }
 
-declare function openOkf(root: string): Promise<OkfSearch>;
+declare function openOkf(root: string, options?: OkfOpenOptions): Promise<OkfSearch>;
 
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfOpenOptions, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.mjs

@@ -27,6 +27,14 @@ function message(code, path, field) {
       return `Cannot parse OKF concept: ${subject}`;
     case "ERR_OKF_FIELD":
       return `Invalid OKF field: ${subject}`;
+    case "ERR_OKF_CACHE_INVALID":
+      return `Invalid OKF cache: ${subject}`;
+    case "ERR_OKF_CACHE_INCOMPATIBLE":
+      return `Incompatible OKF cache: ${subject}`;
+    case "ERR_OKF_WRITE":
+      return `Cannot write OKF cache: ${subject}`;
+    case "ERR_OKF_CACHE_BUSY":
+      return `OKF cache is busy: ${subject}`;
     case "ERR_OKF_INDEX_UNUSABLE":
       return path === "<index>" ? "Search index is permanently unusable and must be rebuilt" : `Search index failed while mutating ${path}; this OkfSearch handle is permanently unusable and must be rebuilt`;
     case "ERR_OKF_UNSUPPORTED":
@@ -41,10 +49,10 @@ function throwNativeError(error, path) {
   if (!NATIVE_MARKER.test(message2)) throw error;
   if (typeof error === "object" && error !== null && "code" in error && "path" in error) {
     const detail = error;
-    if (detail.code === "ERR_OKF_FIELD" || detail.code === "ERR_OKF_PARSE" || detail.code === "ERR_OKF_READ") {
+    if (isNativeStructuredCode(detail.code) && typeof detail.path === "string") {
       throw new OkfError(detail.code, detail.path, {
         ...detail.field === void 0 ? {} : { field: detail.field },
-        ...detail.cause === void 0 ? {} : { cause: new Error(String(detail.cause)) }
+        ...detail.cause === void 0 ? {} : { cause: new Error(detail.cause) }
       });
     }
   }
@@ -54,6 +62,9 @@ function throwNativeError(error, path) {
   const sanitized = message2.replace(NATIVE_MARKER, "").trim();
   throw INVALID_SEARCH_OPTIONS_MARKER.test(message2) ? new TypeError(sanitized) : new Error(sanitized || "Native OKF search failed");
 }
+function isNativeStructuredCode(code) {
+  return code === "ERR_OKF_READ" || code === "ERR_OKF_PARSE" || code === "ERR_OKF_FIELD" || code === "ERR_OKF_CACHE_INVALID" || code === "ERR_OKF_CACHE_INCOMPATIBLE" || code === "ERR_OKF_WRITE" || code === "ERR_OKF_CACHE_BUSY" || code === "ERR_OKF_INDEX_UNUSABLE";
+}
 function nativeMessage(error) {
   const message2 = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "message")?.value : void 0;
   return typeof message2 === "string" ? message2 : "";
@@ -83,6 +94,8 @@ function sanitizeSearchOptions(options = {}) {
   const asOf = validateAsOf(asOfValue);
   const limitValue = options.limit;
   const limit = validateLimit(limitValue);
+  const snippetLengthValue = options.snippetLength;
+  const snippetLength = validateSnippetLength(snippetLengthValue);
   const matchValue = options.match;
   const match = validateMatch(matchValue);
   const fieldsValue = options.fields;
@@ -97,6 +110,9 @@ function sanitizeSearchOptions(options = {}) {
   if (limitValue !== void 0) {
     native.limit = limit;
   }
+  if (snippetLength !== void 0) {
+    native.snippetLength = snippetLength;
+  }
   if (where !== void 0) {
     native.where = where;
   }
@@ -143,6 +159,17 @@ function validateLimit(value) {
   }
   return limit;
 }
+function validateSnippetLength(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(
+      "options.snippetLength must be a finite positive integer"
+    );
+  }
+  return value;
+}
 function validateMatch(value) {
   if (value !== void 0 && value !== "any" && value !== "all") {
     throw new TypeError(
@@ -340,18 +367,29 @@ function wrapNative(native) {
       throw unusableError;
     }
   };
+  const translateNativeFailure = (path, error) => {
+    if (nativeMessage(error).match(POISON_MARKER)) {
+      const nativePath = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "path")?.value : void 0;
+      const failurePath = typeof nativePath === "string" ? nativePath : path;
+      unusableError ??= new OkfError("ERR_OKF_INDEX_UNUSABLE", failurePath);
+      throw unusableError;
+    }
+    throwNativeError(error, path);
+  };
   const callNative = (path, call) => {
     assertUsable();
     try {
       return call();
     } catch (error) {
-      if (nativeMessage(error).match(POISON_MARKER)) {
-        const nativePath = error instanceof Error ? Object.getOwnPropertyDescriptor(error, "path")?.value : void 0;
-        const failurePath = typeof nativePath === "string" ? nativePath : path;
-        unusableError ??= new OkfError("ERR_OKF_INDEX_UNUSABLE", failurePath);
-        throw unusableError;
-      }
-      throwNativeError(error, path);
+      return translateNativeFailure(path, error);
+    }
+  };
+  const callNativeAsync = async (path, call) => {
+    assertUsable();
+    try {
+      return await call();
+    } catch (error) {
+      return translateNativeFailure(path, error);
     }
   };
   return {
@@ -359,6 +397,9 @@ function wrapNative(native) {
       assertUsable();
       return copyIndexStats(callNative("<index>", () => native.indexStats()));
     },
+    async save(path) {
+      await callNativeAsync("<index>", () => native.save(path));
+    },
     ingest(input) {
       callNative("<index>", () => native.assertUsable());
       const snapshot = snapshotInput(input);
@@ -463,9 +504,10 @@ function compare(left, right) {
 
 // packages/okf-search-native/src/open-okf.ts
 import { NativeOkfSearch as NativeOkfSearch2 } from "../native.cjs";
-async function openOkf(root) {
+async function openOkf(root, options) {
+  const cachePath = options?.cachePath;
   try {
-    return wrapNative(await NativeOkfSearch2.openRaw(root));
+    return wrapNative(await NativeOkfSearch2.openRaw(root, cachePath));
   } catch (error) {
     throwNativeError(error, "<index>");
   }

package/native.cjs

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-android-arm64')
         const bindingPackageVersion = require('okf-search-native-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-android-arm-eabi')
         const bindingPackageVersion = require('okf-search-native-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-win32-x64-gnu')
         const bindingPackageVersion = require('okf-search-native-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-win32-x64-msvc')
         const bindingPackageVersion = require('okf-search-native-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-win32-ia32-msvc')
         const bindingPackageVersion = require('okf-search-native-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-win32-arm64-msvc')
         const bindingPackageVersion = require('okf-search-native-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('okf-search-native-darwin-universal')
       const bindingPackageVersion = require('okf-search-native-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-darwin-x64')
         const bindingPackageVersion = require('okf-search-native-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-darwin-arm64')
         const bindingPackageVersion = require('okf-search-native-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-freebsd-x64')
         const bindingPackageVersion = require('okf-search-native-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-freebsd-arm64')
         const bindingPackageVersion = require('okf-search-native-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-x64-musl')
           const bindingPackageVersion = require('okf-search-native-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-x64-gnu')
           const bindingPackageVersion = require('okf-search-native-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-arm64-musl')
           const bindingPackageVersion = require('okf-search-native-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-arm64-gnu')
           const bindingPackageVersion = require('okf-search-native-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-arm-musleabihf')
           const bindingPackageVersion = require('okf-search-native-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-arm-gnueabihf')
           const bindingPackageVersion = require('okf-search-native-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-loong64-musl')
           const bindingPackageVersion = require('okf-search-native-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-loong64-gnu')
           const bindingPackageVersion = require('okf-search-native-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-riscv64-musl')
           const bindingPackageVersion = require('okf-search-native-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('okf-search-native-linux-riscv64-gnu')
           const bindingPackageVersion = require('okf-search-native-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-linux-ppc64-gnu')
         const bindingPackageVersion = require('okf-search-native-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-linux-s390x-gnu')
         const bindingPackageVersion = require('okf-search-native-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-openharmony-arm64')
         const bindingPackageVersion = require('okf-search-native-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-openharmony-x64')
         const bindingPackageVersion = require('okf-search-native-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('okf-search-native-openharmony-arm')
         const bindingPackageVersion = require('okf-search-native-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.6.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -648,8 +648,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('okf-search-native-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.4.0') {
-            throw new Error(`WASI binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.6.0') {
+            throw new Error(`WASI binding package version mismatch, expected 0.6.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('okf-search-native-wasm32-wasi')

package/native.d.cts

@@ -17,7 +17,8 @@ export declare class NativeOkfSearch {
    */
   autoSuggest(query: string, options?: SearchOptions | undefined | null): Array<Suggestion>
   static validateRaw(input: object): unknown
-  static openRaw(root: string): Promise<NativeOkfSearch>
+  static openRaw(root: string, cachePath?: string | undefined | null): Promise<NativeOkfSearch>
+  save(path: string): Promise<void>
   static fromRaw(inputs: Array<object>): NativeOkfSearch
   assertUsable(): void
   ingestRaw(input: object): unknown
@@ -133,6 +134,7 @@ export interface SearchHit {
 
 export interface SearchOptions {
   limit?: number
+  snippetLength?: number
   where?: SearchWhere
   asOf?: Date
   match?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okf-search-native",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Search Open Knowledge Format collections at native speed with a lean Rust and Tantivy engine.",
   "keywords": [
     "open-knowledge-format",
@@ -77,7 +77,7 @@
     "test:rust": "cargo test --locked",
     "test:prepare-bundle": "node ../../scripts/check-private-bundling.mjs native",
     "typecheck": "pnpm run test:types",
-    "test": "pnpm run test:prepare-bundle && pnpm run test:types && pnpm run test:package-api && vitest run tests/directory.test.ts tests/lifecycle.test.ts tests/raw-boundary.test.ts tests/root-contract.test.ts tests/search-options.test.ts --no-file-parallelism && pnpm run test:rust",
+    "test": "pnpm run test:prepare-bundle && pnpm run test:types && pnpm run test:package-api && vitest run tests/directory.test.ts tests/lifecycle.test.ts tests/persistence.test.ts tests/raw-boundary.test.ts tests/root-contract.test.ts tests/search-options.test.ts --no-file-parallelism && pnpm run test:rust",
     "verify:release-artifacts": "node scripts/verify-release-artifacts.mjs"
   }
 }