@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/recommendation/answers.d.ts

@@ -0,0 +1,35 @@
+import { ObjectionAnswer, Objection } from "./types.js";
+/** The objection raised below carries this prefix and the id it objects to. */
+export declare const UNKNOWN_ANSWER_PREFIX = "answers:unknown:";
+/** The answer to one objection, matched by `objectionId` and never by position — the
+ *  agent reorders its list between registrations. A whitespace-only answer closes
+ *  nothing, and the FIRST NON-BLANK entry wins when one id is answered twice. */
+export declare function answerFor(objection: Objection, acknowledged: ObjectionAnswer[]): string | undefined;
+/** One objection per answer naming an objection this call did not raise — a stale
+ *  id, a typo and a pre-emptive answer all used to pass in silence. An id is
+ *  recognised BY ITS PREFIX and never draws an objection of its own. `scope` and
+ *  `suggestion` are passed in: the two callers raise this about different lists. */
+export declare function unknownAnswerObjections(objections: Objection[], acknowledged: ObjectionAnswer[], { scope, suggestion }: {
+    scope: string;
+    suggestion: string;
+}): Objection[];
+/** The one objection an answer does not close. Every other check in v2 can be
+ *  answered, and this one cannot: the missed bugs it exists for were reached by
+ *  prose twice and skipped twice, so an answer would close the objection and
+ *  leave the bug. `verifierContracts.ts` carries the evidence. */
+export declare const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
+export declare function isNonAnswerable(objectionId: unknown): boolean;
+/** The objection a sentence alone does not close either. A change with no test
+ *  needs the test, unless this run could not write one — so the answer closes it
+ *  only when it also names what stopped the run. Measured on run 34176038240:
+ *  across eight fixtures 45 objections were raised and 45 were closed, and the one
+ *  class that a sentence cannot close was never raised at all. Prose closed every
+ *  uncovered change, including changes nothing prevented a test from reaching. */
+export declare const BLOCKER_ONLY_PREFIX = "coverage:change:";
+export declare function needsBlocker(objectionId: unknown): boolean;
+/** The objection raised below carries this prefix and the id it objects to. */
+export declare const REFUSED_ANSWER_PREFIX = "answers:refused:";
+/** One objection per answer to an objection only a planned test closes. The answered
+ *  objection STAYS OPEN — this says so, rather than letting the answer pass in
+ *  silence while the plan still owes the test. */
+export declare function refusedAnswerObjections(objections: Objection[], acknowledged: ObjectionAnswer[]): Objection[];

package/build/recommendation/answers.js

