@abelxiaoxing/cadence 1.0.0 → 1.0.2

package/src/contracts.ts

@@ -21,6 +21,20 @@ export const PHASES = [
   "review",
 ] as const;
 
+export const RECOVERY_CODES = [
+  "mechanical-redispatch-exhausted",
+  "implementation-artifact-delivery-blocked",
+  "environment-blocked",
+  "design-required",
+] as const;
+
+export type RecoveryCode = (typeof RECOVERY_CODES)[number];
+export type RecoveryNext =
+  | "finish-unaffected"
+  | "correct-artifact"
+  | "repair-environment"
+  | "return-to-design";
+
 export const LIMITS = {
   maxActiveChildSessions: 4,
   maxRequestsPerBatch: 8,
@@ -30,10 +44,20 @@ export const LIMITS = {
 } as const;
 
 const NONCANONICAL = /(^|\/)\.\.(\/|$)|(^|\/)\/|^\//;
+const SNAPSHOT_SHA256 = /^[a-f0-9]{64}$/;
+
+export interface VerificationContract {
+  id: string;
+  argv: string[];
+  classification: "expected-red" | "expected-green" | "expected-refactor";
+  expectedFailure?: string;
+  minTests: number;
+}
 
 export interface RequestEnvelope {
   stage: string;
   role: string;
+  taskId?: string;
   id: string;
   phase: string;
   objective: string;
@@ -47,9 +71,23 @@ export interface RequestEnvelope {
     verificationLock?: string;
   };
   output: string;
+  verification?: VerificationContract;
   snapshot?: unknown;
 }
 
+export interface RecoveryRecord {
+  code: RecoveryCode;
+  taskId: string;
+  requestId: string;
+  phase: string;
+  launchIndex: 0 | 1;
+  branchBlocked: true;
+  dependentsBlocked: true;
+  partialResultUsable: false;
+  independentResultsPreserved: true;
+  next: RecoveryNext;
+}
+
 export function isValidRelativePath(p: unknown): p is string {
   return (
     typeof p === "string" &&
@@ -63,6 +101,115 @@ export function isValidRelativePath(p: unknown): p is string {
   );
 }
 
+export function validateVerificationContract(
+  value: unknown,
+): { ok: true; value: VerificationContract } | { ok: false; reason: string } {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return { ok: false, reason: "invalid verification contract" };
+  const contract = value as Record<string, unknown>;
+  if (
+    typeof contract.id !== "string" ||
+    contract.id.length === 0 ||
+    contract.id.length > 128 ||
+    !Array.isArray(contract.argv) ||
+    contract.argv.some(
+      (part) =>
+        typeof part !== "string" ||
+        part.length === 0 ||
+        /[;&|`$<>\n\r]/u.test(part) ||
+        part.includes("\0"),
+    ) ||
+    !["expected-red", "expected-green", "expected-refactor"].includes(
+      String(contract.classification),
+    ) ||
+    !Number.isSafeInteger(contract.minTests) ||
+    (contract.minTests as number) < 1
+  ) {
+    return { ok: false, reason: "invalid verification contract" };
+  }
+  const argv = contract.argv as string[];
+  const check =
+    argv.length === 3 &&
+    argv[0] === "bun" &&
+    argv[1] === "run" &&
+    argv[2] === "check";
+  const target =
+    argv.length >= 4 &&
+    argv[0] === "bun" &&
+    argv[1] === "run" &&
+    argv[2] === "test:target" &&
+    argv
+      .slice(3)
+      .every((part) => part.startsWith("test/") && isValidRelativePath(part));
+  if (!check && !target)
+    return { ok: false, reason: "verification argv is not approved" };
+  if (
+    contract.classification === "expected-red"
+      ? typeof contract.expectedFailure !== "string" ||
+        contract.expectedFailure.length === 0
+      : contract.expectedFailure !== undefined
+  ) {
+    return { ok: false, reason: "invalid expected failure identity" };
+  }
+  return { ok: true, value: contract as unknown as VerificationContract };
+}
+
+function validateImplementationSnapshot(
+  snapshot: unknown,
+  paths: string[],
+): string | null {
+  if (
+    snapshot === undefined ||
+    snapshot === null ||
+    typeof snapshot !== "object" ||
+    Array.isArray(snapshot)
+  ) {
+    return "invalid snapshot";
+  }
+  const bounds = snapshot as Record<string, unknown>;
+  for (const [path, value] of Object.entries(bounds)) {
+    if (
+      !isValidRelativePath(path) ||
+      value === null ||
+      typeof value !== "object" ||
+      Array.isArray(value)
+    ) {
+      return "invalid snapshot";
+    }
+    const entry = value as Record<string, unknown>;
+    if (entry.kind === "file") {
+      if (
+        typeof entry.sha256 !== "string" ||
+        !SNAPSHOT_SHA256.test(entry.sha256) ||
+        typeof entry.bytes !== "number" ||
+        !Number.isSafeInteger(entry.bytes) ||
+        entry.bytes < 0
+      ) {
+        return "invalid snapshot";
+      }
+    } else if (entry.kind === "dir") {
+      if (
+        typeof entry.manifest !== "string" ||
+        !SNAPSHOT_SHA256.test(entry.manifest)
+      ) {
+        return "invalid snapshot";
+      }
+    } else if (entry.kind === "absent") {
+      if (entry.absent !== true) return "invalid snapshot";
+    } else {
+      return "invalid snapshot";
+    }
+  }
+  if (
+    [...new Set(paths)].some(
+      (path) => !Object.prototype.hasOwnProperty.call(bounds, path),
+    )
+  ) {
+    return "snapshot does not cover declared paths";
+  }
+  return null;
+}
+
 export function validateRequestEnvelope(
   value: unknown,
 ): { ok: true; value: RequestEnvelope } | { ok: false; reason: string } {
@@ -98,6 +245,23 @@ export function validateRequestEnvelope(
   ) {
     return { ok: false, reason: "invalid request id" };
   }
+  if (
+    env.taskId !== undefined &&
+    (typeof env.taskId !== "string" ||
+      env.taskId.length === 0 ||
+      env.taskId.length > 128)
+  ) {
+    return { ok: false, reason: "invalid task id" };
+  }
+  // Implementation phases use a phase-local request id and carry their stable
+  // task identity explicitly. Other packets keep id as task id.
+  if (
+    env.stage === "abel-implement" &&
+    env.output === "diff" &&
+    env.taskId === undefined
+  ) {
+    return { ok: false, reason: "missing required field: taskId" };
+  }
   if (
     typeof env.phase !== "string" ||
     !(PHASES as readonly string[]).includes(env.phase)
@@ -155,6 +319,45 @@ export function validateRequestEnvelope(
   if (!(OUTPUT_KINDS as readonly string[]).includes(env.output as string)) {
     return { ok: false, reason: `invalid output kind: ${String(env.output)}` };
   }
+  if (env.verification !== undefined) {
+    const verification = validateVerificationContract(env.verification);
+    if (!verification.ok) {
+      return {
+        ok: false,
+        reason: verification.reason,
+      };
+    }
+  }
+  if (env.stage === "abel-implement" && env.output === "diff") {
+    if (env.verification === undefined) {
+      return { ok: false, reason: "missing required field: verification" };
+    }
+    const expectedClassification = {
+      red: "expected-red",
+      green: "expected-green",
+      refactor: "expected-refactor",
+    }[String(env.phase)];
+    if (
+      expectedClassification === undefined ||
+      (env.verification as VerificationContract).classification !==
+        expectedClassification
+    ) {
+      return {
+        ok: false,
+        reason:
+          "verification classification does not match implementation phase",
+      };
+    }
+  }
+  if (env.stage === "abel-implement" && env.output === "diff") {
+    const snapshotReason = validateImplementationSnapshot(env.snapshot, [
+      ...(decl.read as string[]),
+      ...(decl.write as string[]),
+    ]);
+    if (snapshotReason !== null) {
+      return { ok: false, reason: snapshotReason };
+    }
+  }
   if (
     env.snapshot !== undefined &&
     (env.snapshot === null || typeof env.snapshot !== "object")
@@ -172,68 +375,196 @@ export function diffWritePaths(diffText: string): {
   if (typeof diffText !== "string" || diffText.length === 0) {
     throw new Error("empty diff");
   }
-  if (/^GIT binary patch|^Binary files /.test(diffText)) {
-    throw new Error("binary diff is not supported");
-  }
-  const lines = diffText.split("\n");
-  if (lines.some((line) => /^copy (from|to) /.test(line))) {
-    throw new Error("copy records are not supported");
-  }
-  if (lines.some((line) => /^rename (from|to) /.test(line))) {
-    throw new Error("rename records are not supported");
-  }
-  const paths: string[] = [];
-  let sawHeader = false;
-  let pendingOld: string | null = null;
+  const hasFinalLf = diffText.endsWith("\n");
+  const lines = (hasFinalLf ? diffText.slice(0, -1) : diffText).split("\n");
+
   for (const line of lines) {
-    if (/^old mode /.test(line) || /^new mode /.test(line)) {
+    if (/^(?:GIT binary patch|Binary files )/.test(line)) {
+      throw new Error("binary diff is not supported");
+    }
+    if (/^(?:copy|rename) (?:from|to) /.test(line)) {
+      throw new Error(`${line.split(" ", 1)[0]} records are not supported`);
+    }
+    if (/^(?:old|new) mode /.test(line)) {
       throw new Error("mode transitions are not supported");
     }
-    if (/^(new|deleted) file mode /.test(line)) {
-      const mode = line.split(" ").pop();
-      if (mode === "160000") {
-        throw new Error("submodule mode is not supported");
-      }
-      if (mode !== "100644" && mode !== "100755") {
-        throw new Error(`non-regular file mode is not supported: ${mode}`);
+    const mode = /^(?:new file mode|deleted file mode) (.+)$/.exec(line);
+    if (mode) requireRegularFileMode(mode[1]);
+  }
+
+  const paths: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (!isFileSectionStart(lines[i])) {
+      if (paths.length === 0) {
+        throw new Error("diff has no ordinary text headers");
       }
-      continue;
+      throw new Error(`unconsumed diff content: ${lines[i]}`);
     }
-    if (line.startsWith("--- ") && !line.startsWith("--- /dev/null")) {
-      pendingOld = parseHeaderPath(line.slice(4));
-      continue;
+
+    let gitTarget: string | null = null;
+    if (lines[i].startsWith("diff --git ")) {
+      gitTarget = parseGitTarget(lines[i]);
+      i++;
     }
-    if (line.startsWith("+++ ")) {
-      const newPath = parseHeaderPath(line.slice(4));
-      let target: string;
-      if (newPath === null) {
-        if (pendingOld === null) {
-          throw new Error("diff header pair is malformed");
-        }
-        target = pendingOld;
-      } else {
-        target = newPath;
-        if (pendingOld !== null && pendingOld !== newPath) {
-          throw new Error("mismatched old/new diff targets");
+
+    let operation: "add" | "delete" | null = null;
+    const mode = /^(new file mode|deleted file mode) (.+)$/.exec(
+      lines[i] ?? "",
+    );
+    if (mode) {
+      operation = mode[1] === "new file mode" ? "add" : "delete";
+      i++;
+    }
+    if (lines[i]?.startsWith("index ")) {
+      parseIndexMetadata(lines[i]);
+      i++;
+    }
+
+    if (!lines[i]?.startsWith("--- ")) {
+      throw new Error("file section is missing an ordinary --- header");
+    }
+    const oldPath = parseHeaderPath(lines[i].slice(4), "a");
+    i++;
+    if (!lines[i]?.startsWith("+++ ")) {
+      throw new Error("diff header pair is malformed");
+    }
+    const newPath = parseHeaderPath(lines[i].slice(4), "b");
+    i++;
+
+    if (oldPath === null && newPath === null) {
+      throw new Error("diff header pair has no target");
+    }
+    if (oldPath !== null && newPath !== null && oldPath !== newPath) {
+      throw new Error("mismatched old/new diff targets");
+    }
+    const target = oldPath ?? newPath;
+    if (target === null) throw new Error("diff header pair has no target");
+    if (gitTarget !== null && gitTarget !== target) {
+      throw new Error("mismatched diff --git and text targets");
+    }
+    if (
+      (operation === "add" && oldPath !== null) ||
+      (operation === "delete" && newPath !== null)
+    ) {
+      throw new Error("create/delete metadata does not match text headers");
+    }
+    if (paths.includes(target)) throw new Error("duplicate diff targets");
+    paths.push(target);
+
+    let sawHunk = false;
+    while (lines[i]?.startsWith("@@")) {
+      const hunk = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?: .*)?$/.exec(
+        lines[i],
+      );
+      if (!hunk) throw new Error(`invalid hunk header: ${lines[i]}`);
+      const range = [
+        Number(hunk[1]),
+        Number(hunk[2] ?? "1"),
+        Number(hunk[3]),
+        Number(hunk[4] ?? "1"),
+      ];
+      if (!range.every(Number.isSafeInteger)) {
+        throw new Error("hunk range exceeds supported integer bounds");
+      }
+      let oldRemaining = range[1];
+      let newRemaining = range[3];
+      sawHunk = true;
+      i++;
+
+      while (oldRemaining > 0 || newRemaining > 0) {
+        if (i >= lines.length) throw new Error("hunk body underflow");
+        const body = lines[i];
+        switch (body[0]) {
+          case " ":
+            if (oldRemaining === 0 || newRemaining === 0) {
+              throw new Error("hunk body overflow");
+            }
+            oldRemaining--;
+            newRemaining--;
+            break;
+          case "-":
+            if (oldRemaining === 0) throw new Error("hunk body overflow");
+            oldRemaining--;
+            break;
+          case "+":
+            if (newRemaining === 0) throw new Error("hunk body overflow");
+            newRemaining--;
+            break;
+          default:
+            throw new Error("hunk body underflow");
         }
+        i++;
+        if (lines[i] === "\") i++;
       }
-      pendingOld = null;
-      if (paths.includes(target)) throw new Error("duplicate diff targets");
-      paths.push(target);
-      sawHeader = true;
+    }
+    if (!sawHunk) {
+      throw new Error("file section has no valid unified-diff hunk");
     }
   }
-  if (!sawHeader || paths.length === 0) {
-    throw new Error("diff has no ordinary text headers");
-  }
+
+  if (!hasFinalLf) throw new Error("diff must end with LF");
   return { paths, kind: "text" };
 }
 
-function parseHeaderPath(header: string): string | null {
+function isFileSectionStart(line: string | undefined): boolean {
+  return (
+    line?.startsWith("diff --git ") === true ||
+    line?.startsWith("new file mode ") === true ||
+    line?.startsWith("deleted file mode ") === true ||
+    line?.startsWith("index ") === true ||
+    line?.startsWith("--- ") === true
+  );
+}
+
+function parseGitTarget(line: string): string {
+  const prefix = "diff --git a/";
+  if (!line.startsWith(prefix)) throw new Error("malformed diff --git header");
+  const rest = line.slice(prefix.length);
+  for (
+    let separator = rest.indexOf(" b/");
+    separator >= 0;
+    separator = rest.indexOf(" b/", separator + 1)
+  ) {
+    const oldPath = rest.slice(0, separator);
+    const newPath = rest.slice(separator + 3);
+    if (oldPath === newPath) return requireCanonicalDiffPath(oldPath);
+  }
+  throw new Error("mismatched diff --git targets");
+}
+
+function parseIndexMetadata(line: string): void {
+  const index = /^index [0-9a-f]+\.\.[0-9a-f]+(?: ([0-7]{6}))?$/.exec(line);
+  if (!index) throw new Error("malformed index metadata");
+  if (index[1]) requireRegularFileMode(index[1]);
+}
+
+function requireRegularFileMode(mode: string): void {
+  if (mode === "160000") {
+    throw new Error("submodule mode is not supported: 160000");
+  }
+  if (mode !== "100644" && mode !== "100755") {
+    throw new Error(`non-regular file mode is not supported: ${mode}`);
+  }
+}
+
+function parseHeaderPath(header: string, prefix: "a" | "b"): string | null {
   if (header === "/dev/null") return null;
-  const path = header.replace(/^\s*(a|b)\//, "");
-  if (!isValidRelativePath(path)) {
-    throw new Error(`noncanonical or escaping diff path: ${header}`);
+  const other = prefix === "a" ? "b" : "a";
+  if (header.startsWith(`${other}/`)) {
+    throw new Error("mismatched old/new diff header prefixes");
+  }
+  const path = header.startsWith(`${prefix}/`) ? header.slice(2) : header;
+  return requireCanonicalDiffPath(path);
+}
+
+function requireCanonicalDiffPath(path: string): string {
+  if (
+    !isValidRelativePath(path) ||
+    path.trim() !== path ||
+    /[\r\n\t]/.test(path)
+  ) {
+    throw new Error(`noncanonical or escaping diff path: ${path}`);
   }
   return path;
 }

package/src/file-snapshot.ts

@@ -1,10 +1,17 @@
 // File-level snapshots: content hashes for observed files, deterministic
-// directory-entry manifests for observed directories, and explicit absent
+// recursive content manifests for observed directories, and explicit absent
 // markers for proposed new paths. Currency is decided per bound path; no
 // global workspace revision participates.
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  statSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
 
 export interface FileBound {
   kind: "file";
@@ -37,7 +44,57 @@ export function snapshotFile(root: string, relPath: string): FileBound | null {
   return { sha256: sha256(bytes), bytes: bytes.length, kind: "file" };
 }
 
-/** Deterministic directory-entry manifest: hash of sorted name/type entries. */
+function updateManifest(
+  hash: ReturnType<typeof createHash>,
+  ...fields: Array<string | Buffer>
+): void {
+  for (const field of fields) {
+    const bytes = typeof field === "string" ? Buffer.from(field) : field;
+    hash.update(`${bytes.length}:`);
+    hash.update(bytes);
+  }
+}
+
+function recursiveDirectoryManifest(abs: string): string {
+  const hash = createHash("sha256");
+  updateManifest(hash, "cadence-directory-manifest-v2");
+  const visit = (directory: string, prefix: string): void => {
+    const names = readdirSync(directory).sort();
+    for (const name of names) {
+      const relative = prefix ? `${prefix}/${name}` : name;
+      const current = join(directory, name);
+      const stat = lstatSync(current);
+      if (stat.isDirectory()) {
+        updateManifest(hash, "dir", relative, String(stat.mode & 0o777));
+        visit(current, relative);
+      } else if (stat.isFile()) {
+        const bytes = readFileSync(current);
+        updateManifest(
+          hash,
+          "file",
+          relative,
+          String(stat.mode & 0o777),
+          String(bytes.length),
+          sha256(bytes),
+        );
+      } else if (stat.isSymbolicLink()) {
+        updateManifest(hash, "symlink", relative, readlinkSync(current));
+      } else {
+        updateManifest(
+          hash,
+          "special",
+          relative,
+          String(stat.mode),
+          String(stat.size),
+        );
+      }
+    }
+  };
+  visit(abs, "");
+  return hash.digest("hex");
+}
+
+/** Deterministic recursive directory manifest bound to installed content. */
 export function snapshotDirManifest(
   root: string,
   relDir: string,
@@ -45,10 +102,7 @@ export function snapshotDirManifest(
   const abs = resolve(root, relDir);
   const st = statSync(abs, { throwIfNoEntry: false });
   if (!st?.isDirectory()) return null;
-  const entries = readdirSync(abs, { withFileTypes: true })
-    .map((e) => `${e.name}:${e.isDirectory() ? "dir" : "file"}`)
-    .sort();
-  return { manifest: sha256(Buffer.from(entries.join("\n"))), kind: "dir" };
+  return { manifest: recursiveDirectoryManifest(abs), kind: "dir" };
 }
 
 /** Build a bound map for the given file paths, observed directories, and absent markers. */