@skyramp/mcp 0.4.3-rc.1 → 0.4.3-rc.2

package/build/recommendation/answers.d.ts

@@ -20,8 +20,10 @@ export declare function unknownAnswerObjections(objections: Objection[], acknowl
 export declare const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
 export declare function isNonAnswerable(objectionId: unknown): boolean;
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, and a defect with no test needs the test — a defect the code
- *  already had before this pull request included. Either one closes only when the
+ *  needs the test, a value a page and API change refuses needs a UI test or a
+ *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
+ *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
+ *  the code already had before this pull request included. Each closes only when the
  *  answer also names what stopped the test: a service that is not running, a
  *  branch that no longer exists, the one credential the run holds. Measured on run
  *  34176038240: across eight fixtures 45 objections were raised and 45 were
@@ -29,7 +31,7 @@ export declare function isNonAnswerable(objectionId: unknown): boolean;
  *  Prose closed every uncovered change, including changes nothing prevented a test
  *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
  *  baseline reported: each was listed and closed by a sentence. */
-export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "defects:untested:"];
+export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "coverage:surfaceReject:", "defects:untested:"];
 export declare function needsBlocker(objectionId: unknown): boolean;
 /** The objection raised below carries this prefix and the id it objects to. */
 export declare const REFUSED_ANSWER_PREFIX = "answers:refused:";

package/build/recommendation/answers.js

@@ -53,8 +53,10 @@ export function isNonAnswerable(objectionId) {
         objectionId.startsWith(NON_ANSWERABLE_PREFIX));
 }
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, and a defect with no test needs the test — a defect the code
- *  already had before this pull request included. Either one closes only when the
+ *  needs the test, a value a page and API change refuses needs a UI test or a
+ *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
+ *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
+ *  the code already had before this pull request included. Each closes only when the
  *  answer also names what stopped the test: a service that is not running, a
  *  branch that no longer exists, the one credential the run holds. Measured on run
  *  34176038240: across eight fixtures 45 objections were raised and 45 were
@@ -64,6 +66,7 @@ export function isNonAnswerable(objectionId) {
  *  baseline reported: each was listed and closed by a sentence. */
 export const BLOCKER_ONLY_PREFIXES = [
     "coverage:change:",
+    "coverage:surfaceReject:",
     "defects:untested:",
 ];
 export function needsBlocker(objectionId) {

package/build/recommendation/verifierContracts.d.ts

@@ -188,6 +188,14 @@ export declare const COVERAGE_CONTRACT: {
             readonly message: "No {kind} test cites this change, which is on the {surface}.";
             readonly suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.";
         };
+        readonly surfaceCase: {
+            readonly message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.";
+        };
+        readonly surfaceReject: {
+            readonly message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
+        };
     };
     readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
 };

package/build/recommendation/verifierContracts.js

@@ -202,6 +202,19 @@ export const COVERAGE_CONTRACT = {
             message: "No {kind} test cites this change, which is on the {surface}.",
             suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.",
         },
+        // `{case}` is the rendered case, as in `level="Principal" (accept)`. SKYR-4529: a form offered Lead and Principal, and
+        // only an API test sent Principal.
+        surfaceCase: {
+            message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.",
+            suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.",
+        },
+        // `{case}` is the rendered case, as in `level="Principal" (accept)`. The XR02 run removed Intern from a form; the page
+        // objection closed by a sentence, and no generated test checked the option was
+        // gone.
+        surfaceReject: {
+            message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.",
+            suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
+        },
     },
     suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?",
 };

package/build/recommendation/verifiers/coverage.js

@@ -5,6 +5,7 @@ import { isTestPath } from "../../utils/testFileClassification.js";
 import { maintainedFileIsInItsRepository, normalizeCitedPath, } from "./citedPath.js";
 import { COVERAGE_CONTRACT, fillPlaceholders } from "../verifierContracts.js";
 import { isUIPlannedTest, stateRouteKey, subjectStep } from "../subjectStep.js";
+import { normalizeStepMethod } from "../../types/StepMethod.js";
 /** Whether a path can be product code at all, by the deny list route grounding
  *  already applies to a cited file. Nothing else is excluded: a file's kind is
  *  not this check's judgment to make. */
