@abelxiaoxing/cadence 1.3.0 → 1.4.1

package/src/design-control.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import {
   lstatSync,
@@ -8,9 +9,15 @@ import {
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
+import {
+  type ChangeContract,
+  normalizeChangeContract,
+} from "./change-contract.ts";
+import { changeContractDiagnostics } from "./change-contract-schema.ts";
 import { isValidRelativePath } from "./contracts.ts";
 import {
   assessDeliveryTraceability,
+  bindTaskVerifications,
   compileGateAReceipt,
   compileImplementPlan,
   compileReadyReceipt,
@@ -21,6 +28,7 @@ import {
   parseImplementPlan,
   parseReadyReceipt,
 } from "./delivery-compiler.ts";
+import type { DesignPlanDiagnostic } from "./design-diagnostics.ts";
 import {
   type DesignArtifactOperationFacts,
   type DesignArtifactOperationOutcome,
@@ -28,6 +36,8 @@ import {
   type DesignStatusProjection,
 } from "./design-journal.ts";
 import { OpenSpecCliError, type OpenSpecDiagnostic } from "./openspec-cli.ts";
+import { planAuthoringSummary } from "./plan-draft-summary.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";
@@ -39,6 +49,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;
@@ -82,7 +106,7 @@ export type DesignControlRequest =
       runId: string;
       operationId: string;
       gate: "gate-a";
-      contract: string;
+      contract: string | ChangeContract;
     }
   | {
       operation: "approve-gate";
@@ -179,7 +203,53 @@ function lifecycleOperationId(kind: string, runId: string): string {
     .slice(0, 32)}`;
 }
 
-export function validateDesignControlRequest(
+export class DesignControlValidationError extends DesignPlanValidationError {
+  constructor(diagnostics: readonly DesignPlanDiagnostic[]) {
+    super("invalid-design-control-request", diagnostics);
+  }
+}
+export function validateDesignControlRequest(value: unknown):
+  | { ok: true; value: DesignControlRequest }
+  | {
+      ok: false;
+      code: "invalid-design-control-request";
+      diagnostics: DesignPlanDiagnostic[];
+    } {
+  const parsed = parseDesignControlRequest(value);
+  if (parsed.ok) return parsed;
+  let diagnostics: DesignPlanDiagnostic[] = [];
+  if (
+    isRecord(value) &&
+    value.operation === "approve-gate" &&
+    value.gate === "gate-a" &&
+    typeof value.contract !== "string"
+  )
+    diagnostics = changeContractDiagnostics(value.contract);
+  if (!diagnostics.length) {
+    const field = !isRecord(value)
+      ? "request"
+      : typeof value.operation !== "string"
+        ? "operation"
+        : value.operation !== "start" &&
+            (typeof value.runId !== "string" || !IDENTIFIER.test(value.runId))
+          ? "runId"
+          : !["status", "validate-plan-draft"].includes(
+                String(value.operation),
+              ) &&
+              (typeof value.operationId !== "string" ||
+                !IDENTIFIER.test(value.operationId))
+            ? "operationId"
+            : value.operation === "approve-gate"
+              ? value.gate === "gate-a"
+                ? "contract"
+                : "gate"
+              : "request";
+    diagnostics = [{ code: "design-control-field-invalid", field }];
+  }
+  return { ...parsed, diagnostics };
+}
+
+function parseDesignControlRequest(
   value: unknown,
 ):
   | { ok: true; value: DesignControlRequest }
@@ -275,9 +345,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" };
   }
@@ -459,6 +527,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);
@@ -485,7 +554,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");
   }
 
@@ -519,7 +603,8 @@ export class DesignController {
   async execute(value: unknown): Promise<Record<string, unknown>> {
     this.#assertOpen();
     const validation = validateDesignControlRequest(value);
-    if (!validation.ok) throw new Error(validation.code);
+    if (!validation.ok)
+      throw new DesignControlValidationError(validation.diagnostics);
     const request = validation.value;
     switch (request.operation) {
       case "start":
@@ -597,6 +682,30 @@ export class DesignController {
       completed: run.state === "completed",
       ...(run.pauseCode ? { pause: { code: run.pauseCode } } : {}),
       legalOperations,
+      nextStep: terminal
+        ? null
+        : !design.gates.gateA.current
+          ? {
+              operation: "approve-gate",
+              instruction:
+                "Read applicable instructions, the affected source and existing tests, and the verification manifest together. Resolve only remaining substantive choices; use existing same-task approval. Submit the accepted structured ChangeContract, not a prose placeholder.",
+            }
+          : !design.change
+            ? {
+                operation: "bind-change",
+                instruction: "Bind the approved change name to this runId.",
+              }
+            : !design.plan || !design.gates.gateB.current
+              ? {
+                  operation: "write-artifact",
+                  instruction:
+                    "Write proposal, design, specs, author task checkboxes with exact Scenario references, and plan-draft.json. Use the installed example named in the tool description; omit derived identities. Preflight then compile; compilation supplies verification bindings and Gate B.",
+                }
+              : {
+                  operation: "finalize-delivery",
+                  instruction:
+                    "Finalize the prepared artifacts. If tasks or the draft changed since compilation, preflight and compile again first. No separate Gate B approval is needed.",
+                },
       packetActions: terminal ? [] : ["finish"],
       design,
     };
@@ -631,6 +740,7 @@ export class DesignController {
       throw error;
     }
     if (run.state === "created") {
+      this.#journal.inheritFinalizedAuthority(run.runId);
       this.#runs.transition({
         runId: run.runId,
         to: "paused",
@@ -831,7 +941,22 @@ export class DesignController {
         { code: "design-plan-draft-invalid", field: "plan-draft.json" },
       ]);
     }
+    const authoredDraft = structuredClone(draft);
+    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) {
@@ -839,7 +964,7 @@ export class DesignController {
         { code: "design-plan-change-mismatch", field: "changeId" },
       ]);
     }
-    return { status, compiled };
+    return { status, compiled, authoredDraft };
   }
 
   #validatePlanDraft(
@@ -848,11 +973,12 @@ export class DesignController {
       { operation: "validate-plan-draft" }
     >,
   ) {
-    const { compiled } = this.#readCompiledDraft(request.runId);
+    const { compiled, authoredDraft } = this.#readCompiledDraft(request.runId);
     return {
       operation: request.operation,
       runId: request.runId,
       valid: true,
+      summary: planAuthoringSummary(compiled.plan, authoredDraft),
       plan: {
         taskCount: compiled.plan.tasks.length,
         outputCount: compiled.plan.outputs.length,
@@ -882,9 +1008,47 @@ 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 tasksPath = safeRelative(change, "tasks.md");
+      if (observeSafePath(this.consumerRoot, tasksPath).kind === "absent") {
+        throw new DesignPlanValidationError(
+          "design-traceability-input-unavailable",
+          [{ code: "design-traceability-input-unavailable", path: "tasks.md" }],
+        );
+      }
+      const priorTasks = boundedArtifactBytes(this.consumerRoot, tasksPath);
+      const tasksBytes = Buffer.from(
+        bindTaskVerifications(
+          new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+            priorTasks,
+          ),
+          compiled.plan,
+        ),
+        "utf8",
+      );
+      if (tasksBytes.length > MAX_DESIGN_FILE_BYTES) {
+        throw new Error("design-artifact-content-too-large");
+      }
+      const tasksUnchanged = tasksBytes.equals(priorTasks);
+      const unchanged =
+        tasksUnchanged &&
+        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);
+      if (
+        !boundedArtifactBytes(this.consumerRoot, tasksPath).equals(priorTasks)
+      ) {
+        throw new Error("design-artifact-currentness-mismatch");
+      }
+      // The compilation journal commits only after both files are installed.
+      // A crash before that point can replay this deterministic projection;
+      // finalization always rechecks the plan and task bytes together.
+      if (!tasksUnchanged)
+        atomicWrite(this.consumerRoot, tasksPath, tasksBytes);
       atomicWrite(
         this.consumerRoot,
         safeRelative(change, "implement-plan.json"),
@@ -897,6 +1061,7 @@ export class DesignController {
         rawSha256: compiled.rawSha256,
         canonicalHash: compiled.planHash,
         lease,
+        certify: true,
       });
     } finally {
       this.#journal.releaseFinalizationLease(lease);
@@ -970,7 +1135,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,
         });
@@ -1067,14 +1234,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))

package/src/design-diagnostics.ts

@@ -0,0 +1,150 @@
+import { canonicalJson, compareCanonicalStrings } from "./canonical.ts";
+import { isValidRelativePath } from "./contracts.ts";
+
+export type SafeDesignDiagnostic = Record<string, string | boolean | string[]>;
+const CODE = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
+const IDENTITIES = new Set([
+  "code",
+  "taskId",
+  "phase",
+  "field",
+  "category",
+  "owner",
+  "verificationId",
+  "outputId",
+  "dependencyTaskId",
+  "producerTaskId",
+  "producerPhase",
+  "command",
+  "reason",
+  "systemCode",
+  "exitCode",
+]);
+const HINTS = new Map<string, string>(
+  Object.entries({
+    "change-contract-acceptance-missing":
+      "Read the current approved ChangeContract from Design status and include each accepted verification obligation in the plan's phase, affected, full-suite or post-apply verification. Command, arguments, inputs and classification must match; copying only its ID is insufficient. Keep accepted IDs, statements and scope unchanged.",
+    "script-command-mismatch":
+      "command must equal the literal package.json scripts[script] value, not an invocation such as npm run test. In PlanDraft, omit command to bind it from the manifest. Explicit commands, including approved Gate acceptance verifiers, remain exact and must be corrected rather than silently replaced.",
+    "design-traceability-input-unavailable":
+      "Write tasks.md with author task checkboxes and exact owned Scenario references, plus the referenced spec artifacts, before compilation and finalization.",
+    "traceability-managed-region-invalid":
+      "Repair the paired ABEL:VERIFICATION-BINDINGS markers in tasks.md without removing author evidence, then compile again. Code replaces only one complete managed region.",
+    "traceability-managed-region-stale":
+      "Compile the current draft again to regenerate phase verification bindings; do not copy verifier identities by hand.",
+    "traceability-task-unmapped":
+      "Put each planned task ID in backticks on its author checkbox outside the generated bindings region.",
+    "traceability-verification-unmapped":
+      "Compile after writing tasks.md so code installs phase verification bindings while preserving the author evidence.",
+    "traceability-reference-empty":
+      "Add exact backticked specs/<capability>/spec.md#Requirement title/Scenario title references under the owning author tasks. Code does not infer Scenario ownership.",
+    "change-contract-field-invalid":
+      "Correct the indicated ChangeContract field using the tool schema. Keep accepted scope and evidence unchanged.",
+    "design-control-field-invalid":
+      "Use the exact operation envelope and returned runId; inspect the indicated field in the tool schema.",
+    "verification-reference-unavailable":
+      "Use a declared verificationDefinitions name or an explicit verification contract.",
+    "verification-reference-invalid":
+      "A verification reference contains only use and optional Red expectedFailure. Put executable fields in its definition.",
+    "verification-definition-invalid":
+      "Define one existing atomic verifier without id, classification, executionBindings or references.",
+    "current-task-outside-write-set":
+      "Omit disposition to derive the test owner from task writes. Keep path and evidence; do not widen writes to satisfy this label.",
+    "related-test-owner-ambiguous":
+      "Several other tasks edit this test. Choose the intended regression-task owner explicitly, or resolve overlapping task ownership.",
+    "verification-input-binding-mismatch":
+      "Omit verificationInputs to derive exact bindings from the verification contract and declared outputs. Keep supporting source files in read, not in verificationInputs.",
+    "workspace-input-has-producer":
+      "Omit verificationInputs or bind this path to its declared outputId instead of workspace.",
+    "multiple-output-producers":
+      "Declare one producer per output path before deriving input bindings. Do not choose a producer by list order.",
+    "producer-not-dependency":
+      "The producing task must be an explicit dependency of this task. Input inference does not add dependency authority.",
+    "producer-phase-after-consumer":
+      "This verification needs an output from a later phase. Correct the producer or phase order; input inference cannot make that output available earlier.",
+    "verification-input-not-declared":
+      "The verification contract requires a path outside this phase's read/write declarations. Correct the contract or explicitly declare the approved input path.",
+    "workspace-input-unavailable":
+      "The required workspace input is missing or not a safe regular file. Correct its path or declare its planned producer.",
+  }),
+);
+function safePath(value: unknown): value is string {
+  return isValidRelativePath(value) && !/[\p{Cc}\p{Cf}]/u.test(value);
+}
+
+/** One bounded projection for tool feedback and TUI; guidance is code-owned. */
+export function projectDesignDiagnostic(
+  value: unknown,
+): SafeDesignDiagnostic | undefined {
+  if (typeof value === "string") value = { code: value.split(":", 1)[0] };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  const record = value as Record<string, unknown>;
+  if (typeof record.code !== "string" || !CODE.test(record.code))
+    return undefined;
+  const result: SafeDesignDiagnostic = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (IDENTITIES.has(key) && typeof entry === "string" && CODE.test(entry))
+      result[key] = entry;
+    else if (
+      (key === "retryable" || key === "pathsTruncated") &&
+      typeof entry === "boolean"
+    )
+      result[key] =
+        key === "pathsTruncated"
+          ? result.pathsTruncated === true || entry
+          : entry;
+    else if (key === "path" && safePath(entry)) result.path = entry;
+    else if (
+      (key === "expectedPaths" || key === "actualPaths") &&
+      Array.isArray(entry)
+    ) {
+      const paths = [...new Set(entry.filter(safePath))].sort(
+        compareCanonicalStrings,
+      );
+      result[key] = paths.slice(0, 32);
+      if (entry.some((path) => !safePath(path)) || paths.length > 32)
+        result.pathsTruncated = true;
+    }
+  }
+  const hint = HINTS.get(String(result.category)) ?? HINTS.get(record.code);
+  if (hint) result.hint = hint;
+  return result;
+}
+
+export interface DesignPlanDiagnostic {
+  code: string;
+  taskId?: string;
+  phase?: string;
+  field?: string;
+  category?: string;
+  owner?: string;
+  verificationId?: string;
+  outputId?: string;
+  dependencyTaskId?: string;
+  producerTaskId?: string;
+  producerPhase?: string;
+  path?: string;
+  expectedPaths?: string[];
+  actualPaths?: string[];
+}
+
+export class DesignPlanValidationError extends Error {
+  readonly diagnostics: readonly DesignPlanDiagnostic[];
+
+  constructor(message: string, diagnostics: readonly DesignPlanDiagnostic[]) {
+    const normalized = [
+      ...new Map(
+        diagnostics
+          .map((diagnostic) => structuredClone(diagnostic))
+          .sort((left, right) =>
+            compareCanonicalStrings(canonicalJson(left), canonicalJson(right)),
+          )
+          .map((diagnostic) => [canonicalJson(diagnostic), diagnostic]),
+      ).values(),
+    ];
+    super(message);
+    this.name = "DesignPlanValidationError";
+    this.diagnostics = Object.freeze(normalized);
+  }
+}