@tea-agent/loop-agent 0.38.1 → 0.38.3

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

@@ -8,11 +8,13 @@ import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-sto
 import { findPackageRoot } from "../../shared/package-metadata.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, openspecCitationsRel, parseOpenspecCitationsBlock, persistRuntimeSkeleton, } from "./structured-output-repair.js";
 export const frontendNormalizationActionSchema = z.enum([
     "remove-trailing-commas",
     "strip-comments",
     "canonicalize-requirement-ids",
     "canonicalize-verification-alias",
+    "drop-unresolved-verification-symbols",
     "inject-source-binding",
 ]);
 export function sha256Hex(input) {
@@ -102,6 +104,21 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     return [...labels];
 }
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
+export const FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID = "frontend-implementation-contract-plan-patch-v1";
+/**
+ * Build the deterministic, run-owned portion of the frontend contract. The
+ * planner is allowed to fill semantic fields with an RFC 7386 merge patch but
+ * cannot redefine task identity, risk, or the implementation write boundary.
+ */
+export function buildFrontendImplementationContractSkeleton(input) {
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalFrontendContractSourceBinding(input.sourceBinding),
+        riskLevel: input.riskLevel,
+        targets: { files: [...input.targetFiles] },
+        mockApi: { productionDefaultOff: true },
+    };
+}
 /**
  * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
  * installed loop-agent package docs/templates/ path. Package-root discovery
@@ -499,9 +516,9 @@ function isPlainObject(value) {
  * ever materialized, so a patch that removes a required field still fails
  * closed at the gate.
  */
