knodin 0.9.0 → 0.10.0

package/dist/src/engine/parse-pool-resources.js

@@ -0,0 +1,96 @@
+import os from "node:os";
+/**
+ * Per-worker resident memory allowance.
+ *
+ * Measured rather than guessed: a worker's fixed cost is ~136 MB — roughly
+ * 64 MB of Node baseline, 22 MB to import the engine, and up to 50 MB of
+ * tree-sitter grammars if it ends up touching every language. The rest is
+ * headroom for parse trees, which scale with file size. Kept deliberately
+ * above the measurement so the pool under-spawns rather than over-spawns:
+ * too few workers is a slower index, too many is the user's machine thrashing.
+ */
+export const PER_WORKER_MEMORY_ESTIMATE_BYTES = 192 * 1024 * 1024;
+/**
+ * Fraction of TOTAL system memory the pool may claim.
+ *
+ * This deliberately does NOT use `os.freemem()`, which an earlier version did
+ * on the reasoning that a machine already under load should be respected.
+ * Measured, that reasoning does not survive contact with macOS: on a 24 GB
+ * host, `os.freemem()` reported **133 MB**, because the OS keeps nearly all
+ * RAM in cache and compressed pages rather than "free". The pool computed a
+ * memory ceiling of zero and refused to spawn on an 11-core machine — a
+ * feature that was enabled and silently never used.
+ *
+ * Node exposes no portable "available" figure, so total memory with a
+ * conservative fraction is the honest signal. Real memory pressure is handled
+ * by the hard cap and the per-worker allowance above, not by a number that
+ * means something different on every platform.
+ */
+export const MEMORY_HEADROOM_FRACTION = 0.25;
+/**
+ * Absolute worker ceiling regardless of how large the host is. Guards against
+ * pathological spawn counts on very-high-core machines, where the writer
+ * becomes the bottleneck long before the parsers do and extra workers buy
+ * nothing but memory.
+ */
+export const PARSE_POOL_HARD_CAP = 16;
+/** Read a positive-integer env override, matching `mcp-reliability.ts`'s idiom. */
+function positiveIntegerEnv(raw) {
+    const parsed = Number.parseInt(raw ?? "", 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+ * Decide the parse-pool size from injected machine facts.
+ *
+ * Precedence, highest first:
+ *  1. `KNODIN_DISABLE_PARSE_WORKERS=1` -- absolute kill switch, always 0.
+ *  2. `KNODIN_PARSE_POOL_MAX_WORKERS=n` -- an explicit ceiling, still clamped
+ *     by the hard cap but NOT by the derived CPU/memory bounds, so an operator
+ *     debugging a machine can pin the value without fighting the heuristic.
+ *  3. The smaller of the CPU and memory ceilings.
+ */
+export function resolveParsePoolSize(inputs) {
+    const env = inputs.env ?? process.env;
+    // One core is reserved for the main thread, which is not an idle consumer
+    // here: it performs the synchronous, blocking SQLite writes plus the two
+    // whole-graph post-passes, and it must stay responsive enough to keep the
+    // workers fed.
+    const cpuBound = Math.max(1, Math.floor(inputs.cpuCount) - 1);
+    const usableMemory = Math.max(0, inputs.totalMemoryBytes) * MEMORY_HEADROOM_FRACTION;
+    const memoryBound = Math.floor(usableMemory / PER_WORKER_MEMORY_ESTIMATE_BYTES);
+    if (env.KNODIN_DISABLE_PARSE_WORKERS === "1")
+        return { workers: 0, reason: "disabled-by-env", cpuBound, memoryBound };
+    const override = positiveIntegerEnv(env.KNODIN_PARSE_POOL_MAX_WORKERS);
+    if (override !== null)
+        return {
+            workers: Math.min(override, PARSE_POOL_HARD_CAP),
+            reason: "explicit-override",
+            cpuBound,
+            memoryBound,
+        };
+    // A single-core host has no core to spare once the writer is accounted for,
+    // so the pool would be one worker handing results to an idle main thread --
+    // strictly worse than doing the work inline. Report it distinctly from a
+    // memory refusal: the remedies are completely different.
+    if (cpuBound < 2)
+        return { workers: 0, reason: "single-core", cpuBound, memoryBound };
+    // Too little memory for even one worker's fixed overhead. Sequential
+    // is not a degraded outcome here, it is the correct one.
+    if (memoryBound < 1)
+        return { workers: 0, reason: "memory-bound", cpuBound, memoryBound };
+    const workers = Math.min(cpuBound, memoryBound, PARSE_POOL_HARD_CAP);
+    return {
+        workers,
+        reason: memoryBound < cpuBound ? "memory-bound" : "cpu-bound",
+        cpuBound,
+        memoryBound,
+    };
+}
+/** Sample the live machine. Separated from the policy so the policy stays testable. */
+export function currentParsePoolSizing(env = process.env) {
+    return resolveParsePoolSize({
+        cpuCount: os.cpus().length,
+        totalMemoryBytes: os.totalmem(),
+        env,
+    });
+}

package/dist/src/engine/parse-pool.js

@@ -0,0 +1,352 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { currentParsePoolSizing } from "./parse-pool-resources.js";
+/**
+ * On by default; `KNODIN_DISABLE_PARSE_WORKERS=1` is the kill switch.
+ *
+ * Defaulted on only after the gate it was waiting for actually passed, and
+ * after the economics changed enough to justify it. When the pool was first
+ * wired, `parse_extract` was 10.9% of a full index and the pool bought 1.16x —
+ * not worth worker-thread complexity. Fixing the real bottleneck
+ * (EASFDC-8421) took a full index from 60.5s to 21.3s and left parsing at
+ * 31.6%, which raised the pool's own contribution to a measured 1.57x. The
+ * combined figure against the original baseline is 4.7x.
+ *
+ * Enabling it is safe rather than merely faster: sizing refuses to spawn on
+ * machines that cannot afford workers and returns null BEFORE any Worker is
+ * constructed, a worker crash retries once and then hands the file back for
+ * inline indexing, an exhausted pool drains its queue rather than stalling,
+ * and the graph is proven set-equivalent to the sequential build. Every one of
+ * those has a test.
+ *
+ * `KNODIN_ENABLE_PARSE_WORKERS` is still honoured so anyone who set it during
+ * the opt-in period keeps working, but it is now redundant.
+ */
+export function parseWorkersEnabled(env = process.env) {
+    return env.KNODIN_DISABLE_PARSE_WORKERS !== "1";
+}
+/**
+ * Grammar identity for affinity purposes. Grammars are cached in module-level
+ * state inside the engine, so each worker holds a copy of every language it
+ * sees: measured at 7.4 MB for a TypeScript-only worker against ~50 MB for one
+ * that eventually touches every grammar. Keeping a worker on one extension is
+ * therefore a real memory lever, not a micro-optimization.
+ */
+function languageKey(relativePath) {
+    return path.extname(relativePath).toLowerCase() || "<none>";
+}
+function defaultWorkerEntry() {
+    const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+    return fileURLToPath(new URL(`./parse-worker.${extension}`, import.meta.url));
+}
+/**
+ * When running from TypeScript sources, a worker needs its own TS loader.
+ *
+ * A worker thread does NOT inherit the host's transform pipeline. Under a
+ * plain `tsx` process it happens to work because tsx registers a real Node
+ * loader; under Vitest it does not, and the worker dies with "Cannot find
+ * module .../index.js" while resolving this module's own `./index.js` import.
+ * The pool then silently falls back to the sequential path — correct results,
+ * but no parallelism, and no way to tell from the outside.
+ *
+ * Mirrors what `src/__tests__/support/node-subprocess.ts` already does for the
+ * child-process worker. Returns undefined for a compiled `.js` entry, where
+ * the import resolves natively and tsx may not be installed at all.
+ */
+function workerExecArgv(entry) {
+    if (!entry.endsWith(".ts"))
+        return undefined;
+    try {
+        return ["--import", fileURLToPath(import.meta.resolve("tsx"))];
+    }
+    catch {
+        return undefined;
+    }
+}
+function realWorkerFactory() {
+    const entry = defaultWorkerEntry();
+    const execArgv = workerExecArgv(entry);
+    const worker = new Worker(entry, execArgv ? { execArgv } : undefined);
+    worker.unref();
+    return {
+        postMessage: (task) => worker.postMessage(task),
+        onMessage: (listener) => worker.on("message", listener),
+        onError: (listener) => worker.on("error", listener),
+        onExit: (listener) => worker.on("exit", listener),
+        terminate: async () => {
+            await worker.terminate();
+        },
+    };
+}
+/**
+ * One `run()` call's state machine.
+ *
+ * Deliberately a class of flat methods rather than nested closures: the same
+ * logic written inline nests worker callbacks inside a promise executor inside
+ * a method, which is both hard to follow and a real reviewability problem
+ * (Sonar S2004 flagged five separate spots). Methods keep every step at one
+ * level and let the slot be passed explicitly.
+ */
+class PoolRun {
+    slots;
+    factory;
+    onOutcome;
+    nextId;
+    buckets = new Map();
+    remaining;
+    settled = false;
+    draining = false;
+    resolve;
+    reject;
+    constructor(slots, factory, tasks, onOutcome, nextId) {
+        this.slots = slots;
+        this.factory = factory;
+        this.onOutcome = onOutcome;
+        this.nextId = nextId;
+        for (const task of tasks) {
+            const key = languageKey(task.relativePath);
+            const bucket = this.buckets.get(key);
+            if (bucket)
+                bucket.push(task);
+            else
+                this.buckets.set(key, [task]);
+        }
+        this.remaining = tasks.length;
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+            for (const slot of this.slots)
+                this.attach(slot);
+            for (const slot of this.slots)
+                this.pump(slot);
+        });
+    }
+    /** Prefer the slot's own language; fall back to the largest bucket. */
+    takeNext(slot) {
+        if (slot.affinity) {
+            const own = this.buckets.get(slot.affinity);
+            if (own && own.length > 0)
+                return own.pop() ?? null;
+        }
+        // Preferring affinity without enforcing it keeps a single-language
+        // repository from leaving most of the pool idle.
+        let bestKey = null;
+        let bestLength = 0;
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.length > bestLength) {
+                bestKey = key;
+                bestLength = bucket.length;
+            }
+        }
+        if (!bestKey)
+            return null;
+        slot.affinity = bestKey;
+        return this.buckets.get(bestKey)?.pop() ?? null;
+    }
+    attach(slot) {
+        slot.handle.onMessage((response) => this.onResponse(slot, response));
+        slot.handle.onError((error) => this.onSlotFailure(slot, error.message));
+        slot.handle.onExit((code) => {
+            if (slot.inFlight)
+                this.onSlotFailure(slot, `worker exited with code ${code}`);
+        });
+    }
+    onResponse(slot, response) {
+        if (!slot.inFlight || response.id !== slot.inFlight.id)
+            return;
+        switch (response.kind) {
+            case "result":
+                this.finishOne(slot, { kind: "result", result: response.result });
+                return;
+            case "unparsed":
+                this.finishOne(slot, { kind: "unparsed" });
+                return;
+            case "skipped":
+                this.finishOne(slot, { kind: "skipped" });
+                return;
+            case "special":
+                this.finishOne(slot, { kind: "fallback", reason: "needs main-thread indexer" });
+                return;
+            default:
+                this.finishOne(slot, { kind: "fallback", reason: response.message });
+                return;
+        }
+    }
+    pump(slot) {
+        if (this.settled || slot.dead || slot.inFlight)
+            return;
+        const task = this.takeNext(slot);
+        if (!task)
+            return;
+        const id = this.nextId();
+        slot.inFlight = { task, id, attempt: 0 };
+        this.dispatch(slot, task, id);
+    }
+    dispatch(slot, task, id) {
+        try {
+            slot.handle.postMessage({
+                id,
+                absolutePath: task.absolutePath,
+                relativePath: task.relativePath,
+                repoPath: task.repoPath,
+            });
+        }
+        catch (error) {
+            this.onSlotFailure(slot, error instanceof Error ? error.message : String(error));
+        }
+    }
+    replaceSlot(slot) {
+        try {
+            slot.handle = this.factory();
+            slot.dead = false;
+            this.attach(slot);
+        }
+        catch {
+            slot.dead = true;
+        }
+    }
+    onSlotFailure(slot, reason) {
+        const flight = slot.inFlight;
+        slot.dead = true;
+        void slot.handle.terminate().catch(() => { });
+        if (!flight) {
+            // Died idle. Bring a replacement up so the pool keeps its width.
+            this.replaceSlot(slot);
+            if (!slot.dead)
+                this.pump(slot);
+            // A slot that dies while idle delivers no outcome, so nothing else
+            // would notice the pool has run out of workers.
+            else if (!this.anyLive())
+                void this.drainRemaining(reason);
+            return;
+        }
+        if (flight.attempt === 0) {
+            // One retry on a fresh worker: a crash is far more often about this
+            // particular file than about the worker.
+            this.replaceSlot(slot);
+            if (!slot.dead) {
+                const id = this.nextId();
+                slot.inFlight = { ...flight, attempt: 1, id };
+                this.dispatch(slot, flight.task, id);
+                return;
+            }
+        }
+        // Retried already, or no replacement available: give the file back so
+        // the caller indexes it inline. Never dropped.
+        this.finishOne(slot, { kind: "fallback", reason });
+        if (!slot.dead)
+            this.pump(slot);
+    }
+    finishOne(slot, outcome) {
+        const flight = slot.inFlight;
+        if (!flight)
+            return;
+        slot.inFlight = null;
+        this.remaining--;
+        void this.deliver(slot, flight.task, outcome);
+    }
+    async deliver(slot, task, outcome) {
+        try {
+            await this.onOutcome(task, outcome);
+        }
+        catch (error) {
+            this.fail(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        if (this.remaining === 0) {
+            this.finish();
+            return;
+        }
+        this.pump(slot);
+        if (!this.anyLive())
+            await this.drainRemaining("no parse worker available");
+    }
+    anyLive() {
+        return this.slots.some((slot) => !slot.dead);
+    }
+    /**
+     * Every worker is gone and could not be replaced. Hand back every task that
+     * has not been dispatched so the caller indexes them inline.
+     *
+     * Without this the run simply stops: queued work has no worker to claim it,
+     * nothing ever decrements `remaining`, and `run()` never settles. A pool
+     * that hangs is far worse than one that declines to help, and "never the
+     * reason a run fails" has to include "never the reason a run stalls".
+     */
+    async drainRemaining(reason) {
+        if (this.draining || this.settled)
+            return;
+        this.draining = true;
+        const pending = [];
+        for (const bucket of this.buckets.values())
+            pending.push(...bucket.splice(0));
+        for (const task of pending) {
+            this.remaining--;
+            try {
+                await this.onOutcome(task, { kind: "fallback", reason });
+            }
+            catch (error) {
+                this.fail(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+        }
+        this.draining = false;
+        if (this.remaining === 0)
+            this.finish();
+    }
+    finish() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.resolve();
+    }
+    fail(error) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.reject(error);
+    }
+}
+/**
+ * Builds a pool, or returns `null` when the machine says not to.
+ *
+ * `null` is a normal outcome meaning "use the sequential path" — the decision
+ * is made here, before any worker exists, so an unsuitable machine never
+ * discovers the problem partway through an index.
+ */
+export function createParsePool(options) {
+    const env = options?.env ?? process.env;
+    const sizing = options?.sizing ?? currentParsePoolSizing(env);
+    if (sizing.workers < 1)
+        return null;
+    const factory = options?.workerFactory ?? realWorkerFactory;
+    const slots = [];
+    try {
+        for (let i = 0; i < sizing.workers; i++)
+            slots.push({ handle: factory(), affinity: null, inFlight: null, dead: false });
+    }
+    catch {
+        // Spawning failed outright. Tear down whatever came up and let the
+        // caller stay sequential rather than run a half-sized pool.
+        for (const slot of slots)
+            void slot.handle.terminate().catch(() => { });
+        return null;
+    }
+    let nextId = 1;
+    const allocateId = () => nextId++;
+    return {
+        size: slots.length,
+        sizing,
+        async run(tasks, onOutcome) {
+            if (tasks.length === 0)
+                return;
+            await new PoolRun(slots, factory, tasks, onOutcome, allocateId).start();
+        },
+        async close() {
+            await Promise.all(slots.map((slot) => slot.handle.terminate().catch(() => { })));
+        },
+    };
+}

package/dist/src/engine/parse-protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/src/engine/parse-worker.js

@@ -0,0 +1,51 @@
+import { parentPort } from "node:worker_threads";
+import { extractGenericFileForIndex } from "./index.js";
+/**
+ * Parse-pool worker entry.
+ *
+ * Owns read + parse + extract for one file at a time and posts back plain
+ * data. It never touches SQLite: the database handle is a native, non-
+ * transferable `node:sqlite` object, and exactly one writer on the main
+ * thread remains the invariant this whole design is built around.
+ *
+ * Verified during Step 4 that a worker inherits the tsx loader by default, so
+ * importing the TypeScript engine here works in development and against the
+ * compiled output alike without forwarding `execArgv`.
+ */
+const port = parentPort;
+if (!port)
+    throw new Error("knodin parse worker started without a parent port");
+port.on("message", (task) => {
+    void (async () => {
+        let response;
+        try {
+            const extraction = await extractGenericFileForIndex(task.absolutePath, task.relativePath, task.repoPath);
+            switch (extraction.kind) {
+                case "result":
+                    response = { id: task.id, kind: "result", result: extraction.result };
+                    break;
+                case "unparsed":
+                    response = { id: task.id, kind: "unparsed" };
+                    break;
+                case "skipped":
+                    response = { id: task.id, kind: "skipped" };
+                    break;
+                default:
+                    // `special` carries a live tree; hand the file back instead.
+                    response = { id: task.id, kind: "special" };
+                    break;
+            }
+        }
+        catch (error) {
+            // Serialize by hand. A thrown Error clones without its message on some
+            // paths, and losing the message turns a diagnosable failure into a
+            // mystery at exactly the moment the pool decides whether to retry.
+            response = {
+                id: task.id,
+                kind: "error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        port.postMessage(response);
+    })();
+});

package/dist/src/engine/reflink-copy.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+/**
+ * Copy `source` to `destination`, preferring an OS-level copy-on-write clone
+ * (`clonefile()` on APFS, `FICLONE` on Btrfs/XFS) so the two files share disk
+ * blocks until one of them is later mutated. Falls back to an ordinary byte
+ * copy on any filesystem/platform that doesn't support cloning.
+ */
+export function reflinkCopyFile(source, destination) {
+    try {
+        fs.copyFileSync(source, destination, fs.constants.COPYFILE_FICLONE_FORCE);
+        return { reflinked: true };
+    }
+    catch {
+        try {
+            fs.rmSync(destination, { force: true });
+        }
+        catch {
+            // Best-effort cleanup of a partial clone attempt; the plain copy below still succeeds or throws.
+        }
+        fs.copyFileSync(source, destination);
+        return { reflinked: false };
+    }
+}

package/dist/src/engine/seal-command.js

@@ -0,0 +1,116 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createEngine } from "./index.js";
+import { sealIndex } from "./seal.js";
+import { resolveDbPath } from "./state-paths.js";
+/**
+ * Orchestrates `knodin seal`: gather live health and git identity, then hand
+ * both to the pure sealing transform.
+ *
+ * Kept out of `seal.ts` so that module stays a leaf — the sealed READ path
+ * lives inside the engine, and a seal module that imported the engine back
+ * would make that circular.
+ */
+/**
+ * Profiles are 58% of the SalesforceCI payload in 187 files. They are
+ * permission matrices; no design conversation reads one verbatim, and their
+ * structure is already captured as graph edges. Excluding them is what makes a
+ * 1Gi resident ceiling reachable — but it is recorded as a NAMED rule so a
+ * query about a profile answers "excluded by policy" rather than empty.
+ */
+export const DEFAULT_SOURCE_EXCLUSIONS = [
+    { rule: "profiles-excluded", test: /\.profile-meta\.xml$|(^|\/)profiles\//i },
+];
+function git(repoPath, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd: repoPath,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reduce an origin remote to canonical lowercase `owner/name`.
+ *
+ * The raw URL is NOT usable as identity, and the SSH form is the dangerous
+ * one rather than the obviously-broken one: `git@host:owner/name.git` splits
+ * into exactly two segments, so a consumer validating "must be owner/name"
+ * accepts it and then keys on `git@host:owner` and `name.git`. It passes the
+ * shape check while being semantically garbage, which is worse than the HTTPS
+ * form that simply fails.
+ *
+ * Returns null rather than a guess when the URL does not yield a clean pair —
+ * an identity a consumer cannot key on should be absent, not approximated.
+ */
+export function canonicalRepositoryIdentity(remoteUrl) {
+    if (!remoteUrl)
+        return null;
+    const withoutSuffix = remoteUrl.trim().replace(/\.git$/i, "");
+    // Strip scheme, or the `git@host:` / `host:` prefix of the SCP-like form.
+    // The host may carry an SSH config alias (`github.com-company`), which is a
+    // local routing detail and must not reach identity.
+    const withoutHost = withoutSuffix
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")
+        .replace(/^[^/]*@/, "")
+        .replace(/^[^/:]+[:/]/, "");
+    const segments = withoutHost.split("/").filter(Boolean);
+    if (segments.length < 2)
+        return null;
+    // Take the LAST two: nested group paths (GitLab subgroups) still reduce to
+    // the owner/name pair a consumer keys on.
+    return segments.slice(-2).join("/").toLowerCase();
+}
+export async function runSeal(options) {
+    // Resolve symlinks, not just relative segments. The engine canonicalises the
+    // repository path when it decides where state lives, so a caller passing a
+    // symlinked path (every macOS temp directory: /var -> /private/var) would
+    // have sealing look for the database somewhere the index never wrote it and
+    // report `database-missing` for a repository that is perfectly well indexed.
+    const requested = path.resolve(options.repoPath);
+    const repoPath = fs.existsSync(requested) ? fs.realpathSync(requested) : requested;
+    const engine = createEngine({ watcher: "disabled" });
+    try {
+        const health = await engine.status(repoPath, { audit: "deep" });
+        const remoteUrl = git(repoPath, ["remote", "get-url", "origin"]);
+        const commit = git(repoPath, ["rev-parse", "HEAD"]);
+        // `--symbolic-full-name` so a detached HEAD reports null rather than the
+        // literal string "HEAD", which would read as a real ref downstream.
+        const ref = git(repoPath, ["rev-parse", "--symbolic-full-name", "HEAD"]);
+        const excluded = options.includeExcluded
+            ? undefined
+            : (relativePath) => DEFAULT_SOURCE_EXCLUSIONS.some((entry) => entry.test.test(relativePath));
+        return sealIndex({
+            repoPath,
+            sourceDatabasePath: resolveDbPath(repoPath),
+            outputPath: path.resolve(options.outputPath),
+            stripEmbeddings: options.stripEmbeddings,
+            excludeSource: excluded,
+            health: {
+                status: health.status,
+                pendingPaths: health.freshness.workingTree.pendingPaths ?? 0,
+                freshness: health.freshness.state,
+            },
+            // Canonical owner/name from the remote. `status` reports the local
+            // checkout path, which is not identity a consumer can key on — two
+            // machines cloning the same repository would attest two different
+            // "repositories". The raw URL is kept separately for provenance.
+            identity: canonicalRepositoryIdentity(remoteUrl) ?? health.repo,
+            remoteUrl,
+            commit,
+            ref: ref === "HEAD" ? null : ref,
+            // Files the graph knows about that are GONE from disk. Files that were
+            // MODIFIED do not appear here — those are caught per-file by the drift
+            // check inside `sealIndex`, which compares against `index_state`
+            // directly rather than trusting an aggregate.
+            dirtyPaths: health.missing.files,
+        });
+    }
+    finally {
+        await engine.close();
+    }
+}