@karmaniverous/jeeves-watcher 0.4.4 → 0.5.0-0

package/dist/index.d.ts

@@ -6,6 +6,11 @@ import { z } from 'zod';
 import Handlebars from 'handlebars';
 import { Stats } from 'node:fs';
 
+/**
+ * @module config/schemas/base
+ * Base configuration schemas: watch, logging, API.
+ */
+
 /**
  * Watch configuration for file system monitoring.
  */
@@ -26,34 +31,13 @@ type WatchConfig = z.infer<typeof watchConfigSchema>;
 declare const configWatchConfigSchema: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
     debounceMs: z.ZodOptional<z.ZodNumber>;
+    reindex: z.ZodOptional<z.ZodEnum<{
+        issues: "issues";
+        full: "full";
+    }>>;
 }, z.core.$strip>;
 /** Configuration file watch settings controlling auto-reload behavior on config changes. */
 type ConfigWatchConfig = z.infer<typeof configWatchConfigSchema>;
-/**
- * Embedding model configuration.
- */
-declare const embeddingConfigSchema: z.ZodObject<{
-    provider: z.ZodDefault<z.ZodString>;
-    model: z.ZodDefault<z.ZodString>;
-    chunkSize: z.ZodOptional<z.ZodNumber>;
-    chunkOverlap: z.ZodOptional<z.ZodNumber>;
-    dimensions: z.ZodOptional<z.ZodNumber>;
-    apiKey: z.ZodOptional<z.ZodString>;
-    rateLimitPerMinute: z.ZodOptional<z.ZodNumber>;
-    concurrency: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-/** Embedding model configuration: provider, model, chunking, dimensions, rate limits, and API key. */
-type EmbeddingConfig = z.infer<typeof embeddingConfigSchema>;
-/**
- * Vector store configuration for Qdrant.
- */
-declare const vectorStoreConfigSchema: z.ZodObject<{
-    url: z.ZodString;
-    collectionName: z.ZodString;
-    apiKey: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** Qdrant vector store connection configuration: server URL, collection name, and optional API key. */
-type VectorStoreConfig = z.infer<typeof vectorStoreConfigSchema>;
 /**
  * API server configuration.
  */
@@ -72,21 +56,42 @@ declare const loggingConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Logging configuration: level and optional file output path. */
 type LoggingConfig = z.infer<typeof loggingConfigSchema>;
+
+/**
+ * Global schema entry: inline object or file path.
+ */
+declare const schemaEntrySchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodOptional<z.ZodLiteral<"object">>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>, z.ZodString]>;
+/** Global schema entry. */
+type SchemaEntry = z.infer<typeof schemaEntrySchema>;
 /**
  * An inference rule that enriches document metadata.
  */
 declare const inferenceRuleSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
     match: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    schema: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"object">>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>]>>>;
     map: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>;
     template: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-/** An inference rule: JSON Schema match condition, set fields, and optional JsonMap transformation. */
+/** An inference rule: JSON Schema match condition, schema array, and optional JsonMap transformation. */
 type InferenceRule = z.infer<typeof inferenceRuleSchema>;
+
 /**
  * Top-level configuration for jeeves-watcher.
  */
 declare const jeevesWatcherConfigSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"object">>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>, z.ZodString]>>>;
     watch: z.ZodObject<{
         paths: z.ZodArray<z.ZodString>;
         ignored: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -99,6 +104,10 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
     configWatch: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         debounceMs: z.ZodOptional<z.ZodNumber>;
+        reindex: z.ZodOptional<z.ZodEnum<{
+            issues: "issues";
+            full: "full";
+        }>>;
     }, z.core.$strip>>;
     embedding: z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
@@ -121,19 +130,44 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         port: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     extractors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stateDir: z.ZodOptional<z.ZodString>;
     inferenceRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
         match: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        schema: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            type: z.ZodOptional<z.ZodLiteral<"object">>;
+            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        }, z.core.$strip>]>>>;
         map: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>;
         template: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-    maps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>>;
