@abelxiaoxing/cadence 1.2.2 → 1.2.3

package/src/design-control.ts

@@ -15,6 +15,7 @@ import {
   compileImplementPlan,
   compileReadyReceipt,
   type DeliveryArtifactBinding,
+  DesignPlanValidationError,
   type GateApprovalProof,
   parseGateAReceipt,
   parseImplementPlan,
@@ -88,6 +89,10 @@ export type DesignControlRequest =
       operationId: string;
       gate: "gate-b";
     }
+  | {
+      operation: "validate-plan-draft";
+      runId: string;
+    }
   | {
       operation: "compile-plan";
       runId: string;
@@ -198,7 +203,10 @@ export function validateDesignControlRequest(
       ? { ok: true, value: structuredClone(value) as DesignControlRequest }
       : { ok: false, code: "invalid-design-control-request" };
   }
-  if (value.operation === "status") {
+  if (
+    value.operation === "status" ||
+    value.operation === "validate-plan-draft"
+  ) {
     return exactKeys(value, ["operation", "runId"]) &&
       typeof value.runId === "string" &&
       IDENTIFIER.test(value.runId)
@@ -508,6 +516,8 @@ export class DesignController {
         return this.#journal.recordDecision(request);
       case "approve-gate":
         return this.#journal.approveGate(request);
+      case "validate-plan-draft":
+        return this.#validatePlanDraft(request);
       case "compile-plan":
         return this.#compilePlan(request);
       case "finalize-delivery":
@@ -539,7 +549,7 @@ export class DesignController {
     const canApproveGate =
       !design.gates.gateA.current ||
       (planReadyForGateB && !design.gates.gateB.current);
-    const legalActions = terminal
+    const legalOperations = terminal
       ? ["status"]
       : [
           "status",
@@ -549,7 +559,12 @@ export class DesignController {
             ? ["bind-change"]
             : []),
           ...(design.gates.gateA.current && design.change
-            ? ["write-artifact", "delete-artifact", "compile-plan"]
+            ? [
+                "write-artifact",
+                "delete-artifact",
+                "validate-plan-draft",
+                "compile-plan",
+              ]
             : []),
           ...(design.change &&
           design.plan &&
@@ -557,7 +572,6 @@ export class DesignController {
           design.gates.gateB.current
             ? ["finalize-delivery"]
             : []),
-          "finish",
         ];
     return {
       runId: run.runId,
@@ -566,7 +580,8 @@ export class DesignController {
       state: run.state,
       completed: run.state === "completed",
       ...(run.pauseCode ? { pause: { code: run.pauseCode } } : {}),
-      legalActions,
+      legalOperations,
+      packetActions: terminal ? [] : ["finish"],
       design,
     };
   }
@@ -578,7 +593,7 @@ export class DesignController {
       ...(fromRequirement
         ? {
             provisionalKey: transientHash(
-              "abel-design-requirement-v1",
+              "abel-design-requirement",
               request.requirement,
             ),
           }
@@ -772,6 +787,51 @@ export class DesignController {
     }
   }
 
+  #readCompiledDraft(runId: string) {
+    const status = this.#journal.status(runId);
+    if (!status.change) throw new Error("design-change-required");
+    if (!status.gates.gateA.current) throw new Error("design-gate-a-required");
+    const draftPath = safeRelative(status.change, "plan-draft.json");
+    const draftBytes = readSafeFile(this.consumerRoot, draftPath);
+    let draft: unknown;
+    try {
+      draft = JSON.parse(draftBytes.toString("utf8"));
+    } catch {
+      throw new DesignPlanValidationError("design-plan-draft-invalid", [
+        { code: "design-plan-draft-invalid", field: "plan-draft.json" },
+      ]);
+    }
+    const compiled = compileImplementPlan(draft, {
+      consumerRoot: this.consumerRoot,
+    });
+    if (compiled.plan.changeId !== status.change) {
+      throw new DesignPlanValidationError("design-plan-change-mismatch", [
+        { code: "design-plan-change-mismatch", field: "changeId" },
+      ]);
+    }
+    return { status, compiled };
+  }
+
+  #validatePlanDraft(
+    request: Extract<
+      DesignControlRequest,
+      { operation: "validate-plan-draft" }
+    >,
+  ) {
+    const { compiled } = this.#readCompiledDraft(request.runId);
+    return {
+      operation: request.operation,
+      runId: request.runId,
+      valid: true,
+      plan: {
+        taskCount: compiled.plan.tasks.length,
+        outputCount: compiled.plan.outputs.length,
+        rawSha256: compiled.rawSha256,
+        canonicalHash: compiled.planHash,
+      },
+    };
+  }
+
   #compilePlan(
     request: Extract<DesignControlRequest, { operation: "compile-plan" }>,
   ) {
@@ -787,32 +847,17 @@ export class DesignController {
     });
     try {
       this.#journal.assertNoPendingArtifactOperations(request.runId);
-      const status = this.#journal.status(request.runId);
-      if (!status.change) throw new Error("design-change-required");
-      if (!status.gates.gateA.current)
-        throw new Error("design-gate-a-required");
-      const readyPath = safeRelative(status.change, "ready.yaml");
-      const gateAPath = safeRelative(status.change, "gate-a.yaml");
+      const { status, compiled } = this.#readCompiledDraft(request.runId);
+      const change = status.change;
+      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);
-      const draftPath = safeRelative(status.change, "plan-draft.json");
-      const draftBytes = readSafeFile(this.consumerRoot, draftPath);
-      let draft: unknown;
-      try {
-        draft = JSON.parse(draftBytes.toString("utf8"));
-      } catch {
-        throw new Error("design-plan-draft-invalid");
-      }
-      const compiled = compileImplementPlan(draft as never, {
-        consumerRoot: this.consumerRoot,
-      });
-      if (compiled.plan.changeId !== status.change) {
-        throw new Error("design-plan-change-mismatch");
-      }
       this.#journal.assertFinalizationLease(lease);
       atomicWrite(
         this.consumerRoot,
-        safeRelative(status.change, "implement-plan.json"),
+        safeRelative(change, "implement-plan.json"),
         compiled.bytes,
       );
       return this.#journal.recordCompiledPlan({

package/src/design-journal.ts

@@ -899,7 +899,7 @@ export class DesignJournal {
   }): Record<string, unknown> {
     requireIdentifier(input.decisionId, "design-decision-id");
     const decisionContractHash = contractHash(
-      "abel-design-decision-v1",
+      "abel-design-decision",
       input.contract,
     );
     if (input.category !== "behavior" && input.category !== "technical") {
@@ -1024,7 +1024,7 @@ export class DesignJournal {
     }
     const gateAContractHash =
       input.gate === "gate-a"
-        ? contractHash("abel-design-gate-a-v1", input.contract)
+        ? contractHash("abel-design-gate-a", input.contract)
         : undefined;
     return this.#transaction(() => {
       this.#run(input.runId, true);

package/src/file-snapshot.ts

@@ -56,7 +56,7 @@ function updateManifest(
 
 function recursiveDirectoryManifest(abs: string): string {
   const hash = createHash("sha256");
-  updateManifest(hash, "cadence-directory-manifest-v2");
+  updateManifest(hash, "cadence-directory-manifest");
   const visit = (directory: string, prefix: string): void => {
     const names = readdirSync(directory).sort();
     for (const name of names) {

package/src/index.ts

@@ -38,6 +38,7 @@ import {
   verificationSteps,
 } from "./contracts.ts";
 import {
+  CONTROL_COMMAND_PARAMETERS,
   canonicalizeControlCommandToolInput,
   validateControlCommand,
 } from "./control-contracts.ts";
@@ -45,14 +46,15 @@ import {
   assessDeliveryTraceability,
   compileImplementPlan,
   DeliveryValidationError,
+  DesignPlanValidationError,
   type GateApprovalProof,
-  IMPLEMENT_PLAN_SCHEMA_VERSION,
   parseGateAReceipt,
   parseImplementPlan,
   parseReadyReceipt,
 } from "./delivery-compiler.ts";
 import {
   DesignController,
+  DesignFinalizationError,
   validateDesignControlRequest,
 } from "./design-control.ts";
 import { canonicalJson, hashCanonicalValue } from "./implement-graph.ts";
@@ -67,6 +69,7 @@ import {
   unavailableRoutePolicy,
   type WorkerRoutePolicy,
 } from "./route-policy.ts";
+import { RunStoreFormatError } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
 import { resolveStateRoot } from "./state-root.ts";
 import {
@@ -229,15 +232,15 @@ const DESIGN_CONTROL_REQUEST_SCHEMA = {
       required: ["operation", "operationId", field],
       additionalProperties: false,
     })),
-    {
-      type: "object",
+    ...(["status", "validate-plan-draft"] as const).map((operation) => ({
+      type: "object" as const,
       properties: {
-        operation: { type: "string", enum: ["status"] },
-        runId: { type: "string" },
+        operation: { type: "string" as const, enum: [operation] },
+        runId: { type: "string" as const },
       },
       required: ["operation", "runId"],
       additionalProperties: false,
-    },
+    })),
     {
       type: "object",
       properties: {
@@ -421,6 +424,89 @@ function splitUsage(result: unknown): { payload: unknown; usage?: unknown } {
   return { payload, usage };
 }
 
+const SAFE_DESIGN_ERROR_CODE = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
+const MAX_DESIGN_ERROR_DIAGNOSTICS = 64;
+
+type SafeDesignFailure = {
+  kind: "design-control-failure";
+  operation: string;
+  code: string;
+  diagnostics: ReadonlyArray<Record<string, string>>;
+};
+
+function safeDesignFailure(
+  error: unknown,
+  operation: string,
+): SafeDesignFailure {
+  const message = error instanceof Error ? error.message : "";
+  const code =
+    error instanceof DesignPlanValidationError
+      ? "design-plan-validation-invalid"
+      : SAFE_DESIGN_ERROR_CODE.test(message)
+        ? message
+        : "design-control-failed";
+  const rawDiagnostics: readonly unknown[] =
+    error instanceof DesignFinalizationError ||
+    error instanceof DesignPlanValidationError ||
+    error instanceof DeliveryValidationError
+      ? error.diagnostics
+      : [];
+  const diagnostics = rawDiagnostics
+    .flatMap((candidate) => {
+      if (typeof candidate === "string") {
+        const diagnosticCode = candidate.split(":", 1)[0] ?? "";
+        return SAFE_DESIGN_ERROR_CODE.test(diagnosticCode)
+          ? [{ code: diagnosticCode }]
+          : [];
+      }
+      if (
+        candidate === null ||
+        typeof candidate !== "object" ||
+        Array.isArray(candidate)
+      ) {
+        return [];
+      }
+      const admitted = Object.fromEntries(
+        Object.entries(candidate as Record<string, unknown>)
+          .filter(
+            (entry): entry is [string, string] =>
+              [
+                "code",
+                "taskId",
+                "phase",
+                "field",
+                "category",
+                "owner",
+                "verificationId",
+                "outputId",
+                "dependencyTaskId",
+                "producerTaskId",
+                "producerPhase",
+              ].includes(entry[0]) &&
+              typeof entry[1] === "string" &&
+              SAFE_DESIGN_ERROR_CODE.test(entry[1]),
+          )
+          .sort(([left], [right]) => left.localeCompare(right)),
+      );
+      return typeof admitted.code === "string" ? [admitted] : [];
+    })
+    .sort((left, right) =>
+      canonicalJson(left).localeCompare(canonicalJson(right)),
+    )
+    .filter(
+      (candidate, index, values) =>
+        index === 0 ||
+        canonicalJson(candidate) !== canonicalJson(values[index - 1]),
+    )
+    .slice(0, MAX_DESIGN_ERROR_DIAGNOSTICS);
+  return {
+    kind: "design-control-failure",
+    operation: SAFE_DESIGN_ERROR_CODE.test(operation) ? operation : "unknown",
+    code,
+    diagnostics,
+  };
+}
+
 export interface WorkflowControlEngine {
   execute(
     command: unknown,
@@ -733,7 +819,10 @@ export function packageDeliverySource(
       try {
         receipt = parseReadyReceipt(receiptBytes);
       } catch {
-        throw new DeliveryValidationError(["delivery-receipt-invalid"]);
+        throw new DeliveryValidationError([
+          "delivery-receipt-invalid",
+          "delivery-recompile-required",
+        ]);
       }
       const diagnostics = new Set<string>();
       if (receipt.change !== input.change) {
@@ -899,7 +988,6 @@ export function packageDeliverySource(
         }
         if (
           receipt.plan.path !== "implement-plan.json" ||
-          receipt.plan.schemaVersion !== IMPLEMENT_PLAN_SCHEMA_VERSION ||
           receipt.plan.rawSha256 !== sha256(planBytes) ||
           receipt.plan.canonicalHash !== hashCanonicalValue(plan)
         ) {
@@ -982,7 +1070,6 @@ export function packageDeliverySource(
         throw new DeliveryValidationError([...diagnostics]);
       }
       return {
-        version: 2,
         gate: "gate-b",
         revision: receipt.deliveryRevision,
         receiptHash,
@@ -1251,7 +1338,7 @@ function normalizedFailureIdentities(input: {
   if (vitestFailures.length > 0) {
     return [...new Set(vitestFailures)]
       .sort()
-      .map((failure) => sha256(`vitest-failure-v1\0${failure}`));
+      .map((failure) => sha256(`vitest-failure\0${failure}`));
   }
   const normalizedOutput = input.output
     .replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "gu"), "")
@@ -1261,7 +1348,6 @@ function normalizedFailureIdentities(input: {
   return [
     sha256(
       canonicalJson({
-        version: 1,
         verificationId: input.step.id,
         exitCode: input.exitCode,
         output: normalizedOutput,
@@ -1514,6 +1600,8 @@ export function openPackageWorkflowControlEngine(
         context,
         parentPayloadBridge,
         input.signal,
+        process.env,
+        { onResponse: input.onHeaders },
       );
       if (!phaseRuntime.ok) {
         if (phaseRuntime.failure.kind === "cancelled") {
@@ -1565,6 +1653,9 @@ export function openPackageWorkflowControlEngine(
         ...(input.artifactCorrection
           ? { artifactCorrection: structuredClone(input.artifactCorrection) }
           : {}),
+        ...(input.contextRequest
+          ? { requestedContext: structuredClone(input.contextRequest) }
+          : {}),
         ...(input.repair
           ? {
               repair: {
@@ -1608,7 +1699,6 @@ export function openPackageWorkflowControlEngine(
         failureOverride: phaseRuntime.failureOverride,
         ledgerProjection: input.ledgerProjection,
         candidateArtifact: input.candidateArtifact,
-        onStreamStart: input.onHeaders,
         onStreamProgress: input.onProgress,
       });
       if (!child.ok) {
@@ -1624,10 +1714,18 @@ export function openPackageWorkflowControlEngine(
         if (child.failure.kind === "result-limit") {
           return { kind: "paused", code: "needs-task-split" };
         }
+        const attemptDiagnostic = {
+          finalCategory: child.classification.finalCategory,
+          submitAttempts: child.classification.attempts,
+          schema: child.classification.schema,
+          identityMismatch: Object.entries(child.classification.identity)
+            .filter(([, matches]) => !matches)
+            .map(([dimension]) => dimension),
+        };
         return child.failure.kind === "environment" ||
           child.failure.kind === "verification-adapter"
-          ? { kind: "paused", code: child.failure.code }
-          : { kind: "retryable", code: child.failure.code };
+          ? { kind: "paused", code: child.failure.code, attemptDiagnostic }
+          : { kind: "retryable", code: child.failure.code, attemptDiagnostic };
       }
       const result = child.result;
       if (result.kind === "context-request") {
@@ -1764,6 +1862,39 @@ export function openPackageWorkflowControlEngine(
   };
 }
 
+function runStoreUnavailableStatus(
+  error: RunStoreFormatError,
+  command: {
+    stage: "abel-implement";
+    change: string;
+  },
+): Record<string, unknown> {
+  return {
+    stage: command.stage,
+    change: command.change,
+    state: "paused",
+    durable: false,
+    completed: false,
+    pause: { code: error.code },
+    legalCommands: ["status", "start"],
+    tasks: [],
+    queue: [],
+    controlStore: {
+      code: error.code,
+      databasePath: error.databasePath,
+      recovery: structuredClone(error.recovery),
+    },
+  };
+}
+
+function runStoreResetError(error: RunStoreFormatError): Error {
+  const reset = new Error(
+    `${error.code}: back up and remove the private run store at ${error.databasePath}, then retry the operation`,
+  );
+  reset.name = "RunStoreResetError";
+  return reset;
+}
+
 function visibleRoutePolicyStatus(
   resolution: RoutePolicyResolution,
   brokerStatus: Record<string, unknown> | undefined,
@@ -1783,6 +1914,7 @@ export function registerWorkflowControl(
   const parentPayloadBridge = new ParentPayloadBridge();
   const activity = new ActivityController();
   const engines = new Map<string, Promise<WorkflowControlEngine>>();
+  const designFailures = new Map<string, SafeDesignFailure>();
   let pendingPrompt: EligiblePrompt | undefined;
   let activePrompt: EligiblePrompt | undefined;
   let designToolSnapshot: string[] | undefined;
@@ -1875,30 +2007,15 @@ export function registerWorkflowControl(
 
   // Pi validates tool arguments before execute(), so expose only the schema
   // legal for the active stage instead of one ambiguous command/packet union.
-  const CONTROL_COMMAND_PARAMETERS = {
+  const PACKET_PARAMETERS = {
     type: "object",
     properties: {
-      command: {
-        type: "string",
-        enum: ["start", "status", "resume", "rebind", "cancel", "discard"],
-      },
-      stage: {
+      action: {
         type: "string",
-        enum: ["abel-implement"],
+        enum: [...PACKET_ACTIONS, "design"],
+        description:
+          "Top-level dispatch action. design and run require request; finish is explicit stage exit and MUST omit request.",
       },
-      change: { type: "string" },
-      operationId: { type: "string" },
-      deliveryRevision: { type: "integer", minimum: 1 },
-      receiptHash: { type: "string" },
-      routeId: { type: "string" },
-    },
-    required: ["command", "stage", "change"],
-    additionalProperties: false,
-  } as const;
-  const PACKET_PARAMETERS = {
-    type: "object",
-    properties: {
-      action: { type: "string", enum: [...PACKET_ACTIONS, "design"] },
       request: {
         anyOf: [
           DESIGN_REQUEST_SCHEMA,
@@ -1950,6 +2067,9 @@ export function registerWorkflowControl(
           ) {
             throw new Error("control-envelope-ambiguous");
           }
+          if (record.action === "finish" && Object.hasOwn(record, "request")) {
+            throw new Error("control-envelope-ambiguous");
+          }
           if (
             activePrompt !== "abel-design" &&
             activePrompt !== "abel-diagnose"
@@ -1962,22 +2082,40 @@ export function registerWorkflowControl(
             }
             const designRequest = validateDesignControlRequest(record.request);
             if (!designRequest.ok) throw new Error(designRequest.code);
-            const engine = await engineFor(ctx);
+            let engine: WorkflowControlEngine;
+            try {
+              engine = await engineFor(ctx);
+            } catch (error) {
+              if (error instanceof RunStoreFormatError)
+                throw runStoreResetError(error);
+              throw error;
+            }
             if (!engine.executeDesign)
               throw new Error("design-control-unavailable");
-            const payload = await engine.executeDesign(designRequest.value);
-            if (
-              designRequest.value.operation === "finalize-delivery" &&
-              payload.state === "completed"
-            ) {
-              await deactivateStage();
+            try {
+              const payload = await engine.executeDesign(designRequest.value);
+              if (
+                designRequest.value.operation === "finalize-delivery" &&
+                payload.state === "completed"
+              ) {
+                await deactivateStage();
+              }
+              return {
+                content: [
+                  { type: "text" as const, text: JSON.stringify(payload) },
+                ],
+                details: payload,
+              };
+            } catch (error) {
+              const failure = safeDesignFailure(
+                error,
+                designRequest.value.operation,
+              );
+              designFailures.set(toolCallId, failure);
+              const sanitized = new Error(failure.code);
+              sanitized.name = "DesignControlError";
+              throw sanitized;
             }
-            return {
-              content: [
-                { type: "text" as const, text: JSON.stringify(payload) },
-              ],
-              details: payload,
-            };
           }
           let designEngine: WorkflowControlEngine | undefined;
           if (record.action === "run") {
@@ -1988,7 +2126,13 @@ export function registerWorkflowControl(
               );
             }
             if (packet.value.stage === "abel-design") {
-              designEngine = await engineFor(ctx);
+              try {
+                designEngine = await engineFor(ctx);
+              } catch (error) {
+                if (error instanceof RunStoreFormatError)
+                  throw runStoreResetError(error);
+                throw error;
+              }
               if (!designEngine.assertDesignRun || !packet.value.runId) {
                 throw new Error("design-control-unavailable");
               }
@@ -2076,7 +2220,17 @@ export function registerWorkflowControl(
         ) {
           throw new Error("stage-control-mismatch");
         }
-        const engine = await engineFor(ctx);
+        let engine: WorkflowControlEngine;
+        try {
+          engine = await engineFor(ctx);
+        } catch (error) {
+          if (!(error instanceof RunStoreFormatError)) throw error;
+          const payload = runStoreUnavailableStatus(error, validation.value);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(payload) }],
+            details: payload,
+          };
+        }
         const tuiControl = ctx.mode === "tui";
         if (tuiControl) {
           try {
@@ -2161,6 +2315,39 @@ export function registerWorkflowControl(
   };
   registerDispatchTool("packet");
 
+  pi.on("tool_result", (event) => {
+    if (
+      event.toolName !== DISPATCH_TOOL ||
+      !event.isError ||
+      event.input.action !== "design"
+    ) {
+      return;
+    }
+    const errorText = event.content
+      .flatMap((item) =>
+        item.type === "text" && typeof item.text === "string"
+          ? [item.text]
+          : [],
+      )
+      .join("\n");
+    const failure = safeDesignFailure(
+      new Error(errorText.trim()),
+      typeof (event.input.request as Record<string, unknown> | undefined)
+        ?.operation === "string"
+        ? String((event.input.request as Record<string, unknown>).operation)
+        : "unknown",
+    );
+    const details =
+      event.details && typeof event.details === "object"
+        ? (event.details as Record<string, unknown>)
+        : {};
+    const visible = designFailures.get(event.toolCallId) ?? failure;
+    designFailures.delete(event.toolCallId);
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(visible) }],
+      details: { ...details, designFailure: visible },
+    };
+  });
   pi.on("input", (event) => {
     pendingPrompt = invokedPrompt(event.text);
     return { action: "continue" };
@@ -2214,6 +2401,7 @@ export function registerWorkflowControl(
   pi.on("session_start", async (_event, ctx) => {
     pendingPrompt = undefined;
     activePrompt = undefined;
+    designFailures.clear();
     activity.detach();
     await packetRuntime.drain();
     await closeEngines();
@@ -2229,6 +2417,7 @@ export function registerWorkflowControl(
   });
   pi.on("session_shutdown", async () => {
     activePrompt = undefined;
+    designFailures.clear();
     activity.detach();
     await packetRuntime.drain();
     await closeEngines();