@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,859 @@
+import { createHash } from "node:crypto";
+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"),
+    repairability: z.enum(["repairable", "blocked"]),
+    detail: z.string().min(1),
+}).strict();
+export const backendPytestCollectionFactsSchema = z.object({
+    schemaId: z.literal("backend-test-pytest-collection-v3"),
+    phase: z.enum(["initial", "final", "effective"]),
+    status: z.enum(["PASS", "REPAIRABLE", "BLOCKED"]),
+    repairEligible: z.boolean(),
+    repairAttempt: z.number().int().min(0).max(1),
+    collectionAttempted: z.boolean(),
+    fixtureResolutionAttempted: z.boolean(),
+    fixtureResolutionStatus: z.enum(["NOT_RUN", "PASS", "REPAIRABLE", "BLOCKED"]),
+    fixtureResolutionExitCode: z.number().int().nullable(),
+    repairPaths: z.array(z.string()),
+    mappedScripts: z.array(z.string()).min(1),
+    existingMappedScripts: z.array(z.string()),
+    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()),
+    findings: z.array(backendPytestCollectionFindingSchema),
+    stdoutExcerpt: z.string(),
+    stderrExcerpt: z.string(),
+    fixtureStdoutExcerpt: z.string(),
+    fixtureStderrExcerpt: z.string(),
+    collectionSource: z.enum(["initial", "final"]).optional(),
+}).strict().superRefine((facts, context) => {
+    if (facts.status === "PASS") {
+        if (!facts.collectionAttempted || facts.pytestExitCode !== 0 || !facts.fixtureResolutionAttempted || facts.fixtureResolutionStatus !== "PASS" || facts.fixtureResolutionExitCode !== 0 || facts.missingMappedScripts.length > 0 || facts.assetFiles.length === 0) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest collection PASS requires collection and fixture-resolution PASS, complete mapped scripts and bound assets" });
+        }
+    }
+    if (!facts.collectionAttempted && facts.pytestExitCode !== null) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest collection without an attempt cannot have an exit code" });
+    }
+    if (!facts.fixtureResolutionAttempted && facts.fixtureResolutionExitCode !== null) {
+        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-v2"),
+    status: z.enum(["PASS", "PARTIAL", "BLOCKED"]),
+    collectionStatus: z.literal("PASS"),
+    fixtureResolutionStatus: z.literal("PASS"),
+    scenarioParamStatus: z.enum(["PASS", "PARTIAL", "FAIL", "UNAVAILABLE"]),
+    repairAttempts: z.object({
+        collection: z.number().int().min(0).max(1),
+        scenarioParam: z.number().int().min(0).max(1),
+    }).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, "/");
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+async function walkPythonFiles(root) {
+    const results = [];
+    const visit = async (current) => {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === "__pycache__" || entry.name === ".pytest_cache")
+                continue;
+            const absolute = path.join(current, entry.name);
+            if (entry.isDirectory())
+                await visit(absolute);
+            else if (entry.isFile() && entry.name.endsWith(".py"))
+                results.push(absolute);
+        }
+    };
+    await visit(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 (!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, layout.testRoot);
+        if (absolute !== testcaseRoot && !absolute.startsWith(`${testcaseRoot}${path.sep}`)) {
+            throw new Error(`backend pytest mapped script escapes test root ${layout.testRoot}: ${script}`);
+        }
+        await readFile(absolute);
+    }
+    const pythonFiles = await walkPythonFiles(path.resolve(workspaceRoot, layout.testRoot));
+    const assetFiles = [...new Set(pythonFiles.map((file) => repoRef(workspaceRoot, file)))].sort();
+    const 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]");
+    return normalized.length <= MAX_DIAGNOSTIC_CHARS
+        ? normalized
+        : `${normalized.slice(0, MAX_DIAGNOSTIC_CHARS)}\n...[truncated]`;
+}
+function collectionItems(stdout) {
+    return [...new Set(stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => {
+            if (!line.includes("::"))
+                return false;
+            if (/^(ERROR|FAILED|E\s+)/.test(line))
+                return false;
+            return /^testcase\//.test(line.replaceAll("\\", "/"));
+        }).map((line) => line.replaceAll("\\", "/")))];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^[\]{}()|$]/g, "\\$&");
+}
+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, 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",
+            kind: "missing-generated-fixture",
+            detail: "generated pytest fixture dependency or plugin registration is incomplete",
+            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",
+        detail: "fixture resolution failed without a safely attributable generated provider",
+        repairPaths: paths,
+    };
+}
+function classifyCollectionFailure(output) {
+    const normalized = output.replaceAll("\\", "/");
+    const blockedPatterns = [
+        [/No module named ['\"](?!testcase(?:\.|['\"]))/i, "missing-third-party-module"],
+        [/pytest(?:_|-)plugin|pluggy|unknown hook|unrecognized arguments/i, "pytest-plugin-or-config"],
+        [/(?:apps|src|server|api)\/[A-Za-z0-9_./-]+\.py/i, "production-module-import"],
+        [/permission denied|access is denied|timed? out|not recognized as an internal|no such file or directory.*python/i, "environment-or-spawn"],
+    ];
+    for (const [pattern, kind] of blockedPatterns) {
+        if (pattern.test(normalized))
+            return { status: "BLOCKED", kind, detail: "collection failure is outside generated testcase asset repair scope" };
+    }
+    if (/ImportError:\s*cannot import name/i.test(normalized) && /(?:from ['\"]testcase\.|\/testcase\/)/i.test(normalized)) {
+        return { status: "REPAIRABLE", kind: "missing-local-import-symbol", detail: "generated testcase asset imports a missing local symbol" };
+    }
+    if (/ModuleNotFoundError:\s*No module named ['\"]testcase(?:\.|['\"])/i.test(normalized)) {
+        return { status: "REPAIRABLE", kind: "missing-local-testcase-module", detail: "generated testcase asset imports a missing local testcase module" };
+    }
+    if (/partially initialized module ['\"]testcase\.|circular import/i.test(normalized)) {
+        return { status: "REPAIRABLE", kind: "local-circular-import", detail: "generated testcase assets contain a local circular import" };
+    }
+    if (/SyntaxError|IndentationError|TabError/i.test(normalized) && /testcase\/[A-Za-z0-9_./-]+\.py/i.test(normalized)) {
+        return { status: "REPAIRABLE", kind: "generated-python-syntax", detail: "generated testcase Python source is not syntactically collectable" };
+    }
+    return { status: "BLOCKED", kind: "unclassified-collection-error", detail: "collection failure cannot be safely attributed to generated testcase assets" };
+}
+export function assessBackendPytestCollection(input) {
+    const items = collectionItems(input.stdout);
+    const fixtureResolution = input.fixtureResolution ?? { exitCode: 0, stdout: "fixture resolution assumed by direct assessor", stderr: "" };
+    if (input.exitCode === 0 && fixtureResolution.exitCode === 0) {
+        return backendPytestCollectionFactsSchema.parse({
+            schemaId: "backend-test-pytest-collection-v3",
+            phase: input.phase,
+            status: "PASS",
+            repairEligible: false,
+            repairAttempt: input.phase === "final" ? 1 : 0,
+            collectionAttempted: true,
+            fixtureResolutionAttempted: true,
+            fixtureResolutionStatus: "PASS",
+            fixtureResolutionExitCode: 0,
+            repairPaths: [],
+            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,
+            findings: [],
+            stdoutExcerpt: bounded(input.stdout),
+            stderrExcerpt: bounded(input.stderr),
+            fixtureStdoutExcerpt: bounded(fixtureResolution.stdout),
+            fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
+        });
+    }
+    if (input.exitCode === 0) {
+        const classification = classifyFixtureResolutionFailure(`${fixtureResolution.stdout}\n${fixtureResolution.stderr}`);
+        return backendPytestCollectionFactsSchema.parse({
+            schemaId: "backend-test-pytest-collection-v3",
+            phase: input.phase,
+            status: classification.status,
+            repairEligible: input.phase === "initial" && classification.status === "REPAIRABLE",
+            repairAttempt: input.phase === "final" ? 1 : 0,
+            collectionAttempted: true,
+            fixtureResolutionAttempted: true,
+            fixtureResolutionStatus: classification.status,
+            fixtureResolutionExitCode: fixtureResolution.exitCode,
+            repairPaths: classification.repairPaths,
+            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,
+            findings: [{
+                    kind: classification.kind,
+                    classification: "test-asset-defect",
+                    repairability: classification.status === "REPAIRABLE" ? "repairable" : "blocked",
+                    detail: classification.detail,
+                }],
+            stdoutExcerpt: bounded(input.stdout),
+            stderrExcerpt: bounded(input.stderr),
+            fixtureStdoutExcerpt: bounded(fixtureResolution.stdout),
+            fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
+        });
+    }
+    const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`);
+    return backendPytestCollectionFactsSchema.parse({
+        schemaId: "backend-test-pytest-collection-v3",
+        phase: input.phase,
+        status: classification.status,
+        repairEligible: input.phase === "initial" && classification.status === "REPAIRABLE",
+        repairAttempt: input.phase === "final" ? 1 : 0,
+        collectionAttempted: true,
+        fixtureResolutionAttempted: false,
+        fixtureResolutionStatus: "NOT_RUN",
+        fixtureResolutionExitCode: null,
+        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,
+        findings: [{
+                kind: classification.kind,
+                classification: "test-asset-defect",
+                repairability: classification.status === "REPAIRABLE" ? "repairable" : "blocked",
+                detail: classification.detail,
+            }],
+        stdoutExcerpt: bounded(input.stdout),
+        stderrExcerpt: bounded(input.stderr),
+        fixtureStdoutExcerpt: "",
+        fixtureStderrExcerpt: "",
+    });
+}
+export function assessPriorityOnlyBackendPytestModules(input) {
+    const invalidScripts = priorityOnlyBackendPytestScripts(input.inventory.assetFiles);
+    if (invalidScripts.length === 0)
+        return undefined;
+    return backendPytestCollectionFactsSchema.parse({
+        schemaId: "backend-test-pytest-collection-v3",
+        phase: input.phase,
+        status: "BLOCKED",
+        repairEligible: false,
+        repairAttempt: input.phase === "final" ? 1 : 0,
+        collectionAttempted: false,
+        fixtureResolutionAttempted: false,
+        fixtureResolutionStatus: "NOT_RUN",
+        fixtureResolutionExitCode: null,
+        repairPaths: [],
+        mappedScripts: [...input.mappedScripts],
+        existingMappedScripts: input.inventory.mappedScripts,
+        missingMappedScripts: [],
+        assetFiles: input.inventory.assetFiles,
+        inputHashes: input.inventory.inputHashes,
+        hazardOccurrenceCounts: input.inventory.hazardOccurrenceCounts,
+        hazardOccurrences: input.inventory.hazardOccurrences,
+        pytestExitCode: null,
+        collectedItemCount: 0,
+        collectedItemIds: [],
+        findings: invalidScripts.map((script) => ({
+            kind: "priority-only-pytest-module",
+            classification: "test-asset-defect",
+            repairability: "blocked",
+            detail: `priority-only pytest module is forbidden and cannot be auto-renamed: ${script}`,
+        })),
+        stdoutExcerpt: "",
+        stderrExcerpt: "",
+        fixtureStdoutExcerpt: "",
+        fixtureStderrExcerpt: "",
+    });
+}
+export function assessMissingBackendPytestScripts(input) {
+    return backendPytestCollectionFactsSchema.parse({
+        schemaId: "backend-test-pytest-collection-v3",
+        phase: "initial",
+        status: "REPAIRABLE",
+        repairEligible: true,
+        repairAttempt: 0,
+        collectionAttempted: false,
+        fixtureResolutionAttempted: false,
+        fixtureResolutionStatus: "NOT_RUN",
+        fixtureResolutionExitCode: null,
+        repairPaths: [...input.missingMappedScripts],
+        mappedScripts: [...input.mappedScripts],
+        existingMappedScripts: [...input.existingMappedScripts],
+        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: [],
+        findings: input.missingMappedScripts.map((script) => ({
+            kind: "missing-mapped-pytest-script",
+            classification: "test-asset-defect",
+            repairability: "repairable",
+            detail: `Markdown-mapped generated pytest script is missing: ${script}`,
+        })),
+        stdoutExcerpt: "",
+        stderrExcerpt: "",
+        fixtureStdoutExcerpt: "",
+        fixtureStderrExcerpt: "",
+    });
+}
+export function renderBackendPytestCollectionReport(facts) {
+    return [
+        `# Backend pytest Collection ${facts.phase}`,
+        "",
+        "## Status",
+        "",
+        facts.status,
+        "",
+        `- Repair eligible: ${facts.repairEligible}`,
+        `- Repair attempt: ${facts.repairAttempt}`,
+        `- Collection attempted: ${facts.collectionAttempted}`,
+        `- Pytest exit code: ${facts.pytestExitCode ?? "not-run"}`,
+        `- Fixture resolution attempted: ${facts.fixtureResolutionAttempted}`,
+        `- Fixture resolution status: ${facts.fixtureResolutionStatus}`,
+        `- Fixture resolution exit code: ${facts.fixtureResolutionExitCode ?? "not-run"}`,
+        `- Repair paths: ${facts.repairPaths.join(", ") || "none"}`,
+        `- Mapped scripts: ${facts.mappedScripts.length}`,
+        `- Existing mapped scripts: ${facts.existingMappedScripts.length}`,
+        `- Missing mapped scripts: ${facts.missingMappedScripts.length}`,
+        `- Bound Python assets: ${facts.assetFiles.length}`,
+        `- Collected items: ${facts.collectedItemCount}`,
+        "",
+        "## Findings",
+        "",
+        ...(facts.findings.length ? facts.findings.map((finding) => `- ${finding.kind}: ${finding.detail}`) : ["- None"]),
+        "",
+        "## Collected Items",
+        "",
+        ...(facts.collectedItemIds.length ? facts.collectedItemIds.map((item) => `- ${item}`) : ["- None"]),
+        "",
+        "## Bounded stdout",
+        "",
+        "```text",
+        facts.stdoutExcerpt,
+        "```",
+        "",
+        "## Bounded stderr",
+        "",
+        "```text",
+        facts.stderrExcerpt,
+        "```",
+        "",
+        "## Fixture Resolution stdout",
+        "",
+        "```text",
+        facts.fixtureStdoutExcerpt,
+        "```",
+        "",
+        "## Fixture Resolution stderr",
+        "",
+        "```text",
+        facts.fixtureStderrExcerpt,
+        "```",
+        "",
+    ].join("\n");
+}
+export async function writeBackendPytestCollectionArtifacts(input) {
+    const contractsDir = path.join(input.runDir, "contracts");
+    const reportsDir = path.join(input.runDir, "reports");
+    await mkdir(contractsDir, { recursive: true });
+    await mkdir(reportsDir, { recursive: true });
+    const factsPath = path.join(contractsDir, `backend-test-pytest-collection-${input.stem}.json`);
+    const reportPath = path.join(reportsDir, `backend-test-pytest-collection-${input.stem}.md`);
+    await writeFile(factsPath, `${JSON.stringify(input.facts, null, 2)}\n`, "utf8");
+    await writeFile(reportPath, renderBackendPytestCollectionReport(input.facts), "utf8");
+    return { factsPath, reportPath };
+}
+export async function readBackendPytestCollectionFacts(filePath) {
+    return backendPytestCollectionFactsSchema.parse(JSON.parse(await readFile(filePath, "utf8")));
+}
+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");
+    }
+    for (const file of final.assetFiles) {
+        const source = await readFile(path.resolve(workspaceRoot, file), "utf8");
+        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}`);
+            }
+        }
+    }
+}
+function assertSameInventory(expected, actual) {
+    const expectedFiles = Object.keys(expected.inputHashes).sort();
+    const actualFiles = Object.keys(actual.inputHashes).sort();
+    if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles))
+        throw new Error("backend pytest collection asset inventory drift");
+    for (const file of expectedFiles) {
+        if (expected.inputHashes[file] !== actual.inputHashes[file])
+            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);
+    assertSameInventory(input.effective, current);
+    const eligibility = input.eligibility ?? { eligibleItemIds: input.effective.collectedItemIds, excludedItems: [] };
+    const status = eligibility.eligibleItemIds.length === 0
+        ? "BLOCKED"
+        : input.scenarioParamStatus === "PASS" && eligibility.excludedItems.length === 0
+            ? "PASS"
+            : "PARTIAL";
+    const readiness = backendTestExecutionReadinessSchema.parse({
+        schemaId: "backend-test-execution-readiness-v2",
+        status,
+        collectionStatus: "PASS",
+        fixtureResolutionStatus: "PASS",
+        scenarioParamStatus: input.scenarioParamStatus,
+        repairAttempts: {
+            collection: input.effective.repairAttempt,
+            scenarioParam: input.scenarioParamRepairAttempt,
+        },
+        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 });
+    await writeFile(path.join(contractsDir, "backend-test-execution-readiness.json"), `${JSON.stringify(readiness, null, 2)}\n`, "utf8");
+    return readiness;
+}
+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)) {
+        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 priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
+    if (priorityOnly.length > 0) {
+        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}`);
+        }
+    }
+}
+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,
+            phase: "effective",
+            collectionSource: "initial",
+        });
+    }
+    if (input.initial.status === "BLOCKED")
+        throw new Error("backend pytest collection is blocked and not repairable");
+    if (!input.final)
+        throw new Error("backend pytest collection repair requires final collection facts");
+    if (input.final.status !== "PASS")
+        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,
+        phase: "effective",
+        repairEligible: false,
+        repairAttempt: 1,
+        collectionSource: "final",
+    });
+}