@jagilber-org/index-server 1.22.1 → 1.26.4

package/dist/services/mcpLogBridge.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * MCP Log Bridge — thin adapter over the generalized McpStdioLogger.
+ *
+ * Preserves the existing module-level API (`registerMcpServer`, `activateMcpLogBridge`,
+ * `isMcpLogBridgeActive`, `sendMcpLog`, `_restoreStderr`) so that all existing
+ * call sites in index-server.ts, sdkServer.ts, handshakeManager.ts, and logger.ts
+ * continue to work without changes.
+ *
+ * The actual stderr interception, buffering, replay, and MCP protocol routing is
+ * delegated to `McpStdioLogger` from `../lib/mcpStdioLogging`, which is a
+ * self-contained, reusable module for any MCP stdio server.
+ *
+ * See `src/lib/mcpStdioLogging.ts` for the generalized implementation and
+ * `docs/mcp_stdio_logging.md` for integration guidance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMcpServer = registerMcpServer;
+exports.activateMcpLogBridge = activateMcpLogBridge;
+exports.isMcpLogBridgeActive = isMcpLogBridgeActive;
+exports.sendMcpLog = sendMcpLog;
+exports.writeRealStderr = writeRealStderr;
+exports._restoreStderr = _restoreStderr;
+const mcpStdioLogging_1 = require("../lib/mcpStdioLogging");
+const LEVEL_MAP = {
+    TRACE: 'debug',
+    DEBUG: 'debug',
+    INFO: 'info',
+    WARN: 'warning',
+    ERROR: 'error',
+};
+// Singleton instance — intercepts stderr immediately on module load.
+const _logger = new mcpStdioLogging_1.McpStdioLogger({
+    serverName: 'index-server',
+    interceptImmediately: process.env.INDEX_SERVER_DISABLE_STDERR_BRIDGE !== '1',
+    maxBufferSize: 500,
+});
+/**
+ * Register the SDK server instance. Called once after server creation.
+ * Does NOT activate the bridge — call `activateMcpLogBridge()` after ready.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function registerMcpServer(server) {
+    _logger.registerServer(server);
+}
+/**
+ * Activate the bridge so subsequent log calls are routed via MCP protocol.
+ * Replays any buffered pre-handshake stderr lines through the protocol.
+ * Called from `emitReadyGlobal()` after the handshake completes.
+ */
+function activateMcpLogBridge() {
+    _logger.activate();
+}
+/**
+ * Returns true if the bridge is active and logs will be sent via MCP protocol.
+ */
+function isMcpLogBridgeActive() {
+    return _logger.isActive;
+}
+/**
+ * Send a log message through the MCP `notifications/message` protocol.
+ * No-op if the bridge is not yet active.
+ *
+ * @param level - The index-server log level (TRACE, DEBUG, INFO, WARN, ERROR)
+ * @param data  - The log payload (typically the NDJSON string)
+ */
+function sendMcpLog(level, data) {
+    _logger.log(LEVEL_MAP[level] ?? 'info', data);
+}
+/**
+ * Write directly to the original process.stderr, bypassing the interceptor.
+ * Use from logger.ts to ensure VS Code Output panel always has content.
+ */
+function writeRealStderr(data) {
+    _logger.writeOriginalStderr(data);
+}
+/**
+ * Restore original stderr and deactivate the bridge.
+ * Intended for testing cleanup only.
+ */
+function _restoreStderr() {
+    _logger.restore();
+}

