@abelxiaoxing/cadence 1.3.0 → 1.4.0

package/src/change-contract.ts

@@ -0,0 +1,268 @@
+import {
+  type ImplementTaskBoundary,
+  isValidRelativePath,
+  type StructuredVerificationContract,
+  validateVerificationContract,
+  verificationInputPaths,
+} from "./contracts.ts";
+import { canonicalJson } from "./run-state.ts";
+
+export interface ChangeContract {
+  goal: string;
+  acceptance: Array<{
+    id: string;
+    statement: string;
+    verification: StructuredVerificationContract;
+  }>;
+  constraints: Array<{ id: string; statement: string }>;
+  policy: {
+    writeRoots: string[];
+    dependencies: string[];
+    verificationModes: Array<"behavior" | "mechanical" | "refactor">;
+  };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function keys(value: Record<string, unknown>, expected: string[]) {
+  return (
+    canonicalJson(Object.keys(value).sort()) === canonicalJson(expected.sort())
+  );
+}
+function text(value: unknown): value is string {
+  return (
+    typeof value === "string" && value.trim().length > 0 && value.length <= 8192
+  );
+}
+const identifier = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/u;
+
+export function normalizeChangeContract(value: unknown): ChangeContract {
+  if (
+    !record(value) ||
+    !keys(value, ["goal", "acceptance", "constraints", "policy"]) ||
+    !text(value.goal) ||
+    !Array.isArray(value.acceptance) ||
+    value.acceptance.length < 1 ||
+    value.acceptance.length > 256 ||
+    !Array.isArray(value.constraints) ||
+    value.constraints.length > 256 ||
+    !record(value.policy)
+  )
+    throw new Error("change-contract-invalid");
+  const entries = (values: unknown[], acceptance: boolean) =>
+    values
+      .map((entry) => {
+        if (
+          !record(entry) ||
+          !keys(
+            entry,
+            acceptance
+              ? ["id", "statement", "verification"]
+              : ["id", "statement"],
+          ) ||
+          typeof entry.id !== "string" ||
+          !identifier.test(entry.id) ||
+          !text(entry.statement)
+        )
+          throw new Error("change-contract-invalid");
+        const verification = acceptance
+          ? validateVerificationContract(entry.verification)
+          : undefined;
+        if (verification && !verification.ok)
+          throw new Error("change-contract-invalid");
+        return {
+          id: entry.id,
+          statement: entry.statement.replace(/\r\n?/gu, "\n").trim(),
+          ...(verification?.ok ? { verification: verification.value } : {}),
+        };
+      })
+      .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const acceptance = entries(value.acceptance, true);
+  const constraints = entries(value.constraints, false);
+  for (const group of [acceptance, constraints])
+    if (new Set(group.map((item) => item.id)).size !== group.length)
+      throw new Error("change-contract-invalid");
+  const policy = value.policy;
+  if (!keys(policy, ["writeRoots", "dependencies", "verificationModes"]))
+    throw new Error("change-contract-invalid");
+  for (const key of ["writeRoots", "dependencies", "verificationModes"])
+    if (
+      !Array.isArray(policy[key]) ||
+      policy[key].length > 256 ||
+      !policy[key].every(text) ||
+      new Set(policy[key]).size !== policy[key].length
+    )
+      throw new Error("change-contract-invalid");
+  const roots = policy.writeRoots as string[];
+  const modes = policy.verificationModes as string[];
+  if (
+    !roots.length ||
+    !roots.every((root) => root === "." || isValidRelativePath(root)) ||
+    !modes.length ||
+    !modes.every((mode) =>
+      ["behavior", "mechanical", "refactor"].includes(mode),
+    )
+  )
+    throw new Error("change-contract-invalid");
+  const result = {
+    goal: value.goal.replace(/\r\n?/gu, "\n").trim(),
+    acceptance,
+    constraints,
+    policy: {
+      writeRoots: [...roots].sort(),
+      dependencies: [...(policy.dependencies as string[])].sort(),
+      verificationModes: [...modes].sort(),
+    },
+  } as ChangeContract;
+  if (Buffer.byteLength(canonicalJson(result)) > 64 * 1024)
+    throw new Error("change-contract-invalid");
+  return result;
+}
+
+/** Display identities and fresh input bindings do not change a verification obligation. */
+export function verificationObligation(
+  value: StructuredVerificationContract,
+): string {
+  const strip = (item: unknown): unknown =>
+    Array.isArray(item)
+      ? item.map(strip)
+      : record(item)
+        ? Object.fromEntries(
+            Object.entries(item)
+              .filter(([key]) => !["id", "executionBindings"].includes(key))
+              .map(([key, child]) => [key, strip(child)]),
+          )
+        : item;
+  return canonicalJson(strip(value));
+}
+
+export function assertPlanWithinChangeContract(
+  contract: ChangeContract,
+  tasks: readonly (ImplementTaskBoundary & {
+    verificationMode?: string;
+    affectedVerification: StructuredVerificationContract;
+    repairVerification: StructuredVerificationContract;
+  })[],
+  verifications: readonly StructuredVerificationContract[],
+): void {
+  const available = new Set(
+    [
+      ...verifications,
+      ...tasks.flatMap((task) => [
+        task.affectedVerification,
+        ...Object.entries(task.phases)
+          .filter(
+            ([phase]) =>
+              phase !== "red" ||
+              !task.verificationMode ||
+              task.verificationMode === "behavior",
+          )
+          .map(([, phase]) => phase.verification),
+      ]),
+    ].map(verificationObligation),
+  );
+  for (const accepted of contract.acceptance)
+    if (!available.has(verificationObligation(accepted.verification)))
+      throw new Error("change-contract-acceptance-missing");
+  for (const task of tasks) {
+    if (
+      !contract.policy.verificationModes.includes(
+        (task.verificationMode ?? "behavior") as "behavior",
+      )
+    )
+      throw new Error("change-contract-verification-mode");
+    if (
+      task.approvedDependencies.some(
+        (name) => !contract.policy.dependencies.includes(name),
+      )
+    )
+      throw new Error("change-contract-dependency-outside-policy");
+    if (
+      task.agents &&
+      task.agents.impact !== "none" &&
+      !contract.policy.writeRoots.includes(task.agents.target ?? "")
+    )
+      throw new Error("change-contract-agents-outside-policy");
+    const mode = task.verificationMode ?? "behavior";
+    const writes = Object.entries(task.phases)
+      .filter(([phase]) => phase !== "red" || mode === "behavior")
+      .flatMap(([, phase]) => [...phase.write, ...phase.delete]);
+    if (
+      mode !== "behavior" &&
+      task.impactClosure?.changedSurfaces.some((surface) => surface !== "none")
+    )
+      throw new Error("change-contract-behavior-requires-red");
+    if (
+      mode === "mechanical" &&
+      writes.some((file) => !/\.(?:md|txt|json|ya?ml|toml|lock)$/iu.test(file))
+    )
+      throw new Error("change-contract-mechanical-path");
+    if (
+      mode === "refactor" &&
+      contract.acceptance.some((accepted) =>
+        verificationInputPaths(accepted.verification).some((file) =>
+          writes.includes(file),
+        ),
+      )
+    )
+      throw new Error("change-contract-refactor-verification-mutation");
+    for (const phase of Object.values(task.phases))
+      for (const file of [...phase.write, ...phase.delete])
+        if (
+          !contract.policy.writeRoots.some(
+            (root) =>
+              root === "." || file === root || file.startsWith(`${root}/`),
+          )
+        )
+          throw new Error("change-contract-write-outside-policy");
+  }
+}
+
+export function retainedChangeContract(plan: {
+  changeContract?: ChangeContract;
+  changeId: string;
+  tasks: readonly (ImplementTaskBoundary & {
+    affectedVerification: StructuredVerificationContract;
+  })[];
+  verification: {
+    change: {
+      fullSuite: StructuredVerificationContract;
+      postApply: StructuredVerificationContract;
+    };
+  };
+}): ChangeContract {
+  if (plan.changeContract) return normalizeChangeContract(plan.changeContract);
+  return normalizeChangeContract({
+    goal: plan.changeId,
+    acceptance: [
+      plan.verification.change.fullSuite,
+      plan.verification.change.postApply,
+      ...plan.tasks.map((task) => task.affectedVerification),
+    ].map((verification, index) => ({
+      id: `legacy-${index}`,
+      statement: "Retained verification obligation",
+      verification,
+    })),
+    constraints: [],
+    policy: {
+      writeRoots: [
+        ...new Set(
+          plan.tasks.flatMap((task) => [
+            ...(task.agents.impact !== "none" && task.agents.target
+              ? [task.agents.target]
+              : []),
+            ...Object.values(task.phases).flatMap((phase) => [
+              ...phase.write,
+              ...phase.delete,
+            ]),
+          ]),
+        ),
+      ],
+      dependencies: [
+        ...new Set(plan.tasks.flatMap((task) => task.approvedDependencies)),
+      ],
+      verificationModes: ["behavior"],
+    },
+  });
+}

package/src/child-session.ts

@@ -120,6 +120,7 @@ function wrapScopedTools(
 ) {
   const order = ["read", "grep", "find", "ls"];
   return createScopedTools({
+    cwd,
     roots,
     ...(allowedPaths
       ? {
@@ -162,9 +163,10 @@ function wrapScopedTools(
                 : Type.Object({
                     path: Type.Optional(Type.String()),
                   }),
-        async execute(_id, params) {
+        async execute(_id, params, signal) {
           const result = await scoped.execute(
             params as Record<string, unknown>,
+            signal,
           );
           return {
             content: [{ type: "text" as const, text: JSON.stringify(result) }],
@@ -625,8 +627,7 @@ export async function runChildSession(input: {
     }
     const failureKind: ChildFailureKind = timedOut
       ? "timed-out"
-      : input.signal !== undefined &&
-          (input.signal.aborted || abort.signal.reason === input.signal.reason)
+      : input.signal?.aborted === true
         ? "cancelled"
         : "failed";
     const classification = classifySession();

package/src/contracts.ts

@@ -150,6 +150,9 @@ export const VERIFICATION_ADAPTER_CODES = [
   "script-command-mismatch",
   "script-missing",
   "script-unsafe",
+  "report-arguments-conflict",
+  "verification-config-mismatch",
+  "verification-config-unsafe",
 ] as const;
 export const CHILD_TRANSPORT_CODES = [
   "child-no-final-assistant",
@@ -249,10 +252,35 @@ export type VerificationClassification =
   | "expected-green"
   | "expected-refactor";
 
+/** Runtime-owned evidence; unavailable checks never become product baselines. */
+export interface VerificationEvidence {
+  id: string;
+  exitCode: number;
+  classification: VerificationClassification;
+  tests?: number;
+  failureIdentities: string[];
+  policy: "report-file-v3";
+}
+export type VerificationObservation =
+  | { kind: "accepted"; evidence: VerificationEvidence }
+  | {
+      kind: "rejected";
+      code: "red-not-witnessed" | "verification-rejected";
+      evidence: VerificationEvidence;
+    }
+  | {
+      kind: "unavailable";
+      category: "environment" | "adapter" | "resource";
+      code: string;
+      verificationId: string;
+    }
+  | { kind: "cancelled" };
+
 interface VerificationBase {
   id: string;
   classification: VerificationClassification;
   expectedFailure?: string;
+  executionBindings?: Record<string, string | null>;
 }
 
 export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
@@ -338,6 +366,7 @@ export interface PhaseBoundary {
 }
 
 export interface TaskBoundary {
+  verificationMode?: "behavior" | "mechanical" | "refactor";
   changeId: string;
   taskId: string;
   dependsOn: string[];
@@ -512,7 +541,7 @@ function validScriptCommand(value: unknown): value is string {
     value.length > 0 &&
     value.length <= 1024 &&
     value.trim() === value &&
-    !UNSAFE_VERIFICATION_TOKEN.test(value)
+    !value.includes("\0")
   );
 }
 
@@ -575,6 +604,7 @@ function validateExecutableRunner(value: unknown): value is ExecutableRunner {
 
 function validateVitestRunner(value: ExecutableRunner): boolean {
   if (value.kind === "package-script") {
+    if (UNSAFE_VERIFICATION_TOKEN.test(value.command)) return false;
     const tokens = value.command.split(/\s+/u);
     return (
       tokens[0] === "vitest" ||
@@ -591,8 +621,23 @@ function validateAtomicVerification(
 ): value is AtomicVerificationContract {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const contract = value as Record<string, unknown>;
-  const expectedFailure =
-    contract.classification === "expected-red" ? ["expectedFailure"] : [];
+  if (
+    contract.executionBindings !== undefined &&
+    (!contract.executionBindings ||
+      typeof contract.executionBindings !== "object" ||
+      Array.isArray(contract.executionBindings) ||
+      Object.entries(contract.executionBindings).some(
+        ([key, hash]) =>
+          !VERIFICATION_CONFIGURATION_PATHS.includes(key) ||
+          (hash !== null &&
+            (typeof hash !== "string" || !/^[a-f0-9]{64}$/u.test(hash))),
+      ))
+  )
+    return false;
+  const expectedFailure = [
+    ...(contract.classification === "expected-red" ? ["expectedFailure"] : []),
+    ...(contract.executionBindings === undefined ? [] : ["executionBindings"]),
+  ];
   if (contract.kind === "vitest") {
     const executableRunner = contract.runner as ExecutableRunner;
     return (
@@ -719,6 +764,38 @@ export function verificationSteps(
     : [structuredClone(normalized.value)];
 }
 
+export const VERIFICATION_CONFIGURATION_PATHS: readonly string[] = [
+  "package.json",
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "bun.lock",
+  "bun.lockb",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  ".npmrc",
+  ".yarnrc",
+  ".yarnrc.yml",
+  "bunfig.toml",
+  "pnpm-workspace.yaml",
+];
+
+export function verificationBoundInputPaths(
+  verification: VerificationContract,
+): string[] {
+  return [
+    ...new Set([
+      ...verificationInputPaths(verification),
+      ...verificationSteps(verification).flatMap((step) =>
+        step.kind === "vitest" ||
+        step.kind === "package-script" ||
+        ("runner" in step && step.runner.kind === "package-script")
+          ? VERIFICATION_CONFIGURATION_PATHS
+          : [],
+      ),
+    ]),
+  ];
+}
+
 export function verificationInputPaths(
   verification: VerificationContract,
 ): string[] {
@@ -976,6 +1053,7 @@ function isWithinRoots(path: string, roots: string[]): boolean {
 function validatePhaseBoundary(
   value: unknown,
   phase: ImplementationPhase,
+  mode: unknown = "behavior",
 ): value is PhaseBoundary {
   if (
     !hasExactKeys(
@@ -1002,7 +1080,10 @@ function validatePhaseBoundary(
   const verification = validateVerificationContract(value.verification);
   if (!verification.ok) return false;
   const classification = {
-    red: "expected-red",
+    red:
+      mode !== undefined && mode !== "behavior"
+        ? "expected-green"
+        : "expected-red",
     green: "expected-green",
     refactor: "expected-refactor",
   } as const;
@@ -1014,19 +1095,27 @@ function validateTaskBoundary(
   snapshot: unknown,
 ): value is TaskBoundary {
   if (
-    !hasExactKeys(value, [
-      "changeId",
-      "taskId",
-      "dependsOn",
-      "objective",
-      "context",
-      "roots",
-      "phases",
-      "scheduling",
-      "agents",
-      "approvedDependencies",
-      "impactClosure",
-    ]) ||
+    !hasExactKeys(
+      value,
+      [
+        "changeId",
+        "taskId",
+        "dependsOn",
+        "objective",
+        "context",
+        "roots",
+        "phases",
+        "scheduling",
+        "agents",
+        "approvedDependencies",
+        "impactClosure",
+      ],
+      ["verificationMode"],
+    ) ||
+    (value.verificationMode !== undefined &&
+      !["behavior", "mechanical", "refactor"].includes(
+        String(value.verificationMode),
+      )) ||
     !validIdentifier(value.changeId) ||
     !validIdentifier(value.taskId) ||
     !validateIdentifierSet(value.dependsOn) ||
@@ -1038,7 +1127,7 @@ function validateTaskBoundary(
     typeof value.context.contract !== "string" ||
     !validateRoots(value.roots) ||
     !hasExactKeys(value.phases, ["red", "green"], ["refactor"]) ||
-    !validatePhaseBoundary(value.phases.red, "red") ||
+    !validatePhaseBoundary(value.phases.red, "red", value.verificationMode) ||
     !validatePhaseBoundary(value.phases.green, "green") ||
     (value.phases.refactor !== undefined &&
       !validatePhaseBoundary(value.phases.refactor, "refactor")) ||
@@ -1120,6 +1209,7 @@ export type ImplementGraphContractDiagnostic =
 function phaseBoundaryContractDiagnostic(
   value: unknown,
   phase: ImplementationPhase,
+  mode: unknown = "behavior",
 ): Omit<
   Extract<
     ImplementGraphContractDiagnostic,
@@ -1176,7 +1266,10 @@ function phaseBoundaryContractDiagnostic(
     };
   }
   const classification = {
-    red: "expected-red",
+    red:
+      mode !== undefined && mode !== "behavior"
+        ? "expected-green"
+        : "expected-red",
     green: "expected-green",
     refactor: "expected-refactor",
   } as const;
@@ -1227,22 +1320,33 @@ function taskBoundaryContractDiagnostic(
     category,
   });
   if (
-    !hasExactKeys(value, [
-      "changeId",
-      "taskId",
-      "dependsOn",
-      "objective",
-      "context",
-      "roots",
-      "phases",
-      "scheduling",
-      "agents",
-      "approvedDependencies",
-      "impactClosure",
-    ])
+    !hasExactKeys(
+      value,
+      [
+        "changeId",
+        "taskId",
+        "dependsOn",
+        "objective",
+        "context",
+        "roots",
+        "phases",
+        "scheduling",
+        "agents",
+        "approvedDependencies",
+        "impactClosure",
+      ],
+      ["verificationMode"],
+    )
   ) {
     return diagnostic("task", "shape");
   }
+  if (
+    value.verificationMode !== undefined &&
+    !["behavior", "mechanical", "refactor"].includes(
+      String(value.verificationMode),
+    )
+  )
+    return diagnostic("verificationMode", "shape");
   if (!validIdentifier(value.changeId)) {
     return diagnostic("changeId", "identifier");
   }
@@ -1275,7 +1379,11 @@ function taskBoundaryContractDiagnostic(
   for (const phase of IMPLEMENTATION_PHASES) {
     const boundary = value.phases[phase];
     if (phase === "refactor" && boundary === undefined) continue;
-    const phaseDiagnostic = phaseBoundaryContractDiagnostic(boundary, phase);
+    const phaseDiagnostic = phaseBoundaryContractDiagnostic(
+      boundary,
+      phase,
+      value.verificationMode,
+    );
     if (phaseDiagnostic)
       return { ...diagnostic("phases", "contract"), ...phaseDiagnostic };
   }

package/src/control-contracts.ts

@@ -13,6 +13,12 @@ export const CONTROL_COMMANDS = [
 
 export const CONTROL_STAGES = ["abel-implement"] as const;
 
+export interface RecoveryRequest {
+  incidentKey: string;
+  failureSequence: number;
+  reason: "parent-directed-retry" | "route-changed" | "context-extended";
+}
+
 const CONTROL_SCHEMA_PROPERTIES = {
   command: {
     type: "string",
@@ -24,6 +30,19 @@ const CONTROL_SCHEMA_PROPERTIES = {
   deliveryRevision: { type: "integer", minimum: 1 },
   receiptHash: { type: "string" },
   routeId: { type: "string" },
+  recovery: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      incidentKey: { type: "string", pattern: "^[a-f0-9]{64}$" },
+      failureSequence: { type: "integer", minimum: 1 },
+      reason: {
+        type: "string",
+        enum: ["parent-directed-retry", "route-changed", "context-extended"],
+      },
+    },
+    required: ["incidentKey", "failureSequence", "reason"],
+  },
 } as const;
 
 type ControlSchemaField = Exclude<
@@ -61,6 +80,15 @@ export const CONTROL_COMMAND_PARAMETERS = {
     commandSchema("start", ["stage", "change", "operationId"]),
     commandSchema("status", ["stage", "change"]),
     commandSchema("resume", ["stage", "change", "operationId"]),
+    commandSchema("resume", ["stage", "change", "operationId", "recovery"]),
+    commandSchema("resume", [
+      "stage",
+      "change",
+      "operationId",
+      "deliveryRevision",
+      "receiptHash",
+      "recovery",
+    ]),
     commandSchema("resume", [
       "stage",
       "change",
@@ -102,6 +130,7 @@ export interface ResumeControlCommand extends ControlBase {
   operationId: string;
   deliveryRevision?: number;
   receiptHash?: string;
+  recovery?: RecoveryRequest;
 }
 
 export interface RebindControlCommand extends ControlBase {
@@ -144,6 +173,7 @@ const CONTROL_TOOL_FIELDS = new Set([
   "deliveryRevision",
   "receiptHash",
   "routeId",
+  "recovery",
 ]);
 
 const COMMAND_FIELDS: Readonly<
@@ -158,6 +188,7 @@ const COMMAND_FIELDS: Readonly<
     "operationId",
     "deliveryRevision",
     "receiptHash",
+    "recovery",
   ]),
   rebind: new Set(["command", "stage", "change", "operationId", "routeId"]),
   cancel: new Set(["command", "stage", "change", "operationId"]),
@@ -282,13 +313,32 @@ export function validateControlCommand(
         !hasExactKeys(
           value,
           [...common, "operationId"],
-          ["deliveryRevision", "receiptHash"],
+          ["deliveryRevision", "receiptHash", "recovery"],
         ) ||
         !validChange(value.change) ||
         !validOperationId(value.operationId)
       ) {
         break;
       }
+      if (
+        value.recovery !== undefined &&
+        (!isRecord(value.recovery) ||
+          !hasExactKeys(value.recovery, [
+            "incidentKey",
+            "failureSequence",
+            "reason",
+          ]) ||
+          typeof value.recovery.incidentKey !== "string" ||
+          !SHA256.test(value.recovery.incidentKey) ||
+          !Number.isSafeInteger(value.recovery.failureSequence) ||
+          (value.recovery.failureSequence as number) < 1 ||
+          ![
+            "parent-directed-retry",
+            "route-changed",
+            "context-extended",
+          ].includes(String(value.recovery.reason)))
+      )
+        break;
       const hasRevision = value.deliveryRevision !== undefined;
       const hasReceipt = value.receiptHash !== undefined;
       if (hasRevision !== hasReceipt) break;