@abelxiaoxing/cadence 1.2.2 → 1.2.4

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,8 +69,9 @@ import {
   unavailableRoutePolicy,
   type WorkerRoutePolicy,
 } from "./route-policy.ts";
+import { RunStoreFormatError, RunStoreMigrationError } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
-import { resolveStateRoot } from "./state-root.ts";
+import { resolveStateRoot, StateRootError } from "./state-root.ts";
 import {
   ACTIVITY_DETAILS_KEY,
   ActivityController,
@@ -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,241 @@ 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 | boolean>>;
+};
+
+type DesignFailureBoundary =
+  | "dispatch"
+  | "initialization"
+  | "execution"
+  | "serialization";
+
+function sqliteLocked(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "errcode" in error &&
+    ((error as { errcode?: unknown }).errcode === 5 ||
+      (error as { errcode?: unknown }).errcode === 6)
+  );
+}
+
+function sqliteUnavailable(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const errcode = Number((error as { errcode?: unknown }).errcode);
+  const code = (error as { code?: unknown }).code;
+  return (
+    [8, 10, 13, 14, 23, 24].includes(errcode) ||
+    (typeof code === "string" &&
+      [
+        "EACCES",
+        "EBUSY",
+        "EMFILE",
+        "ENFILE",
+        "ENOSPC",
+        "EPERM",
+        "EROFS",
+      ].includes(code))
+  );
+}
+
+function classifyDesignFailure(
+  error: unknown,
+  operation: string,
+  boundary: DesignFailureBoundary,
+): {
+  code: string;
+  category: string;
+  retryable: boolean;
+  field?: string;
+} {
+  const message = error instanceof Error ? error.message : "";
+  if (error instanceof DesignPlanValidationError) {
+    return {
+      code: "design-plan-validation-invalid",
+      category: "validation",
+      retryable: false,
+    };
+  }
+  if (
+    error instanceof RunStoreMigrationError ||
+    error instanceof RunStoreFormatError
+  ) {
+    return {
+      code: "design-store-migration-failed",
+      category: "storage",
+      retryable: false,
+      field: "schemaVersion",
+    };
+  }
+  if (sqliteLocked(error)) {
+    return {
+      code: "design-store-locked",
+      category: "storage",
+      retryable: true,
+    };
+  }
+  if (sqliteUnavailable(error)) {
+    return {
+      code: "design-store-unavailable",
+      category: "storage",
+      retryable: false,
+    };
+  }
+  if (error instanceof StateRootError) {
+    return {
+      code: "design-store-unavailable",
+      category: "storage",
+      retryable: false,
+    };
+  }
+  if (
+    message === "design-operation-conflict" ||
+    message === "operation-id-conflict"
+  ) {
+    return {
+      code: "design-operation-conflict",
+      category: "control",
+      retryable: false,
+      field: "operationId",
+    };
+  }
+  if (message === "stage-control-mismatch") {
+    return {
+      code: "design-stage-inactive",
+      category: "stage",
+      retryable: false,
+    };
+  }
+  if (message === "invalid-design-control-request") {
+    return {
+      code: "invalid-design-control-request",
+      category: "validation",
+      retryable: false,
+    };
+  }
+  if (boundary === "serialization") {
+    return {
+      code: "design-receipt-serialization-failed",
+      category: "control",
+      retryable: false,
+    };
+  }
+  if (boundary === "initialization") {
+    return {
+      code: "design-store-unavailable",
+      category: "storage",
+      retryable: false,
+    };
+  }
+  if (
+    error instanceof DesignFinalizationError ||
+    error instanceof DeliveryValidationError ||
+    (message.startsWith("design-") && SAFE_DESIGN_ERROR_CODE.test(message))
+  ) {
+    return { code: message, category: "control", retryable: false };
+  }
+  if (operation === "start") {
+    return {
+      code: "design-run-create-failed",
+      category: "storage",
+      retryable: false,
+    };
+  }
+  return {
+    code: "design-control-internal",
+    category: "control",
+    retryable: false,
+  };
+}
+
+function safeDesignFailure(
+  error: unknown,
+  operation: string,
+  boundary: DesignFailureBoundary = "dispatch",
+): SafeDesignFailure {
+  const classified = classifyDesignFailure(error, operation, boundary);
+  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 | boolean] => {
+            if (entry[0] === "retryable") {
+              return typeof entry[1] === "boolean";
+            }
+            return (
+              [
+                "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);
+  if (diagnostics.length === 0) {
+    diagnostics.push({
+      code: classified.code,
+      category: classified.category,
+      retryable: classified.retryable,
+      ...(classified.field ? { field: classified.field } : {}),
+    });
+  }
+  return {
+    kind: "design-control-failure",
+    operation: SAFE_DESIGN_ERROR_CODE.test(operation) ? operation : "unknown",
+    code: classified.code,
+    diagnostics,
+  };
+}
+
 export interface WorkflowControlEngine {
   execute(
     command: unknown,
@@ -733,7 +971,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 +1140,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 +1222,6 @@ export function packageDeliverySource(
         throw new DeliveryValidationError([...diagnostics]);
       }
       return {
-        version: 2,
         gate: "gate-b",
         revision: receipt.deliveryRevision,
         receiptHash,
@@ -1251,7 +1490,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 +1500,6 @@ function normalizedFailureIdentities(input: {
   return [
     sha256(
       canonicalJson({
-        version: 1,
         verificationId: input.step.id,
         exitCode: input.exitCode,
         output: normalizedOutput,
@@ -1514,6 +1752,8 @@ export function openPackageWorkflowControlEngine(
         context,
         parentPayloadBridge,
         input.signal,
+        process.env,
+        { onResponse: input.onHeaders },
       );
       if (!phaseRuntime.ok) {
         if (phaseRuntime.failure.kind === "cancelled") {
@@ -1565,6 +1805,9 @@ export function openPackageWorkflowControlEngine(
         ...(input.artifactCorrection
           ? { artifactCorrection: structuredClone(input.artifactCorrection) }
           : {}),
+        ...(input.contextRequest
+          ? { requestedContext: structuredClone(input.contextRequest) }
+          : {}),
         ...(input.repair
           ? {
               repair: {
@@ -1608,7 +1851,6 @@ export function openPackageWorkflowControlEngine(
         failureOverride: phaseRuntime.failureOverride,
         ledgerProjection: input.ledgerProjection,
         candidateArtifact: input.candidateArtifact,
-        onStreamStart: input.onHeaders,
         onStreamProgress: input.onProgress,
       });
       if (!child.ok) {
@@ -1624,10 +1866,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 +2014,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 +2066,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 +2159,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 +2219,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 +2234,40 @@ export function registerWorkflowControl(
             }
             const designRequest = validateDesignControlRequest(record.request);
             if (!designRequest.ok) throw new Error(designRequest.code);
-            const engine = await engineFor(ctx);
-            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();
+            let boundary: DesignFailureBoundary = "initialization";
+            try {
+              const engine = await engineFor(ctx);
+              if (!engine.executeDesign)
+                throw new Error("design-control-unavailable");
+              boundary = "execution";
+              const payload = await engine.executeDesign(designRequest.value);
+              boundary = "serialization";
+              const serialized = JSON.stringify(payload);
+              if (serialized === undefined) {
+                throw new Error("design-receipt-serialization-failed");
+              }
+              boundary = "execution";
+              if (
+                designRequest.value.operation === "finalize-delivery" &&
+                payload.state === "completed"
+              ) {
+                await deactivateStage();
+              }
+              return {
+                content: [{ type: "text" as const, text: serialized }],
+                details: payload,
+              };
+            } catch (error) {
+              const failure = safeDesignFailure(
+                error,
+                designRequest.value.operation,
+                boundary,
+              );
+              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 +2278,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 +2372,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 +2467,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 +2553,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 +2569,7 @@ export function registerWorkflowControl(
   });
   pi.on("session_shutdown", async () => {
     activePrompt = undefined;
+    designFailures.clear();
     activity.detach();
     await packetRuntime.drain();
     await closeEngines();