@wiscale/velesdb-sdk 1.12.0 → 1.13.1

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 /**
- * VelesDB TypeScript SDK - Type Definitions
+ * VelesDB TypeScript SDK - Core Type Definitions
+ *
+ * Collection, configuration, and basic document types.
  * @packageDocumentation
  */
 /** Supported distance metrics for vector similarity */
@@ -24,13 +26,49 @@ interface VelesDBConfig {
     timeout?: number;
 }
 /** Collection type */
-type CollectionType = 'vector' | 'metadata_only';
+type CollectionType = 'vector' | 'metadata_only' | 'graph';
 /** HNSW index parameters for collection creation */
 interface HnswParams {
     /** Number of bi-directional links per node (M parameter) */
     m?: number;
     /** Size of dynamic candidate list during construction */
     efConstruction?: number;
+    /** Maximum number of elements in the index */
+    maxElements?: number;
+    /** Storage mode for vector quantization */
+    storageMode?: StorageMode;
+    /** Alpha parameter for HNSW construction */
+    alpha?: number;
+}
+/**
+ * Deferred indexing configuration (`velesdb_core::collection::streaming::DeferredIndexerConfig`).
+ *
+ * When enabled, inserts are buffered in memory and batch-merged into the
+ * HNSW index once the buffer reaches `mergeThreshold` or once the oldest
+ * buffered vector is older than `maxBufferAgeMs`. Trades insert latency
+ * for throughput.
+ */
+interface DeferredIndexerOptions {
+    /** Whether deferred indexing is enabled (default: false). */
+    enabled?: boolean;
+    /** Number of buffered vectors that triggers a merge into HNSW. */
+    mergeThreshold?: number;
+    /** Max age (ms) of the oldest buffered vector before a time-based merge. */
+    maxBufferAgeMs?: number;
+}
+/**
+ * Async index builder configuration (`velesdb_core::collection::streaming::AsyncIndexBuilderConfig`).
+ *
+ * Enables the parallel segment-based `AsyncIndexBuilder` for bulk inserts
+ * (Issue #488 -- Bulk Insert V2). Used when the collection is known to
+ * receive large bulk loads where the extra segment coordination cost is
+ * amortised over millions of inserts.
+ */
+interface AsyncIndexBuilderOptions {
+    /** Buffered vector count that triggers a build (default: 10_000). */
+    mergeThreshold?: number;
+    /** Number of segments for parallel construction (default: num_cpus). */
+    segmentCount?: number;
 }
 /** Collection configuration */
 interface CollectionConfig {
@@ -42,6 +80,8 @@ interface CollectionConfig {
      * - 'full': Full f32 precision (3 KB/vector for 768D)
      * - 'sq8': 8-bit scalar quantization, 4x memory reduction (~1% recall loss)
      * - 'binary': 1-bit binary quantization, 32x memory reduction (edge/IoT)
+     * - 'pq': Product quantization (requires training via `trainPq`)
+     * - 'rabitq': RaBitQ quantization (binary + rescoring)
      */
     storageMode?: StorageMode;
     /** Collection type: 'vector' (default) or 'metadata_only' */
@@ -50,6 +90,18 @@ interface CollectionConfig {
     description?: string;
     /** Optional HNSW parameters for index tuning */
     hnsw?: HnswParams;
+    /**
+     * PQ rescore oversampling factor (quantised storage modes only).
+     *
+     * The search pipeline fetches `max(k * factor, k + 32)` candidates from
+     * HNSW and rescores them with full-precision ADC. Default is `4`.
+     * Setting `0` disables rescoring (fastest, lowest recall).
+     */
+    pqRescoreOversampling?: number;
+    /** Deferred indexing buffer configuration (US-366). */
+    deferredIndexing?: DeferredIndexerOptions;
+    /** Parallel async index builder configuration (Issue #488). */
+    asyncIndexBuilder?: AsyncIndexBuilderOptions;
 }
 /** Collection metadata */
 interface Collection {
@@ -68,7 +120,7 @@ interface Collection {
 }
 /** Sparse vector: mapping from term/dimension index to weight */
 type SparseVector = Record<number, number>;
-/** Vector document to insert */
+/** Vector document to upsert */
 interface VectorDocument {
     /** Unique identifier */
     id: string | number;
@@ -79,12 +131,257 @@ interface VectorDocument {
     /** Optional sparse vector for hybrid search */
     sparseVector?: SparseVector;
 }
+/** PQ (Product Quantization) training options */
+interface PqTrainOptions {
+    /** Number of subquantizers (default: 8) */
+    m?: number;
+    /** Number of centroids per subquantizer (default: 256) */
+    k?: number;
+    /** Enable Optimized Product Quantization (default: false) */
+    opq?: boolean;
+}
+
+/**
+ * VelesDB Filter DSL
+ *
+ * Typed mirror of `velesdb_core::filter::Condition` (20 operators).
+ * Provides a fluent builder API (`f.*`) for ergonomic filter construction
+ * and accepts raw `Record<string, unknown>` objects for backward compatibility
+ * with pre-v1.13 code.
+ *
+ * @example Typed builder
+ * ```typescript
+ * import { f } from '@wiscale/velesdb-sdk';
+ *
+ * const filter = f.and([
+ *   f.eq('category', 'tech'),
+ *   f.gte('price', 100),
+ *   f.not(f.isNull('author')),
+ * ]);
+ * const results = await db.search('docs', query, { filter });
+ * ```
+ *
+ * @example Legacy JSON (backward-compat, no compile-time checking)
+ * ```typescript
+ * const filter = {
+ *   condition: { type: 'eq', field: 'category', value: 'tech' }
+ * };
+ * const results = await db.search('docs', query, { filter });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** JSON value accepted by filter operators (mirror of `serde_json::Value`). */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Comparison operators used by `GeoDistance`.
+ *
+ * Mirrors `velesdb_core::velesql::ast::condition::CompareOp` which
+ * serializes with default (PascalCase) serde representation.
+ */
+type CompareOp = 'Eq' | 'NotEq' | 'Gt' | 'Gte' | 'Lt' | 'Lte';
+/**
+ * Discriminated union matching `velesdb_core::filter::Condition`.
+ *
+ * The wire format uses `{"type": "<snake_case_variant>", ...}` as produced
+ * by `#[serde(tag = "type", rename_all = "snake_case")]` on the Rust enum.
+ *
+ * 20 variants total — any change must stay in lock-step with the Rust source.
+ */
+type Condition = {
+    type: 'eq';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'neq';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'gt';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'gte';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'lt';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'lte';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'in';
+    field: string;
+    values: JsonValue[];
+} | {
+    type: 'contains';
+    field: string;
+    value: string;
+} | {
+    type: 'is_null';
+    field: string;
+} | {
+    type: 'is_not_null';
+    field: string;
+} | {
+    type: 'and';
+    conditions: Condition[];
+} | {
+    type: 'or';
+    conditions: Condition[];
+} | {
+    type: 'not';
+    condition: Condition;
+} | {
+    type: 'like';
+    field: string;
+    pattern: string;
+} | {
+    type: 'ilike';
+    field: string;
+    pattern: string;
+} | {
+    type: 'array_contains';
+    field: string;
+    value: JsonValue;
+} | {
+    type: 'array_contains_any';
+    field: string;
+    values: JsonValue[];
+} | {
+    type: 'array_contains_all';
+    field: string;
+    values: JsonValue[];
+} | {
+    type: 'geo_distance';
+    field: string;
+    lat: number;
+    lng: number;
+    operator: CompareOp;
+    threshold: number;
+} | {
+    type: 'geo_bbox';
+    field: string;
+    lat_min: number;
+    lng_min: number;
+    lat_max: number;
+    lng_max: number;
+};
+/**
+ * A filter for metadata-based search refinement.
+ *
+ * Mirrors `velesdb_core::filter::Filter` which wraps a root `Condition`.
+ */
+interface Filter {
+    condition: Condition;
+}
+/**
+ * Filter parameter type accepted by SDK methods.
+ *
+ * - `Filter`: typed filter produced by the `f.*` builders. **Recommended.**
+ * - `Record<string, unknown>`: raw JSON object for backward compatibility
+ *   with pre-v1.13 code. The payload is forwarded verbatim to the server.
+ */
+type FilterInput = Filter | Record<string, unknown>;
+/**
+ * Type guard narrowing a `FilterInput` to the typed `Filter` shape.
+ *
+ * Returns `true` only when the value has a `condition` property that is
+ * itself a non-null object. Does NOT validate the inner condition shape
+ * — use TypeScript's compile-time checking for that.
+ */
+declare function isTypedFilter(input: FilterInput): input is Filter;
+/**
+ * Normalizes a filter input to the wire format expected by velesdb-server.
+ *
+ * The SDK never rewrites filter payloads — it forwards them verbatim. This
+ * helper exists to keep backend code agnostic of whether the caller passed
+ * a typed `Filter` or a legacy `Record<string, unknown>`.
+ *
+ * Passing `undefined` returns `undefined`, signalling the server should
+ * apply no filter.
+ */
+declare function normalizeFilter(input: FilterInput): Record<string, unknown>;
+declare function normalizeFilter(input: undefined): undefined;
+declare function normalizeFilter(input: FilterInput | undefined): Record<string, unknown> | undefined;
+/**
+ * Fluent filter builder.
+ *
+ * Each method returns a new `Filter` whose root `condition` matches the
+ * wire format expected by `velesdb-server`. Builders do not mutate inputs:
+ * arrays passed to `in`, `arrayContainsAny`, `arrayContainsAll`, `and`, `or`
+ * are copied before being wrapped.
+ */
+declare const f: {
+    /** `field == value` */
+    readonly eq: (field: string, value: JsonValue) => Filter;
+    /** `field != value` */
+    readonly neq: (field: string, value: JsonValue) => Filter;
+    /** `field > value` */
+    readonly gt: (field: string, value: JsonValue) => Filter;
+    /** `field >= value` */
+    readonly gte: (field: string, value: JsonValue) => Filter;
+    /** `field < value` */
+    readonly lt: (field: string, value: JsonValue) => Filter;
+    /** `field <= value` */
+    readonly lte: (field: string, value: JsonValue) => Filter;
+    /** `field IN (values...)` — the values list is copied. */
+    readonly in: (field: string, values: JsonValue[]) => Filter;
+    /** Substring containment: `field LIKE '%value%'` (case-sensitive). */
+    readonly contains: (field: string, value: string) => Filter;
+    /** `field IS NULL` */
+    readonly isNull: (field: string) => Filter;
+    /** `field IS NOT NULL` */
+    readonly isNotNull: (field: string) => Filter;
+    /** SQL LIKE pattern matching (case-sensitive). Supports `%` and `_`. */
+    readonly like: (field: string, pattern: string) => Filter;
+    /** SQL ILIKE pattern matching (case-insensitive). */
+    readonly ilike: (field: string, pattern: string) => Filter;
+    /** `value IN field` (field must be an array). */
+    readonly arrayContains: (field: string, value: JsonValue) => Filter;
+    /** At least one of `values` is present in the array field. */
+    readonly arrayContainsAny: (field: string, values: JsonValue[]) => Filter;
+    /** Every value in `values` is present in the array field. */
+    readonly arrayContainsAll: (field: string, values: JsonValue[]) => Filter;
+    /** Haversine distance comparison: `distance(field, (lat, lng)) <op> threshold`. */
+    readonly geoDistance: (field: string, lat: number, lng: number, operator: CompareOp, threshold: number) => Filter;
+    /** Bounding-box containment: point field falls inside `[lat_min, lat_max] x [lng_min, lng_max]`. */
+    readonly geoBbox: (field: string, bounds: {
+        lat_min: number;
+        lng_min: number;
+        lat_max: number;
+        lng_max: number;
+    }) => Filter;
+    /** `field NOT IN (values...)` — shorthand for `not(in(field, values))`. */
+    readonly notIn: (field: string, values: JsonValue[]) => Filter;
+    /** `field BETWEEN low AND high` — shorthand for `and([gte(field, low), lte(field, high)])`. */
+    readonly between: (field: string, low: JsonValue, high: JsonValue) => Filter;
+    /** Logical AND — the filters list is copied and flattened to root conditions. */
+    readonly and: (filters: Filter[]) => Filter;
+    /** Logical OR — the filters list is copied and flattened to root conditions. */
+    readonly or: (filters: Filter[]) => Filter;
+    /** Logical NOT — wraps a single filter. */
+    readonly not: (filter: Filter) => Filter;
+};
+
+/**
+ * VelesDB TypeScript SDK - Search Type Definitions
+ *
+ * Search options, results, and fusion types.
+ * @packageDocumentation
+ */
+
 /** Search options */
 interface SearchOptions {
     /** Number of results to return (default: 10) */
     k?: number;
-    /** Filter expression (optional) */
-    filter?: Record<string, unknown>;
+    /** Filter expression (optional). Accepts typed `Filter` (recommended) or legacy raw JSON. */
+    filter?: FilterInput;
     /** Include vectors in results (default: false) */
     includeVectors?: boolean;
     /** Optional sparse vector for hybrid sparse+dense search */
@@ -92,15 +389,6 @@ interface SearchOptions {
     /** Search quality preset (default: 'balanced'). */
     quality?: SearchQuality;
 }
-/** PQ (Product Quantization) training options */
-interface PqTrainOptions {
-    /** Number of subquantizers (default: 8) */
-    m?: number;
-    /** Number of centroids per subquantizer (default: 256) */
-    k?: number;
-    /** Enable Optimized Product Quantization (default: false) */
-    opq?: boolean;
-}
 /** Fusion strategy for multi-query search */
 type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted' | 'relative_score';
 /** Multi-query search options */
@@ -119,9 +407,13 @@ interface MultiQuerySearchOptions {
         maxWeight?: number;
         /** Weighted fusion: hit weight (default: 0.1) */
         hitWeight?: number;
+        /** Relative score fusion: dense vector weight (default: 0.5) */
+        denseWeight?: number;
+        /** Relative score fusion: sparse vector weight (default: 0.5) */
+        sparseWeight?: number;
     };
-    /** Filter expression (optional) */
-    filter?: Record<string, unknown>;
+    /** Filter expression (optional). Accepts typed `Filter` (recommended) or legacy raw JSON. */
+    filter?: FilterInput;
 }
 /** Search result */
 interface SearchResult {
@@ -134,6 +426,14 @@ interface SearchResult {
     /** Vector data (if includeVectors is true) */
     vector?: number[];
 }
+
+/**
+ * VelesDB TypeScript SDK - Graph Type Definitions
+ *
+ * Knowledge graph types: edges, traversal, degree, graph collections.
+ * @packageDocumentation
+ */
+
 /** Graph edge representing a relationship between nodes */
 interface GraphEdge {
     /** Unique edge ID */
@@ -149,7 +449,7 @@ interface GraphEdge {
 }
 /**
  * Request to add an edge to the graph.
- * Structurally identical to GraphEdge — kept as a named alias for
+ * Structurally identical to GraphEdge -- kept as a named alias for
  * semantic clarity (input vs stored model).
  */
 type AddEdgeRequest = GraphEdge;
@@ -236,6 +536,13 @@ interface GraphCollectionConfig {
     /** Schema mode (default: 'schemaless') */
     schemaMode?: GraphSchemaMode;
 }
+
+/**
+ * VelesDB TypeScript SDK - Agent Memory Type Definitions
+ *
+ * Semantic, episodic, and procedural memory types.
+ * @packageDocumentation
+ */
 /** Semantic memory entry */
 interface SemanticEntry {
     /** Unique fact ID */
@@ -272,6 +579,74 @@ interface AgentMemoryConfig {
     /** Embedding dimension (default: 384) */
     dimension?: number;
 }
+
+/**
+ * VelesDB TypeScript SDK - Query & Introspection Type Definitions
+ *
+ * VelesQL query types, scroll, column stats, EXPLAIN, and collection sanity.
+ * @packageDocumentation
+ */
+
+/** Request parameters for cursor-based scroll pagination. */
+interface ScrollRequest {
+    /** Cursor position to resume from. Omit to start from beginning. */
+    cursor?: string | number;
+    /** Number of points per page (1-10000, default 100). */
+    batchSize?: number;
+    /** Optional filter expression. Accepts typed `Filter` (recommended) or legacy raw JSON. */
+    filter?: FilterInput;
+}
+/** Response from scroll pagination. */
+interface ScrollResponse {
+    /** Points in this page. */
+    points: Array<{
+        id: string | number;
+        vector?: number[];
+        payload?: Record<string, unknown>;
+    }>;
+    /** Cursor for next page, or null if no more results. */
+    nextCursor: string | number | null;
+}
+/** Per-column statistics including histogram metadata. */
+interface ColumnStatsDetail {
+    name: string;
+    nullCount: number;
+    distinctCount: number;
+    minValue: unknown | null;
+    maxValue: unknown | null;
+    avgSizeBytes: number;
+    histogramBuckets: number | null;
+    histogramStale: boolean | null;
+}
+/** Actual execution statistics from EXPLAIN ANALYZE. */
+interface ActualStats {
+    actualRows: number;
+    actualTimeMs: number;
+    loops: number;
+    nodesVisited: number;
+    edgesTraversed: number;
+}
+/**
+ * Per-node **estimated** execution statistics from EXPLAIN ANALYZE.
+ *
+ * All values are synthetic heuristics derived from the plan-global
+ * `actualTimeMs` -- they are NOT individually measured per node.
+ * Field names keep the `actual` prefix for API stability; check
+ * the `estimated` flag to distinguish heuristic values from future
+ * instrumented measurements.
+ */
+interface NodeStats {
+    nodeLabel: string;
+    /** Estimated wall-clock time for this node (ms). */
+    actualTimeMs: number;
+    /** Estimated rows entering this node. */
+    actualRowsIn: number;
+    /** Estimated rows leaving this node. */
+    actualRowsOut: number;
+    loops: number;
+    /** When true, all values are heuristic estimates, not measured. */
+    estimated: boolean;
+}
 /** Collection statistics response */
 interface CollectionStatsResponse {
     totalPoints: number;
@@ -281,17 +656,31 @@ interface CollectionStatsResponse {
     avgRowSizeBytes: number;
     payloadSizeBytes: number;
     lastAnalyzedEpochMs: number;
+    columnStats?: Record<string, ColumnStatsDetail>;
 }
-/** Collection configuration response */
+/** Collection configuration response. Mirrors `velesdb_core::api_types::CollectionConfigResponse`. */
 interface CollectionConfigResponse {
     name: string;
     dimension: number;
-    metric: string;
-    storageMode: string;
+    metric: DistanceMetric;
+    storageMode: StorageMode;
     pointCount: number;
     metadataOnly: boolean;
     graphSchema?: Record<string, unknown>;
     embeddingDimension?: number;
+    /**
+     * On-disk schema version. Increments when the persisted `config.json`
+     * format changes in a way older `VelesDB` versions cannot safely read.
+     */
+    schemaVersion?: number;
+    /** PQ rescore oversampling factor -- see `CollectionConfig.pqRescoreOversampling`. */
+    pqRescoreOversampling?: number;
+    /** Persisted HNSW parameters when customised at create time (raw server JSON). */
+    hnswParams?: Record<string, unknown>;
+    /** Deferred indexing configuration (`null` / absent when the feature is disabled for this collection). */
+    deferredIndexing?: Record<string, unknown>;
+    /** Async index builder configuration (`null` / absent when the feature is disabled for this collection). */
+    asyncIndexBuilder?: Record<string, unknown>;
 }
 /** VelesQL query options */
 interface QueryOptions {
@@ -304,9 +693,9 @@ interface QueryOptions {
  * Query result row from VelesQL query.
  *
  * Shape depends on the SELECT clause:
- * - `SELECT *` → `{id, field1, field2, ...}` (no vector)
- * - `SELECT col1, col2` → `{col1, col2}`
- * - `SELECT similarity() AS score, title` → `{score, title}`
+ * - `SELECT *` -> `{id, field1, field2, ...}` (no vector)
+ * - `SELECT col1, col2` -> `{col1, col2}`
+ * - `SELECT similarity() AS score, title` -> `{score, title}`
  */
 type QueryResult = Record<string, unknown>;
 /** Query execution statistics */
@@ -344,6 +733,7 @@ interface ExplainPlanStep {
     operation: string;
     description: string;
     estimatedRows: number | null;
+    estimationMethod: string | null;
 }
 interface ExplainCost {
     usesIndex: boolean;
@@ -369,6 +759,8 @@ interface ExplainResponse {
     plan: ExplainPlanStep[];
     estimatedCost: ExplainCost;
     features: ExplainFeatures;
+    actualStats?: ActualStats | null;
+    nodeStats?: NodeStats[] | null;
 }
 interface CollectionSanityChecks {
     hasVectors: boolean;
@@ -391,6 +783,13 @@ interface CollectionSanityResponse {
     diagnostics: CollectionSanityDiagnostics;
     hints: string[];
 }
+
+/**
+ * VelesDB TypeScript SDK - Index Management Type Definitions
+ *
+ * Property index types for secondary indexes.
+ * @packageDocumentation
+ */
 /** Index type for property indexes */
 type IndexType = 'hash' | 'range';
 /** Index information */
@@ -415,12 +814,271 @@ interface CreateIndexOptions {
     /** Index type: 'hash' (default) or 'range' */
     indexType?: IndexType;
 }
+
+/**
+ * VelesDB Backend Capability Map
+ *
+ * Static, per-backend description of which features the currently
+ * connected backend supports. Callers use this to gracefully degrade
+ * their UI / plan / workflow when a feature is not available instead
+ * of catching a runtime `NOT_SUPPORTED` error after the fact.
+ *
+ * The map is **frozen at backend construction** — it does not round-
+ * trip to the server. The REST map assumes a `velesdb-server` of the
+ * same minor version; if the server does not ship a given feature,
+ * the individual call will still surface a typed `VelesError` at
+ * runtime.
+ *
+ * @example
+ * ```typescript
+ * import { VelesDB } from '@wiscale/velesdb-sdk';
+ *
+ * const db = new VelesDB({ backend: 'wasm' });
+ * await db.init();
+ *
+ * if (db.capabilities().graphTraversal) {
+ *   await db.traverseGraph('kg', { source: 1, direction: 'out' });
+ * } else {
+ *   // fall back to REST or a pure in-memory traversal
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Capability map surfaced by `VelesDB.capabilities()`.
+ *
+ * Every field is a `boolean` so that callers can write
+ * `if (caps.feature) { ... }` without `?.` chaining. A missing
+ * backend must still expose the full set of keys with `false`
+ * values — we prefer explicit "unsupported" over "unknown".
+ */
+interface CapabilityMap {
+    /** Dense vector similarity search (`search`, `searchIds`, `searchBatch`). */
+    vectorSearch: boolean;
+    /** BM25 full-text search (`textSearch`). */
+    textSearch: boolean;
+    /** Combined dense + BM25 search (`hybridSearch`). */
+    hybridSearch: boolean;
+    /** Multi-query fusion search (`multiQuerySearch`). */
+    multiQuerySearch: boolean;
+    /** Sparse vector search (`sparse_vector` on the search body + hybrid sparse+dense). */
+    sparseSearch: boolean;
+    /** Cursor-based scroll pagination over a collection (`scroll`). */
+    scroll: boolean;
+    /** Knowledge graph edge CRUD + traversal (`addEdge`, `traverseGraph`, `traverseParallel`, `getNodeDegree`). */
+    graphTraversal: boolean;
+    /** Secondary property indexes (`createIndex`, `listIndexes`, `hasIndex`, `dropIndex`). */
+    secondaryIndexes: boolean;
+    /** Agent Memory SDK (semantic, episodic, procedural). */
+    agentMemory: boolean;
+    /** Streaming insert with backpressure (`streamInsert`). */
+    streamInsert: boolean;
+    /** Product quantization training (`trainPq`). */
+    pqTraining: boolean;
+    /** VelesQL multi-model query + EXPLAIN (`query`, `queryExplain`). */
+    velesqlQuery: boolean;
+    /** Collection introspection endpoints (`collectionSanity`, `getCollectionStats`, `analyzeCollection`, `getCollectionConfig`). */
+    collectionIntrospection: boolean;
+}
+/**
+ * Capability map for the REST backend — assumes a server of the
+ * same minor version as the SDK. Every feature the SDK wraps is
+ * advertised; individual endpoints may still surface a typed
+ * `VelesError` at runtime if the server was built with a feature
+ * flag disabled.
+ */
+declare const REST_CAPABILITIES: Readonly<CapabilityMap>;
+/**
+ * Capability map for the WASM backend.
+ *
+ * The WASM build ships a focused subset: the dense / text / hybrid /
+ * multi-query search paths plus VelesQL execution. Everything that
+ * relies on persistent on-disk structures (secondary indexes, graph,
+ * streaming, PQ training, agent memory, introspection, sparse
+ * inverted index) is explicitly `false`. See `backends/wasm-stubs.ts`
+ * for the exact set of `wasmNotSupported()` throw sites.
+ */
+declare const WASM_CAPABILITIES: Readonly<CapabilityMap>;
+
+/**
+ * VelesDB TypeScript SDK - Additional Endpoint Type Definitions
+ *
+ * Types for Sprint 2 Wave 4 endpoints: rebuild index, guardrails,
+ * aggregate, match query, graph node operations, and graph search.
+ * @packageDocumentation
+ */
+/** Result of `POST /collections/{name}/index/rebuild`. */
+interface RebuildIndexResponse {
+    /** Informational message from the server. */
+    message: string;
+    /** Collection name. */
+    collection: string;
+    /** Number of tombstoned entries compacted during rebuild. */
+    compactedEntries: number;
+}
+/** Guard-rails config sent to `PUT /guardrails` (partial update). */
+interface GuardRailsUpdateRequest {
+    maxDepth?: number;
+    maxCardinality?: number;
+    memoryLimitBytes?: number;
+    timeoutMs?: number;
+    rateLimitQps?: number;
+    circuitFailureThreshold?: number;
+    circuitRecoverySeconds?: number;
+}
+/** Guard-rails config returned by `GET /guardrails` and `PUT /guardrails`. */
+interface GuardRailsConfigResponse {
+    maxDepth: number;
+    maxCardinality: number;
+    memoryLimitBytes: number;
+    timeoutMs: number;
+    rateLimitQps: number;
+    circuitFailureThreshold: number;
+    circuitRecoverySeconds: number;
+}
+/** Options for `listNodes`. */
+interface ListNodesResponse {
+    /** Node IDs in insertion order. */
+    nodeIds: number[];
+    /** Total count -- matches `nodeIds.length`. */
+    count: number;
+}
+/** Options for `getNodeEdges`. Mirrors `NodeEdgeQueryParams` on the server. */
+interface GetNodeEdgesOptions {
+    /** Edge direction: "in", "out" (default), or "both". */
+    direction?: 'in' | 'out' | 'both';
+    /** Optional label filter. */
+    label?: string;
+}
+/** Result of `GET /collections/{name}/graph/nodes/{id}/payload`. */
+interface NodePayloadResponse {
+    /** Node ID. */
+    nodeId: number;
+    /** Stored payload -- `null` if no payload has been set. */
+    payload: Record<string, unknown> | null;
+}
+/** Request body for `POST /collections/{name}/graph/search`. */
+interface GraphSearchRequest {
+    /** Query vector for embedding similarity. */
+    vector: number[] | Float32Array;
+    /** Number of results (default: 10). */
+    k?: number;
+}
+/** Single result item from `graphSearch`. */
+interface GraphSearchResultItem {
+    /** Node ID. */
+    id: number;
+    /** Similarity score. */
+    score: number;
+    /** Optional node payload (mirror of `GraphSearchResultItem.payload`). */
+    payload?: Record<string, unknown> | null;
+}
+/** Response of `graphSearch`. */
+interface GraphSearchResponse {
+    /** Result items ordered by score. */
+    results: GraphSearchResultItem[];
+}
+/**
+ * Options for `matchQuery`. Mirrors the extra fields accepted by
+ * `velesdb_server::handlers::match_query::MatchQueryRequest`
+ * beyond `query` and `params`.
+ */
+interface MatchQueryOptions {
+    /** Query vector for `similarity()` scoring inside the MATCH clause. */
+    vector?: number[] | Float32Array;
+    /** Similarity threshold (0.0-1.0). */
+    threshold?: number;
+}
+/** Response from `POST /collections/{name}/match`. Mirrors the Rust
+ * `MatchQueryResponse` struct -- intentionally distinct from the
+ * `/query` and `/aggregate` response shapes. */
+interface MatchQueryResponse {
+    /** Pattern matches returned by the MATCH clause. */
+    results: MatchQueryResultItem[];
+    /** Server-side execution time in whole milliseconds. */
+    tookMs: number;
+    /** Number of result rows (matches `results.length`). */
+    count: number;
+    /** Response metadata (VelesQL contract version). */
+    meta: {
+        velesqlContractVersion: string;
+    };
+}
+/** Single row of a `MatchQueryResponse`. */
+interface MatchQueryResultItem {
+    /** Variable-binding map from the MATCH pattern. */
+    bindings: Record<string, number>;
+    /** Similarity score, present only when `similarity()` was used. */
+    score?: number;
+    /** Traversal depth reached to produce this row. */
+    depth: number;
+    /** Projected properties from the RETURN clause. */
+    projected: Record<string, unknown>;
+}
+/** Options for `aggregate`. Mirrors the extra fields accepted by
+ * `velesdb_core::api_types::QueryRequest` beyond `query` and `params`. */
+interface AggregateQueryOptions {
+    /**
+     * Optional collection name when the query string does not carry an
+     * explicit `FROM <collection>` clause.
+     */
+    collection?: string;
+}
+/** Response from `POST /aggregate`. Mirrors the Rust `AggregationResponse`. */
+interface AggregateResponse {
+    /** Aggregation result -- shape depends on the SELECT clause. */
+    result: unknown;
+    /** Query execution time in milliseconds. */
+    timingMs: number;
+    /** Response metadata. */
+    meta: {
+        velesqlContractVersion: string;
+        count: number;
+    };
+}
+/**
+ * Response from `POST /collections/{name}/points/stream` (NDJSON batch upsert).
+ *
+ * The server returns statistics about the stream processing: how many points
+ * were inserted, how many were malformed, how many upserts failed, and how
+ * many network errors occurred while reading the request body.
+ */
+interface StreamUpsertResponse {
+    /** Informational message from the server. */
+    message: string;
+    /** Number of points successfully upserted. */
+    inserted: number;
+    /** Number of NDJSON lines that could not be parsed as a valid Point. */
+    malformed: number;
+    /** Number of points where the upsert operation itself failed. */
+    failedUpserts: number;
+    /** Number of HTTP body stream read errors (non-zero means truncated transfer). */
+    networkErrors: number;
+}
+
+/**
+ * VelesDB TypeScript SDK - Backend Interface
+ *
+ * The `IVelesDBBackend` interface that all backends must implement.
+ * @packageDocumentation
+ */
+
 /** Backend interface that all backends must implement */
 interface IVelesDBBackend {
     /** Initialize the backend */
     init(): Promise<void>;
     /** Check if backend is initialized */
     isInitialized(): boolean;
+    /**
+     * Return the static capability map for this backend.
+     *
+     * The map is frozen at backend construction -- it does NOT round-trip
+     * to a live server. Use it to gracefully degrade UI / workflow when
+     * a feature is not available instead of catching a runtime
+     * `NOT_SUPPORTED` error after the fact.
+     */
+    capabilities(): Readonly<CapabilityMap>;
     /** Create a new collection */
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     /** Delete a collection */
@@ -429,10 +1087,10 @@ interface IVelesDBBackend {
     getCollection(name: string): Promise<Collection | null>;
     /** List all collections */
     listCollections(): Promise<Collection[]>;
-    /** Insert a single vector */
-    insert(collection: string, doc: VectorDocument): Promise<void>;
-    /** Insert multiple vectors */
-    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    /** Upsert (insert or replace) a single vector */
+    upsert(collection: string, doc: VectorDocument): Promise<void>;
+    /** Upsert (insert or replace) multiple vectors */
+    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
     /** Search for similar vectors */
     search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
     /** Delete a vector by ID */
@@ -443,23 +1101,29 @@ interface IVelesDBBackend {
     searchBatch(collection: string, searches: Array<{
         vector: number[] | Float32Array;
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
+        /** Per-sub-request search quality preset (default: server default). */
+        quality?: SearchQuality;
     }>): Promise<SearchResult[][]>;
     /** Full-text search using BM25 */
     textSearch(collection: string, query: string, options?: {
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
     /** Hybrid search combining vector and text */
     hybridSearch(collection: string, vector: number[] | Float32Array, textQuery: string, options?: {
         k?: number;
         vectorWeight?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
     /** Execute VelesQL multi-model query (EPIC-031 US-011) */
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     /** Explain a VelesQL query without executing it */
-    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
+        analyze?: boolean;
+    }): Promise<ExplainResponse>;
+    /** Scroll through collection points with cursor-based pagination */
+    scroll(collection: string, request?: ScrollRequest): Promise<ScrollResponse>;
     /** Run collection sanity checks */
     collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     /** Multi-query fusion search */
@@ -492,6 +1156,14 @@ interface IVelesDBBackend {
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
     streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
+    /**
+     * Batch upsert points via the NDJSON streaming endpoint.
+     *
+     * Sends all documents as a single NDJSON request to
+     * `POST /collections/{name}/points/stream` (up to 100 MB).
+     * Returns server-side processing statistics.
+     */
+    streamUpsertPoints(collection: string, docs: VectorDocument[]): Promise<StreamUpsertResponse>;
     /** Create a graph collection */
     createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
     /** Get collection statistics */
@@ -517,7 +1189,38 @@ interface IVelesDBBackend {
     storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<void>;
     /** Match procedural patterns */
     matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    /** Rebuild a collection's HNSW index (compacts tombstones). */
+    rebuildIndex(collection: string): Promise<RebuildIndexResponse>;
+    /** Read the current process-wide guard-rails configuration. */
+    getGuardrails(): Promise<GuardRailsConfigResponse>;
+    /** Partial-update the process-wide guard-rails configuration. */
+    updateGuardrails(req: GuardRailsUpdateRequest): Promise<GuardRailsConfigResponse>;
+    /** Execute a VelesQL aggregate query (COUNT/AVG/GROUP BY/...). */
+    aggregate(queryString: string, params?: Record<string, unknown>, options?: AggregateQueryOptions): Promise<AggregateResponse>;
+    /** Execute a VelesQL `MATCH (...)` graph query scoped to a collection. */
+    matchQuery(collection: string, queryString: string, params?: Record<string, unknown>, options?: MatchQueryOptions): Promise<MatchQueryResponse>;
+    /** Remove a graph edge by ID. Returns `true` if removed, `false` if not found. */
+    removeEdge(collection: string, edgeId: number): Promise<boolean>;
+    /** Total edge count in a graph collection. */
+    getEdgeCount(collection: string): Promise<number>;
+    /** List every node ID in a graph collection. */
+    listNodes(collection: string): Promise<ListNodesResponse>;
+    /** Get edges adjacent to a node (filterable by direction + label). */
+    getNodeEdges(collection: string, nodeId: number, options?: GetNodeEdgesOptions): Promise<GraphEdge[]>;
+    /** Read the JSON payload attached to a graph node. */
+    getNodePayload(collection: string, nodeId: number): Promise<NodePayloadResponse>;
+    /** Upsert (create or replace) the JSON payload of a graph node. */
+    upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
+    /** Vector similarity search scoped to graph nodes only. */
+    graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
 }
+
+/**
+ * VelesDB TypeScript SDK - Error Type Definitions
+ *
+ * SDK-level error classes for transport and validation errors.
+ * @packageDocumentation
+ */
 /** Error types */
 declare class VelesDBError extends Error {
     readonly code: string;
@@ -577,459 +1280,91 @@ declare class AgentMemoryClient {
  *
  * Provides a unified interface for interacting with VelesDB
  * using either WASM (browser/Node.js) or REST API backends.
- *
- * @example
- * ```typescript
- * const db = new VelesDB({ backend: 'wasm' });
- * await db.init();
- *
- * await db.createCollection('embeddings', { dimension: 768, metric: 'cosine' });
- * await db.insert('embeddings', { id: 'doc1', vector: [...], payload: { title: 'Hello' } });
- *
- * const results = await db.search('embeddings', queryVector, { k: 5 });
- * ```
  */
 declare class VelesDB {
     private readonly config;
     private backend;
     private initialized;
-    /**
-     * Create a new VelesDB client
-     *
-     * @param config - Client configuration
-     * @throws {ValidationError} If configuration is invalid
-     */
     constructor(config: VelesDBConfig);
     private validateConfig;
     private createBackend;
-    /**
-     * Initialize the client
-     * Must be called before any other operations
-     */
+    /** Initialize the client. Must be called before any other operations. */
     init(): Promise<void>;
-    /**
-     * Check if client is initialized
-     */
+    /** Check if client is initialized. */
     isInitialized(): boolean;
     private ensureInitialized;
-    /**
-     * Create a new collection
-     *
-     * @param name - Collection name
-     * @param config - Collection configuration
-     */
     createCollection(name: string, config: CollectionConfig): Promise<void>;
-    /**
-     * Create a metadata-only collection (no vectors, just payload data)
-     *
-     * Useful for storing reference data that can be JOINed with vector collections.
-     *
-     * @param name - Collection name
-     *
-     * @example
-     * ```typescript
-     * await db.createMetadataCollection('products');
-     * await db.insertMetadata('products', { id: 'P001', name: 'Widget', price: 99 });
-     * ```
-     */
     createMetadataCollection(name: string): Promise<void>;
-    /**
-     * Delete a collection
-     *
-     * @param name - Collection name
-     */
     deleteCollection(name: string): Promise<void>;
-    /**
-     * Get collection information
-     *
-     * @param name - Collection name
-     * @returns Collection info or null if not found
-     */
     getCollection(name: string): Promise<Collection | null>;
-    /**
-     * List all collections
-     *
-     * @returns Array of collections
-     */
     listCollections(): Promise<Collection[]>;
-    /**
-     * Insert a vector document
-     *
-     * @param collection - Collection name
-     * @param doc - Document to insert
-     */
-    insert(collection: string, doc: VectorDocument): Promise<void>;
-    /**
-     * Insert multiple vector documents
-     *
-     * @param collection - Collection name
-     * @param docs - Documents to insert
-     */
-    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
-    private validateDocument;
-    private validateRestPointId;
-    /**
-     * Search for similar vectors
-     *
-     * @param collection - Collection name
-     * @param query - Query vector
-     * @param options - Search options
-     * @returns Search results sorted by relevance
-     */
+    upsert(collection: string, doc: VectorDocument): Promise<void>;
+    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    delete(collection: string, id: string | number): Promise<boolean>;
+    get(collection: string, id: string | number): Promise<VectorDocument | null>;
+    isEmpty(collection: string): Promise<boolean>;
+    flush(collection: string): Promise<void>;
+    close(): Promise<void>;
     search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
-    /**
-     * Search for multiple vectors in parallel
-     *
-     * @param collection - Collection name
-     * @param searches - List of search queries
-     * @returns List of search results for each query
-     */
     searchBatch(collection: string, searches: Array<{
         vector: number[] | Float32Array;
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
+        quality?: SearchQuality;
     }>): Promise<SearchResult[][]>;
-    /**
-     * Delete a vector by ID
-     *
-     * @param collection - Collection name
-     * @param id - Document ID
-     * @returns true if deleted, false if not found
-     */
-    delete(collection: string, id: string | number): Promise<boolean>;
-    /**
-     * Get a vector by ID
-     *
-     * @param collection - Collection name
-     * @param id - Document ID
-     * @returns Document or null if not found
-     */
-    get(collection: string, id: string | number): Promise<VectorDocument | null>;
-    /**
-     * Perform full-text search using BM25
-     *
-     * @param collection - Collection name
-     * @param query - Text query
-     * @param options - Search options (k, filter)
-     * @returns Search results sorted by BM25 score
-     */
     textSearch(collection: string, query: string, options?: {
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
-    /**
-     * Perform hybrid search combining vector similarity and BM25 text search
-     *
-     * @param collection - Collection name
-     * @param vector - Query vector
-     * @param textQuery - Text query for BM25
-     * @param options - Search options (k, vectorWeight, filter)
-     * @returns Search results sorted by fused score
-     */
     hybridSearch(collection: string, vector: number[] | Float32Array, textQuery: string, options?: {
         k?: number;
         vectorWeight?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
-    /**
-     * Execute a VelesQL multi-model query (EPIC-031 US-011)
-     *
-     * Supports hybrid vector + graph queries with VelesQL syntax.
-     *
-     * @param collection - Collection name
-     * @param queryString - VelesQL query string
-     * @param params - Query parameters (vectors, scalars).
-     *   For cross-collection MATCH queries, pass `_collection` to specify the
-     *   primary collection (the one with graph edges). Nodes annotated with
-     *   `@collection` in the MATCH pattern will have their payloads enriched
-     *   from the named collection after traversal.
-     * @param options - Query options (timeout, streaming)
-     * @returns Query response with results and execution stats
-     *
-     * @example
-     * ```typescript
-     * const response = await db.query('docs', `
-     *   MATCH (d:Doc) WHERE vector NEAR $q LIMIT 20
-     * `, { q: queryVector });
-     *
-     * for (const r of response.results) {
-     *   console.log(`ID ${r.id}, title: ${r.title}`);
-     * }
-     * ```
-     *
-     * @example Cross-collection MATCH
-     * ```typescript
-     * // Enrich Product nodes with Inventory data from the 'inventory' collection
-     * const response = await db.query('catalog_graph', `
-     *   MATCH (p:Product)-[:STORED_IN]->(inv:Inventory@inventory)
-     *   RETURN p.name, inv.price, inv.stock
-     *   LIMIT 20
-     * `);
-     * ```
-     */
+    multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
-    /**
-     * Explain the execution plan for a VelesQL query without running it
-     *
-     * @param queryString - VelesQL query string to explain
-     * @param params - Optional query parameters (vectors, scalars)
-     * @returns Explain response with the query execution plan
-     */
-    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
+        analyze?: boolean;
+    }): Promise<ExplainResponse>;
     collectionSanity(collection: string): Promise<CollectionSanityResponse>;
-    /**
-     * Multi-query fusion search combining results from multiple query vectors
-     *
-     * Ideal for RAG pipelines using Multiple Query Generation (MQG).
-     *
-     * @param collection - Collection name
-     * @param vectors - Array of query vectors
-     * @param options - Search options (k, fusion strategy, fusionParams, filter)
-     * @returns Fused search results
-     *
-     * @example
-     * ```typescript
-     * // RRF fusion (default)
-     * const results = await db.multiQuerySearch('docs', [emb1, emb2, emb3], {
-     *   k: 10,
-     *   fusion: 'rrf',
-     *   fusionParams: { k: 60 }
-     * });
-     *
-     * // Weighted fusion
-     * const results = await db.multiQuerySearch('docs', [emb1, emb2], {
-     *   k: 10,
-     *   fusion: 'weighted',
-     *   fusionParams: { avgWeight: 0.6, maxWeight: 0.3, hitWeight: 0.1 }
-     * });
-     * ```
-     */
-    multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
-    /**
-     * Train Product Quantization on a collection
-     *
-     * @param collection - Collection name
-     * @param options - PQ training options (m, k, opq)
-     * @returns Server response message
-     */
+    scroll(collection: string, request?: ScrollRequest): Promise<ScrollResponse>;
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
-    /**
-     * Stream-insert documents with backpressure support
-     *
-     * Sends documents sequentially to respect server backpressure.
-     * Throws BackpressureError on 429 responses.
-     *
-     * @param collection - Collection name
-     * @param docs - Documents to insert
-     */
     streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
-    /**
-     * Check if a collection is empty
-     *
-     * @param collection - Collection name
-     * @returns true if empty, false otherwise
-     */
-    isEmpty(collection: string): Promise<boolean>;
-    /**
-     * Flush pending changes to disk
-     *
-     * @param collection - Collection name
-     */
-    flush(collection: string): Promise<void>;
-    /**
-     * Close the client and release resources
-     */
-    close(): Promise<void>;
-    /**
-     * Get the current backend type
-     */
-    get backendType(): string;
-    /**
-     * Create a property index for O(1) equality lookups or O(log n) range queries
-     *
-     * @param collection - Collection name
-     * @param options - Index configuration (label, property, indexType)
-     *
-     * @example
-     * ```typescript
-     * // Create hash index for fast email lookups
-     * await db.createIndex('users', { label: 'Person', property: 'email' });
-     *
-     * // Create range index for timestamp queries
-     * await db.createIndex('events', { label: 'Event', property: 'timestamp', indexType: 'range' });
-     * ```
-     */
+    streamUpsertPoints(collection: string, docs: VectorDocument[]): Promise<StreamUpsertResponse>;
+    searchIds(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<Array<{
+        id: number;
+        score: number;
+    }>>;
+    rebuildIndex(collection: string): Promise<RebuildIndexResponse>;
+    getGuardrails(): Promise<GuardRailsConfigResponse>;
+    updateGuardrails(req: GuardRailsUpdateRequest): Promise<GuardRailsConfigResponse>;
+    aggregate(queryString: string, params?: Record<string, unknown>, options?: AggregateQueryOptions): Promise<AggregateResponse>;
+    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
+    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
+    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
-    /**
-     * List all indexes on a collection
-     *
-     * @param collection - Collection name
-     * @returns Array of index information
-     */
     listIndexes(collection: string): Promise<IndexInfo[]>;
-    /**
-     * Check if an index exists
-     *
-     * @param collection - Collection name
-     * @param label - Node label
-     * @param property - Property name
-     * @returns true if index exists
-     */
     hasIndex(collection: string, label: string, property: string): Promise<boolean>;
-    /**
-     * Drop an index
-     *
-     * @param collection - Collection name
-     * @param label - Node label
-     * @param property - Property name
-     * @returns true if index was dropped, false if it didn't exist
-     */
     dropIndex(collection: string, label: string, property: string): Promise<boolean>;
-    /**
-     * Add an edge to the collection's knowledge graph
-     *
-     * @param collection - Collection name
-     * @param edge - Edge to add (id, source, target, label, properties)
-     *
-     * @example
-     * ```typescript
-     * await db.addEdge('social', {
-     *   id: 1,
-     *   source: 100,
-     *   target: 200,
-     *   label: 'FOLLOWS',
-     *   properties: { since: '2024-01-01' }
-     * });
-     * ```
-     */
     addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
-    /**
-     * Get edges from the collection's knowledge graph
-     *
-     * @param collection - Collection name
-     * @param options - Query options (filter by label)
-     * @returns Array of edges
-     *
-     * @example
-     * ```typescript
-     * // Get all edges with label "FOLLOWS"
-     * const edges = await db.getEdges('social', { label: 'FOLLOWS' });
-     * ```
-     */
     getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
-    /**
-     * Traverse the graph using BFS or DFS from a source node
-     *
-     * @param collection - Collection name
-     * @param request - Traversal request options
-     * @returns Traversal response with results and stats
-     *
-     * @example
-     * ```typescript
-     * // BFS traversal from node 100
-     * const result = await db.traverseGraph('social', {
-     *   source: 100,
-     *   strategy: 'bfs',
-     *   maxDepth: 3,
-     *   limit: 100,
-     *   relTypes: ['FOLLOWS', 'KNOWS']
-     * });
-     *
-     * for (const node of result.results) {
-     *   console.log(`Reached node ${node.targetId} at depth ${node.depth}`);
-     * }
-     * ```
-     */
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
-    /**
-     * Multi-source parallel BFS traversal with deduplication.
-     *
-     * Starts BFS from multiple source nodes simultaneously and deduplicates
-     * results by path signature.
-     *
-     * @param collection - Collection name
-     * @param request - Parallel traverse request with sources array
-     * @returns Traverse response with results, stats, and pagination
-     *
-     * @example
-     * ```typescript
-     * const result = await db.traverseParallel('social', {
-     *   sources: [100, 200, 300],
-     *   maxDepth: 3,
-     *   limit: 50,
-     * });
-     * ```
-     */
     traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
-    /**
-     * Get the in-degree and out-degree of a node
-     *
-     * @param collection - Collection name
-     * @param nodeId - Node ID
-     * @returns Degree response with inDegree and outDegree
-     *
-     * @example
-     * ```typescript
-     * const degree = await db.getNodeDegree('social', 100);
-     * console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
-     * ```
-     */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
-    /**
-     * Create a graph collection
-     *
-     * @param name - Collection name
-     * @param config - Optional graph collection configuration
-     */
     createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
-    /**
-     * Get collection statistics (requires prior analyze)
-     *
-     * @param collection - Collection name
-     * @returns Statistics or null if not yet analyzed
-     */
-    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
-    /**
-     * Analyze a collection to compute statistics
-     *
-     * @param collection - Collection name
-     * @returns Computed statistics
-     */
-    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
-    /**
-     * Get collection configuration
-     *
-     * @param collection - Collection name
-     * @returns Collection configuration details
-     */
-    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
-    /**
-     * Search returning only IDs and scores (lightweight)
-     *
-     * @param collection - Collection name
-     * @param query - Query vector
-     * @param options - Search options
-     * @returns Array of id/score pairs
-     */
-    searchIds(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<Array<{
-        id: number;
-        score: number;
-    }>>;
-    /**
-     * Create an agent memory interface
-     *
-     * @param config - Optional agent memory configuration
-     * @returns AgentMemoryClient instance
-     */
+    matchQuery(collection: string, queryString: string, params?: Record<string, unknown>, options?: MatchQueryOptions): Promise<MatchQueryResponse>;
+    removeEdge(collection: string, edgeId: number): Promise<boolean>;
+    getEdgeCount(collection: string): Promise<number>;
+    listNodes(collection: string): Promise<ListNodesResponse>;
+    getNodeEdges(collection: string, nodeId: number, options?: GetNodeEdgesOptions): Promise<GraphEdge[]>;
+    getNodePayload(collection: string, nodeId: number): Promise<NodePayloadResponse>;
+    upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
+    graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
+    capabilities(): Readonly<CapabilityMap>;
+    get backendType(): string;
     agentMemory(config?: AgentMemoryConfig): AgentMemoryClient;
 }
 
-/**
- * WASM Backend for VelesDB
- *
- * Uses velesdb-wasm for in-browser/Node.js vector operations
- */
-
 /**
  * WASM Backend
  *
@@ -1042,67 +1377,80 @@ declare class WasmBackend implements IVelesDBBackend {
     private _initialized;
     init(): Promise<void>;
     isInitialized(): boolean;
+    close(): Promise<void>;
+    capabilities(): Readonly<CapabilityMap>;
     private ensureInitialized;
-    private normalizeIdString;
-    private canonicalPayloadKeyFromResultId;
-    private canonicalPayloadKey;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
     getCollection(name: string): Promise<Collection | null>;
     listCollections(): Promise<Collection[]>;
-    insert(collectionName: string, doc: VectorDocument): Promise<void>;
-    insertBatch(collectionName: string, docs: VectorDocument[]): Promise<void>;
-    search(collectionName: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
-    searchBatch(collectionName: string, searches: Array<{
+    upsert(collectionName: string, doc: VectorDocument): Promise<void>;
+    upsertBatch(collectionName: string, docs: VectorDocument[]): Promise<void>;
+    delete(collectionName: string, id: string | number): Promise<boolean>;
+    get(collectionName: string, id: string | number): Promise<VectorDocument | null>;
+    isEmpty(collectionName: string): Promise<boolean>;
+    flush(collectionName: string): Promise<void>;
+    search(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<SearchResult[]>;
+    searchBatch(c: string, s: Array<{
         vector: number[] | Float32Array;
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
+        quality?: SearchQuality;
     }>): Promise<SearchResult[][]>;
-    delete(collectionName: string, id: string | number): Promise<boolean>;
-    get(collectionName: string, id: string | number): Promise<VectorDocument | null>;
-    textSearch(_collection: string, _query: string, _options?: {
+    textSearch(c: string, q: string, o?: {
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
-    hybridSearch(_collection: string, _vector: number[] | Float32Array, _textQuery: string, _options?: {
+    hybridSearch(c: string, v: number[] | Float32Array, t: string, o?: {
         k?: number;
         vectorWeight?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
-    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryApiResponse>;
-    multiQuerySearch(_collection: string, _vectors: Array<number[] | Float32Array>, _options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
-    queryExplain(_queryString: string, _params?: Record<string, unknown>): Promise<ExplainResponse>;
-    collectionSanity(_collection: string): Promise<CollectionSanityResponse>;
-    isEmpty(collectionName: string): Promise<boolean>;
-    flush(collectionName: string): Promise<void>;
-    close(): Promise<void>;
-    private sparseVectorToArrays;
-    private toNumericId;
-    createIndex(_collection: string, _options: CreateIndexOptions): Promise<void>;
-    listIndexes(_collection: string): Promise<IndexInfo[]>;
-    hasIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
-    dropIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
-    addEdge(_collection: string, _edge: AddEdgeRequest): Promise<void>;
-    getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
-    traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
-    traverseParallel(_collection: string, _request: TraverseParallelRequest): Promise<TraverseResponse>;
-    getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
-    trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
-    streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
-    createGraphCollection(_name: string, _config?: GraphCollectionConfig): Promise<void>;
-    getCollectionStats(_collection: string): Promise<CollectionStatsResponse | null>;
-    analyzeCollection(_collection: string): Promise<CollectionStatsResponse>;
-    getCollectionConfig(_collection: string): Promise<CollectionConfigResponse>;
-    searchIds(_collection: string, _query: number[] | Float32Array, _options?: SearchOptions): Promise<Array<{
+    query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
+    multiQuerySearch(c: string, v: Array<number[] | Float32Array>, o?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    queryExplain(q: string, p?: Record<string, unknown>, o?: {
+        analyze?: boolean;
+    }): Promise<ExplainResponse>;
+    collectionSanity(c: string): Promise<CollectionSanityResponse>;
+    scroll(c: string, r?: ScrollRequest): Promise<ScrollResponse>;
+    createIndex(c: string, o: CreateIndexOptions): Promise<void>;
+    listIndexes(c: string): Promise<IndexInfo[]>;
+    hasIndex(c: string, l: string, p: string): Promise<boolean>;
+    dropIndex(c: string, l: string, p: string): Promise<boolean>;
+    addEdge(c: string, e: AddEdgeRequest): Promise<void>;
+    getEdges(c: string, o?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(c: string, r: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(c: string, r: TraverseParallelRequest): Promise<TraverseResponse>;
+    getNodeDegree(c: string, n: number): Promise<DegreeResponse>;
+    trainPq(c: string, o?: PqTrainOptions): Promise<string>;
+    streamInsert(c: string, d: VectorDocument[]): Promise<void>;
+    streamUpsertPoints(c: string, d: VectorDocument[]): Promise<StreamUpsertResponse>;
+    createGraphCollection(n: string, c?: GraphCollectionConfig): Promise<void>;
+    getCollectionStats(c: string): Promise<CollectionStatsResponse | null>;
+    analyzeCollection(c: string): Promise<CollectionStatsResponse>;
+    getCollectionConfig(c: string): Promise<CollectionConfigResponse>;
+    searchIds(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<Array<{
         id: number;
         score: number;
     }>>;
-    storeSemanticFact(_collection: string, _entry: SemanticEntry): Promise<void>;
-    searchSemanticMemory(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(_collection: string, _event: EpisodicEvent): Promise<void>;
-    recallEpisodicEvents(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(_collection: string, _pattern: ProceduralPattern): Promise<void>;
-    matchProceduralPatterns(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
+    storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
+    searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<void>;
+    recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<void>;
+    matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
+    rebuildIndex(c: string): Promise<RebuildIndexResponse>;
+    getGuardrails(): Promise<GuardRailsConfigResponse>;
+    updateGuardrails(r: GuardRailsUpdateRequest): Promise<GuardRailsConfigResponse>;
+    aggregate(_q: string, _p?: Record<string, unknown>, _o?: AggregateQueryOptions): Promise<AggregateResponse>;
+    matchQuery(c: string, q: string, p?: Record<string, unknown>, o?: MatchQueryOptions): Promise<MatchQueryResponse>;
+    removeEdge(c: string, id: number): Promise<boolean>;
+    getEdgeCount(c: string): Promise<number>;
+    listNodes(c: string): Promise<ListNodesResponse>;
+    getNodeEdges(c: string, id: number, o?: GetNodeEdgesOptions): Promise<GraphEdge[]>;
+    getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
+    upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
+    graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
 }
 
 /**
@@ -1110,6 +1458,7 @@ declare class WasmBackend implements IVelesDBBackend {
  *
  * Connects to VelesDB server via REST API.
  * This is the composition root that delegates to focused backend modules.
+ * HTTP infrastructure lives in rest-http.ts.
  */
 
 /**
@@ -1118,48 +1467,51 @@ declare class WasmBackend implements IVelesDBBackend {
  * Provides vector storage via VelesDB REST API server.
  */
 declare class RestBackend implements IVelesDBBackend {
-    private readonly baseUrl;
-    private readonly apiKey?;
-    private readonly timeout;
+    private readonly httpConfig;
     private _initialized;
     constructor(url: string, apiKey?: string, timeout?: number);
     init(): Promise<void>;
     isInitialized(): boolean;
+    capabilities(): Readonly<CapabilityMap>;
+    close(): Promise<void>;
     private ensureInitialized;
-    private mapStatusToErrorCode;
-    private extractErrorPayload;
-    private parseNodeId;
-    private request;
-    private asCrudTransport;
-    private asSearchTransport;
-    private asAgentMemoryTransport;
-    private asQueryTransport;
-    private asStreamingTransport;
-    createCollection(name: string, config: CollectionConfig): Promise<void>;
-    deleteCollection(name: string): Promise<void>;
-    getCollection(name: string): Promise<Collection | null>;
+    createCollection(n: string, c: CollectionConfig): Promise<void>;
+    deleteCollection(n: string): Promise<void>;
+    getCollection(n: string): Promise<Collection | null>;
     listCollections(): Promise<Collection[]>;
-    insert(collection: string, doc: VectorDocument): Promise<void>;
-    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
-    delete(collection: string, id: string | number): Promise<boolean>;
-    get(collection: string, id: string | number): Promise<VectorDocument | null>;
-    isEmpty(collection: string): Promise<boolean>;
-    flush(collection: string): Promise<void>;
-    close(): Promise<void>;
+    upsert(c: string, d: VectorDocument): Promise<void>;
+    upsertBatch(c: string, d: VectorDocument[]): Promise<void>;
+    delete(c: string, id: string | number): Promise<boolean>;
+    get(c: string, id: string | number): Promise<VectorDocument | null>;
+    isEmpty(c: string): Promise<boolean>;
+    flush(c: string): Promise<void>;
+    rebuildIndex(c: string): Promise<RebuildIndexResponse>;
+    getGuardrails(): Promise<GuardRailsConfigResponse>;
+    updateGuardrails(r: GuardRailsUpdateRequest): Promise<GuardRailsConfigResponse>;
+    aggregate(q: string, p?: Record<string, unknown>, o?: AggregateQueryOptions): Promise<AggregateResponse>;
+    matchQuery(c: string, q: string, p?: Record<string, unknown>, o?: MatchQueryOptions): Promise<MatchQueryResponse>;
+    removeEdge(c: string, id: number): Promise<boolean>;
+    getEdgeCount(c: string): Promise<number>;
+    listNodes(c: string): Promise<ListNodesResponse>;
+    getNodeEdges(c: string, id: number, o?: GetNodeEdgesOptions): Promise<GraphEdge[]>;
+    getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
+    upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
+    graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
     search(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<SearchResult[]>;
-    searchBatch(collection: string, searches: Array<{
+    searchBatch(c: string, s: Array<{
         vector: number[] | Float32Array;
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
+        quality?: SearchQuality;
     }>): Promise<SearchResult[][]>;
     textSearch(c: string, q: string, o?: {
         k?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
     hybridSearch(c: string, v: number[] | Float32Array, t: string, o?: {
         k?: number;
         vectorWeight?: number;
-        filter?: Record<string, unknown>;
+        filter?: FilterInput;
     }): Promise<SearchResult[]>;
     multiQuerySearch(c: string, v: Array<number[] | Float32Array>, o?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     searchIds(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<Array<{
@@ -1167,29 +1519,33 @@ declare class RestBackend implements IVelesDBBackend {
         score: number;
     }>>;
     query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
-    queryExplain(q: string, p?: Record<string, unknown>): Promise<ExplainResponse>;
-    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
-    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
-    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
-    traverseGraph(collection: string, req: TraverseRequest): Promise<TraverseResponse>;
-    traverseParallel(collection: string, req: TraverseParallelRequest): Promise<TraverseResponse>;
-    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
-    createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
-    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
-    listIndexes(collection: string): Promise<IndexInfo[]>;
-    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
-    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
-    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
-    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
-    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
-    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
-    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
-    storeSemanticFact(collection: string, entry: SemanticEntry): Promise<void>;
-    searchSemanticMemory(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<void>;
-    recallEpisodicEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<void>;
-    matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    queryExplain(q: string, p?: Record<string, unknown>, o?: {
+        analyze?: boolean;
+    }): Promise<ExplainResponse>;
+    collectionSanity(c: string): Promise<CollectionSanityResponse>;
+    scroll(c: string, r?: ScrollRequest): Promise<ScrollResponse>;
+    addEdge(c: string, e: AddEdgeRequest): Promise<void>;
+    getEdges(c: string, o?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(c: string, r: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(c: string, r: TraverseParallelRequest): Promise<TraverseResponse>;
+    getNodeDegree(c: string, id: number): Promise<DegreeResponse>;
+    createGraphCollection(n: string, c?: GraphCollectionConfig): Promise<void>;
+    createIndex(c: string, o: CreateIndexOptions): Promise<void>;
+    listIndexes(c: string): Promise<IndexInfo[]>;
+    hasIndex(c: string, l: string, p: string): Promise<boolean>;
+    dropIndex(c: string, l: string, p: string): Promise<boolean>;
+    getCollectionStats(c: string): Promise<CollectionStatsResponse | null>;
+    analyzeCollection(c: string): Promise<CollectionStatsResponse>;
+    getCollectionConfig(c: string): Promise<CollectionConfigResponse>;
+    trainPq(c: string, o?: PqTrainOptions): Promise<string>;
+    streamInsert(c: string, d: VectorDocument[]): Promise<void>;
+    streamUpsertPoints(c: string, d: VectorDocument[]): Promise<StreamUpsertResponse>;
+    storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
+    searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<void>;
+    recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<void>;
+    matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
 }
 
 /**
@@ -1285,6 +1641,16 @@ declare class VelesQLBuilder {
      *
      * @param condition - WHERE condition
      * @param params - Optional parameters
+     *
+     * @example
+     * ```typescript
+     * // Substring matching with CONTAINS_TEXT
+     * velesql()
+     *   .match('d', 'Document')
+     *   .where("content CONTAINS_TEXT 'keyword'")
+     *   .limit(10)
+     *   .toVelesQL();
+     * ```
      */
     where(condition: string, params?: Record<string, unknown>): VelesQLBuilder;
     /**
@@ -1381,4 +1747,252 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchQuality, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+/**
+ * VelesDB SearchQuality → REST wire format
+ *
+ * Helper that converts the TypeScript `SearchQuality` type into the
+ * `{ mode, ef_search }` fragment expected by `velesdb-server`'s
+ * `SearchRequest` body. The server supports named presets
+ * (`fast | balanced | accurate | perfect | autotune`) plus two
+ * template-literal forms:
+ * - `custom:<ef>`          — explicit HNSW `ef_search` override
+ * - `adaptive:<min>:<max>` — recall-target adaptive loop
+ *
+ * The helper preserves the string verbatim and lets the server parse
+ * it via `velesdb_core::api_types::mode_to_search_quality`. This
+ * keeps the wire contract in one place (the Rust parser) so the TS
+ * SDK does not duplicate the variant parsing logic.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fragment spliced into a `SearchRequest` body. Only `mode` is set
+ * today — the Rust parser resolves `custom:<ef>` and
+ * `adaptive:<min>:<max>` server-side and populates `ef_search` from
+ * the template payload. Callers that need a raw `ef_search` override
+ * should pass `SearchOptions.k` and use `'custom:<ef>'`.
+ */
+interface SearchQualityWire {
+    /** Search mode preset or template string (see module docs). */
+    mode?: string;
+}
+/**
+ * Convert a `SearchQuality` value into the REST wire fragment.
+ *
+ * Returns an empty object `{}` when the caller passes `undefined`,
+ * so spreading the result into a request body is safe and produces
+ * no `mode` key at all (leaving the server free to apply its
+ * configured default quality).
+ */
+declare function searchQualityToMode(quality: SearchQuality | undefined): SearchQualityWire;
+
+/**
+ * VelesDB Typed Error Hierarchy
+ *
+ * One TypeScript class per `velesdb_core::error::Error` variant, preserving
+ * the verbatim `VELES-XXX` code for ergonomic catch-by-instance narrowing.
+ *
+ * Motivation: the pre-v1.13 SDK mapped all server errors to a handful of
+ * generic classes (`NotFoundError`, `VelesDBError`) and clobbered the real
+ * `VELES-XXX` code with strings like `'NOT_FOUND'`. Client code had no way
+ * to distinguish "collection not found" (VELES-002) from "edge not found"
+ * (VELES-020) without string-sniffing the message. This module fixes that.
+ *
+ * @example Catch by specific class
+ * ```typescript
+ * try {
+ *   await db.search('docs', vec, { k: 10 });
+ * } catch (e) {
+ *   if (e instanceof CollectionNotFoundError) { ... }
+ *   else if (e instanceof DimensionMismatchError) { ... }
+ *   else if (e instanceof VelesError) { ... } // catches any VELES-XXX
+ *   else throw e;                              // not ours, rethrow
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Base class for every server-originated VelesDB error carrying a
+ * `VELES-XXX` code. All 36 typed sub-classes extend this.
+ *
+ * Also a direct sub-class of `VelesDBError` so that legacy handlers
+ * that catch `VelesDBError` continue to receive typed errors too.
+ */
+declare class VelesError extends VelesDBError {
+    constructor(message: string, code: string, cause?: Error);
+}
+/** Collection already exists (VELES-001). */
+declare class CollectionExistsError extends VelesError {
+    constructor(message: string);
+}
+/** Collection not found (VELES-002). */
+declare class CollectionNotFoundError extends VelesError {
+    constructor(message: string);
+}
+/** Point with the given ID not found (VELES-003). */
+declare class PointNotFoundError extends VelesError {
+    constructor(message: string);
+}
+/** Vector dimension mismatch (VELES-004). */
+declare class DimensionMismatchError extends VelesError {
+    constructor(message: string);
+}
+/** Invalid vector (NaN, wrong length, etc.) (VELES-005). */
+declare class InvalidVectorError extends VelesError {
+    constructor(message: string);
+}
+/** Storage layer error (mmap, WAL, I/O) (VELES-006). */
+declare class StorageError extends VelesError {
+    constructor(message: string);
+}
+/** HNSW / BM25 / secondary index error (VELES-007). */
+declare class IndexError extends VelesError {
+    constructor(message: string);
+}
+/** Index files corrupted and need rebuild (VELES-008). */
+declare class IndexCorruptedError extends VelesError {
+    constructor(message: string);
+}
+/** Configuration error (invalid settings) (VELES-009). */
+declare class ConfigError extends VelesError {
+    constructor(message: string);
+}
+/** VelesQL parse or execution error (VELES-010). */
+declare class QueryError extends VelesError {
+    constructor(message: string);
+}
+/** Low-level I/O error (wraps `std::io::Error`) (VELES-011). */
+declare class IoError extends VelesError {
+    constructor(message: string);
+}
+/** Serialization / deserialization error (VELES-012). */
+declare class SerializationError extends VelesError {
+    constructor(message: string);
+}
+/** Internal error — please report if encountered (VELES-013). */
+declare class InternalError extends VelesError {
+    constructor(message: string);
+}
+/** Vector not allowed on metadata-only collection (VELES-014). */
+declare class VectorNotAllowedError extends VelesError {
+    constructor(message: string);
+}
+/** Vector search not supported on metadata-only collection (VELES-015). */
+declare class SearchNotSupportedError extends VelesError {
+    constructor(message: string);
+}
+/** Vector required for vector collection (VELES-016). */
+declare class VectorRequiredError extends VelesError {
+    constructor(message: string);
+}
+/** Schema validation error (VELES-017). */
+declare class SchemaValidationError extends VelesError {
+    constructor(message: string);
+}
+/** Graph operation not supported on this collection type (VELES-018). */
+declare class GraphNotSupportedError extends VelesError {
+    constructor(message: string);
+}
+/** Edge with the given ID already exists (VELES-019). */
+declare class EdgeExistsError extends VelesError {
+    constructor(message: string);
+}
+/** Edge with the given ID not found (VELES-020). */
+declare class EdgeNotFoundError extends VelesError {
+    constructor(message: string);
+}
+/** Invalid edge label (empty, too long, forbidden chars) (VELES-021). */
+declare class InvalidEdgeLabelError extends VelesError {
+    constructor(message: string);
+}
+/** Node with the given ID not found (VELES-022). */
+declare class NodeNotFoundError extends VelesError {
+    constructor(message: string);
+}
+/** Numeric overflow / cast truncation (VELES-023). */
+declare class OverflowError extends VelesError {
+    constructor(message: string);
+}
+/** Column store schema or primary-key validation failed (VELES-024). */
+declare class ColumnStoreError extends VelesError {
+    constructor(message: string);
+}
+/** GPU parameter validation or operation failure (VELES-025). */
+declare class GpuError extends VelesError {
+    constructor(message: string);
+}
+/** Epoch mismatch — stale mmap guard, not recoverable (VELES-026). */
+declare class EpochMismatchError extends VelesError {
+    constructor(message: string);
+}
+/** Guard-rail violation: timeout, depth, cardinality, memory, rate limit (VELES-027). */
+declare class GuardRailError extends VelesError {
+    constructor(message: string);
+}
+/** Invalid quantizer config (PQ subspaces, empty training set, etc.) (VELES-028). */
+declare class InvalidQuantizerConfigError extends VelesError {
+    constructor(message: string);
+}
+/** Quantizer training failed (convergence, insufficient data) (VELES-029). */
+declare class TrainingFailedError extends VelesError {
+    constructor(message: string);
+}
+/** Sparse index error (VELES-030). */
+declare class SparseIndexError extends VelesError {
+    constructor(message: string);
+}
+/** Database already locked by another process (VELES-031). */
+declare class DatabaseLockedError extends VelesError {
+    constructor(message: string);
+}
+/** Vector dimension outside the valid range (VELES-032). */
+declare class InvalidDimensionError extends VelesError {
+    constructor(message: string);
+}
+/** Memory allocation failure (out of memory / invalid layout) (VELES-033). */
+declare class AllocationFailedError extends VelesError {
+    constructor(message: string);
+}
+/** Collection name contains forbidden characters or path separators (VELES-034). */
+declare class InvalidCollectionNameError extends VelesError {
+    constructor(message: string);
+}
+/** CSR snapshot build failed (allocation failure during rebuild) (VELES-035). */
+declare class SnapshotBuildFailedError extends VelesError {
+    constructor(message: string);
+}
+/** Collection was created with a newer schema version than this binary supports (VELES-036). */
+declare class IncompatibleSchemaVersionError extends VelesError {
+    constructor(message: string);
+}
+/**
+ * Every VELES code known to this SDK version, in ascending order.
+ *
+ * Used by tests to verify the 36-code contract and by tooling to emit
+ * doc/type metadata.
+ */
+declare const VELES_ERROR_CODES: readonly ["VELES-001", "VELES-002", "VELES-003", "VELES-004", "VELES-005", "VELES-006", "VELES-007", "VELES-008", "VELES-009", "VELES-010", "VELES-011", "VELES-012", "VELES-013", "VELES-014", "VELES-015", "VELES-016", "VELES-017", "VELES-018", "VELES-019", "VELES-020", "VELES-021", "VELES-022", "VELES-023", "VELES-024", "VELES-025", "VELES-026", "VELES-027", "VELES-028", "VELES-029", "VELES-030", "VELES-031", "VELES-032", "VELES-033", "VELES-034", "VELES-035", "VELES-036"];
+/** Union type of every known VELES code. */
+type VelesErrorCode = (typeof VELES_ERROR_CODES)[number];
+/**
+ * Instantiate the correct typed error class from a server-provided
+ * VELES code and message.
+ *
+ * - If `code` matches one of the 36 known VELES-XXX codes, returns
+ *   the matching typed sub-class.
+ * - If `code` is an unknown VELES code (e.g. `VELES-999` from a
+ *   newer server), returns a generic `VelesError` preserving the
+ *   code verbatim — forward-compatible with future core versions.
+ * - If `code` is null/undefined (legacy `error_response` path in
+ *   server that omits the code field), returns a generic
+ *   `VelesError` with code `'VELES-UNKNOWN'`.
+ *
+ * **Never** fabricates a fake code like `'NOT_FOUND'` — that was the
+ * pre-v1.13 anti-pattern this function exists to replace.
+ */
+declare function parseVelesError(code: string | null | undefined, message: string): VelesError;
+
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };