@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/tasks-CnMLpfk-.d.ts

@@ -0,0 +1,274 @@
+/** Declarative index configuration accepted over HTTP. Function-valued engine
+ * options (custom tokenizer, stopWords-as-function, group reducer, embedding
+ * adapter object) are not representable here; the embedding adapter is named
+ * instead via {@link CreateIndexEmbedding}.
+ *
+ * @public */
+interface CreateIndexRequest {
+    /** The server creates the index under this name. */
+    name: string;
+    /** This carries the schema and settings, in the subset JSON can express. */
+    config: HttpIndexConfig;
+}
+/**
+ * How a JSON `createIndex` request connects an index to an embedding adapter.
+ *
+ * An adapter is a function and cannot cross JSON, so the request names one the
+ * server registered instead of carrying it.
+ *
+ * @public
+ */
+interface CreateIndexEmbedding {
+    /** This names an adapter the server registered under `embeddingAdapters`. */
+    adapter?: string;
+    /** This maps each vector field to the text field, or fields, the server embeds into it. */
+    fields: Record<string, string | string[]>;
+}
+/**
+ * The index settings a JSON request can carry, which is {@link IndexConfig}
+ * minus everything that is a function.
+ *
+ * A custom tokeniser, a stop-word function, and an embedding adapter object
+ * have no JSON form, so an HTTP client names a registered one or supplies a
+ * plain list instead.
+ *
+ * @public
+ */
+interface HttpIndexConfig {
+    /** This layout gives each value as either a field type or a nested schema. */
+    schema: Record<string, unknown>;
+    /** The server tokenises and stems text fields with the language module registered under this name. */
+    language?: string;
+    /** These settings control how the index splits documents across partitions as it grows. */
+    partitions?: {
+        maxDocsPerPartition?: number;
+        maxPartitions?: number;
+        watermark?: number;
+    };
+    /** A query scores this way unless it asks for another mode. */
+    defaultScoring?: 'local' | 'dfs' | 'broadcast';
+    /** These parameters tune BM25 for this index. */
+    bm25?: {
+        k1?: number;
+        b?: number;
+    };
+    /** This list replaces the language's stop words. */
+    stopWords?: string[];
+    /** Setting this records term positions, which phrase queries and highlighting need. */
+    trackPositions?: boolean;
+    /** Setting this to false returns index stems from suggestions and prefix expansion, instead of the words users typed. */
+    surfaceForms?: boolean;
+    /** These settings control when vector fields move to an HNSW graph, and how that graph is built. */
+    vectorPromotion?: Record<string, unknown>;
+    /** Setting this rejects a document carrying a field the schema does not declare. */
+    strict?: boolean;
+    /** This names a server-registered embedding adapter and the fields it embeds. */
+    embedding?: CreateIndexEmbedding;
+    /** The server rejects a document that omits any of these fields. */
+    required?: string[];
+}
+/**
+ * One record an import refused, naming the line it came from and why the
+ * server rejected it.
+ *
+ * @public
+ */
+interface ImportError {
+    /** The failing record sat on this line of the body, counting from one. */
+    line?: number;
+    /** The engine rejected the document stored under this id. */
+    docId?: string;
+    /** This says which failure it is. */
+    code: string;
+    /** This describes the failure, for a log or a person. */
+    message: string;
+}
+/**
+ * What one import produced.
+ *
+ * `errors` is capped by the server's `maxImportErrors` limit while `failed`
+ * counts every refusal, so a run that trips the cap reports the true total and
+ * sets `errorsTruncated`.
+ *
+ * @public
+ */
+interface ImportResult {
+    /** The engine accepted this many documents. */
+    indexed: number;
+    /** The server refused this many records in total. */
+    failed: number;
+    /** The first refusals, up to the server's reporting cap. */
+    errors: ImportError[];
+    /** Setting this says more records failed than `errors` lists. */
+    errorsTruncated: boolean;
+}
+/**
+ * What a server announces at `/capabilities`, which is how a client finds out
+ * whether an optional route or mode is available before it sends a request.
+ *
+ * A server that answers 404 here predates the endpoint, so treat every optional
+ * capability as absent.
+ *
+ * @public
+ */
+interface CapabilitiesResponse {
+    /** Each name marks one capability this server serves. */
+    capabilities: string[];
+}
+
+/**
+ * Which long-running operation a task record tracks.
+ *
+ * @public
+ */
+type TaskType = 'optimizeVectors' | 'rebalance' | 'restore' | 'import' | 'rebuildAnalysis';
+/**
+ * Where a long-running operation stands.
+ *
+ * A task reaches `cancelled` only when the work itself stopped early, so a
+ * cancel that arrives too late leaves the task `succeeded`.
+ *
+ * @public
+ */
+type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+/**
+ * How far a running import has gone, which is what a progress bar reads.
+ *
+ * The byte counts describe the request body, so they give an honest fraction
+ * from the first batch onwards, while the document counts only cover what the
+ * server has already handed to the engine. Task types other than `import`
+ * report no progress.
+ *
+ * @public
+ */
+interface TaskProgress {
+    /** The server has indexed this many documents so far. */
+    indexed: number;
+    /** The server has rejected this many documents so far. */
+    failed: number;
+    /** The server has read this many bytes of the body so far. */
+    bytesProcessed: number;
+    /** The body holds this many bytes in total. */
+    bytesTotal: number;
+}
+/**
+ * One long-running operation, which the server answers with straight away and
+ * you then poll.
+ *
+ * Every route that starts a task answers with this same record, and
+ * `GET /tasks/{id}` returns it again as the work moves on.
+ *
+ * @public
+ */
+interface TaskRecord {
+    /** This identifies the task, and is what you poll by. */
+    id: string;
+    /** This says which operation the task runs. */
+    type: TaskType;
+    /** The operation runs against this index. */
+    indexName: string;
+    /** This says where the operation stands. */
+    status: TaskStatus;
+    /** Identifier of the server instance running this task; see ServerOptions.instanceId. */
+    owner: string;
+    /** The server accepted the task at this many milliseconds since the epoch. */
+    createdAt: number;
+    /** Work started at this many milliseconds since the epoch, and a queued task omits it. */
+    startedAt?: number;
+    /** Work ended at this many milliseconds since the epoch, and a task omits it until it reaches a final status. */
+    completedAt?: number;
+    /** A cancel arrived at this many milliseconds since the epoch, which is how a
+     * task still running shows that it is stopping. */
+    cancelRequestedAt?: number;
+    /** How far the work has gone, which an import reports and other task types omit. */
+    progress?: TaskProgress;
+    /** What the work produced, which an import reports once it finishes. */
+    result?: ImportResult;
+    /** This says why the task failed, and a failed task alone carries it. */
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * Which task records `GET /tasks` returns, and where the page starts.
+ *
+ * Every filter is optional, and omitting all of them lists every record the
+ * store still holds, newest first.
+ *
+ * @public
+ */
+interface TaskListQuery {
+    /** Keeps the tasks running against this index. */
+    indexName?: string;
+    /** Keeps the tasks of these types. */
+    type?: TaskType[];
+    /** Keeps the tasks at these statuses. */
+    status?: TaskStatus[];
+    /** Skips this many records, and starts at the newest by default. */
+    from?: number;
+    /** The page carries this many records, and 20 by default. */
+    limit?: number;
+}
+/**
+ * One page of task records, ordered newest first.
+ *
+ * @public
+ */
+interface TaskListPage {
+    /** The records this page carries. */
+    tasks: TaskRecord[];
+    /** How many records the filters matched in total, across every page. */
+    total: number;
+    /** This page skipped this many records. */
+    from: number;
+    /** This page asked for this many records. */
+    limit: number;
+    /** Pass this back as `from` for the next page, and it is null on the last page. */
+    next: number | null;
+}
+/**
+ * Pluggable backing store for task records. Every method is async so any
+ * backend works: an in-memory map, Redis, an HTTP key-value service, or a
+ * database. `set` upserts by `record.id`; `get` returns null for an unknown id.
+ * `ttlMs`, when honored by the backend, expires the record so terminal tasks do
+ * not accumulate. The server never calls a method that mutates a record it did
+ * not construct, so a backend may treat records as immutable snapshots.
+ *
+ * @public
+ */
+interface TaskStore {
+    /**
+     * Stores a record, replacing whatever its id already held.
+     *
+     * @param record - The record to store.
+     * @param ttlMs - Milliseconds after which the backend may drop it, which
+     * keeps finished tasks from accumulating. Ignore it in a backend without
+     * expiry.
+     */
+    set(record: TaskRecord, ttlMs?: number): Promise<void>;
+    /**
+     * Reads one record back.
+     *
+     * @param id - The task to read.
+     * @returns The record, or `null` when the store holds no such id.
+     */
+    get(id: string): Promise<TaskRecord | null>;
+    /**
+     * Lists every record the store holds.
+     *
+     * @returns Each record the backend still has.
+     */
+    list(): Promise<TaskRecord[]>;
+    /**
+     * Removes one record. An id the store never held is not an error.
+     *
+     * @param id - The task to remove.
+     */
+    delete(id: string): Promise<void>;
+    /** Releases whatever the backend holds open, such as a connection pool. */
+    shutdown?(): Promise<void>;
+}
+
+export type { CapabilitiesResponse as C, HttpIndexConfig as H, ImportError as I, TaskListPage as T, CreateIndexEmbedding as a, ImportResult as b, TaskListQuery as c, TaskProgress as d, TaskRecord as e, TaskStatus as f, TaskType as g, TaskStore as h, CreateIndexRequest as i };

package/dist/types-BQDlIvfS.d.ts

@@ -0,0 +1,34 @@
+import { T as TransportConfig } from './types-D5OwhtsQ.js';
+
+/**
+ * The certificate material one node presents to its peers.
+ *
+ * @public
+ */
+interface TlsConfig {
+    /** This node presents this certificate, in PEM form. */
+    cert: Buffer | string;
+    /** The private key matching the certificate, in PEM form. */
+    key: Buffer | string;
+    /** Peers must chain to this authority. The Node.js default authorities apply when absent. */
+    ca?: Buffer | string;
+    /** Setting this to false accepts an unverified peer, for tests alone. */
+    rejectUnauthorized?: boolean;
+}
+/**
+ * How the TCP transport listens and dials.
+ *
+ * @public
+ */
+interface TcpTransportConfig extends TransportConfig {
+    /** The transport listens on this host. */
+    host: string;
+    /** The transport listens on this port, and 0 asks the system for a free one. */
+    port: number;
+    /** The connection pool holds at most this many outbound connections. */
+    maxConnections: number;
+    /** Presenting this makes every connection mutually authenticated TLS. */
+    tls?: TlsConfig;
+}
+
+export type { TcpTransportConfig as T, TlsConfig as a };

package/dist/{types-BV3nAKTL.d.ts → types-Bfhhnh3G.d.ts}

@@ -1,4 +1,4 @@
-import { b as SchemaDefinition } from './schema-CE6S_aAr.js';
+import { S as SchemaDefinition } from './schema-emTQfEiX.js';
 
 /**
  * What a node does in a cluster. A node may hold several roles at once.
@@ -199,6 +199,13 @@ interface ClusterCoordinator {
      * version no longer matched.
      */
     putAllocation(indexName: string, table: AllocationTable, expectedVersion?: number | null): Promise<boolean>;
+    /**
+     * Removes one index's allocation, which is the last step of dropping the
+     * index. Deleting an allocation that does not exist does nothing.
+     *
+     * @param indexName - The index whose allocation goes.
+     */
+    deleteAllocation(indexName: string): Promise<void>;
     /**
      * Watches allocations changing.
      *
@@ -280,6 +287,21 @@ interface ClusterCoordinator {
      * @param schema - Its field layout.
      */
     putSchema(indexName: string, schema: SchemaDefinition): Promise<void>;
+    /**
+     * Removes one index's schema and tells every watcher it was dropped, which
+     * starts the cluster-wide teardown of that index. Dropping a schema that
+     * does not exist does nothing.
+     *
+     * @param indexName - The index whose schema goes.
+     */
+    dropSchema(indexName: string): Promise<void>;
+    /**
+     * Lists the name of every published schema, which is how a newly elected
+     * controller finds the indexes it must reconcile.
+     *
+     * @returns Every index name holding a schema, sorted by code point.
+     */
+    listSchemas(): Promise<string[]>;
     /**
      * Watches schemas being published and dropped.
      *

package/dist/types-D5OwhtsQ.d.ts

@@ -0,0 +1,97 @@
+/**
+ * One message on the wire between cluster nodes.
+ *
+ * The payload is opaque bytes, which is what lets a node written in another
+ * language join the same cluster: only the header fields have to agree.
+ *
+ * @public
+ */
+interface TransportMessage {
+    /** This says what the message is, such as a replication entry or a search request. */
+    type: string;
+    /** This node sent the message. */
+    sourceId: string;
+    /** This correlates a reply with its request. */
+    requestId: string;
+    /** This carries the encoded body, and the message type tells a reader how to decode it. */
+    payload: Uint8Array;
+}
+/**
+ * How long a transport waits before giving up on each kind of exchange.
+ *
+ * Every value is in milliseconds. Replication and snapshot transfers carry
+ * their own timeouts because they move far more than a search does.
+ *
+ * @public
+ */
+interface TransportConfig {
+    /** Opening a connection to a peer may take this long. */
+    connectTimeout: number;
+    /** An ordinary request and its reply may take this long. */
+    requestTimeout: number;
+    /** A replication entry may take this long to reach a replica and come back acknowledged. */
+    replicationTimeout: number;
+    /** A whole snapshot transfer, which moves a partition between nodes, may take this long. */
+    snapshotTimeout: number;
+}
+/**
+ * How one cluster node reaches the others.
+ *
+ * The package includes a TCP transport for real deployments and an in-process
+ * one for tests, and this is the contract either satisfies. Write your own to
+ * run a cluster over something else.
+ *
+ * @public
+ */
+interface NodeTransport {
+    /**
+     * Sends one request to a peer and waits for its reply.
+     *
+     * @param target - Node id to send to.
+     * @param message - The request.
+     * @returns The peer's reply.
+     * @throws A `TransportError` when the peer is unreachable, the message is
+     * oversized, or the request times out.
+     */
+    send(target: string, message: TransportMessage): Promise<TransportMessage>;
+    /**
+     * Sends one request whose reply arrives in chunks, which is how a snapshot
+     * moves without being held in memory whole.
+     *
+     * @param target - Node id to send to.
+     * @param message - The request.
+     * @param handler - Called once per chunk, in order.
+     */
+    stream(target: string, message: TransportMessage, handler: (chunk: Uint8Array) => void): Promise<void>;
+    /**
+     * Starts accepting requests from peers.
+     *
+     * @param handler - Called for each request, with the function that returns
+     * the reply.
+     * @returns A function that ends the listener.
+     */
+    listen(handler: ListenHandler): Promise<() => void>;
+    /** Closes every connection and releases the port or registration it held. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Sends one reply back to the peer that asked.
+ *
+ * It settles once the transport has taken the reply, which a transport whose
+ * connection is full delays until the connection accepts more. A handler
+ * sending many replies awaits each one before it builds the next, so a
+ * snapshot cannot outrun a slow receiver and exhaust this node's memory.
+ *
+ * @param response - The reply to send.
+ *
+ * @public
+ */
+type RespondFn = (response: TransportMessage) => Promise<void>;
+/**
+ * Handles one request a peer sent, replying through `respond`.
+ *
+ * @public
+ */
+type ListenHandler = (message: TransportMessage, respond: RespondFn) => void | Promise<void>;
+
+export type { ListenHandler as L, NodeTransport as N, RespondFn as R, TransportConfig as T, TransportMessage as a };

package/dist/vector/hnsw-build-worker.d.ts

@@ -1,9 +1,4 @@
-/**
- * Similarity metric a vector search ranks by.
- *
- * @internal
- */
-type VectorMetric = 'cosine' | 'dotProduct' | 'euclidean';
+import { V as VectorMetric } from '../brute-force-DbHYCTc3.js';
 
 /**
  * How an HNSW graph is built.
@@ -107,4 +102,4 @@ interface HNSWBuildError {
  */
 type HNSWWorkerMessage = HNSWBuildResponse | HNSWBuildError;
 
-export type { HNSWBuildError, HNSWBuildRequest, HNSWBuildRequestBinary, HNSWBuildResponse, HNSWConfig, HNSWWorkerMessage, SerializedHNSWGraph, VectorMetric };
+export { type HNSWBuildError, type HNSWBuildRequest, type HNSWBuildRequestBinary, type HNSWBuildResponse, type HNSWConfig, type HNSWWorkerMessage, type SerializedHNSWGraph, VectorMetric };

package/dist/vector/hnsw-build-worker.mjs

@@ -1,4 +1,5 @@
-import { createVectorStore, createHNSWIndex } from '../chunk-S7RJJMHI.mjs';
+import { createVectorStore, createHNSWIndex } from '../chunk-WDL632CN.mjs';
+import '../chunk-BFIH7OV5.mjs';
 
 // src/vector/hnsw-build-worker.ts
 var MAX_WORKER_DIMENSION = 8192;