@dailephd/my-dev-kit-lab 0.6.1 → 0.6.2

package/dist/src/experiments/plugins/incrementalChangeStaleness/executionArtifact.js

@@ -0,0 +1,160 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+// ---------------------------------------------------------------------------
+// v0.6.2 Batch 4 -- final persisted execution/comparison artifact. Owns only
+// the artifact types, the schema constant, the bounded projection from
+// runtime evidence, summary counts, and writing the artifact file. No
+// comparison formula and no artifact serialization logic for another plugin
+// lives here.
+// ---------------------------------------------------------------------------
+export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE = "incremental-change-staleness-execution.json";
+export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION = "my-dev-kit-lab-incremental-change-staleness-execution-v1";
+function sortedUnique(values) {
+    return [...new Set(values)].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function summarizeCommand(command) {
+    return {
+        commandId: command.commandId,
+        ok: command.ok,
+        exitCode: command.exitCode,
+        durationMs: command.durationMs,
+        stdoutPath: command.stdoutPath,
+        stderrPath: command.stderrPath,
+        telemetryPath: command.telemetryPath,
+        error: command.error ?? null
+    };
+}
+function summarizeRetrieval(treatment) {
+    const retrieval = treatment.retrieval;
+    if (!retrieval) {
+        return {
+            status: "not-run",
+            warnings: [],
+            totalChars: 0,
+            totalEstimatedTokens: 0,
+            tokenCountMethod: "unavailable",
+            filesRead: [],
+            selectedNodeId: null,
+            selectedFile: null,
+            selectedSymbol: null,
+            durationMs: 0,
+            commands: []
+        };
+    }
+    return {
+        // Bounded status only; never embeds retrieval.contextText (the full context body).
+        status: treatment.retrievalStatus === "not-run" ? "not-run" : treatment.retrievalStatus,
+        warnings: [...retrieval.warnings],
+        totalChars: retrieval.totalChars,
+        totalEstimatedTokens: retrieval.totalEstimatedTokens,
+        tokenCountMethod: retrieval.tokenCountMethod,
+        filesRead: sortedUnique(retrieval.filesRead),
+        selectedNodeId: retrieval.selectedNodeId ?? null,
+        selectedFile: retrieval.selectedFile ?? null,
+        selectedSymbol: retrieval.selectedSymbol ?? null,
+        durationMs: retrieval.durationMs,
+        commands: retrieval.commands.map(summarizeCommand)
+    };
+}
+function summarizeFakeAgent(treatment) {
+    if (!treatment.fakeAgent)
+        return null;
+    const agent = treatment.fakeAgent;
+    return {
+        status: agent.status,
+        correctness: { ...agent.correctness, failureReasons: [...agent.correctness.failureReasons] },
+        correctnessDetail: agent.correctnessDetail ? { ...agent.correctnessDetail, failureReasons: [...agent.correctnessDetail.failureReasons] } : null,
+        durationMs: agent.durationMs,
+        warnings: [...agent.warnings],
+        errors: [...agent.errors]
+    };
+}
+function summarizeRequiredFileEvidence(evidence) {
+    return {
+        status: evidence.status,
+        requiredFiles: sortedUnique(evidence.requiredFiles),
+        observedFiles: sortedUnique(evidence.observedFiles),
+        missingFiles: sortedUnique(evidence.missingFiles),
+        reason: evidence.reason
+    };
+}
+function summarizeTreatment(treatment) {
+    if (!treatment)
+        return null;
+    return {
+        treatmentId: treatment.treatmentId,
+        status: treatment.status,
+        failureReason: treatment.failureReason,
+        activeIndexPhase: treatment.activeIndexPhase,
+        baselineFreshness: structuredClone(treatment.baselineFreshness),
+        affectedNeighborhood: structuredClone(treatment.affectedNeighborhood),
+        retrieval: summarizeRetrieval(treatment),
+        fakeAgent: summarizeFakeAgent(treatment),
+        requiredFileEvidence: summarizeRequiredFileEvidence(treatment.requiredFileEvidence)
+    };
+}
+function summarizeLifecycle(execution) {
+    const session = execution.session;
+    if (!session)
+        return null;
+    return {
+        preMutationEquivalence: session.preMutationEquivalence.result,
+        postMutationEquivalence: session.postMutationEquivalence.result,
+        controlledFilePaths: [...session.controlledChangedPaths],
+        staleBaselineFreshnessStatus: session.treatments["stale-index"].changeAuthority.postMutationBaselineFreshness.status,
+        fullRefreshBaselineFreshnessStatus: session.treatments["full-refresh"].changeAuthority.postMutationBaselineFreshness.status,
+        fullRefreshRefreshedFreshnessStatus: session.treatments["full-refresh"].refreshedFreshness?.status ?? null,
+        myDevKitVersion: session.toolIdentity.version ?? null,
+        sourceRoots: [...session.baseCase.sourceRoots]
+    };
+}
+function summarizeScenario(execution) {
+    return {
+        scenarioId: execution.scenarioId,
+        category: execution.category,
+        benchmarkProjectId: execution.benchmarkProjectId,
+        baseCaseId: execution.baseCaseId,
+        answerPolicy: execution.answerPolicy,
+        query: execution.query,
+        expectedFiles: sortedUnique(execution.expectedFiles),
+        expectedSymbols: sortedUnique(execution.expectedSymbols),
+        status: execution.status,
+        failureReason: execution.failureReason,
+        lifecycle: summarizeLifecycle(execution),
+        // Treatment order in the persisted record is always stale-index then full-refresh.
+        stale: summarizeTreatment(execution.stale),
+        fullRefresh: summarizeTreatment(execution.fullRefresh),
+        comparison: { ...execution.comparison, reasonCodes: [...execution.comparison.reasonCodes] }
+    };
+}
+function summarize(scenarios) {
+    return {
+        scenarioCount: scenarios.length,
+        readyScenarioCount: scenarios.filter((scenario) => scenario.status === "ready").length,
+        failedScenarioCount: scenarios.filter((scenario) => scenario.status === "failed").length,
+        observedStaleRegressionCount: scenarios.filter((scenario) => scenario.comparison.staleRiskClassification === "observed-stale-regression").length,
+        noObservedStaleRegressionCount: scenarios.filter((scenario) => scenario.comparison.staleRiskClassification === "no-observed-stale-regression").length,
+        inconclusiveCount: scenarios.filter((scenario) => scenario.comparison.staleRiskClassification === "inconclusive").length
+    };
+}
+/**
+ * Builds the final artifact from already-executed scenario evidence, in the exact order the
+ * caller supplies (canonical selected-scenario order). Treatment order within each scenario is
+ * always stale-index then full-refresh (`INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS`).
+ */
+export function buildIncrementalChangeStalenessExecutionArtifact(args) {
+    const scenarios = args.executions.map(summarizeScenario);
+    return {
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION,
+        runId: args.runId,
+        pluginId: args.pluginId,
+        scenarios,
+        summary: summarize(scenarios)
+    };
+}
+export async function writeIncrementalChangeStalenessExecutionArtifact(outDir, artifact) {
+    await mkdir(outDir, { recursive: true });
+    const artifactPath = resolveWithinRoot(outDir, INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE);
+    await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+    return artifactPath;
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/index.js

@@ -0,0 +1,13 @@
+export * from "./scenarioTypes.js";
+export * from "./scenarioMutation.js";
+export * from "./scenarioValidation.js";
+export * from "./scenarioCatalog.js";
+export * from "./disposableTarget.js";
+export * from "./sourceState.js";
+export * from "./mutationExecution.js";
+export * from "./treatmentSession.js";
+export * from "./lifecyclePolicy.js";
+export * from "./scenarioSelection.js";
+export * from "./lifecycle.js";
+export * from "./config.js";
+export * from "./plugin.js";

package/dist/src/experiments/plugins/incrementalChangeStaleness/lifecycle.js

@@ -0,0 +1,276 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { assessIndexFreshness } from "../../../evaluation/indexFreshness.js";
+import { prepareWarmIndexSession } from "../warmIndexReuse/warmIndexSession.js";
+import { createDisposableTreatmentTarget } from "./disposableTarget.js";
+import { evaluateBaselineStaleFreshness, evaluateChangedPathSymmetry, evaluateIndexEvidence, evaluateRefreshedFreshness, evaluateToolIdentity, normalizeRelativePath, normalizeRootForComparison } from "./lifecyclePolicy.js";
+import { executeIncrementalChangeStalenessMutation } from "./mutationExecution.js";
+import { captureIncrementalChangeStalenessSourceState, compareIncrementalChangeStalenessSourceStates } from "./sourceState.js";
+import { INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_SCHEMA_VERSION } from "./treatmentSession.js";
+export const defaultIncrementalChangeStalenessLifecycleDeps = {
+    prepareIndexSession: prepareWarmIndexSession,
+    assessIndexFreshness,
+    executeMutation: executeIncrementalChangeStalenessMutation,
+    captureSourceState: captureIncrementalChangeStalenessSourceState
+};
+/** Deterministic run-owned layout: targets/, indexes/, and commands/ are separate sibling trees. */
+export function incrementalChangeStalenessTargetsRoot(runOwnedRoot) {
+    return path.join(path.resolve(runOwnedRoot), "targets");
+}
+export function incrementalChangeStalenessIndexDir(runOwnedRoot, scenarioId, treatmentId, role) {
+    return resolveWithinRoot(path.resolve(runOwnedRoot), path.join("indexes", scenarioId, treatmentId, role));
+}
+export function incrementalChangeStalenessCommandsDir(runOwnedRoot, scenarioId, treatmentId, role) {
+    return resolveWithinRoot(path.resolve(runOwnedRoot), path.join("commands", scenarioId, treatmentId, role));
+}
+class LifecycleFailure extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}
+function fail(failure) {
+    if (failure)
+        throw new LifecycleFailure(failure);
+}
+/**
+ * Owns the matched Batch 3 lifecycle for ONE frozen scenario:
+ *
+ *  1. two independent disposable copies (stale-index, full-refresh);
+ *  2. pre-mutation controlled source-state equivalence;
+ *  3. stale-index baseline: index -> snapshot -> graph, then identity proof;
+ *  4. full-refresh baseline: index -> snapshot -> graph, then identity proof;
+ *  5. BARRIER: only after both baselines are fully ready, the same frozen
+ *     mutation is applied independently to both copies;
+ *  6. post-mutation controlled source-state equivalence;
+ *  7. each baseline snapshot assessed against its mutated target (complete
+ *     `stale` on exactly the scenario-controlled paths, symmetric across
+ *     treatments);
+ *  8. stale-index keeps its baseline index as active retrieval authority
+ *     (no rebuild);
+ *  9. full-refresh builds a NEW complete index into a separate directory,
+ *     captures its snapshot/graph, and proves it complete `fresh`.
+ *
+ * Exactly three full index builds and three freshness assessments happen per
+ * scenario. Performs no retrieval, affected-neighborhood traversal, metric
+ * computation, correctness evaluation, or comparison classification, and
+ * never acts on a reindex recommendation. Sequential by design. Does not
+ * delete anything: the caller owns and cleans the run-owned root after the
+ * session has been consumed.
+ */
+export async function prepareIncrementalChangeStalenessScenarioLifecycle(options) {
+    const deps = { ...defaultIncrementalChangeStalenessLifecycleDeps, ...options.deps };
+    const { repoRoot, scenario, baseCase, kitCommand } = options;
+    const runOwnedRoot = path.resolve(options.runOwnedRoot);
+    const events = [];
+    const indexBuildCounts = { "stale-index": 0, "full-refresh": 0 };
+    const sourceRoots = baseCase.sourceRoots;
+    const controlledChangedPaths = scenario.mutation.files.map((file) => normalizeRelativePath(file.path)).sort();
+    async function prepareIndex(target, role, indexDir) {
+        const treatmentId = target.treatmentId;
+        if (existsSync(indexDir)) {
+            fail({ code: "index-directory-collision", message: `Refusing to overwrite existing ${treatmentId} ${role} index directory: ${indexDir}.`, treatmentId });
+        }
+        const commandsDir = incrementalChangeStalenessCommandsDir(runOwnedRoot, scenario.id, treatmentId, role);
+        indexBuildCounts[treatmentId] += 1;
+        const prepared = await deps.prepareIndexSession({
+            target: { absoluteTargetRoot: target.targetRoot, sourceRoots: [...sourceRoots] },
+            kitCommand,
+            indexDir,
+            commandsDir,
+            requireKit: false
+        });
+        if (!prepared.ok) {
+            fail({
+                code: role === "baseline" ? "baseline-index-build-failed" : "refresh-index-build-failed",
+                message: `${treatmentId} ${role} my-dev-kit index build failed: ${prepared.warnings.join(" ") || `exit code ${prepared.build.command.exitCode}`}`,
+                treatmentId
+            });
+            throw new Error("unreachable");
+        }
+        // prepareIndexSession resolves only after the index command, snapshot capture, and graph
+        // loading have all completed, in that order.
+        events.push(`${treatmentId}:${role}-index-built`, `${treatmentId}:${role}-snapshot-captured`, `${treatmentId}:${role}-graph-loaded`);
+        const evidence = Object.freeze({
+            role,
+            treatmentId,
+            builtRelativeToMutation: role === "baseline" ? "pre-mutation" : "post-mutation",
+            indexDir: prepared.session.indexDir,
+            commandsDir,
+            targetRoot: prepared.session.targetRoot,
+            sourceRoots: prepared.session.sourceRoots,
+            buildDurationMs: prepared.session.buildDurationMs,
+            buildCommand: prepared.session.buildCommand,
+            snapshot: prepared.session.indexSnapshot,
+            graph: prepared.session.affectedNeighborhoodGraph
+        });
+        fail(evaluateIndexEvidence(evidence, { targetRoot: target.targetRoot, sourceRoots, indexDir }));
+        events.push(`${treatmentId}:${role}-identity-verified`);
+        return evidence;
+    }
+    async function captureState(target) {
+        return deps.captureSourceState(target.targetRoot, sourceRoots, target.treatmentId, baseCase.benchmarkProjectId);
+    }
+    async function mutate(target) {
+        const receipt = await deps.executeMutation(scenario, target, sourceRoots, repoRoot);
+        if (receipt.status !== "applied") {
+            fail({ code: "mutation-failed", message: `${target.treatmentId} mutation was rejected: ${receipt.errors.join(" ")}`, treatmentId: target.treatmentId });
+        }
+        events.push(`${target.treatmentId}:mutation-applied`);
+        return receipt;
+    }
+    async function assess(index, target) {
+        return deps.assessIndexFreshness({ snapshot: index.snapshot, targetRoot: target.targetRoot, sourceRoots });
+    }
+    try {
+        const indexDirs = {
+            staleBaseline: incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, "stale-index", "baseline"),
+            fullBaseline: incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, "full-refresh", "baseline"),
+            fullRefreshed: incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, "full-refresh", "refreshed")
+        };
+        if (normalizeRootForComparison(indexDirs.staleBaseline) === normalizeRootForComparison(indexDirs.fullBaseline) ||
+            normalizeRootForComparison(indexDirs.fullBaseline) === normalizeRootForComparison(indexDirs.fullRefreshed) ||
+            normalizeRootForComparison(indexDirs.staleBaseline) === normalizeRootForComparison(indexDirs.fullRefreshed)) {
+            fail({ code: "index-directory-collision", message: "Treatment/phase index directories are not distinct.", treatmentId: null });
+        }
+        // 1. Two independent disposable copies through the Batch 2 owner.
+        const targets = {};
+        for (const treatmentId of ["stale-index", "full-refresh"]) {
+            try {
+                targets[treatmentId] = await createDisposableTreatmentTarget({
+                    repoRoot,
+                    runRoot: incrementalChangeStalenessTargetsRoot(runOwnedRoot),
+                    scenarioId: scenario.id,
+                    treatmentId,
+                    benchmarkProjectId: baseCase.benchmarkProjectId,
+                    canonicalProjectRootRelative: baseCase.canonicalProjectRootRelative
+                });
+            }
+            catch (error) {
+                fail({ code: "treatment-target-creation-failed", message: `${treatmentId}: ${error.message}`, treatmentId });
+            }
+        }
+        const stale = targets["stale-index"];
+        const full = targets["full-refresh"];
+        events.push("treatment-targets-created");
+        // 2. Pre-mutation equivalence gates all indexing and mutation.
+        const stalePre = await captureState(stale);
+        const fullPre = await captureState(full);
+        events.push("pre-mutation-source-state-captured");
+        const preMutationEquivalence = compareIncrementalChangeStalenessSourceStates(stalePre, fullPre);
+        if (preMutationEquivalence.result !== "equivalent") {
+            fail({
+                code: "pre-mutation-not-equivalent",
+                message: `Treatment copies are not pre-mutation equivalent (${preMutationEquivalence.result}): ${preMutationEquivalence.reasons.join("; ")}`,
+                treatmentId: null
+            });
+        }
+        events.push("pre-mutation-equivalence-proven");
+        // 3-4. Baselines: each index -> snapshot -> graph -> identity, sequentially.
+        const staleBaseline = await prepareIndex(stale, "baseline", indexDirs.staleBaseline);
+        const fullBaseline = await prepareIndex(full, "baseline", indexDirs.fullBaseline);
+        const baselineTools = evaluateToolIdentity([staleBaseline, fullBaseline]);
+        fail(baselineTools.failure);
+        events.push("baseline-tool-identity-verified");
+        // 5. Barrier: both baselines are index + snapshot + graph READY. Only now may mutation begin.
+        events.push("baseline-barrier-ready");
+        const staleReceipt = await mutate(stale);
+        const fullReceipt = await mutate(full);
+        // 6. Post-mutation equivalence.
+        const stalePost = await captureState(stale);
+        const fullPost = await captureState(full);
+        events.push("post-mutation-source-state-captured");
+        const postMutationEquivalence = compareIncrementalChangeStalenessSourceStates(stalePost, fullPost);
+        if (postMutationEquivalence.result !== "equivalent") {
+            fail({
+                code: "post-mutation-not-equivalent",
+                message: `Treatment copies are not post-mutation equivalent (${postMutationEquivalence.result}): ${postMutationEquivalence.reasons.join("; ")}`,
+                treatmentId: null
+            });
+        }
+        events.push("post-mutation-equivalence-proven");
+        // 7. Baseline (change-authority) freshness against each mutated target.
+        const staleBaselineFreshness = await assess(staleBaseline, stale);
+        fail(evaluateBaselineStaleFreshness(staleBaselineFreshness, controlledChangedPaths, "stale-index"));
+        events.push("stale-index:baseline-freshness-stale");
+        const fullBaselineFreshness = await assess(fullBaseline, full);
+        fail(evaluateBaselineStaleFreshness(fullBaselineFreshness, controlledChangedPaths, "full-refresh"));
+        events.push("full-refresh:baseline-freshness-stale");
+        fail(evaluateChangedPathSymmetry(staleBaselineFreshness, fullBaselineFreshness));
+        events.push("baseline-changed-paths-symmetric");
+        // 8. stale-index: no rebuild; baseline stays the active retrieval index.
+        events.push("stale-index:baseline-retained-as-active");
+        // 9. full-refresh: new complete post-mutation index in a separate directory.
+        const refreshed = await prepareIndex(full, "refreshed", indexDirs.fullRefreshed);
+        const refreshedFreshness = await assess(refreshed, full);
+        fail(evaluateRefreshedFreshness(refreshedFreshness));
+        events.push("full-refresh:refreshed-freshness-fresh");
+        const allTools = evaluateToolIdentity([staleBaseline, fullBaseline, refreshed]);
+        fail(allTools.failure);
+        events.push("tool-identity-consistent");
+        events.push("full-refresh:refreshed-active");
+        events.push("lifecycle-ready");
+        const staleSession = Object.freeze({
+            treatmentId: "stale-index",
+            target: stale,
+            preMutationSourceState: stalePre,
+            postMutationSourceState: stalePost,
+            mutationReceipt: staleReceipt,
+            changeAuthority: Object.freeze({ baselineIndex: staleBaseline, postMutationBaselineFreshness: staleBaselineFreshness }),
+            activeRetrieval: Object.freeze({ role: "baseline", index: staleBaseline }),
+            postMutationIndexBuilt: false,
+            refreshedIndex: null,
+            refreshedFreshness: null,
+            indexBuildCount: indexBuildCounts["stale-index"],
+            freshnessAssessmentCount: 1,
+            lifecycleStatus: "ready",
+            warnings: Object.freeze([])
+        });
+        const fullSession = Object.freeze({
+            treatmentId: "full-refresh",
+            target: full,
+            preMutationSourceState: fullPre,
+            postMutationSourceState: fullPost,
+            mutationReceipt: fullReceipt,
+            changeAuthority: Object.freeze({ baselineIndex: fullBaseline, postMutationBaselineFreshness: fullBaselineFreshness }),
+            activeRetrieval: Object.freeze({ role: "refreshed", index: refreshed }),
+            postMutationIndexBuilt: true,
+            refreshedIndex: refreshed,
+            refreshedFreshness,
+            indexBuildCount: indexBuildCounts["full-refresh"],
+            freshnessAssessmentCount: 2,
+            lifecycleStatus: "ready",
+            warnings: Object.freeze([])
+        });
+        const session = Object.freeze({
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_SCHEMA_VERSION,
+            scenarioId: scenario.id,
+            scenario,
+            baseCase,
+            runOwnedRoot,
+            kitCommand,
+            toolIdentity: allTools.tool,
+            controlledChangedPaths: Object.freeze(controlledChangedPaths),
+            preMutationEquivalence,
+            postMutationEquivalence,
+            treatments: Object.freeze({ "stale-index": staleSession, "full-refresh": fullSession }),
+            lifecycleEvents: Object.freeze([...events]),
+            status: "ready"
+        });
+        return { status: "ready", session };
+    }
+    catch (error) {
+        const failure = error instanceof LifecycleFailure
+            ? error.failure
+            : { code: "lifecycle-error", message: `Lifecycle failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`, treatmentId: null };
+        return {
+            status: "failed",
+            scenarioId: scenario.id,
+            failure,
+            lifecycleEvents: Object.freeze([...events]),
+            indexBuildCounts: Object.freeze({ ...indexBuildCounts })
+        };
+    }
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/lifecyclePolicy.js

