@abelxiaoxing/cadence 1.2.1 → 1.2.3

package/src/delivery-compiler.ts

@@ -19,9 +19,7 @@ import {
 } from "./implement-graph.ts";
 import { validateVerificationAdapterCapability } from "./verification-capability.ts";
 
-export const IMPLEMENT_PLAN_SCHEMA_VERSION = 3 as const;
 export const IMPLEMENT_PLAN_PATH = "implement-plan.json" as const;
-export const DELIVERY_RECEIPT_VERSION = 4 as const;
 export const GATE_A_RECEIPT_PATH = "gate-a.yaml" as const;
 export const READY_RECEIPT_PATH = "ready.yaml" as const;
 
@@ -42,7 +40,6 @@ export interface GateApprovalProof {
 }
 
 export interface GateAReceipt {
-  receiptVersion: typeof DELIVERY_RECEIPT_VERSION;
   change: string;
   schema: string;
   approval: GateApprovalProof;
@@ -58,7 +55,6 @@ export interface DeliveryTraceability {
 }
 
 export interface ReadyReceipt {
-  receiptVersion: typeof DELIVERY_RECEIPT_VERSION;
   change: string;
   schema: string;
   deliveryRevision: number;
@@ -98,6 +94,79 @@ export class DeliveryValidationError extends Error {
   }
 }
 
+export interface DesignPlanDiagnostic {
+  code: string;
+  taskId?: string;
+  phase?: string;
+  field?: string;
+  category?: string;
+  owner?: string;
+  verificationId?: string;
+  outputId?: string;
+  dependencyTaskId?: string;
+  producerTaskId?: string;
+  producerPhase?: string;
+}
+
+export class DesignPlanValidationError extends Error {
+  readonly diagnostics: readonly DesignPlanDiagnostic[];
+
+  constructor(message: string, diagnostics: readonly DesignPlanDiagnostic[]) {
+    const normalized = [
+      ...new Map(
+        diagnostics
+          .map((diagnostic) => structuredClone(diagnostic))
+          .sort((left, right) =>
+            canonicalJson(left).localeCompare(canonicalJson(right)),
+          )
+          .map((diagnostic) => [canonicalJson(diagnostic), diagnostic]),
+      ).values(),
+    ];
+    super(message);
+    this.name = "DesignPlanValidationError";
+    this.diagnostics = Object.freeze(normalized);
+  }
+}
+
+const SAFE_PLAN_ERROR_CODE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/u;
+
+function planErrorCode(error: unknown): string {
+  const message = error instanceof Error ? error.message : "";
+  return SAFE_PLAN_ERROR_CODE.test(message) ? message : "delivery-plan-invalid";
+}
+
+function planDiagnosticField(code: string): string | undefined {
+  const fields: Record<string, string> = {
+    "delivery-plan-invalid-task": "task",
+    "delivery-plan-invalid-task-phases": "phases",
+    "delivery-plan-invalid-phase": "phases",
+    "delivery-plan-empty-phase-boundary": "phases",
+    "delivery-plan-write-delete-overlap": "phases",
+    "delivery-verification-invalid": "verification",
+    "delivery-task-verification-invalid": "affectedVerification",
+    "delivery-agents-checkpoint-mismatch": "verification.agentsCheckpoint",
+  };
+  return fields[code];
+}
+
+function asPlanValidationError(
+  error: unknown,
+  context: Omit<DesignPlanDiagnostic, "code"> = {},
+): DesignPlanValidationError {
+  if (error instanceof DesignPlanValidationError) {
+    const diagnostics = error.diagnostics.map((diagnostic) => ({
+      ...context,
+      ...diagnostic,
+    }));
+    return new DesignPlanValidationError(error.message, diagnostics);
+  }
+  const code = planErrorCode(error);
+  const field = planDiagnosticField(code);
+  return new DesignPlanValidationError(code, [
+    { code, ...context, ...(field ? { field } : {}) },
+  ]);
+}
+
 export function assessDeliveryTraceability(input: {
   tasksMarkdown: string;
   specs: readonly { path: string; text: string }[];
@@ -197,7 +266,7 @@ export interface PlanVerification {
     target: "task-red-contracts";
     affected: "task-affected-contracts";
     fullSuite: StructuredVerificationContract;
-    failureIdentity: "normalized-v1";
+    failureIdentity: "normalized";
   };
   change: {
     affected: "task-affected-contracts";
@@ -235,7 +304,6 @@ export interface PlanTracking {
 }
 
 export interface PlanDraft {
-  schemaVersion: typeof IMPLEMENT_PLAN_SCHEMA_VERSION;
   changeId: string;
   tasks: PlanTaskDraft[];
   outputs: ImplementGraphOutput[];
@@ -243,9 +311,7 @@ export interface PlanDraft {
   tracking: PlanTracking;
 }
 
-export interface ImplementPlan extends PlanDraft {
-  schemaVersion: typeof IMPLEMENT_PLAN_SCHEMA_VERSION;
-}
+export type ImplementPlan = PlanDraft;
 
 export interface CompiledDelivery {
   plan: ImplementPlan;
@@ -256,7 +322,6 @@ export interface CompiledDelivery {
   receipt: {
     plan: {
       path: typeof IMPLEMENT_PLAN_PATH;
-      schemaVersion: typeof IMPLEMENT_PLAN_SCHEMA_VERSION;
       rawSha256: string;
       canonicalHash: string;
     };
@@ -360,7 +425,6 @@ export function compileGateAReceipt(input: {
 }): { receipt: GateAReceipt; bytes: Uint8Array; rawSha256: string } {
   requireReceiptIdentity(input.change, input.schema);
   const receipt: GateAReceipt = {
-    receiptVersion: DELIVERY_RECEIPT_VERSION,
     change: input.change,
     schema: input.schema,
     approval: normalizeGateProof(input.approval),
@@ -381,14 +445,7 @@ export function parseGateAReceipt(bytes: Uint8Array): GateAReceipt {
   );
   if (
     !isRecord(receipt) ||
-    !exactKeys(receipt, [
-      "receiptVersion",
-      "change",
-      "schema",
-      "approval",
-      "artifacts",
-    ]) ||
-    receipt.receiptVersion !== DELIVERY_RECEIPT_VERSION ||
+    !exactKeys(receipt, ["change", "schema", "approval", "artifacts"]) ||
     !isRecord(receipt.approval) ||
     !exactKeys(receipt.approval, ["revision", "contractHash", "recordHash"])
   ) {
@@ -454,7 +511,6 @@ export function compileReadyReceipt(input: {
     throw new Error("delivery-receipt-invalid");
   }
   const receipt: ReadyReceipt = {
-    receiptVersion: DELIVERY_RECEIPT_VERSION,
     change: input.change,
     schema: input.schema,
     deliveryRevision: input.deliveryRevision,
@@ -489,7 +545,6 @@ export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
   if (
     !isRecord(receipt) ||
     !exactKeys(receipt, [
-      "receiptVersion",
       "change",
       "schema",
       "deliveryRevision",
@@ -500,7 +555,6 @@ export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
       "traceability",
       "openspec",
     ]) ||
-    receipt.receiptVersion !== DELIVERY_RECEIPT_VERSION ||
     !Number.isSafeInteger(receipt.deliveryRevision) ||
     receipt.deliveryRevision < 1 ||
     !isRecord(receipt.approvals) ||
@@ -516,14 +570,8 @@ export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
       "recordHash",
     ]) ||
     !isRecord(receipt.plan) ||
-    !exactKeys(receipt.plan, [
-      "path",
-      "schemaVersion",
-      "rawSha256",
-      "canonicalHash",
-    ]) ||
+    !exactKeys(receipt.plan, ["path", "rawSha256", "canonicalHash"]) ||
     receipt.plan.path !== IMPLEMENT_PLAN_PATH ||
-    receipt.plan.schemaVersion !== IMPLEMENT_PLAN_SCHEMA_VERSION ||
     !SHA256.test(receipt.plan.rawSha256) ||
     !SHA256.test(receipt.plan.canonicalHash) ||
     !isRecord(receipt.verificationClosure) ||
@@ -603,6 +651,9 @@ function normalizePhase(value: unknown): PlanPhaseDraft {
   }
   const write = sortStrings(value.write as string[]);
   const deletions = sortStrings(value.delete as string[]);
+  if (write.length + deletions.length === 0) {
+    throw new Error("delivery-plan-empty-phase-boundary");
+  }
   if (write.some((candidate) => deletions.includes(candidate))) {
     throw new Error("delivery-plan-write-delete-overlap");
   }
@@ -625,60 +676,97 @@ function normalizePhase(value: unknown): PlanPhaseDraft {
 }
 
 function normalizeTask(value: unknown): PlanTaskDraft {
-  if (
-    !isRecord(value) ||
-    !isRecord(value.phases) ||
-    !isRecord(value.affectedVerification) ||
-    !isRecord(value.repairVerification)
-  ) {
-    throw new Error("delivery-plan-invalid-task");
-  }
-  const phases = value.phases;
-  if (!Object.hasOwn(phases, "red") || !Object.hasOwn(phases, "green")) {
-    throw new Error("delivery-plan-invalid-task-phases");
-  }
-  const cloned = structuredClone(value) as unknown as PlanTaskDraft;
-  const affectedVerification = normalizeVerification(
-    value.affectedVerification,
-  );
-  const repairVerification = normalizeVerification(value.repairVerification);
-  if (
-    affectedVerification.classification !== "expected-green" ||
-    repairVerification.classification !== "expected-green"
-  ) {
-    throw new Error("delivery-task-verification-invalid");
+  const taskId =
+    isRecord(value) && typeof value.taskId === "string"
+      ? value.taskId
+      : undefined;
+  const context = taskId ? { taskId } : {};
+  try {
+    if (
+      !isRecord(value) ||
+      !isRecord(value.phases) ||
+      !isRecord(value.affectedVerification) ||
+      !isRecord(value.repairVerification)
+    ) {
+      throw new Error("delivery-plan-invalid-task");
+    }
+    const phases = value.phases;
+    if (!Object.hasOwn(phases, "red") || !Object.hasOwn(phases, "green")) {
+      throw new Error("delivery-plan-invalid-task-phases");
+    }
+    const cloned = structuredClone(value) as unknown as PlanTaskDraft;
+    let affectedVerification: StructuredVerificationContract;
+    try {
+      affectedVerification = normalizeVerification(value.affectedVerification);
+    } catch (error) {
+      throw asPlanValidationError(error, {
+        ...context,
+        field: "affectedVerification",
+      });
+    }
+    let repairVerification: StructuredVerificationContract;
+    try {
+      repairVerification = normalizeVerification(value.repairVerification);
+    } catch (error) {
+      throw asPlanValidationError(error, {
+        ...context,
+        field: "repairVerification",
+      });
+    }
+    if (
+      affectedVerification.classification !== "expected-green" ||
+      repairVerification.classification !== "expected-green"
+    ) {
+      throw new Error("delivery-task-verification-invalid");
+    }
+    const normalizeTaskPhase = (
+      phase: "red" | "green" | "refactor",
+      candidate: unknown,
+    ) => {
+      try {
+        return normalizePhase(candidate);
+      } catch (error) {
+        throw asPlanValidationError(error, {
+          ...context,
+          phase,
+          field: `phases.${phase}`,
+        });
+      }
+    };
+    return {
+      ...cloned,
+      dependsOn: sortStrings(cloned.dependsOn),
+      roots: sortStrings(cloned.roots),
+      phases: {
+        red: normalizeTaskPhase("red", phases.red),
+        green: normalizeTaskPhase("green", phases.green),
+        ...(phases.refactor !== undefined
+          ? { refactor: normalizeTaskPhase("refactor", phases.refactor) }
+          : {}),
+      },
+      scheduling: {
+        conflicts: sortStrings(cloned.scheduling.conflicts),
+        resources: sortStrings(cloned.scheduling.resources),
+      },
+      approvedDependencies: sortStrings(cloned.approvedDependencies),
+      affectedVerification,
+      repairVerification,
+      impactClosure: {
+        changedSurfaces: sortStrings(
+          cloned.impactClosure.changedSurfaces,
+        ) as PlanTaskDraft["impactClosure"]["changedSurfaces"],
+        searchEvidence: sortStrings(cloned.impactClosure.searchEvidence),
+        relatedTests: [...cloned.impactClosure.relatedTests].sort(
+          (left, right) =>
+            left.path.localeCompare(right.path) ||
+            left.disposition.localeCompare(right.disposition),
+        ),
+        affectedSuite: sortStrings(cloned.impactClosure.affectedSuite),
+      },
+    };
+  } catch (error) {
+    throw asPlanValidationError(error, context);
   }
-  return {
-    ...cloned,
-    dependsOn: sortStrings(cloned.dependsOn),
-    roots: sortStrings(cloned.roots),
-    phases: {
-      red: normalizePhase(phases.red),
-      green: normalizePhase(phases.green),
-      ...(phases.refactor !== undefined
-        ? { refactor: normalizePhase(phases.refactor) }
-        : {}),
-    },
-    scheduling: {
-      conflicts: sortStrings(cloned.scheduling.conflicts),
-      resources: sortStrings(cloned.scheduling.resources),
-    },
-    approvedDependencies: sortStrings(cloned.approvedDependencies),
-    affectedVerification,
-    repairVerification,
-    impactClosure: {
-      changedSurfaces: sortStrings(
-        cloned.impactClosure.changedSurfaces,
-      ) as PlanTaskDraft["impactClosure"]["changedSurfaces"],
-      searchEvidence: sortStrings(cloned.impactClosure.searchEvidence),
-      relatedTests: [...cloned.impactClosure.relatedTests].sort(
-        (left, right) =>
-          left.path.localeCompare(right.path) ||
-          left.disposition.localeCompare(right.disposition),
-      ),
-      affectedSuite: sortStrings(cloned.impactClosure.affectedSuite),
-    },
-  };
 }
 
 function graphFromPlan(plan: ImplementPlan): ImplementGraphBoundary {
@@ -870,7 +958,7 @@ function normalizeVerificationPlan(value: unknown): PlanVerification {
     ]) ||
     value.baseline.target !== "task-red-contracts" ||
     value.baseline.affected !== "task-affected-contracts" ||
-    value.baseline.failureIdentity !== "normalized-v1" ||
+    value.baseline.failureIdentity !== "normalized" ||
     !isRecord(value.change) ||
     !exactKeys(value.change, ["affected", "fullSuite", "postApply"]) ||
     value.change.affected !== "task-affected-contracts" ||
@@ -919,7 +1007,7 @@ function normalizeVerificationPlan(value: unknown): PlanVerification {
       target: "task-red-contracts",
       affected: "task-affected-contracts",
       fullSuite: normalizeExpectedGreenVerification(value.baseline.fullSuite),
-      failureIdentity: "normalized-v1",
+      failureIdentity: "normalized",
     },
     change: {
       affected: "task-affected-contracts",
@@ -974,14 +1062,12 @@ function normalizeDraft(value: unknown): ImplementPlan {
   if (
     !isRecord(value) ||
     !exactKeys(value, [
-      "schemaVersion",
       "changeId",
       "tasks",
       "outputs",
       "verification",
       "tracking",
     ]) ||
-    value.schemaVersion !== IMPLEMENT_PLAN_SCHEMA_VERSION ||
     typeof value.changeId !== "string" ||
     !CHANGE_NAME.test(value.changeId) ||
     !Array.isArray(value.tasks) ||
@@ -989,8 +1075,26 @@ function normalizeDraft(value: unknown): ImplementPlan {
   ) {
     throw new Error("delivery-plan-invalid");
   }
+  const draftGraph = validateImplementGraphBoundary({
+    changeId: value.changeId,
+    tasks: value.tasks.map((candidate) => {
+      if (!isRecord(candidate)) return candidate;
+      const {
+        affectedVerification: _affectedVerification,
+        repairVerification: _repairVerification,
+        ...boundary
+      } = candidate;
+      return boundary;
+    }),
+    outputs: value.outputs,
+  });
+  if (!draftGraph.ok) {
+    throw new DesignPlanValidationError(
+      `delivery-plan-invalid:${draftGraph.reason}`,
+      [draftGraph.diagnostic],
+    );
+  }
   const plan: ImplementPlan = {
-    schemaVersion: IMPLEMENT_PLAN_SCHEMA_VERSION,
     changeId: value.changeId,
     tasks: value.tasks
       .map(normalizeTask)
@@ -1039,7 +1143,10 @@ function normalizeDraft(value: unknown): ImplementPlan {
   }
   const graphValidation = validateImplementGraphBoundary(graphFromPlan(plan));
   if (!graphValidation.ok) {
-    throw new Error(`delivery-plan-invalid:${graphValidation.reason}`);
+    throw new DesignPlanValidationError(
+      `delivery-plan-invalid:${graphValidation.reason}`,
+      [graphValidation.diagnostic],
+    );
   }
   return plan;
 }
@@ -1062,44 +1169,52 @@ export function compileImplementPlan(
   draft: unknown,
   options: { consumerRoot: string },
 ): CompiledDelivery {
-  const plan = normalizeDraft(draft);
-  const graph = graphFromPlan(plan);
-  const readiness = assessImplementGraphReadiness(options.consumerRoot, graph, {
-    completedTasks: [],
-    blockedTasks: [],
-    appliedPhases: [],
-  });
-  const diagnostics = [
-    ...readiness.closure.diagnostics,
-    ...deliveryVerificationDiagnostics(plan, options.consumerRoot),
-  ];
-  if (diagnostics.length > 0) {
-    throw new Error(
-      `delivery-plan-not-executable:${canonicalJson(diagnostics)}`,
+  try {
+    const plan = normalizeDraft(draft);
+    const graph = graphFromPlan(plan);
+    const readiness = assessImplementGraphReadiness(
+      options.consumerRoot,
+      graph,
+      {
+        completedTasks: [],
+        blockedTasks: [],
+        appliedPhases: [],
+      },
     );
-  }
-  const canonical = canonicalJson(plan);
-  const bytes = new TextEncoder().encode(`${canonical}\n`);
-  const rawSha256 = createHash("sha256").update(bytes).digest("hex");
-  const planHash = hashCanonicalValue(plan);
-  const closure = structuredClone(readiness.closure);
-  return {
-    plan,
-    bytes,
-    rawSha256,
-    planHash,
-    closure,
-    receipt: {
-      plan: {
-        path: IMPLEMENT_PLAN_PATH,
-        schemaVersion: IMPLEMENT_PLAN_SCHEMA_VERSION,
-        rawSha256,
-        canonicalHash: planHash,
+    const diagnostics = [
+      ...readiness.closure.diagnostics,
+      ...deliveryVerificationDiagnostics(plan, options.consumerRoot),
+    ] as DesignPlanDiagnostic[];
+    if (diagnostics.length > 0) {
+      throw new DesignPlanValidationError(
+        `delivery-plan-not-executable:${canonicalJson(diagnostics)}`,
+        diagnostics,
+      );
+    }
+    const canonical = canonicalJson(plan);
+    const bytes = new TextEncoder().encode(`${canonical}\n`);
+    const rawSha256 = createHash("sha256").update(bytes).digest("hex");
+    const planHash = hashCanonicalValue(plan);
+    const closure = structuredClone(readiness.closure);
+    return {
+      plan,
+      bytes,
+      rawSha256,
+      planHash,
+      closure,
+      receipt: {
+        plan: {
+          path: IMPLEMENT_PLAN_PATH,
+          rawSha256,
+          canonicalHash: planHash,
+        },
+        verificationClosure: structuredClone(closure),
       },
-      verificationClosure: structuredClone(closure),
-    },
-    tasksMarkdown: renderTasks(plan),
-  };
+      tasksMarkdown: renderTasks(plan),
+    };
+  } catch (error) {
+    throw asPlanValidationError(error);
+  }
 }
 
 export function parseImplementPlan(bytes: Uint8Array): ImplementPlan {