@karmaniverous/jeeves-watcher 0.13.0 → 0.14.0

package/dist/cli/jeeves-watcher/index.js

@@ -5,10 +5,11 @@ import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSy
 import { join, dirname, resolve, relative, extname, basename, isAbsolute } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
-import { readdir, stat, writeFile, rm, readFile, mkdir } from 'node:fs/promises';
+import { readdir, stat, writeFile, readFile } from 'node:fs/promises';
 import { parallel, capitalize, title, camel, snake, dash, isEqual, get, omit } from 'radash';
 import ignore from 'ignore';
 import picomatch from 'picomatch';
+import Database from 'better-sqlite3';
 import { z, ZodError } from 'zod';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
@@ -24,10 +25,10 @@ import { toMarkdown } from 'mdast-util-to-markdown';
 import rehypeParse from 'rehype-parse';
 import { unified } from 'unified';
 import yaml from 'js-yaml';
-import { createHash } from 'node:crypto';
 import crypto from 'crypto';
 import { cosmiconfig } from 'cosmiconfig';
 import https from 'node:https';
+import { createHash } from 'node:crypto';
 import pino from 'pino';
 import { v5 } from 'uuid';
 import * as cheerio from 'cheerio';
@@ -1019,6 +1020,218 @@ class InitialScanTracker {
     }
 }
 
