@dailephd/my-dev-kit-lab 0.5.1 → 0.6.0

package/dist/src/core/runMeasuredCommand.js

@@ -41,13 +41,15 @@ export async function runMeasuredCommand(options) {
         let spawnError;
         let timedOut = false;
         let timeout;
+        let killGraceTimeout;
+        let settled = false;
         let child;
         try {
             child = spawn(executable, args, {
                 cwd: options.cwd,
                 env: { ...process.env, ...options.env },
                 shell: false,
-                stdio: ["ignore", "pipe", "pipe"]
+                stdio: options.stdinText !== undefined ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
             });
         }
         catch (error) {
@@ -80,6 +82,7 @@ export async function runMeasuredCommand(options) {
             ]).then(() => resolve(measured));
             return;
         }
+        // stdout/stderr are always piped in both stdio branches above.
         child.stdout.on("data", (chunk) => {
             stdout += String(chunk);
         });
@@ -89,17 +92,40 @@ export async function runMeasuredCommand(options) {
         child.on("error", (error) => {
             spawnError = error.message;
         });
-        if (options.timeoutMs !== undefined) {
-            timeout = setTimeout(() => {
-                timedOut = true;
-                spawnError = `Command timed out after ${options.timeoutMs}ms.`;
-                forceTerminateProcess(child.pid);
-            }, options.timeoutMs);
+        if (options.stdinText !== undefined) {
+            // A child that exits or closes stdin before we write must not crash the process (EPIPE).
+            child.stdin?.on("error", (error) => {
+                spawnError = spawnError ?? `Failed to write to command stdin: ${error.message}`;
+            });
+            child.stdin?.write(options.stdinText, "utf8");
+            child.stdin?.end();
         }
-        child.on("close", async (exitCode) => {
-            if (timeout) {
+        // forceTerminateProcess is fire-and-forget (it never confirms the target process tree actually
+        // exited: on Windows it spawns a detached `taskkill /T /F` and does not await or check its
+        // result). That is normally sufficient, but a grandchild process spawned through an
+        // intermediate shim (for example a Windows .cmd launcher) can occasionally outlive an
+        // already-killed intermediate process. Without a bounded fallback, a caller whose kill silently
+        // failed would await this promise forever instead of receiving the already-known timeout error.
+        const KILL_GRACE_MS = 3000;
+        const settle = async (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
                 clearTimeout(timeout);
-            }
+            if (killGraceTimeout)
+                clearTimeout(killGraceTimeout);
+            // The caller's `scripts/cli.ts` entry point sets `process.exitCode` rather than calling
+            // `process.exit()`, so the process only exits once Node's event loop actually drains. A
+            // still-open child stdio pipe -- the same situation the kill-grace fallback above exists for
+            // -- would otherwise keep this process alive forever even though this promise has already
+            // resolved. Detaching is safe to do unconditionally: once "close" has fired the streams are
+            // already ended, so this is a harmless no-op on the normal (non-fallback) path.
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.stdin?.destroy();
+            child.removeAllListeners();
+            child.unref();
             const endedAt = new Date().toISOString();
             const durationMs = Date.now() - started;
             await writeArtifact(stdoutPath, stdout);
@@ -125,6 +151,19 @@ export async function runMeasuredCommand(options) {
             };
             await writeArtifact(telemetryPath, JSON.stringify(measured, null, 2));
             resolve(measured);
+        };
+        if (options.timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                spawnError = `Command timed out after ${options.timeoutMs}ms.`;
+                forceTerminateProcess(child.pid);
+                killGraceTimeout = setTimeout(() => {
+                    void settle(null);
+                }, KILL_GRACE_MS);
+            }, options.timeoutMs);
+        }
+        child.on("close", (exitCode) => {
+            void settle(exitCode);
         });
     });
     return result;

package/dist/src/evaluation/indexFreshness.js

