@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.4

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

@@ -8,6 +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 { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
+// Cycle-safe value imports: the check functions are hoisted declarations used
+// only at call time, so the contract module and the policy module can depend
+// on each other without module-init ordering issues.
+import { checkDependencies, checkUiDesignCoverage, checkUiStateAttribution, } from "./frontend-design-policy.js";
+import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, persistRuntimeSkeleton, } from "./structured-output-repair.js";
+import { isConfigurationVerificationFile, verificationSymbolMatchesContent, } from "./frontend-verification-trace.js";
 export const frontendNormalizationActionSchema = z.enum([
     "remove-trailing-commas",
     "strip-comments",
@@ -102,6 +109,39 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     }
     return [...labels];
 }
+/**
+ * Extract the design-policy allowedDependencies set from the DAG run spec
+ * (run.json), mirroring `deriveFrozenCommandLabelsFromRun`. Used by the plan
+ * node's front-loaded policy pre-check so dependency declarations can be
+ * corrected through the retry ladder before the policy shell (the authority)
+ * re-runs the same check on committed facts.
+ */
+async function deriveAllowedDependenciesFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const deps = new Set();
+    for (const task of spec.tasks ?? []) {
+        const allowed = task.shell?.frontendDesignPolicy?.allowedDependencies;
+        if (allowed) {
+            for (const dep of allowed)
+                deps.add(dep);
+        }
+    }
+    return [...deps];
+}
 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";
 /**
@@ -1079,6 +1119,40 @@ function looksLikeStrictFrontendContract(value) {
         asRecord(record.mockApi) !== null &&
         asRecord(record.designEvidence) !== null);
 }
+/**
+ * Single shared completion layer for required-with-fallback contract fields.
+ *
+ * Structural invariant: the coerce normalizer has strict-shape and free-form
+ * branches that reshape differently, but every required key that carries a
+ * deterministic fallback (currently `designEvidence`) must be completed in
+ * exactly ONE place — here — so the branches can never drift again (the
+ * designEvidence Required and invented-uiStates failures both came from
+ * branch-local rules diverging). This layer never invents values that later
+ * refinements reject: it only fills documented fallbacks for keys already
+ * present-but-partial, and is idempotent for already-complete inputs.
+ */
+export function completeCanonicalRequiredFields(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const designEvidence = asRecord(record.designEvidence);
+    if (!designEvidence)
+        return value;
+    const source = asString(designEvidence.source);
+    const paths = Array.isArray(designEvidence.paths);
+    const conflicts = Array.isArray(designEvidence.conflicts);
+    if (source && paths && conflicts)
+        return value;
+    return {
+        ...record,
+        designEvidence: {
+            ...designEvidence,
+            ...(source ? {} : { source: "repository-fallback+task-source" }),
+            ...(paths ? {} : { paths: [] }),
+            ...(conflicts ? {} : { conflicts: [] }),
+        },
+    };
+}
 /**
  * Coerce common free-form plan JSON into frontend-implementation-contract-v1.
  * Near-schema payloads are left untouched so unknown-key fail-closed still holds.
@@ -1183,6 +1257,9 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
                 ...strictRecord,
                 requirements,
                 ...(strictMockApi ? { mockApi: { ...strictMockApi, endpoints: mockEndpoints } } : {}),
+                // Required-with-fallback keys (designEvidence etc.) are completed
+                // by the single shared `completeCanonicalRequiredFields` layer in
+                // the analyze pipeline — never per-branch.
             };
         }
     }
@@ -1231,9 +1308,7 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
             : typeRaw.includes("type")
                 ? "static"
                 : "unit";
-        const commandLabel = asString(vt.commandLabel) ||
-            asString(vt.command) ||
-            (type === "static" ? "npm run typecheck" : "npm run test:unit:fe");
+        const commandLabel = asString(vt.commandLabel) || asString(vt.command);
         const file = asString(vt.file) ||
             (Array.isArray(vt.symbols) ? targetFiles.find((p) => p.includes("__tests__")) : "") ||
             targetFiles.find((p) => p.includes("__tests__")) ||
@@ -1249,7 +1324,11 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
             requirementIds: requirementIds.length > 0
                 ? requirementIds
                 : [...canonicalBinding.requirementIds],
-            uiStates: uiStateNames.length > 0 ? uiStateNames : ["success", "error"],
+            // Never invent UI state references: "success" is not a canonical
+            // state name, so a defaulted ["success","error"] was always rejected
+            // by the schema's unknown-uiState refinement — a verification
+            // target that declares no UI binding stays unbound ([]).
+            uiStates: uiStateNames,
         });
     }
     if (verificationTargets.length === 0) {
@@ -1485,7 +1564,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 {
@@ -1593,8 +1678,9 @@ export async function analyzeFrontendImplementationContract(input) {
     // 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 completedContract = completeCanonicalRequiredFields(normalizedContract);
     const candidate = deriveFrontendVerificationCoverage({
-        ...(asRecord(normalizedContract) ?? parsed),
+        ...(asRecord(completedContract) ?? parsed),
         sourceBinding: canonicalBinding,
     }, canonicalBinding);
     const result = frontendImplementationContractSchema.safeParse(candidate);
@@ -1634,6 +1720,37 @@ const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
     "/targets/files",
     "/mockApi/productionDefaultOff",
 ];
+const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
+    "target-surface",
+    "component-choice",
+    "state-flow",
+    "data-flow",
+    "mock-api",
+    "design-deviation",
+    "dependency",
+];
+/**
+ * Restore the editable RFC 7386 plan patch from a committed plan ledger.
+ * This is the single compile authority for the frontend implementation
+ * contract: the tool payload (`patch` on any committed plan fact) wins over
+ * any narrative JSON in the plan node text.
+ */
+export function restorePlanPatchFromCommittedFacts(records) {
+    const planFacts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => fact.origin === "plan" &&
+        typeof fact.kind === "string" &&
+        PLAN_LEDGER_FACT_KINDS_FOR_COMPILE.includes(fact.kind));
+    if (planFacts.length === 0)
+        return undefined;
+    for (const fact of planFacts) {
+        const patch = fact.patch;
+        if (isPlainObject(patch))
+            return patch;
+    }
+    return undefined;
+}
 function frontendPlanPatchProtectedPathViolations(patch) {
     const record = asRecord(patch);
     if (!record)
@@ -1663,34 +1780,34 @@ function workspaceRootFromDagRunDir(runDir) {
     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;
+        return [];
+    const actions = [];
     for (const targetValue of targets) {
         const target = asRecord(targetValue);
         const file = asString(target?.file);
         const symbol = asString(target?.symbol);
-        if (!target || !file || !symbol)
+        if (!target || !file)
+            continue;
+        // Static targets (project-wide commands such as typecheck/build) verify
+        // by command exit code, never by a per-file symbol. Strip any symbol
+        // the planner attached — including fabricated placeholders like "null"
+        // — so the plan shape check and the verify trace gate never evaluate
+        // it. This is the root fix for the recurring fabricated-symbol error
+        // class: the field was allowed for static, the prompt did not forbid
+        // it, and models habitually fill it; the compiler removes it instead.
+        if (target.type === "static") {
+            if (symbol) {
+                delete target.symbol;
+                if (!actions.includes("strip-static-verification-symbols"))
+                    actions.push("strip-static-verification-symbols");
+            }
+            continue;
+        }
+        if (!symbol)
             continue;
         const absolute = path.resolve(workspaceRoot, file);
         const relative = path.relative(workspaceRoot, absolute);
@@ -1699,6 +1816,10 @@ async function dropUnresolvedVerificationSymbols(input) {
             relative.includes("..")) {
             continue;
         }
+        // Configuration files (tsconfig.json, vite.config.*, ...) do not expose
+        // source symbols; the trace gate skips them, so the drop must too.
+        if (isConfigurationVerificationFile(file))
+            continue;
         let content;
         try {
             content = await readFile(absolute, "utf8");
@@ -1708,65 +1829,78 @@ async function dropUnresolvedVerificationSymbols(input) {
             // changing the optional symbol during candidate normalization.
             continue;
         }
-        if (verificationSymbolMatchesFile(symbol, content))
+        if (verificationSymbolMatchesContent(symbol, content))
             continue;
         delete target.symbol;
-        changed = true;
+        if (!actions.includes("drop-unresolved-verification-symbols"))
+            actions.push("drop-unresolved-verification-symbols");
     }
-    return changed;
-}
-function extractSingleOpenspecCitationsBlock(text, citationsRequired = true) {
-    const blocks = [...text.matchAll(/^```openspec-citations[ \t]*\r?\n([\s\S]*?)^```[ \t]*$/gim)].map((match) => match[0]);
-    if (!citationsRequired) {
-        if (blocks.length === 0)
-            return "";
-        throw new Error("frontend plan output must not include an openspec-citations block when the generation-frozen OpenSpec candidate set is empty");
-    }
-    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];
-}
-/**
- * Frontend plan/revision output has two JSON-bearing regions: the primary
- * payload and line-oriented OpenSpec citations. Keep their parsing domains
- * separate so a citation row can never become a competing contract candidate.
- * A bare JSON payload is retained only for historical node-output compatibility.
- */
-export function extractFrontendPlanPayload(text, options) {
-    const citationsBlock = extractSingleOpenspecCitationsBlock(text, options?.citationsRequired !== false);
-    return {
-        payload: extractFrontendPlanPrimaryPayload(text.replace(citationsBlock, "")),
-        citationsBlock,
-    };
-}
-function extractFrontendPlanPrimaryPayload(text) {
-    const fences = [...text.matchAll(/```json[ \t]*\r?\n([\s\S]*?)\r?\n```/gi)];
-    if (fences.length > 1) {
-        throw new Error(`frontend plan output must contain exactly one primary fenced json payload (found ${fences.length})`);
-    }
-    if (fences.length === 1) {
-        try {
-            return JSON.parse(fences[0][1]);
-        }
-        catch (error) {
-            throw new Error(`frontend plan primary json fence is invalid: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    return extractFrontendImplementationJson(text);
+    return actions;
 }
 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);
+    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 canonical full-contract text for all
+ * prose. A successful result returns a path-only pointer plus the hash-bound canonical artifact for
  * downstream review and prewrite nodes.
  */
+/**
+ * Placeholder tokens that are never valid verification symbols ("null" is the
+ * classic model artifact: it serializes a JS null into the symbol string).
+ */
+const VERIFICATION_SYMBOL_PLACEHOLDERS = new Set([
+    "null",
+    "undefined",
+    "none",
+    "n/a",
+    "na",
+    "tbd",
+    "todo",
+    "...",
+    "?",
+    "-",
+]);
+/** An over-long symbol can never resolve to a real declaration. */
+const VERIFICATION_SYMBOL_MAX_CHARS = 60;
+/**
+ * Deterministic shape check for a verification target symbol. Catches obvious
+ * model fabrication (placeholder tokens, prose fragments) at plan time so the
+ * plan retry ladder can fix the facts in-node instead of the verify trace gate
+ * failing at the very end of the run.
+ *
+ * Deliberately conservative: bare test titles without punctuation ("renders
+ * loading") and `describe(...)` / `it(...)` forms stay valid — a real symbol
+ * may be a function name, a dotted path, or a describe/it title.
+ */
+function isSuspiciousVerificationSymbol(symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed)
+        return false;
+    if (VERIFICATION_SYMBOL_PLACEHOLDERS.has(trimmed.toLowerCase()))
+        return true;
+    if (trimmed.length > VERIFICATION_SYMBOL_MAX_CHARS)
+        return true;
+    // Deliberately conservative: bare test titles with punctuation (e.g.
+    // "adds +1 button") are valid describe/it-style symbols and must pass;
+    // the length + placeholder rules above already catch obvious fabrication
+    // ("null", over-long prose fragments). Everything else is left to the
+    // deterministic drop/trace resolvability check.
+    return false;
+}
+function assertVerificationSymbolShapes(contract) {
+    for (const target of contract.verificationTargets) {
+        if (!target.symbol)
+            continue;
+        if (isSuspiciousVerificationSymbol(target.symbol)) {
+            throw new Error(`frontend plan verification target "${target.id}" declares a fabricated symbol "${target.symbol}" for ${target.file}; fix it to a real symbol present in that file or leave the symbol empty (the deterministic trace gate verifies symbol resolvability after verification)`);
+        }
+    }
+}
 export async function validateFrontendPlanPatchNodeOutput(input) {
     const nodeId = input.nodeId ?? "frontend-plan-pi";
     const attempt = input.attempt ?? 1;
@@ -1803,22 +1937,18 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
         const skeleton = input.structuredContractOutput?.skeleton;
         if (!skeleton)
             throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
-        // Preserve the raw primary candidate even if the separately parsed
-        // citation fence is malformed; the retry report is an audit artifact.
-        const patch = extractFrontendPlanPrimaryPayload(input.text);
+        const committed = await readTypedEventStoreFromJsonl(path.join(input.runDir, nodeId, "plan-typed-facts.jsonl"));
+        const patch = restorePlanPatchFromCommittedFacts(committed);
         if (!isPlainObject(patch))
-            throw new Error("frontend plan patch must extract to one JSON object");
+            throw new Error("frontend plan ledger missing: no committed origin=plan facts (record_* + finalize_plan); narrative JSON is not the compile authority");
         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, input.structuredContractOutput?.citationsRequired !== false);
-        const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
-        await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
         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({
+        const symbolNormalizationActions = await dropUnresolvedVerificationSymbols({
             runDir: input.runDir,
             contract: merged,
         });
@@ -1827,6 +1957,23 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
         });
+        // Front-load the verification-symbol shape check so fabricated symbols
+        // are fixed by the plan retry ladder in-node instead of failing the
+        // verify trace gate at the end of the run.
+        assertVerificationSymbolShapes(analysis.canonical);
+        // Front-load the plan-attributable design-policy checks so the §5.1
+        // retry ladder can fix these facts in-node with diagnostics instead of
+        // the run terminating at the policy shell. The policy shell remains the
+        // final authority and re-runs the identical checks on committed facts.
+        const policyPreFindings = [
+            ...checkUiDesignCoverage(analysis.canonical),
+            ...checkUiStateAttribution(analysis.canonical),
+            ...checkDependencies(analysis.canonical, await deriveAllowedDependenciesFromRun(input.runDir)),
+        ];
+        if (policyPreFindings.length > 0)
+            throw new Error(`frontend plan policy pre-check failed (fix these plan facts, then re-commit and finalize): ${policyPreFindings
+                .map((finding) => `${finding.code}: ${finding.message}`)
+                .join("; ")}`);
         const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
         await writeReport({
             classification: "accepted-normalized",
@@ -1834,47 +1981,60 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             normalizedContractSha256: normalizedArtifact.sha256,
             normalizationActions: [
                 "apply-runtime-skeleton",
-                ...(droppedUnresolvedSymbols
-                    ? ["drop-unresolved-verification-symbols"]
-                    : []),
+                ...symbolNormalizationActions,
                 ...analysis.normalizationActions,
             ],
             errors: [],
         });
+        const canonicalRel = canonicalContractRel(nodeId);
+        const canonicalArtifact = await writeDeterministicJsonArtifact(input.runDir, canonicalRel, analysis.canonical);
+        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,
-            structuredArtifact: {
-                path: normalizedArtifact.path,
-                sha256: normalizedArtifact.sha256,
-                schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
-            },
-            frontendPlanOutput: {
-                schemaVersion: 1,
-                payloadKind: "canonical-contract",
-                citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
-                citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
-                rawCandidatePath: path.join(input.runDir, rawPath),
-                rawCandidateSha256: sha256Hex(input.text),
-            },
-            normalizedText: [
-                "Frontend implementation contract compiled from the runtime skeleton.",
-                "",
-                "```json",
-                serializeDeterministicJson(analysis.canonical),
-                "```",
-                citationsBlock,
-            ].join("\n"),
+            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: "retryable-invalid",
+            classification: classified.classification,
             normalizationActions: [],
-            errors: [{ path: "$", code: "invalid-output", message: reason }],
+            errors: classified.errors,
         });
-        return { ok: false, reason };
+        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;
     }
 }
 /**
@@ -1895,82 +2055,140 @@ 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: when OpenSpec candidates exist, the
- * output contains exactly one ```openspec-citations fenced block; otherwise it
- * contains no citation fence. It must extract (after the citations block is
- * 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.
+ * Deterministically assemble the canonical frontend implementation contract
+ * from committed typed facts, never from plan/contract node text.
+ *
+ * Inputs (all read-only, all fail-closed):
+ * - `<planNodeId>/plan-typed-facts.jsonl` (phase=committed) restores the
+ *   editable RFC 7386 patch;
+ * - `<contractNodeId>/contract-typed-facts.jsonl` (phase=committed) must carry
+ *   a `contract-finalized` terminal fact;
+ * - `<contractNodeId>/frontend-task-contract-vNext.json` must exist and parse.
+ *
+ * The patch is applied onto the runtime skeleton and re-validated through the
+ * same `analyzeFrontendImplementationContract` pipeline used by the legacy
+ * text path, so the downstream artifact semantics are unchanged. The function
+ * is pure: it never writes candidate/audit artifacts and always produces the
+ * same canonical serialization for the same committed facts. It never falls
+ * back to parsing Plan/Contract node text.
  */
