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

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

@@ -0,0 +1,1911 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+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",
+    "drop-unresolved-verification-symbols",
+    "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
+ * when the prewrite gate materializes the contract.
+ */
+async function deriveFrozenCommandLabelsFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        // run.json is guaranteed to exist in production (DAG runner writes it
+        // before any node executes). When absent (e.g. test fixtures), there is
+        // no frozen set to validate against and the check is skipped downstream.
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`cannot derive frozen command labels: run.json is not valid JSON at ${specPath}: ${error.message}`);
+    }
+    const labels = new Set();
+    for (const task of spec.tasks ?? []) {
+        const cmdLabels = task.shell?.verifyEvidence?.commandLabels;
+        if (cmdLabels) {
+            for (const label of cmdLabels)
+                labels.add(label);
+        }
+    }
+    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
+ * works from both the source module and the compiled dist module without
+ * relying on CommonJS globals in the ESM runtime.
+ *
+ * Validation is fail-closed: missing file, malformed JSON, mismatched $id,
+ * missing additionalProperties: false, or incomplete top-level required keys
+ * all throw before any DAG prompt is assembled.
+ */
+export function loadFrontendImplementationContractJsonSchema(startDir = path.dirname(fileURLToPath(import.meta.url))) {
+    const packageRoot = findPackageRoot(startDir);
+    if (!packageRoot) {
+        throw new Error(`cannot locate loop-agent package root from ${path.resolve(startDir)}`);
+    }
+    const schemaPath = path.join(packageRoot, "docs", "templates", "frontend-implementation-contract.schema.json");
+    let content;
+    try {
+        content = readFileSync(schemaPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`cannot load frontend-implementation-contract.schema.json from current loop-agent package at ${schemaPath}: ${error.code ?? String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`frontend-implementation-contract.schema.json is not valid JSON: ${error.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new Error("frontend-implementation-contract.schema.json root is not a JSON object");
+    }
+    const schema = parsed;
+    if (schema.$id !== FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID) {
+        throw new Error(`schema $id mismatch: expected ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID}, got ${String(schema.$id)}`);
+    }
+    if (schema.additionalProperties !== false) {
+        throw new Error("schema must have additionalProperties: false at top level");
+    }
+    const expectedRequired = [
+        "schemaVersion",
+        "sourceBinding",
+        "riskLevel",
+        "targets",
+        "requirements",
+        "uiStates",
+        "interactions",
+        "mockApi",
+        "designEvidence",
+        "verificationTargets",
+        "evidenceGaps",
+    ];
+    const actualRequired = Array.isArray(schema.required) ? schema.required : [];
+    const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
+    if (missing.length > 0) {
+        throw new Error(`schema required fields missing: ${missing.join(", ")}`);
+    }
+    const properties = schema.properties && typeof schema.properties === "object"
+        ? schema.properties
+        : {};
+    const missingProperties = expectedRequired.filter((key) => !Object.hasOwn(properties, key));
+    if (missingProperties.length > 0) {
+        throw new Error(`schema properties missing: ${missingProperties.join(", ")}`);
+    }
+    const schemaVersion = properties.schemaVersion;
+    const mockApi = properties.mockApi;
+    const mockApiProperties = mockApi?.properties;
+    const productionDefaultOff = mockApiProperties?.productionDefaultOff;
+    if (schemaVersion?.const !== 1 || productionDefaultOff?.const !== true) {
+        throw new Error("schema fixed values are incomplete: schemaVersion.const must be 1 and mockApi.productionDefaultOff.const must be true");
+    }
+    return JSON.stringify(parsed);
+}
+const id = z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/);
+const REQUIREMENT_ID_PATTERN = /^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/;
+const safePath = z
+    .string()
+    .min(1)
+    .refine((value) => !value.startsWith("/") &&
+    !value.includes("\\") &&
+    !value.split("/").includes(".."), "must be a relative POSIX path without traversal");
+const gap = z
+    .object({
+    requirementId: id.optional(),
+    description: z.string().min(1),
+    blocking: z.boolean(),
+})
+    .strict();
+/**
+ * Structured component/token selection contract (ADR 0016). Every user-visible
+ * UI purpose the plan touches must be declared here so the prewrite gate can
+ * deterministically cross-check that the selection comes from the frontend
+ * specification (openspec/ai_workspace component + theme specs) instead of
+ * relying on design-review's soft model judgment.
+ *
+ * - `specified`: the frontend spec mandates this component for the purpose →
+ *   `specReference` is required (path/section/line hit).
+ * - `reuse-existing`: reuse an existing repo component/convention not named by
+ *   the spec → `specReference` may be null, rationale explains the basis.
+ * - `new`: neither spec nor existing code fits → `specReference` must be null,
+ *   rationale must declare the deviation (design-review approves it).
+ *
+ * `specReference` is nullable + optional because `stripNullValuesDeep` strips
+ * null object values before validation, so a `new` choice's `specReference:
+ * null` becomes an absent field; the superRefine below treats absent and null
+ * identically.
+ */
+const uiComponentSpecReferenceSchema = z
+    .object({
+    path: safePath,
+    section: z.string(),
+    line: z.number().int().nullable().optional(),
+})
+    .strict();
+const uiComponentChoiceSchema = z
+    .object({
+    purpose: z.string().min(1),
+    component: z.string().min(1),
+    decision: z.enum(["specified", "reuse-existing", "new"]),
+    specReference: uiComponentSpecReferenceSchema.nullable().optional(),
+    rationale: z.string().min(1),
+})
+    .strict();
+const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
+/**
+ * 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
+        .object({
+        taskId: z.string().min(1),
+        requirementPath: safePath,
+        requirementSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        referencePaths: z.array(safePath),
+        requirementIds: z.array(id),
+    })
+        .strict(),
+    riskLevel: z.enum(["small", "standard", "high-risk"]),
+    targets: z
+        .object({
+        files: z.array(safePath).min(1),
+        routes: z.array(z.string().startsWith("/")).optional(),
+        publicApiChanges: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+    requirements: z.array(z
+        .object({
+        id,
+        expectedOutcome: z.string().min(1),
+        implementationTargets: z.array(safePath),
+        verificationTargetIds: z.array(z.string().min(1)),
+        evidenceGap: gap.optional(),
+    })
+        .strict()).min(1),
+    uiStates: z.array(z
+        .object({
+        name: z.string().min(1),
+        applicable: z.boolean(),
+        expectedBehavior: z.string().min(1).optional(),
+        implementationTargets: z.array(safePath).optional(),
+        verificationTargetIds: z.array(z.string().min(1)).optional(),
+        notApplicableReason: z.string().min(1).optional(),
+    })
+        .strict()),
+    interactions: z.array(z
+        .object({
+        name: z.string().min(1),
+        trigger: z.string().min(1),
+        expectedBehavior: z.string().min(1),
+        implementationTargets: z.array(safePath),
+        verificationTargetIds: z.array(z.string().min(1)),
+    })
+        .strict()),
+    mockApi: z
+        .object({
+        strategy: z.enum([
+            "native",
+            "browser-intercept",
+            "request-adapter",
+            "not-needed",
+        ]),
+        productionDefaultOff: z.literal(true),
+        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([
+                "GET",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "HEAD",
+                "OPTIONS",
+            ]),
+            path: z.string().startsWith("/"),
+            // Models occasionally emit an empty fixture when Mock is
+            // intentionally not needed. Treat it like an omitted optional
+            // field; active Mock strategies still fail the refinement below.
+            fixture: z.preprocess((value) => (value === "" || value === null ? undefined : value), safePath.optional()),
+            consumer: safePath.optional(),
+        })
+            .strict()),
+    })
+        .strict(),
+    designEvidence: z
+        .object({
+        source: z.string().min(1),
+        paths: z.array(safePath),
+        conflicts: z.array(z.string().min(1)),
+    })
+        .strict(),
+    verificationTargets: z.array(z
+        .object({
+        id: z.string().min(1),
+        type: z.enum(["static", "unit", "component", "integration", "mock"]),
+        commandLabel: z.string().min(1),
+        file: safePath,
+        symbol: z.preprocess((value) => (value === "" || value === null ? undefined : value), z.string().min(1).optional()),
+        requirementIds: z.array(id),
+        uiStates: z.array(z.string().min(1)),
+    })
+        .strict()).min(1),
+    evidenceGaps: z.array(gap),
+    implementationSteps: z.array(z.string().min(1)).optional(),
+    stylingStrategy: z.string().min(1).optional(),
+    uiComponentChoices: uiComponentChoicesSchema.optional(),
+    dependencyPolicy: z.string().min(1).optional(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+    realIntegrationGap: z.string().min(1).optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const verificationIds = value.verificationTargets.map((target) => target.id);
+    if (new Set(verificationIds).size !== verificationIds.length)
+        ctx.addIssue({
+            code: "custom",
+            message: "duplicate verification target id",
+            path: ["verificationTargets"],
+        });
+    const known = new Set(value.sourceBinding.requirementIds);
+    const stateNames = new Set(value.uiStates.map((state) => state.name));
+    for (const target of value.verificationTargets) {
+        // Verification evidence may point to read-only project files such as
+        // tsconfig.json or a test entrypoint; implementation targets remain
+        // governed by targets.files and the writer writeSet.
+        for (const requirementId of target.requirementIds) {
+            if (!known.has(requirementId)) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `verification target references unknown requirement ${requirementId}`,
+                    path: ["verificationTargets"],
+                });
+            }
+        }
+        for (const stateName of target.uiStates) {
+            if (!stateNames.has(stateName)) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `verification target references unknown UI state ${stateName}`,
+                    path: ["verificationTargets"],
+                });
+            }
+        }
+    }
+    for (const requirement of value.requirements) {
+        if (!known.has(requirement.id))
+            ctx.addIssue({
+                code: "custom",
+                message: "unknown requirement id",
+                path: ["requirements"],
+            });
+        if ((!requirement.implementationTargets.length ||
+            !requirement.verificationTargetIds.length) &&
+            !requirement.evidenceGap)
+            ctx.addIssue({
+                code: "custom",
+                message: "requirement needs targets or evidenceGap",
+                path: ["requirements"],
+            });
+        for (const targetId of requirement.verificationTargetIds)
+            if (!verificationIds.includes(targetId))
+                ctx.addIssue({
+                    code: "custom",
+                    message: `unknown verification target ${targetId}`,
+                    path: ["requirements"],
+                });
+    }
+    for (const state of value.uiStates) {
+        if (state.applicable &&
+            (!state.expectedBehavior ||
+                !state.implementationTargets?.length ||
+                !state.verificationTargetIds?.length))
+            ctx.addIssue({
+                code: "custom",
+                message: "applicable UI state requires behavior, implementation, and verification",
+                path: ["uiStates"],
+            });
+        if (!state.applicable && !state.notApplicableReason)
+            ctx.addIssue({
+                code: "custom",
+                message: "non-applicable UI state requires reason",
+                path: ["uiStates"],
+            });
+    }
+    for (const [index, choice] of (value.uiComponentChoices ?? []).entries()) {
+        if (choice.decision === "specified") {
+            if (!choice.specReference || !choice.specReference.path) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "specified component choice requires a non-empty specReference.path",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+        else if (choice.decision === "new") {
+            if (choice.specReference) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "new component choice must not carry a specReference",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+    }
+    if (value.mockApi.strategy !== "not-needed") {
+        if (value.mockApi.endpoints.length === 0) {
+            ctx.addIssue({
+                code: "custom",
+                message: "Mock strategy requires at least one endpoint",
+                path: ["mockApi", "endpoints"],
+            });
+        }
+        value.mockApi.endpoints.forEach((endpoint, index) => {
+            if (!endpoint.fixture) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "Mock endpoint requires a fixture path",
+                    path: ["mockApi", "endpoints", index, "fixture"],
+                });
+            }
+            if (!endpoint.consumer) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "Mock endpoint requires a consumer path",
+                    path: ["mockApi", "endpoints", index, "consumer"],
+                });
+            }
+            for (const [field, file] of [["fixture", endpoint.fixture], ["consumer", endpoint.consumer]]) {
+                if (file && !value.targets.files.some((pattern) => pathMatchesPattern(file, pattern))) {
+                    ctx.addIssue({
+                        code: "custom",
+                        message: `Mock ${field} is outside contract targets: ${file}`,
+                        path: ["mockApi", "endpoints", index, field],
+                    });
+                }
+            }
+        });
+    }
+}));
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Apply an RFC 7386 merge-patch on a target contract without mutating it.
+ * `null` removes the key; plain objects merge recursively when the target value
+ * is also a plain object; arrays and scalars replace the whole value. The
+ * result is re-validated by analyzeFrontendImplementationContract before it is
+ * ever materialized, so a patch that removes a required field still fails
+ * closed at the gate.
+ */
+export function applyFrontendContractMergePatch(target, patch) {
+    if (!isPlainObject(patch)) {
+        throw new Error("frontend contract patch must be a JSON object");
+    }
+    const merge = (base, delta) => {
+        if (delta === null)
+            return undefined;
+        if (!isPlainObject(delta))
+            return delta;
+        const result = isPlainObject(base)
+            ? { ...base }
+            : {};
+        for (const [key, value] of Object.entries(delta)) {
+            if (value === null) {
+                delete result[key];
+            }
+            else if (isPlainObject(value) && isPlainObject(result[key])) {
+                result[key] = merge(result[key], value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
+    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({
+            workspaceRoot: input.workspaceRoot,
+            taskId: input.binding.taskId,
+            sourcePath: source.path,
+        });
+        let content;
+        try {
+            content = await readFile(absolute);
+            const info = await stat(absolute);
+            if (!info.isFile())
+                throw new Error("not a regular file");
+        }
+        catch (error) {
+            throw new Error(`frontend source binding file unavailable: ${source.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const actual = createHash("sha256").update(content).digest("hex");
+        if (actual !== source.sha256) {
+            throw new Error(`frontend source binding is stale: ${source.path}`);
+        }
+    }
+}
+const SECRET_KEY = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential|authorization)/i;
+const SECRET_VALUE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|ghp|github_pat|xox[baprs]|AKIA)[-_A-Za-z0-9]{12,}\b)/;
+function secretIssues(value, at = "$", issues = []) {
+    if (typeof value === "string" && SECRET_VALUE.test(value))
+        issues.push(`${at}: secret-like value is forbidden`);
+    if (Array.isArray(value))
+        value.forEach((child, index) => secretIssues(child, `${at}[${index}]`, issues));
+    else if (value && typeof value === "object")
+        for (const [key, child] of Object.entries(value)) {
+            if (SECRET_KEY.test(key))
+                issues.push(`${at}.${key}: secret-shaped field name is forbidden`);
+            secretIssues(child, `${at}.${key}`, issues);
+        }
+    return issues;
+}
+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);
+        }
+        catch (error) {
+            // Apply only deterministic, structure-preserving repairs before the
+            // quote repair below. These are common JSONC/model formatting defects,
+            // not a general parser relaxation.
+            const withoutComments = source
+                .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);
+            }
+            catch {
+                // Continue with the narrower embedded-quote repair.
+            }
+            // Models sometimes put ordinary ASCII quotes inside a JSON string
+            // (for example: `reason: "支持..."`). Repair only quotes that are
+            // clearly not structural: a closing quote is followed by JSON
+            // punctuation, while an embedded quote is followed by content.
+            let repaired = "";
+            let inString = false;
+            let escaped = false;
+            for (let index = 0; index < source.length; index += 1) {
+                const character = source[index];
+                if (character !== '"') {
+                    repaired += character;
+                    if (inString && character === "\\" && !escaped)
+                        escaped = true;
+                    else
+                        escaped = false;
+                    continue;
+                }
+                if (escaped) {
+                    repaired += character;
+                    escaped = false;
+                    continue;
+                }
+                if (!inString) {
+                    inString = true;
+                    repaired += character;
+                    continue;
+                }
+                const next = source.slice(index + 1).trimStart()[0];
+                if ([",", "}", "]", ":"].includes(next ?? "") || source.slice(index + 1).trim() === "") {
+                    inString = false;
+                    repaired += character;
+                }
+                else {
+                    repaired += "\\\"";
+                }
+            }
+            try {
+                return JSON.parse(repaired);
+            }
+            catch {
+                throw error;
+            }
+        }
+    };
+    const isContract = (candidate) => {
+        const record = asRecord(candidate);
+        return (record?.schemaVersion === 1 &&
+            asRecord(record.targets) !== null &&
+            Array.isArray(record.requirements) &&
+            Array.isArray(record.verificationTargets));
+    };
+    if (trimmed.startsWith("{") && trimmed.endsWith("}"))
+        return { value: parse(trimmed), actions };
+    const balancedObjects = [];
+    for (let start = 0; start < trimmed.length; start += 1) {
+        if (trimmed[start] !== "{")
+            continue;
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let index = start; index < trimmed.length; index += 1) {
+            const character = trimmed[index];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (character === "\\")
+                    escaped = true;
+                else if (character === '"')
+                    inString = false;
+                continue;
+            }
+            if (character === '"')
+                inString = true;
+            else if (character === "{")
+                depth += 1;
+            else if (character === "}" && --depth === 0) {
+                try {
+                    const candidate = parse(trimmed.slice(start, index + 1));
+                    if (candidate && typeof candidate === "object" && !Array.isArray(candidate))
+                        balancedObjects.push(candidate);
+                }
+                catch {
+                    // Continue scanning for a later complete JSON object.
+                }
+                break;
+            }
+        }
+    }
+    const balancedContracts = balancedObjects.filter(isContract);
+    if (balancedContracts.length === 1)
+        return { value: balancedContracts[0], actions };
+    if (balancedObjects.length === 1)
+        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");
+    const candidates = [];
+    for (const block of blocks) {
+        try {
+            const candidate = parse(block[1]);
+            if (candidate && typeof candidate === "object" && !Array.isArray(candidate))
+                candidates.push(candidate);
+        }
+        catch {
+            // Ignore incomplete model scratch blocks. A later complete contract
+            // block may still be deterministically recoverable.
+        }
+    }
+    const contractCandidates = candidates.filter(isContract);
+    if (contractCandidates.length === 1)
+        return { value: contractCandidates[0], actions };
+    if (candidates.length === 1)
+        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
+ * gate overwrites whatever the model emitted so identity cannot drift.
+ */
+export function canonicalFrontendContractSourceBinding(binding) {
+    const requirement = binding.sources.find((source) => source.kind === "requirement");
+    if (!requirement)
+        throw new Error("frontend implementation contract gate requires a requirement source in DAG sourceBinding");
+    return {
+        taskId: binding.taskId,
+        requirementPath: requirement.path,
+        requirementSha256: requirement.sha256,
+        referencePaths: binding.sources
+            .filter((source) => source.kind === "reference")
+            .map((source) => source.path)
+            .sort(),
+        requirementIds: binding.requirementIds.map(canonicalizeRequirementId),
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => asString(item))
+        .filter((item) => item.length > 0);
+}
+/**
+ * Pass structured component choices through the free-form compatibility
+ * branch. The strict-shape branch already spreads unknown fields, so only this
+ * explicit constructor needs to re-emit `uiComponentChoices`; a missing/empty
+ * array normalizes to undefined (absent) so the optional schema field stays
+ * compatible with legacy free-form contracts.
+ */
+function normalizeUiComponentChoices(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    return value;
+}
+function normalizeFrontendRoute(value) {
+    const route = asString(value).replaceAll("\\", "/").replace(/^\/+/, "");
+    if (!route || route === "." || route.split("/").includes(".."))
+        return null;
+    return `/${route}`;
+}
+function normalizeFrontendContractOptionalFields(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const targets = asRecord(record.targets);
+    const mockApi = asRecord(record.mockApi);
+    return {
+        ...record,
+        ...(targets
+            ? {
+                targets: {
+                    ...targets,
+                    routes: Array.isArray(targets.routes)
+                        ? targets.routes.map(normalizeFrontendRoute).filter((route) => Boolean(route))
+                        : targets.routes,
+                },
+            }
+            : {}),
+        ...(mockApi
+            ? {
+                mockApi: {
+                    ...mockApi,
+                    endpoints: Array.isArray(mockApi.endpoints)
+                        ? mockApi.endpoints.map((item) => {
+                            const endpoint = asRecord(item);
+                            if (!endpoint)
+                                return item;
+                            return {
+                                ...endpoint,
+                                fixture: asString(endpoint.fixture) || undefined,
+                                consumer: asString(endpoint.consumer) || undefined,
+                            };
+                        })
+                        : mockApi.endpoints,
+                },
+            }
+            : {}),
+    };
+}
+function isRequirementId(value) {
+    return REQUIREMENT_ID_PATTERN.test(value);
+}
+/** Normalize the compact IDs models commonly emit (for example AC1) before
+ * strict schema validation. This keeps governance strict while making the
+ * boundary tolerant of presentation-only formatting differences. */
+function canonicalizeRequirementId(value) {
+    const trimmed = value.trim().toUpperCase();
+    if (REQUIREMENT_ID_PATTERN.test(trimmed))
+        return trimmed;
+    const compact = /^(REQ|BR|AC)(\d+)$/.exec(trimmed);
+    if (compact)
+        return `${compact[1]}-${compact[2]}`;
+    return value;
+}
+function canonicalizeRequirementIdsInPayload(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeRequirementIdsInPayload);
+    if (!value || typeof value !== "object")
+        return value;
+    const record = value;
+    const out = {};
+    for (const [key, child] of Object.entries(record)) {
+        if (key === "id" || key === "requirementId") {
+            out[key] = typeof child === "string" ? canonicalizeRequirementId(child) : child;
+        }
+        else if (key === "requirementIds" && Array.isArray(child)) {
+            out[key] = child.map((item) => typeof item === "string" ? canonicalizeRequirementId(item) : item);
+        }
+        else {
+            out[key] = canonicalizeRequirementIdsInPayload(child);
+        }
+    }
+    return out;
+}
+function canonicalizeVerificationTargetAliases(value) {
+    const record = asRecord(value);
+    if (!record || !Array.isArray(record.verificationTargets))
+        return value;
+    const targets = record.verificationTargets
+        .map((item) => asRecord(item))
+        .filter((item) => Boolean(item));
+    const aliases = new Map();
+    for (const target of targets) {
+        const id = asString(target.id);
+        const label = asString(target.commandLabel).toLowerCase();
+        if (!id)
+            continue;
+        aliases.set(id.toLowerCase(), id);
+        if (label.includes("typecheck"))
+            aliases.set("vt-typecheck", id);
+        if (label.includes("unified surface"))
+            aliases.set("vt-unified-surface", id);
+    }
+    const requirements = Array.isArray(record.requirements)
+        ? record.requirements.map((item) => {
+            const requirement = asRecord(item);
+            if (!requirement || !Array.isArray(requirement.verificationTargetIds))
+                return item;
+            return {
+                ...requirement,
+                verificationTargetIds: requirement.verificationTargetIds.map((id) => typeof id === "string" ? aliases.get(id.toLowerCase()) ?? id : id),
+            };
+        })
+        : record.requirements;
+    return { ...record, requirements };
+}
+/**
+ * Model-written evidence gaps are hypotheses, not authoritative coverage
+ * facts. If the plan contains a real verification target that explicitly
+ * names a requirement, the executor can prove that the requirement has a
+ * verification path even when the model forgot to wire the target into the
+ * requirement entry or conservatively marked its gap as blocking.
+ *
+ * Keep gaps blocking when that proof cannot be derived. This is deliberately
+ * narrow: it uses only sourceBinding requirement IDs and structurally present
+ * verification targets, and never invents a command, file, or target.
+ */
+function deriveFrontendVerificationCoverage(value, canonicalBinding) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const rawTargets = Array.isArray(record.verificationTargets)
+        ? record.verificationTargets
+        : [];
+    const targetIds = new Set(rawTargets
+        .map((item) => asRecord(item))
+        .filter((item) => Boolean(item))
+        .map((item) => asString(item.id))
+        .filter(Boolean));
+    const targetIdsByRequirement = new Map();
+    for (const item of rawTargets) {
+        const target = asRecord(item);
+        if (!target)
+            continue;
+        const targetId = asString(target.id);
+        const commandLabel = asString(target.commandLabel) || asString(target.command);
+        const file = asString(target.file);
+        // A target is usable evidence only when it has an identity, command and
+        // file. The strict schema will validate the final shape afterwards.
+        if (!targetId || !commandLabel || !file)
+            continue;
+        const targetRequirementIds = asStringArray(target.requirementIds);
+        const inferredRequirementIds = targetRequirementIds.length > 0
+            ? targetRequirementIds
+            : rawTargets.length === 1
+                ? canonicalBinding.requirementIds
+                : [];
+        for (const requirementId of inferredRequirementIds) {
+            const canonicalId = canonicalizeRequirementId(requirementId);
+            if (!canonicalBinding.requirementIds.includes(canonicalId))
+                continue;
+            const ids = targetIdsByRequirement.get(canonicalId) ?? [];
+            if (!ids.includes(targetId))
+                ids.push(targetId);
+            targetIdsByRequirement.set(canonicalId, ids);
+        }
+    }
+    const provenRequirementIds = new Set(targetIdsByRequirement.keys());
+    const requirements = Array.isArray(record.requirements)
+        ? record.requirements.map((item) => {
+            const requirement = asRecord(item);
+            if (!requirement)
+                return item;
+            const requirementId = canonicalizeRequirementId(asString(requirement.id));
+            const inferredTargetIds = targetIdsByRequirement.get(requirementId) ?? [];
+            const existingTargetIds = asStringArray(requirement.verificationTargetIds)
+                .filter((id) => targetIds.has(id));
+            const verificationTargetIds = [...new Set([
+                    ...existingTargetIds,
+                    ...inferredTargetIds,
+                ])];
+            const evidenceGap = asRecord(requirement.evidenceGap);
+            const hasProof = provenRequirementIds.has(requirementId);
+            return {
+                ...requirement,
+                ...(verificationTargetIds.length > 0 ? { verificationTargetIds } : {}),
+                ...(hasProof
+                    ? (evidenceGap ? { evidenceGap: { ...evidenceGap, blocking: false } } : {})
+                    : {
+                        evidenceGap: {
+                            requirementId,
+                            description: `No executable verification target can be derived for ${requirementId}`,
+                            blocking: true,
+                        },
+                    }),
+            };
+        })
+        : record.requirements;
+    const modelEvidenceGaps = Array.isArray(record.evidenceGaps)
+        ? record.evidenceGaps.map((item) => {
+            const gap = asRecord(item);
+            if (!gap)
+                return item;
+            const requirementId = canonicalizeRequirementId(asString(gap.requirementId));
+            // Model gaps are advisory. Blocking status is reconstructed below
+            // from the source binding and executable verification targets.
+            // 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
+        .filter((requirementId) => !provenRequirementIds.has(requirementId))
+        .map((requirementId) => ({
+        requirementId,
+        description: `No executable verification target can be derived for ${requirementId}`,
+        blocking: true,
+    }));
+    return {
+        ...record,
+        requirements,
+        evidenceGaps: [...modelEvidenceGaps, ...derivedBlockingGaps],
+    };
+}
+function assertFrontendContractPathsSafe(value) {
+    const record = asRecord(value);
+    if (!record)
+        return;
+    const pathFields = ["files", "file", "implementationTargets", "fixture", "consumer"];
+    for (const [key, child] of Object.entries(record)) {
+        if (pathFields.includes(key) && Array.isArray(child)) {
+            for (const item of child) {
+                if (typeof item === "string" && (item.startsWith("/") || item.includes("\\") || item.split("/").includes("..")))
+                    throw new Error(`invalid-output: unsafe frontend contract path ${item}`);
+            }
+        }
+        else if (pathFields.includes(key) && typeof child === "string" && (child.startsWith("/") || child.includes("\\") || child.split("/").includes(".."))) {
+            throw new Error(`invalid-output: unsafe frontend contract path ${child}`);
+        }
+        if (Array.isArray(child))
+            child.forEach(assertFrontendContractPathsSafe);
+        else if (child && typeof child === "object")
+            assertFrontendContractPathsSafe(child);
+    }
+}
+function deriveContractRequirementIds(value) {
+    const record = asRecord(value);
+    if (!record)
+        return [];
+    const ids = [];
+    const push = (candidate) => {
+        const value = asString(candidate);
+        const canonical = canonicalizeRequirementId(value);
+        if (!canonical || !isRequirementId(canonical) || ids.includes(canonical))
+            return;
+        ids.push(canonical);
+    };
+    if (Array.isArray(record.requirements)) {
+        for (const item of record.requirements)
+            push(asRecord(item)?.id);
+    }
+    if (Array.isArray(record.requirementCoverage)) {
+        for (const item of record.requirementCoverage)
+            push(asRecord(item)?.id);
+    }
+    const rawVerification = Array.isArray(record.verificationTargets)
+        ? record.verificationTargets
+        : asRecord(record.verificationTargets)
+            ? Object.values(asRecord(record.verificationTargets))
+            : [];
+    for (const item of rawVerification) {
+        for (const requirementId of asStringArray(asRecord(item)?.requirementIds)) {
+            push(requirementId);
+        }
+    }
+    for (const item of Array.isArray(record.evidenceGaps) ? record.evidenceGaps : []) {
+        push(asRecord(item)?.requirementId);
+    }
+    return ids;
+}
+function withDerivedRequirementIdsWhenUnscoped(binding, parsed) {
+    if (binding.requirementIds.length > 0)
+        return binding;
+    const derivedIds = deriveContractRequirementIds(parsed);
+    return derivedIds.length > 0
+        ? { ...binding, requirementIds: derivedIds }
+        : binding;
+}
+function looksLikeStrictFrontendContract(value) {
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    return (record.schemaVersion === 1 &&
+        asRecord(record.targets) !== null &&
+        Array.isArray(record.requirements) &&
+        Array.isArray(record.uiStates) &&
+        asRecord(record.mockApi) !== null &&
+        asRecord(record.designEvidence) !== null);
+}
+/**
+ * Coerce common free-form plan JSON into frontend-implementation-contract-v1.
+ * Near-schema payloads are left untouched so unknown-key fail-closed still holds.
+ */
+export function coerceFrontendImplementationContractInput(value, canonicalBinding) {
+    const rawRecord = asRecord(value);
+    const rawMockApi = asRecord(rawRecord?.mockApi);
+    if (rawMockApi &&
+        typeof rawMockApi.strategy === "string" &&
+        !["native", "browser-intercept", "request-adapter", "not-needed"].includes(rawMockApi.strategy))
+        return value;
+    const verificationTargetIds = rawRecord && Array.isArray(rawRecord.verificationTargets)
+        ? new Set(rawRecord.verificationTargets
+            .map((item) => asString(asRecord(item)?.id))
+            .filter(Boolean))
+        : undefined;
+    const normalizedValue = rawRecord
+        ? {
+            ...rawRecord,
+            requirements: verificationTargetIds && Array.isArray(rawRecord.requirements)
+                ? rawRecord.requirements.map((item) => {
+                    const requirement = asRecord(item);
+                    if (!requirement || !Array.isArray(requirement.verificationTargetIds))
+                        return item;
+                    const filtered = requirement.verificationTargetIds.filter((id) => typeof id === "string" && verificationTargetIds.has(id));
+                    return {
+                        ...requirement,
+                        verificationTargetIds: filtered.length > 0 ? filtered : requirement.verificationTargetIds,
+                    };
+                })
+                : rawRecord.requirements,
+            uiStates: Array.isArray(rawRecord.uiStates)
+                ? rawRecord.uiStates.map((item) => {
+                    const state = asRecord(item);
+                    if (!state)
+                        return item;
+                    if (state.applicable === true &&
+                        (state.notApplicableReason === null ||
+                            (typeof state.notApplicableReason === "string" &&
+                                state.notApplicableReason.trim() === ""))) {
+                        const { notApplicableReason: _emptyReason, ...withoutEmptyReason } = state;
+                        return withoutEmptyReason;
+                    }
+                    if (state.applicable === false &&
+                        (state.expectedBehavior === null ||
+                            (typeof state.expectedBehavior === "string" &&
+                                state.expectedBehavior.trim() === ""))) {
+                        const { expectedBehavior: _emptyBehavior, ...withoutEmptyBehavior } = state;
+                        return withoutEmptyBehavior;
+                    }
+                    return item;
+                })
+                : rawRecord.uiStates,
+        }
+        : value;
+    const normalizedOptionalFields = normalizeFrontendContractOptionalFields(normalizedValue);
+    // A payload can have the strict top-level shape while still containing
+    // empty requirement coverage arrays. Do not trust shape alone: route such
+    // payloads through the compatibility normalizer so targets and verification
+    // references are deterministically filled from the contract context.
+    if (looksLikeStrictFrontendContract(normalizedOptionalFields)) {
+        const strictRecord = asRecord(normalizedOptionalFields);
+        const strictMockApi = asRecord(strictRecord?.mockApi);
+        if (strictMockApi &&
+            typeof strictMockApi.strategy === "string" &&
+            !["native", "browser-intercept", "request-adapter", "not-needed"].includes(strictMockApi.strategy))
+            return normalizedValue;
+        const targetFiles = asStringArray(asRecord(strictRecord?.targets)?.files);
+        const verificationIds = Array.isArray(strictRecord?.verificationTargets)
+            ? strictRecord.verificationTargets.map((item) => asString(asRecord(item)?.id)).filter(Boolean)
+            : [];
+        if (Array.isArray(strictRecord?.requirements)) {
+            const requirements = strictRecord.requirements.map((item) => {
+                const requirement = asRecord(item);
+                if (!requirement)
+                    return item;
+                return {
+                    ...requirement,
+                    implementationTargets: asStringArray(requirement.implementationTargets).length > 0
+                        ? requirement.implementationTargets
+                        : targetFiles,
+                    verificationTargetIds: asStringArray(requirement.verificationTargetIds).length > 0
+                        ? requirement.verificationTargetIds
+                        : verificationIds,
+                };
+            });
+            const strictMockApi = asRecord(strictRecord.mockApi);
+            const strictTargetFiles = asStringArray(asRecord(strictRecord.targets)?.files);
+            const mockEndpoints = Array.isArray(strictMockApi?.endpoints)
+                ? strictMockApi.endpoints.map((item) => {
+                    const endpoint = asRecord(item);
+                    if (!endpoint)
+                        return item;
+                    return {
+                        ...endpoint,
+                        consumer: asString(endpoint.consumer) ||
+                            strictTargetFiles[0],
+                    };
+                })
+                : strictMockApi?.endpoints;
+            return {
+                ...strictRecord,
+                requirements,
+                ...(strictMockApi ? { mockApi: { ...strictMockApi, endpoints: mockEndpoints } } : {}),
+            };
+        }
+    }
+    const record = asRecord(normalizedOptionalFields);
+    if (!record)
+        return value;
+    const implementation = asRecord(record.implementation);
+    const mockApiIn = asRecord(record.mockApi) ?? {};
+    const api = asRecord(record.api) ?? {};
+    const component = asRecord(record.component);
+    const targetFiles = [
+        ...asStringArray(asRecord(record.targets)?.files),
+        ...asStringArray(implementation?.targetFiles),
+        ...asStringArray(record.writeSet),
+        ...asStringArray(implementation?.writeSet),
+        ...asStringArray(asRecord(component?.paths)?.implementation ? [asRecord(component?.paths)?.implementation] : []),
+        ...asStringArray(asRecord(component?.paths)?.unitTests ? [asRecord(component?.paths)?.unitTests] : []),
+        ...asStringArray(asRecord(component?.paths)?.domHelper ? [asRecord(component?.paths)?.domHelper] : []),
+    ].filter((item, index, arr) => arr.indexOf(item) === index);
+    if (targetFiles.length === 0) {
+        throw new Error("frontend contract compatibility input must declare target files");
+    }
+    const riskRaw = asString(record.riskLevel) ||
+        asString(record.risk) ||
+        "standard";
+    const riskLevel = riskRaw === "small" || riskRaw === "standard" || riskRaw === "high-risk"
+        ? riskRaw
+        : riskRaw.includes("high")
+            ? "high-risk"
+            : "standard";
+    const verificationTargets = [];
+    const rawVerification = Array.isArray(record.verificationTargets)
+        ? record.verificationTargets
+        : asRecord(record.verificationTargets)
+            ? Object.entries(asRecord(record.verificationTargets)).map(([key, val]) => ({
+                ...(asRecord(val) ?? {}),
+                id: key,
+            }))
+            : [];
+    for (const [index, item] of rawVerification.entries()) {
+        const vt = asRecord(item) ?? {};
+        const id = asString(vt.id) || `VT-${String(index + 1).padStart(3, "0")}`;
+        const typeRaw = asString(vt.type) || asString(vt.phase) || "unit";
+        const type = ["static", "unit", "component", "integration", "mock"].includes(typeRaw)
+            ? typeRaw
+            : typeRaw.includes("type")
+                ? "static"
+                : "unit";
+        const commandLabel = asString(vt.commandLabel) ||
+            asString(vt.command) ||
+            (type === "static" ? "npm run typecheck" : "npm run test:unit:fe");
+        const file = asString(vt.file) ||
+            (Array.isArray(vt.symbols) ? targetFiles.find((p) => p.includes("__tests__")) : "") ||
+            targetFiles.find((p) => p.includes("__tests__")) ||
+            targetFiles[0];
+        const requirementIds = asStringArray(vt.requirementIds);
+        const uiStateNames = asStringArray(vt.uiStates);
+        verificationTargets.push({
+            id,
+            type,
+            commandLabel,
+            file,
+            symbol: asString(vt.symbol) || undefined,
+            requirementIds: requirementIds.length > 0
+                ? requirementIds
+                : [...canonicalBinding.requirementIds],
+            uiStates: uiStateNames.length > 0 ? uiStateNames : ["success", "error"],
+        });
+    }
+    if (verificationTargets.length === 0) {
+        throw new Error("frontend contract compatibility input must declare verification targets");
+    }
+    const defaultVerificationIds = verificationTargets.map((item) => String(item.id));
+    const requirements = [];
+    const reqSource = Array.isArray(record.requirements)
+        ? record.requirements
+        : Array.isArray(record.requirementCoverage)
+            ? record.requirementCoverage
+            : [];
+    for (const item of reqSource) {
+        const req = asRecord(item) ?? {};
+        const id = asString(req.id);
+        if (!id)
+            continue;
+        const implementationTargetsRaw = asStringArray(req.implementationTargets);
+        const implementationTargets = implementationTargetsRaw.length > 0
+            ? implementationTargetsRaw
+            : targetFiles;
+        const verificationTargetIdsRaw = asStringArray(req.verificationTargetIds);
+        const verificationTargetIds = verificationTargetIdsRaw.length > 0
+            ? verificationTargetIdsRaw
+            : defaultVerificationIds;
+        const gapText = asString(asRecord(req.evidenceGap)?.description) ||
+            asString(req.realIntegrationGap);
+        const out = {
+            id,
+            expectedOutcome: asString(req.expectedOutcome),
+            implementationTargets: implementationTargets.length > 0 ? implementationTargets : targetFiles,
+            verificationTargetIds: verificationTargetIds.length > 0
+                ? verificationTargetIds
+                : defaultVerificationIds,
+        };
+        // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
+        if (gapText) {
+            out.evidenceGap = {
+                description: gapText,
+                blocking: false,
+                requirementId: id,
+            };
+        }
+        requirements.push(out);
+    }
+    for (const id of canonicalBinding.requirementIds) {
+        if (!requirements.some((item) => item.id === id)) {
+            throw new Error(`frontend contract compatibility input does not cover ${id}`);
+        }
+    }
+    const uiStates = [];
+    if (Array.isArray(record.uiStates)) {
+        for (const item of record.uiStates) {
+            const state = asRecord(item);
+            if (!state)
+                continue;
+            uiStates.push(state);
+        }
+    }
+    else if (asRecord(record.uiStates)) {
+        for (const [name, raw] of Object.entries(asRecord(record.uiStates))) {
+            const state = asRecord(raw);
+            const text = asString(raw);
+            const na = text.toUpperCase().includes("N/A") ||
+                text.toLowerCase().includes("not applicable") ||
+                text.toLowerCase() === "n/a-minimal";
+            if (na || (state && asString(state.notApplicableReason))) {
+                uiStates.push({
+                    name,
+                    applicable: false,
+                    notApplicableReason: asString(state?.notApplicableReason) || text || "not applicable",
+                });
+                continue;
+            }
+            const expectedBehavior = (state &&
+                [
+                    asString(state.expectedBehavior),
+                    asString(state.role) ? `role=${asString(state.role)}` : "",
+                    asString(state.ariaLive) ? `ariaLive=${asString(state.ariaLive)}` : "",
+                    asString(state.source) || asString(state.contentFrom),
+                    asString(state.textMatchHint),
+                    typeof state.silentFailure === "boolean"
+                        ? `silentFailure=${state.silentFailure}`
+                        : "",
+                ]
+                    .filter(Boolean)
+                    .join("; ")) ||
+                text ||
+                `${name} state`;
+            uiStates.push({
+                name,
+                applicable: true,
+                expectedBehavior,
+                implementationTargets: targetFiles,
+                verificationTargetIds: defaultVerificationIds,
+            });
+        }
+    }
+    if (uiStates.length === 0) {
+        uiStates.push({
+            name: "success",
+            applicable: true,
+            expectedBehavior: "visible success state",
+            implementationTargets: targetFiles,
+            verificationTargetIds: defaultVerificationIds,
+        }, {
+            name: "error",
+            applicable: true,
+            expectedBehavior: "visible error state",
+            implementationTargets: targetFiles,
+            verificationTargetIds: defaultVerificationIds,
+        });
+    }
+    const strategyRaw = asString(mockApiIn.strategy) || "not-needed";
+    const allowedStrategies = [
+        "native",
+        "browser-intercept",
+        "request-adapter",
+        "not-needed",
+    ];
+    if (!allowedStrategies.includes(strategyRaw)) {
+        throw new Error(`frontend contract compatibility input has unsupported Mock strategy: ${strategyRaw}`);
+    }
+    const strategy = strategyRaw;
+    const productionDefaultOff = mockApiIn.productionDefaultOff === true || mockApiIn.productionMockOff === true;
+    if (!productionDefaultOff) {
+        throw new Error("frontend contract compatibility input must prove production Mock is off");
+    }
+    const activation = asString(mockApiIn.activation) ||
+        (strategy === "not-needed"
+            ? "production remains real fetch; unit tests may inject fetchImpl only"
+            : "documented mock activation");
+    const endpoints = [];
+    for (const item of Array.isArray(mockApiIn.endpoints) ? mockApiIn.endpoints : []) {
+        const ep = asRecord(item);
+        if (!ep)
+            continue;
+        const method = asString(ep.method).toUpperCase() || "GET";
+        const pathValue = asString(ep.path) || asString(api.path);
+        if (!pathValue.startsWith("/"))
+            continue;
+        endpoints.push({
+            method,
+            path: pathValue,
+            fixture: asString(ep.fixture) || undefined,
+            consumer: asString(ep.consumer) || undefined,
+        });
+    }
+    if (endpoints.length === 0 && asString(api.path).startsWith("/")) {
+        endpoints.push({
+            method: asString(api.method).toUpperCase() || "GET",
+            path: asString(api.path),
+            consumer: targetFiles[0],
+        });
+    }
+    const evidenceGaps = [];
+    for (const item of Array.isArray(record.evidenceGaps) ? record.evidenceGaps : []) {
+        const gapItem = asRecord(item);
+        if (!gapItem)
+            continue;
+        const description = asString(gapItem.description);
+        if (!description)
+            continue;
+        evidenceGaps.push({
+            description,
+            blocking: gapItem.blocking === true,
+            requirementId: asString(gapItem.requirementId) || undefined,
+        });
+    }
+    const realGap = asString(record.realIntegrationGap);
+    if (realGap) {
+        evidenceGaps.push({
+            description: realGap,
+            blocking: false,
+        });
+    }
+    for (const item of Array.isArray(record.residualRisks) ? record.residualRisks : []) {
+        const text = asString(item) || asString(asRecord(item)?.description);
+        if (!text)
+            continue;
+        evidenceGaps.push({ description: text, blocking: false });
+    }
+    const designPaths = [
+        ...canonicalBinding.referencePaths,
+        ...asStringArray(asRecord(record.designEvidence)?.paths),
+    ].filter((item, index, arr) => arr.indexOf(item) === index);
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalBinding,
+        riskLevel,
+        targets: {
+            files: targetFiles,
+            routes: asStringArray(asRecord(record.targets)?.routes),
+            publicApiChanges: asStringArray(asRecord(record.targets)?.publicApiChanges),
+        },
+        requirements,
+        uiStates,
+        interactions: Array.isArray(record.interactions) ? record.interactions : [],
+        mockApi: {
+            strategy,
+            productionDefaultOff: true,
+            activation,
+            endpoints,
+        },
+        designEvidence: {
+            source: asString(asRecord(record.designEvidence)?.source) ||
+                "repository-fallback+task-source",
+            paths: designPaths.length > 0 ? designPaths : [canonicalBinding.requirementPath],
+            conflicts: asStringArray(asRecord(record.designEvidence)?.conflicts),
+        },
+        verificationTargets,
+        evidenceGaps,
+        implementationSteps: asStringArray(record.implementationSteps),
+        stylingStrategy: asString(record.stylingStrategy) || undefined,
+        dependencyPolicy: asString(record.dependencyPolicy) || undefined,
+        residualRisks: asStringArray(record.residualRisks),
+        realIntegrationGap: asString(record.realIntegrationGap) || undefined,
+        uiComponentChoices: normalizeUiComponentChoices(record.uiComponentChoices),
+    };
+}
+/**
+ * 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");
+    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":["/'))
+        fail("blocked", "invalid-output: absolute frontend contract path is forbidden", null);
+    if (/(?:"(?:files|file|implementationTargets|fixture|consumer)"\s*:\s*(?:\[\s*)?)"\//.test(rawContractText))
+        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))
+        fail("blocked", "invalid-output: unsupported mock strategy", null);
+    let parsed;
+    try {
+        const extracted = extractFrontendImplementationJsonWithAudit(rawContractText);
+        parsed = extracted.value;
+        for (const action of extracted.actions)
+            pushAction(action);
+    }
+    catch (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)
+        fail("blocked", `invalid-output: ${secrets.join("; ")}`, candidateJsonSha256);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        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("/")))
+        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);
+    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);
+    if (frozenLabels.length > 0) {
+        const frozen = new Set(frozenLabels);
+        const parsedVt = asRecord(parsed)?.verificationTargets;
+        if (Array.isArray(parsedVt)) {
+            for (const vt of parsedVt) {
+                const label = asString(asRecord(vt)?.commandLabel);
+                if (label && !frozen.has(label)) {
+                    fail("blocked", `invalid-output: verificationTarget commandLabel "${label}" is not in the frozen command set [${[...frozen].join(", ")}]`, candidateJsonSha256);
+                }
+            }
+        }
+    }
+    const parsedTargets = asRecord(parsed)?.targets;
+    const parsedTargetFiles = asStringArray(asRecord(parsedTargets)?.files);
+    if (parsedTargetFiles.some((file) => file.startsWith("/") || file.includes("\\")))
+        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);
+    }))
+        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)))
+        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. 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)
+        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)
+        fail("blocked", `frontend contract has blocking evidence gap: ${blockingGaps
+            .map((item) => item.requirementId ?? item.description)
+            .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))
+            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: written.path,
+        sha256: written.sha256,
+        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 canonical full-contract text for all
+ * 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: [],
+        });
+        return {
+            ok: true,
+            contract: analysis.canonical,
+            normalizedText: [
+                "Frontend implementation contract compiled from the runtime skeleton.",
+                "",
+                "```json",
+                serializeDeterministicJson(analysis.canonical),
+                "```",
+                citationsBlock,
+            ].join("\n"),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        await writeReport({
+            classification: "retryable-invalid",
+            normalizationActions: [],
+            errors: [{ path: "$", code: "invalid-output", message: reason }],
+        });
+        return { ok: false, reason };
+    }
+}
+/**
+ * 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),
+        };
+    }
+}
+/**
+ * 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 exactly 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.
+ */
+export async function validateFrontendRevisionPatchNodeOutput(input) {
+    let citationsBlock;
+    try {
+        citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // 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(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)}`,
+        };
+    }
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+        return {
+            ok: false,
+            reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
+        };
+    }
+    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+    if (protectedViolations.length > 0) {
+        return {
+            ok: false,
+            reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
+        };
+    }
+    return { ok: true, contract: patch };
+}
+export async function materializeFrontendImplementationContract(input) {
+    const analysis = await analyzeFrontendImplementationContract(input);
+    return writeFrontendImplementationContractArtifact({
+        runDir: input.runDir,
+        outputDir: input.outputDir,
+        artifactName: input.artifactName,
+        canonical: analysis.canonical,
+    });
+}