@@ -0,0 +1,199 @@
+import { realpath } from "node:fs/promises";
+import { compareCodeUnits, mapInBatches, resolveIndexedFilePath, snapshotIndexedFile, } from "./indexSnapshot.js";
+export const INDEX_FRESHNESS_SCHEMA_VERSION = "my-dev-kit-lab-index-freshness-v1";
+const MAX_CHANGES = 100;
+const MAX_UNRESOLVED = 50;
+const MAX_REPORTED_PATH_LENGTH = 260;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Policy: the four-state freshness decision table. `fresh` requires a complete baseline and a
+ * complete comparison with no confirmed change; a confirmed change is `stale` only when the
+ * comparison was complete, otherwise `partially-stale`; without a confirmed change an incomplete
+ * comparison is `unknown`. Never converts uncertainty to `fresh`. Pure.
+ */
+export function classifyIndexFreshness(input) {
+    if (input.baselineSnapshotStatus === "unavailable") {
+        return "unknown";
+    }
+    const comparisonComplete = input.baselineSnapshotStatus === "complete" && input.unresolvedCount === 0;
+    if (input.confirmedChangeCount > 0) {
+        return comparisonComplete ? "stale" : "partially-stale";
+    }
+    return comparisonComplete ? "fresh" : "unknown";
+}
+function boundedText(value) {
+    return value.length > MAX_REPORTED_PATH_LENGTH ? `${value.slice(0, MAX_REPORTED_PATH_LENGTH)}...` : value;
+}
+function isValidBaselineEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const candidate = entry;
+    return (typeof candidate.path === "string" &&
+        candidate.path.length > 0 &&
+        typeof candidate.sha256 === "string" &&
+        SHA256_PATTERN.test(candidate.sha256) &&
+        typeof candidate.sizeBytes === "number" &&
+        typeof candidate.modifiedAt === "string");
+}
+async function compareIndexedFile(targetRoot, realTargetRoot, sourceRoots, entry) {
+    if (!isValidBaselineEntry(entry)) {
+        const listedPath = typeof entry?.path === "string" ? boundedText(entry.path) : null;
+        return {
+            kind: "unresolved",
+            unresolved: {
+                path: listedPath,
+                reasonCode: "unsupported-snapshot-entry",
+                message: "Snapshot entry lacks a path, SHA-256, size, or modified time.",
+            },
+        };
+    }
+    const resolution = resolveIndexedFilePath(targetRoot, sourceRoots, entry.path);
+    if (!resolution.ok) {
+        return {
+            kind: "unresolved",
+            unresolved: { path: boundedText(entry.path), reasonCode: "unsafe-path", message: `Path cannot be safely resolved (${resolution.reason}).` },
+        };
+    }
+    const current = await snapshotIndexedFile(targetRoot, realTargetRoot, resolution.relativePath);
+    if (!current.ok) {
+        if (current.reason === "missing") {
+            return {
+                kind: "change",
+                change: {
+                    path: entry.path,
+                    changeType: "missing",
+                    baselineSha256: entry.sha256,
+                    baselineSizeBytes: entry.sizeBytes,
+                    baselineModifiedAt: entry.modifiedAt,
+                    currentSha256: null,
+                    currentSizeBytes: null,
+                    currentModifiedAt: null,
+                },
+            };
+        }
+        const unsafe = current.reason === "outside-target-or-source-roots" || current.reason === "invalid-path";
+        return {
+            kind: "unresolved",
+            unresolved: {
+                path: boundedText(entry.path),
+                reasonCode: unsafe ? "unsafe-path" : "file-read-failed",
+                message: unsafe ? "Current file resolves outside the target." : `Current file could not be read as a regular file (${current.reason}).`,
+            },
+        };
+    }
+    if (current.file.sha256 === entry.sha256) {
+        return { kind: "unchanged" };
+    }
+    return {
+        kind: "change",
+        change: {
+            path: entry.path,
+            changeType: "modified",
+            baselineSha256: entry.sha256,
+            baselineSizeBytes: entry.sizeBytes,
+            baselineModifiedAt: entry.modifiedAt,
+            currentSha256: current.file.sha256,
+            currentSizeBytes: current.file.sizeBytes,
+            currentModifiedAt: current.file.modifiedAt,
+        },
+    };
+}
+/**
+ * Compares the files an index snapshot lists against their current state. Read-only: never
+ * modifies the target, invokes my-dev-kit, re-indexes, or retrieves. Files that exist now but are
+ * absent from the snapshot are deliberately ignored — the snapshot records the exact indexed set,
+ * not everything under the source roots, so "added" files cannot be inferred truthfully. Never
+ * throws; an unassessable input yields an explicit `unknown` assessment.
+ */
+export async function assessIndexFreshness(options) {
+    const { snapshot, targetRoot, sourceRoots } = options;
+    const assessedAt = (options.now ?? (() => new Date()))().toISOString();
+    const baselineSnapshotStatus = snapshot?.status ?? "unavailable";
+    const changes = [];
+    const unresolved = [];
+    let unchangedFileCount = 0;
+    let unresolvedTotal = 0;
+    const addUnresolved = (entry, count = 1) => {
+        unresolvedTotal += count;
+        unresolved.push(entry);
+    };
+    try {
+        if (!snapshot || snapshot.status === "unavailable") {
+            addUnresolved({
+                path: null,
+                reasonCode: "snapshot-unavailable",
+                message: snapshot?.unavailable ? boundedText(snapshot.unavailable.message) : "No index snapshot is available for this session.",
+            });
+        }
+        else {
+            let realTargetRoot;
+            try {
+                realTargetRoot = await realpath(targetRoot);
+            }
+            catch {
+                addUnresolved({ path: null, reasonCode: "file-read-failed", message: "Target root could not be resolved." });
+            }
+            if (snapshot.status === "complete" && snapshot.files.length !== snapshot.indexedFileCount) {
+                addUnresolved({
+                    path: null,
+                    reasonCode: "unsupported-snapshot-entry",
+                    message: `Complete snapshot lists ${snapshot.indexedFileCount} indexed files but carries ${snapshot.files.length} entries.`,
+                });
+            }
+            for (const entry of snapshot.unresolvedFiles) {
+                addUnresolved({
+                    path: entry.path,
+                    reasonCode: "snapshot-file-unresolved",
+                    message: `The index snapshot could not hash this indexed file (${entry.reason}).`,
+                });
+            }
+            // Unresolved entries the snapshot itself truncated still count toward the total.
+            unresolvedTotal += Math.max(0, snapshot.unresolvedFileCount - snapshot.unresolvedFiles.length);
+            if (realTargetRoot !== undefined) {
+                const rootForComparison = realTargetRoot;
+                const comparisons = await mapInBatches(snapshot.files, (entry) => compareIndexedFile(targetRoot, rootForComparison, sourceRoots, entry));
+                for (const comparison of comparisons) {
+                    if (comparison.kind === "unchanged")
+                        unchangedFileCount += 1;
+                    else if (comparison.kind === "change")
+                        changes.push(comparison.change);
+                    else
+                        addUnresolved(comparison.unresolved);
+                }
+            }
+        }
+    }
+    catch (error) {
+        addUnresolved({
+            path: null,
+            reasonCode: "file-read-failed",
+            message: boundedText(`Freshness comparison failed: ${error instanceof Error ? error.message : String(error)}`),
+        });
+    }
+    changes.sort((left, right) => compareCodeUnits(left.path, right.path) || compareCodeUnits(left.changeType, right.changeType));
+    unresolved.sort((left, right) => compareCodeUnits(left.path ?? "", right.path ?? "") || compareCodeUnits(left.reasonCode, right.reasonCode) || compareCodeUnits(left.message, right.message));
+    const modifiedCount = changes.filter((change) => change.changeType === "modified").length;
+    const missingCount = changes.length - modifiedCount;
+    const warnings = [];
+    if (changes.length > MAX_CHANGES)
+        warnings.push(`Change list truncated to ${MAX_CHANGES} of ${changes.length} entries.`);
+    if (unresolved.length > MAX_UNRESOLVED)
+        warnings.push(`Unresolved list truncated to ${MAX_UNRESOLVED} of ${unresolved.length} entries.`);
+    return {
+        schemaVersion: INDEX_FRESHNESS_SCHEMA_VERSION,
+        status: classifyIndexFreshness({ baselineSnapshotStatus, confirmedChangeCount: changes.length, unresolvedCount: unresolvedTotal }),
+        assessedAt,
+        baselineSnapshotStatus,
+        indexedFileCount: snapshot?.indexedFileCount ?? 0,
+        comparableFileCount: unchangedFileCount + modifiedCount,
+        unchangedFileCount,
+        changedFileCount: modifiedCount,
+        missingFileCount: missingCount,
+        unresolvedFileCount: unresolvedTotal,
+        changes: changes.slice(0, MAX_CHANGES),
+        changesTruncated: changes.length > MAX_CHANGES,
+        unresolved: unresolved.slice(0, MAX_UNRESOLVED),
+        unresolvedTruncated: unresolvedTotal > Math.min(unresolved.length, MAX_UNRESOLVED),
+        warnings,
+    };
+}

