@abelxiaoxing/cadence 1.2.1 → 1.2.3

package/src/workflow-engine.ts

@@ -30,7 +30,6 @@ import {
 import type { GateApprovalProof } from "./delivery-compiler.ts";
 import {
   DeliveryValidationError,
-  IMPLEMENT_PLAN_SCHEMA_VERSION,
   type ImplementPlan,
   type PlanTaskDraft,
 } from "./delivery-compiler.ts";
@@ -45,7 +44,13 @@ import { type OperationLease, RunStore } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
 import type { ResolvedStateRoot } from "./state-root.ts";
 import type { WorkflowActivityUpdate } from "./subagent-activity.ts";
-import type { CandidateArtifactSubmission } from "./submit-tool.ts";
+import {
+  type CandidateArtifactSubmission,
+  type CandidateContextBoundary,
+  type CandidateContextRef,
+  classifyCandidateContextRequest,
+  normalizeCandidateContextRefs,
+} from "./submit-tool.ts";
 import {
   type BeginCandidateInput,
   TASK_LEDGER_LIMITS,
@@ -70,11 +75,72 @@ const LOCKFILES = new Set([
   "pnpm-lock.yaml",
   "yarn.lock",
 ]);
-const IMPLEMENTATION_ROUTE_REQUIREMENTS = Object.freeze({
-  minContextWindow: 128_000,
-  minOutputTokens: 64_000,
+const IMPLEMENTATION_ROUTE_LIMITS = Object.freeze({
+  preferredContextWindow: 128_000,
+  preferredOutputTokens: 64_000,
+  minimumContextWindow: 16_000,
+  minimumOutputTokens: 8_000,
 });
 
+function implementationRouteRequirements(
+  input: {
+    task?: PlanTaskDraft;
+    artifactCorrection?: RedArtifactCorrection;
+    repair?: { failureIdentities: string[] };
+  } = {},
+) {
+  if (!input.task) {
+    return {
+      minContextWindow: IMPLEMENTATION_ROUTE_LIMITS.minimumContextWindow,
+      minOutputTokens: IMPLEMENTATION_ROUTE_LIMITS.minimumOutputTokens,
+    };
+  }
+  const serializedBytes = Buffer.byteLength(canonicalJson(input.task), "utf8");
+  const pathCount = Object.values(input.task.phases).reduce(
+    (total, phase) =>
+      total + phase.read.length + phase.write.length + phase.delete.length,
+    0,
+  );
+  const complexity =
+    serializedBytes +
+    pathCount * 512 +
+    (input.artifactCorrection ? 16_384 : 0) +
+    (input.repair ? input.repair.failureIdentities.length * 256 + 16_384 : 0);
+  return {
+    minContextWindow: Math.min(
+      IMPLEMENTATION_ROUTE_LIMITS.preferredContextWindow,
+      Math.max(
+        IMPLEMENTATION_ROUTE_LIMITS.minimumContextWindow,
+        16_384 + complexity * 2,
+      ),
+    ),
+    minOutputTokens: Math.min(
+      IMPLEMENTATION_ROUTE_LIMITS.preferredOutputTokens,
+      Math.max(
+        IMPLEMENTATION_ROUTE_LIMITS.minimumOutputTokens,
+        8_192 + Math.ceil(complexity / 2),
+      ),
+    ),
+  };
+}
+
+const SEMANTIC_ROUTE_FAILURE_CODES = new Set([
+  "child-no-structural-submit",
+  "invalid-structural-result",
+  "structural-identity-mismatch",
+  "invalid-diff",
+  "candidate-diff-invalid",
+]);
+
+function semanticRouteFailure(
+  value: DurableCandidateProposal,
+): string | undefined {
+  return (value.kind === "retryable" || value.kind === "paused") &&
+    SEMANTIC_ROUTE_FAILURE_CODES.has(value.code)
+    ? value.code
+    : undefined;
+}
+
 function isCancellationException(error: unknown, signal: AbortSignal): boolean {
   if (!signal.aborted) return false;
   if (error === signal.reason) return true;
@@ -131,6 +197,7 @@ const ENGINE_SCHEMA = `
     phase TEXT NOT NULL,
     pause_code TEXT,
     context_request_json TEXT,
+    attempt_diagnostic_json TEXT,
     route_id TEXT,
     route_fingerprint TEXT,
     queue_position INTEGER,
@@ -171,7 +238,14 @@ interface WorkflowContextRequest {
     | "approved-context-needed"
     | "task-split-needed"
     | "boundary-review-needed";
-  refs: string[];
+  refs: CandidateContextRef[];
+}
+
+interface RedArtifactCorrection {
+  code: "red-artifact-constraint";
+  attempt: number;
+  maxAttempts: number;
+  contextRequest?: WorkflowContextRequest;
 }
 
 export const APPROVAL_AUTHORITY_CATEGORIES = [
@@ -277,7 +351,9 @@ export type WorkflowAttemptOutcome = (
   | { kind: "operation-cancelled"; code: "cancelled" }
 ) &
   WorkflowWorkspaceFacts &
-  WorkflowRouteFacts;
+  WorkflowRouteFacts & {
+    attemptDiagnostic?: SafeAttemptDiagnostic;
+  };
 
 export interface WorkflowWorker {
   runAttempt(input: {
@@ -296,6 +372,8 @@ export interface WorkflowWorker {
       attribution: "introduced";
       failureIdentities: string[];
     };
+    artifactCorrection?: RedArtifactCorrection;
+    contextRequest?: WorkflowContextRequest;
     signal: AbortSignal;
     onActivity?: (
       event: Pick<
@@ -307,6 +385,7 @@ export interface WorkflowWorker {
   rebind(input: {
     runId: string;
     taskId: string;
+    task: PlanTaskDraft;
     role: "implementation-worker";
     routeId: string;
   }):
@@ -340,7 +419,6 @@ export interface WorkflowWorker {
 }
 
 export interface WorkflowDelivery {
-  version: 2;
   gate: "gate-a" | "gate-b";
   revision: number;
   receiptHash: string;
@@ -480,11 +558,22 @@ interface EngineTaskRow {
   phase: "red" | "green" | "refactor";
   pause_code: string | null;
   context_request_json: string | null;
+  attempt_diagnostic_json: string | null;
   route_id: string | null;
   route_fingerprint: string | null;
   queue_position: number | null;
 }
 
+interface SafeAttemptDiagnostic {
+  fingerprint?: string;
+  finalCategory?: string;
+  submitAttempts?: number;
+  schema?: string;
+  identityMismatch?: string[];
+  sameFailureCount?: number;
+  action?: "rebind-or-revise-delivery";
+}
+
 interface EngineOperationRow {
   command: string;
   state: string;
@@ -568,24 +657,72 @@ function normalizeWorkflowContextRequest(
       "approved-context-needed",
       "task-split-needed",
       "boundary-review-needed",
-    ].includes(String(value.code)) ||
-    !Array.isArray(value.refs) ||
-    value.refs.length === 0 ||
-    value.refs.length > 32 ||
-    value.refs.some(
-      (relative) =>
-        typeof relative !== "string" || !isValidRelativePath(relative),
-    ) ||
-    new Set(value.refs).size !== value.refs.length
+    ].includes(String(value.code))
   ) {
     throw new Error("workflow-context-request-invalid");
   }
+  let refs: CandidateContextRef[];
+  try {
+    refs = normalizeCandidateContextRefs(value.refs);
+  } catch {
+    throw new Error("workflow-context-request-invalid");
+  }
   return {
     code: value.code as WorkflowContextRequest["code"],
-    refs: [...(value.refs as string[])],
+    refs,
   };
 }
 
+function contextApprovalRefs(request: WorkflowContextRequest): string[] {
+  return request.refs.flatMap((ref) =>
+    ref.kind === "requested-path" ? [ref.path] : [],
+  );
+}
+
+function contextBoundaryForTask(
+  task: PlanTaskDraft,
+  phase: "red" | "green" | "refactor",
+): CandidateContextBoundary {
+  const boundary = task.phases[phase];
+  if (!boundary) throw new Error("workflow-task-phase-invalid");
+  return {
+    phase,
+    readPaths: boundary.read,
+    writePaths: boundary.write,
+    deletePaths: boundary.delete,
+    taskPaths: [
+      ...new Set(
+        Object.values(task.phases).flatMap((candidate) => [
+          ...candidate.read,
+          ...candidate.write,
+          ...candidate.delete,
+        ]),
+      ),
+    ],
+    redWritePaths: task.phases.red.write,
+    agents: {
+      impact: task.agents.impact,
+      ...(task.agents.target ? { target: task.agents.target } : {}),
+    },
+  };
+}
+
+function classifyPersistedContextRequest(
+  request: WorkflowContextRequest,
+  task: PlanTaskDraft,
+  phase: "red" | "green" | "refactor",
+) {
+  return classifyCandidateContextRequest(
+    {
+      kind: "context-request",
+      candidateId: "candidate-durable-reclassification",
+      code: request.code,
+      refs: request.refs,
+    },
+    contextBoundaryForTask(task, phase),
+  );
+}
+
 function approvalRequirement(
   code: string,
   contextRequest?: WorkflowContextRequest,
@@ -599,7 +736,7 @@ function approvalRequirement(
   return {
     category: requirement.category,
     requiredGates: [...requirement.requiredGates],
-    refs: contextRequest ? [...contextRequest.refs] : [],
+    refs: contextRequest ? contextApprovalRefs(contextRequest) : [],
   };
 }
 
@@ -908,7 +1045,6 @@ function parsePlan(value: string): ImplementPlan {
 function assertPlan(value: unknown): asserts value is ImplementPlan {
   if (
     !isRecord(value) ||
-    value.schemaVersion !== IMPLEMENT_PLAN_SCHEMA_VERSION ||
     typeof value.changeId !== "string" ||
     !Array.isArray(value.tasks) ||
     !Array.isArray(value.outputs) ||
@@ -954,7 +1090,6 @@ function assertDelivery(
 ): asserts value is WorkflowDelivery {
   if (
     !isRecord(value) ||
-    value.version !== 2 ||
     (value.gate !== "gate-a" && value.gate !== "gate-b") ||
     !Number.isSafeInteger(value.revision) ||
     (value.revision as number) < 1 ||
@@ -1155,6 +1290,7 @@ function ensureEngineColumns(database: DatabaseSync): void {
   ensure("workflow_engine_tasks", [
     ["route_fingerprint", "TEXT"],
     ["context_request_json", "TEXT"],
+    ["attempt_diagnostic_json", "TEXT"],
   ]);
 }
 
@@ -1171,6 +1307,7 @@ export type DurableCandidateProposal =
       kind: "paused" | "retryable" | "approval-needed";
       code: string;
       contextRequest?: WorkflowContextRequest;
+      attemptDiagnostic?: SafeAttemptDiagnostic;
     }
   | { kind: "operation-cancelled"; code: "cancelled" };
 
@@ -1224,7 +1361,6 @@ interface DurableVerificationObservation {
 }
 
 interface DurableVerificationBaseline {
-  version: 1;
   revisionId: string;
   targetContracts: Array<{
     taskId: string;
@@ -1282,6 +1418,8 @@ export interface DurableWorkflowEngineOptions {
       attribution: "introduced";
       failureIdentities: string[];
     };
+    artifactCorrection?: RedArtifactCorrection;
+    contextRequest?: WorkflowContextRequest;
     signal: AbortSignal;
     onHeaders(): void;
     onProgress(): void;
@@ -1571,7 +1709,7 @@ function verificationIdentities(
     return [...new Set(supplied)].sort();
   }
   if (result.ok) return [];
-  return [hash("verification-failure-v1", scope, verification.id, result.code)];
+  return [hash("verification-failure", scope, verification.id, result.code)];
 }
 
 function parseVerificationBaseline(
@@ -1579,7 +1717,6 @@ function parseVerificationBaseline(
 ): DurableVerificationBaseline {
   if (
     !isRecord(value) ||
-    value.version !== 1 ||
     typeof value.revisionId !== "string" ||
     !SHA256.test(value.revisionId) ||
     !Array.isArray(value.targetContracts) ||
@@ -2038,7 +2175,6 @@ class DurableWorkflowComposition
     });
     if (!fullSuite.ok) return fullSuite;
     const baseline: DurableVerificationBaseline = {
-      version: 1,
       revisionId: input.resources.baselineRevisionId,
       targetContracts: plan.tasks.map((task) => ({
         taskId: task.taskId,
@@ -2319,6 +2455,9 @@ class DurableWorkflowComposition
     ledger: TaskLedger,
     input: Parameters<WorkflowWorker["runAttempt"]>[0],
   ): WorkflowAttemptOutcome | undefined {
+    if (input.artifactCorrection?.code === "red-artifact-constraint") {
+      return undefined;
+    }
     const projection = ledger.projection({
       runId: input.runId,
       taskId: input.taskId,
@@ -2866,7 +3005,13 @@ class DurableWorkflowComposition
           ...(request.routeFingerprint
             ? { expectedFingerprint: request.routeFingerprint }
             : {}),
-          requirements: IMPLEMENTATION_ROUTE_REQUIREMENTS,
+          requirements: implementationRouteRequirements({
+            task: request.task,
+            ...(request.artifactCorrection
+              ? { artifactCorrection: request.artifactCorrection }
+              : {}),
+            repair: { failureIdentities: input.failureIdentities },
+          }),
         });
         if (!rebound.ok) return { kind: "paused", code: rebound.code };
       }
@@ -2885,9 +3030,16 @@ class DurableWorkflowComposition
         runId: request.runId,
         operationId: `${request.operationId}:${request.taskId}:repair:${input.repairAttempt}`,
         role: "implementation-worker",
-        requirements: IMPLEMENTATION_ROUTE_REQUIREMENTS,
+        requirements: implementationRouteRequirements({
+          task: request.task,
+          ...(request.artifactCorrection
+            ? { artifactCorrection: request.artifactCorrection }
+            : {}),
+          repair: { failureIdentities: input.failureIdentities },
+        }),
         signal: request.signal,
         ...(request.onActivity ? { onActivity: request.onActivity } : {}),
+        classifyResult: semanticRouteFailure,
         execute: (attempt) => {
           identity = {
             candidateId: `candidate-${randomUUID()}`,
@@ -2925,6 +3077,12 @@ class DurableWorkflowComposition
             },
             route: attempt.route,
             repair,
+            ...(request.artifactCorrection
+              ? { artifactCorrection: request.artifactCorrection }
+              : {}),
+            ...(request.contextRequest
+              ? { contextRequest: request.contextRequest }
+              : {}),
             signal: attempt.signal,
             onHeaders: attempt.onHeaders,
             onProgress: attempt.onProgress,
@@ -2972,7 +3130,8 @@ class DurableWorkflowComposition
         proposal.kind !== "sealed-candidate"
       ) {
         return proposal.kind === "operation-cancelled" ||
-          proposal.kind === "paused"
+          proposal.kind === "paused" ||
+          proposal.kind === "approval-needed"
           ? withRoute(proposal)
           : reject(proposal, {
               category: "artifact",
@@ -3213,7 +3372,9 @@ class DurableWorkflowComposition
         changes: revisionChanges(proposalRoot, approvedPaths),
       });
       const requiredOutputs = request.plan.outputs.filter(
-        (output) => output.producer.taskId === request.taskId,
+        (output) =>
+          output.producer.taskId === request.taskId &&
+          (!request.artifactCorrection || output.producer.phase !== "refactor"),
       );
       if (
         requiredOutputs.some(
@@ -3352,7 +3513,7 @@ class DurableWorkflowComposition
   #verifiedPhaseReplay(
     ledger: TaskLedger,
     input: Parameters<WorkflowWorker["runAttempt"]>[0],
-  ): { artifactHash: string; exitCode: number } {
+  ): { artifactHash: string; exitCode: number; isolatedRevisionId: string } {
     const projection = ledger.projection({
       runId: input.runId,
       taskId: input.taskId,
@@ -3366,6 +3527,8 @@ class DurableWorkflowComposition
       !event ||
       typeof event.artifactHash !== "string" ||
       !SHA256.test(event.artifactHash) ||
+      typeof event.isolatedRevisionId !== "string" ||
+      !SHA256.test(event.isolatedRevisionId) ||
       typeof event.exitCode !== "number" ||
       event.actualClassification !== expectedClassification(input.phase)
     ) {
@@ -3374,6 +3537,285 @@ class DurableWorkflowComposition
     return {
       artifactHash: event.artifactHash,
       exitCode: event.exitCode,
+      isolatedRevisionId: event.isolatedRevisionId,
+    };
+  }
+
+  async #runRedArtifactCorrection(input: {
+    resources: DurableRunResources;
+    ledger: TaskLedger;
+    baseline?: DurableVerificationBaseline;
+    attempt: Parameters<WorkflowWorker["runAttempt"]>[0];
+  }): Promise<WorkflowAttemptOutcome> {
+    const { resources, ledger } = input;
+    const request = input.attempt;
+    if (
+      request.phase !== "green" ||
+      request.artifactCorrection?.code !== "red-artifact-constraint"
+    ) {
+      throw new Error("workflow-red-artifact-correction-invalid");
+    }
+    const priorRed = this.#verifiedPhaseReplay(ledger, {
+      ...request,
+      phase: "red",
+    });
+    if (!hasVerificationLifecycle(request.plan)) {
+      return { kind: "paused", code: "red-artifact-constraint" };
+    }
+    const stableRevisionId = resources.currentRevisionId;
+    const correctionPaths = [
+      ...new Set(
+        Object.values(request.task.phases).flatMap((phase) => [
+          ...phase.write,
+          ...phase.delete,
+        ]),
+      ),
+    ];
+    const rejectCorrection = async <T extends WorkflowAttemptOutcome>(
+      outcome: T,
+    ): Promise<T> => {
+      if (resources.currentRevisionId !== stableRevisionId) {
+        await this.#rollbackWorkspacePaths({
+          resources,
+          baseRevisionId: stableRevisionId,
+          rejectedRevisionId: resources.currentRevisionId,
+          paths: correctionPaths,
+        });
+      }
+      return outcome;
+    };
+    const failureIdentities = [
+      hash(
+        "red-artifact-constraint",
+        request.taskId,
+        request.task.phases.red.verification.id,
+      ),
+    ];
+    const correctionAttemptUsed = request.artifactCorrection.attempt;
+    if (
+      correctionAttemptUsed < 1 ||
+      correctionAttemptUsed > request.artifactCorrection.maxAttempts
+    ) {
+      throw new Error("workflow-red-artifact-correction-invalid");
+    }
+    const repaired = await this.#runRepairCandidate({
+      resources,
+      ledger,
+      attempt: request,
+      repairAttempt: correctionAttemptUsed,
+      failureIdentities,
+    });
+    if (repaired.kind !== "repair-committed") {
+      return rejectCorrection(repaired);
+    }
+
+    const correctedRevision = resources.workspaces.getRevision(
+      repaired.commit.isolatedRevisionId,
+    );
+    const acceptedRedRevision = resources.workspaces.getRevision(
+      priorRed.isolatedRevisionId,
+    );
+    if (!acceptedRedRevision.parentRevisionId) {
+      throw new Error("workflow-ledger-revision-base-invalid");
+    }
+    const correctedRedChanges: Record<
+      string,
+      { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
+    > = {};
+    for (const relative of [
+      ...new Set([
+        ...request.task.phases.red.write,
+        ...request.task.phases.red.delete,
+      ]),
+    ]) {
+      const entry = correctedRevision.entries[relative];
+      correctedRedChanges[relative] =
+        entry?.kind === "file"
+          ? {
+              kind: "file",
+              bytes: resources.artifacts.read(entry.hash),
+              mode: entry.mode,
+            }
+          : { kind: "absent" };
+    }
+    const correctedRedRevision = resources.workspaces.createRevision({
+      parentRevisionId: acceptedRedRevision.parentRevisionId,
+      changes: correctedRedChanges,
+    });
+    const verifyCorrectedContract = async (input: {
+      phase: "red" | "green";
+      revisionId: string;
+      verification: StructuredVerificationContract;
+    }): Promise<DurablePhaseVerificationResult> => {
+      const root = mkdtempSync(path.join(resources.root, "correction-check-"));
+      try {
+        resources.workspaces.materialize(input.revisionId, root);
+        return await this.#options.verifyPhase({
+          runId: request.runId,
+          deliveryRevision: request.deliveryRevision,
+          taskId: request.taskId,
+          phase: input.phase,
+          root,
+          verification: structuredClone(input.verification),
+          signal: request.signal,
+        });
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    };
+    emitWorkflowActivity(request.onActivity, { state: "verifying" });
+    const redVerification = await verifyCorrectedContract({
+      phase: "red",
+      revisionId: correctedRedRevision.revisionId,
+      verification: request.task.phases.red.verification,
+    });
+    if (!redVerification.ok) {
+      return rejectCorrection({
+        ...redVerification,
+        ...(redVerification.kind === "retryable"
+          ? { retryPolicy: "verification" as const }
+          : {}),
+      });
+    }
+    if (
+      redVerification.classification !== "expected-red" ||
+      redVerification.exitCode === 0
+    ) {
+      return rejectCorrection({
+        kind: "retryable",
+        code: "verification-rejected",
+        retryPolicy: "verification",
+      });
+    }
+    const greenVerification = await verifyCorrectedContract({
+      phase: "green",
+      revisionId: repaired.commit.isolatedRevisionId,
+      verification: request.task.phases.green.verification,
+    });
+    if (!greenVerification.ok) {
+      return rejectCorrection({
+        ...greenVerification,
+        ...(greenVerification.kind === "retryable"
+          ? { retryPolicy: "verification" as const }
+          : {}),
+      });
+    }
+    if (
+      greenVerification.classification !== "expected-green" ||
+      greenVerification.exitCode !== 0
+    ) {
+      return rejectCorrection({
+        kind: "retryable",
+        code: "verification-rejected",
+        retryPolicy: "verification",
+      });
+    }
+
+    const repairEvent: VerifiedTaskEvent = {
+      runId: request.runId,
+      taskId: request.taskId,
+      eventId: `red-artifact-correction-${hash(
+        request.operationId,
+        request.taskId,
+        repaired.commit.artifactHash,
+      ).slice(0, 40)}`,
+      kind: "repair-verified",
+      phase: request.phase,
+      attempt: correctionAttemptUsed,
+      commandId: request.task.repairVerification.id,
+      exitCode: 0,
+      diagnostic: repaired.commit.diagnostic,
+      artifactHash: repaired.commit.artifactHash,
+      isolatedRevisionId: repaired.commit.isolatedRevisionId,
+      outputFacts: repaired.commit.outputFacts,
+      attribution: "introduced",
+      failureIdentities: [
+        hash(
+          "red-artifact-constraint",
+          request.taskId,
+          request.task.phases.red.verification.id,
+        ),
+      ],
+      routeId: repaired.commit.routeId,
+      routeFingerprint: repaired.commit.routeFingerprint,
+    };
+    const greenPaths = new Set([
+      ...request.task.phases.green.write,
+      ...request.task.phases.green.delete,
+    ]);
+    const greenEvent: VerifiedTaskEvent = {
+      runId: request.runId,
+      taskId: request.taskId,
+      eventId: `green-corrected-${hash(
+        request.operationId,
+        request.taskId,
+        repaired.commit.artifactHash,
+      ).slice(0, 40)}`,
+      kind: "phase-verified",
+      phase: "green",
+      commandId: request.task.phases.green.verification.id,
+      exitCode: greenVerification.exitCode,
+      expectedClassification: "expected-green",
+      actualClassification: greenVerification.classification,
+      diagnostic: greenVerification.diagnostic,
+      artifactHash: repaired.commit.artifactHash,
+      isolatedRevisionId: repaired.commit.isolatedRevisionId,
+      outputFacts: repaired.commit.outputFacts.filter((fact) =>
+        greenPaths.has(fact.path),
+      ),
+      routeId: repaired.commit.routeId,
+      routeFingerprint: repaired.commit.routeFingerprint,
+    };
+    const events: VerifiedTaskEvent[] = [repairEvent, greenEvent];
+    if (input.baseline) {
+      const affected = await this.#verifyTaskAffected({
+        resources,
+        baseline: input.baseline,
+        task: request.task,
+        revisionId: repaired.commit.isolatedRevisionId,
+        signal: request.signal,
+      });
+      if (affected.kind === "repairable") {
+        return rejectCorrection({
+          kind: "retryable",
+          code: "red-artifact-constraint",
+          retryPolicy: "artifact",
+        });
+      }
+      if (affected.kind !== "verified") return rejectCorrection(affected);
+    }
+    if (request.task.phases.refactor) {
+      ledger.commitVerifiedEvents(events);
+      return {
+        kind: "phase-committed",
+        artifactHash: repaired.commit.artifactHash,
+        isolatedRevisionId: repaired.commit.isolatedRevisionId,
+        exitCode: greenVerification.exitCode,
+        classification: greenVerification.classification,
+        routeId: repaired.commit.routeId,
+        routeFingerprint: repaired.commit.routeFingerprint,
+      };
+    }
+    const completedRevision = this.#completeTracking(resources, request.taskId);
+    ledger.commitTaskCompletion({
+      events,
+      factKey: `task-final-${hash(request.taskId).slice(0, 40)}`,
+      fact: {
+        taskId: request.taskId,
+        phase: request.phase,
+        isolatedRevisionId: completedRevision.revisionId,
+        attribution: "introduced",
+        repairAttempts: correctionAttemptUsed,
+      },
+    });
+    return {
+      kind: "phase-committed",
+      artifactHash: repaired.commit.artifactHash,
+      isolatedRevisionId: completedRevision.revisionId,
+      exitCode: greenVerification.exitCode,
+      classification: greenVerification.classification,
+      routeId: repaired.commit.routeId,
+      routeFingerprint: repaired.commit.routeFingerprint,
     };
   }
 
@@ -3598,6 +4040,16 @@ class DurableWorkflowComposition
       verificationBaseline = captured.baseline;
     }
     this.#openTask(resources, ledger, input);
+    if (input.artifactCorrection?.code === "red-artifact-constraint") {
+      return retained(
+        await this.#runRedArtifactCorrection({
+          resources,
+          ledger,
+          ...(verificationBaseline ? { baseline: verificationBaseline } : {}),
+          attempt: input,
+        }),
+      );
+    }
     if (input.repair) {
       if (!verificationBaseline) {
         throw new Error("workflow-verification-baseline-unavailable");
@@ -3644,7 +4096,13 @@ class DurableWorkflowComposition
           ...(input.routeFingerprint
             ? { expectedFingerprint: input.routeFingerprint }
             : {}),
-          requirements: IMPLEMENTATION_ROUTE_REQUIREMENTS,
+          requirements: implementationRouteRequirements({
+            task: input.task,
+            ...(input.artifactCorrection
+              ? { artifactCorrection: input.artifactCorrection }
+              : {}),
+            ...(input.repair ? { repair: input.repair } : {}),
+          }),
         });
         if (!rebound.ok) {
           return retained({ kind: "paused", code: rebound.code });
@@ -3660,9 +4118,16 @@ class DurableWorkflowComposition
         runId: input.runId,
         operationId: `${input.operationId}:${input.taskId}:${input.phase}`,
         role: "implementation-worker",
-        requirements: IMPLEMENTATION_ROUTE_REQUIREMENTS,
+        requirements: implementationRouteRequirements({
+          task: input.task,
+          ...(input.artifactCorrection
+            ? { artifactCorrection: input.artifactCorrection }
+            : {}),
+          ...(input.repair ? { repair: input.repair } : {}),
+        }),
         signal: input.signal,
         ...(input.onActivity ? { onActivity: input.onActivity } : {}),
+        classifyResult: semanticRouteFailure,
         execute: (attempt) => {
           identity = {
             candidateId: `candidate-${randomUUID()}`,
@@ -3699,6 +4164,9 @@ class DurableWorkflowComposition
               deletePaths: phase.delete,
             },
             route: attempt.route,
+            ...(input.contextRequest
+              ? { contextRequest: input.contextRequest }
+              : {}),
             signal: attempt.signal,
             onHeaders: attempt.onHeaders,
             onProgress: attempt.onProgress,
@@ -3747,7 +4215,8 @@ class DurableWorkflowComposition
         proposal.kind !== "sealed-candidate"
       ) {
         return proposal.kind === "operation-cancelled" ||
-          proposal.kind === "paused"
+          proposal.kind === "paused" ||
+          proposal.kind === "approval-needed"
           ? retained(proposal)
           : reject(proposal, {
               category: "artifact",
@@ -4277,7 +4746,7 @@ class DurableWorkflowComposition
       runId: input.runId,
       role: input.role,
       routeId: input.routeId,
-      requirements: IMPLEMENTATION_ROUTE_REQUIREMENTS,
+      requirements: implementationRouteRequirements({ task: input.task }),
     });
     return rebound.ok
       ? {
@@ -5080,8 +5549,18 @@ export class WorkflowEngine {
       this.#database
         .prepare(
           `UPDATE workflow_engine_tasks
-           SET state = 'paused', pause_code = 'operation-interrupted',
-               context_request_json = NULL, queue_position = NULL
+           SET state = 'paused',
+               pause_code = CASE
+                 WHEN pause_code = 'red-artifact-constraint'
+                   THEN pause_code
+                 ELSE 'operation-interrupted'
+               END,
+               context_request_json = CASE
+                 WHEN pause_code = 'red-artifact-constraint'
+                   THEN context_request_json
+                 ELSE NULL
+               END,
+               queue_position = NULL
            WHERE run_id = ? AND state IN ('phase-running', 'validating')`,
         )
         .run(row.run_id);
@@ -5154,8 +5633,8 @@ export class WorkflowEngine {
     return this.#database
       .prepare(
         `SELECT task_id, task_order, delivery_revision, plan_json, state,
-                phase, pause_code, context_request_json, route_id,
-                route_fingerprint, queue_position
+                phase, pause_code, context_request_json, attempt_diagnostic_json,
+                route_id, route_fingerprint, queue_position
          FROM workflow_engine_tasks WHERE run_id = ? ORDER BY task_order`,
       )
       .all(runId) as unknown as EngineTaskRow[];
@@ -5452,7 +5931,8 @@ export class WorkflowEngine {
             `UPDATE workflow_engine_tasks
              SET task_order = ?, delivery_revision = ?, plan_json = ?,
                  state = 'pending', phase = 'red', pause_code = NULL,
-                 context_request_json = NULL, queue_position = NULL
+                 context_request_json = NULL, attempt_diagnostic_json = NULL,
+                 queue_position = NULL
              WHERE run_id = ? AND task_id = ?`,
           )
           .run(taskOrder, delivery.revision, taskJson, runId, task.taskId);
@@ -5509,6 +5989,7 @@ export class WorkflowEngine {
       phase?: "red" | "green" | "refactor";
       pauseCode?: string | null;
       contextRequest?: WorkflowContextRequest | null;
+      attemptDiagnostic?: SafeAttemptDiagnostic | null;
       routeId?: string | null;
       routeFingerprint?: string | null;
       queuePosition?: number | null;
@@ -5539,6 +6020,14 @@ export class WorkflowEngine {
             ),
       );
     }
+    if (values.attemptDiagnostic !== undefined) {
+      assignments.push("attempt_diagnostic_json = ?");
+      parameters.push(
+        values.attemptDiagnostic === null
+          ? null
+          : JSON.stringify(values.attemptDiagnostic),
+      );
+    }
     if (values.routeId !== undefined) {
       assignments.push("route_id = ?");
       parameters.push(values.routeId);
@@ -5745,6 +6234,24 @@ export class WorkflowEngine {
     const orderedPhases = phases(task);
     let phaseIndex = orderedPhases.indexOf(row.phase);
     let artifactAttempts = 0;
+    const persistedContextRequest = row.context_request_json
+      ? normalizeWorkflowContextRequest(
+          JSON.parse(row.context_request_json) as unknown,
+        )
+      : undefined;
+    const persistedRedArtifactCorrection =
+      row.phase === "green" &&
+      persistedContextRequest !== undefined &&
+      classifyPersistedContextRequest(persistedContextRequest, task, "green")
+        .code === "red-artifact-constraint";
+    let redArtifactCorrection =
+      row.phase === "green" &&
+      (row.pause_code === "red-artifact-constraint" ||
+        persistedRedArtifactCorrection);
+    let requestedContext = persistedContextRequest;
+    let correctionContextRequest = redArtifactCorrection
+      ? persistedContextRequest
+      : undefined;
     if (phaseIndex < 0) throw new Error("workflow-task-phase-invalid");
     while (phaseIndex < orderedPhases.length) {
       const phase = orderedPhases[phaseIndex];
@@ -5771,6 +6278,7 @@ export class WorkflowEngine {
             JSON.parse(current.verification_json) as unknown,
           )
         : undefined;
+      const plan = this.#planForRevision(runId, row.delivery_revision);
       const repair =
         verificationStatus?.scope === "change-task-affected" &&
         verificationStatus.attribution === "introduced" &&
@@ -5782,19 +6290,32 @@ export class WorkflowEngine {
               failureIdentities: [...verificationStatus.failureIdentities],
             }
           : undefined;
+      const artifactCorrection =
+        redArtifactCorrection && phase === "green"
+          ? {
+              code: "red-artifact-constraint" as const,
+              attempt: artifactAttempts + 1,
+              maxAttempts: plan.verification.artifactCorrection.maxAttempts,
+              ...(correctionContextRequest
+                ? {
+                    contextRequest: structuredClone(correctionContextRequest),
+                  }
+                : {}),
+            }
+          : undefined;
       this.#setTask(
         runId,
         row.task_id,
         {
           state: "phase-running",
           phase,
-          pauseCode: null,
-          contextRequest: null,
+          pauseCode: artifactCorrection?.code ?? null,
+          contextRequest: requestedContext ?? null,
+          attemptDiagnostic: null,
           queuePosition: null,
         },
         lease,
       );
-      const plan = this.#planForRevision(runId, row.delivery_revision);
       let outcome: WorkflowAttemptOutcome;
       try {
         outcome = await this.#worker.runAttempt({
@@ -5825,6 +6346,8 @@ export class WorkflowEngine {
               }
             : {}),
           ...(repair ? { repair } : {}),
+          ...(artifactCorrection ? { artifactCorrection } : {}),
+          ...(requestedContext ? { contextRequest: requestedContext } : {}),
           signal,
           onActivity: (event) => {
             const projection = this.#runStore.status(runId);
@@ -5863,10 +6386,69 @@ export class WorkflowEngine {
       ) {
         this.#setVerificationStatus(runId, outcome.verification, lease);
       }
+      if (
+        outcome.kind !== "phase-committed" &&
+        outcome.kind !== "operation-cancelled" &&
+        outcome.contextRequest
+      ) {
+        requestedContext = normalizeWorkflowContextRequest(
+          outcome.contextRequest,
+        );
+      }
+      if (
+        outcome.kind !== "phase-committed" &&
+        outcome.kind !== "operation-cancelled" &&
+        outcome.attemptDiagnostic
+      ) {
+        const previous = row.attempt_diagnostic_json
+          ? (JSON.parse(row.attempt_diagnostic_json) as SafeAttemptDiagnostic)
+          : undefined;
+        const fingerprint = hash(
+          outcome.code,
+          outcome.attemptDiagnostic.finalCategory ?? "unknown",
+          outcome.attemptDiagnostic.schema ?? "unknown",
+          JSON.stringify(outcome.attemptDiagnostic.identityMismatch ?? []),
+        ).slice(0, 16);
+        const sameFailure = previous?.fingerprint === fingerprint;
+        const sameFailureCount = sameFailure
+          ? (previous?.sameFailureCount ?? 1) + 1
+          : 1;
+        const attemptDiagnostic = {
+          ...outcome.attemptDiagnostic,
+          fingerprint,
+          sameFailureCount,
+          ...(sameFailureCount > 1
+            ? { action: "rebind-or-revise-delivery" as const }
+            : {}),
+        };
+        this.#setTask(runId, row.task_id, { attemptDiagnostic }, lease);
+        row.attempt_diagnostic_json = JSON.stringify(attemptDiagnostic);
+      }
       if (outcome.kind === "retryable" && outcome.retryPolicy === "artifact") {
+        if (outcome.code === "red-artifact-constraint") {
+          redArtifactCorrection = true;
+          correctionContextRequest = outcome.contextRequest
+            ? normalizeWorkflowContextRequest(outcome.contextRequest)
+            : correctionContextRequest;
+          requestedContext = correctionContextRequest ?? requestedContext;
+        }
         artifactAttempts += 1;
         const maxAttempts = plan.verification.artifactCorrection.maxAttempts;
         if (artifactAttempts < maxAttempts) {
+          this.#setTask(
+            runId,
+            row.task_id,
+            {
+              state: "retryable",
+              phase,
+              pauseCode: redArtifactCorrection
+                ? "red-artifact-constraint"
+                : outcome.code,
+              contextRequest: requestedContext ?? null,
+              queuePosition: null,
+            },
+            lease,
+          );
           emitWorkflowActivity(onActivity, {
             state: "retrying",
             stage: this.#runStore.status(runId).stage,
@@ -5903,6 +6485,7 @@ export class WorkflowEngine {
               phase,
               pauseCode: null,
               contextRequest: null,
+              attemptDiagnostic: null,
               queuePosition: null,
             },
             lease,
@@ -5910,6 +6493,9 @@ export class WorkflowEngine {
           return;
         }
         artifactAttempts = 0;
+        redArtifactCorrection = false;
+        requestedContext = undefined;
+        correctionContextRequest = undefined;
         phaseIndex += 1;
         if (phaseIndex >= orderedPhases.length) {
           this.#setTask(
@@ -5920,6 +6506,7 @@ export class WorkflowEngine {
               phase,
               pauseCode: null,
               contextRequest: null,
+              attemptDiagnostic: null,
               queuePosition: null,
             },
             lease,
@@ -5934,6 +6521,7 @@ export class WorkflowEngine {
             phase: orderedPhases[phaseIndex],
             pauseCode: null,
             contextRequest: null,
+            attemptDiagnostic: null,
             queuePosition: null,
           },
           lease,
@@ -5975,10 +6563,9 @@ export class WorkflowEngine {
             pauseCode: approvalCodeInvalid
               ? "approval-code-invalid"
               : outcome.code,
-            contextRequest:
-              !approvalCodeInvalid && outcome.contextRequest
-                ? normalizeWorkflowContextRequest(outcome.contextRequest)
-                : null,
+            contextRequest: approvalCodeInvalid
+              ? null
+              : (requestedContext ?? null),
             queuePosition: null,
           },
           lease,
@@ -5990,11 +6577,119 @@ export class WorkflowEngine {
   }
 
   #firstPaused(rows: EngineTaskRow[]): EngineTaskRow | undefined {
-    return rows.find((row) =>
-      ["paused", "retryable", "approval-needed"].includes(row.state),
+    return (
+      rows.find((row) => row.state === "approval-needed") ??
+      rows.find((row) => ["paused", "retryable"].includes(row.state))
     );
   }
 
+  #recoverLegacyContextApproval(runId: string): boolean {
+    const projection = this.#runStore.status(runId);
+    if (!["approval-needed", "paused"].includes(projection.state)) return false;
+    const rows = this.#tasks(runId);
+    const approvalRows = rows.filter((row) => row.state === "approval-needed");
+    if (approvalRows.length === 0) return false;
+    const reclassified = rows.flatMap((row) => {
+      if (
+        row.state !== "approval-needed" ||
+        row.pause_code !== "boundary-review-needed" ||
+        row.context_request_json === null
+      ) {
+        return [];
+      }
+      try {
+        const request = normalizeWorkflowContextRequest(
+          JSON.parse(row.context_request_json) as unknown,
+        );
+        const classified = classifyPersistedContextRequest(
+          request,
+          this.#taskPlan(row),
+          row.phase,
+        );
+        if (classified.kind === "approval-needed") return [];
+        return [
+          {
+            row,
+            state: classified.kind === "retryable" ? "retryable" : "paused",
+            code: classified.code,
+            contextRequest: JSON.stringify(
+              normalizeWorkflowContextRequest(classified.contextRequest),
+            ),
+          },
+        ];
+      } catch {
+        return [];
+      }
+    });
+    const reclassifiedTaskIds = new Set(
+      reclassified.map((entry) => entry.row.task_id),
+    );
+    const retainedApprovals = approvalRows.filter(
+      (row) => !reclassifiedTaskIds.has(row.task_id),
+    );
+    const updateTasks = (database: DatabaseSync) => {
+      for (const entry of reclassified) {
+        const updated = database
+          .prepare(
+            `UPDATE workflow_engine_tasks
+             SET state = ?, phase = ?, pause_code = ?, context_request_json = ?,
+                 queue_position = NULL
+             WHERE run_id = ? AND task_id = ?
+               AND state = 'approval-needed'
+               AND pause_code = 'boundary-review-needed'`,
+          )
+          .run(
+            entry.state,
+            entry.row.phase,
+            entry.code,
+            entry.contextRequest,
+            runId,
+            entry.row.task_id,
+          );
+        if (Number(updated.changes) !== 1) {
+          throw new Error("workflow-legacy-context-race");
+        }
+      }
+    };
+    const transitionWithUpdates = (
+      to: "paused" | "approval-needed",
+      code: string,
+    ) =>
+      this.#runStore.transitionAtomically(
+        {
+          runId,
+          to,
+          operationId: `legacy-context-${hash(
+            runId,
+            String(projection.sequence),
+            to,
+            code,
+            JSON.stringify(
+              reclassified.map((entry) => [entry.row.task_id, entry.code]),
+            ),
+          ).slice(0, 40)}`,
+          code,
+        },
+        updateTasks,
+      );
+    if (retainedApprovals.length > 0) {
+      if (projection.state === "approval-needed") {
+        if (reclassified.length === 0) return false;
+        this.#transaction(() => updateTasks(this.#database));
+      } else {
+        transitionWithUpdates(
+          "approval-needed",
+          retainedApprovals[0].pause_code ?? "approval-code-invalid",
+        );
+      }
+      return true;
+    }
+    const first = reclassified[0];
+    if (!first) return false;
+    transitionWithUpdates("paused", first.code);
+    return true;
+  }
+
   async #finishChange(
     runId: string,
     operationId: string,
@@ -6568,6 +7263,21 @@ export class WorkflowEngine {
     return this.#statusByRun(runId);
   }
 
+  #safeAttemptDiagnostic(
+    _runId: string,
+    row: EngineTaskRow | undefined,
+  ): SafeAttemptDiagnostic | undefined {
+    if (!row) return undefined;
+    if (row.attempt_diagnostic_json) {
+      try {
+        return JSON.parse(row.attempt_diagnostic_json) as SafeAttemptDiagnostic;
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  }
+
   #statusByRun(runId: string): Record<string, unknown> {
     const projection = this.#runStore.status(runId);
     const rows = this.#tasks(runId);
@@ -6592,14 +7302,17 @@ export class WorkflowEngine {
         )
       : undefined;
     const pauseCode =
-      projection.pauseCode ?? firstPaused?.pause_code ?? "task-paused";
+      projection.state === "approval-needed" &&
+      firstPaused?.state === "approval-needed"
+        ? (firstPaused.pause_code ?? projection.pauseCode ?? "task-paused")
+        : (projection.pauseCode ?? firstPaused?.pause_code ?? "task-paused");
     const approval =
       projection.state === "approval-needed"
         ? approvalRequirement(pauseCode, contextRequest)
         : undefined;
+    const attemptDiagnostic = this.#safeAttemptDiagnostic(runId, firstPaused);
     const currentRevision = projection.deliveryRevision ?? 0;
     return {
-      version: 2,
       runId: projection.runId,
       stage: projection.stage,
       ...(projection.change ? { change: projection.change } : {}),
@@ -6616,6 +7329,7 @@ export class WorkflowEngine {
         ? {
             pause: {
               code: pauseCode,
+              ...(attemptDiagnostic ? { diagnostic: attemptDiagnostic } : {}),
             },
           }
         : {}),
@@ -6941,6 +7655,7 @@ export class WorkflowEngine {
   ) {
     const runId = this.#lookupRun(command.stage, command.change);
     if (!runId) throw new Error("run-not-found");
+    this.#recoverLegacyContextApproval(runId);
     const replay = this.#beginOperation(
       runId,
       command.operationId,
@@ -7098,6 +7813,7 @@ export class WorkflowEngine {
     const rebound = this.#worker.rebind({
       runId,
       taskId: task.task_id,
+      task: structuredClone(this.#taskPlan(task)),
       role: "implementation-worker",
       routeId: command.routeId,
     });
@@ -7336,7 +8052,19 @@ export class WorkflowEngine {
         );
       case "status": {
         const runId = this.#lookupRun(command.stage, command.change);
-        if (!runId) throw new Error("run-not-found");
+        if (!runId) {
+          return {
+            stage: command.stage,
+            change: command.change,
+            state: "not-started",
+            durable: true,
+            completed: false,
+            legalCommands: ["start"],
+            tasks: [],
+            queue: [],
+          };
+        }
+        this.#recoverLegacyContextApproval(runId);
         return this.#withAvailableDelivery(this.#statusByRun(runId));
       }
       case "resume":
@@ -7401,7 +8129,7 @@ export class WorkflowEngine {
         outcome.handoffId === existing.handoff_id &&
         outcome.runId === existing.owner_run_id &&
         outcome.receiptHash === existing.receipt_hash &&
-        outcome.selectorBeforeCutover === "v1-bootstrap" &&
+        outcome.selectorBeforeCutover === "bootstrap" &&
         existing.state === "prepared" &&
         outcome.state === "prepared" &&
         outcome.selectorCasPending === true;
@@ -7422,7 +8150,7 @@ export class WorkflowEngine {
       if (
         existing.state !== "prepared" ||
         outcome.state !== "prepared" ||
-        outcome.selectorBeforeCutover !== "v1-bootstrap" ||
+        outcome.selectorBeforeCutover !== "bootstrap" ||
         outcome.selectorCasPending !== true ||
         acceptanceFacts === undefined ||
         workspaceManifestHash === undefined
@@ -7479,7 +8207,7 @@ export class WorkflowEngine {
       acceptanceHash: input.acceptanceHash,
       ...(acceptanceFacts ? { acceptanceFacts } : {}),
       ...(workspaceManifestHash ? { workspaceManifestHash } : {}),
-      selectorBeforeCutover: "v1-bootstrap",
+      selectorBeforeCutover: "bootstrap",
       selectorCasPending: true,
     };
     const preparedRows = this.#database