+/**
+ * @module util/normalizePath
+ * Normalizes file paths for deterministic mapping: lowercase, forward slashes, optional drive letter stripping.
+ */
+/**
+ * Normalize a file path: lowercase, forward slashes, optionally strip drive letter colon.
+ *
+ * @param filePath - The original file path.
+ * @param stripDriveLetter - Whether to strip the colon from a leading drive letter (e.g. `C:` → `c`).
+ * @returns The normalized path string.
+ */
+function normalizePath(filePath, stripDriveLetter = false) {
+    let result = filePath.replace(/\\/g, '/').toLowerCase();
+    if (stripDriveLetter) {
+        result = result.replace(/^([a-z]):/, (_m, letter) => letter);
+    }
+    return result;
+}
+
+/**
+ * @module cache/ContentHashCache
+ * In-memory cache mapping normalized file paths to content hashes.
+ * Supports reverse lookup by hash for move correlation.
+ */
+/**
+ * In-memory content hash cache for move detection.
+ *
+ * Maps normalized file paths to SHA-256 content hashes.
+ * Supports reverse lookup (hash → paths) for correlating
+ * unlink+add events as file moves.
+ */
+class ContentHashCache {
+    pathToHash = new Map();
+    hashToPaths = new Map();
+    /**
+     * Store or update the content hash for a file path.
+     *
+     * @param filePath - The file path (will be normalized).
+     * @param hash - The SHA-256 content hash.
+     */
+    set(filePath, hash) {
+        const normalized = normalizePath(filePath, true);
+        const oldHash = this.pathToHash.get(normalized);
+        // Remove from old hash index if hash changed
+        if (oldHash !== undefined && oldHash !== hash) {
+            const oldPaths = this.hashToPaths.get(oldHash);
+            if (oldPaths) {
+                oldPaths.delete(normalized);
+                if (oldPaths.size === 0)
+                    this.hashToPaths.delete(oldHash);
+            }
+        }
+        this.pathToHash.set(normalized, hash);
+        let paths = this.hashToPaths.get(hash);
+        if (!paths) {
+            paths = new Set();
+            this.hashToPaths.set(hash, paths);
+        }
+        paths.add(normalized);
+    }
+    /**
+     * Get the content hash for a file path.
+     *
+     * @param filePath - The file path (will be normalized).
+     * @returns The content hash, or undefined if not cached.
+     */
+    get(filePath) {
+        return this.pathToHash.get(normalizePath(filePath, true));
+    }
+    /**
+     * Remove a file path from the cache.
+     *
+     * @param filePath - The file path (will be normalized).
+     */
+    delete(filePath) {
+        const normalized = normalizePath(filePath, true);
+        const hash = this.pathToHash.get(normalized);
+        if (hash === undefined)
+            return;
+        this.pathToHash.delete(normalized);
+        const paths = this.hashToPaths.get(hash);
+        if (paths) {
+            paths.delete(normalized);
+            if (paths.size === 0)
+                this.hashToPaths.delete(hash);
+        }
+    }
+    /**
+     * Reverse lookup: get all file paths with a given content hash.
+     *
+     * @param hash - The content hash to look up.
+     * @returns Array of normalized file paths with that hash.
+     */
+    getByHash(hash) {
+        const paths = this.hashToPaths.get(hash);
+        return paths ? [...paths] : [];
+    }
+    /** Number of cached entries. */
+    get size() {
+        return this.pathToHash.size;
+    }
+}
+
+/**
+ * @module enrichment/EnrichmentStore
+ * SQLite-backed enrichment metadata store. Persists path-keyed metadata at stateDir/enrichments.sqlite. Atomic writes, supports move.
+ */
+/**
+ * SQLite-backed enrichment metadata store.
+ */
+class EnrichmentStore {
+    db;
+    /**
+     * Create or open the enrichment store.
+     *
+     * @param stateDir - Directory for the SQLite database file.
+     */
+    constructor(stateDir) {
+        mkdirSync(stateDir, { recursive: true });
+        const dbPath = join(stateDir, 'enrichments.sqlite');
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS enrichments (
+        path TEXT PRIMARY KEY,
+        metadata TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+    }
+    get(path) {
+        const normalized = normalizePath(path);
+        const row = this.db
+            .prepare('SELECT metadata FROM enrichments WHERE path = ?')
+            .get(normalized);
+        if (!row)
+            return null;
+        return JSON.parse(row.metadata);
+    }
+    set(path, metadata) {
+        const normalized = normalizePath(path);
+        const now = new Date().toISOString();
+        const existing = this.get(path);
+        const merged = existing ? { ...existing, ...metadata } : metadata;
+        const json = JSON.stringify(merged);
+        if (existing) {
+            this.db
+                .prepare('UPDATE enrichments SET metadata = ?, updated_at = ? WHERE path = ?')
+                .run(json, now, normalized);
+        }
+        else {
+            this.db
+                .prepare('INSERT INTO enrichments (path, metadata, created_at, updated_at) VALUES (?, ?, ?, ?)')
+                .run(normalized, json, now, now);
+        }
+    }
+    delete(path) {
+        const normalized = normalizePath(path);
+        this.db.prepare('DELETE FROM enrichments WHERE path = ?').run(normalized);
+    }
+    move(oldPath, newPath) {
+        const normalizedOld = normalizePath(oldPath);
+        const normalizedNew = normalizePath(newPath);
+        const now = new Date().toISOString();
+        this.db
+            .prepare('UPDATE enrichments SET path = ?, updated_at = ? WHERE path = ?')
+            .run(normalizedNew, now, normalizedOld);
+    }
+    list() {
+        const rows = this.db
+            .prepare('SELECT path FROM enrichments ORDER BY path')
+            .all();
+        return rows.map((r) => r.path);
+    }
+    close() {
+        this.db.close();
+    }
+}
+
+/**
+ * @module enrichment/merge
+ * Composable merge for inferred + enrichment metadata. Scalars: enrichment overwrites. Arrays: union + deduplicate. No I/O.
+ */
+/**
+ * Merge enrichment metadata into inferred metadata with composable semantics.
+ *
+ * - Scalar fields: enrichment value overwrites inferred value.
+ * - Array fields: union merge with deduplication (enrichment values appended).
+ *
+ * @param inferred - Metadata derived from inference rules.
+ * @param enrichment - Human/agent-provided enrichment metadata.
+ * @returns Merged metadata.
+ */
+function mergeEnrichment(inferred, enrichment) {
+    const result = { ...inferred };
+    for (const [key, enrichValue] of Object.entries(enrichment)) {
+        const inferredValue = result[key];
+        if (Array.isArray(inferredValue) && Array.isArray(enrichValue)) {
+            const combined = [
+                ...inferredValue,
+                ...enrichValue,
+            ];
+            result[key] = [...new Set(combined)];
+        }
+        else {
+            result[key] = enrichValue;
+        }
+    }
+    return result;
+}
+
 /**
  * @module util/JsonFileStore
  * Small base class for JSON-backed read/modify/write stores with in-memory caching.
@@ -1438,6 +1651,24 @@ const watchConfigSchema = z.object({
         .boolean()
         .optional()
         .describe('Skip files ignored by .gitignore in git repositories. Only applies to repos with a .git directory. Default: true.'),
+    /** Move detection configuration for correlating unlink+add as file moves. */
+    moveDetection: z
+        .object({
+        /** Enable move correlation. Default: true. */
+        enabled: z
+            .boolean()
+            .default(true)
+            .describe('Enable move detection via content hash correlation.'),
+        /** Buffer time in ms for holding unlink events before treating as deletes. Default: 2000. */
+        bufferMs: z
+            .number()
+            .int()
+            .min(100)
+            .default(2000)
+            .describe('How long (ms) to buffer unlink events before treating as deletes.'),
+    })
+        .optional()
+        .describe('Move detection: correlate unlink+add events as file moves to avoid re-embedding.'),
 });
 /**
  * Configuration watch settings.
@@ -1746,18 +1977,13 @@ const jeevesWatcherConfigSchema = z.object({
     embedding: embeddingConfigSchema.describe('Embedding model configuration.'),
     /** Vector store configuration. */
     vectorStore: vectorStoreConfigSchema.describe('Qdrant vector store configuration.'),
