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

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

@@ -0,0 +1,298 @@
+import path from "node:path";
+import { createDisposableTreatmentTarget, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { cloneIncrementalChangeStalenessIndexDirectory } from "./indexClone.js";
+import { defaultIncrementalChangeStalenessLifecycleDeps, fail, incrementalChangeStalenessIndexDir, incrementalChangeStalenessTargetsRoot, LifecycleFailure, prepareTreatmentIndexEvidence } from "./lifecycle.js";
+import { evaluateBaselineStaleFreshness, evaluateChangedPathSymmetry, evaluateRefreshedFreshness, evaluateToolIdentity, normalizeRelativePath, normalizeRootForComparison } from "./lifecyclePolicy.js";
+import { evaluateBaselineBootstrapEvidence, evaluatePartialRefreshRealization, evaluateV2InvocationCounts } from "./lifecyclePolicyV2.js";
+import { compareIncrementalChangeStalenessSourceStates } from "./sourceState.js";
+import { INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_V2_SCHEMA_VERSION } from "./treatmentSessionV2.js";
+const PARTIAL_REFRESH_SCOPES = {
+    "changed-files-refresh": "changed-files",
+    "affected-neighborhood-refresh": "affected-neighborhood"
+};
+/** Every baseline is bootstrapped incrementally so upstream writes the cache metadata a later partial refresh needs. */
+const BOOTSTRAP_MODE = { kind: "incremental", refreshScope: "changed-files" };
+const V2_TREATMENT_IDS = INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS;
+function withRefreshEvidence(evidence, buildMode, incrementalRefresh) {
+    return Object.freeze({ ...evidence, buildMode, incrementalRefresh });
+}
+/**
+ * v0.6.3 internal four-treatment lifecycle for ONE frozen scenario (runtime only; not yet wired into the
+ * public plugin, execution artifact, comparison, or reports):
+ *
+ *  1. four independent disposable copies (stale-index, changed-files-refresh, affected-neighborhood-refresh,
+ *     full-refresh), all derived from the same immutable canonical benchmark;
+ *  2. pre-mutation controlled source-state equivalence of every treatment against the stale-index reference;
+ *  3. all four baselines bootstrapped with `--incremental --refresh-scope changed-files` into brand-new
+ *     index directories (expected bootstrap evidence: full fallback, `cache-missing`);
+ *  4. each partial treatment's untouched baseline is cloned byte-for-byte into its own refreshed directory;
+ *  5. BARRIER: only after every baseline + clone is ready is the same frozen mutation applied to all four;
+ *  6. post-mutation source-state equivalence and symmetric complete-stale baseline freshness;
+ *  7. stale-index keeps its baseline; each partial treatment refreshes its clone in place and full-refresh
+ *     builds a new full index; every refreshed index must be complete `fresh`.
+ *
+ * Seven index invocations and seven freshness assessments per scenario. Performs no retrieval,
+ * affected-neighborhood task traversal, or comparison classification. Sequential by design; deletes nothing.
+ */
+export async function prepareIncrementalChangeStalenessScenarioLifecycleV2(options) {
+    const cloneIndexDirectory = options.deps?.cloneIndexDirectory ?? cloneIncrementalChangeStalenessIndexDirectory;
+    const deps = { ...defaultIncrementalChangeStalenessLifecycleDeps, ...options.deps };
+    const { repoRoot, scenario, baseCase, kitCommand } = options;
+    const runOwnedRoot = path.resolve(options.runOwnedRoot);
+    const events = [];
+    const indexInvocationCounts = Object.fromEntries(V2_TREATMENT_IDS.map((id) => [id, 0]));
+    const freshnessAssessmentCounts = Object.fromEntries(V2_TREATMENT_IDS.map((id) => [id, 0]));
+    const sourceRoots = baseCase.sourceRoots;
+    const controlledChangedPaths = scenario.mutation.files.map((file) => normalizeRelativePath(file.path)).sort();
+    async function prepareIndex(target, role, indexDir, mode, existingIndexDir = false) {
+        const treatmentId = target.treatmentId;
+        indexInvocationCounts[treatmentId] += 1;
+        const { evidence, build } = await prepareTreatmentIndexEvidence({
+            deps,
+            runOwnedRoot,
+            scenarioId: scenario.id,
+            kitCommand,
+            sourceRoots,
+            target,
+            role,
+            indexDir,
+            mode,
+            existingIndexDir,
+            onIndexPrepared: () => events.push(`${treatmentId}:${role}-index-built`, `${treatmentId}:${role}-snapshot-captured`, `${treatmentId}:${role}-graph-loaded`)
+        });
+        events.push(`${treatmentId}:${role}-identity-verified`);
+        return { evidence, build };
+    }
+    async function captureState(target) {
+        return deps.captureSourceState(target.targetRoot, sourceRoots, target.treatmentId, baseCase.benchmarkProjectId);
+    }
+    async function mutate(target) {
+        const receipt = await deps.executeMutation(scenario, target, sourceRoots, repoRoot);
+        if (receipt.status !== "applied") {
+            fail({ code: "mutation-failed", message: `${target.treatmentId} mutation was rejected: ${receipt.errors.join(" ")}`, treatmentId: target.treatmentId });
+        }
+        events.push(`${target.treatmentId}:mutation-applied`);
+        return receipt;
+    }
+    async function assess(index, target) {
+        freshnessAssessmentCounts[target.treatmentId] += 1;
+        return deps.assessIndexFreshness({ snapshot: index.snapshot, targetRoot: target.targetRoot, sourceRoots });
+    }
+    function compareAgainstReference(reference, states, code, phase) {
+        const comparisons = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            if (treatmentId === "stale-index")
+                continue;
+            const comparison = compareIncrementalChangeStalenessSourceStates(reference, states[treatmentId]);
+            comparisons[treatmentId] = comparison;
+            if (comparison.result !== "equivalent") {
+                fail({
+                    code,
+                    message: `${treatmentId} is not ${phase} equivalent to the stale-index reference (${comparison.result}): ${comparison.reasons.join("; ")}`,
+                    treatmentId
+                });
+            }
+        }
+        return comparisons;
+    }
+    try {
+        const baselineDirs = {};
+        const refreshedDirs = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            baselineDirs[treatmentId] = incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, treatmentId, "baseline");
+            refreshedDirs[treatmentId] = incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, treatmentId, "refreshed");
+        }
+        const allDirs = [...Object.values(baselineDirs), ...Object.values(refreshedDirs)].map(normalizeRootForComparison);
+        if (new Set(allDirs).size !== allDirs.length) {
+            fail({ code: "index-directory-collision", message: "Treatment/phase index directories are not distinct.", treatmentId: null });
+        }
+        // 1. Four independent disposable copies through the established owner, in fixed order.
+        const targets = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            try {
+                targets[treatmentId] = await createDisposableTreatmentTarget({
+                    repoRoot,
+                    runRoot: incrementalChangeStalenessTargetsRoot(runOwnedRoot),
+                    scenarioId: scenario.id,
+                    treatmentId,
+                    benchmarkProjectId: baseCase.benchmarkProjectId,
+                    canonicalProjectRootRelative: baseCase.canonicalProjectRootRelative
+                });
+            }
+            catch (error) {
+                fail({ code: "treatment-target-creation-failed", message: `${treatmentId}: ${error.message}`, treatmentId });
+            }
+        }
+        const targetRootKeys = V2_TREATMENT_IDS.map((id) => normalizeRootForComparison(targets[id].targetRoot));
+        if (new Set(targetRootKeys).size !== targetRootKeys.length) {
+            fail({ code: "treatment-target-creation-failed", message: "Treatment target roots are not distinct.", treatmentId: null });
+        }
+        events.push("treatment-targets-created");
+        // 2. Pre-mutation equivalence gates all indexing and mutation; stale-index is only the comparison reference.
+        const preStates = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            preStates[treatmentId] = await captureState(targets[treatmentId]);
+        events.push("pre-mutation-source-state-captured");
+        const preMutationEquivalence = compareAgainstReference(preStates["stale-index"], preStates, "pre-mutation-not-equivalent", "pre-mutation");
+        events.push("pre-mutation-equivalence-proven");
+        // 3. Baselines: every treatment bootstraps incrementally into a brand-new index directory.
+        const baselines = {};
+        const bootstraps = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            const { evidence, build } = await prepareIndex(targets[treatmentId], "baseline", baselineDirs[treatmentId], BOOTSTRAP_MODE);
+            fail(evaluateBaselineBootstrapEvidence(build, treatmentId));
+            bootstraps[treatmentId] = build.incrementalRefresh;
+            baselines[treatmentId] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            events.push(`${treatmentId}:baseline-bootstrap-verified`);
+        }
+        const baselineTools = evaluateToolIdentity(V2_TREATMENT_IDS.map((id) => baselines[id]));
+        fail(baselineTools.failure);
+        events.push("baseline-tool-identity-verified");
+        // 4. Preserve each partial treatment's immutable baseline; the refresh runs in place against a byte-for-byte clone.
+        for (const treatmentId of ["changed-files-refresh", "affected-neighborhood-refresh"]) {
+            try {
+                await cloneIndexDirectory(runOwnedRoot, baselineDirs[treatmentId], refreshedDirs[treatmentId]);
+            }
+            catch (error) {
+                fail({ code: "index-clone-failed", message: `${treatmentId} baseline index clone failed: ${error.message}`, treatmentId });
+            }
+            events.push(`${treatmentId}:baseline-index-cloned`);
+        }
+        // 5. Barrier: all four baselines are index + snapshot + graph READY and clones exist. Only now may mutation begin.
+        events.push("baseline-barrier-ready");
+        const receipts = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            receipts[treatmentId] = await mutate(targets[treatmentId]);
+        // 6. Post-mutation equivalence.
+        const postStates = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            postStates[treatmentId] = await captureState(targets[treatmentId]);
+        events.push("post-mutation-source-state-captured");
+        const postMutationEquivalence = compareAgainstReference(postStates["stale-index"], postStates, "post-mutation-not-equivalent", "post-mutation");
+        events.push("post-mutation-equivalence-proven");
+        // 7. Baseline (change-authority) freshness against each mutated target, symmetric with the reference.
+        const baselineFreshness = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            baselineFreshness[treatmentId] = await assess(baselines[treatmentId], targets[treatmentId]);
+            fail(evaluateBaselineStaleFreshness(baselineFreshness[treatmentId], controlledChangedPaths, treatmentId));
+            events.push(`${treatmentId}:baseline-freshness-stale`);
+        }
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            if (treatmentId === "stale-index")
+                continue;
+            fail(evaluateChangedPathSymmetry(baselineFreshness["stale-index"], baselineFreshness[treatmentId], { reference: "stale-index", other: treatmentId }));
+        }
+        events.push("baseline-changed-paths-symmetric");
+        // 8. stale-index: no rebuild; baseline stays the active retrieval index.
+        events.push("stale-index:baseline-retained-as-active");
+        // 9. Partial treatments: refresh the cloned working index in place through the shared build owner.
+        const refreshed = {};
+        const refreshedFreshness = {};
+        const realizations = {};
+        for (const treatmentId of ["changed-files-refresh", "affected-neighborhood-refresh"]) {
+            const scope = PARTIAL_REFRESH_SCOPES[treatmentId];
+            const { evidence, build } = await prepareIndex(targets[treatmentId], "refreshed", refreshedDirs[treatmentId], { kind: "incremental", refreshScope: scope }, true);
+            const realization = evaluatePartialRefreshRealization(build, scope, treatmentId);
+            fail(realization.failure);
+            realizations[treatmentId] = realization.realization;
+            events.push(`${treatmentId}:refresh-realization-${realization.realization === "APPLIED_PARTIAL" ? "applied-partial" : "fallback-full"}`);
+            refreshed[treatmentId] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            refreshedFreshness[treatmentId] = await assess(evidence, targets[treatmentId]);
+            fail(evaluateRefreshedFreshness(refreshedFreshness[treatmentId], treatmentId));
+            events.push(`${treatmentId}:refreshed-freshness-fresh`);
+        }
+        // 10. full-refresh: a NEW complete post-mutation index in a separate directory (baseline is not cloned).
+        {
+            const { evidence, build } = await prepareIndex(targets["full-refresh"], "refreshed", refreshedDirs["full-refresh"], undefined);
+            refreshed["full-refresh"] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            refreshedFreshness["full-refresh"] = await assess(evidence, targets["full-refresh"]);
+            fail(evaluateRefreshedFreshness(refreshedFreshness["full-refresh"], "full-refresh"));
+            events.push("full-refresh:refreshed-freshness-fresh");
+        }
+        // 11. Scenario-level proofs.
+        const allTools = evaluateToolIdentity([...V2_TREATMENT_IDS.map((id) => baselines[id]), ...V2_TREATMENT_IDS.flatMap((id) => (refreshed[id] ? [refreshed[id]] : []))]);
+        fail(allTools.failure);
+        events.push("tool-identity-consistent");
+        fail(evaluateV2InvocationCounts(indexInvocationCounts, freshnessAssessmentCounts));
+        events.push("invocation-counts-verified");
+        events.push("lifecycle-ready");
+        const common = (treatmentId) => ({
+            treatmentIntent: INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatmentId],
+            target: targets[treatmentId],
+            preMutationSourceState: preStates[treatmentId],
+            postMutationSourceState: postStates[treatmentId],
+            mutationReceipt: receipts[treatmentId],
+            changeAuthority: Object.freeze({
+                baselineIndex: baselines[treatmentId],
+                baselineBootstrap: bootstraps[treatmentId],
+                postMutationBaselineFreshness: baselineFreshness[treatmentId]
+            }),
+            indexInvocationCount: indexInvocationCounts[treatmentId],
+            freshnessAssessmentCount: freshnessAssessmentCounts[treatmentId],
+            lifecycleStatus: "ready",
+            warnings: Object.freeze([])
+        });
+        const partialSession = (treatmentId) => Object.freeze({
+            ...common(treatmentId),
+            treatmentId,
+            activeRetrieval: Object.freeze({ role: "refreshed", index: refreshed[treatmentId] }),
+            postMutationIndexBuilt: true,
+            refreshedIndex: refreshed[treatmentId],
+            refreshedFreshness: refreshedFreshness[treatmentId],
+            refreshRealization: realizations[treatmentId]
+        });
+        const staleSession = Object.freeze({
+            ...common("stale-index"),
+            treatmentId: "stale-index",
+            activeRetrieval: Object.freeze({ role: "baseline", index: baselines["stale-index"] }),
+            postMutationIndexBuilt: false,
+            refreshedIndex: null,
+            refreshedFreshness: null,
+            refreshRealization: null
+        });
+        const fullSession = Object.freeze({
+            ...common("full-refresh"),
+            treatmentId: "full-refresh",
+            activeRetrieval: Object.freeze({ role: "refreshed", index: refreshed["full-refresh"] }),
+            postMutationIndexBuilt: true,
+            refreshedIndex: refreshed["full-refresh"],
+            refreshedFreshness: refreshedFreshness["full-refresh"],
+            refreshRealization: null
+        });
+        const session = Object.freeze({
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_V2_SCHEMA_VERSION,
+            scenarioId: scenario.id,
+            scenario,
+            baseCase,
+            runOwnedRoot,
+            kitCommand,
+            toolIdentity: allTools.tool,
+            controlledChangedPaths: Object.freeze(controlledChangedPaths),
+            preMutationEquivalence: Object.freeze(preMutationEquivalence),
+            postMutationEquivalence: Object.freeze(postMutationEquivalence),
+            treatments: Object.freeze({
+                "stale-index": staleSession,
+                "changed-files-refresh": partialSession("changed-files-refresh"),
+                "affected-neighborhood-refresh": partialSession("affected-neighborhood-refresh"),
+                "full-refresh": fullSession
+            }),
+            totalIndexInvocationCount: V2_TREATMENT_IDS.reduce((sum, id) => sum + indexInvocationCounts[id], 0),
+            totalFreshnessAssessmentCount: V2_TREATMENT_IDS.reduce((sum, id) => sum + freshnessAssessmentCounts[id], 0),
+            lifecycleEvents: Object.freeze([...events]),
+            status: "ready"
+        });
+        return { status: "ready", session };
+    }
+    catch (error) {
+        const failure = error instanceof LifecycleFailure
+            ? error.failure
+            : { code: "lifecycle-error", message: `Lifecycle failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`, treatmentId: null };
+        return {
+            status: "failed",
+            scenarioId: scenario.id,
+            failure,
+            lifecycleEvents: Object.freeze([...events]),
+            indexInvocationCounts: Object.freeze({ ...indexInvocationCounts })
+        };
+    }
+}

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

