@wiscale/velesdb-sdk 1.4.1 → 1.6.0

package/dist/index.mjs

@@ -25,6 +25,44 @@ var NotFoundError = class extends VelesDBError {
     this.name = "NotFoundError";
   }
 };
+var BackpressureError = class extends VelesDBError {
+  constructor(message = "Server backpressure: too many requests") {
+    super(message, "BACKPRESSURE");
+    this.name = "BackpressureError";
+  }
+};
+
+// src/backends/shared.ts
+function throwOnError(response, resourceLabel) {
+  if (!response.error) {
+    return;
+  }
+  if (response.error.code === "NOT_FOUND" && resourceLabel !== void 0) {
+    throw new NotFoundError(resourceLabel);
+  }
+  throw new VelesDBError(response.error.message, response.error.code);
+}
+function returnNullOnNotFound(response) {
+  if (!response.error) {
+    return void 0;
+  }
+  if (response.error.code === "NOT_FOUND") {
+    return true;
+  }
+  throw new VelesDBError(response.error.message, response.error.code);
+}
+function collectionPath(collection) {
+  return `/collections/${encodeURIComponent(collection)}`;
+}
+function toNumberArray(v) {
+  return v instanceof Float32Array ? Array.from(v) : v;
+}
+function wasmNotSupported(feature) {
+  throw new VelesDBError(
+    `${feature}: not supported in WASM backend. Use REST backend.`,
+    "NOT_SUPPORTED"
+  );
+}
 
 // src/backends/wasm.ts
 var WasmBackend = class {
@@ -56,6 +94,33 @@ var WasmBackend = class {
       throw new ConnectionError("WASM backend not initialized");
     }
   }
