agentic-flow 2.0.7 → 3.0.0-alpha.2

package/dist/packages/agentdb/src/backends/hnswlib/HNSWLibBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HNSWLibBackend.js","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/hnswlib/HNSWLibBackend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HNSWLibBackend - Vector backend adapter for hnswlib-node\n *\n * Wraps existing HNSWIndex controller to implement VectorBackend interface.\n * Handles string ID to numeric label mapping required by hnswlib.\n *\n * Features:\n * - String ID support (maps to hnswlib numeric labels)\n * - Metadata storage alongside vectors\n * - Persistent save/load with mappings\n * - Backward compatible with existing HNSWIndex usage\n *\n * Note: hnswlib-node doesn't support true deletion - removed IDs are\n * tracked but vectors remain until rebuild.\n */\n\nimport type {\n  VectorBackend,\n  VectorConfig,\n  SearchResult,\n  SearchOptions,\n  VectorStats,\n} from '../VectorBackend.js';\nimport hnswlibNode from 'hnswlib-node';\nimport * as fs from 'fs/promises';\nimport * as fsSync from 'fs';\nimport * as path from 'path';\n\nconst { HierarchicalNSW } = hnswlibNode as any;\n\ninterface SavedMappings {\n  idToLabel: Record<string, number>;\n  labelToId: Record<string, string>;\n  metadata: Record<string, Record<string, any>>;\n  nextLabel: number;\n  config: VectorConfig;\n}\n\nexport class HNSWLibBackend implements VectorBackend {\n  readonly name = 'hnswlib' as const;\n\n  private index: any | null = null;\n  private config: VectorConfig;\n\n  // String ID <-> Numeric Label mappings (hnswlib requires numeric labels)\n  private idToLabel: Map<string, number> = new Map();\n  private labelToId: Map<number, string> = new Map();\n  private metadata: Map<string, Record<string, any>> = new Map();\n  private nextLabel: number = 0;\n\n  // Tracking for deletions (hnswlib doesn't support true deletion)\n  private deletedIds: Set<string> = new Set();\n\n  constructor(config: VectorConfig) {\n    // Handle both dimension and dimensions for backward compatibility\n    const dimension = config.dimension ?? config.dimensions;\n    if (!dimension) {\n      throw new Error('Vector dimension is required (use dimension or dimensions)');\n    }\n    this.config = {\n      maxElements: 100000,\n      M: 16,\n      efConstruction: 200,\n      efSearch: 100,\n      ...config,\n      dimension,  // Ensure dimension (singular) is always set\n    };\n  }\n\n  /**\n   * Initialize the HNSW index\n   * Must be called after construction\n   */\n  async initialize(): Promise<void> {\n    // Map metric names to hnswlib format\n    const metricMap: Record<string, string> = {\n      cosine: 'cosine',\n      l2: 'l2',\n      ip: 'ip',\n    };\n\n    const metric = metricMap[this.config.metric] || 'cosine';\n\n    // Create new HNSW index\n    this.index = new HierarchicalNSW(metric, this.config.dimension);\n    this.index.initIndex(\n      this.config.maxElements!,\n      this.config.M!,\n      this.config.efConstruction!\n    );\n    this.index.setEf(this.config.efSearch!);\n\n    console.log(\n      `[HNSWLibBackend] Initialized with dimension=${this.config.dimension}, ` +\n        `metric=${metric}, M=${this.config.M}, efConstruction=${this.config.efConstruction}`\n    );\n  }\n\n  /**\n   * Insert a single vector with optional metadata\n   */\n  insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void {\n    if (!this.index) {\n      throw new Error('Backend not initialized. Call initialize() first.');\n    }\n\n    // Check if ID already exists\n    if (this.idToLabel.has(id)) {\n      throw new Error(`Vector with ID '${id}' already exists`);\n    }\n\n    // Allocate numeric label\n    const label = this.nextLabel++;\n\n    // Add to index (hnswlib requires number[] not Float32Array)\n    this.index.addPoint(Array.from(embedding), label);\n\n    // Store mappings\n    this.idToLabel.set(id, label);\n    this.labelToId.set(label, id);\n\n    // Store metadata if provided\n    if (metadata) {\n      this.metadata.set(id, metadata);\n    }\n\n    // Remove from deleted set if re-inserting\n    this.deletedIds.delete(id);\n  }\n\n  /**\n   * Insert multiple vectors in batch\n   */\n  insertBatch(\n    items: Array<{\n      id: string;\n      embedding: Float32Array;\n      metadata?: Record<string, any>;\n    }>\n  ): void {\n    for (const item of items) {\n      this.insert(item.id, item.embedding, item.metadata);\n    }\n  }\n\n  /**\n   * Search for k-nearest neighbors\n   */\n  search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[] {\n    if (!this.index) {\n      throw new Error('Backend not initialized. Call initialize() first.');\n    }\n\n    // Update efSearch if specified\n    if (options?.efSearch) {\n      this.index.setEf(options.efSearch);\n    }\n\n    // Perform HNSW search\n    const result = this.index.searchKnn(Array.from(query), k);\n\n    const results: SearchResult[] = [];\n\n    for (let i = 0; i < result.neighbors.length; i++) {\n      const label = result.neighbors[i];\n      const distance = result.distances[i];\n\n      // Map label back to ID\n      const id = this.labelToId.get(label);\n      if (!id) {\n        console.warn(`[HNSWLibBackend] Label ${label} not found in mapping`);\n        continue;\n      }\n\n      // Skip deleted IDs\n      if (this.deletedIds.has(id)) {\n        continue;\n      }\n\n      // Convert distance to similarity\n      const similarity = this.distanceToSimilarity(distance);\n\n      // Apply threshold if specified\n      if (options?.threshold !== undefined && similarity < options.threshold) {\n        continue;\n      }\n\n      results.push({\n        id,\n        distance,\n        similarity,\n        metadata: this.metadata.get(id),\n      });\n    }\n\n    // Apply metadata filters if specified (post-filtering)\n    if (options?.filter) {\n      return this.applyFilters(results, options.filter);\n    }\n\n    return results;\n  }\n\n  /**\n   * Remove a vector by ID\n   * Note: hnswlib doesn't support true deletion - we mark as deleted\n   */\n  remove(id: string): boolean {\n    const label = this.idToLabel.get(id);\n    if (label === undefined) {\n      return false; // Not found\n    }\n\n    // Mark as deleted (can't actually remove from hnswlib)\n    this.deletedIds.add(id);\n    this.metadata.delete(id);\n\n    // Note: We keep idToLabel/labelToId mappings for consistency\n    // A full rebuild would be needed to reclaim space\n\n    return true;\n  }\n\n  /**\n   * Get backend statistics\n   */\n  getStats(): VectorStats {\n    const activeCount = this.idToLabel.size - this.deletedIds.size;\n\n    return {\n      count: activeCount,\n      dimension: this.config.dimension || 384,\n      metric: this.config.metric,\n      backend: 'hnswlib',\n      memoryUsage: 0, // hnswlib doesn't expose memory usage\n    };\n  }\n\n  /**\n   * Save index to disk with mappings\n   */\n  async save(savePath: string): Promise<void> {\n    if (!this.index) {\n      throw new Error('No index to save');\n    }\n\n    try {\n      // Create directory if needed\n      const indexDir = path.dirname(savePath);\n      if (!fsSync.existsSync(indexDir)) {\n        await fs.mkdir(indexDir, { recursive: true });\n      }\n\n      // Save HNSW index\n      this.index.writeIndex(savePath);\n\n      // Save mappings and metadata\n      const mappingsPath = savePath + '.mappings.json';\n      const mappings: SavedMappings = {\n        idToLabel: Object.fromEntries(this.idToLabel.entries()),\n        labelToId: Object.fromEntries(\n          Array.from(this.labelToId.entries()).map(([k, v]) => [k.toString(), v])\n        ),\n        metadata: Object.fromEntries(this.metadata.entries()),\n        nextLabel: this.nextLabel,\n        config: this.config,\n      };\n\n      await fs.writeFile(mappingsPath, JSON.stringify(mappings, null, 2));\n\n      console.log(`[HNSWLibBackend] Index saved to ${savePath}`);\n      console.log(`[HNSWLibBackend] Mappings saved to ${mappingsPath}`);\n    } catch (error) {\n      console.error('[HNSWLibBackend] Failed to save index:', error);\n      throw error;\n    }\n  }\n\n  /**\n   * Load index from disk with mappings\n   */\n  async load(loadPath: string): Promise<void> {\n    if (!fsSync.existsSync(loadPath)) {\n      throw new Error(`Index file not found: ${loadPath}`);\n    }\n\n    try {\n      console.log(`[HNSWLibBackend] Loading index from ${loadPath}...`);\n\n      // Initialize index first\n      const metricMap: Record<string, string> = {\n        cosine: 'cosine',\n        l2: 'l2',\n        ip: 'ip',\n      };\n      const metric = metricMap[this.config.metric] || 'cosine';\n\n      this.index = new HierarchicalNSW(metric, this.config.dimension);\n\n      // Load HNSW index\n      this.index.readIndex(loadPath);\n      this.index.setEf(this.config.efSearch!);\n\n      // Load mappings and metadata\n      const mappingsPath = loadPath + '.mappings.json';\n      if (fsSync.existsSync(mappingsPath)) {\n        const mappingsData: SavedMappings = JSON.parse(\n          await fs.readFile(mappingsPath, 'utf-8')\n        );\n\n        // Restore mappings\n        this.idToLabel = new Map(Object.entries(mappingsData.idToLabel));\n        this.labelToId = new Map(\n          Object.entries(mappingsData.labelToId).map(([k, v]) => [Number(k), v])\n        );\n        this.metadata = new Map(Object.entries(mappingsData.metadata || {}));\n        this.nextLabel = mappingsData.nextLabel;\n\n        // Update config if saved\n        if (mappingsData.config) {\n          this.config = { ...this.config, ...mappingsData.config };\n        }\n\n        console.log(\n          `[HNSWLibBackend] ✅ Index loaded successfully (${this.idToLabel.size} vectors)`\n        );\n      } else {\n        console.warn(\n          '[HNSWLibBackend] No mappings file found - index loaded without ID mappings'\n        );\n      }\n    } catch (error) {\n      console.error('[HNSWLibBackend] Failed to load index:', error);\n      this.index = null;\n      throw error;\n    }\n  }\n\n  /**\n   * Close and cleanup resources\n   */\n  close(): void {\n    this.index = null;\n    this.idToLabel.clear();\n    this.labelToId.clear();\n    this.metadata.clear();\n    this.deletedIds.clear();\n    this.nextLabel = 0;\n  }\n\n  /**\n   * Convert distance to similarity based on metric\n   * Maps to [0, 1] range where 1 = most similar\n   */\n  private distanceToSimilarity(distance: number): number {\n    switch (this.config.metric) {\n      case 'cosine':\n        // Cosine distance is 1 - similarity, so invert\n        return 1 - distance;\n\n      case 'l2':\n        // Euclidean distance: use exponential decay\n        return Math.exp(-distance);\n\n      case 'ip':\n        // Inner product: negate distance (higher IP = more similar)\n        return -distance;\n\n      default:\n        return 1 - distance;\n    }\n  }\n\n  /**\n   * Apply metadata filters (post-filtering)\n   */\n  private applyFilters(\n    results: SearchResult[],\n    filters: Record<string, any>\n  ): SearchResult[] {\n    return results.filter((result) => {\n      if (!result.metadata) return false;\n\n      // Check if all filter conditions match\n      return Object.entries(filters).every(([key, value]) => {\n        return result.metadata![key] === value;\n      });\n    });\n  }\n\n  /**\n   * Check if needs rebuilding (for backward compat with HNSWIndex)\n   * @param updateThreshold - Percentage of deletes to trigger rebuild (default: 0.1)\n   */\n  needsRebuild(updateThreshold: number = 0.1): boolean {\n    if (this.idToLabel.size === 0) return false;\n\n    const deletePercentage = this.deletedIds.size / this.idToLabel.size;\n    return deletePercentage > updateThreshold;\n  }\n\n  /**\n   * Update efSearch parameter\n   */\n  setEfSearch(ef: number): void {\n    if (this.index) {\n      this.index.setEf(ef);\n      this.config.efSearch = ef;\n      console.log(`[HNSWLibBackend] efSearch updated to ${ef}`);\n    }\n  }\n\n  /**\n   * Check if backend is ready\n   */\n  isReady(): boolean {\n    return this.index !== null;\n  }\n}\n"]}

package/dist/packages/agentdb/src/backends/ruvector/GuardedVectorBackend.d.ts

@@ -0,0 +1,93 @@
+/**
+ * GuardedVectorBackend - Proof-Gated State Mutation (ADR-060)
+ *
+ * A drop-in replacement for RuVectorBackend that requires cryptographic
+ * mutation proofs before allowing any state-changing operation. Read-only
+ * operations pass through without proof.
+ *
+ * Architecture:
+ * - Wraps any VectorBackend implementation
+ * - MutationGuard validates and attests each mutation
+ * - AttestationLog records all proof attempts for audit
+ * - ProofDeniedError thrown when mutation is rejected
+ *
+ * Mutating operations (require proof):
+ *   insert, insertBatch, search, remove, save, load
+ *
+ * Read-only operations (pass through):
+ *   getStats, getLearning, setLearning, close
+ */
+import type { VectorBackend, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';
+import type { MutationDenial, AttestationToken } from '../../security/MutationGuard.js';
+import { MutationGuard } from '../../security/MutationGuard.js';
+import type { AttestationLog } from '../../security/AttestationLog.js';
+/**
+ * Error thrown when a mutation proof is denied by the guard.
+ *
+ * Contains the denial reason, error code, operation name,
+ * and the full MutationDenial object for programmatic handling.
+ */
+export declare class ProofDeniedError extends Error {
+    readonly code: string;
+    readonly operation: string;
+    readonly denial: MutationDenial;
+    constructor(reason: string, code: string, operation: string, denial: MutationDenial);
+}
+/**
+ * GuardedVectorBackend - VectorBackend wrapper with proof-gated mutations
+ *
+ * Every mutating method requires an optional AttestationToken. When provided,
+ * the token is validated by MutationGuard before the operation proceeds.
+ * If the proof is denied, a ProofDeniedError is thrown and the operation
+ * is not forwarded to the inner backend.
+ */
+export declare class GuardedVectorBackend implements VectorBackend {
+    readonly name: "ruvector";
+    private readonly inner;
+    private readonly guard;
+    private readonly log?;
+    constructor(inner: VectorBackend, guard: MutationGuard, log?: AttestationLog);
+    private requireProof;
+    private wrapBackendError;
+    insert(id: string, embedding: Float32Array, metadata?: Record<string, any>, token?: AttestationToken): void;
+    insertBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, any>;
+    }>, token?: AttestationToken): void;
+    search(query: Float32Array, k: number, options?: SearchOptions, token?: AttestationToken): SearchResult[];
+    remove(id: string, token?: AttestationToken): boolean;
+    save(path: string, token?: AttestationToken): Promise<void>;
+    load(path: string, token?: AttestationToken): Promise<void>;
+    /**
+     * Get backend statistics (read-only, no proof required).
+     *
+     * Merges inner backend stats with guard stats and optional log stats.
+     */
+    getStats(): VectorStats;
+    /**
+     * Get the learning instance from the inner backend (read-only, no proof required).
+     */
+    getLearning(): any;
+    /**
+     * Set the learning instance on the inner backend (pass-through, no proof required).
+     */
+    setLearning(learning: any): void;
+    /**
+     * Close and cleanup resources (pass-through, no proof required).
+     */
+    close(): void;
+    /**
+     * Get the underlying inner backend for direct access when needed.
+     */
+    getInner(): VectorBackend;
+    /**
+     * Get the mutation guard instance.
+     */
+    getGuard(): MutationGuard;
+    /**
+     * Get the attestation log instance, if configured.
+     */
+    getLog(): AttestationLog | undefined;
+}
+//# sourceMappingURL=GuardedVectorBackend.d.ts.map

