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

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";
+export 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
+    };
+}
+export 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)
+    };
+}
+export 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]
+    };
+}
+export 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/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")));
+}

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/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";