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

package/dist/src/evaluation/affectedNeighborhoodMetrics.js

@@ -0,0 +1,51 @@
+const FIELD_LABELS = {
+    changedFileCount: "the changed indexed file count",
+    changedSymbolCount: "the changed baseline symbol count",
+    affectedNodeCount: "the affected graph node count",
+    affectedEdgeCount: "the affected graph edge count",
+    taskOverlapCount: "the task-overlap node count",
+    taskOverlapPercent: "the task-overlap percent"
+};
+/**
+ * Converts a persisted (or in-memory) affected-neighborhood assessment into the six frozen v0.6.1
+ * metrics, once. A finite value (including zero) is available; a missing assessment or a null
+ * field is unavailable with a bounded reason, never zero. Pure; this is the ONLY owner of this
+ * conversion, reused unchanged by every caller.
+ */
+export function toAffectedNeighborhoodMetricValues(assessment, noAssessmentReason) {
+    const one = (field) => {
+        const unit = field === "taskOverlapPercent" ? "percent" : "count";
+        if (!assessment) {
+            return { availability: "unavailable", value: null, unit, reason: noAssessmentReason };
+        }
+        const value = assessment[field];
+        if (typeof value === "number") {
+            return { availability: "available", value, unit, reason: null };
+        }
+        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 {
+            availability: "unavailable",
+            value: null,
+            unit,
+            reason: `Affected-neighborhood evidence did not establish ${FIELD_LABELS[field]} (${context}).`
+        };
+    };
+    return {
+        changedFileCount: one("changedFileCount"),
+        changedSymbolCount: one("changedSymbolCount"),
+        affectedNodeCount: one("affectedNodeCount"),
+        affectedEdgeCount: one("affectedEdgeCount"),
+        taskOverlapCount: one("taskOverlapCount"),
+        taskOverlapPercent: one("taskOverlapPercent")
+    };
+}
+export const AFFECTED_NEIGHBORHOOD_METRIC_FIELDS = [
+    "changedFileCount",
+    "changedSymbolCount",
+    "affectedNodeCount",
+    "affectedEdgeCount",
+    "taskOverlapCount",
+    "taskOverlapPercent"
+];

package/dist/src/evaluation/benchmarkMetadata.js

@@ -280,7 +280,11 @@ function validateWarmIndexSourceRoots(sourceRoots, profile, label) {
     return errors;
 }
 function normalizeRelativeRoot(value) {
-    return path.posix.normalize(value.replace(/\\/g, "/")).replace(/\/+$/, "");
+    const normalized = path.posix.normalize(value.replaceAll("\\", "/"));
+    let end = normalized.length;
+    while (end > 0 && normalized[end - 1] === "/")
+        end -= 1;
+    return normalized.slice(0, end);
 }
 function sameOrderedValues(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);

package/dist/src/evaluation/parseAgentAnswer.js

@@ -77,11 +77,24 @@ function collectJsonCandidates(text) {
     if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
         candidates.push(trimmed);
     }
-    for (const match of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)) {
-        const body = match[1]?.trim();
+    let cursor = 0;
+    while (cursor < text.length) {
+        const opening = text.indexOf("```", cursor);
+        if (opening < 0)
+            break;
+        let bodyStart = opening + 3;
+        if (text.slice(bodyStart, bodyStart + 4).toLowerCase() === "json")
+            bodyStart += 4;
+        while (bodyStart < text.length && isWhitespace(text[bodyStart]))
+            bodyStart += 1;
+        const closing = text.indexOf("```", bodyStart);
+        if (closing < 0)
+            break;
+        const body = text.slice(bodyStart, closing).trim();
         if (body?.startsWith("{")) {
             candidates.push(body);
         }
+        cursor = closing + 3;
     }
     return candidates;
 }
