@karmaniverous/jeeves-watcher 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -22,6 +22,10 @@ declare const watchConfigSchema: z.ZodObject<{
     debounceMs: z.ZodOptional<z.ZodNumber>;
     stabilityThresholdMs: z.ZodOptional<z.ZodNumber>;
     respectGitignore: z.ZodOptional<z.ZodBoolean>;
+    moveDetection: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        bufferMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Watch configuration for file system monitoring paths, ignore patterns, and debounce/stability settings. */
 type WatchConfig = z.infer<typeof watchConfigSchema>;
@@ -113,6 +117,10 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         debounceMs: z.ZodOptional<z.ZodNumber>;
         stabilityThresholdMs: z.ZodOptional<z.ZodNumber>;
         respectGitignore: z.ZodOptional<z.ZodBoolean>;
+        moveDetection: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            bufferMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     configWatch: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -134,7 +142,6 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         collectionName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    metadataDir: z.ZodOptional<z.ZodString>;
     api: z.ZodOptional<z.ZodObject<{
         host: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodNumber>;
@@ -289,6 +296,62 @@ type ProviderFactory = (config: EmbeddingConfig, logger?: pino.Logger) => Embedd
  */
 declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger, additionalProviders?: Map<string, ProviderFactory>): EmbeddingProvider;
 
+/**
+ * @module enrichment/EnrichmentStore
+ * SQLite-backed enrichment metadata store. Persists path-keyed metadata at stateDir/enrichments.sqlite. Atomic writes, supports move.
+ */
+/**
+ * Interface for enrichment metadata persistence.
+ */
+interface EnrichmentStoreInterface {
+    /** Get enrichment metadata for a file path, or null. */
+    get(path: string): Record<string, unknown> | null;
+    /** Set/merge enrichment metadata for a file path. */
+    set(path: string, metadata: Record<string, unknown>): void;
+    /** Delete enrichment metadata for a file path. */
+    delete(path: string): void;
+    /** Move enrichment from old path to new path (atomic). */
+    move(oldPath: string, newPath: string): void;
+    /** List all enriched paths (for diagnostics). */
+    list(): string[];
+    /** Close the database connection. */
+    close(): void;
+}
+/**
+ * SQLite-backed enrichment metadata store.
+ */
+declare class EnrichmentStore implements EnrichmentStoreInterface {
+    private readonly db;
+    /**
+     * Create or open the enrichment store.
+     *
+     * @param stateDir - Directory for the SQLite database file.
+     */
+    constructor(stateDir: string);
+    get(path: string): Record<string, unknown> | null;
+    set(path: string, metadata: Record<string, unknown>): void;
+    delete(path: string): void;
+    move(oldPath: string, newPath: string): void;
+    list(): string[];
+    close(): void;
+}
+
+/**
+ * @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.
+ */
+declare function mergeEnrichment(inferred: Record<string, unknown>, enrichment: Record<string, unknown>): Record<string, unknown>;
+
 /**
  * Processor-level gitignore filter. Checks file paths against the nearest
  * `.gitignore` chain in git repositories.
@@ -416,6 +479,52 @@ declare class IssuesManager extends JsonFileStore<IssuesFile> {
     getAll(): IssuesFile;
 }
 
+/**
+ * @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.
+ */
+declare class ContentHashCache {
+    private readonly pathToHash;
+    private readonly hashToPaths;
+    /**
+     * 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: string, hash: string): void;
+    /**
+     * 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: string): string | undefined;
+    /**
+     * Remove a file path from the cache.
+     *
+     * @param filePath - The file path (will be normalized).
+     */
+    delete(filePath: string): void;
+    /**
+     * 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: string): string[];
+    /** Number of cached entries. */
+    get size(): number;
+}
+
 /**
  * @module templates/engine
  * Handlebars template compilation, caching, and resolution (file path vs named ref vs inline).
@@ -872,6 +981,13 @@ interface VectorStore {
      * @returns An array of search results.
      */
     hybridSearch(vector: number[], queryText: string, limit: number, textWeight: number, filter?: Record<string, unknown>): Promise<SearchResult[]>;
+    /**
+     * Retrieve points with their vectors by ID.
+     *
+     * @param ids - The point IDs to retrieve.
+     * @returns Points with vectors and payloads; missing IDs are omitted.
+     */
+    getPointsWithVectors(ids: string[]): Promise<VectorPoint[]>;
 }
 
 /**
@@ -989,6 +1105,13 @@ declare class VectorStoreClient implements VectorStore {
      * @returns An array of search results.
      */
     hybridSearch(vector: number[], queryText: string, limit: number, textWeight: number, filter?: Record<string, unknown>): Promise<SearchResult[]>;
