@abelxiaoxing/cadence 1.2.3 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",

package/src/design-control.ts

@@ -456,12 +456,21 @@ export class DesignController {
   private constructor(options: DesignControllerOptions) {
     this.consumerRoot = path.resolve(options.consumerRoot);
     this.#runs = RunStore.open(options.stateRoot);
-    this.#journal = DesignJournal.open(options.stateRoot, {
-      ...(options.now ? { now: options.now } : {}),
-      ...(options.finalizationLeaseMs !== undefined
-        ? { finalizationLeaseMs: options.finalizationLeaseMs }
-        : {}),
-    });
+    try {
+      this.#journal = DesignJournal.open(options.stateRoot, {
+        ...(options.now ? { now: options.now } : {}),
+        ...(options.finalizationLeaseMs !== undefined
+          ? { finalizationLeaseMs: options.finalizationLeaseMs }
+          : {}),
+      });
+    } catch (error) {
+      try {
+        this.#runs.close();
+      } catch {
+        // The Design journal initialization failure remains authoritative.
+      }
+      throw error;
+    }
     this.#inspectOpenSpec = options.inspectOpenSpec;
   }
 
@@ -588,18 +597,32 @@ export class DesignController {
 
   #start(request: Extract<DesignControlRequest, { operation: "start" }>) {
     const fromRequirement = "requirement" in request;
-    const run = this.#runs.startRun({
-      stage: "abel-design",
-      ...(fromRequirement
-        ? {
-            provisionalKey: transientHash(
-              "abel-design-requirement",
-              request.requirement,
-            ),
-          }
-        : { change: request.change }),
-      operationId: request.operationId,
-    });
+    let run: ReturnType<RunStore["startRun"]>;
+    try {
+      run = this.#runs.startRun({
+        stage: "abel-design",
+        ...(fromRequirement
+          ? {
+              provisionalKey: transientHash(
+                "abel-design-requirement",
+                request.requirement,
+              ),
+              provisionalAliases: [
+                transientHash(
+                  "abel-design-requirement-v1",
+                  request.requirement,
+                ),
+              ],
+            }
+          : { change: request.change }),
+        operationId: request.operationId,
+      });
+    } catch (error) {
+      if (error instanceof Error && error.message === "operation-id-conflict") {
+        throw new Error("design-operation-conflict", { cause: error });
+      }
+      throw error;
+    }
     if (run.state === "created") {
       this.#runs.transition({
         runId: run.runId,

package/src/design-journal.ts

@@ -317,12 +317,21 @@ export class DesignJournal {
     }
     const stateRoot = prepareStateRoot(unresolved);
     const database = new DatabaseSync(stateRoot.databasePath);
-    database.exec("PRAGMA foreign_keys = ON");
-    database.exec("PRAGMA journal_mode = WAL");
-    database.exec("PRAGMA synchronous = FULL");
-    database.exec("PRAGMA busy_timeout = 5000");
-    database.exec(SCHEMA);
-    return new DesignJournal(stateRoot, database, options);
+    try {
+      database.exec("PRAGMA foreign_keys = ON");
+      database.exec("PRAGMA journal_mode = WAL");
+      database.exec("PRAGMA synchronous = FULL");
+      database.exec("PRAGMA busy_timeout = 5000");
+      database.exec(SCHEMA);
+      return new DesignJournal(stateRoot, database, options);
+    } catch (error) {
+      try {
+        database.close();
+      } catch {
+        // The Design journal initialization failure remains authoritative.
+      }
+      throw error;
+    }
   }
 
   #assertOpen(): void {
@@ -337,7 +346,11 @@ export class DesignJournal {
       this.#database.exec("COMMIT");
       return result;
     } catch (error) {
-      this.#database.exec("ROLLBACK");
+      try {
+        this.#database.exec("ROLLBACK");
+      } catch {
+        // The original operation or commit failure remains authoritative.
+      }
       throw error;
     }
   }

package/src/index.ts

@@ -69,9 +69,9 @@ import {
   unavailableRoutePolicy,
   type WorkerRoutePolicy,
 } from "./route-policy.ts";
