@tea-agent/loop-agent 0.39.0-next.9 → 0.39.1

package/dist/workflows/dag/backend-test-pytest-collection.js

@@ -3,8 +3,18 @@ import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { priorityOnlyBackendPytestScripts } from "./backend-test-module-stem.js";
+import { resolveBackendTestLayout, } from "./backend-test-layout.js";
 const SHA256 = /^[a-f0-9]{64}$/;
 const MAX_DIAGNOSTIC_CHARS = 12_000;
+/** Upper bound for assertBackendTestExecutionReadinessFresh Error.message (not collection excerpts). */
+export const MAX_READINESS_ERROR_CHARS = 2_048;
+const READINESS_EXCLUSION_CATEGORIES = [
+    "correspondence-missing",
+    "correspondence-status",
+    "payload-contract-status",
+    "scenario-param-field",
+    "other",
+];
 export const backendPytestCollectionFindingSchema = z.object({
     kind: z.string().min(1),
     classification: z.literal("test-asset-defect"),
@@ -27,6 +37,8 @@ export const backendPytestCollectionFactsSchema = z.object({
     missingMappedScripts: z.array(z.string()),
     assetFiles: z.array(z.string()),
     inputHashes: z.record(z.string(), z.string().regex(SHA256)),
+    hazardOccurrenceCounts: z.record(z.string(), z.record(z.string(), z.number().int().min(0))),
+    hazardOccurrences: z.record(z.string(), z.record(z.string(), z.array(z.string()))).optional(),
     pytestExitCode: z.number().int().nullable(),
     collectedItemCount: z.number().int().min(0),
     collectedItemIds: z.array(z.string()),
@@ -49,8 +61,14 @@ export const backendPytestCollectionFactsSchema = z.object({
         context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest fixture resolution without an attempt cannot have an exit code" });
     }
 });
+const backendTestExcludedItemSchema = z.object({
+    itemId: z.string().min(1),
+    caseId: z.string().optional(),
+    symbol: z.string().optional(),
+    reasons: z.array(z.string().min(1)).min(1),
+}).strict();
 export const backendTestExecutionReadinessSchema = z.object({
-    schemaId: z.literal("backend-test-execution-readiness-v1"),
+    schemaId: z.literal("backend-test-execution-readiness-v2"),
     status: z.enum(["PASS", "PARTIAL", "BLOCKED"]),
     collectionStatus: z.literal("PASS"),
     fixtureResolutionStatus: z.literal("PASS"),
@@ -61,9 +79,111 @@ export const backendTestExecutionReadinessSchema = z.object({
     }).strict(),
     mappedScripts: z.array(z.string()).min(1),
     collectedItemIds: z.array(z.string()),
+    eligibleItemIds: z.array(z.string()),
+    excludedItems: z.array(backendTestExcludedItemSchema),
     fixtureIssues: z.array(z.string()),
     assetHashes: z.record(z.string(), z.string().regex(SHA256)),
+    eligibilityInputHashes: z.record(z.string(), z.string().regex(SHA256)),
 }).strict();
+const REPAIR_HAZARD_PATTERNS = [
+    { label: "skip/xfail", source: "pytest\\.mark\\.(?:skip|skipif|xfail)\\b|pytest\\.(?:skip|xfail)\\s*\\(" },
+    { label: "sys.path/PYTHONPATH mutation", source: "sys\\.path\\s*\\.|PYTHONPATH" },
+    { label: "ImportError fallback", source: "except\\s+ImportError\\b" },
+    { label: "broad exception swallowing", source: "except\\s+(?:Exception|BaseException)\\b[\\s\\S]{0,160}?\\bpass\\b" },
+];
+function normalizeSourceNewlines(source) {
+    return source.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+}
+/**
+ * Normalize a hazard occurrence identity by stripping trailing Python `#` comments
+ * while preserving `#` characters inside string literals. Fail closed: if quote
+ * state is ambiguous, keep the original trimmed line rather than over-stripping.
+ */
+function normalizeHazardOccurrenceIdentity(line) {
+    const trimmed = line.trimEnd().trim();
+    if (!trimmed.includes("#"))
+        return trimmed;
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if ((inSingle || inDouble) && ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (!inDouble && ch === "'") {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (!inSingle && ch === '"') {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (!inSingle && !inDouble && ch === "#") {
+            return trimmed.slice(0, i).trimEnd();
+        }
+    }
+    // Unclosed quote or no out-of-string `#`: do not invent a comment boundary.
+    return trimmed;
+}
+/**
+ * Bare `__NNN_*` helper module names imported by a Python source snippet.
+ * Only the head token of an `import`/`from` statement is considered a module
+ * name; dotted submodules (`__551_manager_helpers.x`) collapse to the head.
+ */
+function importedBareHelperModules(source) {
+    const names = [];
+    const seen = new Set();
+    for (const match of normalizeSourceNewlines(source).matchAll(/\b(?:import|from)\s+([A-Za-z0-9_.]+)/g)) {
+        const head = match[1].split(".")[0];
+        if (/^__\d+[A-Za-z0-9_]*$/.test(head) && !seen.has(head)) {
+            seen.add(head);
+            names.push(head);
+        }
+    }
+    return names;
+}
+function listPatternOccurrences(source, patternSource, flags = "") {
+    const normalized = normalizeSourceNewlines(source);
+    const pattern = new RegExp(patternSource, flags.includes("g") ? flags : `${flags}g`);
+    const identities = [];
+    for (const match of normalized.matchAll(pattern)) {
+        const index = match.index ?? 0;
+        const lineStart = normalized.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+        const lineEnd = normalized.indexOf("\n", index);
+        const line = normalized.slice(lineStart, lineEnd === -1 ? normalized.length : lineEnd).trimEnd();
+        identities.push(normalizeHazardOccurrenceIdentity(line));
+    }
+    return identities;
+}
+function scanRepairHazardOccurrenceLists(source) {
+    const lists = {};
+    for (const rule of REPAIR_HAZARD_PATTERNS) {
+        lists[rule.label] = listPatternOccurrences(source, rule.source, rule.flags);
+    }
+    return lists;
+}
+function multisetCounts(identities) {
+    const counts = new Map();
+    for (const identity of identities) {
+        counts.set(identity, (counts.get(identity) ?? 0) + 1);
+    }
+    return counts;
+}
+function hasMultisetIncrement(initialIdentities, finalIdentities) {
+    const initial = multisetCounts(initialIdentities);
+    const final = multisetCounts(finalIdentities);
+    for (const [identity, finalCount] of final) {
+        if (finalCount > (initial.get(identity) ?? 0))
+            return true;
+    }
+    return false;
+}
 function repoRef(workspaceRoot, absolutePath) {
     return path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, "/");
 }
@@ -94,27 +214,43 @@ async function walkPythonFiles(root) {
     return results;
 }
 export async function buildBackendPytestAssetInventory(workspaceRoot, mappedScripts, options = {}) {
+    const layout = options.layout ?? resolveBackendTestLayout(undefined);
+    const scriptRoot = layout.scriptDir;
     const normalizedScripts = [...new Set(mappedScripts.map((value) => value.replaceAll("\\", "/")))].sort();
     if ((options.requireMappedScripts ?? true) && normalizedScripts.length === 0) {
         throw new Error("backend pytest collection requires mapped scripts");
     }
+    const scriptPattern = new RegExp(`^${scriptRoot.replaceAll(/[.*+?^[\]{}()|$]/g, "\\$&")}(?:/[A-Za-z0-9_.-]+)*/test_[A-Za-z0-9_.-]+\\.py$`);
+    const rootScriptPattern = new RegExp(`^${scriptRoot.replaceAll(/[.*+?^[\]{}()|$]/g, "\\$&")}/test_[A-Za-z0-9_.-]+\\.py$`);
     for (const script of normalizedScripts) {
-        if (!/^testcase(?:\/[A-Za-z0-9_.-]+)*\/test_[A-Za-z0-9_.-]+\.py$/.test(script) && !/^testcase\/test_[A-Za-z0-9_.-]+\.py$/.test(script)) {
+        if (!scriptPattern.test(script) && !rootScriptPattern.test(script)) {
             throw new Error(`unsafe backend pytest mapped script: ${script}`);
         }
         const absolute = path.resolve(workspaceRoot, script);
-        const testcaseRoot = path.resolve(workspaceRoot, "testcase");
+        const testcaseRoot = path.resolve(workspaceRoot, layout.testRoot);
         if (absolute !== testcaseRoot && !absolute.startsWith(`${testcaseRoot}${path.sep}`)) {
-            throw new Error(`backend pytest mapped script escapes testcase: ${script}`);
+            throw new Error(`backend pytest mapped script escapes test root ${layout.testRoot}: ${script}`);
         }
         await readFile(absolute);
     }
-    const pythonFiles = await walkPythonFiles(path.resolve(workspaceRoot, "testcase"));
+    const pythonFiles = await walkPythonFiles(path.resolve(workspaceRoot, layout.testRoot));
     const assetFiles = [...new Set(pythonFiles.map((file) => repoRef(workspaceRoot, file)))].sort();
     const inputHashes = {};
-    for (const file of assetFiles)
-        inputHashes[file] = sha256(await readFile(path.resolve(workspaceRoot, file)));
-    return { mappedScripts: normalizedScripts, assetFiles, inputHashes };
+    const hazardOccurrenceCounts = {};
+    const hazardOccurrences = {};
+    const scriptBareImports = {};
+    const mappedScriptSet = new Set(normalizedScripts);
+    for (const file of assetFiles) {
+        const bytes = await readFile(path.resolve(workspaceRoot, file));
+        const source = bytes.toString("utf8");
+        inputHashes[file] = sha256(bytes);
+        const lists = scanRepairHazardOccurrenceLists(source);
+        hazardOccurrences[file] = lists;
+        hazardOccurrenceCounts[file] = Object.fromEntries(Object.entries(lists).map(([label, identities]) => [label, identities.length]));
+        if (mappedScriptSet.has(file))
+            scriptBareImports[file] = importedBareHelperModules(source);
+    }
+    return { mappedScripts: normalizedScripts, assetFiles, inputHashes, hazardOccurrenceCounts, hazardOccurrences, scriptBareImports };
 }
 function bounded(value) {
     const normalized = value.replaceAll(/(Bearer|Basic)\s+[A-Za-z0-9._~+\/-]+/gi, "$1 [REDACTED]");
@@ -131,13 +267,26 @@ function collectionItems(stdout) {
             return /^testcase\//.test(line.replaceAll("\\", "/"));
         }).map((line) => line.replaceAll("\\", "/")))];
 }
-function testcasePythonPaths(output) {
-    return [...new Set((output.replaceAll("\\", "/").match(/testcase\/[A-Za-z0-9_./-]+\.py/gi) ?? []).map((item) => item.replace(/:\d+$/, "")))].sort();
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^[\]{}()|$]/g, "\\$&");
 }