-    templates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    templateHelpers: z.ZodOptional<z.ZodObject<{
-        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString, z.ZodObject<{
+        map: z.ZodUnion<[z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    templates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        template: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    templateHelpers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    mapHelpers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    reindex: z.ZodOptional<z.ZodObject<{
+        callbackUrl: z.ZodOptional<z.ZodURL>;
     }, z.core.$strip>>;
-    mapHelpers: z.ZodOptional<z.ZodObject<{
-        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    slots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    search: z.ZodOptional<z.ZodObject<{
+        scoreThresholds: z.ZodOptional<z.ZodObject<{
+            strong: z.ZodNumber;
+            relevant: z.ZodNumber;
+            noise: z.ZodNumber;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     logging: z.ZodOptional<z.ZodObject<{
         level: z.ZodOptional<z.ZodString>;
@@ -147,9 +181,39 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
 type JeevesWatcherConfig = z.infer<typeof jeevesWatcherConfigSchema>;
 
 /**
- * @module embedding
- *
- * Embedding provider abstractions and registry-backed factory.
+ * @module config/schemas/services
+ * Service configuration schemas: embedding and vector store.
+ */
+
+/**
+ * Embedding model configuration.
+ */
+declare const embeddingConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodString>;
+    model: z.ZodDefault<z.ZodString>;
+    chunkSize: z.ZodOptional<z.ZodNumber>;
+    chunkOverlap: z.ZodOptional<z.ZodNumber>;
+    dimensions: z.ZodOptional<z.ZodNumber>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    rateLimitPerMinute: z.ZodOptional<z.ZodNumber>;
+    concurrency: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Embedding model configuration: provider, model, chunking, dimensions, rate limits, and API key. */
+type EmbeddingConfig = z.infer<typeof embeddingConfigSchema>;
+/**
+ * Vector store configuration for Qdrant.
+ */
+declare const vectorStoreConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    collectionName: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Qdrant vector store connection configuration: server URL, collection name, and optional API key. */
+type VectorStoreConfig = z.infer<typeof vectorStoreConfigSchema>;
+
+/**
+ * @module embedding/types
+ * Embedding provider type definitions.
  */
 
 /**
@@ -161,6 +225,17 @@ interface EmbeddingProvider {
     /** The dimensionality of the embedding vectors. */
     dimensions: number;
 }
+/**
+ * Factory function for creating embedding providers.
+ */
+type ProviderFactory = (config: EmbeddingConfig, logger?: pino.Logger) => EmbeddingProvider;
+
+/**
+ * @module embedding
+ *
+ * Embedding provider abstractions and registry-backed factory.
+ */
+
 /**
  * Create an embedding provider based on the given configuration.
  *
@@ -168,10 +243,107 @@ interface EmbeddingProvider {
  *
  * @param config - The embedding configuration.
  * @param logger - Optional pino logger for retry warnings.
+ * @param additionalProviders - Optional map of additional provider factories to register.
  * @returns An {@link EmbeddingProvider} instance.
  * @throws If the configured provider is not supported.
  */
-declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger): EmbeddingProvider;
+declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger, additionalProviders?: Map<string, ProviderFactory>): EmbeddingProvider;
+
+/**
+ * @module helpers/introspect
+ * JSDoc introspection for helper modules. Extracts function exports and their descriptions.
+ */
+/** Result of introspecting a single helper module. */
+interface HelperModuleIntrospection {
+    /** Map of namespace_exportName to JSDoc description (empty string if none). */
+    exports: Record<string, string>;
+}
+/** Result of introspecting all helper modules. */
+interface AllHelpersIntrospection {
+    mapHelpers: Record<string, HelperModuleIntrospection>;
+    templateHelpers: Record<string, HelperModuleIntrospection>;
+}
+
+/**
+ * @module util/JsonFileStore
+ * Small base class for JSON-backed read/modify/write stores with in-memory caching.
+ */
+
+/** Options for {@link JsonFileStore}. */
+interface JsonFileStoreOptions {
+    /** Path to the JSON file on disk. */
+    filePath: string;
+    /** Logger for warnings. */
+    logger: pino.Logger;
+}
+/**
+ * Base class for JSON file stores.
+ *
+ * @typeParam T - The JSON-serializable data structure stored.
+ */
+declare abstract class JsonFileStore<T> {
+    /** Path to the JSON file on disk. */
+    protected readonly filePath: string;
+    /** In-memory cache of the parsed file contents, or `null` if not yet loaded. */
+    protected cache: T | null;
+    /** Logger instance for warnings and diagnostics. */
+    protected readonly logger: pino.Logger;
+    protected constructor(options: JsonFileStoreOptions);
+    /** Create an empty default value when file is missing or unreadable. */
+    protected abstract createEmpty(): T;
+    /** Load from disk into cache if not already loaded. */
+    protected load(): T;
+    /** Flush cache to disk. */
+    protected save(): void;
+}
+
+/**
+ * @module issues/types
+ * Zod schemas and TypeScript types for the issues tracking system. Defines IssueRecord and IssuesFile structures.
+ */
+
+/** Schema for a single issue record tracking a processing failure. */
+declare const issueRecordSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        type_collision: "type_collision";
+        interpolation_error: "interpolation_error";
+    }>;
+    property: z.ZodOptional<z.ZodString>;
+    rules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    rule: z.ZodOptional<z.ZodString>;
+    types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    message: z.ZodString;
+    timestamp: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$strip>;
+/** A single issue record tracking a processing failure for a file. */
+type IssueRecord = z.infer<typeof issueRecordSchema>;
+/** Issues file: array of issue records per file path. */
+type IssuesFile = Partial<Record<string, IssueRecord[]>>;
+
+/**
+ * @module issues/IssuesManager
+ * Manages persistent issue tracking for file processing failures. Read-modify-write with in-memory cache.
+ */
+
+/**
+ * Manages a persistent issues.json file tracking processing failures per file.
+ */
+declare class IssuesManager extends JsonFileStore<IssuesFile> {
+    constructor(stateDir: string, logger: pino.Logger);
+    protected createEmpty(): IssuesFile;
+    /** Record or update an issue for a file path. */
+    record(filePath: string, type: IssueRecord['type'], message: string, options?: {
+        property?: string;
+        rules?: string[];
+        types?: string[];
+    }): void;
+    /** Clear an issue for a file path (called on successful processing). */
+    clear(filePath: string): void;
+    /** Wipe all issues (called on full reindex start). */
+    clearAll(): void;
+    /** Get all current issues. */
+    getAll(): IssuesFile;
+}
 
 /**
  * @module templates/engine
@@ -202,15 +374,24 @@ declare function resolveTemplateSource(value: string, namedTemplates: Record<str
  */
 declare function createHandlebarsInstance(): typeof Handlebars;
 /**
- * Load custom helpers from file paths.
+ * Load custom helpers from named helper config.
+ *
+ * Each file should export a default function that receives the Handlebars instance
+ * and a namespace prefix string. The function should register helpers with the
+ * namespace prefix applied.
  *
- * Each file should export a default function that receives the Handlebars instance.
+ * If the module does not accept a namespace argument, helpers are registered
+ * with namespace prefixing applied automatically to any helpers registered
+ * during the call.
  *
  * @param hbs - The Handlebars instance.
- * @param paths - File paths to custom helper modules.
+ * @param helpers - Named helper config: Record of namespace to path/description.
  * @param configDir - Directory to resolve relative paths against.
  */
-declare function loadCustomHelpers(hbs: typeof Handlebars, paths: string[], configDir: string): Promise<void>;
+declare function loadCustomHelpers(hbs: typeof Handlebars, helpers: Record<string, {
+    path: string;
+    description?: string;
+}>, configDir: string): Promise<void>;
 /**
  * The template engine: holds compiled templates and renders them against context.
  */
@@ -253,11 +434,17 @@ declare class TemplateEngine {
  *
  * @param rules - The inference rules (may contain template fields).
  * @param namedTemplates - Named template definitions from config.
- * @param templateHelperPaths - Paths to custom helper modules.
+ * @param templateHelpers - Custom helper registrations with paths and descriptions.
  * @param configDir - Directory to resolve relative paths against.
  * @returns The configured TemplateEngine, or undefined if no templates are used.
  */
-declare function buildTemplateEngine(rules: InferenceRule[], namedTemplates?: Record<string, string>, templateHelperPaths?: string[], configDir?: string): Promise<TemplateEngine | undefined>;
+declare function buildTemplateEngine(rules: InferenceRule[], namedTemplates?: Record<string, string | {
+    template: string;
+    description?: string;
+}>, templateHelpers?: Record<string, {
+    path: string;
+    description?: string;
+}>, configDir?: string): Promise<TemplateEngine | undefined>;
 
 /**
  * @module templates/helpers
@@ -327,6 +514,7 @@ interface CompiledRule {
 }
 /**
  * Compile an array of inference rules into executable validators.
+ * Validates rule name uniqueness before compilation.
  *
  * @param rules - The inference rule definitions.
  * @returns An array of compiled rules.
@@ -353,6 +541,8 @@ interface ApplyRulesResult {
     metadata: Record<string, unknown>;
     /** Rendered template content from the last matching rule with a template, or null. */
     renderedContent: string | null;
+    /** Names of rules that matched. */
+    matchedRules: string[];
 }
 /**
  * Apply compiled inference rules to file attributes, returning merged metadata and optional rendered content.
@@ -367,10 +557,40 @@ interface ApplyRulesResult {
  * @param logger - Optional logger for warnings (falls back to console.warn).
  * @param templateEngine - Optional template engine for rendering content templates.
  * @param configDir - Optional config directory for resolving .json map file paths.
+ * @param globalSchemas - Optional global schemas collection for resolving schema references.
  * @returns The merged metadata and optional rendered content.
  */
-declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger, templateEngine?: TemplateEngine, configDir?: string, customMapLib?: Record<string, (...args: unknown[]) => unknown>): Promise<ApplyRulesResult>;
+declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger, templateEngine?: TemplateEngine, configDir?: string, customMapLib?: Record<string, (...args: unknown[]) => unknown>, globalSchemas?: Record<string, SchemaEntry>): Promise<ApplyRulesResult>;
+
+/**
+ * @module values/ValuesManager
+ * Manages per-rule distinct metadata value tracking. Persists to disk with in-memory caching and sorted deduplication.
+ */
+
+/** Per-rule distinct values: rule name → field name → sorted unique values. */
+type ValuesIndex = Record<string, Record<string, unknown[]>>;
+/**
+ * Manages a persistent values.json file tracking distinct metadata values per rule.
+ */
+declare class ValuesManager extends JsonFileStore<ValuesIndex> {
+    constructor(stateDir: string, logger: pino.Logger);
+    protected createEmpty(): ValuesIndex;
+    /** Check if a value is a trackable primitive (string, number, boolean). */
+    private isTrackable;
+    /** Update distinct values for a rule from metadata. */
+    update(ruleName: string, metadata: Record<string, unknown>): void;
+    /** Wipe all values (called on full reindex start). */
+    clearAll(): void;
+    /** Get all current values. */
+    getAll(): ValuesIndex;
+    /** Get values for a specific rule. */
+    getForRule(ruleName: string): Record<string, unknown[]>;
+}
 
+/**
+ * @module vectorStore/types
+ * Vector store interface and type definitions.
+ */
 /**
  * A point to upsert into the vector store.
  */
@@ -418,10 +638,72 @@ interface CollectionInfo {
     /** Payload field schema keyed by field name. */
     payloadFields: Record<string, PayloadFieldSchema>;
 }
+/**
+ * Abstract interface for vector store operations.
+ *
+ * Enables dependency inversion and easier testing.
+ */
+interface VectorStore {
+    /**
+     * Ensure the collection exists with correct configuration.
+     */
+    ensureCollection(): Promise<void>;
+    /**
+     * Upsert points into the collection.
+     *
+     * @param points - The points to upsert.
+     */
+    upsert(points: VectorPoint[]): Promise<void>;
+    /**
+     * Delete points by their IDs.
+     *
+     * @param ids - The point IDs to delete.
+     */
+    delete(ids: string[]): Promise<void>;
+    /**
+     * Set payload fields for the specified point IDs.
+     *
+     * @param ids - Point IDs to update.
+     * @param payload - Payload fields to set.
+     */
+    setPayload(ids: string[], payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the payload of a point by ID.
+     *
+     * @param id - The point ID.
+     * @returns The payload, or `null` if the point doesn't exist.
+     */
+    getPayload(id: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Get collection info including point count, dimensions, and payload field schema.
+     */
+    getCollectionInfo(): Promise<CollectionInfo>;
+    /**
+     * Search for similar vectors.
+     *
+     * @param vector - The query vector.
+     * @param limit - Maximum results to return.
+     * @param filter - Optional Qdrant filter.
+     * @param offset - Optional result offset.
+     * @returns An array of search results.
+     */
+    search(vector: number[], limit: number, filter?: Record<string, unknown>, offset?: number): Promise<SearchResult[]>;
+    /**
+     * Scroll through all points matching a filter.
+     *
+     * @param filter - Optional Qdrant filter.
+     * @param limit - Page size for scrolling.
+     * @yields Scrolled points.
+     */
+    scroll(filter?: Record<string, unknown>, limit?: number): AsyncGenerator<ScrolledPoint>;
+}
+
 /**
  * Client wrapper for Qdrant vector store operations.
+ *
+ * Implements the {@link VectorStore} interface for dependency inversion.
  */
-declare class VectorStoreClient {
+declare class VectorStoreClient implements VectorStore {
     private readonly client;
     private readonly collectionName;
     private readonly dims;
@@ -438,6 +720,13 @@ declare class VectorStoreClient {
      * Ensure the collection exists with correct dimensions and Cosine distance.
      */
     ensureCollection(): Promise<void>;
+    /**
+     * Retry a Qdrant operation with standardized config and logging.
+     *
+     * @param operation - Operation name for logging (e.g., 'upsert', 'delete').
+     * @param fn - Async function to retry.
+     */
+    private retryOperation;
     /**
      * Upsert points into the collection.
      *
@@ -488,7 +777,7 @@ declare class VectorStoreClient {
      * @param filter - Optional Qdrant filter.
      * @returns An array of search results.
      */
-    search(vector: number[], limit: number, filter?: Record<string, unknown>): Promise<SearchResult[]>;
+    search(vector: number[], limit: number, filter?: Record<string, unknown>, offset?: number): Promise<SearchResult[]>;
     /**
      * Scroll through all points matching a filter.
      *
@@ -500,9 +789,8 @@ declare class VectorStoreClient {
 }
 
 /**
- * @module processor
- *
- * Core document processing pipeline. Handles extracting text, computing embeddings, syncing with vector store.
+ * @module processor/ProcessorConfig
+ * Configuration interface for DocumentProcessor, extracted for single-responsibility.
  */
 
 /**
@@ -521,30 +809,82 @@ interface ProcessorConfig {
     configDir?: string;
     /** Custom JsonMap lib functions loaded from mapHelpers config. */
     customMapLib?: Record<string, (...args: unknown[]) => unknown>;
+    /** Global schemas collection for inference rule schema references. */
+    globalSchemas?: Record<string, SchemaEntry>;
+}
+
+/**
+ * @module processor/types
+ * Document processor interface definitions.
+ */
+
+/**
+ * Abstraction for document processing operations.
+ *
+ * Enables factories and consumers to depend on an interface (DIP).
+ */
+interface DocumentProcessorInterface {
+    /** Process a file through the full pipeline (extract/embed/upsert). */
+    processFile(filePath: string): Promise<void>;
+    /** Delete a file's points/metadata from the system. */
+    deleteFile(filePath: string): Promise<void>;
+    /** Process a metadata sidecar update for a file (payload update only). */
+    processMetadataUpdate(filePath: string, metadata: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** Process a rules update for a file (rebuild merged metadata, payload update only). */
+    processRulesUpdate(filePath: string): Promise<Record<string, unknown> | null>;
+    /** Update compiled inference rules and associated engines. */
+    updateRules(compiledRules: CompiledRule[], templateEngine?: TemplateEngine, customMapLib?: Record<string, (...args: unknown[]) => unknown>): void;
+}
+
+/**
+ * @module processor
+ *
+ * Core document processing pipeline. Handles extracting text, computing embeddings, syncing with vector store.
+ */
+
+/**
+ * Core document processing pipeline.
+ *
+ * Handles extracting text, computing embeddings, and syncing with the vector store.
+ */
+interface DocumentProcessorDeps {
+    /** Processor configuration (chunk sizes, directories, maps). */
+    config: ProcessorConfig;
+    /** Provider for generating text embeddings. */
+    embeddingProvider: EmbeddingProvider;
+    /** Vector store for persistence. */
+    vectorStore: VectorStore;
+    /** Pre-compiled inference rules for metadata extraction. */
+    compiledRules: CompiledRule[];
+    /** Pino logger instance. */
+    logger: pino.Logger;
+    /** Optional Handlebars template engine for content templates. */
+    templateEngine?: TemplateEngine;
+    /** Optional issues manager for tracking processing errors. */
+    issuesManager?: IssuesManager;
+    /** Optional values manager for tracking rule-extracted values. */
+    valuesManager?: ValuesManager;
 }
 /**
  * Core document processing pipeline.
  *
  * Handles extracting text, computing embeddings, and syncing with the vector store.
  */
-declare class DocumentProcessor {
+declare class DocumentProcessor implements DocumentProcessorInterface {
     private config;
     private readonly embeddingProvider;
     private readonly vectorStore;
     private compiledRules;
     private readonly logger;
     private templateEngine?;
+    private readonly issuesManager?;
+    private readonly valuesManager?;
     /**
      * Create a new DocumentProcessor.
      *
-     * @param config - The processor configuration.
-     * @param embeddingProvider - The embedding provider.
-     * @param vectorStore - The vector store client.
-     * @param compiledRules - The compiled inference rules.
-     * @param logger - The logger instance.
-     * @param templateEngine - Optional template engine for content templates.
+     * @param deps - The processor dependencies.
      */
-    constructor(config: ProcessorConfig, embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: CompiledRule[], logger: pino.Logger, templateEngine?: TemplateEngine);
+    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, issuesManager, valuesManager, }: DocumentProcessorDeps);
     /**
      * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
      *
@@ -662,12 +1002,45 @@ declare class EventQueue {
     private maybeResolveDrain;
 }
 
+/**
+ * @module api/ReindexTracker
+ * Tracks reindex operation state for status reporting. Single instance shared across handlers.
+ */
+/** Reindex status snapshot for API consumers. */
+interface ReindexStatus {
+    /** Whether a reindex operation is currently in progress. */
+    active: boolean;
+    /** The active reindex scope (when {@link active} is true). */
+    scope?: string;
+    /** ISO 8601 timestamp when the current reindex started (when {@link active} is true). */
+    startedAt?: string;
+}
+/**
+ * Tracks the state of reindex operations.
+ */
+declare class ReindexTracker {
+    private _active;
+    private _scope?;
+    private _startedAt?;
+    /** Mark a reindex as started. */
+    start(scope: 'issues' | 'full'): void;
+    /** Mark the current reindex as complete. */
+    complete(): void;
+    /** Get current reindex status. */
+    getStatus(): ReindexStatus;
+}
+
+/**
+ * @module api
+ * Fastify API server factory. Registers all route handlers and returns an unstarted server instance.
+ */
+
 /**
  * Options for {@link createApiServer}.
  */
 interface ApiServerOptions {
     /** The document processor. */
-    processor: DocumentProcessor;
+    processor: DocumentProcessorInterface;
     /** The vector store client. */
     vectorStore: VectorStoreClient;
     /** The embedding provider. */
@@ -678,6 +1051,16 @@ interface ApiServerOptions {
     config: JeevesWatcherConfig;
     /** The logger instance. */
     logger: pino.Logger;
+    /** The issues manager. */
+    issuesManager: IssuesManager;
+    /** The values manager. */
+    valuesManager: ValuesManager;
+    /** The reindex tracker (optional, created if not provided). */
+    reindexTracker?: ReindexTracker;
+    /** Path to the config file on disk. */
+    configPath: string;
+    /** Helper introspection for merged document. */
+    helperIntrospection?: AllHelpersIntrospection;
 }
 /**
  * Create the Fastify API server with all routes registered.
@@ -831,7 +1214,7 @@ declare class FileSystemWatcher {
      * @param logger - The logger instance.
      * @param options - Optional health/fatal error options.
      */
-    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger, options?: FileSystemWatcherOptions);
+    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessorInterface, logger: pino.Logger, options?: FileSystemWatcherOptions);
     /**
      * Start watching the filesystem and processing events.
      */
@@ -880,11 +1263,11 @@ interface JeevesWatcherFactories {
     /** Compile inference rules from config. */
     compileRules: typeof compileRules;
     /** Create a document processor for file ingestion. */
-    createDocumentProcessor: (config: ConstructorParameters<typeof DocumentProcessor>[0], embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: ConstructorParameters<typeof DocumentProcessor>[3], logger: pino.Logger, templateEngine?: ConstructorParameters<typeof DocumentProcessor>[5]) => DocumentProcessor;
+    createDocumentProcessor: (deps: ConstructorParameters<typeof DocumentProcessor>[0]) => DocumentProcessorInterface;
     /** Create an event queue for batching file-system events. */
     createEventQueue: (options: ConstructorParameters<typeof EventQueue>[0]) => EventQueue;
     /** Create a file-system watcher for the configured watch paths. */
-    createFileSystemWatcher: (config: JeevesWatcherConfig['watch'], queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger, options?: FileSystemWatcherOptions) => FileSystemWatcher;
+    createFileSystemWatcher: (config: JeevesWatcherConfig['watch'], queue: EventQueue, processor: DocumentProcessorInterface, logger: pino.Logger, options?: FileSystemWatcherOptions) => FileSystemWatcher;
     /** Create the HTTP API server. */
     createApiServer: typeof createApiServer;
 }
@@ -928,6 +1311,9 @@ declare class JeevesWatcher {
     private server;
     private processor;
     private configWatcher;
+    private issuesManager;
+    private valuesManager;
+    private helperIntrospection;
     /**
      * Create a new JeevesWatcher instance.
      *
@@ -945,8 +1331,6 @@ declare class JeevesWatcher {
      * Gracefully stop all components.
      */
     stop(): Promise<void>;
-    private initEmbeddingAndStore;
-    private createWatcher;
     private startApiServer;
     private startConfigWatch;
     private stopConfigWatch;
@@ -978,14 +1362,16 @@ interface ExtractedText {
     /** Parsed JSON object (JSON files). */
     json?: Record<string, unknown>;
 }
+type Extractor = (filePath: string) => Promise<ExtractedText>;
 /**
  * Extract text from a file based on extension.
  *
  * @param filePath - Path to the file.
  * @param extension - File extension (including leading dot).
+ * @param additionalExtractors - Optional map of additional extractors by extension.
  * @returns Extracted text and optional structured data.
  */
-declare function extractText(filePath: string, extension: string): Promise<ExtractedText>;
+declare function extractText(filePath: string, extension: string, additionalExtractors?: Map<string, Extractor>): Promise<ExtractedText>;
 
 /**
  * Compute a SHA-256 hex digest of the given text.
@@ -1036,5 +1422,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, TemplateEngine, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
-export type { ApiConfig, ApiServerOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, FileSystemWatcherOptions, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };
+export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, 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 { ApiConfig, ApiServerOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, FileSystemWatcherOptions, InferenceRule, IssueRecord, IssuesFile, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, ReindexStatus, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };