@karmaniverous/jeeves-watcher 0.19.1 → 0.21.0-0

package/dist/index.d.ts

@@ -1,24 +1,59 @@
-import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
 import { FastifyInstance } from 'fastify';
+import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
+import { EmbeddingConfig, IssueRecord, InferenceRule, SchemaEntry, SourcesConfig, VectorStoreConfig, DocumentResult, DocumentRejectionError, DocumentFailure, VcsRetentionConfig, VcsConfig, JeevesWatcherConfig, VcsHealth, InitialScanStatus, RestartCause, ConfigWatchReindexScope, ChangeSourceHealth, WatchConfig, ReindexStatus, IndexCheckHealth, LoggingConfig } from '@karmaniverous/jeeves-watcher-core';
+export { ApiConfig, ConfigWatchConfig, EmbeddingConfig, InferenceRule, InitialScanStatus, IssueRecord, JeevesWatcherConfig, JeevesWatcherConfigInput, LoggingConfig, ReindexStatus, VectorStoreConfig, WatchConfig, apiConfigSchema, configWatchConfigSchema, embeddingConfigSchema, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loggingConfigSchema, vectorStoreConfigSchema, watchConfigSchema } from '@karmaniverous/jeeves-watcher-core';
 import pino from 'pino';
-import { EmbeddingConfig, InferenceRule, SchemaEntry, VectorStoreConfig, VcsConfig, JeevesWatcherConfig, WatchConfig, LoggingConfig, VcsRetentionConfig } from '@karmaniverous/jeeves-watcher-core';
-export { ApiConfig, ConfigWatchConfig, EmbeddingConfig, InferenceRule, JeevesWatcherConfig, JeevesWatcherConfigInput, LoggingConfig, VectorStoreConfig, WatchConfig, apiConfigSchema, configWatchConfigSchema, embeddingConfigSchema, inferenceRuleSchema, jeevesWatcherConfigSchema, loggingConfigSchema, vectorStoreConfigSchema, watchConfigSchema } from '@karmaniverous/jeeves-watcher-core';
-import { z } from 'zod';
+import { ErrorObject } from 'ajv';
 import Handlebars from 'handlebars';
-import { JsonMapMap } from '@karmaniverous/jsonmap';
+import { z } from 'zod';
 import { Stats } from 'node:fs';
+import ParcelWatcher from '@parcel/watcher';
+import { JsonMapMap } from '@karmaniverous/jsonmap';
 
 /**
  * @module embedding/types
  * Embedding provider type definitions.
  */
 
+/**
+ * Per-call budget for the shared rate limiter. Providers that do not
+ * rate-limit ignore the budget; providers that retry internally await
+ * `beforeRetry` before each retry.
+ *
+ * The budget bounds the limiter, not the provider's own network retries:
+ * each of the `attempts` provider calls may itself retry a transient
+ * (non-429) failure up to `NETWORK_RETRY_POLICY.attempts` times in all, with
+ * backoff sleeps, so one `embed()` can issue up to `attempts` x 5 HTTP
+ * requests.
+ */
+interface EmbedOptions {
+    /**
+     * Maximum provider calls for this call: a 429 ends a provider call and
+     * costs one attempt. Transient network retries inside a provider call do
+     * not count against it (see the interface note).
+     */
+    attempts?: number;
+    /**
+     * Maximum total time to wait for the limiter (token or `Retry-After`
+     * pause), in ms. When a wait would exceed it, the call fails fast. The
+     * provider's own network-retry backoff sleeps are not counted.
+     */
+    maxWaitMs?: number;
+    /**
+     * Awaited by a provider before each retry it makes internally (any HTTP
+     * request after the first of an `embed()` call), so every request draws
+     * from the shared limiter. Supplied by the rate-limited wrapper; it may
+     * reject (e.g. `EmbeddingUnavailableError`), which the provider must
+     * propagate without retrying.
+     */
+    beforeRetry?: () => Promise<void>;
+}
 /**
  * An embedding provider that converts text into vector representations.
  */
 interface EmbeddingProvider {
-    /** Generate embedding vectors for the given texts. */
-    embed(texts: string[]): Promise<number[][]>;
+    /** Generate embedding vectors for the given texts (one provider request). */
+    embed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
     /** The dimensionality of the embedding vectors. */
     dimensions: number;
 }
@@ -46,9 +81,41 @@ type ProviderFactory = (config: EmbeddingConfig, logger?: pino.Logger) => Embedd
  */
 declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger, additionalProviders?: Map<string, ProviderFactory>): EmbeddingProvider;
 
+/**
+ * @module embedding/EmbeddingHealth
+ * Embedding health (D86, D88, D89): wraps the shared rate-limited provider and tracks ok/failing (3+ failures since the last success and 60 s without one), with transition logs and alerts. Health shows codes, never provider text.
+ *
+ * A rate-limit wait that later succeeds is not a failure; any error a call
+ * throws (including a fail-fast `EmbeddingUnavailableError`) is. The first
+ * success returns the state to `ok`.
+ */
+
+/** Embedding health state. */
+type EmbeddingHealthState = 'ok' | 'failing';
+/** The most recent embedding error: when, and a machine-readable code. */
+interface EmbeddingErrorSummary {
+    /** ISO timestamp. */
+    at: string;
+    /** `rate_limited`, `timeout`, `http_<status>`, `network` or `error`. */
+    code: string;
+}
+/** `GET /status` `health.embedding`. */
+interface EmbeddingHealthSnapshot {
+    /** `ok` or `failing`. */
+    state: EmbeddingHealthState;
+    /** Last successful call (ISO), `null` before the first. */
+    lastSuccessAt: string | null;
+    /** Most recent error, `null` if none yet. */
+    lastError: EmbeddingErrorSummary | null;
+    /** When the state turned `failing` (ISO), `null` while `ok`. */
+    failingSince: string | null;
+    /** End of the stored provider back-off (ISO), `null` if none. */
+    backoffUntil: string | null;
+}
+
 /**
  * @module enrichment/EnrichmentStore
- * SQLite-backed enrichment metadata store. Persists path-keyed metadata at stateDir/enrichments.sqlite. Atomic writes, supports move.
+ * SQLite-backed enrichment metadata store. Persists path- or source-reference-keyed metadata (references verbatim) at stateDir/enrichments.sqlite. Atomic writes, supports move.
  */
 
 /**
@@ -188,95 +255,44 @@ declare abstract class JsonFileStore<T> {
 
 /**
  * @module issues/types
- * Zod schemas and TypeScript types for the issues tracking system. Defines IssueRecord and IssuesFile structures.
+ * Issue record schema and types for the issues tracking system. IssueRecord is defined in core (GET /issues response); IssuesFile is the on-disk shape.
  */
 