-function classifyFixtureResolutionFailure(output) {
+function testcasePythonPaths(output, layout) {
+    const root = (layout ?? resolveBackendTestLayout(undefined)).testRoot;
+    const pattern = new RegExp(`(?:${escapeRegExp(root)})/[A-Za-z0-9_./-]+\\.py`, "gi");
+    return [...new Set((output.replaceAll("\\", "/").match(pattern) ?? []).map((item) => item.replace(/:\d+$/, "")))].sort();
+}
+function classifyFixtureResolutionFailure(output, layout) {
+    const resolvedLayout = layout ?? resolveBackendTestLayout(undefined);
+    const rootPrefix = `${resolvedLayout.testRoot}/`;
     const normalized = output.replaceAll("\\", "/");
-    const paths = testcasePythonPaths(normalized);
-    const generatedProviderPaths = paths.filter((item) => /testcase\/(?:helpers|factories)\//.test(item));
+    const paths = testcasePythonPaths(normalized, resolvedLayout);
+    const generatedProviderPaths = paths.filter((item) => new RegExp(`^${escapeRegExp(rootPrefix)}(?:helpers|factories)/`).test(item) ||
+        new RegExp(`^${escapeRegExp(resolvedLayout.scriptDir)}/(?:helpers|factories)/`).test(item));
+    const generatedTestModulePaths = paths.filter((item) => new RegExp(`^${escapeRegExp(resolvedLayout.scriptDir)}(?:/[A-Za-z0-9_./-]+)?/test_[A-Za-z0-9_.-]+\\.py$`, "i").test(item) ||
+        new RegExp(`^${escapeRegExp(rootPrefix)}test_[A-Za-z0-9_.-]+\\.py$`, "i").test(item));
+    const onlyGeneratedTestcasePaths = paths.length > 0 && paths.every((item) => item.startsWith(rootPrefix));
+    const mentionsProduction = /(?:apps|src|server)\/[A-Za-z0-9_./-]+\.py/i.test(normalized) ||
+        new RegExp(`No module named ['\"](?!${escapeRegExp(resolvedLayout.testRoot)}(?:\\.|['\"]))`, "i").test(normalized);
     if (/fixture ['"][^'"]+['"] not found/i.test(normalized) && generatedProviderPaths.length > 0) {
         return {
             status: "REPAIRABLE",
@@ -146,6 +295,33 @@ function classifyFixtureResolutionFailure(output) {
             repairPaths: generatedProviderPaths,
         };
     }
+    // ScopeMismatch and other setup failures fully attributed to generated test modules are
+    // writer-local and may be fixed by one bounded repair (align scopes / define fixtures).
+    if (!mentionsProduction &&
+        onlyGeneratedTestcasePaths &&
+        generatedTestModulePaths.length > 0 &&
+        /ScopeMismatch|scope mismatch|function scoped fixture|module scoped request object|module scoped fixture|ERROR at setup of/i.test(normalized)) {
+        const isScope = /ScopeMismatch|scope mismatch|function scoped fixture|module scoped request object|module scoped fixture/i.test(normalized);
+        return {
+            status: "REPAIRABLE",
+            kind: isScope ? "generated-fixture-scope-mismatch" : "generated-fixture-setup-defect",
+            detail: isScope
+                ? "generated pytest fixture scopes are inconsistent inside mapped test modules"
+                : "generated pytest fixture setup failed inside mapped test modules",
+            repairPaths: [...new Set([...generatedTestModulePaths, ...generatedProviderPaths])].sort(),
+        };
+    }
+    if (!mentionsProduction &&
+        onlyGeneratedTestcasePaths &&
+        generatedTestModulePaths.length > 0 &&
+        /fixture ['"][^'"]+['"] not found/i.test(normalized)) {
+        return {
+            status: "REPAIRABLE",
+            kind: "missing-generated-fixture",
+            detail: "mapped pytest module requests a fixture not defined in generated testcase assets",
+            repairPaths: [...new Set([...generatedTestModulePaths, ...generatedProviderPaths])].sort(),
+        };
+    }
     return {
         status: "BLOCKED",
         kind: "unresolved-fixture-dependency",
@@ -153,8 +329,68 @@ function classifyFixtureResolutionFailure(output) {
         repairPaths: paths,
     };
 }
-function classifyCollectionFailure(output) {
+/**
+ * Generated-local bare helper module signatures found in the bound pytest
+ * asset inventory. A file such as `testcase/__551_manager_helpers.py` in the
+ * test root/script dir is generated-local: when collection reports
+ * `No module named '__551_manager_helpers'`, the defect can be precisely
+ * attributed to the generated mapped script instead of a missing third-party
+ * package.
+ */
+function generatedLocalBareHelperNames(inventory) {
+    if (!inventory)
+        return [];
+    const names = [];
+    for (const file of inventory.assetFiles) {
+        const stem = path.posix.basename(file).replace(/\.py$/, "");
+        if (/^__\d+[A-Za-z0-9_]*$/.test(stem))
+            names.push(stem);
+    }
+    return [...new Set(names)];
+}
+function classifyCollectionFailure(output, evidence) {
     const normalized = output.replaceAll("\\", "/");
+    const helperNames = generatedLocalBareHelperNames(evidence?.inventory);
+    const helperByLower = new Map(helperNames.map((name) => [name.toLowerCase(), name]));
+    // A bare `__NNN_...` module import that collection cannot find is only a
+    // candidate generated-local helper signature. REPAIRABLE requires two
+    // deterministic pieces of evidence: (1) a helper asset of the same name in
+    // the bound inventory, and (2) at least one mapped generated script whose
+    // source truly imports that bare module. Without both — or when attribution
+    // is impossible — fail closed as BLOCKED so an un-attributable dependency
+    // error is never widened into a repair. Genuine third-party modules (no
+    // `__NNN_` signature) stay BLOCKED below.
+    const missingModule = /No module named ['\"]([^'\"]+)['\"]/i.exec(normalized)?.[1];
+    if (missingModule && /^__\d+[A-Za-z0-9_]*$/.test(missingModule)) {
+        const helperAsset = helperByLower.get(missingModule.toLowerCase());
+        const inventory = evidence?.inventory;
+        const scriptBareImports = inventory?.scriptBareImports ?? {};
+        const missingLower = missingModule.toLowerCase();
+        const importedByMappedScript = inventory
+            ? inventory.mappedScripts.some((script) => (scriptBareImports[script] ?? []).some((name) => name.toLowerCase() === missingLower))
+            : false;
+        if (helperAsset && importedByMappedScript && inventory) {
+            const repairPaths = [...new Set([
+                    ...(helperAsset
+                        ? inventory.assetFiles.filter((file) => path.posix.basename(file).replace(/\.py$/, "") === helperAsset)
+                        : []),
+                    ...inventory.mappedScripts,
+                ])].sort();
+            return {
+                status: "REPAIRABLE",
+                kind: "missing-generated-local-helper",
+                detail: `generated testcase asset imports missing bare generated-local helper module ${missingModule}; inline the helper or remove the generated shared dependency`,
+                repairPaths,
+            };
+        }
+        return {
+            status: "BLOCKED",
+            kind: "missing-generated-local-helper-without-evidence",
+            detail: helperAsset
+                ? `missing bare generated-local helper module ${missingModule} has a name match but no mapped generated script imports it (no precise generated-local attribution)`
+                : `missing bare __NNN_* module ${missingModule} has no generated-local helper asset in the bound inventory (cannot be precisely attributed)`,
+        };
+    }
     const blockedPatterns = [
         [/No module named ['\"](?!testcase(?:\.|['\"]))/i, "missing-third-party-module"],
         [/pytest(?:_|-)plugin|pluggy|unknown hook|unrecognized arguments/i, "pytest-plugin-or-config"],
@@ -199,6 +435,8 @@ export function assessBackendPytestCollection(input) {
             missingMappedScripts: [],
             assetFiles: input.inventory.assetFiles,
             inputHashes: input.inventory.inputHashes,
+            hazardOccurrenceCounts: input.inventory.hazardOccurrenceCounts,
+            hazardOccurrences: input.inventory.hazardOccurrences,
             pytestExitCode: input.exitCode,
             collectedItemCount: items.length,
             collectedItemIds: items,
@@ -227,6 +465,8 @@ export function assessBackendPytestCollection(input) {
             missingMappedScripts: [],
             assetFiles: input.inventory.assetFiles,
             inputHashes: input.inventory.inputHashes,
+            hazardOccurrenceCounts: input.inventory.hazardOccurrenceCounts,
+            hazardOccurrences: input.inventory.hazardOccurrences,
             pytestExitCode: input.exitCode,
             collectedItemCount: items.length,
             collectedItemIds: items,
@@ -242,7 +482,7 @@ export function assessBackendPytestCollection(input) {
             fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
         });
     }
-    const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`);
+    const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`, { layout: input.layout, inventory: input.inventory });
     return backendPytestCollectionFactsSchema.parse({
         schemaId: "backend-test-pytest-collection-v3",
         phase: input.phase,
@@ -253,12 +493,16 @@ export function assessBackendPytestCollection(input) {
         fixtureResolutionAttempted: false,
         fixtureResolutionStatus: "NOT_RUN",
         fixtureResolutionExitCode: null,
-        repairPaths: testcasePythonPaths(`${input.stdout}\n${input.stderr}`),
+        repairPaths: classification.repairPaths && classification.repairPaths.length > 0
+            ? classification.repairPaths
+            : testcasePythonPaths(`${input.stdout}\n${input.stderr}`),
         mappedScripts: input.inventory.mappedScripts,
         existingMappedScripts: input.inventory.mappedScripts,
         missingMappedScripts: [],
         assetFiles: input.inventory.assetFiles,
         inputHashes: input.inventory.inputHashes,
+        hazardOccurrenceCounts: input.inventory.hazardOccurrenceCounts,
+        hazardOccurrences: input.inventory.hazardOccurrences,
         pytestExitCode: input.exitCode,
         collectedItemCount: items.length,
         collectedItemIds: items,
@@ -294,6 +538,8 @@ export function assessPriorityOnlyBackendPytestModules(input) {
         missingMappedScripts: [],
         assetFiles: input.inventory.assetFiles,
         inputHashes: input.inventory.inputHashes,
+        hazardOccurrenceCounts: input.inventory.hazardOccurrenceCounts,
+        hazardOccurrences: input.inventory.hazardOccurrences,
         pytestExitCode: null,
         collectedItemCount: 0,
         collectedItemIds: [],
@@ -326,6 +572,8 @@ export function assessMissingBackendPytestScripts(input) {
         missingMappedScripts: [...input.missingMappedScripts],
         assetFiles: [...input.assetFiles],
         inputHashes: input.inputHashes,
+        hazardOccurrenceCounts: input.hazardOccurrenceCounts ?? Object.fromEntries(input.assetFiles.map((file) => [file, {}])),
+        hazardOccurrences: input.hazardOccurrences ?? Object.fromEntries(input.assetFiles.map((file) => [file, {}])),
         pytestExitCode: null,
         collectedItemCount: 0,
         collectedItemIds: [],
@@ -415,17 +663,21 @@ async function assertBackendPytestRepairSafety(workspaceRoot, initial, final) {
     if (JSON.stringify(initial.mappedScripts) !== JSON.stringify(final.mappedScripts)) {
         throw new Error("backend pytest repair changed mapped script scope");
     }
-    const forbidden = [
-        [/pytest\.mark\.(?:skip|skipif|xfail)\b|pytest\.(?:skip|xfail)\s*\(/, "skip/xfail"],
-        [/sys\.path\s*\.|PYTHONPATH/, "sys.path/PYTHONPATH mutation"],
-        [/except\s+ImportError\b/, "ImportError fallback"],
-        [/except\s+(?:Exception|BaseException)\b[\s\S]{0,160}?\bpass\b/, "broad exception swallowing"],
-    ];
     for (const file of final.assetFiles) {
         const source = await readFile(path.resolve(workspaceRoot, file), "utf8");
-        for (const [pattern, label] of forbidden) {
-            if (pattern.test(source))
-                throw new Error(`backend pytest repair safety blocked ${label}: ${file}`);
+        const liveHash = sha256(source);
+        if (final.inputHashes[file] && final.inputHashes[file] !== liveHash) {
+            throw new Error(`backend pytest collection hash drift: ${file}`);
+        }
+        if (initial.inputHashes[file] === final.inputHashes[file])
+            continue;
+        const finalLists = scanRepairHazardOccurrenceLists(source);
+        for (const rule of REPAIR_HAZARD_PATTERNS) {
+            const baseline = initial.hazardOccurrences?.[file]?.[rule.label] ?? [];
+            const finalIdentities = finalLists[rule.label] ?? [];
+            if (hasMultisetIncrement(baseline, finalIdentities)) {
+                throw new Error(`backend pytest repair safety blocked ${rule.label}: ${file}`);
+            }
         }
     }
 }
@@ -439,23 +691,65 @@ function assertSameInventory(expected, actual) {
             throw new Error(`backend pytest collection hash drift: ${file}`);
     }
 }
+export function buildBackendTestItemEligibility(collectedItemIds, input) {
+    const eligibleItemIds = [];
+    const excludedItems = [];
+    for (const itemId of collectedItemIds) {
+        const segments = itemId.split("::");
+        const symbolSegment = [...segments].reverse().find((segment) => /^test_/.test(segment));
+        const symbol = symbolSegment?.replace(/\[.*$/, "");
+        const parameterTokens = orderedUnique((itemId.match(/TP-[A-Z0-9-]+/g) ?? []));
+        const mapping = input.correspondenceEntries.find((entry) => symbol && (entry.declaredPrimarySymbol === symbol || entry.pytestSymbols.includes(symbol)));
+        const reasons = [];
+        if (!mapping)
+            reasons.push("no exact Markdown Case/primary-symbol correspondence");
+        if (mapping && mapping.status !== "EXACT_1_TO_1")
+            reasons.push(`correspondence status is ${mapping.status}`);
+        if (mapping && mapping.payloadAssessment.status !== "SAFE")
+            reasons.push(`payload contract status is ${mapping.payloadAssessment.status}`);
+        const scenarioEntries = mapping?.caseId ? input.scenarioEntries.filter((entry) => entry.caseId === mapping.caseId) : [];
+        const relevantScenarioEntries = parameterTokens.length > 0
+            ? scenarioEntries.filter((entry) => parameterTokens.includes(entry.tpId))
+            : scenarioEntries;
+        const payloadPaths = orderedUnique([
+            ...(mapping?.payloadAssessment.requiredPaths ?? []),
+            ...(mapping?.payloadAssessment.allowedPaths ?? []),
+            ...(mapping?.payloadAssessment.observedPaths ?? []),
+        ]).map((item) => item.toLowerCase());
+        for (const entry of relevantScenarioEntries) {
+            // Field names heuristically inferred only from a TP token (for example
+            // TP-HEALTH-HTTP-200 -> hEALTH) are not execution-safety evidence. Exclude
+            // only when the field is also present in the deterministic payload contract
+            // or observed Python payload shape.
+            const normalizedField = entry.field?.toLowerCase();
+            const fieldIsPayloadBound = Boolean(normalizedField && payloadPaths.some((item) => item === normalizedField || item.endsWith(`.${normalizedField}`)));
+            if (fieldIsPayloadBound && entry.status !== "MATCH")
+                reasons.push(`scenario-param ${entry.tpId} field ${entry.field} is ${entry.status}`);
+        }
+        if (reasons.length === 0)
+            eligibleItemIds.push(itemId);
+        else
+            excludedItems.push({ itemId, ...(mapping?.caseId ? { caseId: mapping.caseId } : {}), ...(symbol ? { symbol } : {}), reasons: orderedUnique(reasons) });
+    }
+    return { eligibleItemIds, excludedItems };
+}
+function orderedUnique(values) {
+    return [...new Set(values)];
+}
 export async function materializeBackendTestExecutionReadiness(input) {
     if (input.effective.phase !== "effective" || input.effective.status !== "PASS" || input.effective.fixtureResolutionStatus !== "PASS") {
         throw new Error("backend-test execution readiness requires effective collection and fixture-resolution PASS");
     }
     const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.effective.mappedScripts);
-    const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
-    if (priorityOnly.length > 0) {
-        throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
-    }
     assertSameInventory(input.effective, current);
-    const status = input.scenarioParamStatus === "FAIL"
+    const eligibility = input.eligibility ?? { eligibleItemIds: input.effective.collectedItemIds, excludedItems: [] };
+    const status = eligibility.eligibleItemIds.length === 0
         ? "BLOCKED"
-        : input.scenarioParamStatus === "PASS"
+        : input.scenarioParamStatus === "PASS" && eligibility.excludedItems.length === 0
             ? "PASS"
             : "PARTIAL";
     const readiness = backendTestExecutionReadinessSchema.parse({
-        schemaId: "backend-test-execution-readiness-v1",
+        schemaId: "backend-test-execution-readiness-v2",
         status,
         collectionStatus: "PASS",
         fixtureResolutionStatus: "PASS",
@@ -466,8 +760,11 @@ export async function materializeBackendTestExecutionReadiness(input) {
         },
         mappedScripts: input.effective.mappedScripts,
         collectedItemIds: input.effective.collectedItemIds,
+        eligibleItemIds: eligibility.eligibleItemIds,
+        excludedItems: eligibility.excludedItems,
         fixtureIssues: input.effective.findings.filter((item) => /fixture/i.test(item.kind)).map((item) => item.detail),
         assetHashes: input.effective.inputHashes,
+        eligibilityInputHashes: input.eligibilityInputHashes ?? {},
     });
     const contractsDir = path.join(input.runDir, "contracts");
     await mkdir(contractsDir, { recursive: true });
@@ -477,27 +774,145 @@ export async function materializeBackendTestExecutionReadiness(input) {
 export async function readBackendTestExecutionReadiness(filePath) {
     return backendTestExecutionReadinessSchema.parse(JSON.parse(await readFile(filePath, "utf8")));
 }
+function formatReadinessCounts(readiness) {
+    return `mapped=${readiness.mappedScripts.length} collected=${readiness.collectedItemIds.length} eligible=${readiness.eligibleItemIds.length} excluded=${readiness.excludedItems.length}`;
+}
+export function classifyExclusionReason(reason) {
+    if (reason === "no exact Markdown Case/primary-symbol correspondence")
+        return "correspondence-missing";
+    if (/^correspondence status is\b/.test(reason))
+        return "correspondence-status";
+    if (/^payload contract status is\b/.test(reason))
+        return "payload-contract-status";
+    if (/^scenario-param\b.*\bfield\b/.test(reason))
+        return "scenario-param-field";
+    return "other";
+}
+/** Fixed-category tally for readiness Error messages — never echoes raw reason text. */
+function tallyExclusionReasonCategories(excludedItems) {
+    const counts = new Map();
+    for (const item of excludedItems) {
+        for (const reason of item.reasons) {
+            const category = classifyExclusionReason(reason);
+            counts.set(category, (counts.get(category) ?? 0) + 1);
+        }
+    }
+    const parts = READINESS_EXCLUSION_CATEGORIES
+        .filter((category) => (counts.get(category) ?? 0) > 0)
+        .map((category) => `${category}=${counts.get(category)}`);
+    return parts.length > 0 ? parts.join("; ") : "none";
+}
+const READINESS_ERROR_TRUNCATION_SUFFIX = "...[truncated]";
+export function boundReadinessErrorMessage(message) {
+    if (message.length <= MAX_READINESS_ERROR_CHARS)
+        return message;
+    // Truncate to leave room for the suffix so the final message never exceeds
+    // MAX_READINESS_ERROR_CHARS. Never append beyond the declared limit.
+    const limit = MAX_READINESS_ERROR_CHARS - READINESS_ERROR_TRUNCATION_SUFFIX.length;
+    return `${message.slice(0, Math.max(0, limit))}${READINESS_ERROR_TRUNCATION_SUFFIX}`;
+}
+function throwReadinessError(message) {
+    throw new Error(boundReadinessErrorMessage(message));
+}
+function firstInventoryDeltaPath(expectedHashes, actualHashes) {
+    const expectedFiles = Object.keys(expectedHashes).sort();
+    const actualFiles = Object.keys(actualHashes).sort();
+    const actualSet = new Set(actualFiles);
+    const expectedSet = new Set(expectedFiles);
+    const onlyExpected = expectedFiles.find((file) => !actualSet.has(file));
+    if (onlyExpected)
+        return onlyExpected;
+    return actualFiles.find((file) => !expectedSet.has(file));
+}
+async function firstUnreadableAssetPath(workspaceRoot, readiness) {
+    const candidatePaths = [...new Set([
+            ...Object.keys(readiness.assetHashes),
+            ...readiness.mappedScripts,
+        ])].sort();
+    for (const relativePath of candidatePaths) {
+        try {
+            await readFile(path.resolve(workspaceRoot, relativePath));
+        }
+        catch {
+            return relativePath;
+        }
+    }
+    return undefined;
+}
 export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, readiness) {
     if (!["PASS", "PARTIAL"].includes(readiness.status)) {
-        throw new Error(`backend pytest execution readiness is ${readiness.status}`);
+        const counts = formatReadinessCounts(readiness);
+        const reasonTally = readiness.eligibleItemIds.length === 0 && readiness.excludedItems.length > 0
+            ? `; exclusionReasons: ${tallyExclusionReasonCategories(readiness.excludedItems)}`
+            : "";
+        throwReadinessError(`backend pytest execution readiness is ${readiness.status}: ${counts}${reasonTally}`);
+    }
+    if (readiness.eligibleItemIds.length === 0) {
+        throwReadinessError(`backend pytest execution readiness authorizes zero eligible items: ${tallyExclusionReasonCategories(readiness.excludedItems)}`);
+    }
+    const missingEligibleCount = readiness.eligibleItemIds.filter((itemId) => !readiness.collectedItemIds.includes(itemId)).length;
+    if (missingEligibleCount > 0) {
+        // Do not replay raw pytest item IDs: they may contain TP-*, field, payload,
+        // secret-like or parameter markers. Report only the fixed category + count.
+        throwReadinessError(`backend pytest readiness has ${missingEligibleCount} eligible item(s) absent from collected items: ${formatReadinessCounts(readiness)}`);
+    }
+    const unreadableAsset = await firstUnreadableAssetPath(workspaceRoot, readiness);
+    if (unreadableAsset) {
+        throwReadinessError(`backend pytest collection asset inventory drift: firstPath=${unreadableAsset}`);
+    }
+    let current;
+    try {
+        current = await buildBackendPytestAssetInventory(workspaceRoot, readiness.mappedScripts);
+    }
+    catch {
+        const fallbackPath = [...readiness.mappedScripts].sort()[0] ?? Object.keys(readiness.assetHashes).sort()[0] ?? "unknown";
+        throwReadinessError(`backend pytest collection asset inventory drift: firstPath=${fallbackPath}`);
     }
-    const current = await buildBackendPytestAssetInventory(workspaceRoot, readiness.mappedScripts);
     const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
     if (priorityOnly.length > 0) {
-        throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
+        throwReadinessError(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
+    }
+    const expectedHashes = readiness.assetHashes;
+    const inventoryDelta = firstInventoryDeltaPath(expectedHashes, current.inputHashes);
+    if (inventoryDelta) {
+        throwReadinessError(`backend pytest collection asset inventory drift: firstPath=${inventoryDelta}`);
+    }
+    for (const file of Object.keys(expectedHashes).sort()) {
+        if (expectedHashes[file] !== current.inputHashes[file]) {
+            throwReadinessError(`backend pytest collection hash drift: ${file}`);
+        }
+    }
+    for (const relativePath of Object.keys(readiness.eligibilityInputHashes).sort()) {
+        const expectedHash = readiness.eligibilityInputHashes[relativePath];
+        const absolute = path.resolve(workspaceRoot, relativePath);
+        let actualHash;
+        try {
+            actualHash = sha256(await readFile(absolute));
+        }
+        catch {
+            throwReadinessError(`backend pytest eligibility input hash drift: firstPath=${relativePath}`);
+        }
+        if (actualHash !== expectedHash) {
+            throwReadinessError(`backend pytest eligibility input hash drift: ${relativePath}`);
+        }
     }
-    assertSameInventory({ mappedScripts: readiness.mappedScripts, assetFiles: Object.keys(readiness.assetHashes), inputHashes: readiness.assetHashes }, current);
 }
 export async function assertBackendPytestCollectionFresh(workspaceRoot, effective) {
     if (effective.phase !== "effective" || effective.status !== "PASS") {
         throw new Error("backend pytest execution requires effective collection PASS facts");
     }
     const current = await buildBackendPytestAssetInventory(workspaceRoot, effective.mappedScripts);
+    const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
+    if (priorityOnly.length > 0)
+        throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
     assertSameInventory(effective, current);
 }
 export async function materializeEffectiveBackendPytestCollection(input) {
     if (input.initial.status === "PASS") {
         const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.initial.mappedScripts);
+        const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
+        if (priorityOnly.length > 0)
+            throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
         assertSameInventory(input.initial, current);
         return backendPytestCollectionFactsSchema.parse({
             ...input.initial,
@@ -513,6 +928,9 @@ export async function materializeEffectiveBackendPytestCollection(input) {
         throw new Error("backend pytest collection still fails after bounded repair");
     await assertBackendPytestRepairSafety(input.workspaceRoot, input.initial, input.final);
     const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.final.mappedScripts);
+    const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
+    if (priorityOnly.length > 0)
+        throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
     assertSameInventory(input.final, current);
     return backendPytestCollectionFactsSchema.parse({
         ...input.final,