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

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

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/incrementalChangeStaleness/treatmentSessionV2.js

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

package/dist/src/experiments/plugins/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/experiments/plugins/warmIndexReuse/warmIndexSession.js

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

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

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

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

@@ -1,4 +1,5 @@
-import { createHash } from "node:crypto";
+import { scryptSync } from "node:crypto";
+import path from "node:path";
 import { stripUnsafeControlChars } from "../../../securityValidation/attackScenarios/exploitEvidence.js";
 // ---------------------------------------------------------------------------
 // v0.4.1 Batch 1 — redaction and fingerprint primitives for later Android
@@ -13,8 +14,8 @@ import { stripUnsafeControlChars } from "../../../securityValidation/attackScena
 // payload). Android candidate evidence has a different, narrower need: a
 // human reviewing a static-candidate finding benefits from a short prefix/
 // suffix so they can recognize *which* secret in their own source it is
-// without the full value ever being reconstructable — so this module adds
-// that prefix/suffix-preserving preview and a non-reversible fingerprint on
+// without retaining the full value — so this module adds that
+// prefix/suffix-preserving preview and a one-way fingerprint on
 // top of the shared control-character stripping, instead of creating a
 // second, competing full-redaction implementation.
 // ---------------------------------------------------------------------------
@@ -42,13 +43,21 @@ export function redactedPreviewForCandidate(input, options = {}) {
     const suffix = bounded.slice(-edgeLength);
     return `${prefix}${MASK}${suffix}`;
 }
-// Stable, non-reversible fingerprint for deduplication. Uses Node's built-in
-// sha256 (no new dependency). Distinct from redactedPreviewForCandidate: the
-// fingerprint is stored for dedup, the preview is stored for human review —
-// neither one can be used to recover the raw value.
-export function fingerprintCandidateValue(input) {
+// Deterministic, one-way evidence identity. Scrypt makes guessing more costly
+// than a fast hash, but low-entropy values are not cryptographically
+// unrecoverable. The context salt separates equivalent values at distinct
+// evidence locations without storing a secret salt or the raw value.
+export function fingerprintCandidateValue(input, context) {
     if (input === undefined)
         return "unavailable";
-    const hash = createHash("sha256").update(input, "utf8").digest("hex");
-    return `sha256:${hash}`;
+    const contextSalt = Buffer.from(JSON.stringify([
+        "my-dev-kit-lab/android-candidate-fingerprint/v2",
+        context.ruleId,
+        path.posix.normalize(context.sourcePath.replaceAll("\\", "/")),
+        context.line ?? null,
+        context.column ?? null,
+        context.purpose
+    ]), "utf8");
+    const derived = scryptSync(input, contextSalt, 32, { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+    return `scrypt-v1:${derived.toString("hex")}`;
 }

package/dist/src/mobile/android/advancedSecurity/secretCandidates/analyzeSecretCandidates.js

@@ -51,7 +51,6 @@ export function analyzeSecretCandidateFile(targetRoot, file) {
     const fileKind = fileKindFor(file.relativePath);
     for (const block of matchPrivateKeyBlocks(file.content)) {
         const location = buildAndroidSourceLocation(targetRoot, file.absolutePath, { line: block.line });
-        const fingerprint = fingerprintCandidateValue(block.rawBlock);
         if (!block.terminated) {
             candidates.push(makeCandidateEvidence({
                 ruleId: "android-secret-private-key-candidate",
@@ -66,6 +65,12 @@ export function analyzeSecretCandidateFile(targetRoot, file) {
             }));
             continue;
         }
+        const fingerprint = fingerprintCandidateValue(block.rawBlock, {
+            ruleId: "android-secret-private-key-candidate",
+            sourcePath: location.path,
+            line: location.line,
+            purpose: "private-key-finding"
+        });
         findings.push(makeAndroidFinding({
             ruleId: "android-secret-private-key-candidate",
             title: `Private key material found (${block.headerLabel})`,
@@ -98,7 +103,12 @@ export function analyzeSecretCandidateFile(targetRoot, file) {
             }));
             continue;
         }
-        const fingerprint = fingerprintCandidateValue(match.rawValue);
+        const fingerprint = fingerprintCandidateValue(match.rawValue, {
+            ruleId: classification.ruleId,
+            sourcePath: location.path,
+            line: location.line,
+            purpose: `credential-finding:${classification.sensitiveDataCategory}`
+        });
         findings.push(makeAndroidFinding({
             ruleId: classification.ruleId,
             title: `Hardcoded ${match.identifier} literal found`,

package/dist/src/mobile/android/advancedSecurity/signingConfiguration/analyzeSigningConfiguration.js

@@ -149,7 +149,7 @@ export function analyzeModuleSigningConfiguration(targetRoot, gradleModule, buil
     const buildFileRelativePath = gradleModule.buildFilePath ?? modulePath;
     const buildFileAbsolutePath = path.join(targetRoot, buildFileRelativePath);
     const location = loc(targetRoot, buildFileAbsolutePath);
-    const signingConfigs = extractSigningConfigurations(buildFileText);
+    const signingConfigs = extractSigningConfigurations(buildFileText, { sourcePath: location.path });
     const literalCredentialConfigNames = new Set();
     for (const config of signingConfigs) {
         const storePasswordResult = analyzeCredential("storePassword", config.storePassword, config.name, modulePath, location, buildFileRelativePath);