package/dist/packages/agentdb/src/backends/ruvector/GuardedVectorBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuardedVectorBackend.d.ts","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/ruvector/GuardedVectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACjH,OAAO,KAAK,EAAiB,cAAc,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACvG,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,MAAM,EAAE,cAAc,CAAC;gBAE3B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc;CAOpF;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAiB;gBAE1B,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,cAAc;IAM5E,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,gBAAgB;IAOxB,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,YAAY,EACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,KAAK,CAAC,EAAE,gBAAgB,GACvB,IAAI;IASP,WAAW,CACT,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,EACrF,KAAK,CAAC,EAAE,gBAAgB,GACvB,IAAI;IASP,MAAM,CACJ,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,aAAa,EACvB,KAAK,CAAC,EAAE,gBAAgB,GACvB,YAAY,EAAE;IASjB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO;IAS/C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE;;;;OAIG;IACH,QAAQ,IAAI,WAAW;IAgBvB;;OAEG;IACH,WAAW,IAAI,GAAG;IAIlB;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI;IAIhC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,QAAQ,IAAI,aAAa;IAIzB;;OAEG;IACH,QAAQ,IAAI,aAAa;IAIzB;;OAEG;IACH,MAAM,IAAI,cAAc,GAAG,SAAS;CAGrC"}