@@ -0,0 +1,96 @@
+/** The objection raised below carries this prefix and the id it objects to. */
+export const UNKNOWN_ANSWER_PREFIX = "answers:unknown:";
+/** The answer to one objection, matched by `objectionId` and never by position — the
+ *  agent reorders its list between registrations. A whitespace-only answer closes
+ *  nothing, and the FIRST NON-BLANK entry wins when one id is answered twice. */
+export function answerFor(objection, acknowledged) {
+    const wantsBlocker = needsBlocker(objection.objectionId);
+    for (const entry of acknowledged) {
+        if (entry?.objectionId !== objection.objectionId)
+            continue;
+        const rawAnswer = entry.answer;
+        const answer = typeof rawAnswer === "string" ? rawAnswer.trim() : "";
+        if (answer.length === 0)
+            continue;
+        if (wantsBlocker && String(entry?.blocker ?? "").trim().length === 0)
+            continue;
+        return answer;
+    }
+    return undefined;
+}
+/** One objection per answer naming an objection this call did not raise — a stale
+ *  id, a typo and a pre-emptive answer all used to pass in silence. An id is
+ *  recognised BY ITS PREFIX and never draws an objection of its own. `scope` and
+ *  `suggestion` are passed in: the two callers raise this about different lists. */
+export function unknownAnswerObjections(objections, acknowledged, { scope, suggestion }) {
+    const answered = acknowledged.map((entry) => entry?.objectionId).filter((id) => typeof id === "string");
+    const raised = new Set(objections.map((objection) => objection.objectionId));
+    const raisedHere = [];
+    const seen = new Set();
+    for (const id of answered) {
+        if (id.startsWith(UNKNOWN_ANSWER_PREFIX) || raised.has(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        raisedHere.push({
+            objectionId: `${UNKNOWN_ANSWER_PREFIX}${id}`,
+            verifier: "answers",
+            message: "An answer names an objection this registration did not raise, so it closed nothing.",
+            evidence: `answered "${id}", which is not the id of any objection ${scope}`,
+            suggestion,
+        });
+    }
+    return raisedHere;
+}
+/** The one objection an answer does not close. Every other check in v2 can be
+ *  answered, and this one cannot: the missed bugs it exists for were reached by
+ *  prose twice and skipped twice, so an answer would close the objection and
+ *  leave the bug. `verifierContracts.ts` carries the evidence. */
+export const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
+export function isNonAnswerable(objectionId) {
+    return typeof objectionId === "string" && objectionId.startsWith(NON_ANSWERABLE_PREFIX);
+}
+/** The objection a sentence alone does not close either. A change with no test
+ *  needs the test, unless this run could not write one — so the answer closes it
+ *  only when it also names what stopped the run. Measured on run 34176038240:
+ *  across eight fixtures 45 objections were raised and 45 were closed, and the one
+ *  class that a sentence cannot close was never raised at all. Prose closed every
+ *  uncovered change, including changes nothing prevented a test from reaching. */
+export const BLOCKER_ONLY_PREFIX = "coverage:change:";
+export function needsBlocker(objectionId) {
+    return typeof objectionId === "string" && objectionId.startsWith(BLOCKER_ONLY_PREFIX);
+}
+/** The objection raised below carries this prefix and the id it objects to. */
+export const REFUSED_ANSWER_PREFIX = "answers:refused:";
+/** One objection per answer to an objection only a planned test closes. The answered
+ *  objection STAYS OPEN — this says so, rather than letting the answer pass in
+ *  silence while the plan still owes the test. */
+export function refusedAnswerObjections(objections, acknowledged) {
+    const raised = new Set(objections.map((objection) => objection.objectionId).filter((id) => isNonAnswerable(id) || needsBlocker(id)));
+    const refused = [];
+    const seen = new Set();
+    for (const entry of acknowledged) {
+        const id = entry?.objectionId;
+        if (typeof id !== "string" || !raised.has(id) || seen.has(id))
+            continue;
+        const answer = entry.answer;
+        if (typeof answer !== "string" || answer.trim().length === 0)
+            continue;
+        // An answer that names a blocker DOES close an untested change, so it is not
+        // refused. Only the sentence on its own is.
+        if (needsBlocker(id) && String(entry?.blocker ?? "").trim().length > 0)
+            continue;
+        seen.add(id);
+        refused.push({
+            objectionId: `${REFUSED_ANSWER_PREFIX}${id}`,
+            verifier: "answers",
+            message: needsBlocker(id)
+                ? "The answer says why this change has no test, and it does not say what stopped this run from writing one, so the objection stays open."
+                : "This objection is closed only by a planned test, so the answer closed nothing and the objection stays open.",
+            evidence: `answered "${id}"${needsBlocker(id) ? " with no `blocker`" : ", which no answer closes"}`,
+            suggestion: needsBlocker(id)
+                ? "Plan a test for this change and register the plan again. If this run cannot write one, send the same answer with `blocker` naming what stopped it — a service that is not running, a paired branch that no longer exists, the one credential the run holds. A reason the change is not worth testing is not a blocker."
+                : "Add a planned test that names the record's state as `startState` and runs this route's mutation on it, then register the plan again. Every other objection takes an answer; this one takes a test.",
+        });
+    }
+    return refused;
+}

package/build/recommendation/registerPlan.d.ts

@@ -0,0 +1,49 @@
+import { Objection, ObjectionAnswer, PlanChange, PlanInput, PlannedTest, VerifyContext } from "./types.js";
+/** The plan as stored for the run. Every registration produces one; the newest
+ *  replaces the last. */
+export interface Plan {
+    /** The changes the agent said the diff makes. Published in the report
+     *  beside the tests delivered against each one. */
+    changes: PlanChange[];
+    plannedTests: PlannedTest[];
+    /** Objections the agent answered, with the answers. */
+    answeredObjections: Array<{
+        objection: Objection;
+        answer: string;
+        blocker?: string;
+    }>;
+    /** Closed by a blocker nothing checked. Its own bucket rather than a flag on
+     *  `answeredObjections`, so a run's count of them is a number the report can
+     *  carry: the server holds six facts about a run and can falsify almost no
+     *  blocker, so the honest position is that these closes are UNCHECKED, not that
+     *  they are wrong. A run whose objections all close this way looks, in the
+     *  counts, exactly like a run that answered nothing. */
+    unverifiedCloses: Array<{
+        objection: Objection;
+        answer: string;
+        blocker: string;
+    }>;
+    /** Objections with no answer. Rendered in the report — this is the accountability. */
+    openObjections: Objection[];
+    /** Recorded, not owned. The caller counts the run's registrations and overwrites
+     *  whatever the agent sent; this function is pure and holds no run state, so it
+     *  stores the number it was handed. Nothing here enforces that. */
+    registrationNumber: number;
+}
+export interface PlanResult {
+    /** Always present. Once a registration reaches this function it is never refused;
+     *  the schema, which runs before it, is the only thing that can reject a call. */
+    plan: Plan;
+    /** Every objection this registration raised, answered or not. */
+    objections: Objection[];
+    /** One line for the tool's output text. */
+    summary: string;
+    /** The answers taken from the previous registration, and the number it had.
+     *  Absent when this registration carried none. Rendered so the agent rechecks
+     *  each one against the plan it has just changed. */
+    carried?: {
+        registrationNumber: number;
+        answers: ObjectionAnswer[];
+    };
+}
+export declare function registerPlan(registration: PlanInput, ctx: VerifyContext, previous?: Plan): PlanResult;

package/build/recommendation/registerPlan.js

@@ -0,0 +1,117 @@
+import { answerFor, isNonAnswerable, refusedAnswerObjections, unknownAnswerObjections } from "./answers.js";
+import { runPlanTimeVerifiers } from "./runVerifiers.js";
+import { logger } from "../utils/logger.js";
+function storedRegistrationNumber(registration) {
+    const raw = registration.registrationNumber;
+    return typeof raw === "number" && Number.isFinite(raw) ? raw : 1;
+}
+/** Run the plan-time verifiers and store the registration as the run's plan. Every
+ *  registration reaching here is stored and no objection blocks the agent; the schema
+ *  runs first and CAN reject. Never throws, because a crash discards the plan —
+ *  the strongest refusal there is. */
+/** The answer the previous registration gave one objection, or nothing. Passed as
+ *  a parameter rather than on `VerifyContext`: no verifier reads it, and the
+ *  previous plan is state the caller holds, not a fact a check is run against. */
+function carriedAnswerFor(objectionId, previous) {
+    // Both buckets: a blocker close is stored apart from an answer, and an objection
+    // that recurs still carries the one it was closed with.
+    const answered = [
+        ...(Array.isArray(previous?.answeredObjections) ? previous.answeredObjections : []),
+        ...(Array.isArray(previous?.unverifiedCloses) ? previous.unverifiedCloses : []),
+    ];
+    if (answered.length === 0)
+        return undefined;
+    for (const entry of answered) {
+        if (entry?.objection?.objectionId !== objectionId)
+            continue;
+        const answer = typeof entry.answer === "string" ? entry.answer.trim() : "";
+        // The blocker travels with the answer it belongs to. Carrying the sentence
+        // alone would reopen every untested change the previous registration closed.
+        if (answer.length > 0)
+            return { objectionId, answer, ...(entry.blocker ? { blocker: entry.blocker } : {}) };
+    }
+    return undefined;
+}
+/** The previous registration's answers to the objections THIS one raised again. An
+ *  answer sent in this call wins, a state-test objection is never carried, and an
+ *  answer whose objection is gone is dropped in silence — the agent sends the new
+ *  answers only, and the stored plan holds the rest. */
+function carriedAnswers(objections, acknowledged, previous) {
+    const carried = [];
+    for (const objection of objections) {
+        if (isNonAnswerable(objection.objectionId))
+            continue;
+        if (answerFor(objection, acknowledged))
+            continue;
+        const carriedAnswer = carriedAnswerFor(objection.objectionId, previous);
+        if (carriedAnswer)
+            carried.push(carriedAnswer);
+    }
+    return carried;
+}
+export function registerPlan(registration, ctx, previous) {
+    const acknowledged = Array.isArray(registration.answers) ? registration.answers : [];
+    const plannedTests = Array.isArray(registration.plannedTests) ? registration.plannedTests : [];
+    const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const registrationNumber = storedRegistrationNumber(registration);
+    // The verifiers see the same normalised fields the STORED plan gets, not the raw
+    // registration: handing them the raw one let a malformed top-level field crash
+    // every check at once, giving eight `:crashed` objections and no real ones.
+    // Crash containment is for a malformed field INSIDE a planned test.
+    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, answers: acknowledged }, ctx);
+    const objections = [
+        ...verified,
+        ...unknownAnswerObjections(verified, acknowledged, {
+            scope: "on this plan",
+            suggestion: "Answer only the ids in the Objections list this registration returns. An objection you have since fixed is gone and needs no answer, and an objection raised after the tests run cannot be answered before them.",
+        }),
+        ...refusedAnswerObjections(verified, acknowledged),
+    ];
+    const carried = carriedAnswers(objections, acknowledged, previous);
+    // The carried answers go last: `answerFor` takes the first non-blank entry, so
+    // an answer this registration sends wins over the one it replaces.
+    const answers = carried.length === 0 ? acknowledged : [...acknowledged, ...carried];
+    const answeredObjections = [];
+    const unverifiedCloses = [];
+    const openObjections = [];
+    for (const objection of objections) {
+        // Two objections take more than a sentence, and nothing here refuses a plan.
+        // Only a planned test closes the state-test objection. An untested change takes
+        // a planned test too, unless the answer names what stopped this run from
+        // writing one. Either way an answer that does not close it leaves it open and
+        // draws the refusal objection raised above.
+        const answer = isNonAnswerable(objection.objectionId) ? undefined : answerFor(objection, answers);
+        if (answer) {
+            const blocker = answers.find((entry) => entry?.objectionId === objection.objectionId && String(entry?.blocker ?? "").trim().length > 0)?.blocker;
+            // A blocker closes the objection and nothing here can check it, so it is
+            // counted apart from an answer the plan itself makes checkable.
+            if (blocker)
+                unverifiedCloses.push({ objection, answer, blocker });
+            else
+                answeredObjections.push({ objection, answer });
+        }
+        else
+            openObjections.push(objection);
+    }
+    const summary = objections.length === 0
+        ? "Plan stored. No objections."
+        : `Plan stored. ${openObjections.length} objection(s) open, ${answeredObjections.length} answered${unverifiedCloses.length > 0
+            ? `, ${unverifiedCloses.length} closed by a blocker nothing checked`
+            : ""}. Revise and register it again, or answer them — open objections appear in the report.`;
+    logger.info(`Plan v2: registration ${registrationNumber} stored — ${summary}`);
+    return {
+        objections,
+        summary,
+        ...(carried.length > 0 && previous
+            ? { carried: { registrationNumber: previous.registrationNumber, answers: carried } }
+            : {}),
+        plan: {
+            changes,
+            plannedTests,
+            answeredObjections,
+            unverifiedCloses,
+            openObjections,
+            registrationNumber,
+        },
+    };
+}

