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

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

@@ -0,0 +1,49 @@
+import { compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+function neutral(relation) {
+    if (relation === "stale-worse")
+        return "candidate-worse";
+    if (relation === "stale-better")
+        return "candidate-better";
+    return relation;
+}
+/** Same rules as the v0.6.2 correctness comparison, candidate vs reference. */
+export function compareCandidateCorrectness(candidate, reference) {
+    return neutral(compareCorrectness(candidate, reference));
+}
+/** Same rules as the v0.6.2 required-file comparison, candidate vs reference. */
+export function compareCandidateRequiredFileEvidence(candidate, reference) {
+    return neutral(compareRequiredFileEvidence(candidate, reference));
+}
+/**
+ * Frozen precedence. Rule 0 (realization gate) first: a full fallback is never evidence about
+ * partial-refresh performance. Then observed regression (either dimension worse), then inconclusive
+ * (a dimension unknown), then no observed regression (including candidate-better, which is not a
+ * winner claim). affected-neighborhood evidence and reindexRecommendation are never inputs.
+ */
+export function classifyPartialRefreshAgainstFull(args) {
+    const { realization, correctnessRelation, requiredFileEvidenceRelation } = args;
+    // RULE 0 -- realization gate.
+    if (realization === "FALLBACK_FULL") {
+        return { classification: "not-comparable-as-partial-refresh", reasonCodes: ["candidate-fell-back-to-full"] };
+    }
+    // RULE 1 -- observed regression wins even if the other dimension is unknown.
+    if (correctnessRelation === "candidate-worse" || requiredFileEvidenceRelation === "candidate-worse") {
+        const reasonCodes = [];
+        if (correctnessRelation === "candidate-worse")
+            reasonCodes.push("candidate-correctness-lower");
+        if (requiredFileEvidenceRelation === "candidate-worse")
+            reasonCodes.push("candidate-missing-required-file");
+        return { classification: "observed-regression-relative-to-full", reasonCodes };
+    }
+    // RULE 2 -- inconclusive.
+    if (correctnessRelation === "unknown" || requiredFileEvidenceRelation === "unknown") {
+        const reasonCodes = [];
+        if (correctnessRelation === "unknown")
+            reasonCodes.push("correctness-unavailable");
+        if (requiredFileEvidenceRelation === "unknown")
+            reasonCodes.push("required-file-evidence-unavailable");
+        return { classification: "inconclusive", reasonCodes };
+    }
+    // RULE 3 -- no observed regression.
+    return { classification: "no-observed-regression-relative-to-full", reasonCodes: ["no-reference-regression-observed"] };
+}

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

@@ -1,10 +1,11 @@
 import { invalidExperimentConfig, isPlainObject, mergeConfig, validExperimentConfig } from "../../config.js";
 import { FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS } from "./scenarioTypes.js";
 /**
- * The frozen v0.6.2 compatibility baseline for the upstream tool. Every index
- * of one matched scenario must come from this one configured command.
+ * The upstream tool version the four-treatment experiment expects: 1.12.5 is the first published
+ * my-dev-kit that exposes the incremental refresh-scope options. Every index of one matched scenario
+ * must come from this one configured command.
  */
-export const INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND = "npx @dailephd/my-dev-kit@1.12.4";
+export const INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND = "npx @dailephd/my-dev-kit@1.12.5";
 export const defaultIncrementalChangeStalenessConfig = {
     outDir: "lab-output/incremental-change-staleness",
     kitCommand: INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND
@@ -17,7 +18,7 @@ export const incrementalChangeStalenessConfigDefinition = {
         {
             name: "caseIds",
             type: "array",
-            description: `Frozen scenario ids to include (${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}); defaults to all. Both stale-index and full-refresh always run for each selected scenario.`
+            description: `Frozen scenario ids to include (${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}); defaults to all. All four treatments run for each selected scenario: stale-index, changed-files-refresh, affected-neighborhood-refresh, and full-refresh.`
         }
     ]
 };

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

@@ -8,6 +8,24 @@ import { resolveWithinRoot } from "../../../core/pathSafety.js";
  * target copies; it never builds a treatment index or runs retrieval.
  */
 export const INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS = ["stale-index", "full-refresh"];
+/**
+ * The four v0.6.3 internal lifecycle treatment identities in their fixed order
+ * (never alphabetical). The released v0.6.2 public constant above is unchanged;
+ * this set is used only by the internal v0.6.3 lifecycle.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS = [
+    "stale-index",
+    "changed-files-refresh",
+    "affected-neighborhood-refresh",
+    "full-refresh"
+];
+/** Treatment ID and treatment intent are separate runtime evidence. */
+export const INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS = {
+    "stale-index": "my-dev-kit-no-refresh",
+    "changed-files-refresh": "my-dev-kit-changed-files-refresh",
+    "affected-neighborhood-refresh": "my-dev-kit-affected-neighborhood-refresh",
+    "full-refresh": "my-dev-kit-full-refresh"
+};
 /**
  * Default project-relative, gitignored runtime location for disposable
  * treatment targets. Callers may pass a different `runRoot`, but it must
@@ -38,8 +56,8 @@ function assertDisposableRootDoesNotOverlapCanonical(targetRoot, canonicalProjec
  */
 export async function createDisposableTreatmentTarget(options) {
     const { repoRoot, scenarioId, treatmentId, benchmarkProjectId, canonicalProjectRootRelative } = options;
-    if (!INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.includes(treatmentId)) {
-        throw new Error(`Unknown treatment id: ${treatmentId}. Expected one of ${INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.join(", ")}.`);
+    if (!INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS.includes(treatmentId)) {
+        throw new Error(`Unknown treatment id: ${treatmentId}. Expected one of ${INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS.join(", ")}.`);
     }
     if (typeof scenarioId !== "string" || scenarioId.length === 0) {
         throw new Error("scenarioId must be a nonempty string.");

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

@@ -224,13 +224,13 @@ export async function runIncrementalChangeStalenessFakeAgent(args) {
         };
     }
 }
-function correctnessComparable(fakeAgent) {
+export function correctnessComparable(fakeAgent) {
     if (!fakeAgent || !fakeAgent.correctness.available || fakeAgent.correctness.score === null) {
         return { available: false };
     }
     return { available: true, score: fakeAgent.correctness.score };
 }
-const INCONCLUSIVE_NO_EXECUTION = {
+export const INCONCLUSIVE_NO_EXECUTION = {
     correctnessRelation: "unknown",
     requiredFileEvidenceRelation: "unknown",
     staleRiskClassification: "inconclusive",
@@ -240,10 +240,12 @@ export const defaultIncrementalChangeStalenessExecutionDeps = {
     runRetrieval: runIncrementalChangeStalenessTreatmentRetrieval,
     runFakeAgent: runIncrementalChangeStalenessFakeAgent
 };
-async function executeOneTreatment(args) {
-    const treatment = args.session.treatments[args.treatmentId];
-    const baselineFreshness = treatment.changeAuthority.postMutationBaselineFreshness;
-    const activeIndexPhase = treatment.activeRetrieval.role;
+/**
+ * Retrieval + deterministic fake-agent + required-file evidence for ONE treatment against its own active
+ * index. Shared by the v0.6.2 two-treatment path and the v0.6.3 four-treatment path; takes only the
+ * lifecycle-provided facts it needs so it never reaches into another treatment's state.
+ */
+export async function executeTreatmentEvaluation(args) {
     let retrieval = null;
     let retrievalStatus = "not-run";
     let failureReason = null;
@@ -251,7 +253,7 @@ async function executeOneTreatment(args) {
         retrieval = await args.deps.runRetrieval({
             derivedTask: args.derivedTask,
             kitCommand: args.kitCommand,
-            indexDir: treatment.activeRetrieval.index.indexDir,
+            indexDir: args.activeIndexDir,
             commandsDir: args.retrievalCommandsDir
         });
         retrievalStatus = classifyIncrementalChangeStalenessRetrieval(retrieval);
@@ -284,8 +286,8 @@ async function executeOneTreatment(args) {
         treatmentId: args.treatmentId,
         status,
         failureReason,
-        activeIndexPhase,
-        baselineFreshness,
+        activeIndexPhase: args.activeIndexPhase,
+        baselineFreshness: args.baselineFreshness,
         affectedNeighborhood: args.affectedNeighborhood,
         retrieval,
         retrievalStatus,
@@ -293,6 +295,36 @@ async function executeOneTreatment(args) {
         requiredFileEvidence
     };
 }
+async function executeOneTreatment(args) {
+    const treatment = args.session.treatments[args.treatmentId];
+    return executeTreatmentEvaluation({
+        treatmentId: args.treatmentId,
+        baselineFreshness: treatment.changeAuthority.postMutationBaselineFreshness,
+        activeIndexPhase: treatment.activeRetrieval.role,
+        activeIndexDir: treatment.activeRetrieval.index.indexDir,
+        derivedTask: args.derivedTask,
+        affectedNeighborhood: args.affectedNeighborhood,
+        requiredFiles: args.requiredFiles,
+        kitCommand: args.kitCommand,
+        retrievalCommandsDir: args.retrievalCommandsDir,
+        agentOutDir: args.agentOutDir,
+        projectProfiles: args.projectProfiles,
+        cwd: args.cwd,
+        env: args.env,
+        deps: args.deps
+    });
+}
+/** Resolves the scenario's query/answer and derives the one in-memory task shared by every matched treatment. */
+export async function resolveIncrementalChangeStalenessScenarioTask(options) {
+    const { scenario } = options;
+    const resolved = await resolveIncrementalChangeStalenessQueryAndAnswer({ scenario, repoRoot: options.repoRoot });
+    const cases = await readEvaluationCases(path.resolve(options.repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), options.repoRoot);
+    const baseEvaluationCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
+    if (!baseEvaluationCase) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for task-descriptor construction.`);
+    }
+    return { resolved, derivedTask: buildIncrementalChangeStalenessDerivedTask({ scenario, baseEvaluationCase, resolved }) };
+}
 /**
  * Executes the frozen Batch 4 order (section 36) for one ready lifecycle session: resolve query and
  * answer, derive the task descriptor, assess both treatments' affected neighborhoods from BASELINE
@@ -323,13 +355,7 @@ export async function executeIncrementalChangeStalenessScenario(options) {
         };
     }
     const session = options.lifecycle.session;
-    const resolved = await resolveIncrementalChangeStalenessQueryAndAnswer({ scenario, repoRoot: options.repoRoot });
-    const cases = await readEvaluationCases(path.resolve(options.repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), options.repoRoot);
-    const baseEvaluationCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
-    if (!baseEvaluationCase) {
-        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for task-descriptor construction.`);
-    }
-    const derivedTask = buildIncrementalChangeStalenessDerivedTask({ scenario, baseEvaluationCase, resolved });
+    const { resolved, derivedTask } = await resolveIncrementalChangeStalenessScenarioTask({ repoRoot: options.repoRoot, scenario });
     const staleAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["stale-index"], derivedTask);
     const fullAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["full-refresh"], derivedTask);
     const symmetry = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(staleAffected, fullAffected);

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

@@ -9,7 +9,7 @@ import { resolveWithinRoot } from "../../../core/pathSafety.js";
 // ---------------------------------------------------------------------------
 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) {
+export function sortedUnique(values) {
     return [...new Set(values)].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
 }
 function summarizeCommand(command) {
@@ -24,7 +24,7 @@ function summarizeCommand(command) {
         error: command.error ?? null
     };
 }
-function summarizeRetrieval(treatment) {
+export function summarizeRetrieval(treatment) {
     const retrieval = treatment.retrieval;
     if (!retrieval) {
         return {
@@ -56,7 +56,7 @@ function summarizeRetrieval(treatment) {
         commands: retrieval.commands.map(summarizeCommand)
     };
 }
-function summarizeFakeAgent(treatment) {
+export function summarizeFakeAgent(treatment) {
     if (!treatment.fakeAgent)
         return null;
     const agent = treatment.fakeAgent;
@@ -69,7 +69,7 @@ function summarizeFakeAgent(treatment) {
         errors: [...agent.errors]
     };
 }
-function summarizeRequiredFileEvidence(evidence) {
+export function summarizeRequiredFileEvidence(evidence) {
     return {
         status: evidence.status,
         requiredFiles: sortedUnique(evidence.requiredFiles),

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

@@ -0,0 +1,289 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { classifyStaleRisk } from "./comparison.js";
+import { classifyPartialRefreshAgainstFull } from "./comparisonV2.js";
+import { INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE, INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION, sortedUnique, summarizeFakeAgent, summarizeRequiredFileEvidence, summarizeRetrieval } from "./executionArtifact.js";
+// ---------------------------------------------------------------------------
+// v0.6.3 Batch 3 -- persisted four-treatment execution artifact. A distinct schema from V1 written to the
+// same canonical filename; the schemaVersion is the discriminator. Bounded structured evidence only:
+// never raw retrieved context bodies, graph artifacts, or file contents. Descriptive counts, no ranking.
+// ---------------------------------------------------------------------------
+export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2 = "my-dev-kit-lab-incremental-change-staleness-execution-v2";
+const PARTIAL_IDS = ["changed-files-refresh", "affected-neighborhood-refresh"];
+const REQUESTED_SCOPE = {
+    "changed-files-refresh": "changed-files",
+    "affected-neighborhood-refresh": "affected-neighborhood"
+};
+const COMPARISON_CANDIDATE_ORDER = ["stale-index", "changed-files-refresh", "affected-neighborhood-refresh"];
+function record(build) {
+    return Object.fromEntries(INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS.map((id) => [id, build(id)]));
+}
+function summarizeTreatmentV2(treatment) {
+    return {
+        treatmentId: treatment.treatmentId,
+        treatmentIntent: treatment.treatmentIntent,
+        status: treatment.status,
+        failureReason: treatment.failureReason,
+        activeIndexPhase: treatment.activeIndexPhase,
+        baselineFreshness: structuredClone(treatment.baselineFreshness),
+        refreshedFreshness: treatment.refreshedFreshness ? structuredClone(treatment.refreshedFreshness) : null,
+        refreshExecution: structuredClone(treatment.refreshExecution),
+        affectedNeighborhood: structuredClone(treatment.affectedNeighborhood),
+        // Bounded status/telemetry only; never embeds retrieval.contextText.
+        retrieval: summarizeRetrieval(treatment),
+        fakeAgent: summarizeFakeAgent(treatment),
+        requiredFileEvidence: summarizeRequiredFileEvidence(treatment.requiredFileEvidence)
+    };
+}
+function summarizeLifecycleV2(execution) {
+    const session = execution.session;
+    if (!session)
+        return null;
+    const refreshedStatus = {};
+    for (const id of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        const freshness = session.treatments[id].refreshedFreshness;
+        if (freshness)
+            refreshedStatus[id] = freshness.status;
+    }
+    return {
+        controlledFilePaths: [...session.controlledChangedPaths],
+        treatmentIntents: record((id) => INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[id]),
+        preMutationEquivalence: {
+            "changed-files-refresh": session.preMutationEquivalence["changed-files-refresh"].result,
+            "affected-neighborhood-refresh": session.preMutationEquivalence["affected-neighborhood-refresh"].result,
+            "full-refresh": session.preMutationEquivalence["full-refresh"].result
+        },
+        postMutationEquivalence: {
+            "changed-files-refresh": session.postMutationEquivalence["changed-files-refresh"].result,
+            "affected-neighborhood-refresh": session.postMutationEquivalence["affected-neighborhood-refresh"].result,
+            "full-refresh": session.postMutationEquivalence["full-refresh"].result
+        },
+        baselineFreshnessStatus: record((id) => session.treatments[id].changeAuthority.postMutationBaselineFreshness.status),
+        refreshedFreshnessStatus: refreshedStatus,
+        partialRealization: {
+            "changed-files-refresh": session.treatments["changed-files-refresh"].refreshRealization,
+            "affected-neighborhood-refresh": session.treatments["affected-neighborhood-refresh"].refreshRealization
+        },
+        indexInvocationCounts: record((id) => session.treatments[id].indexInvocationCount),
+        freshnessAssessmentCounts: record((id) => session.treatments[id].freshnessAssessmentCount),
+        totalIndexInvocationCount: session.totalIndexInvocationCount,
+        totalFreshnessAssessmentCount: session.totalFreshnessAssessmentCount,
+        myDevKitVersion: session.toolIdentity.version ?? null,
+        sourceRoots: [...session.baseCase.sourceRoots]
+    };
+}
+function summarizeScenarioV2(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: summarizeLifecycleV2(execution),
+        treatments: execution.treatments.map(summarizeTreatmentV2),
+        referenceComparisons: structuredClone(execution.referenceComparisons)
+    };
+}
+function partialComparison(scenario, candidate) {
+    const found = scenario.referenceComparisons.find((comparison) => comparison.candidateTreatmentId === candidate);
+    return found && found.kind === "partial-refresh" ? found : null;
+}
+function countPartial(scenarios, candidate, classification) {
+    return scenarios.filter((scenario) => partialComparison(scenario, candidate)?.classification === classification).length;
+}
+function countRealization(scenarios, candidate, realization) {
+    return scenarios.filter((scenario) => scenario.treatments.find((treatment) => treatment.treatmentId === candidate)?.refreshExecution.realization === realization).length;
+}
+function summarizeV2(scenarios) {
+    const staleClass = (scenario) => {
+        const stale = scenario.referenceComparisons.find((comparison) => comparison.candidateTreatmentId === "stale-index");
+        return stale && stale.kind === "stale-risk" ? stale.comparison.staleRiskClassification : null;
+    };
+    return {
+        scenarioCount: scenarios.length,
+        readyScenarioCount: scenarios.filter((scenario) => scenario.status === "ready").length,
+        failedScenarioCount: scenarios.filter((scenario) => scenario.status === "failed").length,
+        staleObservedRegressionCount: scenarios.filter((scenario) => staleClass(scenario) === "observed-stale-regression").length,
+        staleNoObservedRegressionCount: scenarios.filter((scenario) => staleClass(scenario) === "no-observed-stale-regression").length,
+        staleInconclusiveCount: scenarios.filter((scenario) => staleClass(scenario) === "inconclusive").length,
+        changedFilesAppliedPartialCount: countRealization(scenarios, "changed-files-refresh", "APPLIED_PARTIAL"),
+        changedFilesFallbackFullCount: countRealization(scenarios, "changed-files-refresh", "FALLBACK_FULL"),
+        affectedNeighborhoodAppliedPartialCount: countRealization(scenarios, "affected-neighborhood-refresh", "APPLIED_PARTIAL"),
+        affectedNeighborhoodFallbackFullCount: countRealization(scenarios, "affected-neighborhood-refresh", "FALLBACK_FULL"),
+        changedFilesObservedRegressionRelativeToFullCount: countPartial(scenarios, "changed-files-refresh", "observed-regression-relative-to-full"),
+        changedFilesNoObservedRegressionRelativeToFullCount: countPartial(scenarios, "changed-files-refresh", "no-observed-regression-relative-to-full"),
+        changedFilesInconclusiveCount: countPartial(scenarios, "changed-files-refresh", "inconclusive"),
+        changedFilesNotComparableCount: countPartial(scenarios, "changed-files-refresh", "not-comparable-as-partial-refresh"),
+        affectedNeighborhoodObservedRegressionRelativeToFullCount: countPartial(scenarios, "affected-neighborhood-refresh", "observed-regression-relative-to-full"),
+        affectedNeighborhoodNoObservedRegressionRelativeToFullCount: countPartial(scenarios, "affected-neighborhood-refresh", "no-observed-regression-relative-to-full"),
+        affectedNeighborhoodInconclusiveCount: countPartial(scenarios, "affected-neighborhood-refresh", "inconclusive"),
+        affectedNeighborhoodNotComparableCount: countPartial(scenarios, "affected-neighborhood-refresh", "not-comparable-as-partial-refresh")
+    };
+}
+function contradiction(scenarioId, message) {
+    throw new Error(`Contradictory v2 execution evidence for scenario ${scenarioId}: ${message}`);
+}
+function sameList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * Rejects internally contradictory evidence; called before anything is built or written. Unavailable/null
+ * evidence is preserved, never coerced.
+ */
+export function validateIncrementalChangeStalenessScenarioRecordV2(scenario) {
+    const id = scenario.scenarioId;
+    // Comparisons: exactly three, fixed order, explicit identities, reference is full-refresh, never full vs full.
+    if (!sameList(scenario.referenceComparisons.map((comparison) => comparison.candidateTreatmentId), COMPARISON_CANDIDATE_ORDER)) {
+        contradiction(id, "reference comparisons must be exactly stale-index, changed-files-refresh, affected-neighborhood-refresh in order.");
+    }
+    for (const comparison of scenario.referenceComparisons) {
+        if (comparison.referenceTreatmentId !== "full-refresh")
+            contradiction(id, `${comparison.candidateTreatmentId} comparison references ${comparison.referenceTreatmentId}, not full-refresh.`);
+        if ((comparison.candidateTreatmentId === "stale-index") !== (comparison.kind === "stale-risk")) {
+            contradiction(id, `${comparison.candidateTreatmentId} comparison uses the wrong comparison kind (${comparison.kind}).`);
+        }
+    }
+    // Stale comparison must use the unchanged stale-risk semantics.
+    const stale = scenario.referenceComparisons[0];
+    if (stale.kind === "stale-risk") {
+        const expected = classifyStaleRisk(stale.comparison.correctnessRelation, stale.comparison.requiredFileEvidenceRelation);
+        if (expected.staleRiskClassification !== stale.comparison.staleRiskClassification || !sameList(expected.reasonCodes, stale.comparison.reasonCodes)) {
+            contradiction(id, "stale-index comparison does not follow the stale-risk classification rules.");
+        }
+    }
+    // Treatment collection.
+    if (scenario.treatments.length === 0) {
+        if (scenario.status === "ready")
+            contradiction(id, "a ready scenario must carry four treatment records.");
+        for (const comparison of scenario.referenceComparisons) {
+            if (comparison.kind === "partial-refresh" && comparison.refreshRealization !== null) {
+                contradiction(id, `${comparison.candidateTreatmentId} carries a refresh realization although no treatment executed.`);
+            }
+        }
+        return;
+    }
+    if (scenario.status !== "ready")
+        contradiction(id, "a failed scenario must not carry treatment records.");
+    if (!sameList(scenario.treatments.map((treatment) => treatment.treatmentId), INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS)) {
+        contradiction(id, "treatments must be exactly stale-index, changed-files-refresh, affected-neighborhood-refresh, full-refresh, each once, in order.");
+    }
+    for (const treatment of scenario.treatments) {
+        if (treatment.treatmentIntent !== INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatment.treatmentId]) {
+            contradiction(id, `${treatment.treatmentId} carries treatment intent ${treatment.treatmentIntent}.`);
+        }
+        const refresh = treatment.refreshExecution;
+        if (treatment.treatmentId === "stale-index") {
+            if (refresh.kind !== "no-refresh" || refresh.realization !== "NO_REFRESH" || refresh.incrementalRefresh !== null)
+                contradiction(id, "stale-index must be no-refresh without incrementalRefresh evidence.");
+            if (treatment.activeIndexPhase !== "baseline")
+                contradiction(id, "stale-index active index must be the baseline.");
+            if (treatment.refreshedFreshness !== null)
+                contradiction(id, "stale-index has no refreshed freshness.");
+        }
+        else {
+            if (treatment.activeIndexPhase !== "refreshed")
+                contradiction(id, `${treatment.treatmentId} active index must be the refreshed index.`);
+            if (treatment.refreshedFreshness === null)
+                contradiction(id, `${treatment.treatmentId} is missing refreshed freshness.`);
+        }
+        if (treatment.treatmentId === "full-refresh") {
+            if (refresh.kind !== "full" || refresh.realization !== "FULL_REFRESH" || refresh.incrementalRefresh !== null)
+                contradiction(id, "full-refresh must be a full refresh without incrementalRefresh evidence.");
+        }
+        if (treatment.treatmentId === "changed-files-refresh" || treatment.treatmentId === "affected-neighborhood-refresh") {
+            if (refresh.kind !== "incremental")
+                contradiction(id, `${treatment.treatmentId} must be an incremental refresh.`);
+            if (refresh.kind === "incremental") {
+                const upstream = refresh.incrementalRefresh;
+                if (upstream.requestedScope !== REQUESTED_SCOPE[treatment.treatmentId])
+                    contradiction(id, `${treatment.treatmentId} requested scope ${upstream.requestedScope} does not match the treatment.`);
+                if (refresh.realization === "APPLIED_PARTIAL" && (upstream.selectionStatus !== "applied" || upstream.appliedScope !== upstream.requestedScope)) {
+                    contradiction(id, `${treatment.treatmentId} is APPLIED_PARTIAL but upstream reported status=${upstream.selectionStatus} applied=${upstream.appliedScope}.`);
+                }
+                if (refresh.realization === "FALLBACK_FULL" && (upstream.selectionStatus !== "fallback-full" || upstream.appliedScope !== "full")) {
+                    contradiction(id, `${treatment.treatmentId} is FALLBACK_FULL but upstream reported status=${upstream.selectionStatus} applied=${upstream.appliedScope}.`);
+                }
+            }
+        }
+    }
+    // Partial comparisons must agree with their treatment's realization and the frozen precedence.
+    for (const candidate of PARTIAL_IDS) {
+        const comparison = partialComparison(scenario, candidate);
+        const treatment = scenario.treatments.find((entry) => entry.treatmentId === candidate);
+        if (!comparison || !treatment || treatment.refreshExecution.kind !== "incremental")
+            contradiction(id, `${candidate} comparison or treatment is missing.`);
+        else {
+            if (comparison.refreshRealization !== treatment.refreshExecution.realization) {
+                contradiction(id, `${candidate} comparison realization ${comparison.refreshRealization} differs from the treatment realization ${treatment.refreshExecution.realization}.`);
+            }
+            const expected = classifyPartialRefreshAgainstFull({
+                realization: treatment.refreshExecution.realization,
+                correctnessRelation: comparison.correctnessRelation,
+                requiredFileEvidenceRelation: comparison.requiredFileEvidenceRelation
+            });
+            if (expected.classification !== comparison.classification || !sameList(expected.reasonCodes, comparison.reasonCodes)) {
+                contradiction(id, `${candidate} comparison does not follow the partial-refresh reference rules.`);
+            }
+        }
+    }
+    if (scenario.lifecycle) {
+        for (const count of [...Object.values(scenario.lifecycle.indexInvocationCounts), ...Object.values(scenario.lifecycle.freshnessAssessmentCounts)]) {
+            if (!Number.isInteger(count) || count < 0)
+                contradiction(id, "lifecycle counts must be non-negative integers.");
+        }
+    }
+    else {
+        contradiction(id, "a ready scenario must carry a lifecycle summary.");
+    }
+}
+export function validateIncrementalChangeStalenessExecutionArtifactV2(artifact) {
+    if (artifact.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2) {
+        throw new Error(`Unexpected execution artifact schema ${String(artifact.schemaVersion)}.`);
+    }
+    for (const scenario of artifact.scenarios)
+        validateIncrementalChangeStalenessScenarioRecordV2(scenario);
+}
+/**
+ * Builds and validates the v2 artifact from already-executed scenario evidence, in the caller's canonical
+ * scenario order. Throws on internal contradiction instead of serializing it.
+ */
+export function buildIncrementalChangeStalenessExecutionArtifactV2(args) {
+    const scenarios = args.executions.map(summarizeScenarioV2);
+    const artifact = {
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2,
+        runId: args.runId,
+        pluginId: args.pluginId,
+        scenarios,
+        summary: summarizeV2(scenarios)
+    };
+    validateIncrementalChangeStalenessExecutionArtifactV2(artifact);
+    return artifact;
+}
+/** Writes to the canonical filename shared with v1; validates first so contradictory evidence is never serialized. */
+export async function writeIncrementalChangeStalenessExecutionArtifactV2(outDir, artifact) {
+    validateIncrementalChangeStalenessExecutionArtifactV2(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;
+}
+/** Discriminates V1 from V2 by schemaVersion only; historical V1 evidence is never converted to V2. */
+export function parseIncrementalChangeStalenessExecutionArtifact(json) {
+    const schemaVersion = json && typeof json === "object" ? json.schemaVersion : undefined;
+    if (schemaVersion === INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION) {
+        return { version: "v1", artifact: json };
+    }
+    if (schemaVersion === INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2) {
+        return { version: "v2", artifact: json };
+    }
+    throw new Error(`Unrecognized incremental-change-staleness execution artifact schema: ${String(schemaVersion)}.`);
+}
+export async function readIncrementalChangeStalenessExecutionArtifact(artifactPath) {
+    return parseIncrementalChangeStalenessExecutionArtifact(JSON.parse(await readFile(artifactPath, "utf8")));
+}