@skyramp/mcp 0.4.1 → 0.4.2-rc.1

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

@@ -15,13 +15,68 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
 /** Python only: the spec imports the shared module in a form that cannot resolve
  *  in the customer's repo. Not marker-eligible — a broken import has no reason to
  *  stay. */
- | "import-form";
+ | "import-form"
+/** A `reuse-verify: allow` marker that no finding of this pass consumes. The
+ *  decline it documents is not in the delivered files: either it never was, or the
+ *  agent went on to fix the fault and left the marker behind, so the file states a
+ *  reason its own code contradicts. Not marker-eligible — a marker that documents
+ *  nothing is deleted, and documenting it would only add a second one. */
+ | "stale-allow"
+/** A shared helper whose request body no parameter of its signature reaches, beside
+ *  a spec that defines its OWN helper for the same route. The pair is the fault: a
+ *  body the helper holds is the right default while one caller exists, and becomes
+ *  wrong the moment a second caller needs another. Marker-eligible — a caller that
+ *  genuinely needs a different REQUEST, not a different body, is a decline worth
+ *  documenting rather than a shape to force. */
+ | "frozen-body"
+/** A shared helper's expected-status parameter — the one its status assertion
+ *  reads — carries a default (or is optional). A call site may then omit the
+ *  status it expects, and the spec states its expectation nowhere a reader can
+ *  see it; a helper named for the happy path defaulting to a rejection reads as
+ *  a bug on sight. Keyed on what the assertion READS, not on the parameter's
+ *  name, which diverges between runs. Marker-eligible. Routed to `advisories`
+ *  for now — see the classification pass in verify.ts. */
+ | "status-default"
+/** The spec asserts the status of a response returned by a helper that already
+ *  asserted it — the same literal stated twice, and the two can disagree. The
+ *  expectation is stated once, as the call's status argument. Marker-eligible. */
+ | "status-restated"
+/** A helper defined at HEAD whose parameter list this run narrowed — a default
+ *  removed, a parameter renamed, removed or reordered, or a required one added.
+ *  Callers this run cannot see depend on the signature at HEAD. Not
+ *  marker-eligible: an incumbent is restored, not documented away. See incumbent.ts. */
+ | "incumbent-signature"
+/** TypeScript only: the delivered module or spec fails the compiler under its most
+ *  permissive settings — an error under EVERY configuration, so the customer's own
+ *  `tsc` is the next thing to report it (the executor transpiles without checking
+ *  types). Not marker-eligible: a file that cannot compile has no reason to stay
+ *  as it is. An error that exists only under the repository's tsconfig is the
+ *  `tsconfig-type-error` ADVISORY instead. */
+ | "type-error"
+/** The spec imports a name from one of the repository's own modules that the
+ *  module does not define. Not marker-eligible: the marker grammar lives in a
+ *  Skyramp module, and nothing of ours is written into the customer's file. */
+ | "in-house-unresolved"
+/** A call to an in-house helper passes an argument count outside the range its
+ *  definition accepts (required count to total count). Not marker-eligible. */
+ | "in-house-arity"
+/** This run changed an in-house module in a way that is not additive: a helper
+ *  removed, renamed or rewritten, a parameter added without a default, a line
+ *  outside every helper deleted. Not marker-eligible — the change is undone. */
+ | "in-house-modified"
+/** The spec imports a sibling module this pass cannot recognise: a file with no
+ *  Skyramp header that is not the repository's own (not at HEAD) — this run's
+ *  module written without its header — or an import that resolves to no file.
+ *  The pass cannot verify or stage what it cannot see, and a PASSED here was a
+ *  gate failing open (fixture 12, run 9). Not marker-eligible: the remedy is the
+ *  header line, or the path, both named in the finding. */
+ | "unresolved-module";
 /** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
  *  meaning "a kind the allow grammar and the gate know about" — an advisory can
  *  never fail a verify and never needs (or accepts) an allow marker. */
