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

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

@@ -0,0 +1,274 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { readBenchmarkProjectProfiles } from "../../../evaluation/benchmarkMetadata.js";
+import { toAffectedNeighborhoodMetricValues } from "../../../evaluation/affectedNeighborhoodMetrics.js";
+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 { BENCHMARK_PROJECT_PROFILES_PATH } from "./scenarioCatalog.js";
+import { resolveIncrementalChangeStalenessScenarios } from "./scenarioSelection.js";
+export const INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID = "incremental-change-staleness";
+export const STALE_INDEX_VARIANT_ID = "stale-index";
+export const FULL_REFRESH_VARIANT_ID = "full-refresh";
+/** Marker proving a runtime directory was created by (and belongs to) one plugin run. */
+export const INCREMENTAL_CHANGE_STALENESS_RUN_OWNER_MARKER = ".incremental-change-staleness-run-owner.json";
+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.",
+    schemaVersion: "1.0.0",
+    status: "experimental",
+    supportedTargets: ["self"],
+    supportedOutputs: ["json", "html"]
+};
+const TREATMENT_VARIANTS = [
+    {
+        id: STALE_INDEX_VARIANT_ID,
+        name: "Stale index",
+        description: "Keeps the pre-mutation baseline index as its active retrieval index after the controlled change; never reindexes."
+    },
+    {
+        id: FULL_REFRESH_VARIANT_ID,
+        name: "Full refresh",
+        description: "Builds a new complete post-mutation index in a separate directory and uses it as its active retrieval index."
+    }
+];
+export function resolveIncrementalChangeStalenessRunOwnedRoot(toolRoot, runId) {
+    return resolveWithinRoot(path.resolve(toolRoot), path.join(DEFAULT_INCREMENTAL_CHANGE_STALENESS_RUNTIME_ROOT_RELATIVE, sanitizePathSegment(runId)));
+}
+async function claimRunOwnedRoot(runOwnedRoot, runId) {
+    if (existsSync(runOwnedRoot)) {
+        throw new Error(`Incremental-change-staleness run-owned runtime root already exists; refusing to reuse it: ${runOwnedRoot}`);
+    }
+    await mkdir(path.dirname(runOwnedRoot), { recursive: true });
+    // Non-recursive: fails if another run claimed the same directory in the meantime.
+    await mkdir(runOwnedRoot);
+    await writeFile(path.join(runOwnedRoot, INCREMENTAL_CHANGE_STALENESS_RUN_OWNER_MARKER), `${JSON.stringify({ pluginId: INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID, runId }, null, 2)}\n`, "utf8");
+}
+async function isOwnedByRun(runOwnedRoot, runId) {
+    try {
+        const marker = JSON.parse(await readFile(path.join(runOwnedRoot, INCREMENTAL_CHANGE_STALENESS_RUN_OWNER_MARKER), "utf8"));
+        return marker.pluginId === INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID && marker.runId === runId;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes the run-owned runtime root (targets, indexes, command logs, agent artifacts) only when
+ * it carries this run's ownership marker. Never touches the shared runtime parent, canonical
+ * benchmarks, or any other run's directory. Called by the framework's `cleanup` phase, strictly
+ * after `run()` has already written the persisted execution artifact to the (separate) output root.
+ */
+export async function cleanupIncrementalChangeStalenessRun(toolRoot, runId) {
+    const runOwnedRoot = resolveIncrementalChangeStalenessRunOwnedRoot(toolRoot, runId);
+    if (!(await isOwnedByRun(runOwnedRoot, runId))) {
+        return false;
+    }
+    await removeIncrementalChangeStalenessRuntimeRoot(toolRoot, runOwnedRoot);
+    return true;
+}
+export const incrementalChangeStalenessPlugin = {
+    metadata: incrementalChangeStalenessMetadata,
+    defaultConfig: defaultIncrementalChangeStalenessConfig,
+    configDefinition: incrementalChangeStalenessConfigDefinition,
+    supportedVariants: [...INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS],
+    validateConfig: validateIncrementalChangeStalenessConfig,
+    async run(context) {
+        if (!context.target.isSelf) {
+            throw new Error("incremental-change-staleness runs only against the lab's bundled benchmark projects; an external --target is not supported.");
+        }
+        const startedAt = context.startedAt.toISOString();
+        const runOwnedRoot = resolveIncrementalChangeStalenessRunOwnedRoot(context.toolRoot, context.runId);
+        await claimRunOwnedRoot(runOwnedRoot, context.runId);
+        const resolvedScenarios = await resolveIncrementalChangeStalenessScenarios({
+            repoRoot: context.toolRoot,
+            scenarioIds: context.config.caseIds
+        });
+        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({
+                repoRoot: context.toolRoot,
+                runOwnedRoot,
+                scenario: resolved.scenario,
+                baseCase: resolved.baseCase,
+                kitCommand: context.config.kitCommand
+            });
+            const execution = await executeIncrementalChangeStalenessScenario({
+                repoRoot: context.toolRoot,
+                scenario: resolved.scenario,
+                lifecycle,
+                baseCase: resolved.baseCase,
+                projectProfiles,
+                runOwnedRoot,
+                cwd: context.target.targetRoot
+            });
+            executions.push(execution);
+        }
+        const outDir = context.outputRoot ?? path.resolve(context.toolRoot, context.config.outDir);
+        const artifact = buildIncrementalChangeStalenessExecutionArtifact({
+            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({
+            runId: context.runId,
+            startedAt,
+            completedAt: new Date().toISOString(),
+            target: context.target,
+            kitCommand: context.config.kitCommand,
+            executions,
+            artifactPath
+        });
+    },
+    summarize(result) {
+        return result.summary ?? summarizeExperimentRun(result);
+    },
+    async cleanup(context) {
+        await cleanupIncrementalChangeStalenessRun(context.toolRoot, context.runId);
+    }
+};
+function metric(id, name, description, unit, value, variantId, caseId) {
+    return { id, name, description, unit, value, variantId, caseId };
+}
+function treatmentMetrics(treatment, caseId) {
+    const variantId = treatment.treatmentId;
+    const metrics = [];
+    if (treatment.retrieval) {
+        metrics.push(metric("context-character-count", "Context characters", "Characters in the retrieved my-dev-kit context.", "characters", treatment.retrieval.totalChars, variantId, caseId), metric("context-estimated-token-count", "Estimated context tokens", "Character-based estimate of retrieved context tokens; not provider token usage.", "estimated-tokens", treatment.retrieval.totalEstimatedTokens, variantId, caseId), metric("operation-duration-ms", "Operation duration", "Measured retrieval-only duration (search, lookup, slice, source); excludes index build.", "ms", treatment.retrieval.durationMs, variantId, caseId));
+    }
+    if (treatment.fakeAgent && treatment.fakeAgent.correctness.available && treatment.fakeAgent.correctness.score !== null) {
+        metrics.push(metric("agent-correctness-score", "Agent correctness score", "Deterministic benchmark answer-key correctness score for the selected agent output; not semantic LLM judging.", "score", treatment.fakeAgent.correctness.score, variantId, caseId));
+    }
+    const affectedMetricValues = toAffectedNeighborhoodMetricValues(treatment.affectedNeighborhood, "No affected-neighborhood assessment was recorded for this treatment.");
+    const affectedSpecs = [
+        { id: "affected-neighborhood-changed-file-count", name: "Changed indexed files", description: "Unique confirmed modified or missing files that the baseline index snapshot represents.", field: "changedFileCount" },
+        { id: "affected-neighborhood-changed-symbol-count", name: "Changed baseline symbols", description: "Baseline indexed symbol identities belonging to confirmed changed indexed files.", field: "changedSymbolCount" },
+        { id: "affected-neighborhood-node-count", name: "Affected graph nodes", description: "Unique resolved seed nodes plus their direct one-hop baseline graph neighbors.", field: "affectedNodeCount" },
+        { id: "affected-neighborhood-edge-count", name: "Affected graph edges", description: "Unique baseline graph edges incident to at least one resolved seed node.", field: "affectedEdgeCount" },
+        { id: "affected-neighborhood-task-overlap-count", name: "Task-overlap nodes", description: "Unique baseline graph nodes both in the affected neighborhood and resolved from the task's expected files/symbols.", field: "taskOverlapCount" },
+        { id: "affected-neighborhood-task-overlap-percent", name: "Task-overlap percent", description: "Task-overlap nodes as a percentage of resolvable task graph nodes.", field: "taskOverlapPercent" }
+    ];
+    for (const spec of affectedSpecs) {
+        const value = affectedMetricValues[spec.field];
+        if (value.availability === "available" && value.value !== null) {
+            metrics.push(metric(spec.id, spec.name, spec.description, value.unit, value.value, variantId, caseId));
+        }
+    }
+    return metrics;
+}
+function treatmentOutcome(execution, treatmentId) {
+    const caseId = execution.scenarioId;
+    const base = { id: `${caseId}:${treatmentId}`, caseId, variantId: treatmentId, artifacts: [] };
+    if (execution.status === "failed" || !execution.stale || !execution.fullRefresh) {
+        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, scenarioStatus: execution.status }
+        };
+    }
+    const treatment = treatmentId === "stale-index" ? execution.stale : execution.fullRefresh;
+    const status = treatment.status === "completed" ? "completed" : treatment.status === "failed" ? "failed" : "partial";
+    return {
+        ...base,
+        status,
+        metrics: treatmentMetrics(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,
+            activeIndexPhase: treatment.activeIndexPhase,
+            retrievalStatus: treatment.retrievalStatus,
+            fakeAgentStatus: treatment.fakeAgent?.status ?? "not-run",
+            requiredFileEvidenceStatus: treatment.requiredFileEvidence.status,
+            affectedNeighborhoodRelationship: treatment.affectedNeighborhood.relationship,
+            affectedNeighborhoodReindexRecommendation: treatment.affectedNeighborhood.reindexRecommendation,
+            comparisonCorrectnessRelation: execution.comparison.correctnessRelation,
+            comparisonRequiredFileEvidenceRelation: execution.comparison.requiredFileEvidenceRelation,
+            staleRiskClassification: execution.comparison.staleRiskClassification
+        }
+    };
+}
+export function mapIncrementalChangeStalenessExecutionsToRun(args) {
+    const cases = args.executions.map((execution) => ({
+        id: execution.scenarioId,
+        name: `${execution.scenarioId} (${execution.category})`,
+        // Exactly two outcomes per scenario, stale-index then full-refresh (never a third "raw" outcome).
+        outcomes: [treatmentOutcome(execution, "stale-index"), treatmentOutcome(execution, "full-refresh")],
+        metadata: {
+            category: execution.category,
+            benchmarkProject: execution.benchmarkProjectId,
+            baseCaseId: execution.baseCaseId,
+            scenarioStatus: execution.status,
+            staleRiskClassification: execution.comparison.staleRiskClassification
+        }
+    }));
+    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 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: [
+            { id: "incremental-change-staleness-scenario-count", name: "Scenario count", value: args.executions.length, unit: "count", description: "Selected scenarios in this run." },
+            {
+                id: "incremental-change-staleness-observed-regression-count",
+                name: "Observed stale regression count",
+                value: args.executions.filter((execution) => execution.comparison.staleRiskClassification === "observed-stale-regression").length,
+                unit: "count",
+                description: "Scenarios classified observed-stale-regression."
+            }
+        ],
+        artifacts: [
+            {
+                id: "incremental-change-staleness-execution",
+                label: "Incremental-change-staleness execution evidence",
+                path: args.artifactPath,
+                kind: "artifact",
+                mimeType: "application/json",
+                description: "Per-scenario matched stale-index/full-refresh execution and 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/scenarioCatalog.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { readBenchmarkProjectProfiles } from "../../../evaluation/benchmarkMetadata.js";
+import { readEvaluationCases } from "../../../evaluation/readEvaluationCases.js";
+import { validateIncrementalChangeStalenessCatalog } from "./scenarioValidation.js";
+/** Canonical repository-relative locations reused by the production catalog. */
+export const INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATALOG_PATH = "benchmarks/contracts/incremental-change-staleness-scenarios.json";
+export const BENCHMARK_PROJECT_PROFILES_PATH = "benchmarks/contracts/benchmark-project-profiles.json";
+export const WARM_INDEX_BENCHMARK_CASES_PATH = "benchmarks/contracts/warm-index-benchmark-cases.json";
+/**
+ * Parses and strictly validates an incremental-change-staleness scenario
+ * catalog JSON file. Never mutates the referenced benchmark project/case
+ * files or the catalog file itself; mutation validation runs entirely
+ * in-memory.
+ */
+export async function readIncrementalChangeStalenessScenarioCatalog(catalogPath, profiles, cases, repoRoot = process.cwd(), options = { requireFrozenProductionScenarios: true }) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(catalogPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Failed to parse incremental-change-staleness scenario catalog: ${error.message}`);
+    }
+    const errors = await validateIncrementalChangeStalenessCatalog(parsed, profiles, cases, repoRoot, {
+        requireFrozenProductionScenarios: options.requireFrozenProductionScenarios ?? true
+    });
+    if (errors.length > 0) {
+        throw new Error(`Invalid incremental-change-staleness scenario catalog:\n${errors.join("\n")}`);
+    }
+    return parsed;
+}
+/**
+ * Convenience loader for the canonical production catalog and its two
+ * existing benchmark-contract dependencies, resolved relative to `repoRoot`.
+ * This is the loader later batches (and this batch's tests) should use to
+ * obtain the validated, immutable production scenario set.
+ */
+export async function readProductionIncrementalChangeStalenessScenarioCatalog(repoRoot = process.cwd()) {
+    const profiles = await readBenchmarkProjectProfiles(path.resolve(repoRoot, BENCHMARK_PROJECT_PROFILES_PATH), repoRoot);
+    const cases = await readEvaluationCases(path.resolve(repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), repoRoot);
+    return readIncrementalChangeStalenessScenarioCatalog(path.resolve(repoRoot, INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATALOG_PATH), profiles, cases, repoRoot, { requireFrozenProductionScenarios: true });
+}

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

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/**
+ * True when `relativePath` (project-root-relative, either separator style) is
+ * covered by one of the declared source roots, i.e. equals a root or is
+ * nested underneath one. Shared by Batch 1 catalog validation and Batch 2
+ * execution-time re-validation so both enforce identical coverage semantics.
+ */
+export function isPathCoveredBySourceRoots(relativePath, sourceRoots) {
+    const normalizedFilePath = relativePath.replace(/\\/g, "/");
+    return sourceRoots.some((root) => {
+        const normalizedRoot = root.replace(/\\/g, "/").replace(/\/+$/, "");
+        return normalizedFilePath === normalizedRoot || normalizedFilePath.startsWith(`${normalizedRoot}/`);
+    });
+}
+/**
+ * Applies one scenario's ordered, literal replacement operations to in-memory
+ * text. Every preimage must match exactly once at the point it is applied;
+ * this never touches the filesystem.
+ */
+export function applyMutationOperations(text, operations) {
+    let mutated = text;
+    for (const [index, operation] of operations.entries()) {
+        const occurrences = countOccurrences(mutated, operation.expectedPreimage);
+        if (occurrences === 0) {
+            throw new Error(`operation ${index}: expectedPreimage not found: ${JSON.stringify(operation.expectedPreimage)}.`);
+        }
+        if (occurrences > 1) {
+            throw new Error(`operation ${index}: expectedPreimage matches ${occurrences} times; it must match exactly once: ${JSON.stringify(operation.expectedPreimage)}.`);
+        }
+        mutated = mutated.split(operation.expectedPreimage).join(operation.replacement);
+    }
+    return mutated;
+}
+function countOccurrences(text, needle) {
+    if (needle.length === 0) {
+        return 0;
+    }
+    return text.split(needle).length - 1;
+}
+/**
+ * Validates one controlled mutation file declaration against the real,
+ * on-disk canonical benchmark file:
+ *  - the resolved path stays within the benchmark project root;
+ *  - the resolved path is covered by one of the case's configured indexed
+ *    source roots;
+ *  - the current canonical SHA-256 equals `expectedPreSha256`;
+ *  - the ordered operations apply cleanly to in-memory text;
+ *  - the resulting in-memory SHA-256 equals `expectedPostSha256`.
+ *
+ * This function only reads the canonical file; it never writes to disk, so
+ * canonical benchmark source/test files remain byte-for-byte unchanged.
+ */
+export async function validateMutationFile(label, file, projectAbsoluteRoot, caseSourceRoots) {
+    const errors = [];
+    if (typeof file.path !== "string" || file.path.length === 0) {
+        return { errors: [`${label}: mutation file path must be a nonempty string.`] };
+    }
+    if (path.isAbsolute(file.path) || file.path.includes("..")) {
+        return { errors: [`${label}: mutation file path must be a safe project-relative path: ${file.path}.`] };
+    }
+    const covered = isPathCoveredBySourceRoots(file.path, caseSourceRoots);
+    if (!covered) {
+        errors.push(`${label}: mutation file path ${file.path} is not covered by the referenced case's indexed source roots (${caseSourceRoots.join(", ")}).`);
+    }
+    let absolutePath;
+    try {
+        absolutePath = resolveWithinRoot(projectAbsoluteRoot, file.path);
+    }
+    catch (error) {
+        return { errors: [`${label}: ${error.message}`] };
+    }
+    if (typeof file.expectedPreSha256 !== "string" || !/^[0-9a-f]{64}$/.test(file.expectedPreSha256)) {
+        errors.push(`${label}: expectedPreSha256 must be a lowercase 64-character hex SHA-256 string.`);
+    }
+    if (typeof file.expectedPostSha256 !== "string" || !/^[0-9a-f]{64}$/.test(file.expectedPostSha256)) {
+        errors.push(`${label}: expectedPostSha256 must be a lowercase 64-character hex SHA-256 string.`);
+    }
+    if (!Array.isArray(file.operations) || file.operations.length === 0) {
+        errors.push(`${label}: operations must be a nonempty array.`);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    let buffer;
+    try {
+        buffer = await readFile(absolutePath);
+    }
+    catch (error) {
+        return { errors: [`${label}: unable to read mutation file ${file.path}: ${error.message}`] };
+    }
+    const actualPreSha256 = sha256Hex(buffer);
+    if (actualPreSha256 !== file.expectedPreSha256) {
+        errors.push(`${label}: expectedPreSha256 ${file.expectedPreSha256} does not match actual canonical file SHA-256 ${actualPreSha256}.`);
+        return { errors };
+    }
+    let mutatedText;
+    try {
+        mutatedText = applyMutationOperations(buffer.toString("utf8"), file.operations);
+    }
+    catch (error) {
+        errors.push(`${label}: ${error.message}`);
+        return { errors };
+    }
+    const actualPostSha256 = sha256Hex(Buffer.from(mutatedText, "utf8"));
+    if (actualPostSha256 !== file.expectedPostSha256) {
+        errors.push(`${label}: expectedPostSha256 ${file.expectedPostSha256} does not match computed in-memory post-mutation SHA-256 ${actualPostSha256}.`);
+        return { errors };
+    }
+    return { errors: [], mutatedText };
+}

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

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { readBenchmarkProjectProfiles } from "../../../evaluation/benchmarkMetadata.js";
+import { readEvaluationCases } from "../../../evaluation/readEvaluationCases.js";
+import { normalizeRootForComparison } from "./lifecyclePolicy.js";
+import { BENCHMARK_PROJECT_PROFILES_PATH, INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATALOG_PATH, WARM_INDEX_BENCHMARK_CASES_PATH, readIncrementalChangeStalenessScenarioCatalog } from "./scenarioCatalog.js";
+/**
+ * Policy: selects scenarios from the validated catalog. No selection means
+ * every catalog scenario. An explicit selection must be non-empty, contain no
+ * duplicates, and name only catalog scenarios. The result always follows
+ * catalog order, never request order, so run ordering is deterministic.
+ */
+export function selectIncrementalChangeStalenessScenarios(catalog, scenarioIds) {
+    if (scenarioIds === undefined) {
+        return [...catalog.scenarios];
+    }
+    if (scenarioIds.length === 0) {
+        throw new Error("Scenario selection must name at least one scenario when provided.");
+    }
+    const duplicates = scenarioIds.filter((id, index) => scenarioIds.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+        throw new Error(`Scenario selection contains duplicate scenario id(s): ${[...new Set(duplicates)].join(", ")}.`);
+    }
+    const known = new Set(catalog.scenarios.map((scenario) => scenario.id));
+    const unknown = scenarioIds.filter((id) => !known.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown incremental-change-staleness scenario id(s): ${unknown.join(", ")}. Known: ${[...known].join(", ")}.`);
+    }
+    const requested = new Set(scenarioIds);
+    return catalog.scenarios.filter((scenario) => requested.has(scenario.id));
+}
+/**
+ * Policy: resolves a scenario's canonical base case identity from the existing
+ * benchmark case and project-profile contracts. Source roots always come from
+ * the base case; the canonical project root always comes from the project
+ * profile, and the two must agree.
+ */
+export function resolveIncrementalChangeStalenessBaseCase(scenario, cases, profiles, 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.`);
+    }
+    const profile = profiles.find((candidate) => candidate.projectId === scenario.benchmarkProjectId);
+    if (!profile) {
+        throw new Error(`Scenario ${scenario.id}: benchmark project ${scenario.benchmarkProjectId} was not found.`);
+    }
+    if (baseCase.benchmarkProject !== scenario.benchmarkProjectId) {
+        throw new Error(`Scenario ${scenario.id}: base case ${baseCase.id} belongs to ${baseCase.benchmarkProject}, not ${scenario.benchmarkProjectId}.`);
+    }
+    const canonicalProjectRoot = path.resolve(repoRoot, profile.rootPath);
+    if (normalizeRootForComparison(canonicalProjectRoot) !== normalizeRootForComparison(baseCase.absoluteTargetRoot)) {
+        throw new Error(`Scenario ${scenario.id}: base case target root ${baseCase.absoluteTargetRoot} does not match project profile root ${canonicalProjectRoot}.`);
+    }
+    if (!Array.isArray(baseCase.sourceRoots) || baseCase.sourceRoots.length === 0) {
+        throw new Error(`Scenario ${scenario.id}: base case ${baseCase.id} declares no source roots.`);
+    }
+    return Object.freeze({
+        caseId: baseCase.id,
+        benchmarkProjectId: scenario.benchmarkProjectId,
+        canonicalProjectRootRelative: profile.rootPath,
+        canonicalProjectRoot,
+        sourceRoots: Object.freeze([...baseCase.sourceRoots])
+    });
+}
+/**
+ * Loads the canonical production scenario catalog (the only mutation
+ * authority) and its benchmark case/profile dependencies, then resolves the
+ * selected scenarios with their base-case identities in catalog order.
+ * Read-only.
+ */
+export async function resolveIncrementalChangeStalenessScenarios(options) {
+    const { repoRoot } = options;
+    const profiles = await readBenchmarkProjectProfiles(path.resolve(repoRoot, BENCHMARK_PROJECT_PROFILES_PATH), repoRoot);
+    const cases = await readEvaluationCases(path.resolve(repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), repoRoot);
+    const catalog = await readIncrementalChangeStalenessScenarioCatalog(path.resolve(repoRoot, INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATALOG_PATH), profiles, cases, repoRoot, { requireFrozenProductionScenarios: true });
+    return selectIncrementalChangeStalenessScenarios(catalog, options.scenarioIds).map((scenario) => ({
+        scenario,
+        baseCase: resolveIncrementalChangeStalenessBaseCase(scenario, cases, profiles, repoRoot)
+    }));
+}

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

@@ -0,0 +1,37 @@
+/**
+ * v0.6.2 incremental-change-staleness scenario catalog schema version.
+ *
+ * This is a separate, versioned contract from the warm-index benchmark case
+ * contract (`benchmarks/contracts/warm-index-benchmark-cases.json`), which
+ * remains unchanged. Scenario records here reference existing benchmark
+ * project/case ids rather than duplicating canonical project/target metadata.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION = "1.0.0";
+/**
+ * The experimental dimension a scenario deliberately changes. Categories are
+ * not required to be structurally exclusive (for example, an exported
+ * function body is still implementation code); the selected category
+ * describes the intended experimental contrast, not an exhaustive structural
+ * classification.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES = [
+    "unrelated-file-change",
+    "local-implementation-change",
+    "exported-symbol-change",
+    "public-api-change",
+    "import-graph-change",
+    "test-only-change"
+];
+/**
+ * Answer-key policy for a scenario's follow-up query:
+ * - `inherit`: reuse the referenced base case's existing query/answer key
+ *   because the controlled change does not alter that task's semantic truth.
+ * - `scenario`: use a scenario-specific post-mutation query and answer key,
+ *   expressed with the existing benchmark answer-key structure.
+ *
+ * Exactly these two policies are supported; no other correctness vocabulary
+ * is introduced.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES = ["inherit", "scenario"];
+/** The six planner-frozen production scenario ids, in their planned order. */
+export const FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS = ["U1", "L2", "E1", "P1", "I1", "T1"];