@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/utils/utils-verify/fixed-sleep.d.ts

@@ -0,0 +1,96 @@
+import { type UtilsLanguage } from "./language-spec.js";
+/**
+ * A fixed sleep inside a shared helper — a wait for a duration rather than for a
+ * condition, written into the module every test imports.
+ *
+ * The substance-floor row of the code-reuse plan measures whether a shared helper
+ * holds a whole step or something one scenario's narrative needs. A sleep is the
+ * form that costs every later caller: it is inherited by every test that imports the
+ * helper, it converts a wrong result into a slow one, and it is invisible at the call
+ * site. Run 9 (gha-2026-09-18-integration-238cc734) produced both of its shapes from
+ * ONE build — a browser `signIn` carrying `waitForTimeout(1500)`, and a Python
+ * `get_order` whose ten-attempt retry loop sleeps five seconds an attempt — beside a
+ * clean `signIn` of the same name on the same repository. Same model, same commit:
+ * the prompt rule holds in some runs and not others, which is a rule without a gate.
+ *
+ * The bare wait is the smaller half. A retry loop whose backoff is a sleep hides the
+ * duration BEHIND an iteration count, so a rule written for the bare form alone would
+ * read `time.sleep(sleep_time)` as five seconds and miss the fifty this one costs.
+ * Both are found here, and the loop's multiplier is reported with the finding.
+ *
+ * SCOPE — the header-bearing Skyramp module, and nothing else. The caller reaches
+ * this through `locateUtilsFiles`, which recognises a module by the `Generated by
+ * Skyramp on …` header, so a repository's own helper and a page object are out of
+ * reach by construction. That is deliberate in both directions: an in-house module
+ * may not be modified beyond being added to (SKYR-4483), and the POM path treats a
+ * customer method's internal `waitForTimeout` as a REASON TO PREFER it (see
+ * `pom-aware-code-reuse`, STEP 2b) — a rule that flagged sleeps anywhere would
+ * contradict that prompt.
+ */
+export interface HelperSleep {
+    /** 1-based line in the FILE. */
+    line: number;
+    /** The call as the agent reads it: the source line(s) it spans, whitespace collapsed. */
+    text: string;
+    /** What one call waits, in milliseconds — resolved from a numeric literal or from
+     *  a parameter's numeric default. `undefined` when neither is readable; the finding
+     *  still stands, because a sleep of an unknown length is not a shorter one. */
+    ms?: number;
+    /** Present when the sleep sits inside one or more loops, which multiply it.
+     *  `depth` is how many enclose it; `iterations` is the PRODUCT of their bounds, and
+     *  is `undefined` as soon as one of them is a condition rather than a count. */
+    loop?: {
+        iterations?: number;
+        depth: number;
+    };
+}
+/**
+ * What a Python module binds to a sleep function, read from its imports.
+ *
+ * The bare form cannot be matched by SPELLING. `def run(sleep): return sleep(5)`
+ * invokes a callback and was reported as a blocking sleep, and a module that never
+ * imports one was too — a false blocking finding on a correct file. The inverse was
+ * also true and is not something spelling could have caught: `from time import sleep
+ * as pause` binds the sleep to `pause`, and `pause(2)` was missed entirely.
+ *
+ * So the names come from the module rather than from a list: whatever `time` and
+ * `asyncio` are imported AS, and whatever their `sleep` is imported AS.
+ */
+export interface SleepBindings {
+    /** Names that call a sleep directly: `sleep`, or its `as` alias. */
+    bare: Set<string>;
+    /** Qualifiers whose `.sleep` is a sleep: `time`, `asyncio`, or an alias. */
+    qualified: Set<string>;
+}
+export declare function pythonSleepBindings(content: string): SleepBindings;
+/** `1500` → `1.5s`, `50000` → `50s`. Seconds throughout: a reviewer compares a helper's
+ *  cost against a test's runtime, not against a frame. */
+export declare function describeSleepMs(ms: number): string;
+/**
+ * Every fixed sleep in one helper body.
+ *
+ * `body` is the raw source lines, `scan` the same lines with comments and string
+ * CONTENTS blanked (offsets preserved) — so a commented-out wait and a wait quoted
+ * inside a fill() are neither of them calls. Structure is read from `scan`; the text
+ * the agent is shown comes from `body`.
+ */
+export declare function fixedSleepsIn(body: string[], scan: string[], language: UtilsLanguage, params: string[], startLine: number, bindings?: SleepBindings): HelperSleep[];
+/** The whole finding for one helper: every sleep it holds, what each costs, and what
+ *  the loop around one of them multiplies it by. ONE finding per helper — so one
+ *  `reuse-verify: allow` marker documents a helper's timing decision rather than
+ *  needing one line per call. */
+export declare function describeFixedSleeps(sleeps: HelperSleep[]): string;
+/** What every call of the helper costs at worst, loops multiplied in. `undefined`
+ *  when any sleep's duration — or any loop's bound — could not be read: a total that
+ *  silently omitted one would understate the cost, and understating it is how the
+ *  finding gets argued down. */
+export declare function totalMs(sleeps: HelperSleep[]): number | undefined;
+/**
+ * What to do INSTEAD, named in the finding itself.
+ *
+ * A finding an agent cannot act on burns verify rounds and is then documented away,
+ * which is the outcome this gate exists to avoid. So the text never says "remove the
+ * sleep": it names the wait that replaces it, and rules out the fix the model reaches
+ * for first — a shorter sleep, which is the same defect at a smaller number.
+ */
+export declare function fixedSleepReplacement(family: "api" | "browser", language: UtilsLanguage): string;