package/build/recommendation/runVerifiers.d.ts

@@ -0,0 +1,10 @@
+import { Objection, PlanInput, Verifier, VerifyContext } from "./types.js";
+/** Verifiers that need only the plan and the run's facts. The order is the order
+ *  objections are reported in; it carries no priority. */
+export declare const PLAN_TIME_VERIFIERS: Verifier[];
+/** One verifier, crash contained: declared types hold only on the validated
+ *  path, and a throw would discard a registration this design promises to store. */
+export declare function runVerifier(verifier: Verifier, registration: PlanInput, ctx: VerifyContext): Objection[];
+/** Every verifier runs on every registration: stopping at the first objection would
+ *  hand the agent one objection per round trip. */
+export declare function runPlanTimeVerifiers(registration: PlanInput, ctx: VerifyContext): Objection[];

package/build/recommendation/runVerifiers.js

@@ -0,0 +1,49 @@
+import { changedFile } from "./verifiers/changedFile.js";
+import { endpointGrounded } from "./verifiers/endpointGrounded.js";
+import { statedDifference } from "./verifiers/statedDifference.js";
+import { existingCoverage } from "./verifiers/existingCoverage.js";
+import { expectedOutcomeAtPlanTime } from "./verifiers/expectedOutcome.js";
+import { uiElementGrounded } from "./verifiers/uiElementGrounded.js";
+import { screenRoute } from "./verifiers/screenRoute.js";
+import { coverage } from "./verifiers/coverage.js";
+import { removedElementGuarded } from "./verifiers/removedElementGuarded.js";
+/** Verifiers that need only the plan and the run's facts. The order is the order
+ *  objections are reported in; it carries no priority. */
+export const PLAN_TIME_VERIFIERS = [
+    changedFile,
+    endpointGrounded,
+    statedDifference,
+    existingCoverage,
+    expectedOutcomeAtPlanTime,
+    uiElementGrounded,
+    screenRoute,
+    coverage,
+    removedElementGuarded,
+];
+/** How a crashed verifier reads back. The id is the verifier's name plus a fixed
+ *  word, so it stays stable across registrations and can be answered. */
+function crashedObjection(verifierName, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+        objectionId: `${verifierName}:crashed`,
+        verifier: verifierName,
+        message: `The ${verifierName} check could not run against this plan.`,
+        evidence: `${verifierName} threw: ${detail}`,
+        suggestion: "A field on one of the planned tests is probably not the type the schema describes — check `changedFile`, `expected`, `differsFrom` and `routes`, and that every entry of `plannedTests` is an object. The plan was stored and the other checks still ran.",
+    };
+}
+/** One verifier, crash contained: declared types hold only on the validated
+ *  path, and a throw would discard a registration this design promises to store. */
+export function runVerifier(verifier, registration, ctx) {
+    try {
+        return verifier.run(registration, ctx);
+    }
+    catch (error) {
+        return [crashedObjection(verifier.name, error)];
+    }
+}
+/** Every verifier runs on every registration: stopping at the first objection would
+ *  hand the agent one objection per round trip. */
+export function runPlanTimeVerifiers(registration, ctx) {
+    return PLAN_TIME_VERIFIERS.flatMap((verifier) => runVerifier(verifier, registration, ctx));
+}

