forge-server 0.1.0

package/dist/storage/falkordb-store.js

@@ -0,0 +1,346 @@
+/**
+ * FalkorDB implementation of GraphStore.
+ * FalkorDB speaks Redis protocol + GRAPH commands.
+ * Connects to localhost:6380 (remapped from container port 6379 per ADR-7).
+ *
+ * FalkorDB GRAPH.QUERY --compact response format:
+ * [
+ *   ["header", [...column_names]],
+ *   ["data", [[row], [row], ...]],
+ *   ["stats", ["Query internal execution time: X ms"]]
+ * ]
+ *
+ * Without --compact:
+ * [header_array, data_array, stats_array]
+ * where header_array = [column_names]
+ * and data_array = [[cell, cell, ...], ...]
+ */
+import { createClient } from 'redis';
+import { logger } from '../util/logger.js';
+import { CircuitBreaker } from '../util/circuit-breaker.js';
+const DEFAULT_QUERY_TIMEOUT_MS = 5000;
+const RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_ATTEMPTS = 3;
+export class FalkorDBGraphStore {
+    client = null;
+    url;
+    graphName;
+    queryTimeoutMs;
+    connected = false;
+    reconnectAttempts = 0;
+    breaker;
+    constructor(url = 'redis://localhost:6380', graphName = 'forge_knowledge', queryTimeoutMs = DEFAULT_QUERY_TIMEOUT_MS) {
+        this.url = url;
+        this.graphName = graphName;
+        this.queryTimeoutMs = queryTimeoutMs;
+        this.breaker = new CircuitBreaker({
+            name: 'falkordb',
+            failureThreshold: 5,
+            resetTimeoutMs: 30_000,
+        });
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        this.client = createClient({
+            url: this.url,
+            socket: {
+                connectTimeout: this.queryTimeoutMs,
+                reconnectStrategy: (retries) => {
+                    if (retries >= MAX_RECONNECT_ATTEMPTS) {
+                        logger.error('FalkorDB max reconnect attempts reached');
+                        return new Error('Max reconnect attempts reached');
+                    }
+                    const delay = RECONNECT_DELAY_MS * Math.pow(2, retries);
+                    logger.warn('FalkorDB reconnecting', { attempt: retries + 1, delayMs: delay });
+                    return delay;
+                },
+            },
+        });
+        this.client.on('error', (err) => {
+            logger.error('FalkorDB connection error', { error: err.message });
+            this.connected = false;
+        });
+        this.client.on('ready', () => {
+            this.connected = true;
+            this.reconnectAttempts = 0;
+            logger.info('FalkorDB ready', { url: this.url, graph: this.graphName });
+        });
+        this.client.on('reconnecting', () => {
+            this.reconnectAttempts++;
+            logger.warn('FalkorDB reconnecting', { attempt: this.reconnectAttempts });
+        });
+        await this.client.connect();
+        this.connected = true;
+        logger.info('FalkorDB connected', { url: this.url, graph: this.graphName });
+    }
+    async disconnect() {
+        if (this.client && this.connected) {
+            await this.client.disconnect();
+            this.client = null;
+            this.connected = false;
+            logger.info('FalkorDB disconnected');
+        }
+    }
+    async isHealthy() {
+        // Circuit breaker short-circuits when OPEN — no ping needed
+        if (!this.breaker.isHealthy())
+            return false;
+        if (!this.client || !this.connected)
+            return false;
+        try {
+            const result = await this.withTimeout(this.client.ping(), this.queryTimeoutMs);
+            return result === 'PONG';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Execute a raw Cypher query and return typed results.
+     * Parses FalkorDB's non-compact response format.
+     */
+    async query(cypher, params) {
+        try {
+            const raw = await this.graphQuery(cypher, params);
+            return this.parseGraphQueryResult(raw);
+        }
+        catch (err) {
+            logger.error('Graph query error', { error: String(err), cypher: cypher.slice(0, 100) });
+            return { nodes: [], edges: [], raw: [] };
+        }
+    }
+    async upsertNode(label, matchProps, setProps) {
+        const matchClause = this.propsToMatch(matchProps);
+        const setClause = this.propsToSet(setProps, 'n');
+        const cypher = `MERGE (n:${label} {${matchClause}}) SET ${setClause}`;
+        try {
+            await this.graphQuery(cypher);
+        }
+        catch (err) {
+            logger.warn('upsertNode failed', { label, error: String(err) });
+        }
+    }
+    async upsertEdge(fromLabel, fromProps, edgeType, edgeProps, toLabel, toProps) {
+        const fromMatch = this.propsToMatch(fromProps);
+        const toMatch = this.propsToMatch(toProps);
+        const edgeSet = Object.keys(edgeProps).length > 0
+            ? ` {${this.propsToMatch(edgeProps)}}`
+            : '';
+        const cypher = `
+      MATCH (a:${fromLabel} {${fromMatch}})
+      MATCH (b:${toLabel} {${toMatch}})
+      MERGE (a)-[r:${edgeType}${edgeSet}]->(b)
+    `;
+        try {
+            await this.graphQuery(cypher);
+        }
+        catch (err) {
+            logger.warn('upsertEdge failed', { edgeType, error: String(err) });
+        }
+    }
+    async deleteFile(filePath, repoId) {
+        // Delete child nodes (symbols contained in the file)
+        const deleteChildren = `
+      MATCH (f:File {path: "${this.escape(filePath)}", repo_id: "${this.escape(repoId)}"})-[:CONTAINS]->(s)
+      DETACH DELETE s
+    `;
+        // Delete the file node itself
+        const deleteFile = `
+      MATCH (f:File {path: "${this.escape(filePath)}", repo_id: "${this.escape(repoId)}"})
+      DETACH DELETE f
+    `;
+        try {
+            await this.graphQuery(deleteChildren);
+            await this.graphQuery(deleteFile);
+        }
+        catch (err) {
+            logger.warn('deleteFile failed', { filePath, error: String(err) });
+        }
+    }
+    async deleteRepo(repoId) {
+        const cypher = `
+      MATCH (n {repo_id: "${this.escape(repoId)}"})
+      DETACH DELETE n
+    `;
+        try {
+            await this.graphQuery(cypher);
+        }
+        catch (err) {
+            logger.warn('deleteRepo failed', { repoId, error: String(err) });
+        }
+    }
+    async getCounts() {
+        try {
+            // FalkorDB GRAPH.QUERY returns [headers, data, stats]
+            // MATCH (n) RETURN count(n) returns [[count_value]]
+            const nodeResult = await this.graphQuery('MATCH (n) RETURN count(n) AS cnt');
+            const edgeResult = await this.graphQuery('MATCH ()-[r]->() RETURN count(r) AS cnt');
+            const totalNodes = this.extractScalarNumber(nodeResult);
+            const totalEdges = this.extractScalarNumber(edgeResult);
+            // Get per-label counts for known node labels
+            const labels = ['File', 'Function', 'Class', 'Interface', 'Module', 'TypeAlias', 'Variable', 'Observation'];
+            const byLabel = {};
+            await Promise.all(labels.map(async (label) => {
+                try {
+                    const result = await this.graphQuery(`MATCH (n:${label}) RETURN count(n) AS cnt`);
+                    const count = this.extractScalarNumber(result);
+                    if (count > 0)
+                        byLabel[label] = count;
+                }
+                catch {
+                    // Label might not exist in graph yet - skip
+                }
+            }));
+            return { totalNodes, totalEdges, byLabel };
+        }
+        catch (err) {
+            logger.warn('getCounts failed', { error: String(err) });
+            return { totalNodes: 0, totalEdges: 0, byLabel: {} };
+        }
+    }
+    async ensureIndexes() {
+        const indexes = [
+            'CREATE INDEX ON :File(path, repo_id)',
+            'CREATE INDEX ON :Function(name, repo_id)',
+            'CREATE INDEX ON :Class(name, repo_id)',
+            'CREATE INDEX ON :Interface(name, repo_id)',
+            'CREATE INDEX ON :Module(name, repo_id)',
+            'CREATE INDEX ON :Observation(id)',
+            'CREATE INDEX ON :Observation(session_id)',
+        ];
+        for (const idx of indexes) {
+            try {
+                await this.graphQuery(idx);
+            }
+            catch {
+                // Index may already exist - FalkorDB throws on duplicate index creation.
+                // This is expected and safe to ignore.
+            }
+        }
+        logger.info('FalkorDB indexes ensured');
+    }
+    // ============================================================
+    // Private helpers
+    // ============================================================
+    /**
+     * Execute a GRAPH.QUERY command with timeout, wrapped in the circuit breaker.
+     * Returns the raw FalkorDB response array.
+     */
+    async graphQuery(cypher, _params) {
+        if (!this.client)
+            throw new Error('FalkorDB not connected. Call connect() first.');
+        return this.breaker.execute(async () => {
+            const queryPromise = this.client.sendCommand([
+                'GRAPH.QUERY',
+                this.graphName,
+                cypher,
+            ]);
+            return this.withTimeout(queryPromise, this.queryTimeoutMs);
+        });
+    }
+    /**
+     * Wrap a promise with a timeout that rejects after timeoutMs.
+     */
+    withTimeout(promise, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`FalkorDB query timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            promise.then((value) => { clearTimeout(timer); resolve(value); }, (err) => { clearTimeout(timer); reject(err); });
+        });
+    }
+    /**
+     * Parse FalkorDB GRAPH.QUERY response into GraphQueryResult.
+     * FalkorDB non-compact format: [header_row, data_rows, stats_row]
+     * header_row: ["column1", "column2", ...]
+     * data_rows: [[val1, val2, ...], [val1, val2, ...], ...]
+     */
+    parseGraphQueryResult(raw) {
+        if (!Array.isArray(raw) || raw.length < 2) {
+            return { nodes: [], edges: [], raw };
+        }
+        const headers = raw[0];
+        const dataRows = raw[1];
+        if (!Array.isArray(headers) || !Array.isArray(dataRows)) {
+            return { nodes: [], edges: [], raw };
+        }
+        const nodes = [];
+        const edges = [];
+        for (const row of dataRows) {
+            if (!Array.isArray(row))
+                continue;
+            for (let i = 0; i < headers.length; i++) {
+                const cell = row[i];
+                if (cell && typeof cell === 'object' && !Array.isArray(cell)) {
+                    const obj = cell;
+                    // FalkorDB node: { id, labels, properties }
+                    if (Array.isArray(obj.labels)) {
+                        nodes.push({
+                            id: String(obj.id ?? ''),
+                            label: obj.labels[0] ?? '',
+                            properties: obj.properties ?? {},
+                        });
+                    }
+                    // FalkorDB edge: { id, type, src_node, dest_node, properties }
+                    if (typeof obj.type === 'string' && obj.src_node !== undefined) {
+                        edges.push({
+                            type: obj.type,
+                            from: String(obj.src_node),
+                            to: String(obj.dest_node ?? ''),
+                            properties: obj.properties ?? {},
+                        });
+                    }
+                }
+            }
+        }
+        return { nodes, edges, raw };
+    }
+    /**
+     * Extract a single scalar number from a GRAPH.QUERY count result.
+     * Response: [["cnt"], [[42]], [...stats]]
+     */
+    extractScalarNumber(raw) {
+        if (!Array.isArray(raw) || raw.length < 2)
+            return 0;
+        const dataRows = raw[1];
+        if (!Array.isArray(dataRows) || dataRows.length === 0)
+            return 0;
+        const firstRow = dataRows[0];
+        if (!Array.isArray(firstRow) || firstRow.length === 0)
+            return 0;
+        const val = firstRow[0];
+        if (typeof val === 'number')
+            return val;
+        if (typeof val === 'string')
+            return parseInt(val, 10) || 0;
+        return 0;
+    }
+    propsToMatch(props) {
+        return Object.entries(props)
+            .map(([k, v]) => `${k}: ${this.valueToLiteral(v)}`)
+            .join(', ');
+    }
+    propsToSet(props, alias) {
+        return Object.entries(props)
+            .map(([k, v]) => `${alias}.${k} = ${this.valueToLiteral(v)}`)
+            .join(', ');
+    }
+    valueToLiteral(v) {
+        if (typeof v === 'string')
+            return `"${this.escape(v)}"`;
+        if (typeof v === 'number')
+            return String(v);
+        if (typeof v === 'boolean')
+            return v ? 'true' : 'false';
+        if (v === null || v === undefined)
+            return 'null';
+        if (Array.isArray(v))
+            return `[${v.map(x => this.valueToLiteral(x)).join(', ')}]`;
+        return `"${this.escape(JSON.stringify(v))}"`;
+    }
+    escape(s) {
+        return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+    }
+}
+//# sourceMappingURL=falkordb-store.js.map

package/dist/storage/falkordb-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"falkordb-store.js","sourceRoot":"","sources":["../../src/storage/falkordb-store.ts"],"names":[],"mappings":"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"}

package/dist/storage/file-cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-memory LRU file content cache.
+ * Provides the cross-agent shared context (ADR-8, section 4.6).
+ * Size-aware eviction with content-hash keying for invalidation.
+ */
+import type { FileContentCache } from './interfaces.js';
+import type { CacheEntry, CacheStats } from '../util/types.js';
+export interface FileCacheOptions {
+    maxSizeBytes?: number;
+    maxEntries?: number;
+    ttlMs?: number;
+}
+export declare class LRUFileContentCache implements FileContentCache {
+    private cache;
+    private hits;
+    private misses;
+    private evictionCount;
+    private startedAt;
+    constructor(options?: FileCacheOptions);
+    private cacheKey;
+    get(repoId: string, filePath: string): CacheEntry | null;
+    set(repoId: string, filePath: string, content: string, contentHash: string): void;
+    invalidate(repoId: string, filePath: string): void;
+    invalidateRepo(repoId: string): void;
+    clear(): void;
+    getStats(): CacheStats;
+}
+/**
+ * Utility: compute SHA-256 hash of content string.
+ */
+export declare function hashContent(content: string): string;
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/storage/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/storage/file-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAO/D,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAc;gBAEnB,OAAO,GAAE,gBAAqB;IAqB1C,OAAO,CAAC,QAAQ;IAIhB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAexD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAgBjF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMlD,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAYpC,KAAK,IAAI,IAAI;IAOb,QAAQ,IAAI,UAAU;CAuBvB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/storage/file-cache.js

@@ -0,0 +1,115 @@
+/**
+ * In-memory LRU file content cache.
+ * Provides the cross-agent shared context (ADR-8, section 4.6).
+ * Size-aware eviction with content-hash keying for invalidation.
+ */
+import { LRUCache } from 'lru-cache';
+import { createHash } from 'crypto';
+import { logger } from '../util/logger.js';
+const DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB
+const DEFAULT_MAX_ENTRIES = 2000;
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 min
+export class LRUFileContentCache {
+    cache;
+    hits = 0;
+    misses = 0;
+    evictionCount = 0;
+    startedAt = Date.now();
+    constructor(options = {}) {
+        const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+        const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.cache = new LRUCache({
+            maxSize: maxSizeBytes,
+            // LRU cache requires sizeCalculation to return a positive integer.
+            // Use minimum of 1 so zero-byte content (empty string) is still accepted.
+            sizeCalculation: (entry) => Math.max(1, entry.sizeBytes),
+            ttl: ttlMs,
+            max: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+            // Use Date.now() for TTL tracking. This makes the cache compatible with
+            // vi.useFakeTimers() in tests (which replaces Date.now but not performance.now).
+            // lru-cache v11 defaults to performance.now which isn't affected by fake timers.
+            perf: { now: () => Date.now() },
+            dispose: () => {
+                this.evictionCount++;
+            },
+        });
+    }
+    cacheKey(repoId, filePath) {
+        return `${repoId}:${filePath}`;
+    }
+    get(repoId, filePath) {
+        const key = this.cacheKey(repoId, filePath);
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.hits++;
+            // Update access count in-place
+            entry.accessCount++;
+            return entry;
+        }
+        this.misses++;
+        return null;
+    }
+    set(repoId, filePath, content, contentHash) {
+        const key = this.cacheKey(repoId, filePath);
+        const sizeBytes = Buffer.byteLength(content, 'utf8');
+        const entry = {
+            content,
+            contentHash,
+            cachedAt: Date.now(),
+            accessCount: 0,
+            sizeBytes, // Report the actual byte size (may be 0 for empty string)
+        };
+        this.cache.set(key, entry);
+        logger.debug('File cached', { filePath, sizeBytes, repoId });
+    }
+    invalidate(repoId, filePath) {
+        const key = this.cacheKey(repoId, filePath);
+        this.cache.delete(key);
+        logger.debug('Cache invalidated', { filePath, repoId });
+    }
+    invalidateRepo(repoId) {
+        const prefix = `${repoId}:`;
+        let count = 0;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        logger.info('Repo cache invalidated', { repoId, count });
+    }
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        logger.info('File content cache cleared');
+    }
+    getStats() {
+        const total = this.hits + this.misses;
+        const hitRate = total > 0 ? this.hits / total : 0;
+        // Calculate current memory usage
+        let totalBytes = 0;
+        let oldestAge = 0;
+        const now = Date.now();
+        for (const entry of this.cache.values()) {
+            totalBytes += entry.sizeBytes;
+            const age = (now - entry.cachedAt) / 1000;
+            if (age > oldestAge)
+                oldestAge = age;
+        }
+        return {
+            entries: this.cache.size,
+            memoryUsageMb: totalBytes / (1024 * 1024),
+            hitRate,
+            evictionCount: this.evictionCount,
+            oldestEntryAgeSeconds: oldestAge,
+        };
+    }
+}
+/**
+ * Utility: compute SHA-256 hash of content string.
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/storage/file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.js","sourceRoot":"","sources":["../../src/storage/file-cache.ts"],"names":[],"mappings":"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"}

package/dist/storage/interfaces.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { GraphQueryResult, VectorSearchResult, CodeChunkPayload, ObservationPayload, CacheEntry, CacheStats } from '../util/types.js';
+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>;
+}
+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[]>;
+}
+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;
+}
+//# sourceMappingURL=interfaces.d.ts.map