@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.11

package/dist/workflows/dag/backend-test-writer-completeness.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { z } from "zod";
 import { BACKEND_TEST_MAX_MODULE_COUNT, isOpaqueHashBackendTestModuleStem, isPriorityOnlyBackendTestModuleStem, } from "./backend-test-module-stem.js";
 import { resolveBackendTestLayout, } from "./backend-test-layout.js";
-import { inspectBackendTestMarkdownTestPointBindings } from "./backend-test-case-coverage-analysis.js";
+import { canonicalizeBackendTestMarkdownTestPointBindings, inspectBackendTestMarkdownTestPointBindings, } from "./backend-test-case-coverage-analysis.js";
+import { BACKEND_TEST_SCENARIO_PARTITION_SLOTS_SCHEMA_ID, canonicalizeBackendTestPlanProtocolHeadings, collectMarkdownPartitionSlotCoverage, lookupRequiredVariantSlotsForMarkdownPath, } from "./backend-test-plan-protocol.js";
 /**
  * Maps a backend-test generation writer task id to its writer-progress role.
  * Returns undefined for nodes that are not completeness-gated generators.
@@ -47,8 +48,16 @@ const progressSchema = z
         path: z.string().optional(),
         detail: z.string(),
         recoverable: z.boolean(),
+        failureSubreason: z.literal("markdown-test-point-binding-format").optional(),
+        affectedCases: z.array(z.string()).optional(),
+        testPointIds: z.array(z.string()).optional(),
+        canonicalizationEligible: z.boolean().optional(),
+        canonicalizationOutcome: z.enum(["not-attempted", "changed", "already-canonical", "unsafe", "revalidation-failed"]).optional(),
     })
         .strict()),
+    canonicalizationOutcome: z.enum(["not-attempted", "changed", "already-canonical", "unsafe", "revalidation-failed"]).optional(),
+    canonicalizedTestPointCount: z.number().int().min(0).optional(),
+    lightweightRepairEligible: z.boolean().optional(),
 })
     .strict();
 async function exists(filePath) {
@@ -119,10 +128,8 @@ function looksLikeValidModuleStem(raw) {
     return moduleStemInvalidReason(raw) === undefined;
 }
 function extractCanonicalModuleIndexSection(readme) {
-    const lines = readme
-        .replaceAll("\r\n", "\n")
-        .replaceAll("\r", "\n")
-        .split("\n");
+    const canonical = canonicalizeBackendTestPlanProtocolHeadings(readme).markdown;
+    const lines = canonical.split("\n");
     const headings = lines.flatMap((line, index) => line.trim() === "## Module Index" ? [index] : []);
     if (headings.length === 0) {
         return { section: "", structureIssues: ["missing-module-index"] };
@@ -362,8 +369,6 @@ function pythonParseable(source) {
     const normalized = source.replace(/\r\n/g, "\n");
     if (!normalized.trim())
         return false;
-    if (/^\s*(?:def|class|import|from)\b/m.test(normalized) === false)
-        return false;
     const structural = pythonStructureOutsideStrings(normalized);
     if (!structural.stringsClosed)
         return false;
@@ -380,7 +385,13 @@ function pythonParseable(source) {
         return false;
     if (openBraces !== closeBraces)
         return false;
-    return true;
+    // Business modules still need a statement. Evidence-only mapped scripts may
+    // be a closed module docstring + Case-ID with no `def test_` (R10 health).
+    if (/^\s*(?:def|class|import|from|__all__\s*=)/m.test(normalized))
+        return true;
+    return (/^\s*(?:'''|""")/.test(normalized) &&
+        /\bCase-ID\s*:/i.test(normalized) &&
+        !/^\s*(?:async\s+)?def\s+test_/m.test(normalized));
 }
 /**
  * Forbidden generated shared helper/factory namespaces for the self-contained
@@ -511,6 +522,19 @@ export async function loadBackendTestWriterProgressForRetry(runDir, taskId) {
  * child's own target file(s): md children are checked for structural
  * completeness, pytest children for parseability. Sibling modules are ignored.
  */