+  normalizeIdString(id) {
+    const trimmed = id.trim();
+    return /^\d+$/.test(trimmed) ? trimmed : null;
+  }
+  canonicalPayloadKeyFromResultId(id) {
+    if (typeof id === "bigint") {
+      return id.toString();
+    }
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
+  canonicalPayloadKey(id) {
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
   async createCollection(name, config) {
     this.ensureInitialized();
     if (this.collections.has(name)) {
@@ -121,9 +186,13 @@ var WasmBackend = class {
         "DIMENSION_MISMATCH"
       );
     }
-    collection.store.insert(BigInt(id), vector);
     if (doc.payload) {
-      collection.payloads.set(String(doc.id), doc.payload);
+      collection.store.insert_with_payload(BigInt(id), vector, doc.payload);
+    } else {
+      collection.store.insert(BigInt(id), vector);
+    }
+    if (doc.payload) {
+      collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
     }
   }
   async insertBatch(collectionName, docs) {
@@ -142,24 +211,32 @@ var WasmBackend = class {
       }
     }
     collection.store.reserve(docs.length);
-    const batch = docs.map((doc) => [
-      BigInt(this.toNumericId(doc.id)),
-      Array.isArray(doc.vector) ? doc.vector : Array.from(doc.vector)
-    ]);
-    collection.store.insert_batch(batch);
+    const batch = [];
     for (const doc of docs) {
+      const id = BigInt(this.toNumericId(doc.id));
+      const vector = doc.vector instanceof Float32Array ? doc.vector : new Float32Array(doc.vector);
       if (doc.payload) {
-        collection.payloads.set(String(doc.id), doc.payload);
+        collection.store.insert_with_payload(id, vector, doc.payload);
+      } else {
+        batch.push([id, Array.from(vector)]);
+      }
+    }
+    if (batch.length > 0) {
+      collection.store.insert_batch(batch);
+    }
+    for (const doc of docs) {
+      if (doc.payload) {
+        collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
       }
     }
   }
-  async search(collectionName, query, options) {
+  async search(collectionName, query2, options) {
     this.ensureInitialized();
     const collection = this.collections.get(collectionName);
     if (!collection) {
       throw new NotFoundError(`Collection '${collectionName}'`);
     }
-    const queryVector = query instanceof Float32Array ? query : new Float32Array(query);
+    const queryVector = query2 instanceof Float32Array ? query2 : new Float32Array(query2);
     if (queryVector.length !== collection.config.dimension) {
       throw new VelesDBError(
         `Query dimension mismatch: expected ${collection.config.dimension}, got ${queryVector.length}`,
@@ -167,12 +244,43 @@ var WasmBackend = class {
       );
     }
     const k = options?.k ?? 10;
+    if (options?.sparseVector) {
+      const { indices, values } = this.sparseVectorToArrays(options.sparseVector);
+      if (queryVector.length > 0 && collection.config.dimension && collection.config.dimension > 0) {
+        const denseResults = collection.store.search(queryVector, k);
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        const sparseArray = sparseResults;
+        const denseForFuse = denseResults.map(([id, score]) => [Number(id), score]);
+        const sparseForFuse = sparseArray.map((r) => [Number(r.doc_id), r.score]);
+        const fused = this.wasmModule.hybrid_search_fuse(denseForFuse, sparseForFuse, 60);
+        return fused.slice(0, k).map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      } else {
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        return sparseResults.map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      }
+    }
     if (options?.filter) {
       const results = collection.store.search_with_filter(queryVector, k, options.filter);
       return results.map((r) => ({
         id: String(r.id),
         score: r.score,
-        payload: r.payload || collection.payloads.get(String(r.id))
+        payload: r.payload || collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.id))
       }));
     }
     const rawResults = collection.store.search(queryVector, k);
@@ -182,7 +290,7 @@ var WasmBackend = class {
         id: stringId,
         score
       };
-      const payload = collection.payloads.get(stringId);
+      const payload = collection.payloads.get(this.canonicalPayloadKeyFromResultId(id));
       if (payload) {
         result.payload = payload;
       }
@@ -206,7 +314,7 @@ var WasmBackend = class {
     const numericId = this.toNumericId(id);
     const removed = collection.store.remove(BigInt(numericId));
     if (removed) {
-      collection.payloads.delete(String(id));
+      collection.payloads.delete(this.canonicalPayloadKey(id));
     }
     return removed;
   }
@@ -216,40 +324,129 @@ var WasmBackend = class {
     if (!collection) {
       throw new NotFoundError(`Collection '${collectionName}'`);
     }
-    const payload = collection.payloads.get(String(id));
-    if (!payload) {
+    const numericId = this.toNumericId(id);
+    const point = collection.store.get(BigInt(numericId));
+    if (!point) {
       return null;
     }
+    const payload = point.payload ?? collection.payloads.get(this.canonicalPayloadKey(numericId));
     return {
-      id,
-      vector: [],
-      // Not available in current WASM impl
+      id: String(point.id),
+      vector: Array.isArray(point.vector) ? point.vector : Array.from(point.vector),
       payload
     };
   }
   async textSearch(_collection, _query, _options) {
-    throw new VelesDBError(
-      "Text search is not supported in WASM backend. Use REST backend for BM25 search.",
-      "NOT_SUPPORTED"
-    );
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const k = _options?.k ?? 10;
+    const field = void 0;
+    const raw = collection.store.text_search(_query, k, field);
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
   }
   async hybridSearch(_collection, _vector, _textQuery, _options) {
-    throw new VelesDBError(
-      "Hybrid search is not supported in WASM backend. Use REST backend for hybrid search.",
-      "NOT_SUPPORTED"
-    );
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const queryVector = _vector instanceof Float32Array ? _vector : new Float32Array(_vector);
+    const k = _options?.k ?? 10;
+    const vectorWeight = _options?.vectorWeight ?? 0.5;
+    const raw = collection.store.hybrid_search(queryVector, _textQuery, k, vectorWeight);
+    return raw.map((r) => {
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return {
+        id: String(r.id),
+        score: r.score,
+        payload: r.payload ?? collection.payloads.get(key)
+      };
+    });
   }
   async query(_collection, _queryString, _params, _options) {
-    throw new VelesDBError(
-      "VelesQL queries are not supported in WASM backend. Use REST backend for query support.",
-      "NOT_SUPPORTED"
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const paramsVector = _params?.q;
+    if (!Array.isArray(paramsVector) && !(paramsVector instanceof Float32Array)) {
+      throw new VelesDBError(
+        "WASM query() expects params.q to contain the query embedding vector.",
+        "BAD_REQUEST"
+      );
+    }
+    const requestedK = _params?.k;
+    const k = typeof requestedK === "number" && Number.isInteger(requestedK) && requestedK > 0 ? requestedK : 10;
+    const raw = collection.store.query(
+      paramsVector instanceof Float32Array ? paramsVector : new Float32Array(paramsVector),
+      k
     );
+    return {
+      results: raw,
+      stats: {
+        executionTimeMs: 0,
+        strategy: "wasm-query",
+        scannedNodes: raw.length
+      }
+    };
   }
   async multiQuerySearch(_collection, _vectors, _options) {
-    throw new VelesDBError(
-      "Multi-query fusion is not supported in WASM backend. Use REST backend for MQF search.",
-      "NOT_SUPPORTED"
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    if (_vectors.length === 0) {
+      return [];
+    }
+    const numVectors = _vectors.length;
+    const dimension = collection.config.dimension ?? 0;
+    const flat = new Float32Array(numVectors * dimension);
+    _vectors.forEach((vector, idx) => {
+      const src = vector instanceof Float32Array ? vector : new Float32Array(vector);
+      flat.set(src, idx * dimension);
+    });
+    const strategy = _options?.fusion ?? "rrf";
+    if (strategy === "weighted") {
+      throw new VelesDBError(
+        "Fusion strategy 'weighted' is not supported in WASM backend.",
+        "NOT_SUPPORTED"
+      );
+    }
+    const raw = collection.store.multi_query_search(
+      flat,
+      numVectors,
+      _options?.k ?? 10,
+      strategy,
+      _options?.fusionParams?.k ?? 60
     );
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
+  }
+  async queryExplain(_queryString, _params) {
+    this.ensureInitialized();
+    wasmNotSupported("Query explain");
+  }
+  async collectionSanity(_collection) {
+    this.ensureInitialized();
+    wasmNotSupported("Collection sanity endpoint");
   }
   async isEmpty(collectionName) {
     this.ensureInitialized();
@@ -273,13 +470,25 @@ var WasmBackend = class {
     this.collections.clear();
     this._initialized = false;
   }
+  sparseVectorToArrays(sv) {
+    const indices = [];
+    const values = [];
+    for (const [k, v] of Object.entries(sv)) {
+      indices.push(Number(k));
+      values.push(v);
+    }
+    return { indices, values };
+  }
   toNumericId(id) {
     if (typeof id === "number") {
       return id;
     }
-    const parsed = parseInt(id, 10);
-    if (!isNaN(parsed)) {
-      return parsed;
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      const parsed = Number(normalized);
+      if (Number.isSafeInteger(parsed)) {
+        return parsed;
+      }
     }
     let hash = 0;
     for (let i = 0; i < id.length; i++) {
@@ -317,34 +526,715 @@ var WasmBackend = class {
   // ========================================================================
   async addEdge(_collection, _edge) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Knowledge Graph operations");
   }
   async getEdges(_collection, _options) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Knowledge Graph operations");
   }
   async traverseGraph(_collection, _request) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Graph traversal is not supported in WASM backend. Use REST backend for graph features.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Graph traversal");
   }
   async getNodeDegree(_collection, _nodeId) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Graph degree query is not supported in WASM backend. Use REST backend for graph features.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Graph degree query");
+  }
+  // ========================================================================
+  // Sparse / PQ / Streaming (v1.5)
+  // ========================================================================
+  async trainPq(_collection, _options) {
+    this.ensureInitialized();
+    wasmNotSupported("PQ training");
+  }
+  async streamInsert(_collection, _docs) {
+    this.ensureInitialized();
+    wasmNotSupported("Streaming insert");
+  }
+  // ========================================================================
+  // Graph Collection / Stats / Agent Memory (Phase 8) - WASM stubs
+  // ========================================================================
+  async createGraphCollection(_name, _config) {
+    this.ensureInitialized();
+    wasmNotSupported("Graph collections");
+  }
+  async getCollectionStats(_collection) {
+    this.ensureInitialized();
+    wasmNotSupported("Collection stats");
+  }
+  async analyzeCollection(_collection) {
+    this.ensureInitialized();
+    wasmNotSupported("Collection analyze");
+  }
+  async getCollectionConfig(_collection) {
+    this.ensureInitialized();
+    wasmNotSupported("Collection config");
+  }
+  async searchIds(_collection, _query, _options) {
+    this.ensureInitialized();
+    wasmNotSupported("searchIds");
+  }
+  async storeSemanticFact(_collection, _entry) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
+  }
+  async searchSemanticMemory(_collection, _embedding, _k) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
+  }
+  async recordEpisodicEvent(_collection, _event) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
+  }
+  async recallEpisodicEvents(_collection, _embedding, _k) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
+  }
+  async storeProceduralPattern(_collection, _pattern) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
+  }
+  async matchProceduralPatterns(_collection, _embedding, _k) {
+    this.ensureInitialized();
+    wasmNotSupported("Agent memory");
   }
 };
 