@@ -7,10 +7,10 @@ import { toAffectedNeighborhoodMetricValues } from "../../../evaluation/affected
 import { sanitizePathSegment } from "../../outputPaths.js";
 import { summarizeExperimentRun } from "../../results.js";
 import { defaultIncrementalChangeStalenessConfig, incrementalChangeStalenessConfigDefinition, validateIncrementalChangeStalenessConfig } from "./config.js";
-import { DEFAULT_INCREMENTAL_CHANGE_STALENESS_RUNTIME_ROOT_RELATIVE, INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS, removeIncrementalChangeStalenessRuntimeRoot } from "./disposableTarget.js";
-import { executeIncrementalChangeStalenessScenario } from "./execution.js";
-import { buildIncrementalChangeStalenessExecutionArtifact, writeIncrementalChangeStalenessExecutionArtifact } from "./executionArtifact.js";
-import { prepareIncrementalChangeStalenessScenarioLifecycle } from "./lifecycle.js";
+import { DEFAULT_INCREMENTAL_CHANGE_STALENESS_RUNTIME_ROOT_RELATIVE, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS, removeIncrementalChangeStalenessRuntimeRoot } from "./disposableTarget.js";
+import { buildIncrementalChangeStalenessExecutionArtifactV2, writeIncrementalChangeStalenessExecutionArtifactV2 } from "./executionArtifactV2.js";
+import { executeIncrementalChangeStalenessScenarioV2 } from "./executionV2.js";
+import { prepareIncrementalChangeStalenessScenarioLifecycleV2 } from "./lifecycleV2.js";
 import { BENCHMARK_PROJECT_PROFILES_PATH } from "./scenarioCatalog.js";
 import { resolveIncrementalChangeStalenessScenarios } from "./scenarioSelection.js";
 export const INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID = "incremental-change-staleness";