package/build/recommendation/subjectStep.d.ts

@@ -0,0 +1,42 @@
+import { ScenarioStep } from "../types/RepositoryAnalysis.js";
+import { PlannedTest } from "./types.js";
+export declare const HTTP_METHODS: ReadonlySet<string>;
+/** Whether the planned test carries a `ui` or `e2e` label. The label alone exempts
+ *  nothing (see `isUICandidate`); the schema reads it alone only for a planned test
+ *  with no steps to look at. */
+export declare function hasUITestTypeLabel(rawTestType: unknown): boolean;
+/** Whether a step is an HTTP call: a real request method AND a path, since a verb
+ *  with no path names no route. `interactionType` is deliberately not consulted —
+ *  it labels what a step exercises, not how it reaches the app. Applied PER STEP. */
+export declare function isHTTPStep(step: ScenarioStep | undefined): boolean;
+/** Whether a step calls the app rather than driving a screen: anything with a
+ *  target whose method is not a page interaction, so an HTTP request and an
+ *  `OPERATION` both count. The page interactions are the closed set. */
+export declare function isCallStep(step: ScenarioStep | undefined): boolean;
+/** Whether a planned test is exempt from the route checks. A UI test's endpoints are
+ *  attributions the agent wrote, not what it asserts. THE LABEL DECIDES: inferring
+ *  from method names read a fixed list of HTTP verbs, so a GraphQL or Thrift call
+ *  looked like a browser click. Every verifier reads this one function. */
+export declare function isUIPlannedTest(plannedTest: PlannedTest): boolean;
+/** Every step that calls the app rather than driving a screen. */
+export declare function callSteps(plannedTest: PlannedTest): ScenarioStep[];
+/** The step a planned test's test is about: the one `stepUnderTest` names, or the only
+ *  call the planned test makes. A planned test that makes several calls and names none
+ *  has NO subject — the agent states it and the server asks when it is missing,
+ *  rather than ranking write methods and path prefixes to guess. A `stepUnderTest`
+ *  matching no call is undefined too: the declaration is wrong, not a hint. */
+export declare function subjectStep(plannedTest: PlannedTest): ScenarioStep | undefined;
+/** One step's route as a single key, `METHOD path`. The method is trimmed and
+ *  upper-cased, because a method is case-insensitive by protocol; the PATH is
+ *  compared AS WRITTEN, so two spellings of one route stay two routes. A step
+ *  with no path names no route and gets no key. */
+export declare function stepRouteKey(step: ScenarioStep | undefined): string | undefined;
+/** One step's route as `METHOD path` with every record id folded to `{id}`.
+ *
+ *  The state test asks whether the PLAN covers a route, and the id a step happened
+ *  to write is not part of the route: `/orders/777` and `/orders/888` are one
+ *  route tested twice, and reading them as two let a plan owe two state tests and
+ *  close one by renumbering (run 33988304641, LB03). `stepRouteKey` keeps the path
+ *  as written because `statedDifference` asks the opposite question — whether two
+ *  planned tests test the same thing — and there two spellings must stay two. */
+export declare function stateRouteKey(step: ScenarioStep | undefined): string | undefined;

