@abelxiaoxing/cadence 1.4.0 → 1.5.0

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);
+  }
+}

package/src/durable-contracts.ts

@@ -0,0 +1,213 @@
+import type { ArtifactStore } from "./artifact-store.ts";
+import type { StructuredVerificationContract } from "./contracts.ts";
+import type { ImplementPlan, PlanTaskDraft } from "./delivery-compiler.ts";
+import type { RoutePolicy, WorkerRoutePolicy } from "./route-policy.ts";
+
+import type { ResolvedStateRoot } from "./state-root.ts";
+import type { CandidateArtifactSubmission } from "./submit-tool.ts";
+import type { TaskLedger } from "./task-ledger.ts";
+
+import type {
+  DurableCandidateProposal,
+  DurableVerificationScope,
+  RedArtifactCorrection,
+  WorkflowAttemptOutcome,
+  WorkflowContextRequest,
+  WorkflowDeliverySource,
+  WorkflowRecoveryFeedback,
+} from "./workflow-policy.ts";
+
+import type { WorkspaceStore } from "./workspace-store.ts";
+
+export interface DurableResourceInput {
+  runId: string;
+  deliveryRevision: number;
+  plan?: ImplementPlan;
+  baselineRevisionId?: string;
+  currentWorkspaceRevisionId?: string;
+}
+
+export type DurablePhaseVerificationResult =
+  | {
+      ok: true;
+      exitCode: number;
+      classification: "expected-red" | "expected-green" | "expected-refactor";
+      diagnostic: { kind: "assertion" | "compiler"; id: string };
+    }
+  | {
+      ok: false;
+      kind: "paused" | "retryable" | "approval-needed";
+      code: string;
+    };
+
+export type DurableChangeVerificationResult =
+  | {
+      ok: true;
+      exitCode: 0;
+      classification: string;
+      failureIdentities?: string[];
+      attributionReliable?: boolean;
+    }
+  | {
+      ok: false;
+      kind:
+        | "artifact"
+        | "environment"
+        | "verification"
+        | "verification-adapter"
+        | "approval-boundary"
+        | "cancelled";
+      code: string;
+      failureIdentities?: string[];
+      attributionReliable?: boolean;
+    };
+
+export interface DurableVerificationObservation {
+  status: "passed" | "failed";
+  verificationId: string;
+  failureIdentities: string[];
+  code?: string;
+  attributionReliable?: boolean;
+}
+
+export interface DurableVerificationBaseline {
+  revisionId: string;
+  targetContracts: Array<{
+    taskId: string;
+    verificationId: string;
+    expectedFailure: string;
+  }>;
+  affected: Array<{
+    taskId: string;
+    observation: DurableVerificationObservation;
+  }>;
+  fullSuite: DurableVerificationObservation;
+}
+
+export type DurableObservedVerification =
+  | { ok: true; observation: DurableVerificationObservation }
+  | {
+      ok: false;
+      outcome:
+        | { kind: "paused"; code: string }
+        | { kind: "approval-needed"; code: string }
+        | { kind: "operation-cancelled"; code: "cancelled" };
+    };
+
+export type DurableBaselineResult =
+  | { ok: true; baseline: DurableVerificationBaseline }
+  | Extract<DurableObservedVerification, { ok: false }>;
+
+export type DurableAffectedResult =
+  | { kind: "verified"; attribution: "none" | "pre-existing" }
+  | {
+      kind: "repairable";
+      attribution: "introduced";
+      failureIdentities: string[];
+    }
+  | Extract<DurableObservedVerification, { ok: false }>["outcome"];
+
+export interface DurableWorkflowEngineOptions {
+  consumerRoot: string;
+  stateRoot: ResolvedStateRoot;
+  deliverySource: WorkflowDeliverySource;
+  routePolicy: RoutePolicy;
+  proposeCandidate(input: {
+    runId: string;
+    operationId: string;
+    deliveryRevision: number;
+    taskId: string;
+    phase: "red" | "green" | "refactor";
+    task: PlanTaskDraft;
+    workspaceRoot: string;
+    ledgerProjection: unknown;
+    candidateArtifact: CandidateArtifactSubmission;
+    route: WorkerRoutePolicy;
+    repair?: {
+      attempt: number;
+      attribution: "introduced";
+      failureIdentities: string[];
+    };
+    artifactCorrection?: RedArtifactCorrection;
+    contextRequest?: WorkflowContextRequest;
+    contextReadPaths?: string[];
+    recoveryFeedback?: WorkflowRecoveryFeedback;
+    signal: AbortSignal;
+    onRequestStart?(): void;
+    onHeaders(): void;
+    onProgress(): void;
+  }): Promise<DurableCandidateProposal>;
+  verifyPhase(input: {
+    executionWritePaths?: readonly string[];
+    runId: string;
+    deliveryRevision: number;
+    taskId: string;
+    phase: "red" | "green" | "refactor";
+    root: string;
+    verification: StructuredVerificationContract;
+    signal: AbortSignal;
+  }): Promise<DurablePhaseVerificationResult>;
+  verifyChange(input: {
+    runId: string;
+    deliveryRevision: number;
+    root: string;
+    plan: ImplementPlan;
+    scope?: DurableVerificationScope;
+    verification?: StructuredVerificationContract;
+    taskId?: string;
+    signal: AbortSignal;
+  }): Promise<DurableChangeVerificationResult>;
+  now?: () => number;
+  leaseTtlMs?: number;
+  workHardLimit?: number;
+  verificationPolicy?: string;
+  verificationEnvironment?(
+    plan: ImplementPlan,
+    signal: AbortSignal,
+  ): Promise<string>;
+}
+
+export interface DurableExecutionResources {
+  runId: string;
+  root: string;
+  plan: ImplementPlan;
+  deliveryRevision: number;
+  artifacts: ArtifactStore;
+  workspaces: WorkspaceStore;
+  ledgers: Map<number, TaskLedger>;
+  baselineRevisionId: string;
+  currentRevisionId: string;
+  mergeTail: Promise<void>;
+  verificationFact?: object;
+  baselinePromises: Map<number, Promise<DurableBaselineResult>>;
+  environmentIdentity?: string;
+}
+
+export interface DurablePhaseFact {
+  kind: "phase-verified" | "repair-verified";
+  phase: "red" | "green" | "refactor";
+  isolatedRevisionId: string;
+  outputFacts: Array<
+    | { path: string; kind: "absent" }
+    | { path: string; kind: "file"; hash: string; bytes: number }
+  >;
+}
+
+export interface DurableCandidateCommit {
+  artifactHash: string;
+  isolatedRevisionId: string;
+  exitCode: number;
+  classification: "expected-red" | "expected-green" | "expected-refactor";
+  diagnostic: { kind: "assertion" | "compiler"; id: string };
+  outputFacts: DurablePhaseFact["outputFacts"];
+  routeId: string;
+  routeFingerprint: string;
+}
+
+export type DurableRepairResult =
+  | { kind: "repair-committed"; commit: DurableCandidateCommit }
+  | Exclude<WorkflowAttemptOutcome, { kind: "phase-committed" }>;
+export type PhaseResources = Omit<
+  DurableExecutionResources,
+  "verificationFact"
+>;