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

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

@@ -0,0 +1,195 @@
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { classifyStaleRisk, compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+import { compareCandidateCorrectness, compareCandidateRequiredFileEvidence, classifyPartialRefreshAgainstFull } from "./comparisonV2.js";
+import { INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { assessIncrementalChangeStalenessAffectedNeighborhood, checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry, correctnessComparable, defaultIncrementalChangeStalenessExecutionDeps, executeTreatmentEvaluation, INCONCLUSIVE_NO_EXECUTION, resolveIncrementalChangeStalenessScenarioTask } from "./execution.js";
+/**
+ * Four-way check with stale-index only as the deterministic reference. Reuses the v0.6.2 pairwise check
+ * (status, relationship, reindexRecommendation, and the six numeric metrics) and additionally requires
+ * equal seedNodeCount. Conflicting evidence is never averaged or merged.
+ */
+export function checkAffectedNeighborhoodFourWaySymmetry(assessments) {
+    const reference = assessments["stale-index"];
+    const reasons = [];
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        if (treatmentId === "stale-index")
+            continue;
+        const other = assessments[treatmentId];
+        const pairwise = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(reference, other);
+        if (!pairwise.symmetric)
+            reasons.push(`${treatmentId}: ${pairwise.reason}`);
+        if (reference.seedNodeCount !== other.seedNodeCount) {
+            reasons.push(`${treatmentId}: seedNodeCount (${reference.seedNodeCount} vs ${other.seedNodeCount})`);
+        }
+    }
+    return reasons.length === 0 ? { symmetric: true } : { symmetric: false, reason: `Affected-neighborhood assessments are asymmetric across treatments: ${reasons.join(" | ")}` };
+}
+const PARTIAL_TREATMENT_IDS = ["changed-files-refresh", "affected-neighborhood-refresh"];
+function placeholderComparisons() {
+    return [
+        { kind: "stale-risk", candidateTreatmentId: "stale-index", referenceTreatmentId: "full-refresh", comparison: { ...INCONCLUSIVE_NO_EXECUTION, reasonCodes: [...INCONCLUSIVE_NO_EXECUTION.reasonCodes] } },
+        ...PARTIAL_TREATMENT_IDS.map((candidateTreatmentId) => ({
+            kind: "partial-refresh",
+            candidateTreatmentId,
+            referenceTreatmentId: "full-refresh",
+            refreshRealization: null,
+            correctnessRelation: "unknown",
+            requiredFileEvidenceRelation: "unknown",
+            classification: "inconclusive",
+            reasonCodes: ["correctness-unavailable", "required-file-evidence-unavailable"]
+        }))
+    ];
+}
+function refreshExecutionOf(session, treatmentId) {
+    const treatment = session.treatments[treatmentId];
+    if (treatment.refreshRealization !== null) {
+        const incrementalRefresh = treatment.refreshedIndex.incrementalRefresh;
+        if (!incrementalRefresh) {
+            throw new Error(`${treatmentId} lifecycle reported ${treatment.refreshRealization} without upstream incrementalRefresh evidence.`);
+        }
+        return { kind: "incremental", realization: treatment.refreshRealization, incrementalRefresh: structuredClone(incrementalRefresh) };
+    }
+    return treatment.postMutationIndexBuilt
+        ? { kind: "full", realization: "FULL_REFRESH", incrementalRefresh: null }
+        : { kind: "no-refresh", realization: "NO_REFRESH", incrementalRefresh: null };
+}
+/**
+ * Executes the four matched treatments in fixed order for one lifecycle-ready V2 session, then builds
+ * exactly three comparisons against full-refresh. A lifecycle that is not ready, or an affected-neighborhood
+ * asymmetry, is a failed scenario with no fabricated treatment evidence.
+ */
+export async function executeIncrementalChangeStalenessScenarioV2(options) {
+    const deps = { ...defaultIncrementalChangeStalenessExecutionDeps, ...options.deps };
+    const scenario = options.scenario;
+    if (options.lifecycle.status !== "ready") {
+        return {
+            scenarioId: scenario.id,
+            category: scenario.category,
+            benchmarkProjectId: options.baseCase.benchmarkProjectId,
+            baseCaseId: options.baseCase.caseId,
+            answerPolicy: scenario.answerPolicy,
+            query: null,
+            expectedFiles: [],
+            expectedSymbols: [],
+            status: "failed",
+            failureReason: `${options.lifecycle.failure.code}: ${options.lifecycle.failure.message}`,
+            session: null,
+            treatments: [],
+            referenceComparisons: placeholderComparisons()
+        };
+    }
+    const session = options.lifecycle.session;
+    const { resolved, derivedTask } = await resolveIncrementalChangeStalenessScenarioTask({ repoRoot: options.repoRoot, scenario });
+    const scenarioBase = {
+        scenarioId: scenario.id,
+        category: scenario.category,
+        benchmarkProjectId: scenario.benchmarkProjectId,
+        baseCaseId: scenario.baseCaseId,
+        answerPolicy: scenario.answerPolicy,
+        query: resolved.query,
+        expectedFiles: resolved.expectedFiles,
+        expectedSymbols: resolved.expectedSymbols,
+        session
+    };
+    // Affected-neighborhood evidence is derived from each treatment's ORIGINAL BASELINE change authority.
+    const affected = {};
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        affected[treatmentId] = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments[treatmentId], derivedTask);
+    }
+    const symmetry = checkAffectedNeighborhoodFourWaySymmetry(affected);
+    if (!symmetry.symmetric) {
+        return {
+            ...scenarioBase,
+            status: "failed",
+            failureReason: `AFFECTED_NEIGHBORHOOD_ASYMMETRY: ${symmetry.reason}`,
+            treatments: [],
+            referenceComparisons: placeholderComparisons()
+        };
+    }
+    const retrievalCommandsDir = (treatmentId) => resolveWithinRoot(options.runOwnedRoot, path.join("commands", scenario.id, treatmentId, "retrieval"));
+    const agentOutDir = (treatmentId) => resolveWithinRoot(options.runOwnedRoot, path.join("agents", scenario.id, treatmentId));
+    // Fixed deterministic order, sequential; each treatment retrieves only from its own active index.
+    const treatments = [];
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        const lifecycleTreatment = session.treatments[treatmentId];
+        const evaluation = await executeTreatmentEvaluation({
+            treatmentId,
+            baselineFreshness: lifecycleTreatment.changeAuthority.postMutationBaselineFreshness,
+            activeIndexPhase: lifecycleTreatment.activeRetrieval.role,
+            activeIndexDir: lifecycleTreatment.activeRetrieval.index.indexDir,
+            derivedTask,
+            affectedNeighborhood: affected[treatmentId],
+            requiredFiles: resolved.expectedFiles,
+            kitCommand: session.kitCommand,
+            retrievalCommandsDir: retrievalCommandsDir(treatmentId),
+            agentOutDir: agentOutDir(treatmentId),
+            projectProfiles: options.projectProfiles,
+            cwd: options.cwd,
+            env: options.env,
+            deps
+        });
+        treatments.push({
+            ...evaluation,
+            treatmentIntent: INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatmentId],
+            refreshedFreshness: lifecycleTreatment.refreshedFreshness,
+            refreshExecution: refreshExecutionOf(session, treatmentId)
+        });
+    }
+    return {
+        ...scenarioBase,
+        status: "ready",
+        failureReason: null,
+        treatments,
+        referenceComparisons: buildReferenceComparisons(treatments)
+    };
+}
+/** Exactly three comparisons against full-refresh: stale-index, changed-files-refresh, affected-neighborhood-refresh. */
+export function buildReferenceComparisons(treatments) {
+    const byId = new Map(treatments.map((treatment) => [treatment.treatmentId, treatment]));
+    const reference = byId.get("full-refresh");
+    const stale = byId.get("stale-index");
+    if (!reference || !stale)
+        throw new Error("Reference comparisons require the stale-index and full-refresh treatment executions.");
+    // Historical v0.6.2 semantics, unchanged.
+    const staleCorrectness = compareCorrectness(correctnessComparable(stale.fakeAgent), correctnessComparable(reference.fakeAgent));
+    const staleRequired = compareRequiredFileEvidence(stale.requiredFileEvidence, reference.requiredFileEvidence);
+    const staleRisk = classifyStaleRisk(staleCorrectness, staleRequired);
+    const comparisons = [
+        {
+            kind: "stale-risk",
+            candidateTreatmentId: "stale-index",
+            referenceTreatmentId: "full-refresh",
+            comparison: {
+                correctnessRelation: staleCorrectness,
+                requiredFileEvidenceRelation: staleRequired,
+                staleRiskClassification: staleRisk.staleRiskClassification,
+                reasonCodes: staleRisk.reasonCodes
+            }
+        }
+    ];
+    for (const candidateTreatmentId of PARTIAL_TREATMENT_IDS) {
+        const candidate = byId.get(candidateTreatmentId);
+        if (!candidate || candidate.refreshExecution.kind !== "incremental") {
+            throw new Error(`${candidateTreatmentId} has no incremental refresh execution to compare.`);
+        }
+        const correctnessRelation = compareCandidateCorrectness(correctnessComparable(candidate.fakeAgent), correctnessComparable(reference.fakeAgent));
+        const requiredFileEvidenceRelation = compareCandidateRequiredFileEvidence(candidate.requiredFileEvidence, reference.requiredFileEvidence);
+        const classified = classifyPartialRefreshAgainstFull({
+            realization: candidate.refreshExecution.realization,
+            correctnessRelation,
+            requiredFileEvidenceRelation
+        });
+        comparisons.push({
+            kind: "partial-refresh",
+            candidateTreatmentId,
+            referenceTreatmentId: "full-refresh",
+            refreshRealization: candidate.refreshExecution.realization,
+            correctnessRelation,
+            requiredFileEvidenceRelation,
+            classification: classified.classification,
+            reasonCodes: classified.reasonCodes
+        });
+    }
+    return comparisons;
+}

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

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { cp, lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+/**
+ * Narrow v0.6.3 lifecycle-preparation helper: copies one already-produced my-dev-kit index
+ * directory byte-for-byte to a new sibling directory so an upstream incremental refresh can run
+ * in place against the copy while the original baseline stays immutable change authority.
+ *
+ * Both paths must resolve inside `runOwnedRoot` (textually and, for the destination parent, by
+ * real path), the destination must not exist, symlinks in the source are refused, and the copy
+ * is verified file-for-file by SHA-256. Index contents are never edited. Any failure throws.
+ */
+export async function cloneIncrementalChangeStalenessIndexDirectory(runOwnedRoot, sourceDir, destinationDir) {
+    const root = path.resolve(runOwnedRoot);
+    const source = resolveWithinRoot(root, path.resolve(sourceDir));
+    const destination = resolveWithinRoot(root, path.resolve(destinationDir));
+    if (!existsSync(source)) {
+        throw new Error(`Index clone source does not exist: ${source}.`);
+    }
+    if (existsSync(destination)) {
+        throw new Error(`Index clone destination already exists; refusing to overwrite: ${destination}.`);
+    }
+    const relativeToSource = path.relative(source, destination);
+    if (relativeToSource === "" || (!relativeToSource.startsWith("..") && !path.isAbsolute(relativeToSource))) {
+        throw new Error(`Index clone destination ${destination} must not be inside the source ${source}.`);
+    }
+    const sourceFiles = await listRegularFiles(source);
+    // The destination parent must be real-path contained by the real run-owned root (no symlink escape).
+    const parent = path.dirname(destination);
+    await mkdir(parent, { recursive: true });
+    const [realParent, realRoot] = await Promise.all([realpath(parent), realpath(root)]);
+    const parentRelative = path.relative(realRoot, realParent);
+    if (parentRelative === ".." || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
+        throw new Error(`Index clone destination parent escapes the run-owned root via a symbolic link: ${parent}.`);
+    }
+    await cp(source, destination, { recursive: true, errorOnExist: true, force: false, dereference: false });
+    const copiedFiles = await listRegularFiles(destination);
+    if (copiedFiles.length !== sourceFiles.length || copiedFiles.some((file, index) => file !== sourceFiles[index])) {
+        throw new Error(`Index clone is incomplete: ${destination} does not contain exactly the files of ${source}.`);
+    }
+    for (const file of sourceFiles) {
+        const [left, right] = await Promise.all([sha256(path.join(source, file)), sha256(path.join(destination, file))]);
+        if (left !== right) {
+            throw new Error(`Index clone content differs for ${file}.`);
+        }
+    }
+}
+async function sha256(filePath) {
+    return createHash("sha256").update(await readFile(filePath)).digest("hex");
+}
+/** Sorted POSIX-relative regular files; refuses symlinks and other non-regular entries. */
+async function listRegularFiles(root) {
+    const files = [];
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            const stat = await lstat(full);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Index directory contains a symbolic link, which is not copied: ${full}.`);
+            }
+            if (stat.isDirectory()) {
+                await walk(full);
+            }
+            else if (stat.isFile()) {
+                files.push(path.relative(root, full).replace(/\\/g, "/"));
+            }
+            else {
+                throw new Error(`Index directory contains a non-regular entry: ${full}.`);
+            }
+        }
+    }
+    await walk(root);
+    return files.sort();
+}

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

@@ -24,17 +24,69 @@ export function incrementalChangeStalenessIndexDir(runOwnedRoot, scenarioId, tre
 export function incrementalChangeStalenessCommandsDir(runOwnedRoot, scenarioId, treatmentId, role) {
     return resolveWithinRoot(path.resolve(runOwnedRoot), path.join("commands", scenarioId, treatmentId, role));
 }
-class LifecycleFailure extends Error {
+export class LifecycleFailure extends Error {
     failure;
     constructor(failure) {
         super(failure.message);
         this.failure = failure;
     }
 }
-function fail(failure) {
+export function fail(failure) {
     if (failure)
         throw new LifecycleFailure(failure);
 }
+/**
+ * Shared by the v0.6.2 and v0.6.3 lifecycles: runs the index through the established warm-index
+ * session owner (index -> version probe -> snapshot -> graph), then proves target/index identity.
+ * `mode` defaults to an ordinary full build. The index directory must be absent unless
+ * `existingIndexDir` is set (an in-place refresh of an already-cloned baseline).
+ */
+export async function prepareTreatmentIndexEvidence(params) {
+    const { deps, target, role, indexDir, sourceRoots } = params;
+    const treatmentId = target.treatmentId;
+    if (params.existingIndexDir ? !existsSync(indexDir) : existsSync(indexDir)) {
+        fail({
+            code: "index-directory-collision",
+            message: params.existingIndexDir
+                ? `Expected an existing cloned ${treatmentId} ${role} index directory: ${indexDir}.`
+                : `Refusing to overwrite existing ${treatmentId} ${role} index directory: ${indexDir}.`,
+            treatmentId
+        });
+    }
+    const commandsDir = incrementalChangeStalenessCommandsDir(params.runOwnedRoot, params.scenarioId, treatmentId, role);
+    const prepared = await deps.prepareIndexSession({
+        target: { absoluteTargetRoot: target.targetRoot, sourceRoots: [...sourceRoots] },
+        kitCommand: params.kitCommand,
+        indexDir,
+        commandsDir,
+        requireKit: false,
+        ...(params.mode ? { mode: params.mode } : {})
+    });
+    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");
+    }
+    params.onIndexPrepared?.();
+    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 }));
+    return { evidence, build: prepared.build };
+}
 /**
  * Owns the matched Batch 3 lifecycle for ONE frozen scenario:
  *
@@ -73,40 +125,20 @@ export async function prepareIncrementalChangeStalenessScenarioLifecycle(options
         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] },
+        const { evidence } = await prepareTreatmentIndexEvidence({
+            deps,
+            runOwnedRoot,
+            scenarioId: scenario.id,
             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({
+            sourceRoots,
+            target,
             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
+            indexDir,
+            // prepareIndexSession resolves only after the index command, snapshot capture, and graph
+            // loading have all completed, in that order.
+            onIndexPrepared: () => events.push(`${treatmentId}:${role}-index-built`, `${treatmentId}:${role}-snapshot-captured`, `${treatmentId}:${role}-graph-loaded`)
         });
-        fail(evaluateIndexEvidence(evidence, { targetRoot: target.targetRoot, sourceRoots, indexDir }));
         events.push(`${treatmentId}:${role}-identity-verified`);
         return evidence;
     }

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

@@ -130,7 +130,7 @@ export function evaluateBaselineStaleFreshness(assessment, controlledChangedPath
  * baseline freshness change evidence must agree path-for-path, including
  * baseline and current content identity.
  */
-export function evaluateChangedPathSymmetry(stale, fullRefresh) {
+export function evaluateChangedPathSymmetry(stale, fullRefresh, labels = { reference: "stale-index", other: "full-refresh" }) {
     const key = (assessment) => assessment.changes
         .map((change) => `${normalizeRelativePath(change.path)}\t${change.changeType}\t${change.baselineSha256}\t${change.currentSha256 ?? "null"}`)
         .sort();
@@ -138,15 +138,17 @@ export function evaluateChangedPathSymmetry(stale, fullRefresh) {
     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 failure("treatment-changed-paths-conflict", `${labels.reference} and ${labels.other} baseline freshness disagree about the controlled change: ${labels.reference}=[${left.join("; ")}] ${labels.other}=[${right.join("; ")}].`, null);
     }
     return null;
 }
 /** The refreshed index must be proven complete `fresh` against the unchanged mutated target. */
-export function evaluateRefreshedFreshness(assessment) {
+export function evaluateRefreshedFreshness(assessment, treatmentId = "full-refresh") {
     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 failure("refreshed-freshness-not-fresh", `${treatmentId} refreshed index freshness is ${assessment.status} (snapshot ${assessment.baselineSnapshotStatus}, ${assessment.changedFileCount} changed, ${assessment.missingFileCount} missing, ${assessment.unresolvedFileCount} unresolved); complete fresh is required.`, treatmentId);
     }
     return null;
 }
+/** Shared failure constructor for the v0.6.3 lifecycle policy module. */
+export { failure as lifecycleFailure };

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

@@ -0,0 +1,78 @@
+import { lifecycleFailure } from "./lifecyclePolicy.js";
+/** Pure v0.6.3 four-treatment lifecycle policy; inspects already-produced evidence only. */
+/**
+ * v0.6.3: every treatment baseline is bootstrapped with `--incremental --refresh-scope changed-files`
+ * against a brand-new index directory. Upstream must truthfully report the expected bootstrap full
+ * fallback (`cache-missing`); this is bootstrap evidence, never an experimental partial-refresh fallback.
+ */
+export function evaluateBaselineBootstrapEvidence(build, treatmentId) {
+    const evidence = build.incrementalRefresh;
+    const label = `${treatmentId} baseline bootstrap`;
+    if (build.mode.kind !== "incremental" || build.mode.refreshScope !== "changed-files") {
+        return lifecycleFailure("baseline-bootstrap-contract-mismatch", `${label} was not requested as incremental changed-files.`, treatmentId);
+    }
+    if (!evidence) {
+        return lifecycleFailure("baseline-bootstrap-contract-mismatch", `${label} returned no incrementalRefresh evidence.`, treatmentId);
+    }
+    if (evidence.requestedScope !== "changed-files" ||
+        evidence.appliedScope !== "full" ||
+        evidence.selectionStatus !== "fallback-full" ||
+        evidence.fallbackReason !== "cache-missing") {
+        return lifecycleFailure("baseline-bootstrap-contract-mismatch", `${label} expected requested=changed-files applied=full status=fallback-full reason=cache-missing but observed requested=${evidence.requestedScope} applied=${evidence.appliedScope} status=${evidence.selectionStatus} reason=${evidence.fallbackReason}.`, treatmentId);
+    }
+    return null;
+}
+/**
+ * v0.6.3: classifies a post-mutation partial-refresh build. A truthful `fallback-full` is a valid
+ * realization (FALLBACK_FULL), never collapsed to APPLIED_PARTIAL. `not-needed` after an already
+ * proven controlled mutation contradicts that mutation and fails the lifecycle. Missing or invalid
+ * evidence fails too.
+ */
+export function evaluatePartialRefreshRealization(build, requestedScope, treatmentId) {
+    const evidence = build.incrementalRefresh;
+    if (build.mode.kind !== "incremental" || build.mode.refreshScope !== requestedScope || !evidence || evidence.requestedScope !== requestedScope) {
+        return {
+            failure: lifecycleFailure("refresh-evidence-invalid", `${treatmentId} refresh did not carry valid ${requestedScope} incrementalRefresh evidence.`, treatmentId),
+            realization: null
+        };
+    }
+    if (evidence.selectionStatus === "not-needed" || evidence.appliedScope === "none") {
+        return {
+            failure: lifecycleFailure("refresh-not-needed-after-mutation", `${treatmentId} refresh reported not-needed (applied=${evidence.appliedScope}) although the controlled mutation was already proven.`, treatmentId),
+            realization: null
+        };
+    }
+    if (evidence.selectionStatus === "applied" && evidence.appliedScope === requestedScope) {
+        return { failure: null, realization: "APPLIED_PARTIAL" };
+    }
+    if (evidence.selectionStatus === "fallback-full" && evidence.appliedScope === "full") {
+        return { failure: null, realization: "FALLBACK_FULL" };
+    }
+    return {
+        failure: lifecycleFailure("refresh-evidence-invalid", `${treatmentId} refresh reported an unclassifiable outcome (status=${evidence.selectionStatus}, applied=${evidence.appliedScope}).`, treatmentId),
+        realization: null
+    };
+}
+/** v0.6.3 per-scenario counts: 7 index invocations and 7 freshness assessments. */
+export const INCREMENTAL_CHANGE_STALENESS_V2_EXPECTED_INDEX_INVOCATIONS = {
+    "stale-index": 1,
+    "changed-files-refresh": 2,
+    "affected-neighborhood-refresh": 2,
+    "full-refresh": 2
+};
+export const INCREMENTAL_CHANGE_STALENESS_V2_EXPECTED_FRESHNESS_ASSESSMENTS = {
+    "stale-index": 1,
+    "changed-files-refresh": 2,
+    "affected-neighborhood-refresh": 2,
+    "full-refresh": 2
+};
+export function evaluateV2InvocationCounts(indexInvocationCounts, freshnessAssessmentCounts) {
+    for (const treatmentId of Object.keys(INCREMENTAL_CHANGE_STALENESS_V2_EXPECTED_INDEX_INVOCATIONS)) {
+        const expectedIndex = INCREMENTAL_CHANGE_STALENESS_V2_EXPECTED_INDEX_INVOCATIONS[treatmentId];
+        const expectedFreshness = INCREMENTAL_CHANGE_STALENESS_V2_EXPECTED_FRESHNESS_ASSESSMENTS[treatmentId];
+        if (indexInvocationCounts[treatmentId] !== expectedIndex || freshnessAssessmentCounts[treatmentId] !== expectedFreshness) {
+            return lifecycleFailure("invocation-count-mismatch", `${treatmentId} performed ${indexInvocationCounts[treatmentId]} index invocation(s) and ${freshnessAssessmentCounts[treatmentId]} freshness assessment(s); expected ${expectedIndex} and ${expectedFreshness}.`, treatmentId);
+        }
+    }
+    return null;
+}