@autorag/librarian 2.13.0 → 2.13.2

package/dist/minsync/client.d.ts

@@ -1,4 +1,4 @@
-import type { MinSyncEmbedderConfig, MinSyncQueryHit, MinSyncSyncResult } from "./types.js";
+import type { MinSyncEmbedderConfig, MinSyncQueryHit, MinSyncSyncProgress, MinSyncSyncResult } from "./types.js";
 export interface MinSyncClientOptions {
     readonly binaryPath: string;
     readonly workspacePath: string;
@@ -32,7 +32,7 @@ export declare class MinSyncClient {
     private readIdentity;
     private writeIdentity;
     private identityMismatch;
-    sync(force?: boolean, signal?: AbortSignal): Promise<MinSyncSyncResult>;
+    sync(force?: boolean, signal?: AbortSignal, onProgress?: (progress: MinSyncSyncProgress) => void): Promise<MinSyncSyncResult>;
     /**
      * The tokenizer to run this sync with: always {@link MINSYNC_LEXICAL_LANGUAGE}, which fails every sync when the
      * Kiwi native library is missing. A workspace that is new, or tokenized differently, then gets whitespace

package/dist/minsync/index.d.ts

@@ -5,5 +5,5 @@ export { type EnsureMinSyncBinaryOptions, ensureMinSyncBinary, executableName, f
 export { ensureLocalEmbedder, LocalEmbedderError, type LocalEmbedderPreflightOptions, } from "./local-embedder.js";
 export { MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";
 export { MINSYNC_FILES_SUBDIR, MINSYNC_SUBDIR, minSyncDocumentPath, minSyncWorkspaceRoot } from "./paths.js";
-export type { MinSyncChunkerConfig, MinSyncDiagnostic, MinSyncEmbedderConfig, MinSyncFileFailure, MinSyncOptions, MinSyncQueryHit, MinSyncSyncResult, } from "./types.js";
+export type { MinSyncChunkerConfig, MinSyncDiagnostic, MinSyncEmbedderConfig, MinSyncFileFailure, MinSyncOptions, MinSyncQueryHit, MinSyncSyncProgress, MinSyncSyncResult, } from "./types.js";
 export { buildMinSyncPathMap, type MinSyncWorkspaceEntry, type MinSyncWorkspaceSyncResult, syncMinSyncWorkspace, } from "./workspace.js";

package/dist/minsync/installer.d.ts

@@ -1,4 +1,4 @@
-export declare const MINSYNC_VERSION = "0.4.12";
+export declare const MINSYNC_VERSION = "0.5.1";
 export declare const MINSYNC_CARGO_INSTALL_TIMEOUT_MS: number;
 export interface MinSyncReleaseAsset {
     readonly name: string;

package/dist/minsync/method.d.ts

@@ -1,7 +1,7 @@
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
 import type { MinSyncQueryMode } from "./client.js";
 import type { EnsureMinSyncBinaryOptions } from "./installer.js";
-import type { MinSyncEmbedderConfig, MinSyncSyncResult } from "./types.js";
+import type { MinSyncEmbedderConfig, MinSyncSyncProgress, MinSyncSyncResult } from "./types.js";
 export interface MinSyncVectorMethodOptions {
     readonly root: string;
     /** Test/embedded override; CLI config intentionally does not persist this. */
@@ -31,7 +31,7 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
     private readonly scopedTopK;
     constructor(options: MinSyncVectorMethodOptions);
     describe(): RetrievalMethodDescriptor;
-    sync(force?: boolean, signal?: AbortSignal): Promise<MinSyncSyncResult>;
+    sync(force?: boolean, signal?: AbortSignal, onProgress?: (progress: MinSyncSyncProgress) => void): Promise<MinSyncSyncResult>;
     private syncUnlocked;
     /** Report unavailable binaries without treating auto-install as already failed. */
     isBinaryMissing(): boolean;
@@ -45,7 +45,7 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
      * Queries pass `install: false` so a user's turn never waits on `cargo install`; only `sync` (refresh)
      * may install. See {@link resolveMinSyncBinary}.
      */
-    protected resolveBinary(options?: {
+    resolveBinary(options?: {
         readonly install?: boolean;
     }): Promise<string>;
 }

package/dist/minsync/process.d.ts

@@ -9,4 +9,5 @@ export declare function spawnProcess(command: string, args: readonly string[], c
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
     readonly env?: NodeJS.ProcessEnv;
+    readonly onStdoutLine?: (line: string) => void;
 }): Promise<ProcessResult>;

package/dist/minsync/stage.d.ts

@@ -0,0 +1,361 @@
+/**
+ * The host side of MinSync's materialization-stage protocol: one JSON request
+ * per line on the child's stdin, one JSON response per line on its stdout
+ * (`minsync stage --state-dir DIR`).
+ *
+ * One session is one run. MinSync holds the stage's state lock from `open`
+ * until `finish` or exit, and the OS releases it on any exit, so a session that
+ * ends without `finish` (EOF, a signal, a crash) leaves the journal behind and
+ * the next `open` resumes from it. Requests are strictly sequential: one
+ * request is in flight at a time, whatever the caller does.
+ *
+ * Keys and output paths stay exactly as given: both are relative to the
+ * session's source listing and to `output_root`, and MinSync validates them at
+ * its own boundary. MinSync is the only authority on what a request means — a
+ * refusal rejects with its protocol code and the session stays usable, while a
+ * request that MinSync never answers (EOF, a dead host-side pipe) rejects too,
+ * so nothing waits on a process that is gone. Each request returns its own
+ * promise; a caller that does not await one owns its rejection.
+ *
+ * `plan` and `inspect` are the read-only doors onto the same state: neither
+ * opens a run, takes the lock, or writes anything, so either may be used
+ * before `open` or while this session's own run is open.
+ *
+ * `open` is the only mutation, so it performs one `capabilities` handshake
+ * first: a build that does not speak this transport's protocol is refused with
+ * `unsupported_protocol` before any state is touched.
+ */
+/** What MinSync decided for one item. Only `process`, `retry` and `delete` are work to do. */
+export type MinSyncStageAction = "process" | "retry" | "skip" | "delete" | "preserve";
+export type MinSyncStageVerify = "fast" | "digest";
+/**
+ * What a MinSync build says it can do, from the `capabilities` op: the stage
+ * protocol revision and the named capabilities it implements.
+ */
+export interface MinSyncStageCapabilities {
+    /** Stage protocol revision; the durable-outcome protocol this host needs is 2. */
+    readonly protocol: number;
+    readonly features: readonly string[];
+}
+/** One current source item, relative to the stage's source listing. */
+export interface MinSyncStageItem {
+    readonly key: string;
+    /**
+     * Any host-chosen string that changes whenever the item's content or its
+     * processing does — the mirror sends a stable JSON identity of the source
+     * path, parser and sizes. Opaque here: the transport passes it through.
+     */
+    readonly version: string;
+}
+export interface MinSyncStageOpenInput {
+    /** Stage name: 1-64 characters of `[A-Za-z0-9._-]`, not starting with `.` or `-`. */
+    readonly stage: string;
+    /** Corpus identity; one state directory belongs to exactly one. */
+    readonly source_id: string;
+    /** Everything that changes what the stage produces (parser name and version, output format, ...). */
+    readonly fingerprint: string;
+    /** Directory holding every output; MinSync creates it if missing. */
+    readonly output_root: string;
+    /** The whole current source. An item absent from `items` and from `unknown` is confirmed gone. */
+    readonly items: readonly MinSyncStageItem[];
+    /** Keys the source could not be observed for: their previous output is kept, never deleted. */
+    readonly unknown?: readonly string[];
+    /** Reuse only what this run committed itself, via its own ledger. */
+    readonly full?: boolean;
+    readonly verify?: MinSyncStageVerify;
+    /**
+     * Identity of the host's retry policy. A deferred failure is only retried
+     * once this differs from the one it was deferred under, so a stage that
+     * changes how it retries does not inherit the previous policy's deferrals.
+     */
+    readonly retry_fingerprint?: string;
+    /** Release every deferred failure now, whatever it was deferred against. */
+    readonly retry_failed?: boolean;
+    /** Wait for another run's lock instead of failing. */
+    readonly wait?: boolean;
+}
+export interface MinSyncStageCounts {
+    readonly process: number;
+    readonly retry: number;
+    readonly skip: number;
+    /** Skips that rest on the interrupted run's ledger (a subset of `skip`). */
+    readonly resumed: number;
+    readonly delete: number;
+    readonly preserve: number;
+}
+export interface MinSyncStageDecision {
+    readonly key: string;
+    readonly action: MinSyncStageAction;
+    /** The source version to process; absent for `skip`, `delete` and `preserve`. */
+    readonly version?: string;
+    /**
+     * Set on the `skip` that stands in for a deferred failure: MinSync is
+     * deliberately not retrying until the source, the settings or the retry
+     * fingerprint change, or the host releases it. `open` reports these so the
+     * host can diagnose them; an unchanged successful skip stays a count.
+     */
+    readonly deferred?: boolean;
+    /** The recorded failure message behind a deferred `skip`. */
+    readonly error?: string;
+}
+export interface MinSyncStageOpenReport {
+    readonly run_token: string;
+    /** An interrupted run's ledger was resumed. */
+    readonly resumed: boolean;
+    readonly counts: MinSyncStageCounts;
+    /**
+     * Work still to do, in key order, plus a `skip` for every deferred failure
+     * MinSync is holding back. Unchanged successful skips stay in `counts`.
+     */
+    readonly decisions: readonly MinSyncStageDecision[];
+}
+/** What the host wrote, relative to `output_root`. `size` and `digest` are optional cross-checks. */
+export interface MinSyncStageOutput {
+    readonly path: string;
+    readonly size?: number;
+    readonly digest?: string;
+}
+/** What MinSync recorded: measured itself, not what the host claimed. */
+export interface MinSyncStageRecordedOutput {
+    readonly path: string;
+    readonly size: number;
+    readonly digest: string;
+}
+export interface MinSyncStageFinishReport {
+    /** Items committed in this run, including ones resumed from its ledger. */
+    readonly committed: number;
+    readonly deleted: number;
+    readonly failed: number;
+    /** Items the next run still has to do. */
+    readonly pending: number;
+}
+/** How `fail` records an item beyond the failure itself. */
+export interface MinSyncStageFailOptions {
+    /**
+     * Keep MinSync from retrying this exact failure until the source, the
+     * settings or the retry fingerprint change, or the host releases it with
+     * `retry_failed`. The item's previous output stays either way.
+     */
+    readonly defer?: boolean;
+    /**
+     * Remove the item's known output through MinSync, so a later run can no
+     * longer reuse it. Without this the last good output is preserved.
+     */
+    readonly discard_output?: boolean;
+}
+/** A stage to reconstruct the durable state of; no open session is needed. */
+export interface MinSyncStageInspectInput {
+    readonly stage: string;
+    readonly source_id: string;
+    readonly output_root: string;
+    readonly verify?: MinSyncStageVerify;
+}
+/** One durable output, as the recorded commit measured it. */
+export interface MinSyncStageInspectOutput {
+    readonly path: string;
+    readonly size: number;
+    readonly digest: string;
+    /** Modification time at commit, in nanoseconds, as a decimal string. */
+    readonly mtime_ns: string;
+}
+/** One source item MinSync holds a verified output for. */
+export interface MinSyncStageInspectItem {
+    readonly key: string;
+    /** The host's own source version for the item; MinSync only stores it. */
+    readonly version: string;
+    readonly fingerprint: string;
+    readonly output: MinSyncStageInspectOutput;
+    /** Stable timestamp of this output, derived from the recorded mtime. */
+    readonly updated_at: string;
+}
+/** The latest failure MinSync holds for an item. */
+export interface MinSyncStageInspectFailure {
+    readonly key: string;
+    /** The source version that failed, absent when the host did not name one. */
+    readonly version: string | null;
+    readonly error: string;
+    /** MinSync is holding the failure back instead of retrying it. */
+    readonly deferred: boolean;
+}
+/** A deliberate omission MinSync recorded for an item. */
+export interface MinSyncStageInspectSkip {
+    readonly key: string;
+    readonly version: string;
+    readonly reason: string;
+    readonly fingerprint: string;
+}
+/** A key MinSync still holds durable state for, and the version it holds it at. */
+export interface MinSyncStageInspectKnown {
+    readonly key: string;
+    /**
+     * The failure's version when MinSync holds one, else the omission's, else
+     * the completion's. `null` only for a legacy failure the host never named.
+     */
+    readonly version: string | null;
+}
+/**
+ * The durable state of a stage: every output that still verifies, every
+ * failure and every deliberate omission. An item can appear in `items` with
+ * its last good output and in `failed` for a newer version at the same time.
+ */
+export interface MinSyncStageInspectReport {
+    readonly items: readonly MinSyncStageInspectItem[];
+    readonly failed: readonly MinSyncStageInspectFailure[];
+    readonly skipped: readonly MinSyncStageInspectSkip[];
+    /**
+     * Every key the durable state holds, whatever the three lists above report:
+     * a key stays here when its output no longer verifies or when its failure is
+     * deferred. Always present, empty when the state holds nothing.
+     */
+    readonly known: readonly MinSyncStageInspectKnown[];
+}
+export interface MinSyncStagePlanReport {
+    readonly counts: MinSyncStageCounts;
+    /**
+     * Every item's decision, in key order — `skip` and `preserve` included, so
+     * the host can report staleness without opening a run.
+     */
+    readonly decisions: readonly MinSyncStageDecision[];
+}
+/**
+ * A stage session failure. `code` is MinSync's protocol code when it refused the
+ * request (`invalid_output_path`, `output_missing`, `version_mismatch`,
+ * `unknown_item`, `still_present`, `lock_failed`, ...) and a transport code when
+ * it never answered: `spawn_failed`, `eof`, `invalid_response`, `process_failed`.
+ */
+export declare class MinSyncStageError extends Error {
+    readonly code: string;
+    readonly op: string | undefined;
+    /** Tail of the session's stderr, for a failure MinSync could not report itself. */
+    readonly stderr: string;
+    constructor(code: string, message: string, details?: {
+        readonly op?: string;
+        readonly stderr?: string;
+    });
+}
+export declare class MinSyncStageSession {
+    private readonly child;
+    private readonly lines;
+    private readonly signal;
+    private readonly exitPromise;
+    private readonly settleExit;
+    /** The caller gave up: stop the tree, then reject with the caller's own reason. */
+    private readonly abortHandler;
+    private stderrTail;
+    private stderrTruncated;
+    private pending;
+    private closedReason;
+    private exit;
+    private tail;
+    private closing;
+    /** The one capability handshake this session performs, before it mutates. */
+    private handshake;
+    private escalation;
+    /**
+     * Start `minsync stage --state-dir stateDir` in `cwd`. `stateDir` holds the
+     * run's lock, marker, journal and snapshot, and belongs to one stage and one
+     * source. An aborted `signal` rejects the in-flight request with the signal's
+     * reason and takes the process tree down, which releases the stage lock.
+     */
+    constructor(binaryPath: string, stateDir: string, cwd: string, signal?: AbortSignal);
+    /**
+     * Open a run, or resume the interrupted one, and return what it still has to
+     * do. A refusal (bad key, duplicate item, held lock, ...) rejects with its
+     * protocol code.
+     *
+     * A run is the first thing this transport mutates, so it first asks the
+     * build what it implements — once per session — and refuses to start
+     * against one that cannot own durable parsing outcomes.
+     */
+    open(input: MinSyncStageOpenInput): Promise<MinSyncStageOpenReport>;
+    /** Check this binary's contract without opening or creating a stage. */
+    verifyProtocol(): Promise<void>;
+    /**
+     * The one capability handshake this session performs, started on first use
+     * and always inside the request queue: a build from before the extended
+     * protocol answers the capabilities op with a refusal, or claims less than
+     * a run requires, and both become `unsupported_protocol`.
+     */
+    private capabilities;
+    private checkCapabilities;
+    /**
+     * Preview what a run with the same request would do, without opening one:
+     * no lock, no journal, no snapshot write. Unlike `open` it lists every
+     * decision — `skip` and `preserve` included — so the host can report
+     * staleness without a session.
+     */
+    plan(input: MinSyncStageOpenInput): Promise<MinSyncStagePlanReport>;
+    /**
+     * Reconstruct a stage's durable state from its snapshot and journal and
+     * verify every recorded output. Non-mutating: it takes no lock, so it is
+     * safe while another run of the same stage is open (that run's own journal
+     * records are merged in), and it needs no `open` of its own.
+     */
+    inspect(input: MinSyncStageInspectInput): Promise<MinSyncStageInspectReport>;
+    /**
+     * Commit an item's output: `output.path` is relative to `output_root` and must
+     * already be written. MinSync checks the file and returns what it recorded.
+     */
+    commit(key: string, version: string, output: MinSyncStageOutput): Promise<MinSyncStageRecordedOutput>;
+    /**
+     * Record that an item could not be produced. Its previous output stays
+     * intact unless `discard_output` asks MinSync to remove it, and `defer`
+     * keeps MinSync from retrying this same failure until the source, the
+     * settings or the retry fingerprint change.
+     */
+    fail(key: string, version: string, error: string, options?: MinSyncStageFailOptions): Promise<void>;
+    /**
+     * Record a deliberate omission: the item was considered and intentionally
+     * produced nothing, which is not a failure. MinSync removes any previous
+     * output of the item and stops asking for it while the source version and
+     * the settings stay the same.
+     */
+    skip(key: string, version: string, reason: string): Promise<void>;
+    /**
+     * Delete an item's recorded output, which must be absent from `items` and from
+     * `unknown`. Idempotent; returns whether a file was removed.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Fold this run into the snapshot and end the session with exit code 0, which
+     * is what makes the run complete rather than resumable. Fails if the session
+     * dies without finishing, or finishes with any other exit code.
+     */
+    finish(): Promise<MinSyncStageFinishReport>;
+    /**
+     * End the session without `finish`: the run stays in the journal and the next
+     * `open` resumes it. Idempotent, and always reaps the child — stdin closes,
+     * then SIGTERM, then SIGKILL — so no stage lock holder is left behind.
+     */
+    close(): Promise<void>;
+    private reap;
+    /** One outstanding line-in/line-out exchange at a time, whatever the caller awaits. */
+    private send;
+    /**
+     * Run `work` after every request already issued and before any later one,
+     * so a job of several exchanges — the handshake and the open — is atomic
+     * with respect to a caller that does not await its requests.
+     */
+    private enqueue;
+    private exchange;
+    private write;
+    private onLine;
+    private onExit;
+    /** SIGTERM the process tree, escalating to SIGKILL when it does not go. */
+    private terminate;
+    /** The session is unusable from here on: reject whatever is in flight. */
+    private failSession;
+    private appendStderr;
+    private stderrText;
+}
+/**
+ * Read a stage's durable state in one synchronous round trip, for callers that
+ * reconstruct state while they are already synchronous. Exactly one `inspect`
+ * line is written and stdin is closed, so a helper that answers and then exits
+ * non-zero on EOF is still fine — code 0 or 1 with a valid answer is success.
+ *
+ * Anything else throws `MinSyncStageError`: MinSync's own refusal code, a
+ * transport code (`spawn_failed`, `process_failed`) or `unsupported_protocol`
+ * when the build simply never answered.
+ */
+export declare function readMinSyncStage(binaryPath: string, stateDir: string, cwd: string, input: MinSyncStageInspectInput): MinSyncStageInspectReport;

package/dist/minsync/types.d.ts

@@ -26,6 +26,10 @@ export interface MinSyncOptions {
     readonly embedder?: MinSyncEmbedderConfig;
     readonly maxChunkSize?: number;
 }
+export interface MinSyncSyncProgress {
+    readonly processed: number;
+    readonly total: number;
+}
 export interface MinSyncSyncResult {
     readonly ok: boolean;
     readonly synced: number;

package/dist/minsync/workspace.d.ts

@@ -16,5 +16,6 @@ export interface MinSyncWorkspaceSyncResult {
 }
 export declare function syncMinSyncWorkspace(root: string, options?: {
     readonly workspacePath?: string;
+    readonly minSyncBinaryPath?: string;
 }): MinSyncWorkspaceSyncResult;
-export declare function buildMinSyncPathMap(root: string, workspacePath: string): ReadonlyMap<string, MinSyncWorkspaceEntry>;
+export declare function buildMinSyncPathMap(root: string, workspacePath: string, minSyncBinaryPath?: string): ReadonlyMap<string, MinSyncWorkspaceEntry>;

package/dist/mirror/index-store.d.ts

@@ -1,3 +1,5 @@
+import { type MinSyncStageInspectReport } from "../minsync/stage.js";
+/** A read-only application view of MinSync-owned committed source metadata. */
 export interface ParsedMirrorEntry {
     readonly virtualPath: string;
     readonly sourcePath: string;
@@ -6,35 +8,34 @@ export interface ParsedMirrorEntry {
     readonly sourceMtimeNs: number;
     readonly sourceSizeBytes: number;
     readonly updatedAt: string;
+    readonly parserVersion?: string;
+    readonly sourceVersion?: string;
+    readonly parserFingerprint?: string;
 }
-/** Why refresh deliberately left a source out of the parsed mirror. */
 export type ParsedMirrorSkipReason = "duplicate-excluded" | "user-excluded" | "parser-skipped" | "parser-failed" | "source-unreadable";
-/**
- * A source the last refresh decided not to mirror, pinned to the exact version it
- * decided on. Staleness checks compare against this record instead of re-deriving
- * the decision, so a deliberately skipped file is not reported as a new source.
- *
- * Retryable skips (`parser-failed`, `source-unreadable`) also carry the parser stamp, so refresh
- * can honor the record without reading or parsing the file again.
- */
+/** Projected from engine outcomes; never stored or used to schedule work by the host. */
 export interface ParsedMirrorSkipEntry {
     readonly virtualPath: string;
     readonly sourcePath: string;
     readonly reason: ParsedMirrorSkipReason;
     readonly sourceMtimeNs: number;
     readonly sourceSizeBytes: number;
-    readonly updatedAt: string;
-    /** `Parser.name` the skip was decided with. */
     readonly parserName?: string;
-    /** `Parser.version` the skip was decided with. Absent on records written before version stamps. */
     readonly parserVersion?: string;
+    readonly parserFingerprint?: string;
 }
 export interface ParsedMirrorIndex {
     readonly version: 1;
     readonly entries: Readonly<Record<string, ParsedMirrorEntry>>;
-    /** Deliberate skips recorded by the last refresh. Absent in indexes written before this field existed. */
     readonly skipped?: Readonly<Record<string, ParsedMirrorSkipEntry>>;
+    /** All engine-held identities, including missing outputs and ordinary failures; never reusable outputs. */
+    readonly known?: readonly string[];
 }
 export declare function emptyMirrorIndex(): ParsedMirrorIndex;
-export declare function loadMirrorIndex(root: string): ParsedMirrorIndex;
-export declare function saveMirrorIndex(root: string, index: ParsedMirrorIndex): void;
+export declare function mirrorStageKey(virtualPath: string): string;
+export declare function loadMirrorIndex(root: string, options?: {
+    readonly minSyncBinaryPath?: string;
+}): ParsedMirrorIndex;
+/** Decode only the host's own opaque source payload, never the engine's disk format. */
+export declare function mirrorSourceMetadata(version: string | null): Omit<ParsedMirrorEntry, "outputPath" | "updatedAt"> | undefined;
+export declare function mirrorIndexFromStage(root: string, report: MinSyncStageInspectReport): ParsedMirrorIndex;

package/dist/mirror/index.d.ts

@@ -1,5 +1,5 @@
 export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
-export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
-export { isParsedRefreshComplete, parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath, } from "./paths.js";
+export { emptyMirrorIndex, loadMirrorIndex } from "./index-store.js";
+export { isParsedRefreshComplete, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath, } from "./paths.js";
 export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorProgress, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
 export { DEFAULT_MAX_SOURCE_BYTES, DEFAULT_TRANSIENT_RETRIES, detectMirrorStaleness, isPathExcluded, MirrorWorkspaceError, syncParsedMirrors, } from "./sync.js";

package/dist/mirror/paths.d.ts

@@ -1,10 +1,8 @@
 export declare const PARSED_MIRROR_SUBDIR: string;
 export declare const PARSED_FILES_SUBDIR = "files";
-export declare const PARSED_INDEX_FILE = "index.json";
 export declare const REFRESH_READINESS_FILE = "refresh-complete.json";
 export declare const REFRESH_PROGRESS_FILE = "refresh-progress.json";
 export declare function parsedMirrorRoot(root: string): string;
-export declare function parsedMirrorIndexPath(root: string): string;
 export declare function parsedOutputPath(root: string, virtualPath: string): string;
 export declare function refreshReadinessPath(root: string): string;
 export declare function refreshProgressPath(root: string): string;

package/dist/mirror/sync.d.ts

@@ -2,8 +2,6 @@ import { type DefaultParserRegistryOptions } from "../parser/defaults.js";
 import type { ParserRegistry } from "../parser/registry.js";
 /** Refuse to fully load/parse sources larger than this. Keeps Node heap stable on home folders. */
 export declare const DEFAULT_MAX_SOURCE_BYTES: number;
-/** Persist partial mirror progress this often so an OOM mid-run still restarts incrementally. */
-export declare const MIRROR_CHECKPOINT_EVERY = 25;
 /** A refresh may delete at most this share of the indexed documents (above {@link MASS_DELETE_FLOOR}). */
 export declare const DEFAULT_MAX_DELETE_RATIO = 0.3;
 /** Directory entries examined per search root before the walk stops. */
@@ -16,6 +14,8 @@ export interface ParsedMirrorSyncOptions {
     readonly registry?: ParserRegistry;
     readonly parserOptions?: DefaultParserRegistryOptions;
     readonly force?: boolean;
+    /** Embedded/test binary override; the normal path resolves the installed MinSync. */
+    readonly minSyncBinaryPath?: string;
     /** Override max source size for parse attempts (bytes). */
     readonly maxSourceBytes?: number;
     /** Absolute source paths omitted from parsed mirrors (for example exact duplicate copies). */
@@ -28,8 +28,8 @@ export interface ParsedMirrorSyncOptions {
      */
     readonly retrySkipped?: boolean;
     /**
-     * Stops the sync between files and kills an in-flight parse worker. The sync rejects with the signal's
-     * reason after checkpointing the mirror, so finished files are not re-parsed next time.
+     * Stops between files and kills an in-flight parse worker. Rejects with the signal's
+     * reason; MinSync's durable journal retains completed items for the next run.
      */
     readonly signal?: AbortSignal;
     /** Called before each file and once more with `processed === total` when the parse phase ends. */
@@ -63,7 +63,7 @@ export interface ParsedMirrorProgress {
     /** The file about to be processed; absent on the final event. */
     readonly currentVirtualPath?: string;
 }
-export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "parser-crashed" | "source-vanished" | "source-unreadable" | "source-read-failed" | "mirror-write-failed" | "duplicate-excluded" | "deleted-mirror" | "stale-index" | "pdf-extract-thin" | "parser-warning" | "search-root-unavailable" | "mass-delete-suppressed" | "walk-truncated" | "directory-unreadable";
+export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "parser-crashed" | "source-changed" | "source-vanished" | "source-unreadable" | "source-read-failed" | "mirror-write-failed" | "duplicate-excluded" | "deleted-mirror" | "stale-index" | "pdf-extract-thin" | "parser-warning" | "search-root-unavailable" | "mass-delete-suppressed" | "walk-truncated" | "directory-unreadable";
 /**
  * Refresh diagnostic. `source` is an opaque virtual path, never a real filesystem path.
  * `message` keeps the underlying error text, which may include a filesystem path.
@@ -94,15 +94,6 @@ export declare class MirrorWorkspaceError extends Error {
     constructor(workspace: string, cause: unknown);
 }
 export declare function syncParsedMirrors(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorSyncResult>;
-/**
- * Cheap, parse-free staleness check: compares current source files (by mtime and
- * size only — no parsing) against the mirror index's own records. A source is
- * current when the last refresh either indexed it or deliberately skipped it at
- * this exact version, so a skipped duplicate, oversize, or unparseable file is not
- * reported as a new source. Returns a `stale-index` diagnostic (opaque virtual
- * path) for every supported source that is new or changed since the last
- * successful refresh. Safe to call outside the query hot path (e.g. from
- * getRefreshStatus).
- */
+/** Ask MinSync's read-only plan which current source revisions still need work. */
 export declare function detectMirrorStaleness(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorDiagnostic[]>;
 export declare function isPathExcluded(sourcePath: string, excluded: ReadonlySet<string> | undefined): boolean;

package/dist/parser/types.d.ts

@@ -18,8 +18,8 @@ export declare abstract class Parser {
     abstract readonly name: string;
     abstract readonly extensions: readonly string[];
     /**
-     * Stamp recorded next to a per-file skip. Refresh retries a source a parser failed on exactly
-     * once when this changes, so bump it whenever parse behavior changes (including the engine behind it).
+     * Processing revision used by the durable parse stage and per-file failure skips.
+     * Bump whenever parse behavior changes, including an engine dependency upgrade.
      */
     readonly version: string;
     abstract parse(input: ParseInput): Promise<ParseOutput>;

package/dist/process/lifecycle.d.ts

@@ -0,0 +1,10 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * Track a spawned child so it cannot outlive the host: a host exit, and
+ * SIGINT/SIGTERM/SIGHUP, kill its process tree. Windows has no process group to
+ * signal, so it keeps the parent/child chain `taskkill /t` walks and tracks
+ * nothing.
+ */
+export declare function trackLiveChild(child: ChildProcess): void;
+/** Stop tracking a child that has exited; the host handlers go with the last one. */
+export declare function untrackLiveChild(child: ChildProcess): void;