@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/types/RepositoryAnalysis.d.ts

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { ScenarioCategory } from "./TestRecommendation.js";
-import { TestType } from "./TestTypes.js";
 import type { ProjectType, DeploymentPattern } from "../utils/projectMetadata.js";
 /**
  * Repository Analysis Types
@@ -98,44 +96,6 @@ export declare enum ScenarioSource {
     Documentation = "documentation",
     AgentEnriched = "agent-enriched"
 }
-export interface PlanScenario {
-    scenarioName: string;
-    description: string;
-    category: ScenarioCategory;
-    priority: "high" | "medium" | "low";
-    steps: ScenarioStep[];
-    chainingKeys: string[];
-    requiresAuth: boolean;
-    estimatedComplexity: "simple" | "moderate" | "complex";
-    source?: ScenarioSource;
-    /** Only integration, contract, e2e, and ui are valid for drafted scenarios. */
-    testType?: TestType;
-    /** Internal marker for destructive sibling auth-boundary scenarios. */
-    isAttackSurfaceSecurityBoundary?: boolean;
-    /**
-     * The specific bug or formula this test is designed to catch.
-     * Written during scenario drafting when source code is read.
-     * Examples:
-     *   "discount formula: total_amount = subtotal * (1 - discount_value / 100)"
-     *   "items not recalculated after PATCH — total_amount stays at old value"
-     *   "missing 404 guard on non-existent order_id"
-     * Used by the testbot to compute exact assertion values instead of null-checks.
-     */
-    bugCatchingTarget?: string;
-    /**
-     * The endpoints this test is about, resolved one time by
-     * `resolveSubjectEndpoints` where the PR diff is available. Every dedup
-     * reader keys off this list rather than deriving a subject again from
-     * `steps[]` — SKYR-4214: two stages derived different subjects for one
-     * candidate, so whether a candidate deduped depended on whether the model
-     * happened to append a cleanup step.
-     *
-     * Absent on a scenario from an older state file; readers then fall back to
-     * the last-mutating-step rule. An EMPTY list means "no information" and must
-     * never be read as "covered".
-     */
-    subjectEndpoints?: SubjectEndpoint[];
-}
 export interface BranchDiffContext {
     currentBranch: string;
     baseBranch: string;
@@ -967,15 +927,15 @@ export declare const chainingRefSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sourceStep: number;
     sourceField: string;
-    sourceLocation: "body" | "header" | "cookie";
+    sourceLocation: "cookie" | "body" | "header";
     targetParam: string;
-    targetLocation: "path" | "body" | "header" | "cookie" | "query";
+    targetLocation: "path" | "cookie" | "body" | "header" | "query";
 }, {
     sourceStep: number;
     sourceField: string;
-    sourceLocation: "body" | "header" | "cookie";
+    sourceLocation: "cookie" | "body" | "header";
     targetParam: string;
-    targetLocation: "path" | "body" | "header" | "cookie" | "query";
+    targetLocation: "path" | "cookie" | "body" | "header" | "query";
 }>;
 export declare const scenarioStepSchema: z.ZodObject<{
     order: z.ZodNumber;
@@ -997,15 +957,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }>, z.ZodArray<z.ZodObject<{
         sourceStep: z.ZodNumber;
         sourceField: z.ZodString;
@@ -1015,15 +975,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }>, "many">]>>;
     bodyMustInclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
@@ -1040,15 +1000,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     chainsFrom?: {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     } | {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }[] | undefined;
     bodyMustInclude?: string[] | undefined;
 }, {
@@ -1065,15 +1025,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     chainsFrom?: {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     } | {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }[] | undefined;
     bodyMustInclude?: string[] | undefined;
 }>;
@@ -1224,14 +1184,14 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }, {
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }>, "many">;
         playwrightRecordings: z.ZodArray<z.ZodObject<{
             path: z.ZodString;
@@ -1265,8 +1225,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1284,8 +1244,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1429,6 +1389,9 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         scanDepth: "quick" | "full";
         analysisScope?: AnalysisScope | undefined;
     };
+    workspace: {
+        baseUrl: string;
+    };
     projectClassification: {
         projectType: "rest-api" | "frontend" | "full-stack" | "microservices" | "library" | "cli" | "other";
         primaryLanguage: string;
@@ -1456,8 +1419,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1471,9 +1434,6 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         }[];
         notFound: string[];
     };
