@tea-agent/loop-agent 0.38.2 → 0.39.0-beta.0

package/dist/workflows/dag/backend-test-case-coverage-analysis.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { z } from "zod";
 import YAML from "yaml";
 import { resolveBackendTestLayout, } from "./backend-test-layout.js";
-import { assessScenarioPartitionCoverage, parseScenarioPartitions, } from "./backend-test-scenario-partitions.js";
+import { applyOpenApiPartitionDomainPolicy, assessScenarioPartitionCoverage, parseScenarioPartitions, } from "./backend-test-scenario-partitions.js";
 import { backendTestCaseManifestSchema, computeCaseManifestCoverageSummary, } from "./backend-test-case-manifest.js";
 const CASE_HEADING = /^##\s+(BE-[A-Z0-9_-]+-\d{3})\b.*$/gm;
 const CASE_ID_IN_TEXT = /\bBE-[A-Z0-9_-]+-\d{3}\b/g;
@@ -486,6 +486,55 @@ export async function extractBackendTestOpenApiRules(input) {
     }
     return rules.sort((left, right) => left.ruleKey.localeCompare(right.ruleKey));
 }
+export async function extractBackendTestOpenApiPartitionAxes(input) {
+    const axes = [];
+    const seen = new Set();
+    for (const referencePath of input.sourceBinding.referencePaths) {
+        const physicalPath = resolveBoundSourcePath(input.workspaceRoot, input.sourceBinding.taskId, referencePath);
+        let document;
+        try {
+            const parsed = YAML.parse(await readFile(physicalPath, "utf8"));
+            if (!isRecord(parsed) || !isRecord(parsed.paths))
+                continue;
+            document = parsed;
+        }
+        catch {
+            continue;
+        }
+        for (const [apiPath, pathItem] of Object.entries(document.paths)) {
+            if (!isRecord(pathItem))
+                continue;
+            const operation = pathItem.get;
+            if (!isRecord(operation))
+                continue;
+            const parameterValues = [
+                ...(Array.isArray(pathItem.parameters) ? pathItem.parameters : []),
+                ...(Array.isArray(operation.parameters) ? operation.parameters : []),
+            ];
+            for (const rawParameter of parameterValues) {
+                const parameter = resolveOpenApiSchema(document, rawParameter);
+                if (!parameter || typeof parameter.name !== "string")
+                    continue;
+                const location = parameter.in === "path" ? "path" : parameter.in === "query" ? "query" : undefined;
+                if (!location)
+                    continue;
+                const property = resolveOpenApiSchema(document, parameter.schema);
+                const enumValues = property && Array.isArray(property.enum) ? property.enum.map(String) : null;
+                const identity = `GET ${apiPath}|${location}|${parameter.name}`;
+                if (seen.has(identity))
+                    continue;
+                seen.add(identity);
+                axes.push({
+                    operation: `GET ${apiPath}`,
+                    name: parameter.name,
+                    in: location,
+                    enumValues,
+                });
+            }
+        }
+    }
+    return axes;
+}
 function orderedUnique(values) {
     const result = [];
     const seen = new Set();
@@ -985,8 +1034,11 @@ export async function analyzeBackendTestCaseCoverage(input) {
     // Plan C: deterministic query/filter axis partitions (fail-closed on missing slots).
     const parsedPartitions = parseScenarioPartitions(readme);
     findings.push(...parsedPartitions.issues);
+    const openApiPartitionAxes = await extractBackendTestOpenApiPartitionAxes(input);
+    const partitionedBySource = applyOpenApiPartitionDomainPolicy(parsedPartitions.partitions, openApiPartitionAxes);
+    findings.push(...partitionedBySource.issues);
     const declaredPointUniverse = new Set(cases.flatMap((item) => item.testPoints));
-    const partitionAssessment = assessScenarioPartitionCoverage(parsedPartitions.partitions, declaredPointUniverse);
+    const partitionAssessment = assessScenarioPartitionCoverage(partitionedBySource.partitions, declaredPointUniverse);
     findings.push(...partitionAssessment.findings);
     const [enumValueCount, coveredEnumValueCount] = dimensionCounts(rules, /enum/);
     const [boundaryPointCount, coveredBoundaryPointCount] = dimensionCounts(rules, /boundary|length|numeric/);
@@ -1003,7 +1055,7 @@ export async function analyzeBackendTestCaseCoverage(input) {
         sourceBinding: input.sourceBinding,
         inputFiles: await inputFileFacts(input.workspaceRoot, [
             ...((await exists(readmePath)) ? [readmePath] : []),
-            ...(await markdownModuleFiles(input.workspaceRoot)),
+            ...(await markdownModuleFiles(input.workspaceRoot, layout)),
             ...(await Promise.all(input.sourceBinding.referencePaths.map(async (referencePath) => {
                 const physicalPath = resolveBoundSourcePath(input.workspaceRoot, input.sourceBinding.taskId, referencePath);
                 return (await exists(physicalPath)) ? physicalPath : "";
@@ -1794,7 +1846,7 @@ export async function analyzeBackendTestMarkdownPytestCorrespondence(input) {
         status: findings.length === 0 ? "PASS" : "FAIL",
         inputFiles: await inputFileFacts(input.workspaceRoot, [
             path.join(input.workspaceRoot, ...layout.readmePath.split("/")),
-            ...(await markdownModuleFiles(input.workspaceRoot)),
+            ...(await markdownModuleFiles(input.workspaceRoot, layout)),
             ...scriptFiles,
         ].filter((file) => file && path.isAbsolute(file))),
         summary: {

package/dist/workflows/dag/backend-test-scenario-partitions.js

@@ -35,6 +35,8 @@ export const scenarioPartitionRowSchema = z.object({
 const PARTITION_HEADING = /^##\s+Scenario Partitions\s*$/;
 const PARTITION_TABLE_HEADER = /^\|\s*Partition ID\s*\|\s*Operation\s*\|\s*Axis\s*\|\s*Domain\s*\|\s*Required Slots\s*\|\s*Expected by Slot\s*\|\s*Bind Rule\s*\|\s*$/;
 const TABLE_ROW = /^\|(.+)\|$/;
+const FINITE_DOMAIN_MEMBER = /^[A-Za-z0-9]+(?:[._\- ][A-Za-z0-9]+)*$/;
+const RESERVED_SLOT_TOKENS = new Set(["OMITTED", "NOT-IN-SET"]);
 function splitCells(raw) {
     return raw
         .split("|")
@@ -100,6 +102,11 @@ export function parseScenarioPartitions(readmeMarkdown) {
             continue;
         }
         seen.add(partitionId);
+        const domainIssue = describeInvalidPartitionDomain(domain);
+        if (domainIssue) {
+            issues.push(`INVALID_PARTITION_DOMAIN: partition ${partitionId} ${domainIssue}`);
+            continue;
+        }
         partitions.push({
             partitionId,
             operation,
@@ -119,6 +126,40 @@ function slotToken(value) {
         .replace(/[^A-Z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
+function describeInvalidPartitionDomain(domain) {
+    const tokens = [];
+    const seenTokens = new Set();
+    for (const value of domain) {
+        if (!FINITE_DOMAIN_MEMBER.test(value)) {
+            return `value is not a finite identifier member: ${value}`;
+        }
+        const token = slotToken(value);
+        if (!token) {
+            return `value cannot produce a stable non-empty slot token: ${value}`;
+        }
+        if (RESERVED_SLOT_TOKENS.has(token)) {
+            return `value maps to reserved slot token ${token}: ${value}`;
+        }
+        if (seenTokens.has(token)) {
+            return `values collapse to duplicate slot token ${token}`;
+        }
+        seenTokens.add(token);
+        tokens.push(token);
+    }
+    return tokens.length === 0 ? "domain produced no slot tokens" : undefined;
+}
+function normalizePartitionAxisName(value) {
+    return value.trim().replace(/^(?:query|path)\s*:\s*/i, "").toLowerCase();
+}
+function normalizePartitionOperation(value) {
+    return value.trim().replace(/\s+/g, " ").toUpperCase();
+}
+function sameFiniteSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const expected = new Set(left);
+    return right.every((value) => expected.has(value));
+}
 const STABLE_PARTITION_ID = /^SP-[A-Z0-9][A-Z0-9._-]*$/i;
 /**
  * Slot IDs are `TP-<Partition ID>-<VALUE|OMITTED|NOT-IN-SET>`.
@@ -138,13 +179,16 @@ function partitionToken(row) {
 export function expandScenarioPartitions(partitions) {
     const slots = [];
     for (const row of partitions) {
+        if (describeInvalidPartitionDomain(row.domain))
+            continue;
         const prefix = partitionToken(row);
         for (const value of row.domain) {
+            const token = slotToken(value);
             slots.push({
                 partitionId: row.partitionId,
                 operation: row.operation,
                 axis: row.axis,
-                slotId: `${prefix}-${slotToken(value)}`,
+                slotId: `${prefix}-${token}`,
                 kind: "each-value",
                 value,
                 intent: "nominal-filter",
@@ -176,6 +220,34 @@ export function expandScenarioPartitions(partitions) {
     }
     return slots;
 }
+/**
+ * Bind parsed partitions to GET query/path OpenAPI axes.
+ * Unconfirmed axes keep identifier-valid Domain rows (requirement finite sets).
+ */
+export function applyOpenApiPartitionDomainPolicy(partitions, axes) {
+    const issues = [];
+    const valid = [];
+    for (const row of partitions) {
+        const operation = normalizePartitionOperation(row.operation);
+        const axisName = normalizePartitionAxisName(row.axis);
+        const matched = axes.find((axis) => normalizePartitionOperation(axis.operation) === operation &&
+            normalizePartitionAxisName(axis.name) === axisName);
+        if (!matched) {
+            valid.push(row);
+            continue;
+        }
+        if (matched.enumValues === null) {
+            issues.push(`NO_FINITE_DOMAIN: partition ${row.partitionId} axis ${row.axis} exists on ${row.operation} without a documented enum`);
+            continue;
+        }
+        if (!sameFiniteSet(matched.enumValues, row.domain)) {
+            issues.push(`PARTITION_SOURCE_MISMATCH: partition ${row.partitionId} domain does not match OpenAPI enum for ${row.operation} ${row.axis}`);
+            continue;
+        }
+        valid.push(row);
+    }
+    return { partitions: valid, issues };
+}
 /** Facts projection consumed by N6 and plan D gap-fill. */
 export const scenarioPartitionFactsSchema = z.object({
     partitions: z.array(z.object({

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

@@ -41,6 +41,9 @@ export function serializeDeterministicJson(value) {
 export function deterministicSha256(value) {
     return sha256Hex(serializeDeterministicJson(value));
 }
+/** Provider-safe limits for the two planner outputs. Larger work must split. */
+export const FRONTEND_PLAN_RESPONSE_MAX_BYTES = 14 * 1024;
+export const FRONTEND_CANONICAL_CONTRACT_MAX_BYTES = 16 * 1024;
 /** 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
@@ -1722,9 +1725,37 @@ function extractSingleOpenspecCitationsBlock(text) {
     }
     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) {
+    const citationsBlock = extractSingleOpenspecCitationsBlock(text);
+    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);
+}
 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`);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text);
     return relativePath;
 }
 /**
@@ -1765,18 +1796,23 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
         });
     };
     try {
+        if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
+            throw new Error(`frontend plan response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`);
+        }
         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);
+        const patch = extractFrontendPlanPrimaryPayload(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 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(", ")}`);
@@ -1790,6 +1826,10 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
         });
+        if (Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8") >
+            FRONTEND_CANONICAL_CONTRACT_MAX_BYTES) {
+            throw new Error(`frontend canonical contract exceeds the ${FRONTEND_CANONICAL_CONTRACT_MAX_BYTES}-byte limit; split the task`);
+        }
         const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
         await writeReport({
             classification: "accepted-normalized",
@@ -1807,6 +1847,19 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
         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.",
                 "",
@@ -1862,27 +1915,32 @@ export async function validateFrontendContractNodeOutput(input) {
  * the prewrite gate, which remains the only authority.
  */
 export async function validateFrontendRevisionPatchNodeOutput(input) {
-    let citationsBlock;
-    try {
-        citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
-    }
-    catch (error) {
+    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,
+    });
+    if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
         return {
             ok: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: `frontend revision response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`,
         };
     }
-    // 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 citationsBlock;
     let patch;
     try {
-        patch = extractFrontendImplementationJson(textWithoutCitations);
+        const parsed = extractFrontendPlanPayload(input.text);
+        citationsBlock = parsed.citationsBlock;
+        patch = parsed.payload;
     }
     catch (error) {
         return {
             ok: false,
-            reason: `revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`,
+            reason: error instanceof Error ? error.message : String(error),
         };
     }
     if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
@@ -1898,7 +1956,27 @@ export async function validateFrontendRevisionPatchNodeOutput(input) {
             reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
         };
     }
-    return { ok: true, contract: patch };
+    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);

package/dist/workflows/dag/frontend-prewrite-gate.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
 import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { countExcludedGovernanceSpecFiles, resolveOpenspecGovernanceRoot, } from "../../task/frontend-project-capability.js";
-import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, applyFrontendImplementationContractPatch, extractFrontendImplementationJson, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
+import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, FRONTEND_CANONICAL_CONTRACT_MAX_BYTES, applyFrontendImplementationContractPatch, extractFrontendImplementationJson, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
 import { captureFrontendWorktreeBaseline } from "./frontend-worktree-diff.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
@@ -12,7 +12,7 @@ import { normalizeVerdictCandidateLine } from "./dynamic-runtime/shared.js";
 export const FRONTEND_PREWRITE_RESULT_SCHEMA_ID = "frontend-prewrite-result-v1";
 export const FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME = "frontend-prewrite-result.json";
 /** Canonical contract serialization must stay at or below this byte size. */
-export const FRONTEND_CONTRACT_MAX_BYTES = 65536;
+export const FRONTEND_CONTRACT_MAX_BYTES = FRONTEND_CANONICAL_CONTRACT_MAX_BYTES;
 /**
  * Machine-readable failure classification for blocked/retryable-invalid
  * prewrite outcomes. Kept alongside the human-readable failureReason so
@@ -176,6 +176,82 @@ async function readNodeRawText(runDir, nodeId) {
     const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
     return record.assistantText ?? record.stdout ?? "";
 }
+function resolveRunOwnedArtifact(runDir, candidate, label) {
+    const root = path.resolve(runDir);
+    const resolved = path.resolve(candidate);
+    const relative = path.relative(root, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`frontend prewrite gate ${label} must be contained by the current run directory`);
+    }
+    return resolved;
+}
+async function readHashBoundArtifact(input) {
+    const resolved = resolveRunOwnedArtifact(input.runDir, input.artifactPath, input.label);
+    const text = await readFile(resolved, "utf8");
+    const actual = sha256Hex(text);
+    if (actual !== input.expectedSha256) {
+        throw new Error(`frontend prewrite gate ${input.label} SHA-256 mismatch (expected ${input.expectedSha256}, got ${actual})`);
+    }
+    return text;
+}
+async function readFrontendPlanNodeInput(runDir, nodeId) {
+    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
+    if (record.status !== "FINISHED") {
+        throw new Error(`frontend prewrite gate requires FINISHED node ${nodeId} (got ${String(record.status)})`);
+    }
+    const frontend = record.frontendPlanOutput;
+    if (!frontend) {
+        const payloadText = record.assistantText?.trim() || record.stdout?.trim() || "";
+        if (!payloadText)
+            throw new Error(`frontend prewrite gate empty output from ${nodeId}`);
+        return {
+            artifactFirst: false,
+            payloadText,
+            citationsText: payloadText,
+            rawCandidateSha256: sha256Hex(record.assistantText ?? record.stdout ?? ""),
+            payloadKind: "canonical-contract",
+        };
+    }
+    if (frontend.schemaVersion !== 1 ||
+        !record.structuredArtifactPath ||
+        !record.structuredArtifactSha256 ||
+        !record.structuredArtifactSchemaId) {
+        throw new Error(`frontend prewrite gate ${nodeId} has incomplete artifact-first metadata`);
+    }
+    const expectedSchema = frontend.payloadKind === "canonical-contract"
+        ? "frontend-implementation-contract-v1"
+        : "frontend-implementation-contract-revision-patch-v1";
+    if (record.structuredArtifactSchemaId !== expectedSchema) {
+        throw new Error(`frontend prewrite gate ${nodeId} artifact schema ${record.structuredArtifactSchemaId} does not match ${frontend.payloadKind}`);
+    }
+    const [payloadText, citationsText] = await Promise.all([
+        readHashBoundArtifact({
+            runDir,
+            artifactPath: record.structuredArtifactPath,
+            expectedSha256: record.structuredArtifactSha256,
+            label: `${nodeId} primary payload`,
+        }),
+        readHashBoundArtifact({
+            runDir,
+            artifactPath: frontend.citationsArtifactPath,
+            expectedSha256: frontend.citationsArtifactSha256,
+            label: `${nodeId} citations`,
+        }),
+        readHashBoundArtifact({
+            runDir,
+            artifactPath: frontend.rawCandidatePath,
+            expectedSha256: frontend.rawCandidateSha256,
+            label: `${nodeId} raw candidate`,
+        }).then(() => undefined),
+    ]);
+    return {
+        artifactFirst: true,
+        payloadText,
+        citationsText,
+        rawCandidateSha256: frontend.rawCandidateSha256,
+        payloadKind: frontend.payloadKind,
+    };
+}
 /**
  * Same shape predicate as the internal `isContract` inside
  * `extractFrontendImplementationJson` (frontend-implementation-contract.ts):
@@ -458,9 +534,9 @@ export async function runFrontendPrewriteGate(input) {
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
         openspecPolicy,
     };
-    let planText;
+    let planInput;
     try {
-        planText = await readNodeText(input.runDir, planNodeId);
+        planInput = await readFrontendPlanNodeInput(input.runDir, planNodeId);
     }
     catch (error) {
         return finalizePrewrite(input, {
@@ -470,6 +546,9 @@ export async function runFrontendPrewriteGate(input) {
             failureCode: "plan-text-unreadable",
         });
     }
+    const planText = planInput.payloadText;
+    const citationsText = planInput.citationsText;
+    basePending.candidateRawSha256 = planInput.rawCandidateSha256;
     let reviewText;
     try {
         reviewText = await readNodeText(input.runDir, reviewNodeId);
@@ -502,7 +581,20 @@ export async function runFrontendPrewriteGate(input) {
     if (revisionPatchMode) {
         const originalNodeId = input.config.planFallbackFromNodeIds[0];
         try {
-            effectiveContractText = await mergeRevisionPatch(input.runDir, planText, originalNodeId);
+            const originalInput = await readFrontendPlanNodeInput(input.runDir, originalNodeId);
+            if (planInput.artifactFirst && !originalInput.artifactFirst) {
+                throw new Error(`artifact-first revision ${planNodeId} requires artifact-first original contract ${originalNodeId}`);
+            }
+            if (planInput.artifactFirst) {
+                if (planInput.payloadKind !== "merge-patch" ||
+                    originalInput.payloadKind !== "canonical-contract") {
+                    throw new Error("artifact-first revision/original payload kinds are invalid");
+                }
+                effectiveContractText = serializeDeterministicJson(applyFrontendImplementationContractPatch(JSON.parse(originalInput.payloadText), JSON.parse(planInput.payloadText)));
+            }
+            else {
+                effectiveContractText = await mergeRevisionPatch(input.runDir, planText, originalNodeId);
+            }
         }
         catch (error) {
             return finalizePrewrite(input, {
@@ -610,14 +702,17 @@ export async function runFrontendPrewriteGate(input) {
                 workspaceRoot,
             });
     }
-    // Candidate -> canonical conversion. The gate consumes the selected
-    // plan/revision assistant output directly and is the only conversion point.
+    // Candidate -> canonical conversion. Artifact-first inputs must keep using
+    // the already hash-verified payload: re-reading the selected node record
+    // here would silently fall back to its prose and defeat the integrity gate.
+    // Historical records intentionally retain their node-text compatibility path.
     let analysis;
     try {
+        const rawContractText = effectiveContractText ?? (planInput.artifactFirst ? planText : undefined);
         analysis = await analyzeFrontendImplementationContract({
             runDir: input.runDir,
-            fromNodeId: effectiveContractText ? undefined : planNodeId,
-            rawContractText: effectiveContractText ?? undefined,
+            fromNodeId: rawContractText ? undefined : planNodeId,
+            rawContractText,
             sourceBinding: input.sourceBinding,
         });
     }
@@ -762,7 +857,7 @@ export async function runFrontendPrewriteGate(input) {
             repoRoot: candidateRoot,
         });
         if (candidatePaths.length > 0) {
-            const parsed = parseOpenspecCitations(planText, candidateRoot);
+            const parsed = parseOpenspecCitations(citationsText, candidateRoot);
             if (!parsed.blockPresent || parsed.unparseable) {
                 return finalizePrewrite(input, {
                     ...basePending,
@@ -903,7 +998,7 @@ export async function runFrontendPrewriteGate(input) {
             });
         }
         if (openspecPolicy === "cited") {
-            const parsedCitations = parseOpenspecCitations(planText, candidateRoot);
+            const parsedCitations = parseOpenspecCitations(citationsText, candidateRoot);
             const citedPaths = new Set(parsedCitations.citations.map((citation) => citation.path));
             const readSet = new Set(openspecReadPaths);
             const uncorroborated = [