@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/utils/utils-verify/call-sites.d.ts

@@ -22,14 +22,13 @@ export declare function generatedSiblings(testFile: string, spec: UtilsLanguageS
 }): Promise<SiblingFile[]>;
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export declare const REQUEST_CALL_RE: RegExp;
-export interface InlineCallSite {
+interface InlineSiteBase {
     /** Absolute path of the sibling test. */
     file: string;
-    /** 1-based line of the request call. */
+    /** 1-based line of the request call, or of the first action of the sequence. */
     line: number;
-    method: string;
-    path: string;
-    /** The utils helper that wraps the same method+path. */
+    /** The utils helper that wraps the same method+path, or performs the same
+     *  action sequence. */
     helper: string;
     /** Absolute path of the utils file that defines `helper` — with several modules in
      *  scope, the advisory names this one, not the list. */
@@ -39,6 +38,19 @@ export interface InlineCallSite {
      *  block-by-block. */
     localHelper?: string;
 }
+/** An inline copy of a shared step: one request keyed by route (the API family), or
+ *  a run of actions keyed by action sequence (the browser family). */
+export type InlineCallSite = (InlineSiteBase & {
+    kind: "request";
+    method: string;
+    path: string;
+}) | (InlineSiteBase & {
+    kind: "sequence";
+    /** The action key the sequence and the helper share (see actionKeyOf). */
+    actionKey: string;
+    /** 1-based line of the sequence's last action. */
+    endLine: number;
+});
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a
  * utils helper already wraps — the reuse the prompt asks for and the agent does not
@@ -54,7 +66,9 @@ export interface InlineCallSite {
  * normalised path, nothing else — literals are what the call's arguments are for.
  *
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
- * flow owns, so it informs rather than gates. Never throws.
+ * flow owns, so it informs rather than gates. Never throws. The API family's scan;
+ * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
+ * decides which runs.
  */
 export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
 /** One operation written in two or more sibling generated specs that no shared
@@ -95,6 +109,10 @@ export interface UnextractedSite {
  * different question. Advisory by design — consolidation is a judgement. Never throws.
  */
 export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnextractedDuplicate[]>;
+/** The generated siblings less the utils files themselves (a utils file carries no
+ *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
+ *  the caller's walk decides whether the spec itself is among them. */
+export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
 /** Lines after a call scanned for its schema assertion — the generated shape puts it
  *  immediately after the status-code assertion. */
 export declare const SCHEMA_SCAN_LINES = 12;
@@ -135,7 +153,13 @@ export declare function queryKeys(call: string): Set<string>;
  *  this is a TS/JS-only change. */
 export declare function callShape(call: string): Set<string>;
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
- *  object keys), less the liftable ones — a cheap normalised call shape. */
+ *  object keys), less the liftable ones — a cheap normalised call shape. Read from a
+ *  string-blanked copy: a value carries colons and equals signs of its own — a URL
+ *  scheme (`"https://…"`), a query string or a field expression in a path literal
+ *  (`"/search?q=name:foo"`) — and reading one as a keyword invents an entry on
+ *  whichever side spells the value that way, so two calls carrying the same keywords
+ *  compare as different shapes. */
 export declare function shapeKeys(call: string): Set<string>;
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
 export declare function callText(content: string, open: number): string;
+export {};

package/build/utils/utils-verify/call-sites.js

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { SKYRAMP_UTILS_HEADER } from "../utils.js";
-import { blankCommentsAndStrings, isSingleLiteral, parseUtilsFile, } from "./parse.js";
+import { blankCommentsAndStrings, isSingleLiteral, localHelperAt, localHelpersOf, parseUtilsFile, } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
 import { escapeRegExp } from "../regex.js";
@@ -66,7 +66,9 @@ export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * normalised path, nothing else — literals are what the call's arguments are for.
  *
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
- * flow owns, so it informs rather than gates. Never throws.
+ * flow owns, so it informs rather than gates. Never throws. The API family's scan;
+ * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
+ * decides which runs.
  */
 export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
     const byRoute = await helperRoutes(utilsFiles, spec);
@@ -82,7 +84,7 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             const match = byRoute.get(c.key);
             if (!match)
                 continue;
-            if (!sameShape(callShape(c.call), match.keys))
+            if (!sameShape(inlineShape(c.call), match.keys))
                 continue;
             if (!substitutable(match, {
                 fields: requestFields(content, c.call, c.start),
@@ -91,6 +93,7 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             }))
                 continue;
             out.push({
+                kind: "request",
                 file,
                 line: c.line,
                 method: c.method,
@@ -166,7 +169,7 @@ async function helperRoutes(utilsFiles, spec) {
             byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
                 helper: owner.name,
                 utilsFile,
-                keys: callShape(call),
+                keys: inlineShape(call),
                 fields: requestFields(content, call, start),
                 query: queryKeys(call),
                 schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
@@ -178,7 +181,7 @@ async function helperRoutes(utilsFiles, spec) {
 /** The generated siblings less the utils files themselves (a utils file carries no
  *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
  *  the caller's walk decides whether the spec itself is among them. */
-async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
+export async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
     return (preReadSiblings ??
         (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
@@ -189,7 +192,7 @@ async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, inc
  *  commented-out or quoted request is never a site and a `)` inside a string never
  *  truncates the argument text, which is read from the original. */
 function requestCallsIn(content, spec) {
-    const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
+    const localHelpers = localHelpersOf(content, spec);
     const scan = blankCommentsAndStrings(content, spec);
     const out = [];
     for (const m of scan.matchAll(REQUEST_CALL_RE)) {
@@ -205,7 +208,7 @@ function requestCallsIn(content, spec) {
         if (!method || !pm || !isSingleLiteral(call, pm))
             continue;
         const p = pm[1];
-        const owner = localHelpers.find((h) => line >= h.line && line <= h.endLine);
+        const owner = localHelperAt(localHelpers, line);
         out.push({
             line,
             start,
@@ -356,11 +359,25 @@ export function requestFields(content, call, callAt) {
 }
 const OVERRIDE_OBJECT_RE = /\b(?:data_override|dataOverride)\s*[=:]\s*\{/g;
 const BODY_OBJECT_RE = /\b(?:body|data)\s*[=:]\s*\{/g;
-const QUERY_OBJECT_RE = /\b(?:query_params|queryParams)\s*[=:]\s*\{/g;
+/** The keyword a query object is written under, in either spelling. */
+const QUERY_KEYWORDS = ["query_params", "queryParams"];
+const QUERY_OBJECT_RE = new RegExp(`\\b(?:${QUERY_KEYWORDS.join("|")})\\s*[=:]\\s*\\{`, "g");
+/** An object ENTRY whose key queryKeys cannot enumerate: a spread or an unpack of
+ *  another value (`{ ...params }`, `{**params}`), or a computed key (`{ [k]: v }`).
+ *  Anchored to an entry position, so an array VALUE (`{ fields: ["id"] }`, which the
+ *  generated code writes) and a `**` exponent inside one are not mistaken for it. */
+const DYNAMIC_ENTRY_RE = /[{,]\s*(?:\.\.\.|\*\*|\[)/;
+/** The query argument however it is written — the object form above, or a reference
+ *  (`query_params=params`) whose contents are not at the call. */
+const QUERY_ARGUMENT_RE = new RegExp(`\\b(?:${QUERY_KEYWORDS.join("|")})\\s*[=:]`, "g");
 /** A bare identifier between `{`/`,` and `,`/`}` — TS object shorthand. */
 const SHORTHAND_KEY_RE = /(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g;
-/** One quoted string, any of the three quote kinds, escapes honoured. */
-const STRING_LITERAL_RE = /(["'`])(?:\\.|(?!\1)[^\\])*\1/g;
+/** One quoted string: a Python triple quote, or any of the three single-character
+ *  quote kinds, escapes honoured. The triple forms come FIRST — read as one quote,
+ *  a triple delimiter opens an EMPTY string at its first two characters and leaves
+ *  the payload outside any literal, where every scan that reads a blanked copy sees
+ *  its contents as code. Generated Python passes the request body this way. */
+const STRING_LITERAL_RE = /("""|'''|["'`])(?:\\.|(?!\1)[^\\])*\1/g;
 /** The key names written in one `{…}` object literal: quoted (`"page":`, either
  *  language), unquoted (`page:`, TS) and shorthand (`page,`, TS). The unquoted and
  *  shorthand passes run with string CONTENTS blanked, so `q: "a, b: c"` names one
@@ -408,7 +425,7 @@ function keyedObjects(call, keyRe) {
 /** `text` with the CONTENTS of every string literal replaced by spaces, quotes kept,
  *  length preserved — so offsets found on the copy index into the original. */
 function blankStringContents(text) {
-    return text.replace(STRING_LITERAL_RE, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]);
+    return text.replace(STRING_LITERAL_RE, (lit, quote) => quote + " ".repeat(Math.max(0, lit.length - 2 * quote.length)) + quote);
 }
 /** The call shape both sibling scans compare: shapeKeys of the call with the interior
  *  of every keyed `{…}` value blanked, so the keys INSIDE a body, path-params or
@@ -422,6 +439,51 @@ function blankStringContents(text) {
 export function callShape(call) {
     return shapeKeys(withoutKeyedLiterals(call));
 }
+/**
+ * The shape the INLINE CALL-SITE scan compares: `callShape` less the query argument.
+ *
+ * A query object is a literal the merge rule lifts, exactly as a body is — a site
+ * writing `?status=paid` against a helper that sends no query differs from it by one
+ * value, and the repair is a `status` parameter. Whether the helper can stand in is
+ * the question `substitutable` answers, and it already applies the body rule to the
+ * query keys; while the keyword itself counted as shape, the two keyword sets differed
+ * by one entry, `sameShape` discarded the site, and `substitutable` never saw it.
+ *
+ * Only this scan sets it aside. findUnextractedDuplicates asks whether a helper should
+ * EXIST, where two sites that carry different options are two shapes rather than one
+ * literal to lift, so it keeps `callShape`. And LIFTABLE_KEYS is left alone: it also
+ * feeds retrofit-equivalence, which reads `shapeKeys` as an exact-match gate on an
+ * edit already made, where a dropped query IS a changed request.
+ */
+function inlineShape(call) {
+    const keys = callShape(call);
+    if (!queryIsReadable(call))
+        return keys;
+    for (const k of QUERY_KEYWORDS)
+        keys.delete(k);
+    return keys;
+}
+/** Whether every query argument the call carries is a `{…}` written at the call, so
+ *  queryKeys can read its names. A reference (`query_params=params`) yields an EMPTY
+ *  key set, which is what a call sending NO query yields: setting the keyword aside
+ *  would have substitutable compare nothing against nothing and offer the helper to a
+ *  site that sends no query, when substituting it adds whatever the reference holds.
+ *  So the keyword stays in the shape whenever its value cannot be read, and the site
+ *  is discarded as it was before — the scan only ever drops candidates. */
+function queryIsReadable(call) {
+    // Counted at OPTION level: a request field of the payload may be named
+    // `queryParams`, and reading that as a second, unreadable query argument discarded
+    // a site whose own query argument is a plain object literal. withoutKeyedLiterals
+    // blanks each keyed value's interior while keeping its own braces, which is the
+    // level callShape reads the keywords at.
+    const scan = blankStringContents(withoutKeyedLiterals(call));
+    if ([...scan.matchAll(QUERY_ARGUMENT_RE)].length !==
+        [...scan.matchAll(QUERY_OBJECT_RE)].length)
+        return false;
+    // An object literal is not the same as a readable one. The interiors are blanked in
+    // `scan`, so the entries are read from the original.
+    return !keyedObjects(call, QUERY_OBJECT_RE).some((o) => DYNAMIC_ENTRY_RE.test(blankStringContents(o)));
+}
 /** `call` with the interior of every keyed `{…}` value blanked, offsets kept. */
 function withoutKeyedLiterals(call) {
     // Balanced on the string-blanked copy (see keyedObjects); the copy and the output
@@ -469,10 +531,15 @@ const LIFTABLE_KEYS = new Set([
     "pathParams",
 ]);
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
- *  object keys), less the liftable ones — a cheap normalised call shape. */
+ *  object keys), less the liftable ones — a cheap normalised call shape. Read from a
+ *  string-blanked copy: a value carries colons and equals signs of its own — a URL
+ *  scheme (`"https://…"`), a query string or a field expression in a path literal
+ *  (`"/search?q=name:foo"`) — and reading one as a keyword invents an entry on
+ *  whichever side spells the value that way, so two calls carrying the same keywords
+ *  compare as different shapes. */
 export function shapeKeys(call) {
     const keys = new Set();
-    for (const m of call.matchAll(/\b([A-Za-z_]\w*)\s*[=:](?![=])/g)) {
+    for (const m of blankStringContents(call).matchAll(/\b([A-Za-z_]\w*)\s*[=:](?![=])/g)) {
         if (!LIFTABLE_KEYS.has(m[1]))
             keys.add(m[1]);
     }

package/build/utils/utils-verify/delivered-imports.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a DELIVERED test file imports from the shared utils modules beside it —
+ * read from the file, with no run state and no verify pass behind it.
+ *
+ * This exists because the report's shared-helper record was keyed on the agent
+ * having called `skyramp_reuse_code` with `verify: true` on that file. A spec that
+ * imports and calls a helper from a header-bearing module reused it whether or not
+ * anything verified it, and a record keyed on the tool's own activity describes the
+ * tool rather than the product: every contract row in the 2026-09-18 cohort read
+ * `reuse: null` over a file that imported three helpers and called them.
+ *
+ * Deliberately NOT a second verifier. It runs no gate, produces no verdict, and
+ * cannot refuse a report — `verifyUtils` remains the only thing that judges a
+ * module. The one fact it establishes is which helpers the delivered file takes
+ * from which module, which is exactly the fact the record was missing.
+ *
+ * The same "imported AND defined" rule `verifyUtils` applies: a name the spec
+ * imports that the module does not define is a broken import, not reuse.
+ */
+export interface DeliveredImports {
+    /** Utils files located for the spec (absolute, sorted). Empty means no shared
+     *  module exists beside it or in its imports — which is a finding, not a failure. */
+    utilsFiles: string[];
+    /** Names the spec imports from those files that the files define, sorted and
+     *  deduplicated across files. Empty with a non-empty `utilsFiles` means a module
+     *  exists and this spec takes nothing from it. */
+    importedNames: string[];
+}
+/**
+ * Read `testFile`'s imports of its shared modules, or state why it could not be done.
+ *
+ * Returns a `reason` rather than throwing or answering an empty result, because the
+ * caller writes that reason into the report row: an empty answer and an unreadable
+ * file are different facts, and a row that cannot tell them apart is the `null` this
+ * function exists to replace.
+ */
+export declare function readDeliveredImports(params: {
+    testFile: string;
+    language?: string;
+    cwd?: string;
+}): Promise<DeliveredImports | {
+    reason: string;
+}>;

package/build/utils/utils-verify/delivered-imports.js

@@ -0,0 +1,84 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../logger.js";
+import { locateUtilsFiles } from "./locate.js";
+import { parseUtilsFile } from "./parse.js";
+import { utilsSpecFor, utilsSpecForFile } from "./language-spec.js";
+/**
+ * Read `testFile`'s imports of its shared modules, or state why it could not be done.
+ *
+ * Returns a `reason` rather than throwing or answering an empty result, because the
+ * caller writes that reason into the report row: an empty answer and an unreadable
+ * file are different facts, and a row that cannot tell them apart is the `null` this
+ * function exists to replace.
+ */
+export async function readDeliveredImports(params) {
+    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    if (!spec)
+        return {
+            reason: `no shared-helper support for this file type (${path.extname(params.testFile) || "no extension"})`,
+        };
+    let specContent;
+    try {
+        specContent = await fs.promises.readFile(params.testFile, "utf8");
+    }
+    catch (err) {
+        return {
+            reason: `the delivered file could not be read (${err?.code ?? String(err)})`,
+        };
+    }
+    let utilsFiles;
+    try {
+        utilsFiles = await locateUtilsFiles(params);
+    }
+    catch (err) {
+        // locateUtilsFiles is documented never to throw; if that ever changes, the row
+        // says so rather than claiming the spec imports nothing.
+        logger.warning("Could not locate shared utils files for a delivered test", {
+            testFile: params.testFile,
+            error: String(err),
+        });
+        return {
+            reason: "the shared modules beside this test could not be located",
+        };
+    }
+    const importedNames = new Set();
+    // Built from the modules actually READ, never from the located list. A module that
+    // is named but whose helpers were never counted publishes "this test takes nothing
+    // from it" over an unknown — the same false zero this reader exists to stop.
+    const read = [];
+    for (const file of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch (err) {
+            // A module that vanished between locating and reading is the ordinary race, not
+            // a fault: it leaves the list with the rest, and the others still answer.
+            if (err?.code === "ENOENT")
+                continue;
+            // Anything else means a module exists that cannot be read, so what this spec
+            // takes from it is unknown. A partial answer cannot be represented here, and
+            // a silent one would be read as a measured zero.
+            //
+            // Untested, and untestable from outside: `locateUtilsFiles` screens every
+            // candidate with `hasUtilsHeader`, which opens and reads it, so a module that
+            // cannot be read is never located and this branch is not reached. It stands as
+            // the guard that keeps `read` below honest if that screen ever changes.
+            logger.warning("Could not read a located utils file for the report", {
+                file,
+                error: String(err),
+            });
+            return {
+                reason: `a shared helper module beside this test could not be read (${path.basename(file)}: ${err?.code ?? String(err)})`,
+            };
+        }
+        read.push(file);
+        const defined = new Set(parseUtilsFile(content, spec).map((h) => h.name));
+        const stem = path.basename(file).replace(/\.[^.]+$/, "");
+        for (const n of spec.importedNames(specContent, stem))
+            if (defined.has(n))
+                importedNames.add(n);
+    }
+    return { utilsFiles: read, importedNames: [...importedNames].sort() };
+}

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;