pi-ast-sgrep 2.0.2 → 2.2.0

package/dist/runtime/config.js

@@ -0,0 +1,98 @@
+/**
+ * Runtime configuration: schema, legacy migration, env overlay, precedence.
+ * Leaf module (imports types only).
+ */
+import { CONFIG_SCHEMA_VERSION, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, RuntimeError, } from "./types.js";
+export function finitePositive(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new RuntimeError("INVALID_CONFIG", `${name} must be a positive integer`);
+    }
+    return value;
+}
+function sameSetting(current, legacy, currentName, legacyName) {
+    if (current !== undefined && legacy !== undefined && current !== legacy) {
+        throw new RuntimeError("CONFIG_MIGRATION_CONFLICT", `Conflicting ${currentName} and legacy ${legacyName} values`, { currentName, legacyName });
+    }
+    return current ?? legacy;
+}
+const LEGACY_NUMBER_FIELDS = [
+    ["timeoutMs", "timeout"],
+    ["maxOutputBytes", "maxOutput"],
+    ["refreshIntervalMs", "refreshInterval"],
+];
+/** Convert schema 0/unversioned settings without mutating the rollback source. */
+export function migrateConfig(input = {}) {
+    const value = { ...input };
+    const schema = value.schemaVersion ?? 0;
+    if (schema !== 0 && schema !== CONFIG_SCHEMA_VERSION) {
+        throw new RuntimeError("CONFIG_VERSION_MISMATCH", "Unsupported ast-sgrep configuration schema", { supported: [0, CONFIG_SCHEMA_VERSION], actual: schema, rollbackSafe: true });
+    }
+    if (schema === CONFIG_SCHEMA_VERSION)
+        return value;
+    const legacy = value;
+    const migrated = { ...legacy, schemaVersion: CONFIG_SCHEMA_VERSION };
+    for (const [currentName, legacyName] of LEGACY_NUMBER_FIELDS) {
+        const next = sameSetting(value[currentName], legacy[legacyName], currentName, legacyName);
+        if (next !== undefined)
+            migrated[currentName] = next;
+    }
+    for (const [, legacyName] of LEGACY_NUMBER_FIELDS) {
+        delete migrated[legacyName];
+    }
+    return migrated;
+}
+/** Serialize current settings for a schema-0 rollback without mutating the current value. */
+export function rollbackConfig(input) {
+    const current = migrateConfig(input);
+    const legacy = { ...current, schemaVersion: 0 };
+    for (const [currentName, legacyName] of LEGACY_NUMBER_FIELDS) {
+        const value = current[currentName];
+        if (value !== undefined)
+            legacy[legacyName] = value;
+        delete legacy[currentName];
+    }
+    return legacy;
+}
+/** env var → config key. ASGREP_BIN also accepts the launcher's legacy alias. */
+const ENV_VARS = [
+    ["root", "ASGREP_ROOT", (v) => v],
+    ["timeoutMs", "ASGREP_TIMEOUT_MS", Number],
+    ["maxOutputBytes", "ASGREP_MAX_OUTPUT_BYTES", Number],
+    ["refreshIntervalMs", "ASGREP_REFRESH_INTERVAL_MS", Number],
+];
+function envConfig(env = {}) {
+    const result = {};
+    // Canonical: ASGREP_BIN; alias AST_SGREP_BINARY (launcher historical name).
+    const bin = env.ASGREP_BIN || env.AST_SGREP_BINARY;
+    if (bin)
+        result.binaryPath = bin;
+    for (const [key, name, parse] of ENV_VARS) {
+        const raw = env[name];
+        if (raw !== undefined && raw !== "") {
+            result[key] = parse(raw);
+        }
+    }
+    return result;
+}
+/** Merge each setting independently, from the documented lowest to highest priority. */
+export function resolveConfig(sources = {}) {
+    const merged = {
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        maxOutputBytes: DEFAULT_MAX_OUTPUT_BYTES,
+        refreshIntervalMs: DEFAULT_REFRESH_INTERVAL_MS,
+        ...migrateConfig(sources.defaults),
+        ...envConfig(sources.environment),
+        ...migrateConfig(sources.globalSettings),
+        ...migrateConfig(sources.projectSettings),
+        ...migrateConfig(sources.explicitProjectConfig),
+    };
+    merged.timeoutMs = finitePositive(merged.timeoutMs, DEFAULT_TIMEOUT_MS, "timeoutMs");
+    merged.maxOutputBytes = finitePositive(merged.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, "maxOutputBytes");
+    merged.refreshIntervalMs = finitePositive(merged.refreshIntervalMs, DEFAULT_REFRESH_INTERVAL_MS, "refreshIntervalMs");
+    // Only explicit project configuration may relax project confinement.
+    merged.allowOutsideProject = migrateConfig(sources.explicitProjectConfig).allowOutsideProject === true;
+    merged.schemaVersion = CONFIG_SCHEMA_VERSION;
+    return merged;
+}