-import { RunStoreFormatError } from "./run-store.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,
@@ -431,20 +431,160 @@ type SafeDesignFailure = {
   kind: "design-control-failure";
   operation: string;
   code: string;
-  diagnostics: ReadonlyArray<Record<string, 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 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 classified = classifyDesignFailure(error, operation, boundary);
   const rawDiagnostics: readonly unknown[] =
     error instanceof DesignFinalizationError ||
     error instanceof DesignPlanValidationError ||
@@ -468,8 +608,11 @@ function safeDesignFailure(
       }
       const admitted = Object.fromEntries(
         Object.entries(candidate as Record<string, unknown>)
-          .filter(
-            (entry): entry is [string, string] =>
+          .filter((entry): entry is [string, string | boolean] => {
+            if (entry[0] === "retryable") {
+              return typeof entry[1] === "boolean";
+            }
+            return (
               [
                 "code",
                 "taskId",
@@ -484,8 +627,9 @@ function safeDesignFailure(
                 "producerPhase",
               ].includes(entry[0]) &&
               typeof entry[1] === "string" &&
-              SAFE_DESIGN_ERROR_CODE.test(entry[1]),
-          )
+              SAFE_DESIGN_ERROR_CODE.test(entry[1])
+            );
+          })
           .sort(([left], [right]) => left.localeCompare(right)),
       );
       return typeof admitted.code === "string" ? [admitted] : [];
@@ -499,10 +643,18 @@ function safeDesignFailure(
         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,
+    code: classified.code,
     diagnostics,
   };
 }
@@ -2082,18 +2234,19 @@ export function registerWorkflowControl(
             }
             const designRequest = validateDesignControlRequest(record.request);
             if (!designRequest.ok) throw new Error(designRequest.code);
-            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");
+            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"
@@ -2101,15 +2254,14 @@ export function registerWorkflowControl(
                 await deactivateStage();
               }
               return {
-                content: [
-                  { type: "text" as const, text: JSON.stringify(payload) },
-                ],
+                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);

package/src/run-store.ts

@@ -33,6 +33,17 @@ export class RunStoreFormatError extends Error {
   }
 }
 
+export class RunStoreMigrationError extends Error {
+  readonly code = "run-store-migration-failed" as const;
+  readonly schemaVersion: number;
+
+  constructor(schemaVersion: number, cause: unknown) {
+    super("run-store-migration-failed", { cause });
+    this.name = "RunStoreMigrationError";
+    this.schemaVersion = schemaVersion;
+  }
+}
+
 const CHANGE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/u;
 const IDENTIFIER = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
 const SHA256 = /^[a-f0-9]{64}$/u;
@@ -67,6 +78,7 @@ export interface StartRunInput {
   stage: RunStage;
   change?: string;
   provisionalKey?: string;
+  provisionalAliases?: readonly string[];
   operationId: string;
 }
 
@@ -236,6 +248,7 @@ const REQUIRED_DELIVERY_BINDING_COLUMNS = [
   "record_hash",
   "operation_id",
 ] as const;
