@karmaniverous/jeeves-watcher 0.20.0 → 0.21.0-0

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 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, IssueRecord, InferenceRule, SchemaEntry, SourcesConfig, VectorStoreConfig, DocumentResult, DocumentRejectionError, DocumentFailure, VcsConfig, JeevesWatcherConfig, WatchConfig, LoggingConfig, VcsRetentionConfig } from '@karmaniverous/jeeves-watcher-core';
-export { ApiConfig, ConfigWatchConfig, EmbeddingConfig, InferenceRule, IssueRecord, JeevesWatcherConfig, JeevesWatcherConfigInput, LoggingConfig, VectorStoreConfig, WatchConfig, apiConfigSchema, configWatchConfigSchema, embeddingConfigSchema, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loggingConfigSchema, vectorStoreConfigSchema, watchConfigSchema } from '@karmaniverous/jeeves-watcher-core';
 import { ErrorObject } from 'ajv';
 import Handlebars from 'handlebars';
 import { z } from 'zod';
-import { JsonMapMap } from '@karmaniverous/jsonmap';
 import { Stats } from 'node:fs';
+import ParcelWatcher from '@parcel/watcher';
+import { JsonMapMap } from '@karmaniverous/jsonmap';
 
 /**
  * @module embedding/types
@@ -80,6 +81,38 @@ 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- or source-reference-keyed metadata (references verbatim) at stateDir/enrichments.sqlite. Atomic writes, supports move.
@@ -602,6 +635,60 @@ 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.
@@ -860,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.
@@ -961,6 +1116,37 @@ interface VectorStore {
      * @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.
      *
@@ -1041,6 +1227,8 @@ interface VectorStore {
  * fresh client (see QdrantWriter).
  */
 declare class VectorStoreClient implements VectorStore {
+    /** Facet reads behind `countFacets` (spec Design 12). */
+    readonly facets: FacetStore;
     private readonly client;
     private readonly writer;
     private readonly clientConfig;
@@ -1048,6 +1236,7 @@ declare class VectorStoreClient implements VectorStore {
     private readonly dims;
     private readonly pinoLogger?;
     private readonly payloadIndexes;
+    private readonly systemIndexes;
     /**
      * Create a new VectorStoreClient.
      *
@@ -1066,18 +1255,26 @@ declare class VectorStoreClient implements VectorStore {
      * (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 (Cosine, configured dimensions) and create
-     * any missing payload indexes (configured plus `source`/`source_rule`).
+     * any missing payload indexes (configured plus `source`/`source_rule`),
+     * then start the background system-index builds (D74, D154; not awaited).
      */
     ensureCollection(): Promise<void>;
+    /** @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>;
     /** {@inheritDoc VectorStore.delete} */
@@ -1086,77 +1283,39 @@ declare class VectorStoreClient implements VectorStore {
     setPayload(ids: string[], payload: Record<string, unknown>): Promise<void>;
     /** {@inheritDoc VectorStore.deletePayload} */
     deletePayload(ids: string[], keys: string[]): 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.
-     * @throws When the read fails (never reported as a missing point).
-     */
+    /** {@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.
-     * @throws When the read fails (never reported as missing points).
-     */
+    /** {@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.
@@ -1211,6 +1370,10 @@ interface DocumentProcessorDeps {
     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;
 }
 
 /**
@@ -1236,7 +1399,7 @@ interface RenderResult {
 
 /**
  * @module processor/documentPipeline
- * The shared indexing pipeline for resolved documents (file or source): onResolved hook, empty check, hash compare, chunk, embed, upsert, orphan cleanup; plus point deletion.
+ * 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.
  */
 
 /**
@@ -1282,8 +1445,18 @@ interface SourceOperationsInterface {
     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. */
-    updateMetadata(ref: string, metadata: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /**
+     * 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 {
@@ -1306,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). */
@@ -1337,23 +1516,19 @@ type WatcherProcessor = DocumentProcessorInterface & SourceOperationsProvider;
  * Handles extracting text, computing embeddings, and syncing with the vector store.
  */
 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 sourceRetriever?;
+    private readonly locks;
     /**
      * Create a new DocumentProcessor.
      *
      * @param deps - The processor dependencies.
      */
     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. */
@@ -1389,18 +1564,22 @@ declare class DocumentProcessor implements WatcherProcessor {
      *
      * @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 (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.
@@ -1715,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.
@@ -1733,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. */
@@ -1741,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.
@@ -1817,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.
+     * 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 on success (including "nothing staged").
      */
     private commitBatch;
-    /**
-     * One commit attempt: stage, skip if nothing is staged, commit, push.
-     *
-     * @returns true if a commit was created; false for a no-op.
-     */
-    private tryCommit;
-    private onCommitSuccess;
     private onCommitFailure;
 }
 
@@ -1894,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>;
     /**
@@ -1920,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).
      */
@@ -1942,48 +2238,6 @@ declare class VcsCoordinator {
     findManagerForPath(normalizedPath: string): VcsManager | undefined;
 }
 
-/**
- * @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.
- */
-declare class InitialScanTracker {
-    private _active;
-    private _filesMatched;
-    private _filesEnqueued;
-    private _startedAt?;
-    private _completedAt?;
-    private _durationMs?;
-    private _started;
-    /** Mark the initial scan as started. */
-    start(): void;
-    /** Set the total number of matched files. */
-    setMatched(count: number): void;
-    /** Increment the processed file count. */
-    incrementEnqueued(): void;
-    /** Mark the scan as complete. */
-    complete(): void;
-    /** Get current scan status. */
-    getStatus(): InitialScanStatus;
-}
-
 /**
  * @module health
  * Tracks consecutive system-level failures and applies exponential backoff.
@@ -2039,12 +2293,265 @@ declare class SystemHealth {
      * @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;
 }
 
 /**
- * Options for {@link FileSystemWatcher} beyond basic config.
+ * @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.
+ */
+
+/**
+ * Tracks the state of the initial filesystem scan after service start.
+ */
+declare class InitialScanTracker {
+    private _active;
+    private _filesMatched;
+    private _filesEnqueued;
+    private _startedAt?;
+    private _completedAt?;
+    private _durationMs?;
+    private _started;
+    /** Mark the initial scan as started. */
+    start(): void;
+    /** Set the total number of matched files. */
+    setMatched(count: number): void;
+    /** Increment the processed file count. */
+    incrementEnqueued(): void;
+    /** Mark the scan as complete. */
+    complete(): void;
+    /** Get current scan status. */
+    getStatus(): InitialScanStatus;
+}
+
+/**
+ * @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;
+
+/**
+ * @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.
+ */
+/** 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;
+}
+/**
+ * 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 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;
+    /**
+     * Remove a file.
+     *
+     * @returns True when it was present.
+     */
+    delete(path: string): boolean;
+    /** The entry for a path, if present. */
+    get(path: string): InventoryEntry | undefined;
+    /**
+     * Whether a path is a directory the inventory holds files under (D127:
+     * an absent path is classified as a directory delete by this).
+     */
+    isDirectory(path: string): boolean;
+    /** Every file path, as the source reported it (`/walk`, D83). */
+    paths(): string[];
+    /**
+     * 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).
+     *
+     * @param count - Failures to add (default 1).
+     */
+    recordRenewFailure(count?: number): void;
+    /** A subscription renewal finished (Linux parcel, D129, D157). */
+    recordRenew(durationMs: number): void;
+    /**
+     * The previous process exited for a restart (D196): its cause and when.
+     *
+     * @param restart - The record it left.
+     */
+    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;
+}
+
+/**
+ * @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. */
@@ -2060,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.
      *
@@ -2092,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.
@@ -2134,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.
  */
@@ -2209,33 +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 all route handlers (status, query, documents, config, rules, VCS) and returns an unstarted server instance.
+ * 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.
@@ -2279,17 +2873,37 @@ interface LoadConfigOptions {
 declare function loadConfig(configPath?: string, options?: LoadConfigOptions): Promise<JeevesWatcherConfig>;
 
 /**
- * @module logger
- * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
- */
-
-/**
- * Create a pino logger instance.
+ * 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
@@ -2323,6 +2937,13 @@ interface JeevesWatcherFactories {
     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;
 }
 
 /**
@@ -2369,9 +2990,7 @@ declare function startFromConfig(configPath?: string, descriptor?: JeevesCompone
  * Main application orchestrator. Wires components, manages lifecycle (start/stop/reload).
  */
 
-/**
- * Main application class that wires together all components.
- */
+/** Main application class that wires together all components. */
 declare class JeevesWatcher {
     private config;
     private readonly configPath?;
@@ -2385,34 +3004,33 @@ declare class JeevesWatcher {
     private server;
     private processor;
     private configWatcher;
-    private issuesManager;
-    private valuesManager;
+    private stores;
     private helperIntrospection;
     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(): 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: the API server closes first (no new
-     * notifications), then producers stop and queues drain (see
-     * shutdownComponents).
-     */
+    /** Gracefully stop: API server first (no new notifications), then producers, then queues drain (shutdownComponents). */
     stop(): Promise<void>;
+    /** Wiring every watcher the app builds shares, across rebuilds. */
+    private watcherWiring;
     private apiServerOptions;
     private reloadConfig;
 }
@@ -2487,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, DEFAULT_SOURCE_NOTIFY_CONCURRENCY, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SourceClient, SourceNotifyQueue, SourceNotifyQueueStoppedError, SourceReferenceError, SquashManager, SystemHealth, TemplateEngine, ValuesManager, VcsCoordinator, VcsManager, VectorStoreClient, VirtualRuleStore, applyRules, buildAttributes, buildTemplateEngine, compileRules, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, extractText, loadConfig, loadCustomHelpers, mergeEnrichment, parseSourceReference, parsedSourceReferenceSchema, pointId, registerBuiltinHelpers, resolveTemplateSource, resolvedSourceReferenceSchema, sourceAttributesSchema, sourceErrorCodeSchema, sourceNotifyQueueOptionsSchema, sourceRejectionCodeSchema, sourceRetrievalResultSchema, startFromConfig, watcherDescriptor, withoutSourceSupport };
-export type { AllHelpersIntrospection, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CircuitBreakerSnapshot, CollectionInfo, CommitInfo, CompiledRule, CompiledTemplate, ConfigWarning, DocumentProcessorDeps, DocumentProcessorInterface, EmbedOptions, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, IndexOptions, InitialScanStatus, IssuesFile, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoadConfigOptions, ParsedSourceReference, PausableQueue, PayloadFieldSchema, PendingReversion, ProcessFn, ProcessNowOptions, ProcessorConfig, ProviderFactory, PushError, ReindexStatus, RenderResult, ResolvedSourceReference, ResolvedWatchRoot, RuleAttributes, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SourceAttributes, SourceErrorCode, SourceNotifyQueueOptions, SourceOperationsInterface, SourceOperationsProvider, SourceProcess, SourceQueueIssues, SourceRejectionCode, SourceRenderOutcome, SourceRetrievalResult, SourceRetriever, SquashManagerOptions, SquashResult, SystemHealthOptions, ValuesIndex, VcsBreakerState, VectorPoint, VectorStore, WatchEvent, WatcherProcessor };
+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 };