package/dist/src/evaluation/indexSnapshot.js

@@ -0,0 +1,393 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { relativeWithinRoot, resolveWithinRoot } from "../core/pathSafety.js";
+export const INDEX_SNAPSHOT_SCHEMA_VERSION = "my-dev-kit-lab-index-snapshot-v1";
+const SUPPORTED_MANIFEST_ARTIFACT_KIND = "my-dev-kit-v1-manifest";
+const SUPPORTED_MANIFEST_VERSION_PATTERN = /^1\./;
+const MANIFEST_FILE = "manifest.json";
+const MAX_ARTIFACT_ENTRIES = 512;
+const MAX_UNRESOLVED_ENTRIES = 50;
+const MAX_REPORTED_PATH_LENGTH = 260;
+const HASH_CONCURRENCY = 32;
+const MAX_TOOL_VERSION_LENGTH = 128;
+const TOOL_VERSION_NOT_PROBED = {
+    name: "my-dev-kit",
+    version: null,
+    availability: "unavailable",
+    reason: "The my-dev-kit index manifest and index command output do not expose the tool version, and no --version probe result was supplied.",
+};
+/**
+ * Policy: turns the outcome of a `<kit-command> --version` probe into bounded tool evidence. Uses
+ * the first non-empty output line verbatim (no semver requirement); anything unsupported, empty,
+ * unprintable, or oversized is explicitly unavailable rather than guessed. Pure.
+ */
+export function interpretToolVersionOutput(probe) {
+    const unavailable = (reason) => ({
+        name: "my-dev-kit",
+        version: null,
+        availability: "unavailable",
+        reason: boundedText(reason),
+    });
+    if (!probe.ok) {
+        const detail = probe.error ? `: ${probe.error}` : "";
+        return unavailable(`The --version probe did not succeed (exit code ${probe.exitCode ?? "none"})${detail}`);
+    }
+    const line = probe.stdout.split(/\r?\n/).map((entry) => entry.trim()).find((entry) => entry.length > 0);
+    if (line === undefined) {
+        return unavailable("The --version probe produced no output.");
+    }
+    if (/[\u0000-\u001f\u007f]/.test(line)) {
+        return unavailable("The --version probe reported a non-printable value.");
+    }
+    if (line.length > MAX_TOOL_VERSION_LENGTH) {
+        return unavailable(`The --version probe reported a value longer than ${MAX_TOOL_VERSION_LENGTH} characters.`);
+    }
+    return { name: "my-dev-kit", version: line, availability: "available", reason: null };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Locale- and platform-independent ordering so snapshots never depend on enumeration order. */
+export function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function boundedText(value) {
+    return value.length > MAX_REPORTED_PATH_LENGTH ? `${value.slice(0, MAX_REPORTED_PATH_LENGTH)}...` : value;
+}
+/**
+ * Policy: validates the manifest against the supported my-dev-kit contract and the expected
+ * target. Pure; performs no filesystem access.
+ */
+export function interpretIndexManifest(manifest, expected) {
+    const unsupported = (message) => ({ ok: false, code: "manifest-unsupported", message });
+    if (!isRecord(manifest)) {
+        return unsupported("Index manifest is not a JSON object.");
+    }
+    if (manifest.artifactKind !== SUPPORTED_MANIFEST_ARTIFACT_KIND) {
+        return unsupported(`Index manifest artifactKind is not ${SUPPORTED_MANIFEST_ARTIFACT_KIND}.`);
+    }
+    if (typeof manifest.version !== "string" || !SUPPORTED_MANIFEST_VERSION_PATTERN.test(manifest.version)) {
+        return unsupported("Index manifest version is missing or not a supported 1.x version.");
+    }
+    const artifacts = manifest.artifacts;
+    const symbolIndexPath = isRecord(artifacts) ? artifacts.symbolIndex : undefined;
+    if (typeof symbolIndexPath !== "string" || symbolIndexPath.length === 0) {
+        return unsupported("Index manifest does not name a symbolIndex artifact.");
+    }
+    if (typeof manifest.projectRoot !== "string" || manifest.projectRoot.length === 0) {
+        return unsupported("Index manifest does not record a projectRoot.");
+    }
+    const sourceRoots = manifest.sourceRoots;
+    if (!Array.isArray(sourceRoots) || !sourceRoots.every((root) => typeof root === "string")) {
+        return unsupported("Index manifest does not record sourceRoots.");
+    }
+    const sameSourceRoots = sourceRoots.length === expected.sourceRoots.length && sourceRoots.every((root, index) => root === expected.sourceRoots[index]);
+    if (!sameSourceRoots) {
+        return {
+            ok: false,
+            code: "manifest-target-mismatch",
+            message: `Index manifest source roots [${sourceRoots.join(", ")}] do not match [${expected.sourceRoots.join(", ")}].`,
+        };
+    }
+    const summary = manifest.summary;
+    const manifestFileCount = isRecord(summary) && typeof summary.fileCount === "number" ? summary.fileCount : null;
+    return {
+        ok: true,
+        contract: {
+            manifestArtifactKind: manifest.artifactKind,
+            manifestVersion: manifest.version,
+            createdAt: typeof manifest.createdAt === "string" ? manifest.createdAt : null,
+            symbolIndexRelativePath: symbolIndexPath,
+            manifestFileCount,
+            sourceRoots: [...sourceRoots],
+            projectRoot: manifest.projectRoot,
+        },
+    };
+}
+/**
+ * Policy: extracts the exact indexed-file path list from a symbol-index artifact. The count the
+ * index declares must agree with the list; duplicates are rejected rather than merged.
+ */
+export function interpretSymbolIndexFiles(symbolIndex, manifestFileCount) {
+    const unsupported = (message) => ({ ok: false, code: "symbol-index-unsupported", message });
+    if (!isRecord(symbolIndex)) {
+        return unsupported("Symbol index is not a JSON object.");
+    }
+    if (typeof symbolIndex.schemaVersion !== "string") {
+        return unsupported("Symbol index does not record a schemaVersion.");
+    }
+    const files = symbolIndex.files;
+    if (!Array.isArray(files)) {
+        return unsupported("Symbol index does not list indexed files.");
+    }
+    const paths = [];
+    for (const entry of files) {
+        if (!isRecord(entry) || typeof entry.path !== "string" || entry.path.length === 0) {
+            return unsupported("Symbol index contains a file entry without a path.");
+        }
+        paths.push(entry.path);
+    }
+    if (new Set(paths).size !== paths.length) {
+        return unsupported("Symbol index lists the same file path more than once.");
+    }
+    const declaredCounts = [symbolIndex.fileCount, manifestFileCount].filter((count) => typeof count === "number");
+    if (declaredCounts.some((count) => count !== paths.length)) {
+        return {
+            ok: false,
+            code: "indexed-file-count-mismatch",
+            message: `Symbol index lists ${paths.length} files but the index declares ${declaredCounts.join("/")}.`,
+        };
+    }
+    return { ok: true, schemaVersion: symbolIndex.schemaVersion, paths };
+}
+/**
+ * Policy: normalizes an index-listed path to a target-relative forward-slash path and confirms it
+ * stays inside the target and one of the configured source roots. Pure.
+ */
+export function resolveIndexedFilePath(targetRoot, sourceRoots, listedPath) {
+    const forward = listedPath.replace(/\\/g, "/");
+    if (forward.length === 0 || forward.includes("\0") || forward.startsWith("/") || /^[A-Za-z]:/.test(forward)) {
+        return { ok: false, reason: "invalid-path" };
+    }
+    try {
+        const absolute = resolveWithinRoot(targetRoot, forward);
+        const relativePath = relativeWithinRoot(targetRoot, absolute);
+        if (relativePath.length === 0) {
+            return { ok: false, reason: "invalid-path" };
+        }
+        const insideSourceRoot = sourceRoots.some((sourceRoot) => {
+            try {
+                relativeWithinRoot(resolveWithinRoot(targetRoot, sourceRoot), absolute);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        return insideSourceRoot ? { ok: true, relativePath } : { ok: false, reason: "outside-target-or-source-roots" };
+    }
+    catch {
+        return { ok: false, reason: "outside-target-or-source-roots" };
+    }
+}
+async function hashFile(absolutePath) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(absolutePath)) {
+        const buffer = chunk;
+        sizeBytes += buffer.length;
+        hash.update(buffer);
+    }
+    return { sha256: hash.digest("hex"), sizeBytes };
+}
+/** Reads and hashes one target-relative file without leaving the target (symlinks are resolved first). */
+export async function snapshotIndexedFile(targetRoot, realTargetRoot, relativePath) {
+    const absolutePath = path.resolve(targetRoot, relativePath);
+    try {
+        // A symlink must not carry the read outside the target.
+        const realPath = await realpath(absolutePath);
+        try {
+            relativeWithinRoot(realTargetRoot, realPath);
+        }
+        catch {
+            return { ok: false, reason: "outside-target-or-source-roots" };
+        }
+        const stats = await stat(realPath);
+        if (!stats.isFile()) {
+            return { ok: false, reason: "not-a-file" };
+        }
+        const { sha256, sizeBytes } = await hashFile(realPath);
+        return { ok: true, file: { path: relativePath, sha256, sizeBytes, modifiedAt: stats.mtime.toISOString() } };
+    }
+    catch (error) {
+        return { ok: false, reason: error.code === "ENOENT" ? "missing" : "unreadable" };
+    }
+}
+async function enumerateIndexArtifacts(indexDir) {
+    const artifacts = [];
+    let truncated = false;
+    const pending = [indexDir];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(absolutePath);
+            }
+            else if (entry.isFile()) {
+                if (artifacts.length >= MAX_ARTIFACT_ENTRIES) {
+                    truncated = true;
+                    continue;
+                }
+                artifacts.push({ path: relativeWithinRoot(indexDir, absolutePath), sizeBytes: (await stat(absolutePath)).size });
+            }
+        }
+    }
+    artifacts.sort((left, right) => compareCodeUnits(left.path, right.path));
+    return { artifacts, truncated };
+}
+async function readJson(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        return { ok: false, missing, message: missing ? "file does not exist" : `file could not be read: ${error.message}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return { ok: false, missing: false, message: `file is not valid JSON: ${error.message}` };
+    }
+}
+/** Runs `fn` over `items` with bounded concurrency, returning results in input order. */
+export async function mapInBatches(items, fn) {
+    const results = [];
+    for (let start = 0; start < items.length; start += HASH_CONCURRENCY) {
+        results.push(...(await Promise.all(items.slice(start, start + HASH_CONCURRENCY).map(fn))));
+    }
+    return results;
+}
+function unavailableSnapshot(command, failure, tool, manifest = null) {
+    return {
+        schemaVersion: INDEX_SNAPSHOT_SCHEMA_VERSION,
+        status: "unavailable",
+        unavailable: { code: failure.code, message: boundedText(failure.message) },
+        manifest,
+        tool: { ...tool },
+        indexCommand: summarizeIndexCommand(command),
+        indexedFileCount: 0,
+        files: [],
+        unresolvedFileCount: 0,
+        unresolvedFiles: [],
+        artifacts: [],
+        artifactsTruncated: false,
+    };
+}
+function summarizeIndexCommand(command) {
+    return { commandString: command.commandString, executable: command.executable, args: [...command.args] };
+}
+/**
+ * Captures bounded index-build evidence from an already built index: which files the index lists,
+ * their SHA-256 content identity, and the generated artifact inventory. Reads only the index
+ * directory and the listed files inside the target; runs no my-dev-kit command and never throws —
+ * an uninterpretable index yields an explicit `unavailable` snapshot instead of a guessed one.
+ * Performs no comparison and assigns no freshness.
+ */
+export async function captureIndexSnapshot(options) {
+    const { indexDir, targetRoot, sourceRoots, command } = options;
+    const tool = options.tool ?? TOOL_VERSION_NOT_PROBED;
+    try {
+        const manifestRead = await readJson(path.join(indexDir, MANIFEST_FILE));
+        if (!manifestRead.ok) {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: manifestRead.missing ? "manifest-missing" : "manifest-unreadable",
+                message: `Index manifest ${manifestRead.message}.`,
+            }, tool);
+        }
+        const manifest = interpretIndexManifest(manifestRead.value, { sourceRoots });
+        if (!manifest.ok) {
+            return unavailableSnapshot(command, manifest, tool);
+        }
+        const { contract } = manifest;
+        const realTargetRoot = await realpath(targetRoot);
+        let manifestRoot;
+        try {
+            manifestRoot = await realpath(contract.projectRoot);
+        }
+        catch {
+            manifestRoot = path.resolve(contract.projectRoot);
+        }
+        if (path.relative(realTargetRoot, manifestRoot) !== "") {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: "manifest-target-mismatch",
+                message: "Index manifest projectRoot does not match the target root.",
+            }, tool);
+        }
+        let symbolIndexFile;
+        try {
+            symbolIndexFile = resolveWithinRoot(indexDir, contract.symbolIndexRelativePath);
+        }
+        catch {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: "manifest-unsupported",
+                message: "Index manifest symbolIndex path escapes the index directory.",
+            }, tool);
+        }
+        const symbolIndexRead = await readJson(symbolIndexFile);
+        if (!symbolIndexRead.ok) {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: symbolIndexRead.missing ? "symbol-index-missing" : "symbol-index-unreadable",
+                message: `Symbol index ${symbolIndexRead.message}.`,
+            }, tool);
+        }
+        const symbolIndex = interpretSymbolIndexFiles(symbolIndexRead.value, contract.manifestFileCount);
+        const manifestSummary = {
+            path: MANIFEST_FILE,
+            artifactKind: contract.manifestArtifactKind,
+            schemaVersion: contract.manifestVersion,
+            createdAt: contract.createdAt,
+            symbolIndexPath: relativeWithinRoot(indexDir, symbolIndexFile),
+            symbolIndexSchemaVersion: symbolIndex.ok ? symbolIndex.schemaVersion : "unknown",
+        };
+        if (!symbolIndex.ok) {
+            return unavailableSnapshot(command, symbolIndex, tool, manifestSummary);
+        }
+        const resolved = symbolIndex.paths.map((listed) => ({ listed, resolution: resolveIndexedFilePath(targetRoot, sourceRoots, listed) }));
+        const unresolved = [];
+        const toHash = [];
+        for (const { listed, resolution } of resolved) {
+            if (resolution.ok) {
+                toHash.push(resolution.relativePath);
+            }
+            else {
+                unresolved.push({ path: boundedText(listed), reason: resolution.reason });
+            }
+        }
+        const files = [];
+        for (let start = 0; start < toHash.length; start += HASH_CONCURRENCY) {
+            const batch = toHash.slice(start, start + HASH_CONCURRENCY);
+            const results = await Promise.all(batch.map((relativePath) => snapshotIndexedFile(targetRoot, realTargetRoot, relativePath)));
+            results.forEach((result, position) => {
+                if (result.ok) {
+                    files.push(result.file);
+                }
+                else {
+                    unresolved.push({ path: boundedText(batch[position]), reason: result.reason });
+                }
+            });
+        }
+        files.sort((left, right) => compareCodeUnits(left.path, right.path));
+        unresolved.sort((left, right) => compareCodeUnits(left.path, right.path) || compareCodeUnits(left.reason, right.reason));
+        const inventory = await enumerateIndexArtifacts(indexDir);
+        return {
+            schemaVersion: INDEX_SNAPSHOT_SCHEMA_VERSION,
+            status: unresolved.length === 0 ? "complete" : "partial",
+            unavailable: null,
+            manifest: manifestSummary,
+            tool: { ...tool },
+            indexCommand: summarizeIndexCommand(command),
+            indexedFileCount: symbolIndex.paths.length,
+            files,
+            unresolvedFileCount: unresolved.length,
+            unresolvedFiles: unresolved.slice(0, MAX_UNRESOLVED_ENTRIES),
+            artifacts: inventory.artifacts,
+            artifactsTruncated: inventory.truncated,
+        };
+    }
+    catch (error) {
+        return unavailableSnapshot(command, {
+            ok: false,
+            code: "snapshot-capture-failed",
+            message: `Index snapshot capture failed: ${error.message}`,
+        }, tool);
+    }
+}