@@ -0,0 +1,152 @@
+import path from "node:path";
+/**
+ * Pure v0.6.2 Batch 3 lifecycle-readiness policy. Every function here only
+ * inspects already-produced evidence and returns an explicit failure or
+ * null; none touches the filesystem, runs my-dev-kit, mutates, or retrieves.
+ * These rules are scoped to this experiment's matched production lifecycle
+ * and deliberately do not change the released v0.6.0/v0.6.1 semantics of the
+ * evidence they read.
+ */
+export function normalizeRootForComparison(root) {
+    const resolved = path.resolve(root);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+export function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/\\/g, "/");
+}
+function normalizeSourceRoot(root) {
+    return root.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/** Exact, order-preserving source-root equality after separator/trailing-slash normalization. */
+export function sameSourceRoots(left, right) {
+    return left.length === right.length && left.every((root, index) => normalizeSourceRoot(root) === normalizeSourceRoot(right[index]));
+}
+/**
+ * Graph evidence is usable for this lifecycle only when an indexed-file claim
+ * exists (not `unavailable`) AND the code graph was actually loaded, since a
+ * null code graph makes later node mapping impossible.
+ */
+export function isUsableGraphEvidence(graph) {
+    return graph.status !== "unavailable" && graph.codeGraph !== null;
+}
+function failure(code, message, treatmentId) {
+    return { code, message, treatmentId };
+}
+/**
+ * Proves one prepared index belongs to the intended treatment target, uses
+ * the canonical source roots, carries a complete IndexSnapshotV1 (whose
+ * manifest projectRoot/sourceRoots were already checked against the target by
+ * captureIndexSnapshot), and carries usable graph evidence loaded from the
+ * same index directory. Never relies on directory naming alone.
+ */
+export function evaluateIndexEvidence(evidence, expected) {
+    const refreshed = evidence.role === "refreshed";
+    const label = `${evidence.treatmentId} ${evidence.role} index`;
+    const targetMismatchCode = refreshed ? "active-index-target-mismatch" : "index-target-mismatch";
+    if (normalizeRootForComparison(evidence.targetRoot) !== normalizeRootForComparison(expected.targetRoot)) {
+        return failure(targetMismatchCode, `${label} target root ${evidence.targetRoot} does not match treatment target ${expected.targetRoot}.`, evidence.treatmentId);
+    }
+    if (normalizeRootForComparison(evidence.indexDir) !== normalizeRootForComparison(expected.indexDir)) {
+        return failure(targetMismatchCode, `${label} directory ${evidence.indexDir} does not match the owned index directory ${expected.indexDir}.`, evidence.treatmentId);
+    }
+    if (!sameSourceRoots(evidence.sourceRoots, expected.sourceRoots)) {
+        return failure("source-root-mismatch", `${label} source roots [${evidence.sourceRoots.join(", ")}] do not match canonical base-case source roots [${expected.sourceRoots.join(", ")}].`, evidence.treatmentId);
+    }
+    const snapshot = evidence.snapshot;
+    if (snapshot.status === "unavailable" && snapshot.unavailable?.code === "manifest-target-mismatch") {
+        return failure(targetMismatchCode, `${label} manifest does not belong to the treatment target: ${snapshot.unavailable.message}`, evidence.treatmentId);
+    }
+    if (snapshot.status !== "complete") {
+        const reason = snapshot.unavailable ? `${snapshot.unavailable.code}: ${snapshot.unavailable.message}` : `${snapshot.unresolvedFileCount} unresolved indexed file(s)`;
+        return failure(refreshed ? "refreshed-snapshot-unavailable" : "baseline-snapshot-unavailable", `${label} IndexSnapshotV1 is ${snapshot.status} (${reason}).`, evidence.treatmentId);
+    }
+    if (normalizeRootForComparison(evidence.graph.indexRoot) !== normalizeRootForComparison(expected.indexDir)) {
+        return failure(targetMismatchCode, `${label} graph evidence was loaded from ${evidence.graph.indexRoot}, not ${expected.indexDir}.`, evidence.treatmentId);
+    }
+    if (!isUsableGraphEvidence(evidence.graph)) {
+        const reason = evidence.graph.unavailable ? `${evidence.graph.unavailable.code}: ${evidence.graph.unavailable.message}` : "code graph was not loaded";
+        return failure(refreshed ? "refreshed-graph-unavailable" : "baseline-graph-unavailable", `${label} graph evidence is not usable (${evidence.graph.status}; ${reason}).`, evidence.treatmentId);
+    }
+    return null;
+}
+/**
+ * Every index of one matched scenario must come from the same configured
+ * my-dev-kit command and the same probed tool version. An unavailable
+ * version is never guessed: identity that cannot be established blocks
+ * readiness explicitly.
+ */
+export function evaluateToolIdentity(indexes) {
+    for (const index of indexes) {
+        if (index.snapshot.tool.availability !== "available" || index.snapshot.tool.version === null) {
+            return {
+                failure: failure("tool-identity-unavailable", `${index.treatmentId} ${index.role} index my-dev-kit version could not be established: ${index.snapshot.tool.reason ?? "unavailable"}.`, index.treatmentId),
+                tool: null
+            };
+        }
+    }
+    const versions = [...new Set(indexes.map((index) => index.snapshot.tool.version))];
+    if (versions.length > 1) {
+        return {
+            failure: failure("tool-identity-mismatch", `Matched scenario indexes were built with different my-dev-kit versions: ${indexes.map((index) => `${index.treatmentId}/${index.role}=${index.snapshot.tool.version}`).join(", ")}.`, null),
+            tool: null
+        };
+    }
+    const commands = [...new Set(indexes.map((index) => index.snapshot.indexCommand.commandString))];
+    if (commands.length > 1) {
+        return {
+            failure: failure("tool-identity-mismatch", `Matched scenario indexes were built with different my-dev-kit commands: ${commands.join(" | ")}.`, null),
+            tool: null
+        };
+    }
+    return { failure: null, tool: indexes.length > 0 ? { ...indexes[0].snapshot.tool } : null };
+}
+function changedPaths(assessment) {
+    return assessment.changes.map((change) => normalizeRelativePath(change.path)).sort();
+}
+/**
+ * A frozen production scenario must be observed as COMPLETE `stale` against
+ * the pre-mutation baseline snapshot, and the confirmed changed set must be
+ * exactly the scenario-declared controlled file(s) (all modifications, none
+ * missing). `fresh`, `unknown`, and `partially-stale` never count as a proven
+ * controlled stale state.
+ */
+export function evaluateBaselineStaleFreshness(assessment, controlledChangedPaths, treatmentId) {
+    if (assessment.status !== "stale") {
+        return failure("baseline-freshness-not-stale", `${treatmentId} baseline freshness after mutation is ${assessment.status}, not complete stale.`, treatmentId);
+    }
+    if (assessment.baselineSnapshotStatus !== "complete" || assessment.unresolvedFileCount !== 0 || assessment.changesTruncated) {
+        return failure("baseline-freshness-not-stale", `${treatmentId} baseline freshness comparison is incomplete (snapshot ${assessment.baselineSnapshotStatus}, ${assessment.unresolvedFileCount} unresolved, truncated=${assessment.changesTruncated}).`, treatmentId);
+    }
+    const expected = [...controlledChangedPaths].map(normalizeRelativePath).sort();
+    const observed = changedPaths(assessment);
+    const sameSet = observed.length === expected.length && observed.every((value, index) => value === expected[index]);
+    if (!sameSet || assessment.missingFileCount !== 0) {
+        return failure("baseline-changed-paths-mismatch", `${treatmentId} baseline freshness changed paths [${observed.join(", ")}] (missing=${assessment.missingFileCount}) do not match scenario-controlled paths [${expected.join(", ")}].`, treatmentId);
+    }
+    return null;
+}
+/**
+ * Both treatments applied the same mutation to equivalent copies, so their
+ * baseline freshness change evidence must agree path-for-path, including
+ * baseline and current content identity.
+ */
+export function evaluateChangedPathSymmetry(stale, fullRefresh) {
+    const key = (assessment) => assessment.changes
+        .map((change) => `${normalizeRelativePath(change.path)}\t${change.changeType}\t${change.baselineSha256}\t${change.currentSha256 ?? "null"}`)
+        .sort();
+    const left = key(stale);
+    const right = key(fullRefresh);
+    const same = left.length === right.length && left.every((value, index) => value === right[index]);
+    if (!same) {
+        return failure("treatment-changed-paths-conflict", `stale-index and full-refresh baseline freshness disagree about the controlled change: stale=[${left.join("; ")}] full-refresh=[${right.join("; ")}].`, null);
+    }
+    return null;
+}
+/** The refreshed index must be proven complete `fresh` against the unchanged mutated target. */
+export function evaluateRefreshedFreshness(assessment) {
+    const complete = assessment.baselineSnapshotStatus === "complete" && assessment.unresolvedFileCount === 0;
+    if (assessment.status !== "fresh" || !complete || assessment.changedFileCount !== 0 || assessment.missingFileCount !== 0) {
+        return failure("refreshed-freshness-not-fresh", `full-refresh refreshed index freshness is ${assessment.status} (snapshot ${assessment.baselineSnapshotStatus}, ${assessment.changedFileCount} changed, ${assessment.missingFileCount} missing, ${assessment.unresolvedFileCount} unresolved); complete fresh is required.`, "full-refresh");
+    }
+    return null;
+}