@skyramp/mcp 0.3.6 → 0.3.7

package/build/utils/utils-verify/language-spec.js

@@ -125,20 +125,20 @@ export const HELPER_FAMILIES = {
     api: {
         family: "api",
         routeDuplicates: true,
-        allowedAssertion: (spec) => spec.allowedAssertion,
         isAllowed: (spec, expr) => spec.allowedAssertion.test(expr),
         assertionRule: "a shared API helper asserts only the status code; move this assertion to the test body, applied to the response the helper returns",
+        fixRule: "a helper that wraps an SDK request asserts only the status code — one helper per method+path, extended with defaulted parameters, named method + resource",
     },
     browser: {
         family: "browser",
         routeDuplicates: false,
-        allowedAssertion: (spec) => spec.allowedBrowserAssertion,
         // A structural wait on a locator that carries a scenario LITERAL
         // (`getByText("Total: $899.98")`) is a value assertion in disguise: digits or
         // currency in any string inside the expect(...) arguments disqualify it.
         isAllowed: (spec, expr) => spec.allowedBrowserAssertion.test(expr) &&
             !SCENARIO_LITERAL_RE.test(expectArgs(expr)),
         assertionRule: "a shared browser helper holds actions and structural waits only (toBeVisible, toBeEnabled, …); move this value assertion to the test body immediately after the helper call, selector verbatim",
+        fixRule: "every other helper holds actions and structural waits only, named for the user intent",
     },
 };
 /** The helper family a test type's shared helpers follow. Unlike `isBrowserTestType`,
@@ -149,6 +149,16 @@ export function helperFamilyFor(testType) {
     const t = (testType ?? "").toLowerCase();
     return HELPER_FAMILIES[t === "ui" || t === "e2e" ? "browser" : "api"];
 }
+/** The family ONE helper is judged by. A helper that issues an SDK request follows
+ *  the api rules whatever the test type: UI flows routinely keep a sign-in or seed
+ *  request beside their browser helpers, and judging that request by the browser
+ *  rules made its status assertion a false violation. Keyed on the request itself,
+ *  not the duplicate key — a two-request sign-in, a concatenated path, and a
+ *  parameterised route are all API helpers with no keyable route. A helper with no
+ *  request falls back to the test type's family. */
+export function helperFamilyOf(helper, fallback) {
+    return helper.wrapsRequest ? HELPER_FAMILIES.api : fallback;
+}
 /** The spec for a language string as the tools receive it, or `undefined` for a
  *  language this verifier does not cover (Java: utils reuse is disabled for it). */
 export function utilsSpecFor(language) {

package/build/utils/utils-verify/parse.d.ts

@@ -2,8 +2,6 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
 export interface HelperAssertion {
     line: number;
     text: string;
-    /** True for the one permitted shape — a status-code comparison. */
-    allowed: boolean;
 }
 export interface UtilsHelper {
     name: string;
@@ -15,8 +13,23 @@ export interface UtilsHelper {
     path?: string;
     /** `path` with every path parameter collapsed to `{}`; the duplicate key with `method`. */
     normalizedPath?: string;
+    /** The helper issues at least one SDK request — what makes it an API helper,
+     *  whatever the test type, and whether or not it has a keyable single route
+     *  (a two-request sign-in, a concatenated path, and a parameterised route all
+     *  wrap requests without one). */
+    wrapsRequest: boolean;
+    /** The body holds a live `page.on('pageerror', …)` registration. A guard moved
+     *  into a shared helper is still delivered — see hasPageErrorGuard. */
+    hasGuard: boolean;
     assertions: HelperAssertion[];
+    /** TypeScript only: signature parameters with no type annotation (`page`, not
+     *  `page: Page`). Empty for other languages. */
+    untypedParams: string[];
 }
+/** The parameter names in a TS signature that carry no `: type`. Reads the signature
+ *  from the definition line to its `{` (Prettier wraps long signatures), takes the
+ *  first balanced `(...)`, and splits it on top-level commas. */
+export declare function untypedParamsOf(sigLines: string[]): string[];
 /**
  * Structured extraction of the module-level helpers in a utils file.
  *
@@ -27,8 +40,23 @@ export interface UtilsHelper {
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
-export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec, allowedAssertion?: RegExp | ((expr: string) => boolean)): UtilsHelper[];
+export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
 /** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
  *  comments are `#…`; TS/JS go through the shared stripper. */
 /** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
 export declare function blankStrings(src: string, spec: UtilsLanguageSpec): string;
+/** Assertions in a source file: lines (Python) / occurrences (TS) matching the
+ *  language's assertion pattern, with comments and string contents blanked so a
+ *  commented-out or quoted `expect(` never counts. */
+export declare function countAssertions(content: string, spec: UtilsLanguageSpec): number;
+/**
+ * A live `page.on('pageerror', …)` registration — the guard the enhancer adds and
+ * modularization must not drop. Exactly `pageerror`: a `console` listener is not an
+ * error collector, and accepting it would let an unrelated listener mask the removal.
+ * The call is located on a copy with comments AND string contents blanked (so a
+ * commented-out or quoted example never satisfies the check) and its argument is read
+ * from the comment-blanked copy, where the `'pageerror'` literal is still legible.
+ * Both copies preserve offsets, so a Prettier-wrapped registration matches too.
+ */
+export declare function hasPageErrorGuard(content: string, spec: UtilsLanguageSpec): boolean;
+export declare function blankCommentsAndStrings(src: string, spec: UtilsLanguageSpec): string;

package/build/utils/utils-verify/parse.js

@@ -1,5 +1,96 @@
 import { normalizePath } from "./language-spec.js";
-import { stripCommentsAndStrings, stripStrings } from "../pom-scope/strip.js";
+import { stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
+/** The parameter names in a TS signature that carry no `: type`. Reads the signature
+ *  from the definition line to its `{` (Prettier wraps long signatures), takes the
+ *  first balanced `(...)`, and splits it on top-level commas. */
+export function untypedParamsOf(sigLines) {
+    const sig = sigLines.join(" ");
+    const open = sig.indexOf("(");
+    if (open === -1) {
+        // Bare-arrow form: `export const open = async page => …` — one parameter,
+        // untyped by construction (a typed single parameter requires parentheses).
+        const bare = /(?:^|=)\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*=>/.exec(sig);
+        return bare ? [bare[1]] : [];
+    }
+    // `>` closes a nesting level only when it is not the arrow token's tail:
+    // `(callback: (x: string) => void, page)` must not close at `=>`.
+    const closes = (ch, prev) => ch === ")" || ch === "]" || ch === "}" || (ch === ">" && prev !== "=");
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < sig.length; i++) {
+        const ch = sig[i];
+        if ("([{<".includes(ch))
+            depth++;
+        else if (closes(ch, sig[i - 1] ?? "")) {
+            depth--;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close === -1)
+        return [];
+    const params = [];
+    let cur = "";
+    depth = 0;
+    for (let i = open + 1; i < close; i++) {
+        const ch = sig[i];
+        if ("([{<".includes(ch))
+            depth++;
+        else if (closes(ch, sig[i - 1] ?? ""))
+            depth--;
+        if (ch === "," && depth === 0) {
+            params.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    params.push(cur);
+    const out = [];
+    for (const raw of params) {
+        const param = raw.trim().replace(/^\.\.\./, "");
+        if (!param)
+            continue;
+        // A default value means TypeScript infers the type — not a finding, even
+        // unannotated (`expectedStatus = 200`). `=>` inside a function-type
+        // annotation is not a default.
+        if (/=(?!>)/.test(param.replace(/\([^)]*\)/g, "")))
+            continue;
+        // A binding pattern's inner colons are renames, not annotations:
+        // `{ page: browserPage }` is implicitly any unless a `:` follows the
+        // complete pattern.
+        if (param.startsWith("{") || param.startsWith("[")) {
+            let d = 0;
+            let after = -1;
+            for (let i = 0; i < param.length; i++) {
+                if ("([{<".includes(param[i]))
+                    d++;
+                else if (closes(param[i], param[i - 1] ?? "")) {
+                    d--;
+                    if (d === 0) {
+                        after = i + 1;
+                        break;
+                    }
+                }
+            }
+            if (after === -1 || !param.slice(after).trimStart().startsWith(":"))
+                out.push(param.replace(/\s+/g, " "));
+            continue;
+        }
+        if (param.includes(":")) {
+            // `page: any` compiles clean under noImplicitAny — the customer's compiler
+            // will NEVER report it, which makes it the one case this advisory can catch
+            // that tsc cannot. It is also the exact legacy convention SKYR-3324 wrote.
+            if (/:\s*any\s*$/.test(param))
+                out.push(param.split(":")[0].trim().replace(/\?$/, "") + ": any");
+            continue;
+        }
+        out.push(param.replace(/\?$/, ""));
+    }
+    return out;
+}
 /**
  * Structured extraction of the module-level helpers in a utils file.
  *
@@ -10,10 +101,7 @@ import { stripCommentsAndStrings, stripStrings } from "../pom-scope/strip.js";
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
-export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAssertion) {
-    const isAllowed = typeof allowedAssertion === "function"
-        ? allowedAssertion
-        : (expr) => allowedAssertion.test(expr);
+export function parseUtilsFile(content, spec) {
     const lines = content.split("\n");
     const helpers = [];
     let i = 0;
@@ -37,7 +125,14 @@ export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAss
             name,
             line: start + 1,
             endLine: Math.max(end, start + 1),
+            wrapsRequest: false,
+            hasGuard: hasPageErrorGuard(body.join("\n"), spec),
             assertions: [],
+            untypedParams: spec.language === "typescript"
+                ? // The blanked copy: a comment inside a wrapped signature must not
+                    // reach the agent as a "parameter".
+                    untypedParamsOf(signatureLines(scan))
+                : [],
         };
         let requests = 0;
         for (let k = 0; k < body.length; k++) {
@@ -77,13 +172,13 @@ export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAss
                 helper.assertions.push({
                     line: start + k + 1,
                     text: original,
-                    allowed: isAllowed(original),
                 });
                 k = last;
             }
         }
         // A helper wrapping two requests is a sequence, not "one SDK call": it has no single
         // route to be a duplicate of, and the shared-helper rules do not apply to it.
+        helper.wrapsRequest = requests > 0;
         if (requests > 1) {
             helper.method = undefined;
             helper.path = undefined;
@@ -122,16 +217,88 @@ export function blankStrings(src, spec) {
         .map((line) => line.replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]))
         .join("\n");
 }
-function blankCommentsAndStrings(src, spec) {
+/** Assertions in a source file: lines (Python) / occurrences (TS) matching the
+ *  language's assertion pattern, with comments and string contents blanked so a
+ *  commented-out or quoted `expect(` never counts. */
+export function countAssertions(content, spec) {
+    const scan = blankCommentsAndStrings(content, spec);
+    if (spec.language === "python")
+        return scan.split("\n").filter((l) => spec.assertionRe.test(l)).length;
+    return (scan.match(new RegExp(spec.assertionRe.source, "g")) ?? []).length;
+}
+/**
+ * A live `page.on('pageerror', …)` registration — the guard the enhancer adds and
+ * modularization must not drop. Exactly `pageerror`: a `console` listener is not an
+ * error collector, and accepting it would let an unrelated listener mask the removal.
+ * The call is located on a copy with comments AND string contents blanked (so a
+ * commented-out or quoted example never satisfies the check) and its argument is read
+ * from the comment-blanked copy, where the `'pageerror'` literal is still legible.
+ * Both copies preserve offsets, so a Prettier-wrapped registration matches too.
+ */
+export function hasPageErrorGuard(content, spec) {
+    const noComments = blankComments(content, spec);
+    const code = blankStrings(noComments, spec);
+    for (const m of code.matchAll(/\bpage\.on\(/g)) {
+        const at = (m.index ?? 0) + m[0].length;
+        if (/^\s*["']pageerror["']/.test(noComments.slice(at)))
+            return true;
+    }
+    return false;
+}
+/** Comments blanked, strings preserved, offsets kept. TS/JS use the shared stripper;
+ *  Python blanks each line from its first `#` outside a string. */
+function blankComments(src, spec) {
+    if (spec.language !== "python")
+        return stripComments(src);
+    const blanked = blankStrings(src, spec).split("\n");
+    return src
+        .split("\n")
+        .map((line, i) => {
+        const at = blanked[i].indexOf("#");
+        return at === -1
+            ? line
+            : line.slice(0, at) + " ".repeat(line.length - at);
+    })
+        .join("\n");
+}
+export function blankCommentsAndStrings(src, spec) {
     if (spec.language !== "python")
         return stripCommentsAndStrings(src);
     return src
         .split("\n")
         .map((line) => line
         .replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0])
-        .replace(/#.*$/, ""))
+        // Blanked, not deleted: callers scan this copy for OFFSETS and read the text
+        // back out of the original, so every line must keep its length.
+        .replace(/#.*$/, (c) => " ".repeat(c.length)))
         .join("\n");
 }
+function signatureLines(body) {
+    // The signature runs until its parameter parentheses close: a `{` inside a
+    // wrapped object-type parameter (`opts: { a: string },`) is not the body
+    // opener, so a bare `/[{]|=>/` test truncated such signatures.
+    const out = [];
+    let depth = 0;
+    let opened = false;
+    for (const l of body) {
+        out.push(l);
+        for (let i = 0; i < l.length; i++) {
+            if (l[i] === "(") {
+                depth++;
+                opened = true;
+            }
+            else if (l[i] === ")")
+                depth--;
+        }
+        if (opened && depth <= 0)
+            break;
+        if (!opened && /=>/.test(l))
+            break; // bare-arrow form has no parentheses
+        if (out.length > 12)
+            break;
+    }
+    return out;
+}
 /** Exclusive end index of a Python def starting at `start`: the next non-blank line at
  *  column 0 (a following def, import, or module statement). */
 function pythonBodyEnd(lines, start) {
@@ -147,12 +314,26 @@ function pythonBodyEnd(lines, start) {
 /** Exclusive end index of a brace-delimited definition starting at `start`. Strings and
  *  comments are not tracked — helper bodies contain request paths, not braces in
  *  strings — and an unbalanced body runs to end of file rather than throwing. */
+/** The definition line through the one that opens the body (`{` or `=>`). */
 function braceBodyEnd(lines, start) {
     let depth = 0;
     let opened = false;
+    // A `{` inside the signature's still-open parentheses is an object-type
+    // parameter (`opts: { a: string },` wrapped by Prettier), not the body opener.
+    let parens = 0;
     for (let i = start; i < lines.length; i++) {
         for (const ch of lines[i]) {
-            if (ch === "{") {
+            // Parens matter only until the body opens: they exist to get past a wrapped
+            // signature. Tracking them afterwards let one unbalanced `(` in a string or
+            // comment blind the brace count for the rest of the file — swallowing every
+            // later helper and misattributing its violations (the gate then never clears).
+            if (!opened && ch === "(")
+                parens++;
+            else if (!opened && ch === ")")
+                parens = Math.max(0, parens - 1);
+            else if (!opened && parens > 0)
+                continue;
+            else if (ch === "{") {
                 depth++;
                 opened = true;
             }

package/build/utils/utils-verify/retrofit-equivalence.d.ts

@@ -0,0 +1,43 @@
+import { type UtilsLanguageSpec } from "./language-spec.js";
+export interface RetrofitMismatch {
+    /** Absolute path of the rewired pre-existing test. */
+    file: string;
+    /** The shared helper the file now calls in place of its own request block. */
+    helper: string;
+    method: string;
+    path: string;
+    /** What the substitution changed about the request. */
+    detail: string;
+}
+/**
+ * Whether a retrofit changed the request the rewired test sends.
+ *
+ * STEP 5c edits a PRE-EXISTING test — code the customer already owns and whose
+ * behaviour nothing in this run chose — to call a shared helper instead of its own
+ * inline request block. That is only safe if the helper sends the same request. It
+ * usually does, because the helper was extracted from an identical block; but nothing
+ * checked it, and a helper that hardcodes a field the block never sent (or omits one
+ * it did) silently changes what the customer's test exercises. The failure is quiet:
+ * the test still runs, and a red result reads like any other red.
+ *
+ * The advisory path already refuses to OFFER such a site (see `substitutable` in
+ * call-sites.ts). This is the same question asked after the fact, about the edit that
+ * was actually made, and the rule is stricter: offering tolerates a site with an extra
+ * field, because extending the helper with a defaulted parameter is the sanctioned
+ * move; a completed retrofit must leave the request byte-equivalent in shape, so the
+ * field sets must match exactly in both directions.
+ *
+ * LIMIT: this compares the request's SHAPE — which fields and options it carries —
+ * not the values passed. A baseline sending `status: "draft"` rewired to
+ * `createPost(..., "published")` has the same field set and is not reported. Value
+ * equivalence needs argument-to-parameter binding, default resolution and expression
+ * normalisation; a wrong answer here REFUSES the report, so it is deliberately left
+ * out rather than approximated. The value case is also visible in the rewired file's
+ * own diff, where a hardcoded helper field is not.
+ *
+ * Compares against the file's committed baseline (`git show HEAD:<path>`), which is
+ * the only record of what the block sent before the edit. Fails OPEN — an untracked
+ * file, a detached worktree, or an unreadable baseline yields no mismatches rather
+ * than a refusal the agent cannot act on.
+ */
+export declare function retrofitMismatches(retrofitFile: string, utilsFiles: string[], spec: UtilsLanguageSpec): Promise<RetrofitMismatch[]>;

package/build/utils/utils-verify/retrofit-equivalence.js

@@ -0,0 +1,218 @@
+import { execFile } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { promisify } from "util";
+import { logger } from "../logger.js";
+import { detectGitRoot } from "../gitStaging.js";
+import { blankCommentsAndStrings, parseUtilsFile } from "./parse.js";
+import { normalizePath } from "./language-spec.js";
+import { callText, hasSchemaCheck, requestFields, REQUEST_CALL_RE, SCHEMA_SCAN_LINES, shapeKeys, } from "./call-sites.js";
+import { escapeRegExp } from "../regex.js";
+const exec = promisify(execFile);
+/**
+ * Whether a retrofit changed the request the rewired test sends.
+ *
+ * STEP 5c edits a PRE-EXISTING test — code the customer already owns and whose
+ * behaviour nothing in this run chose — to call a shared helper instead of its own
+ * inline request block. That is only safe if the helper sends the same request. It
+ * usually does, because the helper was extracted from an identical block; but nothing
+ * checked it, and a helper that hardcodes a field the block never sent (or omits one
+ * it did) silently changes what the customer's test exercises. The failure is quiet:
+ * the test still runs, and a red result reads like any other red.
+ *
+ * The advisory path already refuses to OFFER such a site (see `substitutable` in
+ * call-sites.ts). This is the same question asked after the fact, about the edit that
+ * was actually made, and the rule is stricter: offering tolerates a site with an extra
+ * field, because extending the helper with a defaulted parameter is the sanctioned
+ * move; a completed retrofit must leave the request byte-equivalent in shape, so the
+ * field sets must match exactly in both directions.
+ *
+ * LIMIT: this compares the request's SHAPE — which fields and options it carries —
+ * not the values passed. A baseline sending `status: "draft"` rewired to
+ * `createPost(..., "published")` has the same field set and is not reported. Value
+ * equivalence needs argument-to-parameter binding, default resolution and expression
+ * normalisation; a wrong answer here REFUSES the report, so it is deliberately left
+ * out rather than approximated. The value case is also visible in the rewired file's
+ * own diff, where a hardcoded helper field is not.
+ *
+ * Compares against the file's committed baseline (`git show HEAD:<path>`), which is
+ * the only record of what the block sent before the edit. Fails OPEN — an untracked
+ * file, a detached worktree, or an unreadable baseline yields no mismatches rather
+ * than a refusal the agent cannot act on.
+ */
+export async function retrofitMismatches(retrofitFile, utilsFiles, spec) {
+    const baseline = await committedBaseline(retrofitFile);
+    if (baseline === undefined)
+        return [];
+    let delivered;
+    try {
+        delivered = await fs.promises.readFile(retrofitFile, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const byRoute = new Map();
+    for (const utilsFile of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(utilsFile, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const helpers = parseUtilsFile(content, spec);
+        // Positions come from a comment/string-blanked copy (offsets preserved), so a
+        // commented-out or quoted request is never read as a real one; the text itself
+        // is taken from the original.
+        const scan = blankCommentsAndStrings(content, spec);
+        for (const m of scan.matchAll(new RegExp(REQUEST_CALL_RE))) {
+            const start = m.index ?? 0;
+            const line = content.slice(0, start).split("\n").length;
+            const owner = helpers.find((h) => h.line <= line && line <= h.endLine);
+            if (!owner?.method || !owner.normalizedPath)
+                continue;
+            const call = callText(content, start + m[0].length - 1);
+            const route = `${owner.method} ${owner.normalizedPath}`;
+            const list = byRoute.get(route) ?? [];
+            // One helper may issue several requests; judge it by its first for this route.
+            if (!list.some((h) => h.helper === owner.name))
+                list.push({
+                    helper: owner.name,
+                    keys: shapeKeys(call),
+                    fields: requestFields(content, call, start),
+                    schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
+                });
+            byRoute.set(route, list);
+        }
+    }
+    if (byRoute.size === 0)
+        return [];
+    // The requests the file used to make itself, before the edit.
+    const baselineByRoute = new Map();
+    const ambiguous = new Set();
+    const baselineScan = blankCommentsAndStrings(baseline, spec);
+    for (const m of baselineScan.matchAll(new RegExp(REQUEST_CALL_RE))) {
+        const start = m.index ?? 0;
+        const line = baseline.slice(0, start).split("\n").length;
+        const call = callText(baseline, start + m[0].length - 1);
+        const method = spec.methodRe.exec(call)?.[1]?.toUpperCase();
+        const p = spec.pathRe.exec(call)?.[1];
+        if (!method || !p)
+            continue;
+        const key = `${method} ${normalizePath(p)}`;
+        const seen = baselineByRoute.get(key);
+        const here = {
+            keys: shapeKeys(call),
+            fields: requestFields(baseline, call, start),
+            schemaChecked: hasSchemaCheck(baseline, line, line + SCHEMA_SCAN_LINES),
+        };
+        if (!seen) {
+            baselineByRoute.set(key, here);
+            continue;
+        }
+        // The same route more than once: only one of them was replaced, and nothing here
+        // says which. Identical blocks compare the same either way; DIFFERING ones are
+        // ambiguous, so the route is dropped rather than judged against a block that may
+        // not be the one the helper took over. Occurrence-level attribution would need to
+        // know which block disappeared, and getting that wrong refuses a safe edit.
+        if (!sameSet(seen.fields, here.fields) || !sameSet(seen.keys, here.keys))
+            ambiguous.add(key);
+    }
+    for (const key of ambiguous)
+        baselineByRoute.delete(key);
+    if (baselineByRoute.size === 0)
+        return [];
+    const calls = blankCommentsAndStrings(delivered, spec);
+    const out = [];
+    for (const [route, helpers] of byRoute) {
+        const before = baselineByRoute.get(route);
+        if (!before)
+            continue; // the file never made this request; nothing was replaced
+        for (const helper of helpers) {
+            // Only a helper this file actually calls now can have replaced anything —
+            // under whatever local name it was imported as (`import create_order as mk`).
+            const local = localBindings(calls, helper.helper);
+            if (!local.some((n) => new RegExp(`\\b${escapeRegExp(n)}\\s*\\(`).test(calls)))
+                continue;
+            const added = [...helper.fields].filter((f) => !before.fields.has(f));
+            const dropped = [...before.fields].filter((f) => !helper.fields.has(f));
+            const reasons = [];
+            // Non-liftable call options (query_params, timeout, …): the advisory compares
+            // these before offering a site, so the completed edit must be held to them too.
+            const optAdded = [...helper.keys].filter((k) => !before.keys.has(k));
+            const optDropped = [...before.keys].filter((k) => !helper.keys.has(k));
+            if (optAdded.length > 0 || optDropped.length > 0)
+                reasons.push(`the request options changed (${[
+                    ...optAdded.map((k) => `+\`${k}\``),
+                    ...optDropped.map((k) => `-\`${k}\``),
+                ].join(", ")})`);
+            if (added.length > 0)
+                reasons.push(`it now also sends ${added.map((f) => `\`${f}\``).join(", ")}`);
+            if (dropped.length > 0)
+                reasons.push(`it no longer sends ${dropped.map((f) => `\`${f}\``).join(", ")}`);
+            if (before.schemaChecked && !helper.schemaChecked)
+                reasons.push("the response-schema check the block carried is gone");
+            if (reasons.length === 0)
+                continue;
+            const [method, ...rest] = route.split(" ");
+            out.push({
+                file: retrofitFile,
+                helper: helper.helper,
+                method,
+                path: rest.join(" "),
+                detail: reasons.join("; "),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The local names a module's export can be called by in this file: the export's own
+ * name, plus any `import X as Y` / `{ X as Y }` alias. A retrofit that imported the
+ * helper under an alias would otherwise look uncalled and fail open.
+ */
+function localBindings(content, exported) {
+    const esc = escapeRegExp(exported);
+    const names = new Set([exported]);
+    // Python `from M import x as y`; TS `import { x as y }` / `{ x: y } = require(...)`.
+    for (const re of [
+        new RegExp(`\\b${esc}\\s+as\\s+([A-Za-z_$][\\w$]*)`, "g"),
+        new RegExp(`\\b${esc}\\s*:\\s*([A-Za-z_$][\\w$]*)`, "g"),
+    ])
+        for (const m of content.matchAll(re))
+            names.add(m[1]);
+    return [...names];
+}
+function sameSet(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const v of a)
+        if (!b.has(v))
+            return false;
+    return true;
+}
+/** The file's content at HEAD, or undefined when there is nothing to compare against
+ *  (untracked, no git root, or git unavailable). Never throws. */
+async function committedBaseline(file) {
+    const root = detectGitRoot(file);
+    if (!root)
+        return undefined;
+    const rel = path.relative(root, file);
+    if (!rel || rel.startsWith(".."))
+        return undefined;
+    try {
+        const { stdout } = await exec("git", ["show", `HEAD:${rel}`], {
+            cwd: root,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (err) {
+        // A file added by this run has no HEAD version — the common case, not an error.
+        logger.debug("No committed baseline for a retrofit; skipping equivalence", {
+            file,
+            error: String(err),
+        });
+        return undefined;
+    }
+}

package/build/utils/utils-verify/stage.d.ts

@@ -16,6 +16,12 @@
 export interface StagingResult {
     /** Files that reached the index. */
     staged: string[];
+    /** Utils files located for the test (absolute), staged or not. */
+    utilsFiles: string[];
+    /** Pre-existing generated siblings this run edited to import from those files
+     *  (absolute) — the caller records them as retrofits so the report must disclose
+     *  them. */
+    retrofits: string[];
     /** Utils files that `git add` refused (gitignored, outside the repo, git failure) —
      *  the tests importing them will fail in the output commit, so the verify pass
      *  treats a non-empty list as a failed verification. */

package/build/utils/utils-verify/stage.js

@@ -12,7 +12,9 @@ const execFileAsync = promisify(execFile);
 export async function stageUtilsArtifacts(testFile, language) {
     const staged = [];
     const failed = [];
-    const result = { staged, failed };
+    const utilsFilesOut = [];
+    const retrofits = [];
+    const result = { staged, failed, utilsFiles: utilsFilesOut, retrofits };
     // Outside a testbot run stageGeneratedPaths is a no-op; report nothing as staged
     // rather than a list of files nothing touched.
     if (!isTestbotEnabled())
@@ -46,7 +48,9 @@ export async function stageUtilsArtifacts(testFile, language) {
     // file, so without this the sibling's edit drops out of the output commit while the
     // utils change lands — the same class of hole as the unstaged utils file.
     if (files.length > 0) {
+        utilsFilesOut.push(...files);
         for (const sibling of await modifiedSiblingsImporting(testFile, files, language)) {
+            retrofits.push(sibling);
             try {
                 await stageGeneratedPaths(sibling);
                 staged.push(sibling);
@@ -69,7 +73,13 @@ async function modifiedSiblingsImporting(testFile, utilsFiles, language) {
     let modified;
     try {
         // `-z`: unquoted, NUL-separated — git C-quotes non-ASCII paths otherwise.
-        const { stdout } = await execFileAsync("git", ["diff", "-z", "--name-only"], {
+        const { stdout } = await execFileAsync("git", 
+        // Against HEAD, modified only: a test THIS run created is staged at discovery, so
+        // its later STEP 5b edits show in a plain `git diff` and it would masquerade as a
+        // pre-existing sibling (observed: the report gate then demanded an execution no
+        // record could satisfy, and the agent un-shared the helpers to escape). Files
+        // added since HEAD are excluded; they are staged by their own tool calls.
+        ["diff", "-z", "--name-only", "--diff-filter=M", "HEAD"], {
             cwd: root,
             encoding: "utf8",
         });