-export declare const UTILS_ADVISORY_KINDS: readonly ["untyped-parameter", "duplicate-action"];
+export declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "in-house-duplicate"];
 export type UtilsAdvisoryKind = (typeof UTILS_ADVISORY_KINDS)[number];
-export declare const MARKERABLE_UTILS_KINDS: readonly ["duplicate-helper", "body-assertion", "scenario-name", "assertion-loss"];
+export declare const MARKERABLE_UTILS_KINDS: readonly ["frozen-body", "duplicate-helper", "body-assertion", "scenario-name", "assertion-loss", "status-default", "status-restated"];
 /** A kind the allow grammar accepts. `guard-removed` is a gate kind but never
  *  markerable — a guard is restored, not documented away — so the grammar itself
  *  cannot spell it; the regex below is built from this list. */
@@ -30,9 +85,73 @@ export interface UtilsAllow {
     kind: MarkerableUtilsKind;
     helper: string;
     reason: string;
+    /** 1-based line the marker sits on — where a finding about the marker points. */
+    line: number;
 }
+/**
+ * The documented-decline marker for a utils-file invariant, written in the utils file:
+ *
+ *     # reuse-verify: allow <kind> <helper> — <reason>      (Python)
+ *     // reuse-verify: allow <kind> <helper> — <reason>     (TS/JS)
+ *
+ * ONE grammar, used by both the gate and the report. The POM path's `// kept inline:`
+ * marker had two — the gate's regex and the report parser disagreed on the separator
+ * and on the file extension — and the gap was a run where the gate blocked execution
+ * on declines the report listed correctly (mcp#716, run 30965653402). Here the gate
+ * and the report call this one function.
+ *
+ * The separator is an em/en dash or a hyphen with whitespace on BOTH sides, so a
+ * hyphen inside a helper name cannot be mistaken for it. `(?!<reason)` rejects the
+ * paste-ready line from the failure text when it was pasted unedited: publishing the
+ * placeholder as the stated reason is worse than no marker.
+ */
+export declare const ALLOW_RE: RegExp;
+/** Anything that announces a decline in this grammar, well-formed or not. Exported
+ *  so the delivery-time strip recognises the grammar from its one declaration here
+ *  rather than re-spelling it. */
+export declare const ALLOW_LOOSE_RE: RegExp;
+/** THIS grammar at the start of what a comment says. `reuse-verify: allow` is not a
+ *  phrase a customer writes, so an own-line comment opening with it is gate-addressed
+ *  whatever follows — the delivery strip removes it without being able to READ it.
+ *  `kept inline:` cannot claim that: it opens ordinary English too. */
+export declare const ALLOW_START_RE: RegExp;
+/** A marker's SHAPE, whatever kind it names: the announcement, then a subject, then
+ *  the separator and a reason. Ordinary prose that merely opens with the phrase — `//
+ *  kept inline: this loop is kept inline for performance` — carries no separator and
+ *  is not matched. Used where a line must be recognised as gate-addressed without the
+ *  grammar being able to READ it: an advisory kind is inert by design, so the verify
+ *  pass passes it and the comment would otherwise ship. */
+export declare const MARKER_SHAPE_RE: RegExp;
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: MarkerableUtilsKind, helper: string): string;
+/**
+ * The marker text, when the marker's comment OWNS its line: whitespace, the comment
+ * prefix, then the marker and nothing else.
+ *
+ * One placement, because it is the one both gates instruct and the only one that can
+ * be removed from a delivered file by deleting a line. A marker after code, inside a
+ * block comment or on a JSDoc continuation is reported as malformed instead — the
+ * decline is never dropped in silence, and the failure text gives back the line to
+ * paste in its place.
+ *
+ * A line whose first characters are the comment prefix cannot be a regex literal or a
+ * trailing comment, so this needs no lexer beyond the blanked strings. It cannot tell
+ * whether the prefix OPENS anything, though — inside `/* … *\/` a `//` opens nothing,
+ * the block does — so the caller settles that with `lineCommentOpeners` first. The
+ * parser asked the text while the strip asked the lexer, and a marker in a block
+ * comment was then read as a decline that the strip could not remove: the fault was
+ * authorised and the note shipped.
+ */
+export declare function markerOnOwnLine(raw: string, code: string, prefix: "//" | "#"): string | undefined;
+/**
+ * Line indices whose first non-space characters OPEN a line comment.
+ *
+ * `undefined` where the language has no block comment: every line with the prefix at
+ * its head opens one, and the caller needs no check. Stated ONCE, because the parser
+ * and the delivery strip must not disagree about which lines are comments — when they
+ * did, one authorised a decline the other refused to remove.
+ */
+export declare function lineCommentOpeners(content: string, prefix: "//" | "#"): Set<number> | undefined;
 export declare function parseUtilsAllows(content: string, spec: UtilsLanguageSpec): {
     allows: UtilsAllow[];
     /** Marker lines the loose pattern recognises but the grammar cannot read — a decline

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

@@ -1,20 +1,69 @@
 import { blankStrings } from "./parse.js";
+import { commentSpans } from "../pom-scope/strip.js";
 /** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
  *  meaning "a kind the allow grammar and the gate know about" — an advisory can
  *  never fail a verify and never needs (or accepts) an allow marker. */
 export const UTILS_ADVISORY_KINDS = [
-    "untyped-parameter",
+    "unusable-parameter-type",
+    /** A shared helper waits for a DURATION rather than for a condition: a
+     *  `waitForTimeout`, a `time.sleep`, a promise-wrapped `setTimeout` — or one of
+     *  those as the backoff of a retry loop, where an iteration count hides the real
+     *  cost. Every test that imports the helper inherits the wait, and the call site
+     *  cannot see it. ADVISORY for its first cohort: the case for blocking rested on
+     *  the predicate being narrow enough that a false hit was unlikely, and review
+     *  falsified that three times — a helper NAMED `sleep`, a parameter shadowing the
+     *  name, and a bare call no import binds. The convergence lever is the prompt,
+     *  which states this rule in BROWSER_HELPERS' structuralNoise; the gate measures
+     *  what the prompt leaves. Promote once a cohort has counted the false-hit rate
+     *  instead of estimating it. See fixed-sleep.ts. */
+    "fixed-sleep",
+    /** A shared module this run CREATED under a name other than the one the reuse
+     *  prompt prescribes for its language, while that name was free. Two runs on one
+     *  repository then write two modules for one role and never meet. ADVISORY for its
+     *  first cohort: the convergence lever is the prompt, which states the rule, and
+     *  four of the six findings this rule's review produced were false BLOCKS — so the
+     *  false-hit rate is measured here before it is argued. Promote once a cohort has
+     *  counted it, on the same advisory-first policy as `fixed-sleep`. A module HEAD
+     *  already holds is never judged either way: renaming it breaks callers this run
+     *  cannot see. See module-name.ts. */
+    "module-name",
+    /** A shared API helper that reaches its own request body through TWO parameters at
+     *  once: a whole-body parameter, and an override parameter passed straight through.
+     *  The override can change nothing the body parameter cannot, so the second is a
+     *  choice no rule makes — which is how two runs wrote the same helper with
+     *  different arities. Advisory for the same reason as `module-name` and `fixed-sleep`,
+     *  and it carried three of that review's four false blocks. See bodyReachedTwice. */
+    "duplicate-body-reach",
     /** Two browser helpers perform one action sequence (see actionKeyOf) — the
      *  browser analogue of `duplicate-helper`. Advisory, not blocking: the key is a
      *  heuristic over selector literals, and a false positive on a customer's first
      *  run is the worse outcome. */
     "duplicate-action",
+    /** A compiler error present only under the repository's own tsconfig settings
+     *  (`noImplicitAny`, `strictNullChecks`, …). Whether that tsconfig is the one the
+     *  customer's build runs is their call, so this advises where `type-error` blocks. */
+    "tsconfig-type-error",
+    /** A name the compiler could not find (`process`, `describe`, `Promise`). Its
+     *  declarations come from a package the repository installs or from its `lib`
+     *  setting, neither of which the run can see — the testbot never installs the
+     *  repository's dependencies — so the customer's own `tsc` may accept it. Advised,
+     *  never blocked: a block here made an agent rewrite `process.env` into a
+     *  `globalThis` cast to get past the gate. */
+    "ambient-type-error",
+    /** A helper this run added to one of the repository's own modules performs an
+     *  action sequence a helper already in that module performs — the duplicate the
+     *  extension exists to avoid, now inside the customer's file. Advisory for the
+     *  same reason as `duplicate-action`: the key is read from selector literals. */
+    "in-house-duplicate",
 ];
 export const MARKERABLE_UTILS_KINDS = [
+    "frozen-body",
     "duplicate-helper",
     "body-assertion",
     "scenario-name",
     "assertion-loss",
+    "status-default",
+    "status-restated",
 ];
 /**
  * The documented-decline marker for a utils-file invariant, written in the utils file:
@@ -33,40 +82,115 @@ export const MARKERABLE_UTILS_KINDS = [
  * paste-ready line from the failure text when it was pasted unedited: publishing the
  * placeholder as the stated reason is worse than no marker.
  */
-const ALLOW_RE = new RegExp(`reuse-verify:\\s*allow\\s+(${MARKERABLE_UTILS_KINDS.join("|")})\\s+([A-Za-z_$][\\w$]*)\\s*(?:[—–]+|\\s+-+\\s+)\\s*(?!<reason)(\\S.*?)\\s*$`);
-const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
-/** A marker naming an advisory kind — inert, never malformed (see parseUtilsAllows). */
-const ADVISORY_MARKER_RE = new RegExp(`allow\\s+(?:${UTILS_ADVISORY_KINDS.join("|")})\\b`);
+export const ALLOW_RE = new RegExp(`reuse-verify:\\s*allow\\s+(${MARKERABLE_UTILS_KINDS.join("|")})\\s+([A-Za-z_$][\\w$]*)\\s*(?:[—–]+|\\s+-+\\s+)\\s*(?!<reason)(\\S.*?)\\s*$`);
+/** Anything that announces a decline in this grammar, well-formed or not. Exported
+ *  so the delivery-time strip recognises the grammar from its one declaration here
+ *  rather than re-spelling it. */
+export const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
+/** A marker at the START of what a comment says — either grammar. Anchored, because
+ *  the own-line rule is about what the comment opens with, not what it contains. */
+const MARKER_START_RE = /^(?:reuse-verify:\s*allow\b|kept inline:)/;
+/** THIS grammar at the start of what a comment says. `reuse-verify: allow` is not a
+ *  phrase a customer writes, so an own-line comment opening with it is gate-addressed
+ *  whatever follows — the delivery strip removes it without being able to READ it.
+ *  `kept inline:` cannot claim that: it opens ordinary English too. */
+export const ALLOW_START_RE = /^reuse-verify:\s*allow\b/;
+/** A marker's SHAPE, whatever kind it names: the announcement, then a subject, then
+ *  the separator and a reason. Ordinary prose that merely opens with the phrase — `//
+ *  kept inline: this loop is kept inline for performance` — carries no separator and
+ *  is not matched. Used where a line must be recognised as gate-addressed without the
+ *  grammar being able to READ it: an advisory kind is inert by design, so the verify
+ *  pass passes it and the comment would otherwise ship. */
+export const MARKER_SHAPE_RE = /^(?:reuse-verify:\s*allow\s+\S+\s+\S+|kept inline:\s*\S+)\s*(?:[—–]+|\s+-+\s+)\s*\S/;
+/** Former spellings of an advisory kind. Nothing emits them, but a utils file
+ *  delivered before the kind was renamed — and before the delivery strip of
+ *  2026-09-15 removed such lines — can still carry one, and a second run on that
+ *  repository must not refuse over a line that was inert when it shipped. */
+const LEGACY_ADVISORY_MARKER_KINDS = ["untyped-parameter"];
+/** A marker naming an advisory kind, current or former — inert, never malformed
+ *  (see parseUtilsAllows). */
+const ADVISORY_MARKER_RE = new RegExp(`allow\\s+(?:${[...UTILS_ADVISORY_KINDS, ...LEGACY_ADVISORY_MARKER_KINDS].join("|")})\\b`);
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export function allowMarkerLine(spec, kind, helper) {
     return `${spec.commentPrefix} reuse-verify: allow ${kind} ${helper} — <reason this helper must stay as it is>`;
 }
+/**
+ * The marker text, when the marker's comment OWNS its line: whitespace, the comment
+ * prefix, then the marker and nothing else.
+ *
+ * One placement, because it is the one both gates instruct and the only one that can
+ * be removed from a delivered file by deleting a line. A marker after code, inside a
+ * block comment or on a JSDoc continuation is reported as malformed instead — the
+ * decline is never dropped in silence, and the failure text gives back the line to
+ * paste in its place.
+ *
+ * A line whose first characters are the comment prefix cannot be a regex literal or a
+ * trailing comment, so this needs no lexer beyond the blanked strings. It cannot tell
+ * whether the prefix OPENS anything, though — inside `/* … *\/` a `//` opens nothing,
+ * the block does — so the caller settles that with `lineCommentOpeners` first. The
+ * parser asked the text while the strip asked the lexer, and a marker in a block
+ * comment was then read as a decline that the strip could not remove: the fault was
+ * authorised and the note shipped.
+ */
+export function markerOnOwnLine(raw, code, prefix) {
+    // Judged on the RAW line, not on the blanked copy. A blanked string leaves its
+    // quotes but loses its contents, so `"use strict" // kept inline: …` read as a line
+    // that opens with a comment — and the strip deleted the directive with it.
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith(prefix))
+        return undefined;
+    // The comment must open the line AND the marker must open the comment. Otherwise
+    // `// Customer note; // kept inline: …` is one comment whose line the strip would
+    // delete, prose and all.
+    const body = trimmed.slice(prefix.length).trimStart();
+    return MARKER_START_RE.test(body) ? trimmed : undefined;
+}
+/**
+ * Line indices whose first non-space characters OPEN a line comment.
+ *
+ * `undefined` where the language has no block comment: every line with the prefix at
+ * its head opens one, and the caller needs no check. Stated ONCE, because the parser
+ * and the delivery strip must not disagree about which lines are comments — when they
+ * did, one authorised a decline the other refused to remove.
+ */
+export function lineCommentOpeners(content, prefix) {
+    if (prefix !== "//")
+        return undefined;
+    const starts = new Set(commentSpans(content).map((c) => c.start));
+    const opens = new Set();
+    let offset = 0;
+    content.split("\n").forEach((raw, n) => {
+        const indent = raw.length - raw.trimStart().length;
+        if (starts.has(offset + indent))
+            opens.add(n);
+        offset += raw.length + 1;
+    });
+    return opens;
+}
 export function parseUtilsAllows(content, spec) {
     const allows = [];
     const malformed = [];
-    // String contents are blanked first, so a marker (or a comment token) quoted in
-    // code can neither be read as a decline nor make one look like a comment.
+    // String contents are blanked first, so a marker quoted in code — or inside a Python
+    // docstring — can neither be read as a decline nor look like a comment.
     const rawLines = content.split("\n");
     const codeLines = blankStrings(content, spec).split("\n");
+    const opens = lineCommentOpeners(content, spec.commentPrefix);
     for (let n = 0; n < rawLines.length; n++) {
         const raw = rawLines[n];
         const code = codeLines[n] ?? "";
-        // The marker may sit in a trailing comment, a block comment or a JSDoc line — any
-        // comment form. Match from the marker itself, so the comment syntax around it does
-        // not decide whether a decline is read.
-        const at = code.search(ALLOW_LOOSE_RE);
-        if (at === -1)
+        if (!ALLOW_LOOSE_RE.test(code))
             continue;
-        const before = code.slice(0, at);
-        const inComment = spec.commentPrefix === "#"
-            ? /#/.test(before)
-            : /\/\/|\/\*|^\s*\*/.test(before);
-        if (!inComment)
+        const line = opens && !opens.has(n)
+            ? undefined
+            : markerOnOwnLine(raw, code, spec.commentPrefix);
+        if (line === undefined) {
+            // PLACEMENT is reported for every kind, the advisory kinds included. The
+            // advisory exemption says a kind never blocks; it does not say a marker may sit
+            // anywhere. Exempting placement too left a trailing advisory that the verify
+            // passed and the delivery strip could not remove — so the comment shipped.
+            malformed.push(raw.trim());
             continue;
-        const line = raw
-            .slice(at)
-            .replace(/\s*\*\/\s*$/, "")
-            .trim();
+        }
         const m = ALLOW_RE.exec(line);
         if (!m) {
             // A marker naming an advisory kind is inert, not malformed: advisories never
@@ -81,6 +205,7 @@ export function parseUtilsAllows(content, spec) {
             kind: m[1],
             helper: m[2],
             reason: m[3],
+            line: n + 1,
         });
     }
     return { allows, malformed };

package/build/utils/utils-verify/body-reach.d.ts

@@ -0,0 +1,120 @@
+import type { UtilsLanguageSpec } from "./language-spec.js";
+import { type SiblingFile } from "./call-sites.js";
+/**
+ * A shared helper whose request body no parameter of its signature reaches, beside a
+ * spec that defines its OWN helper for the same route.
+ *
+ * The two halves together are the fault. A body the helper holds is not wrong on its
+ * own — on a first run there is one caller and its body is the right default. It
+ * becomes wrong the moment a second caller needs a different body, and the visible
+ * sign of that is a spec writing its own helper for a route the shared module already
+ * wraps. The advisory that names inline call sites cannot see this pair: it refuses a
+ * site whose payload the helper cannot send, which is exactly the site this looks for.
+ */
+export interface UnreachableBody {
+    /** The shared helper whose body is out of reach. */
+    helper: string;
+    /** Absolute path of the utils file that defines `helper`. */
+    utilsFile: string;
+    method: string;
+    /** The path as the helper writes it. */
+    path: string;
+    /** Absolute path of the spec that defines its own helper for the same route. */
+    rivalFile: string;
+    /** That spec's own helper — the caller the shared helper could not carry. */
+    rivalHelper: string;
+}
+/**
+ * The TOP-LEVEL options of a request call, as `name -> value text`.
+ *
+ * Both SDK spellings: the keyword arguments of `send_request(url=…, body=…)`, and the
+ * properties of the single object `sendRequest({ url: …, body })` takes. A shorthand
+ * property's value is its own name, which is what makes it a shorthand.
+ *
+ * Top-level is the whole point, and a regex could not hold it. Reading `body` or
+ * `data_override` anywhere in the call text made an option's value run to the first
+ * `)` — so an argument written AFTER the override joined its value — and made a name
+ * of the same spelling nested inside ANOTHER option read as the SDK's own, which
+ * blocks a delivery over something that is not there.
+ *
+ * Not `signatureParams`: that reads a parameter list, does not unwrap the object the
+ * TypeScript SDK takes, and expects text whose strings its caller already blanked.
+ * Here the call is raw — a path literal can carry a comma or a brace — so the
+ * structure is walked on a blanked copy and each value is cut from the original.
+ */
+export declare function requestOptions(call: string): Map<string, string>;
+/**
+ * The request's `body` option, as the text of its value, or `undefined` when the call
+ * sends no body.
+ *
+ * `shared-helper-policy` prescribes the object SHORTHAND as the canonical TypeScript
+ * form of body-form 2 — `updateOrder(client, orderId, body = DEFAULT_ORDER_BODY)`
+ * calling `sendRequest({ ..., body })` — so a reader that saw only `body:` judged the
+ * helper the prompt TEACHES as sending no body at all.
+ */
+export declare function bodyArgument(call: string): string | undefined;
+/** The request's override option, as the text of its value. Either spelling. */
+export declare function overrideArgument(call: string): string | undefined;
+/**
+ * Whether a caller can change what this request sends, through the helper's signature.
+ *
+ * The question is whether the body DERIVES from a parameter, not which mechanism
+ * carried it there. Naming the mechanisms would answer the shapes already seen and
+ * mis-judge the next one: the body as the parameter, an override map, and a local
+ * template with the parameters interpolated into it are three ways to reach the same
+ * property, and there is no reason to think they are the last three.
+ *
+ * FAILS OPEN — this feeds a blocking gate, so every answer it cannot establish is
+ * `true`. A request with no body has nothing to reach; a signature it cannot read is
+ * not judged. Only a body it can see, built from no parameter at all, is false.
+ *
+ * `before` is the helper text that precedes the request call. A body passed by name
+ * is resolved there: generated code assigns the template immediately above the call,
+ * so a parameter that reaches the body appears between that assignment and the call.
+ */
+export declare function bodyReachable(call: string, params: string[] | undefined, before?: string): boolean;
+/**
+ * The override parameter of a helper that reaches its own request body TWICE: once
+ * through a body parameter, and again through an override argument passed straight
+ * from the signature. `undefined` when the helper reaches its body through at most
+ * one of them.
+ *
+ * The prompt already states the rule — two body forms are offered and the helper
+ * takes "the FIRST one that reaches everything the callers need" — and nothing
+ * checked it. A body parameter reaches every property of the request body, so an
+ * override beside it can change nothing it cannot; carrying both is the hedge a run
+ * writes when no rule decides, and it is what made demoshop's `create_order` arity 5
+ * in one run and 4 in the other (testplan-run-9).
+ *
+ * The body must BE a parameter — form 2 as the policy states it. A body built at the
+ * call out of a parameter reaches only the properties it names, so an override beside
+ * it carries what the parameter cannot and the two are not one mechanism twice.
+ *
+ * The override must be a BARE PASS-THROUGH — the parameter and nothing else, a
+ * `or {}` / `?? {}` fallback aside. An override that BUILDS a map carries values the
+ * body parameter's default does not, which is the prompt's form 1 working; that is
+ * the shape a unique-suffix helper delivers, and it is not this fault.
+ *
+ * Reads the request call alone, never a body resolved from an assignment above it:
+ * this feeds a blocking gate, and the direct form is the one that cannot be read two
+ * ways.
+ */
+export declare function bodyReachedTwice(call: string, params: string[] | undefined): string | undefined;
+/** A helper reaching its request body through two parameters. */
+export interface DuplicateBodyReach {
+    helper: string;
+    /** Absolute path of the utils file that defines it. */
+    utilsFile: string;
+    /** 1-based line of the definition. */
+    line: number;
+    /** The override parameter the body parameter makes redundant. */
+    override: string;
+}
+/** Every helper in the located modules that reaches its request body twice. Never
+ *  throws; a file it cannot read contributes nothing. */
+export declare function findDuplicateBodyReach(utilsFiles: string[], spec: UtilsLanguageSpec): Promise<DuplicateBodyReach[]>;
+/**
+ * Shared helpers whose body no parameter reaches, each paired with a sibling spec
+ * that defines its own helper for the same route. Never throws; fails open to [].
+ */
+export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnreachableBody[]>;