@skyramp/mcp 0.3.6 → 0.3.7

package/build/types/AssertionOutcome.d.ts

@@ -0,0 +1,68 @@
+import type { TestType } from "./TestTypes.js";
+import type { EnhanceType } from "../prompts/enhance-assertions/sharedAssertionRules.js";
+/**
+ * Server-derived assertion-enhancement state. Lives in types/ (not beside
+ * assertion-state.ts) because AnalysisStateManager embeds AssertionRecord in
+ * the run state while assertion-state.ts imports AnalysisStateManager — same
+ * layering as ReuseOutcome.
+ */
+/** A verdict a verify pass can produce and store. */
+export type AssertionVerdict = "passed" | "failed";
+/** What the report can say about verification: the stored verdicts plus
+ *  "never-verified" — the report-time reading of a record that has no verdict
+ *  yet (instructions were handed out or the spec was executed, but no verify
+ *  pass ever ran). Only real verdicts are ever STORED (AssertionRecord);
+ *  "never-verified" exists only on the wire type below. */
+export type AssertionVerification = AssertionVerdict | "never-verified";
+/** One spec's enhancement record in the run state, keyed by the spec's
+ *  CANONICAL ABSOLUTE PATH (see assertion-state.ts `canonicalTestPath`).
+ *
+ *  Two creation paths, which is why the baseline group is optional while the
+ *  identity fields are not:
+ *  - instruction hand-out (recordAssertionBaseline) writes the full record;
+ *  - execution counting (recordAssertionExecution) creates a minimal record
+ *    for a spec that executed without ever being enhanced — identity fields
+ *    plus executionCount, no baseline group.
+ */
+export interface AssertionRecord {
+    /** Canonical path the record is for — kept in the record as a
+     *  defense-in-depth ownership check on reads and writes. */
+    testFilePath: string;
+    testType: TestType;
+    /** Times skyramp_execute_test ran this spec (recorded server-side after the
+     *  gates pass). Proof-of-work substrate: generated-but-never-executed and
+     *  executed-but-never-enhanced both become visible. */
+    executionCount: number;
+    /** Absent on execution-only records (no hand-out happened). */
+    enhanceType?: EnhanceType;
+    /** File hash + metrics at instruction hand-out time — the verify baseline.
+     *  Present as a group iff a hand-out happened. */
+    fileSha256?: string;
+    /** Copy of the generated file at hand-out time, saved under the run artifact
+     *  dir (never the repo, so it cannot leak into the customer commit). Lets the
+     *  agent diff/restore and gives evals a ground-truth pre-enhancement artifact. */
+    baselineFilePath?: string;
+    baselineCount?: number;
+    baselineStrength?: number;
+    baselineFingerprints?: string[];
+    issuedAt?: string;
+    /** Verdict of the last verify pass; absent until one runs. */
+    verification?: AssertionVerdict;
+    /** Reason from an accepted `assertions complete` decline marker. */
+    declinedReason?: string;
+}
+/** Report-facing proof-of-work summary attached to `newTestsCreated` rows —
+ *  the compact wire projection of AssertionRecord (which stays internal: it
+ *  carries fingerprints, hashes, and baseline paths the report must not).
+ *  Server-derived, re-derived from the delivered file at report time, never
+ *  supplied by the LLM. A missing `assertions` field on a row means no record
+ *  exists at all — the enhance tool never ran and the spec never executed. */
+export interface AssertionOutcome {
+    verification: AssertionVerification;
+    assertionsBaseline?: number;
+    assertionsFinal?: number;
+    strengthBaseline?: number;
+    strengthFinal?: number;
+    declinedReason?: string;
+    executionCount: number;
+}

package/build/types/AssertionOutcome.js

@@ -0,0 +1 @@
+export {};

package/build/types/ReuseOutcome.d.ts

@@ -1,3 +1,4 @@
+import type { TestExecutionStatus } from "./TestExecution.js";
 /**
  * The code-reuse observability shape carried in a TestbotReport — the wire contract
  * between this server and the consumers that render it (test-bot.git). It covers
@@ -85,6 +86,14 @@ export declare enum HelperVerificationOutcome {
     /** The test neither wrote nor imports a shared utils file. */
     NoUtilsFile = "no-utils-file"
 }