-    workspace: {
-        baseUrl: string;
-    };
     authentication: {
         method: string;
         configLocation: string;
@@ -1517,6 +1477,9 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         scanDepth: "quick" | "full";
         analysisScope?: AnalysisScope | undefined;
     };
+    workspace: {
+        baseUrl: string;
+    };
     projectClassification: {
         projectType: "rest-api" | "frontend" | "full-stack" | "microservices" | "library" | "cli" | "other";
         primaryLanguage: string;
@@ -1544,8 +1507,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1559,9 +1522,6 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         }[];
         notFound: string[];
     };
-    workspace: {
-        baseUrl: string;
-    };
     authentication: {
         method: string;
         configLocation: string;

package/build/types/ReuseOutcome.d.ts

@@ -17,6 +17,22 @@ import type { UtilsViolationKind } from "../utils/utils-verify/allow.js";
  * The internal record that run state keeps between the verify pass and the report
  * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
  * not part of this contract and must never reach a report.
+ *
+ * ABSENCE MEANS NOT MEASURED — the one invariant every member here obeys, and the
+ * one a producer is most likely to break. An optional member is omitted when this
+ * run did not establish its value, NEVER to mean `false`, `0` or "no": a `boolean?`
+ * left off says the check did not run, not that it failed, and a count left off says
+ * nothing was counted, not that the count was zero. So a producer that cannot
+ * measure something omits it rather than defaulting it, and a consumer renders an
+ * absent member as unknown rather than as a negative result.
+ *
+ * It is what lets a field be added without re-reading every row ever written, and
+ * what keeps a row from asserting more than the run established — the failure this
+ * whole shape exists to prevent, and the one that has recurred: a `reuse` of `null`
+ * over a test that demonstrably reused was read as "did not reuse" for four cohorts
+ * (see {@link ReuseOutcome.notDerived}). Where the distinction has to be visible in
+ * the report rather than inferred, the shape says so explicitly instead of relying
+ * on an omission.
  */
 /** Which gate declined a POM member. */
 export declare enum ReuseDeclinedBy {
@@ -138,9 +154,10 @@ export interface HelperReuseOutcome {
      *  TODO: remove `helpersImported` once the testbot renderer reads this field. The
      *  two carry one fact; the count stays only because testbot#349 reads it today. */
     helperNames: string[];
-    /** Inline request calls in OTHER Skyramp-generated tests beside this one that a
-     *  helper in `utilsFile` already wraps — reuse that was available and not taken.
-     *  Omitted at zero. Informational, like {@link ReuseOutcome.missedReuse}. */
+    /** Inline request calls (integration) or inline action sequences (UI) in OTHER
+     *  Skyramp-generated tests beside this one that a helper in `utilsFile` already
+     *  wraps — reuse that was available and not taken. Omitted at zero. Informational,
+     *  like {@link ReuseOutcome.missedReuse}. */
     siblingInlineCallSites?: number;
     /** Whether the delivered utils file holds the shared-helper invariants: one helper
      *  per method+path, status-code-only assertions, method+resource names — with
@@ -158,8 +175,17 @@ export interface HelperReuseOutcome {
      *  row ships with this field set, so the fault is disclosed rather than delivered
      *  in silence — or not delivered at all. */
     verificationFailures?: ReuseVerificationFailure[];
-    /** Pre-existing generated tests this spec's reuse pass rewired onto the utils
-     *  file, each with its recorded execution. Omitted when none. */
+    /** Pre-existing generated tests rewired onto the utils file by this run, each with
+     *  its recorded execution. Omitted when none.
+     *
+     *  Normally these are the siblings THIS spec's reuse pass reached. A row may also
+     *  name its OWN file: where two specs on one module were each edited by their own
+     *  chain, each claimed the other as its retrofit, and a claim that cannot be true
+     *  in both directions is reported against neither. The rewiring is still disclosed,
+     *  on the row for the file it happened to.
+     *
+     *  Across the rows of one report every file appears at most once, so the lists stay
+     *  disjoint and summable. */
     retrofits?: RetrofitOutcome[];
     /** Whether the delivered test plus the helpers it imports and calls still hold at
      *  least as many assertions as when modularization was handed out. A measured
@@ -172,10 +198,58 @@ export interface HelperReuseOutcome {
     /** Whether the `page.on('pageerror', …)` guard present at the modularization
      *  hand-out is still registered, in the test or in a shared helper it imports and
      *  calls. `true` when the hand-out had no guard to lose. Present whenever the
-     *  baseline exists, absent otherwise — like every optional member here, absent
-     *  means "not measured", never "false". */
+     *  baseline exists, absent otherwise — by the absence rule in this file's header. */
     pageErrorGuardPreserved?: boolean;
 }
+/** One of the repository's own helpers, and the module it lives in. */
+export interface InHouseHelperRef {
+    /** REPOSITORY-RELATIVE PATH (posix) of the customer's module. */
+    module: string;
+    helper: string;
+}
+/** A helper the run read in an in-house module and did not use. DECLARED by the
+ *  agent — recorded, never measured. */
+export interface InHouseDeclinedEntry {
+    file: string;
+    helper: string;
+    reason: string;
+}
+/**
+ * Reuse of the repository's OWN helper modules — files the customer wrote — by a
+ * browser test. Two kinds of field, and the report must label them apart:
+ *
+ * - MEASURED, re-derived from the delivered files at report time: which of the
+ *   customer's modules the spec imports, which helpers resolve, what this run added
+ *   to or widened in those modules (against HEAD), whether the additive gate ran.
+ * - DECLARED by the agent, recorded as testimony: the files its search read, and
+ *   the helpers it read and declined with the reason. A file list the agent produced
+ *   is not evidence the agent read everything, and the report says so.
+ *
+ * Absent when the spec imports no in-house module.
+ */
+export interface InHouseReuseOutcome {
+    /** MEASURED. Repository-relative paths of the customer's modules the spec imports. */
+    modules: string[];
+    /** MEASURED. Helpers the spec imports from those modules that resolve there. */
+    helpersUsed: string[];
+    /** MEASURED. Helpers this run added to a customer's module. */
+    helpersAdded: InHouseHelperRef[];
+    /** MEASURED. Existing helpers this run gave a defaulted parameter, and nothing else. */
+    helpersWidened: InHouseHelperRef[];
+    /** MEASURED. Whether every module was compared against HEAD. `false` is a gate
+     *  that could not run, never one that found nothing. */
+    additiveGateRan: boolean;
+    /** DECLARED. The files the agent's search read. Omitted when nothing was declared. */
+    filesRead?: string[];
+    /** DECLARED. Helpers the agent read and did not use, with its reason for each. */
+    declined?: InHouseDeclinedEntry[];
+    /** The in-house verdict, present only when no `helpers` row carries one — a spec
+     *  calling only in-house helpers has no Skyramp utils file, and "no utils file"
+     *  must not read as "nothing verified". */
+    verification?: HelperVerificationOutcome;
+    /** See {@link HelperReuseOutcome.verificationFailures}; present only on `failed`. */
+    verificationFailures?: ReuseVerificationFailure[];
+}
 /**
  * What lands in a report's `reuse` field for a generated test. Every member is
  * optional: consumers must render from whatever subset is present, and omit the
@@ -231,6 +305,25 @@ export interface ReuseOutcome {
     skipped?: ReuseSkippedEntry[];
     /** Shared-helper (SkyrampUtils) reuse. See {@link HelperReuseOutcome}. */
     helpers?: HelperReuseOutcome;
+    /** Reuse of the repository's own helper modules. See {@link InHouseReuseOutcome}. */
+    inHouse?: InHouseReuseOutcome;
+    /** Why no reuse record could be derived for this row, in a reader's words.
+     *
+     *  Present only when nothing else here is: no `helpers`, no `inHouse`, no POM
+     *  fields. It exists because their absence alone is ambiguous — a row with no
+     *  reuse summary reads identically to a row whose test reused nothing, and
+     *  consumers and reviewers have read it as the latter. A stated reason ("the
+     *  delivered file could not be read", "no shared helper module was located for
+     *  this test") separates the two.
+     *
+     *  The one place the absence rule above is not enough, and so the one member that
+     *  states what an omission cannot: every other member is absent when unmeasured,
+     *  and this says WHY the whole row is.
+     *
+     *  Never a verdict and never a fault: a run that legitimately had nothing to reuse
+     *  says so here. Additive and optional like every other member, so a consumer that
+     *  does not know it renders exactly what it rendered before. */
+    notDerived?: string;
     /** Present — and only ever `true` — when generation handed off a modularize→reuse
      *  step for this test and no reuse pass was recorded for it. Since the execution
      *  checkpoint refuses to run such a test until reuse is called, this can only

package/build/types/ReuseOutcome.js

@@ -15,6 +15,22 @@
  * The internal record that run state keeps between the verify pass and the report
  * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
  * not part of this contract and must never reach a report.
+ *
+ * ABSENCE MEANS NOT MEASURED — the one invariant every member here obeys, and the
+ * one a producer is most likely to break. An optional member is omitted when this
+ * run did not establish its value, NEVER to mean `false`, `0` or "no": a `boolean?`
+ * left off says the check did not run, not that it failed, and a count left off says
+ * nothing was counted, not that the count was zero. So a producer that cannot
+ * measure something omits it rather than defaulting it, and a consumer renders an
+ * absent member as unknown rather than as a negative result.
+ *
+ * It is what lets a field be added without re-reading every row ever written, and
+ * what keeps a row from asserting more than the run established — the failure this
+ * whole shape exists to prevent, and the one that has recurred: a `reuse` of `null`
+ * over a test that demonstrably reused was read as "did not reuse" for four cohorts
+ * (see {@link ReuseOutcome.notDerived}). Where the distinction has to be visible in
+ * the report rather than inferred, the shape says so explicitly instead of relying
+ * on an omission.
  */
 /** Which gate declined a POM member. */
 export var ReuseDeclinedBy;

package/build/types/StepMethod.js

@@ -37,7 +37,11 @@ export const UI_STEP_VERBS = [
 /** A call to something with no HTTP verb — a GraphQL operation, a Thrift or gRPC
  *  method. The operation's own name goes in `path`, and in `routes.operation`. */
 export const OPERATION_STEP_METHOD = "OPERATION";
-export const STEP_METHODS = [...HTTP_STEP_METHODS, ...UI_STEP_VERBS, OPERATION_STEP_METHOD];
+export const STEP_METHODS = [
+    ...HTTP_STEP_METHODS,
+    ...UI_STEP_VERBS,
+    OPERATION_STEP_METHOD,
+];
 const HTTP_BY_SPELLING = new Map(HTTP_STEP_METHODS.map((m) => [m.toLowerCase(), m]));
 const UI_BY_SPELLING = new Map(UI_STEP_VERBS.map((v) => [v, v]));
 /** One spelling of a method reduced to the canonical one, or `undefined` when it is
@@ -45,21 +49,27 @@ const UI_BY_SPELLING = new Map(UI_STEP_VERBS.map((v) => [v, v]));
  *  fixed on store, so `" post"` and `"Click"` are the same step as `POST` and
  *  `click`. Without the trim, one trailing space decided which checks ran. */
 export function normalizeStepMethod(raw) {
-    const spelling = String(raw ?? "").trim().toLowerCase();
+    const spelling = String(raw ?? "")
+        .trim()
+        .toLowerCase();
     if (!spelling)
         return undefined;
-    return HTTP_BY_SPELLING.get(spelling) ?? UI_BY_SPELLING.get(spelling) ?? (spelling === "operation" ? OPERATION_STEP_METHOD : undefined);
+    return (HTTP_BY_SPELLING.get(spelling) ??
+        UI_BY_SPELLING.get(spelling) ??
+        (spelling === "operation" ? OPERATION_STEP_METHOD : undefined));
 }
 /** Whether a method names a page interaction. Read off the canonical spelling,
  *  so a step that never went through the schema is judged the same way. */
 export function isUiStepVerb(raw) {
     const method = normalizeStepMethod(raw);
-    return method !== undefined && UI_STEP_VERBS.includes(method);
+    return (method !== undefined &&
+        UI_STEP_VERBS.includes(method));
 }
 /** Whether a method names an HTTP request. */
 export function isHttpStepMethod(raw) {
     const method = normalizeStepMethod(raw);
-    return method !== undefined && HTTP_STEP_METHODS.includes(method);
+    return (method !== undefined &&
+        HTTP_STEP_METHODS.includes(method));
 }
 const STEP_METHOD_HELP = `must be an HTTP method (${HTTP_STEP_METHODS.join(", ")}), a page interaction ` +
     `(${UI_STEP_VERBS.join(", ")}), or "${OPERATION_STEP_METHOD}" for a call with no HTTP verb — ` +
@@ -74,4 +84,8 @@ export const STEP_METHOD_DESCRIPTION = "What this step does to the system: an HT
  * The field itself: normalised first, then checked, so a rejection is about the
  * verb and never about its capitalisation.
  */
-export const stepMethodSchema = z.preprocess((value) => (typeof value === "string" ? (normalizeStepMethod(value) ?? value.trim()) : value), z.enum(STEP_METHODS, { errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }) }));
+export const stepMethodSchema = z.preprocess((value) => typeof value === "string"
+    ? (normalizeStepMethod(value) ?? value.trim())
+    : value, z.enum(STEP_METHODS, {
+    errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }),
+}));

