@wiscale/velesdb-sdk 1.5.1 → 1.7.0

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AgentMemoryClient: () => AgentMemoryClient,
   BackpressureError: () => BackpressureError,
   ConnectionError: () => ConnectionError,
   NotFoundError: () => NotFoundError,
@@ -77,6 +78,38 @@ var BackpressureError = class extends VelesDBError {
   }
 };
 
+// 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 {
   constructor() {
@@ -243,13 +276,13 @@ var WasmBackend = class {
       }
     }
   }
-  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}`,
@@ -406,14 +439,7 @@ var WasmBackend = class {
       k
     );
     return {
-      results: raw.map((r) => ({
-        nodeId: r.nodeId ?? r.node_id,
-        vectorScore: r.vectorScore ?? r.vector_score ?? null,
-        graphScore: r.graphScore ?? r.graph_score ?? null,
-        fusedScore: r.fusedScore ?? r.fused_score ?? 0,
-        bindings: r.bindings ?? {},
-        columnData: r.columnData ?? r.column_data ?? null
-      })),
+      results: raw,
       stats: {
         executionTimeMs: 0,
         strategy: "wasm-query",
@@ -462,17 +488,11 @@ var WasmBackend = class {
   }
   async queryExplain(_queryString, _params) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Query explain is not supported in WASM backend. Use REST backend for EXPLAIN support.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Query explain");
   }
   async collectionSanity(_collection) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Collection sanity endpoint is not supported in WASM backend. Use REST backend for diagnostics.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("Collection sanity endpoint");
   }
   async isEmpty(collectionName) {
     this.ensureInitialized();
@@ -552,51 +572,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();
-    throw new VelesDBError(
-      "PQ training is not available in WASM mode. Use REST backend for PQ training.",
-      "NOT_SUPPORTED"
-    );
+    wasmNotSupported("PQ training");
   }
   async streamInsert(_collection, _docs) {
     this.ensureInitialized();
-    throw new VelesDBError(
-      "Streaming insert is not available in WASM mode. Use REST backend for streaming.",
-      "NOT_SUPPORTED"
-    );
+    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) {
@@ -664,10 +1348,6 @@ var RestBackend = class {
     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;
@@ -677,37 +1357,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;
   }
-  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;
-  }
-  isLikelyAggregationQuery(query) {
-    return /\bGROUP\s+BY\b|\bHAVING\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bMIN\s*\(|\bMAX\s*\(/i.test(
-      query
-    );
-  }
   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}`;
     }
