@delali/narsil 0.2.4-next.52 → 0.2.4-next.55

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

@@ -1,6 +1,6 @@
-import { P as PartitionConfig, A as AnyDocument, a as InsertOptions, W as WriteOptions } from './schema-OSWaaZzx.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-OmgkX_Z2.js';
-import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-DiF1c9v2.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-OmgkX_Z2.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-CuTSXvbN.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-DiF1c9v2.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-BMJWVxOP.js';
-import './schema-OSWaaZzx.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-qMLpi5T4.js';
-import './config-BcYZkdMw.js';
-import './types-LEzMyjVX.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-qMLpi5T4.d.ts → config-CNas6wJH.d.ts}

@@ -1,5 +1,5 @@
-import { N as NarsilConfig } from './config-BcYZkdMw.js';
-import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './types-LEzMyjVX.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-BcYZkdMw.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-OmgkX_Z2.js';
-import { I as IndexConfig, A as AnyDocument } from './schema-OSWaaZzx.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-LEzMyjVX.js';
-import '../../schema-OSWaaZzx.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-LEzMyjVX.js';
-import '../../schema-OSWaaZzx.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-qMLpi5T4.js';
-export { c as ClusterControllerConfig, d as ClusterNodeInfo, e as ClusterQueryConfig, N as NodeReadiness, R as ReplicationConfig } from './config-qMLpi5T4.js';
-import { N as NarsilEventMap, a as Narsil } from './engine-zhms1qId.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-OmgkX_Z2.js';
-import { I as IndexConfig, A as AnyDocument, a as InsertOptions } from './schema-OSWaaZzx.js';
-import { b as NodeCapacity, N as NodeRole } from './types-LEzMyjVX.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-LEzMyjVX.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-BcYZkdMw.js';
+import './config-bXxnJrQc.js';
 import './adapters-79OIa4xm.js';
 
 /**

package/dist/distribution.mjs

@@ -1,24 +1,24 @@
 import { MAX_MESSAGE_SIZE_BYTES } from './chunk-UNEEFTEU.mjs';
-import { validateIndexName, indexConfigKey, putIndexMetadata, getIndexMetadata } from './chunk-72AXTIBW.mjs';
-import { createEngineCore, checkHeapAfterRecovery, createNarsilFromCore, runEngineQueryStats, runEngineListDocuments, runEngineSuggest, runEnginePreflight, runEngineQuery, createEngineIndex, applyIndexEntry, applyDeleteEntry, validateEntryBatchPayload, createAckMessage, validateEntryPayload, validateForwardBatchPayload, createForwardBatchResultMessage, createForwardBatchMessage, validateForwardBatchResultPayload, createForwardMessage, validateReplicationEntry, computeEntryChecksum, createEntryMessage, createEntryBatchMessage, createInsyncConfirmMessage, validateAckPayload, createInsyncRemoveMessage, validateInsyncConfirmPayload, createInsyncAddMessage } from './chunk-ULJ36FK4.mjs';
+import { validateIndexName, indexConfigKey, putIndexMetadata, getIndexMetadata } from './chunk-NTZYA3SJ.mjs';
+import { createEngineCore, checkHeapAfterRecovery, createNarsilFromCore, runEngineQueryStats, runEngineListDocuments, runEngineSuggest, runEnginePreflight, runEngineQuery, createEngineIndex, applyIndexEntry, applyDeleteEntry, validateEntryBatchPayload, createAckMessage, validateEntryPayload, validateForwardBatchPayload, createForwardBatchResultMessage, createForwardBatchMessage, validateForwardBatchResultPayload, createForwardMessage, validateReplicationEntry, computeEntryChecksum, createEntryMessage, createEntryBatchMessage, createInsyncConfirmMessage, validateAckPayload, createInsyncRemoveMessage, validateInsyncConfirmPayload, createInsyncAddMessage } from './chunk-BH5SYB5W.mjs';
 import { ReplicationMessageTypes, TransportErrorCodes, ClusterMessageTypes, QueryMessageTypes, TransportError } from './chunk-GCM3JFVA.mjs';
-import { MAX_PARTITION_COUNT, MAX_REPLICATION_FACTOR, WIRE_BATCH_BUDGET } from './chunk-U36IDJN7.mjs';
-import { generateId, deserializePayloadV2, createPartitionIndex, getLanguage, FILTER_EXPRESSION_KEYS, FIELD_FILTER_OPERATORS } from './chunk-2FO7KZ6K.mjs';
+import { providedDocId, MAX_PARTITION_COUNT, MAX_REPLICATION_FACTOR, WIRE_BATCH_BUDGET } from './chunk-4NVPQ6S5.mjs';
+import { generateId, deserializePayloadV2, createPartitionIndex, getLanguage, FILTER_EXPRESSION_KEYS, FIELD_FILTER_OPERATORS } from './chunk-XNQAIO74.mjs';
 import './chunk-AV4IJKD2.mjs';
-import { now, listBindingOf, queryBindingOf, foldGroupReducer, clampLimit, dedupePinnedEntries } from './chunk-YPYULM5E.mjs';
-import { DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, MAX_INDEX_NAME_LENGTH, MAX_DOC_ID_LENGTH, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, INDEX_NAME_PATTERN } from './chunk-3GWP2TO6.mjs';
-import { resolveProjection, clampRowCount, sortSignatureOf, requireMatchingCursor, decodePageCursor, normalizeSort, encodePageCursor, applyProjection, readSortValues, requireWithinResultWindow, fnv1a, mergePartitionStats } from './chunk-WM7IS45M.mjs';
-import { DEFAULT_PAGE_SIZE, MAX_SORT_FIELDS, MAX_CURSOR_LENGTH, RESULT_WINDOW, MAX_NESTING_DEPTH } from './chunk-ZT5BRDFW.mjs';
+import { now, listBindingOf, queryBindingOf, foldGroupReducer, clampLimit, dedupePinnedEntries } from './chunk-TVT5V4E7.mjs';
+import { DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, MAX_INDEX_NAME_LENGTH, MAX_DOC_ID_LENGTH, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, INDEX_NAME_PATTERN } from './chunk-D2S642IV.mjs';
+import { resolveProjection, clampRowCount, sortSignatureOf, requireMatchingCursor, decodePageCursor, normalizeSort, encodePageCursor, applyProjection, readSortValues, requireWithinResultWindow, fnv1a, mergePartitionStats } from './chunk-5T6AOR37.mjs';
+import { DEFAULT_PAGE_SIZE, MAX_SORT_FIELDS, MAX_CURSOR_LENGTH, RESULT_WINDOW, MAX_NESTING_DEPTH } from './chunk-L225SHNB.mjs';
 import './chunk-TGP5M5R7.mjs';
-import './chunk-T62YOSGS.mjs';
+import './chunk-U2AL3SON.mjs';
 import { MIN_OVERSAMPLE } from './chunk-ZJ4CSAB2.mjs';
-import './chunk-WFKIGEBY.mjs';
+import './chunk-UTOFOJOR.mjs';
 import { crc32 } from './chunk-3L4U6EJQ.mjs';
 import './chunk-IFBKLBGB.mjs';
 import './chunk-U2BKYEC7.mjs';
 import { compareCodePoints, toComparableSortValue, compareComparableKeys, compareSortValues } from './chunk-2GWVQWGA.mjs';
 import './chunk-POWOTUKJ.mjs';
-import { ErrorCodes, NarsilError, describeError } from './chunk-P4ELXVJQ.mjs';
+import { ErrorCodes, NarsilError, describeError } from './chunk-FRQVMFY7.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/distribution/cluster/constants.ts
@@ -9204,7 +9204,7 @@ async function routeDropIndex(name, coordinator, engine) {
   await coordinator.dropSchema(name);
 }
 async function routeInsert(indexName, document, docId, deps, options) {
-  const resolvedDocId = docId ?? generateId();
+  const resolvedDocId = docId ?? providedDocId(document) ?? generateId();
   const resolution = await resolvePrimaryAssignment(indexName, resolvedDocId, deps, false);
   if (resolution === null) {
     return deps.engine.insert(indexName, document, resolvedDocId, options);

package/dist/embeddings/openai.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-FRQVMFY7.mjs';
 
 // src/embeddings/constants.ts
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503]);

package/dist/{engine-zhms1qId.d.ts → engine-Dj4I91Jv.d.ts}

@@ -1,6 +1,6 @@
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { B as BatchResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './memory-OmgkX_Z2.js';
-import { A as AnyDocument, a as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-OSWaaZzx.js';
+import { B as BatchResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, j as SuggestParams, k as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './memory-xrXOZMbw.js';
+import { A as AnyDocument, a as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-mLpXZBEh.js';
 
 /**
  * Every event the engine emits, with the payload each one carries.
@@ -68,17 +68,23 @@ type NarsilEventMap = {
         partitionCount: number;
     };
     /**
-     * The process heap crossed nine tenths of its limit during a write or a
+     * The process uses nine tenths of its heap, measured during a write or a
      * load, so the next large index may end the process with an out-of-memory
-     * error. The engine emits the event once per crossing and arms it again
-     * once the heap falls below eight tenths of the limit. Raise the limit with
+     * error. Where `--max-old-space-size` or `--max-old-space-size-percentage`
+     * sets a limit, on the command line or in `NODE_OPTIONS`, the engine measures
+     * the used bytes against that figure and `heapLimit` reports it. Where
+     * neither flag sets one, the engine compares the used bytes with the headroom
+     * that V8 reports, which runs about 192 MB above the true ceiling, so a
+     * default heap below about 2 GB may end before this event fires. The engine
+     * emits the event once per crossing and arms it again once the headroom
+     * recovers to two tenths. Raise the limit with
      * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
      * idle index; see {@link ProcessMemoryReport.heapLimit}.
      */
     heapPressure: {
-        /** The heap crossed nine tenths of its limit during a write to this index or a load of it. */
+        /** The heap reaches that point during a write to this index or a load of it. */
         indexName: string;
-        /** The process is using this much heap, in bytes. */
+        /** The process uses this much heap, in bytes. */
         heapUsed: number;
         /** The heap may grow to this many bytes. */
         heapLimit: number;
@@ -155,7 +161,9 @@ interface DocumentWriteOperations {
      * @param indexName - The index that receives the document.
      * @param document - Its fields must match the types the schema declares.
      * @param docId - Pass an id to control it yourself, or omit it and read the
-     * returned value.
+     * returned value. An id that differs from the document's own `id` field
+     * raises `DOC_VALIDATION_FAILED`, because the stored document would
+     * otherwise contradict the key that it is stored under.
      * @param options - Per-write settings, such as skipping the defensive copy
      * or waiting for every worker copy to apply the write.
      * @returns The id the document is stored under.
@@ -294,6 +302,11 @@ interface Narsil extends IndexLifecycleOperations, DocumentWriteOperations {
     /**
      * Fetches one stored document by id, without searching.
      *
+     * A vector field comes back as a `Float32Array`, whatever form you give it.
+     * `JSON.stringify` writes one as an object keyed by index, so convert it
+     * with `Array.from`, or project the field away, before you serialise the
+     * document yourself. The HTTP routes convert it for you.
+     *
      * @param indexName - The index holding the document.
      * @param docId - The document to fetch.
      * @returns The document, or `undefined` when the index holds no such id.