@@ -640,9 +641,6 @@ function rejectObjections(registration) {
     }
     return objections;
 }
-// ── The surface a change is on ──────────────────────────────────────────────
-/** The test types that reach each surface. An `e2e` test drives the page AND the
- *  requests behind it, so it counts for both. */
 const TEST_TYPES_FOR = {
     api: {
         types: new Set(["contract", "integration", "e2e"]),
@@ -658,7 +656,7 @@ function declaredSurfaces(change) {
         return [];
     return [
         ...new Set(named.map((surface) => String(surface ?? "").trim())),
-    ].filter((surface) => surface in TEST_TYPES_FOR);
+    ].filter((surface) => Object.hasOwn(TEST_TYPES_FOR, surface));
 }
 /** A change on a page needs a test that opens the page, and a change on the API
  *  needs one that calls it. Run 34065056830 cited a page change from an API test
@@ -698,6 +696,146 @@ function surfaceObjections(registration) {
     }
     return objections;
 }
+/** Whether `text` names `value` as a whole word, ignoring case. Letters in any
+ *  script: an ASCII boundary found "Gr" in "Größe". */
+function namesWord(text, value) {
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, "iu").test(text);
+}
+/** An `absent` case names no value, so it draws no page objection. */
+function pageObjectionKind(testCase) {
+    if (testCase.absent === true)
+        return undefined;
+    if (testCase.expect === "accept")
+        return "surfaceCase";
+    if (testCase.expect === "reject")
+        return "surfaceReject";
+    return undefined;
+}
+/** The value as a UI step would spell it, or undefined when no step can: a number,
+ *  a boolean, text with no letter and a `{placeholder}` are never spelled in a step,
+ *  and a page chooses no HTTP verb. */
+function valueAPageSpells(testCase) {
+    const param = testCase.param.trim();
+    const value = testCase.value;
+    if (!param || param.toLowerCase() === METHOD_PARAM)
+        return undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const word = value.trim();
+    if (!/\p{L}/u.test(word))
+        return undefined;
+    if (/^(true|false)$/i.test(word) || PLACEHOLDER_VALUE.test(word))
+        return undefined;
+    return word;
+}
+/** The page steps that choose a value. An `assert` that the radio is visible
+ *  chose nothing: the XR02 run passed Principal on one, and no test saved at it.
+ *  An e2e test's HTTP step is not the page either. */
+const CHOOSING_VERBS = new Set([
+    "click",
+    "type",
+    "press",
+    "tap",
+]);
+/** A refused value is also met by asserting the page no longer offers it. */
+const REFUSING_VERBS = new Set([
+    ...CHOOSING_VERBS,
+    "assert",
+]);
+/** The text that can name a value on the page: the steps of the UI tests whose verb
+ *  is in `verbs`, and the edit note of each maintained spec, which is prose with no
+ *  verb to read. */
+function pageTexts(uiTests, maintained, verbs) {
+    return [
+        ...uiTests.flatMap((plannedTest) => plannedTest.scenario.steps
+            .filter((step) => verbs.has(normalizeStepMethod(step.method) ?? ""))
+            .flatMap((step) => [step.path, step.description ?? ""])),
+        ...maintained.map((entry) => entry.differsBy),
+    ];
+}
+/** A change on the page AND the API needs each accepted value chosen on the page,
+ *  and each refused value tried or shown absent there, not only sent by an API
+ *  test. `surfaceObjections` passes the page once any UI test cites the change,
+ *  whatever value it picks. A UI step is free text (`Senior radio`), so the check
+ *  reads whether a page step of a citing ui or e2e test that chooses the value (or,
+ *  for a refused one, asserts it), or the `differsBy` of a citing maintained spec,
+ *  names the value.
+ *
+ *  A refused value takes a test, a resolving maintained spec, or a blocker, never a
+ *  sentence: in the XR02 run the page objection for a removed option closed by
+ *  prose, and only an existing spec checked that the option was gone. */
+function surfaceCaseObjections(registration, ctx) {
+    const objections = [];
+    const seen = new Set();
+    const pageTypes = TEST_TYPES_FOR.page.types;
+    for (const change of registration.changes) {
+        const id = change.id.trim();
+        const surfaces = declaredSurfaces(change);
+        if (!id || !surfaces.includes("page") || !surfaces.includes("api"))
+            continue;
+        const uiTests = registration.plannedTests.filter((plannedTest) => citesChange(plannedTest, id) &&
+            pageTypes.has(plannedTest.scenario.testType.toLowerCase()));
+        // A maintained spec counts only when its file resolves, the bar
+        // `citedBehaviors` sets: the refused half closes by no sentence, so a note on a
+        // file nobody can open must not close it either.
+        const maintained = (registration.maintains ?? []).filter((entry) => entry.changes.some((cited) => cited.trim() === id) &&
+            maintainedFileIsInItsRepository(entry, ctx));
+        const citedAtAll = maintained.length > 0 ||
+            registration.plannedTests.some((plannedTest) => citesChange(plannedTest, id));
+        const texts = {
+            surfaceCase: pageTexts(uiTests, maintained, CHOOSING_VERBS),
+            surfaceReject: pageTexts(uiTests, maintained, REFUSING_VERBS),
+        };
+        for (const testCase of change.testCases ?? []) {
+            const kind = pageObjectionKind(testCase);
+            // An accepted value with no UI test and no maintained spec already draws
+            // `coverage:surface:<id>:page`, and a second objection would need a second
+            // answer for one gap. A maintained spec alone does not stop that objection,
+            // but a sentence citing the spec closed it while a value went untried, so the
+            // value is checked then. A refused value is always checked: that sentence is
+            // the gap. A change nothing cites draws `coverage:change:<id>`.
+            if (!kind || !citedAtAll)
+                continue;
+            if (kind === "surfaceCase" &&
+                uiTests.length === 0 &&
+                maintained.length === 0)
+                continue;
+            const word = valueAPageSpells(testCase);
+            if (word === undefined)
+                continue;
+            if (texts[kind].some((text) => namesWord(text, word)))
+                continue;
+            const rendered = renderTestCase({
+                ...testCase,
+                param: testCase.param.trim(),
+                value: word,
+            });
+            const objectionId = `coverage:${kind}:${id}:page:${rendered}`;
+            // One step closes `Intern` and `intern` alike, so they are one objection.
+            const key = objectionId.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const citers = [
+                ...uiTests.map((plannedTest) => plannedTest.plannedTestId),
+                ...maintained.map((entry) => entry.file),
+            ];
+            objections.push({
+                objectionId,
+                verifier: "coverage",
+                message: fillPlaceholders(COVERAGE_CONTRACT.objections[kind].message, {
+                    case: rendered,
+                }),
+                evidence: citers.length === 0
+                    ? `No ui or e2e test or maintained spec cites ${id}.`
+                    : `${citers.join(", ")} cite ${id}; no step or maintained edit of theirs names ${word}.`,
+                suggestion: COVERAGE_CONTRACT.objections[kind].suggestion,
+            });
+        }
+    }
+    return objections;
+}
 /** One repository's changed files, and the name to attribute uncovered ones to.
  *  Keying the objection id on the path alone let two repositories that each change
  *  `src/App.tsx` share one id, so every id names its repository. */