@@ -89,39 +102,103 @@ function collectFieldValues(text) {
     const fields = new Map();
     let currentKey;
     for (const line of text.split(/\r?\n/)) {
-        const fieldMatch = line.match(/^\s*(?:[-*]\s*)?(?:[*_`]{0,2})([A-Za-z][A-Za-z0-9 _-]{1,40})(?:[*_`]{0,2})\s*:\s*(.*)$/);
-        if (fieldMatch) {
-            currentKey = normalizeKey(fieldMatch[1]);
+        const field = parseStructuredFieldLine(line);
+        if (field) {
+            currentKey = normalizeKey(field.label);
             const current = fields.get(currentKey) ?? [];
-            current.push(stripMarkupOnlyValue(fieldMatch[2] ?? ""));
+            current.push(stripMarkupOnlyValue(field.value));
             fields.set(currentKey, current);
             continue;
         }
-        if (currentKey && (/^\s+[-*]?\s*\S/.test(line) || /^\s*[-*]\s+\S/.test(line))) {
-            fields.get(currentKey)?.push(line.trim().replace(/^[-*]\s*/, ""));
+        if (currentKey) {
+            const continuation = parseFieldContinuation(line);
+            if (continuation !== undefined)
+                fields.get(currentKey)?.push(continuation);
         }
     }
     return fields;
 }
+function isWhitespace(character) {
+    return character.trim().length === 0;
+}
+function parseStructuredFieldLine(line) {
+    let start = 0;
+    while (start < line.length && isWhitespace(line[start]))
+        start += 1;
+    if (line[start] === "-" || line[start] === "*") {
+        start += 1;
+        while (start < line.length && isWhitespace(line[start]))
+            start += 1;
+    }
+    let leadingMarkup = 0;
+    while (start < line.length && leadingMarkup < 2 && "*_`".includes(line[start])) {
+        start += 1;
+        leadingMarkup += 1;
+    }
+    const colon = line.indexOf(":", start);
+    if (colon < 0)
+        return undefined;
+    let labelEnd = colon;
+    let trailingMarkup = 0;
+    while (labelEnd > start && trailingMarkup < 2 && "*_`".includes(line[labelEnd - 1])) {
+        labelEnd -= 1;
+        trailingMarkup += 1;
+    }
+    const label = line.slice(start, labelEnd);
+    if (label.length < 2 || label.length > 41 || !isAsciiLetter(label[0]))
+        return undefined;
+    for (let index = 1; index < label.length; index += 1) {
+        const character = label[index];
+        if (!isAsciiLetter(character) && !(character >= "0" && character <= "9") && character !== " " && character !== "_" && character !== "-")
+            return undefined;
+    }
+    let valueStart = colon + 1;
+    while (valueStart < line.length && isWhitespace(line[valueStart]))
+        valueStart += 1;
+    return { label, value: line.slice(valueStart) };
+}
+function isAsciiLetter(character) {
+    return (character >= "a" && character <= "z") || (character >= "A" && character <= "Z");
+}
+function parseFieldContinuation(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const indented = index > 0;
+    if (index === line.length)
+        return undefined;
+    if (line[index] === "-" || line[index] === "*") {
+        index += 1;
+        const whitespaceStart = index;
+        while (index < line.length && isWhitespace(line[index]))
+            index += 1;
+        if ((!indented && index === whitespaceStart) || index === line.length)
+            return undefined;
+        return line.slice(index).trim();
+    }
+    if (!indented)
+        return undefined;
+    return line.slice(index).trim();
+}
 function parseMarkdownSection(text, headings) {
     const lines = text.split(/\r?\n/);
     const values = [];
     let inSection = false;
     for (const line of lines) {
-        const heading = line.match(/^\s*#{1,6}\s*(.+?)\s*$/);
-        if (heading) {
-            inSection = headings.some((candidate) => normalizeKey(candidate) === normalizeKey(heading[1]));
+        const heading = parseMarkdownHeading(line);
+        if (heading !== undefined) {
+            inSection = headings.some((candidate) => normalizeKey(candidate) === normalizeKey(heading));
             continue;
         }
         if (!inSection) {
             continue;
         }
-        if (/^\s*#{1,6}\s+/.test(line)) {
+        if (isMarkdownHeading(line)) {
             break;
         }
-        const bullet = line.match(/^\s*[-*]\s+(.+)$/);
-        if (bullet) {
-            values.push(bullet[1].trim());
+        const bullet = parseMarkdownBullet(line);
+        if (bullet !== undefined) {
+            values.push(bullet);
         }
         else if (line.includes(",")) {
             values.push(...splitListValues([line]));
@@ -129,6 +206,41 @@ function parseMarkdownSection(text, headings) {
     }
     return unique(values);
 }
+function parseMarkdownHeading(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const hashStart = index;
+    while (index < line.length && line[index] === "#" && index - hashStart < 6)
+        index += 1;
+    if (index === hashStart || (index < line.length && line[index] === "#"))
+        return undefined;
+    const heading = line.slice(index).trim();
+    return heading.length > 0 ? heading : undefined;
+}
+function isMarkdownHeading(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const start = index;
+    while (index < line.length && line[index] === "#" && index - start < 6)
+        index += 1;
+    return index > start && index < line.length && isWhitespace(line[index]);
+}
+function parseMarkdownBullet(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    if (line[index] !== "-" && line[index] !== "*")
+        return undefined;
+    index += 1;
+    if (index >= line.length || !isWhitespace(line[index]))
+        return undefined;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const content = line.slice(index).trim();
+    return content.length > 0 ? content : undefined;
+}
 function enrichFacts(parsed, text, answerKey) {
     parsed.expectedFactsFound = normalizeFactMatches(parsed.expectedFactsFound, text, answerKey);
     if (parsed.answerText.length === 0) {
@@ -168,15 +280,51 @@ function splitListValues(values) {
         .filter(Boolean));
 }
 function cleanListItem(value) {
-    const codeSpan = value.match(/`([^`]+)`/);
-    const cleaned = (codeSpan?.[1] ?? value)
-        .trim()
-        .replace(/^[-*]\s*/, "")
-        .replace(/^["'`]+|["'`.]+$/g, "")
-        .replace(/\s+[--]\s+.*$/g, "")
-        .replace(/\s+[-–—]\s+.*$/g, "")
-        .trim();
-    return cleaned;
+    let source = value;
+    let searchFrom = 0;
+    while (searchFrom < value.length) {
+        const open = value.indexOf("`", searchFrom);
+        if (open < 0)
+            break;
+        const close = value.indexOf("`", open + 1);
+        if (close < 0)
+            break;
+        if (close > open + 1) {
+            source = value.slice(open + 1, close);
+            break;
+        }
+        searchFrom = close + 1;
+    }
+    let start = 0;
+    let end = source.length;
+    while (start < end && isWhitespace(source[start]))
+        start += 1;
+    while (end > start && isWhitespace(source[end - 1]))
+        end -= 1;
+    if (source[start] === "-" || source[start] === "*") {
+        start += 1;
+        while (start < end && isWhitespace(source[start]))
+            start += 1;
+    }
+    while (start < end && (source[start] === '"' || source[start] === "'" || source[start] === "`"))
+        start += 1;
+    while (end > start && (source[end - 1] === '"' || source[end - 1] === "'" || source[end - 1] === "`" || source[end - 1] === "."))
+        end -= 1;
+    let whitespaceStart = -1;
+    for (let index = start; index < end; index += 1) {
+        const character = source[index];
+        if (isWhitespace(character)) {
+            if (whitespaceStart < 0)
+                whitespaceStart = index;
+            continue;
+        }
+        if ((character === "-" || character === "–" || character === "—") && whitespaceStart >= start && index + 1 < end && isWhitespace(source[index + 1])) {
+            end = whitespaceStart;
+            break;
+        }
+        whitespaceStart = -1;
+    }
+    return source.slice(start, end).trim();
 }
 function stripMarkupOnlyValue(value) {
     return /^[*_`\s]+$/.test(value) ? "" : value;

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -55,13 +55,118 @@ function skippedRetrieval(caseId, warnings, commands, durationMs) {
         durationMs
     };
 }
+const APPLIED_SCOPES = ["none", "changed-files", "affected-neighborhood", "full"];
+const SELECTION_STATUSES = ["not-needed", "applied", "fallback-full"];
+const NEIGHBORHOOD_COUNT_KEYS = ["seedFileCount", "seedSymbolCount", "affectedNodeCount", "affectedEdgeCount"];
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/**
+ * Validates the per-invocation `incrementalRefresh` object from `my-dev-kit index --incremental --json`
+ * stdout against the scope Lab requested. Returns validated evidence or an explicit error; never coerces.
+ * The fallback reason is intentionally an open string: upstream reason codes may evolve additively.
+ */
+export function parseIncrementalRefreshEvidence(stdout, requestedScope) {
+    const payload = parseJsonIfPossible(stdout);
+    if (payload === undefined)
+        return { ok: false, error: "index stdout is not valid JSON" };
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return { ok: false, error: "index JSON result is not an object" };
+    }
+    const raw = payload.incrementalRefresh;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: "index JSON result has no incrementalRefresh object" };
+    }
+    const r = raw;
+    if (r.requestedScope !== requestedScope) {
+        return {
+            ok: false,
+            error: `incrementalRefresh.requestedScope ${JSON.stringify(r.requestedScope)} does not match requested scope ${requestedScope}`
+        };
+    }
+    if (!APPLIED_SCOPES.includes(r.appliedScope)) {
+        return { ok: false, error: `incrementalRefresh.appliedScope ${JSON.stringify(r.appliedScope)} is not a known value` };
+    }
+    if (!SELECTION_STATUSES.includes(r.selectionStatus)) {
+        return { ok: false, error: `incrementalRefresh.selectionStatus ${JSON.stringify(r.selectionStatus)} is not a known value` };
+    }
+    if (r.fallbackReason !== null && typeof r.fallbackReason !== "string") {
+        return { ok: false, error: "incrementalRefresh.fallbackReason must be a string or null" };
+    }
+    for (const key of NEIGHBORHOOD_COUNT_KEYS) {
+        if (r[key] !== null && !isNonNegativeInteger(r[key])) {
+            return { ok: false, error: `incrementalRefresh.${key} must be a non-negative integer or null` };
+        }
+    }
+    for (const key of ["forcedNeighborReanalysisFileCount", "freshExtractionFileCount", "reusedFileCount"]) {
+        if (!isNonNegativeInteger(r[key])) {
+            return { ok: false, error: `incrementalRefresh.${key} must be a non-negative integer` };
+        }
+    }
+    if (!Array.isArray(r.forcedNeighborSample) || r.forcedNeighborSample.some((item) => typeof item !== "string")) {
+        return { ok: false, error: "incrementalRefresh.forcedNeighborSample must be an array of strings" };
+    }
+    const appliedScope = r.appliedScope;
+    const selectionStatus = r.selectionStatus;
+    const fallbackReason = r.fallbackReason;
+    if (selectionStatus === "applied") {
+        if (appliedScope !== requestedScope) {
+            return { ok: false, error: "incrementalRefresh applied status requires appliedScope equal to requestedScope" };
+        }
+        if (fallbackReason !== null)
+            return { ok: false, error: "incrementalRefresh applied status requires a null fallbackReason" };
+    }
+    else if (selectionStatus === "fallback-full") {
+        if (appliedScope !== "full")
+            return { ok: false, error: "incrementalRefresh fallback-full status requires appliedScope full" };
+        if (fallbackReason === null || fallbackReason.length === 0) {
+            return { ok: false, error: "incrementalRefresh fallback-full status requires a nonempty fallbackReason" };
+        }
+    }
+    else {
+        if (appliedScope !== "none")
+            return { ok: false, error: "incrementalRefresh not-needed status requires appliedScope none" };
+        if (fallbackReason !== null)
+            return { ok: false, error: "incrementalRefresh not-needed status requires a null fallbackReason" };
+    }
+    if (requestedScope === "affected-neighborhood" && selectionStatus === "applied") {
+        for (const key of NEIGHBORHOOD_COUNT_KEYS) {
+            if (r[key] === null) {
+                return { ok: false, error: `incrementalRefresh.${key} must be numeric for an applied affected-neighborhood refresh` };
+            }
+        }
+    }
+    return {
+        ok: true,
+        evidence: {
+            requestedScope,
+            appliedScope,
+            selectionStatus,
+            fallbackReason,
+            seedFileCount: r.seedFileCount,
+            seedSymbolCount: r.seedSymbolCount,
+            affectedNodeCount: r.affectedNodeCount,
+            affectedEdgeCount: r.affectedEdgeCount,
+            forcedNeighborReanalysisFileCount: r.forcedNeighborReanalysisFileCount,
+            forcedNeighborSample: [...r.forcedNeighborSample],
+            freshExtractionFileCount: r.freshExtractionFileCount,
+            reusedFileCount: r.reusedFileCount
+        }
+    };
+}
 /**
  * Runs exactly one my-dev-kit `index` command for the target and writes the index only to
  * `indexDir`. Performs no search/lookup/slice/source work. With `requireKit` a failed index
  * throws; otherwise the failure is returned as `ok: false` with a warning.
+ *
+ * `mode` defaults to a full index. An incremental mode adds `--incremental --refresh-scope <scope>`
+ * and requires valid per-invocation `incrementalRefresh` JSON evidence on stdout; a successful
+ * process without that evidence is not a usable incremental build. Upstream full-fallback and
+ * no-change outcomes are valid evidence and are returned as-is.
  */
 export async function buildMyDevKitIndex(options) {
     const warnings = [];
+    const mode = options.mode ?? { kind: "full" };
     const command = await runMeasuredCommand({
         commandId: "index",
         commandString: options.kitCommand,
@@ -74,22 +179,30 @@ export async function buildMyDevKitIndex(options) {
             ...options.target.sourceRoots.flatMap((sourceRoot) => ["--src", sourceRoot]),
             "--out",
             options.indexDir,
+            ...(mode.kind === "incremental" ? ["--incremental", "--refresh-scope", mode.refreshScope] : []),
             "--json"
         ]
     });
+    const result = { indexDir: options.indexDir, durationMs: command.durationMs, command, mode };
     if (!command.ok) {
         if (options.requireKit) {
             throw new Error(command.error || `my-dev-kit index failed with exit code ${command.exitCode}`);
         }
         warnings.push("my-dev-kit index command was unavailable or failed.");
+        return { ...result, ok: false, warnings, incrementalRefresh: null };
     }
-    return {
-        ok: command.ok,
-        indexDir: options.indexDir,
-        durationMs: command.durationMs,
-        warnings,
-        command
-    };
+    if (mode.kind === "full") {
+        return { ...result, ok: true, warnings, incrementalRefresh: null };
+    }
+    const parsed = parseIncrementalRefreshEvidence(command.stdout, mode.refreshScope);
+    if (!parsed.ok) {
+        const message = `my-dev-kit incremental index (${mode.refreshScope}) returned no valid incrementalRefresh evidence: ${parsed.error}`;
+        if (options.requireKit)
+            throw new Error(message);
+        warnings.push(message);
+        return { ...result, ok: false, warnings, incrementalRefresh: null };
+    }
+    return { ...result, ok: true, warnings, incrementalRefresh: parsed.evidence };
 }
 /**
  * Runs `<kit-command> --version` once through the shared measured-command runner and returns

package/dist/src/experiments/defaultRegistry.js

@@ -1,9 +1,11 @@
 import { ExperimentPluginRegistry } from "./registry.js";
 import { contextStrategyComparisonPlugin } from "./plugins/contextStrategyComparison/index.js";
+import { incrementalChangeStalenessPlugin } from "./plugins/incrementalChangeStaleness/index.js";
 import { warmIndexReusePlugin } from "./plugins/warmIndexReuse/index.js";
 export function createDefaultExperimentPluginRegistry() {
     const registry = new ExperimentPluginRegistry();
     registry.register(contextStrategyComparisonPlugin);
     registry.register(warmIndexReusePlugin);
+    registry.register(incrementalChangeStalenessPlugin);
     return registry;
 }

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

@@ -0,0 +1,101 @@
+// v0.6.2 Batch 4 -- pure, deterministic comparison/classification owner.
+//
+// This module owns exactly:
+//  - CorrectnessRelationV1;
+//  - RequiredFileEvidenceStatusV1 / RequiredFileEvidenceV1;
+//  - RequiredFileEvidenceRelationV1;
+//  - StaleRiskClassificationV1;
+//  - the pure functions that compute them.
+//
+// Every function here is a pure, side-effect-free transform over already
+// collected evidence. No retrieval, no filesystem access, no my-dev-kit
+// invocation, and no numeric risk score: see the frozen batch prompt
+// sections 22-35 for the exact rules this file implements.
+/** Section 23: exact correctness comparison rules. */
+export function compareCorrectness(stale, fullRefresh) {
+    if (!stale.available || !fullRefresh.available) {
+        return "unknown";
+    }
+    if (stale.score < fullRefresh.score)
+        return "stale-worse";
+    if (stale.score > fullRefresh.score)
+        return "stale-better";
+    return "same";
+}
+/** Repository-standard forward-slash path normalization, matching existing lifecycle policy. */
+export function normalizeRequiredFilePath(value) {
+    return value.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+}
+function sortedUnique(values) {
+    return [...new Set(values.map(normalizeRequiredFilePath))].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+/**
+ * Section 27: builds one treatment's required-file evidence.
+ *
+ * - `observedFilesComplete: false` means the treatment's actual-files-read set could not be
+ *   established completely (retrieval failed/partial or the contract could not prove completeness);
+ *   the result is always `unknown` in that case, regardless of `observedFiles` contents.
+ * - Otherwise: every normalized required file present in `observedFiles` is `present`; any
+ *   absence is `missing`.
+ */
+export function buildRequiredFileEvidence(args) {
+    const requiredFiles = sortedUnique(args.requiredFiles);
+    const observedFiles = sortedUnique(args.observedFiles);
+    if (!args.observedFilesComplete) {
+        return {
+            status: "unknown",
+            requiredFiles,
+            observedFiles,
+            missingFiles: [],
+            reason: args.unknownReason ?? "Retrieval evidence did not establish a complete actual-files-read set."
+        };
+    }
+    const observedSet = new Set(observedFiles);
+    const missingFiles = requiredFiles.filter((file) => !observedSet.has(file));
+    return {
+        status: missingFiles.length === 0 ? "present" : "missing",
+        requiredFiles,
+        observedFiles,
+        missingFiles,
+        reason: null
+    };
+}
+/** Section 30: exact required-file comparison rules. */
+export function compareRequiredFileEvidence(stale, fullRefresh) {
+    if (stale.status === "unknown" || fullRefresh.status === "unknown") {
+        return "unknown";
+    }
+    if (stale.status === "missing" && fullRefresh.status === "present")
+        return "stale-worse";
+    if (stale.status === "present" && fullRefresh.status === "missing")
+        return "stale-better";
+    return "same";
+}
+/**
+ * Sections 31-35: the frozen precedence algorithm. Correctness and required-file evidence are the
+ * only two inputs; affected-neighborhood evidence and reindexRecommendation are never inputs here.
+ */
+export function classifyStaleRisk(correctnessRelation, requiredFileEvidenceRelation) {
+    const reasonCodes = [];
+    // RULE 1 -- observed regression wins even if the other dimension is unknown.
+    if (correctnessRelation === "stale-worse" || requiredFileEvidenceRelation === "stale-worse") {
+        if (correctnessRelation === "stale-worse")
+            reasonCodes.push("stale-correctness-lower");
+        if (requiredFileEvidenceRelation === "stale-worse")
+            reasonCodes.push("stale-missing-required-file");
+        return { staleRiskClassification: "observed-stale-regression", reasonCodes: dedupe(reasonCodes) };
+    }
+    // RULE 2 -- inconclusive.
+    if (correctnessRelation === "unknown" || requiredFileEvidenceRelation === "unknown") {
+        if (correctnessRelation === "unknown")
+            reasonCodes.push("correctness-unavailable");
+        if (requiredFileEvidenceRelation === "unknown")
+            reasonCodes.push("required-file-evidence-unavailable");
+        return { staleRiskClassification: "inconclusive", reasonCodes: dedupe(reasonCodes) };
+    }
+    // RULE 3 -- no observed regression.
+    return { staleRiskClassification: "no-observed-stale-regression", reasonCodes: ["no-stale-specific-difference-observed"] };
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

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

@@ -0,0 +1,49 @@
+import { compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+function neutral(relation) {
+    if (relation === "stale-worse")
+        return "candidate-worse";
+    if (relation === "stale-better")
+        return "candidate-better";
+    return relation;
+}
+/** Same rules as the v0.6.2 correctness comparison, candidate vs reference. */
+export function compareCandidateCorrectness(candidate, reference) {
+    return neutral(compareCorrectness(candidate, reference));
+}
+/** Same rules as the v0.6.2 required-file comparison, candidate vs reference. */
+export function compareCandidateRequiredFileEvidence(candidate, reference) {
+    return neutral(compareRequiredFileEvidence(candidate, reference));
+}
+/**
+ * Frozen precedence. Rule 0 (realization gate) first: a full fallback is never evidence about
+ * partial-refresh performance. Then observed regression (either dimension worse), then inconclusive
+ * (a dimension unknown), then no observed regression (including candidate-better, which is not a
+ * winner claim). affected-neighborhood evidence and reindexRecommendation are never inputs.
+ */
+export function classifyPartialRefreshAgainstFull(args) {
+    const { realization, correctnessRelation, requiredFileEvidenceRelation } = args;
+    // RULE 0 -- realization gate.
+    if (realization === "FALLBACK_FULL") {
+        return { classification: "not-comparable-as-partial-refresh", reasonCodes: ["candidate-fell-back-to-full"] };
+    }
+    // RULE 1 -- observed regression wins even if the other dimension is unknown.
+    if (correctnessRelation === "candidate-worse" || requiredFileEvidenceRelation === "candidate-worse") {
+        const reasonCodes = [];
+        if (correctnessRelation === "candidate-worse")
+            reasonCodes.push("candidate-correctness-lower");
+        if (requiredFileEvidenceRelation === "candidate-worse")
+            reasonCodes.push("candidate-missing-required-file");
+        return { classification: "observed-regression-relative-to-full", reasonCodes };
+    }
+    // RULE 2 -- inconclusive.
+    if (correctnessRelation === "unknown" || requiredFileEvidenceRelation === "unknown") {
+        const reasonCodes = [];
+        if (correctnessRelation === "unknown")
+            reasonCodes.push("correctness-unavailable");
+        if (requiredFileEvidenceRelation === "unknown")
+            reasonCodes.push("required-file-evidence-unavailable");
+        return { classification: "inconclusive", reasonCodes };
+    }
+    // RULE 3 -- no observed regression.
+    return { classification: "no-observed-regression-relative-to-full", reasonCodes: ["no-reference-regression-observed"] };
+}