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

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

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

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { validateAnswerKey } from "../../../evaluation/benchmarkMetadata.js";
+import { validateMutationFile } from "./scenarioMutation.js";
+import { FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS, INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES, INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES, INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION } from "./scenarioTypes.js";
+/** Category each frozen production scenario id is required to declare. */
+export const FROZEN_SCENARIO_CATEGORY_BY_ID = {
+    U1: "unrelated-file-change",
+    L2: "local-implementation-change",
+    E1: "exported-symbol-change",
+    P1: "public-api-change",
+    I1: "import-graph-change",
+    T1: "test-only-change"
+};
+/** Substrings that must never appear in scenario notes/query text (Section 7/9/22.I). */
+const FORBIDDEN_TEXT_PATTERNS = [/partial-refresh/i, /changed-files-refresh/i, /affected-neighborhood-refresh/i, /graph-diff/i];
+/**
+ * Strictly validates a parsed incremental-change-staleness scenario catalog.
+ * Performs schema/vocabulary checks, benchmark project/case reference checks,
+ * answer-policy completeness checks, forbidden-content checks, and full
+ * in-memory mutation validation (pre-hash, ordered exact-preimage
+ * replacement, post-hash) against the real canonical benchmark files. Never
+ * writes to disk.
+ */
+export async function validateIncrementalChangeStalenessCatalog(catalog, profiles, cases, repoRoot, options = {}) {
+    const errors = [];
+    if (!catalog || typeof catalog !== "object") {
+        return ["Scenario catalog must be an object."];
+    }
+    const candidate = catalog;
+    if (candidate.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION}; received ${JSON.stringify(candidate.schemaVersion)}.`);
+    }
+    if (!Array.isArray(candidate.scenarios)) {
+        errors.push("scenarios must be an array.");
+        return errors;
+    }
+    const profilesById = new Map(profiles.map((profile) => [profile.projectId, profile]));
+    const casesById = new Map(cases.map((benchmarkCase) => [benchmarkCase.id, benchmarkCase]));
+    const seenIds = new Set();
+    for (const [index, scenario] of candidate.scenarios.entries()) {
+        errors.push(...(await validateOneScenario(scenario, index, profilesById, casesById, repoRoot, seenIds)));
+    }
+    if (options.requireFrozenProductionScenarios === true) {
+        const actualIds = candidate.scenarios
+            .map((scenario) => (scenario && typeof scenario === "object" ? scenario.id : undefined))
+            .filter((id) => typeof id === "string");
+        const expected = FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS;
+        const actualSet = new Set(actualIds);
+        const missing = expected.filter((id) => !actualSet.has(id));
+        const extra = actualIds.filter((id) => !expected.includes(id));
+        if (missing.length > 0) {
+            errors.push(`Production catalog is missing required frozen scenario(s): ${missing.join(", ")}.`);
+        }
+        if (extra.length > 0) {
+            errors.push(`Production catalog contains unexpected scenario id(s) beyond the six frozen scenarios: ${extra.join(", ")}.`);
+        }
+        if (actualIds.length !== expected.length || missing.length > 0 || extra.length > 0) {
+            errors.push(`Production catalog must contain exactly the six frozen scenarios ${expected.join(", ")}; received ${actualIds.join(", ") || "<none>"}.`);
+        }
+    }
+    return errors;
+}
+async function validateOneScenario(scenario, index, profilesById, casesById, repoRoot, seenIds) {
+    const errors = [];
+    if (!scenario || typeof scenario !== "object") {
+        return [`scenario at index ${index}: must be an object.`];
+    }
+    const candidate = scenario;
+    const id = typeof candidate.id === "string" && candidate.id.length > 0 ? candidate.id : undefined;
+    const label = id === undefined ? `scenario at index ${index}` : `scenario ${id}`;
+    if (id === undefined) {
+        errors.push(`${label}: id must be a nonempty string.`);
+    }
+    else if (seenIds.has(id)) {
+        errors.push(`${label}: duplicate scenario id.`);
+    }
+    else {
+        seenIds.add(id);
+    }
+    if (typeof candidate.category !== "string" || !INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES.includes(candidate.category)) {
+        errors.push(`${label}: category must be one of ${INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES.join(", ")}; received ${JSON.stringify(candidate.category)}.`);
+    }
+    else if (id !== undefined && id in FROZEN_SCENARIO_CATEGORY_BY_ID) {
+        const expectedCategory = FROZEN_SCENARIO_CATEGORY_BY_ID[id];
+        if (candidate.category !== expectedCategory) {
+            errors.push(`${label}: category must be ${expectedCategory} for frozen scenario ${id}; received ${candidate.category}.`);
+        }
+    }
+    if (typeof candidate.answerPolicy !== "string" || !INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES.includes(candidate.answerPolicy)) {
+        errors.push(`${label}: answerPolicy must be one of ${INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES.join(", ")}; received ${JSON.stringify(candidate.answerPolicy)}.`);
+    }
+    const projectId = typeof candidate.benchmarkProjectId === "string" && candidate.benchmarkProjectId.length > 0 ? candidate.benchmarkProjectId : undefined;
+    if (projectId === undefined) {
+        errors.push(`${label}: benchmarkProjectId must be a nonempty string.`);
+    }
+    const profile = projectId === undefined ? undefined : profilesById.get(projectId);
+    if (projectId !== undefined && profile === undefined) {
+        errors.push(`${label}: unknown benchmarkProjectId ${projectId}.`);
+    }
+    const caseId = typeof candidate.baseCaseId === "string" && candidate.baseCaseId.length > 0 ? candidate.baseCaseId : undefined;
+    if (caseId === undefined) {
+        errors.push(`${label}: baseCaseId must be a nonempty string.`);
+    }
+    const baseCase = caseId === undefined ? undefined : casesById.get(caseId);
+    if (caseId !== undefined && baseCase === undefined) {
+        errors.push(`${label}: unknown baseCaseId ${caseId}.`);
+    }
+    if (baseCase !== undefined && projectId !== undefined && baseCase.benchmarkProject !== projectId) {
+        errors.push(`${label}: baseCaseId ${caseId} belongs to benchmark project ${baseCase.benchmarkProject}, not the referenced benchmarkProjectId ${projectId}.`);
+    }
+    // Answer-policy completeness (Section 22.H). Reuses the existing answer-key structure/validator.
+    if (candidate.answerPolicy === "inherit") {
+        if (baseCase !== undefined) {
+            if (typeof baseCase.query !== "string" || baseCase.query.length === 0) {
+                errors.push(`${label}: inherit policy requires the base case to have a nonempty query.`);
+            }
+            if (baseCase.answerKey === undefined) {
+                errors.push(`${label}: inherit policy requires the base case to have an answerKey.`);
+            }
+            else {
+                errors.push(...validateAnswerKey(baseCase.answerKey, `${label} (inherited answerKey)`).map((message) => message));
+            }
+        }
+        if (candidate.scenarioQuery !== undefined || candidate.scenarioAnswerKey !== undefined) {
+            errors.push(`${label}: inherit policy must not declare scenarioQuery or scenarioAnswerKey.`);
+        }
+    }
+    else if (candidate.answerPolicy === "scenario") {
+        if (typeof candidate.scenarioQuery !== "string" || candidate.scenarioQuery.trim().length === 0) {
+            errors.push(`${label}: scenario policy requires a nonempty scenarioQuery.`);
+        }
+        if (candidate.scenarioAnswerKey === undefined) {
+            errors.push(`${label}: scenario policy requires a scenarioAnswerKey.`);
+        }
+        else {
+            errors.push(...validateAnswerKey(candidate.scenarioAnswerKey, `${label}.scenarioAnswerKey`));
+        }
+    }
+    if (candidate.expectedRelationship !== undefined && !["related", "unrelated", "unknown"].includes(candidate.expectedRelationship)) {
+        errors.push(`${label}: expectedRelationship must be one of related, unrelated, unknown; received ${JSON.stringify(candidate.expectedRelationship)}.`);
+    }
+    for (const text of [candidate.notes, candidate.scenarioQuery, candidate.id, candidate.category]) {
+        if (typeof text === "string") {
+            for (const pattern of FORBIDDEN_TEXT_PATTERNS) {
+                if (pattern.test(text)) {
+                    errors.push(`${label}: forbidden v0.6.3+/graph-diff reference found in scenario text: matched ${pattern}.`);
+                }
+            }
+        }
+    }
+    if (!candidate.mutation || typeof candidate.mutation !== "object" || !Array.isArray(candidate.mutation.files) || candidate.mutation.files.length === 0) {
+        errors.push(`${label}: mutation.files must be a nonempty array.`);
+        return errors;
+    }
+    if (profile !== undefined && baseCase !== undefined) {
+        const projectAbsoluteRoot = path.resolve(repoRoot, profile.rootPath);
+        const caseSourceRoots = Array.isArray(baseCase.sourceRoots) ? baseCase.sourceRoots : [];
+        for (const [fileIndex, file] of candidate.mutation.files.entries()) {
+            const fileLabel = `${label}.mutation.files[${fileIndex}]`;
+            const result = await validateMutationFile(fileLabel, file, projectAbsoluteRoot, caseSourceRoots);
+            errors.push(...result.errors);
+        }
+    }
+    else {
+        errors.push(`${label}: mutation files cannot be validated because the benchmark project/case reference is invalid.`);
+    }
+    return errors;
+}

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

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { sha256Hex } from "./scenarioMutation.js";
+/**
+ * v0.6.2 Batch 2 controlled-source-state schema version. This is a
+ * copy-equivalence guard scoped to a benchmark case's configured indexed
+ * source roots; it is NOT the real `IndexSnapshotV1` captured from an actual
+ * my-dev-kit index build (that remains Batch 3's responsibility).
+ */
+export const INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION = "1.0.0";
+function normalizeSourceRoot(root) {
+    return root.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/**
+ * Recursively enumerates regular files (symbolic links are skipped, never
+ * followed) underneath one project-relative source root, hashing each with
+ * SHA-256. Deterministic: results are always returned to the caller sorted.
+ */
+async function collectSourceRootFiles(projectRoot, sourceRoot) {
+    const absoluteRoot = resolveWithinRoot(projectRoot, sourceRoot);
+    const results = [];
+    async function walk(currentAbsoluteDir) {
+        const entries = await readdir(currentAbsoluteDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+                // Never follow symlinks when building controlled source-state evidence.
+                continue;
+            }
+            const entryAbsolutePath = path.join(currentAbsoluteDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryAbsolutePath);
+            }
+            else if (entry.isFile()) {
+                const buffer = await readFile(entryAbsolutePath);
+                const relativePath = path.relative(projectRoot, entryAbsolutePath).split(path.sep).join("/");
+                results.push({ relativePath, sha256: sha256Hex(buffer) });
+            }
+        }
+    }
+    await walk(absoluteRoot);
+    return results;
+}
+function computeDigest(files) {
+    const serialized = files.map((file) => `${file.relativePath}\t${file.sha256}\n`).join("");
+    return createHash("sha256").update(Buffer.from(serialized, "utf8")).digest("hex");
+}
+/**
+ * Captures bounded, deterministic controlled source-state evidence for one
+ * disposable treatment copy, scoped to the base case's own configured
+ * `sourceRoots` (never invented separately). Never converts an unreadable or
+ * missing source root into an empty/zero-file "complete" result: any
+ * enumeration failure makes the whole capture "unavailable" with a reason.
+ */
+export async function captureIncrementalChangeStalenessSourceState(projectRoot, sourceRoots, treatmentId, benchmarkProjectId) {
+    const normalizedSourceRoots = sourceRoots.map(normalizeSourceRoot);
+    if (normalizedSourceRoots.length === 0) {
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "unavailable",
+            files: [],
+            fileCount: 0,
+            digest: null,
+            reason: "No source roots were configured for this benchmark case."
+        };
+    }
+    try {
+        const perRoot = await Promise.all(normalizedSourceRoots.map((root) => collectSourceRootFiles(projectRoot, root)));
+        const files = perRoot.flat().sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "complete",
+            files,
+            fileCount: files.length,
+            digest: computeDigest(files)
+        };
+    }
+    catch (error) {
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "unavailable",
+            files: [],
+            fileCount: 0,
+            digest: null,
+            reason: `Unable to capture controlled source state: ${error.message}`
+        };
+    }
+}
+/**
+ * Deterministically compares two controlled source-state captures.
+ * `equivalent` requires both sides complete, matching normalized source-root
+ * sets, matching path sets, and matching per-file SHA-256 values.
+ * Incomplete/unavailable evidence on either side always yields `unknown`,
+ * never `equivalent` and never a false `different`.
+ */
+export function compareIncrementalChangeStalenessSourceStates(left, right) {
+    const reasons = [];
+    if (left.status !== "complete") {
+        reasons.push(`left source state is unavailable${left.reason ? `: ${left.reason}` : "."}`);
+    }
+    if (right.status !== "complete") {
+        reasons.push(`right source state is unavailable${right.reason ? `: ${right.reason}` : "."}`);
+    }
+    if (reasons.length > 0) {
+        return { result: "unknown", reasons };
+    }
+    const leftRoots = [...left.sourceRoots].sort();
+    const rightRoots = [...right.sourceRoots].sort();
+    if (leftRoots.length !== rightRoots.length || leftRoots.some((root, index) => root !== rightRoots[index])) {
+        return {
+            result: "different",
+            reasons: [`source-root contract differs: left=${JSON.stringify(leftRoots)} right=${JSON.stringify(rightRoots)}`]
+        };
+    }
+    const leftByPath = new Map(left.files.map((file) => [file.relativePath, file.sha256]));
+    const rightByPath = new Map(right.files.map((file) => [file.relativePath, file.sha256]));
+    const differences = [];
+    for (const [relativePath, sha256] of leftByPath) {
+        if (!rightByPath.has(relativePath)) {
+            differences.push(`only on left: ${relativePath}`);
+        }
+        else if (rightByPath.get(relativePath) !== sha256) {
+            differences.push(`content differs: ${relativePath}`);
+        }
+    }
+    for (const relativePath of rightByPath.keys()) {
+        if (!leftByPath.has(relativePath)) {
+            differences.push(`only on right: ${relativePath}`);
+        }
+    }
+    if (differences.length > 0) {
+        return { result: "different", reasons: differences };
+    }
+    return { result: "equivalent", reasons: [] };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * v0.6.2 Batch 3 in-memory lifecycle session schema version. This is the
+ * runtime handoff contract Batch 4 consumes for treatment execution; it is
+ * NOT a persisted artifact and carries full graph evidence only in memory.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_SCHEMA_VERSION = "1.0.0";

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

@@ -1,2 +1,3 @@
 export * from "./contextStrategyComparison/index.js";
+export * from "./incrementalChangeStaleness/index.js";
 export * from "./warmIndexReuse/index.js";

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

@@ -1,3 +1,4 @@
+import { toAffectedNeighborhoodMetricValues } from "../../../evaluation/affectedNeighborhoodMetrics.js";
 // ---------------------------------------------------------------------------
 // Warm-index metric owner. Every warm-index formula (amortization, cumulative
 // prefix sums, availability) is calculated here exactly once, as a pure
@@ -194,32 +195,28 @@ function warmDirect(task) {
     };
 }
 const NO_AFFECTED_NEIGHBORHOOD_REASON = "No affected-neighborhood assessment was recorded for this task.";
+function wrapAffectedNeighborhoodMetricValue(value) {
+    return value.availability === "available"
+        ? availableMetric(value.value, value.unit, "derived")
+        : unavailableMetric(value.unit, "derived", value.reason);
+}
 /**
  * Converts the persisted affected-neighborhood assessment into the six warm-side metrics, once.
  * A finite value (including zero) is available; an absent assessment or a null field is
- * unavailable with a reason, never zero. The metric layer alone owns these value objects.
+ * unavailable with a reason, never zero. The formula itself is owned by the shared
+ * `toAffectedNeighborhoodMetricValues` (src/evaluation/affectedNeighborhoodMetrics.ts, extracted in
+ * v0.6.2 Batch 4 for reuse by incremental-change-staleness); this function only wraps its bounded
+ * values into the warm-index `WarmIndexNumberMetricV1` envelope.
  */
 function affectedNeighborhoodMetrics(task) {
-    const assessment = task.affectedNeighborhood;
-    const one = (field, label) => {
-        const unit = field === "taskOverlapPercent" ? "percent" : "count";
-        if (!assessment)
-            return unavailableMetric(unit, "derived", NO_AFFECTED_NEIGHBORHOOD_REASON);
-        const value = assessment[field];
-        if (typeof value === "number")
-            return availableMetric(value, unit, "derived");
-        const context = `assessment ${assessment.status}; seed mapping ${assessment.seedMappingStatus}; ` +
-            `graph ${assessment.graphEvidenceStatus}; neighborhood ${assessment.neighborhoodStatus}; task mapping ${assessment.taskMapping.status}` +
-            (field === "taskOverlapPercent" ? `; resolvable task nodes ${assessment.taskMapping.resolvableTaskNodeCount}` : "");
-        return unavailableMetric(unit, "derived", `Affected-neighborhood evidence did not establish ${label} (${context}).`);
-    };
+    const values = toAffectedNeighborhoodMetricValues(task.affectedNeighborhood, NO_AFFECTED_NEIGHBORHOOD_REASON);
     return {
-        changedFileCount: one("changedFileCount", "the changed indexed file count"),
-        changedSymbolCount: one("changedSymbolCount", "the changed baseline symbol count"),
-        affectedNodeCount: one("affectedNodeCount", "the affected graph node count"),
-        affectedEdgeCount: one("affectedEdgeCount", "the affected graph edge count"),
-        taskOverlapCount: one("taskOverlapCount", "the task-overlap node count"),
-        taskOverlapPercent: one("taskOverlapPercent", "the task-overlap percent"),
+        changedFileCount: wrapAffectedNeighborhoodMetricValue(values.changedFileCount),
+        changedSymbolCount: wrapAffectedNeighborhoodMetricValue(values.changedSymbolCount),
+        affectedNodeCount: wrapAffectedNeighborhoodMetricValue(values.affectedNodeCount),
+        affectedEdgeCount: wrapAffectedNeighborhoodMetricValue(values.affectedEdgeCount),
+        taskOverlapCount: wrapAffectedNeighborhoodMetricValue(values.taskOverlapCount),
+        taskOverlapPercent: wrapAffectedNeighborhoodMetricValue(values.taskOverlapPercent)
     };
 }
 /** Pure, order-preserving calculation; ordinals and cumulative state restart for every project. */

package/dist/src/report/experiments/buildIncrementalChangeStalenessReport.js

@@ -0,0 +1,112 @@
+// v0.6.2 Batch 5 -- projects the persisted Batch 4 incremental-change-staleness-execution.json
+// artifact into the plugin report model. This is a deterministic projection only: no retrieval,
+// no fake-agent evaluation, no correctness scoring, no affected-neighborhood assessment, no
+// freshness assessment, no stale-risk classification, and no source/index/benchmark reads happen
+// here. The persisted artifact is the only plugin-specific evidence source (frozen batch plan
+// Section 4); this file's only I/O is reading that one JSON file.
+import { readFileSync } from "node:fs";
+import { INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION } from "../../experiments/plugins/incrementalChangeStaleness/executionArtifact.js";
+import { INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID } from "../../experiments/plugins/incrementalChangeStaleness/plugin.js";
+import { INCREMENTAL_CHANGE_STALENESS_REPORT_SCHEMA_VERSION } from "./incrementalChangeStalenessReportModel.js";
+// Frozen wording (Section 25). Every point must appear in report.txt and report.html.
+const LIMITATIONS = [
+    "Results are scoped to the executed benchmark scenarios, deterministic controlled changes, configured my-dev-kit version, and observed retrieval/evaluation evidence.",
+    "\"no-observed-stale-regression\" means only that the frozen comparison did not observe a stale-specific regression in that matched run. It does not prove stale indexes are generally safe.",
+    "\"reindexRecommendation\" is separate affected-neighborhood observational evidence; it did not select or trigger either experiment treatment.",
+    "Required-file evidence is a bounded answer-key file-presence check, not retrieval precision/recall.",
+    "Correctness is deterministic fake-agent/harness evidence unless a future version explicitly adds real-agent evidence.",
+    "v0.6.2 compares stale full-index reuse with complete full refresh only.",
+    "Partial refresh is not evaluated in v0.6.2.",
+    "The experiment does not use graph-diff.",
+    "\"changedSymbolCount\" does not mean source-level symbol-diff proof; it retains the released v0.6.1 definition."
+];
+/** Fixed neutral wording per stale-risk classification category (Section 21). Presentation only. */
+export const STALE_RISK_CLASSIFICATION_EXPLANATIONS = {
+    "observed-stale-regression": "The persisted matched comparison observed at least one stale-specific regression under the frozen v0.6.2 evidence dimensions: correctness and/or required-file presence.",
+    "no-observed-stale-regression": "This matched scenario/run did not observe a stale-specific regression under the frozen correctness and required-file evidence dimensions. This does not establish general stale-index safety and does not imply that reindexing should be skipped.",
+    inconclusive: "Available persisted evidence was insufficient to determine whether a stale-specific regression occurred under the frozen comparison rules. Inconclusive is not the same as no regression."
+};
+/**
+ * Builds the plugin report section for an incremental-change-staleness run, or `null` for any
+ * other plugin. Every field is a deterministic projection of the persisted Batch 4 execution
+ * artifact; this function performs no scientific recomputation of its own.
+ */
+export function buildIncrementalChangeStalenessReport(run) {
+    if (run.pluginId !== INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID)
+        return null;
+    const artifact = loadExecutionArtifact(run);
+    const scenarios = artifact.scenarios.map(toReportScenario);
+    return {
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_REPORT_SCHEMA_VERSION,
+        pluginId: artifact.pluginId,
+        scenarioCount: artifact.summary.scenarioCount,
+        readyScenarioCount: artifact.summary.readyScenarioCount,
+        failedScenarioCount: artifact.summary.failedScenarioCount,
+        observedStaleRegressionCount: artifact.summary.observedStaleRegressionCount,
+        noObservedStaleRegressionCount: artifact.summary.noObservedStaleRegressionCount,
+        inconclusiveCount: artifact.summary.inconclusiveCount,
+        scenarios,
+        limitations: [...LIMITATIONS]
+    };
+}
+function toReportScenario(record) {
+    return {
+        scenarioId: record.scenarioId,
+        category: record.category,
+        benchmarkProjectId: record.benchmarkProjectId,
+        baseCaseId: record.baseCaseId,
+        status: record.status,
+        failureReason: record.failureReason,
+        query: record.query,
+        answerPolicy: record.answerPolicy,
+        expectedFiles: [...record.expectedFiles],
+        expectedSymbols: [...record.expectedSymbols],
+        lifecycle: record.lifecycle
+            ? {
+                ...record.lifecycle,
+                controlledFilePaths: [...record.lifecycle.controlledFilePaths],
+                sourceRoots: [...record.lifecycle.sourceRoots]
+            }
+            : null,
+        // Section 12/34: always stale-index then full-refresh, never combined, never resorted.
+        staleTreatment: record.stale ? structuredClone(record.stale) : null,
+        fullRefreshTreatment: record.fullRefresh ? structuredClone(record.fullRefresh) : null,
+        comparison: { ...record.comparison, reasonCodes: [...record.comparison.reasonCodes] }
+    };
+}
+function readArtifactPath(run) {
+    const fromMetadata = run.metadata?.executionArtifactPath;
+    if (typeof fromMetadata === "string" && fromMetadata)
+        return fromMetadata;
+    return run.artifacts.find((artifact) => artifact.id === "incremental-change-staleness-execution")?.path ?? undefined;
+}
+/**
+ * The persisted execution artifact is the sole plugin-specific evidence source for this report
+ * (Section 4/46). A missing, unreadable, malformed, or schema-mismatched artifact is a report
+ * construction error, never silently reconstructed from source/index/retrieval state.
+ */
+function loadExecutionArtifact(run) {
+    const artifactPath = readArtifactPath(run);
+    if (!artifactPath) {
+        throw new Error("Invalid incremental-change-staleness report source: no execution artifact path was found on the run.");
+    }
+    let raw;
+    try {
+        raw = readFileSync(artifactPath, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Invalid incremental-change-staleness report source: execution artifact could not be read at ${artifactPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid incremental-change-staleness report source: execution artifact at ${artifactPath} is not valid JSON.`);
+    }
+    const candidate = parsed;
+    if (candidate.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION) {
+        throw new Error(`Invalid incremental-change-staleness report source: unsupported execution artifact schema version ${String(candidate.schemaVersion)}.`);
+    }
+    return candidate;
+}