+// src/backends/agent-memory-backend.ts
+var _idCounter = 0;
+var _lastTimestamp = 0;
+function generateUniqueId() {
+  let now = Date.now();
+  if (now <= _lastTimestamp) {
+    _idCounter++;
+    if (_idCounter >= 1e3) {
+      _lastTimestamp++;
+      _idCounter = 0;
+    }
+  } else {
+    _lastTimestamp = now;
+    _idCounter = 0;
+  }
+  return _lastTimestamp * 1e3 + _idCounter;
+}
+async function storeSemanticFact(transport, collection, entry) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points`,
+    {
+      points: [{
+        id: entry.id,
+        vector: entry.embedding,
+        payload: {
+          _memory_type: "semantic",
+          text: entry.text,
+          ...entry.metadata
+        }
+      }]
+    }
+  );
+  throwOnError(response);
+}
+async function searchSemanticMemory(transport, collection, embedding, k = 5) {
+  return transport.searchVectors(collection, embedding, k, { _memory_type: "semantic" });
+}
+async function recordEpisodicEvent(transport, collection, event) {
+  const id = generateUniqueId();
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points`,
+    {
+      points: [{
+        id,
+        vector: event.embedding,
+        payload: {
+          _memory_type: "episodic",
+          event_type: event.eventType,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...event.data,
+          ...event.metadata
+        }
+      }]
+    }
+  );
+  throwOnError(response);
+}
+async function recallEpisodicEvents(transport, collection, embedding, k = 5) {
+  return transport.searchVectors(collection, embedding, k, { _memory_type: "episodic" });
+}
+async function storeProceduralPattern(transport, collection, pattern) {
+  const id = generateUniqueId();
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points`,
+    {
+      points: [{
+        id,
+        payload: {
+          _memory_type: "procedural",
+          name: pattern.name,
+          steps: pattern.steps,
+          ...pattern.metadata
+        }
+      }]
+    }
+  );
+  throwOnError(response);
+}
+async function matchProceduralPatterns(transport, collection, embedding, k = 5) {
+  return transport.searchVectors(collection, embedding, k, { _memory_type: "procedural" });
+}
+
+// src/backends/search-backend.ts
+async function search(transport, collection, query2, options) {
+  const queryVector = toNumberArray(query2);
+  const body = {
+    vector: queryVector,
+    top_k: options?.k ?? 10,
+    filter: options?.filter,
+    include_vectors: options?.includeVectors ?? false
+  };
+  if (options?.sparseVector) {
+    body.sparse_vector = transport.sparseToRest(options.sparseVector);
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
+async function searchBatch(transport, collection, searches) {
+  const formattedSearches = searches.map((s) => ({
+    vector: toNumberArray(s.vector),
+    top_k: s.k ?? 10,
+    filter: s.filter
+  }));
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search/batch`,
+    { searches: formattedSearches }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results.map((r) => r.results) ?? [];
+}
+async function textSearch(transport, collection, query2, options) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search/text`,
+    {
+      query: query2,
+      top_k: options?.k ?? 10,
+      filter: options?.filter
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
+async function hybridSearch(transport, collection, vector, textQuery, options) {
+  const queryVector = toNumberArray(vector);
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search/hybrid`,
+    {
+      vector: queryVector,
+      query: textQuery,
+      top_k: options?.k ?? 10,
+      vector_weight: options?.vectorWeight ?? 0.5,
+      filter: options?.filter
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
+async function multiQuerySearch(transport, collection, vectors, options) {
+  const formattedVectors = vectors.map(toNumberArray);
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search/multi`,
+    {
+      vectors: formattedVectors,
+      top_k: options?.k ?? 10,
+      strategy: options?.fusion ?? "rrf",
+      rrf_k: options?.fusionParams?.k ?? 60,
+      avg_weight: options?.fusionParams?.avgWeight,
+      max_weight: options?.fusionParams?.maxWeight,
+      hit_weight: options?.fusionParams?.hitWeight,
+      filter: options?.filter
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
+async function searchIds(transport, collection, query2, options) {
+  const queryVector = toNumberArray(query2);
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search/ids`,
+    {
+      vector: queryVector,
+      top_k: options?.k ?? 10,
+      filter: options?.filter
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
+
+// src/backends/graph-backend.ts
+async function addEdge(transport, collection, edge) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/graph/edges`,
+    {
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      label: edge.label,
+      properties: edge.properties ?? {}
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
+async function getEdges(transport, collection, options) {
+  const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/graph/edges${queryParams}`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.edges ?? [];
+}
+async function traverseGraph(transport, collection, request) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/graph/traverse`,
+    {
+      source: request.source,
+      strategy: request.strategy ?? "bfs",
+      max_depth: request.maxDepth ?? 3,
+      limit: request.limit ?? 100,
+      cursor: request.cursor,
+      rel_types: request.relTypes ?? []
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  const data = response.data;
+  return {
+    results: data.results.map((r) => ({
+      targetId: r.target_id,
+      depth: r.depth,
+      path: r.path
+    })),
+    nextCursor: data.next_cursor ?? void 0,
+    hasMore: data.has_more,
+    stats: {
+      visited: data.stats.visited,
+      depthReached: data.stats.depth_reached
+    }
+  };
+}
+async function getNodeDegree(transport, collection, nodeId) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/graph/nodes/${nodeId}/degree`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return {
+    inDegree: response.data?.in_degree ?? 0,
+    outDegree: response.data?.out_degree ?? 0
+  };
+}
+async function createGraphCollection(transport, name, config) {
+  const response = await transport.requestJson("POST", "/collections", {
+    name,
+    collection_type: "graph",
+    dimension: config?.dimension,
+    metric: config?.metric ?? "cosine",
+    schema_mode: config?.schemaMode ?? "schemaless"
+  });
+  throwOnError(response);
+}
+
+// src/backends/query-backend.ts
+function isLikelyAggregationQuery(queryString) {
+  return /\bGROUP\s+BY\b|\bHAVING\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bMIN\s*\(|\bMAX\s*\(/i.test(
+    queryString
+  );
+}
+async function query(transport, collection, queryString, params, options) {
+  const endpoint = isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
+  const response = await transport.requestJson(
+    "POST",
+    endpoint,
+    {
+      query: queryString,
+      params: params ?? {},
+      collection,
+      timeout_ms: options?.timeoutMs,
+      stream: options?.stream ?? false
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  const rawData = response.data;
+  if (rawData && Object.prototype.hasOwnProperty.call(rawData, "result")) {
+    return {
+      result: rawData.result,
+      stats: {
+        executionTimeMs: rawData.timing_ms ?? 0,
+        strategy: "aggregation",
+        scannedNodes: 0
+      }
+    };
+  }
+  return {
+    results: rawData?.results ?? [],
+    stats: {
+      executionTimeMs: rawData?.timing_ms ?? 0,
+      strategy: "select",
+      scannedNodes: rawData?.rows_returned ?? 0
+    }
+  };
+}
+async function queryExplain(transport, queryString, params) {
+  const response = await transport.requestJson(
+    "POST",
+    "/query/explain",
+    {
+      query: queryString,
+      params: params ?? {}
+    }
+  );
+  throwOnError(response);
+  const data = response.data;
+  return {
+    query: data.query,
+    queryType: data.query_type,
+    collection: data.collection,
+    plan: data.plan.map((step) => ({
+      step: step.step,
+      operation: step.operation,
+      description: step.description,
+      estimatedRows: step.estimated_rows
+    })),
+    estimatedCost: {
+      usesIndex: data.estimated_cost.uses_index,
+      indexName: data.estimated_cost.index_name,
+      selectivity: data.estimated_cost.selectivity,
+      complexity: data.estimated_cost.complexity
+    },
+    features: {
+      hasVectorSearch: data.features.has_vector_search,
+      hasFilter: data.features.has_filter,
+      hasOrderBy: data.features.has_order_by,
+      hasGroupBy: data.features.has_group_by,
+      hasAggregation: data.features.has_aggregation,
+      hasJoin: data.features.has_join,
+      hasFusion: data.features.has_fusion,
+      limit: data.features.limit,
+      offset: data.features.offset
+    }
+  };
+}
+async function collectionSanity(transport, collection) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/sanity`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  const data = response.data;
+  return {
+    collection: data.collection,
+    dimension: data.dimension,
+    metric: data.metric,
+    pointCount: data.point_count,
+    isEmpty: data.is_empty,
+    checks: {
+      hasVectors: data.checks.has_vectors,
+      searchReady: data.checks.search_ready,
+      dimensionConfigured: data.checks.dimension_configured
+    },
+    diagnostics: {
+      searchRequestsTotal: data.diagnostics.search_requests_total,
+      dimensionMismatchTotal: data.diagnostics.dimension_mismatch_total,
+      emptySearchResultsTotal: data.diagnostics.empty_search_results_total,
+      filterParseErrorsTotal: data.diagnostics.filter_parse_errors_total
+    },
+    hints: data.hints ?? []
+  };
+}
+
+// src/backends/admin-backend.ts
+function mapStatsResponse(data) {
+  return {
+    totalPoints: data.total_points,
+    totalSizeBytes: data.total_size_bytes,
+    rowCount: data.row_count,
+    deletedCount: data.deleted_count,
+    avgRowSizeBytes: data.avg_row_size_bytes,
+    payloadSizeBytes: data.payload_size_bytes,
+    lastAnalyzedEpochMs: data.last_analyzed_epoch_ms
+  };
+}
+async function getCollectionStats(transport, collection) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/stats`
+  );
+  if (returnNullOnNotFound(response)) {
+    return null;
+  }
+  return mapStatsResponse(response.data);
+}
+async function analyzeCollection(transport, collection) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/analyze`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return mapStatsResponse(response.data);
+}
+async function getCollectionConfig(transport, collection) {
+  const response = await transport.requestJson("GET", `${collectionPath(collection)}/config`);
+  throwOnError(response, `Collection '${collection}'`);
+  const data = response.data;
+  return {
+    name: data.name,
+    dimension: data.dimension,
+    metric: data.metric,
+    storageMode: data.storage_mode,
+    pointCount: data.point_count,
+    metadataOnly: data.metadata_only,
+    graphSchema: data.graph_schema,
+    embeddingDimension: data.embedding_dimension
+  };
+}
+
+// src/backends/index-backend.ts
+async function createIndex(transport, collection, options) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/indexes`,
+    {
+      label: options.label,
+      property: options.property,
+      index_type: options.indexType ?? "hash"
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
+async function listIndexes(transport, collection) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/indexes`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return (response.data?.indexes ?? []).map((idx) => ({
+    label: idx.label,
+    property: idx.property,
+    indexType: idx.index_type,
+    cardinality: idx.cardinality,
+    memoryBytes: idx.memory_bytes
+  }));
+}
+async function hasIndex(transport, collection, label, property) {
+  const indexes = await listIndexes(transport, collection);
+  return indexes.some((idx) => idx.label === label && idx.property === property);
+}
+async function dropIndex(transport, collection, label, property) {
+  const response = await transport.requestJson(
+    "DELETE",
+    `${collectionPath(collection)}/indexes/${encodeURIComponent(label)}/${encodeURIComponent(property)}`
+  );
+  if (returnNullOnNotFound(response)) {
+    return false;
+  }
+  return response.data?.dropped ?? true;
+}
+
+// src/backends/streaming-backend.ts
+async function trainPq(transport, collection, options) {
+  const m = options?.m ?? 8;
+  const k = options?.k ?? 256;
+  const withClause = options?.opq ? `WITH (m=${m}, k=${k}, opq=true)` : `WITH (m=${m}, k=${k})`;
+  const queryString = `TRAIN QUANTIZER ON ${collection} ${withClause}`;
+  const response = await transport.requestJson(
+    "POST",
+    "/query",
+    { query: queryString }
+  );
+  throwOnError(response);
+  return response.data?.message ?? "PQ training initiated";
+}
+async function streamInsert(transport, collection, docs) {
+  for (const doc of docs) {
+    const restId = transport.parseRestPointId(doc.id);
+    const vector = toNumberArray(doc.vector);
+    const body = {
+      id: restId,
+      vector,
+      payload: doc.payload
+    };
+    if (doc.sparseVector) {
+      body.sparse_vector = transport.sparseVectorToRestFormat(doc.sparseVector);
+    }
+    const url = `${transport.baseUrl}${collectionPath(collection)}/stream/insert`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (transport.apiKey) {
+      headers["Authorization"] = `Bearer ${transport.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), transport.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 429) {
+        throw new BackpressureError();
+      }
+      if (!response.ok && response.status !== 202) {
+        const data = await response.json().catch(() => ({}));
+        const errorPayload = transport.extractErrorPayload(data);
+        throw new VelesDBError(
+          errorPayload.message ?? `HTTP ${response.status}`,
+          errorPayload.code ?? transport.mapStatusToErrorCode(response.status)
+        );
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof BackpressureError || error instanceof VelesDBError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ConnectionError("Request timeout");
+      }
+      throw new ConnectionError(
+        `Stream insert failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+}
+
+// src/backends/crud-backend.ts
+function parseRestPointId(id) {
+  if (typeof id !== "number" || !Number.isFinite(id) || id < 0 || !Number.isInteger(id) || id > Number.MAX_SAFE_INTEGER) {
+    throw new ValidationError(
+      `REST backend requires numeric u64-compatible IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER}). Received: ${String(id)}`
+    );
+  }
+  return id;
+}
+function sparseVectorToRestFormat(sv) {
+  const result = {};
+  for (const [k, v] of Object.entries(sv)) {
+    result[String(k)] = v;
+  }
+  return result;
+}
+async function createCollection(transport, name, config) {
+  const response = await transport.requestJson("POST", "/collections", {
+    name,
+    dimension: config.dimension,
+    metric: config.metric ?? "cosine",
+    storage_mode: config.storageMode ?? "full",
+    collection_type: config.collectionType ?? "vector",
+    description: config.description,
+    hnsw_m: config.hnsw?.m,
+    hnsw_ef_construction: config.hnsw?.efConstruction
+  });
+  throwOnError(response);
+}
+async function deleteCollection(transport, name) {
+  const response = await transport.requestJson(
+    "DELETE",
+    collectionPath(name)
+  );
+  throwOnError(response, `Collection '${name}'`);
+}
+async function getCollection(transport, name) {
+  const response = await transport.requestJson(
+    "GET",
+    collectionPath(name)
+  );
+  if (returnNullOnNotFound(response)) {
+    return null;
+  }
+  return response.data ?? null;
+}
+async function listCollections(transport) {
+  const response = await transport.requestJson("GET", "/collections");
+  throwOnError(response);
+  return response.data ?? [];
+}
+async function insert(transport, collection, doc) {
+  const restId = parseRestPointId(doc.id);
+  const vector = toNumberArray(doc.vector);
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points`,
+    { points: [{ id: restId, vector, payload: doc.payload }] }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
+async function insertBatch(transport, collection, docs) {
+  const vectors = docs.map((doc) => ({
+    id: parseRestPointId(doc.id),
+    vector: toNumberArray(doc.vector),
+    payload: doc.payload
+  }));
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points`,
+    { points: vectors }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
+async function deletePoint(transport, collection, id) {
+  const restId = parseRestPointId(id);
+  const response = await transport.requestJson(
+    "DELETE",
+    `${collectionPath(collection)}/points/${encodeURIComponent(String(restId))}`
+  );
+  if (returnNullOnNotFound(response)) {
+    return false;
+  }
+  return response.data?.deleted ?? false;
+}
+async function get(transport, collection, id) {
+  const restId = parseRestPointId(id);
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/points/${encodeURIComponent(String(restId))}`
+  );
+  if (returnNullOnNotFound(response)) {
+    return null;
+  }
+  return response.data ?? null;
+}
+async function isEmpty(transport, collection) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/empty`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.is_empty ?? true;
+}
+async function flush(transport, collection) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/flush`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
+
 // src/backends/rest.ts
 var RestBackend = class {
   constructor(url, apiKey, timeout = 3e4) {
@@ -405,15 +1295,13 @@ var RestBackend = class {
       return {};
     }
     const payload = data;
-    const code = typeof payload.code === "string" ? payload.code : void 0;
-    const messageField = payload.message ?? payload.error;
+    const nestedError = payload.error && typeof payload.error === "object" ? payload.error : void 0;
+    const codeField = nestedError?.code ?? payload.code;
+    const code = typeof codeField === "string" ? codeField : void 0;
+    const messageField = nestedError?.message ?? payload.message ?? payload.error;
     const message = typeof messageField === "string" ? messageField : void 0;
     return { code, message };
   }
-  /**
-   * Parse node ID safely to handle u64 values above Number.MAX_SAFE_INTEGER.
-   * Returns bigint for large values, number for safe values.
-   */
   parseNodeId(value) {
     if (value === null || value === void 0) {
       return 0;
@@ -423,24 +1311,16 @@ var RestBackend = class {
     }
     if (typeof value === "string") {
       const num = Number(value);
-      if (num > Number.MAX_SAFE_INTEGER) {
-        return BigInt(value);
-      }
-      return num;
+      return num > Number.MAX_SAFE_INTEGER ? BigInt(value) : num;
     }
     if (typeof value === "number") {
-      if (value > Number.MAX_SAFE_INTEGER) {
-        return value;
-      }
       return value;
     }
     return 0;
   }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
-    const headers = {
-      "Content-Type": "application/json"
-    };
+    const headers = { "Content-Type": "application/json" };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
     }
@@ -476,445 +1356,259 @@ var RestBackend = class {
       );
     }
   }