+async function loadScenarioPartitionSlotInventory(runDir) {
+    if (!runDir)
+        return undefined;
+    try {
+        const raw = JSON.parse(await readFile(path.join(runDir, "contracts", "backend-test-scenario-partition-slots.json"), "utf8"));
+        if (raw?.schemaId !== BACKEND_TEST_SCENARIO_PARTITION_SLOTS_SCHEMA_ID)
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function assessBackendTestShardChildCompleteness(input) {
     const role = input.role;
     const targetPaths = input.writeSet
@@ -520,6 +544,12 @@ export async function assessBackendTestShardChildCompleteness(input) {
     const actualPaths = [];
     const missingPaths = [];
     const brokenPaths = [];
+    let canonicalizationOutcome = role === "md-generate" ? "already-canonical" : undefined;
+    let canonicalizedTestPointCount = 0;
+    let lightweightRepairEligible = false;
+    const slotInventory = role === "md-generate"
+        ? await loadScenarioPartitionSlotInventory(input.runDir)
+        : undefined;
     for (const target of targetPaths) {
         // Rendered map-child writeSet entries are concrete (e.g.
         // testcase/md/health.md / testcase/test_orders.py); glob-only entries are
@@ -538,16 +568,65 @@ export async function assessBackendTestShardChildCompleteness(input) {
             continue;
         }
         actualPaths.push(target);
-        const body = await readFile(absolute, "utf8");
+        let body = await readFile(absolute, "utf8");
         if (role === "md-generate") {
+            const beforeBindings = inspectBackendTestMarkdownTestPointBindings(body);
+            const canonicalization = canonicalizeBackendTestMarkdownTestPointBindings(body);
+            if (canonicalization.changed) {
+                await writeFile(absolute, canonicalization.markdown, "utf8");
+                body = canonicalization.markdown;
+                canonicalizationOutcome = "changed";
+                canonicalizedTestPointCount += canonicalization.canonicalizedTestPoints.length;
+            }
+            const afterBindings = inspectBackendTestMarkdownTestPointBindings(body);
+            const unresolved = afterBindings.flatMap((entry) => entry.unclassifiedTestPoints);
+            const bindingCases = afterBindings
+                .filter((entry) => entry.unclassifiedTestPoints.length > 0 || entry.duplicateBindingTestPoints.length > 0)
+                .map((entry) => entry.caseId);
             const structural = moduleStructurallyComplete(body);
+            const requiredSlots = lookupRequiredVariantSlotsForMarkdownPath(slotInventory, target);
+            const slotCoverage = requiredSlots.length > 0
+                ? collectMarkdownPartitionSlotCoverage(body, requiredSlots)
+                : undefined;
+            const missingSlots = orderedUnique([
+                ...(slotCoverage?.missingFromDeclared ?? []),
+                ...(slotCoverage?.missingFromVariant ?? []),
+            ]);
+            if (missingSlots.length > 0) {
+                lightweightRepairEligible = true;
+                if (!brokenPaths.includes(target))
+                    brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: `incomplete-partition-slot-set: missing ${missingSlots.join(", ")}; Scheme A requires each exact slot as an independent variant Test Point, not Case count or SINGLE/MULTIPLE aliases`,
+                    recoverable: true,
+                    affectedCases: afterBindings.map((entry) => entry.caseId),
+                    testPointIds: missingSlots,
+                });
+            }
             if (!structural.ok) {
+                lightweightRepairEligible = bindingCases.length > 0;
+                if (bindingCases.length > 0)
+                    canonicalizationOutcome = canonicalization.changed ? "revalidation-failed" : "unsafe";
                 brokenPaths.push(target);
+                const bindingFormatIssue = bindingCases.length > 0;
                 issues.push({
                     code: "T5",
                     path: target,
                     detail: moduleStructuralDetail(structural),
                     recoverable: true,
+                    ...(bindingFormatIssue
+                        ? {
+                            failureSubreason: "markdown-test-point-binding-format",
+                            affectedCases: orderedUnique(bindingCases),
+                            testPointIds: orderedUnique(unresolved),
+                            canonicalizationEligible: canonicalization.canonicalizedTestPoints.length > 0,
+                            canonicalizationOutcome: canonicalization.changed
+                                ? (unresolved.length === 0 ? "changed" : "revalidation-failed")
+                                : (beforeBindings.some((entry) => entry.unclassifiedTestPoints.length > 0) ? "unsafe" : "already-canonical"),
+                        }
+                        : {}),
                 });
             }
         }
@@ -586,6 +665,9 @@ export async function assessBackendTestShardChildCompleteness(input) {
         brokenPaths: orderedUnique(brokenPaths),
         targetPaths: recoverableTargets,
         issues,
+        ...(role === "md-generate"
+            ? { canonicalizationOutcome, canonicalizedTestPointCount, lightweightRepairEligible }
+            : {}),
     };
 }
 export async function assessBackendTestMdWriterCompleteness(workspaceRoot, layout) {
@@ -609,7 +691,7 @@ export async function assessBackendTestMdWriterCompleteness(workspaceRoot, layou
     }
     else {
         actualPaths.push(readmeRel);
-        readme = await readFile(readmePath, "utf8");
+        readme = canonicalizeBackendTestPlanProtocolHeadings(await readFile(readmePath, "utf8")).markdown;
         if (!readme.includes("## Coverage Scope")) {
             brokenPaths.push(readmeRel);
             issues.push({
@@ -853,7 +935,7 @@ export async function writeBackendTestWriterProgressArtifacts(input) {
         "## Issues",
         "",
         ...(input.progress.issues.length
-            ? input.progress.issues.map((issue) => `- [${issue.code}] ${issue.path ?? "(workspace)"}: ${issue.detail}`)
+            ? input.progress.issues.map((issue) => `- [${issue.code}] ${issue.path ?? "(workspace)"}: ${issue.detail}${issue.failureSubreason ? `; failureSubreason=${issue.failureSubreason}; canonicalizationOutcome=${issue.canonicalizationOutcome ?? "not-attempted"}; canonicalizationEligible=${issue.canonicalizationEligible ?? false}; affectedCases=${(issue.affectedCases ?? []).join(",") || "none"}; testPointIds=${(issue.testPointIds ?? []).join(",") || "none"}` : ""}`)
             : ["- None"]),
         "",
         `<!-- sha256:${createHash("sha256").update(JSON.stringify(parsed)).digest("hex")} -->`,
@@ -862,6 +944,16 @@ export async function writeBackendTestWriterProgressArtifacts(input) {
     await writeFile(reportPath, body, "utf8");
     return { factsPath, reportPath };
 }
+export function isBackendTestPytestCollectionRepairOutcomeRecoveryCandidate(task) {
+    return (task.id === "repair-backend-pytest-collection-pi" &&
+        task.executor === "pi" &&
+        task.role === "implementer" &&
+        task.toolProfile === "write" &&
+        task.writePolicy === "exclusive" &&
+        (task.writeSet?.length ?? 0) > 0 &&
+        task.writerOutcomePolicy?.type === "implementation-outcome-v1" &&
+        task.writerOutcomePolicy.requireChangedFiles === true);
+}
 export function isBackendTestCompletenessRetryCandidate(task) {
     if (task.executor !== "pi" || task.role !== "implementer")
         return false;
@@ -933,7 +1025,7 @@ export async function assessBackendTestMdPlanCompleteness(workspaceRoot, layout)
     }
     else {
         actualPaths.push(planReadmeRel);
-        const readme = await readFile(readmePath, "utf8");
+        const readme = canonicalizeBackendTestPlanProtocolHeadings(await readFile(readmePath, "utf8")).markdown;
         if (!readme.includes("## Coverage Scope")) {
             brokenPaths.push(planReadmeRel);
             issues.push({

package/dist/workflows/dag/contract-validator-registrations.js

@@ -3,8 +3,7 @@
  * its schemaId in the contract output registry. Imported once by the node
  * executor; keeps per-contract imports out of the executor.
  */
-import { validateFrontendContractNodeOutput, validateFrontendPlanPatchNodeOutput, validateFrontendRevisionPatchNodeOutput, } from "./frontend-implementation-contract.js";
+import { validateFrontendContractNodeOutput, validateFrontendPlanPatchNodeOutput, } from "./frontend-implementation-contract.js";
 import { registerStructuredContractValidator } from "./contract-output-registry.js";
 registerStructuredContractValidator("frontend-implementation-contract-v1", validateFrontendContractNodeOutput);
 registerStructuredContractValidator("frontend-implementation-contract-plan-patch-v1", validateFrontendPlanPatchNodeOutput);
-registerStructuredContractValidator("frontend-implementation-contract-revision-patch-v1", validateFrontendRevisionPatchNodeOutput);

package/dist/workflows/dag/dag-retry-schema.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+/**
+ * Leaf module for the retry-policy schema surface: failure-category constants,
+ * the zod retry-policy schema, and the target-template transient retry profile
+ * literal.
+ *
+ * `types.ts` reads `dagRetryPolicySchema` / `TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE`
+ * during its own module initialization, and the retry-policy module transitively
+ * reaches `types.ts` (retry-policy → frontend-recovery-capsule →
+ * frontend-recovery-lineage → frontend-implementation-contract → types). With
+ * these definitions living in retry-policy itself, a run whose entry module is
+ * retry-policy (e.g. test/dag-node-retry.test.ts) evaluates `types.ts` while
+ * retry-policy is still initializing and reads an undefined
+ * `dagRetryPolicySchema`. Keeping this module a leaf (zod is its only import)
+ * makes the cycle resolve order-independently; retry-policy re-exports
+ * everything for source compatibility.
+ */
+/**
+ * Failure categories that are safe to auto-retry for read-only Pi nodes.
+ *
+ * These are failures with no repository write side-effects: model connection
+ * interruption, provider rate-limiting, temporary provider unavailability,
+ * request timeout, or a settled read-only turn with no assistant text.
+ *
+ * `quota` is intentionally NOT included: a quota exhaustion is an account
+ * billing/plan state, not a transient rate limit, and retrying immediately
+ * will not help and may waste budget.
+ */
+export const DEFAULT_DAG_RETRY_CATEGORIES = [
+    "timeout",
+    "network",
+    "rate-limit",
+    "unavailable",
+    "empty-output",
+];
+export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
+export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
+/** Recoverable model artifact/schema formatting failure on read-only structured nodes. */
+export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
+/** Provider stopReason=length truncated the response before the JSON contract completed. */
+export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
+/**
+ * The review node emitted a verdict in response text (e.g. "VERDICT: pass")
+ * but never committed the authoritative typed terminal tool call
+ * (approve_review / request_review_changes). Read-only and safe to retry with
+ * a corrected instruction; the typed terminal is the only authority.
+ */
+export const REVIEW_TERMINAL_MISSING_RETRY_CATEGORY = "review-terminal-missing";
+/**
+ * The plan node issued too many read-only tool calls (read/grep/ls/find),
+ * blowing up the context window and eventually a 400 request-too-large. The
+ * plan should trust upstream typed facts instead of re-reading contract/scout
+ * outputs and source files repeatedly. Read-only and safe to retry with a
+ * reduced-reading instruction.
+ */
+export const READ_BURST_RETRY_CATEGORY = "read-burst";
+/**
+ * Provider returned a context-overflow error (400 request-too-large / context
+ * window exceeded). The SDK compacts and auto-retries once internally; when it
+ * still surfaces, the executor classifies this so retry policies and reports
+ * treat it as overflow (not empty-output) and can retry with a compacted
+ * session / fresh context.
+ */
+export const CONTEXT_OVERFLOW_RETRY_CATEGORY = "context-overflow";
+/** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
+export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
+/** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
+export const INCOMPLETE_WRITE_SET_RETRY_CATEGORY = "incomplete-write-set";
+/**
+ * Provider/transport stall or absolute timeout on a Pi exclusive writer that
+ * left zero attributed workspace writes and zero write-tool calls. Safe to
+ * retry once because the attempt was a pure provider flake (no side effects).
+ * Partial writes keep the original `timeout` category and do NOT retry.
+ */
+export const WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY = "writer-clean-timeout";
+export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    STRUCTURED_OUTPUT_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
+];
+/** Categories allowed on nodes that declare a machine-readable outputProtocol. */
+export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    PROTOCOL_INVALID_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+];
+export const ALL_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    STRUCTURED_OUTPUT_RETRY_CATEGORY,
+    PROTOCOL_INVALID_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
+    WRITER_EMPTY_DIFF_RETRY_CATEGORY,
+    INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
+    WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+    REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
+    READ_BURST_RETRY_CATEGORY,
+    CONTEXT_OVERFLOW_RETRY_CATEGORY,
+];
+export const dagRetryCategorySchema = z.enum(ALL_DAG_RETRY_CATEGORIES);
+export const dagRetryBackoffSchema = z.enum(["exponential"]);
+/**
+ * Opt-in retry policy for a DagTask. Generated for safe read-only Pi nodes,
+ * except the single validation-gated writer-empty-diff policy. Validation
+ * rejects all other writers, dynamic, shell, static, and decision-gate nodes.
+ */
+export const dagRetryPolicySchema = z
+    .object({
+    /**
+     * Total number of attempts (including the first try). Must be 1..5.
+     * A value of 1 disables retry (one attempt, no retry).
+     */
+    maxAttempts: z.number().int().positive().max(5),
+    backoff: dagRetryBackoffSchema.default("exponential"),
+    /** Initial delay before the second attempt, in milliseconds. */
+    initialDelayMs: z.number().int().nonnegative().default(2000),
+    /** Upper bound on a single backoff delay, in milliseconds. */
+    maxDelayMs: z.number().int().nonnegative().default(30000),
+    /**
+     * Explicit set of failure categories eligible for retry. Defaults to
+     * {@link DEFAULT_DAG_RETRY_CATEGORIES}. `quota` and other categories
+     * are never retried.
+     */
+    retryCategories: z
+        .array(dagRetryCategorySchema)
+        .default([...DEFAULT_DAG_RETRY_CATEGORIES]),
+})
+    .superRefine((policy, ctx) => {
+    if (policy.maxDelayMs < policy.initialDelayMs) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "retryPolicy.maxDelayMs must be >= retryPolicy.initialDelayMs",
+            path: ["maxDelayMs"],
+        });
+    }
+});
+export const TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE = "standard-reviewed-supervised-v1";

package/dist/workflows/dag/frontend-closeout.js

@@ -0,0 +1,221 @@
+import { z } from "zod";
+export { buildFrontendShapeTransitionCapsule, computeFrontendShapeSourceDigest, evaluateFrontendShapeEscalation, FRONTEND_SHAPE_NODE_COUNTS, frontendShapeTransitionCapsuleSchema, frontendShapeTransitionReshapeCapsuleSchema, frontendShapeTransitionSplitCapsuleSchema, parseFrontendShapeTransitionCapsule, resolveFrontendTaskShape, } from "./frontend-shape.js";
+/**
+ * Deterministic frontend closeout facts + renderer (M7).
+ *
+ * The functions here are pure (no I/O, no model, no side effects). The closeout
+ * renderer reads only committed facts, never model summaries or node prose, so
+ * a weak conclusion (failed / not-run / baseline-debt / mock-backed / pending)
+ * can never be rewritten into a stronger one (passed / real-integrated).
+ *
+ * Canonical shape routing and transition capsules live in `frontend-shape.ts`
+ * and are re-exported here for callers that also consume closeout contracts.
+ */
+export const FRONTEND_CLOSEOUT_FACTS_SCHEMA_ID = "frontend-closeout-facts-v1";
+/* ------------------------------------------------------------------ *
+ * Enums + facts schema                                                 *
+ * ------------------------------------------------------------------ */
+export const frontendCoverageStatusSchema = z.enum([
+    "passed",
+    "failed",
+    "not-run",
+    "blocked",
+    "unavailable",
+]);
+export const frontendLintStatusSchema = z.enum([
+    "passed",
+    "baseline-debt",
+    "failed",
+    "unavailable",
+]);
+export const frontendIntegrationFactsSchema = z.enum([
+    "real-api",
+    "mock-backed",
+    "local-no-remote",
+    "unavailable",
+]);
+export const frontendCloseoutFactsSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(FRONTEND_CLOSEOUT_FACTS_SCHEMA_ID),
+    coverageMatrix: z.array(z
+        .object({
+        verificationTargetId: z.string().min(1),
+        status: frontendCoverageStatusSchema,
+    })
+        .strict()),
+    lintStatus: frontendLintStatusSchema,
+    integrationFacts: frontendIntegrationFactsSchema,
+    reviewApproval: z
+        .object({
+        typedVerdict: z
+            .enum(["approve_review", "request_review_changes"])
+            .nullable(),
+        legacyVerdict: z.enum(["pass", "request-revision"]).nullable(),
+        match: z.boolean(),
+    })
+        .strict(),
+    cumulativeDiff: z
+        .object({
+        cumulativeDigest: z.string().min(1),
+        empty: z.boolean(),
+    })
+        .strict(),
+    notRun: z
+        .object({
+        browser: z.literal("not-run"),
+        visual: z.literal("not-run"),
+    })
+        .strict(),
+    pendingRealIntegration: z.boolean(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+    evidenceGaps: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+/* ------------------------------------------------------------------ *
+ * FrontendTestHandoff (A+B AC-010)                                   *
+ * ------------------------------------------------------------------ */
+export const FRONTEND_TEST_HANDOFF_SCHEMA_ID = "frontend-test-handoff-v1";
+/**
+ * A+B (AC-010): deterministic frontend-test handoff. Bound to the task id,
+ * source digest, and candidate hash; browser/visual/runtime-a11y are always
+ * `not-run` and the handoff is always `deferred-to-frontend-test`, so a weak
+ * closeout can never block implementation and can never be rewritten as
+ * passed.
+ */
+export const frontendTestHandoffSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(FRONTEND_TEST_HANDOFF_SCHEMA_ID),
+    taskId: z.string().min(1),
+    sourceDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    candidateHash: z.string().regex(/^[a-f0-9]{64}$/),
+    executionStatus: z.literal("not-run"),
+    handoffStatus: z.literal("deferred-to-frontend-test"),
+    nonBlocking: z.literal(true),
+})
+    .strict();
+export function buildFrontendTestHandoff(input) {
+    return frontendTestHandoffSchema.parse({
+        schemaVersion: 1,
+        schemaId: FRONTEND_TEST_HANDOFF_SCHEMA_ID,
+        taskId: input.taskId,
+        sourceDigest: input.sourceDigest,
+        candidateHash: input.candidateHash,
+        executionStatus: "not-run",
+        handoffStatus: "deferred-to-frontend-test",
+        nonBlocking: true,
+    });
+}
+/**
+ * Deterministic, fail-closed mapping from structured evidence to integration
+ * facts. Never reads model text. `real-api` is the only value that may report
+ * real integration, and it requires both real passed evidence and satisfied
+ * required verification evidence. Anything else downgrades to pending.
+ */
+export function deriveFrontendIntegrationFacts(input) {
+    const requiredEvidenceSatisfied = input.verificationTargets.length > 0 &&
+        input.verificationTargets.every((target) => target.status === "ok");
+    if (input.realApiEvidence.present &&
+        input.realApiEvidence.passed &&
+        requiredEvidenceSatisfied) {
+        return "real-api";
+    }
+    // Required evidence not satisfied → never report real-integrated or
+    // mock/locally-validated; evidence is unavailable.
+    if (!requiredEvidenceSatisfied) {
+        return "unavailable";
+    }
+    if (input.mockStrategy !== "not-needed" && input.mockEvidenceBound) {
+        return "mock-backed";
+    }
+    if (input.mockStrategy === "not-needed" && !input.realApiEvidence.present) {
+        return "local-no-remote";
+    }
+    return "unavailable";
+}
+/* ------------------------------------------------------------------ *
+ * Deterministic closeout renderer                                     *
+ * ------------------------------------------------------------------ */
+function bulletList(items) {
+    if (!items || items.length === 0)
+        return "";
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function coverageLines(facts) {
+    const lines = facts.coverageMatrix.map((entry) => `- ${entry.verificationTargetId}: ${entry.status}`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function frontendStatus(facts) {
+    switch (facts.integrationFacts) {
+        case "real-api":
+            return "Frontend status: real-integrated";
+        case "mock-backed":
+            return "Frontend status: mock-validated";
+        case "local-no-remote":
+            return "Frontend status: locally-validated";
+        case "unavailable":
+            return "Frontend status: unverified";
+    }
+}
+function integrationStatus(facts) {
+    return facts.integrationFacts === "real-api"
+        ? "Real integration: validated"
+        : `Real integration: pending (${facts.integrationFacts})`;
+}
+function reviewApprovalLines(facts) {
+    const { typedVerdict, legacyVerdict, match } = facts.reviewApproval;
+    return [
+        `typed: ${typedVerdict ?? "none"}`,
+        `legacy: ${legacyVerdict ?? "none"}`,
+        `match: ${match}`,
+    ].join("\n");
+}
+/**
+ * Render a deterministic closeout Markdown document from committed facts only.
+ * The same facts always render byte-identical output; weak statuses are
+ * emitted verbatim and never promoted to `passed` / real-integrated.
+ */
+export function renderFrontendCloseout(facts) {
+    const lintLine = facts.lintStatus === "baseline-debt"
+        ? `${facts.lintStatus} (explicit debt; not passed)`
+        : facts.lintStatus;
+    return [
+        "# Frontend Closeout",
+        "",
+        "## Coverage Matrix",
+        coverageLines(facts),
+        "",
+        "## Lint Status",
+        lintLine,
+        "",
+        "## Integration Facts",
+        facts.integrationFacts,
+        "",
+        "## Frontend Status",
+        frontendStatus(facts),
+        "",
+        "## Real Integration Status",
+        integrationStatus(facts),
+        "",
+        "## Real Integration Pending",
+        facts.pendingRealIntegration ? "yes" : "no",
+        "",
+        "## Review Approval",
+        reviewApprovalLines(facts),
+        "",
+        "## Cumulative Diff",
+        `digest: ${facts.cumulativeDiff.cumulativeDigest}`,
+        `empty: ${facts.cumulativeDiff.empty}`,
+        "",
+        "## Browser / Visual",
+        `Browser: ${facts.notRun.browser}`,
+        `Visual: ${facts.notRun.visual}`,
+        "",
+        "## Residual Risks",
+        bulletList(facts.residualRisks) || "_(none)_",
+        "",
+        "## Evidence Gaps",
+        bulletList(facts.evidenceGaps) || "_(none)_",
+    ].join("\n") + "\n";
+}