@@ -743,631 +1402,281 @@ 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 restId = this.parseRestPointId(doc.id);
-    const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/points`,
-      {
-        points: [{
-          id: restId,
-          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: this.parseRestPointId(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);
   }
-  sparseVectorToRestFormat(sv) {
-    const result = {};
-    for (const [k, v] of Object.entries(sv)) {
-      result[String(k)] = v;
-    }
-    return result;
+  async delete(collection, id) {
+    this.ensureInitialized();
+    return deletePoint(this.asCrudTransport(), collection, id);
   }
-  async search(collection, query, options) {
+  async get(collection, id) {
     this.ensureInitialized();
-    const queryVector = query instanceof Float32Array ? Array.from(query) : query;
-    const body = {
-      vector: queryVector,
-      top_k: options?.k ?? 10,
-      filter: options?.filter,
-      include_vectors: options?.includeVectors ?? false
-    };
-    if (options?.sparseVector) {
-      body.sparse_vector = this.sparseVectorToRestFormat(options.sparseVector);
-    }
-    const response = await this.request(
-      "POST",
-      `/collections/${encodeURIComponent(collection)}/search`,
-      body
-    );
-    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 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 restId = this.parseRestPointId(id);
-    const response = await this.request(
-      "DELETE",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
-    );
-    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 restId = this.parseRestPointId(id);
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
-    );
-    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 endpoint = this.isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
-    const response = await this.request(
-      "POST",
-      endpoint,
-      {
-        query: queryString,
-        params: params ?? {},
-        collection,
-        timeout_ms: options?.timeoutMs,
-        stream: options?.stream ?? false
-      }
-    );
-    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;
-    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 ?? []).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 queryExplain(queryString, params) {
+  async queryExplain(q, p) {
     this.ensureInitialized();
-    const response = await this.request(
-      "POST",
-      "/query/explain",
-      {
-        query: queryString,
-        params: params ?? {}
-      }
-    );
-    if (response.error) {
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    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
-      }
-    };
+    return queryExplain(this.asQueryTransport(), q, p);
   }
   async collectionSanity(collection) {
     this.ensureInitialized();
-    const response = await this.request(
-      "GET",
-      `/collections/${encodeURIComponent(collection)}/sanity`
-    );
-    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 {
-      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 ?? []
-    };
+    return collectionSanity(this.asQueryTransport(), collection);
   }
-  async multiQuerySearch(collection, vectors, options) {
+  // ==========================================================================
+  // Graph — delegates to graph-backend.ts
+  // ==========================================================================
+  async addEdge(collection, edge) {
     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,
-        avg_weight: options?.fusionParams?.avgWeight,
-        max_weight: options?.fusionParams?.maxWeight,
-        hit_weight: options?.fusionParams?.hitWeight,
-        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 addEdge(this.asCrudTransport(), collection, edge);
   }
-  async isEmpty(collection) {
+  async getEdges(collection, options) {
     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 getEdges(this.asCrudTransport(), collection, options);
   }
-  async flush(collection) {
+  async traverseGraph(collection, req) {
     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 traverseGraph(this.asCrudTransport(), collection, req);
   }
-  // ========================================================================
-  // Sparse / PQ / Streaming (v1.5)
-  // ========================================================================
-  async trainPq(collection, options) {
+  async getNodeDegree(collection, nodeId) {
     this.ensureInitialized();
-    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 this.request(
-      "POST",
-      "/query",
-      { query: queryString }
-    );
-    if (response.error) {
-      throw new VelesDBError(response.error.message, response.error.code);
-    }
-    return response.data?.message ?? "PQ training initiated";
+    return getNodeDegree(this.asCrudTransport(), collection, nodeId);
   }
-  async streamInsert(collection, docs) {
+  async createGraphCollection(name, config) {
     this.ensureInitialized();
-    for (const doc of docs) {
-      const restId = this.parseRestPointId(doc.id);
-      const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
-      const body = {
-        id: restId,
-        vector,
-        payload: doc.payload
-      };
-      if (doc.sparseVector) {
-        body.sparse_vector = this.sparseVectorToRestFormat(doc.sparseVector);
-      }
-      const url = `${this.baseUrl}/collections/${encodeURIComponent(collection)}/stream/insert`;
-      const headers = {
-        "Content-Type": "application/json"
-      };
-      if (this.apiKey) {
-        headers["Authorization"] = `Bearer ${this.apiKey}`;
-      }
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.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 = this.extractErrorPayload(data);
-          throw new VelesDBError(
-            errorPayload.message ?? `HTTP ${response.status}`,
-            errorPayload.code ?? this.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
-        );
-      }
-    }
+    return createGraphCollection(this.asCrudTransport(), name, config);
   }
-  async close() {
-    this._initialized = false;
-  }
-  // ========================================================================
-  // Index Management (EPIC-009)
-  // ========================================================================
+  // ==========================================================================
+  // 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);
   }
 };
 
 // src/client.ts
+function requireNonEmptyString(value, label) {
+  if (!value || typeof value !== "string") {
+    throw new ValidationError(`${label} must be a non-empty string`);
+  }
+}
+function requireVector(value, label) {
+  if (!value || !Array.isArray(value) && !(value instanceof Float32Array)) {
+    throw new ValidationError(`${label} must be an array or Float32Array`);
+  }
+}
+function validateDocsBatch(docs, validateDoc) {
+  if (!Array.isArray(docs)) {
+    throw new ValidationError("Documents must be an array");
+  }
+  for (const doc of docs) {
+    validateDoc(doc);
+  }
+}
 var VelesDB = class {
   /**
    * Create a new VelesDB client
@@ -1432,9 +1741,7 @@ var VelesDB = class {
    */
   async createCollection(name, config) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     const isMetadataOnly = config.collectionType === "metadata_only";
     if (!isMetadataOnly && (!config.dimension || config.dimension <= 0)) {
       throw new ValidationError("Dimension must be a positive integer for vector collections");
@@ -1456,9 +1763,7 @@ var VelesDB = class {
    */
   async createMetadataCollection(name) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     await this.backend.createCollection(name, { collectionType: "metadata_only" });
   }
   /**
@@ -1508,29 +1813,15 @@ var VelesDB = class {
    */
   async insertBatch(collection, docs) {
     this.ensureInitialized();
-    if (!Array.isArray(docs)) {
-      throw new ValidationError("Documents must be an array");
-    }
-    for (const doc of docs) {
-      this.validateDocument(doc);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.insertBatch(collection, docs);
   }
   validateDocument(doc) {
     if (doc.id === void 0 || doc.id === null) {
       throw new ValidationError("Document ID is required");
     }
-    if (!doc.vector) {
-      throw new ValidationError("Document vector is required");
-    }
-    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})`
-      );
-    }
+    requireVector(doc.vector, "Vector");
+    this.validateRestPointId(doc.id);
   }
   validateRestPointId(id) {
     if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
@@ -1547,12 +1838,10 @@ 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)) {
-      throw new ValidationError("Query must be an array or Float32Array");
-    }
-    return this.backend.search(collection, query, options);
+    requireVector(query2, "Query");
+    return this.backend.search(collection, query2, options);
   }
   /**
    * Search for multiple vectors in parallel
@@ -1567,9 +1856,7 @@ var VelesDB = class {
       throw new ValidationError("Searches must be an array");
     }
     for (const s of searches) {
-      if (!s.vector || !Array.isArray(s.vector) && !(s.vector instanceof Float32Array)) {
-        throw new ValidationError("Each search must have a vector (array or Float32Array)");
-      }
+      requireVector(s.vector, "Each search vector");
     }
     return this.backend.searchBatch(collection, searches);
   }
@@ -1605,12 +1892,10 @@ 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") {
-      throw new ValidationError("Query must be a non-empty string");
-    }
-    return this.backend.textSearch(collection, query, options);
+    requireNonEmptyString(query2, "Query");
+    return this.backend.textSearch(collection, query2, options);
   }
   /**
    * Perform hybrid search combining vector similarity and BM25 text search
@@ -1623,12 +1908,8 @@ var VelesDB = class {
    */
   async hybridSearch(collection, vector, textQuery, options) {
     this.ensureInitialized();
-    if (!vector || !Array.isArray(vector) && !(vector instanceof Float32Array)) {
-      throw new ValidationError("Vector must be an array or Float32Array");
-    }
-    if (!textQuery || typeof textQuery !== "string") {
-      throw new ValidationError("Text query must be a non-empty string");
-    }
+    requireVector(vector, "Vector");
+    requireNonEmptyString(textQuery, "Text query");
     return this.backend.hybridSearch(collection, vector, textQuery, options);
   }
   /**
@@ -1649,30 +1930,43 @@ 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}`);
    * }
    * ```
    */
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
-    if (!collection || typeof collection !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
-    if (!queryString || typeof queryString !== "string") {
-      throw new ValidationError("Query string must be a non-empty string");
-    }
+    requireNonEmptyString(collection, "Collection name");
+    requireNonEmptyString(queryString, "Query string");
     return this.backend.query(collection, queryString, params, options);
   }