-export function applyFrontendImplementationContractPatch(target, patch) {
+export function applyFrontendContractMergePatch(target, patch) {
     if (!isPlainObject(patch)) {
-        throw new Error("frontend revision patch must be a JSON object");
+        throw new Error("frontend contract patch must be a JSON object");
     }
     const merge = (base, delta) => {
         if (delta === null)
@@ -526,6 +543,9 @@ export function applyFrontendImplementationContractPatch(target, patch) {
     };
     return merge(target, patch);
 }
+export function applyFrontendImplementationContractPatch(target, patch) {
+    return applyFrontendContractMergePatch(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -1466,7 +1486,13 @@ export async function analyzeFrontendImplementationContract(input) {
         rawOutput = input.rawContractText;
     }
     else if (input.fromNodeId !== undefined) {
-        const record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+        let record;
+        try {
+            record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+        }
+        catch (error) {
+            throw new Error(`cannot parse node record ${input.fromNodeId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
         rawOutput = record.assistantText ?? record.stdout ?? "";
     }
     else {
@@ -1608,6 +1634,239 @@ export async function writeFrontendImplementationContractArtifact(input) {
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
     };
 }
+const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
+    "/schemaVersion",
+    "/sourceBinding",
+    "/riskLevel",
+    "/targets/files",
+    "/mockApi/productionDefaultOff",
+];
+function frontendPlanPatchProtectedPathViolations(patch) {
+    const record = asRecord(patch);
+    if (!record)
+        return ["/"];
+    const violations = [];
+    for (const key of ["schemaVersion", "sourceBinding", "riskLevel"]) {
+        if (Object.hasOwn(record, key))
+            violations.push(`/${key}`);
+    }
+    const targets = asRecord(record.targets);
+    if (targets && Object.hasOwn(targets, "files"))
+        violations.push("/targets/files");
+    const mockApi = asRecord(record.mockApi);
+    if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
+        violations.push("/mockApi/productionDefaultOff");
+    return violations;
+}
+function workspaceRootFromDagRunDir(runDir) {
+    const absolute = path.resolve(runDir);
+    const segments = absolute.split(path.sep);
+    const harnessIndex = segments.lastIndexOf(".harness");
+    if (harnessIndex < 0 ||
+        segments[harnessIndex + 1] !== "dag-runs" ||
+        harnessIndex + 3 >= segments.length) {
+        return null;
+    }
+    const joined = segments.slice(0, harnessIndex).join(path.sep);
+    return joined || path.parse(absolute).root;
+}
+function verificationSymbolMatchesFile(symbol, content) {
+    if (symbol.trim().toLowerCase() === "all describe blocks")
+        return content.includes("describe(");
+    const symbols = symbol.includes(" / ")
+        ? symbol
+            .split(/[（(]/, 1)[0]
+            .split("/")
+            .map((item) => item.trim())
+            .filter(Boolean)
+        : [symbol];
+    return symbols.every((item) => {
+        const describeTitle = item.match(/^describe\((?:['"])(.+?)(?:['"])/i)?.[1];
+        return [item, describeTitle, describeTitle ? "describe(" : undefined]
+            .filter((candidate) => Boolean(candidate))
+            .some((candidate) => content.includes(candidate));
+    });
+}
+async function dropUnresolvedVerificationSymbols(input) {
+    const workspaceRoot = workspaceRootFromDagRunDir(input.runDir);
+    const targets = asRecord(input.contract)?.verificationTargets;
+    if (!workspaceRoot || !Array.isArray(targets))
+        return false;
+    let changed = false;
+    for (const targetValue of targets) {
+        const target = asRecord(targetValue);
+        const file = asString(target?.file);
+        const symbol = asString(target?.symbol);
+        if (!target || !file || !symbol)
+            continue;
+        const absolute = path.resolve(workspaceRoot, file);
+        const relative = path.relative(workspaceRoot, absolute);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative) ||
+            relative.includes("..")) {
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(absolute, "utf8");
+        }
+        catch {
+            // Missing files remain a trace-time hard failure; do not hide them by
+            // changing the optional symbol during candidate normalization.
+            continue;
+        }
+        if (verificationSymbolMatchesFile(symbol, content))
+            continue;
+        delete target.symbol;
+        changed = true;
+    }
+    return changed;
+}
+function extractSingleOpenspecCitationsBlock(text) {
+    const blocks = text.match(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g) ?? [];
+    if (blocks.length !== 1) {
+        throw new Error(`frontend plan patch output must include exactly one fenced openspec-citations block (found ${blocks.length})`);
+    }
+    return blocks[0];
+}
+async function writeFrontendPlanCandidateRaw(input) {
+    const relativePath = path.posix.join("contracts", "candidates", input.nodeId, `attempt-${input.attempt}.raw.md`);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text.endsWith("\n") ? input.text : `${input.text}\n`);
+    return relativePath;
+}
+/**
+ * Compile the planner's editable RFC 7386 patch against the deterministic
+ * runtime skeleton. Every attempt is preserved under contracts/candidates so
+ * format/schema failures can be inspected and replayed without trusting model
+ * prose. A successful result returns a path-only pointer plus the hash-bound canonical artifact for
+ * downstream review and prewrite nodes.
+ */
+export async function validateFrontendPlanPatchNodeOutput(input) {
+    const nodeId = input.nodeId ?? "frontend-plan-pi";
+    const attempt = input.attempt ?? 1;
+    const candidateDir = path.posix.join("contracts", "candidates", nodeId);
+    const rawPath = await writeFrontendPlanCandidateRaw({
+        runDir: input.runDir,
+        nodeId,
+        attempt,
+        text: input.text,
+    });
+    const reportBase = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
+        nodeId,
+        attempt,
+        rawPath,
+        protectedPaths: [...FRONTEND_PLAN_PATCH_PROTECTED_PATHS],
+        candidateRawSha256: sha256Hex(input.text),
+    };
+    let extractedPatchPath;
+    let extractedPatchSha256;
+    const writeReport = async (value) => {
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
+            ...reportBase,
+            ...(extractedPatchPath
+                ? { extractedPatchPath, extractedPatchSha256 }
+                : {}),
+            ...value,
+        });
+    };
+    try {
+        if (!input.sourceBinding)
+            throw new Error("frontend plan patch validator requires DAG sourceBinding");
+        const skeleton = input.structuredContractOutput?.skeleton;
+        if (!skeleton)
+            throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
+        const patch = extractFrontendImplementationJson(input.text);
+        if (!isPlainObject(patch))
+            throw new Error("frontend plan patch must extract to one JSON object");
+        extractedPatchPath = path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`);
+        const extractedArtifact = await writeDeterministicJsonArtifact(input.runDir, extractedPatchPath, patch);
+        extractedPatchSha256 = extractedArtifact.sha256;
+        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+        const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+        if (protectedViolations.length > 0)
+            throw new Error(`frontend plan patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+        const merged = applyFrontendContractMergePatch(skeleton, patch);
+        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
+            runDir: input.runDir,
+            contract: merged,
+        });
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
+        await writeReport({
+            classification: "accepted-normalized",
+            normalizedContractPath: path.posix.relative(input.runDir.replaceAll(path.sep, "/"), normalizedArtifact.path.replaceAll(path.sep, "/")),
+            normalizedContractSha256: normalizedArtifact.sha256,
+            normalizationActions: [
+                "apply-runtime-skeleton",
+                ...(droppedUnresolvedSymbols
+                    ? ["drop-unresolved-verification-symbols"]
+                    : []),
+                ...analysis.normalizationActions,
+            ],
+            errors: [],
+        });
+        const canonicalRel = canonicalContractRel(nodeId);
+        const canonicalArtifact = await writeDeterministicJsonArtifact(input.runDir, canonicalRel, analysis.canonical);
+        const parsedCitations = parseOpenspecCitationsBlock(citationsBlock);
+        await writeDeterministicJsonArtifact(input.runDir, openspecCitationsRel(nodeId), {
+            citations: parsedCitations.citations,
+            block: citationsBlock,
+        });
+        await persistRuntimeSkeleton({
+            runDir: input.runDir,
+            nodeId,
+            skeleton,
+        });
+        const artifact = {
+            path: canonicalArtifact.path,
+            sha256: canonicalArtifact.sha256,
+            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+        };
+        return {
+            ok: true,
+            contract: analysis.canonical,
+            artifact,
+            normalizedText: formatStructuredArtifactPointer(artifact),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const classified = classifyStructuredContractFailure({
+            reason,
+            kind: error instanceof FrontendContractFailure ? error.kind : undefined,
+        });
+        await writeReport({
+            classification: classified.classification,
+            normalizationActions: [],
+            errors: classified.errors,
+        });
+        return {
+            ok: false,
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
+        };
+    }
+}
+export async function readFrontendCanonicalCandidate(runDir, nodeId) {
+    const candidatePath = path.join(runDir, canonicalContractRel(nodeId));
+    try {
+        const raw = await readFile(candidatePath, "utf8");
+        const parsed = frontendImplementationContractSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return undefined;
+    }
+}
 /**
  * Node-output self-check for plan nodes that produce the implementation
  * contract. Mirrors the prewrite gate validation so schema/typo/null violations
@@ -1626,51 +1885,121 @@ export async function validateFrontendContractNodeOutput(input) {
         return { ok: true, contract: analysis.canonical };
     }
     catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const classified = classifyStructuredContractFailure({
+            reason,
+            kind: error instanceof FrontendContractFailure ? error.kind : undefined,
+        });
         return {
             ok: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
         };
     }
 }
 /**
- * Node-output self-check for the plan revision node, which emits an RFC 7386
- * merge-patch delta against the original contract instead of a full contract.
- * Deliberately loose and format-level: the output must contain at least one
- * ```openspec-citations fenced block and must extract (after the citations
- * blocks are stripped) to exactly one JSON object. The delta carries no
- * schemaVersion/targets, so no full-contract schema/semantic checks run here;
- * content parsing, patch application, and merged-contract validation stay with
- * the prewrite gate, which remains the only authority.
+ * Node-output self-check for the plan revision node. Format-level checks still
+ * require one openspec-citations fence and one JSON object. When the original
+ * canonical contract and sourceBinding are present, this node is the merge
+ * authority: it applies the RFC 7386 patch, validates the full contract, and
+ * writes the revision node's own hash-bound canonical artifact.
  */
 export async function validateFrontendRevisionPatchNodeOutput(input) {
-    // Mirror the prewrite gate's block-presence semantics (a fenced
-    // ```openspec-citations block with a newline-terminated body).
-    if (!/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/.test(input.text)) {
+    const fail = (reason) => {
+        const classified = classifyStructuredContractFailure({ reason });
         return {
             ok: false,
-            reason: "revision patch output must include at least one ```openspec-citations fenced block",
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
         };
+    };
+    const nodeId = input.nodeId ?? "frontend-plan-revision-pi";
+    const attempt = input.attempt ?? 1;
+    await writeFrontendPlanCandidateRaw({
+        runDir: input.runDir,
+        nodeId,
+        attempt,
+        text: input.text,
+    });
+    let citationsBlock;
+    try {
+        citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
     }
-    // Strip the citation blocks before extraction: their per-row JSON objects
-    // would otherwise count as competing balanced objects in the extractor.
-    const textWithoutCitations = input.text.replace(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g, "");
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+    const textWithoutCitations = input.text.replace(citationsBlock, "");
     let patch;
     try {
         patch = extractFrontendImplementationJson(textWithoutCitations);
     }
     catch (error) {
-        return {
-            ok: false,
-            reason: `revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`,
-        };
+        return fail(`revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+        return fail("revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)");
+    }
+    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+    if (protectedViolations.length > 0) {
+        return fail(`frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+    }
+    const original = (await readFrontendCanonicalCandidate(input.runDir, "frontend-plan-pi")) ??
+        (await readFrontendCanonicalCandidate(input.runDir, nodeId));
+    if (!input.sourceBinding) {
+        return { ok: true, contract: patch };
+    }
+    if (!original) {
+        return fail("frontend revision patch requires the original frontend-plan-pi canonical contract");
+    }
+    try {
+        const merged = applyFrontendContractMergePatch(original, patch);
+        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
+            runDir: input.runDir,
+            contract: merged,
+        });
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        const candidateDir = path.posix.join("contracts", "candidates", nodeId);
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`), patch);
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
+            classification: "accepted-normalized",
+            normalizationActions: [
+                "apply-original-canonical",
+                ...(droppedUnresolvedSymbols
+                    ? ["drop-unresolved-verification-symbols"]
+                    : []),
+                ...analysis.normalizationActions,
+            ],
+            errors: [],
+        });
+        const canonicalArtifact = await writeDeterministicJsonArtifact(input.runDir, canonicalContractRel(nodeId), analysis.canonical);
+        const parsedCitations = parseOpenspecCitationsBlock(citationsBlock);
+        await writeDeterministicJsonArtifact(input.runDir, openspecCitationsRel(nodeId), {
+            citations: parsedCitations.citations,
+            block: citationsBlock,
+        });
+        const artifact = {
+            path: canonicalArtifact.path,
+            sha256: canonicalArtifact.sha256,
+            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+        };
         return {
-            ok: false,
-            reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
+            ok: true,
+            contract: analysis.canonical,
+            artifact,
+            normalizedText: formatStructuredArtifactPointer(artifact),
         };
     }
-    return { ok: true, contract: patch };
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return fail(reason);
+    }
 }
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);