@abelxiaoxing/cadence 1.2.1 → 1.2.3

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") {
@@ -1525,19 +1613,49 @@ export function openPackageWorkflowControlEngine(
       if (!phase) {
         return { kind: "paused", code: "task-phase-unavailable" };
       }
+      const taskPhases = Object.values(input.task.phases);
+      const executionBoundary = input.artifactCorrection
+        ? {
+            read: [
+              ...new Set(
+                taskPhases.flatMap((boundary) => [
+                  ...boundary.read,
+                  ...boundary.write,
+                  ...boundary.delete,
+                ]),
+              ),
+            ].sort(),
+            write: [
+              ...new Set(taskPhases.flatMap((boundary) => boundary.write)),
+            ].sort(),
+            delete: [
+              ...new Set(taskPhases.flatMap((boundary) => boundary.delete)),
+            ].sort(),
+          }
+        : {
+            read: [...phase.read],
+            write: [...phase.write],
+            delete: [...phase.delete],
+          };
       const phaseContract = {
         candidateId: input.candidateArtifact.identity.candidateId,
         taskId: input.taskId,
         phase: input.phase,
-        readSet: [...phase.read],
-        writeSet: [...phase.write],
-        deleteSet: [...phase.delete],
+        readSet: executionBoundary.read,
+        writeSet: executionBoundary.write,
+        deleteSet: executionBoundary.delete,
         verification: structuredClone(phase.verification),
         agentsImpact: input.task.agents.impact,
         agentsTarget: input.task.agents.target ?? null,
         agentsManagedOnly: true,
         agentsWriteAllowed: false,
         impactClosure: structuredClone(input.task.impactClosure),
+        ...(input.artifactCorrection
+          ? { artifactCorrection: structuredClone(input.artifactCorrection) }
+          : {}),
+        ...(input.contextRequest
+          ? { requestedContext: structuredClone(input.contextRequest) }
+          : {}),
         ...(input.repair
           ? {
               repair: {
@@ -1570,14 +1688,17 @@ export function openPackageWorkflowControlEngine(
           path.resolve(input.workspaceRoot, root),
         ),
         allowedPaths: [
-          ...new Set([...phase.read, ...phase.write, ...phase.delete]),
+          ...new Set([
+            ...executionBoundary.read,
+            ...executionBoundary.write,
+            ...executionBoundary.delete,
+          ]),
         ],
         timeoutMs: LIMITS.phaseTimeoutMs,
         signal: input.signal,
         failureOverride: phaseRuntime.failureOverride,
         ledgerProjection: input.ledgerProjection,
         candidateArtifact: input.candidateArtifact,
-        onStreamStart: input.onHeaders,
         onStreamProgress: input.onProgress,
       });
       if (!child.ok) {
@@ -1593,18 +1714,43 @@ 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") {
-        return classifyCandidateContextRequest(result, [
-          ...phase.read,
-          ...phase.write,
-          ...phase.delete,
-        ]);
+        return classifyCandidateContextRequest(result, {
+          phase: input.phase,
+          readPaths: phase.read,
+          writePaths: phase.write,
+          deletePaths: phase.delete,
+          taskPaths: [
+            ...new Set(
+              Object.values(input.task.phases).flatMap((boundary) => [
+                ...boundary.read,
+                ...boundary.write,
+                ...boundary.delete,
+              ]),
+            ),
+          ],
+          redWritePaths: input.task.phases.red.write,
+          agents: {
+            impact: input.task.agents.impact,
+            ...(input.task.agents.target
+              ? { target: input.task.agents.target }
+              : {}),
+          },
+        });
       }
       if (result.kind !== "sealed-candidate") {
         return { kind: "retryable", code: "candidate-diff-invalid" };
@@ -1716,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,
@@ -1735,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;
@@ -1827,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,
@@ -1902,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"
@@ -1914,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") {
@@ -1940,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");
               }
@@ -2028,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 {
@@ -2113,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" };
@@ -2166,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();
@@ -2181,6 +2417,7 @@ export function registerWorkflowControl(
   });
   pi.on("session_shutdown", async () => {
     activePrompt = undefined;
+    designFailures.clear();
     activity.detach();
     await packetRuntime.drain();
     await closeEngines();