-export async function validateFrontendRevisionPatchNodeOutput(input) {
-    const nodeId = input.nodeId ?? "frontend-plan-revision-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,
-    });
-    let citationsBlock;
-    let patch;
+export async function buildContractFromCommittedFacts(input) {
+    const contractNodeId = input.contractNodeId ?? "frontend-contract-pi";
+    // Skeleton guard: the runtime skeleton must carry the protected identity
+    // fields so the merged contract can be validated against the full schema.
+    const skeletonRecord = asRecord(input.skeleton);
+    const skeletonTargets = asRecord(skeletonRecord?.targets);
+    const skeletonRiskLevel = asString(skeletonRecord?.riskLevel);
+    if (!skeletonRecord ||
+        !["small", "standard", "high-risk"].includes(skeletonRiskLevel) ||
+        !Array.isArray(skeletonTargets?.files) ||
+        skeletonTargets.files.length === 0) {
+        return {
+            ok: false,
+            reason: "frontend contract skeleton missing required runtime fields (riskLevel/targets.files)",
+            failureCode: "missing-skeleton",
+        };
+    }
+    // a. Committed plan ledger restores the editable patch.
+    const planRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.planNodeId, "plan-typed-facts.jsonl"));
+    const patch = restorePlanPatchFromCommittedFacts(planRecords);
+    if (!isPlainObject(patch)) {
+        return {
+            ok: false,
+            reason: "frontend plan ledger missing: no committed origin=plan facts (record_* + finalize_plan); narrative JSON is not the compile authority",
+            failureCode: "missing-plan-ledger",
+        };
+    }
+    // b. Committed contract terminal fact (contract-finalized).
+    const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, contractNodeId, "contract-typed-facts.jsonl"));
+    const contractKinds = new Set(contractRecords
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact.kind)
+        .filter((kind) => typeof kind === "string"));
+    if (!contractKinds.has("contract-finalized")) {
+        return {
+            ok: false,
+            reason: "frontend contract facts missing: no committed contract-finalized terminal fact",
+            failureCode: "missing-contract-finalize",
+        };
+    }
+    // c. frontend-task-contract-vNext.json must exist and parse (input integrity).
+    let rawVNext;
     try {
-        const parsed = extractFrontendPlanPayload(input.text, {
-            citationsRequired: input.structuredContractOutput?.citationsRequired,
-        });
-        citationsBlock = parsed.citationsBlock;
-        patch = parsed.payload;
+        rawVNext = await readFile(path.join(input.runDir, contractNodeId, "frontend-task-contract-vNext.json"), "utf8");
+    }
+    catch {
+        return {
+            ok: false,
+            reason: `frontend task contract vNext missing at ${contractNodeId}/frontend-task-contract-vNext.json`,
+            failureCode: "contract-vnext-missing",
+        };
+    }
+    try {
+        JSON.parse(rawVNext);
     }
     catch (error) {
         return {
             ok: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: `frontend task contract vNext is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "contract-vnext-invalid",
         };
     }
-    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    // d. Merge the editable patch onto the protected skeleton and validate.
+    let merged;
+    try {
+        merged = applyFrontendContractMergePatch(input.skeleton, patch);
+    }
+    catch (error) {
         return {
             ok: false,
-            reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
+            reason: `frontend contract patch could not be applied to the runtime skeleton: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "schema-drift",
+        };
+    }
+    // The design-policy shell is the authoritative materializer of the
+    // canonical contract; keep it on the same unresolved-symbol drop as the
+    // plan validator so the verify trace gate never sees fabricated symbols.
+    await dropUnresolvedVerificationSymbols({
+        runDir: input.runDir,
+        contract: merged,
+    });
+    try {
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        return {
+            ok: true,
+            canonical: analysis.canonical,
+            normalizationActions: analysis.normalizationActions,
+            candidateJsonSha256: analysis.candidateJsonSha256,
         };
     }
-    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
-    if (protectedViolations.length > 0) {
+    catch (error) {
+        const failureKind = error instanceof FrontendContractFailure ? error.kind : undefined;
         return {
             ok: false,
-            reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
+            reason: `frontend contract schema drift: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "schema-drift",
+            ...(failureKind ? { failureKind } : {}),
         };
     }
-    const payloadPath = path.posix.join(candidateDir, `attempt-${attempt}.patch.json`);
-    const payloadArtifact = await writeDeterministicJsonArtifact(input.runDir, payloadPath, patch);
-    const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
-    await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
-    return {
-        ok: true,
-        contract: patch,
-        structuredArtifact: {
-            path: payloadArtifact.path,
-            sha256: payloadArtifact.sha256,
-            schemaId: "frontend-implementation-contract-revision-patch-v1",
-        },
-        frontendPlanOutput: {
-            schemaVersion: 1,
-            payloadKind: "merge-patch",
-            citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
-            citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
-            rawCandidatePath: path.join(input.runDir, rawPath),
-            rawCandidateSha256: sha256Hex(input.text),
-        },
-    };
 }
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);