@@ -21,13 +21,39 @@ export const INCREMENTAL_CHANGE_STALENESS_RUN_OWNER_MARKER = ".incremental-chang
 export const incrementalChangeStalenessMetadata = {
     id: INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID,
     name: "Incremental Change Staleness",
-    description: "Compares stale-index and full-refresh my-dev-kit retrieval after the same frozen controlled source change: matched correctness, required-file evidence, and a conservative stale-risk classification.",
+    description: "Compares no refresh, my-dev-kit changed-files incremental refresh, my-dev-kit affected-neighborhood incremental refresh, and full refresh after the same deterministic controlled source change. Comparisons are scoped to the observed evidence (correctness and required-file presence); full refresh is a reference treatment, not an asserted winner, and a partial treatment may truthfully fall back to a full rebuild.",
     schemaVersion: "1.0.0",
     status: "experimental",
     supportedTargets: ["self"],
     supportedOutputs: ["json", "html"]
 };
+export const CHANGED_FILES_REFRESH_VARIANT_ID = "changed-files-refresh";
+export const AFFECTED_NEIGHBORHOOD_REFRESH_VARIANT_ID = "affected-neighborhood-refresh";
+/** Public v0.6.3 treatments, in the fixed lifecycle order. Factual descriptions only; no treatment is called best or preferred. */
 const TREATMENT_VARIANTS = [
+    {
+        id: STALE_INDEX_VARIANT_ID,
+        name: "No refresh (stale index)",
+        description: "Keeps the pre-mutation baseline index and performs no post-mutation refresh."
+    },
+    {
+        id: CHANGED_FILES_REFRESH_VARIANT_ID,
+        name: "Changed-files refresh",
+        description: "Uses my-dev-kit's incremental changed-files refresh after the controlled mutation; upstream may truthfully fall back to a full rebuild."
+    },
+    {
+        id: AFFECTED_NEIGHBORHOOD_REFRESH_VARIANT_ID,
+        name: "Affected-neighborhood refresh",
+        description: "Uses my-dev-kit's affected-neighborhood incremental refresh after the controlled mutation; upstream may truthfully fall back to a full rebuild."
+    },
+    {
+        id: FULL_REFRESH_VARIANT_ID,
+        name: "Full refresh",
+        description: "Builds a complete post-mutation index and uses it as the comparison reference."
+    }
+];
+/** The released v0.6.2 two-treatment variants, kept only for the historical V1 run mapper. */
+const V1_TREATMENT_VARIANTS = [
     {
         id: STALE_INDEX_VARIANT_ID,
         name: "Stale index",
@@ -78,7 +104,7 @@ export const incrementalChangeStalenessPlugin = {
     metadata: incrementalChangeStalenessMetadata,
     defaultConfig: defaultIncrementalChangeStalenessConfig,
     configDefinition: incrementalChangeStalenessConfigDefinition,
-    supportedVariants: [...INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS],
+    supportedVariants: [...INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS],
     validateConfig: validateIncrementalChangeStalenessConfig,
     async run(context) {
         if (!context.target.isSelf) {
@@ -94,14 +120,14 @@ export const incrementalChangeStalenessPlugin = {
         const projectProfiles = await readBenchmarkProjectProfiles(path.resolve(context.toolRoot, BENCHMARK_PROJECT_PROFILES_PATH), context.toolRoot);
         const executions = [];
         for (const resolved of resolvedScenarios) {
-            const lifecycle = await prepareIncrementalChangeStalenessScenarioLifecycle({
+            const lifecycle = await prepareIncrementalChangeStalenessScenarioLifecycleV2({
                 repoRoot: context.toolRoot,
                 runOwnedRoot,
                 scenario: resolved.scenario,
                 baseCase: resolved.baseCase,
                 kitCommand: context.config.kitCommand
             });
-            const execution = await executeIncrementalChangeStalenessScenario({
+            const execution = await executeIncrementalChangeStalenessScenarioV2({
                 repoRoot: context.toolRoot,
                 scenario: resolved.scenario,
                 lifecycle,
@@ -113,15 +139,15 @@ export const incrementalChangeStalenessPlugin = {
             executions.push(execution);
         }
         const outDir = context.outputRoot ?? path.resolve(context.toolRoot, context.config.outDir);
-        const artifact = buildIncrementalChangeStalenessExecutionArtifact({
+        const artifact = buildIncrementalChangeStalenessExecutionArtifactV2({
             runId: context.runId,
             pluginId: INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID,
             executions
         });
         // The artifact is written before the framework's separate `cleanup` phase runs, so it is
         // written before the run-owned ephemeral index/target state is ever destroyed.
-        const artifactPath = await writeIncrementalChangeStalenessExecutionArtifact(outDir, artifact);
-        return mapIncrementalChangeStalenessExecutionsToRun({
+        const artifactPath = await writeIncrementalChangeStalenessExecutionArtifactV2(outDir, artifact);
+        return mapIncrementalChangeStalenessExecutionsToRunV2({
             runId: context.runId,
             startedAt,
             completedAt: new Date().toISOString(),
@@ -239,7 +265,7 @@ export function mapIncrementalChangeStalenessExecutionsToRun(args) {
         completedAt: args.completedAt,
         status,
         target: args.target,
-        variants: TREATMENT_VARIANTS.map((variant) => ({ ...variant })),
+        variants: V1_TREATMENT_VARIANTS.map((variant) => ({ ...variant })),
         cases,
         metrics: [
             { id: "incremental-change-staleness-scenario-count", name: "Scenario count", value: args.executions.length, unit: "count", description: "Selected scenarios in this run." },
@@ -272,3 +298,178 @@ export function mapIncrementalChangeStalenessExecutionsToRun(args) {
     run.summary = summarizeExperimentRun(run);
     return run;
 }
+// ---------------------------------------------------------------------------
+// v0.6.3 four-treatment mapping. Maps already-executed V2 evidence; recomputes nothing.
+// ---------------------------------------------------------------------------
+const UPSTREAM_REFRESH_METRIC_SPECS = [
+    { id: "upstream-refresh-fresh-extraction-file-count", name: "Upstream fresh-extraction files", field: "freshExtractionFileCount", description: "Files my-dev-kit freshly re-extracted during the refresh invocation (upstream execution evidence, not Lab task overlap)." },
+    { id: "upstream-refresh-reused-file-count", name: "Upstream reused files", field: "reusedFileCount", description: "Files my-dev-kit reused from the previous index during the refresh invocation (upstream execution evidence)." },
+    { id: "upstream-refresh-forced-neighbor-reanalysis-file-count", name: "Upstream forced-neighbor reanalysis files", field: "forcedNeighborReanalysisFileCount", description: "Neighbor files my-dev-kit forced to re-analyze during the refresh invocation (upstream execution evidence)." },
+    { id: "upstream-refresh-seed-file-count", name: "Upstream seed files", field: "seedFileCount", description: "Seed files my-dev-kit selected for the affected-neighborhood refresh (upstream execution evidence; absent when upstream reported none)." },
+    { id: "upstream-refresh-seed-symbol-count", name: "Upstream seed symbols", field: "seedSymbolCount", description: "Seed symbols my-dev-kit selected for the affected-neighborhood refresh (upstream execution evidence; absent when upstream reported none)." },
+    { id: "upstream-refresh-affected-node-count", name: "Upstream affected nodes", field: "affectedNodeCount", description: "Graph nodes my-dev-kit treated as affected during the refresh (upstream execution evidence, distinct from the Lab affected-neighborhood metrics)." },
+    { id: "upstream-refresh-affected-edge-count", name: "Upstream affected edges", field: "affectedEdgeCount", description: "Graph edges my-dev-kit treated as affected during the refresh (upstream execution evidence, distinct from the Lab affected-neighborhood metrics)." }
+];
+function upstreamRefreshMetrics(treatment, caseId) {
+    const refresh = treatment.refreshExecution;
+    if (refresh.kind !== "incremental")
+        return [];
+    const metrics = [];
+    for (const spec of UPSTREAM_REFRESH_METRIC_SPECS) {
+        const value = refresh.incrementalRefresh[spec.field];
+        // Null upstream fields are unavailable evidence, never a zero-valued metric.
+        if (typeof value === "number")
+            metrics.push(metric(spec.id, spec.name, spec.description, "count", value, treatment.treatmentId, caseId));
+    }
+    return metrics;
+}
+function comparisonMetadata(execution, treatmentId) {
+    const comparison = execution.referenceComparisons.find((entry) => entry.candidateTreatmentId === treatmentId);
+    if (!comparison)
+        return {};
+    if (comparison.kind === "stale-risk") {
+        return {
+            comparisonCorrectnessRelation: comparison.comparison.correctnessRelation,
+            comparisonRequiredFileEvidenceRelation: comparison.comparison.requiredFileEvidenceRelation,
+            staleRiskClassification: comparison.comparison.staleRiskClassification
+        };
+    }
+    return {
+        referenceComparisonCorrectnessRelation: comparison.correctnessRelation,
+        referenceComparisonRequiredFileEvidenceRelation: comparison.requiredFileEvidenceRelation,
+        referenceComparisonClassification: comparison.classification
+    };
+}
+function treatmentOutcomeV2(execution, treatmentId) {
+    const caseId = execution.scenarioId;
+    const treatmentIntent = INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatmentId];
+    const base = { id: `${caseId}:${treatmentId}`, caseId, variantId: treatmentId, artifacts: [] };
+    const treatment = execution.treatments.find((entry) => entry.treatmentId === treatmentId);
+    if (execution.status === "failed" || !treatment) {
+        return {
+            ...base,
+            status: "failed",
+            metrics: [],
+            warnings: [],
+            failures: [
+                {
+                    code: "incremental-change-staleness-scenario-failed",
+                    message: execution.failureReason ?? "Scenario execution failed before treatment evidence was produced.",
+                    variantId: treatmentId,
+                    caseId,
+                    recoverable: false
+                }
+            ],
+            metadata: { treatmentId, treatmentIntent, scenarioStatus: execution.status }
+        };
+    }
+    const status = treatment.status === "completed" ? "completed" : treatment.status === "failed" ? "failed" : "partial";
+    const refresh = treatment.refreshExecution;
+    const incremental = refresh.kind === "incremental" ? refresh.incrementalRefresh : null;
+    return {
+        ...base,
+        status,
+        metrics: [...treatmentMetrics(treatment, caseId), ...upstreamRefreshMetrics(treatment, caseId)],
+        warnings: treatment.retrievalStatus === "failed" || treatment.fakeAgent?.status === "failed"
+            ? [{ code: "incremental-change-staleness-treatment-partial", message: treatment.failureReason ?? "Treatment retrieval or fake-agent evaluation did not fully complete.", variantId: treatmentId, caseId }]
+            : [],
+        failures: [],
+        metadata: {
+            treatmentId,
+            treatmentIntent,
+            activeIndexPhase: treatment.activeIndexPhase,
+            treatmentStatus: treatment.status,
+            retrievalStatus: treatment.retrievalStatus,
+            fakeAgentStatus: treatment.fakeAgent?.status ?? "not-run",
+            requiredFileEvidenceStatus: treatment.requiredFileEvidence.status,
+            affectedNeighborhoodRelationship: treatment.affectedNeighborhood.relationship,
+            affectedNeighborhoodReindexRecommendation: treatment.affectedNeighborhood.reindexRecommendation,
+            refreshKind: refresh.kind,
+            refreshRealization: refresh.realization,
+            // Upstream categorical evidence only for incremental treatments; never invented for the others.
+            ...(incremental
+                ? {
+                    requestedScope: incremental.requestedScope,
+                    appliedScope: incremental.appliedScope,
+                    selectionStatus: incremental.selectionStatus,
+                    fallbackReason: incremental.fallbackReason
+                }
+                : {}),
+            ...comparisonMetadata(execution, treatmentId)
+        }
+    };
+}
+function countByRealization(executions, treatmentId, realization) {
+    return executions.filter((execution) => execution.treatments.find((treatment) => treatment.treatmentId === treatmentId)?.refreshExecution.realization === realization).length;
+}
+export function mapIncrementalChangeStalenessExecutionsToRunV2(args) {
+    const cases = args.executions.map((execution) => {
+        const partialClass = (candidate) => {
+            const comparison = execution.referenceComparisons.find((entry) => entry.candidateTreatmentId === candidate);
+            return comparison && comparison.kind === "partial-refresh" ? comparison.classification : null;
+        };
+        const stale = execution.referenceComparisons.find((entry) => entry.candidateTreatmentId === "stale-index");
+        return {
+            id: execution.scenarioId,
+            name: `${execution.scenarioId} (${execution.category})`,
+            // Exactly four outcomes per scenario, in the fixed lifecycle order (never a "raw" outcome).
+            outcomes: INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS.map((treatmentId) => treatmentOutcomeV2(execution, treatmentId)),
+            metadata: {
+                category: execution.category,
+                benchmarkProject: execution.benchmarkProjectId,
+                baseCaseId: execution.baseCaseId,
+                scenarioStatus: execution.status,
+                staleRiskClassification: stale && stale.kind === "stale-risk" ? stale.comparison.staleRiskClassification : null,
+                changedFilesReferenceClassification: partialClass("changed-files-refresh"),
+                affectedNeighborhoodReferenceClassification: partialClass("affected-neighborhood-refresh")
+            }
+        };
+    });
+    const outcomeStatuses = cases.flatMap((experimentCase) => experimentCase.outcomes.map((outcome) => outcome.status));
+    const status = outcomeStatuses.length > 0 && outcomeStatuses.every((value) => value === "failed")
+        ? "failed"
+        : outcomeStatuses.every((value) => value === "completed")
+            ? "completed"
+            : "partial";
+    const count = (id, name, value, description) => ({ id, name, value, unit: "count", description });
+    const run = {
+        runId: args.runId,
+        pluginId: INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID,
+        startedAt: args.startedAt,
+        completedAt: args.completedAt,
+        status,
+        target: args.target,
+        variants: TREATMENT_VARIANTS.map((variant) => ({ ...variant })),
+        cases,
+        metrics: [
+            count("incremental-change-staleness-scenario-count", "Scenario count", args.executions.length, "Selected scenarios in this run."),
+            count("incremental-change-staleness-observed-regression-count", "Observed stale regression count", args.executions.filter((execution) => {
+                const stale = execution.referenceComparisons.find((entry) => entry.candidateTreatmentId === "stale-index");
+                return stale?.kind === "stale-risk" && stale.comparison.staleRiskClassification === "observed-stale-regression";
+            }).length, "Scenarios whose no-refresh treatment was classified observed-stale-regression against full refresh."),
+            count("incremental-change-staleness-changed-files-applied-partial-count", "Changed-files applied-partial count", countByRealization(args.executions, "changed-files-refresh", "APPLIED_PARTIAL"), "Scenarios where the changed-files refresh was applied as a partial refresh."),
+            count("incremental-change-staleness-changed-files-fallback-full-count", "Changed-files fallback-full count", countByRealization(args.executions, "changed-files-refresh", "FALLBACK_FULL"), "Scenarios where the changed-files refresh fell back to a full rebuild."),
+            count("incremental-change-staleness-affected-neighborhood-applied-partial-count", "Affected-neighborhood applied-partial count", countByRealization(args.executions, "affected-neighborhood-refresh", "APPLIED_PARTIAL"), "Scenarios where the affected-neighborhood refresh was applied as a partial refresh."),
+            count("incremental-change-staleness-affected-neighborhood-fallback-full-count", "Affected-neighborhood fallback-full count", countByRealization(args.executions, "affected-neighborhood-refresh", "FALLBACK_FULL"), "Scenarios where the affected-neighborhood refresh fell back to a full rebuild.")
+        ],
+        artifacts: [
+            {
+                id: "incremental-change-staleness-execution",
+                label: "Incremental-change-staleness execution evidence",
+                path: args.artifactPath,
+                kind: "artifact",
+                mimeType: "application/json",
+                description: "Per-scenario four-treatment execution, refresh-realization, and full-refresh reference-comparison evidence, without raw context bodies."
+            }
+        ],
+        warnings: [],
+        failures: [],
+        metadata: {
+            kitCommand: args.kitCommand,
+            scenarioIds: args.executions.map((execution) => execution.scenarioId),
+            executionArtifactPath: args.artifactPath
+        }
+    };
+    run.summary = summarizeExperimentRun(run);
+    return run;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * v0.6.3 in-memory (runtime-only) four-treatment lifecycle session schema version. This is NOT the
+ * persisted execution artifact; persistence is a later batch.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_V2_SCHEMA_VERSION = "2.0.0";

package/dist/src/experiments/plugins/warmIndexReuse/warmIndexSession.js

@@ -5,7 +5,9 @@ import { loadAffectedNeighborhoodGraphEvidence } from "../../../evaluation/affec
 import { captureIndexSnapshot } from "../../../evaluation/indexSnapshot.js";
 /**
  * Builds the index once through the shared `buildMyDevKitIndex` owner. A build that reports
- * success but leaves no index directory is not treated as a prepared session.
+ * success but leaves no index directory is not treated as a prepared session. `mode` is optional
+ * and defaults to an ordinary full build; only callers that explicitly request an incremental
+ * build mode get one.
  */
 export async function prepareWarmIndexSession(options) {
     const build = await buildMyDevKitIndex(options);

package/dist/src/mobile/android/advancedSecurity/candidateEvidence.js

@@ -19,14 +19,21 @@ function buildCandidateEvidenceId(ruleId, location, fingerprint) {
     const locationPart = [location.path, location.line !== undefined ? `l${location.line}` : undefined, location.column !== undefined ? `c${location.column}` : undefined]
         .filter((part) => Boolean(part))
         .join(":");
-    return [ruleId, slug(locationPart), fingerprint.slice(0, 16)].join("--");
+    const payloadStart = fingerprint.indexOf(":") + 1;
+    return [ruleId, slug(locationPart), fingerprint.slice(payloadStart, payloadStart + 16)].join("--");
 }
 // Never accepts a raw secret value as a plain string parameter name to
 // discourage accidental logging at call sites — `rawValue` is redacted and
 // fingerprinted here, once, and the raw value is never stored on the
 // returned object.
 export function makeCandidateEvidence(input) {
-    const fingerprint = fingerprintCandidateValue(input.rawValue);
+    const fingerprint = fingerprintCandidateValue(input.rawValue, {
+        ruleId: input.ruleId,
+        sourcePath: input.location.path,
+        line: input.location.line,
+        column: input.location.column,
+        purpose: "candidate-evidence"
+    });
     const redactedPreview = redactedPreviewForCandidate(input.rawValue);
     const id = buildCandidateEvidenceId(input.ruleId, input.location, fingerprint);
     return {