+    /**
+     * Retrieve points with their vectors by ID.
+     *
+     * @param ids - The point IDs to retrieve.
+     * @returns Points with vectors and payloads; missing IDs are omitted.
+     */
+    getPointsWithVectors(ids: string[]): Promise<VectorPoint[]>;
     /**
      * Scroll one page of points matching a filter.
      *
@@ -1018,8 +1141,6 @@ declare class VectorStoreClient implements VectorStore {
  * Configuration needed by DocumentProcessor (ISP — narrow interface).
  */
 interface ProcessorConfig {
-    /** Metadata directory for enrichment files. */
-    metadataDir: string;
     /** Maximum chunk size in characters. */
     chunkSize?: number;
     /** Overlap between chunks in characters. */
@@ -1075,6 +1196,8 @@ interface DocumentProcessorInterface {
     processRulesUpdate(filePath: string): Promise<Record<string, unknown> | null>;
     /** Render a file through the rule engine without embedding. */
     renderFile(filePath: string): Promise<RenderResult>;
+    /** Move a file's vector points and metadata from old path to new path (no re-embed). */
+    moveFile(oldPath: string, newPath: string): Promise<void>;
     /** Update compiled inference rules and associated engines. */
     updateRules(compiledRules: CompiledRule[], templateEngine?: TemplateEngine, customMapLib?: Record<string, (...args: unknown[]) => unknown>): void;
 }
@@ -1103,10 +1226,14 @@ interface DocumentProcessorDeps {
     logger: pino.Logger;
     /** Optional Handlebars template engine for content templates. */
     templateEngine?: TemplateEngine;
+    /** Optional enrichment store for persisted enrichment metadata. */
+    enrichmentStore?: EnrichmentStoreInterface;
     /** Optional issues manager for tracking processing errors. */
     issuesManager?: IssuesManager;
     /** Optional values manager for tracking rule-extracted values. */
     valuesManager?: ValuesManager;
+    /** Optional content hash cache for move detection. */
+    contentHashCache?: ContentHashCache;
 }
 /**
  * Core document processing pipeline.
@@ -1120,14 +1247,16 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
     private compiledRules;
     private readonly logger;
     private templateEngine?;
+    private readonly enrichmentStore?;
     private readonly issuesManager?;
     private readonly valuesManager?;
+    private readonly contentHashCache?;
     /**
      * Create a new DocumentProcessor.
      *
      * @param deps - The processor dependencies.
      */
-    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, issuesManager, valuesManager, }: DocumentProcessorDeps);
+    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, enrichmentStore, issuesManager, valuesManager, contentHashCache, }: DocumentProcessorDeps);
     /**
      * Build merged metadata for a file and add matched_rules.
      */
@@ -1149,7 +1278,7 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
      */
     deleteFile(filePath: string): Promise<void>;
     /**
-     * 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.
@@ -1173,6 +1302,14 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
      * @returns The render result.
      */
     renderFile(filePath: string): Promise<RenderResult>;
+    /**
+     * 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.
+     */
+    moveFile(oldPath: string, newPath: string): Promise<void>;
     /**
      * Update compiled inference rules, template engine, and custom map lib.
      *
@@ -1192,9 +1329,11 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
  */
 type WatchEvent = {
     /** Event type. */
-    type: 'create' | 'modify' | 'delete';
-    /** File path associated with the event. */
+    type: 'create' | 'modify' | 'delete' | 'move';
+    /** File path associated with the event (new path for moves). */
     path: string;
+    /** Original path before move (populated only for move events). */
+    oldPath?: string;
     /** Event priority. */
     priority: 'normal' | 'low';
 };
@@ -1376,6 +1515,8 @@ interface FileSystemWatcherOptions {
     gitignoreFilter?: GitignoreFilter;
     /** Optional tracker for initial scan visibility in /status. */
     initialScanTracker?: InitialScanTracker;
+    /** Optional content hash cache for move detection. */
+    contentHashCache?: ContentHashCache;
 }
 /**
  * Filesystem watcher that maps chokidar events to the processing queue.
@@ -1388,6 +1529,8 @@ declare class FileSystemWatcher {
     private readonly health;
     private readonly gitignoreFilter?;
     private readonly initialScanTracker?;
+    private readonly contentHashCache?;
+    private moveCorrelator?;
     private globMatches;
     private watcher;
     /**
@@ -1518,6 +1661,8 @@ interface ApiServerOptions {
     initialScanTracker?: InitialScanTracker;
     /** Filesystem watcher instance for /walk endpoint (in-memory file list). */
     fileSystemWatcher?: FileSystemWatcher;
+    /** Optional enrichment store for persisted enrichment metadata. */
+    enrichmentStore?: EnrichmentStoreInterface;
 }
 /**
  * Create the Fastify API server with all routes registered.
@@ -1617,6 +1762,8 @@ declare class JeevesWatcher {
     private vectorStore;
     private embeddingProvider;
     private gitignoreFilter;
+    private enrichmentStore;
+    private contentHashCache;
     private readonly initialScanTracker;
     private readonly version;
     /** Create a new JeevesWatcher instance. */
@@ -1680,38 +1827,6 @@ declare function extractText(filePath: string, extension: string, additionalExtr
  */
 declare function contentHash(text: string): string;
 
-/**
- * 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.
- */
-declare function metadataPath(filePath: string, metadataDir: string): string;
-/**
- * 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.
- */
-declare function readMetadata(filePath: string, metadataDir: string): Promise<Record<string, unknown> | null>;
-/**
- * Write metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @param metadata - The metadata to persist.
- */
-declare function writeMetadata(filePath: string, metadataDir: string, metadata: Record<string, unknown>): Promise<void>;
-/**
- * Delete metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- */
-declare function deleteMetadata(filePath: string, metadataDir: string): Promise<void>;
-
 /**
  * Generate a deterministic UUID v5 point ID for a file (and optional chunk index).
  *
@@ -1721,5 +1836,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
-export type { AllHelpersIntrospection, ApiConfig, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InferenceRule, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherConfig, JeevesWatcherConfigInput, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, ProviderFactory, ReindexStatus, RenderResult, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, VectorStoreConfig, WatchConfig, WatchEvent };
+export { DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema };
+export type { AllHelpersIntrospection, ApiConfig, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingConfig, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InferenceRule, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherConfig, JeevesWatcherConfigInput, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, ProviderFactory, ReindexStatus, RenderResult, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, VectorStoreConfig, WatchConfig, WatchEvent };