@tea-agent/loop-agent 0.35.2 → 0.35.3

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -4,10 +4,69 @@ import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { findPackageRoot } from "../../shared/package-metadata.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+export const frontendNormalizationActionSchema = z.enum([
+    "remove-trailing-commas",
+    "strip-comments",
+    "canonicalize-requirement-ids",
+    "canonicalize-verification-alias",
+    "inject-source-binding",
+]);
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            sorted[key] = sortKeysDeep(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** Deterministic JSON serialization: fixed key order, 2-space indent, no
+ * trailing newline. Shared by candidate/canonical/digest hashes so the same
+ * input always reproduces the same digest. */
+export function serializeDeterministicJson(value) {
+    return JSON.stringify(sortKeysDeep(value), null, 2);
+}
+export function deterministicSha256(value) {
+    return sha256Hex(serializeDeterministicJson(value));
+}
+/** A contract materialization failure carries its classification plus the
+ * audit context collected up to the failure point, so the prewrite gate can
+ * persist a complete frontend-prewrite-result-v1 even when the canonical
+ * contract is never materialized. */
+export class FrontendContractFailure extends Error {
+    kind;
+    candidateRawSha256;
+    candidateJsonSha256;
+    normalizationActions;
+    constructor(options) {
+        super(options.message);
+        this.name = "FrontendContractFailure";
+        this.kind = options.kind;
+        this.candidateRawSha256 = options.candidateRawSha256;
+        this.candidateJsonSha256 = options.candidateJsonSha256 ?? null;
+        this.normalizationActions = options.normalizationActions ?? [];
+    }
+}
+/** Write a JSON artifact with deterministic key order and return its sha256
+ * over the exact file bytes, so the canonical contract identity matches what
+ * downstream verify/repair/review re-read from disk. */
+export async function writeDeterministicJsonArtifact(runDir, relativePath, value) {
+    const json = `${serializeDeterministicJson(value)}\n`;
+    const targetPath = path.join(runDir, relativePath);
+    await writeTextArtifactFile(targetPath, json);
+    return { path: targetPath, sha256: sha256Hex(json) };
+}
 /**
  * Extract frozen command labels from the DAG run spec (run.json).
  * The run spec is written before any node executes, so it is always available
@@ -132,7 +191,32 @@ const gap = z
     blocking: z.boolean(),
 })
     .strict();
+/**
+ * Normalize unstable model emissions before the strict schema sees them:
+ * recursively drop null values (object entries and array elements). A null for
+ * an optional field becomes "absent" (accepted); a null for a required field
+ * still fails, but with a clean Required issue instead of a confusing type
+ * mismatch. Unknown keys and misspellings remain strict rejections.
+ */
+function stripNullValuesDeep(value) {
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => item !== null)
+            .map((item) => stripNullValuesDeep(item));
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const stripped = {};
+        for (const [key, item] of Object.entries(record)) {
+            if (item !== null)
+                stripped[key] = stripNullValuesDeep(item);
+        }
+        return stripped;
+    }
+    return value;
+}
 export const frontendImplementationContractSchema = z
+    .preprocess(stripNullValuesDeep, z
     .object({
     schemaVersion: z.literal(1),
     sourceBinding: z
@@ -189,7 +273,9 @@ export const frontendImplementationContractSchema = z
             "not-needed",
         ]),
         productionDefaultOff: z.literal(true),
-        activation: z.preprocess((value) => (value === "" || value === null ? "explicit activation boundary" : value), z.string().min(1)),
+        activation: z.preprocess((value) => value === "" || value === null || value === undefined
+            ? "explicit activation boundary"
+            : value, z.string().min(1)),
         endpoints: z.array(z
             .object({
             method: z.enum([
@@ -339,7 +425,7 @@ export const frontendImplementationContractSchema = z
             }
         });
     }
-});
+}));
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -378,8 +464,13 @@ function secretIssues(value, at = "$", issues = []) {
         }
     return issues;
 }
