@dastbal/nestjs-ai-agent 1.0.0

package/dist/core/llm/provider.js

@@ -0,0 +1,84 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMProvider = void 0;
+const google_vertexai_1 = require("@langchain/google-vertexai");
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+// 1. Cargar variables de entorno desde la RAÍZ del proyecto
+// process.cwd() obtiene la carpeta desde donde ejecutas "npm run agent"
+const rootDir = process.cwd();
+dotenv.config({ path: path.join(rootDir, '.env.development') });
+class LLMProvider {
+    constructor() { }
+    static getModel() {
+        if (!this.instance) {
+            // 2. Validación de variables críticas
+            const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+            if (!credentialsPath) {
+                throw new Error('❌ GOOGLE_APPLICATION_CREDENTIALS no está definido en el .env');
+            }
+            // 3. Convertir ruta relativa a ABSOLUTA (Truco para Windows)
+            // Si dice "./credentials.json", lo convierte a "C:\Users\...\credentials.json"
+            const absoluteCredentialsPath = path.resolve(rootDir, credentialsPath);
+            // Verificamos que el archivo JSON realmente exista antes de intentar conectar
+            if (!fs.existsSync(absoluteCredentialsPath)) {
+                throw new Error(`❌ No se encuentra el archivo de credenciales en: ${absoluteCredentialsPath}`);
+            }
+            // Sobrescribimos la variable de entorno con la ruta absoluta para que la librería de Google la lea bien
+            process.env.GOOGLE_APPLICATION_CREDENTIALS = absoluteCredentialsPath;
+            console.log(`📄 Usando credenciales: ${absoluteCredentialsPath}`);
+            this.instance = new google_vertexai_1.ChatVertexAI({
+                // Usamos tus variables específicas
+                model: process.env.GOOGLE_CLOUD_MODEL_NAME || 'gemini-2.0-flash-lite-001',
+                temperature: 0,
+                // maxOutputTokens: 8192,
+            });
+        }
+        return this.instance;
+    }
+    static getEmbeddingsModel() {
+        if (!this.embeddingsInstance) {
+            // Validar credentials igual que antes...
+            this.embeddingsInstance = new google_vertexai_1.VertexAIEmbeddings({
+                model: 'text-embedding-004', // El modelo más eficiente de Google actualmente
+                // Los mismos parámetros de location y projectID que ya configuramos
+            });
+        }
+        return this.embeddingsInstance;
+    }
+}
+exports.LLMProvider = LLMProvider;

package/dist/core/rag/indexer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Indexer Service (The Orchestrator) 🎼
+ * Responsible for keeping the AI memory in sync with the codebase.
+ * It coordinates the FileRegistry, AST Parser, and Vector Store.
+ */
+export declare class IndexerService {
+    private registry;
+    private chunker;
+    private db;
+    private BATCH_SIZE;
+    constructor();
+    /**
+     * Main Entry Point: Scans the project and updates the brain.
+     * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
+     * * @param sourceDir - Relative path to source code (usually 'src').
+     */
+    indexProject(sourceDir?: string): Promise<void>;
+    /**
+     * Processes a single file: Reads content, Calculates Hash, Parses AST,
+     * Updates Registry, and Accumulates Chunks.
+     */
+    private processSingleFile;
+    /**
+     * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
+     */
+    private embedAndSaveBatches;
+    /**
+     * Persists dependency relationships into the graph table.
+     * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
+     */
+    private saveGraph;
+    /**
+     * Recursively gets all .ts files in a directory.
+     * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
+     */
+    private getAllFiles;
+}

package/dist/core/rag/indexer.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexerService = void 0;
+const file_registry_1 = require("../state/file-registry");
+const chunker_1 = require("../tools/ast/chunker");
+const db_1 = require("../state/db");
+const provider_1 = require("../llm/provider");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * The Indexer Service (The Orchestrator) 🎼
+ * Responsible for keeping the AI memory in sync with the codebase.
+ * It coordinates the FileRegistry, AST Parser, and Vector Store.
+ */
+class IndexerService {
+    constructor() {
+        // Optimization: Send chunks to Vertex AI in groups to respect rate limits and improve speed.
+        this.BATCH_SIZE = 10;
+        this.registry = new file_registry_1.FileRegistry();
+        this.chunker = new chunker_1.NestChunker();
+        this.db = db_1.AgentDB.getInstance();
+    }
+    /**
+     * Main Entry Point: Scans the project and updates the brain.
+     * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
+     * * @param sourceDir - Relative path to source code (usually 'src').
+     */
+    async indexProject(sourceDir = 'src') {
+        const rootDir = process.cwd();
+        const fullSourceDir = path.join(rootDir, sourceDir);
+        console.log(`🚀 Starting Indexing Process on: ${sourceDir}`);
+        const files = this.getAllFiles(fullSourceDir);
+        const filesToProcess = [];
+        // Check changes
+        for (const file of files) {
+            if (this.registry.isFileChanged(file)) {
+                filesToProcess.push(file);
+            }
+        }
+        if (filesToProcess.length === 0) {
+            console.log('✨ Project is up to date.');
+            return;
+        }
+        console.log(`📦 Found ${filesToProcess.length} files to process.`);
+        // --- CAMBIO IMPORTANTE ---
+        // Acumuladores separados
+        const pendingChunks = [];
+        const pendingEdges = []; // <--- Acumulamos el grafo aquí
+        // 1. PRIMERA PASADA: Registrar archivos y generar datos
+        for (const filePath of filesToProcess) {
+            await this.processSingleFile(filePath, pendingChunks, pendingEdges);
+        }
+        // 2. SEGUNDA PASADA: Guardar Grafo (Ahora que todos los archivos existen en registry)
+        if (pendingEdges.length > 0) {
+            console.log(`🕸️ Saving ${pendingEdges.length} dependency relations...`);
+            this.saveGraph(pendingEdges);
+        }
+        // 3. TERCERA PASADA: Guardar Vectores
+        if (pendingChunks.length > 0) {
+            await this.embedAndSaveBatches(pendingChunks);
+        }
+        console.log('✅ Indexing Complete.');
+    }
+    // ==========================================
+    // ⚙️ INTERNAL LOGIC
+    // ==========================================
+    /**
+     * Processes a single file: Reads content, Calculates Hash, Parses AST,
+     * Updates Registry, and Accumulates Chunks.
+     */
+    processSingleFile(filePath, chunkAccumulator, edgeAccumulator) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            // A. Calculate Hash
+            const hash = require('crypto')
+                .createHash('md5')
+                .update(content)
+                .digest('hex');
+            // B. Analyze
+            const analysis = this.chunker.analyze(filePath, content, hash);
+            // --- CAMBIO CLAVE: ORDEN DE OPERACIONES ---
+            // 1. PRIMERO: Registrar el archivo en DB.
+            // Si no hacemos esto, el foreign key de 'source' fallará si intentáramos guardar algo.
+            this.registry.updateFile(filePath, analysis.skeleton);
+            // 2. SEGUNDO: Acumular relaciones para guardarlas DESPUÉS
+            // No llamamos a this.saveGraph() aquí.
+            edgeAccumulator.push(...analysis.dependencies);
+            // 3. TERCERO: Acumular Chunks
+            const chunksWithFile = analysis.chunks.map((c) => ({
+                ...c,
+                filePath: filePath,
+            }));
+            chunkAccumulator.push(...chunksWithFile);
+        }
+        catch (error) {
+            console.error(`❌ Error processing file ${filePath}:`, error);
+        }
+    }
+    /**
+     * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
+     */
+    async embedAndSaveBatches(allChunks) {
+        console.log(`🧠 Generating Embeddings for ${allChunks.length} chunks...`);
+        for (let i = 0; i < allChunks.length; i += this.BATCH_SIZE) {
+            const batch = allChunks.slice(i, i + this.BATCH_SIZE);
+            // 1. Prepare Text for Embedding
+            // CRITICAL: We embed "metadata + content" for better semantic search results.
+            // This allows the LLM to find "UsersService method" even if the code doesn't say "User".
+            const textsToEmbed = batch.map((c) => {
+                const metaStr = c.metadata.methodName
+                    ? `Method: ${c.metadata.methodName}`
+                    : `Class: ${c.metadata.className}`;
+                return `${metaStr}\n${c.content}`;
+            });
+            try {
+                // 2. Call Vertex AI (Embeddings API)
+                const embeddingsModel = provider_1.LLMProvider.getEmbeddingsModel();
+                const vectors = await embeddingsModel.embedDocuments(textsToEmbed);
+                // 3. Save to DB (Transaction for performance)
+                const insertChunk = this.db.prepare(`
+          INSERT OR REPLACE INTO code_chunks (id, file_path, chunk_type, content, vector_json, metadata)
+          VALUES (?, ?, ?, ?, ?, ?)
+        `);
+                // Explicitly typed transaction callback to fix TS7006
+                const insertMany = this.db.transaction((chunks, vectors) => {
+                    chunks.forEach((chunk, idx) => {
+                        insertChunk.run(chunk.id, chunk.filePath, // filePath added in processSingleFile
+                        chunk.type, chunk.content, JSON.stringify(vectors[idx]), // Serialize vector to string for storage
+                        JSON.stringify(chunk.metadata));
+                    });
+                });
+                insertMany(batch, vectors);
+                process.stdout.write('.'); // Visual feedback
+            }
+            catch (err) {
+                console.error('❌ Embedding Error:', err);
+            }
+        }
+        console.log('\n💾 Vectors Saved.');
+    }
+    /**
+     * Persists dependency relationships into the graph table.
+     * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
+     */
+    saveGraph(edges) {
+        if (!edges || edges.length === 0)
+            return;
+        const insertEdge = this.db.prepare(`
+      INSERT OR IGNORE INTO dependency_graph (source, target, relation)
+      VALUES (?, ?, ?)
+    `);
+        // Explicitly typed transaction callback to fix TS7006
+        const runMany = this.db.transaction((edges) => {
+            edges.forEach((edge) => insertEdge.run(edge.sourcePath, edge.targetPath, edge.relation));
+        });
+        runMany(edges);
+    }
+    /**
+     * Recursively gets all .ts files in a directory.
+     * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
+     */
+    getAllFiles(dir, fileList = []) {
+        const files = fs.readdirSync(dir);
+        files.forEach((file) => {
+            const absolutePath = path.join(dir, file);
+            const stat = fs.statSync(absolutePath);
+            if (stat.isDirectory()) {
+                this.getAllFiles(absolutePath, fileList);
+            }
+            else {
+                // Filter: Only TS files, ignore tests (.spec.ts)
+                if (file.endsWith('.ts') && !file.endsWith('.spec.ts')) {
+                    // KEY FIX: Normalize to relative path before adding to list
+                    const relativePath = path.relative(process.cwd(), absolutePath);
+                    fileList.push(relativePath);
+                }
+            }
+        });
+        return fileList;
+    }
+}
+exports.IndexerService = IndexerService;

package/dist/core/rag/math.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Mathematical utilities for Vector Search.
+ */
+/**
+ * Calculates the Cosine Similarity between two vectors.
+ * A score of 1.0 means identical direction (perfect match).
+ * A score of 0.0 means orthogonal (no relation).
+ * * @param vecA - The query vector
+ * @param vecB - The database vector
+ */
+export declare function cosineSimilarity(vecA: number[], vecB: number[]): number;

package/dist/core/rag/math.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Mathematical utilities for Vector Search.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cosineSimilarity = cosineSimilarity;
+/**
+ * Calculates the Cosine Similarity between two vectors.
+ * A score of 1.0 means identical direction (perfect match).
+ * A score of 0.0 means orthogonal (no relation).
+ * * @param vecA - The query vector
+ * @param vecB - The database vector
+ */
+function cosineSimilarity(vecA, vecB) {
+    if (vecA.length !== vecB.length) {
+        throw new Error('Vectors must have the same dimensionality');
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < vecA.length; i++) {
+        dotProduct += vecA[i] * vecB[i];
+        normA += vecA[i] * vecA[i];
+        normB += vecB[i] * vecB[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}

package/dist/core/rag/retriever.d.ts

@@ -0,0 +1,28 @@
+import { ProcessedChunk } from '../types';
+interface SearchResult {
+    chunk: ProcessedChunk;
+    score: number;
+}
+export declare class RetrieverService {
+    private db;
+    /**
+     * Searches the codebase using Vector Embeddings (Cosine Similarity).
+     * @param query - The natural language query.
+     * @param limit - Max chunks to retrieve.
+     */
+    query(query: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Retrieves the 'Graph Dependencies' for a specific file from the DB.
+     * This allows the Agent to know what other files are related (DTOs, Interfaces).
+     */
+    private getDependencies;
+    /**
+     * Generates a Rich Context Report for the LLM.
+     * It combines:
+     * 1. The matched code snippets (Vector Search).
+     * 2. The file's dependencies (Graph Search).
+     * 3. Explicit File Paths to encourage using 'read_file'.
+     */
+    getContextForLLM(query: string): Promise<string>;
+}
+export {};

package/dist/core/rag/retriever.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetrieverService = void 0;
+const db_1 = require("../state/db");
+const provider_1 = require("../llm/provider");
+const math_1 = require("./math");
+const path = __importStar(require("path"));
+class RetrieverService {
+    constructor() {
+        this.db = db_1.AgentDB.getInstance();
+    }
+    /**
+     * Searches the codebase using Vector Embeddings (Cosine Similarity).
+     * @param query - The natural language query.
+     * @param limit - Max chunks to retrieve.
+     */
+    async query(query, limit = 5) {
+        console.log(`🔍 [RAG] Embedding Query: "${query}"...`);
+        const embeddingModel = provider_1.LLMProvider.getEmbeddingsModel();
+        const queryVector = await embeddingModel.embedQuery(query);
+        const stmt = this.db.prepare('SELECT * FROM code_chunks');
+        const rows = stmt.all();
+        const scoredChunks = rows.map((row) => {
+            const vector = JSON.parse(row.vector_json);
+            const score = (0, math_1.cosineSimilarity)(queryVector, vector);
+            const metadata = JSON.parse(row.metadata);
+            return {
+                score,
+                chunk: {
+                    id: row.id,
+                    type: row.chunk_type,
+                    content: row.content,
+                    metadata: metadata,
+                    // Ensure filePath is recovered from the DB row or metadata
+                    filePath: row.file_path || metadata.filePath,
+                },
+            };
+        });
+        return scoredChunks.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /**
+     * Retrieves the 'Graph Dependencies' for a specific file from the DB.
+     * This allows the Agent to know what other files are related (DTOs, Interfaces).
+     */
+    getDependencies(sourcePath) {
+        // 1. IMPORTANTE: Normalizar la ruta para que coincida con lo guardado en DB
+        // Esto convierte "src\module\..." a "src/module/..."
+        const normalizedPath = sourcePath.split(path.sep).join('/');
+        try {
+            // 2. Consultar la tabla dependency_graph que definiste en AgentDB
+            // Buscamos todo lo que este archivo (source) importa (target)
+            const stmt = this.db.prepare(`
+            SELECT target 
+            FROM dependency_graph 
+            WHERE source = ? OR source = ?
+        `);
+            // Probamos con la ruta normalizada y la original por si acaso
+            const results = stmt.all(normalizedPath, sourcePath);
+            // 3. Devolver solo los strings de los targets
+            return results.map((row) => row.target);
+        }
+        catch (error) {
+            console.error(`Error fetching dependencies for ${sourcePath}:`, error);
+            return [];
+        }
+    }
+    /**
+     * Generates a Rich Context Report for the LLM.
+     * It combines:
+     * 1. The matched code snippets (Vector Search).
+     * 2. The file's dependencies (Graph Search).
+     * 3. Explicit File Paths to encourage using 'read_file'.
+     */
+    async getContextForLLM(query) {
+        const results = await this.query(query, 4);
+        // Group chunks by File to provide a structured view
+        const filesMap = new Map();
+        for (const res of results) {
+            const path = res.chunk.filePath || 'unknown';
+            // console.log(res);
+            // console.log(path);
+            // console.log(this.getDependencies(path));
+            if (!filesMap.has(path)) {
+                filesMap.set(path, {
+                    filePath: path,
+                    relevance: res.score,
+                    chunks: [],
+                    imports: this.getDependencies(path), // <--- GRAPH MAGIC 🕸️
+                });
+            }
+            filesMap.get(path)?.chunks.push(res.chunk);
+        }
+        // Build the formatted string
+        let output = `🔎 **RAG ANALYSIS REPORT**\n`;
+        output += `Query: "${query}"\n`;
+        output += `Found ${filesMap.size} relevant files.\n\n`;
+        filesMap.forEach((fileCtx) => {
+            const relevancePct = (fileCtx.relevance * 100).toFixed(1);
+            output += `=================================================================\n`;
+            output += `📂 **FILE:** ${fileCtx.filePath}\n`;
+            output += `📊 **RELEVANCE:** ${relevancePct}%\n`;
+            if (fileCtx.imports.length > 0) {
+                output += `🔗 **DEPENDENCIES (Imports):**\n`;
+                // Show top 5 imports to give context on DTOs/Entities used
+                fileCtx.imports
+                    .slice(0, 5)
+                    .forEach((imp) => (output += `   - ${imp}\n`));
+                if (fileCtx.imports.length > 5)
+                    output += `   - (...and ${fileCtx.imports.length - 5} more)\n`;
+            }
+            output += `\n📝 **CODE SNIPPETS:**\n`;
+            fileCtx.chunks.forEach((chunk) => {
+                output += `   --- [${chunk.metadata.methodName || 'Class Structure'}] ---\n`;
+                output += `${chunk.content.trim()}\n\n`;
+            });
+            output += `💡 **AGENT HINT:** To edit this file or see full imports, run: read_file("${fileCtx.filePath}")\n`;
+            output += `=================================================================\n\n`;
+        });
+        // console.log(output);
+        return output;
+    }
+}
+exports.RetrieverService = RetrieverService;

package/dist/core/state/db.d.ts

@@ -0,0 +1,23 @@
+import Database from 'better-sqlite3';
+/**
+ * Singleton Database Manager.
+ * Handles the connection to the local SQLite instance used for caching and state management.
+ */
+export declare class AgentDB {
+    private static instance;
+    /**
+     * Private constructor to enforce Singleton pattern.
+     */
+    private constructor();
+    /**
+     * Retrieves the active database connection.
+     * If it doesn't exist, it initializes the DB file and the schema.
+     * * @returns {Database.Database} The SQLite connection instance.
+     */
+    static getInstance(): Database.Database;
+    /**
+     * Initializes the database tables based on our architectural plan.
+     * 1. file_registry: Tracks file hashes and cached skeletons.
+     */
+    private static initSchema;
+}