package/build/types/TestAnalysis.d.ts

@@ -59,6 +59,13 @@ export interface MaintenanceActionCore {
      *  without this a downstream stage cannot tell a regeneration that rewrote a file from
      *  one that only advised it — and maintenance coverage would credit the advice. */
     reportOnly?: boolean;
+    /** Computed during instruction building — the path this UPDATE renames the spec TO,
+     *  when the endpoint rename implies one. Part of the core shape because the report
+     *  stage needs it: the rename lands before the test is executed, so the run is
+     *  recorded under THIS path while `testFilePath` still holds the old name, and a
+     *  stage that joins runs to files by `testFilePath` alone looks for a file that is
+     *  no longer there. */
+    _suggestedNewFile?: string;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {
@@ -78,8 +85,9 @@ export interface DriftRecommendation extends MaintenanceActionCore {
         anchor: string;
         change?: string;
     }>;
-    /** Computed during instruction building — suggested renamed file path if applicable. */
-    _suggestedNewFile?: string;
+    /** Computed during instruction building — the modularize → reuse steps this UPDATE's
+     *  file owes, when its language and test type are a modularize-first target. */
+    _postEditSteps?: string;
     /** REGENERATE/DELETE on an external (user-authored) test is report-only: the verdict is
      *  recorded and rendered in the report so the developer sees the recommendation, but the
      *  file is never touched (the apply loops skip reportOnly entries). Lets the report keep

package/build/types/TestExecution.d.ts

@@ -3,6 +3,7 @@
  *
  * These types define the structure for test execution results
  */
+import type { TestType } from "./TestTypes.js";
 /** Execution outcome for a test run recorded in the maintenance report. */
 export declare enum TestExecutionStatus {
     Pass = "Pass",
@@ -26,6 +27,50 @@ export interface TestExecutionResult extends TestExecutionData {
     testFile: string;
     videoPath?: string;
 }
+/**
+ * The latest skyramp_execute_test run of one file, persisted in run state for
+ * the post-execution steps (assertion alignment, the report) — every file, not
+ * only the maintained ones that have an `existingTests` row. `output` is
+ * bounded (head and tail around a marker); the tool response keeps the full
+ * text. A re-run of the file replaces the record and bumps `runs`.
+ */
+export interface TestExecutionRecord {
+    testType: TestType;
+    phase: "before" | "after";
+    status: TestExecutionStatus;
+    executedAt: string;
+    duration: number;
+    /** The process's real exit code, or -1 when none was produced — a timeout
+     *  kill or a spawn error before the process exited (an Error-status run;
+     *  see runTest in skyramp_execute_test). Never a real exit
+     *  code, which is always 0-255. */
+    exitCode: number;
+    errors: string[];
+    output: string;
+    outputTruncated: boolean;
+    /** Runs of this file recorded so far in this run, re-runs included. */
+    runs: number;
+    /** Runs recorded in the final ("after") phase only — the count the
+     *  fix-and-rerun attempt cap is measured against (SKYR-4460). A maintained
+     *  test's `phase: "before"` baseline run is not one of them. Absent on a
+     *  record written before the field existed; readers treat that as 0. */
+    afterRuns?: number;
+    /** sha256 of the test file's contents when this run was reserved (SKYR-4460).
+     *  Lets the next run tell an unchanged re-run from a fixed one: when the hash
+     *  has not moved, the tool withholds the unchanged-re-run allowances so one
+     *  of them cannot be regenerated run after run. Absent on older records. */
+    fileHash?: string;
+    /** Set on the placeholder a reservation writes while a run is in flight
+     *  (SKYR-4460): what the file's last COMPLETED run was, so a process that
+     *  dies mid-run leaves a record that still says what the file last did. A
+     *  completed result replaces the whole record and carries no previousRun. */
+    previousRun?: {
+        status: TestExecutionStatus;
+        phase: "before" | "after";
+        executedAt: string;
+        exitCode: number;
+    };
+}
 /**
  * One browser execution's recorded video, as persisted in run state by
  * skyramp_execute_test and read back by skyramp_submit_report (SKYR-4156).

package/build/types/TestRecommendation.d.ts

@@ -8,7 +8,7 @@ export declare enum Novelty {
  *  against this one: the report used to take a shorter list and rename the three
  *  above into it, which meant one test carried two category names. */
 export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
-export type ScenarioCategory = typeof SCENARIO_CATEGORIES[number];
+export type ScenarioCategory = (typeof SCENARIO_CATEGORIES)[number];
 /** What each category means, and whether it expects a failing test. The plan
  *  tool renders its `category` description from this, so the agent reads these
  *  sentences as it picks one. `expectsRed` is true only for the two naming a

package/build/types/TestRecommendation.js

@@ -31,7 +31,10 @@ const CATEGORIES = [
 /** Every category, and the only list there is. The plan and the report validate
  *  against this one: the report used to take a shorter list and rename the three
  *  above into it, which meant one test carried two category names. */
-export const SCENARIO_CATEGORIES = [...INTERNAL_CATEGORIES, ...CATEGORIES];
+export const SCENARIO_CATEGORIES = [
+    ...INTERNAL_CATEGORIES,
+    ...CATEGORIES,
+];
 /** What each category means, and whether it expects a failing test. The plan
  *  tool renders its `category` description from this, so the agent reads these
  *  sentences as it picks one. `expectsRed` is true only for the two naming a

package/build/types/TestTypes.d.ts

@@ -7,6 +7,9 @@ export declare enum ProgrammingLanguage {
     JAVASCRIPT = "javascript",
     JAVA = "java"
 }
+/** The languages skyramp_execute_test accepts, as prose for a prompt. Rendered from
+ *  the enum so the text and the gate that reads it cannot disagree. */
+export declare function runnableLanguagesText(): string;
 export declare enum TestType {
     SMOKE = "smoke",
     FUZZ = "fuzz",
@@ -18,6 +21,12 @@ export declare enum TestType {
     UNIT = "unit",
     UNKNOWN = "unknown"
 }
+/** The four types the testbot can plan and deliver. `TestType`'s others are
+ *  maintenance outcomes or report-only labels, so a planned test can never carry
+ *  one. The plan schema, the stored plan's type and the report's join all read
+ *  THIS list. */
+export declare const TESTBOT_SUPPORTED_TEST_TYPES: readonly [TestType.CONTRACT, TestType.INTEGRATION, TestType.E2E, TestType.UI];
+export type TestbotSupportedTestType = (typeof TESTBOT_SUPPORTED_TEST_TYPES)[number];
 /**
  * Mock is not a test type — mock files are deployed via apply_mock(),
  * not executed as tests. Kept as a standalone constant for mock generation.
@@ -246,6 +255,13 @@ export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse?: boolean | undefined;
     modularizeCode?: boolean | undefined;
 }>;
+/** The `testName` field for a recording-driven generation tool.
+ *
+ *  Single-sourced because the description is prompt text: it is the only thing
+ *  steering the agent's choice of title, it gets re-tuned against eval results,
+ *  and two copies would let the UI and E2E tools drift apart silently. Each
+ *  tool passes the title its own generator falls back to (SKYR-4468). */
+export declare const testNameField: (fallbackTitle: string) => z.ZodOptional<z.ZodString>;
 /** 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). */