package/dist/packages/agentdb/src/backends/ruvector/GuardedVectorBackend.js

@@ -0,0 +1,182 @@
+/**
+ * GuardedVectorBackend - Proof-Gated State Mutation (ADR-060)
+ *
+ * A drop-in replacement for RuVectorBackend that requires cryptographic
+ * mutation proofs before allowing any state-changing operation. Read-only
+ * operations pass through without proof.
+ *
+ * Architecture:
+ * - Wraps any VectorBackend implementation
+ * - MutationGuard validates and attests each mutation
+ * - AttestationLog records all proof attempts for audit
+ * - ProofDeniedError thrown when mutation is rejected
+ *
+ * Mutating operations (require proof):
+ *   insert, insertBatch, search, remove, save, load
+ *
+ * Read-only operations (pass through):
+ *   getStats, getLearning, setLearning, close
+ */
+import { MutationGuard } from '../../security/MutationGuard.js';
+/**
+ * Error thrown when a mutation proof is denied by the guard.
+ *
+ * Contains the denial reason, error code, operation name,
+ * and the full MutationDenial object for programmatic handling.
+ */
+export class ProofDeniedError extends Error {
+    code;
+    operation;
+    denial;
+    constructor(reason, code, operation, denial) {
+        super(`Proof denied for ${operation}: ${reason}`);
+        this.name = 'ProofDeniedError';
+        this.code = code;
+        this.operation = operation;
+        this.denial = denial;
+    }
+}
+/**
+ * GuardedVectorBackend - VectorBackend wrapper with proof-gated mutations
+ *
+ * Every mutating method requires an optional AttestationToken. When provided,
+ * the token is validated by MutationGuard before the operation proceeds.
+ * If the proof is denied, a ProofDeniedError is thrown and the operation
+ * is not forwarded to the inner backend.
+ */
+export class GuardedVectorBackend {
+    name = 'ruvector';
+    inner;
+    guard;
+    log;
+    constructor(inner, guard, log) {
+        this.inner = inner;
+        this.guard = guard;
+        this.log = log;
+    }
+    requireProof(result, operation, token) {
+        if (MutationGuard.isDenial(result)) {
+            if (this.log) {
+                this.log.recordDenial(result, token?.agentId ?? 'unknown', token?.namespace ?? 'default');
+            }
+            throw new ProofDeniedError(result.reason, result.code, operation, result);
+        }
+        if (this.log) {
+            this.log.record(result);
+        }
+    }
+    wrapBackendError(err, operation, token) {
+        const msg = err.message ?? String(err);
+        const denial = { operation, reason: `Backend error: ${msg}`, code: 'BACKEND_ERROR', timestamp: Date.now() };
+        if (this.log)
+            this.log.recordDenial(denial, token?.agentId ?? 'unknown', token?.namespace ?? 'default');
+        throw new ProofDeniedError(denial.reason, denial.code, operation, denial);
+    }
+    insert(id, embedding, metadata, token) {
+        this.requireProof(this.guard.proveInsert(id, embedding, metadata, token), 'insert', token);
+        try {
+            this.inner.insert(id, embedding, metadata);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'insert', token);
+        }
+    }
+    insertBatch(items, token) {
+        this.requireProof(this.guard.proveBatchInsert(items, token), 'insertBatch', token);
+        try {
+            this.inner.insertBatch(items);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'insertBatch', token);
+        }
+    }
+    search(query, k, options, token) {
+        this.requireProof(this.guard.proveSearch(query, k, options, token), 'search', token);
+        try {
+            return this.inner.search(query, k, options);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'search', token);
+        }
+    }
+    remove(id, token) {
+        this.requireProof(this.guard.proveRemove(id, token), 'remove', token);
+        try {
+            return this.inner.remove(id);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'remove', token);
+        }
+    }
+    async save(path, token) {
+        this.requireProof(this.guard.proveSave(path, token), 'save', token);
+        try {
+            return await this.inner.save(path);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'save', token);
+        }
+    }
+    async load(path, token) {
+        this.requireProof(this.guard.proveLoad(path, token), 'load', token);
+        try {
+            return await this.inner.load(path);
+        }
+        catch (err) {
+            this.wrapBackendError(err, 'load', token);
+        }
+    }
+    /**
+     * Get backend statistics (read-only, no proof required).
+     *
+     * Merges inner backend stats with guard stats and optional log stats.
+     */
+    getStats() {
+        const innerStats = this.inner.getStats();
+        const guardStats = this.guard.getStats();
+        return {
+            ...innerStats,
+            ...(guardStats.proofsIssued !== undefined && {
+                totalProofs: guardStats.proofsIssued,
+                totalDenials: guardStats.denials,
+            }),
+        };
+    }
+    /**
+     * Get the learning instance from the inner backend (read-only, no proof required).
+     */
+    getLearning() {
+        return this.inner.getLearning?.() ?? null;
+    }
+    /**
+     * Set the learning instance on the inner backend (pass-through, no proof required).
+     */
+    setLearning(learning) {
+        this.inner.setLearning?.(learning);
+    }
+    /**
+     * Close and cleanup resources (pass-through, no proof required).
+     */
+    close() {
+        this.inner.close();
+    }
+    /**
+     * Get the underlying inner backend for direct access when needed.
+     */
+    getInner() {
+        return this.inner;
+    }
+    /**
+     * Get the mutation guard instance.
+     */
+    getGuard() {
+        return this.guard;
+    }
+    /**
+     * Get the attestation log instance, if configured.
+     */
+    getLog() {
+        return this.log;
+    }
+}
+//# sourceMappingURL=GuardedVectorBackend.js.map

