@tea-agent/loop-agent 0.33.6 → 0.33.7-beta.0

package/dist/workflows/dag/backend-test-case-manifest.js

@@ -149,6 +149,10 @@ export const backendTestCaseManifestSchema = z
         crossCuttingTestPointCount: z.number().int().min(0),
         unclassifiedTestPointCount: z.number().int().min(0),
         duplicateBindingTestPointCount: z.number().int().min(0),
+        payloadSafeCount: z.number().int().min(0),
+        payloadUnsafeCount: z.number().int().min(0),
+        payloadUnavailableCount: z.number().int().min(0),
+        duplicateExecutionSignatureCount: z.number().int().min(0),
     }).strict().optional(),
     artifactRefs: z.object({
         caseCoverageFacts: z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/).optional() }).strict(),

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -471,7 +471,10 @@ export async function validateBackendMarkdownCases(input) {
             }
             const expectedScript = expectedBackendTestPytestScriptForMarkdownModule(relativeFile);
             const mappedScripts = extractMappedPytestScripts(testCase.body);
-            if (mappedScripts.length === 0) {
+            if (isEvidenceOnlyMarkdownCaseBody(testCase.body)) {
+                // Evidence-only meta cases intentionally declare 脚本/primary symbol as 无 and keep only assertion/cross-cutting TPs.
+            }
+            else if (mappedScripts.length === 0) {
                 findings.push(`${testCase.id} has no mapped pytest script in Automation Notes/自动化映射 (expected ${expectedScript} from module ${path.basename(relativeFile)})`);
             }
             else {
@@ -560,6 +563,24 @@ function extractMappedPytestScripts(testCaseBody) {
         .map((match) => match[1].replaceAll("\\", "/"))
         .filter((value) => !value.includes("..")));
 }
+function isEvidenceOnlyMarkdownCaseBody(testCaseBody) {
+    const automation = sectionBody(testCaseBody, CASE_SECTION_ALIASES.automationNotes);
+    if (!automation.trim())
+        return false;
+    const scriptLine = /^\s*[-*+]\s*(?:脚本|script)\s*[：:]\s*(.*)$/im.exec(automation)?.[1]?.replaceAll("`", "").trim() ??
+        "";
+    const primaryLine = /^\s*[-*+]\s*(?:primary symbol|Primary Symbol|主测试符号)\s*[：:]\s*(.*)$/im.exec(automation)?.[1]
+        ?.replaceAll("`", "")
+        .trim() ?? "";
+    const noneLike = /^(?:none|无|n\/a|not-applicable)(?:\s*[（(].*[）)])?$/i;
+    const scriptIsNone = noneLike.test(scriptLine) || scriptLine.length === 0;
+    const primaryIsNone = noneLike.test(primaryLine) || primaryLine.length === 0;
+    const hasMappedScript = extractMappedPytestScripts(testCaseBody).length > 0;
+    const hasPrimary = /\btest_[A-Za-z0-9_]+\b/.test(primaryLine);
+    const hasVariant = /(?:变体测试点|Variant Test Points)\s*[：:]\s*(?!\s*(?:无|none)\b)[^\n]*\bTP-[A-Z0-9-]+/i.test(automation);
+    const hasAssertionOrCross = /(?:场景断言测试点|Assertion Test Points|横切证据测试点|Cross-Cutting Test Points)\s*[：:]\s*(?!\s*(?:无|none)\b)[^\n]*\bTP-[A-Z0-9-]+/i.test(automation);
+    return scriptIsNone && primaryIsNone && !hasMappedScript && !hasPrimary && !hasVariant && hasAssertionOrCross;
+}
 function isSafeBackendPytestScript(script, workspaceRoot) {
     const absolute = path.resolve(workspaceRoot, script);
     const relative = path.relative(workspaceRoot, absolute).replaceAll(path.sep, "/");
@@ -621,6 +642,9 @@ export async function validateBackendMarkdownTraceability(workspaceRoot) {
         for (const testCase of splitCases(content)) {
             markdownIds.add(testCase.id);
             const scripts = extractMappedPytestScripts(testCase.body);
+            if (isEvidenceOnlyMarkdownCaseBody(testCase.body)) {
+                continue;
+            }
             if (scripts.length === 0) {
                 findings.push(`${testCase.id} has no mapped pytest script in Automation Notes/自动化映射`);
                 continue;

package/dist/workflows/dag/backend-test-module-stem.js

@@ -1,5 +1,7 @@
 import path from "node:path";
 const PRIORITY_ONLY_MODULE_STEMS = new Set(["p0", "p1", "p2"]);
+const OPAQUE_HASH_MODULE_STEM = /^[a-f][a-f0-9]{6,63}$/;
+export const BACKEND_TEST_MAX_MODULE_COUNT = 8;
 export function normalizeBackendTestModuleStemCandidate(raw) {
     return path.basename(raw)
         .replace(/\.(?:md|py)$/i, "")
@@ -11,6 +13,9 @@ export function normalizeBackendTestModuleStemCandidate(raw) {
 export function isPriorityOnlyBackendTestModuleStem(raw) {
     return PRIORITY_ONLY_MODULE_STEMS.has(normalizeBackendTestModuleStemCandidate(raw));
 }
+export function isOpaqueHashBackendTestModuleStem(raw) {
+    return OPAQUE_HASH_MODULE_STEM.test(normalizeBackendTestModuleStemCandidate(raw));
+}
 export function isPriorityOnlyBackendPytestScript(script) {
     const basename = path.posix.basename(script.replaceAll("\\", "/"));
     const match = /^test_(.+)\.py$/i.exec(basename);

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

@@ -5,6 +5,15 @@ import { z } from "zod";
 import { priorityOnlyBackendPytestScripts } from "./backend-test-module-stem.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 +36,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 +60,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 +78,94 @@ 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;
+}
+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, "/");
 }
@@ -112,9 +214,17 @@ export async function buildBackendPytestAssetInventory(workspaceRoot, mappedScri
     const pythonFiles = await walkPythonFiles(path.resolve(workspaceRoot, "testcase"));
     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 = {};
+    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]));
+    }
+    return { mappedScripts: normalizedScripts, assetFiles, inputHashes, hazardOccurrenceCounts, hazardOccurrences };
 }
 function bounded(value) {
     const normalized = value.replaceAll(/(Bearer|Basic)\s+[A-Za-z0-9._~+\/-]+/gi, "$1 [REDACTED]");
@@ -138,6 +248,10 @@ function classifyFixtureResolutionFailure(output) {
     const normalized = output.replaceAll("\\", "/");
     const paths = testcasePythonPaths(normalized);
     const generatedProviderPaths = paths.filter((item) => /testcase\/(?:helpers|factories)\//.test(item));
+    const generatedTestModulePaths = paths.filter((item) => /testcase\/(?:[A-Za-z0-9_./-]+\/)?test_[A-Za-z0-9_.-]+\.py$/i.test(item));
+    const onlyGeneratedTestcasePaths = paths.length > 0 && paths.every((item) => item.startsWith("testcase/"));
+    const mentionsProduction = /(?:apps|src|server)\/[A-Za-z0-9_./-]+\.py/i.test(normalized) ||
+        /No module named ['"](?!testcase(?:\.|['"]))/i.test(normalized);
     if (/fixture ['"][^'"]+['"] not found/i.test(normalized) && generatedProviderPaths.length > 0) {
         return {
             status: "REPAIRABLE",
@@ -146,6 +260,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",
@@ -199,6 +340,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 +370,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,
@@ -259,6 +404,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,
@@ -294,6 +441,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 +475,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 +566,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 +594,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 +663,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 +677,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 +831,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,