+/** A pre-existing Skyramp-generated test the reuse pass edited to import from the
+ *  shared utils file. `execution` is the recorded post-edit run; a retrofit without
+ *  one cannot be reported (skyramp_submit_report refuses). */
+export interface RetrofitOutcome {
+    /** BASENAME of the edited test. */
+    file: string;
+    execution?: TestExecutionStatus;
+}
 /** Shared-helper reuse for an API test, re-derived from the delivered files at report
  *  time — nothing here is read back from what the agent or the verify pass recorded.
  *  Absent altogether when no utils file exists for the test (the same omission rule
@@ -105,6 +114,13 @@ export interface HelperReuseOutcome {
      *  per method+path, status-code-only assertions, method+resource names — with
      *  documented declines (`reuse-verify: allow …`) counted as holding. */
     verification?: HelperVerificationOutcome;
+    /** Pre-existing generated tests this spec's reuse pass rewired onto the utils
+     *  file, each with its recorded execution. Omitted when none. */
+    retrofits?: RetrofitOutcome[];
+    /** Whether the delivered test plus the helpers it imports still hold every
+     *  assertion (and page-error guard) present when modularization was handed out.
+     *  Present only when that baseline exists. */
+    assertionsPreserved?: boolean;
 }
 /**
  * What lands in a report's `reuse` field for a generated test. Every member is

package/build/types/TestTypes.d.ts

@@ -246,3 +246,7 @@ export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse?: boolean | undefined;
     modularizeCode?: boolean | undefined;
 }>;
+/** Test types skyramp_enhance_assertions supports — single-sourced so the
+ *  tool's schema enum and generation-time baseline seeding cannot drift
+ *  (contract additionally requires provider mode at the seeding site). */
+export declare const ASSERTION_ENHANCEABLE_TEST_TYPES: readonly [TestType.INTEGRATION, TestType.CONTRACT, TestType.UI];

package/build/types/TestTypes.js

@@ -274,3 +274,11 @@ export const codeRefactoringSchema = z.object({
         .default(false)
         .describe("Whether to modularize the code"),
 });
+/** Test types skyramp_enhance_assertions supports — single-sourced so the
+ *  tool's schema enum and generation-time baseline seeding cannot drift
+ *  (contract additionally requires provider mode at the seeding site). */
+export const ASSERTION_ENHANCEABLE_TEST_TYPES = [
+    TestType.INTEGRATION,
+    TestType.CONTRACT,
+    TestType.UI,
+];

package/build/types/TestbotReport.d.ts

@@ -2,6 +2,7 @@ import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
 import type { HttpMethod, TestType } from "./TestTypes.js";
 import type { ReuseOutcome } from "./ReuseOutcome.js";
+import type { AssertionOutcome } from "./AssertionOutcome.js";
 /** Classification of an issuesFound entry. Bug is a product/code defect; the
  *  other values are tooling noise that the Testbot report renders in its
  *  Configuration Errors section instead of Issues Found. */
@@ -39,6 +40,14 @@ export interface TestbotReport {
          *  rest of this file mirrors Zod schemas by hand, which is why only this field
          *  is imported). Absent in reports from MCP versions predating it. */
         reuse?: ReuseOutcome;