package/build/utils/utils-verify/fixed-sleep.js

@@ -0,0 +1,461 @@
+import { playwrightSpelling } from "./language-spec.js";
+import { HELPER_ASSERTION_POLICIES } from "../../prompts/shared-helper-policy.js";
+export function pythonSleepBindings(content) {
+    const bare = new Set();
+    const qualified = new Set();
+    for (const m of content.matchAll(/^\s*from\s+(time|asyncio)\s+import\s+([^\n#]+)/gm))
+        for (const raw of m[2].replace(/[()]/g, "").split(",")) {
+            const [name, alias] = raw.trim().split(/\s+as\s+/);
+            if (name === "sleep")
+                bare.add(alias?.trim() || "sleep");
+        }
+    for (const m of content.matchAll(/^\s*import\s+(time|asyncio)(?:\s+as\s+([A-Za-z_]\w*))?\s*$/gm))
+        qualified.add(m[2] ?? m[1]);
+    return { bare, qualified };
+}
+/** The sleep call shapes to look for in one FILE — Python's depend on what that
+ *  file imports, so the table is built per file rather than declared once. */
+function formsFor(language, bindings) {
+    if (language !== "python")
+        return FORMS[language];
+    const forms = [
+        // Playwright for Python — milliseconds, like its JavaScript spelling.
+        { re: /\.wait_for_timeout\s*\(/g, arg: 0, unit: "ms" },
+    ];
+    // Seconds, in every Python form.
+    const qualified = [...bindings.qualified];
+    if (qualified.length > 0)
+        forms.push({
+            re: new RegExp(`(?<![\\w.])(?:${qualified.join("|")})\\.sleep\\s*\\(`, "g"),
+            arg: 0,
+            unit: "s",
+        });
+    // `time.sleep(…)` / `asyncio.sleep(…)` written without an `import` this pass can
+    // see — a fully qualified call names its module, so no binding is needed to read it.
+    forms.push({
+        re: /(?<![\w.])(?:time|asyncio)\.sleep\s*\(/g,
+        arg: 0,
+        unit: "s",
+    });
+    if (bindings.bare.size > 0)
+        forms.push({
+            re: new RegExp(`(?<![\\w.])(?:${[...bindings.bare].join("|")})\\s*\\(`, "g"),
+            arg: 0,
+            unit: "s",
+        });
+    return forms;
+}
+const FORMS = {
+    python: [],
+    typescript: [
+        { re: /\.waitForTimeout\s*\(/g, arg: 0, unit: "ms" },
+        // `timers/promises`' setTimeout, and a module-local `sleep`/`delay` helper —
+        // awaited, because only an awaited promise makes the caller wait.
+        {
+            re: /(?<![\w.])await\s+(?:setTimeout|sleep|delay)\s*\(/g,
+            arg: 0,
+            unit: "ms",
+        },
+        // `await new Promise((resolve) => setTimeout(resolve, 1000))` — the idiom that
+        // spells a sleep where no API offers one. The delay is the second argument.
+        {
+            re: /(?<![\w.])setTimeout\s*\(/g,
+            arg: 1,
+            unit: "ms",
+            inPromise: true,
+        },
+    ],
+    javascript: [],
+};
+FORMS.javascript = FORMS.typescript;
+/** `1500` → `1.5s`, `50000` → `50s`. Seconds throughout: a reviewer compares a helper's
+ *  cost against a test's runtime, not against a frame. */
+export function describeSleepMs(ms) {
+    return `${Number((ms / 1000).toFixed(3))}s`;
+}
+/**
+ * Every fixed sleep in one helper body.
+ *
+ * `body` is the raw source lines, `scan` the same lines with comments and string
+ * CONTENTS blanked (offsets preserved) — so a commented-out wait and a wait quoted
+ * inside a fill() are neither of them calls. Structure is read from `scan`; the text
+ * the agent is shown comes from `body`.
+ */
+export function fixedSleepsIn(body, scan, language, params, startLine, bindings = { bare: new Set(), qualified: new Set() }) {
+    const src = scan.join("\n");
+    // A parameter shadows a module binding: `run(sleep)` calling `sleep(5)` invokes
+    // what its caller passed, whatever the module imported.
+    const shadowed = new Set(params.map(paramNameOf).filter(Boolean));
+    const lineStarts = lineStartOffsets(src);
+    const promises = language === "python" ? [] : promiseSpans(src);
+    // Which loops repeat which stretch of source, computed ONCE for the body. A sleep
+    // is inside a loop when its offset lies in that loop's span — see loopSpans.
+    const loops = loopSpans(src, scan, language, params);
+    const found = new Map();
+    for (const form of formsFor(language, bindings)) {
+        for (const m of src.matchAll(form.re)) {
+            const open = m.index + m[0].length - 1;
+            if (form.inPromise && !promises.some(([a, b]) => open > a && open < b))
+                continue;
+            // A DECLARATION is not a call: `def sleep(seconds)` names a helper, it does
+            // not wait, and reporting it is a false BLOCKING finding on a correct file —
+            // the one outcome this gate must not produce. Only the bare Python form is
+            // exposed to this; every other form requires a `.` or an `await` before it,
+            // which a declaration cannot carry. Checked here rather than by blanking the
+            // signature span: `signatureLines` reads the sole `(` of a bare-arrow helper
+            // (`const settle = async page => { await page.waitForTimeout(250); }`) as its
+            // parameter list, so blanking that span would blank the sleep itself.
+            if (/\bdef$/.test(src.slice(0, m.index).trimEnd()))
+                continue;
+            // The called name, when the form matched a bare one.
+            const called = /^([A-Za-z_$][\w$]*)\s*\($/.exec(m[0]);
+            if (called && shadowed.has(called[1]))
+                continue;
+            const awaited = /^await\s+([A-Za-z_$][\w$]*)\s*\($/.exec(m[0]);
+            if (awaited && shadowed.has(awaited[1]))
+                continue;
+            const close = closeOf(src, open);
+            if (close === -1)
+                continue;
+            const args = splitArgs(src.slice(open + 1, close));
+            const raw = args[form.arg];
+            const value = raw === undefined ? undefined : resolveNumber(raw, params);
+            const first = lineOf(lineStarts, m.index);
+            const last = lineOf(lineStarts, close);
+            found.set(m.index, {
+                line: startLine + first,
+                text: body
+                    .slice(first, last + 1)
+                    .join(" ")
+                    .trim()
+                    .replace(/\s+/g, " "),
+                ms: value === undefined
+                    ? undefined
+                    : value * (form.unit === "s" ? 1000 : 1),
+                loop: enclosedBy(loops, m.index),
+            });
+        }
+    }
+    return [...found.entries()].sort((a, b) => a[0] - b[0]).map(([, s]) => s);
+}
+/** The whole finding for one helper: every sleep it holds, what each costs, and what
+ *  the loop around one of them multiplies it by. ONE finding per helper — so one
+ *  `reuse-verify: allow` marker documents a helper's timing decision rather than
+ *  needing one line per call. */
+export function describeFixedSleeps(sleeps) {
+    const each = sleeps.map((s) => {
+        const where = s.loop ? `, inside ${describeLoop(s.loop)}` : "";
+        const cost = s.ms === undefined
+            ? " — a wait for a duration this pass cannot read"
+            : ` — ${describeSleepMs(s.ms)} per call`;
+        return `\`${s.text}\` (line ${s.line})${where}${cost}`;
+    });
+    // The total is what a LOOP or a second sleep adds to what each line already says;
+    // for one bare wait it would only restate the duration.
+    const total = sleeps.length === 1 && !sleeps[0].loop ? undefined : totalMs(sleeps);
+    return (each.join("; ") +
+        (total === undefined
+            ? ""
+            : ` — up to ${describeSleepMs(total)} inside one helper`));
+}
+/** `a loop of up to 10 iterations` / `2 nested loops of up to 100 iterations in
+ *  total` / `a loop` when the bound is a condition. */
+function describeLoop(loop) {
+    const what = loop.depth === 1 ? "a loop" : `${loop.depth} nested loops`;
+    return loop.iterations === undefined
+        ? what
+        : `${what} of up to ${loop.iterations} iterations${loop.depth === 1 ? "" : " in total"}`;
+}
+/** What every call of the helper costs at worst, loops multiplied in. `undefined`
+ *  when any sleep's duration — or any loop's bound — could not be read: a total that
+ *  silently omitted one would understate the cost, and understating it is how the
+ *  finding gets argued down. */
+export function totalMs(sleeps) {
+    let sum = 0;
+    for (const s of sleeps) {
+        if (s.ms === undefined)
+            return undefined;
+        if (s.loop && s.loop.iterations === undefined)
+            return undefined;
+        sum += s.ms * (s.loop?.iterations ?? 1);
+    }
+    return sum;
+}
+/**
+ * Which loops repeat which stretch of the helper body.
+ *
+ * Read as SPANS rather than by walking lines outward from the sleep. The walk was
+ * wrong in four separate ways, each found after the last was fixed: it missed a
+ * Prettier-wrapped header (the depth-lowering line is only `) {`), it counted a loop
+ * that had already CLOSED before the sleep, it saw one of two loops opening on a
+ * single line, and it stopped at the innermost of a nest. All four are the same
+ * defect — a loop's extent is not a property of the lines around it — so the extent
+ * is now computed directly and the question becomes whether the sleep's offset falls
+ * inside it.
+ */
+function loopSpans(src, scan, language, params) {
+    return language === "python"
+        ? pythonLoopSpans(scan, params)
+        : braceLoopSpans(src, params);
+}
+/** Every loop whose span holds `offset`, folded into one bound. One unreadable
+ *  bound makes the product unknown rather than partial — a total that understates
+ *  the cost is how the finding gets argued down. */
+function enclosedBy(loops, offset) {
+    const inside = loops.filter((l) => offset > l.from && offset < l.to);
+    if (inside.length === 0)
+        return undefined;
+    return {
+        iterations: inside.some((l) => l.iterations === undefined)
+            ? undefined
+            : inside.reduce((a, l) => a * l.iterations, 1),
+        depth: inside.length,
+    };
+}
+function braceLoopSpans(src, params) {
+    const out = [];
+    for (const m of src.matchAll(/(?<![\w$.])(?:for|while)\s*\(/g)) {
+        const paren = m.index + m[0].length - 1;
+        const close = closeOf(src, paren);
+        if (close === -1)
+            continue;
+        const body = bodyAfter(src, close + 1);
+        if (!body)
+            continue;
+        // The header is read from its own span, so a wrapped one reads the same as a
+        // one-line one and two headers on a line each read their own bound.
+        out.push({
+            iterations: braceIterations(src.slice(m.index, close + 1), params),
+            ...body,
+        });
+    }
+    for (const m of src.matchAll(/(?<![\w$.])do\s*\{/g)) {
+        const brace = m.index + m[0].length - 1;
+        const end = matchingBrace(src, brace);
+        if (end !== -1)
+            out.push({ iterations: undefined, from: brace, to: end });
+    }
+    return out;
+}
+/** The statement a loop header repeats: a braced block, or one statement ending at
+ *  the next top-level `;`. */
+function bodyAfter(src, i) {
+    let k = i;
+    while (k < src.length && /\s/.test(src[k]))
+        k++;
+    if (k >= src.length)
+        return undefined;
+    if (src[k] === "{") {
+        const end = matchingBrace(src, k);
+        return end === -1 ? undefined : { from: k, to: end };
+    }
+    let depth = 0;
+    for (let j = k; j < src.length; j++) {
+        const c = src[j];
+        if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        else if (c === ";" && depth === 0)
+            return { from: i, to: j };
+    }
+    return { from: i, to: src.length };
+}
+function matchingBrace(src, open) {
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        if (src[i] === "{")
+            depth++;
+        else if (src[i] === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** Python has no braces: a loop repeats the lines indented past its header, or the
+ *  single statement written after the colon on the header's own line. */
+function pythonLoopSpans(scan, params) {
+    const starts = lineStartOffsets(scan.join("\n"));
+    const out = [];
+    for (let i = 0; i < scan.length; i++) {
+        const m = /^(\s*)(?:async\s+)?(?:for|while)\b/.exec(scan[i]);
+        if (!m)
+            continue;
+        const iterations = pythonIterations(scan[i], params);
+        const lineEnd = starts[i] + scan[i].length;
+        const colon = scan[i].indexOf(":");
+        if (colon !== -1 && scan[i].slice(colon + 1).trim() !== "") {
+            out.push({ iterations, from: starts[i] + colon, to: lineEnd });
+            continue;
+        }
+        const indent = m[1].length;
+        let last = i;
+        for (let j = i + 1; j < scan.length; j++) {
+            if (scan[j].trim() === "")
+                continue;
+            if (indentOf(scan[j]) <= indent)
+                break;
+            last = j;
+        }
+        if (last === i)
+            continue;
+        out.push({
+            iterations,
+            from: lineEnd,
+            to: starts[last] + scan[last].length,
+        });
+    }
+    return out;
+}
+/** `for idx in range(max_retries):` → the bound, when it is one number. A two- or
+ *  three-argument range, an iterable, and a `while` all read as unbounded. */
+function pythonIterations(line, params) {
+    const m = /\brange\s*\(\s*([^),]+)\s*\)/.exec(line);
+    return m ? wholeIterations(resolveNumber(m[1], params)) : undefined;
+}
+/** A loop runs a whole number of times. A non-integer bound (`i < 2.5`, which runs
+ *  three times) is left unknown rather than reported as itself: reporting 2.5 would
+ *  understate the total this module documents itself as never understating. A
+ *  DURATION may still be fractional — `asyncio.sleep(0.5)` is ordinary. */
+function wholeIterations(n) {
+    return n !== undefined && Number.isInteger(n) ? n : undefined;
+}
+/**
+ * `for (let i = 0; i < 6; i++)` → the bound. `<=` counts one more.
+ *
+ * The CANONICAL form only — one counter, started at zero, stepped by one, compared
+ * against the bound. Reading the comparison alone made `for (let i = -10; i < 6; i++)`
+ * count 6 where it runs 16, and `i += 2` count the same where it runs half as often.
+ * Anything else (a `for…of`, a non-zero start, a step that is not one) leaves the
+ * count unknown, which withholds the total rather than understating it — the
+ * invariant `totalMs` states. The sleep is still found; only its arithmetic is.
+ */
+function braceIterations(line, params) {
+    const m = /(?<![\w$.])for\s*\(\s*(?:let|var|const)?\s*([A-Za-z_$][\w$]*)\s*=\s*0\s*;\s*\1\s*(<=?)\s*([^;]+?)\s*;\s*(?:\1\s*\+\+|\+\+\s*\1|\1\s*\+=\s*1)\s*\)/.exec(line);
+    if (!m)
+        return undefined;
+    const n = wholeIterations(resolveNumber(m[3], params));
+    return n === undefined ? undefined : m[2] === "<=" ? n + 1 : n;
+}
+/** A numeric literal, or a parameter whose DEFAULT is one (`sleep_time=5`,
+ *  `retries: number = 10`). Anything else is unreadable — never guessed at. */
+function resolveNumber(text, params) {
+    const t = text.trim();
+    if (/^\d+(?:\.\d+)?$/.test(t))
+        return Number(t);
+    if (!/^[A-Za-z_$][\w$]*$/.test(t))
+        return undefined;
+    for (const p of params) {
+        const m = /^([A-Za-z_$][\w$]*)\s*\??\s*(?::[^=]*)?=\s*(.+)$/.exec(p.trim());
+        if (m && m[1] === t && /^\d+(?:\.\d+)?$/.test(m[2].trim()))
+            return Number(m[2].trim());
+    }
+    return undefined;
+}
+/** Spans of every `new Promise(` in the source, as [open, close] offsets.
+ *
+ *  The type argument is optional and is skipped: `new Promise<void>(…)` is what a
+ *  strict TypeScript file writes, and reading only the bare form let the idiomatic
+ *  spelling of a promise-wrapped sleep through the gate entirely. `[^()]*` spans a
+ *  nested generic (`Promise<Record<string, number>>`) and cannot run past the
+ *  constructor's own parenthesis. */
+function promiseSpans(src) {
+    const out = [];
+    for (const m of src.matchAll(/(?<![\w$.])new\s+Promise\s*(?:<[^()]*>\s*)?\(/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = closeOf(src, open);
+        if (close !== -1)
+            out.push([open, close]);
+    }
+    return out;
+}
+/** The `)` matching the `(` at `open`, or -1. `src` has its string contents blanked,
+ *  so a parenthesis inside a literal never counts. */
+function closeOf(src, open) {
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        if (src[i] === "(")
+            depth++;
+        else if (src[i] === ")" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** An argument list split on TOP-LEVEL commas: a comma inside a nested call, an
+ *  object or an array does not separate arguments. */
+function splitArgs(text) {
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of text) {
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch))
+            depth--;
+        if (ch === "," && depth === 0) {
+            out.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    out.push(cur);
+    return out.map((a) => a.trim()).filter((a, i) => i === 0 || a !== "");
+}
+/** The name a declared parameter introduces: `page: Page` → `page`,
+ *  `sleep_time=5` → `sleep_time`, `...rest` → `rest`, `*args` → `args`. */
+function paramNameOf(param) {
+    return (/^[\s*.]*([A-Za-z_$][\w$]*)/.exec(param.replace(/^\.\.\./, ""))?.[1] ?? "");
+}
+function indentOf(line) {
+    return line.length - line.trimStart().length;
+}
+function lineStartOffsets(src) {
+    const out = [0];
+    for (let i = 0; i < src.length; i++)
+        if (src[i] === "\n")
+            out.push(i + 1);
+    return out;
+}
+/** 0-based line index holding `offset`. */
+function lineOf(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/**
+ * What to do INSTEAD, named in the finding itself.
+ *
+ * A finding an agent cannot act on burns verify rounds and is then documented away,
+ * which is the outcome this gate exists to avoid. So the text never says "remove the
+ * sleep": it names the wait that replaces it, and rules out the fix the model reaches
+ * for first — a shorter sleep, which is the same defect at a smaller number.
+ */
+export function fixedSleepReplacement(family, language) {
+    // The presence matchers are READ from the policy rather than spelled here. Spelled,
+    // the text offered `toBeEnabled`, which that policy REFUSES for a shared helper: an
+    // agent following the fix literally would clear `fixed-sleep` in one round and raise
+    // `body-assertion` in the next, against a budget of three. A list the gate keeps of
+    // its own is a list that drifts from the one the gate enforces.
+    if (family !== "browser")
+        return "Wait on the RESOURCE'S OWN state: re-read it and assert the field the change lands in, or use the API's own readiness signal. If one scenario genuinely needs to poll, the polling belongs in THAT test, not in the module every test imports. Never a shorter sleep — that is the same wait at a smaller number";
+    // A Python browser helper told to call `toBeVisible` receives a name Playwright for
+    // Python does not have, which makes a BLOCKING finding non-actionable. The matchers
+    // differ only in spelling, so they come from the policy through playwrightSpelling;
+    // the network wait differs in SHAPE — Python has no `waitForResponse` call, only the
+    // `expect_response` context manager — so snake-casing it produced a call that does
+    // not exist, and it is named per language instead.
+    const presence = HELPER_ASSERTION_POLICIES.browser.permittedMatchers
+        .map((m) => `\`.${playwrightSpelling(m, language)}()\``)
+        .join(" / ");
+    const NEVER = "Never a shorter sleep — that is the same wait at a smaller number";
+    return language === "python"
+        ? `Wait for the CONDITION the sleep stands in for: \`expect(<locator>)\` with ${presence}, \`page.wait_for_url(<pattern>)\`, or \`page.wait_for_load_state()\`; for a network wait, wrap the action that triggers it in \`with page.expect_response(<url>):\` — Playwright Python's response wait is a context manager, not a call. In an \`async def\` helper use the async API throughout: \`await\` each call, and \`async with\` the context manager. ${NEVER}`
+        : `Wait for the CONDITION the sleep stands in for: \`await expect(<locator>)\` with ${presence}, \`page.waitForResponse(<url>)\`, \`page.waitForURL(<pattern>)\`, or \`page.waitForLoadState()\`. ${NEVER}`;
+}

package/build/utils/utils-verify/in-house.d.ts

@@ -0,0 +1,93 @@
+import { type UtilsHelper } from "./parse.js";
+import type { UtilsLanguageSpec } from "./language-spec.js";
+import type { UtilsViolation } from "./verify.js";
+/**
+ * The repository's own helper modules — files the customer wrote — as far as a verify
+ * pass can see them: the modules the delivered spec imports that are tracked at HEAD
+ * and carry no Skyramp header.
+ *
+ * "Tracked at HEAD" is what makes a module in-house here. A module this run created
+ * is not at HEAD; a Skyramp module from an earlier run is, but carries the header and
+ * is the utils verifier's. Nothing here routes on who wrote a file beyond that: a
+ * helper at HEAD keeps its own conventions, whoever wrote it, and the checks below
+ * ask only whether the spec's calls resolve and whether this run's changes to the
+ * module were additive.
+ */
+export interface InHouseModule {
+    /** Canonical absolute path. */
+    file: string;
+    /** Repository-relative, posix — what `git show HEAD:<relPath>` reads. */
+    relPath: string;
+}
+export declare function locateInHouseModules(params: {
+    testFile: string;
+    spec: UtilsLanguageSpec;
+    cwd?: string;
+}): Promise<InHouseModule[]>;
+/** The number of arguments a helper accepts: from the position of its last required
+ *  parameter to its total, a rest parameter opening the top. A parameter with a
+ *  default, an optional `x?`, or a Python `*args`/`**kw` is not required — but a
+ *  required one AFTER a defaulted one still has to be reached positionally, so the
+ *  minimum is its position, not the count of required parameters. `undefined` when
+ *  the signature could not be read. */
+export declare function argumentRange(helper: Pick<UtilsHelper, "params">): {
+    min: number;
+    max: number;
+} | undefined;
+export interface InHouseResolution {
+    /** Imported names the module defines as readable helpers, checked or not. */
+    resolved: string[];
+    /** Imported names the module exports in a form this cannot read — a class, a
+     *  re-export, a constant. Not a violation: the run is told, not blocked. */
+    unverifiable: string[];
+    violations: UtilsViolation[];
+}
+/**
+ * Resolve — verify step 9. The imported name exists in the module's source, and each
+ * call passes an argument count between the definition's required count and its
+ * total. A range, not an exact count: every helper in the pilot's module has
+ * defaulted parameters, and an exact count rejects them all.
+ *
+ * `stem` is the module's basename without extension, which is how the language
+ * spec reads the spec's imports of it.
+ */
+export declare function resolveInHouseCalls(specContent: string, moduleContent: string, stem: string, spec: UtilsLanguageSpec, file?: string): InHouseResolution;
+export interface AdditiveResult {
+    /** Whether HEAD's copy of the module could be read and compared. `false` is
+     *  reported, never read as "nothing changed". */
+    ran: boolean;
+    violations: UtilsViolation[];
+    /** Helpers in the working copy that HEAD does not hold — what this run added. */
+    added: string[];
+    /** HEAD helpers that gained a defaulted parameter and nothing else. */
+    widened: string[];
+    /** An added helper whose action sequence a HEAD helper already performs: the
+     *  duplicate the extension exists to avoid, now inside the customer's file. */
+    duplicates: {
+        added: string;
+        existing: string;
+    }[];
+}
+/**
+ * Additive only — verify step 11. Every change this run made to an in-house module
+ * adds a helper, or adds a parameter that carries a default. Anything else is
+ * refused: a helper removed or renamed, a body changed, a parameter added with no
+ * default, a line outside every helper deleted or edited.
+ *
+ * The widening rule is checked, not trusted: with each added parameter's name
+ * replaced by its default in the new body, and the added parameters dropped from
+ * the signature, the helper must read as it did at HEAD. That is what "the default
+ * is what the helper sends today" means, and it is decidable from the two texts.
+ *
+ * Compared on HEAD versus the working tree, so it holds at the verify call and again
+ * at the submit-time re-derivation. Fails open: a module HEAD does not hold, or a
+ * git that cannot be asked, reports `ran: false` with no violations.
+ */
+export declare function additiveChanges(file: string, root: string, spec: UtilsLanguageSpec): Promise<AdditiveResult>;
+/** Formatting whitespace outside string literals dropped, `'` normalised to `"` (a
+ *  template literal keeps its backticks), Prettier's trailing commas removed — two spellings of one code compare equal, and
+ *  a changed string content still compares unequal. Whitespace that SEPARATES two
+ *  identifier characters is a token boundary, not formatting: it is kept as one
+ *  space, so `await Promise` and `awaitPromise` stay two different texts.
+ *  Whitespace inside a regex literal is not recognised as significant. */
+export declare function squash(text: string): string;