-/** Schema for a single issue record tracking a processing failure. */
-declare const issueRecordSchema: z.ZodObject<{
-    type: z.ZodUnion<readonly [z.ZodLiteral<"type_collision">, z.ZodLiteral<"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 persistent issue tracking for processing failures, keyed by document key (file path or source reference). Read-modify-write with in-memory cache.
  */
 
 /**
- * Manages a persistent issues.json file tracking processing failures per file.
+ * Manages a persistent issues.json file tracking processing failures per
+ * document key (file path or source reference).
  */
 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;
+    /**
+     * Record an issue for a document key (file path or source reference).
+     *
+     * @param key - Document key (file path or source reference).
+     * @param type - Canonical issue code.
+     * @param message - Error message.
+     * @param options - Optional operation, property, rule(s), types and
+     *   structured `details` (stored as JSON, e.g. AJV errors).
+     */
+    record(key: string, type: IssueRecord['type'], message: string, options?: Pick<IssueRecord, 'operation' | 'property' | 'rules' | 'rule' | 'types' | 'details'>): void;
+    /** Clear the issues of a document key (called on successful processing). */
+    clear(key: string): void;
     /** Wipe all issues (called on full reindex start). */
     clearAll(): void;
+    /** Get the current issues of one document key, if any. */
+    get(key: string): IssueRecord[] | undefined;
     /** Get all current issues. */
     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).
@@ -391,6 +407,29 @@ declare function buildTemplateEngine(rules: InferenceRule[], namedTemplates?: Re
  */
 declare function registerBuiltinHelpers(hbs: typeof Handlebars): void;
 
+/**
+ * @module rules/sourceAttributes
+ * Zod schema and builder for source-document rule attributes (`source` identity block + `json` record; no `file` key). Pure, no I/O.
+ */
+
+/**
+ * Attributes a source document is matched and resolved against. There is no
+ * `file` key, so file rules (`file.path` globs) never match a source
+ * document, and a source rule (`required: ["source"]`) never matches a file.
+ */
+declare const sourceAttributesSchema: z.ZodObject<{
+    source: z.ZodObject<{
+        ref: z.ZodString;
+        name: z.ZodString;
+        id: z.ZodString;
+        rule: z.ZodString;
+        retrievedAt: z.ZodString;
+    }, z.core.$strip>;
+    json: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Attributes of a source document. */
+type SourceAttributes = z.infer<typeof sourceAttributesSchema>;
+
 /**
  * @module rules/attributes
  * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
@@ -420,6 +459,8 @@ interface FileAttributes {
     /** Parsed JSON content, if any. */
     json?: Record<string, unknown>;
 }
+/** Attributes rules are matched and resolved against: a file or a source document. */
+type RuleAttributes = FileAttributes | SourceAttributes;
 /**
  * Build {@link FileAttributes} from a file path and stat info.
  *
@@ -442,8 +483,13 @@ declare function buildAttributes(filePath: string, stats: Stats, extractedFrontm
 interface CompiledRule {
     /** The original rule definition. */
     rule: InferenceRule;
-    /** The compiled AJV validate function. */
-    validate: (data: unknown) => boolean;
+    /**
+     * The compiled AJV validate function. After a failed call, `errors` holds
+     * the AJV errors (used for `match_failed` issues).
+     */
+    validate: ((data: unknown) => boolean) & {
+        errors?: ErrorObject[] | null;
+    };
 }
 /**
  * Compile an array of inference rules into executable validators.
@@ -454,9 +500,31 @@ interface CompiledRule {
  */
 declare function compileRules(rules: InferenceRule[]): CompiledRule[];
 
+/**
+ * @module rules/ruleErrors
+ * Interpolation errors collected while applying rules (schema `set` resolution, `render`, `template`): Zod schema, type and one-line formatting. Pure.
+ */
+
+/**
+ * One interpolation failure of a matched rule. The rule's output for that
+ * stage is missing (schema failure: the rule's metadata, map and render are
+ * skipped; render/template failure: the raw content is used instead).
+ */
+declare const ruleApplicationErrorSchema: z.ZodObject<{
+    rule: z.ZodString;
+    stage: z.ZodEnum<{
+        schema: "schema";
+        render: "render";
+        template: "template";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+/** One interpolation failure of a matched rule. */
+type RuleApplicationError = z.infer<typeof ruleApplicationErrorSchema>;
+
 /**
  * @module rules/apply
- * Applies compiled inference rules to file attributes, producing merged metadata via template resolution and JsonMap transforms.
+ * Applies compiled inference rules to file or source attributes, producing merged metadata via schema resolution, JsonMap transforms and render/template output; collects interpolation errors.
  */
 
 /**
@@ -478,6 +546,11 @@ interface ApplyRulesResult {
     matchedRules: string[];
     /** The renderAs value from the last matching rule that declares it, or null. */
     renderAs: string | null;
+    /**
+     * Interpolation failures (schema `set` resolution, `render`, `template`)
+     * of matched rules, in order. Each was also logged as a warning.
+     */
+    errors: RuleApplicationError[];
 }
 /**
  * Optional parameters for applyRules beyond the required compiledRules and attributes.
@@ -503,14 +576,16 @@ interface ApplyRulesOptions {
  *
  * 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.
+ * and map output overrides set output on conflict. A failing schema, render
+ * or template is logged and reported in `errors`; the rule's output for that
+ * stage is skipped (a schema failure skips the rest of the rule).
  *
  * @param compiledRules - The compiled rules to evaluate.
- * @param attributes - The file attributes to match against.
+ * @param attributes - The file or source attributes to match against.
  * @param options - Optional configuration for rule application.
- * @returns The merged metadata and optional rendered content.
+ * @returns The merged metadata, optional rendered content and errors.
  */
-declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, options?: ApplyRulesOptions): Promise<ApplyRulesResult>;
+declare function applyRules(compiledRules: CompiledRule[], attributes: RuleAttributes, options?: ApplyRulesOptions): Promise<ApplyRulesResult>;
 
 /**
  * @module rules/virtualRules
@@ -560,6 +635,242 @@ declare class VirtualRuleStore {
     get size(): number;
 }
 
+/**
+ * @module processor/DocumentLocks
+ * One in-process FIFO lock per document key (D98): every process, delete, move, too_large and metadata change of a document runs under it. API routes wait at most 10 s, then 503 (D118). Idle locks are dropped.
+ *
+ * Keys: the normalised file path (the same normalisation as point IDs) or
+ * the source reference. A move takes both keys in sorted order, so two moves
+ * cannot deadlock.
+ */
+
+/** Options of one locked operation. */
+interface DocumentLockOptions {
+    /** Longest wait for the lock (omit: unbounded, as for background work). */
+    lockWaitMs?: number;
+}
+/**
+ * The lock key of a file.
+ *
+ * @param filePath - The file path, as given.
+ * @returns The normalised path (lower-case, forward slashes).
+ */
+declare function fileLockKey(filePath: string): string;
+/** The per-document locks of one processor. */
+declare class DocumentLocks {
+    private readonly logger;
+    private readonly locks;
+    /** @param logger - Logger for long-hold warnings. */
+    constructor(logger: pino.Logger);
+    /** Number of keys currently locked or waited for. */
+    get size(): number;
+    /**
+     * Run `work` under the lock of `key`.
+     *
+     * @param key - Document key ({@link fileLockKey} or a source reference).
+     * @param operation - Operation name (warnings, timeout error).
+     * @param work - The work (must not take the same key again).
+     * @param options - Bounded wait.
+     * @returns What `work` returns.
+     * @throws DocumentLockTimeoutError when a bounded wait runs out.
+     */
+    run<T>(key: string, operation: string, work: () => Promise<T>, options?: DocumentLockOptions): Promise<T>;
+    /**
+     * Run `work` holding the locks of every key, taken one at a time in sorted
+     * order (duplicates once).
+     *
+     * @param keys - Document keys.
+     * @param operation - Operation name.
+     * @param work - The work.
+     * @param options - Bounded wait (per lock).
+     * @returns What `work` returns.
+     */
+    runAll<T>(keys: string[], operation: string, work: () => Promise<T>, options?: DocumentLockOptions): Promise<T>;
+    private lockFor;
+}
+
+/**
+ * @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 sources/types
+ * Zod schemas and derived types for source callback outcomes (document / gone / error) and reference rejections. Pure declarations; no I/O.
+ */
+
+/**
+ * Error codes a source callback can produce: the subset of the canonical
+ * issue codes that belong to retrieval.
+ */
+declare const sourceErrorCodeSchema: z.ZodEnum<{
+    source_unavailable: "source_unavailable";
+    unsupported_content_type: "unsupported_content_type";
+}>;
+/** A source callback error code. */
+type SourceErrorCode = z.infer<typeof sourceErrorCodeSchema>;
+/** Outcome of one source callback (discriminated on `kind`). */
+declare const sourceRetrievalResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"document">;
+    body: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"gone">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    code: z.ZodEnum<{
+        source_unavailable: "source_unavailable";
+        unsupported_content_type: "unsupported_content_type";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>], "kind">;
+/** Outcome of one source callback. */
+type SourceRetrievalResult = z.infer<typeof sourceRetrievalResultSchema>;
+/**
+ * Why a reference was rejected before any request was made:
+ * `invalid_reference` (not `<name>://<id>`), `unknown_source` (name not in
+ * config `sources`), `invalid_id` (empty, `.` or `..` segment, or the built
+ * URL would leave the configured origin). The reference-level subset of
+ * core `documentRejectionCodeSchema`.
+ */
+declare const sourceRejectionCodeSchema: z.ZodEnum<{
+    invalid_reference: "invalid_reference";
+    unknown_source: "unknown_source";
+    invalid_id: "invalid_id";
+}>;
+/** A reference rejection code. */
+type SourceRejectionCode = z.infer<typeof sourceRejectionCodeSchema>;
+/** A parsed `<name>://<id>` reference. */
+declare const parsedSourceReferenceSchema: z.ZodObject<{
+    ref: z.ZodString;
+    name: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+/** A parsed `<name>://<id>` reference. */
+type ParsedSourceReference = z.infer<typeof parsedSourceReferenceSchema>;
+/** A reference resolved against config: parsed parts plus the URL to request. */
+declare const resolvedSourceReferenceSchema: z.ZodObject<{
+    ref: z.ZodString;
+    name: z.ZodString;
+    id: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+/** A reference resolved against config. */
+type ResolvedSourceReference = z.infer<typeof resolvedSourceReferenceSchema>;
+/**
+ * Thrown (or rejected) when a reference cannot be retrieved for a reason
+ * known before any request is made. No request is ever sent for a rejected
+ * reference.
+ */
+declare class SourceReferenceError extends Error {
+    /** Rejection code. */
+    readonly code: SourceRejectionCode;
+    /**
+     * @param code - Rejection code.
+     * @param message - Human-readable reason (never contains header values).
+     */
+    constructor(code: SourceRejectionCode, message: string);
+}
+
+/**
+ * @module sources/SourceClient
+ * Registry of configured sources: resolves `<name>://<id>` to a config-built URL and retrieves it with per-source concurrency caps. Network I/O via requestSource.
+ */
+
+/**
+ * Retrieves source documents by callback. Injected into later pipeline
+ * stages (resolver, notify queue, reindex) so tests can substitute it.
+ */
+interface SourceRetriever {
+    /**
+     * Validate a reference and build its URL without making a request.
+     *
+     * @throws {@link SourceReferenceError}
+     */
+    resolve(reference: string): ResolvedSourceReference;
+    /**
+     * Retrieve a document. Rejects with {@link SourceReferenceError} (and
+     * sends nothing) for an invalid reference; otherwise never rejects.
+     */
+    retrieve(reference: string): Promise<SourceRetrievalResult>;
+}
+/**
+ * The source callback client. Constructed once from the parsed `sources`
+ * config (defaults applied, `${ENV}` already substituted at load). Each
+ * source gets its own concurrency semaphore; the `timeoutMs` clock starts
+ * when a request leaves the queue, not while it waits for a slot. Callbacks
+ * do not draw from the embedding rate limiter.
+ */
+declare class SourceClient implements SourceRetriever {
+    private readonly entries;
+    /**
+     * @param sources - The parsed `sources` config section.
+     * @throws Error when a `url` template is not an absolute http(s) URL or
+     *   places `{id}` in its origin (scheme, host or port).
+     */
+    constructor(sources?: SourcesConfig);
+    /** {@inheritDoc SourceRetriever.resolve} */
+    resolve(reference: string): ResolvedSourceReference;
+    /** {@inheritDoc SourceRetriever.retrieve} */
+    retrieve(reference: string): Promise<SourceRetrievalResult>;
+    private resolveEntry;
+}
+
+/**
+ * @module sources/sourceUrl
+ * Pure helpers: parse `<name>://<id>` references, encode ids segment-by-segment, and build callback URLs from a configured template. No I/O.
+ */
+
+/**
+ * Parse a source reference.
+ *
+ * @param reference - A `<name>://<id>` string.
+ * @returns The parsed reference.
+ * @throws {@link SourceReferenceError} `invalid_reference` when the string
+ *   does not match the core reference schema.
+ */
+declare function parseSourceReference(reference: string): ParsedSourceReference;
+
 /**
  * @module util/BinaryFileStore
  * Binary-backed read/modify/write store with in-memory caching and debounced flush.
@@ -619,7 +930,7 @@ declare abstract class BinaryFileStore<T> {
 /** 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.
+ * Manages a persistent values.v8 file tracking distinct metadata values per rule.
  */
 declare class ValuesManager extends BinaryFileStore<ValuesIndex> {
     constructor(stateDir: string, logger: pino.Logger);
@@ -636,6 +947,74 @@ declare class ValuesManager extends BinaryFileStore<ValuesIndex> {
     getForRule(ruleName: string): Record<string, unknown[]>;
 }
 
+/**
+ * @module vectorStore/systemIndexes
+ * System payload indexes (D74, D154, D155): created at startup by background wait=true calls (startup never waits), reported as building, ready, conflict or failed; plus keyword-index readiness for by-filter writes. Qdrant I/O.
+ *
+ * `chunk_index` (integer) lets `countFacets` count documents, not chunks;
+ * `file_path` (keyword) serves metadata writes by filter (D139);
+ * `matched_rules` (keyword) serves rule-scoped counts (D155). A field
+ * already indexed with another type is left alone (`conflict`): writes keep
+ * using ID addressing, and `countFacets` answers 503 naming the index.
+ */
+
+/** State of one system index (`GET /status` `health.collection.systemIndexes`). */
+type SystemIndexState = 'building' | 'ready' | 'conflict' | 'failed';
+
+/**
+ * @module vectorStore/facets
+ * Qdrant reads behind `countFacets` (spec Design 12): approximate facet counts (D194), one-point ordered scrolls for a field's range, and the collection's payload index types. Every count and scroll passes Qdrant's `timeout` (whole seconds) so an abandoned call also stops in Qdrant. Qdrant I/O.
+ */
+
+/** A facet value as Qdrant reports it. */
+type FacetValue = string | number | boolean;
+/** One counted value. */
+interface FacetHit {
+    /** The payload value. */
+    value: FacetValue;
+    /** Points holding it. */
+    count: number;
+}
+/** Which end of a range an ordered scroll reads. */
+type RangeEnd = 'min' | 'max';
+/** A range bound: a number, a stored date string, or null when nothing matched. */
+type RangeBound = number | string | null;
+/** One facet count or range read: field, filter and Qdrant timeout. */
+interface FacetRead {
+    /** Payload field. */
+    field: string;
+    /** Qdrant filter (already scoped by the caller). */
+    filter: Record<string, unknown>;
+    /** Qdrant `timeout` query parameter, whole seconds. */
+    timeoutS: number;
+}
+/** Facet reads used by `countFacets` (`VectorStoreClient.facets`). */
+interface FacetStore {
+    /**
+     * Approximate value counts of a field, highest first (D194).
+     *
+     * @param read - Field, filter and timeout.
+     * @param limit - Most values returned.
+     * @returns The counted values.
+     */
+    facetCounts(read: FacetRead, limit: number): Promise<FacetHit[]>;
+    /**
+     * One end of a field's range over the filter.
+     *
+     * @param read - Field, filter and timeout.
+     * @param end - `min` or `max`.
+     * @returns The bound, or null when no point holds the field.
+     */
+    rangeBound(read: FacetRead, end: RangeEnd): Promise<RangeBound>;
+    /** @returns Payload index type by field (`keyword`, `integer`, ...). */
+    payloadIndexTypes(): Promise<Record<string, string>>;
+    /**
+     * @param field - A system index field (`chunk_index`, `matched_rules`).
+     * @returns Its state, or undefined before startup.
+     */
+    systemIndexState(field: string): SystemIndexState | undefined;
+}
+
 /**
  * @module vectorStore/types
  * Vector store interface and type definitions.
@@ -730,11 +1109,50 @@ interface VectorStore {
      * @param payload - Payload fields to set.
      */
     setPayload(ids: string[], payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove payload keys from the specified point IDs (other keys kept).
+     *
+     * @param ids - Point IDs to update.
+     * @param keys - Payload keys to remove.
+     */
+    deletePayload(ids: string[], keys: string[]): Promise<void>;
+    /**
+     * Whether `field` has a ready `keyword` payload index, so a by-filter
+     * write on it is cheap (D154). A system index counts once its background
+     * build returned; any other field when it was keyword-indexed at startup.
+     *
+     * @param field - Payload field.
+     * @returns True when by-filter writes on `field` may be used.
+     */
+    keywordIndexReady(field: string): boolean;
+    /**
+     * Set payload fields on every point matching a filter (D139).
+     *
+     * @param filter - Qdrant filter selecting one document's points.
+     * @param payload - Payload fields to set.
+     */
+    setPayloadWhere(filter: Record<string, unknown>, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove payload keys from every point matching a filter (D139).
+     *
+     * @param filter - Qdrant filter selecting one document's points.
+     * @param keys - Payload keys to remove.
+     */
+    deletePayloadWhere(filter: Record<string, unknown>, keys: string[]): Promise<void>;
+    /**
+     * The IDs among `ids` that exist, in the given order (no payload, no
+     * vectors; needs no index, D154).
+     *
+     * @param ids - Candidate point IDs.
+     * @returns The existing IDs.
+     */
+    existingIds(ids: string[]): Promise<string[]>;
     /**
      * Get the payload of a point by ID.
      *
      * @param id - The point ID.
      * @returns The payload, or `null` if the point doesn't exist.
+     * @throws When the read fails (never reported as a missing point).
      */
     getPayload(id: string): Promise<Record<string, unknown> | null>;
     /**
@@ -796,19 +1214,29 @@ interface VectorStore {
     getPointsWithVectors(ids: string[]): Promise<VectorPoint[]>;
 }
 
+/**
+ * @module vectorStore
+ * Qdrant-backed {@link VectorStore}: collection setup, retried writes (see `writes`), payload reads, search, hybrid search and scrolling. Qdrant I/O.
+ */
+
 /**
  * Client wrapper for Qdrant vector store operations.
  *
  * Implements the {@link VectorStore} interface for dependency inversion.
+ * Writes (upsert, delete, set/delete payload) are retried, each retry on a
+ * fresh client (see QdrantWriter).
  */
 declare class VectorStoreClient implements VectorStore {
+    /** Facet reads behind `countFacets` (spec Design 12). */
+    readonly facets: FacetStore;
     private readonly client;
-    private writeClient;
+    private readonly writer;
     private readonly clientConfig;
     private readonly collectionName;
     private readonly dims;
-    private readonly log;
     private readonly pinoLogger?;
+    private readonly payloadIndexes;
+    private readonly systemIndexes;
     /**
      * Create a new VectorStoreClient.
      *
@@ -823,123 +1251,71 @@ declare class VectorStoreClient implements VectorStore {
      * Used to avoid stale HTTP keep-alive connections. The Qdrant JS client's
      * internal undici Agent uses keepAliveTimeout: 10s, which causes ECONNRESET
      * when connections sit idle during slow embedding calls (Gemini p99 ~8s).
-     * Creating a fresh client for write operations ensures clean TCP connections.
+     * Writes therefore run on their own client, replaced on every retry
+     * (see QdrantWriter).
      */
     private createClient;
-    /**
-     * Count points matching a filter.
-     *
-     * @param filter - Optional Qdrant filter.
-     * @returns The number of matching points.
-     */
+    /** {@inheritDoc VectorStore.count} */
     count(filter?: Record<string, unknown>): Promise<number>;
     /**
-     * Ensure the collection exists with correct dimensions and Cosine distance.
+     * Ensure the collection exists (Cosine, configured dimensions) and create
+     * any missing payload indexes (configured plus `source`/`source_rule`),
+     * then start the background system-index builds (D74, D154; not awaited).
      */
     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;
-    private getWriteClient;
-    /**
-     * Upsert points into the collection.
-     *
-     * Uses the shared client. On retry (after ECONNRESET from stale connections),
-     * creates a fresh client to recover.
-     *
-     * @param points - The points to upsert.
-     */
+    /** @returns Each system index's state (`health.collection.systemIndexes`). */
+    systemIndexStates(): Record<string, SystemIndexState>;
+    /** @returns A promise settling once the background index builds end. */
+    whenSystemIndexesSettled(): Promise<void>;
+    /** {@inheritDoc VectorStore.keywordIndexReady} */
+    keywordIndexReady(field: string): boolean;
+    /** {@inheritDoc VectorStore.setPayloadWhere} */
+    setPayloadWhere(filter: Record<string, unknown>, payload: Record<string, unknown>): Promise<void>;
+    /** {@inheritDoc VectorStore.deletePayloadWhere} */
+    deletePayloadWhere(filter: Record<string, unknown>, keys: string[]): Promise<void>;
+    /** {@inheritDoc VectorStore.existingIds} */
+    existingIds(ids: string[]): Promise<string[]>;
+    /** {@inheritDoc VectorStore.upsert} */
     upsert(points: VectorPoint[]): Promise<void>;
-    /**
-     * Delete points by their IDs.
-     *
-     * Uses the shared client. On retry, creates a fresh client to recover.
-     *
-     * @param ids - The point IDs to delete.
-     */
+    /** {@inheritDoc VectorStore.delete} */
     delete(ids: string[]): Promise<void>;
-    /**
-     * Set payload fields for the specified point IDs.
-     *
-     * This merges the given payload object into each point's existing payload.
-     *
-     * @param ids - Point IDs to update.
-     * @param payload - Payload fields to set.
-     */
+    /** {@inheritDoc VectorStore.setPayload} */
     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.
-     */
+    /** {@inheritDoc VectorStore.deletePayload} */
+    deletePayload(ids: string[], keys: string[]): Promise<void>;
+    /** {@inheritDoc VectorStore.getPayload} */
     getPayload(id: string): Promise<Record<string, unknown> | null>;
-    /**
-     * Get collection info including point count, dimensions, and payload field schema.
-     *
-     * When Qdrant has payload indexes, uses `payload_schema` directly. Otherwise
-     * samples points to discover fields and infer types.
-     */
+    /** {@inheritDoc VectorStore.getCollectionInfo} */
     getCollectionInfo(): Promise<CollectionInfo>;
-    /**
-     * Search for similar vectors.
-     *
-     * @param vector - The query vector.
-     * @param limit - Maximum results to return.
-     * @param filter - Optional Qdrant filter.
-     * @returns An array of search results.
-     */
+    /** {@inheritDoc VectorStore.search} */
     search(vector: number[], limit: number, filter?: Record<string, unknown>, offset?: number): Promise<SearchResult[]>;
-    /**
-     * Create a full-text payload index on the specified field.
-     * Idempotent — skips if the field already has a text index.
-     *
-     * @param fieldName - The payload field to index.
-     */
+    /** {@inheritDoc VectorStore.ensureTextIndex} */
     ensureTextIndex(fieldName: string): Promise<void>;
-    /**
-     * Hybrid search combining dense vector and full-text match with RRF fusion.
-     *
-     * @param vector - The query vector.
-     * @param queryText - The raw query text for full-text matching.
-     * @param limit - Maximum results to return.
-     * @param textWeight - Weight for text results in RRF (0–1).
-     * @param filter - Optional Qdrant filter.
-     * @param offset - Optional result offset for pagination.
-     * @returns An array of search results.
-     */
+    /** {@inheritDoc VectorStore.hybridSearch} */
     hybridSearch(vector: number[], queryText: string, limit: number, textWeight: number, filter?: Record<string, unknown>, offset?: number): 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.
-     */
+    /** {@inheritDoc VectorStore.getPointsWithVectors} */
     getPointsWithVectors(ids: string[]): Promise<VectorPoint[]>;
-    /**
-     * Scroll one page of points matching a filter.
-     *
-     * @param filter - Optional Qdrant filter.
-     * @param limit - Page size.
-     * @param offset - Cursor offset from previous page.
-     * @param fields - Optional field projection.
-     * @returns Page of points and next cursor.
-     */
+    /** {@inheritDoc VectorStore.scrollPage} */
     scrollPage(filter?: Record<string, unknown>, limit?: number, offset?: string | number, fields?: string[]): Promise<ScrollPageResult>;
-    /**
-     * Scroll through all points matching a filter.
-     *
-     * @param filter - Optional Qdrant filter.
-     * @param limit - Page size for scrolling.
-     * @yields Scrolled points.
-     */
+    /** {@inheritDoc VectorStore.scroll} */
     scroll(filter?: Record<string, unknown>, limit?: number): AsyncGenerator<ScrolledPoint>;
 }
 
+/**
+ * @module processor/processingLimits
+ * Resolve the `processing` ceilings (D44, D64) from the live config to bytes and a chunk count; read per document, so a reload applies to the next one. Pure.
+ */
+
+/** The resolved ceilings. */
+interface ProcessingLimits {
+    /** Largest file processed (bytes, checked with `stat` before extraction). */
+    maxFileBytes: number;
+    /** Most chunks one document may split into. */
+    maxChunksPerFile: number;
+    /** Largest extracted text (UTF-8 bytes). */
+    maxTextBytes: number;
+}
+
 /**
  * @module processor/ProcessorConfig
  * Configuration interface for DocumentProcessor, extracted for single-responsibility.
@@ -963,10 +1339,48 @@ interface ProcessorConfig {
     globalSchemas?: Record<string, SchemaEntry>;
 }
 
+/**
+ * @module processor/DocumentProcessorDeps
+ * Constructor dependencies for DocumentProcessor (config, embedding provider, vector store, rules, optional stores), extracted for single-responsibility.
+ */
+
+/**
+ * Dependencies injected into DocumentProcessor.
+ */
+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 enrichment store for persisted enrichment metadata. */
+    enrichmentStore?: EnrichmentStoreInterface;
+    /** Optional issues manager; processing failures are recorded as typed issues (#255). */
+    issuesManager?: IssuesManager;
+    /** Optional values manager for tracking rule-extracted values. */
+    valuesManager?: ValuesManager;
+    /** Optional content hash cache for move detection. */
+    contentHashCache?: ContentHashCache;
+    /** Optional source callback client; without it, source documents fail `source_unavailable`. */
+    sourceRetriever?: SourceRetriever;
+    /** Per-document locks (D98); default: the processor's own. */
+    documentLocks?: DocumentLocks;
+    /** The processing ceilings, read per document (D44); default: every default. */
+    getProcessingLimits?: () => ProcessingLimits;
+}
+
 /**
  * @module processor/renderResult
- * Type definition for the render endpoint result.
+ * The render endpoint result and its one constructor from a resolved document (file or source). Pure, no I/O.
  */
+
 /**
  * Result returned by {@link DocumentProcessorInterface.renderFile}.
  */
@@ -983,6 +1397,73 @@ interface RenderResult {
     transformed: boolean;
 }
 
+/**
+ * @module processor/documentPipeline
+ * The shared indexing pipeline for resolved documents (file or source): onResolved hook, empty check, text and chunk ceilings (too_large), hash compare, streamed embed and upsert; plus point deletion.
+ */
+
+/**
+ * Options for indexing one document (see
+ * {@link SourceOperationsInterface.process}).
+ */
+interface IndexOptions {
+    /**
+     * Re-embed and rewrite even when the content hash is unchanged (source
+     * documents on a `full` reindex).
+     */
+    force?: boolean;
+}
+
+/**
+ * @module processor/SourceOperations
+ * Source-document operations for the API: notify validation (reference, configured source, rule), stored designated rule lookup, uncached render, metadata enrichment and processing. Qdrant and callback I/O.
+ */
+
+/** Outcome of rendering a source document (`POST /render { source }`). */
+type SourceRenderOutcome = {
+    kind: 'rendered';
+    result: RenderResult;
+} | {
+    kind: 'gone';
+} | {
+    kind: 'failed';
+    error: DocumentFailure;
+};
+/** Source-document operations used by the API. */
+interface SourceOperationsInterface {
+    /** Process a reference with its designated rule (see `processSourceDocument`); `force` re-embeds unchanged content. */
+    process(ref: string, rule: string, options?: IndexOptions): Promise<DocumentResult>;
+    /** Synchronously validate a notification; `undefined` when acceptable. */
+    validate(ref: string, rule: string): DocumentRejectionError | undefined;
+    /** Designated rule stored on the document's chunk-0 point, or `null` if not indexed. */
+    storedRule(ref: string): Promise<string | null>;
+    /**
+     * The compiled rule a designated rule name resolves to in the merged rule
+     * set (config rules, then virtual rules: first of that name), or
+     * `undefined` when no such rule exists.
+     */
+    compiledRule(name: string): CompiledRule | undefined;
+    /** Retrieve and render a document without embedding or writing anything. */
+    render(ref: string, rule: string): Promise<SourceRenderOutcome>;
+    /**
+     * Merge enrichment metadata into an indexed document's points; `null` if
+     * not indexed. `options.lockWaitMs` bounds the document-lock wait (D118).
+     */
+    updateMetadata(ref: string, metadata: Record<string, unknown>, options?: DocumentLockOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * Run `work` under the processor's document lock of `ref` (D98), e.g. a
+     * whole-document delete. `ref` is any document key: a source reference,
+     * or `fileLockKey(path)` for a file (`POST /rebuild-metadata`).
+     * `options.lockWaitMs` bounds the wait (D118).
+     */
+    withLock<T>(ref: string, operation: string, work: () => Promise<T>, options?: DocumentLockOptions): Promise<T>;
+}
+/** A processor exposing source operations (`DocumentProcessor` implements it). */
+interface SourceOperationsProvider {
+    /** Source operations bound to the processor's current rules and stores. */
+    sourceOperations(): SourceOperationsInterface;
+}
+
 /**
  * @module processor/types
  * Document processor interface definitions.
@@ -998,10 +1479,16 @@ interface DocumentProcessorInterface {
     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>;
+    /**
+     * Process a metadata sidecar update for a file (payload update only).
+     * `options.lockWaitMs` bounds the document-lock wait (API routes, D118).
+     */
+    processMetadataUpdate(filePath: string, metadata: Record<string, unknown>, options?: DocumentLockOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * Process a rules update for a file (rebuild merged metadata, payload
+     * update only). `options.lockWaitMs` bounds the document-lock wait.
+     */
+    processRulesUpdate(filePath: string, options?: DocumentLockOptions): 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). */
@@ -1009,76 +1496,61 @@ interface DocumentProcessorInterface {
     /** 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.
+ * The processor the service runs on: file operations plus source operations.
+ * `createDocumentProcessor` returns it; the API server and the notify queue
+ * depend on it (`DocumentProcessor` implements it). Adapt a custom file-only
+ * processor with `withoutSourceSupport`, whose source operations fail.
  */
+type WatcherProcessor = DocumentProcessorInterface & SourceOperationsProvider;
 
 /**
- * Core document processing pipeline.
+ * @module processor
  *
- * Handles extracting text, computing embeddings, and syncing with the vector store.
+ * Core document processing pipeline. Resolves files and source documents, computes embeddings, syncs with 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 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.
  *
  * Handles extracting text, computing embeddings, and syncing with the vector store.
  */
-declare class DocumentProcessor implements DocumentProcessorInterface {
+declare class DocumentProcessor implements WatcherProcessor {
+    private readonly deps;
     private config;
-    private readonly embeddingProvider;
-    private readonly vectorStore;
     private compiledRules;
-    private readonly logger;
     private templateEngine?;
-    private readonly enrichmentStore?;
-    private readonly issuesManager?;
-    private readonly valuesManager?;
-    private readonly contentHashCache?;
+    private readonly locks;
     /**
      * Create a new DocumentProcessor.
      *
      * @param deps - The processor dependencies.
      */
-    constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, enrichmentStore, issuesManager, valuesManager, contentHashCache, }: DocumentProcessorDeps);
-    /**
-     * Build merged metadata for a file and add matched_rules.
-     */
-    private buildMetadataWithRules;
+    constructor(deps: DocumentProcessorDeps);
+    /** The processing ceilings now (read per document, D44). */
+    private limits;
+    /** Rule context reflecting the current rules, templates and config. */
+    private ruleContext;
+    /** Shared pipeline dependencies. */
+    private pipelineContext;
+    /** File resolver bound to the current rule context. */
+    private fileResolver;
+    /** Dependencies of the payload-only file operations. */
+    private fileOperations;
     /**
-     * Execute an async operation with standardized file error handling.
+     * Run a file operation with standard failure handling: log, and record a
+     * typed issue when `context.issueType` (the code for untagged failures)
+     * is given; return `fallback` on failure.
      */
-    private withFileErrorHandling;
+    private withFailureHandling;
     /**
      * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
      *
      * @param filePath - The file to process.
      */
     processFile(filePath: string): Promise<void>;
+    /** {@inheritDoc SourceOperationsProvider.sourceOperations} */
+    sourceOperations(): SourceOperationsInterface;
     /**
      * Delete all chunks for a file from the vector store and remove metadata.
      *
@@ -1086,22 +1558,28 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
      */
     deleteFile(filePath: string): Promise<void>;
     /**
-     * Process a metadata update: merge into enrichment store, update Qdrant payloads (no re-embed).
+     * Process a metadata update: merge into enrichment store, update Qdrant
+     * payloads (no re-embed). The stored `file_path` (casing included) and
+     * `matched_rules` are kept.
      *
      * @param filePath - The file whose metadata to update.
      * @param metadata - The new metadata to merge.
+     * @param options - Bounded lock wait (API routes, D118).
      * @returns The merged payload, or `null` if the file is not indexed.
+     * @throws DocumentLockTimeoutError when a bounded lock wait runs out.
      */
-    processMetadataUpdate(filePath: string, metadata: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    processMetadataUpdate(filePath: string, metadata: Record<string, unknown>, options?: DocumentLockOptions): Promise<Record<string, unknown> | null>;
     /**
-     * Re-apply inference rules to a file without re-embedding.
-     * Reads file attributes, applies current rules, merges with enrichment metadata,
-     * and updates Qdrant payloads.
+     * Re-apply inference rules to a file without re-embedding (see
+     * `reapplyFileRules`: system fields and the stored `file_path` are
+     * re-asserted; interpolation failures are recorded as an issue).
      *
      * @param filePath - The file to update.
+     * @param options - Bounded lock wait (API routes, D118).
      * @returns The merged metadata, or `null` if the file is not indexed.
+     * @throws DocumentLockTimeoutError when a bounded lock wait runs out.
      */
-    processRulesUpdate(filePath: string): Promise<Record<string, unknown> | null>;
+    processRulesUpdate(filePath: string, options?: DocumentLockOptions): Promise<Record<string, unknown> | null>;
     /**
      * Render a file through the rule engine without embedding.
      * Returns rendered content, renderAs, matched rules, and metadata.
@@ -1128,10 +1606,29 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
     updateRules(compiledRules: CompiledRule[], templateEngine?: TemplateEngine, customMapLib?: Record<string, (...args: unknown[]) => unknown>): void;
 }
 
+/**
+ * @module queue/pausable
+ * The pause/resume/quiesce surface shared by the file event queue and the source notify queue, and a combinator that drives several queues as one (used by prune). No I/O.
+ */
+/**
+ * A queue that can stop starting new work, resume, and report when its
+ * in-flight work has finished. Prune uses this to quiesce every writer
+ * before it computes and executes its plan.
+ */
+interface PausableQueue {
+    /** Stop starting new work; enqueues are still accepted. */
+    pause(): void;
+    /** Resume starting work. */
+    resume(): void;
+    /** Resolve once no work is in flight (queued work may remain). */
+    waitForIdleWorkers(): Promise<void>;
+}
+
 /**
  * @module queue
- * Debounced, rate-limited, concurrent event queue for file watchers. Manages priority queuing and async callbacks. No direct I/O; orchestrates processing.
+ * Debounced, concurrent event queue for file watchers. Manages priority queuing and async callbacks. Embedding request rate is limited by the shared embedding provider wrapper, not here. No direct I/O.
  */
+
 /**
  * A watch event.
  */
@@ -1157,27 +1654,22 @@ interface EventQueueOptions {
     debounceMs: number;
     /** Maximum number of concurrent processors. */
     concurrency: number;
-    /** Optional max processed events per minute (token bucket). */
-    rateLimitPerMinute?: number;
 }
 /**
- * A debounced, rate-limited, concurrent event queue.
+ * A debounced, concurrent event queue.
  */
 declare class EventQueue {
     private readonly debounceMs;
     private readonly concurrency;
-    private readonly rateLimitPerMinute?;
     private started;
     private paused;
+    private stopped;
     private active;
     private readonly debounceTimers;
     private readonly latestByKey;
     private readonly normalQueue;
     private readonly lowQueue;
-    private tokens;
-    private lastRefillMs;
-    private drainWaiters;
-    private idleWorkerWaiters;
+    private readonly signals;
     /**
      * Create an event queue.
      *
@@ -1185,16 +1677,25 @@ declare class EventQueue {
      */
     constructor(options: EventQueueOptions);
     /**
-     * Enqueue an event, debounced per path+priority.
+     * Enqueue an event, debounced per path+priority. Ignored once stopped.
      *
      * @param event - The watch event.
      * @param fn - The processing function to invoke when dequeued.
      */
     enqueue(event: WatchEvent, fn: ProcessFn): void;
     /**
-     * Start processing events.
+     * Start processing events (events enqueued earlier are held until now).
+     */
+    start(): void;
+    /**
+     * Alias of {@link EventQueue.start}, kept for existing callers.
      */
     process(): void;
+    /**
+     * Stop: cancel pending debounces, drop queued events, ignore new ones, and
+     * resolve once in-flight work finishes. Drain waiters resolve then too.
+     */
+    stop(): Promise<void>;
     /**
      * Pause processing events. Events can still be enqueued but will not be processed.
      */
@@ -1218,13 +1719,136 @@ declare class EventQueue {
      */
     waitForIdleWorkers(): Promise<void>;
     private push;
-    private refillTokens;
-    private takeToken;
     private nextItem;
     private pump;
     private isIdle;
-    private maybeResolveDrain;
-    private maybeResolveIdleWorkers;
+    private settle;
+}
+
+/**
+ * @module queue/sourceNotifyTypes
+ * Options, errors and job bookkeeping types of the source notify queue (validated options schema, stopped error, coalesced jobs and their waiters). No I/O.
+ */
+
+/**
+ * Default number of references processed at once: the core
+ * `embedding.concurrency` default, which the service passes in.
+ */
+declare const DEFAULT_SOURCE_NOTIFY_CONCURRENCY: number;
+/** Options for the source notify queue. */
+declare const sourceNotifyQueueOptionsSchema: z.ZodObject<{
+    concurrency: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Options for the source notify queue (input form; defaults applied). */
+type SourceNotifyQueueOptions = z.input<typeof sourceNotifyQueueOptionsSchema>;
+/** Issues-store operations the queue needs. */
+type SourceQueueIssues = Pick<IssuesManager, 'record' | 'clear'>;
+/** Per-run options of `SourceNotifyQueue.processNow`. */
+interface ProcessNowOptions {
+    /**
+     * Re-embed even when content is unchanged (reindex scope `full`). Merged
+     * as OR into a run it joins.
+     */
+    force?: boolean;
+}
+/** Rejection for `SourceNotifyQueue.processNow` after `stop()`. */
+declare class SourceNotifyQueueStoppedError extends Error {
+    /** Create the error. */
+    constructor();
+}
+
+/**
+ * @module queue/SourceNotifyQueue
+ * In-memory notify queue for source documents, keyed by reference: pending notifications merge, in-flight ones mark the reference dirty for exactly one re-run. Runs each reference through the source operations; records an issue when a run rejects unexpectedly.
+ */
+
+/** What the queue runs: one reference with its designated rule. */
+type SourceProcess = Pick<SourceOperationsInterface, 'process'>;
+/**
+ * Coalescing queue for source-document notifications (Decision 12).
+ *
+ * - A notification for a **pending** reference is merged into it (the latest
+ *   rule wins; the reference keeps its place in line).
+ * - One for an **in-flight** reference marks it dirty: when the current run
+ *   ends the reference is queued once more (at the back), however many
+ *   notifications arrived meanwhile.
+ * - Every run calls `process`, which retrieves current state, so a
+ *   burst on one reference costs at most two retrievals and the final state
+ *   wins. Runs never overlap for the same reference.
+ *
+ * References are compared exactly (case-sensitive), like source point IDs.
+ * The queue holds work until {@link start}; {@link pause} (prune) stops new
+ * runs without rejecting enqueues. Failures never escape: `process`
+ * records issues itself, and an unexpected rejection becomes a `failed`
+ * result and an `extraction_error` issue (with the designated rule).
+ *
+ * Reindex runs go through {@link processNow} as well, so a notification and
+ * a reindex of one reference never run in parallel and the latest state wins.
+ */
+declare class SourceNotifyQueue implements PausableQueue {
+    private readonly processor;
+    private readonly logger?;
+    private readonly issues?;
+    private readonly concurrency;
+    private started;
+    private paused;
+    private stopped;
+    private readonly pending;
+    private readonly inFlight;
+    private readonly signals;
+    /**
+     * @param processor - Processes one reference with its designated rule
+     *   (source operations).
+     * @param options - Queue options (validated).
+     * @param logger - Logger for unexpected processing rejections.
+     * @param issues - Issues store for unexpected processing rejections.
+     */
+    constructor(processor: SourceProcess, options?: SourceNotifyQueueOptions, logger?: pino.Logger | undefined, issues?: SourceQueueIssues | undefined);
+    /**
+     * Notify that a source document changed (fire and forget).
+     *
+     * @param ref - The exact `<name>://<id>` reference.
+     * @param rule - The designated rule name.
+     * @returns `false` when the queue is stopped and the notification was dropped.
+     */
+    enqueue(ref: string, rule: string): boolean;
+    /**
+     * Process a reference and resolve with the result of a run that started
+     * after this call, so the result reflects the source's state at or after
+     * the call (the `?wait=true` path). Coalesces with other notifications:
+     * if the reference is pending, this joins that run; if it is in flight,
+     * this waits for the current run and then the one dirty re-run.
+     *
+     * @param ref - The exact `<name>://<id>` reference.
+     * @param rule - The designated rule name.
+     * @param options - `force` re-embeds unchanged content.
+     * @returns The per-document result.
+     * @throws {@link SourceNotifyQueueStoppedError} (as a rejection) when the
+     *   queue is stopped before the run starts.
+     */
+    processNow(ref: string, rule: string, options?: ProcessNowOptions): Promise<DocumentResult>;
+    /** Start processing (work enqueued earlier is held until now). */
+    start(): void;
+    /** {@inheritDoc PausableQueue.pause} */
+    pause(): void;
+    /** {@inheritDoc PausableQueue.resume} */
+    resume(): void;
+    /** {@inheritDoc PausableQueue.waitForIdleWorkers} */
+    waitForIdleWorkers(): Promise<void>;
+    /** Resolve once nothing is pending, owed (dirty) or in flight. */
+    drain(): Promise<void>;
+    /**
+     * Stop: drop pending and owed runs (their `processNow` callers reject with
+     * {@link SourceNotifyQueueStoppedError}), refuse new work, and resolve once
+     * in-flight runs finish.
+     */
+    stop(): Promise<void>;
+    private schedule;
+    private pump;
+    private run;
+    private execute;
+    private isIdle;
+    private settle;
 }
 
 /**
@@ -1270,6 +1894,166 @@ declare class CommitMessageGenerator {
     generate(files: string[], diffSummary: string): Promise<string | null>;
 }
 
+/**
+ * @module vcs/RootGitLock
+ * Per-root, in-process FIFO async mutex serialising the watcher's own git work on a root: batch commits (with push), squash, untracking and temp-file sweeps (D66, D81). Never re-entered. Logs long waits and holds; an API route's wait is bounded (D102).
+ *
+ * It cannot exclude other processes (people and agents run git in the same
+ * repositories), so everything done under it must also be safe without it.
+ */
+
+/** FIFO mutex for one VCS root. */
+declare class RootGitLock {
+    private readonly lock;
+    /**
+     * @param root - Repository root (named in warnings).
+     * @param logger - Logger for long-wait and long-hold warnings.
+     */
+    constructor(root: string, logger: pino.Logger);
+    /** The operation holding the lock, if any. */
+    get heldBy(): string | undefined;
+    /**
+     * Run `work` while holding the lock. Callers queue in arrival order; the
+     * lock is released when `work` settles, whatever its outcome.
+     *
+     * @param operation - Operation name, for warnings and {@link heldBy}.
+     * @param work - The work to run under the lock (must not take it again).
+     * @returns What `work` returns.
+     */
+    run<T>(operation: string, work: () => Promise<T>): Promise<T>;
+    /**
+     * {@link run}, giving up when the lock is not acquired within `waitMs`
+     * (D102). A caller that gives up never runs `work`; its place in the
+     * queue passes straight on, so later callers keep their order.
+     *
+     * @param operation - Operation name, for warnings and {@link heldBy}.
+     * @param waitMs - Longest wait for the lock.
+     * @param work - The work to run under the lock (must not take it again).
+     * @returns What `work` returns.
+     * @throws LockWaitTimeoutError when the wait runs out.
+     */
+    runWithin<T>(operation: string, waitMs: number, work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * @module vcs/squashPlumbing
+ * Plumbing-only history rewrite for squash retention (D148, D166): list the first-parent history, rebuild it with `commit-tree` from a parentless baseline, keeping each retained commit's tree, raw message, identities and raw dates. Never touches the working tree or the index.
+ */
+/** Commit metadata for retention calculation. */
+interface CommitInfo {
+    /** Full hash. */
+    hash: string;
+    /** Author date. */
+    date: Date;
+}
+
+/**
+ * @module vcs/SquashManager
+ * Scheduled squash retention for one VCS root: under RootGitLock, flush the pending batch, then rewrite the branch in plumbing and move it with a compare-and-swap `update-ref` (D101, D148, D166). Force-pushes when a remote is set.
+ *
+ * No checkout, reset or cherry-pick runs, so the working tree and the index
+ * are never touched: a file untracked by `/vcs/exclude` or the size cap
+ * keeps its newest content on disk, and no clean tree is needed. Squash
+ * still refuses while a merge, rebase, cherry-pick or revert is in
+ * progress, or when HEAD is not on the configured branch (D20).
+ */
+
+/** Result of a squash operation. */
+interface SquashResult {
+    squashed: boolean;
+    commitsRemoved?: number;
+    commitsRetained?: number;
+    error?: string;
+}
+/** Test hooks around the reference update (not public API). @internal */
+interface SquashHooks {
+    /** Receives the rebuilt tip; returns the tip to check and publish. */
+    rebuiltTip?: (tip: string) => Promise<string>;
+    /** Runs after the tree check, just before `update-ref`. */
+    beforeUpdateRef?: () => Promise<void>;
+}
+/** Options for SquashManager construction beyond the required params. */
+interface SquashManagerOptions {
+    /** Git branch name for squash operations. Default: "master". */
+    branch?: string;
+    /** The root's lock; squash holds it for its whole run (D81). */
+    lock: RootGitLock;
+    /**
+     * Commit pending changes inside the hold through the non-locking commit
+     * path (D101). Resolves false when that commit failed (squash refuses).
+     */
+    flushInHold?: () => Promise<boolean>;
+    /** Remote URL for force-push after squash. */
+    remoteUrl?: string;
+    /** Access token for HTTPS push authentication. */
+    accessToken?: string;
+    /** Test hooks (not public API). @internal */
+    hooks?: SquashHooks;
+}
+/**
+ * Manages scheduled squash retention for a single VCS root.
+ *
+ * Runs on a cron schedule (checked every 60s). When triggered, squashes
+ * commits older than the retention boundary (the tighter of maxAgeDays
+ * and maxVersions) into a single "historical baseline" commit and
+ * recreates the retained commits on top of it.
+ */
+declare class SquashManager {
+    private readonly rootPath;
+    private readonly retention;
+    private readonly logger;
+    private readonly options;
+    private readonly branch;
+    private intervalTimer;
+    private running;
+    constructor(rootPath: string, retention: VcsRetentionConfig, logger: pino.Logger, options: SquashManagerOptions);
+    /**
+     * Start the cron-based squash scheduler.
+     * Checks every 60 seconds if the cron expression matches.
+     */
+    start(): void;
+    /**
+     * Stop the cron scheduler.
+     */
+    stop(): void;
+    /**
+     * Run the squash under the root's lock: flush, guard, rewrite, publish,
+     * force-push. Exposed publicly for testing.
+     */
+    runSquash(): Promise<SquashResult>;
+    /**
+     * Refuse while an abandoned cherry-pick, rebase or merge is present, or
+     * when HEAD is not on the configured branch (#249, D20: report only).
+     *
+     * @returns The refusal reason, or undefined if the squash may proceed.
+     */
+    private checkRepoPreconditions;
+    /** Rewrite and publish the branch (inside the hold). */
+    private squashBranch;
+    /** Log a finished squash, force push if configured, and report it. */
+    private completed;
+    /**
+     * Get all first-parent commits of HEAD in chronological order (oldest
+     * first), or none when HEAD is unborn.
+     */
+    getCommitLog(): Promise<CommitInfo[]>;
+    /**
+     * Calculate the retention boundary index.
+     * Returns the index of the oldest commit to KEEP.
+     * All commits before this index will be squashed into a baseline.
+     *
+     * Strategy: find the tighter constraint between age and count.
+     * - Age: keep commits newer than maxAgeDays
+     * - Count: keep the last maxVersions commits
+     * The boundary is the one that retains FEWER old commits (tighter).
+     */
+    calculateRetentionBoundary(commits: CommitInfo[]): number;
+    /**
+     * Force push to remote after squash (history rewrite requires force).
+     */
+    private forcePushIfConfigured;
+}
+
 /**
  * @module vcs/types
  * Shared types for the VCS subsystem.
@@ -1288,7 +2072,7 @@ interface PushError {
 
 /**
  * @module vcs/VcsManager
- * Per-root VCS manager for git-backed content versioning.
+ * Per-root VCS manager for git-backed content versioning: a throttled batch queue, a circuit breaker, the root's RootGitLock, squash scheduling and startup maintenance. Commits run through {@link BatchCommitter} under the lock.
  */
 
 /** Per-root circuit breaker state, exposed via /vcs/status. */
@@ -1296,75 +2080,56 @@ interface VcsBreakerState extends CircuitBreakerSnapshot {
     /** Files queued or in flight, not yet committed. */
     pendingCount: number;
 }
+/** Optional VcsManager collaborators. */
+interface VcsManagerOptions {
+    /** `vcs.maxFileBytes` in bytes, read at each staging (D67). */
+    getMaxFileBytes?: () => number;
+    /** Path-list timeout override (tests only). */
+    timeoutFor?: (paths: number) => number;
+}
 /**
- * Per-root VCS manager for git-backed content versioning.
- *
- * Each VCS-enabled watch root gets its own VcsManager instance, which owns
- * a throttled commit pipeline: file changes are batched, staged, committed
- * (with optional AI-generated messages), and optionally pushed to a remote.
- *
- * Concurrency: only one commit is in-flight at a time per root. Index.lock
- * contention is handled with exponential backoff retries (D10). Failed
- * batches are always retained; a circuit breaker spaces out retries of a
- * persistently failing root (#249).
+ * Per-root VCS manager: batches file changes and commits them under the
+ * root's {@link RootGitLock}; failed batches are always retained (#249).
  */
 declare class VcsManager {
     readonly config: VcsConfig;
     readonly rootPath: string;
     readonly remoteUrl: string | undefined;
-    private readonly accessToken;
+    /** Serialises this root's git work (D66, D81). */
+    readonly lock: RootGitLock;
     private readonly logger;
-    private readonly commitMessageBuilder;
+    private readonly committer;
     private readonly breaker;
-    private readonly pending;
+    private readonly queue;
     private readonly pendingReversions;
-    private readonly _pushErrors;
     private readonly squashManager;
-    private throttleTimer;
-    private breakerRetryTimer;
-    private commitInFlight;
-    private inFlightFileCount;
+    private sweepTimer;
     private started;
-    private paused;
     private isBaseline;
-    private _lastPushTime;
-    constructor(rootPath: string, config: VcsConfig, logger: pino.Logger, commitMessageGenerator?: CommitMessageGenerator, remoteUrl?: string, accessToken?: string);
+    constructor(rootPath: string, config: VcsConfig, logger: pino.Logger, commitMessageGenerator?: CommitMessageGenerator, remoteUrl?: string, accessToken?: string, options?: VcsManagerOptions);
     get lastPushTime(): string | null;
     get pushErrors(): readonly PushError[];
     /** Current circuit breaker state and backlog, for /vcs/status. */
     get breakerState(): VcsBreakerState;
+    /** First breaker trip since the last success, for `health.vcs`. */
+    get trippedSince(): string | null;
     /**
-     * Begin accepting file changes. Sets the manager to started state and
-     * starts the squash manager if configured.
-     *
-     * Performs startup orphan detection/recovery before starting the squash
-     * manager, ensuring the repo is on the configured branch, and reports
-     * (never clears) an abandoned cherry-pick, rebase, or merge.
-     *
-     * Baseline mode (commit prefix `"baseline:"`) remains active until
-     * {@link endBaseline} is called by the coordinator after the initial scan.
+     * Begin accepting file changes after startup maintenance under the lock
+     * (never a checkout, D167); start the hourly sweep and squash. Baseline
+     * mode lasts until {@link endBaseline}.
      */
     start(): Promise<void>;
-    /**
-     * Signal that the initial filesystem scan is complete.
-     * Clears the baseline flag so subsequent commits use normal "watcher: batch" messages.
-     */
+    /** Initial scan done: later commits use `watcher: batch` messages. */
     endBaseline(): void;
     /**
-     * Add a file to the pending set and start the throttle timer.
-     * If the pending set reaches maxBatchSize, commit a batch immediately.
-     *
-     * The circuit breaker is intentionally not reset here: recovery is
+     * Add a file to the pending set and start the throttle timer; a full set
+     * commits at once. The breaker is intentionally not reset here: recovery is
      * time-based, so a busy root cannot hammer a deterministic failure.
      *
      * @param filePath - Absolute path of the changed file.
      */
     fileChanged(filePath: string): void;
-    /**
-     * Record reversion metadata so the next commit uses a revert-prefixed message.
-     *
-     * @param reversion - The reversion metadata to record.
-     */
+    /** Record a reversion so the next commit uses a revert-prefixed message. */
     addPendingReversion(reversion: PendingReversion): void;
     /**
      * Queue a deleted file. Staging records the deletion if git tracks it.
@@ -1372,66 +2137,31 @@ declare class VcsManager {
      * @param filePath - Absolute path of the deleted file.
      */
     handleUnlink(filePath: string): void;
-    /**
-     * Pause the commit pipeline. Drains pending commits via flush(), then
-     * sets a flag that makes commitBatch queue instead of execute.
-     * Used by SquashManager to coordinate squash operations.
-     */
-    pause(): Promise<void>;
-    /**
-     * Resume the commit pipeline after a pause.
-     * Re-enables normal commit operations and starts a throttle timer
-     * if there are pending files that accumulated during the pause.
-     */
-    resume(): void;
-    /**
-     * Commit all pending files now, in batches of at most maxBatchSize.
-     */
+    /** Push now; the caller holds {@link lock} (`/vcs/exclude`, D71). */
+    pushInHold(): Promise<void>;
+    /** Commit all pending files now, in batches of at most maxBatchSize. */
     flush(): Promise<void>;
-    /**
-     * Stop accepting file changes, flush pending, and clean up timers.
-     */
+    /** Stop accepting file changes, flush pending, and clean up timers. */
     stop(): Promise<void>;
+    /** Run a squash now (as the cron does); undefined when retention is off. */
+    runSquash(): ReturnType<SquashManager['runSquash']> | undefined;
     /**
      * Add tracked-but-deleted paths (`git ls-files --deleted`) in this
      * manager's watch scope to pending, so the next commit (typically the
-     * baseline) records deletions that happened while nothing was watching.
-     * Called by the coordinator before flush/endBaseline on startup. See #249.
+     * baseline) records deletions made while nothing was watching (#249).
      *
      * @param isInScope - Returns true if the absolute path routes to this
      *   manager (the coordinator's routing and watch-scope logic).
      */
     reconcileDeletions(isInScope: (absolutePath: string) => boolean): Promise<void>;
-    /** Take up to maxBatchSize files from the pending set. */
-    private takeBatch;
-    /** Chain a batch behind the in-flight commit, tracking it as backlog. */
-    private enqueueBatch;
-    /** Put files back in the pending set. Pending is a set, so this cannot grow it past the distinct paths seen. */
-    private retain;
-    private clearThrottle;
     /**
-     * Start the throttle timer to fire flush() after commitThrottleMs.
-     * If a timer is already running, do not reset it — this is throttle, not debounce.
-     */
-    private resetThrottle;
-    private clearBreakerRetry;
-    /**
-     * Ensure a timer will flush pending files when the breaker's cooldown
-     * elapses, without needing a new file-change event.
-     */
-    private scheduleBreakerRetry;
-    /**
-     * Commit a batch with index.lock retry, stale lock detection, pause
-     * support, and the circuit breaker. A failed batch is always retained.
-     */
-    private commitBatch;
-    /**
-     * One commit attempt: stage, skip if nothing is staged, commit, push.
+     * Commit a batch (the caller holds the lock) with index.lock retry,
+     * stale lock removal and the circuit breaker. A failed batch is always
+     * retained.
      *
-     * @returns true if a commit was created; false for a no-op.
+     * @returns true on success (including "nothing staged").
      */
-    private tryCommit;
-    private onCommitSuccess;
+    private commitBatch;
     private onCommitFailure;
 }
 
@@ -1449,10 +2179,15 @@ declare class VcsCoordinator {
     private readonly roots;
     private readonly logger;
     private readonly isInWatchScope;
-    constructor(config: JeevesWatcherConfig, logger: pino.Logger);
     /**
-     * Start all VcsManager instances.
-     * Runs startup orphan detection/recovery for each root.
+     * @param config - Config at construction (roots, remotes, retention).
+     * @param logger - Logger.
+     * @param getConfig - Live config, for settings read at each staging
+     *   (`vcs.maxFileBytes`, D67). Default: the construction config.
+     */
+    constructor(config: JeevesWatcherConfig, logger: pino.Logger, getConfig?: () => JeevesWatcherConfig);
+    /**
+     * Start all VcsManager instances (each runs its startup maintenance).
      */
     start(): Promise<void>;
     /**
@@ -1475,6 +2210,12 @@ declare class VcsCoordinator {
      * Flush all managers and clean up.
      */
     stop(): Promise<void>;
+    /**
+     * VCS state for `GET /status` `health.vcs` (D86).
+     *
+     * @returns Root count, total backlog, tripped roots and the oldest trip.
+     */
+    getHealth(): VcsHealth;
     /**
      * Get the sorted root paths (longest-first).
      */
@@ -1497,25 +2238,129 @@ declare class VcsCoordinator {
     findManagerForPath(normalizedPath: string): VcsManager | undefined;
 }
 
+/**
+ * @module health
+ * Tracks consecutive system-level failures and applies exponential backoff.
+ * Triggers fatal error callback when maxRetries is exceeded.
+ */
+
+/**
+ * Options for {@link SystemHealth}.
+ */
+interface SystemHealthOptions {
+    /** Maximum consecutive failures before fatal. Default: Infinity. */
+    maxRetries?: number;
+    /** Maximum backoff delay in milliseconds. Default: 60000. */
+    maxBackoffMs?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 1000. */
+    baseDelayMs?: number;
+    /** Called when maxRetries is exceeded. If not set, throws. */
+    onFatalError?: (error: unknown) => void;
+    /** Logger instance. */
+    logger: pino.Logger;
+}
+/**
+ * Tracks system health via consecutive failure count and exponential backoff.
+ */
+declare class SystemHealth {
+    private consecutiveFailures;
+    private readonly maxRetries;
+    private readonly maxBackoffMs;
+    private readonly baseDelayMs;
+    private readonly onFatalError?;
+    private readonly logger;
+    constructor(options: SystemHealthOptions);
+    /**
+     * Record a successful system operation. Resets the failure counter.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a system-level failure. If maxRetries is exceeded, triggers fatal error.
+     *
+     * @param error - The error that occurred.
+     * @returns Whether the watcher should continue (false = fatal).
+     */
+    recordFailure(error: unknown): boolean;
+    /**
+     * Compute the current backoff delay based on consecutive failures.
+     *
+     * @returns Delay in milliseconds.
+     */
+    get currentBackoffMs(): number;
+    /**
+     * Sleep for the current backoff duration.
+     *
+     * @param signal - Optional abort signal.
+     */
+    backoff(signal?: AbortSignal): Promise<void>;
+    /**
+     * Run one operation with health tracking: back off, run it and record
+     * the success, or record its failure.
+     *
+     * @param fn - The operation.
+     * @returns False when the failure was fatal (the caller stops).
+     * @throws When retries are exhausted and no fatal-error callback is set.
+     */
+    run(fn: () => Promise<void>): Promise<boolean>;
+    /** Current consecutive failure count. */
+    get failures(): number;
+}
+
+/**
+ * @module watcher/changeSource/types
+ * The change-source seam (spec Design 9, D120, D149): a `ChangeSource` supplies raw events and root signals to a `ChangeSink`; `FileSystemWatcher` implements the sink and owns every decision. Types only.
+ */
+
+/** A classified event, as chokidar reports it. */
+type ClassifiedEventType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
+/**
+ * One unclassified event of a parcel batch (D149): an absolute path and a
+ * type that is a hint only (`lstat` decides).
+ */
+interface RawChangeEvent {
+    /** Absolute path. */
+    path: string;
+    /** Parcel's event type. */
+    type: 'create' | 'update' | 'delete';
+}
+/**
+ * Where a change source delivers events and signals. Implemented by
+ * `FileSystemWatcher`, which owns classification, stability waits, pairing,
+ * renewals and every reconcile trigger (D120).
+ */
+interface ChangeSink {
+    /** A classified event (chokidar). */
+    event: (type: ClassifiedEventType, path: string, stats?: Stats) => void;
+    /** One whole parcel batch for a root, sorted by path (D149). */
+    rawEvents: (root: string, events: RawChangeEvent[]) => void;
+    /** The source finished its initial set for `root`. */
+    initialScanDone: (root: string) => void;
+    /** The source re-created `root`'s subscription after an error (D131). */
+    resubscribed: (root: string) => void;
+    /**
+     * `root` became unreachable (D109), or is reachable but cannot be
+     * watched (`reachable`, D156: it is still reconciled); `code` is the
+     * error code.
+     */
+    rootUnavailable: (root: string, code: string, options?: RootUnavailableOptions) => void;
+    /** `root` is reachable again (D109). */
+    rootAvailable: (root: string) => void;
+}
+/** Details of {@link ChangeSink.rootUnavailable}. */
+interface RootUnavailableOptions {
+    /**
+     * The root is still on disk but unwatched (a non-transient subscribe
+     * failure, D156): it counts in `unavailableRoots` and is still
+     * reconciled.
+     */
+    reachable?: boolean;
+}
+
 /**
  * @module api/InitialScanTracker
  * Tracks initial filesystem scan state for status reporting.
  */
-/** Initial scan status snapshot for API consumers. */
-interface InitialScanStatus {
-    /** Whether the initial scan is currently in progress. */
-    active: boolean;
-    /** Number of files matched by watch globs. */
-    filesMatched?: number;
-    /** Number of files enqueued for processing so far. */
-    filesEnqueued?: number;
-    /** ISO 8601 timestamp when the scan started. */
-    startedAt?: string;
-    /** ISO 8601 timestamp when the scan completed. */
-    completedAt?: string;
-    /** Total scan duration in milliseconds. */
-    durationMs?: number;
-}
+
 /**
  * Tracks the state of the initial filesystem scan after service start.
  */
@@ -1540,66 +2385,173 @@ declare class InitialScanTracker {
 }
 
 /**
- * @module health
- * Tracks consecutive system-level failures and applies exponential backoff.
- * Triggers fatal error callback when maxRetries is exceeded.
+ * @module watcher/fileEvents
+ * What a filtered file event does: the VCS hook, move correlation and the processing queue. I/O: enqueues processor work.
  */
 
+/** VCS change callback. */
+type VcsFileChange = (filePath: string, event: 'add' | 'change' | 'unlink') => void;
+
 /**
- * Options for {@link SystemHealth}.
+ * @module watcher/inventory/Inventory
+ * `FileSystemWatcher`'s inventory (D99): the files that passed its filters, keyed by `normalizeDocumentKey`, with the child-set directory index (D127, D150). Pure.
  */
-interface SystemHealthOptions {
-    /** Maximum consecutive failures before fatal. Default: Infinity. */
-    maxRetries?: number;
-    /** Maximum backoff delay in milliseconds. Default: 60000. */
-    maxBackoffMs?: number;
-    /** Base delay in milliseconds for exponential backoff. Default: 1000. */
-    baseDelayMs?: number;
-    /** Called when maxRetries is exceeded. If not set, throws. */
-    onFatalError?: (error: unknown) => void;
-    /** Logger instance. */
-    logger: pino.Logger;
+/** File size and modification time, as a walk or `stat` reports them. */
+interface FileStats {
+    /** Size in bytes. */
+    size: number;
+    /** Modification time (ms since epoch). */
+    mtimeMs: number;
+}
+/** One inventory entry. */
+interface InventoryEntry {
+    /** The path as the source reported it. */
+    path: string;
+    /** Size, when the inventory tracks stats (parcel source). */
+    size?: number;
+    /** Modification time, when the inventory tracks stats. */
+    mtimeMs?: number;
 }
 /**
- * Tracks system health via consecutive failure count and exponential backoff.
+ * The files the change source last saw that pass `FileSystemWatcher`'s
+ * filters. Stats are stored only when `trackStats` is set (the parcel
+ * source, whose initial set is the walk); under chokidar entries hold paths
+ * only (spec Design 9).
  */
-declare class SystemHealth {
-    private consecutiveFailures;
-    private readonly maxRetries;
-    private readonly maxBackoffMs;
-    private readonly baseDelayMs;
-    private readonly onFatalError?;
-    private readonly logger;
-    constructor(options: SystemHealthOptions);
+declare class Inventory {
+    private readonly trackStats;
+    private readonly entries;
+    private readonly index;
+    /** @param trackStats - Store size and mtime with each entry. */
+    constructor(trackStats: boolean);
+    /** Number of files. */
+    get size(): number;
+    /** Add or update a file. */
+    set(path: string, stats?: FileStats): void;
     /**
-     * Record a successful system operation. Resets the failure counter.
+     * Remove a file.
+     *
+     * @returns True when it was present.
      */
-    recordSuccess(): void;
+    delete(path: string): boolean;
+    /** The entry for a path, if present. */
+    get(path: string): InventoryEntry | undefined;
     /**
-     * Record a system-level failure. If maxRetries is exceeded, triggers fatal error.
-     *
-     * @param error - The error that occurred.
-     * @returns Whether the watcher should continue (false = fatal).
+     * Whether a path is a directory the inventory holds files under (D127:
+     * an absent path is classified as a directory delete by this).
      */
-    recordFailure(error: unknown): boolean;
+    isDirectory(path: string): boolean;
+    /** Every file path, as the source reported it (`/walk`, D83). */
+    paths(): string[];
     /**
-     * Compute the current backoff delay based on consecutive failures.
+     * The entries beneath a directory, at any depth, keyed by document key;
+     * O(subtree size), never a scan of the inventory.
+     */
+    entriesUnder(dir: string): Map<string, InventoryEntry>;
+}
+
+/**
+ * @module watcher/changeSource/parcelModule
+ * Loading `@parcel/watcher` only when it is selected (D125): a cached dynamic import whose failure becomes a refusal naming the chokidar switch, the native-load error test, and the explicit backend per platform (D124). I/O: the import.
+ */
+
+/** The parts of `@parcel/watcher` the parcel source uses. */
+type ParcelWatcherModule = Pick<typeof ParcelWatcher, 'subscribe'>;
+/** Imports the module (injectable for tests). */
+type ParcelImporter = () => Promise<ParcelWatcherModule>;
+
+/**
+ * @module watcher/changeSource/restart
+ * The process-restart seam of D196: on Windows the parcel source never unsubscribes (`@parcel/watcher` 2.6.0 crashes the process natively there), so a watcher rebuild or a subscription recovery exits the process for the service manager to restart it. The app implements the graceful restarter; `exitingRestarter` is the fallback for a watcher built without the app. I/O: `process.exit` in that fallback only.
+ */
+
+/** One request to exit for a restart. */
+interface RestartRequest {
+    /** The cause (a code, no path: it reaches health, D89). */
+    cause: RestartCause;
+    /** The root concerned, for the log line only. */
+    root?: string;
+    /** The error behind it, for the log line only. */
+    err?: unknown;
+    /**
+     * A config reload's reindex scope (`configWatch.reindex`), run by the
+     * restarted process instead of this one.
+     */
+    reindex?: ConfigWatchReindexScope;
+}
+/**
+ * Exits the process for a service-manager restart (D196). `restart`
+ * returns at once: the exit follows a graceful stop, so callers inside the
+ * change source's queue never wait on themselves. Only the first request
+ * of a process counts. Injected, so tests never call `process.exit`.
+ */
+interface ProcessRestarter {
+    /** Log the cause, stop gracefully, then exit with code 75 (`EX_TEMPFAIL`). */
+    restart: (request: RestartRequest) => void;
+}
+
+/**
+ * @module watcher/ChangeSourceHealthTracker
+ * `health.changeSource` (D133, D157): counters since start, owned by the app so they survive watcher rebuilds, plus the cause of the exit for a restart this process started after (D196). Pure.
+ */
+
+/**
+ * Counts and timestamps behind `health.changeSource`. Never holds a path in
+ * its snapshot (D89).
+ */
+declare class ChangeSourceHealthTracker {
+    private source;
+    private resubscribes;
+    private renewFailures;
+    private reconcileEvents;
+    private reconcileErrors;
+    private lastReconcileAt;
+    private lastReconcileDurationMs;
+    private lastRenewDurationMs;
+    private lastRestart;
+    private readonly unavailable;
+    private pendingStability;
+    /** Record the running source and its pending-stability reader. */
+    attach(source: ChangeSourceHealth['source'], pending: () => number): void;
+    /** A subscription was re-created after an error (D131). */
+    recordResubscribe(): void;
+    /**
+     * A renewal forced a source rebuild (D165), or rejected inside one
+     * (D176).
      *
-     * @returns Delay in milliseconds.
+     * @param count - Failures to add (default 1).
      */
-    get currentBackoffMs(): number;
+    recordRenewFailure(count?: number): void;
+    /** A subscription renewal finished (Linux parcel, D129, D157). */
+    recordRenew(durationMs: number): void;
     /**
-     * Sleep for the current backoff duration.
+     * The previous process exited for a restart (D196): its cause and when.
      *
-     * @param signal - Optional abort signal.
+     * @param restart - The record it left.
      */
-    backoff(signal?: AbortSignal): Promise<void>;
-    /** Current consecutive failure count. */
-    get failures(): number;
+    recordRestart(restart: {
+        cause: RestartCause;
+        at: string;
+    }): void;
+    /** Mark a root unavailable (D109) or available again. */
+    setUnavailable(root: string, unavailable: boolean): void;
+    /** Synthetic events a reconcile emitted (D90). */
+    recordReconcileEvents(count: number): void;
+    /** A reconcile finished (walk and compare). */
+    recordReconcile(durationMs: number, at: Date): void;
+    /** A reconcile errored and emitted nothing (D90). */
+    recordReconcileError(): void;
+    /** The `health.changeSource` body. */
+    snapshot(): ChangeSourceHealth;
 }
 
 /**
- * Options for {@link FileSystemWatcher} beyond basic config.
+ * @module watcher/running
+ * What one `FileSystemWatcher.start` builds: the change source (parcel or chokidar, D125), filters, inventory, filtered handlers, queue actions and, for parcel, the batch pipeline, wired together. Pure apart from constructing the source (not started here).
+ */
+
+/**
+ * Options for `FileSystemWatcher` beyond basic config.
  */
 interface FileSystemWatcherOptions {
     /** Maximum consecutive system-level failures before fatal error. */
@@ -1615,27 +2567,75 @@ interface FileSystemWatcherOptions {
     /** Optional content hash cache for move detection. */
     contentHashCache?: ContentHashCache;
     /** Optional callback for VCS file change notifications. */
-    onVcsFileChange?: (filePath: string, event: 'add' | 'change' | 'unlink') => void;
-    /** Optional callback invoked when the initial filesystem scan completes. */
-    onInitialScanComplete?: () => void | Promise<void>;
+    onVcsFileChange?: VcsFileChange;
+    /**
+     * Optional callback invoked when the initial filesystem scan completes,
+     * with the index check's view of the watcher that completed it (D197).
+     */
+    onInitialScanComplete?: (view: IndexCheckView) => void | Promise<void>;
+    /** `health.changeSource` counters (D133), owned by the app across rebuilds. */
+    changeSourceHealth?: ChangeSourceHealthTracker;
+    /** Live `watch.reconcileIntervalMs` (D111), read at each scheduling. */
+    getReconcileIntervalMs?: () => number | undefined;
+    /** Imports `@parcel/watcher` (tests; default the real module, D125). */
+    importParcel?: ParcelImporter;
+    /** The service state directory (the parcel rebuild sentinel, D165). */
+    stateDir?: string;
+    /**
+     * Exits for a service-manager restart where parcel never unsubscribes
+     * (Windows, D196); default an immediate exit.
+     */
+    restarter?: ProcessRestarter;
+}
+
+/**
+ * @module watcher/indexCheck/view
+ * What the index check at start (D197) reads from a running `FileSystemWatcher`: its roots, why a root must be skipped (unavailable D109, unwatched D156, start walk failed) and whether the inventory holds a path. Pure.
+ */
+
+/** Why a root is not checked (besides being gone at check time). */
+type IndexCheckSkipReason = 'unavailable' | 'unwatched' | 'walkFailed';
+/** The running watcher as the index check sees it. */
+interface IndexCheckView {
+    /** The resolved watch roots, nested ones collapsed (D195 case). */
+    roots: readonly string[];
+    /**
+     * Why the root must be skipped, or undefined when it can be checked.
+     *
+     * @param root - One of {@link IndexCheckView.roots}.
+     */
+    skipReason: (root: string) => IndexCheckSkipReason | undefined;
+    /**
+     * Whether the inventory holds the file (its point-ID key form).
+     *
+     * @param path - A file path.
+     */
+    has: (path: string) => boolean;
+    /** Whether this running state is still the watcher's (no stop or rebuild). */
+    live: () => boolean;
 }
+
 /**
- * Filesystem watcher that maps chokidar events to the processing queue.
+ * @module watcher
+ * Filesystem watcher: drives a change source (parcel or chokidar, D125) through the `ChangeSink` seam, filters its events, keeps the inventory and enqueues processing. I/O: watches files, enqueues processor work.
  */
-declare class FileSystemWatcher {
+
+/**
+ * Filesystem watcher. A change source only reports events (D120); this
+ * class filters them, keeps the inventory (D99) and maps them to the
+ * processing queue.
+ */
+declare class FileSystemWatcher implements ChangeSink {
     private readonly config;
     private readonly queue;
     private readonly processor;
     private readonly logger;
+    private readonly options;
     private readonly health;
-    private readonly gitignoreFilter?;
-    private readonly initialScanTracker?;
-    private readonly contentHashCache?;
-    private readonly onVcsFileChange?;
-    private readonly onInitialScanComplete?;
-    private moveCorrelator?;
-    private globMatches;
-    private watcher;
+    private running;
+    /** A stopped source left its watches live (D196). */
+    private leftWatches;
+    private initialScanComplete;
     /**
      * Create a new FileSystemWatcher.
      *
@@ -1647,36 +2647,64 @@ declare class FileSystemWatcher {
      */
     constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessorInterface, logger: pino.Logger, options?: FileSystemWatcherOptions);
     /**
-     * Start watching the filesystem and processing events.
-     */
-    start(): void;
-    /**
-     * Get the list of all currently watched file paths (absolute).
+     * Start watching the filesystem and processing events. With parcel the
+     * roots are subscribed first, then walked in the background (D58).
      *
-     * Uses chokidar's in-memory `getWatched()` state — no filesystem I/O.
-     * Returns an empty array if the watcher hasn't been started.
+     * @throws ChangeSourceLoadError when parcel is selected and cannot load.
      */
-    getWatchedFiles(): string[];
-    /**
-     * Whether the initial filesystem scan is complete.
+    start(): Promise<void>;
+    /** A classified event from the change source (chokidar), with the stats it read, if any. */
+    event(type: ClassifiedEventType, path: string, stats?: Stats): void;
+    /**
+     * The directory-create handler (D91, D120): reconcile a directory created
+     * after the initial scan, so files written into it before its watch was
+     * set up are not missed. The reconciler drops it before the scan ends.
+     */
+    private directoryCreated;
+    /** Start a reconcile of `dir` (every trigger is owned here, D120). */
+    private reconcile;
+    /**
+     * A raw parcel batch (D149): into the FIFO, classified from the disk and
+     * applied in order.
+     */
+    rawEvents(root: string, events: RawChangeEvent[]): void;
+    /** The source finished its initial set for a root; the scan completes when every root has. */
+    initialScanDone(sourceRoot: string): void;
+    /** The source re-created a root's subscription after an error (D131). */
+    resubscribed(sourceRoot: string): void;
+    /** A root is unreachable (D109), or reachable but unwatched (D156). */
+    rootUnavailable(sourceRoot: string, code: string, options?: RootUnavailableOptions): void;
+    /** A root is reachable again (D109). */
+    rootAvailable(sourceRoot: string): void;
+    /** A root signal's context (the canonical root), or undefined when not running. */
+    private signal;
+    /**
+     * The inventory's file paths (absolute, as the source reported them):
+     * matched files only, never directories or filtered files (D83). No
+     * filesystem I/O; empty before start.
      */
+    getWatchedFiles(): string[];
+    /** Whether the initial filesystem scan is complete. */
     get isReady(): boolean;
     /**
-     * Stop the filesystem watcher.
+     * Whether a rebuild must exit for a restart (D196): the running source,
+     * or one this watcher stopped (its watches stay live), cannot release
+     * its watches in-process (parcel on Windows).
      */
+    get restartsToRebuild(): boolean;
+    /** The running watcher's inventory (D99), undefined before start. */
+    get inventory(): Inventory | undefined;
+    /** What the index check at start reads (D197); undefined before start. */
+    get indexCheckView(): IndexCheckView | undefined;
+    /** Stop the filesystem watcher. */
     stop(): Promise<void>;
-    /**
-     * Get the system health tracker.
-     */
+    /** Get the system health tracker. */
     get systemHealth(): SystemHealth;
     /**
-     * Check if a path is gitignored and should be skipped.
-     */
-    private isGitignored;
-    /**
-     * If the changed file is a `.gitignore`, invalidate the filter cache.
+     * Re-arm the periodic reconcile timers with the live interval: a reload
+     * that changed only `watch.reconcileIntervalMs` needs no rebuild (D111).
      */
-    private handleGitignoreChange;
+    refreshReconcileSchedule(): void;
     /**
      * Wrap a processing operation with health tracking.
      * On success, resets the failure counter.
@@ -1689,19 +2717,7 @@ declare class FileSystemWatcher {
  * @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;
-    /** Number of files processed so far (when {@link active} is true). */
-    filesProcessed?: number;
-    /** Total number of files to process (when {@link active} is true). */
-    totalFiles?: number;
-}
+
 /**
  * Tracks the state of reindex operations.
  */
@@ -1724,24 +2740,30 @@ declare class ReindexTracker {
 }
 
 /**
- * @module api
- * Fastify API server factory. Registers all route handlers and returns an unstarted server instance.
+ * @module api/apiServerOptions
+ * Options accepted by createApiServer: processor, stores, queues, config access, trackers and optional collaborators (virtual rules, VCS, source queue). Types only.
  */
 
 /**
- * Options for {@link createApiServer}.
+ * Options for `createApiServer`.
  */
 interface ApiServerOptions {
+    /**
+     * Queues paused while a prune deletes points. The service passes
+     * `combinePausableQueues(fileQueue, sourceQueue)` (`app/index.ts`), so a
+     * prune quiesces both the file event queue and the source notify queue.
+     */
+    queue: PausableQueue;
+    /** Source notify queue (`POST /documents`); absent in file-only setups. */
+    sourceQueue?: SourceNotifyQueue;
     /** The component descriptor (used for config-apply handler). */
     descriptor: JeevesComponentDescriptor;
-    /** The document processor. */
-    processor: DocumentProcessorInterface;
+    /** The document processor: file and source operations. */
+    processor: WatcherProcessor;
     /** The vector store client. */
     vectorStore: VectorStoreClient;
     /** The embedding provider. */
     embeddingProvider: EmbeddingProvider;
-    /** The event queue. */
-    queue: EventQueue;
     /** The application configuration (used as initial/fallback value). */
     config: JeevesWatcherConfig;
     /** Config getter for live config access after hot-reload. */
@@ -1758,27 +2780,56 @@ interface ApiServerOptions {
     configPath: string;
     /** Helper introspection for merged document. */
     helperIntrospection?: AllHelpersIntrospection;
-    /** Virtual rule store for externally registered inference rules. */
-    virtualRuleStore?: VirtualRuleStore;
+    /** Virtual rule store for externally registered inference rules (the
+     * `/rules/*` routes). */
+    virtualRuleStore: VirtualRuleStore;
     /** Gitignore filter for reindex path validation. */
     gitignoreFilter?: GitignoreFilter;
     /** Service version string for /status endpoint. */
     version?: string;
     /** Initial scan tracker for /status visibility. */
     initialScanTracker?: InitialScanTracker;
-    /** Filesystem watcher instance for /walk endpoint (in-memory file list). */
+    /** Filesystem watcher instance for /walk endpoint (its inventory, D83). */
     fileSystemWatcher?: FileSystemWatcher;
     /** Getter for live filesystem watcher access after hot-reload rebuilds. */
     getFileSystemWatcher?: () => FileSystemWatcher | undefined;
     /** Optional enrichment store for persisted enrichment metadata. */
     enrichmentStore?: EnrichmentStoreInterface;
-    /** VCS coordinator for git-backed versioning API routes. */
+    /** VCS coordinator for the git-backed versioning (`/vcs/*`) routes; without
+     * it they answer as unregistered (`api/featureGates`). */
     vcsCoordinator?: VcsCoordinator;
+    /**
+     * Longest document-lock wait of `POST /metadata`, `POST /rules/reapply`
+     * and `POST /documents/delete` (default 10 s, D118; tests only).
+     */
+    documentLockWaitMs?: number;
+    /** Embedding health (`GET /status` `health.embedding`, D88). */
+    embeddingHealth?: {
+        snapshot: () => EmbeddingHealthSnapshot;
+    };
+    /** Change-source health (`GET /status` `health.changeSource`, D133). */
+    changeSourceHealth?: {
+        snapshot: () => ChangeSourceHealth;
+    };
+    /** Index check at start (`health.indexCheck`, D197). */
+    indexCheckHealth?: {
+        snapshot: () => IndexCheckHealth;
+    };
 }
+
+/**
+ * @module api
+ * Fastify API server factory. Registers every `WATCHER_CATALOG` route (plus `GET /openapi.json`) from the catalog, and returns an unstarted server instance.
+ */
+
 /**
  * Create the Fastify API server with all routes registered.
  *
- * The returned instance is not yet listening — call `server.listen()` to start.
+ * The returned instance is not yet listening; call `server.listen()` to
+ * start. The catalog routes are registered in a child plugin, so a
+ * registration error surfaces from `ready()` or `listen()` (spec #281 D29).
+ * The `/vcs/*` routes answer as unregistered unless a `vcsCoordinator` is
+ * given (`api/featureGates`).
  *
  * @param options - The server options.
  * @returns A configured Fastify instance.
@@ -1786,29 +2837,90 @@ interface ApiServerOptions {
 declare function createApiServer(options: ApiServerOptions): FastifyInstance;
 
 /**
- * @module logger
- * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
+ * @module config/warnings
+ * The non-fatal config warning shape shared by config loading (unknown source keys, reserved rule field names) and `POST /config/validate`. Types only.
+ */
+/** A non-fatal config validation warning. */
+interface ConfigWarning {
+    /** Config location the warning refers to. */
+    path: string;
+    /** Human-readable warning message. */
+    message: string;
+}
+
+/**
+ * @module config/loadConfig
+ * Loads the watcher config via cosmiconfig: schema validation, rule/map file resolution, defaults, env substitution and secret checks; reports non-fatal warnings (unknown source keys, reserved rule field names) through onWarning. Reads files.
+ */
+
+/** Options of {@link loadConfig}. */
+interface LoadConfigOptions {
+    /**
+     * Receives non-fatal warnings once the config has loaded successfully:
+     * unknown keys under `sources.<name>` (which validation drops), then rule
+     * schema properties named like reserved system fields.
+     */
+    onWarning?: (warning: ConfigWarning) => void;
+}
+/**
+ * Load the jeeves-watcher configuration.
+ *
+ * @param configPath - Optional explicit path to a config file.
+ * @param options - Optional warning sink.
+ * @returns The loaded configuration.
+ * @throws If no configuration is found or validation fails.
  */
+declare function loadConfig(configPath?: string, options?: LoadConfigOptions): Promise<JeevesWatcherConfig>;
 
 /**
- * Create a pino logger instance.
+ * Create a pino logger. With `logging.file`, the file is open (or the
+ * call rejects) before the logger is returned, so no early line is lost.
  *
  * @param config - Optional logging configuration.
  * @returns A configured pino logger.
  */
-declare function createLogger(config?: LoggingConfig): pino.Logger;
+declare function createLogger(config?: LoggingConfig): Promise<pino.Logger>;
+
+/**
+ * @module app/processRestarter
+ * The app's exit for a service-manager restart (D196): log the cause, leave a restart record in the state directory, stop gracefully (with a hard deadline), then exit with `RESTART_EXIT_CODE`; at the next start, read the record, report it in `health.changeSource` (the app runs any deferred config reindex) and clear it once the start succeeded. I/O: the record file, a timer, `process.exit`.
+ */
+
+/** What `createProcessRestarter` needs from the app. */
+interface ProcessRestarterDeps {
+    /** The state directory (the record goes there). */
+    stateDir: string;
+    /** The app's logger, once it exists. */
+    logger: () => pino.Logger | undefined;
+    /** The app's graceful stop. */
+    stop: () => Promise<void>;
+    /**
+     * The longest the graceful stop may take before the process exits
+     * anyway: some stop steps (a hung `lstat` or git call) have no timeout.
+     */
+    deadlineMs: number;
+    /** `process.exit` (tests). */
+    exit?: (code: number) => void;
+    /** The clock (tests). */
+    now?: () => Date;
+}
 
 /**
  * @module app/factories
  * Component factory interfaces and defaults for {@link JeevesWatcher}. Override in tests to inject mocks.
  */
 
+/** Runtime options for {@link JeevesWatcher} that aren't serializable in config. */
+interface JeevesWatcherRuntimeOptions {
+    /** Callback invoked on unrecoverable system error. If not set, throws. */
+    onFatalError?: (error: unknown) => void;
+}
 /**
  * Component factories for {@link JeevesWatcher}. Override in tests to inject mocks.
  */
 interface JeevesWatcherFactories {
     /** Load and validate a {@link JeevesWatcherConfig} from disk. */
-    loadConfig: (configPath?: string) => Promise<JeevesWatcherConfig>;
+    loadConfig: (configPath?: string, options?: LoadConfigOptions) => Promise<JeevesWatcherConfig>;
     /** Create a pino logger instance. */
     createLogger: typeof createLogger;
     /** Create an embedding provider from config. */
@@ -1818,15 +2930,43 @@ interface JeevesWatcherFactories {
     /** Compile inference rules from config. */
     compileRules: typeof compileRules;
     /** Create a document processor for file ingestion. */
-    createDocumentProcessor: (deps: ConstructorParameters<typeof DocumentProcessor>[0]) => DocumentProcessorInterface;
+    createDocumentProcessor: (deps: ConstructorParameters<typeof DocumentProcessor>[0]) => WatcherProcessor;
     /** 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: DocumentProcessorInterface, logger: pino.Logger, options?: FileSystemWatcherOptions) => FileSystemWatcher;
     /** Create the HTTP API server. */
     createApiServer: typeof createApiServer;
+    /** Import `@parcel/watcher` when it is the selected source (D125). */
+    importParcel: ParcelImporter;
+    /**
+     * The exit for a service-manager restart (D196). Tests replace it, so
+     * they never call `process.exit`.
+     */
+    createProcessRestarter: (deps: ProcessRestarterDeps) => ProcessRestarter;
 }
 
+/**
+ * @module app/sources
+ * Startup wiring for source documents: builds the source callback client from `sources` config (read at startup only), the notify queue over the processor's source operations, and the adapter giving a file-only processor failing source operations. No I/O.
+ */
+
+/**
+ * Adapt a custom file-only processor to the {@link WatcherProcessor} the
+ * service runs on. File operations are forwarded unchanged. Its source
+ * operations fail: every notify-queue run returns a `failed` result with
+ * `source_unavailable` (the run's issue, as for a failing callback), and
+ * every other source operation throws the API's `503 not_available`, so
+ * `POST /documents`, `POST /metadata { source }`, `POST /render { source }`
+ * and `POST /reindex { source }` answer as before source support existed.
+ * Use it in a custom `createDocumentProcessor` factory; never wrap a
+ * processor that has source operations of its own (they would be hidden).
+ *
+ * @param processor - The file-only processor.
+ * @returns The processor with failing source operations.
+ */
+declare function withoutSourceSupport(processor: DocumentProcessorInterface): WatcherProcessor;
+
 /**
  * @module app/startFromConfig
  * Convenience entry point: loads config from disk and starts a {@link JeevesWatcher}.
@@ -1850,14 +2990,7 @@ declare function startFromConfig(configPath?: string, descriptor?: JeevesCompone
  * Main application orchestrator. Wires components, manages lifecycle (start/stop/reload).
  */
 
-/** Runtime options for {@link JeevesWatcher} that aren't serializable in config. */
-interface JeevesWatcherRuntimeOptions {
-    /** Callback invoked on unrecoverable system error. If not set, throws. */
-    onFatalError?: (error: unknown) => void;
-}
-/**
- * Main application class that wires together all components.
- */
+/** Main application class that wires together all components. */
 declare class JeevesWatcher {
     private config;
     private readonly configPath?;
@@ -1867,52 +3000,41 @@ declare class JeevesWatcher {
     private logger;
     private watcher;
     private queue;
+    private sourceQueue;
     private server;
     private processor;
     private configWatcher;
-    private issuesManager;
-    private valuesManager;
+    private stores;
     private helperIntrospection;
-    private virtualRuleStore;
+    private readonly virtualRuleStore;
     private vectorStore;
     private embeddingProvider;
+    private embeddingHealth;
     private gitignoreFilter;
-    private enrichmentStore;
-    private contentHashCache;
     private vcsCoordinator;
     private readonly initialScanTracker;
+    private readonly changeSourceHealth;
+    private readonly indexCheck;
+    private readonly restarter;
+    /** The state directory (default `ROOT_DEFAULTS.stateDir`). */
+    private readonly stateDir;
     private readonly version;
     /** Create a new JeevesWatcher instance. */
     constructor(config: JeevesWatcherConfig, configPath?: string, descriptor?: JeevesComponentDescriptor, factories?: Partial<JeevesWatcherFactories>, runtimeOptions?: JeevesWatcherRuntimeOptions);
-    /**
-     * Start the watcher, API server, and all components.
-     */
+    /** Start the watcher, API server, and all components. */
     start(): Promise<void>;
-    /** Set up logger, VCS, embedding provider, and vector store. */
-    private initInfrastructure;
     /** Build the processing pipeline: rules, templates, processor, queue, VCS. */
     private initPipeline;
     /** Wire up watcher and VCS coordinator, then start all services. */
     private startServicesAndWatcher;
-    /**
-     * Gracefully stop all components.
-     */
+    /** Gracefully stop: API server first (no new notifications), then producers, then queues drain (shutdownComponents). */
     stop(): Promise<void>;
-    private startApiServer;
-    private startConfigWatch;
-    private stopConfigWatch;
+    /** Wiring every watcher the app builds shares, across rebuilds. */
+    private watcherWiring;
+    private apiServerOptions;
     private reloadConfig;
 }
 
-/**
- * Load the jeeves-watcher configuration.
- *
- * @param configPath - Optional explicit path to a config file.
- * @returns The loaded configuration.
- * @throws If no configuration is found or validation fails.
- */
-declare function loadConfig(configPath?: string): Promise<JeevesWatcherConfig>;
-
 /**
  * @module descriptor
  * Jeeves Component Descriptor for the watcher service. Single source of truth
@@ -1983,112 +3105,5 @@ interface ResolvedWatchRoot {
     relativePath: string;
 }
 
-/**
- * @module vcs/SquashManager
- * Handles scheduled squash retention for git-backed VCS roots.
- */
-
-/** Result of a squash operation. */
-interface SquashResult {
-    squashed: boolean;
-    commitsRemoved?: number;
-    commitsRetained?: number;
-    error?: string;
-}
-/** Commit metadata for retention calculation. */
-interface CommitInfo {
-    hash: string;
-    date: Date;
-}
-/** Options for SquashManager construction beyond the required params. */
-interface SquashManagerOptions {
-    /** Git branch name for squash operations. Default: "master". */
-    branch?: string;
-    /** Called before squash to drain and pause the commit pipeline. */
-    pauseCommits?: () => Promise<void>;
-    /** Called after squash to resume the commit pipeline. */
-    resumeCommits?: () => void;
-    /** Remote URL for force-push after squash. */
-    remoteUrl?: string;
-    /** Access token for HTTPS push authentication. */
-    accessToken?: string;
-}
-/**
- * Manages scheduled squash retention for a single VCS root.
- *
- * Runs on a cron schedule (checked every 60s). When triggered, squashes
- * commits older than the retention boundary (the tighter of maxAgeDays
- * and maxVersions) into a single "historical baseline" orphan commit,
- * then cherry-picks retained commits on top. Force-pushes to remote
- * if configured (D13).
- */
-declare class SquashManager {
-    private readonly rootPath;
-    private readonly retention;
-    private readonly branch;
-    private readonly pauseCommits;
-    private readonly resumeCommits;
-    private readonly remoteUrl;
-    private readonly accessToken;
-    private readonly logger;
-    private intervalTimer;
-    private running;
-    constructor(rootPath: string, retention: VcsRetentionConfig, logger: pino.Logger, options?: SquashManagerOptions);
-    /**
-     * Start the cron-based squash scheduler.
-     * Checks every 60 seconds if the cron expression matches.
-     */
-    start(): void;
-    /**
-     * Stop the cron scheduler.
-     */
-    stop(): void;
-    /**
-     * Run the squash operation. Exposed publicly for testing.
-     *
-     * Coordinates with VcsManager by calling pause/resume callbacks
-     * to drain and suspend the commit pipeline during the squash.
-     */
-    runSquash(): Promise<SquashResult>;
-    /**
-     * Refuse to start a multi-step history rewrite while another git
-     * operation holds the index or an abandoned cherry-pick, rebase, or merge
-     * is present (#249: report only, never auto-clear).
-     *
-     * @returns The refusal reason, or undefined if the squash may proceed.
-     */
-    private checkRepoPreconditions;
-    /**
-     * Get all commits in chronological order (oldest first).
-     */
-    getCommitLog(): Promise<CommitInfo[]>;
-    /**
-     * Calculate the retention boundary index.
-     * Returns the index of the oldest commit to KEEP.
-     * All commits before this index will be squashed into a baseline.
-     *
-     * Strategy: find the tighter constraint between age and count.
-     * - Age: keep commits newer than maxAgeDays
-     * - Count: keep the last maxVersions commits
-     * The boundary is the one that retains FEWER old commits (tighter).
-     */
-    calculateRetentionBoundary(commits: CommitInfo[]): number;
-    /**
-     * Perform the squash: create orphan with baseline + cherry-pick retained commits.
-     * Uses the configured branch name instead of dynamic detection (Bug 1).
-     */
-    private performSquash;
-    /**
-     * Best-effort cleanup after a failed squash. Aborts any half-finished
-     * cherry-pick first, so a failure never leaves a sequencer behind (#249),
-     * then returns to the configured branch and removes a leftover lock.
-     */
-    private cleanupFailedSquash;
-    /**
-     * Force push to remote after squash (history rewrite requires force).
-     */
-    private forcePushIfConfigured;
-}
-
-export { CommitMessageGenerator, ContentHashCache, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SquashManager, SystemHealth, TemplateEngine, ValuesManager, VcsCoordinator, VcsManager, VectorStoreClient, VirtualRuleStore, applyRules, buildAttributes, buildTemplateEngine, compileRules, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, extractText, issueRecordSchema, loadConfig, loadCustomHelpers, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, watcherDescriptor };
-export type { AllHelpersIntrospection, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CommitInfo, CompiledRule, CompiledTemplate, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, PayloadFieldSchema, PendingReversion, ProcessFn, ProcessorConfig, ProviderFactory, PushError, ReindexStatus, RenderResult, ResolvedWatchRoot, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SquashManagerOptions, SquashResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, WatchEvent };
+export { ChangeSourceHealthTracker, CommitMessageGenerator, ContentHashCache, DEFAULT_SOURCE_NOTIFY_CONCURRENCY, DocumentLocks, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, Inventory, IssuesManager, JeevesWatcher, ReindexTracker, RootGitLock, SourceClient, SourceNotifyQueue, SourceNotifyQueueStoppedError, SourceReferenceError, SquashManager, SystemHealth, TemplateEngine, ValuesManager, VcsCoordinator, VcsManager, VectorStoreClient, VirtualRuleStore, applyRules, buildAttributes, buildTemplateEngine, compileRules, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, extractText, fileLockKey, loadConfig, loadCustomHelpers, mergeEnrichment, parseSourceReference, parsedSourceReferenceSchema, pointId, registerBuiltinHelpers, resolveTemplateSource, resolvedSourceReferenceSchema, sourceAttributesSchema, sourceErrorCodeSchema, sourceNotifyQueueOptionsSchema, sourceRejectionCodeSchema, sourceRetrievalResultSchema, startFromConfig, watcherDescriptor, withoutSourceSupport };
+export type { AllHelpersIntrospection, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, ChangeSink, CircuitBreakerSnapshot, ClassifiedEventType, CollectionInfo, CommitInfo, CompiledRule, CompiledTemplate, ConfigWarning, DocumentLockOptions, DocumentProcessorDeps, DocumentProcessorInterface, EmbedOptions, EmbeddingErrorSummary, EmbeddingHealthSnapshot, EmbeddingHealthState, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FacetHit, FacetRead, FacetStore, FacetValue, FileAttributes, FileStats, FileSystemWatcherOptions, HelperModuleIntrospection, IndexCheckSkipReason, IndexCheckView, IndexOptions, InventoryEntry, IssuesFile, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoadConfigOptions, ParcelImporter, ParcelWatcherModule, ParsedSourceReference, PausableQueue, PayloadFieldSchema, PendingReversion, ProcessFn, ProcessNowOptions, ProcessRestarter, ProcessRestarterDeps, ProcessingLimits, ProcessorConfig, ProviderFactory, PushError, RangeBound, RangeEnd, RawChangeEvent, RenderResult, ResolvedSourceReference, ResolvedWatchRoot, RestartRequest, RootUnavailableOptions, RuleAttributes, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SourceAttributes, SourceErrorCode, SourceNotifyQueueOptions, SourceOperationsInterface, SourceOperationsProvider, SourceProcess, SourceQueueIssues, SourceRejectionCode, SourceRenderOutcome, SourceRetrievalResult, SourceRetriever, SquashManagerOptions, SquashResult, SystemHealthOptions, SystemIndexState, ValuesIndex, VcsBreakerState, VcsFileChange, VcsManagerOptions, VectorPoint, VectorStore, WatchEvent, WatcherProcessor };