package/dist/services/ownershipService.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOwner = resolveOwner;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const logger_js_1 = require("./logger.js");
+const regexSafety_js_1 = require("./regexSafety.js");
 let cached = null;
 function loadRules() {
     const file = path_1.default.join(process.cwd(), 'owners.json');
@@ -13,8 +15,20 @@ function loadRules() {
         const stat = fs_1.default.statSync(file);
         if (cached && cached.mtimeMs === stat.mtimeMs)
             return cached.rules;
-        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
-        const rules = Array.isArray(raw.ownership) ? raw.ownership.filter(r => r && typeof r.pattern === 'string' && typeof r.owner === 'string') : [];
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8')); // lgtm[js/file-system-race] — file path is cwd-resolved owners.json; mtime-checked above for cache invalidation
+        const rules = Array.isArray(raw.ownership)
+            ? raw.ownership.flatMap((rule) => {
+                if (!rule || typeof rule.pattern !== 'string' || typeof rule.owner !== 'string') {
+                    return [];
+                }
+                const { regex, error } = (0, regexSafety_js_1.compileSafeRegex)(rule.pattern);
+                if (!regex) {
+                    (0, logger_js_1.logWarn)(`[ownershipService] Skipping ownership rule for "${rule.owner}": ${error}`);
+                    return [];
+                }
+                return [{ owner: rule.owner, regex }];
+            })
+            : [];
         cached = { mtimeMs: stat.mtimeMs, rules };
         return rules;
     }
@@ -25,12 +39,8 @@ function loadRules() {
 function resolveOwner(id) {
     const rules = loadRules();
     for (const r of rules) {
-        try {
-            const re = new RegExp(r.pattern);
-            if (re.test(id))
-                return r.owner;
-        }
-        catch { /* ignore */ }
+        if (r.regex.test(id))
+            return r.owner;
     }
     return undefined;
 }

package/dist/services/performanceBaseline.js

@@ -10,6 +10,7 @@ const child_process_1 = require("child_process");
 const perf_hooks_1 = require("perf_hooks");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const logger_js_1 = require("./logger.js");
 function startServer(enableUsage) {
     return new Promise((resolve) => {
         const env = {
@@ -143,37 +144,37 @@ function calculateOverhead(withoutUsage, withUsage) {
     return ((usageP95 - baselineP95) / baselineP95) * 100;
 }
 async function runPerformanceBaseline() {
-    console.log('🚀 Starting Phase 1 Performance Baseline Measurement...');
-    console.log('Target: <5% overhead for usage tracking');
-    console.log();
+    (0, logger_js_1.logInfo)('🚀 Starting Phase 1 Performance Baseline Measurement...');
+    (0, logger_js_1.logInfo)('Target: <5% overhead for usage tracking');
+    (0, logger_js_1.logInfo)('---');
     // List operations
-    console.log('📊 Measuring list operations...');
+    (0, logger_js_1.logInfo)('📊 Measuring list operations...');
     const listWithoutUsage = await measureListOperations(false);
     const listWithUsage = await measureListOperations(true);
     const listOverhead = calculateOverhead(listWithoutUsage, listWithUsage);
-    console.log('✅ List operations measured');
-    console.log(`   Without usage: ${calculateStats(listWithoutUsage).p95.toFixed(2)}ms P95`);
-    console.log(`   With usage: ${calculateStats(listWithUsage).p95.toFixed(2)}ms P95`);
-    console.log(`   Overhead: ${listOverhead.toFixed(2)}%`);
-    console.log();
+    (0, logger_js_1.logInfo)('✅ List operations measured');
+    (0, logger_js_1.logInfo)(`   Without usage: ${calculateStats(listWithoutUsage).p95.toFixed(2)}ms P95`);
+    (0, logger_js_1.logInfo)(`   With usage: ${calculateStats(listWithUsage).p95.toFixed(2)}ms P95`);
+    (0, logger_js_1.logInfo)(`   Overhead: ${listOverhead.toFixed(2)}%`);
+    (0, logger_js_1.logInfo)('---');
     // Mutation operations
-    console.log('📊 Measuring mutation operations...');
+    (0, logger_js_1.logInfo)('📊 Measuring mutation operations...');
     const mutationWithoutUsage = await measureMutationOperations(false);
     const mutationWithUsage = await measureMutationOperations(true);
     const mutationOverhead = calculateOverhead(mutationWithoutUsage, mutationWithUsage);
-    console.log('✅ Mutation operations measured');
-    console.log(`   Without usage: ${calculateStats(mutationWithoutUsage).p95.toFixed(2)}ms P95`);
-    console.log(`   With usage: ${calculateStats(mutationWithUsage).p95.toFixed(2)}ms P95`);
-    console.log(`   Overhead: ${mutationOverhead.toFixed(2)}%`);
-    console.log();
+    (0, logger_js_1.logInfo)('✅ Mutation operations measured');
+    (0, logger_js_1.logInfo)(`   Without usage: ${calculateStats(mutationWithoutUsage).p95.toFixed(2)}ms P95`);
+    (0, logger_js_1.logInfo)(`   With usage: ${calculateStats(mutationWithUsage).p95.toFixed(2)}ms P95`);
+    (0, logger_js_1.logInfo)(`   Overhead: ${mutationOverhead.toFixed(2)}%`);
+    (0, logger_js_1.logInfo)('---');
     // Summary
     const maxOverhead = Math.max(listOverhead, mutationOverhead);
     const meetsTarget = maxOverhead <= 5.0;
-    console.log('📈 Performance Baseline Summary:');
-    console.log(`   List operations overhead: ${listOverhead.toFixed(2)}%`);
-    console.log(`   Mutation operations overhead: ${mutationOverhead.toFixed(2)}%`);
-    console.log(`   Maximum overhead: ${maxOverhead.toFixed(2)}%`);
-    console.log(`   Target met (<5%): ${meetsTarget ? '✅ YES' : '❌ NO'}`);
+    (0, logger_js_1.logInfo)('📈 Performance Baseline Summary:');
+    (0, logger_js_1.logInfo)(`   List operations overhead: ${listOverhead.toFixed(2)}%`);
+    (0, logger_js_1.logInfo)(`   Mutation operations overhead: ${mutationOverhead.toFixed(2)}%`);
+    (0, logger_js_1.logInfo)(`   Maximum overhead: ${maxOverhead.toFixed(2)}%`);
+    (0, logger_js_1.logInfo)(`   Target met (<5%): ${meetsTarget ? '✅ YES' : '❌ NO'}`);
     const results = {
         listOperations: {
             withoutUsage: listWithoutUsage,
@@ -204,7 +205,7 @@ async function runPerformanceBaseline() {
         target: '<5% overhead',
         results
     }, null, 2));
-    console.log();
-    console.log(`💾 Detailed results saved to: ${baselineFile}`);
+    (0, logger_js_1.logInfo)('---');
+    (0, logger_js_1.logInfo)(`💾 Detailed results saved to: ${baselineFile}`);
     return results;
 }

package/dist/services/promptReviewService.d.ts

@@ -20,7 +20,7 @@ export interface PromptIssue {
     match?: string;
 }
 export declare class PromptReviewService {
-    private criteria;
+    private compiledCategories;
     /**
      * @param criteriaPath - Optional explicit path to a `PROMPT-CRITERIA.json` file.
      *   When omitted the service searches a set of standard candidate locations.
@@ -32,6 +32,8 @@ export declare class PromptReviewService {
      * @returns Array of {@link PromptIssue} objects describing detected rule violations; empty when clean
      */
     review(prompt: string): PromptIssue[];
+    private compileCategories;
+    private compileRule;
 }
 /**
  * Aggregate a list of prompt issues into per-severity counts and identify the highest severity present.

package/dist/services/promptReviewService.js

@@ -7,8 +7,10 @@ exports.PromptReviewService = void 0;
 exports.summarizeIssues = summarizeIssues;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const logger_js_1 = require("./logger.js");
+const regexSafety_js_1 = require("./regexSafety.js");
 class PromptReviewService {
-    criteria;
+    compiledCategories;
     /**
      * @param criteriaPath - Optional explicit path to a `PROMPT-CRITERIA.json` file.
      *   When omitted the service searches a set of standard candidate locations.
@@ -41,14 +43,14 @@ class PromptReviewService {
         if (!loaded) {
             // Graceful fallback: empty criteria so server can still start.
             const msg = `[promptReviewService] WARN: Could not locate PROMPT-CRITERIA.json in any candidate paths. Using empty criteria.`;
-            // Write to stderr explicitly (console.error already does)
-            console.error(msg);
+            // Write to stderr explicitly (logWarn writes to stderr)
+            (0, logger_js_1.logWarn)(msg);
             loaded = { version: '0.0.0', categories: [] };
         }
         else {
-            console.error(`[promptReviewService] Loaded criteria from ${usedPath}`); // stderr so it won't pollute stdout
+            (0, logger_js_1.logInfo)(`[promptReviewService] Loaded criteria from ${usedPath}`); // stderr so it won't pollute stdout
         }
-        this.criteria = loaded;
+        this.compiledCategories = this.compileCategories(loaded);
     }
     /**
      * Run all loaded criteria rules against a prompt string and return any detected issues.
@@ -57,19 +59,17 @@ class PromptReviewService {
      */
     review(prompt) {
         const issues = [];
-        for (const cat of this.criteria.categories) {
+        for (const cat of this.compiledCategories) {
             for (const rule of cat.rules) {
-                if (rule.pattern) {
-                    // Apply global + case-insensitive flags for broader detection
-                    const regex = new RegExp(rule.pattern, 'gi');
-                    const m = prompt.match(regex);
+                if (rule.patternRegex) {
+                    rule.patternRegex.lastIndex = 0;
+                    const m = prompt.match(rule.patternRegex);
                     if (m) {
                         issues.push({ ruleId: rule.id, severity: rule.severity, description: rule.description, match: m[0] });
                     }
                 }
-                if (rule.mustContain) {
-                    const mc = new RegExp(rule.mustContain, 'i');
-                    if (!mc.test(prompt)) {
+                if (rule.mustContainRegex) {
+                    if (!rule.mustContainRegex.test(prompt)) {
                         issues.push({ ruleId: rule.id, severity: rule.severity, description: 'Missing required token(s): ' + rule.description });
                     }
                 }
@@ -77,6 +77,34 @@ class PromptReviewService {
         }
         return issues;
     }
+    compileCategories(criteria) {
+        return criteria.categories.map((category) => ({
+            id: category.id,
+            rules: category.rules.map((rule) => this.compileRule(category.id, rule)),
+        }));
+    }
+    compileRule(categoryId, rule) {
+        const compiled = { ...rule };
+        if (rule.pattern) {
+            const { regex, error } = (0, regexSafety_js_1.compileSafeRegex)(rule.pattern, 'gi');
+            if (regex) {
+                compiled.patternRegex = regex;
+            }
+            else {
+                (0, logger_js_1.logWarn)(`[promptReviewService] Skipping unsafe pattern regex for rule "${rule.id}" in category "${categoryId}": ${error}`);
+            }
+        }
+        if (rule.mustContain) {
+            const { regex, error } = (0, regexSafety_js_1.compileSafeRegex)(rule.mustContain, 'i');
+            if (regex) {
+                compiled.mustContainRegex = regex;
+            }
+            else {
+                (0, logger_js_1.logWarn)(`[promptReviewService] Skipping unsafe mustContain regex for rule "${rule.id}" in category "${categoryId}": ${error}`);
+            }
+        }
+        return compiled;
+    }
 }
 exports.PromptReviewService = PromptReviewService;
 /**

package/dist/services/regexSafety.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_REGEX_PATTERN_LENGTH = 200;
+export declare function getRegexSafetyError(pattern: string): string | undefined;
+export declare function compileSafeRegex(pattern: string, flags?: string): {
+    regex?: RegExp;
+    error?: string;
+};

package/dist/services/regexSafety.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REGEX_PATTERN_LENGTH = void 0;
+exports.getRegexSafetyError = getRegexSafetyError;
+exports.compileSafeRegex = compileSafeRegex;
+const safe_regex2_1 = __importDefault(require("safe-regex2"));
+exports.MAX_REGEX_PATTERN_LENGTH = 200;
+function getRegexSafetyError(pattern) {
+    if (pattern.length > exports.MAX_REGEX_PATTERN_LENGTH) {
+        return 'Regex patterns must not exceed 200 characters to prevent ReDoS';
+    }
+    if (/\([^)]*[+*}]\)[+*{]/.test(pattern)) {
+        return 'Regex pattern rejected: nested quantifiers can cause catastrophic backtracking';
+    }
+    if (/\)[+*}][^(]*\)[+*{]/.test(pattern)) {
+        return 'Regex pattern rejected: nested quantifiers can cause catastrophic backtracking';
+    }
+    if (/\([^)]*\|[^)]*\)[+*]{1,}/.test(pattern)) {
+        return 'Regex pattern rejected: alternation with quantifiers can cause catastrophic backtracking';
+    }
+    try {
+        new RegExp(pattern);
+    }
+    catch {
+        return `Invalid regex pattern "${pattern}": check syntax and try again`;
+    }
+    if (!(0, safe_regex2_1.default)(pattern)) {
+        return 'Regex pattern rejected: potentially catastrophic backtracking detected';
+    }
+    return undefined;
+}
+function compileSafeRegex(pattern, flags) {
+    const error = getRegexSafetyError(pattern);
+    if (error) {
+        return { error };
+    }
+    try {
+        return { regex: new RegExp(pattern, flags) };
+    }
+    catch {
+        return { error: `Invalid regex pattern "${pattern}": check syntax and try again` };
+    }
+}

package/dist/services/seedBootstrap.js

@@ -94,7 +94,7 @@ Or add directly:
 
 - \`index_groom\` — clean duplicates and stale entries
 - \`index_governanceUpdate\` — deprecate outdated content (don't silently delete)
-- \`feedback_dispatch\` with action="submit" — report issues or request features
+- \`feedback_submit\` — report issues or request features
 - \`usage_track\` — signal when guidance was helpful or outdated
 
 ---

package/dist/services/storage/factory.d.ts

@@ -4,8 +4,13 @@
  * Creates the appropriate IInstructionStore implementation based on config.
  * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
  */
-import type { IInstructionStore } from './types.js';
+import type { IInstructionStore, IEmbeddingStore } from './types.js';
 export type StorageBackend = 'json' | 'sqlite';
+/**
+ * Check that the current Node.js version meets the minimum requirement.
+ * Throws a clear error if the version is too old.
+ */
+export declare function checkNodeVersion(minVersion: string, feature: string): void;
 /**
  * Create a storage backend instance.
  *
@@ -15,3 +20,11 @@ export type StorageBackend = 'json' | 'sqlite';
  * @returns An IInstructionStore implementation.
  */
 export declare function createStore(backend?: StorageBackend, dir?: string, sqlitePath?: string): IInstructionStore;
+/**
+ * Create an embedding store instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param embeddingPath - Override embedding file/db path (default: from config).
+ * @returns An IEmbeddingStore implementation.
+ */
+export declare function createEmbeddingStore(backend?: StorageBackend, embeddingPath?: string): IEmbeddingStore;

package/dist/services/storage/factory.js

@@ -6,10 +6,31 @@
  * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkNodeVersion = checkNodeVersion;
 exports.createStore = createStore;
+exports.createEmbeddingStore = createEmbeddingStore;
 const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
 const jsonFileStore_js_1 = require("./jsonFileStore.js");
+const jsonEmbeddingStore_js_1 = require("./jsonEmbeddingStore.js");
 const sqliteStore_js_1 = require("./sqliteStore.js");
+const logger_js_1 = require("../logger.js");
+/**
+ * Check that the current Node.js version meets the minimum requirement.
+ * Throws a clear error if the version is too old.
+ */
+function checkNodeVersion(minVersion, feature) {
+    const current = process.versions.node;
+    const cur = current.split('.').map(Number);
+    const min = minVersion.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((cur[i] ?? 0) > (min[i] ?? 0))
+            return;
+        if ((cur[i] ?? 0) < (min[i] ?? 0)) {
+            throw new Error(`Node.js ${minVersion}+ required for ${feature} (current: ${current}). ` +
+                `Please upgrade Node.js or switch to the JSON storage backend.`);
+        }
+    }
+}
 /**
  * Create a storage backend instance.
  *
@@ -24,7 +45,8 @@ function createStore(backend, dir, sqlitePath) {
     const resolvedDir = dir ?? config.index?.baseDir;
     switch (resolvedBackend) {
         case 'sqlite': {
-            console.warn('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
+            checkNodeVersion('22.5.0', 'SQLite storage backend (node:sqlite)');
+            (0, logger_js_1.logWarn)('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
             const dbPath = sqlitePath ?? config.storage?.sqlitePath ?? 'data/index.db';
             return new sqliteStore_js_1.SqliteStore(dbPath);
         }
@@ -33,3 +55,41 @@ function createStore(backend, dir, sqlitePath) {
             return new jsonFileStore_js_1.JsonFileStore(resolvedDir);
     }
 }
+/**
+ * Create an embedding store instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param embeddingPath - Override embedding file/db path (default: from config).
+ * @returns An IEmbeddingStore implementation.
+ */
+function createEmbeddingStore(backend, embeddingPath) {
+    const config = (0, runtimeConfig_js_1.getRuntimeConfig)();
+    const resolvedBackend = backend ?? config.storage?.backend ?? 'json';
+    switch (resolvedBackend) {
+        case 'sqlite': {
+            // Check if sqlite-vec is explicitly disabled via config
+            if (config.storage?.sqliteVecEnabled === false) {
+                const jsonPath = embeddingPath ?? config.semantic?.embeddingPath ?? 'data/embeddings.json';
+                return new jsonEmbeddingStore_js_1.JsonEmbeddingStore(jsonPath);
+            }
+            checkNodeVersion('22.13.0', 'sqlite-vec extension (DatabaseSync.loadExtension)');
+            // Lazy-load SqliteEmbeddingStore to avoid import errors when sqlite-vec is unavailable
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const { SqliteEmbeddingStore } = require('./sqliteEmbeddingStore.js');
+                const dbPath = embeddingPath ?? (config.storage?.sqliteVecPath || 'data/embeddings.db');
+                return new SqliteEmbeddingStore(dbPath);
+            }
+            catch (err) {
+                (0, logger_js_1.logWarn)(`[storage] sqlite-vec embedding store failed to initialize: ${err instanceof Error ? err.message : 'unknown'}. Falling back to JSON.`);
+                const jsonPath = embeddingPath ?? config.semantic?.embeddingPath ?? 'data/embeddings.json';
+                return new jsonEmbeddingStore_js_1.JsonEmbeddingStore(jsonPath);
+            }
+        }
+        case 'json':
+        default: {
+            const jsonPath = embeddingPath ?? config.semantic?.embeddingPath ?? 'data/embeddings.json';
+            return new jsonEmbeddingStore_js_1.JsonEmbeddingStore(jsonPath);
+        }
+    }
+}

package/dist/services/storage/jsonEmbeddingStore.d.ts

@@ -0,0 +1,15 @@
+/**
+ * JsonEmbeddingStore — IEmbeddingStore backed by a flat JSON file.
+ *
+ * Wraps the existing embeddings.json disk cache format.
+ * Search is brute-force cosine similarity (no indexing).
+ */
+import type { IEmbeddingStore, EmbeddingCacheData, EmbeddingSearchResult } from './types.js';
+export declare class JsonEmbeddingStore implements IEmbeddingStore {
+    private filePath;
+    constructor(filePath: string);
+    load(): EmbeddingCacheData | null;
+    save(data: EmbeddingCacheData): void;
+    search(queryVector: Float32Array, limit: number): EmbeddingSearchResult[];
+    close(): void;
+}

package/dist/services/storage/jsonEmbeddingStore.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * JsonEmbeddingStore — IEmbeddingStore backed by a flat JSON file.
+ *
+ * Wraps the existing embeddings.json disk cache format.
+ * Search is brute-force cosine similarity (no indexing).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEmbeddingStore = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Cosine similarity between two numeric arrays.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+class JsonEmbeddingStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return null;
+            const raw = fs_1.default.readFileSync(this.filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            // Backwards-compat: older caches used 'catalogHash'
+            if (data && typeof data.catalogHash === 'string' && typeof data.indexHash !== 'string') {
+                data.indexHash = data.catalogHash;
+                delete data.catalogHash;
+            }
+            if (!data || typeof data.indexHash !== 'string' || typeof data.embeddings !== 'object')
+                return null;
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
+    save(data) {
+        const dir = path_1.default.dirname(this.filePath);
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(data), 'utf-8');
+    }
+    search(queryVector, limit) {
+        if (limit <= 0)
+            return [];
+        const cached = this.load();
+        if (!cached)
+            return [];
+        const query = Array.from(queryVector);
+        const results = [];
+        for (const [id, vec] of Object.entries(cached.embeddings)) {
+            const similarity = cosineSimilarity(query, vec);
+            // Distance = 1 - similarity (lower is closer)
+            results.push({ id, distance: 1 - similarity });
+        }
+        results.sort((a, b) => a.distance - b.distance);
+        return results.slice(0, limit);
+    }
+    close() {
+        // No resources to release for file-based store
+    }
+}
+exports.JsonEmbeddingStore = JsonEmbeddingStore;

package/dist/services/storage/jsonFileStore.d.ts

@@ -19,7 +19,9 @@ export declare class JsonFileStore implements IInstructionStore {
     load(): LoadResult;
     close(): void;
     get(id: string): InstructionEntry | null;
-    write(entry: InstructionEntry): void;
+    write(entry: InstructionEntry, opts?: {
+        createOnly?: boolean;
+    }): void;
     remove(id: string): void;
     list(opts?: ListOptions): InstructionEntry[];
     query(opts: QueryOptions): InstructionEntry[];

package/dist/services/storage/jsonFileStore.js

@@ -14,8 +14,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonFileStore = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const crypto_1 = __importDefault(require("crypto"));
 const hashUtils_js_1 = require("./hashUtils.js");
+const atomicFs_js_1 = require("../atomicFs.js");
 class JsonFileStore {
     dir;
     cache = new Map();
@@ -87,12 +87,14 @@ class JsonFileStore {
         this.ensureLoaded();
         return this.cache.get(id) ?? null;
     }
-    write(entry) {
-        // Write to disk
+    write(entry, opts) {
         const filePath = path_1.default.join(this.dir, `${entry.id}.json`);
-        const tmpPath = `${filePath}.${crypto_1.default.randomBytes(4).toString('hex')}.tmp`;
-        fs_1.default.writeFileSync(tmpPath, JSON.stringify(entry, null, 2), 'utf-8');
-        fs_1.default.renameSync(tmpPath, filePath);
+        if (opts?.createOnly) {
+            (0, atomicFs_js_1.atomicCreateJson)(filePath, entry);
+        }
+        else {
+            (0, atomicFs_js_1.atomicWriteJson)(filePath, entry);
+        }
         // Update in-memory cache
         this.cache.set(entry.id, entry);
         this.loaded = true;

package/dist/services/storage/migrationEngine.d.ts

@@ -3,6 +3,7 @@
  *
  * Uses Node.js built-in node:sqlite. Zero third-party dependencies.
  */
+import type { IEmbeddingStore } from './types.js';
 export interface MigrationOptions {
     onProgress?: (current: number, total: number) => void;
 }
@@ -33,3 +34,15 @@ export declare function migrateJsonToSqlite(jsonDir: string, dbPath: string, opt
  * Each entry becomes a separate .json file named by ID.
  */
 export declare function migrateSqliteToJson(dbPath: string, jsonDir: string, opts?: MigrationOptions): ExportResult;
+export interface EmbeddingMigrationResult {
+    migrated: number;
+    skipped: number;
+    error?: string;
+}
+/**
+ * Migrate embeddings from a JSON file to an IEmbeddingStore (e.g. SqliteEmbeddingStore).
+ *
+ * Reads the JSON embedding cache and saves it into the target store.
+ * Idempotent: calling again with the same data overwrites safely.
+ */
+export declare function migrateJsonEmbeddingsToStore(jsonEmbeddingPath: string, targetStore: IEmbeddingStore): EmbeddingMigrationResult;