@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/recommendation/budgeters/shared.js

@@ -1,246 +0,0 @@
-import { TestType } from "../../types/TestTypes.js";
-import { inferScenarioType, prioritizeAttackSurfaceBundles } from "../diversity.js";
-import { externalDedupKeys, scenarioCoverageKeys, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
-import { isFlawTargetingCategory } from "../../types/TestRecommendation.js";
-import { logger } from "../../utils/logger.js";
-/**
- * What each PR class GUARANTEES in GENERATE (SKYR-4275). These are floors, not
- * quotas: the slots above them are open to either kind, decided by `pick`.
- * An open slot goes to whichever candidate `pick` chooses on rank, so a backend
- * candidate takes one when it outranks the UI candidates, not merely because it
- * exists. Measured against main on random mixed pools at `maxGenerate` 5 with no
- * caught bugs: 35% get fewer backend tests than main did, average 3.53 to 3.24.
- *
- * Backend-only floors nothing on purpose: of 86 backend-only diffs in the eval
- * corpus, ZERO generated a UI test, so a floor there would guarantee what
- * already happens every time.
- *
- * At one slot there is no room for a floor plus an open slot, so each class
- * keeps that slot for its own kind.
- *
- * The floors always sum to at most `maxGenerate`, which is what lets
- * `applyFloors` satisfy both without one starving the other.
- */
-export function generateFloors(ctx) {
-    // Number.isFinite, not Math.max: `Math.max(0, NaN)` is NaN, which compares
-    // false against 0 and would fall through to the class branches below.
-    const max = Number.isFinite(ctx.maxGenerate) ? Math.max(0, Math.floor(ctx.maxGenerate)) : 0;
-    if (max === 0)
-        return { ui: 0, backend: 0 };
-    if (ctx.isUIOnlyPR)
-        return { ui: max === 1 ? 1 : max - 1, backend: 0 };
-    if (ctx.hasFrontendChanges)
-        return max === 1 ? { ui: 1, backend: 0 } : { ui: 1, backend: 1 };
-    return { ui: 0, backend: 0 };
-}
-/**
- * Raise a chosen GENERATE set to meet the floors, by swapping rather than
- * re-picking. `pick` runs ONCE over the whole pool, so its protected-first
- * ordering, its one-slot-per-test-type coverage and attack-surface bundle
- * adjacency are all settled before this runs. Picking each floor from its own
- * slice instead would compute those guarantees per slice and collapse them —
- * measured at 25% of mixed-PR inputs losing a test type, 8.3% losing contract
- * coverage outright.
- *
- * A floor is raised only as far as the pool allows. Satisfying one floor cannot
- * starve the other, because `generateFloors` never returns two that sum above
- * the budget — `generateFloors.test.ts` pins that invariant.
- */
-function applyFloors(generate, slotOrdered, floors, isUI) {
-    const isBackend = (item) => !isUI(item);
-    const result = [...generate];
-    for (const [want, wanted] of [
-        [floors.ui, isUI],
-        [floors.backend, isBackend],
-    ]) {
-        const spare = slotOrdered.filter((item) => wanted(item) && !result.includes(item));
-        let shortfall = Math.min(want, result.filter(wanted).length + spare.length) - result.filter(wanted).length;
-        // Swap from the END: `pick` returns its slots in preference order, so the
-        // last one it chose is the one this PR class needs least.
-        for (let i = result.length - 1; i >= 0 && shortfall > 0; i--) {
-            if (wanted(result[i]))
-                continue;
-            result[i] = spare.shift();
-            shortfall--;
-        }
-    }
-    return result;
-}
-/**
- * Split candidates by whether an external test already covers them. Protected
- * `bug_caught` / `requirement_conflict` / attack-surface scenarios always count
- * as uncovered — they require semantic flaw coverage the external test may not
- * provide.
- *
- * A candidate is covered only when the set holds EVERY one of its keys. One
- * match is not coverage: a scenario exercising two changed endpoints would lose
- * the endpoint the external test does not reach (SKYR-4214). An empty key list
- * carries no information, so it never removes anything.
- *
- * The covered group is held back, not discarded. `runBudget` moves it into
- * ADDITIONAL when GENERATE's backend half would otherwise be empty (SKYR-4024),
- * and records it as dropped, with a reason, when it does not.
- */
-function partitionByExternalCoverage(ranked, externalCoverage) {
-    if (externalCoverage.size === 0)
-        return { uncovered: ranked, covered: [] };
-    const uncovered = [];
-    const covered = [];
-    for (const item of ranked) {
-        const keys = externalDedupKeys(item.scenario);
-        if (keys.length === 0 || !keys.every((key) => externalCoverage.has(key))) {
-            uncovered.push(item);
-            continue;
-        }
-        if (isFlawTargetingCategory(item.scenario.category) || isAttackSurfaceSecurityBoundary(item.scenario)) {
-            logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/requirement-conflict/attack-surface scenario requires semantic flaw coverage`);
-            uncovered.push(item);
-            continue;
-        }
-        logger.info(`External dedup: "${item.scenario.scenarioName}" (${keys.join(", ")}) covered by an external test — eligible for the reserve`);
-        covered.push({ item, keys });
-    }
-    return { uncovered, covered };
-}
-/**
- * Shared budgeting pipeline. All Budgeters run the same external-dedup,
- * attack-surface prioritization, and ADDITIONAL set-difference; they differ
- * ONLY in how they pick the GENERATE items from the slot-ordered list (`pick`).
- *
- * With `pick = roundRobinByType` this reproduces the pre-refactor selection in
- * diffExecutionPlan.ts exactly.
- */
-export function runBudget(ranked, rawCtx, pick) {
-    // SKYR-4292: maxTotal is the budget; maxGenerate is how much of it to generate.
-    // Every producer clamps upstream (getTestbotPrompt, computeScoredCandidates,
-    // buildScopeAssessmentSection), but a state file is the tool boundary and can
-    // carry maxGenerate > maxTotal — the UI-only branch then reserved maxGenerate
-    // slots and planned more items than the total. Clamp once here so every
-    // budgeter agrees with the prompt. It must stay ABOVE generateFloors(ctx):
-    // the floors are computed from the clamped budget, and moving the clamp
-    // below them would let the floors sum past maxTotal again (review on #835).
-    const ctx = { ...rawCtx, maxGenerate: Math.min(rawCtx.maxGenerate, rawCtx.maxTotal) };
-    const dropped = [];
-    const floors = generateFloors(ctx);
-    const { uncovered, covered } = partitionByExternalCoverage(ranked, ctx.externalCoverage);
-    const slotOrdered = prioritizeAttackSurfaceBundles(uncovered);
-    const isUICandidate = (item) => inferScenarioType(item.scenario) === TestType.UI;
-    // ONE pick over the whole pool — the shape the backend pick always had — so
-    // `pick` decides protected-first order, per-type coverage and bundle adjacency
-    // exactly once. `applyFloors` then corrects only the UI/backend mix.
-    const budget = Number.isFinite(ctx.maxGenerate) ? Math.max(0, Math.floor(ctx.maxGenerate)) : 0;
-    const picked = pick(slotOrdered, Math.min(budget, slotOrdered.length));
-    const generate = applyFloors(picked, slotOrdered, floors, isUICandidate);
-    // SKYR-4024. A covered candidate is one an existing test already reaches, so
-    // generating a second test for it is wrong — maintenance updates the existing
-    // one. But dropping it outright removed it from the RECOMMENDATIONS too, and an
-    // empty GENERATE is authoritative downstream. The reserve surfaces it as
-    // ADDITIONAL instead. The emptiness test reads the backend half: on a mixed PR
-    // one UI candidate fills the reserved slot while every covered backend
-    // candidate would otherwise vanish.
-    //
-    // Three conditions keep the reserve shut where recommending nothing is right.
-    // A UI-only PR is left alone. A zero budget is an explicit abstention, so it
-    // must not be talked out of recommending nothing. And the PR must not touch a
-    // test file of its own: coverage is read from the working tree, and a test
-    // file without the Skyramp marker counts as external, so a PR that adds its
-    // own tests would have that coverage used as grounds to recommend duplicates
-    // of it.
-    //
-    // One pick over the whole pool leaves no "backend half" to count, so the
-    // emptiness test reproduces what that half used to mean per class. On a mixed
-    // PR the UI slot must not read as backend coverage, or a covered backend
-    // candidate vanishes behind it. On a backend-only PR the pick always drew from
-    // the whole pool, so a non-empty GENERATE closed the reserve even when every
-    // item was UI — keep that, or an all-UI pool opens a reserve it never opened.
-    const backendChosen = generate.filter((item) => !isUICandidate(item));
-    const backendHalfEmpty = ctx.hasFrontendChanges
-        ? backendChosen.length === 0
-        : generate.length === 0;
-    // One per-class behaviour DID change here, deliberately. On a mixed PR at a
-    // budget of 1 the old gate also required `backendGenerateCount > 0`, which is
-    // 0 for that class, so a covered backend candidate was dropped outright. The
-    // reserve exists because dropping removes a candidate from the
-    // RECOMMENDATIONS too (SKYR-4024), and a budget of 1 is the case where that
-    // costs most — there is no second slot to find it later. It is now
-    // recommended instead of dropped. `reserveOpensForMixedPRAtBudgetOne` in
-    // shared.test.ts pins it, so a future change has to mean it.
-    const spendReserve = backendHalfEmpty &&
-        !ctx.isUIOnlyPR &&
-        budget > 0 &&
-        covered.length > 0 &&
-        !ctx.diffChangesTestFiles;
-    if (spendReserve) {
-        logger.info(`External dedup: GENERATE empty after dedup — recommending ${covered.length} held-back candidate(s) as ADDITIONAL rather than approving an empty plan`);
-    }
-    else if (covered.length > 0) {
-        // SKYR-4214. The reserve stayed shut, so these really are dropped — say so,
-        // with the reason, instead of leaving the agent an unexplained short list.
-        const reason = !backendHalfEmpty
-            ? `the backend half of GENERATE is filled (${backendChosen.length || generate.length})`
-            : ctx.isUIOnlyPR
-                ? "a UI-only PR keeps its slots for UI"
-                : budget === 0
-                    ? "the budget is zero"
-                    : "the PR changes test files of its own";
-        logger.info(`External dedup: dropping ${covered.length} covered candidate(s) — reserve shut because ${reason}`);
-        for (const { item, keys } of covered) {
-            dropped.push({
-                candidateId: item.candidateId,
-                reason: `covered by an external test (${keys.join(", ")})`,
-            });
-        }
-    }
-    // ADDITIONAL = everything not chosen for GENERATE, in rank order, minus any
-    // whose subject endpoints are ALL already covered by GENERATE, then capped at
-    // the remaining budget. All, not any: an item that also covers an endpoint no
-    // GENERATE item reaches is not a duplicate. An empty key list never removes
-    // an item.
-    //
-    // The duplicate filter runs BEFORE the cap. In the other order a duplicate
-    // took a slot and then vacated it, and nothing moved up: eval run
-    // 32543498147, fixture cc15-org-reviewer-role, filled 19 of a maxTotal of 20
-    // while 16 candidates carried the reason "beyond the maxTotal budget of 20".
-    // A candidate that is both a duplicate and past the cap now reports the
-    // duplicate — the stronger reason, and the only one that does not depend on
-    // where the cap happened to fall.
-    const additionalSource = spendReserve
-        ? [...slotOrdered, ...prioritizeAttackSurfaceBundles(covered.map((c) => c.item))]
-        : slotOrdered;
-    const chosen = new Set(generate);
-    const notChosen = additionalSource.filter((it) => !chosen.has(it));
-    const remainingBudget = Math.max(0, ctx.maxTotal - generate.length);
-    const generatedCoverage = new Set(generate.flatMap((item) => scenarioCoverageKeys(item.scenario)));
-    const notDuplicate = notChosen.filter((item) => {
-        const keys = scenarioCoverageKeys(item.scenario);
-        if (keys.length === 0 || !keys.every((key) => generatedCoverage.has(key)))
-            return true;
-        // Same exemption the EXTERNAL dedup above already makes, for the same
-        // reason: a flaw-targeting scenario (a caught bug, or a requirement the code
-        // contradicts) or an attack-surface boundary asserts a specific defect, and
-        // sharing an endpoint with a GENERATE item is not evidence that the defect is
-        // covered. Without it a PR with two defects in one handler had its second one
-        // deleted here — the first took a GENERATE slot, and the key is method +
-        // resource + test type + interaction + status, which two tests on one
-        // endpoint share.
-        if (isFlawTargetingCategory(item.scenario.category) || isAttackSurfaceSecurityBoundary(item.scenario)) {
-            logger.info(`GENERATE dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/requirement-conflict/attack-surface scenario requires semantic flaw coverage`);
-            return true;
-        }
-        dropped.push({
-            candidateId: item.candidateId,
-            reason: `covered by GENERATE (${keys.join(", ")})`,
-        });
-        return false;
-    });
-    const additional = notDuplicate.slice(0, remainingBudget);
-    for (const item of notDuplicate.slice(remainingBudget)) {
-        dropped.push({
-            candidateId: item.candidateId,
-            reason: `beyond the maxTotal budget of ${ctx.maxTotal}`,
-        });
-    }
-    // Budgeting itself produces no demotions; the register-plan selection stage
-    // (planRanker.selectPlan) fills this channel from discriminator verification.
-    return { generate, additional, reservedUISlots: floors.ui, demotions: [], dropped };
-}

package/build/recommendation/discriminators.d.ts

@@ -1,37 +0,0 @@
-import { DraftedScenario } from "../types/RepositoryAnalysis.js";
-import { DiscriminatorKind } from "../types/Recommendation.js";
-/**
- * A discriminator claim the agent (or server) attaches to a candidate: the
- * structural bug-shape (`kind`) plus the verbatim diff snippet the test probes.
- */
-export interface DiscriminatorClaim {
-    kind: DiscriminatorKind;
-    changedCodeAnchor: string;
-}
-/** Result of verifying a claim against a scenario's steps and the PR diff. */
-export interface DiscriminatorValidation {
-    verified: boolean;
-    /** One-sentence, human-readable reason present ONLY when `verified` is false;
-     *  it is returned to the LLM to help it fix the claim. */
-    reason?: string;
-}
-/**
- * Verify a declared discriminator against the candidate's `steps[]` and the PR
- * diff. Mirrors the classification precedent (`recommendationShared.ts`): the
- * claim is checked STRUCTURALLY, never by fuzzy keyword scans of prose. A failed
- * check returns `verified: false` with a one-sentence reason (the claim is
- * demoted, never used to reject the candidate). NEVER throws — malformed or
- * partial input is treated as unverified.
- *
- * Two gates, both required to verify:
- *  1. `changedCodeAnchor` must be a non-trivial string (>= 8 chars after trim)
- *     occurring verbatim in `diffText` — grounds the claim in the real change.
- *  2. The `kind`-specific structural predicate must hold over `steps[]`.
- *
- * `reposWithoutDiff` names repos in the run whose section carries no branch
- * diff (e.g. a related repo that fell back to its default branch, SKYR-4203).
- * An anchor those repos' changes could contain cannot be disproven, so an
- * unmatched anchor then fails with a "could not be checked" reason instead of
- * the "not grounded" one — still unverified (no boost), but distinguishable.
- */
-export declare function validateDiscriminator(scenario: DraftedScenario, declared: DiscriminatorClaim, diffText: string, reposWithoutDiff?: string[]): DiscriminatorValidation;

package/build/recommendation/discriminators.js

@@ -1,379 +0,0 @@
-import { DiscriminatorKind } from "../types/Recommendation.js";
-const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
-const MIN_ANCHOR_LENGTH = 8;
-const MIN_NEAR_MISS_LENGTH = 3;
-/**
- * Verify a declared discriminator against the candidate's `steps[]` and the PR
- * diff. Mirrors the classification precedent (`recommendationShared.ts`): the
- * claim is checked STRUCTURALLY, never by fuzzy keyword scans of prose. A failed
- * check returns `verified: false` with a one-sentence reason (the claim is
- * demoted, never used to reject the candidate). NEVER throws — malformed or
- * partial input is treated as unverified.
- *
- * Two gates, both required to verify:
- *  1. `changedCodeAnchor` must be a non-trivial string (>= 8 chars after trim)
- *     occurring verbatim in `diffText` — grounds the claim in the real change.
- *  2. The `kind`-specific structural predicate must hold over `steps[]`.
- *
- * `reposWithoutDiff` names repos in the run whose section carries no branch
- * diff (e.g. a related repo that fell back to its default branch, SKYR-4203).
- * An anchor those repos' changes could contain cannot be disproven, so an
- * unmatched anchor then fails with a "could not be checked" reason instead of
- * the "not grounded" one — still unverified (no boost), but distinguishable.
- */
-export function validateDiscriminator(scenario, declared, diffText, reposWithoutDiff = []) {
-    try {
-        const anchorResult = verifyAnchor(declared?.changedCodeAnchor, diffText, reposWithoutDiff);
-        if (!anchorResult.verified)
-            return anchorResult;
-        const steps = Array.isArray(scenario?.steps) ? scenario.steps : [];
-        switch (declared?.kind) {
-            case DiscriminatorKind.BOUNDARY_EQUALITY:
-                return verifyBoundaryEquality(steps);
-            case DiscriminatorKind.MULTI_RECORD_AGGREGATE:
-                return verifyMultiRecordAggregate(steps);
-            case DiscriminatorKind.NEGATIVE_MATCH:
-                return verifyNegativeMatch(steps);
-            case DiscriminatorKind.STATE_TRANSITION:
-                return verifyStateTransition(steps);
-            default:
-                return {
-                    verified: false,
-                    reason: `Unknown discriminator kind "${String(declared?.kind)}"; expected one of boundary_equality, multi_record_aggregate, negative_match, state_transition.`,
-                };
-        }
-    }
-    catch {
-        // Defensive: any malformed input is treated as unverified, never a throw.
-        return { verified: false, reason: "Discriminator claim could not be verified against the scenario steps." };
-    }
-}
-// ── Anchor grounding ──
-function verifyAnchor(rawAnchor, diffText, reposWithoutDiff = []) {
-    const anchor = typeof rawAnchor === "string" ? rawAnchor.trim() : "";
-    if (anchor.length < MIN_ANCHOR_LENGTH) {
-        return {
-            verified: false,
-            reason: `changedCodeAnchor "${String(rawAnchor ?? "")}" is too short (needs >= ${MIN_ANCHOR_LENGTH} non-whitespace chars) to ground the claim in the diff.`,
-        };
-    }
-    const diff = typeof diffText === "string" ? diffText : "";
-    // A statement wrapped across diff lines carries +/- prefixes and indentation
-    // between its fragments, so a multi-line anchor can never match the raw diff
-    // text — compare whitespace-collapsed forms with diff markers stripped, or
-    // legitimate multi-line anchors are systematically false-demoted.
-    if (!diff.includes(anchor) && !normalizeForAnchorMatch(diff).includes(normalizeForAnchorMatch(anchor))) {
-        if (reposWithoutDiff.length > 0) {
-            return {
-                verified: false,
-                reason: `changedCodeAnchor "${anchor}" was not found in the available PR diffs, and no branch diff exists for ` +
-                    `${reposWithoutDiff.join(", ")} (likely checked out on the default branch), so the claim could not be checked against those changes.`,
-            };
-        }
-        return {
-            verified: false,
-            reason: `changedCodeAnchor "${anchor}" does not occur verbatim in the PR diff, so the discriminator claim is not grounded in the actual change.`,
-        };
-    }
-    return { verified: true };
-}
-/** Strip per-line diff +/- markers and collapse all whitespace runs to single
- *  spaces so anchors spanning wrapped/indented lines still match. */
-function normalizeForAnchorMatch(text) {
-    return text
-        .split("\n")
-        .map((line) => line.replace(/^[+\- ]/, ""))
-        .join(" ")
-        .replace(/\s+/g, " ")
-        .trim();
-}
-// ── Structural predicates ──
-/**
- * boundary_equality: some step carries two DISTINCT fields holding EQUAL values
- * in requestBody/queryParams (probing an on-boundary case, e.g.
- * install_date == termination_date) AND that step is either an accept-side probe
- * (2xx) or a mirrored reject-side probe (4xx with interactionType "error").
- */
-function verifyBoundaryEquality(steps) {
-    for (const step of steps) {
-        const leaves = [];
-        collectLeaves(step?.requestBody, leaves);
-        collectLeaves(step?.queryParams, leaves);
-        if (hasDistinctFieldEqualValue(leaves) && satisfiesBoundaryStatus(step)) {
-            return { verified: true };
-        }
-    }
-    return {
-        verified: false,
-        reason: "boundary_equality unverified: no step sets two distinct fields to an equal value on an accept-side (2xx) or mirrored reject-side (4xx error) request — the on-boundary case is not exercised.",
-    };
-}
-/**
- * multi_record_aggregate: >= 2 POST steps on the same (param-normalized) resource
- * path occurring before an asserting step, OR any step asserting a numeric value
- * >= 2 in expectedResponseFields/bodyMustInclude (e.g. account_count == 2).
- */
-function verifyMultiRecordAggregate(steps) {
-    const ordered = orderedSteps(steps);
-    // (b) any step asserting a numeric value >= 2.
-    for (const step of ordered) {
-        const assertions = [...toStringArray(step?.expectedResponseFields), ...toStringArray(step?.bodyMustInclude)];
-        if (assertions.some((s) => maxNumberIn(s) >= 2))
-            return { verified: true };
-    }
-    // (a) >= 2 same-path POSTs before an asserting step.
-    for (let i = 0; i < ordered.length; i++) {
-        if (!isAssertStep(ordered[i]))
-            continue;
-        const counts = new Map();
-        for (let j = 0; j < i; j++) {
-            const prior = ordered[j];
-            if ((prior?.method ?? "").toUpperCase() !== "POST")
-                continue;
-            const key = normalizePath(prior?.path ?? "");
-            const next = (counts.get(key) ?? 0) + 1;
-            counts.set(key, next);
-            if (next >= 2)
-                return { verified: true };
-        }
-    }
-    return {
-        verified: false,
-        reason: "multi_record_aggregate unverified: found neither >= 2 same-resource POST steps before an assertion nor an assertion of a numeric count >= 2 — the aggregation over multiple records is not exercised.",
-    };
-}
-/**
- * negative_match: a step asserting empty/zero/404 whose query/body carries a
- * value that is a strict substring or superstring of a value seeded in an
- * earlier step (a near-miss that must NOT match).
- */
-function verifyNegativeMatch(steps) {
-    const ordered = orderedSteps(steps);
-    for (let i = 0; i < ordered.length; i++) {
-        const step = ordered[i];
-        if (!isNegativeAssertStep(step))
-            continue;
-        const nearMissValues = [];
-        collectStringValues(step?.requestBody, nearMissValues);
-        collectStringValues(step?.queryParams, nearMissValues);
-        const seeded = [];
-        for (let j = 0; j < i; j++) {
-            collectStringValues(ordered[j]?.requestBody, seeded);
-            collectStringValues(ordered[j]?.queryParams, seeded);
-        }
-        if (nearMissValues.some((q) => seeded.some((s) => isStrictNearMiss(q, s)))) {
-            return { verified: true };
-        }
-    }
-    return {
-        verified: false,
-        reason: "negative_match unverified: no empty/zero/404 assertion queries a strict near-miss (substring or superstring) of a value seeded in an earlier step — the false-positive boundary is not probed.",
-    };
-}
-/**
- * state_transition: >= 2 mutating steps (POST/PUT/PATCH/DELETE) on the same
- * resource — same param-normalized path, or linked via chainsFrom — with a
- * DIFFERENT expectedStatusCode or interactionType.
- */
-function verifyStateTransition(steps) {
-    const mutating = steps.filter((s) => MUTATING_METHODS.has((s?.method ?? "").toUpperCase()));
-    // Same normalized path.
-    const groups = new Map();
-    for (const step of mutating) {
-        const key = normalizePath(step?.path ?? "");
-        if (!groups.has(key))
-            groups.set(key, []);
-        groups.get(key).push(step);
-    }
-    for (const group of groups.values()) {
-        if (group.length >= 2 && groupHasDivergentOutcome(group))
-            return { verified: true };
-    }
-    // Linked via chainsFrom (a mutating step chaining off another mutating step).
-    const byOrder = new Map();
-    for (const step of steps) {
-        if (typeof step?.order === "number")
-            byOrder.set(step.order, step);
-    }
-    for (const step of mutating) {
-        for (const sourceStep of toChainSourceSteps(step?.chainsFrom)) {
-            const src = byOrder.get(sourceStep);
-            if (src &&
-                MUTATING_METHODS.has((src.method ?? "").toUpperCase()) &&
-                (src.expectedStatusCode !== step.expectedStatusCode || src.interactionType !== step.interactionType)) {
-                return { verified: true };
-            }
-        }
-    }
-    return {
-        verified: false,
-        reason: "state_transition unverified: no two mutating steps on the same resource diverge in expectedStatusCode or interactionType — the state machine's differing outcomes are not exercised.",
-    };
-}
-/** Recursively collect leaf (field, value) pairs for string/number values. */
-function collectLeaves(value, out) {
-    if (value === null || value === undefined || typeof value !== "object")
-        return;
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectLeaves(item, out);
-        return;
-    }
-    for (const [key, v] of Object.entries(value)) {
-        if (v === null || v === undefined)
-            continue;
-        if (typeof v === "object") {
-            collectLeaves(v, out);
-        }
-        else if (typeof v === "string" || typeof v === "number") {
-            out.push({ field: key, value: v });
-        }
-    }
-}
-/** Recursively collect leaf string values (used for near-miss substring scans). */
-function collectStringValues(value, out) {
-    if (value === null || value === undefined)
-        return;
-    if (typeof value === "string") {
-        if (value.length > 0)
-            out.push(value);
-        return;
-    }
-    if (typeof value !== "object")
-        return;
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectStringValues(item, out);
-        return;
-    }
-    for (const v of Object.values(value))
-        collectStringValues(v, out);
-}
-/** True if two leaves have different field names but an equal (non-trivial) value. */
-function hasDistinctFieldEqualValue(leaves) {
-    for (let a = 0; a < leaves.length; a++) {
-        for (let b = a + 1; b < leaves.length; b++) {
-            const la = leaves[a];
-            const lb = leaves[b];
-            if (la.field === lb.field)
-                continue;
-            if (la.value !== lb.value)
-                continue;
-            if (typeof la.value === "string" && la.value.length === 0)
-                continue;
-            return true;
-        }
-    }
-    return false;
-}
-function satisfiesBoundaryStatus(step) {
-    const status = typeof step?.expectedStatusCode === "number" ? step.expectedStatusCode : 0;
-    const accept = status >= 200 && status < 300;
-    const reject = status >= 400 && status < 500 && step?.interactionType === "error";
-    return accept || reject;
-}
-function isAssertStep(step) {
-    return (toStringArray(step?.expectedResponseFields).length > 0 ||
-        toStringArray(step?.bodyMustInclude).length > 0 ||
-        (step?.responseBody !== null && typeof step?.responseBody === "object" && Object.keys(step.responseBody).length > 0));
-}
-function isNegativeAssertStep(step) {
-    if (step?.expectedStatusCode === 404)
-        return true;
-    const assertions = [...toStringArray(step?.expectedResponseFields), ...toStringArray(step?.bodyMustInclude)];
-    return assertsEmptyOrZero(assertions, step?.responseBody);
-}
-/**
- * True when the step asserts an empty or zero result, reading the assertion
- * strings AND `responseBody`. An EMPTY ARRAY body is itself the "no rows came
- * back" assertion, and can be the only empty-result signal a step carries.
- *
- * `{}` deliberately does NOT count: an unspecified body is filled in as `{}`
- * (ScenarioGenerationService), so it cannot be told apart from a body the agent
- * never wrote. `isAssertStep` above already reads `{}` as asserting nothing.
- */
-function assertsEmptyOrZero(strings, responseBody) {
-    if (Array.isArray(responseBody) && responseBody.length === 0)
-        return true;
-    return strings.some((raw) => {
-        const s = raw.toLowerCase();
-        if (/\bcount\b/.test(s) && /\b0\b/.test(s))
-            return true;
-        if (/(^|\D)0\s+results?\b/.test(s))
-            return true;
-        if (s.includes("empty"))
-            return true;
-        if (s.includes("no results") || s.includes("no result"))
-            return true;
-        if (s.includes("[]"))
-            return true;
-        return false;
-    });
-}
-/** Strict near-miss: one string strictly contains the other (different length). */
-function isStrictNearMiss(a, b) {
-    if (a === b)
-        return false;
-    if (Math.min(a.length, b.length) < MIN_NEAR_MISS_LENGTH)
-        return false;
-    return a.includes(b) || b.includes(a);
-}
-function groupHasDivergentOutcome(group) {
-    const statuses = new Set(group.map((s) => s?.expectedStatusCode));
-    const interactions = new Set(group.map((s) => s?.interactionType));
-    return statuses.size > 1 || interactions.size > 1;
-}
-/** Largest number appearing in a string, or -Infinity when none. */
-function maxNumberIn(text) {
-    const matches = text.match(/-?\d+(?:\.\d+)?/g);
-    if (!matches)
-        return Number.NEGATIVE_INFINITY;
-    return Math.max(...matches.map(Number));
-}
-/**
- * Normalize a path so param segments collapse: numeric ids, `{brace}` params,
- * `:colon` params and long hex/uuid segments all become `:p`.
- */
-function normalizePath(path) {
-    const pathPart = (path ?? "").split("?")[0];
-    return pathPart
-        .split("/")
-        .map((seg) => {
-        if (seg === "")
-            return seg;
-        if (/^\{.*\}$/.test(seg))
-            return ":p";
-        if (/^:.+/.test(seg))
-            return ":p";
-        if (/^\d+$/.test(seg))
-            return ":p";
-        if (/^[0-9a-fA-F-]{16,}$/.test(seg))
-            return ":p";
-        return seg.toLowerCase();
-    })
-        .join("/");
-}
-/** Steps sorted by their `order` field, falling back to array position. */
-function orderedSteps(steps) {
-    return steps
-        .map((step, index) => ({ step, index }))
-        .sort((a, b) => {
-        const ao = typeof a.step?.order === "number" ? a.step.order : a.index;
-        const bo = typeof b.step?.order === "number" ? b.step.order : b.index;
-        if (ao !== bo)
-            return ao - bo;
-        return a.index - b.index;
-    })
-        .map((entry) => entry.step);
-}
-function toStringArray(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((v) => typeof v === "string");
-}
-function toChainSourceSteps(chainsFrom) {
-    if (!chainsFrom)
-        return [];
-    const refs = Array.isArray(chainsFrom) ? chainsFrom : [chainsFrom];
-    return refs.map((r) => r?.sourceStep).filter((s) => typeof s === "number");
-}