@delali/narsil 0.2.4-next.51 → 0.2.4-next.54

package/dist/chunk-Y3L5MDRV.mjs

@@ -0,0 +1,96 @@
+import { performance } from 'perf_hooks';
+import { getHeapStatistics, setFlagsFromString } from 'v8';
+import { runInNewContext } from 'vm';
+
+// src/runtime/idle-heap-cleanup.ts
+
+// src/runtime/constants.ts
+var IDLE_HEAP_CLEANUP_CHECK_MS = 1e3;
+var IDLE_HEAP_CLEANUP_QUIET_CHECKS = 2;
+var IDLE_HEAP_CLEANUP_MAX_UTILISATION = 0.1;
+var IDLE_HEAP_CLEANUP_MAX_GROWTH_BYTES = 4 * 1024 * 1024;
+var IDLE_HEAP_CLEANUP_MIN_RECLAIMABLE_BYTES = 64 * 1024 * 1024;
+
+// src/runtime/idle-heap-cleaner.ts
+function createIdleHeapCleaner(deps) {
+  let quietChecks = 0;
+  let liveBytesAfterLastCleanup = 0;
+  let heldBytesAtLastCheck = Number.POSITIVE_INFINITY;
+  return {
+    check() {
+      const busy = deps.utilisationSinceLastCheck() > IDLE_HEAP_CLEANUP_MAX_UTILISATION;
+      const before = deps.readHeap();
+      if (before === null) return false;
+      const heapGrew = before.heldBytes > heldBytesAtLastCheck + IDLE_HEAP_CLEANUP_MAX_GROWTH_BYTES;
+      heldBytesAtLastCheck = before.heldBytes;
+      if (busy || heapGrew) {
+        quietChecks = 0;
+        return false;
+      }
+      quietChecks += 1;
+      if (quietChecks < IDLE_HEAP_CLEANUP_QUIET_CHECKS) return false;
+      if (before.heldBytes - liveBytesAfterLastCleanup < IDLE_HEAP_CLEANUP_MIN_RECLAIMABLE_BYTES) return false;
+      if (!deps.collectAndReturnPages()) return false;
+      const after = deps.readHeap();
+      liveBytesAfterLastCleanup = after?.liveBytes ?? before.liveBytes;
+      heldBytesAtLastCheck = after?.heldBytes ?? before.heldBytes;
+      quietChecks = 0;
+      return true;
+    }
+  };
+}
+
+// src/runtime/idle-heap-cleanup.ts
+var collectorOfThisThread = null;
+function acquireCollector() {
+  if (collectorOfThisThread !== null) return collectorOfThisThread;
+  try {
+    setFlagsFromString("--expose-gc");
+    const collect = runInNewContext("gc");
+    setFlagsFromString("--no-expose-gc");
+    if (typeof collect !== "function") return null;
+    collectorOfThisThread = collect;
+    return collectorOfThisThread;
+  } catch {
+    return null;
+  }
+}
+function collectAndReturnPages() {
+  const collect = acquireCollector();
+  if (collect === null) return false;
+  try {
+    collect({ type: "major", execution: "sync", flavor: "last-resort" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readHeap() {
+  try {
+    const stats = getHeapStatistics();
+    return { heldBytes: stats.total_physical_size, liveBytes: stats.used_heap_size };
+  } catch {
+    return null;
+  }
+}
+function startIdleHeapCleanup() {
+  if (typeof performance.eventLoopUtilization !== "function") return () => void 0;
+  let lastReading = performance.eventLoopUtilization();
+  const cleaner = createIdleHeapCleaner({
+    utilisationSinceLastCheck() {
+      const reading = performance.eventLoopUtilization();
+      const { utilization } = performance.eventLoopUtilization(reading, lastReading);
+      lastReading = reading;
+      return utilization;
+    },
+    readHeap,
+    collectAndReturnPages
+  });
+  const timer = setInterval(() => {
+    cleaner.check();
+  }, IDLE_HEAP_CLEANUP_CHECK_MS);
+  timer.unref();
+  return () => clearInterval(timer);
+}
+
+export { startIdleHeapCleanup };

package/dist/chunk-ZJ4CSAB2.mjs

@@ -0,0 +1,13 @@
+// src/vector/osq/constants.ts
+var OSQ_GRID = { 1: 0.798, 2: 1.493, 4: 2.514, 8: 3.922 };
+var OSQ_STEPS = { 1: 1, 2: 3, 4: 15, 8: 255 };
+var OSQ_QUERY_BITS = { 1: 4, 2: 4, 4: 4, 8: 8 };
+var OSQ_LAMBDA = 0.1;
+var OSQ_REFINE_ROUNDS = 5;
+var OSQ_REFINE_TOLERANCE = 1e-8;
+var DEFAULT_OVERSAMPLE_BY_BITS = { 1: 3, 2: 3, 4: 2, 8: 2 };
+var DEFAULT_OSQ4_NARROW_OVERSAMPLE = 5;
+var OSQ4_NARROW_DIMENSION_LIMIT = 1024;
+var MIN_OVERSAMPLE = 1;
+
+export { DEFAULT_OSQ4_NARROW_OVERSAMPLE, DEFAULT_OVERSAMPLE_BY_BITS, MIN_OVERSAMPLE, OSQ4_NARROW_DIMENSION_LIMIT, OSQ_GRID, OSQ_LAMBDA, OSQ_QUERY_BITS, OSQ_REFINE_ROUNDS, OSQ_REFINE_TOLERANCE, OSQ_STEPS };

package/dist/{client-B_X6_AbT.d.ts → client-CQUqt9Ir.d.ts}

@@ -1,6 +1,6 @@
-import { P as PartitionConfig, A as AnyDocument, b as InsertOptions, W as WriteOptions } from './schema-BqRx9t4E.js';
-import { V as VectorMaintenanceResult, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './memory-Bzd5xcEW.js';
-import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-DT7L1p6w.js';
+import { P as PartitionConfig, A as AnyDocument, a as InsertOptions, W as WriteOptions } from './schema-mLpXZBEh.js';
+import { V as VectorMaintenanceResult, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, j as SuggestParams, k as SuggestResult } from './memory-xrXOZMbw.js';
+import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-Df73Tjgq.js';
 
 /**
  * This is the `fetch` implementation the client sends every request through.
@@ -596,9 +596,11 @@ interface SearchOperations {
      * this request.
      * @returns The result holds the hits, the total match count, and whatever
      * else the query asked for.
-     * @throws A `NarsilError` with `SEARCH_RESULT_WINDOW_EXCEEDED` when `offset`
+     * @throws A `NarsilError` with `SEARCH_RESULT_WINDOW_EXCEEDED` where `offset`
      * plus `limit` passes the server's result window, which the cursor pages
      * beyond.
+     * @throws A `NarsilError` with `INVALID_REQUEST` where `limit` alone passes
+     * `limits.maxFetchDocuments`, which the server checks before the window.
      */
     query<T = AnyDocument>(indexName: string, params: QueryParams, options?: RequestOptions): Promise<QueryResult<T>>;
     /**
@@ -644,6 +646,13 @@ interface ServerVersion {
     gitSha: string | null;
     /** This is true when the working tree held uncommitted changes at build time. */
     dirty: boolean;
+    /**
+     * The server thread that answered searches vector graphs through this path.
+     * `native` is the native search core in C, and `wasm` is WebAssembly. Both
+     * paths return the same results. A server that predates this field leaves it
+     * out.
+     */
+    vectorSearch?: 'native' | 'wasm';
 }
 /**
  * These methods ask a server what it is and what it serves, before you ask it

package/dist/client.d.ts

@@ -1,10 +1,10 @@
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './memory-Bzd5xcEW.js';
-export { A as ASYNC_IMPORT_CAPABILITY, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, R as REBUILD_ANALYSIS_CAPABILITY, S as SERVER_CAPABILITIES, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './capabilities-BWm4IITU.js';
-export { C as CapabilitiesResponse, a as CreateIndexEmbedding, H as HttpIndexConfig, I as ImportError, b as ImportResult, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, d as TaskProgress, e as TaskRecord, f as TaskStatus, g as TaskType } from './tasks-DT7L1p6w.js';
-export { A as AdminOperations, B as BulkOperations, D as DocumentOperations, F as FetchFunction, I as ImportSource, a as IndexOperations, N as NarsilClient, b as NarsilClientOptions, P as PutResult, R as RequestOptions, S as SearchOperations, c as ServerOperations, d as ServerVersion, T as TaskOperations, W as WaitForTaskOptions, e as createNarsilClient } from './client-B_X6_AbT.js';
-import './schema-BqRx9t4E.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-xrXOZMbw.js';
+export { A as ASYNC_IMPORT_CAPABILITY, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, R as REBUILD_ANALYSIS_CAPABILITY, S as SERVER_CAPABILITIES, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './capabilities-DlYw0Ov0.js';
+export { C as CapabilitiesResponse, a as CreateIndexEmbedding, H as HttpIndexConfig, I as ImportError, b as ImportResult, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, d as TaskProgress, e as TaskRecord, f as TaskStatus, g as TaskType } from './tasks-Df73Tjgq.js';
+export { A as AdminOperations, B as BulkOperations, D as DocumentOperations, F as FetchFunction, I as ImportSource, a as IndexOperations, N as NarsilClient, b as NarsilClientOptions, P as PutResult, R as RequestOptions, S as SearchOperations, c as ServerOperations, d as ServerVersion, T as TaskOperations, W as WaitForTaskOptions, e as createNarsilClient } from './client-CQUqt9Ir.js';
+import './schema-mLpXZBEh.js';
 import './adapters-79OIa4xm.js';
-import './config-Czh2YNDi.js';
-import './config-OON7IJ_B.js';
-import './types-DXPxaXPO.js';
+import './config-CNas6wJH.js';
+import './config-bXxnJrQc.js';
+import './types-BTIVO8DI.js';
 import './types-D5OwhtsQ.js';

package/dist/client.mjs

@@ -1,4 +1,5 @@
 // src/errors.ts
+var NARSIL_ERROR_MARKER = /* @__PURE__ */ Symbol.for("@delali/narsil.NarsilError");
 var ErrorCodes = {
   SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE",
   SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED",
@@ -16,6 +17,7 @@ var ErrorCodes = {
   WORKER_CRASHED: "WORKER_CRASHED",
   WORKER_BUSY: "WORKER_BUSY",
   WORKER_TIMEOUT: "WORKER_TIMEOUT",
+  WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED",
   PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED",
   PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED",
   PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED",
@@ -135,8 +137,12 @@ var NarsilError = class extends Error {
     this.name = "NarsilError";
     this.code = code;
     this.details = details ?? {};
+    Object.defineProperty(this, NARSIL_ERROR_MARKER, { value: true });
   }
 };
+function isNarsilError(value) {
+  return typeof value === "object" && value !== null && NARSIL_ERROR_MARKER in value;
+}
 function describeError(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -188,7 +194,7 @@ function isRecord(value) {
 }
 function malformed(path, expected) {
   return new NarsilError(ClientErrorCodes.CLIENT_INVALID_RESPONSE, `The answer from ${path} holds no ${expected}`, {
-    url: path
+    route: path
   });
 }
 function readArray(payload, key, path) {
@@ -535,10 +541,10 @@ function errorFromBody(status, payload, url) {
   const details = isRecord2(envelope.details) ? envelope.details : {};
   return new NarsilError(envelope.code, envelope.message, { ...details, status });
 }
-function isAbsoluteUrl(value) {
+function isHttpUrl(value) {
   try {
-    new URL(value);
-    return true;
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
   } catch {
     return false;
   }
@@ -548,14 +554,14 @@ function normaliseBase(url) {
   if (trimmed.length === 0) {
     throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'The client needs a server address, and "url" is empty');
   }
-  if (!trimmed.startsWith("/") && !isAbsoluteUrl(trimmed)) {
+  if (!trimmed.startsWith("/") && !isHttpUrl(trimmed)) {
     throw new NarsilError(
       ErrorCodes.CONFIG_INVALID,
-      `The client cannot read "${trimmed}" as a server address; pass an absolute URL or a path starting with "/"`,
+      `The client cannot read "${trimmed}" as a server address; pass an http or https URL, or a path starting with "/" that a browser resolves against the page`,
       { url: trimmed }
     );
   }
-  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+  return trimmed.replace(/\/+$/, "");
 }
 function withQuery(path, query) {
   if (query === void 0) return path;
@@ -596,7 +602,7 @@ function createTransport(options) {
       const response = await send(url, init);
       const wantsBytes = spec.binaryAnswer === true && response.ok;
       const answer = await readAnswer(response, resolveResponseCeiling(spec), wantsBytes);
-      return { status: response.status, ...answer };
+      return { status: response.status, url, ...answer };
     } catch (err) {
       if (err instanceof ResponseTooLargeError) {
         throw invalidResponse(`The server at ${url} answered more than this client reads: ${err.message}`, {
@@ -634,10 +640,10 @@ function createTransport(options) {
     }
   }
   async function json(spec) {
-    const { status, text } = await exchange(spec);
-    const payload = parse(status, text, spec.path);
+    const { status, text, url } = await exchange(spec);
+    const payload = parse(status, text, url);
     if (status >= 200 && status < 300) return payload;
-    throw errorFromBody(status, payload, spec.path);
+    throw errorFromBody(status, payload, url);
   }
   return {
     json,
@@ -650,9 +656,9 @@ function createTransport(options) {
       }
     },
     async binary(spec) {
-      const { status, text, bytes } = await exchange(spec);
+      const { status, text, bytes, url } = await exchange(spec);
       if (bytes !== null) return bytes;
-      throw errorFromBody(status, parse(status, text, spec.path), spec.path);
+      throw errorFromBody(status, parse(status, text, url), url);
     },
     async probe(spec) {
       const { status } = await exchange(spec);
@@ -866,4 +872,4 @@ function createNarsilClient(options) {
   };
 }
 
-export { ASYNC_IMPORT_CAPABILITY, ClientErrorCodes, ErrorCodes, INDEX_LIFECYCLE_CAPABILITY, NarsilError, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, ServerErrorCodes, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createNarsilClient };
+export { ASYNC_IMPORT_CAPABILITY, ClientErrorCodes, ErrorCodes, INDEX_LIFECYCLE_CAPABILITY, NarsilError, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, ServerErrorCodes, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createNarsilClient, isNarsilError };

package/dist/{config-Czh2YNDi.d.ts → config-CNas6wJH.d.ts}

@@ -1,5 +1,5 @@
-import { N as NarsilConfig } from './config-OON7IJ_B.js';
-import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './types-DXPxaXPO.js';
+import { N as NarsilConfig } from './config-bXxnJrQc.js';
+import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './types-BTIVO8DI.js';
 import { N as NodeTransport } from './types-D5OwhtsQ.js';
 
 /**

package/dist/{config-OON7IJ_B.d.ts → config-bXxnJrQc.d.ts}

@@ -1,44 +1,72 @@
 import { P as PersistenceAdapter, I as InvalidationAdapter, E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { Q as QueryParams, e as QueryResult } from './memory-Bzd5xcEW.js';
-import { I as IndexConfig, A as AnyDocument } from './schema-BqRx9t4E.js';
+import { Q as QueryParams, e as QueryResult } from './memory-xrXOZMbw.js';
+import { I as IndexConfig, A as AnyDocument } from './schema-mLpXZBEh.js';
 
 /**
  * Hooks that run alongside the engine's own work, which is how you add
  * validation, auditing, enrichment, or metrics without forking the engine.
  *
- * Every hook is optional. A `before` hook runs first and rejects the operation
- * by throwing; an `after` hook runs once the operation succeeds. The engine
- * awaits a hook that returns a promise, so slow work in one slows every write
- * or search it covers.
+ * Every hook is optional. A `before` hook fires first and rejects the
+ * operation by throwing, while an `after` hook fires once the operation
+ * succeeds. The engine awaits a hook that returns a promise, so slow work in
+ * one hook slows every write or search that it covers.
  *
  * @public
  */
 interface NarsilPlugin {
     /** This name identifies the plugin in errors and in event payloads. */
     name: string;
-    /** Runs before a document is indexed. Throw to reject the write. */
+    /** Fires before the engine indexes a document. Throw to reject the write. */
     beforeInsert?(ctx: InsertContext): void | Promise<void>;
-    /** Runs once a document is indexed. */
+    /** Fires once the engine has indexed a document. */
     afterInsert?(ctx: InsertContext): void | Promise<void>;
-    /** Runs before a document is removed. Throw to reject the removal. */
+    /** Fires before the engine removes a document. Throw to reject the removal. */
     beforeRemove?(ctx: RemoveContext): void | Promise<void>;
-    /** Runs once a document is removed. */
+    /** Fires once the engine has removed a document. */
     afterRemove?(ctx: RemoveContext): void | Promise<void>;
-    /** Runs before a document is replaced. Throw to reject the update. */
+    /** Fires before the engine replaces a document. Throw to reject the update. */
     beforeUpdate?(ctx: UpdateContext): void | Promise<void>;
-    /** Runs once a document is replaced. */
+    /** Fires once the engine has replaced a document. */
     afterUpdate?(ctx: UpdateContext): void | Promise<void>;
-    /** Runs before a search executes. Throw to reject the query. */
+    /**
+     * Fires before every search, and before every preflight. Throw to reject the
+     * query. It fires before the engine embeds a `vector.text` query, so a hook
+     * that counts or refuses work stops the call to the embedding provider, and
+     * `ctx.params.vector` still holds the text that the caller passed.
+     * {@link Narsil.suggest} scans the term dictionary and searches no document,
+     * so it fires no hook.
+     */
     beforeSearch?(ctx: SearchContext): void | Promise<void>;
-    /** Runs once a search returns, with the results on the context. */
+    /**
+     * Fires once a search returns. The context holds a copy of the results, so a
+     * change that you make here leaves the caller's own result untouched. Where
+     * this hook throws, the engine logs a warning and answers the query all the
+     * same, because the search is already over.
+     */
     afterSearch?(ctx: SearchContext): void | Promise<void>;
-    /** Runs once an index is created. */
+    /**
+     * Fires once the engine creates an index, and a `restore` fires it too,
+     * because a restore recreates the index that it replaces. Where this hook
+     * throws, the engine logs a warning and keeps the index, because the hook
+     * fires after the index exists.
+     */
     onIndexCreate?(ctx: IndexContext): void | Promise<void>;
-    /** Runs once an index is dropped. */
+    /**
+     * Fires once the engine drops an index, and a `restore` fires it too,
+     * because a restore drops the index that it replaces. Where this hook
+     * throws, the engine logs a warning, because the hook fires after the index
+     * is gone.
+     */
     onIndexDrop?(ctx: IndexContext): void | Promise<void>;
-    /** Runs once an index grows into another partition. */
+    /**
+     * Fires once {@link Narsil.rebalance} moves an index onto a new partition
+     * count, which is the only way that the count changes. An index opens with
+     * the count that `partitions.maxPartitions` sets, because the engine adds no
+     * partition on its own. Subscribe to the `partitionWatermark` event to learn
+     * when an index fills its capacity.
+     */
     onPartitionSplit?(ctx: PartitionContext): void | Promise<void>;
-    /** Runs once the engine moves its indexes onto worker threads. */
+    /** Fires once the engine loads worker copies of its indexes. */
     onWorkerPromote?(ctx: WorkerContext): void | Promise<void>;
 }
 /**
@@ -62,7 +90,7 @@ interface InsertContext {
 interface RemoveContext {
     /** The engine removes the document from this index. */
     indexName: string;
-    /** This document is being removed. */
+    /** The engine removes this document. */
     docId: string;
 }
 /**
@@ -73,9 +101,9 @@ interface RemoveContext {
 interface UpdateContext {
     /** The document belongs to this index. */
     indexName: string;
-    /** This document is being replaced. */
+    /** The engine replaces this document. */
     docId: string;
-    /** The index stored this document before the update. */
+    /** The index holds this document before the update. */
     oldDocument: AnyDocument;
     /** This document replaces it, and the engine indexes whatever a `before` hook leaves here. */
     newDocument: AnyDocument;
@@ -90,29 +118,33 @@ interface SearchContext {
     indexName: string;
     /** These are the parameters the query runs with, and a `before` hook that changes them rewrites the search. */
     params: QueryParams;
-    /** These are the results, which an `after` hook alone receives. */
+    /**
+     * These are the results, which an `after` hook alone receives. A preflight
+     * fires `beforeSearch` and stops there, because it answers with a count and
+     * no hits. Read this field inside an `afterSearch` hook alone.
+     */
     results?: QueryResult;
 }
 /**
- * What a plugin receives when an index is created or dropped.
+ * What a plugin receives when the engine creates or drops an index.
  *
  * @public
  */
 interface IndexContext {
-    /** This index is being created or dropped. */
+    /** The engine creates or drops this index. */
     indexName: string;
-    /** The index was created with this configuration. */
+    /** The index holds this configuration. */
     config: IndexConfig;
 }
 /**
- * What a plugin receives when an index grows into another partition.
+ * What a plugin receives when a rebalance changes an index's partition count.
  *
  * @public
  */
 interface PartitionContext {
-    /** This index grew. */
+    /** The rebalance moved this index. */
     indexName: string;
-    /** The index held this many partitions before. */
+    /** The index held this many partitions before the rebalance. */
     oldPartitionCount: number;
     /** The index holds this many partitions now. */
     newPartitionCount: number;
@@ -123,9 +155,9 @@ interface PartitionContext {
  * @public
  */
 interface WorkerContext {
-    /** The pool started with this many workers. */
+    /** The pool holds this many workers. */
     workerCount: number;
-    /** The engine promoted for this reason, such as the threshold the index passed. */
+    /** The engine promoted for this reason, such as the threshold that the index crossed. */
     reason: string;
 }
 
@@ -245,7 +277,11 @@ interface DurabilityConfig {
     checkpointIntervalMs?: number;
     /** This many mutations trigger a checkpoint before the interval elapses. */
     checkpointMutationThreshold?: number;
-    /** Compaction reclaims the log once this fraction of it is dead. */
+    /**
+     * The engine merges a partition's checkpoint segments once that partition
+     * holds more than this many of them, 12 by default. The value is a whole
+     * number of segments.
+     */
     compactionThreshold?: number;
 }
 /**
@@ -280,9 +316,12 @@ interface WorkerConfig {
     enabled?: boolean;
     /**
      * The keyword copies and the vector search pool share this many threads
-     * between them, half each, in an embedded engine. The HTTP server holds a
-     * copy on every one of them and receives requests there. The engine takes
-     * the host's cores minus one by default, between 2 and 8.
+     * between them, half each, in an embedded engine, so a budget of 4 gives 2
+     * keyword copies and 2 vector search workers. The HTTP server holds a copy
+     * on every one of them and receives requests there. The engine takes the
+     * host's cores minus one by default, between 2 and 8. It caps a value that
+     * you set at 31, which is how many scratch slots the shared vector arena
+     * reserves.
      */
     count?: number;
     /** An index gains worker copies once it holds this many documents, 1,000 by default. */
@@ -303,7 +342,13 @@ interface WorkerConfig {
      * an engine that leaves this unset.
      */
     mainCopyQueries?: MainCopyQueries;
-    /** Each worker imports this module on start-up, which is how a worker reaches a custom tokeniser or language. */
+    /**
+     * Each worker imports this module on start-up, which is how a worker reaches
+     * a custom tokeniser or language. Give an absolute path or a URL, such as
+     * `new URL('./bootstrap.js', import.meta.url).href`, because a worker
+     * resolves a relative specifier against Narsil's own directory. A relative
+     * value raises `CONFIG_INVALID`.
+     */
     bootstrapModule?: string;
 }
 

package/dist/direct-executor-RBA5O7EN.mjs

@@ -0,0 +1,12 @@
+export { createDirectExecutor } from './chunk-XNQAIO74.mjs';
+import './chunk-AV4IJKD2.mjs';
+import './chunk-5T6AOR37.mjs';
+import './chunk-L225SHNB.mjs';
+import './chunk-TGP5M5R7.mjs';
+import './chunk-U2AL3SON.mjs';
+import './chunk-ZJ4CSAB2.mjs';
+import './chunk-UTOFOJOR.mjs';
+import './chunk-IFBKLBGB.mjs';
+import './chunk-U2BKYEC7.mjs';
+import './chunk-2GWVQWGA.mjs';
+import './chunk-FRQVMFY7.mjs';

package/dist/distribution/coordinator/etcd.d.ts

@@ -1,5 +1,5 @@
-import { C as ClusterCoordinator } from '../../types-DXPxaXPO.js';
-import '../../schema-BqRx9t4E.js';
+import { C as ClusterCoordinator } from '../../types-BTIVO8DI.js';
+import '../../schema-mLpXZBEh.js';
 import '../../adapters-79OIa4xm.js';
 
 /**

package/dist/distribution/coordinator/etcd.mjs

@@ -1,6 +1,6 @@
 import { MAX_NODE_ID_LENGTH, MAX_WATCHERS } from '../../chunk-ORBLD3EL.mjs';
 import { compareCodePoints } from '../../chunk-2GWVQWGA.mjs';
-import { NarsilError, ErrorCodes } from '../../chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from '../../chunk-FRQVMFY7.mjs';
 import { decode, encode } from '@msgpack/msgpack';
 
 // src/distribution/coordinator/etcd/types.ts

package/dist/distribution/coordinator/in-memory.d.ts

@@ -1,5 +1,5 @@
-import { C as ClusterCoordinator } from '../../types-DXPxaXPO.js';
-import '../../schema-BqRx9t4E.js';
+import { C as ClusterCoordinator } from '../../types-BTIVO8DI.js';
+import '../../schema-mLpXZBEh.js';
 import '../../adapters-79OIa4xm.js';
 
 /**

package/dist/distribution/transport/grpc.mjs

@@ -1,7 +1,7 @@
 import { decodeTransportMessage, encodeTransportMessage } from '../../chunk-OOSIDHA3.mjs';
 import { MAX_MESSAGE_SIZE_BYTES, GRPC_KEEPALIVE_TIMEOUT_MS, GRPC_KEEPALIVE_TIME_MS, GRPC_ENVELOPE_OVERHEAD_BYTES } from '../../chunk-UNEEFTEU.mjs';
 import { TransportError, TransportErrorCodes } from '../../chunk-GCM3JFVA.mjs';
-import { NarsilError, ErrorCodes } from '../../chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from '../../chunk-FRQVMFY7.mjs';
 
 // src/distribution/transport/grpc/codec.ts
 var FIELD_ONE_LENGTH_DELIMITED_KEY = 10;

package/dist/distribution.d.ts

@@ -1,12 +1,12 @@
-import { a as CreateIndexOptions, C as ClusterNamespace, b as ClusterNodeConfig } from './config-Czh2YNDi.js';
-export { c as ClusterControllerConfig, d as ClusterNodeInfo, e as ClusterQueryConfig, N as NodeReadiness, R as ReplicationConfig } from './config-Czh2YNDi.js';
-import { N as NarsilEventMap, a as Narsil } from './engine-9PtFY50q.js';
-import { B as BatchResult, L as ListParams, g as ListResult, i as SuggestParams, j as SuggestResult, Q as QueryParams, h as PreflightResult, f as IndexStats, P as PartitionStatsResult, M as MemoryStats, e as QueryResult } from './memory-Bzd5xcEW.js';
-import { I as IndexConfig, A as AnyDocument, b as InsertOptions } from './schema-BqRx9t4E.js';
-import { b as NodeCapacity, N as NodeRole } from './types-DXPxaXPO.js';
-export { c as AllocationConstraints, d as AllocationEvent, A as AllocationTable, C as ClusterCoordinator, e as NodeEvent, a as NodeRegistration, P as PartitionAssignment, f as PartitionState, S as SchemaEvent, U as UnassignedReason } from './types-DXPxaXPO.js';
+import { a as CreateIndexOptions, C as ClusterNamespace, b as ClusterNodeConfig } from './config-CNas6wJH.js';
+export { c as ClusterControllerConfig, d as ClusterNodeInfo, e as ClusterQueryConfig, N as NodeReadiness, R as ReplicationConfig } from './config-CNas6wJH.js';
+import { N as NarsilEventMap, a as Narsil } from './engine-Dj4I91Jv.js';
+import { B as BatchResult, L as ListParams, g as ListResult, j as SuggestParams, k as SuggestResult, Q as QueryParams, h as PreflightResult, f as IndexStats, P as PartitionStatsResult, M as MemoryStats, e as QueryResult } from './memory-xrXOZMbw.js';
+import { I as IndexConfig, A as AnyDocument, a as InsertOptions } from './schema-mLpXZBEh.js';
+import { b as NodeCapacity, N as NodeRole } from './types-BTIVO8DI.js';
+export { c as AllocationConstraints, d as AllocationEvent, A as AllocationTable, C as ClusterCoordinator, e as NodeEvent, a as NodeRegistration, P as PartitionAssignment, f as PartitionState, S as SchemaEvent, U as UnassignedReason } from './types-BTIVO8DI.js';
 export { L as ListenHandler, N as NodeTransport, R as RespondFn, T as TransportConfig, a as TransportMessage } from './types-D5OwhtsQ.js';
-import './config-OON7IJ_B.js';
+import './config-bXxnJrQc.js';
 import './adapters-79OIa4xm.js';
 
 /**