+  // ==========================================================================
+  // Transport adapters
+  // ==========================================================================
+  asCrudTransport() {
+    return {
+      requestJson: (m, p, b) => this.request(m, p, b)
+    };
+  }
+  asSearchTransport() {
+    return {
+      requestJson: (m, p, b) => this.request(m, p, b),
+      sparseToRest: (sv) => sparseVectorToRestFormat(sv)
+    };
+  }
+  asAgentMemoryTransport() {
+    return {
+      requestJson: (m, p, b) => this.request(m, p, b),
+      searchVectors: (c, e, k, f) => this.search(c, e, { k, filter: f })
+    };
+  }
+  asQueryTransport() {
+    return {
+      requestJson: (m, p, b) => this.request(m, p, b),
+      parseNodeId: (v) => this.parseNodeId(v)
+    };
+  }
+  asStreamingTransport() {
+    return {
+      requestJson: (m, p, b) => this.request(m, p, b),
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      timeout: this.timeout,
+      parseRestPointId,
+      sparseVectorToRestFormat,
+      mapStatusToErrorCode: (s) => this.mapStatusToErrorCode(s),
+      extractErrorPayload: (d) => this.extractErrorPayload(d)
+    };
+  }
+  // ==========================================================================
+  // Collection CRUD — delegates to crud-backend.ts
+  // ==========================================================================
   async createCollection(name, config) {
     this.ensureInitialized();
-    const response = await this.request("POST", "/collections", {
-      name,
-      dimension: config.dimension,
-      metric: config.metric ?? "cosine",
-      storage_mode: config.storageMode ?? "full",
-      collection_type: config.collectionType ?? "vector",
-      description: config.description
-    });
-    if (response.error) {
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return createCollection(this.asCrudTransport(), name, config);
   }
   async deleteCollection(name) {
     this.ensureInitialized();
-    const response = await this.request("DELETE", `/collections/${encodeURIComponent(name)}`);
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${name}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return deleteCollection(this.asCrudTransport(), name);
   }
   async getCollection(name) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(name)}`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        return null;
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data ?? null;
+    return getCollection(this.asCrudTransport(), name);
   }
   async listCollections() {
     this.ensureInitialized();
-    const response = await this.request("GET", "/collections");
-    if (response.error) {
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data ?? [];
+    return listCollections(this.asCrudTransport());
   }
   async insert(collection, doc) {
     this.ensureInitialized();
-    const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/points`,
-      {
-        points: [{
-          id: doc.id,
-          vector,
-          payload: doc.payload
-        }]
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return insert(this.asCrudTransport(), collection, doc);
   }
   async insertBatch(collection, docs) {
     this.ensureInitialized();
-    const vectors = docs.map((doc) => ({
-      id: doc.id,
-      vector: doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector,
-      payload: doc.payload
-    }));
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/points`,
-      { points: vectors }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return insertBatch(this.asCrudTransport(), collection, docs);
   }
-  async search(collection, query, options) {
+  async delete(collection, id) {
     this.ensureInitialized();
-    const queryVector = query instanceof Float32Array ? Array.from(query) : query;
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search`,
-      {
-        vector: queryVector,
-        k: options?.k ?? 10,
-        filter: options?.filter,
-        include_vectors: options?.includeVectors ?? false
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data ?? [];
+    return deletePoint(this.asCrudTransport(), collection, id);
+  }
+  async get(collection, id) {
+    this.ensureInitialized();
+    return get(this.asCrudTransport(), collection, id);
+  }
+  async isEmpty(collection) {
+    this.ensureInitialized();
+    return isEmpty(this.asCrudTransport(), collection);
+  }
+  async flush(collection) {
+    this.ensureInitialized();
+    return flush(this.asCrudTransport(), collection);
+  }
+  async close() {
+    this._initialized = false;
+  }
+  // ==========================================================================
+  // Search — delegates to search-backend.ts
+  // ==========================================================================
+  async search(c, q, o) {
+    this.ensureInitialized();
+    return search(this.asSearchTransport(), c, q, o);
   }
   async searchBatch(collection, searches) {
     this.ensureInitialized();
-    const formattedSearches = searches.map((s) => ({
-      vector: s.vector instanceof Float32Array ? Array.from(s.vector) : s.vector,
-      top_k: s.k ?? 10,
-      filter: s.filter
-    }));
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search/batch`,
-      { searches: formattedSearches }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.results.map((r) => r.results) ?? [];
+    return searchBatch(this.asSearchTransport(), collection, searches);
   }
-  async delete(collection, id) {
+  async textSearch(c, q, o) {
     this.ensureInitialized();
-    const response = await this.request(
-      "DELETE",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        return false;
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.deleted ?? false;
+    return textSearch(this.asSearchTransport(), c, q, o);
   }
-  async get(collection, id) {
+  async hybridSearch(c, v, t, o) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        return null;
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data ?? null;
+    return hybridSearch(this.asSearchTransport(), c, v, t, o);
   }
-  async textSearch(collection, query, options) {
+  async multiQuerySearch(c, v, o) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search/text`,
-      {
-        query,
-        top_k: options?.k ?? 10,
-        filter: options?.filter
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.results ?? [];
+    return multiQuerySearch(this.asSearchTransport(), c, v, o);
   }
-  async hybridSearch(collection, vector, textQuery, options) {
+  async searchIds(c, q, o) {
     this.ensureInitialized();
-    const queryVector = vector instanceof Float32Array ? Array.from(vector) : vector;
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search/hybrid`,
-      {
-        vector: queryVector,
-        query: textQuery,
-        top_k: options?.k ?? 10,
-        vector_weight: options?.vectorWeight ?? 0.5,
-        filter: options?.filter
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.results ?? [];
+    return searchIds(this.asSearchTransport(), c, q, o);
   }
-  async query(collection, queryString, params, _options) {
+  // ==========================================================================
+  // Query — delegates to query-backend.ts
+  // ==========================================================================
+  async query(c, q, p, o) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      "/query",
-      {
-        query: queryString,
-        params: params ?? {}
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    const rawData = response.data;
-    return {
-      results: (rawData?.results ?? []).map((r) => ({
-        // Server returns `id` (u64), map to nodeId with precision handling
-        nodeId: this.parseNodeId(r.id ?? r.node_id ?? r.nodeId),
-        // Server returns `score`, map to vectorScore (primary score for SELECT queries)
-        vectorScore: r.score ?? r.vector_score ?? r.vectorScore,
-        // graph_score not returned by SELECT queries, only by future MATCH queries
-        graphScore: r.graph_score ?? r.graphScore,
-        // Use score as fusedScore for compatibility
-        fusedScore: r.score ?? r.fused_score ?? r.fusedScore ?? 0,
-        // payload maps to bindings for compatibility
-        bindings: r.payload ?? r.bindings ?? {},
-        columnData: r.column_data ?? r.columnData
-      })),
-      stats: {
-        executionTimeMs: rawData?.timing_ms ?? 0,
-        strategy: "select",
-        scannedNodes: rawData?.rows_returned ?? 0
-      }
-    };
+    return query(this.asQueryTransport(), c, q, p, o);
   }
-  async multiQuerySearch(collection, vectors, options) {
+  async queryExplain(q, p) {
     this.ensureInitialized();
-    const formattedVectors = vectors.map(
-      (v) => v instanceof Float32Array ? Array.from(v) : v
-    );
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search/multi`,
-      {
-        vectors: formattedVectors,
-        top_k: options?.k ?? 10,
-        strategy: options?.fusion ?? "rrf",
-        rrf_k: options?.fusionParams?.k ?? 60,
-        filter: options?.filter
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.results ?? [];
+    return queryExplain(this.asQueryTransport(), q, p);
   }
-  async isEmpty(collection) {
+  async collectionSanity(collection) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/empty`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.is_empty ?? true;
+    return collectionSanity(this.asQueryTransport(), collection);
   }
-  async flush(collection) {
+  // ==========================================================================
+  // Graph — delegates to graph-backend.ts
+  // ==========================================================================
+  async addEdge(collection, edge) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/flush`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return addEdge(this.asCrudTransport(), collection, edge);
   }
-  async close() {
-    this._initialized = false;
+  async getEdges(collection, options) {
+    this.ensureInitialized();
+    return getEdges(this.asCrudTransport(), collection, options);
   }
-  // ========================================================================
-  // Index Management (EPIC-009)
-  // ========================================================================
+  async traverseGraph(collection, req) {
+    this.ensureInitialized();
+    return traverseGraph(this.asCrudTransport(), collection, req);
+  }
+  async getNodeDegree(collection, nodeId) {
+    this.ensureInitialized();
+    return getNodeDegree(this.asCrudTransport(), collection, nodeId);
+  }
+  async createGraphCollection(name, config) {
+    this.ensureInitialized();
+    return createGraphCollection(this.asCrudTransport(), name, config);
+  }
+  // ==========================================================================
+  // Index — delegates to index-backend.ts
+  // ==========================================================================
   async createIndex(collection, options) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/indexes`,
-      {
-        label: options.label,
-        property: options.property,
-        index_type: options.indexType ?? "hash"
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return createIndex(this.asCrudTransport(), collection, options);
   }
   async listIndexes(collection) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/indexes`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return (response.data?.indexes ?? []).map((idx) => ({
-      label: idx.label,
-      property: idx.property,
-      indexType: idx.index_type,
-      cardinality: idx.cardinality,
-      memoryBytes: idx.memory_bytes
-    }));
+    return listIndexes(this.asCrudTransport(), collection);
   }
   async hasIndex(collection, label, property) {
-    const indexes = await this.listIndexes(collection);
-    return indexes.some((idx) => idx.label === label && idx.property === property);
+    this.ensureInitialized();
+    return hasIndex(this.asCrudTransport(), collection, label, property);
   }
   async dropIndex(collection, label, property) {
     this.ensureInitialized();
-    const response = await this.request(
-      "DELETE",
-      `/collections/${encodeURIComponent(collection)}/indexes/${encodeURIComponent(label)}/${encodeURIComponent(property)}`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        return false;
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.dropped ?? true;
+    return dropIndex(this.asCrudTransport(), collection, label, property);
   }
-  // ========================================================================
-  // Knowledge Graph (EPIC-016 US-041)
-  // ========================================================================
-  async addEdge(collection, edge) {
+  // ==========================================================================
+  // Admin — delegates to admin-backend.ts
+  // ==========================================================================
+  async getCollectionStats(collection) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/graph/edges`,
-      {
-        id: edge.id,
-        source: edge.source,
-        target: edge.target,
-        label: edge.label,
-        properties: edge.properties ?? {}
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
+    return getCollectionStats(this.asCrudTransport(), collection);
   }
-  async getEdges(collection, options) {
+  async analyzeCollection(collection) {
     this.ensureInitialized();
-    const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/graph/edges${queryParams}`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.edges ?? [];
+    return analyzeCollection(this.asCrudTransport(), collection);
   }
-  // ========================================================================
-  // Graph Traversal (EPIC-016 US-050)
-  // ========================================================================
-  async traverseGraph(collection, request) {
+  async getCollectionConfig(collection) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/graph/traverse`,
-      {
-        source: request.source,
-        strategy: request.strategy ?? "bfs",
-        max_depth: request.maxDepth ?? 3,
-        limit: request.limit ?? 100,
-        cursor: request.cursor,
-        rel_types: request.relTypes ?? []
-      }
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    const data = response.data;
-    return {
-      results: data.results.map((r) => ({
-        targetId: r.target_id,
-        depth: r.depth,
-        path: r.path
-      })),
-      nextCursor: data.next_cursor ?? void 0,
-      hasMore: data.has_more,
-      stats: {
-        visited: data.stats.visited,
-        depthReached: data.stats.depth_reached
-      }
-    };
+    return getCollectionConfig(this.asCrudTransport(), collection);
   }
-  async getNodeDegree(collection, nodeId) {
+  // ==========================================================================
+  // Streaming / PQ — delegates to streaming-backend.ts
+  // ==========================================================================
+  async trainPq(collection, options) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/graph/nodes/${nodeId}/degree`
-    );
-    if (response.error) {
-      if (response.error.code === "NOT_FOUND") {
-        throw new NotFoundError(`Collection '${collection}'`);
-      }
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return {
-      inDegree: response.data?.in_degree ?? 0,
-      outDegree: response.data?.out_degree ?? 0
-    };
+    return trainPq(this.asStreamingTransport(), collection, options);
+  }
+  async streamInsert(collection, docs) {
+    this.ensureInitialized();
+    return streamInsert(this.asStreamingTransport(), collection, docs);
+  }
+  // ==========================================================================
+  // Agent Memory — delegates to agent-memory-backend.ts
+  // ==========================================================================
+  async storeSemanticFact(collection, entry) {
+    this.ensureInitialized();
+    return storeSemanticFact(this.asAgentMemoryTransport(), collection, entry);
+  }
+  async searchSemanticMemory(collection, embedding, k = 5) {
+    return searchSemanticMemory(this.asAgentMemoryTransport(), collection, embedding, k);
+  }
+  async recordEpisodicEvent(collection, event) {
+    this.ensureInitialized();
+    return recordEpisodicEvent(this.asAgentMemoryTransport(), collection, event);
+  }
+  async recallEpisodicEvents(collection, embedding, k = 5) {
+    return recallEpisodicEvents(this.asAgentMemoryTransport(), collection, embedding, k);
+  }
+  async storeProceduralPattern(collection, pattern) {
+    this.ensureInitialized();
+    return storeProceduralPattern(this.asAgentMemoryTransport(), collection, pattern);
+  }
+  async matchProceduralPatterns(collection, embedding, k = 5) {
+    return matchProceduralPatterns(this.asAgentMemoryTransport(), collection, embedding, k);
+  }
+};
+
+// src/agent-memory.ts
+var AgentMemoryClient = class {
+  constructor(backend, config) {
+    this.backend = backend;
+    this.config = config;
+  }
+  /** Configured embedding dimension (default: 384) */
+  get dimension() {
+    return this.config?.dimension ?? 384;
+  }
+  /** Store a semantic fact */
+  async storeFact(collection, entry) {
+    return this.backend.storeSemanticFact(collection, entry);
+  }
+  /** Search semantic memory */
+  async searchFacts(collection, embedding, k = 5) {
+    return this.backend.searchSemanticMemory(collection, embedding, k);
+  }
+  /** Record an episodic event */
+  async recordEvent(collection, event) {
+    return this.backend.recordEpisodicEvent(collection, event);
+  }
+  /** Recall episodic events */
+  async recallEvents(collection, embedding, k = 5) {
+    return this.backend.recallEpisodicEvents(collection, embedding, k);
+  }
+  /** Store a procedural pattern */
+  async learnProcedure(collection, pattern) {
+    return this.backend.storeProceduralPattern(collection, pattern);
+  }
+  /** Match procedural patterns */
+  async recallProcedures(collection, embedding, k = 5) {
+    return this.backend.matchProceduralPatterns(collection, embedding, k);
   }
 };
 
@@ -1077,6 +1771,18 @@ var VelesDB = class {
     if (!Array.isArray(doc.vector) && !(doc.vector instanceof Float32Array)) {
       throw new ValidationError("Vector must be an array or Float32Array");
     }
+    if (this.config.backend === "rest" && (typeof doc.id !== "number" || !Number.isInteger(doc.id) || doc.id < 0 || doc.id > Number.MAX_SAFE_INTEGER)) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
+      );
+    }
+  }
+  validateRestPointId(id) {
+    if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
+      );
+    }
   }
   /**
    * Search for similar vectors
@@ -1086,12 +1792,12 @@ var VelesDB = class {
    * @param options - Search options
    * @returns Search results sorted by relevance
    */
