@abelxiaoxing/cadence 1.2.4 → 1.4.0

package/src/delivery-compiler.ts

@@ -1,4 +1,10 @@
 import { createHash } from "node:crypto";
+import { compareCanonicalStrings } from "./canonical.ts";
+import {
+  assertPlanWithinChangeContract,
+  type ChangeContract,
+  normalizeChangeContract,
+} from "./change-contract.ts";
 import {
   type AgentsImpact,
   type ImplementGraphBoundary,
@@ -17,7 +23,10 @@ import {
   hashCanonicalValue,
   type ImplementGraphReadiness,
 } from "./implement-graph.ts";
-import { validateVerificationAdapterCapability } from "./verification-capability.ts";
+import {
+  bindDraftVerificationInputs,
+  validateVerificationAdapterCapability,
+} from "./verification-capability.ts";
 
 export const IMPLEMENT_PLAN_PATH = "implement-plan.json" as const;
 export const GATE_A_RECEIPT_PATH = "gate-a.yaml" as const;
@@ -117,7 +126,7 @@ export class DesignPlanValidationError extends Error {
         diagnostics
           .map((diagnostic) => structuredClone(diagnostic))
           .sort((left, right) =>
-            canonicalJson(left).localeCompare(canonicalJson(right)),
+            compareCanonicalStrings(canonicalJson(left), canonicalJson(right)),
           )
           .map((diagnostic) => [canonicalJson(diagnostic), diagnostic]),
       ).values(),
@@ -218,7 +227,9 @@ export function assessDeliveryTraceability(input: {
   }
   const verificationIds = input.plan.tasks
     .flatMap((task) => [
-      task.phases.red.verification.id,
+      ...(task.verificationMode && task.verificationMode !== "behavior"
+        ? []
+        : [task.phases.red.verification.id]),
       task.phases.green.verification.id,
       ...(task.phases.refactor ? [task.phases.refactor.verification.id] : []),
     ])
@@ -304,6 +315,7 @@ export interface PlanTracking {
 }
 
 export interface PlanDraft {
+  changeContract?: ChangeContract;
   changeId: string;
   tasks: PlanTaskDraft[];
   outputs: ImplementGraphOutput[];
@@ -371,7 +383,9 @@ function normalizeArtifactBindings(
     paths.add(binding.path);
     return { path: binding.path, rawSha256: binding.rawSha256 };
   });
-  return normalized.sort((left, right) => left.path.localeCompare(right.path));
+  return normalized.sort((left, right) =>
+    compareCanonicalStrings(left.path, right.path),
+  );
 }
 
 function requireReceiptIdentity(
@@ -405,7 +419,41 @@ function normalizeGateProof(value: GateApprovalProof): GateApprovalProof {
   return structuredClone(value);
 }
 
-function parseCanonicalReceipt<T>(bytes: Uint8Array, code: string): T {
+export interface DeliveryReadOptions {
+  /** Only the proof-bound delivery loader may admit historical collection ordering. */
+  allowLegacyOrder?: boolean;
+}
+
+const legacyPlans = new WeakMap<object, string>();
+
+function unorderedIdentity(value: unknown): string {
+  if (Array.isArray(value))
+    return `[${value.map(unorderedIdentity).sort().join(",")}]`;
+  if (isRecord(value))
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => compareCanonicalStrings(a, b))
+      .map(
+        ([key, entry]) => `${JSON.stringify(key)}:${unorderedIdentity(entry)}`,
+      )
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+function sameNormalized(
+  left: unknown,
+  right: unknown,
+  options: DeliveryReadOptions,
+): boolean {
+  return options.allowLegacyOrder
+    ? unorderedIdentity(left) === unorderedIdentity(right)
+    : canonicalJson(left) === canonicalJson(right);
+}
+
+function parseCanonicalReceipt<T>(
+  bytes: Uint8Array,
+  code: string,
+  options: DeliveryReadOptions = {},
+): T {
   const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
   let parsed: unknown;
   try {
@@ -413,7 +461,11 @@ function parseCanonicalReceipt<T>(bytes: Uint8Array, code: string): T {
   } catch {
     throw new Error(code);
   }
-  if (`${canonicalJson(parsed)}\n` !== text) throw new Error(code);
+  if (
+    `${canonicalJson(parsed)}\n` !== text &&
+    (!options.allowLegacyOrder || `${JSON.stringify(parsed)}\n` !== text)
+  )
+    throw new Error(code);
   return parsed as T;
 }
 
@@ -438,10 +490,14 @@ export function compileGateAReceipt(input: {
   };
 }
 
-export function parseGateAReceipt(bytes: Uint8Array): GateAReceipt {
+export function parseGateAReceipt(
+  bytes: Uint8Array,
+  options: DeliveryReadOptions = {},
+): GateAReceipt {
   const receipt = parseCanonicalReceipt<GateAReceipt>(
     bytes,
     "gate-a-receipt-invalid",
+    options,
   );
   if (
     !isRecord(receipt) ||
@@ -455,8 +511,8 @@ export function parseGateAReceipt(bytes: Uint8Array): GateAReceipt {
   const approval = normalizeGateProof(receipt.approval);
   const artifacts = normalizeArtifactBindings(receipt.artifacts);
   if (
-    canonicalJson(approval) !== canonicalJson(receipt.approval) ||
-    canonicalJson(artifacts) !== canonicalJson(receipt.artifacts)
+    !sameNormalized(approval, receipt.approval, options) ||
+    !sameNormalized(artifacts, receipt.artifacts, options)
   ) {
     throw new Error("gate-a-receipt-invalid");
   }
@@ -537,10 +593,14 @@ export function compileReadyReceipt(input: {
   };
 }
 
-export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
+export function parseReadyReceipt(
+  bytes: Uint8Array,
+  options: DeliveryReadOptions = {},
+): ReadyReceipt {
   const receipt = parseCanonicalReceipt<ReadyReceipt>(
     bytes,
     "delivery-receipt-invalid",
+    options,
   );
   if (
     !isRecord(receipt) ||
@@ -592,9 +652,9 @@ export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
   const traceability = normalizeTraceability(receipt.traceability);
   if (
     gateB.contractHash !== receipt.plan.canonicalHash ||
-    canonicalJson(gateB) !== canonicalJson(receipt.approvals.gateB) ||
-    canonicalJson(artifacts) !== canonicalJson(receipt.artifacts) ||
-    canonicalJson(traceability) !== canonicalJson(receipt.traceability)
+    !sameNormalized(gateB, receipt.approvals.gateB, options) ||
+    !sameNormalized(artifacts, receipt.artifacts, options) ||
+    !sameNormalized(traceability, receipt.traceability, options)
   ) {
     throw new Error("delivery-receipt-invalid");
   }
@@ -602,12 +662,14 @@ export function parseReadyReceipt(bytes: Uint8Array): ReadyReceipt {
 }
 
 function sortStrings(values: readonly string[]): string[] {
-  return [...values].sort((left, right) => left.localeCompare(right));
+  return [...values].sort((left, right) =>
+    compareCanonicalStrings(left, right),
+  );
 }
 
 function sortCanonical<T>(values: readonly T[]): T[] {
   return [...values].sort((left, right) =>
-    canonicalJson(left).localeCompare(canonicalJson(right)),
+    compareCanonicalStrings(canonicalJson(left), canonicalJson(right)),
   );
 }
 
@@ -628,7 +690,7 @@ function normalizeVerification(
   return cloned;
 }
 
-function normalizePhase(value: unknown): PlanPhaseDraft {
+function normalizePhase(value: unknown, readOnly = false): PlanPhaseDraft {
   if (
     !isRecord(value) ||
     !exactKeys(value, [
@@ -651,7 +713,7 @@ 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) {
+  if (!readOnly && write.length + deletions.length === 0) {
     throw new Error("delivery-plan-empty-phase-boundary");
   }
   if (write.some((candidate) => deletions.includes(candidate))) {
@@ -724,7 +786,12 @@ function normalizeTask(value: unknown): PlanTaskDraft {
       candidate: unknown,
     ) => {
       try {
-        return normalizePhase(candidate);
+        return normalizePhase(
+          candidate,
+          phase === "red" &&
+            value.verificationMode !== undefined &&
+            value.verificationMode !== "behavior",
+        );
       } catch (error) {
         throw asPlanValidationError(error, {
           ...context,
@@ -758,8 +825,8 @@ function normalizeTask(value: unknown): PlanTaskDraft {
         searchEvidence: sortStrings(cloned.impactClosure.searchEvidence),
         relatedTests: [...cloned.impactClosure.relatedTests].sort(
           (left, right) =>
-            left.path.localeCompare(right.path) ||
-            left.disposition.localeCompare(right.disposition),
+            compareCanonicalStrings(left.path, right.path) ||
+            compareCanonicalStrings(left.disposition, right.disposition),
         ),
         affectedSuite: sortStrings(cloned.impactClosure.affectedSuite),
       },
@@ -936,7 +1003,7 @@ function normalizeAgentsCheckpointOperations(
             : normalizeAgentsManagedBlock(operation.managedBlock),
       };
     })
-    .sort((left, right) => left.target.localeCompare(right.target));
+    .sort((left, right) => compareCanonicalStrings(left.target, right.target));
 }
 
 function normalizeVerificationPlan(value: unknown): PlanVerification {
@@ -1059,6 +1126,7 @@ function normalizeTracking(value: unknown): PlanTracking {
 }
 
 function normalizeDraft(value: unknown): ImplementPlan {
+  value = structuredClone(value);
   if (
     !isRecord(value) ||
     !exactKeys(value, [
@@ -1067,6 +1135,7 @@ function normalizeDraft(value: unknown): ImplementPlan {
       "outputs",
       "verification",
       "tracking",
+      ...(value.changeContract === undefined ? [] : ["changeContract"]),
     ]) ||
     typeof value.changeId !== "string" ||
     !CHANGE_NAME.test(value.changeId) ||
@@ -1075,9 +1144,26 @@ function normalizeDraft(value: unknown): ImplementPlan {
   ) {
     throw new Error("delivery-plan-invalid");
   }
+  const source = value;
+  const taskDrafts = value.tasks.map((task: unknown) => {
+    if (
+      !isRecord(task) ||
+      !["mechanical", "refactor"].includes(String(task.verificationMode))
+    )
+      return task;
+    if (!isRecord(task.phases) || !isRecord(task.phases.green))
+      throw new Error("delivery-plan-invalid-task-phases");
+    if (!source.changeContract)
+      throw new Error("change-contract-verification-mode-required");
+    const green = task.phases.green;
+    return {
+      ...task,
+      phases: { ...task.phases, red: { ...green, write: [], delete: [] } },
+    };
+  });
   const draftGraph = validateImplementGraphBoundary({
     changeId: value.changeId,
-    tasks: value.tasks.map((candidate) => {
+    tasks: taskDrafts.map((candidate) => {
       if (!isRecord(candidate)) return candidate;
       const {
         affectedVerification: _affectedVerification,
@@ -1095,12 +1181,17 @@ function normalizeDraft(value: unknown): ImplementPlan {
     );
   }
   const plan: ImplementPlan = {
+    ...(value.changeContract === undefined
+      ? {}
+      : { changeContract: normalizeChangeContract(value.changeContract) }),
     changeId: value.changeId,
-    tasks: value.tasks
+    tasks: taskDrafts
       .map(normalizeTask)
-      .sort((left, right) => left.taskId.localeCompare(right.taskId)),
+      .sort((left, right) =>
+        compareCanonicalStrings(left.taskId, right.taskId),
+      ),
     outputs: (structuredClone(value.outputs) as ImplementGraphOutput[]).sort(
-      (left, right) => left.id.localeCompare(right.id),
+      (left, right) => compareCanonicalStrings(left.id, right.id),
     ),
     verification: normalizeVerificationPlan(value.verification),
     tracking: normalizeTracking(value.tracking),
@@ -1141,6 +1232,11 @@ function normalizeDraft(value: unknown): ImplementPlan {
   ) {
     throw new Error("delivery-agents-checkpoint-mismatch");
   }
+  if (plan.changeContract)
+    assertPlanWithinChangeContract(plan.changeContract, plan.tasks, [
+      plan.verification.change.fullSuite,
+      plan.verification.change.postApply,
+    ]);
   const graphValidation = validateImplementGraphBoundary(graphFromPlan(plan));
   if (!graphValidation.ok) {
     throw new DesignPlanValidationError(
@@ -1158,7 +1254,12 @@ function renderTasks(plan: ImplementPlan): string {
     lines.push(
       `  - Depends on: ${task.dependsOn.length > 0 ? task.dependsOn.join(", ") : "[]"}`,
     );
-    lines.push(`  - Red verification: ${task.phases.red.verification.id}`);
+    if (!task.verificationMode || task.verificationMode === "behavior")
+      lines.push(`  - Red verification: ${task.phases.red.verification.id}`);
+    else
+      lines.push(
+        `  - Evidence mode: ${task.verificationMode}; baseline and postconditions required`,
+      );
     lines.push(`  - Green verification: ${task.phases.green.verification.id}`);
   }
   lines.push("");
@@ -1167,10 +1268,16 @@ function renderTasks(plan: ImplementPlan): string {
 
 export function compileImplementPlan(
   draft: unknown,
-  options: { consumerRoot: string },
+  options: { consumerRoot: string; bindExecutionInputs?: boolean },
 ): CompiledDelivery {
   try {
-    const plan = normalizeDraft(draft);
+    if (options.bindExecutionInputs)
+      draft = bindDraftVerificationInputs(options.consumerRoot, draft);
+    const normalized = normalizeDraft(draft);
+    const plan =
+      isRecord(draft) && legacyPlans.get(draft) === JSON.stringify(draft)
+        ? (draft as unknown as ImplementPlan)
+        : normalized;
     const graph = graphFromPlan(plan);
     const readiness = assessImplementGraphReadiness(
       options.consumerRoot,
@@ -1217,7 +1324,10 @@ export function compileImplementPlan(
   }
 }
 
-export function parseImplementPlan(bytes: Uint8Array): ImplementPlan {
+export function parseImplementPlan(
+  bytes: Uint8Array,
+  options: DeliveryReadOptions = {},
+): ImplementPlan {
   const text = new TextDecoder().decode(bytes);
   let parsed: unknown;
   try {
@@ -1226,8 +1336,15 @@ export function parseImplementPlan(bytes: Uint8Array): ImplementPlan {
     throw new Error("delivery-plan-json-invalid");
   }
   const normalized = normalizeDraft(parsed);
-  if (`${canonicalJson(normalized)}\n` !== text) {
+  if (`${canonicalJson(normalized)}\n` === text) return normalized;
+  if (
+    !options.allowLegacyOrder ||
+    `${canonicalJson(parsed)}\n` !== text ||
+    !sameNormalized(normalized, parsed, options)
+  ) {
     throw new Error("delivery-plan-not-canonical");
   }
-  return normalized;
+  // Keep proof-bound historical bytes unchanged; a mutation invalidates this association.
+  legacyPlans.set(parsed as object, JSON.stringify(parsed));
+  return parsed as ImplementPlan;
 }

package/src/design-control.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import {
   lstatSync,
@@ -8,6 +9,10 @@ import {
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
+import {
+  type ChangeContract,
+  normalizeChangeContract,
+} from "./change-contract.ts";
 import { isValidRelativePath } from "./contracts.ts";
 import {
   assessDeliveryTraceability,
@@ -27,6 +32,8 @@ import {
   DesignJournal,
   type DesignStatusProjection,
 } from "./design-journal.ts";
+import { OpenSpecCliError, type OpenSpecDiagnostic } from "./openspec-cli.ts";
+import { canonicalJson } from "./run-state.ts";
 import { RunStore } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
 import type { ResolvedStateRoot } from "./state-root.ts";
@@ -38,6 +45,20 @@ const MAX_DESIGN_FILE_BYTES = 16 * 1024 * 1024;
 const MAX_DESIGN_REQUIREMENT_BYTES = 64 * 1024;
 const MAX_DESIGN_CONTRACT_BYTES = 256 * 1024;
 
+function validGateContract(value: unknown): boolean {
+  if (typeof value === "string")
+    return (
+      value.trim().length > 0 &&
+      Buffer.byteLength(value, "utf8") <= MAX_DESIGN_CONTRACT_BYTES
+    );
+  try {
+    normalizeChangeContract(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export interface DesignOpenSpecInspection {
   change: string;
   schema: string;
@@ -81,7 +102,7 @@ export type DesignControlRequest =
       runId: string;
       operationId: string;
       gate: "gate-a";
-      contract: string;
+      contract: string | ChangeContract;
     }
   | {
       operation: "approve-gate";
@@ -131,11 +152,17 @@ export interface DesignControllerOptions {
 export class DesignFinalizationError extends Error {
   readonly diagnostics: readonly string[];
 
-  constructor(diagnostics: readonly string[]) {
+  readonly openSpecDiagnostic?: Readonly<OpenSpecDiagnostic>;
+
+  constructor(
+    diagnostics: readonly string[],
+    openSpecDiagnostic?: Readonly<OpenSpecDiagnostic>,
+  ) {
     const normalized = [...new Set(diagnostics)].sort();
     super("design-finalization-invalid");
     this.name = "DesignFinalizationError";
     this.diagnostics = Object.freeze(normalized);
+    this.openSpecDiagnostic = openSpecDiagnostic;
   }
 }
 
@@ -268,9 +295,7 @@ export function validateDesignControlRequest(
         "gate",
         "contract",
       ]) &&
-      typeof value.contract === "string" &&
-      value.contract.trim().length > 0 &&
-      Buffer.byteLength(value.contract, "utf8") <= MAX_DESIGN_CONTRACT_BYTES
+      validGateContract(value.contract)
       ? { ok: true, value: structuredClone(value) as DesignControlRequest }
       : { ok: false, code: "invalid-design-control-request" };
   }
@@ -452,6 +477,7 @@ export class DesignController {
   readonly #runs: RunStore;
   readonly #inspectOpenSpec: DesignControllerOptions["inspectOpenSpec"];
   #closed = false;
+  readonly #authority = new AsyncLocalStorage<() => void>();
 
   private constructor(options: DesignControllerOptions) {
     this.consumerRoot = path.resolve(options.consumerRoot);
@@ -478,7 +504,22 @@ export class DesignController {
     return new DesignController(options);
   }
 
+  executeWithAuthority(
+    value: unknown,
+    assertAuthority: () => void,
+  ): Promise<Record<string, unknown>> {
+    return this.#authority.run(assertAuthority, () => this.execute(value));
+  }
+
+  #assertFinalizationLease(
+    lease: Parameters<DesignJournal["assertFinalizationLease"]>[0],
+  ): void {
+    this.#authority.getStore()?.();
+    this.#journal.assertFinalizationLease(lease);
+  }
+
   #assertOpen(): void {
+    this.#authority.getStore()?.();
     if (this.#closed) throw new Error("design-controller-closed");
   }
 
@@ -624,6 +665,7 @@ export class DesignController {
       throw error;
     }
     if (run.state === "created") {
+      this.#journal.inheritFinalizedAuthority(run.runId);
       this.#runs.transition({
         runId: run.runId,
         to: "paused",
@@ -824,7 +866,21 @@ export class DesignController {
         { code: "design-plan-draft-invalid", field: "plan-draft.json" },
       ]);
     }
+    if (status.changeContract) {
+      if (!draft || typeof draft !== "object" || Array.isArray(draft))
+        throw new Error("change-contract-invalid");
+      const record = draft as Record<string, unknown>;
+      if (
+        record.changeContract !== undefined &&
+        canonicalJson(normalizeChangeContract(record.changeContract)) !==
+          canonicalJson(status.changeContract)
+      )
+        throw new Error("change-contract-mismatch");
+      record.changeContract = status.changeContract;
+    } else if (draft && typeof draft === "object" && "changeContract" in draft)
+      throw new Error("change-contract-gate-a-required");
     const compiled = compileImplementPlan(draft, {
+      bindExecutionInputs: true,
       consumerRoot: this.consumerRoot,
     });
     if (compiled.plan.changeId !== status.change) {
@@ -875,9 +931,15 @@ export class DesignController {
       if (!change) throw new Error("design-change-required");
       const readyPath = safeRelative(change, "ready.yaml");
       const gateAPath = safeRelative(change, "gate-a.yaml");
-      removeSafeFile(this.consumerRoot, readyPath);
-      removeSafeFile(this.consumerRoot, gateAPath);
-      this.#journal.assertFinalizationLease(lease);
+      const unchanged =
+        status.gates.gateB.current &&
+        status.plan?.rawSha256 === compiled.rawSha256 &&
+        status.plan.canonicalHash === compiled.planHash;
+      if (!unchanged) {
+        removeSafeFile(this.consumerRoot, readyPath);
+        removeSafeFile(this.consumerRoot, gateAPath);
+      }
+      this.#assertFinalizationLease(lease);
       atomicWrite(
         this.consumerRoot,
         safeRelative(change, "implement-plan.json"),
@@ -890,6 +952,7 @@ export class DesignController {
         rawSha256: compiled.rawSha256,
         canonicalHash: compiled.planHash,
         lease,
+        certify: true,
       });
     } finally {
       this.#journal.releaseFinalizationLease(lease);
@@ -934,9 +997,12 @@ export class DesignController {
       removeSafeFile(this.consumerRoot, readyPath);
       const diagnostics = new Set<string>();
       let inspection: DesignOpenSpecInspection | undefined;
+      let openSpecDiagnostic: Readonly<OpenSpecDiagnostic> | undefined;
       try {
         inspection = await this.#inspectOpenSpec(this.consumerRoot, change);
-      } catch {
+      } catch (error) {
+        if (error instanceof OpenSpecCliError)
+          openSpecDiagnostic = error.diagnostic;
         diagnostics.add("design-openspec-unavailable");
       }
       if (inspection) {
@@ -960,7 +1026,9 @@ export class DesignController {
       }
       let compiled: ReturnType<typeof compileImplementPlan> | undefined;
       try {
-        const plan = parseImplementPlan(installedPlanBytes);
+        const plan = parseImplementPlan(installedPlanBytes, {
+          allowLegacyOrder: true,
+        });
         compiled = compileImplementPlan(plan, {
           consumerRoot: this.consumerRoot,
         });
@@ -1004,7 +1072,7 @@ export class DesignController {
       let traceability:
         | ReturnType<typeof assessDeliveryTraceability>
         | undefined;
-      if (compiled) {
+      if (compiled && inspection) {
         const tasks = artifactBytes.get("tasks.md");
         const specs = [...artifactBytes]
           .filter(
@@ -1035,7 +1103,7 @@ export class DesignController {
         !traceability?.ok ||
         diagnostics.size > 0
       ) {
-        throw new DesignFinalizationError([...diagnostics]);
+        throw new DesignFinalizationError([...diagnostics], openSpecDiagnostic);
       }
       const gateAReceipt = compileGateAReceipt({
         change,
@@ -1057,14 +1125,14 @@ export class DesignController {
         traceability: traceability.value,
       });
       readyHash = readyReceipt.rawSha256;
-      this.#journal.assertFinalizationLease(lease);
+      this.#assertFinalizationLease(lease);
       atomicWrite(this.consumerRoot, gateAPath, gateAReceipt.bytes);
       atomicWrite(this.consumerRoot, readyPath, readyReceipt.bytes);
       readyInstalled = true;
       const installedGateA = readSafeFile(this.consumerRoot, gateAPath);
       const installedReady = readSafeFile(this.consumerRoot, readyPath);
-      parseGateAReceipt(installedGateA);
-      parseReadyReceipt(installedReady);
+      parseGateAReceipt(installedGateA, { allowLegacyOrder: true });
+      parseReadyReceipt(installedReady, { allowLegacyOrder: true });
       if (
         !Buffer.from(installedGateA).equals(Buffer.from(gateAReceipt.bytes)) ||
         !Buffer.from(installedReady).equals(Buffer.from(readyReceipt.bytes))