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

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

@@ -0,0 +1,404 @@
+import path from "node:path";
+import { runAgentPrompt } from "../../../agents/index.js";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { assessAffectedNeighborhood, mapAffectedNeighborhoodSeeds } from "../../../evaluation/affectedNeighborhood.js";
+import { classifyAgentRunOutcome } from "../../../evaluation/classifyAgentRunOutcome.js";
+import { parseAgentAnswer } from "../../../evaluation/parseAgentAnswer.js";
+import { readEvaluationCases } from "../../../evaluation/readEvaluationCases.js";
+import { runMyDevKitRetrievalFromIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { scoreCorrectness } from "../../../evaluation/scoreCorrectness.js";
+import { generatePromptVariants } from "../../../prompts/index.js";
+import { buildRequiredFileEvidence, classifyStaleRisk, compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+import { WARM_INDEX_BENCHMARK_CASES_PATH } from "./scenarioCatalog.js";
+// ---------------------------------------------------------------------------
+// v0.6.2 Batch 4 -- treatment retrieval, correctness, and required-file
+// evidence. Reuses existing generic owners exactly (mapAffectedNeighborhoodSeeds
+// / assessAffectedNeighborhood, runMyDevKitRetrievalFromIndex, scoreCorrectness,
+// generatePromptVariants + runAgentPrompt("fake-agent") + parseAgentAnswer +
+// classifyAgentRunOutcome). No new correctness/retrieval/fake-agent algorithm
+// is introduced here.
+// ---------------------------------------------------------------------------
+const SCOREABLE_STATUSES = new Set(["completed", "invalid-output"]);
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Resolves one scenario's query/answer key. `inherit` reuses the referenced base case's existing
+ * query/answer key unchanged; `scenario` uses the scenario's own post-mutation query/answer key.
+ * The two are never merged. Reads the same canonical benchmark-case contract the lifecycle already
+ * validated against; never mutates it.
+ */
+export async function resolveIncrementalChangeStalenessQueryAndAnswer(options) {
+    const { scenario, repoRoot } = options;
+    if (scenario.answerPolicy === "scenario") {
+        if (!scenario.scenarioQuery || !scenario.scenarioAnswerKey) {
+            throw new Error(`Scenario ${scenario.id}: answerPolicy is "scenario" but scenarioQuery/scenarioAnswerKey are missing.`);
+        }
+        return {
+            query: scenario.scenarioQuery,
+            answerKey: scenario.scenarioAnswerKey,
+            expectedFiles: [...scenario.scenarioAnswerKey.expectedFiles],
+            expectedSymbols: [...scenario.scenarioAnswerKey.expectedSymbols]
+        };
+    }
+    const cases = await readEvaluationCases(path.resolve(repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), repoRoot);
+    const baseCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
+    if (!baseCase) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for query/answer resolution.`);
+    }
+    if (!baseCase.answerKey) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} declares no answerKey for the "inherit" answer policy.`);
+    }
+    return {
+        query: baseCase.query,
+        answerKey: baseCase.answerKey,
+        expectedFiles: [...baseCase.answerKey.expectedFiles],
+        expectedSymbols: [...baseCase.answerKey.expectedSymbols]
+    };
+}
+// ---------------------------------------------------------------------------
+// Derived in-memory task descriptor (section 9). Never written to disk and
+// never replaces the canonical benchmark case/answer-key files.
+// ---------------------------------------------------------------------------
+/**
+ * Builds one in-memory `EvaluationCase`-shaped task descriptor: identity/project/source ownership
+ * comes from the canonical base case; query and expected files/symbols come from the resolved
+ * query/answer. Used for affected-neighborhood task mapping, treatment retrieval, and fake-agent
+ * prompt generation; it is never materialized as a benchmark case file.
+ */
+export function buildIncrementalChangeStalenessDerivedTask(args) {
+    const base = args.baseEvaluationCase;
+    return {
+        ...base,
+        id: `${args.scenario.id}:${base.id}`,
+        title: `${args.scenario.id} (${base.title})`,
+        query: args.resolved.query,
+        expectedFiles: [...args.resolved.expectedFiles],
+        expectedSymbols: [...args.resolved.expectedSymbols],
+        answerKey: args.resolved.answerKey,
+        projectProfileRef: base.projectProfileRef ?? base.benchmarkProject
+    };
+}
+// ---------------------------------------------------------------------------
+// Affected-neighborhood execution (sections 10-14, 56).
+// ---------------------------------------------------------------------------
+/**
+ * Assesses one treatment's affected neighborhood using its BASELINE change authority (never the
+ * refreshed graph, even for full-refresh): the baseline index's snapshot/graph plus the treatment's
+ * already-established post-mutation baseline freshness.
+ */
+export function assessIncrementalChangeStalenessAffectedNeighborhood(treatment, derivedTask) {
+    const changeAuthority = treatment.changeAuthority;
+    const seedMapping = mapAffectedNeighborhoodSeeds({
+        indexSnapshot: changeAuthority.baselineIndex.snapshot,
+        freshness: changeAuthority.postMutationBaselineFreshness,
+        graph: changeAuthority.baselineIndex.graph
+    });
+    return assessAffectedNeighborhood({ graph: changeAuthority.baselineIndex.graph, seedMapping, task: derivedTask });
+}
+const SYMMETRIC_NUMERIC_FIELDS = [
+    "changedFileCount",
+    "changedSymbolCount",
+    "affectedNodeCount",
+    "affectedEdgeCount",
+    "taskOverlapCount",
+    "taskOverlapPercent"
+];
+/**
+ * Section 13: requires equality of assessment status, relationship, reindexRecommendation, and the
+ * availability/value of all six numeric metrics between the two treatment baselines. Does not
+ * require raw graph identity or absolute paths to match.
+ */
+export function checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(stale, fullRefresh) {
+    const mismatches = [];
+    if (stale.status !== fullRefresh.status)
+        mismatches.push(`status (${stale.status} vs ${fullRefresh.status})`);
+    if (stale.relationship !== fullRefresh.relationship)
+        mismatches.push(`relationship (${stale.relationship} vs ${fullRefresh.relationship})`);
+    if (stale.reindexRecommendation !== fullRefresh.reindexRecommendation) {
+        mismatches.push(`reindexRecommendation (${stale.reindexRecommendation} vs ${fullRefresh.reindexRecommendation})`);
+    }
+    for (const field of SYMMETRIC_NUMERIC_FIELDS) {
+        if (stale[field] !== fullRefresh[field]) {
+            mismatches.push(`${field} (${String(stale[field])} vs ${String(fullRefresh[field])})`);
+        }
+    }
+    if (mismatches.length === 0)
+        return { symmetric: true };
+    return { symmetric: false, reason: `Affected-neighborhood assessments are asymmetric: ${mismatches.join("; ")}.` };
+}
+/** Same classification rule as the existing warm-index-reuse execution owner. */
+export function classifyIncrementalChangeStalenessRetrieval(result) {
+    if (!result.skipped)
+        return "completed";
+    return result.commands.some((command) => !command.ok) ? "failed" : "skipped";
+}
+export async function runIncrementalChangeStalenessTreatmentRetrieval(args) {
+    return runMyDevKitRetrievalFromIndex({
+        evaluationCase: args.derivedTask,
+        kitCommand: args.kitCommand,
+        indexDir: args.indexDir,
+        commandsDir: args.commandsDir,
+        requireKit: false
+    });
+}
+/**
+ * Section 27: a `failed` retrieval status means the actual-files-read set cannot be trusted as
+ * complete (unknown); `completed` and `skipped` (search ran and legitimately found no candidate)
+ * both provide a complete, trustworthy files-read set, possibly empty.
+ */
+export function buildIncrementalChangeStalenessRequiredFileEvidence(args) {
+    if (!args.retrieval) {
+        return buildRequiredFileEvidence({
+            requiredFiles: args.requiredFiles,
+            observedFiles: [],
+            observedFilesComplete: false,
+            unknownReason: "No retrieval was attempted for this treatment."
+        });
+    }
+    const status = classifyIncrementalChangeStalenessRetrieval(args.retrieval);
+    return buildRequiredFileEvidence({
+        requiredFiles: args.requiredFiles,
+        observedFiles: args.retrieval.filesRead,
+        observedFilesComplete: status !== "failed",
+        unknownReason: status === "failed"
+            ? `Retrieval failed (${args.retrieval.warnings.join(" ") || "my-dev-kit retrieval command failed."}); the actual-files-read set is incomplete.`
+            : undefined
+    });
+}
+export async function runIncrementalChangeStalenessFakeAgent(args) {
+    try {
+        const [promptVariant] = generatePromptVariants({
+            cases: [args.derivedTask],
+            projectProfiles: [...args.projectProfiles],
+            strategies: ["my-dev-kit-guided"],
+            complexityLevels: ["short"]
+        });
+        if (!promptVariant) {
+            throw new Error(`Failed to generate a fake-agent prompt for case ${args.derivedTask.id}.`);
+        }
+        const agentRunResult = await runAgentPrompt({
+            runId: args.runId,
+            agentId: "fake-agent",
+            promptVariant,
+            promptText: promptVariant.promptText,
+            cwd: args.cwd,
+            outDir: args.outDir,
+            env: args.env
+        });
+        const parsedAnswer = parseAgentAnswer({
+            text: agentRunResult.finalAnswerText,
+            answerKey: promptVariant.expectedAnswerKey,
+            tokenUsage: agentRunResult.tokenUsage
+        });
+        const classification = classifyAgentRunOutcome({ agentRunResult, parsedAnswer });
+        const correctness = scoreCorrectness({
+            caseId: args.derivedTask.id,
+            answerKey: promptVariant.expectedAnswerKey,
+            parsedAnswer,
+            status: classification.status
+        });
+        const scoreable = SCOREABLE_STATUSES.has(classification.status) && Number.isFinite(correctness.correctnessScore);
+        return {
+            status: classification.status,
+            correctness: {
+                available: scoreable,
+                score: scoreable ? correctness.correctnessScore : null,
+                passed: scoreable ? correctness.passed : null,
+                failureReasons: [...correctness.failureReasons]
+            },
+            correctnessDetail: scoreable ? correctness : null,
+            durationMs: agentRunResult.durationMs,
+            warnings: [...classification.warnings],
+            errors: [...classification.errors]
+        };
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            correctness: { available: false, score: null, passed: null, failureReasons: [] },
+            correctnessDetail: null,
+            durationMs: null,
+            warnings: [],
+            errors: [errorMessage(error)]
+        };
+    }
+}
+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 = {
+    correctnessRelation: "unknown",
+    requiredFileEvidenceRelation: "unknown",
+    staleRiskClassification: "inconclusive",
+    reasonCodes: ["correctness-unavailable", "required-file-evidence-unavailable"]
+};
+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;
+    let retrieval = null;
+    let retrievalStatus = "not-run";
+    let failureReason = null;
+    try {
+        retrieval = await args.deps.runRetrieval({
+            derivedTask: args.derivedTask,
+            kitCommand: args.kitCommand,
+            indexDir: treatment.activeRetrieval.index.indexDir,
+            commandsDir: args.retrievalCommandsDir
+        });
+        retrievalStatus = classifyIncrementalChangeStalenessRetrieval(retrieval);
+    }
+    catch (error) {
+        failureReason = `Treatment retrieval threw: ${errorMessage(error)}`;
+        retrievalStatus = "failed";
+    }
+    let fakeAgent = null;
+    if (retrieval !== null) {
+        fakeAgent = await args.deps.runFakeAgent({
+            derivedTask: args.derivedTask,
+            projectProfiles: args.projectProfiles,
+            outDir: args.agentOutDir,
+            cwd: args.cwd,
+            runId: `${args.derivedTask.id}.${args.treatmentId}`,
+            env: args.env
+        });
+    }
+    const requiredFileEvidence = buildIncrementalChangeStalenessRequiredFileEvidence({
+        requiredFiles: args.requiredFiles,
+        retrieval
+    });
+    const status = retrievalStatus === "failed" || fakeAgent?.status === "failed"
+        ? "partial"
+        : retrievalStatus === "completed" && fakeAgent && fakeAgent.correctness.available
+            ? "completed"
+            : "partial";
+    return {
+        treatmentId: args.treatmentId,
+        status,
+        failureReason,
+        activeIndexPhase,
+        baselineFreshness,
+        affectedNeighborhood: args.affectedNeighborhood,
+        retrieval,
+        retrievalStatus,
+        fakeAgent,
+        requiredFileEvidence
+    };
+}
+/**
+ * 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
+ * change authority, verify symmetry, then run stale retrieval/fake-agent/correctness/required-file
+ * evidence, then full-refresh, then compare and classify. A lifecycle that is not `ready` is
+ * reported as a failed scenario execution with no fabricated treatment evidence (section 39).
+ */
+export async function executeIncrementalChangeStalenessScenario(options) {
+    const deps = { ...defaultIncrementalChangeStalenessExecutionDeps, ...options.deps };
+    const scenario = options.scenario;
+    if (options.lifecycle.status !== "ready") {
+        // Section 39: scenario-level failure; no treatment execution, comparison stays inconclusive.
+        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,
+            stale: null,
+            fullRefresh: null,
+            comparison: INCONCLUSIVE_NO_EXECUTION
+        };
+    }
+    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 staleAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["stale-index"], derivedTask);
+    const fullAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["full-refresh"], derivedTask);
+    const symmetry = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(staleAffected, fullAffected);
+    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
+    };
+    if (!symmetry.symmetric) {
+        return {
+            ...scenarioBase,
+            status: "failed",
+            failureReason: `AFFECTED_NEIGHBORHOOD_ASYMMETRY: ${symmetry.reason}`,
+            stale: null,
+            fullRefresh: null,
+            comparison: INCONCLUSIVE_NO_EXECUTION
+        };
+    }
+    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));
+    // Stale-index runs first, deterministically, before full-refresh (section 37).
+    const stale = await executeOneTreatment({
+        session,
+        treatmentId: "stale-index",
+        derivedTask,
+        affectedNeighborhood: staleAffected,
+        requiredFiles: resolved.expectedFiles,
+        kitCommand: session.kitCommand,
+        retrievalCommandsDir: retrievalCommandsDir("stale-index"),
+        agentOutDir: agentOutDir("stale-index"),
+        projectProfiles: options.projectProfiles,
+        cwd: options.cwd,
+        env: options.env,
+        deps
+    });
+    const fullRefresh = await executeOneTreatment({
+        session,
+        treatmentId: "full-refresh",
+        derivedTask,
+        affectedNeighborhood: fullAffected,
+        requiredFiles: resolved.expectedFiles,
+        kitCommand: session.kitCommand,
+        retrievalCommandsDir: retrievalCommandsDir("full-refresh"),
+        agentOutDir: agentOutDir("full-refresh"),
+        projectProfiles: options.projectProfiles,
+        cwd: options.cwd,
+        env: options.env,
+        deps
+    });
+    const correctnessRelation = compareCorrectness(correctnessComparable(stale.fakeAgent), correctnessComparable(fullRefresh.fakeAgent));
+    const requiredFileEvidenceRelation = compareRequiredFileEvidence(stale.requiredFileEvidence, fullRefresh.requiredFileEvidence);
+    const classification = classifyStaleRisk(correctnessRelation, requiredFileEvidenceRelation);
+    return {
+        ...scenarioBase,
+        status: "ready",
+        failureReason: null,
+        stale,
+        fullRefresh,
+        comparison: {
+            correctnessRelation,
+            requiredFileEvidenceRelation,
+            staleRiskClassification: classification.staleRiskClassification,
+            reasonCodes: classification.reasonCodes
+        }
+    };
+}

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

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

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

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