+  /**
+   * 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
+   */
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    requireNonEmptyString(queryString, "Query string");
+    return this.backend.queryExplain(queryString, params);
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    requireNonEmptyString(collection, "Collection name");
+    return this.backend.collectionSanity(collection);
+  }
   /**
    * 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)
@@ -1681,7 +1975,7 @@ var VelesDB = class {
    *   fusion: 'rrf',
    *   fusionParams: { k: 60 }
    * });
-   * 
+   *
    * // Weighted fusion
    * const results = await db.multiQuerySearch('docs', [emb1, emb2], {
    *   k: 10,
@@ -1690,29 +1984,13 @@ 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) {
       throw new ValidationError("Vectors must be a non-empty array");
     }
     for (const v of vectors) {
-      if (!Array.isArray(v) && !(v instanceof Float32Array)) {
-        throw new ValidationError("Each vector must be an array or Float32Array");
-      }
+      requireVector(v, "Each vector");
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
@@ -1738,12 +2016,7 @@ var VelesDB = class {
    */
   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);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.streamInsert(collection, docs);
   }
   /**
@@ -1942,6 +2215,75 @@ 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();
+    requireNonEmptyString(name, "Collection name");
+    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
@@ -2247,6 +2589,7 @@ function velesql() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentMemoryClient,
   BackpressureError,
   ConnectionError,
   NotFoundError,