package/dist/src/report/experiments/buildPluginExperimentReport.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { buildContextStrategyComparisonV043Report } from "./buildContextStrategyComparisonV043Report.js";
 import { buildWarmIndexReuseReport } from "./buildWarmIndexReuseReport.js";
+import { buildIncrementalChangeStalenessReport } from "./buildIncrementalChangeStalenessReport.js";
 const V043_BULK_ARRAY_KEYS = [
     "v043StageContextExecutions",
     "v043StageContextEvaluations",
@@ -11,6 +12,7 @@ export function buildPluginExperimentReport(args) {
     const allOutcomes = args.run.cases.flatMap((experimentCase) => experimentCase.outcomes);
     const contextStrategyComparisonV043 = buildContextStrategyComparisonV043Report(args.run);
     const warmIndexReuse = buildWarmIndexReuseReport(args.run);
+    const incrementalChangeStaleness = buildIncrementalChangeStalenessReport(args.run);
     const rawRun = { ...args.run, artifacts: relativizeArtifacts(args.run.artifacts, outputRoot) };
     for (const key of V043_BULK_ARRAY_KEYS) {
         delete rawRun[key];
@@ -39,6 +41,7 @@ export function buildPluginExperimentReport(args) {
         skippedOutcomes: allOutcomes.filter((outcome) => outcome.status === "skipped"),
         findings: buildFindings(args.run),
         warmIndexReuse,
+        incrementalChangeStaleness,
         contextStrategyComparisonV043,
         interpretation: buildInterpretation(args.run, contextStrategyComparisonV043, warmIndexReuse),
         rawRun,

package/dist/src/report/experiments/incrementalChangeStalenessReportModel.js

@@ -0,0 +1,4 @@
+// v0.6.2 Batch 5 -- plugin-specific presentation model types only. No projection logic, no HTML,
+// no text rendering, and no recomputation live here; see buildIncrementalChangeStalenessReport.ts
+// and renderIncrementalChangeStalenessHtml.ts for those responsibilities.
+export const INCREMENTAL_CHANGE_STALENESS_REPORT_SCHEMA_VERSION = "my-dev-kit-lab-incremental-change-staleness-report-v1";

package/dist/src/report/experiments/index.js

@@ -14,3 +14,6 @@ export { buildContextIntegrityReport } from "./buildContextIntegrityReport.js";
 export { renderContextIntegrityJsonReport } from "./renderContextIntegrityJsonReport.js";
 export { renderContextIntegrityText } from "./renderContextIntegrityText.js";
 export { renderContextIntegrityHtml } from "./renderContextIntegrityHtml.js";
+export * from "./incrementalChangeStalenessReportModel.js";
+export { buildIncrementalChangeStalenessReport, STALE_RISK_CLASSIFICATION_EXPLANATIONS } from "./buildIncrementalChangeStalenessReport.js";
+export { renderIncrementalChangeStalenessHtml } from "./renderIncrementalChangeStalenessHtml.js";