forge-server 0.1.0

package/src/storage/interfaces.ts

@@ -0,0 +1,201 @@
+/**
+ * Storage abstraction interfaces (ADR-8).
+ * All tool handlers interact with these interfaces, never with FalkorDB/Qdrant clients directly.
+ * This enables swapping implementations without rewriting the query engine.
+ */
+
+import type {
+  GraphNode,
+  GraphEdge,
+  GraphQueryResult,
+  VectorSearchResult,
+  CodeChunkPayload,
+  ObservationPayload,
+  CacheEntry,
+  CacheStats,
+} from '../util/types.js';
+
+// ============================================================
+// GraphStore Interface
+// ============================================================
+
+export interface GraphStore {
+  /**
+   * Connect to the graph database.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect and clean up.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Check if the connection is healthy.
+   */
+  isHealthy(): Promise<boolean>;
+
+  /**
+   * Execute a raw Cypher query.
+   */
+  query(cypher: string, params?: Record<string, unknown>): Promise<GraphQueryResult>;
+
+  /**
+   * Create or update a node. Uses MERGE to avoid duplicates.
+   * Returns the node's internal ID.
+   */
+  upsertNode(label: string, matchProps: Record<string, unknown>, setProps: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Create or update an edge between two nodes.
+   */
+  upsertEdge(
+    fromLabel: string,
+    fromProps: Record<string, unknown>,
+    edgeType: string,
+    edgeProps: Record<string, unknown>,
+    toLabel: string,
+    toProps: Record<string, unknown>
+  ): Promise<void>;
+
+  /**
+   * Delete all nodes and edges for a given file path + repo.
+   * Used during re-indexing.
+   */
+  deleteFile(filePath: string, repoId: string): Promise<void>;
+
+  /**
+   * Delete all nodes and edges for a given repo.
+   */
+  deleteRepo(repoId: string): Promise<void>;
+
+  /**
+   * Get total node and edge counts.
+   */
+  getCounts(): Promise<{ totalNodes: number; totalEdges: number; byLabel: Record<string, number> }>;
+
+  /**
+   * Ensure all required indexes exist.
+   */
+  ensureIndexes(): Promise<void>;
+}
+
+// ============================================================
+// VectorStore Interface
+// ============================================================
+
+export interface VectorSearchOptions {
+  limit?: number;
+  filter?: Record<string, unknown>;
+  scoreThreshold?: number;
+}
+
+export interface VectorStore {
+  /**
+   * Connect / verify connection.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Check if the connection is healthy.
+   */
+  isHealthy(): Promise<boolean>;
+
+  /**
+   * Ensure collections exist with the correct schema.
+   */
+  ensureCollections(dimension: number): Promise<void>;
+
+  /**
+   * Upsert code chunk vectors.
+   */
+  upsertCodeChunks(
+    chunks: Array<{ id: string; vector: number[]; payload: CodeChunkPayload }>
+  ): Promise<void>;
+
+  /**
+   * Upsert observation vectors.
+   */
+  upsertObservation(id: string, vector: number[], payload: ObservationPayload): Promise<void>;
+
+  /**
+   * Semantic search over code_chunks collection.
+   */
+  searchCodeChunks(queryVector: number[], options: VectorSearchOptions): Promise<VectorSearchResult[]>;
+
+  /**
+   * Semantic search over observations collection.
+   */
+  searchObservations(queryVector: number[], options: VectorSearchOptions): Promise<VectorSearchResult[]>;
+
+  /**
+   * Delete all code chunk vectors for a file.
+   */
+  deleteFileChunks(filePath: string, repoId: string): Promise<void>;
+
+  /**
+   * Delete all vectors for a repo.
+   */
+  deleteRepoChunks(repoId: string): Promise<void>;
+
+  /**
+   * Get count of points in each collection.
+   */
+  getCounts(): Promise<{ codeChunks: number; observations: number }>;
+
+  /**
+   * Retrieve a specific observation by ID.
+   */
+  getObservation(id: string): Promise<ObservationPayload | null>;
+
+  /**
+   * Update an observation's payload fields.
+   */
+  updateObservation(id: string, payload: Partial<ObservationPayload>): Promise<void>;
+
+  /**
+   * Filter observations by payload conditions (e.g. by key + namespace).
+   */
+  filterObservations(filter: Record<string, unknown>, limit?: number): Promise<VectorSearchResult[]>;
+}
+
+// ============================================================
+// FileContentCache Interface
+// ============================================================
+
+export interface FileContentCache {
+  /**
+   * Get cached file content. Returns null on miss.
+   */
+  get(repoId: string, filePath: string): CacheEntry | null;
+
+  /**
+   * Store file content in cache.
+   */
+  set(repoId: string, filePath: string, content: string, contentHash: string): void;
+
+  /**
+   * Invalidate a specific file's cache entry.
+   */
+  invalidate(repoId: string, filePath: string): void;
+
+  /**
+   * Invalidate all cache entries for a repo.
+   */
+  invalidateRepo(repoId: string): void;
+
+  /**
+   * Clear all cache entries.
+   */
+  clear(): void;
+
+  /**
+   * Get cache statistics.
+   */
+  getStats(): CacheStats;
+}