package/build/recommendation/subjectStep.js

@@ -0,0 +1,86 @@
+import { HTTP_STEP_METHODS, isUiStepVerb } from "../types/StepMethod.js";
+export const HTTP_METHODS = new Set(HTTP_STEP_METHODS);
+/** Whether the planned test carries a `ui` or `e2e` label. The label alone exempts
+ *  nothing (see `isUICandidate`); the schema reads it alone only for a planned test
+ *  with no steps to look at. */
+export function hasUITestTypeLabel(rawTestType) {
+    // Trimmed as well as lower-cased: without the trim `"ui "` was checked and
+    // `"UI"` was not, so one trailing space decided which of three verifiers ran.
+    const testType = String(rawTestType ?? "").trim().toLowerCase();
+    return testType === "ui" || testType === "e2e";
+}
+/** Whether a step is an HTTP call: a real request method AND a path, since a verb
+ *  with no path names no route. `interactionType` is deliberately not consulted —
+ *  it labels what a step exercises, not how it reaches the app. Applied PER STEP. */
+export function isHTTPStep(step) {
+    const method = String(step?.method ?? "").trim().toUpperCase();
+    return HTTP_METHODS.has(method) && String(step?.path ?? "").trim().length > 0;
+}
+/** Whether a step calls the app rather than driving a screen: anything with a
+ *  target whose method is not a page interaction, so an HTTP request and an
+ *  `OPERATION` both count. The page interactions are the closed set. */
+export function isCallStep(step) {
+    return !isUiStepVerb(step?.method) && String(step?.path ?? "").trim().length > 0;
+}
+/** Whether a planned test is exempt from the route checks. A UI test's endpoints are
+ *  attributions the agent wrote, not what it asserts. THE LABEL DECIDES: inferring
+ *  from method names read a fixed list of HTTP verbs, so a GraphQL or Thrift call
+ *  looked like a browser click. Every verifier reads this one function. */
+export function isUIPlannedTest(plannedTest) {
+    // A null entry in `plannedTests` reaches here on the second, unvalidated
+    // caller the schema does not cover. Without this guard `planned test.scenario`
+    // throws, and `runVerifier` turns that throw into an acknowledgeable
+    // "crashed" objection — which hides the real objection instead of raising it.
+    if (!plannedTest)
+        return false;
+    return hasUITestTypeLabel(plannedTest.scenario?.testType);
+}
+/** Every step that calls the app rather than driving a screen. */
+export function callSteps(plannedTest) {
+    return (plannedTest?.scenario?.steps ?? []).filter((step) => isCallStep(step));
+}
+/** The step a planned test's test is about: the one `stepUnderTest` names, or the only
+ *  call the planned test makes. A planned test that makes several calls and names none
+ *  has NO subject — the agent states it and the server asks when it is missing,
+ *  rather than ranking write methods and path prefixes to guess. A `stepUnderTest`
+ *  matching no call is undefined too: the declaration is wrong, not a hint. */
+export function subjectStep(plannedTest) {
+    const calls = callSteps(plannedTest);
+    const declaredOrder = plannedTest?.declarations?.stepUnderTest;
+    if (typeof declaredOrder === "number")
+        return calls.find((step) => (step.order ?? 0) === declaredOrder);
+    return calls.length === 1 ? calls[0] : undefined;
+}
+/** One step's route as a single key, `METHOD path`. The method is trimmed and
+ *  upper-cased, because a method is case-insensitive by protocol; the PATH is
+ *  compared AS WRITTEN, so two spellings of one route stay two routes. A step
+ *  with no path names no route and gets no key. */
+export function stepRouteKey(step) {
+    const path = String(step?.path ?? "").trim();
+    if (!path)
+        return undefined;
+    const method = String(step?.method ?? "ANY").trim().toUpperCase() || "ANY";
+    return `${method} ${path}`;
+}
+/** A segment that identifies one record rather than naming part of the route: all
+ *  digits, a UUID, or a `{param}` / `:param` placeholder. */
+const RECORD_ID_SEGMENT = /^(?:\d+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|\{[^}]*\}|:[^/]+)$/;
+/** One step's route as `METHOD path` with every record id folded to `{id}`.
+ *
+ *  The state test asks whether the PLAN covers a route, and the id a step happened
+ *  to write is not part of the route: `/orders/777` and `/orders/888` are one
+ *  route tested twice, and reading them as two let a plan owe two state tests and
+ *  close one by renumbering (run 33988304641, LB03). `stepRouteKey` keeps the path
+ *  as written because `statedDifference` asks the opposite question — whether two
+ *  planned tests test the same thing — and there two spellings must stay two. */
+export function stateRouteKey(step) {
+    const path = String(step?.path ?? "").trim();
+    if (!path)
+        return undefined;
+    const method = String(step?.method ?? "ANY").trim().toUpperCase() || "ANY";
+    const folded = path
+        .split("/")
+        .map((segment) => (RECORD_ID_SEGMENT.test(segment) ? "{id}" : segment))
+        .join("/");
+    return `${method} ${folded}`;
+}