package/dist/runtime/freshness.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Index freshness coordination: dirty tracking, shared root-owned refreshes,
+ * bounded per-caller waits, filesystem watchers.
+ */
+import { type FSWatcher } from "node:fs";
+import { type MachineEnvelope, type RunOptions, type RuntimeContext } from "./types.js";
+import { type IndexHealth } from "./index-health.js";
+export { type IndexHealth } from "./index-health.js";
+export interface FreshnessRuntime {
+    run(args: readonly string[], context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+    resolveRoot(context: RuntimeContext): Promise<string>;
+    inspectIndexCompatibility?(context: RuntimeContext): Promise<IndexHealth>;
+    rebuildIncompatibleIndex?(context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+    /** Absolute database path whose SQLite/derived writes are owned by this runtime. */
+    resolveIndexPath?(root: string): string;
+    /**
+     * Optional warm native call (session sticky pool). When present, freshness
+     * prefers this over cold `run` for status/index — same Searcher as Code Mode.
+     */
+    nativeCall?(tool: string, args: Record<string, unknown>, context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+    /** Enable low-latency external filesystem change detection for real runtimes. */
+    watchExternalChanges?: boolean;
+}
+export interface FreshnessCoordinatorOptions {
+    refreshIntervalMs?: number;
+    /** Cap on how long one caller waits for an in-flight refresh (serve-stale after). */
+    maxWaitMs?: number;
+    now?: () => number;
+    watchFactory?: FreshnessWatchFactory;
+}
+export type FreshnessWatchFactory = (root: string, options: {
+    recursive: true;
+    persistent: false;
+    encoding: "utf8";
+}, listener: (eventType: "rename" | "change", filename: string | null) => void) => FSWatcher;
+export declare class FreshnessCoordinator {
+    #private;
+    constructor(options?: FreshnessCoordinatorOptions);
+    markAffectedPath(path: string, cwd: string): void;
+    markRootDirty(root: string): void;
+    ensureFresh(runtime: FreshnessRuntime, context: RuntimeContext, options?: RunOptions): Promise<string>;
+    shutdown(): void;
+}

package/dist/runtime/freshness.js

@@ -0,0 +1,446 @@
+/**
+ * Index freshness coordination: dirty tracking, shared root-owned refreshes,
+ * bounded per-caller waits, filesystem watchers.
+ */
+import { existsSync, realpathSync, statSync, watch } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { DEFAULT_FRESHNESS_WAIT_MS, DEFAULT_REFRESH_INTERVAL_MS, RuntimeError, RESOLVED_ROOT, } from "./types.js";
+import { finitePositive } from "./config.js";
+import { indexCompletion, incompatibleStatusFailure, indexHealth, pathContained, } from "./index-health.js";
+export {} from "./index-health.js";
+const MAX_TARGETED_INDEX_PATHS = 1_024;
+/** Probe compatibility hook then status; map incompat operational failures to health. */
+async function probeIndexHealth(runtime, rootContext, options) {
+    const hinted = await runtime.inspectIndexCompatibility?.(rootContext);
+    if (hinted === "missing" || hinted === "incompatible")
+        return hinted;
+    try {
+        const status = runtime.nativeCall
+            ? await runtime.nativeCall("index_status", {}, rootContext, options)
+            : await runtime.run(["status", ".", "--json"], rootContext, options);
+        return indexHealth(status);
+    }
+    catch (cause) {
+        if (!incompatibleStatusFailure(cause))
+            throw cause;
+        return "incompatible";
+    }
+}
+/**
+ * Run index_repo via the host's native call (the extension routes it out of
+ * process — see host/tools.ts) or CLI argv. force=true → reindex.
+ *
+ * Implicit (freshness-driven) refreshes index lexical/AST rows only: neural
+ * embeddings for a cold repo took 36-60s on large trees before the first search
+ * could answer. Embeddings are built by the explicit index/reindex tool.
+ */
+async function runIndex(runtime, force, rootContext, options) {
+    const response = runtime.nativeCall
+        ? await runtime.nativeCall("index_repo", { force, use_embed: false }, rootContext, options)
+        : await runtime.run([force ? "reindex" : "index", ".", "--json", "--no-embed"], rootContext, options);
+    const { failed, walkErrors } = indexCompletion(response, true);
+    if (failed > 0 || walkErrors) {
+        throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", "ast-sgrep did not complete the full index reconciliation", { failed, walkErrors, force });
+    }
+}
+/** Update known changed paths without walking the repository. */
+async function runTargetedIndex(runtime, paths, rootContext, options) {
+    for (let offset = 0; offset < paths.length; offset += MAX_TARGETED_INDEX_PATHS) {
+        const chunk = paths.slice(offset, offset + MAX_TARGETED_INDEX_PATHS);
+        const response = runtime.nativeCall
+            ? await runtime.nativeCall("index_repo", { paths: chunk, use_embed: false }, rootContext, options)
+            : await runtime.run(["index", ".", "--json", "--no-embed", ...chunk.flatMap((path) => ["--path", path])], rootContext, options);
+        const { failed } = indexCompletion(response, false);
+        if (failed > 0) {
+            throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", `ast-sgrep failed to update ${failed} changed path${failed === 1 ? "" : "s"}`, { failed, pathCount: chunk.length });
+        }
+    }
+}
+function canonicalizeAffectedPath(path) {
+    const absolute = resolve(path);
+    const unresolved = [basename(absolute)];
+    let existing = dirname(absolute);
+    for (;;) {
+        try {
+            return resolve(realpathSync(existing), ...unresolved.reverse());
+        }
+        catch (cause) {
+            const code = cause.code;
+            const parent = dirname(existing);
+            if ((code !== "ENOENT" && code !== "ENOTDIR") || parent === existing)
+                return resolve(path);
+            unresolved.push(basename(existing));
+            existing = parent;
+        }
+    }
+}
+function canonicalizeRootPath(path) {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        return canonicalizeAffectedPath(path);
+    }
+}
+function changesIgnoreRules(path) {
+    const name = basename(path);
+    return name === ".gitignore" || name === ".ignore" || name === ".asgrepignore";
+}
+function ignoredIndexWrite(root, path, indexPath) {
+    const defaultIndexDirectory = join(root, ".asgrep");
+    if (pathContained(defaultIndexDirectory, path))
+        return true;
+    const indexDirectory = dirname(indexPath);
+    if (dirname(path) !== indexDirectory)
+        return false;
+    const name = basename(path);
+    const sqliteArtifact = (database) => {
+        const suffix = name.slice(database.length);
+        return name.startsWith(database) && (suffix === ""
+            || suffix === "-wal"
+            || suffix === "-shm"
+            || suffix === "-journal"
+            || suffix === ".reindex.lock"
+            || /^\.corrupt(?:\.\d+)?(?:-(?:wal|shm|journal))?$/u.test(suffix));
+    };
+    return sqliteArtifact(basename(indexPath))
+        || sqliteArtifact("lexical.db")
+        || name === "semantic.ivf"
+        || (name.startsWith(".semantic.ivf.") && name.endsWith(".tmp"));
+}
+function existingDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function markStatePathDirty(state, path) {
+    state.dirtyGeneration += 1;
+    if (changesIgnoreRules(path)) {
+        state.dirtyPaths.clear();
+        state.fullScanRequired = true;
+    }
+    else if (!state.fullScanRequired) {
+        if (!state.dirtyPaths.has(path) && state.dirtyPaths.size >= MAX_TARGETED_INDEX_PATHS) {
+            state.dirtyPaths.clear();
+            state.fullScanRequired = true;
+        }
+        else {
+            state.dirtyPaths.add(path);
+        }
+    }
+}
+function markStateFullScan(state) {
+    state.dirtyGeneration += 1;
+    state.dirtyPaths.clear();
+    state.fullScanRequired = true;
+}
+function cancelledRefreshWait() {
+    return new RuntimeError("CANCELLED", "ast-sgrep freshness wait was cancelled");
+}
+/**
+ * A cancellation that belongs to another caller's dead refresh, not to this
+ * caller. The last waiter's cancel aborts shared work (resource hygiene); a
+ * caller holding a live signal must never inherit that teardown as its own
+ * failure — it settles the dead refresh and owns a fresh one instead.
+ */
+function isForeignRefreshCancel(cause, signal) {
+    if (signal?.aborted === true)
+        return false;
+    if (cause instanceof RuntimeError)
+        return cause.code === "CANCELLED";
+    if (cause instanceof Error && cause.name === "AbortError")
+        return true;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return /aborted|was cancelled/i.test(message);
+}
+/** Stop one caller waiting without transferring cancellation ownership to shared work. */
+function waitForRefresh(refresh, signal, waitMs) {
+    if (!signal && (!waitMs || waitMs <= 0))
+        return refresh;
+    if (signal?.aborted)
+        return Promise.reject(cancelledRefreshWait());
+    return new Promise((resolveWait, rejectWait) => {
+        let timer;
+        const cleanup = () => {
+            signal?.removeEventListener("abort", onAbort);
+            if (timer)
+                clearTimeout(timer);
+        };
+        const onAbort = () => {
+            cleanup();
+            rejectWait(cancelledRefreshWait());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        // A caller never spends its whole budget on freshness: after waitMs it
+        // serves whatever index state exists instead of dying on a 60s index.
+        if (waitMs && waitMs > 0) {
+            timer = setTimeout(() => {
+                cleanup();
+                rejectWait(new RuntimeError("TIMEOUT", "ast-sgrep freshness wait exceeded " + waitMs + "ms; serving the current index", { timeoutMs: waitMs }));
+            }, waitMs);
+        }
+        refresh.then(() => {
+            cleanup();
+            resolveWait();
+        }, (cause) => {
+            cleanup();
+            rejectWait(cause);
+        });
+    });
+}
+/** Shared refresh continues while other waiters remain; the last cancel stops it. */
+function attachRefreshWaiter(state, refresh, signal, waitMs) {
+    state.waiterCount += 1;
+    let cancelledByWaiter = false;
+    const wait = waitForRefresh(refresh, signal, waitMs).catch((cause) => {
+        cancelledByWaiter = cause instanceof RuntimeError && cause.code === "CANCELLED" && signal?.aborted === true;
+        throw cause;
+    });
+    return wait.finally(() => {
+        state.waiterCount = Math.max(0, state.waiterCount - 1);
+        if (cancelledByWaiter && state.waiterCount === 0 && state.inFlight !== undefined) {
+            state.refreshAbort?.abort();
+        }
+    });
+}
+export class FreshnessCoordinator {
+    #states = new Map();
+    #pending = new Map();
+    #interval;
+    #maxWaitMs;
+    #now;
+    #watchFactory;
+    constructor(options = {}) {
+        this.#interval = finitePositive(options.refreshIntervalMs, DEFAULT_REFRESH_INTERVAL_MS, "refreshIntervalMs");
+        this.#maxWaitMs = finitePositive(options.maxWaitMs, DEFAULT_FRESHNESS_WAIT_MS, "maxWaitMs");
+        this.#now = options.now ?? Date.now;
+        this.#watchFactory = options.watchFactory ?? watch;
+    }
+    /** One caller's freshness budget: bounded, and never more than its own timeout. */
+    #waitBudget(options) {
+        const budget = this.#maxWaitMs;
+        return options.timeoutMs !== undefined ? Math.min(budget, options.timeoutMs) : budget;
+    }
+    markAffectedPath(path, cwd) {
+        const affected = canonicalizeAffectedPath(isAbsolute(path) ? path : resolve(canonicalizeAffectedPath(cwd), path));
+        let matched = false;
+        for (const [root, state] of this.#states) {
+            if (!pathContained(root, affected))
+                continue;
+            markStatePathDirty(state, affected);
+            matched = true;
+        }
+        if (!matched) {
+            const pendingRoot = canonicalizeRootPath(cwd);
+            // Before root resolution, the caller's cwd is the only trustworthy
+            // confinement boundary. Do not retain unrelated/escaping paths forever.
+            if (!pathContained(pendingRoot, affected))
+                return;
+            let pending = this.#pending.get(pendingRoot);
+            if (!pending) {
+                pending = { paths: new Set(), fullScanRequired: false, consumedFullScanRoots: new Set() };
+                this.#pending.set(pendingRoot, pending);
+            }
+            if (changesIgnoreRules(affected)) {
+                pending.paths.clear();
+                pending.fullScanRequired = true;
+            }
+            else if (!pending.fullScanRequired) {
+                if (!pending.paths.has(affected) && pending.paths.size >= MAX_TARGETED_INDEX_PATHS) {
+                    pending.paths.clear();
+                    pending.fullScanRequired = true;
+                }
+                else {
+                    pending.paths.add(affected);
+                }
+            }
+        }
+    }
+    markRootDirty(root) {
+        const canonical = canonicalizeRootPath(root);
+        const state = this.#states.get(canonical);
+        if (state) {
+            markStateFullScan(state);
+        }
+        else {
+            this.#pending.set(canonical, {
+                paths: new Set(),
+                fullScanRequired: true,
+                consumedFullScanRoots: new Set(),
+            });
+        }
+    }
+    async ensureFresh(runtime, context, options = {}) {
+        const root = canonicalizeRootPath(await runtime.resolveRoot(context));
+        const rootContext = { cwd: root, [RESOLVED_ROOT]: true };
+        let state = this.#states.get(root);
+        if (!state) {
+            state = {
+                dirtyGeneration: 0,
+                cleanGeneration: 0,
+                dirtyPaths: new Set(),
+                fullScanRequired: false,
+                initialized: false,
+                lastRefreshAt: 0,
+                inFlight: undefined,
+                refreshAbort: undefined,
+                waiterCount: 0,
+                watcher: undefined,
+            };
+            this.#states.set(root, state);
+        }
+        if (runtime.watchExternalChanges && state.watcher === undefined) {
+            const indexPath = canonicalizeAffectedPath(runtime.resolveIndexPath?.(root) ?? join(root, ".asgrep", "index.db"));
+            this.#startWatcher(root, state, indexPath);
+        }
+        for (const [pendingRoot, pending] of this.#pending) {
+            if (!pathContained(pendingRoot, root) && !pathContained(root, pendingRoot))
+                continue;
+            if (pending.fullScanRequired) {
+                if (!pending.consumedFullScanRoots.has(root)) {
+                    markStateFullScan(state);
+                    pending.consumedFullScanRoots.add(root);
+                }
+                continue;
+            }
+            for (const path of pending.paths) {
+                if (!pathContained(root, path))
+                    continue;
+                markStatePathDirty(state, path);
+                pending.paths.delete(path);
+            }
+            if (pending.paths.size === 0)
+                this.#pending.delete(pendingRoot);
+        }
+        if (state.inFlight) {
+            const shared = state.inFlight;
+            try {
+                await attachRefreshWaiter(state, shared, options.signal, this.#waitBudget(options));
+            }
+            catch (cause) {
+                if (!isForeignRefreshCancel(cause, options.signal))
+                    throw cause;
+                // Another caller's cancel tore down the shared refresh. This caller is
+                // still alive: settle the dead promise, then decide for itself below.
+                await shared.catch(() => undefined);
+            }
+            return this.ensureFresh(runtime, rootContext, options);
+        }
+        if (options.signal?.aborted)
+            throw cancelledRefreshWait();
+        const now = this.#now();
+        const elapsed = now - state.lastRefreshAt;
+        // Lease expiry: initialized and interval elapsed (or clock went backwards).
+        // Expiry re-probes status (missing/incompatible) but must not walk a ready
+        // index. First search of a ready, clean index is the same: status only.
+        const expired = state.initialized && (elapsed < 0 || elapsed >= this.#interval);
+        if (state.initialized && state.cleanGeneration === state.dirtyGeneration && !expired)
+            return root;
+        const refreshGeneration = state.dirtyGeneration;
+        const refreshPaths = [...state.dirtyPaths];
+        const fullScanRequired = state.fullScanRequired;
+        // Correctness work belongs to the root, not to whichever request happened
+        // to start it. Individual callers may stop waiting, but cannot cancel the
+        // shared refresh while other callers still depend on it. The last waiter
+        // abort stops the in-flight index so Pi/tool cancel cannot leave rayon
+        // workers burning CPU.
+        const refreshAbort = new AbortController();
+        state.refreshAbort = refreshAbort;
+        const sharedOptions = { signal: refreshAbort.signal };
+        if (options.timeoutMs !== undefined)
+            sharedOptions.timeoutMs = options.timeoutMs;
+        if (options.env !== undefined)
+            sharedOptions.env = options.env;
+        const refresh = (async () => {
+            const health = await probeIndexHealth(runtime, rootContext, sharedOptions);
+            const dirty = refreshGeneration > state.cleanGeneration;
+            if (health === "incompatible") {
+                // Requisite variety: force rebuild path (hook or reindex).
+                if (runtime.rebuildIncompatibleIndex)
+                    await runtime.rebuildIncompatibleIndex(rootContext, sharedOptions);
+                else
+                    await runIndex(runtime, true, rootContext, sharedOptions);
+            }
+            else if (health === "missing") {
+                await runIndex(runtime, false, rootContext, sharedOptions);
+            }
+            else if (dirty && (fullScanRequired || refreshPaths.length === 0)) {
+                await runIndex(runtime, false, rootContext, sharedOptions);
+            }
+            else if (dirty) {
+                await runTargetedIndex(runtime, refreshPaths, rootContext, sharedOptions);
+            }
+            state.initialized = true;
+            state.cleanGeneration = refreshGeneration;
+            if (state.dirtyGeneration === refreshGeneration) {
+                state.dirtyPaths.clear();
+                state.fullScanRequired = false;
+            }
+            state.lastRefreshAt = this.#now();
+        })();
+        let tracked;
+        tracked = refresh.finally(() => {
+            if (state.inFlight === tracked) {
+                state.inFlight = undefined;
+                state.refreshAbort = undefined;
+            }
+        });
+        state.inFlight = tracked;
+        // If every waiter is cancelled, the root-owned refresh still needs a
+        // rejection handler while it finishes in the background.
+        void tracked.catch(() => undefined);
+        await attachRefreshWaiter(state, tracked, options.signal, this.#waitBudget(options));
+        if (state.cleanGeneration !== state.dirtyGeneration) {
+            return this.ensureFresh(runtime, rootContext, options);
+        }
+        return root;
+    }
+    shutdown() {
+        for (const state of this.#states.values())
+            state.watcher?.close();
+        this.#states.clear();
+        this.#pending.clear();
+    }
+    #startWatcher(root, state, indexPath) {
+        if (!existsSync(root)) {
+            state.watcher = null;
+            markStateFullScan(state);
+            return;
+        }
+        try {
+            const watcher = this.#watchFactory(root, { recursive: true, persistent: false, encoding: "utf8" }, (eventType, filename) => {
+                if (!filename) {
+                    markStateFullScan(state);
+                    return;
+                }
+                const affected = canonicalizeAffectedPath(join(root, filename));
+                if (ignoredIndexWrite(root, affected, indexPath))
+                    return;
+                if (eventType === "rename" || existingDirectory(affected)) {
+                    markStateFullScan(state);
+                    return;
+                }
+                markStatePathDirty(state, affected);
+            });
+            watcher.on("error", () => {
+                watcher.close();
+                // Watcher errors (including backend overflow) make event history
+                // unknowable. Scan once, then rely on the periodic correctness lease;
+                // retrying a permanently broken watcher on every request hot-loops.
+                if (state.watcher === watcher)
+                    state.watcher = null;
+                markStateFullScan(state);
+            });
+            state.watcher = watcher;
+        }
+        catch {
+            // Do one correctness scan now, then rely on periodic scans instead of
+            // retrying (and rescanning) on every query on unsupported filesystems.
+            state.watcher = null;
+            markStateFullScan(state);
+        }
+    }
+}

package/dist/runtime/index-health.d.ts

@@ -0,0 +1,16 @@
+import { type MachineEnvelope } from "./types.js";
+export type IndexHealth = "ready" | "missing" | "incompatible";
+export declare function pathContained(parent: string, child: string): boolean;
+export declare function record(value: unknown): Record<string, unknown> | undefined;
+export declare function indexHealth(status: MachineEnvelope): IndexHealth;
+export declare function incompatibleStatusFailure(cause: unknown): boolean;
+export declare function indexCompletion(response: MachineEnvelope, requireWalkErrors: boolean): {
+    failed: number;
+    walkErrors: boolean;
+};
+export declare function indexPathFor(root: string, env: NodeJS.ProcessEnv): string;
+export declare function indexQuarantines(indexPath: string): string[];
+/** Classify a rebuild failure and identify recovery copies made by this attempt. */
+export declare function throwIndexRebuildFailed(cause: unknown, indexPath: string, quarantinesBefore: ReadonlySet<string>): never;
+/** Read the on-disk index format marker. The binary is the authority on what it can read. */
+export declare function inspectIndexFile(path: string): "missing" | "incompatible" | number;