-  async search(collection, query, options) {
+  async search(collection, query2, options) {
     this.ensureInitialized();
-    if (!query || !Array.isArray(query) && !(query instanceof Float32Array)) {
+    if (!query2 || !Array.isArray(query2) && !(query2 instanceof Float32Array)) {
       throw new ValidationError("Query must be an array or Float32Array");
     }
-    return this.backend.search(collection, query, options);
+    return this.backend.search(collection, query2, options);
   }
   /**
    * Search for multiple vectors in parallel
@@ -1121,6 +1827,7 @@ var VelesDB = class {
    */
   async delete(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.delete(collection, id);
   }
   /**
@@ -1132,6 +1839,7 @@ var VelesDB = class {
    */
   async get(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.get(collection, id);
   }
   /**
@@ -1142,12 +1850,12 @@ var VelesDB = class {
    * @param options - Search options (k, filter)
    * @returns Search results sorted by BM25 score
    */
-  async textSearch(collection, query, options) {
+  async textSearch(collection, query2, options) {
     this.ensureInitialized();
-    if (!query || typeof query !== "string") {
+    if (!query2 || typeof query2 !== "string") {
       throw new ValidationError("Query must be a non-empty string");
     }
-    return this.backend.textSearch(collection, query, options);
+    return this.backend.textSearch(collection, query2, options);
   }
   /**
    * Perform hybrid search combining vector similarity and BM25 text search
@@ -1186,7 +1894,7 @@ var VelesDB = class {
    * `, { q: queryVector });
    * 
    * for (const r of response.results) {
-   *   console.log(`Node ${r.nodeId}: ${r.fusedScore}`);
+   *   console.log(`ID ${r.id}, title: ${r.title}`);
    * }
    * ```
    */
@@ -1227,6 +1935,20 @@ var VelesDB = class {
    * });
    * ```
    */
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    if (!queryString || typeof queryString !== "string") {
+      throw new ValidationError("Query string must be a non-empty string");
+    }
+    return this.backend.queryExplain(queryString, params);
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    if (!collection || typeof collection !== "string") {
+      throw new ValidationError("Collection name must be a non-empty string");
+    }
+    return this.backend.collectionSanity(collection);
+  }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
     if (!Array.isArray(vectors) || vectors.length === 0) {
@@ -1239,9 +1961,39 @@ var VelesDB = class {
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
+  /**
+   * Train Product Quantization on a collection
+   *
+   * @param collection - Collection name
+   * @param options - PQ training options (m, k, opq)
+   * @returns Server response message
+   */
+  async trainPq(collection, options) {
+    this.ensureInitialized();
+    return this.backend.trainPq(collection, options);
+  }
+  /**
+   * 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
+   */
+  async streamInsert(collection, docs) {
+    this.ensureInitialized();
+    if (!Array.isArray(docs)) {
+      throw new ValidationError("Documents must be an array");
+    }
+    for (const doc of docs) {
+      this.validateDocument(doc);
+    }
+    await this.backend.streamInsert(collection, docs);
+  }
   /**
    * Check if a collection is empty
-   * 
+   *
    * @param collection - Collection name
    * @returns true if empty, false otherwise
    */
@@ -1435,6 +2187,77 @@ var VelesDB = class {
     }
     return this.backend.getNodeDegree(collection, nodeId);
   }
+  // ========================================================================
+  // Graph Collection Management (Phase 8)
+  // ========================================================================
+  /**
+   * Create a graph collection
+   *
+   * @param name - Collection name
+   * @param config - Optional graph collection configuration
+   */
+  async createGraphCollection(name, config) {
+    this.ensureInitialized();
+    if (!name || typeof name !== "string") {
+      throw new ValidationError("Collection name must be a non-empty string");
+    }
+    await this.backend.createGraphCollection(name, config);
+  }
+  /**
+   * Get collection statistics (requires prior analyze)
+   *
+   * @param collection - Collection name
+   * @returns Statistics or null if not yet analyzed
+   */
+  async getCollectionStats(collection) {
+    this.ensureInitialized();
+    return this.backend.getCollectionStats(collection);
+  }
+  /**
+   * Analyze a collection to compute statistics
+   *
+   * @param collection - Collection name
+   * @returns Computed statistics
+   */
+  async analyzeCollection(collection) {
+    this.ensureInitialized();
+    return this.backend.analyzeCollection(collection);
+  }
+  /**
+   * Get collection configuration
+   *
+   * @param collection - Collection name
+   * @returns Collection configuration details
+   */
+  async getCollectionConfig(collection) {
+    this.ensureInitialized();
+    return this.backend.getCollectionConfig(collection);
+  }
+  /**
+   * 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
+   */
+  async searchIds(collection, query2, options) {
+    this.ensureInitialized();
+    return this.backend.searchIds(collection, query2, options);
+  }
+  // ========================================================================
+  // Agent Memory (Phase 8)
+  // ========================================================================
+  /**
+   * Create an agent memory interface
+   *
+   * @param config - Optional agent memory configuration
+   * @returns AgentMemoryClient instance
+   */
+  agentMemory(config) {
+    this.ensureInitialized();
+    return new AgentMemoryClient(this.backend, config);
+  }
 };
 
 // src/query-builder.ts
@@ -1739,6 +2562,8 @@ function velesql() {
   return new VelesQLBuilder();
 }
 export {
+  AgentMemoryClient,
+  BackpressureError,
   ConnectionError,
   NotFoundError,
   RestBackend,