+        /** Assertion-enhancement proof-of-work summary, present when
+         *  skyramp_enhance_assertions or skyramp_execute_test recorded state for
+         *  this test. Server-derived like `reuse` (imported for the same reason);
+         *  cross-checks the LLM-authored narrative against server-observed facts:
+         *  verification status, before/after assertion metrics, decline reason,
+         *  and how many times the test actually executed. Absent in reports from
+         *  MCP versions predating it. */
+        assertions?: AssertionOutcome;
     }[];
     /** Omitted when no existing tests were found (agent omits the field). */
     testMaintenance?: {
@@ -51,6 +60,10 @@ export interface TestbotReport {
         beforeDetails: string;
         afterStatus: TestExecutionStatus;
         afterDetails: string;
+        /** See newTestsCreated[].assertions — maintenance rows are matched by
+         *  exact canonical path, so this carries the maintenance honesty labels
+         *  (nothing-to-verify vs verified) into the report. */
+        assertions?: AssertionOutcome;
     }[];
     testResults: {
         testType: TestType;

package/build/types/index.d.ts

@@ -4,5 +4,5 @@ export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
 export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
-export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/utils/AnalysisStateManager.d.ts

@@ -1,4 +1,5 @@
 import type { ReuseRecord } from "../tools/code-refactor/reuse-outcome.js";
+import type { AssertionRecord } from "../types/AssertionOutcome.js";
 import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
@@ -181,6 +182,16 @@ export interface PlanBudgetContext {
     /** Whether the PR diff changes any test file; see BudgetContext. */
     diffChangesTestFiles?: boolean;
 }
+/** A pre-existing Skyramp-generated test the reuse pass edited to import from a
+ *  shared utils file (STEP 5c / the sibling-inline advisory). Keyed by ABSOLUTE
+ *  PATH. Recorded in-process where staging finds the edit; skyramp_submit_report
+ *  refuses a report that leaves one undisclosed or unexecuted. */
+export interface ReuseRetrofit {
+    /** BASENAME(s) of the utils file(s) it now imports from. */
+    utilsFile: string;
+    /** Absolute path of the generated test whose reuse pass caused the edit. */
+    testFile: string;
+}
 export interface ReuseHandOff {
     testType: string;
     language: string;
@@ -231,19 +242,14 @@ export interface UnifiedAnalysisState {
      *  which computes every value in-process; skyramp_submit_report merges it into
      *  the report's `reuse` field. Never supplied by the LLM. */
     reuseOutcomes?: Record<string, ReuseRecord>;
-    /** SKYR-4262. Assertion-enhancement obligations per spec, keyed by test-file
-     *  BASENAME (same key as `reuseOutcomes`). Written in-process by
-     *  skyramp_enhance_assertions when it hands out instructions; checked by
-     *  skyramp_execute_test, which blocks when the spec is byte-identical to its
-     *  state at handout time (the agent acknowledged the instructions but never
-     *  acted on them). Never supplied by the LLM. */
-    enhanceOutcomes?: Record<string, import("../tools/code-refactor/enhance-state.js").EnhanceRecord>;
     /** Generation hand-offs that owe a modularize→reuse pass, keyed by the ABSOLUTE
      *  PATH of each file the generation call wrote (found by snapshotting `outputDir`
      *  before and after codegen — the agent, not the tool, chooses the file name).
      *  Written by the generation service at the exact site that emits the hand-off, so
      *  the debt has the same server-derived trust as `reuseOutcomes`. */
     reuseHandOffs?: Record<string, ReuseHandOff>;
+    /** See {@link ReuseRetrofit}. Never supplied by the LLM. */
+    reuseRetrofits?: Record<string, ReuseRetrofit>;
     /**
      * SKYR-4156. Recorded video per executed browser test, keyed by test-file
      * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path
@@ -258,6 +264,13 @@ export interface UnifiedAnalysisState {
      * the earlier attempt's now-stale directory.
      */
     executionVideos?: Record<string, VideoRecord>;
+    /** Assertion-enhancement baseline + verify verdict per test file, keyed by
+     *  CANONICAL ABSOLUTE PATH (path.resolve — unlike `reuseOutcomes`, nothing
+     *  here matches report rows, and path keying removes basename collisions and
+     *  alias bypasses). Written in-process by skyramp_enhance_assertions;
+     *  skyramp_execute_test verifies against it server-side before executing.
+     *  Never supplied by the LLM. */
+    assertionOutcomes?: Record<string, AssertionRecord>;
 }
 /**
  * State file metadata

package/build/utils/assertion-verify/api-shared-lints.d.ts

@@ -0,0 +1,5 @@
+import type { AssertionLanguage } from "./metrics.js";
+import { type LintFinding, type LintOptions } from "./lint-types.js";
+/** Checks shared by integration and provider-contract tests. Java is never
+ *  linted (count+hash gates only). */
+export declare function lintApiShared(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/api-shared-lints.js

@@ -0,0 +1,315 @@
+import { escapeRegExp } from "../regex.js";
+import { strippedSources } from "./strip-dispatch.js";
+import { balancedCloseIndex, identifierRe, inScope, interpolationRe, lineOfOffset, } from "./lint-types.js";
+/**
+ * Deterministic checks shared by integration and provider-contract tests — the
+ * machine-checkable slice of the D5 rubric's echo_computed and array_depth
+ * dims. Exact VALUE correctness (does the assertion match the recorded/sent
+ * value?) needs trace ground truth and stays with the LLM judge.
+ */
+const RESPONSE_BINDING_RES = {
+    jsts: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+[\w$.]*sendRequest\s*\(/g,
+    python: /^[ \t]*([A-Za-z_]\w*)\s*=\s*[\w.]*send_request\s*\(/gm,
+};
+const STATUS_USE_RE = /^\s*\.\s*(?:statusCode|status_code|status)\b/;
+/** All send_request/sendRequest bindings in the stripped source. */
+function responseBindings(stripped, language) {
+    const bindings = [];
+    const re = language === "python"
+        ? RESPONSE_BINDING_RES.python
+        : RESPONSE_BINDING_RES.jsts;
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const openIdx = stripped.indexOf("(", m.index + m[0].length - 1);
+        const declClose = balancedCloseIndex(stripped, openIdx);
+        if (declClose === -1)
+            continue;
+        bindings.push({ varName: m[1], declIndex: m.index, declClose });
+    }
+    return bindings;
+}
+/** Statuses asserted on a var's status lines; used for the 204/202 exemption. */
+function assertedStatuses(commentless, statusUseOffsets) {
+    const statuses = [];
+    for (const offset of statusUseOffsets) {
+        const lineEnd = commentless.indexOf("\n", offset);
+        const line = commentless.slice(offset, lineEnd === -1 ? undefined : lineEnd);
+        const code = /\b([1-5]\d{2})\b/.exec(line);
+        if (code)
+            statuses.push(Number(code[1]));
+    }
+    return statuses;
+}
+/** True when the binding at `idx` is declared inside a loop body — codegen's
+ *  polling loops (`for (…) { const r = await sendRequest(…); if (r.status …) break; }`)
+ *  bind a response that legitimately exists only to poll, and the remediation
+ *  ("assert after the status assertion") points at a place that is out of
+ *  scope after the loop. Poll bindings are exempt. */
+function isInsideLoop(stripped, idx, language) {
+    if (language === "python") {
+        const upto = stripped.slice(0, idx);
+        const lineStart = upto.lastIndexOf("\n") + 1;
+        let threshold = (/^[ \t]*/.exec(stripped.slice(lineStart)) ?? [""])[0]
+            .length;
+        const lines = upto.slice(0, lineStart).split("\n");
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (line.trim() === "")
+                continue;
+            const indent = (/^[ \t]*/.exec(line) ?? [""])[0].length;
+            if (indent >= threshold)
+                continue;
+            if (/^[ \t]*(?:for|while)\b/.test(line))
+                return true;
+            threshold = indent;
+            if (threshold === 0)
+                return false;
+        }
+        return false;
+    }
+    const blockIsLoop = [];
+    for (let i = 0; i < idx; i++) {
+        const c = stripped[i];
+        if (c === "{") {
+            const head = stripped.slice(Math.max(0, i - 160), i);
+            blockIsLoop.push(/\b(?:for|while)\s*\([^{]*\)\s*$/.test(head) || /\bdo\s*$/.test(head));
+        }
+        else if (c === "}") {
+            blockIsLoop.pop();
+        }
+    }
+    return blockIsLoop.some(Boolean);
+}
+// The SDK's own status helper: `checkStatusCode(r, "200")` passes the response
+// as a call argument, but it is a STATUS use, not a body read.
+const STATUS_HELPER_BEFORE_RE = /check_?status_?code\s*\(\s*$/i;
+/** Response bindings whose every use is a status read (or that are never used).
+ *  Any other read — getValue/get_response_value/checkSchema/.json()/passed as a
+ *  call argument, including inside a template-literal or f-string interpolation
+ *  — clears it. Exempt: DELETE calls, sole 204/202 statuses, poll bindings
+ *  inside loops. Severity follows the rubric: unconditional (`hard`) for
+ *  4xx/5xx — an error body must always be asserted — and advisory (`warn`)
+ *  when only 2xx statuses are asserted, because a 200 can legitimately carry
+ *  no body (/logout, /cancel) and that is not deterministically knowable. */
+function lintStatusOnlyResponses(stripped, commentless, language, bindings) {
+    const findings = [];
+    for (const { varName, declIndex, declClose } of bindings) {
+        // DELETE exemption: the request itself is a DELETE (args read from the
+        // comment-stripped raw so the method string literal is visible; the
+        // enum spelling `method: Method.DELETE` counts too).
+        const openIdx = stripped.indexOf("(", declIndex);
+        const declArgs = commentless.slice(openIdx, declClose + 1);
+        if (/['"]delete['"]|method\s*[:=]\s*[\w.]*\bDELETE\b/i.test(declArgs)) {
+            continue;
+        }
+        if (isInsideLoop(stripped, declIndex, language))
+            continue;
+        const after = stripped.slice(declClose + 1);
+        const refRe = identifierRe(varName, "g");
+        let ref;
+        let statusUses = 0;
+        let otherUses = 0;
+        const statusUseOffsets = [];
+        while ((ref = refRe.exec(after)) !== null) {
+            // Bounded window: STATUS_USE_RE is anchored and needs ~20 chars, so
+            // slicing to EOF per reference was O(n × references).
+            const tail = after.slice(ref.index + varName.length, ref.index + varName.length + 40);
+            const before = after.slice(Math.max(0, ref.index - 24), ref.index);
+            if (STATUS_USE_RE.test(tail) || STATUS_HELPER_BEFORE_RE.test(before)) {
+                statusUses++;
+                statusUseOffsets.push(declClose + 1 + ref.index);
+            }
+            else {
+                otherUses++;
+            }
+        }
+        // Template-literal `${...}` and python f-string `{...}` interpolations are
+        // blanked wholesale by the strippers, so a use like
+        // `sendRequest(\`/orders/\${getValue(resp, "id")}\`)` is invisible above.
+        // Count interpolation reads from the comment-stripped source.
+        if (otherUses === 0 &&
+            interpolationRe(varName, language).test(commentless.slice(declClose + 1))) {
+            otherUses++;
+        }
+        if (otherUses > 0)
+            continue;
+        const statuses = assertedStatuses(commentless, statusUseOffsets);
+        if (statuses.length > 0 && statuses.every((s) => s === 204 || s === 202)) {
+            continue;
+        }
+        // Never-used responses and asserted error statuses are unconditional
+        // violations; a 2xx-only status check is advisory (empty-body 200s exist).
+        const severity = statusUses === 0 || statuses.some((s) => s >= 400) ? "hard" : "warn";
+        findings.push({
+            rule: "status-only-response",
+            severity,
+            line: lineOfOffset(stripped, declIndex),
+            message: statusUses > 0
+                ? severity === "hard"
+                    ? `Error response \`${varName}\` is only checked for its status code — the error body (code/message/detail) must be asserted.`
+                    : `Response \`${varName}\` is only checked for its status code — if this endpoint returns a body, assert its fields (skip only for genuinely empty-body responses).`
+                : `Response \`${varName}\` is captured but never asserted.`,
+            remediation: language === "python"
+                ? `Assert body fields via \`skyramp.get_response_value(${varName}, "json.path")\` after the status assertion.`
+                : `Assert body fields via \`getValue(${varName}, "json.path")\` after the status assertion.`,
+        });
+    }
+    return findings;
+}
+/** Dict-subscript access on a response binding (`r["field"]`) — the rules
+ *  mandate the SDK helper for every body read; subscript access bypasses the
+ *  helper's null-safe path handling. Near-zero false positives: response
+ *  objects are not lists/dicts, so a legitimate subscript on one is not a real
+ *  pattern. */
+function lintSdkHelperBypass(stripped, bindings, language) {
+    const findings = [];
+    for (const { varName, declClose } of bindings) {
+        const after = stripped.slice(declClose + 1);
+        const subscriptRe = new RegExp(`(?<![\\w$])${escapeRegExp(varName)}\\s*\\[`, "g");
+        const m = subscriptRe.exec(after);
+        if (m) {
+            findings.push({
+                rule: "sdk-helper-bypass",
+                severity: "hard",
+                line: lineOfOffset(stripped, declClose + 1 + m.index),
+                message: `Response \`${varName}\` is read via dict/subscript access instead of the SDK helper.`,
+                remediation: language === "python"
+                    ? `Use \`skyramp.get_response_value(${varName}, "json.path")\` — never \`${varName}[...]\`.`
+                    : `Use \`getValue(${varName}, "json.path")\` — never \`${varName}[...]\`.`,
+            });
+        }
+    }
+    return findings;
+}
+// Exactly the permissive forms the rules name — anything cleverer is not chased.
+const PERMISSIVE_STATUS_RES = [
+    /toBeGreaterThanOrEqual\s*\(\s*200\s*\)/,
+    /toMatch\s*\(\s*\/\^?2/,
+    /\b200\s*<=\s*[\w.]*status(?:_code|Code)?\b/,
+    /str\s*\(\s*[\w.]*status_code\s*\)\s*\.\s*startswith\s*\(\s*['"]2/,
+    // Only WILDCARD forms ('20x', '2xx') are permissive — the SDK documents
+    // '"200" matches exactly 200', so a fully numeric literal is an exact match.
+    /check_?status_?code\s*\([^)]*['"][0-9x]*x[0-9x]*['"]/i,
+];
+const STATUS_MENTION_RE = /statusCode|status_code|\.status\b|check_?status/i;
+function lintPermissiveStatusMatchers(commentless, opts) {
+    const findings = [];
+    const lines = commentless.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!STATUS_MENTION_RE.test(line))
+            continue;
+        if (PERMISSIVE_STATUS_RES.some((re) => re.test(line)) &&
+            inScope(i + 1, opts)) {
+            findings.push({
+                rule: "permissive-status-matcher",
+                severity: "hard",
+                line: i + 1,
+                message: "Permissive status matcher — the exact recorded status is knowable.",
+                remediation: "Assert the exact status code from the recorded trace or expected_response_body (e.g. `.toBe(201)` / `== 201`).",
+            });
+        }
+    }
+    return findings;
+}
+const SHAPE_ONLY_RE = /Array\.isArray\s*\(|typeof\s+[\w.[\]]+\s*===|instanceof\s+Array|Object\.keys\s*\([^)]*\)\s*\.length|isinstance\s*\(/;
+function lintShapeOnlyChecks(commentless) {
+    const findings = [];
+    const lines = commentless.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (SHAPE_ONLY_RE.test(lines[i])) {
+            findings.push({
+                rule: "shape-only-check",
+                severity: "warn",
+                line: i + 1,
+                message: "Shape/type-only check — fine as a companion, not as the sole validation.",
+                remediation: "Ensure the response's actual values are also asserted exactly (fields, lengths, per-item values).",
+            });
+        }
+    }
+    return findings;
+}
+// JSON paths read through the SDK helpers, e.g. getValue(r, "items.0.id").
+const SDK_PATH_RE = /(?:getValue|getResponseValue|get_response_value)\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]/g;
+// Length reads on an SDK-helper result: `getValue(r, "items").length` or
+// `len(skyramp.get_response_value(r, "items"))`.
+const JS_LENGTH_RE = /(?:getValue|getResponseValue)\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]\s*\)\s*\.\s*length/g;
+const PY_LENGTH_RE = /len\s*\(\s*[\w.]*get_response_value\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]/g;
+/** Array-depth advisories (warn-only — array emptiness/size is trace-dependent):
+ *  - length asserted for a path but no per-item field asserted under it
+ *  - per-item assertions exist but the next index is never asserted absent */
+function lintArrayDepth(commentless) {
+    const findings = [];
+    const paths = [];
+    SDK_PATH_RE.lastIndex = 0;
+    let m;
+    while ((m = SDK_PATH_RE.exec(commentless)) !== null)
+        paths.push(m[1]);
+    const lengthPaths = new Set();
+    for (const re of [JS_LENGTH_RE, PY_LENGTH_RE]) {
+        re.lastIndex = 0;
+        while ((m = re.exec(commentless)) !== null)
+            lengthPaths.add(m[1]);
+    }
+    // Length-only: a counted array with no per-item content assertion under it.
+    for (const arrayPath of lengthPaths) {
+        const hasItemRead = paths.some((p) => p.startsWith(`${arrayPath}.`));
+        if (!hasItemRead) {
+            findings.push({
+                rule: "array-length-only",
+                severity: "warn",
+                message: `Array \`${arrayPath}\` is only checked for its length — no per-item field is asserted.`,
+                remediation: `Assert key fields on each recorded item (e.g. "${arrayPath}.0.<field>") in addition to the length.`,
+            });
+        }
+    }
+    // Indexed item-content reads (`items.N.field`) without a next-index-absent
+    // assertion (a bare `items.N+1` read). Scalar arrays (bare-index-only reads)
+    // are skipped — a bare index there is a content assertion, not an absence
+    // check, and the two are indistinguishable without parsing matchers.
+    const contentMaxByPath = new Map();
+    const barePaths = new Set();
+    for (const p of paths) {
+        const withField = /^(.+)\.(\d+)\./.exec(p);
+        if (withField) {
+            const base = withField[1];
+            const n = Number(withField[2]);
+            contentMaxByPath.set(base, Math.max(contentMaxByPath.get(base) ?? -1, n));
+            continue;
+        }
+        if (/^.+\.\d+$/.test(p))
+            barePaths.add(p);
+    }
+    for (const [base, maxIdx] of contentMaxByPath) {
+        const nextPath = `${base}.${maxIdx + 1}`;
+        if (!barePaths.has(nextPath)) {
+            findings.push({
+                rule: "array-missing-next-index-check",
+                severity: "warn",
+                message: `Items of \`${base}\` are asserted up to index ${maxIdx}, but index ${maxIdx + 1} is never asserted absent.`,
+                remediation: `Add an absence assertion for the index after the last expected item (e.g. \`getValue(response, "${nextPath}")\` is undefined / None).`,
+            });
+        }
+    }
+    return findings;
+}
+/** Checks shared by integration and provider-contract tests. Java is never
+ *  linted (count+hash gates only). */
+export function lintApiShared(raw, language, opts) {
+    if (language === "java")
+        return [];
+    const maintenance = opts?.scopeLines !== undefined;
+    const { commentless, stripped } = strippedSources(raw, language);
+    const findings = [];
+    if (!maintenance) {
+        // Bindings discovered once, shared by both binding-scoped lints.
+        const bindings = responseBindings(stripped, language);
+        findings.push(...lintStatusOnlyResponses(stripped, commentless, language, bindings));
+        findings.push(...lintSdkHelperBypass(stripped, bindings, language));
+        findings.push(...lintShapeOnlyChecks(commentless));
+        findings.push(...lintArrayDepth(commentless));
+    }
+    findings.push(...lintPermissiveStatusMatchers(commentless, opts));
+    return findings;
+}

package/build/utils/assertion-verify/contract-lints.d.ts

@@ -0,0 +1,3 @@
+import type { AssertionLanguage } from "./metrics.js";
+import { type LintFinding, type LintOptions } from "./lint-types.js";
+export declare function lintContractTest(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/contract-lints.js

@@ -0,0 +1,87 @@
+import { strippedSources } from "./strip-dispatch.js";
+import { balancedCloseIndex, identifierRe, lineOfOffset, } from "./lint-types.js";
+import { lintApiShared } from "./api-shared-lints.js";
+/**
+ * Provider-contract lints: the shared API checks plus the machine-checkable
+ * slice of the D5 `value_sources` dim — contract assertions must use inline
+ * request values, never data provisioned in beforeAll/beforeEach.
+ */
+const SETUP_BLOCK_RE = /\b(?:beforeAll|beforeEach)\s*\(/g;
+const DECL_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g;
+/** Identifiers assigned inside beforeAll/beforeEach blocks and the block
+ *  ranges themselves (JS/TS only — python contract tests use pytest fixtures,
+ *  out of scope here). The ranges matter: codegen's own provisioning status
+ *  checks live INSIDE the setup blocks and reference these names legitimately
+ *  — only TEST-BODY assertions using setup data violate the rubric (measured:
+ *  7 of 8 pristine provider-contract goldens false-warned without this). */
+function setupDeclarations(stripped) {
+    const names = new Set();
+    const ranges = [];
+    SETUP_BLOCK_RE.lastIndex = 0;
+    let m;
+    while ((m = SETUP_BLOCK_RE.exec(stripped)) !== null) {
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        if (close === -1)
+            continue;
+        ranges.push([m.index, close]);
+        const block = stripped.slice(m.index, close + 1);
+        DECL_RE.lastIndex = 0;
+        let decl;
+        while ((decl = DECL_RE.exec(block)) !== null)
+            names.add(decl[1]);
+    }
+    return { names, ranges };
+}
+/** An assertion references a value provisioned in beforeAll/beforeEach.
+ *  Warn-only: block-scoped `const` inside beforeAll is not reachable from a
+ *  test body in real code, so hits are usually closure vars — a strong smell,
+ *  but shared infra handles (clients, tokens) are legitimate closure vars too. */
+function lintSetupDataInAssertions(stripped) {
+    const { names, ranges } = setupDeclarations(stripped);
+    if (names.size === 0)
+        return [];
+    // Compile once per name, not per (site × name).
+    const nameRes = new Map([...names].map((name) => [name, identifierRe(name)]));
+    const findings = [];
+    const expectRe = /\bexpect(?:\s*\.\s*soft)?\s*\(/g;
+    let m;
+    while ((m = expectRe.exec(stripped)) !== null) {
+        // Setup-internal assertions (provisioning status checks) are codegen's
+        // own sanctioned shape — only test-body references are the violation.
+        const at = m.index;
+        if (ranges.some(([start, end]) => at >= start && at <= end))
+            continue;
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        if (close === -1)
+            continue;
+        // The whole statement line, so matcher arguments count too.
+        const lineEnd = stripped.indexOf("\n", close);
+        const stmt = stripped.slice(m.index, lineEnd === -1 ? undefined : lineEnd);
+        for (const [name, re] of nameRes) {
+            if (re.test(stmt)) {
+                findings.push({
+                    rule: "setup-data-in-assertion",
+                    severity: "warn",
+                    line: lineOfOffset(stripped, m.index),
+                    message: `Assertion references \`${name}\`, which is provisioned in beforeAll/beforeEach.`,
+                    remediation: "Contract assertions must use values from the inline request body, path, query, or expected_response_body — not setup-provisioned data.",
+                });
+                break;
+            }
+        }
+    }
+    return findings;
+}
+export function lintContractTest(raw, language, opts) {
+    // Java is count+hash gated only (a documented limit of the verifier): the
+    // lint regexes and strength weights are written for the python/ts/js SDK
+    // helper idioms, and applying them to JUnit source would produce false
+    // findings, not protection. Same guard as helper-imports.ts.
+    if (language === "java")
+        return [];
+    const findings = lintApiShared(raw, language, opts);
+    if (opts?.scopeLines === undefined && language !== "python") {
+        findings.push(...lintSetupDataInAssertions(strippedSources(raw, language).stripped));
+    }
+    return findings;
+}

package/build/utils/assertion-verify/format.d.ts

@@ -0,0 +1,5 @@
+import type { AssertionVerifyResult } from "./verify.js";
+/** Renders the verify result as the text returned to the agent — PASSED/FAILED
+ *  with one actionable remediation per violation, in the style of the reuse
+ *  verify report (verify-gates.ts). */
+export declare function formatAssertionVerifyReport(r: AssertionVerifyResult, testFile: string): string;