-    /** Directory for persisted metadata. */
-    metadataDir: z
-        .string()
-        .optional()
-        .describe('Directory for persisted metadata sidecar files.'),
     /** API server configuration. */
     api: apiConfigSchema.optional().describe('API server configuration.'),
-    /** Directory for persistent state files (issues.json, values.json). Defaults to metadataDir. */
+    /** Directory for persistent state files (issues.json, values.json, enrichments.sqlite). */
     stateDir: z
         .string()
         .optional()
-        .describe('Directory for persistent state files (issues.json, values.json). Defaults to metadataDir.'),
+        .describe('Directory for persistent state files (issues.json, values.json, enrichments.sqlite). Defaults to .jeeves-metadata.'),
     /** Rules for inferring metadata from document properties (inline objects or file paths). */
     inferenceRules: z
         .array(z.union([inferenceRuleSchema, z.string()]))
@@ -3892,97 +4118,6 @@ function createPointsDeleteHandler(deps) {
     }, deps.logger, 'PointsDelete');
 }
 
-/**
- * @module util/normalizePath
- * Normalizes file paths for deterministic mapping: lowercase, forward slashes, optional drive letter stripping.
- */
-/**
- * Normalize a file path: lowercase, forward slashes, optionally strip drive letter colon.
- *
- * @param filePath - The original file path.
- * @param stripDriveLetter - Whether to strip the colon from a leading drive letter (e.g. `C:` → `c`).
- * @returns The normalized path string.
- */
-function normalizePath(filePath, stripDriveLetter = false) {
-    let result = filePath.replace(/\\/g, '/').toLowerCase();
-    if (stripDriveLetter) {
-        result = result.replace(/^([a-z]):/, (_m, letter) => letter);
-    }
-    return result;
-}
-
-/**
- * @module metadata/metadata
- * Persists file metadata as .meta.json. I/O: reads/writes/deletes metadata files under metadataDir. Path mapping via SHA-256 hash.
- */
-/**
- * Derive a deterministic `.meta.json` path for a given file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @returns The full path to the metadata file.
- */
-function metadataPath(filePath, metadataDir) {
-    const normalised = normalizePath(filePath, true);
-    const hash = createHash('sha256').update(normalised, 'utf8').digest('hex');
-    return join(metadataDir, `${hash}.meta.json`);
-}
-/**
- * Read persisted metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @returns The parsed metadata object, or `null` if not found.
- */
-async function readMetadata(filePath, metadataDir) {
-    try {
-        const raw = await readFile(metadataPath(filePath, metadataDir), 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Write metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @param metadata - The metadata to persist.
- */
-async function writeMetadata(filePath, metadataDir, metadata) {
-    const dest = metadataPath(filePath, metadataDir);
-    await mkdir(dirname(dest), { recursive: true });
-    await writeFile(dest, JSON.stringify(metadata, null, 2), 'utf8');
-}
-/**
- * Delete metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- */
-async function deleteMetadata(filePath, metadataDir) {
-    try {
-        await rm(metadataPath(filePath, metadataDir));
-    }
-    catch {
-        // Ignore if file doesn't exist.
-    }
-}
-
-/**
- * @module metadata/constants
- * Shared constants for metadata key classification. System keys are injected by the indexing pipeline, not user-provided.
- */
-/** Keys managed by the indexing pipeline (not user enrichment). */
-const SYSTEM_METADATA_KEYS = [
-    'file_path',
-    'chunk_index',
-    'total_chunks',
-    'content_hash',
-    'chunk_text',
-];
-
 /**
  * @module processor/payloadFields
  * Constants for Qdrant payload field names used across the processing pipeline.
@@ -4005,10 +4140,18 @@ const FIELD_MODIFIED_AT = 'modified_at';
 const FIELD_LINE_START = 'line_start';
 /** Qdrant payload field: 1-indexed line number where this chunk ends in the source file. */
 const FIELD_LINE_END = 'line_end';
+/** Keys managed by the indexing pipeline (not user enrichment). */
+const SYSTEM_METADATA_KEYS = [
+    FIELD_FILE_PATH,
+    FIELD_CHUNK_INDEX,
+    FIELD_TOTAL_CHUNKS,
+    FIELD_CONTENT_HASH,
+    FIELD_CHUNK_TEXT,
+];
 
 /**
  * @module api/handlers/rebuildMetadata
- * Fastify route handler for POST /rebuild-metadata. Recreates enrichment metadata files from vector store payloads.
+ * Fastify route handler for POST /rebuild-metadata. Rebuilds enrichment store from vector store payloads.
  */
 /**
  * Create handler for POST /rebuild-metadata.
@@ -4017,7 +4160,6 @@ const FIELD_LINE_END = 'line_end';
  */
 function createRebuildMetadataHandler(deps) {
     return wrapHandler(async (_request, reply) => {
-        const metadataDir = deps.metadataDir ?? '.jeeves-metadata';
         const systemKeys = [...SYSTEM_METADATA_KEYS];
         for await (const point of deps.vectorStore.scroll()) {
             const payload = point.payload;
@@ -4025,7 +4167,7 @@ function createRebuildMetadataHandler(deps) {
             if (typeof filePath !== 'string' || filePath.length === 0)
                 continue;
             const enrichment = omit(payload, systemKeys);
-            await writeMetadata(filePath, metadataDir, enrichment);
+            deps.enrichmentStore?.set(filePath, enrichment);
         }
         return await reply.status(200).send({ ok: true });
     }, deps.logger, 'Rebuild metadata');
@@ -4525,7 +4667,6 @@ async function buildTemplateEngineAndCustomMapLib(config, configDir) {
  */
 function createProcessorConfig(config, configDir, customMapLib) {
     return {
-        metadataDir: config.metadataDir ?? '.jeeves-metadata',
         chunkSize: config.embedding.chunkSize,
         chunkOverlap: config.embedding.chunkOverlap,
         maps: resolveMapsConfig(config.maps),
@@ -4537,7 +4678,7 @@ function createProcessorConfig(config, configDir, customMapLib) {
 /**
  * Create file system watcher with gitignore filtering.
  */
-function createWatcher(config, factories, queue, processor, logger, runtimeOptions, initialScanTracker) {
+function createWatcher(config, factories, queue, processor, logger, runtimeOptions, initialScanTracker, contentHashCache) {
     const respectGitignore = config.watch.respectGitignore ?? true;
     const gitignoreFilter = respectGitignore
         ? new GitignoreFilter(config.watch.paths)
@@ -4548,6 +4689,7 @@ function createWatcher(config, factories, queue, processor, logger, runtimeOptio
         onFatalError: runtimeOptions.onFatalError,
         gitignoreFilter,
         initialScanTracker,
+        contentHashCache,
     });
     return { watcher, gitignoreFilter };
 }
@@ -4748,7 +4890,7 @@ function createApiServer(options) {
         hybridConfig,
     }));
     app.post('/rebuild-metadata', createRebuildMetadataHandler({
-        metadataDir: config.metadataDir,
+        enrichmentStore: options.enrichmentStore,
         vectorStore,
         logger,
     }));
@@ -4828,7 +4970,7 @@ function createApiServer(options) {
  */
 /** Default root-level config values. */
 const ROOT_DEFAULTS = {
-    metadataDir: '.jeeves-watcher',
+    stateDir: '.jeeves-metadata',
     shutdownTimeoutMs: 10000,
 };
 /** Default configWatch values. */
@@ -4879,7 +5021,7 @@ const INIT_CONFIG_TEMPLATE = {
         url: 'http://127.0.0.1:6333',
         collectionName: 'jeeves-watcher',
     },
-    metadataDir: ROOT_DEFAULTS.metadataDir,
+    stateDir: ROOT_DEFAULTS.stateDir,
     api: API_DEFAULTS,
     logging: LOGGING_DEFAULTS,
 };
@@ -5221,7 +5363,7 @@ function createLogger(config) {
 
 /**
  * @module hash
- * Provides SHA-256 content hashing. Pure function: given text string, returns hex digest. No I/O or side effects.
+ * Provides SHA-256 content hashing. Pure functions: text hash and file hash. File hash does I/O.
  */
 /**
  * Compute a SHA-256 hex digest of the given text.
@@ -5232,6 +5374,16 @@ function createLogger(config) {
 function contentHash(text) {
     return createHash('sha256').update(text, 'utf8').digest('hex');
 }
+/**
+ * Compute a SHA-256 hex digest of a file's raw bytes.
+ *
+ * @param filePath - Path to the file.
+ * @returns The hex-encoded SHA-256 hash.
+ */
+async function fileHash(filePath) {
+    const buffer = await readFile(filePath);
+    return createHash('sha256').update(buffer).digest('hex');
+}
 
 /**
  * @module pointId
@@ -5391,7 +5543,7 @@ async function extractText(filePath, extension, additionalExtractors) {
 
 /**
  * @module processor/buildMetadata
- * Builds merged metadata from file content, inference rules, and enrichment. I/O: reads files, extracts text, loads enrichment .meta.json.
+ * Builds merged metadata from file content, inference rules, and enrichment store. I/O: reads files, extracts text, queries SQLite enrichment.
  */
 /**
  * Build merged metadata for a file by applying inference rules and merging with enrichment metadata.
@@ -5400,7 +5552,7 @@ async function extractText(filePath, extension, additionalExtractors) {
  * @returns The merged metadata and intermediate data.
  */
 async function buildMergedMetadata(options) {
-    const { filePath, compiledRules, metadataDir, maps, logger, templateEngine, configDir, customMapLib, globalSchemas, } = options;
+    const { filePath, compiledRules, enrichmentStore, maps, logger, templateEngine, configDir, customMapLib, globalSchemas, } = options;
     const ext = extname(filePath);
     const stats = await stat(filePath);
     // 1. Extract text and structured data
@@ -5415,12 +5567,11 @@ async function buildMergedMetadata(options) {
         customMapLib,
         globalSchemas,
     });
-    // 3. Read enrichment metadata (merge, enrichment wins)
-    const enrichment = await readMetadata(filePath, metadataDir);
-    const metadata = {
-        ...inferred,
-        ...(enrichment ?? {}),
-    };
+    // 3. Read enrichment metadata from store (composable merge)
+    const enrichment = enrichmentStore?.get(filePath) ?? null;
+    const metadata = enrichment
+        ? mergeEnrichment(inferred, enrichment)
+        : { ...inferred };
     return {
         inferred,
         enrichment,
@@ -5609,22 +5760,26 @@ class DocumentProcessor {
     compiledRules;
     logger;
     templateEngine;
+    enrichmentStore;
     issuesManager;
     valuesManager;
+    contentHashCache;
     /**
      * Create a new DocumentProcessor.
      *
      * @param deps - The processor dependencies.
      */
-    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, issuesManager, valuesManager, }) {
+    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, enrichmentStore, issuesManager, valuesManager, contentHashCache, }) {
         this.config = config;
         this.embeddingProvider = embeddingProvider;
         this.vectorStore = vectorStore;
         this.compiledRules = compiledRules;
         this.logger = logger;
         this.templateEngine = templateEngine;
+        this.enrichmentStore = enrichmentStore;
         this.issuesManager = issuesManager;
         this.valuesManager = valuesManager;
+        this.contentHashCache = contentHashCache;
     }
     /**
      * Build merged metadata for a file and add matched_rules.
@@ -5633,7 +5788,7 @@ class DocumentProcessor {
         const result = await buildMergedMetadata({
             filePath,
             compiledRules: this.compiledRules,
-            metadataDir: this.config.metadataDir,
+            enrichmentStore: this.enrichmentStore,
             maps: this.config.maps,
             logger: this.logger,
             templateEngine: this.templateEngine,
@@ -5680,6 +5835,9 @@ class DocumentProcessor {
                 this.logger.debug({ filePath }, 'Skipping empty file');
                 return;
             }
+            // Compute file-level hash for move correlation cache.
+            const rawHash = await fileHash(filePath);
+            this.contentHashCache?.set(filePath, rawHash);
             const hash = contentHash(textToEmbed);
             const baseId = pointId(filePath, 0);
             const existingPayload = await this.vectorStore.getPayload(baseId);
@@ -5716,12 +5874,13 @@ class DocumentProcessor {
             const totalChunks = getChunkCount(existingPayload);
             const ids = chunkIds(filePath, totalChunks);
             await this.vectorStore.delete(ids);
-            await deleteMetadata(filePath, this.config.metadataDir);
+            this.enrichmentStore?.delete(filePath);
+            this.contentHashCache?.delete(filePath);
             this.logger.info({ filePath }, 'File deleted from index');
         }, undefined);
     }
     /**
-     * Process a metadata update: merge metadata, write to disk, update Qdrant payloads (no re-embed).
+     * Process a metadata update: merge into enrichment store, update Qdrant payloads (no re-embed).
      *
      * @param filePath - The file whose metadata to update.
      * @param metadata - The new metadata to merge.
@@ -5729,9 +5888,8 @@ class DocumentProcessor {
      */
     async processMetadataUpdate(filePath, metadata) {
         return this.withFileErrorHandling(filePath, 'Failed to update metadata', async () => {
-            const existing = (await readMetadata(filePath, this.config.metadataDir)) ?? {};
-            const merged = { ...existing, ...metadata };
-            await writeMetadata(filePath, this.config.metadataDir, merged);
+            this.enrichmentStore?.set(filePath, metadata);
+            const merged = this.enrichmentStore?.get(filePath) ?? metadata;
             const baseId = pointId(filePath, 0);
             const existingPayload = await this.vectorStore.getPayload(baseId);
             if (!existingPayload)
@@ -5793,6 +5951,56 @@ class DocumentProcessor {
             transformed: renderedContent !== null,
         };
     }
+    /**
+     * Move a file's vector points from old path to new path without re-embedding.
+     * Re-applies inference rules against the new path.
+     *
+     * @param oldPath - The original file path.
+     * @param newPath - The new file path.
+     */
+    async moveFile(oldPath, newPath) {
+        await this.withFileErrorHandling(newPath, 'Failed to move file', async () => {
+            const baseId = pointId(oldPath, 0);
+            const existingPayload = await this.vectorStore.getPayload(baseId);
+            const totalChunks = getChunkCount(existingPayload);
+            const oldIds = chunkIds(oldPath, totalChunks);
+            const oldPoints = await this.vectorStore.getPointsWithVectors(oldIds);
+            if (oldPoints.length === 0) {
+                this.logger.warn({ oldPath, newPath }, 'No points found for move');
+                return;
+            }
+            // Build new metadata from inference rules against the new path.
+            const { metadataWithRules, matchedRules, metadata } = await this.buildMetadataWithRules(newPath);
+            // Create new points with updated IDs and file_path payload.
+            const newPoints = oldPoints.map((pt, i) => ({
+                id: pointId(newPath, i),
+                vector: pt.vector,
+                payload: {
+                    ...pt.payload,
+                    ...metadataWithRules,
+                    [FIELD_FILE_PATH]: normalizeSlashes(newPath),
+                },
+            }));
+            await this.vectorStore.upsert(newPoints);
+            await this.vectorStore.delete(oldIds);
+            // Migrate enrichment and clear old issues.
+            this.enrichmentStore?.move(oldPath, newPath);
+            this.issuesManager?.clear(oldPath);
+            // Update values index for the new path's matched rules.
+            if (this.valuesManager) {
+                for (const ruleName of matchedRules) {
+                    this.valuesManager.update(ruleName, metadata);
+                }
+            }
+            // Update content hash cache.
+            const oldHash = this.contentHashCache?.get(oldPath);
+            if (oldHash) {
+                this.contentHashCache?.set(newPath, oldHash);
+            }
+            this.contentHashCache?.delete(oldPath);
+            this.logger.info({ oldPath, newPath, chunks: oldPoints.length }, 'File moved in index');
+        }, undefined);
+    }
     /**
      * Update compiled inference rules, template engine, and custom map lib.
      *
@@ -6451,6 +6659,33 @@ class VectorStoreClient {
     async hybridSearch(vector, queryText, limit, textWeight, filter) {
         return hybridSearch(this.client, this.collectionName, vector, queryText, limit, textWeight, filter);
     }
+    /**
+     * Retrieve points with their vectors by ID.
+     *
+     * @param ids - The point IDs to retrieve.
+     * @returns Points with vectors and payloads; missing IDs are omitted.
+     */
+    async getPointsWithVectors(ids) {
+        if (ids.length === 0)
+            return [];
+        try {
+            const results = await this.client.retrieve(this.collectionName, {
+                ids,
+                with_payload: true,
+                with_vector: true,
+            });
+            return results
+                .filter((r) => r.vector != null)
+                .map((r) => ({
+                id: String(r.id),
+                vector: r.vector,
+                payload: r.payload,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Scroll one page of points matching a filter.
      *
@@ -6658,6 +6893,163 @@ function resolveIgnored(ignored) {
     });
 }
 
+/**
+ * @module watcher/MoveCorrelator
+ * Correlates unlink+add events as file moves using content hash matching.
+ * Buffers unlink events and matches against subsequent add events.
+ */
+/**
+ * Correlates unlink+add file system events as moves using content hash matching.
+ *
+ * When move detection is disabled, events pass straight through.
+ */
+class MoveCorrelator {
+    enabled;
+    bufferMs;
+    cache;
+    logger;
+    onMove;
+    onDelete;
+    onCreate;
+    /** Buffered unlinks indexed by content hash (FIFO per hash). */
+    buffer = new Map();
+    /** Track unlink burst rate per parent directory for bulk mode. */
+    burstCounters = new Map();
+    /** Threshold: if N+ unlinks from same parent in burstWindowMs, extend buffer. */
+    static BURST_THRESHOLD = 5;
+    static BURST_WINDOW_MS = 500;
+    static BURST_MULTIPLIER = 3;
+    constructor(options) {
+        this.enabled = options.enabled;
+        this.bufferMs = options.bufferMs;
+        this.cache = options.contentHashCache;
+        this.logger = options.logger;
+        this.onMove = options.onMove;
+        this.onDelete = options.onDelete;
+        this.onCreate = options.onCreate;
+    }
+    /**
+     * Handle an unlink event. Buffers the event for correlation.
+     *
+     * @param path - The removed file path.
+     */
+    handleUnlink(path) {
+        if (!this.enabled) {
+            this.onDelete(path);
+            return;
+        }
+        const hash = this.cache.get(path);
+        if (!hash) {
+            this.logger.debug({ path }, 'No cached hash for unlinked file, treating as delete');
+            this.onDelete(path);
+            return;
+        }
+        const timeoutMs = this.getEffectiveTimeout(path);
+        const timer = setTimeout(() => {
+            this.expireUnlink(hash, path);
+        }, timeoutMs);
+        const entry = {
+            path,
+            hash,
+            timestamp: Date.now(),
+            timer,
+        };
+        let entries = this.buffer.get(hash);
+        if (!entries) {
+            entries = [];
+            this.buffer.set(hash, entries);
+        }
+        entries.push(entry);
+        this.logger.debug({ path, hash: hash.slice(0, 12), timeoutMs }, 'Buffered unlink for move correlation');
+    }
+    /**
+     * Handle an add event. Checks buffer for matching unlink (move detection).
+     *
+     * @param path - The added file path.
+     */
+    async handleAdd(path) {
+        if (!this.enabled) {
+            this.onCreate(path);
+            return;
+        }
+        let hash;
+        try {
+            hash = await fileHash(path);
+        }
+        catch {
+            this.onCreate(path);
+            return;
+        }
+        const entries = this.buffer.get(hash);
+        if (entries && entries.length > 0) {
+            // FIFO: consume oldest matching unlink
+            const matched = entries.shift();
+            clearTimeout(matched.timer);
+            if (entries.length === 0)
+                this.buffer.delete(hash);
+            this.logger.info({ oldPath: matched.path, newPath: path }, 'Move detected');
+            this.onMove(matched.path, path);
+        }
+        else {
+            this.onCreate(path);
+        }
+    }
+    /**
+     * Flush all buffered unlinks as deletes. Call on shutdown.
+     */
+    flush() {
+        for (const [, entries] of this.buffer) {
+            for (const entry of entries) {
+                clearTimeout(entry.timer);
+                this.onDelete(entry.path);
+            }
+        }
+        this.buffer.clear();
+        this.burstCounters.clear();
+    }
+    /** Number of currently buffered unlink events. */
+    get pendingCount() {
+        let count = 0;
+        for (const [, entries] of this.buffer) {
+            count += entries.length;
+        }
+        return count;
+    }
+    /**
+     * Get effective timeout, applying burst detection for bulk moves.
+     */
+    getEffectiveTimeout(path) {
+        const parentDir = dirname(path);
+        const now = Date.now();
+        let counter = this.burstCounters.get(parentDir);
+        if (!counter || now - counter.firstTs > MoveCorrelator.BURST_WINDOW_MS) {
+            counter = { count: 0, firstTs: now };
+            this.burstCounters.set(parentDir, counter);
+        }
+        counter.count++;
+        if (counter.count >= MoveCorrelator.BURST_THRESHOLD) {
+            return this.bufferMs * MoveCorrelator.BURST_MULTIPLIER;
+        }
+        return this.bufferMs;
+    }
+    /**
+     * Handle a buffered unlink timeout — emit as delete.
+     */
+    expireUnlink(hash, path) {
+        const entries = this.buffer.get(hash);
+        if (entries) {
+            const idx = entries.findIndex((e) => e.path === path);
+            if (idx >= 0) {
+                entries.splice(idx, 1);
+                if (entries.length === 0)
+                    this.buffer.delete(hash);
+            }
+        }
+        this.logger.debug({ path, hash: hash.slice(0, 12) }, 'Buffered unlink expired, treating as delete');
+        this.onDelete(path);
+    }
+}
+
 /**
  * @module watcher
  * Filesystem watcher wrapping chokidar. I/O: watches files/directories for add/change/unlink events, enqueues to processing queue.
@@ -6673,6 +7065,8 @@ class FileSystemWatcher {
     health;
     gitignoreFilter;
     initialScanTracker;
+    contentHashCache;
+    moveCorrelator;
     globMatches;
     watcher;
     /**
@@ -6691,6 +7085,7 @@ class FileSystemWatcher {
         this.logger = logger;
         this.gitignoreFilter = options.gitignoreFilter;
         this.initialScanTracker = options.initialScanTracker;
+        this.contentHashCache = options.contentHashCache;
         this.globMatches = () => true;
         const healthOptions = {
             maxRetries: options.maxRetries,
@@ -6736,6 +7131,26 @@ class FileSystemWatcher {
                 }
             }
         };
+        // Create move correlator if move detection is configured and cache is available.
+        const moveConfig = this.config.moveDetection;
+        if (moveConfig?.enabled && this.contentHashCache) {
+            this.moveCorrelator = new MoveCorrelator({
+                enabled: true,
+                bufferMs: moveConfig.bufferMs,
+                contentHashCache: this.contentHashCache,
+                logger: this.logger,
+                onMove: (oldPath, newPath) => {
+                    this.queue.enqueue({ type: 'move', path: newPath, oldPath, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.moveFile(oldPath, newPath)));
+                },
+                onDelete: (deletedPath) => {
+                    this.queue.enqueue({ type: 'delete', path: deletedPath, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.deleteFile(deletedPath)));
+                },
+                onCreate: (createdPath) => {
+                    this.queue.enqueue({ type: 'create', path: createdPath, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.processFile(createdPath)));
+                },
+            });
+        }
+        const correlator = this.moveCorrelator;
         this.watcher = chokidar.watch(roots, {
             ignored,
             usePolling: this.config.usePolling,
@@ -6769,7 +7184,12 @@ class FileSystemWatcher {
                 this.initialScanTracker?.incrementEnqueued();
             }
             this.logger.debug({ path }, 'File added');
-            this.queue.enqueue({ type: 'create', path, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.processFile(path)));
+            if (correlator && initialScanComplete) {
+                void correlator.handleAdd(path);
+            }
+            else {
+                this.queue.enqueue({ type: 'create', path, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.processFile(path)));
+            }
         });
         this.watcher.on('change', (path) => {
             this.handleGitignoreChange(path);
@@ -6789,7 +7209,12 @@ class FileSystemWatcher {
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File removed');
-            this.queue.enqueue({ type: 'delete', path, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.deleteFile(path)));
+            if (correlator) {
+                correlator.handleUnlink(path);
+            }
+            else {
+                this.queue.enqueue({ type: 'delete', path, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.deleteFile(path)));
+            }
         });
         this.watcher.on('ready', () => {
             initialScanComplete = true;
@@ -6834,6 +7259,7 @@ class FileSystemWatcher {
      * Stop the filesystem watcher.
      */
     async stop() {
+        this.moveCorrelator?.flush();
         if (this.watcher) {
             await this.watcher.close();
             this.watcher = undefined;
@@ -6967,6 +7393,8 @@ class JeevesWatcher {
     vectorStore;
     embeddingProvider;
     gitignoreFilter;
+    enrichmentStore;
+    contentHashCache;
     initialScanTracker;
     version;
     /** Create a new JeevesWatcher instance. */
@@ -7007,9 +7435,13 @@ class JeevesWatcher {
         const { templateEngine, customMapLib } = await buildTemplateEngineAndCustomMapLib(this.config, configDir);
         this.helperIntrospection = await introspectHelpers(this.config, configDir);
         const processorConfig = createProcessorConfig(this.config, configDir, customMapLib);
-        const stateDir = this.config.stateDir ?? this.config.metadataDir ?? '.jeeves-metadata';
+        const stateDir = this.config.stateDir ?? '.jeeves-metadata';
         this.issuesManager = new IssuesManager(stateDir, logger);
         this.valuesManager = new ValuesManager(stateDir, logger);
+        this.enrichmentStore = new EnrichmentStore(stateDir);
+        const enrichmentStore = this.enrichmentStore;
+        this.contentHashCache = new ContentHashCache();
+        const contentHashCache = this.contentHashCache;
         const processor = this.factories.createDocumentProcessor({
             config: processorConfig,
             embeddingProvider,
@@ -7017,8 +7449,10 @@ class JeevesWatcher {
             compiledRules,
             logger,
             templateEngine,
+            enrichmentStore,
             issuesManager: this.issuesManager,
             valuesManager: this.valuesManager,
+            contentHashCache,
         });
         this.processor = processor;
         this.queue = this.factories.createEventQueue({
@@ -7026,7 +7460,7 @@ class JeevesWatcher {
             concurrency: this.config.embedding.concurrency ?? 5,
             rateLimitPerMinute: this.config.embedding.rateLimitPerMinute,
         });
-        const { watcher, gitignoreFilter } = createWatcher(this.config, this.factories, this.queue, processor, logger, this.runtimeOptions, this.initialScanTracker);
+        const { watcher, gitignoreFilter } = createWatcher(this.config, this.factories, this.queue, processor, logger, this.runtimeOptions, this.initialScanTracker, contentHashCache);
         this.watcher = watcher;
         this.gitignoreFilter = gitignoreFilter;
         this.server = await this.startApiServer();
@@ -7078,6 +7512,7 @@ class JeevesWatcher {
             version: this.version,
             initialScanTracker: this.initialScanTracker,
             fileSystemWatcher: this.watcher,
+            enrichmentStore: this.enrichmentStore,
         });
         await server.listen({
             host: this.config.api?.host ?? '127.0.0.1',