+const LEGACY_SCHEMA_VERSION = 4;
 
 function applicationTables(database: DatabaseSync): string[] {
   return (
@@ -257,11 +270,12 @@ function tableColumns(database: DatabaseSync, table: string): string[] {
   ).map(({ name }) => name);
 }
 
-function hasCurrentSchema(database: DatabaseSync): boolean {
-  const tables = applicationTables(database);
+function hasRequiredCoreSchema(
+  database: DatabaseSync,
+  tables: readonly string[],
+): boolean {
   const deliveryBindingColumns = tableColumns(database, "delivery_bindings");
   return (
-    !tables.includes("schema_meta") &&
     REQUIRED_TABLES.every((table) => tables.includes(table)) &&
     REQUIRED_DELIVERY_BINDING_COLUMNS.every((column) =>
       deliveryBindingColumns.includes(column),
@@ -269,6 +283,110 @@ function hasCurrentSchema(database: DatabaseSync): boolean {
   );
 }
 
+function hasCurrentSchema(
+  database: DatabaseSync,
+  tables: readonly string[],
+): boolean {
+  return (
+    !tables.includes("schema_meta") && hasRequiredCoreSchema(database, tables)
+  );
+}
+
+function isSupportedLegacySchema(
+  database: DatabaseSync,
+  tables: readonly string[],
+): boolean {
+  if (
+    !tables.includes("schema_meta") ||
+    !hasRequiredCoreSchema(database, tables) ||
+    tableColumns(database, "schema_meta").join("\0") !== "version"
+  ) {
+    return false;
+  }
+  const rows = database
+    .prepare("SELECT version FROM schema_meta")
+    .all() as unknown as Array<{
+    version: number;
+  }>;
+  return (
+    rows.length === 1 && Number(rows[0]?.version) === LEGACY_SCHEMA_VERSION
+  );
+}
+
+function isSqliteLocked(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 isStoreUnavailable(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const errcode = (error as { errcode?: unknown }).errcode;
+  if ([8, 10, 13, 14, 23, 24].includes(Number(errcode))) return true;
+  const code = (error as { code?: unknown }).code;
+  return (
+    typeof code === "string" &&
+    [
+      "EACCES",
+      "EBUSY",
+      "EMFILE",
+      "ENFILE",
+      "ENOSPC",
+      "EPERM",
+      "EROFS",
+    ].includes(code)
+  );
+}
+
+function ensureCurrentSchema(
+  database: DatabaseSync,
+  databasePath: string,
+): void {
+  const initialTables = applicationTables(database);
+  if (hasCurrentSchema(database, initialTables)) return;
+  let transactionStarted = false;
+  let migrating = false;
+  try {
+    database.exec("BEGIN IMMEDIATE");
+    transactionStarted = true;
+    const tables = applicationTables(database);
+    if (tables.length === 0) {
+      database.exec(SCHEMA);
+    } else if (hasCurrentSchema(database, tables)) {
+      // Another opener may already have completed the same migration.
+    } else if (isSupportedLegacySchema(database, tables)) {
+      migrating = true;
+      database.exec("DROP TABLE schema_meta");
+    } else {
+      throw new RunStoreFormatError(databasePath);
+    }
+    database.exec("COMMIT");
+  } catch (error) {
+    if (transactionStarted) {
+      try {
+        database.exec("ROLLBACK");
+      } catch {
+        // The original schema or commit failure remains authoritative.
+      }
+    }
+    if (
+      error instanceof RunStoreFormatError ||
+      error instanceof RunStoreMigrationError ||
+      isSqliteLocked(error)
+    ) {
+      throw error;
+    }
+    if (migrating) {
+      throw new RunStoreMigrationError(LEGACY_SCHEMA_VERSION, error);
+    }
+    throw error;
+  }
+}
+
 function parseProjection(value: string): RunProjection {
   const parsed = JSON.parse(value) as RunProjection;
   if (
@@ -281,22 +399,35 @@ function parseProjection(value: string): RunProjection {
   return parsed;
 }
 
-function lookupKey(input: StartRunInput): string {
+function lookupKeys(input: StartRunInput): string[] {
   const hasChange = typeof input.change === "string";
   const hasProvisional = typeof input.provisionalKey === "string";
   if (hasChange === hasProvisional) throw new Error("invalid-run-lookup-key");
   if (hasChange) {
+    if (input.provisionalAliases !== undefined) {
+      throw new Error("invalid-run-lookup-key");
+    }
     if (!CHANGE_NAME.test(input.change as string))
       throw new Error("invalid-change");
-    return `change:${input.change}`;
+    return [`change:${input.change}`];
   }
   if (!SHA256.test(input.provisionalKey as string)) {
     throw new Error("invalid-provisional-key");
   }
+  if (
+    input.provisionalAliases !== undefined &&
+    (!Array.isArray(input.provisionalAliases) ||
+      input.provisionalAliases.length > 4 ||
+      input.provisionalAliases.some((alias) => !SHA256.test(alias)))
+  ) {
+    throw new Error("invalid-provisional-key");
+  }
   if (input.stage !== "abel-design") {
     throw new Error("provisional-run-requires-design");
   }
-  return `provisional:${input.provisionalKey}`;
+  return [
+    ...new Set([input.provisionalKey, ...(input.provisionalAliases ?? [])]),
+  ].map((hash) => `provisional:${hash}`);
 }
 
 export class RunStore {
@@ -344,22 +475,37 @@ export class RunStore {
     try {
       database = new DatabaseSync(stateRoot.databasePath);
       configureDatabase(database, options.busyTimeoutMs);
-      const tables = applicationTables(database);
-      if (tables.length === 0) {
-        database.exec(SCHEMA);
-      } else if (!hasCurrentSchema(database)) {
-        throw new RunStoreFormatError(stateRoot.databasePath);
-      }
+      ensureCurrentSchema(database, stateRoot.databasePath);
     } catch (error) {
-      database?.close();
-      if (error instanceof RunStoreFormatError) throw error;
+      try {
+        database?.close();
+      } catch {
+        // The run-store initialization failure remains authoritative.
+      }
+      if (
+        error instanceof RunStoreFormatError ||
+        error instanceof RunStoreMigrationError ||
+        isSqliteLocked(error) ||
+        isStoreUnavailable(error)
+      ) {
+        throw error;
+      }
       throw new RunStoreFormatError(stateRoot.databasePath);
     }
     if (!database) throw new RunStoreFormatError(stateRoot.databasePath);
     const store = new RunStore(stateRoot, database, options);
-    store.#secureDatabaseFiles();
-    store.recoverExpiredLeases();
-    return store;
+    try {
+      store.#secureDatabaseFiles();
+      store.recoverExpiredLeases();
+      return store;
+    } catch (error) {
+      try {
+        database.close();
+      } catch {
+        // The permission or lease-recovery failure remains authoritative.
+      }
+      throw error;
+    }
   }
 
   #assertOpen(): void {
@@ -374,7 +520,11 @@ export class RunStore {
       value = work();
       this.#database.exec("COMMIT");
     } catch (error) {
-      this.#database.exec("ROLLBACK");
+      try {
+        this.#database.exec("ROLLBACK");
+      } catch {
+        // The original operation or commit failure remains authoritative.
+      }
       throw error;
     }
     this.#secureDatabaseFiles();
@@ -517,16 +667,62 @@ export class RunStore {
     if (input.stage !== "abel-design" && input.stage !== "abel-implement") {
       throw new Error("invalid-run-stage");
     }
-    const key = lookupKey(input);
+    const keys = lookupKeys(input);
+    const key = keys[0];
+    if (!key) throw new Error("invalid-run-lookup-key");
     return this.#transaction(() => {
-      let existing = this.#database
+      const operationRows = this.#database
         .prepare(
-          `SELECT run_id, projection_json FROM runs
-           WHERE root_hash = ? AND stage = ? AND lookup_key = ?`,
+          `SELECT operations.run_id, operations.kind, operations.state,
+                  operations.outcome_json, runs.lookup_key
+           FROM operations
+           JOIN runs ON runs.run_id = operations.run_id
+           WHERE runs.root_hash = ? AND runs.stage = ?
+             AND operations.operation_id = ?`,
         )
-        .get(this.stateRoot.consumerRootHash, input.stage, key) as
-        | RunRow
-        | undefined;
+        .all(
+          this.stateRoot.consumerRootHash,
+          input.stage,
+          input.operationId,
+        ) as unknown as Array<{
+        run_id: string;
+        kind: string;
+        state: string;
+        outcome_json: string | null;
+        lookup_key: string;
+      }>;
+      if (operationRows.length > 0) {
+        const replay = operationRows.find(
+          (row) =>
+            row.kind === "start" &&
+            row.state === "committed" &&
+            row.outcome_json !== null &&
+            keys.includes(row.lookup_key),
+        );
+        if (operationRows.length !== 1 || !replay) {
+          throw new Error("operation-id-conflict");
+        }
+        const outcome = parseProjection(replay.outcome_json as string);
+        if (outcome.runId !== replay.run_id) {
+          throw new Error("operation-outcome-invalid");
+        }
+        return outcome;
+      }
+      let existing: RunRow | undefined;
+      for (const compatibleKey of keys) {
+        const candidate = this.#database
+          .prepare(
+            `SELECT run_id, projection_json FROM runs
+             WHERE root_hash = ? AND stage = ? AND lookup_key = ?`,
+          )
+          .get(this.stateRoot.consumerRootHash, input.stage, compatibleKey) as
+          | RunRow
+          | undefined;
+        if (candidate && existing && candidate.run_id !== existing.run_id) {
+          throw new Error("run-lookup-conflict");
+        }
+        existing ??= candidate;
+      }
       if (existing) {
         const projection = parseProjection(existing.projection_json);
         if (