@karmaniverous/jeeves-watcher 0.1.0 → 0.2.1

package/dist/index.iife.js

@@ -1,4 +1,4 @@
-(function (exports, Fastify, node_crypto, promises, node_path, picomatch, chokidar, Ajv, cosmiconfig, googleGenai, pino, textsplitters, cheerio, yaml, mammoth, uuid, addFormats, jsClientRest) {
+(function (exports, Fastify, promises, node_path, picomatch, radash, node_crypto, cosmiconfig, zod, jsonmap, googleGenai, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest, chokidar) {
     'use strict';
 
     function _interopNamespaceDefault(e) {
@@ -20,73 +20,6 @@
 
     var cheerio__namespace = /*#__PURE__*/_interopNamespaceDefault(cheerio);
 
-    /**
-     * Normalise a file path for deterministic mapping: lowercase, forward slashes, strip leading drive letter colon.
-     *
-     * @param filePath - The original file path.
-     * @returns The normalised path string.
-     */
-    function normalisePath$1(filePath) {
-        return filePath
-            .replace(/\\/g, '/')
-            .replace(/^([A-Za-z]):/, (_m, letter) => letter.toLowerCase())
-            .toLowerCase();
-    }
-    /**
-     * 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 = normalisePath$1(filePath);
-        const hash = node_crypto.createHash('sha256').update(normalised, 'utf8').digest('hex');
-        return node_path.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 promises.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 promises.mkdir(node_path.dirname(dest), { recursive: true });
-        await promises.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 promises.rm(metadataPath(filePath, metadataDir));
-        }
-        catch {
-            // Ignore if file doesn't exist.
-        }
-    }
-
     /**
      * Best-effort base directory inference for a glob pattern.
      *
@@ -160,233 +93,536 @@
     }
 
     /**
-     * Create the Fastify API server with all routes registered.
+     * @module processAllFiles
      *
-     * The returned instance is not yet listening — call `server.listen()` to start.
+     * Shared helper for processing all files matching configured globs.
+     */
+    /**
+     * Process all files from globs using the specified processor method.
      *
-     * @param options - The server options.
-     * @returns A configured Fastify instance.
+     * @param watchPaths - The glob patterns to match.
+     * @param ignoredPaths - The glob patterns to ignore.
+     * @param processor - The document processor instance.
+     * @param method - The processor method to call ('processFile' or 'processRulesUpdate').
+     * @returns The number of files processed.
      */
-    function createApiServer(options) {
-        const { processor, vectorStore, embeddingProvider, logger } = options;
-        const app = Fastify({ logger: false });
-        app.get('/status', () => ({
-            status: 'ok',
-            uptime: process.uptime(),
-        }));
-        app.post('/metadata', async (request, reply) => {
+    async function processAllFiles(watchPaths, ignoredPaths, processor, method) {
+        const files = await listFilesFromGlobs(watchPaths, ignoredPaths);
+        for (const file of files) {
+            // Sequential on purpose to avoid surprising load.
+            // Queue integration can come later.
+            await processor[method](file);
+        }
+        return files.length;
+    }
+
+    /**
+     * @module api/handlers/configReindex
+     * Fastify route handler for POST /config-reindex. Triggers an async reindex job scoped to rules or full processing.
+     */
+    /**
+     * Create handler for POST /config-reindex.
+     *
+     * @param deps - Route dependencies.
+     */
+    function createConfigReindexHandler(deps) {
+        return async (request, reply) => {
             try {
-                const { path, metadata } = request.body;
-                await processor.processMetadataUpdate(path, metadata);
-                return { ok: true };
+                const scope = request.body.scope ?? 'rules';
+                // Return immediately and run async
+                void (async () => {
+                    try {
+                        if (scope === 'rules') {
+                            const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processRulesUpdate');
+                            deps.logger.info({ scope, filesProcessed: count }, 'Config reindex (rules) completed');
+                        }
+                        else {
+                            const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processFile');
+                            deps.logger.info({ scope, filesProcessed: count }, 'Config reindex (full) completed');
+                        }
+                    }
+                    catch (error) {
+                        deps.logger.error({ error, scope }, 'Config reindex failed');
+                    }
+                })();
+                return await reply.status(200).send({ status: 'started', scope });
             }
             catch (error) {
-                logger.error({ error }, 'Metadata update failed');
-                return reply.status(500).send({ error: 'Internal server error' });
+                deps.logger.error({ error }, 'Config reindex request failed');
+                return await reply.status(500).send({ error: 'Internal server error' });
             }
-        });
-        app.post('/search', async (request, reply) => {
+        };
+    }
+
+    /**
+     * @module api/handlers/metadata
+     * Fastify route handler for POST /metadata. Performs enrichment metadata updates via the document processor.
+     */
+    /**
+     * Create handler for POST /metadata.
+     *
+     * @param deps - Route dependencies.
+     */
+    function createMetadataHandler(deps) {
+        return async (request, reply) => {
             try {
-                const { query, limit = 10 } = request.body;
-                const vectors = await embeddingProvider.embed([query]);
-                const results = await vectorStore.search(vectors[0], limit);
-                return results;
+                const { path, metadata } = request.body;
+                await deps.processor.processMetadataUpdate(path, metadata);
+                return { ok: true };
             }
             catch (error) {
-                logger.error({ error }, 'Search failed');
+                deps.logger.error({ error }, 'Metadata update failed');
                 return reply.status(500).send({ error: 'Internal server error' });
             }
-        });
-        app.post('/reindex', async (_request, reply) => {
-            try {
-                const files = await listFilesFromGlobs(options.config.watch.paths, options.config.watch.ignored);
-                for (const file of files) {
-                    // Sequential on purpose to avoid surprising load.
-                    // Queue integration can come later.
-                    await processor.processFile(file);
-                }
-                return await reply
-                    .status(200)
-                    .send({ ok: true, filesIndexed: files.length });
-            }
-            catch (error) {
-                logger.error({ error }, 'Reindex failed');
-                return await reply.status(500).send({ error: 'Internal server error' });
-            }
-        });
-        app.post('/rebuild-metadata', async (_request, reply) => {
+        };
+    }
+
+    /**
+     * @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 = node_crypto.createHash('sha256').update(normalised, 'utf8').digest('hex');
+        return node_path.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 promises.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 promises.mkdir(node_path.dirname(dest), { recursive: true });
+        await promises.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 promises.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 api/handlers/rebuildMetadata
+     * Fastify route handler for POST /rebuild-metadata. Recreates enrichment metadata files from vector store payloads.
+     */
+    /**
+     * Create handler for POST /rebuild-metadata.
+     *
+     * @param deps - Route dependencies.
+     */
+    function createRebuildMetadataHandler(deps) {
+        return async (_request, reply) => {
             try {
-                const metadataDir = options.config.metadataDir ?? '.jeeves-metadata';
-                for await (const point of vectorStore.scroll()) {
+                const metadataDir = deps.config.metadataDir ?? '.jeeves-metadata';
+                const systemKeys = [...SYSTEM_METADATA_KEYS];
+                for await (const point of deps.vectorStore.scroll()) {
                     const payload = point.payload;
                     const filePath = payload['file_path'];
                     if (typeof filePath !== 'string' || filePath.length === 0)
                         continue;
                     // Persist only enrichment-ish fields, not chunking/index fields.
-                    const rest = { ...payload };
-                    delete rest.file_path;
-                    delete rest.chunk_index;
-                    delete rest.total_chunks;
-                    delete rest.content_hash;
-                    delete rest.chunk_text;
-                    await writeMetadata(filePath, metadataDir, rest);
+                    const enrichment = radash.omit(payload, systemKeys);
+                    await writeMetadata(filePath, metadataDir, enrichment);
                 }
                 return await reply.status(200).send({ ok: true });
             }
             catch (error) {
-                logger.error({ error }, 'Rebuild metadata failed');
+                deps.logger.error({ error }, 'Rebuild metadata failed');
                 return await reply.status(500).send({ error: 'Internal server error' });
             }
-        });
-        app.post('/config-reindex', async (request, reply) => {
+        };
+    }
+
+    /**
+     * @module api/handlers/reindex
+     * Fastify route handler for POST /reindex. Reprocesses all watched files through the processor.
+     */
+    /**
+     * Create handler for POST /reindex.
+     *
+     * @param deps - Route dependencies.
+     */
+    function createReindexHandler(deps) {
+        return async (_request, reply) => {
             try {
-                const scope = request.body.scope ?? 'rules';
-                // Return immediately and run async
-                void (async () => {
-                    try {
-                        if (scope === 'rules') {
-                            // Re-apply inference rules to all files, update Qdrant payloads (no re-embedding)
-                            const files = await listFilesFromGlobs(options.config.watch.paths, options.config.watch.ignored);
-                            for (const file of files) {
-                                // Use the new processRulesUpdate method
-                                await processor.processRulesUpdate(file);
-                            }
-                            logger.info({ scope, filesProcessed: files.length }, 'Config reindex (rules) completed');
-                        }
-                        else {
-                            // Full reindex: re-extract, re-embed, re-upsert
-                            const files = await listFilesFromGlobs(options.config.watch.paths, options.config.watch.ignored);
-                            for (const file of files) {
-                                await processor.processFile(file);
-                            }
-                            logger.info({ scope, filesProcessed: files.length }, 'Config reindex (full) completed');
-                        }
-                    }
-                    catch (error) {
-                        logger.error({ error, scope }, 'Config reindex failed');
-                    }
-                })();
-                return await reply.status(200).send({ status: 'started', scope });
+                const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processFile');
+                return await reply.status(200).send({ ok: true, filesIndexed: count });
             }
             catch (error) {
-                logger.error({ error }, 'Config reindex request failed');
+                deps.logger.error({ error }, 'Reindex failed');
                 return await reply.status(500).send({ error: 'Internal server error' });
             }
+        };
+    }
+
+    /**
+     * @module api/handlers/search
+     * Fastify route handler for POST /search. Embeds a query and performs vector store similarity search.
+     */
+    /**
+     * Create handler for POST /search.
+     *
+     * @param deps - Route dependencies.
+     */
+    function createSearchHandler(deps) {
+        return async (request, reply) => {
+            try {
+                const { query, limit = 10 } = request.body;
+                const vectors = await deps.embeddingProvider.embed([query]);
+                const results = await deps.vectorStore.search(vectors[0], limit);
+                return results;
+            }
+            catch (error) {
+                deps.logger.error({ error }, 'Search failed');
+                return reply.status(500).send({ error: 'Internal server error' });
+            }
+        };
+    }
+
+    /**
+     * @module api/handlers/status
+     * Fastify route handler for GET /status. Pure handler: returns process uptime and health.
+     */
+    /**
+     * Create handler for GET /status.
+     */
+    function createStatusHandler() {
+        return () => ({
+            status: 'ok',
+            uptime: process.uptime(),
         });
+    }
+
+    /**
+     * Create the Fastify API server with all routes registered.
+     *
+     * The returned instance is not yet listening — call `server.listen()` to start.
+     *
+     * @param options - The server options.
+     * @returns A configured Fastify instance.
+     */
+    function createApiServer(options) {
+        const { processor, vectorStore, embeddingProvider, logger, config } = options;
+        const app = Fastify({ logger: false });
+        app.get('/status', createStatusHandler());
+        app.post('/metadata', createMetadataHandler({ processor, logger }));
+        app.post('/search', createSearchHandler({ embeddingProvider, vectorStore, logger }));
+        app.post('/reindex', createReindexHandler({ config, processor, logger }));
+        app.post('/rebuild-metadata', createRebuildMetadataHandler({ config, vectorStore, logger }));
+        app.post('/config-reindex', createConfigReindexHandler({ config, processor, logger }));
         return app;
     }
 
-    const MODULE_NAME = 'jeeves-watcher';
-    /** JSON Schema for validating jeeves-watcher configuration. */
-    const configSchema = {
-        type: 'object',
-        required: ['watch', 'embedding', 'vectorStore'],
-        properties: {
-            watch: {
-                type: 'object',
-                required: ['paths'],
-                properties: {
-                    paths: { type: 'array', items: { type: 'string' }, minItems: 1 },
-                    ignored: { type: 'array', items: { type: 'string' } },
-                    pollIntervalMs: { type: 'number' },
-                    usePolling: { type: 'boolean' },
-                    debounceMs: { type: 'number' },
-                    stabilityThresholdMs: { type: 'number' },
-                },
-                additionalProperties: false,
-            },
-            configWatch: {
-                type: 'object',
-                properties: {
-                    enabled: { type: 'boolean' },
-                    debounceMs: { type: 'number' },
-                },
-                additionalProperties: false,
-            },
-            embedding: {
-                type: 'object',
-                required: ['provider', 'model'],
-                properties: {
-                    provider: { type: 'string' },
-                    model: { type: 'string' },
-                    chunkSize: { type: 'number' },
-                    chunkOverlap: { type: 'number' },
-                    dimensions: { type: 'number' },
-                    apiKey: { type: 'string' },
-                    rateLimitPerMinute: { type: 'number' },
-                    concurrency: { type: 'number' },
-                },
-                additionalProperties: false,
-            },
-            vectorStore: {
-                type: 'object',
-                required: ['url', 'collectionName'],
-                properties: {
-                    url: { type: 'string' },
-                    collectionName: { type: 'string' },
-                    apiKey: { type: 'string' },
-                },
-                additionalProperties: false,
-            },
-            metadataDir: { type: 'string' },
-            api: {
-                type: 'object',
-                properties: {
-                    host: { type: 'string' },
-                    port: { type: 'number' },
-                },
-                additionalProperties: false,
-            },
-            extractors: { type: 'object' },
-            inferenceRules: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    required: ['match', 'set'],
-                    properties: {
-                        match: { type: 'object' },
-                        set: { type: 'object' },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            logging: {
-                type: 'object',
-                properties: {
-                    level: { type: 'string' },
-                    file: { type: 'string' },
-                },
-                additionalProperties: false,
-            },
-            shutdownTimeoutMs: { type: 'number' },
-        },
-        additionalProperties: false,
-    };
-    const ajv = new Ajv({ allErrors: true });
-    const validate = ajv.compile(configSchema);
-    /** Default values for optional configuration fields. */
-    const DEFAULTS = {
-        configWatch: { enabled: true, debounceMs: 1000 },
+    /**
+     * @module config/defaults
+     * Default configuration values for jeeves-watcher. Pure data export, no I/O or side effects.
+     */
+    /** Default root-level config values. */
+    const ROOT_DEFAULTS = {
         metadataDir: '.jeeves-watcher',
-        api: { host: '127.0.0.1', port: 3100 },
-        logging: { level: 'info' },
         shutdownTimeoutMs: 10000,
     };
-    /** Default values for watch configuration. */
+    /** Default configWatch values. */
+    const CONFIG_WATCH_DEFAULTS = {
+        enabled: true,
+        debounceMs: 1000,
+    };
+    /** Default API values. */
+    const API_DEFAULTS = {
+        host: '127.0.0.1',
+        port: 3456,
+    };
+    /** Default logging values. */
+    const LOGGING_DEFAULTS = {
+        level: 'info',
+    };
+    /** Default watch configuration. */
     const WATCH_DEFAULTS = {
         debounceMs: 300,
         stabilityThresholdMs: 500,
         usePolling: false,
         pollIntervalMs: 1000,
     };
-    /** Default values for embedding configuration. */
+    /** Default embedding configuration. */
     const EMBEDDING_DEFAULTS = {
         chunkSize: 1000,
         chunkOverlap: 200,
-        dimensions: 768,
+        dimensions: 3072,
         rateLimitPerMinute: 300,
         concurrency: 5,
     };
+
+    /**
+     * Watch configuration for file system monitoring.
+     */
+    const watchConfigSchema = zod.z.object({
+        /** Glob patterns to watch. */
+        paths: zod.z
+            .array(zod.z.string())
+            .min(1)
+            .describe('Glob patterns for files to watch (e.g., "**/*.md"). At least one required.'),
+        /** Glob patterns to ignore. */
+        ignored: zod.z
+            .array(zod.z.string())
+            .optional()
+            .describe('Glob patterns to exclude from watching (e.g., "**/node_modules/**").'),
+        /** Polling interval in milliseconds. */
+        pollIntervalMs: zod.z
+            .number()
+            .optional()
+            .describe('Polling interval in milliseconds when usePolling is enabled.'),
+        /** Whether to use polling instead of native watchers. */
+        usePolling: zod.z
+            .boolean()
+            .optional()
+            .describe('Use polling instead of native file system events (for network drives).'),
+        /** Debounce delay in milliseconds for file change events. */
+        debounceMs: zod.z
+            .number()
+            .optional()
+            .describe('Debounce delay in milliseconds for file change events.'),
+        /** Time in milliseconds a file must be stable before processing. */
+        stabilityThresholdMs: zod.z
+            .number()
+            .optional()
+            .describe('Time in milliseconds a file must remain unchanged before processing.'),
+    });
+    /**
+     * Configuration watch settings.
+     */
+    const configWatchConfigSchema = zod.z.object({
+        /** Whether config file watching is enabled. */
+        enabled: zod.z
+            .boolean()
+            .optional()
+            .describe('Enable automatic reloading when config file changes.'),
+        /** Debounce delay in milliseconds for config change events. */
+        debounceMs: zod.z
+            .number()
+            .optional()
+            .describe('Debounce delay in milliseconds for config file change detection.'),
+    });
+    /**
+     * Embedding model configuration.
+     */
+    const embeddingConfigSchema = zod.z.object({
+        /** The embedding model provider. */
+        provider: zod.z
+            .string()
+            .default('gemini')
+            .describe('Embedding provider name (e.g., "gemini", "openai").'),
+        /** The embedding model name. */
+        model: zod.z
+            .string()
+            .default('gemini-embedding-001')
+            .describe('Embedding model identifier (e.g., "gemini-embedding-001", "text-embedding-3-small").'),
+        /** Maximum tokens per chunk for splitting. */
+        chunkSize: zod.z
+            .number()
+            .optional()
+            .describe('Maximum chunk size in characters for text splitting.'),
+        /** Overlap between chunks in tokens. */
+        chunkOverlap: zod.z
+            .number()
+            .optional()
+            .describe('Character overlap between consecutive chunks.'),
+        /** Embedding vector dimensions. */
+        dimensions: zod.z
+            .number()
+            .optional()
+            .describe('Embedding vector dimensions (must match model output).'),
+        /** API key for the embedding provider. */
+        apiKey: zod.z
+            .string()
+            .optional()
+            .describe('API key for embedding provider (supports ${ENV_VAR} substitution).'),
+        /** Maximum embedding requests per minute. */
+        rateLimitPerMinute: zod.z
+            .number()
+            .optional()
+            .describe('Maximum embedding API requests per minute (rate limiting).'),
+        /** Maximum concurrent embedding requests. */
+        concurrency: zod.z
+            .number()
+            .optional()
+            .describe('Maximum concurrent embedding requests.'),
+    });
+    /**
+     * Vector store configuration for Qdrant.
+     */
+    const vectorStoreConfigSchema = zod.z.object({
+        /** Qdrant server URL. */
+        url: zod.z
+            .string()
+            .describe('Qdrant server URL (e.g., "http://localhost:6333").'),
+        /** Qdrant collection name. */
+        collectionName: zod.z
+            .string()
+            .describe('Qdrant collection name for vector storage.'),
+        /** Qdrant API key. */
+        apiKey: zod.z
+            .string()
+            .optional()
+            .describe('Qdrant API key for authentication (supports ${ENV_VAR} substitution).'),
+    });
+    /**
+     * API server configuration.
+     */
+    const apiConfigSchema = zod.z.object({
+        /** Host to bind to. */
+        host: zod.z
+            .string()
+            .optional()
+            .describe('Host address for API server (e.g., "127.0.0.1", "0.0.0.0").'),
+        /** Port to listen on. */
+        port: zod.z.number().optional().describe('Port for API server (e.g., 3456).'),
+    });
+    /**
+     * Logging configuration.
+     */
+    const loggingConfigSchema = zod.z.object({
+        /** Log level. */
+        level: zod.z
+            .string()
+            .optional()
+            .describe('Logging level (trace, debug, info, warn, error, fatal).'),
+        /** Log file path. */
+        file: zod.z
+            .string()
+            .optional()
+            .describe('Path to log file (logs to stdout if omitted).'),
+    });
+    /**
+     * An inference rule that enriches document metadata.
+     */
+    const inferenceRuleSchema = zod.z.object({
+        /** JSON Schema object to match against document metadata. */
+        match: zod.z
+            .record(zod.z.string(), zod.z.unknown())
+            .describe('JSON Schema object to match against file attributes.'),
+        /** Metadata fields to set when the rule matches. */
+        set: zod.z
+            .record(zod.z.string(), zod.z.unknown())
+            .describe('Metadata fields to set when match succeeds.'),
+        /** JsonMap transformation (inline or reference to named map). */
+        map: zod.z
+            .union([jsonmap.jsonMapMapSchema, zod.z.string()])
+            .optional()
+            .describe('JsonMap transformation (inline definition or named map reference).'),
+    });
+    /**
+     * Top-level configuration for jeeves-watcher.
+     */
+    const jeevesWatcherConfigSchema = zod.z.object({
+        /** File system watch configuration. */
+        watch: watchConfigSchema.describe('File system watch configuration.'),
+        /** Configuration file watch settings. */
+        configWatch: configWatchConfigSchema
+            .optional()
+            .describe('Configuration file watch settings.'),
+        /** Embedding model configuration. */
+        embedding: embeddingConfigSchema.describe('Embedding model configuration.'),
+        /** Vector store configuration. */
+        vectorStore: vectorStoreConfigSchema.describe('Qdrant vector store configuration.'),
+        /** Directory for persisted metadata. */
+        metadataDir: zod.z
+            .string()
+            .optional()
+            .describe('Directory for persisted metadata sidecar files.'),
+        /** API server configuration. */
+        api: apiConfigSchema.optional().describe('API server configuration.'),
+        /** Extractor configurations keyed by name. */
+        extractors: zod.z
+            .record(zod.z.string(), zod.z.unknown())
+            .optional()
+            .describe('Extractor configurations keyed by name.'),
+        /** Rules for inferring metadata from document properties. */
+        inferenceRules: zod.z
+            .array(inferenceRuleSchema)
+            .optional()
+            .describe('Rules for inferring metadata from file attributes.'),
+        /** Reusable named JsonMap transformations. */
+        maps: zod.z
+            .record(zod.z.string(), jsonmap.jsonMapMapSchema)
+            .optional()
+            .describe('Reusable named JsonMap transformations.'),
+        /** Logging configuration. */
+        logging: loggingConfigSchema.optional().describe('Logging configuration.'),
+        /** Timeout in milliseconds for graceful shutdown. */
+        shutdownTimeoutMs: zod.z
+            .number()
+            .optional()
+            .describe('Timeout in milliseconds for graceful shutdown.'),
+    });
+
+    const MODULE_NAME = 'jeeves-watcher';
     /**
      * Merge sensible defaults into a loaded configuration.
      *
@@ -395,13 +631,13 @@
      */
     function applyDefaults(raw) {
         return {
-            ...DEFAULTS,
+            ...ROOT_DEFAULTS,
             ...raw,
             watch: { ...WATCH_DEFAULTS, ...raw.watch },
-            configWatch: { ...DEFAULTS.configWatch, ...raw.configWatch },
+            configWatch: { ...CONFIG_WATCH_DEFAULTS, ...raw.configWatch },
             embedding: { ...EMBEDDING_DEFAULTS, ...raw.embedding },
-            api: { ...DEFAULTS.api, ...raw.api },
-            logging: { ...DEFAULTS.logging, ...raw.logging },
+            api: { ...API_DEFAULTS, ...raw.api },
+            logging: { ...LOGGING_DEFAULTS, ...raw.logging },
         };
     }
     /**
@@ -419,21 +655,114 @@
         if (!result || result.isEmpty) {
             throw new Error('No jeeves-watcher configuration found. Create a .jeeves-watcherrc or jeeves-watcher.config.{js,ts,json,yaml} file.');
         }
-        const raw = result.config;
-        if (!validate(raw)) {
-            const errors = validate.errors
-                ?.map((e) => {
-                const instancePath = 'instancePath' in e
-                    ? e.instancePath
-                    : undefined;
-                return `${instancePath ?? '/'}: ${e.message ?? 'unknown error'}`;
-            })
-                .join('; ');
-            throw new Error(`Invalid jeeves-watcher configuration: ${errors ?? 'unknown error'}`);
+        try {
+            const validated = jeevesWatcherConfigSchema.parse(result.config);
+            return applyDefaults(validated);
+        }
+        catch (error) {
+            if (error instanceof zod.ZodError) {
+                const errors = error.issues
+                    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                    .join('; ');
+                throw new Error(`Invalid jeeves-watcher configuration: ${errors}`);
+            }
+            throw error;
         }
-        return applyDefaults(raw);
     }
 
+    /**
+     * @module util/logger
+     * Logger fallback helper. Provides a unified warn interface that delegates to pino or console.
+     */
+    /**
+     * Return a minimal logger that delegates to pino if available, otherwise console.
+     *
+     * @param logger - Optional pino logger instance.
+     * @returns A minimal logger.
+     */
+    function getLogger(logger) {
+        if (logger)
+            return logger;
+        return {
+            warn(obj, msg) {
+                if (msg) {
+                    console.warn(obj, msg);
+                }
+                else {
+                    console.warn(obj);
+                }
+            },
+        };
+    }
+
+    /**
+     * @module util/retry
+     * Small async retry helper with exponential backoff. Side effects: sleeps between attempts; can invoke onRetry callback for logging.
+     */
+    function sleep(ms, signal) {
+        if (ms <= 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                cleanup();
+                reject(new Error('Retry sleep aborted'));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                if (signal)
+                    signal.removeEventListener('abort', onAbort);
+            };
+            if (signal) {
+                if (signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+    }
+    function computeDelayMs(attempt, baseDelayMs, maxDelayMs, jitter = 0) {
+        const exp = Math.max(0, attempt - 1);
+        const raw = Math.min(maxDelayMs, baseDelayMs * 2 ** exp);
+        const factor = jitter > 0 ? 1 + Math.random() * jitter : 1;
+        return Math.round(raw * factor);
+    }
+    /**
+     * Retry an async operation using exponential backoff.
+     *
+     * @param fn - Operation to execute.
+     * @param options - Retry policy.
+     * @returns The operation result.
+     */
+    async function retry(fn, options) {
+        const attempts = Math.max(1, options.attempts);
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                return await fn(attempt);
+            }
+            catch (error) {
+                lastError = error;
+                const isLast = attempt >= attempts;
+                if (isLast)
+                    break;
+                const delayMs = computeDelayMs(attempt, options.baseDelayMs, options.maxDelayMs, options.jitter);
+                options.onRetry?.({ attempt, attempts, delayMs, error });
+                await sleep(delayMs, options.signal);
+            }
+        }
+        throw lastError;
+    }
+
+    /**
+     * @module embedding
+     *
+     * Embedding provider abstractions and registry-backed factory.
+     */
     /**
      * Create a mock embedding provider that generates deterministic vectors from content hashes.
      *
@@ -461,14 +790,16 @@
      * Create a Gemini embedding provider using the Google Generative AI SDK.
      *
      * @param config - The embedding configuration.
+     * @param logger - Optional pino logger for retry warnings.
      * @returns A Gemini {@link EmbeddingProvider}.
      * @throws If the API key is missing.
      */
-    function createGeminiProvider(config) {
+    function createGeminiProvider(config, logger) {
         if (!config.apiKey) {
             throw new Error('Gemini embedding provider requires config.embedding.apiKey');
         }
         const dimensions = config.dimensions ?? 3072;
+        const log = getLogger(logger);
         const embedder = new googleGenai.GoogleGenerativeAIEmbeddings({
             apiKey: config.apiKey,
             model: config.model,
@@ -476,8 +807,27 @@
         return {
             dimensions,
             async embed(texts) {
-                // embedDocuments returns vectors for multiple texts
-                const vectors = await embedder.embedDocuments(texts);
+                const vectors = await retry(async (attempt) => {
+                    if (attempt > 1) {
+                        log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
+                    }
+                    // embedDocuments returns vectors for multiple texts
+                    return embedder.embedDocuments(texts);
+                }, {
+                    attempts: 5,
+                    baseDelayMs: 500,
+                    maxDelayMs: 10_000,
+                    jitter: 0.2,
+                    onRetry: ({ attempt, delayMs, error }) => {
+                        log.warn({
+                            attempt,
+                            delayMs,
+                            provider: 'gemini',
+                            model: config.model,
+                            error,
+                        }, 'Embedding call failed; will retry');
+                    },
+                });
                 // Validate dimensions
                 for (const vector of vectors) {
                     if (vector.length !== dimensions) {
@@ -488,25 +838,36 @@
             },
         };
     }
+    function createMockFromConfig(config) {
+        const dimensions = config.dimensions ?? 768;
+        return createMockProvider(dimensions);
+    }
+    const embeddingProviderRegistry = new Map([
+        ['mock', createMockFromConfig],
+        ['gemini', createGeminiProvider],
+    ]);
     /**
      * Create an embedding provider based on the given configuration.
      *
+     * Each provider is responsible for its own default dimensions.
+     *
      * @param config - The embedding configuration.
+     * @param logger - Optional pino logger for retry warnings.
      * @returns An {@link EmbeddingProvider} instance.
      * @throws If the configured provider is not supported.
      */
-    function createEmbeddingProvider(config) {
-        const dimensions = config.dimensions ?? 768;
-        switch (config.provider) {
-            case 'mock':
-                return createMockProvider(dimensions);
-            case 'gemini':
-                return createGeminiProvider(config);
-            default:
-                throw new Error(`Unsupported embedding provider: ${config.provider}`);
+    function createEmbeddingProvider(config, logger) {
+        const factory = embeddingProviderRegistry.get(config.provider);
+        if (!factory) {
+            throw new Error(`Unsupported embedding provider: ${config.provider}`);
         }
+        return factory(config, logger);
     }
 
+    /**
+     * @module logger
+     * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
+     */
     /**
      * Create a pino logger instance.
      *
@@ -525,6 +886,45 @@
         return pino({ level });
     }
 
+    /**
+     * @module hash
+     * Provides SHA-256 content hashing. Pure function: given text string, returns hex digest. No I/O or side effects.
+     */
+    /**
+     * Compute a SHA-256 hex digest of the given text.
+     *
+     * @param text - The input text to hash.
+     * @returns The hex-encoded SHA-256 hash.
+     */
+    function contentHash(text) {
+        return node_crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+    }
+
+    /**
+     * @module pointId
+     * Generates deterministic UUIDv5 point IDs for file paths and chunk indices. Pure function: normalizes paths, returns stable IDs. No I/O.
+     */
+    /** Namespace UUID for jeeves-watcher point IDs. */
+    const NAMESPACE = '6a6f686e-6761-4c74-ad6a-656576657321';
+    /**
+     * Generate a deterministic UUID v5 point ID for a file (and optional chunk index).
+     *
+     * @param filePath - The file path.
+     * @param chunkIndex - Optional chunk index within the file.
+     * @returns A deterministic UUID v5 string.
+     */
+    function pointId(filePath, chunkIndex) {
+        const key = chunkIndex !== undefined
+            ? `${normalizePath(filePath)}#${String(chunkIndex)}`
+            : normalizePath(filePath);
+        return uuid.v5(key, NAMESPACE);
+    }
+
+    /**
+     * @module extractors
+     *
+     * Text extraction registry for supported file formats.
+     */
     /**
      * Extract YAML frontmatter from a Markdown document.
      *
@@ -570,6 +970,55 @@
         }
         return JSON.stringify(obj);
     }
+    async function extractMarkdown(filePath) {
+        const raw = await promises.readFile(filePath, 'utf8');
+        const { frontmatter, body } = extractMarkdownFrontmatter(raw);
+        return { text: body, frontmatter };
+    }
+    async function extractPlaintext(filePath) {
+        const raw = await promises.readFile(filePath, 'utf8');
+        return { text: raw };
+    }
+    async function extractJson(filePath) {
+        const raw = await promises.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const json = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+        return { text: extractJsonText(parsed), json };
+    }
+    async function extractPdf(filePath) {
+        const buffer = await promises.readFile(filePath);
+        const uint8Array = new Uint8Array(buffer);
+        const { extractText: extractPdfText } = await import('unpdf');
+        const { text } = await extractPdfText(uint8Array);
+        // unpdf returns an array of strings (one per page)
+        const content = Array.isArray(text) ? text.join('\n\n') : text;
+        return { text: content };
+    }
+    async function extractDocx(filePath) {
+        const buffer = await promises.readFile(filePath);
+        const result = await mammoth.extractRawText({ buffer });
+        return { text: result.value };
+    }
+    async function extractHtml(filePath) {
+        const raw = await promises.readFile(filePath, 'utf8');
+        const $ = cheerio__namespace.load(raw);
+        $('script, style').remove();
+        const text = $('body').text().trim() || $.text().trim();
+        return { text };
+    }
+    const extractorRegistry = new Map([
+        ['.md', extractMarkdown],
+        ['.markdown', extractMarkdown],
+        ['.txt', extractPlaintext],
+        ['.text', extractPlaintext],
+        ['.json', extractJson],
+        ['.pdf', extractPdf],
+        ['.docx', extractDocx],
+        ['.html', extractHtml],
+        ['.htm', extractHtml],
+    ]);
     /**
      * Extract text from a file based on extension.
      *
@@ -578,87 +1027,132 @@
      * @returns Extracted text and optional structured data.
      */
     async function extractText(filePath, extension) {
-        const ext = extension.toLowerCase();
-        if (ext === '.md' || ext === '.markdown') {
-            const raw = await promises.readFile(filePath, 'utf8');
-            const { frontmatter, body } = extractMarkdownFrontmatter(raw);
-            return { text: body, frontmatter };
-        }
-        if (ext === '.txt' || ext === '.text') {
-            const raw = await promises.readFile(filePath, 'utf8');
-            return { text: raw };
-        }
-        if (ext === '.json') {
-            const raw = await promises.readFile(filePath, 'utf8');
-            const parsed = JSON.parse(raw);
-            const json = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-                ? parsed
-                : undefined;
-            return { text: extractJsonText(parsed), json };
-        }
-        if (ext === '.pdf') {
-            const buffer = await promises.readFile(filePath);
-            const uint8Array = new Uint8Array(buffer);
-            const { extractText: extractPdfText } = await import('unpdf');
-            const { text } = await extractPdfText(uint8Array);
-            // unpdf returns an array of strings (one per page)
-            const content = Array.isArray(text) ? text.join('\n\n') : text;
-            return { text: content };
-        }
-        if (ext === '.docx') {
-            const buffer = await promises.readFile(filePath);
-            const result = await mammoth.extractRawText({ buffer });
-            return { text: result.value };
-        }
-        if (ext === '.html' || ext === '.htm') {
-            const raw = await promises.readFile(filePath, 'utf8');
-            const $ = cheerio__namespace.load(raw);
-            // Remove script and style elements
-            $('script, style').remove();
-            // Extract text content
-            const text = $('body').text().trim() || $.text().trim();
-            return { text };
-        }
+        const extractor = extractorRegistry.get(extension.toLowerCase());
+        if (extractor)
+            return extractor(filePath);
         // Default: treat as plaintext.
-        const raw = await promises.readFile(filePath, 'utf8');
-        return { text: raw };
+        return extractPlaintext(filePath);
     }
 
     /**
-     * Compute a SHA-256 hex digest of the given text.
+     * @module rules/templates
+     * Resolves template variables (`${path.to.value}`) in rule `set` objects against file attributes.
+     */
+    /**
+     * Resolve `${template.vars}` in a value against the given attributes.
      *
-     * @param text - The input text to hash.
-     * @returns The hex-encoded SHA-256 hash.
+     * @param value - The value to resolve.
+     * @param attributes - The file attributes for variable lookup.
+     * @returns The resolved value.
      */
-    function contentHash(text) {
-        return node_crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+    function resolveTemplateVars(value, attributes) {
+        if (typeof value !== 'string')
+            return value;
+        return value.replace(/\$\{([^}]+)\}/g, (_match, varPath) => {
+            const current = radash.get(attributes, varPath);
+            if (current === null || current === undefined)
+                return '';
+            return typeof current === 'string' ? current : JSON.stringify(current);
+        });
+    }
+    /**
+     * Resolve all template variables in a `set` object.
+     *
+     * @param setObj - The key-value pairs to resolve.
+     * @param attributes - The file attributes for variable lookup.
+     * @returns The resolved key-value pairs.
+     */
+    function resolveSet(setObj, attributes) {
+        const result = {};
+        for (const [key, value] of Object.entries(setObj)) {
+            result[key] = resolveTemplateVars(value, attributes);
+        }
+        return result;
     }
 
-    /** Namespace UUID for jeeves-watcher point IDs. */
-    const NAMESPACE = '6a6f686e-6761-4c74-ad6a-656576657321';
     /**
-     * Normalise a file path for deterministic point ID generation.
+     * @module rules/apply
+     * Applies compiled inference rules to file attributes, producing merged metadata via template resolution and JsonMap transforms.
+     */
+    /**
+     * Create the lib object for JsonMap transformations.
      *
-     * @param filePath - The original file path.
-     * @returns The normalised path string.
+     * @returns The lib object.
      */
-    function normalisePath(filePath) {
-        return filePath.replace(/\\/g, '/').toLowerCase();
+    function createJsonMapLib() {
+        return {
+            split: (str, separator) => str.split(separator),
+            slice: (arr, start, end) => arr.slice(start, end),
+            join: (arr, separator) => arr.join(separator),
+            toLowerCase: (str) => str.toLowerCase(),
+            replace: (str, search, replacement) => str.replace(search, replacement),
+            get: (obj, path) => radash.get(obj, path),
+        };
     }
     /**
-     * Generate a deterministic UUID v5 point ID for a file (and optional chunk index).
+     * Apply compiled inference rules to file attributes, returning merged metadata.
      *
-     * @param filePath - The file path.
-     * @param chunkIndex - Optional chunk index within the file.
-     * @returns A deterministic UUID v5 string.
+     * Rules are evaluated in order; later rules override earlier ones.
+     * If a rule has a `map`, the JsonMap transformation is applied after `set` resolution,
+     * and map output overrides set output on conflict.
+     *
+     * @param compiledRules - The compiled rules to evaluate.
+     * @param attributes - The file attributes to match against.
+     * @param namedMaps - Optional record of named JsonMap definitions.
+     * @param logger - Optional logger for warnings (falls back to console.warn).
+     * @returns The merged metadata from all matching rules.
      */
-    function pointId(filePath, chunkIndex) {
-        const key = chunkIndex !== undefined
-            ? `${normalisePath(filePath)}#${String(chunkIndex)}`
-            : normalisePath(filePath);
-        return uuid.v5(key, NAMESPACE);
+    async function applyRules(compiledRules, attributes, namedMaps, logger) {
+        // JsonMap's type definitions expect a generic JsonMapLib shape with unary functions.
+        // Our helper functions accept multiple args, which JsonMap supports at runtime.
+        const lib = createJsonMapLib();
+        let merged = {};
+        const log = logger ?? console;
+        for (const { rule, validate } of compiledRules) {
+            if (validate(attributes)) {
+                // Apply set resolution
+                const setOutput = resolveSet(rule.set, attributes);
+                merged = { ...merged, ...setOutput };
+                // Apply map transformation if present
+                if (rule.map) {
+                    let mapDef;
+                    // Resolve map reference
+                    if (typeof rule.map === 'string') {
+                        mapDef = namedMaps?.[rule.map];
+                        if (!mapDef) {
+                            log.warn(`Map reference "${rule.map}" not found in named maps. Skipping map transformation.`);
+                            continue;
+                        }
+                    }
+                    else {
+                        mapDef = rule.map;
+                    }
+                    // Execute JsonMap transformation
+                    try {
+                        const jsonMap = new jsonmap.JsonMap(mapDef, lib);
+                        const mapOutput = await jsonMap.transform(attributes);
+                        if (mapOutput &&
+                            typeof mapOutput === 'object' &&
+                            !Array.isArray(mapOutput)) {
+                            merged = { ...merged, ...mapOutput };
+                        }
+                        else {
+                            log.warn(`JsonMap transformation did not return an object; skipping merge.`);
+                        }
+                    }
+                    catch (error) {
+                        log.warn(`JsonMap transformation failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+        }
+        return merged;
     }
 
+    /**
+     * @module rules/attributes
+     * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
+     */
     /**
      * Build {@link FileAttributes} from a file path and stat info.
      *
@@ -686,10 +1180,15 @@
             attrs.json = extractedJson;
         return attrs;
     }
+
+    /**
+     * @module rules/ajvSetup
+     * AJV instance factory with custom glob keyword for picomatch-based pattern matching in rule schemas.
+     */
     /**
-     * Create an ajv instance with a custom `glob` format for picomatch glob matching.
+     * Create an AJV instance with a custom `glob` format for picomatch glob matching.
      *
-     * @returns The configured ajv instance.
+     * @returns The configured AJV instance.
      */
     function createRuleAjv() {
         const ajv = new Ajv({ allErrors: true });
@@ -702,6 +1201,11 @@
         });
         return ajv;
     }
+
+    /**
+     * @module rules/compile
+     * Compiles inference rule definitions into executable AJV validators for efficient rule evaluation.
+     */
     /**
      * Compile an array of inference rules into executable validators.
      *
@@ -718,62 +1222,95 @@
             }),
         }));
     }
+
+    /**
+     * @module processor/buildMetadata
+     * Builds merged metadata from file content, inference rules, and enrichment. I/O: reads files, extracts text, loads enrichment .meta.json.
+     */
     /**
-     * Resolve `$\{template.vars\}` in a value against the given attributes.
+     * Build merged metadata for a file by applying inference rules and merging with enrichment metadata.
      *
-     * @param value - The value to resolve.
-     * @param attributes - The file attributes for variable lookup.
-     * @returns The resolved value.
+     * @param filePath - The file to process.
+     * @param compiledRules - The compiled inference rules.
+     * @param metadataDir - The metadata directory for enrichment files.
+     * @param maps - Optional named JsonMap definitions.
+     * @param logger - Optional logger for rule warnings.
+     * @returns The merged metadata and intermediate data.
      */
-    function resolveTemplateVars(value, attributes) {
-        if (typeof value !== 'string')
-            return value;
-        return value.replace(/\$\{([^}]+)\}/g, (_match, varPath) => {
-            const parts = varPath.split('.');
-            let current = attributes;
-            for (const part of parts) {
-                if (current === null || current === undefined)
-                    return '';
-                current = current[part];
-            }
-            if (current === null || current === undefined)
-                return '';
-            return typeof current === 'string' ? current : JSON.stringify(current);
-        });
+    async function buildMergedMetadata(filePath, compiledRules, metadataDir, maps, logger) {
+        const ext = node_path.extname(filePath);
+        const stats = await promises.stat(filePath);
+        // 1. Extract text and structured data
+        const extracted = await extractText(filePath, ext);
+        // 2. Build attributes + apply rules
+        const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
+        const inferred = await applyRules(compiledRules, attributes, maps, logger);
+        // 3. Read enrichment metadata (merge, enrichment wins)
+        const enrichment = await readMetadata(filePath, metadataDir);
+        const metadata = {
+            ...inferred,
+            ...(enrichment ?? {}),
+        };
+        return { inferred, enrichment, metadata, attributes, extracted };
     }
+
     /**
-     * Resolve all template variables in a `set` object.
+     * @module processor/chunkIds
+     * Generates chunk point IDs from file paths and chunk indices. Extracts chunk counts from Qdrant payloads. Pure functions, no I/O.
+     */
+    /**
+     * Generate an array of chunk IDs for a file.
      *
-     * @param setObj - The key-value pairs to resolve.
-     * @param attributes - The file attributes for variable lookup.
-     * @returns The resolved key-value pairs.
+     * @param filePath - The file path.
+     * @param totalChunks - The total number of chunks.
+     * @returns An array of point IDs for each chunk.
      */
-    function resolveSet(setObj, attributes) {
-        const result = {};
-        for (const [key, value] of Object.entries(setObj)) {
-            result[key] = resolveTemplateVars(value, attributes);
+    function chunkIds(filePath, totalChunks) {
+        const ids = [];
+        for (let i = 0; i < totalChunks; i++) {
+            ids.push(pointId(filePath, i));
         }
-        return result;
+        return ids;
     }
     /**
-     * Apply compiled inference rules to file attributes, returning merged metadata.
+     * Extract the total chunk count from a payload, with a fallback.
      *
-     * Rules are evaluated in order; later rules override earlier ones.
+     * @param payload - The Qdrant point payload (or null).
+     * @param fallback - The fallback value if total_chunks is missing or invalid.
+     * @returns The total chunk count.
+     */
+    function getChunkCount(payload, fallback = 1) {
+        if (!payload)
+            return fallback;
+        const count = payload['total_chunks'];
+        return typeof count === 'number' ? count : fallback;
+    }
+
+    /**
+     * @module processor/splitter
+     * Factory for LangChain text splitters. Returns MarkdownTextSplitter or RecursiveCharacterTextSplitter based on file extension. No I/O.
+     */
+    /**
+     * Create the appropriate text splitter for the given file extension.
      *
-     * @param compiledRules - The compiled rules to evaluate.
-     * @param attributes - The file attributes to match against.
-     * @returns The merged metadata from all matching rules.
+     * @param ext - File extension (including leading dot).
+     * @param chunkSize - Maximum chunk size in characters.
+     * @param chunkOverlap - Overlap between chunks in characters.
+     * @returns A text splitter instance.
      */
-    function applyRules(compiledRules, attributes) {
-        let merged = {};
-        for (const { rule, validate } of compiledRules) {
-            if (validate(attributes)) {
-                merged = { ...merged, ...resolveSet(rule.set, attributes) };
-            }
+    function createSplitter(ext, chunkSize, chunkOverlap) {
+        const lowerExt = ext.toLowerCase();
+        if (lowerExt === '.md' || lowerExt === '.markdown') {
+            return new textsplitters.MarkdownTextSplitter({ chunkSize, chunkOverlap });
         }
-        return merged;
+        return new textsplitters.RecursiveCharacterTextSplitter({ chunkSize, chunkOverlap });
     }
 
+    /**
+     * @module processor
+     *
+     * Core document processing pipeline. Handles extracting text, computing embeddings, syncing with vector store.
+     */
     /**
      * Core document processing pipeline.
      *
@@ -785,11 +1322,10 @@
         vectorStore;
         compiledRules;
         logger;
-        metadataDir;
         /**
          * Create a new DocumentProcessor.
          *
-         * @param config - The application configuration.
+         * @param config - The processor configuration.
          * @param embeddingProvider - The embedding provider.
          * @param vectorStore - The vector store client.
          * @param compiledRules - The compiled inference rules.
@@ -801,7 +1337,6 @@
             this.vectorStore = vectorStore;
             this.compiledRules = compiledRules;
             this.logger = logger;
-            this.metadataDir = config.metadataDir ?? '.jeeves-metadata';
         }
         /**
          * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
@@ -811,9 +1346,8 @@
         async processFile(filePath) {
             try {
                 const ext = node_path.extname(filePath);
-                const stats = await promises.stat(filePath);
-                // 1. Extract text
-                const extracted = await extractText(filePath, ext);
+                // 1. Build merged metadata + extract text
+                const { metadata, extracted } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
                 if (!extracted.text.trim()) {
                     this.logger.debug({ filePath }, 'Skipping empty file');
                     return;
@@ -826,26 +1360,15 @@
                     this.logger.debug({ filePath }, 'Content unchanged, skipping');
                     return;
                 }
-                const oldTotalChunks = typeof existingPayload?.['total_chunks'] === 'number'
-                    ? existingPayload['total_chunks']
-                    : 0;
-                // 3. Build attributes + apply rules → inferred metadata
-                const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-                const inferred = applyRules(this.compiledRules, attributes);
-                // 4. Read enrichment metadata (merge, enrichment wins)
-                const enrichment = await readMetadata(filePath, this.metadataDir);
-                const metadata = {
-                    ...inferred,
-                    ...(enrichment ?? {}),
-                };
-                // 5. Chunk text
-                const chunkSize = this.config.embedding.chunkSize ?? 1000;
-                const chunkOverlap = this.config.embedding.chunkOverlap ?? 200;
-                const splitter = this.createSplitter(ext, chunkSize, chunkOverlap);
+                const oldTotalChunks = getChunkCount(existingPayload);
+                // 3. Chunk text
+                const chunkSize = this.config.chunkSize ?? 1000;
+                const chunkOverlap = this.config.chunkOverlap ?? 200;
+                const splitter = createSplitter(ext, chunkSize, chunkOverlap);
                 const chunks = await splitter.splitText(extracted.text);
-                // 6. Embed all chunks
+                // 4. Embed all chunks
                 const vectors = await this.embeddingProvider.embed(chunks);
-                // 7. Upsert all chunk points
+                // 5. Upsert all chunk points
                 const points = chunks.map((chunk, i) => ({
                     id: pointId(filePath, i),
                     vector: vectors[i],
@@ -859,12 +1382,9 @@
                     },
                 }));
                 await this.vectorStore.upsert(points);
-                // 8. Clean up orphaned chunks
+                // 6. Clean up orphaned chunks
                 if (oldTotalChunks > chunks.length) {
-                    const orphanIds = [];
-                    for (let i = chunks.length; i < oldTotalChunks; i++) {
-                        orphanIds.push(pointId(filePath, i));
-                    }
+                    const orphanIds = chunkIds(filePath, oldTotalChunks).slice(chunks.length);
                     await this.vectorStore.delete(orphanIds);
                 }
                 this.logger.info({ filePath, chunks: chunks.length }, 'File processed successfully');
@@ -883,15 +1403,10 @@
                 // Get the existing payload to find total chunks
                 const baseId = pointId(filePath, 0);
                 const existingPayload = await this.vectorStore.getPayload(baseId);
-                const totalChunks = typeof existingPayload?.['total_chunks'] === 'number'
-                    ? existingPayload['total_chunks']
-                    : 1;
-                const ids = [];
-                for (let i = 0; i < totalChunks; i++) {
-                    ids.push(pointId(filePath, i));
-                }
+                const totalChunks = getChunkCount(existingPayload);
+                const ids = chunkIds(filePath, totalChunks);
                 await this.vectorStore.delete(ids);
-                await deleteMetadata(filePath, this.metadataDir);
+                await deleteMetadata(filePath, this.config.metadataDir);
                 this.logger.info({ filePath }, 'File deleted from index');
             }
             catch (error) {
@@ -908,21 +1423,16 @@
         async processMetadataUpdate(filePath, metadata) {
             try {
                 // Read existing enrichment metadata and merge
-                const existing = (await readMetadata(filePath, this.metadataDir)) ?? {};
+                const existing = (await readMetadata(filePath, this.config.metadataDir)) ?? {};
                 const merged = { ...existing, ...metadata };
-                await writeMetadata(filePath, this.metadataDir, merged);
+                await writeMetadata(filePath, this.config.metadataDir, merged);
                 // Update all chunk payloads in Qdrant
                 const baseId = pointId(filePath, 0);
                 const existingPayload = await this.vectorStore.getPayload(baseId);
                 if (!existingPayload)
                     return null;
-                const totalChunks = typeof existingPayload['total_chunks'] === 'number'
-                    ? existingPayload['total_chunks']
-                    : 1;
-                const ids = [];
-                for (let i = 0; i < totalChunks; i++) {
-                    ids.push(pointId(filePath, i));
-                }
+                const totalChunks = getChunkCount(existingPayload);
+                const ids = chunkIds(filePath, totalChunks);
                 await this.vectorStore.setPayload(ids, merged);
                 this.logger.info({ filePath, chunks: totalChunks }, 'Metadata updated');
                 return merged;
@@ -948,27 +1458,11 @@
                     this.logger.debug({ filePath }, 'File not indexed, skipping');
                     return null;
                 }
-                const ext = node_path.extname(filePath);
-                const stats = await promises.stat(filePath);
-                // Extract frontmatter/json for attribute building (lightweight)
-                const extracted = await extractText(filePath, ext);
-                // Build attributes + apply current rules
-                const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-                const inferred = applyRules(this.compiledRules, attributes);
-                // Read enrichment metadata (merge, enrichment wins)
-                const enrichment = await readMetadata(filePath, this.metadataDir);
-                const metadata = {
-                    ...inferred,
-                    ...(enrichment ?? {}),
-                };
+                // Build merged metadata (lightweight — no embedding)
+                const { metadata } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
                 // Update all chunk payloads
-                const totalChunks = typeof existingPayload['total_chunks'] === 'number'
-                    ? existingPayload['total_chunks']
-                    : 1;
-                const ids = [];
-                for (let i = 0; i < totalChunks; i++) {
-                    ids.push(pointId(filePath, i));
-                }
+                const totalChunks = getChunkCount(existingPayload);
+                const ids = chunkIds(filePath, totalChunks);
                 await this.vectorStore.setPayload(ids, metadata);
                 this.logger.info({ filePath, chunks: totalChunks }, 'Rules re-applied');
                 return metadata;
@@ -987,23 +1481,12 @@
             this.compiledRules = compiledRules;
             this.logger.info({ rules: compiledRules.length }, 'Inference rules updated');
         }
-        /**
-         * Create the appropriate text splitter for the given file extension.
-         *
-         * @param ext - File extension.
-         * @param chunkSize - Maximum chunk size in characters.
-         * @param chunkOverlap - Overlap between chunks in characters.
-         * @returns A text splitter instance.
-         */
-        createSplitter(ext, chunkSize, chunkOverlap) {
-            const lowerExt = ext.toLowerCase();
-            if (lowerExt === '.md' || lowerExt === '.markdown') {
-                return new textsplitters.MarkdownTextSplitter({ chunkSize, chunkOverlap });
-            }
-            return new textsplitters.RecursiveCharacterTextSplitter({ chunkSize, chunkOverlap });
-        }
     }
 
+    /**
+     * @module queue
+     * Debounced, rate-limited, concurrent event queue for file watchers. Manages priority queuing and async callbacks. No direct I/O; orchestrates processing.
+     */
     /**
      * A debounced, rate-limited, concurrent event queue.
      */
@@ -1152,19 +1635,23 @@
         client;
         collectionName;
         dims;
+        log;
         /**
          * Create a new VectorStoreClient.
          *
          * @param config - Vector store configuration.
          * @param dimensions - The embedding vector dimensions.
+         * @param logger - Optional pino logger for retry warnings.
          */
-        constructor(config, dimensions) {
+        constructor(config, dimensions, logger) {
             this.client = new jsClientRest.QdrantClient({
                 url: config.url,
                 apiKey: config.apiKey,
+                checkCompatibility: false,
             });
             this.collectionName = config.collectionName;
             this.dims = dimensions;
+            this.log = getLogger(logger);
         }
         /**
          * Ensure the collection exists with correct dimensions and Cosine distance.
@@ -1191,13 +1678,26 @@
         async upsert(points) {
             if (points.length === 0)
                 return;
-            await this.client.upsert(this.collectionName, {
-                wait: true,
-                points: points.map((p) => ({
-                    id: p.id,
-                    vector: p.vector,
-                    payload: p.payload,
-                })),
+            await retry(async (attempt) => {
+                if (attempt > 1) {
+                    this.log.warn({ attempt, operation: 'qdrant.upsert', points: points.length }, 'Retrying Qdrant upsert');
+                }
+                await this.client.upsert(this.collectionName, {
+                    wait: true,
+                    points: points.map((p) => ({
+                        id: p.id,
+                        vector: p.vector,
+                        payload: p.payload,
+                    })),
+                });
+            }, {
+                attempts: 5,
+                baseDelayMs: 500,
+                maxDelayMs: 10_000,
+                jitter: 0.2,
+                onRetry: ({ attempt, delayMs, error }) => {
+                    this.log.warn({ attempt, delayMs, operation: 'qdrant.upsert', error }, 'Qdrant upsert failed; will retry');
+                },
             });
         }
         /**
@@ -1208,9 +1708,22 @@
         async delete(ids) {
             if (ids.length === 0)
                 return;
-            await this.client.delete(this.collectionName, {
-                wait: true,
-                points: ids,
+            await retry(async (attempt) => {
+                if (attempt > 1) {
+                    this.log.warn({ attempt, operation: 'qdrant.delete', ids: ids.length }, 'Retrying Qdrant delete');
+                }
+                await this.client.delete(this.collectionName, {
+                    wait: true,
+                    points: ids,
+                });
+            }, {
+                attempts: 5,
+                baseDelayMs: 500,
+                maxDelayMs: 10_000,
+                jitter: 0.2,
+                onRetry: ({ attempt, delayMs, error }) => {
+                    this.log.warn({ attempt, delayMs, operation: 'qdrant.delete', error }, 'Qdrant delete failed; will retry');
+                },
             });
         }
         /**
@@ -1310,6 +1823,10 @@
         }
     }
 
+    /**
+     * @module watcher
+     * Filesystem watcher wrapping chokidar. I/O: watches files/directories for add/change/unlink events, enqueues to processing queue.
+     */
     /**
      * Filesystem watcher that maps chokidar events to the processing queue.
      */
@@ -1376,57 +1893,141 @@
         }
     }
 
+    /**
+     * @module app/configWatcher
+     * Watches the config file for changes and triggers debounced reload. Isolated I/O wrapper around chokidar.
+     */
+    /**
+     * Debounced config file watcher.
+     */
+    class ConfigWatcher {
+        options;
+        watcher;
+        debounce;
+        constructor(options) {
+            this.options = options;
+        }
+        start() {
+            if (!this.options.enabled)
+                return;
+            this.watcher = chokidar.watch(this.options.configPath, {
+                ignoreInitial: true,
+            });
+            this.watcher.on('change', () => {
+                if (this.debounce)
+                    clearTimeout(this.debounce);
+                this.debounce = setTimeout(() => {
+                    void this.options.onChange();
+                }, this.options.debounceMs);
+            });
+            this.watcher.on('error', (error) => {
+                this.options.logger.error({ error }, 'Config watcher error');
+            });
+            this.options.logger.info({
+                configPath: this.options.configPath,
+                debounceMs: this.options.debounceMs,
+            }, 'Config watcher started');
+        }
+        async stop() {
+            if (this.debounce) {
+                clearTimeout(this.debounce);
+                this.debounce = undefined;
+            }
+            if (this.watcher) {
+                await this.watcher.close();
+                this.watcher = undefined;
+            }
+        }
+    }
+
+    /**
+     * @module app/shutdown
+     * Process signal shutdown orchestration. Installs SIGINT/SIGTERM handlers that invoke a provided async stop function.
+     */
+    /**
+     * Install process signal handlers.
+     *
+     * @param stop - Async stop function to invoke on shutdown signals.
+     */
+    function installShutdownHandlers(stop) {
+        const shutdown = async () => {
+            await stop();
+            process.exit(0);
+        };
+        process.on('SIGTERM', () => void shutdown());
+        process.on('SIGINT', () => void shutdown());
+    }
+
+    const defaultFactories = {
+        loadConfig,
+        createLogger,
+        createEmbeddingProvider,
+        createVectorStoreClient: (config, dimensions, logger) => new VectorStoreClient(config, dimensions, logger),
+        compileRules,
+        createDocumentProcessor: (config, embeddingProvider, vectorStore, compiledRules, logger) => new DocumentProcessor(config, embeddingProvider, vectorStore, compiledRules, logger),
+        createEventQueue: (options) => new EventQueue(options),
+        createFileSystemWatcher: (config, queue, processor, logger) => new FileSystemWatcher(config, queue, processor, logger),
+        createApiServer,
+    };
     /**
      * Main application class that wires together all components.
      */
     class JeevesWatcher {
         config;
         configPath;
+        factories;
         logger;
         watcher;
         queue;
         server;
         processor;
         configWatcher;
-        configDebounce;
         /**
          * Create a new JeevesWatcher instance.
          *
          * @param config - The application configuration.
          * @param configPath - Optional config file path to watch for changes.
+         * @param factories - Optional component factories (for dependency injection).
          */
-        constructor(config, configPath) {
+        constructor(config, configPath, factories = {}) {
             this.config = config;
             this.configPath = configPath;
+            this.factories = { ...defaultFactories, ...factories };
         }
         /**
          * Start the watcher, API server, and all components.
          */
         async start() {
-            const logger = createLogger(this.config.logging);
+            const logger = this.factories.createLogger(this.config.logging);
             this.logger = logger;
             let embeddingProvider;
             try {
-                embeddingProvider = createEmbeddingProvider(this.config.embedding);
+                embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
             }
             catch (error) {
                 logger.fatal({ error }, 'Failed to create embedding provider');
                 throw error;
             }
-            const vectorStore = new VectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions);
+            const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
             await vectorStore.ensureCollection();
-            const compiledRules = compileRules(this.config.inferenceRules ?? []);
-            const processor = new DocumentProcessor(this.config, embeddingProvider, vectorStore, compiledRules, logger);
+            const compiledRules = this.factories.compileRules(this.config.inferenceRules ?? []);
+            const processorConfig = {
+                metadataDir: this.config.metadataDir ?? '.jeeves-metadata',
+                chunkSize: this.config.embedding.chunkSize,
+                chunkOverlap: this.config.embedding.chunkOverlap,
+                maps: this.config.maps,
+            };
+            const processor = this.factories.createDocumentProcessor(processorConfig, embeddingProvider, vectorStore, compiledRules, logger);
             this.processor = processor;
-            const queue = new EventQueue({
+            const queue = this.factories.createEventQueue({
                 debounceMs: this.config.watch.debounceMs ?? 2000,
                 concurrency: this.config.embedding.concurrency ?? 5,
                 rateLimitPerMinute: this.config.embedding.rateLimitPerMinute,
             });
             this.queue = queue;
-            const watcher = new FileSystemWatcher(this.config.watch, queue, processor, logger);
+            const watcher = this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger);
             this.watcher = watcher;
-            const server = createApiServer({
+            const server = this.factories.createApiServer({
                 processor,
                 vectorStore,
                 embeddingProvider,
@@ -1437,7 +2038,7 @@
             this.server = server;
             await server.listen({
                 host: this.config.api?.host ?? '127.0.0.1',
-                port: this.config.api?.port ?? 3458,
+                port: this.config.api?.port ?? 3456,
             });
             watcher.start();
             this.startConfigWatch();
@@ -1453,12 +2054,17 @@
             }
             if (this.queue) {
                 const timeout = this.config.shutdownTimeoutMs ?? 10000;
-                await Promise.race([
-                    this.queue.drain(),
+                const drained = await Promise.race([
+                    this.queue.drain().then(() => true),
                     new Promise((resolve) => {
-                        setTimeout(resolve, timeout);
+                        setTimeout(() => {
+                            resolve(false);
+                        }, timeout);
                     }),
                 ]);
+                if (!drained) {
+                    this.logger?.warn({ timeoutMs: timeout }, 'Queue drain timeout hit, forcing shutdown');
+                }
             }
             if (this.server) {
                 await this.server.close();
@@ -1477,28 +2083,18 @@
                 return;
             }
             const debounceMs = this.config.configWatch?.debounceMs ?? 10000;
-            this.configWatcher = chokidar.watch(this.configPath, {
-                ignoreInitial: true,
-            });
-            this.configWatcher.on('change', () => {
-                if (this.configDebounce)
-                    clearTimeout(this.configDebounce);
-                this.configDebounce = setTimeout(() => {
-                    void this.reloadConfig();
-                }, debounceMs);
-            });
-            this.configWatcher.on('error', (error) => {
-                logger.error({ error }, 'Config watcher error');
+            this.configWatcher = new ConfigWatcher({
+                configPath: this.configPath,
+                enabled,
+                debounceMs,
+                logger,
+                onChange: async () => this.reloadConfig(),
             });
-            logger.info({ configPath: this.configPath, debounceMs }, 'Config watcher started');
+            this.configWatcher.start();
         }
         async stopConfigWatch() {
-            if (this.configDebounce) {
-                clearTimeout(this.configDebounce);
-                this.configDebounce = undefined;
-            }
             if (this.configWatcher) {
-                await this.configWatcher.close();
+                await this.configWatcher.stop();
                 this.configWatcher = undefined;
             }
         }
@@ -1507,10 +2103,11 @@
             const processor = this.processor;
             if (!logger || !processor || !this.configPath)
                 return;
+            logger.info({ configPath: this.configPath }, 'Config change detected, reloading...');
             try {
-                const newConfig = await loadConfig(this.configPath);
+                const newConfig = await this.factories.loadConfig(this.configPath);
                 this.config = newConfig;
-                const compiledRules = compileRules(newConfig.inferenceRules ?? []);
+                const compiledRules = this.factories.compileRules(newConfig.inferenceRules ?? []);
                 processor.updateRules(compiledRules);
                 logger.info({ configPath: this.configPath, rules: compiledRules.length }, 'Config reloaded');
             }
@@ -1528,12 +2125,7 @@
     async function startFromConfig(configPath) {
         const config = await loadConfig(configPath);
         const app = new JeevesWatcher(config, configPath);
-        const shutdown = async () => {
-            await app.stop();
-            process.exit(0);
-        };
-        process.on('SIGTERM', () => void shutdown());
-        process.on('SIGINT', () => void shutdown());
+        installShutdownHandlers(() => app.stop());
         await app.start();
         return app;
     }
@@ -1543,20 +2135,28 @@
     exports.FileSystemWatcher = FileSystemWatcher;
     exports.JeevesWatcher = JeevesWatcher;
     exports.VectorStoreClient = VectorStoreClient;
+    exports.apiConfigSchema = apiConfigSchema;
     exports.applyRules = applyRules;
     exports.buildAttributes = buildAttributes;
     exports.compileRules = compileRules;
+    exports.configWatchConfigSchema = configWatchConfigSchema;
     exports.contentHash = contentHash;
     exports.createApiServer = createApiServer;
     exports.createEmbeddingProvider = createEmbeddingProvider;
     exports.createLogger = createLogger;
     exports.deleteMetadata = deleteMetadata;
+    exports.embeddingConfigSchema = embeddingConfigSchema;
     exports.extractText = extractText;
+    exports.inferenceRuleSchema = inferenceRuleSchema;
+    exports.jeevesWatcherConfigSchema = jeevesWatcherConfigSchema;
     exports.loadConfig = loadConfig;
+    exports.loggingConfigSchema = loggingConfigSchema;
     exports.metadataPath = metadataPath;
     exports.pointId = pointId;
     exports.readMetadata = readMetadata;
     exports.startFromConfig = startFromConfig;
+    exports.vectorStoreConfigSchema = vectorStoreConfigSchema;
+    exports.watchConfigSchema = watchConfigSchema;
     exports.writeMetadata = writeMetadata;
 
-})(this["jeeves-watcher"] = this["jeeves-watcher"] || {}, Fastify, node_crypto, promises, node_path, picomatch, chokidar, Ajv, cosmiconfig, googleGenai, pino, textsplitters, cheerio, yaml, mammoth, uuid, addFormats, jsClientRest);
+})(this["jeeves-watcher"] = this["jeeves-watcher"] || {}, Fastify, promises, node_path, picomatch, radash, node_crypto, cosmiconfig, zod, jsonmap, googleGenai, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest, chokidar);