package/dist/packages/agentdb/src/backends/ruvector/GuardedVectorBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuardedVectorBackend.js","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/ruvector/GuardedVectorBackend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * GuardedVectorBackend - Proof-Gated State Mutation (ADR-060)\n *\n * A drop-in replacement for RuVectorBackend that requires cryptographic\n * mutation proofs before allowing any state-changing operation. Read-only\n * operations pass through without proof.\n *\n * Architecture:\n * - Wraps any VectorBackend implementation\n * - MutationGuard validates and attests each mutation\n * - AttestationLog records all proof attempts for audit\n * - ProofDeniedError thrown when mutation is rejected\n *\n * Mutating operations (require proof):\n *   insert, insertBatch, search, remove, save, load\n *\n * Read-only operations (pass through):\n *   getStats, getLearning, setLearning, close\n */\n\nimport type { VectorBackend, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';\nimport type { MutationProof, MutationDenial, AttestationToken } from '../../security/MutationGuard.js';\nimport { MutationGuard } from '../../security/MutationGuard.js';\nimport type { AttestationLog } from '../../security/AttestationLog.js';\n\n/**\n * Error thrown when a mutation proof is denied by the guard.\n *\n * Contains the denial reason, error code, operation name,\n * and the full MutationDenial object for programmatic handling.\n */\nexport class ProofDeniedError extends Error {\n  public readonly code: string;\n  public readonly operation: string;\n  public readonly denial: MutationDenial;\n\n  constructor(reason: string, code: string, operation: string, denial: MutationDenial) {\n    super(`Proof denied for ${operation}: ${reason}`);\n    this.name = 'ProofDeniedError';\n    this.code = code;\n    this.operation = operation;\n    this.denial = denial;\n  }\n}\n\n/**\n * GuardedVectorBackend - VectorBackend wrapper with proof-gated mutations\n *\n * Every mutating method requires an optional AttestationToken. When provided,\n * the token is validated by MutationGuard before the operation proceeds.\n * If the proof is denied, a ProofDeniedError is thrown and the operation\n * is not forwarded to the inner backend.\n */\nexport class GuardedVectorBackend implements VectorBackend {\n  readonly name = 'ruvector' as const;\n\n  private readonly inner: VectorBackend;\n  private readonly guard: MutationGuard;\n  private readonly log?: AttestationLog;\n\n  constructor(inner: VectorBackend, guard: MutationGuard, log?: AttestationLog) {\n    this.inner = inner;\n    this.guard = guard;\n    this.log = log;\n  }\n\n  private requireProof(\n    result: MutationProof | MutationDenial,\n    operation: string,\n    token?: AttestationToken,\n  ): asserts result is MutationProof {\n    if (MutationGuard.isDenial(result)) {\n      if (this.log) {\n        this.log.recordDenial(result, token?.agentId ?? 'unknown', token?.namespace ?? 'default');\n      }\n      throw new ProofDeniedError(result.reason, result.code, operation, result);\n    }\n    if (this.log) {\n      this.log.record(result);\n    }\n  }\n\n  private wrapBackendError(err: unknown, operation: string, token?: AttestationToken): never {\n    const msg = (err as Error).message ?? String(err);\n    const denial: MutationDenial = { operation, reason: `Backend error: ${msg}`, code: 'BACKEND_ERROR', timestamp: Date.now() };\n    if (this.log) this.log.recordDenial(denial, token?.agentId ?? 'unknown', token?.namespace ?? 'default');\n    throw new ProofDeniedError(denial.reason, denial.code, operation, denial);\n  }\n\n  insert(\n    id: string,\n    embedding: Float32Array,\n    metadata?: Record<string, any>,\n    token?: AttestationToken\n  ): void {\n    this.requireProof(this.guard.proveInsert(id, embedding, metadata, token), 'insert', token);\n    try {\n      this.inner.insert(id, embedding, metadata);\n    } catch (err) {\n      this.wrapBackendError(err, 'insert', token);\n    }\n  }\n\n  insertBatch(\n    items: Array<{ id: string; embedding: Float32Array; metadata?: Record<string, any> }>,\n    token?: AttestationToken\n  ): void {\n    this.requireProof(this.guard.proveBatchInsert(items, token), 'insertBatch', token);\n    try {\n      this.inner.insertBatch(items);\n    } catch (err) {\n      this.wrapBackendError(err, 'insertBatch', token);\n    }\n  }\n\n  search(\n    query: Float32Array,\n    k: number,\n    options?: SearchOptions,\n    token?: AttestationToken\n  ): SearchResult[] {\n    this.requireProof(this.guard.proveSearch(query, k, options, token), 'search', token);\n    try {\n      return this.inner.search(query, k, options);\n    } catch (err) {\n      this.wrapBackendError(err, 'search', token);\n    }\n  }\n\n  remove(id: string, token?: AttestationToken): boolean {\n    this.requireProof(this.guard.proveRemove(id, token), 'remove', token);\n    try {\n      return this.inner.remove(id);\n    } catch (err) {\n      this.wrapBackendError(err, 'remove', token);\n    }\n  }\n\n  async save(path: string, token?: AttestationToken): Promise<void> {\n    this.requireProof(this.guard.proveSave(path, token), 'save', token);\n    try {\n      return await this.inner.save(path);\n    } catch (err) {\n      this.wrapBackendError(err, 'save', token);\n    }\n  }\n\n  async load(path: string, token?: AttestationToken): Promise<void> {\n    this.requireProof(this.guard.proveLoad(path, token), 'load', token);\n    try {\n      return await this.inner.load(path);\n    } catch (err) {\n      this.wrapBackendError(err, 'load', token);\n    }\n  }\n\n  /**\n   * Get backend statistics (read-only, no proof required).\n   *\n   * Merges inner backend stats with guard stats and optional log stats.\n   */\n  getStats(): VectorStats {\n    const innerStats = this.inner.getStats();\n    const guardStats = this.guard.getStats();\n\n    return {\n      ...innerStats,\n      ...(guardStats.proofsIssued !== undefined && {\n        totalProofs: guardStats.proofsIssued,\n        totalDenials: guardStats.denials,\n      }),\n    } as VectorStats & {\n      totalProofs?: number;\n      totalDenials?: number;\n    };\n  }\n\n  /**\n   * Get the learning instance from the inner backend (read-only, no proof required).\n   */\n  getLearning(): any {\n    return (this.inner as any).getLearning?.() ?? null;\n  }\n\n  /**\n   * Set the learning instance on the inner backend (pass-through, no proof required).\n   */\n  setLearning(learning: any): void {\n    (this.inner as any).setLearning?.(learning);\n  }\n\n  /**\n   * Close and cleanup resources (pass-through, no proof required).\n   */\n  close(): void {\n    this.inner.close();\n  }\n\n  /**\n   * Get the underlying inner backend for direct access when needed.\n   */\n  getInner(): VectorBackend {\n    return this.inner;\n  }\n\n  /**\n   * Get the mutation guard instance.\n   */\n  getGuard(): MutationGuard {\n    return this.guard;\n  }\n\n  /**\n   * Get the attestation log instance, if configured.\n   */\n  getLog(): AttestationLog | undefined {\n    return this.log;\n  }\n}\n"]}

package/dist/packages/agentdb/src/backends/ruvector/RuVectorBackend.d.ts

@@ -0,0 +1,108 @@
+/**
+ * RuVectorBackend - High-Performance Vector Storage (v0.1.99+)
+ *
+ * Implements VectorBackend using ruvector with native SIMD and multi-threading.
+ * Updated for ruvector 0.1.99+ async API with object-style insert/search.
+ *
+ * Features:
+ * - Native SIMD acceleration (2-4x faster vector ops)
+ * - Automatic fallback when ruvector packages not installed
+ * - Separate metadata storage for rich queries
+ * - Score-to-similarity conversion for all metrics
+ * - Batch operations for optimal throughput
+ * - Parallel batch search via searchBatch()
+ * - Persistent storage with separate metadata files
+ */
+import type { VectorBackend, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';
+import type { RuVectorLearning } from './RuVectorLearning.js';
+export declare class RuVectorBackend implements VectorBackend {
+    readonly name: "ruvector";
+    private db;
+    private config;
+    private metadata;
+    private initialized;
+    private learning;
+    private nativeVersion;
+    private isNativeImpl;
+    constructor(config: VectorConfig);
+    /**
+     * Initialize RuVector database with SIMD and multi-threading (0.1.99+)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Insert single vector with optional metadata.
+     * Uses ruvector 0.1.99+ object-style API: insert({ id, vector, metadata? })
+     */
+    insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;
+    /**
+     * Batch insert for optimal performance.
+     * Uses ruvector 0.1.99+ insertBatch([{ id, vector, metadata? }])
+     */
+    insertBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, any>;
+    }>): void;
+    /**
+     * Set a RuVectorLearning instance for GNN-enhanced search
+     */
+    setLearning(learning: RuVectorLearning | null): void;
+    /**
+     * Get the current RuVectorLearning instance, if any
+     */
+    getLearning(): RuVectorLearning | null;
+    /**
+     * Search for k-nearest neighbors with optional filtering and GNN enhancement.
+     * Uses ruvector 0.1.99+ search({ vector, k, efSearch?, filter? })
+     * Results contain { id, score, vector?, metadata? }
+     */
+    search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
+    /**
+     * Batch search for parallel query processing (0.1.99+).
+     * Executes multiple searches concurrently for throughput.
+     */
+    searchBatch(queries: Float32Array[], k: number, options?: SearchOptions): Promise<SearchResult[][]>;
+    /**
+     * Remove vector by ID.
+     * Uses ruvector 0.1.99+ delete(id) instead of remove(id)
+     */
+    remove(id: string): boolean;
+    /**
+     * Get database statistics including native SIMD status
+     */
+    getStats(): VectorStats;
+    /**
+     * Get extended stats including SIMD and version info
+     */
+    getExtendedStats(): {
+        count: number;
+        dimension: number;
+        metric: string;
+        backend: string;
+        nativeVersion: string;
+        isNative: boolean;
+        simdEnabled: boolean;
+    };
+    /**
+     * Save index and metadata to disk
+     */
+    save(path: string): Promise<void>;
+    /**
+     * Load index and metadata from disk
+     */
+    load(path: string): Promise<void>;
+    /**
+     * Close and cleanup resources
+     */
+    close(): void;
+    /**
+     * Convert score to distance for backward compatibility.
+     * ruvector 0.1.99+ returns scores (higher = more similar).
+     */
+    private scoreToDistance;
+    /**
+     * Ensure database is initialized before operations
+     */
+    private ensureInitialized;
+}
+//# sourceMappingURL=RuVectorBackend.d.ts.map

package/dist/packages/agentdb/src/backends/ruvector/RuVectorBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuVectorBackend.d.ts","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/ruvector/RuVectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,YAAY,CAAkB;gBAE1B,MAAM,EAAE,YAAY;IAUhC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgEjC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IA0BjF;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,GAAG,IAAI;IAuBxG;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI;IAIpD;;OAEG;IACH,WAAW,IAAI,gBAAgB,GAAG,IAAI;IAItC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE;IAgI/E;;;OAGG;IACG,WAAW,CACf,OAAO,EAAE,YAAY,EAAE,EACvB,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;IAiC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAsB3B;;OAEG;IACH,QAAQ,IAAI,WAAW;IA4BvB;;OAEG;IACH,gBAAgB,IAAI;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;KACtB;IAaD;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvC;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}