package/build/recommendation/types.d.ts

@@ -0,0 +1,163 @@
+import { ChangedFileName } from "../utils/branchDiff.js";
+import { PlanScenario } from "../types/RepositoryAnalysis.js";
+import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
+import type { RemovedUiElement } from "../utils/removedUiElements.js";
+/** One element a UI planned test targets. EVERY field is optional and three are
+ *  nullable: a declaration reaches a verifier unvalidated, so a missing or null
+ *  field is an objection, not a crash. Not `Partial<BlueprintElementDigest>` —
+ *  the capture's shape has no nulls and requires role and accessibleName. */
+export interface DeclaredUiElement {
+    role?: string;
+    accessibleName?: string;
+    testId?: string | null;
+    stableId?: string | null;
+    contextText?: string[] | null;
+    /** Carried because the plan schema reuses the report's `targetElementSchema`.
+     *  No plan check reads either one. */
+    mutability?: "mutable" | "immutable" | "unknown";
+    widgetType?: "native" | "custom" | "unknown";
+}
+/** One change the diff makes, as the agent read it. Nothing on the server parses
+ *  a description. */
+export interface PlanChange {
+    id: string;
+    text: string;
+    source: string;
+    /** Where a user or caller meets this change. Every change states it: an optional
+     *  field the agent skips gives the check nothing to read. */
+    surfaces: Array<"api" | "page">;
+    /** The inputs that prove this change: what a route must accept and what it must
+     *  reject. Exactly one of `value` and `absent` per entry. The coverage check reads
+     *  it; nothing else on the server does. */
+    cases?: Array<{
+        param: string;
+        value?: string | number | boolean | null;
+        absent?: true;
+        expect: "accept" | "reject";
+    }>;
+}
+/** What a planned test states so a verifier has a checkable change. Kept in step with
+ *  `declarationFieldsSchema`, which the plan tool asserts against this type. */
+export interface PlannedTestDetails {
+    /** One of the files this run's diff changed. It is what makes a planned test count
+     *  as covering that file. Absent on a full-repo run. */
+    changedFile?: string;
+    asserts: string;
+    /** The `order` of the step the test is about. Required whenever the planned test
+     *  makes more than one call: nothing infers a subject. */
+    stepUnderTest?: number;
+    /** ABSENT means undeclared, which readers must tell apart from a declared red. */
+    expected?: {
+        outcome: "fail" | "pass";
+        why: string;
+    };
+    /** Required only when another planned test targets the same endpoint. */
+    differsFrom?: Array<{
+        plannedTestId: string;
+        difference: string;
+    }>;
+    /** Only each file's presence in the checkout is checked. */
+    existingTests?: Array<{
+        file: string;
+        differsBy: string;
+    }>;
+    /** The file that declares what a step calls, one entry per step, named by
+     *  `order`. Nothing reads INSIDE the cited file: frameworks assemble paths from
+     *  scopes and prefixes, so the path often appears nowhere. */
+    routes?: Array<{
+        step?: number;
+        file: string;
+    }>;
+    /** The changed file that renders the screen `elements.pageUrl` opens. */
+    screenEvidence?: {
+        file: string;
+    };
+    /** The ids of the declared changes this test proves. */
+    changes?: string[];
+    /** The state the mutated record is in before the mutation. Presence only. */
+    startState?: string;
+    /** UI planned tests only. `items` entries are COPIES of elements a capture of
+     *  `pageUrl` holds. `items: null` MEANS capture failed and carries the
+     *  `[no-blueprint-data]` obligation; `elements: null` is dropped at parse. */
+    elements?: {
+        pageUrl?: string;
+        items?: DeclaredUiElement[] | null;
+    };
+}
+export interface PlannedTest {
+    plannedTestId: string;
+    scenario: PlanScenario;
+    declarations: PlannedTestDetails;
+    /** Deliberately NOT part of the planned test id: an id stays the same across
+     *  registrations, and a single-repo plan names no repository. */
+    repository?: string;
+}
+export interface ObjectionAnswer {
+    objectionId: string;
+    answer: string;
+    /** What stopped this run from writing the test: a service that is not running,
+     *  a paired branch that no longer exists, the one credential the run holds.
+     *  An objection about an untested change closes only with one of these. */
+    blocker?: string;
+}
+export interface PlanInput {
+    /** The changes the diff makes. Each planned test cites the ones it tests. */
+    changes: PlanChange[];
+    plannedTests: PlannedTest[];
+    answers: ObjectionAnswer[];
+    /** The tool owns this and overwrites whatever the caller sends. */
+    registrationNumber: number;
+}
+/** A verifier's objection. Advisory: it never removes a planned test. */
+export interface Objection {
+    /** UNIQUE within a run — answers match by id, so a shared id closes the wrong
+     *  objection. `<verifier>:<plannedTestId>`, or `<verifier>:<objection>`. */
+    objectionId: string;
+    verifier: string;
+    /** Absent for a plan-level objection, and absent whenever the id is not one the
+     *  plan holds. It is always in `evidence` regardless. */
+    plannedTestId?: string;
+    message: string;
+    evidence: string;
+    /** Required: an objection without a next move reads as a rejection. */
+    suggestion: string;
+}
+/** Facts the verifiers check against. Gathered once per run by the caller. */
+export interface VerifyContext {
+    /** Every repository this run analyzed, and the files its diff changed there.
+     *  NAMES ONLY, never contents. A single-repository run has one entry. */
+    changedFiles: Record<string, ChangedFileName[]>;
+    /** Repositories with no branch diff. Softens objections RUN-WIDE, because a
+     *  planned test that names no repository is checked against every one of them. */
+    reposWithoutDiff: string[];
+    /** Every `browser_blueprint` capture this run took, in order. Evidence, not an
+     *  allowlist: a capture shows the page as it stood when it was taken, so an
+     *  element behind a modal the walk never opened is legitimately missing. */
+    uiCaptures: BlueprintCaptureDigest[];
+    /** The identifying `data-*` attributes the diff removed from a page that
+     *  survives. A removal guard declares the element that is GONE, so no capture
+     *  can hold it and this list is its only grounding. */
+    removedUiElements: RemovedUiElement[];
+    /** Whether a cited path names a file in any of the run's repositories. Injected
+     *  to keep the verifiers filesystem-free. */
+    citedFileExists(relativePath: string): boolean;
+    /** The route patterns that mount a changed frontend file, as the framework
+     *  spells them (`/secrets/$envSlug`, `/orders/:id`). Injected for the same
+     *  reason as `citedFileExists`: the scan reads the repository, the verifier
+     *  does not. UNDEFINED means the resolver cannot speak for this file — an
+     *  unsupported framework, a route table it could not parse — and the check
+     *  stays silent. An EMPTY array is a statement: nothing mounts it. */
+    routesRenderingFile?(relativePath: string): string[] | undefined;
+}
+/** Every changed file of the run, whatever repository it sits in. */
+export declare function allChangedFiles(ctx: VerifyContext): ChangedFileName[];
+export interface Verifier {
+    readonly name: string;
+    run(registration: PlanInput, ctx: VerifyContext): Objection[];
+}
+/** The changed files a planned test is checked against: its own repository's when it
+ *  names one this run analyzed, every repository's when it names none. UNDEFINED
+ *  when it names a repository this run does not know, which the caller objects to. */
+export declare function changedFilesFor(ctx: VerifyContext, plannedTest: {
+    repository?: string;
+}): ChangedFileName[] | undefined;