@@ -759,6 +897,7 @@ export const coverage = {
             ...testCaseObjections(registration),
             ...rejectObjections(registration),
             ...surfaceObjections(registration),
+            ...surfaceCaseObjections(registration, ctx),
         ];
         if (allChangedFiles(ctx).length === 0)
             return objections;

package/build/tools/code-refactor/removed-modules.d.ts

@@ -0,0 +1,33 @@
+import type { UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import type { RemovedModuleEntry } from "../../types/ReuseOutcome.js";
+/**
+ * A shared module the run created and then removed — the one thing about a
+ * module that cannot be re-derived from the delivered files, because there is no
+ * file left to derive from. The verify pass records what it located and how the
+ * pass ended (`locatedModules`, in reuse-state.ts beside the record writes); the
+ * report reads the records for a run-created module that is no longer on disk
+ * (`removedModulesFrom`). This module imports reuse-state.ts and nothing here
+ * is imported back, so the two cannot load each other half-initialised.
+ */
+/** A shared module a run created and removed again, read off the records. `file`
+ *  is the absolute path for the caller's directory match; the rest is the wire
+ *  entry. */
+export type RemovedModule = RemovedModuleEntry & {
+    file: string;
+};
+/**
+ * The modules the run created and then removed, across every record: each module a
+ * verify pass located that HEAD did not hold and that is no longer on disk. One
+ * entry per module, however many specs' passes located it.
+ *
+ * The reason is what the record holds and nothing more: the last verify pass that
+ * had the module, and how it ended. The run's own motive is not on record — an
+ * agent deletes a module after a failed pass, and the failures are the closest
+ * thing to its reason — so the entry states the verdict and lets the reader draw
+ * the line. A module removed after a PASSED verify is stated as such. Nor does
+ * the entry say what the delivered tests import instead: a module the run
+ * RENAMED is gone from this path and present under another, and the row's
+ * `helpers` field names that one. The entry claims only what it measured — the
+ * path is not in the delivery.
+ */
+export declare function removedModulesFrom(outcomes: UnifiedAnalysisState["reuseOutcomes"]): Promise<RemovedModule[]>;

package/build/tools/code-refactor/removed-modules.js

@@ -0,0 +1,61 @@
+import { stat } from "fs/promises";
+import { utilsFileLabel } from "./reuse-state.js";
+/**
+ * The modules the run created and then removed, across every record: each module a
+ * verify pass located that HEAD did not hold and that is no longer on disk. One
+ * entry per module, however many specs' passes located it.
+ *
+ * The reason is what the record holds and nothing more: the last verify pass that
+ * had the module, and how it ended. The run's own motive is not on record — an
+ * agent deletes a module after a failed pass, and the failures are the closest
+ * thing to its reason — so the entry states the verdict and lets the reader draw
+ * the line. A module removed after a PASSED verify is stated as such. Nor does
+ * the entry say what the delivered tests import instead: a module the run
+ * RENAMED is gone from this path and present under another, and the row's
+ * `helpers` field names that one. The entry claims only what it measured — the
+ * path is not in the delivery.
+ */
+export async function removedModulesFrom(outcomes) {
+    // Several specs' records can hold one module; the LATEST pass over it is the
+    // verdict it was removed under, and the latest answer on whether this run
+    // created it — whichever record holds it. Latest FIRST, then the claim: an
+    // older "created" must not outrank a newer "found at HEAD".
+    const latest = new Map();
+    for (const record of Object.values(outcomes ?? {}))
+        for (const m of record.utils?.modules ?? []) {
+            const held = latest.get(m.file);
+            if (!held || m.lastPass.at > held.lastPass.at)
+                latest.set(m.file, m);
+        }
+    const out = [];
+    for (const m of latest.values()) {
+        if (!m.createdByThisRun)
+            continue;
+        if (await exists(m.file))
+            continue;
+        const { failed, failures, errored } = m.lastPass;
+        const verdict = errored
+            ? "could not run (the verifier threw)"
+            : !failed
+                ? "passed, so the run gave no reason"
+                : failures
+                    ? `failed on ${failures.map((f) => `${f.kind} ×${f.count}`).join(", ")}`
+                    : "failed outside the file's invariants (a staging refusal)";
+        out.push({
+            file: m.file,
+            utilsFile: utilsFileLabel([m.file]),
+            reason: `this run created the module, and it is not in the delivery; the last verify pass that had it ${verdict}`,
+            ...(failures ? { verificationFailures: failures } : {}),
+        });
+    }
+    return out;
+}
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/build/tools/code-refactor/reuse-outcome.d.ts

@@ -1,6 +1,6 @@
 import type { VerifyResult } from "../../utils/pom-verify/index.js";
 import { ReuseVerificationOutcome, type InHouseDeclinedEntry, type ReuseSkippedEntry } from "../../types/ReuseOutcome.js";
-import { HelperVerificationOutcome } from "../../types/ReuseOutcome.js";
+import { HelperVerificationOutcome, type ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, type ReuseOutcome, type ReuseSkippedEntry, } from "../../types/ReuseOutcome.js";
 /** A member the verifier flagged at some point in this run. NOT the same as "a
  *  member that was demoted": the workflow allows one remap attempt, so a flagged
@@ -87,6 +87,32 @@ export interface UtilsReuseRecord {
      *  repository's own browser helper modules: the files it read, the helpers it
      *  declined. Testimony, kept for the report and labelled there as such. */
     inHouseDeclared?: InHouseDeclaration;
+    /** Every shared module a verify pass of this spec located, accumulated across
+     *  passes. A pass that locates a module overwrites its entry; a pass that
+     *  locates none touches nothing — that is the pass after the run DELETED the
+     *  module, and the record is the only place the module's existence survives. */
+    modules?: LocatedModule[];
+}
+export interface LocatedModule {
+    file: string;
+    /** HEAD lacked it: this run created it. `false` for an incumbent. ABSENT when
+     *  git gave no answer — outside a repository, or a git failure — so the report
+     *  never says "this run created it" on no evidence. */
+    createdByThisRun?: boolean;
+    /** The last verify pass that had this module: when, whether it failed, and on
+     *  what. The PASS's failures, filed under each module it had: a failure on the
+     *  spec side (a type error at a call site, an assertion loss) names no module,
+     *  and it is still the verdict the module was removed under. A failed pass with
+     *  no failures failed outside the file's invariants — a staging refusal. */
+    lastPass: {
+        /** ISO time, so the latest pass wins when several specs' records hold the
+         *  same module. */
+        at: string;
+        failed: boolean;
+        failures?: ReuseVerificationFailure[];
+        /** The pass threw before it could judge anything. `failed` is true too. */
+        errored?: true;
+    };
 }
 export interface InHouseDeclaration {
     filesRead: string[];

package/build/tools/code-refactor/reuse-record-store.d.ts

@@ -47,6 +47,11 @@ export declare function owns(record: ReuseRecord, testFile: string): boolean;
 export declare function samePath(a: string, b: string): boolean;
 /** Exported for retrofit-state: the same canonicalisation the records use. */
 export declare function canonPath(p: string): string;
+/** Canonical path for a file that may be GONE: `realpath` fails on a missing
+ *  file and the fallback leaves a symlinked parent (macOS `/tmp` → `/private/tmp`)
+ *  unresolved, so a deleted module never matched a canonical spec path. The
+ *  nearest existing ancestor is canonicalised and the missing tail put back. */
+export declare function canonPathEvenIfGone(p: string): string;
 /** Whether the run state file can be written — the precondition for any debt this
  *  module holds, since only a write clears it. */
 export declare function runStateWritable(explicitStateFile?: string): Promise<boolean>;

package/build/tools/code-refactor/reuse-record-store.js

@@ -1,6 +1,6 @@
 import * as path from "path";
 import { access, constants as fsConstants } from "fs/promises";
-import { realpathSync } from "fs";
+import { existsSync, realpathSync } from "fs";
 import { logger } from "../../utils/logger.js";
 import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
 import { realpath } from "../../utils/utils-verify/index.js";
@@ -86,6 +86,7 @@ export function freshRecord() {
         utils: undefined,
         modularized: undefined,
         pomPassFinished: undefined,
+        baseline: undefined,
     };
 }
 /** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
@@ -102,6 +103,19 @@ export function samePath(a, b) {
 export function canonPath(p) {
     return canon(p);
 }
+/** Canonical path for a file that may be GONE: `realpath` fails on a missing
+ *  file and the fallback leaves a symlinked parent (macOS `/tmp` → `/private/tmp`)
+ *  unresolved, so a deleted module never matched a canonical spec path. The
+ *  nearest existing ancestor is canonicalised and the missing tail put back. */
+export function canonPathEvenIfGone(p) {
+    let probe = p;
+    const tail = [];
+    while (!existsSync(probe) && path.dirname(probe) !== probe) {
+        tail.unshift(path.basename(probe));
+        probe = path.dirname(probe);
+    }
+    return path.join(canon(probe), ...tail);
+}
 function canon(p) {
     try {
         return realpathSync(p);

package/build/tools/code-refactor/reuse-state.d.ts

@@ -1,11 +1,11 @@
 import { type ReuseHandOff, type ReuseHandOffSource } from "../../utils/AnalysisStateManager.js";
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
-import { type InHouseDeclaration, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
+import { type InHouseDeclaration, type LocatedModule, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
 import { type UtilsVerifyResult, type UtilsViolationKind } from "../../utils/utils-verify/index.js";
 import type { HelperReuseOutcome, ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
 /** The canonical path comparison the records use — declared in the store, re-exported
  *  here for the readers that always imported it from this module. */
-export { samePath, canonPath } from "./reuse-record-store.js";
+export { samePath, canonPath, canonPathEvenIfGone, } from "./reuse-record-store.js";
 /**
  * Persistence for the server-derived POM-reuse outcome, keyed by test-file
  * basename (what `newTestsCreated[].fileName` carries, so
@@ -105,8 +105,21 @@ export declare function recordUtilsVerifyError(testFile: string, explicitStateFi
  * repository, or for a file the root does not contain, the basename stands in.
  */
 export declare function utilsFileLabel(files: string[]): string;
-/** Verdict of one utils verify pass. The verdict alone is stored — counts and the
- *  file list are re-derived from the delivered files at report time. */
+/** The record's module list after one verify pass: every module the pass located
+ *  gets a fresh entry — whether HEAD lacked it, and the pass's failures when it
+ *  failed — and every module the pass did not locate keeps its entry. A pass that
+ *  locates nothing is the pass after the run DELETED the module, and the record
+ *  is the only place the module's existence survives. */
+export declare function locatedModules(prior: LocatedModule[] | undefined, r: UtilsVerifyResult): LocatedModule[];
+/** The record's module list after a verify pass that THREW: every module keeps
+ *  its entry and is stamped with the failed pass, so a module removed after it
+ *  never reads as removed after a pass that passed. */
+export declare function modulesAfterVerifyError(prior: LocatedModule[] | undefined): LocatedModule[];
+/** Verdict of one utils verify pass. The verdict is stored — counts and the file
+ *  list are re-derived from the delivered files at report time — and so are the
+ *  modules the pass located and the failures of a failed pass: a module the run
+ *  removes afterwards can be re-derived from nothing, and its row must still say
+ *  it existed and why it went. */
 export declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string, 
 /** The agent's declarations from this verify call, when it made any. */
 inHouseDeclared?: InHouseDeclaration): Promise<boolean>;

package/build/tools/code-refactor/reuse-state.js

@@ -1,3 +1,4 @@
+import { existsSync } from "fs";
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { readFile, stat } from "fs/promises";
@@ -18,11 +19,11 @@ const execFileAsync = promisify(execFile);
 import { resolvePomCatalogPath } from "../../utils/pom-catalog.js";
 import { parsePomCatalog, findMissedReuse, } from "../../utils/pom-catalog-parse.js";
 import { ProgrammingLanguage } from "../../types/TestTypes.js";
-import { canonPath, freshRecord, owns, readHandOff, readReuseRecord, readRunState, runStateWritable, samePath, updateReuseOutcome, } from "./reuse-record-store.js";
+import { canonPath, canonPathEvenIfGone, freshRecord, owns, readHandOff, readReuseRecord, readRunState, runStateWritable, samePath, updateReuseOutcome, } from "./reuse-record-store.js";
 import { combineRederivations, pomFirstHandOff } from "./pom-pass-state.js";
 /** The canonical path comparison the records use — declared in the store, re-exported
  *  here for the readers that always imported it from this module. */
-export { samePath, canonPath } from "./reuse-record-store.js";
+export { samePath, canonPath, canonPathEvenIfGone, } from "./reuse-record-store.js";
 /**
  * Persistence for the server-derived POM-reuse outcome, keyed by test-file
  * basename (what `newTestsCreated[].fileName` carries, so
@@ -184,7 +185,15 @@ export async function recordUtilsReuseIssued(testFile, language, framework, test
  *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
 export async function recordUtilsVerifyError(testFile, explicitStateFile) {
     await updateReuseOutcome(testFile, (existing) => owns(existing, testFile) && existing.utils
-        ? { utils: { ...existing.utils, verifyError: true } }
+        ? {
+            utils: {
+                ...existing.utils,
+                verifyError: true,
+                ...(existing.utils.modules
+                    ? { modules: modulesAfterVerifyError(existing.utils.modules) }
+                    : {}),
+            },
+        }
         : {}, explicitStateFile);
 }
 /**
@@ -202,12 +211,17 @@ export function utilsFileLabel(files) {
     return files.map(repoRelativeLabel).join(", ");
 }
 function repoRelativeLabel(file) {
-    const root = detectGitRoot(file);
+    // Canonical even when GONE: a module the run REMOVED has no file to stat, and
+    // its label must still name where in the repository it was.
+    const canonFile = canonPathEvenIfGone(file);
+    let probe = path.dirname(canonFile);
+    while (!existsSync(probe) && path.dirname(probe) !== probe)
+        probe = path.dirname(probe);
+    const root = detectGitRoot(probe);
     if (!root)
         return path.basename(file);
-    // Both sides canonical: git reports the REAL root, and a path through a symlink
-    // (macOS /tmp → /private/tmp) would otherwise relativise to `../../…`.
-    const rel = path.relative(canonPath(root), canonPath(file));
+    // Both sides canonical: git reports the REAL root.
+    const rel = path.relative(canonPath(root), canonFile);
     // Outside the root means a leading `..` SEGMENT — not any name starting with two
     // dots (`..generated/SkyrampUtils.py` is a valid in-repository path).
     const outside = rel === ".." || rel.startsWith(`..${path.sep}`);
@@ -215,8 +229,50 @@ function repoRelativeLabel(file) {
         return path.basename(file);
     return rel.split(path.sep).join("/");
 }
-/** Verdict of one utils verify pass. The verdict alone is stored — counts and the
- *  file list are re-derived from the delivered files at report time. */
+/** The record's module list after one verify pass: every module the pass located
+ *  gets a fresh entry — whether HEAD lacked it, and the pass's failures when it
+ *  failed — and every module the pass did not locate keeps its entry. A pass that
+ *  locates nothing is the pass after the run DELETED the module, and the record
+ *  is the only place the module's existence survives. */
+export function locatedModules(prior, r) {
+    const incumbents = new Set(r.incumbentModules);
+    const unknown = new Set(r.headUnknownModules);
+    const modules = new Map((prior ?? []).map((m) => [m.file, m]));
+    const failures = r.ok ? [] : verificationFailures(r);
+    const lastPass = {
+        at: new Date().toISOString(),
+        failed: !r.ok,
+        ...(failures.length > 0 ? { failures } : {}),
+    };
+    for (const file of r.utilsFiles) {
+        // Git gave no answer this pass: an earlier pass's answer stands. A transient
+        // failure on the last pass before a deletion must not erase the claim.
+        const createdByThisRun = unknown.has(file)
+            ? modules.get(file)?.createdByThisRun
+            : !incumbents.has(file);
+        modules.set(file, {
+            file,
+            ...(createdByThisRun === undefined ? {} : { createdByThisRun }),
+            lastPass,
+        });
+    }
+    return [...modules.values()];
+}
+/** The record's module list after a verify pass that THREW: every module keeps
+ *  its entry and is stamped with the failed pass, so a module removed after it
+ *  never reads as removed after a pass that passed. */
+export function modulesAfterVerifyError(prior) {
+    const at = new Date().toISOString();
+    return (prior ?? []).map((m) => ({
+        ...m,
+        lastPass: { at, failed: true, errored: true },
+    }));
+}
+/** Verdict of one utils verify pass. The verdict is stored — counts and the file
+ *  list are re-derived from the delivered files at report time — and so are the
+ *  modules the pass located and the failures of a failed pass: a module the run
+ *  removes afterwards can be re-derived from nothing, and its row must still say
+ *  it existed and why it went. */
 export async function recordUtilsVerifyOutcome(testFile, r, language, framework, testType, explicitStateFile, 
 /** The agent's declarations from this verify call, when it made any. */
 inHouseDeclared) {
@@ -234,6 +290,7 @@ inHouseDeclared) {
     return updateReuseOutcome(testFile, (existing) => {
         const mine = owns(existing, testFile);
         const prior = mine ? existing.utils : undefined;
+        const modules = locatedModules(prior?.modules, r);
         return {
             ...(mine ? {} : freshRecord()),
             testFilePath: testFile,
@@ -255,6 +312,7 @@ inHouseDeclared) {
                 ...((inHouseDeclared ?? prior?.inHouseDeclared)
                     ? { inHouseDeclared: inHouseDeclared ?? prior?.inHouseDeclared }
                     : {}),
+                ...(modules.length > 0 ? { modules } : {}),
             },
         };
     }, explicitStateFile);