@skyramp/mcp 0.4.2 → 0.4.3-rc.2

package/build/tools/code-refactor/modularizationTool.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { fixErrorsInstruction } from "../../skills/fixTestImportErrorsSkill.js";
 import fs from "fs";
 import { logger } from "../../utils/logger.js";
+import { toolError } from "../../utils/utils.js";
 import { ProgrammingLanguage, TestType } from "../../types/TestTypes.js";
 import { ModularizationService, } from "../../services/ModularizationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -9,6 +10,7 @@ import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/norma
 import { normalizeSkyrampImportsInFile } from "../../utils/normalizeSkyrampImports.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 import { recordModularized } from "./reuse-state.js";
+import { pendingPomPass } from "./pom-pass-state.js";
 const modularizationSchema = {
     testFile: z
         .string()
@@ -82,6 +84,14 @@ After modularization, if errors remain, ${fixErrorsInstruction()}.
             if (!params.isTraceBased &&
                 [TestType.UI, TestType.E2E, TestType.INTEGRATION].includes(params.testType))
                 params.isTraceBased = true;
+            // Both reuse settings on: the page-object pass maps the raw steps first, and
+            // its gates judge the spec while what it did not substitute is still inline.
+            // Checked before anything is recorded, so a refused call leaves no mark.
+            const owedPomPass = await pendingPomPass(params.testFile);
+            if (owedPomPass) {
+                errorResult = toolError(owedPomPass);
+                return errorResult;
+            }
             normalizeSkyrampImportsInFile(params.testFile);
             // Stage so testbot includes the generated files in its output commit.
             await stageGeneratedPaths(params.testFile);

package/build/tools/code-refactor/pom-pass-state.d.ts

@@ -0,0 +1,51 @@
+import type { ReuseHandOff } from "../../utils/AnalysisStateManager.js";
+import type { ReuseRederivation } from "./reuse-state.js";
+/**
+ * The page-object pass as run state, for a target both reuse settings serve
+ * (isPomFirstTarget): whether the pass has finished for a spec, the mark that
+ * finishes it, the checkpoint that holds modularization until it has, and the
+ * merge of the two halves one such spec's report row carries.
+ */
+/** Whether a hand-off's chain starts with the page-object pass. Derived from what the
+ *  hand-off already stores, never recorded beside it: generation writes the hand-off
+ *  from exactly these three values, and maintenance arms none for such a target. */
+export declare function pomFirstHandOff(handOff: ReuseHandOff): boolean;
+/**
+ * With both reuse settings on (isPomFirstTarget), where this spec's page-object pass
+ * stands. `undefined` while it is open; `"finished"` once its verify pass PASSED;
+ * `"no-layer"` when discovery found no page-object layer to reuse. From then on the
+ * reuse tool serves the SkyrampUtils flow for the spec, and the page-object gates
+ * have already judged the spec while every step they did not substitute was still raw
+ * and inline — the state they were written for.
+ *
+ * A FAILED verdict keeps the pass open: the page-object report says to fix and
+ * re-verify, and `pendingReuseVerification` refuses the tools after it until that
+ * happens. A record owned by another spec, or no run state, reads as open; the caller
+ * then serves the page-object pass, which is what the spec gets without composition.
+ */
+export declare function pomPassOutcome(testFile: string, explicitStateFile?: string): Promise<"finished" | "no-layer" | undefined>;
+/** Mark the page-object pass finished for a spec (see `pomPassOutcome`). Written by
+ *  the reuse tool at the two points that finish it: a PASSED page-object verify, and
+ *  discovery that found no page-object layer. */
+export declare function recordPomPassFinished(testFile: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Does this spec owe its page-object pass before `skyramp_modularization`? Only a spec
+ * generation handed off with the page-object pass first. Modularizing first would move
+ * the raw steps the page-object pass maps into helpers it cannot see, and its gates
+ * would then judge a spec with nothing left inline. Fails open without a hand-off, on
+ * an unreadable or unwritable state file.
+ */
+export declare function pendingPomPass(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * One row, both halves. The outcome fields are disjoint by construction (the
+ * page-object fields sit at the top level, the shared-helper ones under `helpers` and
+ * `inHouse`). The two blocking verdicts become ONE, because the report refuses per
+ * spec and one `verify: true` call re-checks both halves (the reuse tool's combined
+ * verify). Declines are retired only where the half that owns them was measured: the
+ * page-object half measures a `kept inline` decline only when its zero-reuse gate
+ * walked the candidates, which it does not at non-zero reuse.
+ */
+export declare function combineRederivations(pom: ReuseRederivation, helper: ReuseRederivation, carriesKeptInline: boolean, 
+/** The call that re-checks both halves — the shared-helper verify call, which the
+ *  reuse tool routes to its combined verify for such a spec. */
+combinedVerifyCall: string | undefined): ReuseRederivation;

package/build/tools/code-refactor/pom-pass-state.js

@@ -0,0 +1,115 @@
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+import { isPomFirstTarget } from "../../utils/reuseRouting.js";
+import { ReuseVerificationOutcome } from "./reuse-outcome.js";
+import { freshRecord, owns, readHandOff, readReuseRecord, runStateWritable, updateReuseOutcome, } from "./reuse-record-store.js";
+/**
+ * The page-object pass as run state, for a target both reuse settings serve
+ * (isPomFirstTarget): whether the pass has finished for a spec, the mark that
+ * finishes it, the checkpoint that holds modularization until it has, and the
+ * merge of the two halves one such spec's report row carries.
+ */
+/** Whether a hand-off's chain starts with the page-object pass. Derived from what the
+ *  hand-off already stores, never recorded beside it: generation writes the hand-off
+ *  from exactly these three values, and maintenance arms none for such a target. */
+export function pomFirstHandOff(handOff) {
+    return isPomFirstTarget(handOff.language, handOff.testType);
+}
+/**
+ * With both reuse settings on (isPomFirstTarget), where this spec's page-object pass
+ * stands. `undefined` while it is open; `"finished"` once its verify pass PASSED;
+ * `"no-layer"` when discovery found no page-object layer to reuse. From then on the
+ * reuse tool serves the SkyrampUtils flow for the spec, and the page-object gates
+ * have already judged the spec while every step they did not substitute was still raw
+ * and inline — the state they were written for.
+ *
+ * A FAILED verdict keeps the pass open: the page-object report says to fix and
+ * re-verify, and `pendingReuseVerification` refuses the tools after it until that
+ * happens. A record owned by another spec, or no run state, reads as open; the caller
+ * then serves the page-object pass, which is what the spec gets without composition.
+ */
+export async function pomPassOutcome(testFile, explicitStateFile) {
+    try {
+        const record = await readReuseRecord(testFile, explicitStateFile);
+        if (!record?.pomPassFinished || !owns(record, testFile))
+            return undefined;
+        return record.verification === ReuseVerificationOutcome.SkippedNoPom
+            ? "no-layer"
+            : "finished";
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Mark the page-object pass finished for a spec (see `pomPassOutcome`). Written by
+ *  the reuse tool at the two points that finish it: a PASSED page-object verify, and
+ *  discovery that found no page-object layer. */
+export async function recordPomPassFinished(testFile, explicitStateFile) {
+    await updateReuseOutcome(testFile, (existing) => owns(existing, testFile)
+        ? { pomPassFinished: true }
+        : { ...freshRecord(), testFilePath: testFile, pomPassFinished: true }, explicitStateFile);
+}
+/**
+ * Does this spec owe its page-object pass before `skyramp_modularization`? Only a spec
+ * generation handed off with the page-object pass first. Modularizing first would move
+ * the raw steps the page-object pass maps into helpers it cannot see, and its gates
+ * would then judge a spec with nothing left inline. Fails open without a hand-off, on
+ * an unreadable or unwritable state file.
+ */
+export async function pendingPomPass(testFile, explicitStateFile) {
+    try {
+        const handOff = (await readHandOff(testFile, explicitStateFile))?.handOff;
+        if (!handOff || !pomFirstHandOff(handOff))
+            return undefined;
+        if ((await pomPassOutcome(testFile, explicitStateFile)) !== undefined)
+            return undefined;
+        if (!(await runStateWritable(explicitStateFile)))
+            return undefined;
+        return (`${path.basename(testFile)} takes the page-object pass BEFORE modularization. Call skyramp_reuse_code with ` +
+            `{ testFile: "${testFile}", language: "${handOff.language}", framework: "${handOff.framework}", testType: "${handOff.testType}" }, ` +
+            `follow its steps to a PASSED verification (or its "No reusable POM layer detected" answer), then call skyramp_modularization again.`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending page-object pass — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * One row, both halves. The outcome fields are disjoint by construction (the
+ * page-object fields sit at the top level, the shared-helper ones under `helpers` and
+ * `inHouse`). The two blocking verdicts become ONE, because the report refuses per
+ * spec and one `verify: true` call re-checks both halves (the reuse tool's combined
+ * verify). Declines are retired only where the half that owns them was measured: the
+ * page-object half measures a `kept inline` decline only when its zero-reuse gate
+ * walked the candidates, which it does not at non-zero reuse.
+ */
+export function combineRederivations(pom, helper, carriesKeptInline, 
+/** The call that re-checks both halves — the shared-helper verify call, which the
+ *  reuse tool routes to its combined verify for such a spec. */
+combinedVerifyCall) {
+    const outcome = pom.outcome || helper.outcome
+        ? { ...(pom.outcome ?? {}), ...(helper.outcome ?? {}) }
+        : undefined;
+    const verdicts = [pom.blocking, helper.blocking].filter((v) => v !== undefined);
+    const blocking = verdicts.length === 0
+        ? undefined
+        : {
+            file: verdicts[0].file,
+            failures: verdicts.flatMap((v) => v.failures),
+            detail: verdicts.map((v) => v.detail).join("\n\n"),
+            verifyCall: combinedVerifyCall ?? verdicts[0].verifyCall,
+        };
+    return {
+        outcome,
+        ...(blocking ? { blocking } : {}),
+        carriedConsumed: [
+            ...(pom.carriedConsumed ?? []),
+            ...(helper.carriedConsumed ?? []),
+        ],
+        carriedEvaluated: !!helper.carriedEvaluated &&
+            (!!pom.carriedEvaluated || !carriesKeptInline),
+    };
+}

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/retrofit-state.d.ts

@@ -6,8 +6,9 @@ import { type StagingResult } from "../../utils/utils-verify/index.js";
  * sibling-inline advisory). Staging carries the edit into the output commit, so the
  * report must disclose it — with an execution that ran the edited bytes.
  *
- * Whether an execution counts is answered by TIME, not by a stored hash: the
- * execution record already carries `executedAt`, and the file's mtime says when it
+ * Whether an execution counts is answered by TIME, not by a stored hash (the rule
+ * itself is `freshExecution`, shared with the changed-helper gate): the execution
+ * record already carries `executedAt`, and the file's mtime says when it
  * was last edited — an execution older than the last edit ran bytes that no longer
  * exist. That also covers a bare editor write with no tool call in between, which a
  * record-time hash cannot see. (Same identity pattern as VideoRecord's

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

@@ -6,14 +6,16 @@ import { stageUtilsArtifacts, } from "../../utils/utils-verify/index.js";
 import { importFormViolations, locateUtilsFiles, retrofitMismatches, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
 import { realpath } from "../../utils/utils-verify/index.js";
 import { canonPath, samePath, utilsFileLabel } from "./reuse-state.js";
+import { freshExecution } from "../../types/TestExecution.js";
 /**
  * Retrofit tracking (SKYR-4276 A4): a RETROFIT is a pre-existing Skyramp-generated
  * test the reuse pass edited to import from the shared utils file (STEP 5c / the
  * sibling-inline advisory). Staging carries the edit into the output commit, so the
  * report must disclose it — with an execution that ran the edited bytes.
  *
- * Whether an execution counts is answered by TIME, not by a stored hash: the
- * execution record already carries `executedAt`, and the file's mtime says when it
+ * Whether an execution counts is answered by TIME, not by a stored hash (the rule
+ * itself is `freshExecution`, shared with the changed-helper gate): the execution
+ * record already carries `executedAt`, and the file's mtime says when it
  * was last edited — an execution older than the last edit ran bytes that no longer
  * exist. That also covers a bare editor write with no tool call in between, which a
  * record-time hash cannot see. (Same identity pattern as VideoRecord's
@@ -70,17 +72,14 @@ export async function standingRetrofits(state, changedFilesAbs) {
         if (!changed.has(canonPath(file)))
             continue;
         const recorded = state.existingTests?.find((t) => samePath(t.testFile, file))?.executionAfter;
-        let execution = recorded?.status;
-        if (recorded) {
-            try {
-                const mtime = (await stat(file)).mtimeMs;
-                if (Date.parse(recorded.executedAt) < mtime)
-                    execution = undefined;
-            }
-            catch {
-                /* fail open: an unreadable mtime must not demand a re-run */
-            }
+        let mtime = 0; // fail open: an unreadable mtime must not demand a re-run
+        try {
+            mtime = (await stat(file)).mtimeMs;
+        }
+        catch {
+            /* see above */
         }
+        const execution = freshExecution(recorded, mtime);
         out.push({ file, utilsFile: r.utilsFile, testFile: r.testFile, execution });
     }
     return uncrossAttributions(out);

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
@@ -60,6 +60,12 @@ export interface ReuseRecord {
      *  enforceable unit, as with every other debt here). Read by the reuse tool on a
      *  hand-off target: modularize-first flows owe modularization BEFORE reuse. */
     modularized?: true;
+    /** Both reuse settings on (isPomFirstTarget): the page-object pass finished for this
+     *  spec — its verify pass PASSED, or it found no page-object layer. Sticky: a later
+     *  page-object verdict (the combined verify of the SkyrampUtils flow re-checks the
+     *  page-object calls) does not reopen the pass, so routing never flips back to it.
+     *  Not recoverable from the spec: it is a fact about the run's order. */
+    pomPassFinished?: true;
     /** The spec as it stood when `skyramp_modularization` handed out its instructions —
      *  after the enhancer, before any code moved (SKYR-4276 A7/A8). The verify pass
      *  compares the delivered spec plus the helpers it imports against this. */
@@ -81,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

@@ -0,0 +1,57 @@
+import { StateManager, type ReuseHandOff, type UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import type { ReuseRecord } from "./reuse-outcome.js";
+/**
+ * The run-state store behind every reuse record and hand-off: one read, one
+ * read-modify-write, one ownership rule, one canonical path comparison. The reuse
+ * checkpoints (reuse-state.ts) and the page-object-pass state (pom-pass-state.ts)
+ * both build on these and nothing else touches the file.
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
+/**
+ * Read-modify-write one spec's outcome. `patch` receives the entry recorded so
+ * far, so a caller that needs prior state (the verify pass, which accumulates
+ * flagged members) uses the same path as one that does not.
+ *
+ * Fields the patch omits are preserved: the prompt-generation call knows the
+ * candidate count, each verify pass knows the counts and verdict.
+ */
+export declare function updateReuseOutcome(testFile: string, patch: (existing: ReuseRecord) => Partial<ReuseRecord>, explicitStateFile?: string): Promise<boolean>;
+/** The run state as one read — the state manager (for a write-back) and what it
+ *  holds — or `undefined` when there is no run state to read. */
+export declare function readRunState(explicitStateFile?: string): Promise<{
+    manager: StateManager<UnifiedAnalysisState>;
+    data: UnifiedAnalysisState;
+} | undefined>;
+/** This spec's hand-off, keyed by realpath, with the run state it was read from —
+ *  the ONE read every hand-off checkpoint makes. `handOff` is `undefined` when the
+ *  file was never handed off; the whole result is when there is no run state. */
+export declare function readHandOff(testFile: string, explicitStateFile?: string): Promise<{
+    data: UnifiedAnalysisState;
+    handOff: ReuseHandOff | undefined;
+} | undefined>;
+/** Read one spec's record, or `undefined` when there is no run state, no record, or the
+ * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
+ * so the two cannot disagree about which key a spec maps to. */
+export declare function readReuseRecord(testFile: string, explicitStateFile?: string): Promise<ReuseRecord | undefined>;
+/** Every field cleared — the patch spread onto a record owned by another spec. */
+export declare function freshRecord(): Partial<ReuseRecord>;
+/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
+ *  means two specs can share one record; only the owner's history carries over. */
+export declare function owns(record: ReuseRecord, testFile: string): boolean;
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+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

@@ -0,0 +1,140 @@
+import * as path from "path";
+import { access, constants as fsConstants } from "fs/promises";
+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";
+/**
+ * The run-state store behind every reuse record and hand-off: one read, one
+ * read-modify-write, one ownership rule, one canonical path comparison. The reuse
+ * checkpoints (reuse-state.ts) and the page-object-pass state (pom-pass-state.ts)
+ * both build on these and nothing else touches the file.
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
+/**
+ * Read-modify-write one spec's outcome. `patch` receives the entry recorded so
+ * far, so a caller that needs prior state (the verify pass, which accumulates
+ * flagged members) uses the same path as one that does not.
+ *
+ * Fields the patch omits are preserved: the prompt-generation call knows the
+ * candidate count, each verify pass knows the counts and verdict.
+ */
+export async function updateReuseOutcome(testFile, patch, explicitStateFile) {
+    try {
+        const state = await readRunState(explicitStateFile);
+        if (!state)
+            return false;
+        const { manager, data } = state;
+        const key = path.basename(testFile);
+        const existing = data.reuseOutcomes?.[key] ?? {};
+        await manager.appendData({
+            ...data,
+            reuseOutcomes: {
+                ...data.reuseOutcomes,
+                [key]: { ...existing, ...patch(existing) },
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.warning("Could not record POM-reuse outcome — report will omit the reuse summary", {
+            testFile,
+            error: String(err),
+        });
+        return false;
+    }
+}
+/** The run state as one read — the state manager (for a write-back) and what it
+ *  holds — or `undefined` when there is no run state to read. */
+export async function readRunState(explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return undefined;
+    const manager = StateManager.fromStatePath(stateFile);
+    const data = await manager.readData();
+    return data ? { manager, data } : undefined;
+}
+/** This spec's hand-off, keyed by realpath, with the run state it was read from —
+ *  the ONE read every hand-off checkpoint makes. `handOff` is `undefined` when the
+ *  file was never handed off; the whole result is when there is no run state. */
+export async function readHandOff(testFile, explicitStateFile) {
+    const state = await readRunState(explicitStateFile);
+    if (!state)
+        return undefined;
+    return {
+        data: state.data,
+        handOff: state.data.reuseHandOffs?.[await realpath(testFile)],
+    };
+}
+/** Read one spec's record, or `undefined` when there is no run state, no record, or the
+ * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
+ * so the two cannot disagree about which key a spec maps to. */
+export async function readReuseRecord(testFile, explicitStateFile) {
+    return (await readRunState(explicitStateFile))?.data.reuseOutcomes?.[path.basename(testFile)];
+}
+/** Every field cleared — the patch spread onto a record owned by another spec. */
+export function freshRecord() {
+    return {
+        candidatesDetected: undefined,
+        verification: undefined,
+        flagged: undefined,
+        language: undefined,
+        utils: undefined,
+        modularized: undefined,
+        pomPassFinished: undefined,
+        baseline: undefined,
+    };
+}
+/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
+ *  means two specs can share one record; only the owner's history carries over. */
+export function owns(record, testFile) {
+    return !record.testFilePath || samePath(record.testFilePath, testFile);
+}
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+export function samePath(a, b) {
+    return canon(a) === canon(b);
+}
+/** Exported for retrofit-state: the same canonicalisation the records use. */
+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);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Whether the run state file can be written — the precondition for any debt this
+ *  module holds, since only a write clears it. */
+export async function runStateWritable(explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return false;
+    try {
+        await access(stateFile, fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}