-export function extractFrontendImplementationJson(text) {
+function extractFrontendImplementationJsonWithAudit(text) {
     const trimmed = text.trim();
+    const actions = [];
+    const recordAction = (action) => {
+        if (!actions.includes(action))
+            actions.push(action);
+    };
     const parse = (source) => {
         try {
             return JSON.parse(source);
@@ -392,6 +483,10 @@ export function extractFrontendImplementationJson(text) {
                 .replace(/\/\*[\s\S]*?\*\//g, "")
                 .replace(/^\s*\/\/.*$/gm, "");
             const withoutTrailingCommas = withoutComments.replace(/,\s*([}\]])/g, "$1");
+            if (withoutComments !== source)
+                recordAction("strip-comments");
+            if (withoutTrailingCommas !== withoutComments)
+                recordAction("remove-trailing-commas");
             try {
                 return JSON.parse(withoutTrailingCommas);
             }
@@ -450,7 +545,7 @@ export function extractFrontendImplementationJson(text) {
             Array.isArray(record.verificationTargets));
     };
     if (trimmed.startsWith("{") && trimmed.endsWith("}"))
-        return parse(trimmed);
+        return { value: parse(trimmed), actions };
     const balancedObjects = [];
     for (let start = 0; start < trimmed.length; start += 1) {
         if (trimmed[start] !== "{")
@@ -488,9 +583,9 @@ export function extractFrontendImplementationJson(text) {
     }
     const balancedContracts = balancedObjects.filter(isContract);
     if (balancedContracts.length === 1)
-        return balancedContracts[0];
+        return { value: balancedContracts[0], actions };
     if (balancedObjects.length === 1)
-        return balancedObjects[0];
+        return { value: balancedObjects[0], actions };
     const blocks = [...trimmed.matchAll(/```json\s*\n([\s\S]*?)\n```/gi)];
     if (blocks.length === 0)
         throw new Error("output must contain exactly one fenced json object");
@@ -508,13 +603,16 @@ export function extractFrontendImplementationJson(text) {
     }
     const contractCandidates = candidates.filter(isContract);
     if (contractCandidates.length === 1)
-        return contractCandidates[0];
+        return { value: contractCandidates[0], actions };
     if (candidates.length === 1)
-        return candidates[0];
+        return { value: candidates[0], actions };
     if (candidates.length === 0)
         throw new Error("output must contain exactly one valid fenced json object (found 0)");
     throw new Error(`output must contain exactly one valid frontend contract json object (found ${contractCandidates.length || candidates.length})`);
 }
+export function extractFrontendImplementationJson(text) {
+    return extractFrontendImplementationJsonWithAudit(text).value;
+}
 /**
  * Build the authoritative frontend-implementation-contract sourceBinding from
  * the DAG-owned binding. Model JSON must not invent taskId/path/sha256; the
@@ -752,7 +850,14 @@ function deriveFrontendVerificationCoverage(value, canonicalBinding) {
             const requirementId = canonicalizeRequirementId(asString(gap.requirementId));
             // Model gaps are advisory. Blocking status is reconstructed below
             // from the source binding and executable verification targets.
-            return { ...gap, blocking: false };
+            // Drop a null/empty optional requirementId so the strict schema
+            // accepts model emissions (null is not a valid string).
+            const { requirementId: _rawRequirementId, ...rest } = gap;
+            return {
+                ...rest,
+                ...(requirementId ? { requirementId } : {}),
+                blocking: false,
+            };
         })
         : [];
     const derivedBlockingGaps = canonicalBinding.requirementIds
@@ -1228,40 +1333,87 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         evidenceGaps,
     };
 }
-export async function materializeFrontendImplementationContract(input) {
+/**
+ * Deterministic contract validation shared by the prewrite gate and the plan
+ * node output self-check. Extracts, security-checks, coerces, and schema-parses
+ * a model-emitted frontend contract, so schema/typo/null violations surface as
+ * invalid-output at the producing node (where they can retry) instead of only
+ * failing later at the prewrite gate.
+ */
+export async function analyzeFrontendImplementationContract(input) {
     if (!input.sourceBinding)
         throw new Error("frontend implementation contract gate requires DAG sourceBinding");
-    const record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
-    let parsed;
-    const rawContractText = record.assistantText?.trim() || record.stdout?.trim() || "";
+    let rawOutput;
+    if (input.rawContractText !== undefined) {
+        rawOutput = input.rawContractText;
+    }
+    else if (input.fromNodeId !== undefined) {
+        const record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+        rawOutput = record.assistantText ?? record.stdout ?? "";
+    }
+    else {
+        throw new Error("analyzeFrontendImplementationContract requires fromNodeId or rawContractText");
+    }
+    const rawContractText = rawOutput.trim();
+    const candidateRawSha256 = sha256Hex(rawOutput);
+    const normalizationActions = [];
+    const pushAction = (action) => {
+        if (!normalizationActions.includes(action))
+            normalizationActions.push(action);
+    };
+    function fail(kind, message, candidateJsonSha256) {
+        throw new FrontendContractFailure({
+            kind,
+            message,
+            candidateRawSha256,
+            candidateJsonSha256,
+            normalizationActions,
+        });
+    }
     if (rawContractText.includes('"files":["/'))
-        throw new Error("invalid-output: absolute frontend contract path is forbidden");
+        fail("blocked", "invalid-output: absolute frontend contract path is forbidden", null);
     if (/(?:"(?:files|file|implementationTargets|fixture|consumer)"\s*:\s*(?:\[\s*)?)"\//.test(rawContractText))
-        throw new Error("invalid-output: absolute frontend contract path is forbidden");
+        fail("blocked", "invalid-output: absolute frontend contract path is forbidden", null);
     if (/(?:"strategy"\s*:\s*")(?!native\b|browser-intercept\b|request-adapter\b|not-needed\b)[^"]+"/.test(rawContractText))
-        throw new Error("invalid-output: unsupported mock strategy");
+        fail("blocked", "invalid-output: unsupported mock strategy", null);
+    let parsed;
     try {
-        parsed = extractFrontendImplementationJson(rawContractText);
+        const extracted = extractFrontendImplementationJsonWithAudit(rawContractText);
+        parsed = extracted.value;
+        for (const action of extracted.actions)
+            pushAction(action);
     }
     catch (error) {
-        throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
+        fail("retryable-invalid", `invalid-output: ${error instanceof Error ? error.message : String(error)}`, null);
     }
+    const candidateJsonSha256 = deterministicSha256(parsed);
     const secrets = secretIssues(parsed);
     if (secrets.length)
-        throw new Error(`invalid-output: ${secrets.join("; ")}`);
+        fail("blocked", `invalid-output: ${secrets.join("; ")}`, candidateJsonSha256);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        throw new Error("invalid-output: frontend contract must be a JSON object");
+        fail("retryable-invalid", "invalid-output: frontend contract must be a JSON object", candidateJsonSha256);
     const parsedTargetObject = parsed.targets;
     const parsedFiles = parsedTargetObject && typeof parsedTargetObject === "object"
         ? parsedTargetObject.files
         : undefined;
     if (Array.isArray(parsedFiles) && parsedFiles.some((file) => typeof file === "string" && file.startsWith("/")))
-        throw new Error("invalid-output: absolute frontend contract path is forbidden");
+        fail("blocked", "invalid-output: absolute frontend contract path is forbidden", candidateJsonSha256);
     // Normalize model-emitted compact requirement IDs before deriving the
     // canonical binding or invoking the strict zod schema.
+    const beforeIds = JSON.stringify(parsed);
     parsed = canonicalizeRequirementIdsInPayload(parsed);
+    if (JSON.stringify(parsed) !== beforeIds)
+        pushAction("canonicalize-requirement-ids");
+    const beforeAliases = JSON.stringify(parsed);
     parsed = canonicalizeVerificationTargetAliases(parsed);
-    assertFrontendContractPathsSafe(parsed);
+    if (JSON.stringify(parsed) !== beforeAliases)
+        pushAction("canonicalize-verification-alias");
+    try {
+        assertFrontendContractPathsSafe(parsed);
+    }
+    catch (error) {
+        fail("blocked", error instanceof Error ? error.message : String(error), candidateJsonSha256);
+    }
     // Validate verificationTarget commandLabels against frozen command set.
     // The frozen set is derived from DAG verification shell task verifyEvidence.
     const frozenLabels = await deriveFrozenCommandLabelsFromRun(input.runDir);
@@ -1272,7 +1424,7 @@ export async function materializeFrontendImplementationContract(input) {
             for (const vt of parsedVt) {
                 const label = asString(asRecord(vt)?.commandLabel);
                 if (label && !frozen.has(label)) {
-                    throw new Error(`invalid-output: verificationTarget commandLabel "${label}" is not in the frozen command set [${[...frozen].join(", ")}]`);
+                    fail("blocked", `invalid-output: verificationTarget commandLabel "${label}" is not in the frozen command set [${[...frozen].join(", ")}]`, candidateJsonSha256);
                 }
             }
         }
@@ -1280,52 +1432,94 @@ export async function materializeFrontendImplementationContract(input) {
     const parsedTargets = asRecord(parsed)?.targets;
     const parsedTargetFiles = asStringArray(asRecord(parsedTargets)?.files);
     if (parsedTargetFiles.some((file) => file.startsWith("/") || file.includes("\\")))
-        throw new Error("invalid-output: frontend contract target paths must be relative POSIX paths");
+        fail("blocked", "invalid-output: frontend contract target paths must be relative POSIX paths", candidateJsonSha256);
     const parsedStates = asRecord(parsed)?.uiStates;
     if (Array.isArray(parsedStates) && parsedStates.some((item) => {
         const state = asRecord(item);
         return state?.applicable === true &&
             (!asString(state.expectedBehavior) || asStringArray(state.implementationTargets).length === 0 || asStringArray(state.verificationTargetIds).length === 0);
     }))
-        throw new Error("invalid-output: applicable UI state requires behavior, implementation, and verification");
+        fail("retryable-invalid", "invalid-output: applicable UI state requires behavior, implementation, and verification", candidateJsonSha256);
     const parsedMockApi = asRecord(parsed)?.mockApi;
     if (asRecord(parsedMockApi) &&
         typeof asRecord(parsedMockApi)?.strategy === "string" &&
         !["native", "browser-intercept", "request-adapter", "not-needed"].includes(String(asRecord(parsedMockApi)?.strategy)))
-        throw new Error(`invalid-output: unsupported mock strategy ${String(asRecord(parsedMockApi)?.strategy)}`);
+        fail("blocked", `invalid-output: unsupported mock strategy ${String(asRecord(parsedMockApi)?.strategy)}`, candidateJsonSha256);
     const baseCanonicalBinding = canonicalFrontendContractSourceBinding(input.sourceBinding);
     const canonicalBinding = withDerivedRequirementIdsWhenUnscoped(baseCanonicalBinding, parsed);
     // Always inject DAG-owned identity. Model-provided sourceBinding is advisory
-    // only and must not fail a otherwise-valid contract (common live failure:
-    // wrong requirementPath/sha, extra referencePaths, or omitted binding).
-    const normalizedContract = coerceFrontendImplementationContractInput(parsed, canonicalBinding);
+    // only and must not fail a otherwise-valid contract. Record the action only
+    // when the model's emitted binding actually differs from canonical identity.
+    const modelBinding = asRecord(asRecord(parsed)?.sourceBinding);
+    if (serializeDeterministicJson(modelBinding ?? null) !== serializeDeterministicJson(canonicalBinding))
+        pushAction("inject-source-binding");
     // There is exactly one post-security candidate. A fallback candidate would
     // allow malformed raw fields to bypass the boundary checks above.
+    const normalizedContract = coerceFrontendImplementationContractInput(parsed, canonicalBinding);
     const candidate = deriveFrontendVerificationCoverage({
         ...(asRecord(normalizedContract) ?? parsed),
         sourceBinding: canonicalBinding,
     }, canonicalBinding);
     const result = frontendImplementationContractSchema.safeParse(candidate);
     if (!result.success)
-        throw new Error(`invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`);
+        fail("retryable-invalid", `invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`, candidateJsonSha256);
     const blockingGaps = [
         ...result.data.evidenceGaps,
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
     ].filter((item) => item.blocking);
     if (blockingGaps.length > 0)
-        throw new Error(`frontend contract has blocking evidence gap: ${blockingGaps
+        fail("blocked", `frontend contract has blocking evidence gap: ${blockingGaps
             .map((item) => item.requirementId ?? item.description)
-            .join(", ")}`);
+            .join(", ")}`, candidateJsonSha256);
     for (const requirementId of canonicalBinding.requirementIds)
         if (!result.data.requirements.some((item) => item.id === requirementId) &&
             !result.data.evidenceGaps.some((item) => item.requirementId === requirementId))
-            throw new Error(`frontend contract does not cover ${requirementId}`);
-    const artifactPath = await writeDagRunJsonArtifact(input.runDir, path.posix.join(input.outputDir, input.artifactName), result.data);
+            fail("blocked", `frontend contract does not cover ${requirementId}`, candidateJsonSha256);
+    return {
+        canonical: result.data,
+        candidateRawSha256,
+        candidateJsonSha256,
+        normalizationActions,
+    };
+}
+export async function writeFrontendImplementationContractArtifact(input) {
+    const written = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(input.outputDir, input.artifactName), input.canonical);
     return {
-        path: artifactPath,
-        sha256: createHash("sha256")
-            .update(`${JSON.stringify(result.data, null, 2)}\n`)
-            .digest("hex"),
+        path: written.path,
+        sha256: written.sha256,
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
     };
 }
+/**
+ * Node-output self-check for plan nodes that produce the implementation
+ * contract. Mirrors the prewrite gate validation so schema/typo/null violations
+ * are caught at the producing node and retried instead of failing the run later.
+ * Skipped when no sourceBinding is available (the gate remains the authority).
+ */
+export async function validateFrontendContractNodeOutput(input) {
+    if (!input.sourceBinding)
+        return { ok: true };
+    try {
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: input.text,
+            sourceBinding: input.sourceBinding,
+        });
+        return { ok: true, contract: analysis.canonical };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function materializeFrontendImplementationContract(input) {
+    const analysis = await analyzeFrontendImplementationContract(input);
+    return writeFrontendImplementationContractArtifact({
+        runDir: input.runDir,
+        outputDir: input.outputDir,
+        artifactName: input.artifactName,
+        canonical: analysis.canonical,
+    });
+}