@abelxiaoxing/cadence 1.0.2 → 1.0.4

package/src/patch.ts

@@ -1,7 +1,23 @@
 import { spawn } from "node:child_process";
+import {
+  copyFileSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { preflightCandidate } from "./candidate-preflight.ts";
-import { diffWritePaths } from "./contracts.ts";
-import { isCurrent } from "./file-snapshot.ts";
+import {
+  type AgentsCheckpointRequest,
+  type ApplyCandidateResult,
+  type CandidateFailure,
+  diffWritePaths,
+  validateAgentsCheckpointRequest,
+} from "./contracts.ts";
+import { type Bound, isCurrent } from "./file-snapshot.ts";
 import type { ResultStore } from "./result-store.ts";
 
 interface CommandResult {
@@ -58,8 +74,223 @@ async function git(
   });
 }
 
-function cancellationFailure(): { ok: false; error: string } {
-  return { ok: false, error: "candidate application cancelled" };
+function failure(value: CandidateFailure): {
+  ok: false;
+  failure: CandidateFailure;
+} {
+  return { ok: false, failure: value };
+}
+
+function cancellationFailure(): {
+  ok: false;
+  failure: CandidateFailure;
+} {
+  return failure({ kind: "cancelled", code: "cancelled" });
+}
+
+type AgentsCheckpointResult =
+  | {
+      ok: true;
+      target: string;
+      agentsImpact: AgentsCheckpointRequest["agentsImpact"];
+      checkExitCode: 0;
+      applyExitCode: 0;
+    }
+  | {
+      ok: false;
+      failure: CandidateFailure;
+    };
+
+const AGENTS_START = "<!-- ABEL:AGENTS-INDEX:START -->";
+const AGENTS_END = "<!-- ABEL:AGENTS-INDEX:END -->";
+const NONREGULAR_AGENTS_TARGET = Symbol("nonregular AGENTS target");
+
+function managedParts(text: string): { prefix: string; suffix: string } | null {
+  const lines = text.split("\n");
+  const starts: Array<{ line: number; start: number; end: number }> = [];
+  const ends: Array<{ line: number; start: number; end: number }> = [];
+  let offset = 0;
+  for (const [line, value] of lines.entries()) {
+    const range = { line, start: offset, end: offset + value.length };
+    if (value === AGENTS_START) starts.push(range);
+    if (value === AGENTS_END) ends.push(range);
+    offset = range.end + 1;
+  }
+  if (
+    starts.length !== 1 ||
+    ends.length !== 1 ||
+    starts[0].line >= ends[0].line
+  ) {
+    return null;
+  }
+  return {
+    prefix: text.slice(0, starts[0].start),
+    suffix: text.slice(ends[0].end),
+  };
+}
+
+function checkpointContentIsScoped(
+  impact: AgentsCheckpointRequest["agentsImpact"],
+  before: string | null,
+  after: string | null,
+): boolean {
+  const beforeParts = before === null ? null : managedParts(before);
+  const afterParts = after === null ? null : managedParts(after);
+  if (impact === "update-existing") {
+    return (
+      beforeParts !== null &&
+      afterParts !== null &&
+      beforeParts.prefix === afterParts.prefix &&
+      beforeParts.suffix === afterParts.suffix
+    );
+  }
+  if (impact === "create-index") {
+    return (
+      before === null &&
+      afterParts !== null &&
+      afterParts.prefix.trim() === "" &&
+      afterParts.suffix.trim() === ""
+    );
+  }
+  if (beforeParts === null) return false;
+  if (after === null) {
+    return beforeParts.prefix.trim() === "" && beforeParts.suffix.trim() === "";
+  }
+  return (
+    managedParts(after) === null &&
+    after === `${beforeParts.prefix}${beforeParts.suffix}`
+  );
+}
+
+function regularText(
+  root: string,
+  target: string,
+): string | null | typeof NONREGULAR_AGENTS_TARGET {
+  const resolvedRoot = path.resolve(root);
+  const absolute = path.resolve(resolvedRoot, target);
+  if (
+    absolute === resolvedRoot ||
+    !absolute.startsWith(`${resolvedRoot}${path.sep}`)
+  ) {
+    throw new Error("AGENTS target escapes the root");
+  }
+  const stat = lstatSync(absolute, { throwIfNoEntry: false });
+  if (!stat) return null;
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    return NONREGULAR_AGENTS_TARGET;
+  }
+  return readFileSync(absolute, "utf8");
+}
+
+export async function applyAgentsCheckpoint(
+  root: string,
+  value: unknown,
+  signal?: AbortSignal,
+): Promise<AgentsCheckpointResult> {
+  const validation = validateAgentsCheckpointRequest(value);
+  if (!validation.ok) {
+    return failure({ kind: "artifact", code: "invalid-checkpoint-contract" });
+  }
+  const request = validation.value;
+  if (signal?.aborted) {
+    return cancellationFailure();
+  }
+  const before = regularText(root, request.agentsTarget);
+  if (before === NONREGULAR_AGENTS_TARGET) {
+    return failure({ kind: "artifact", code: "nonregular-mode" });
+  }
+  if (!isCurrent(root, request.snapshot as Bound)) {
+    return failure({ kind: "stale", code: "stale-snapshot" });
+  }
+  let targets: string[];
+  try {
+    targets = diffWritePaths(request.diff).paths;
+  } catch {
+    return failure({ kind: "artifact", code: "invalid-diff" });
+  }
+  if (targets.length !== 1 || targets[0] !== request.agentsTarget) {
+    return failure({ kind: "artifact", code: "agents-target-mismatch" });
+  }
+
+  let temp: string | undefined;
+  try {
+    if (
+      (request.agentsImpact === "create-index" && before !== null) ||
+      (request.agentsImpact !== "create-index" && before === null)
+    ) {
+      return failure({ kind: "artifact", code: "agents-impact-mismatch" });
+    }
+    temp = mkdtempSync(path.join(tmpdir(), "cadence-agents-checkpoint-"));
+    if (before !== null) {
+      const temporaryTarget = path.join(temp, request.agentsTarget);
+      mkdirSync(path.dirname(temporaryTarget), { recursive: true });
+      copyFileSync(path.join(root, request.agentsTarget), temporaryTarget);
+    }
+    const bytes = Buffer.from(request.diff, "utf8");
+    const candidateCheck = await git(
+      temp,
+      ["apply", "--check", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (candidateCheck.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (candidateCheck.code !== 0) {
+      return failure({ kind: "artifact", code: "git-apply-check-failed" });
+    }
+    const candidateApply = await git(
+      temp,
+      ["apply", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (candidateApply.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (candidateApply.code !== 0) {
+      return failure({ kind: "artifact", code: "git-apply-failed" });
+    }
+    const after = regularText(temp, request.agentsTarget);
+    if (after === NONREGULAR_AGENTS_TARGET) {
+      return failure({ kind: "artifact", code: "nonregular-mode" });
+    }
+    if (!checkpointContentIsScoped(request.agentsImpact, before, after)) {
+      return failure({ kind: "artifact", code: "outside-managed-region" });
+    }
+    if (!isCurrent(root, request.snapshot as Bound)) {
+      return failure({ kind: "stale", code: "stale-snapshot" });
+    }
+    const check = await git(
+      root,
+      ["apply", "--check", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (check.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (check.code !== 0) {
+      return failure({ kind: "stale", code: "git-apply-check-failed" });
+    }
+    const apply = await git(
+      root,
+      ["apply", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+    );
+    if (apply.code !== 0) {
+      return failure({ kind: "environment", code: "git-apply-failed" });
+    }
+    return {
+      ok: true,
+      target: request.agentsTarget,
+      agentsImpact: request.agentsImpact,
+      checkExitCode: 0,
+      applyExitCode: 0,
+    };
+  } finally {
+    if (temp) rmSync(temp, { recursive: true, force: true });
+  }
 }
 
 export async function applyRetainedPatch(input: {
@@ -67,29 +298,22 @@ export async function applyRetainedPatch(input: {
   id: string;
   store: ResultStore;
   signal?: AbortSignal;
-}): Promise<
-  | { ok: true; targets: string[]; checkExitCode: 0; applyExitCode: 0 }
-  | { ok: false; error: string }
-> {
+}): Promise<ApplyCandidateResult> {
   if (input.signal?.aborted) return cancellationFailure();
-  const retained = input.store.get(input.id);
-  if (!retained) return { ok: false, error: "retained result not found" };
+  const retained = input.store.resolveForApply(input.id);
   if (retained.root !== input.root)
-    return { ok: false, error: "retained result root mismatch" };
+    throw new Error("retained result root mismatch");
   if (!retained.verification && !isCurrent(input.root, retained.snapshot))
-    return { ok: false, error: "stale file snapshot" };
+    return failure({ kind: "stale", code: "stale-snapshot" });
 
   let targets: string[];
   try {
     targets = diffWritePaths(retained.diff.toString("utf8")).paths;
-  } catch (error) {
-    return { ok: false, error: (error as Error).message };
+  } catch {
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   if (targets.some((path) => !retained.writeSet.includes(path))) {
-    return {
-      ok: false,
-      error: "patch target is outside the declared write set",
-    };
+    return failure({ kind: "artifact", code: "write-set-mismatch" });
   }
 
   if (retained.verification) {
@@ -98,15 +322,13 @@ export async function applyRetainedPatch(input: {
       !retained.lockfile ||
       !retained.dependencyTarget
     ) {
-      return {
-        ok: false,
-        error: "retained candidate preflight inputs are incomplete",
-      };
+      throw new Error("retained candidate preflight inputs are incomplete");
     }
     const preflight = await preflightCandidate({
       root: input.root,
       diff: retained.diff,
       writeSet: retained.writeSet,
+      approvedDependencies: retained.approvedDependencies,
       snapshot: retained.snapshot,
       baseline: retained.baseline,
       verification: retained.verification,
@@ -116,13 +338,25 @@ export async function applyRetainedPatch(input: {
       signal: input.signal,
     });
     if (!preflight.ok) {
-      return {
-        ok: false,
-        error: `candidate preflight rejected: ${preflight.class}:${preflight.code}`,
-      };
+      switch (preflight.kind) {
+        case "artifact":
+          return failure({
+            kind: preflight.kind,
+            code: preflight.code,
+            ...(preflight.excerpt ? { evidence: [preflight.excerpt] } : {}),
+          });
+        case "stale":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "environment":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "approval-boundary":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "cancelled":
+          return failure({ kind: preflight.kind, code: preflight.code });
+      }
     }
     if (!isCurrent(input.root, retained.snapshot)) {
-      return { ok: false, error: "stale file snapshot after preflight" };
+      return failure({ kind: "stale", code: "stale-snapshot" });
     }
   }
   if (input.signal?.aborted) return cancellationFailure();
@@ -135,10 +369,7 @@ export async function applyRetainedPatch(input: {
   );
   if (numstat.cancelled || input.signal?.aborted) return cancellationFailure();
   if (numstat.code !== 0 || numstat.stdout.includes(Buffer.from("-\t-\t"))) {
-    return {
-      ok: false,
-      error: `git numstat screening failed: ${numstat.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   const summary = await git(
     input.root,
@@ -153,7 +384,7 @@ export async function applyRetainedPatch(input: {
       summary.stdout.toString("utf8"),
     )
   ) {
-    return { ok: false, error: "git summary screening rejected the patch" };
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   const check = await git(
     input.root,
@@ -163,10 +394,7 @@ export async function applyRetainedPatch(input: {
   );
   if (check.cancelled || input.signal?.aborted) return cancellationFailure();
   if (check.code !== 0)
-    return {
-      ok: false,
-      error: `git apply --check failed: ${check.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "artifact", code: "git-apply-check-failed" });
   if (input.signal?.aborted) return cancellationFailure();
   const apply = await git(
     input.root,
@@ -174,10 +402,10 @@ export async function applyRetainedPatch(input: {
     retained.diff,
   );
   if (apply.code !== 0)
-    return {
-      ok: false,
-      error: `git apply failed: ${apply.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "environment", code: "git-apply-failed" });
   input.store.discard(input.id);
-  return { ok: true, targets, checkExitCode: 0, applyExitCode: 0 };
+  return {
+    ok: true,
+    result: { targets, checkExitCode: 0, applyExitCode: 0 },
+  };
 }

package/src/result-store.ts

@@ -1,15 +1,42 @@
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import type {
   BaselineEntry,
   VerificationContract,
 } from "./candidate-preflight.ts";
+import type { ImplementationPhase } from "./contracts.ts";
 import type { Bound, DirBound, FileBound } from "./file-snapshot.ts";
 import { snapshotFiles } from "./file-snapshot.ts";
 
+export interface RetainedCandidateIdentity {
+  stage: "abel-implement";
+  canonicalRoot: string;
+  root: string;
+  changeId: string;
+  taskId: string;
+  originRequestId: string;
+  phase: ImplementationPhase;
+  launchIndex: 0 | 1;
+}
+
+export interface RetainedCandidateFacts extends RetainedCandidateIdentity {
+  writeSet: string[];
+  approvedDependencies: string[];
+  snapshot: Bound;
+}
+
 export interface RetainedResult {
   id: string;
   diff: Buffer;
+  stage?: RetainedCandidateIdentity["stage"];
+  canonicalRoot?: string;
+  changeId?: string;
+  taskId?: string;
+  originRequestId?: string;
+  phase?: ImplementationPhase;
+  launchIndex?: 0 | 1;
   writeSet: string[];
+  approvedDependencies: string[];
   root: string;
   snapshot: Bound;
   baseline: BaselineEntry[];
@@ -19,27 +46,103 @@ export interface RetainedResult {
   dependencyTarget?: FileBound | DirBound;
 }
 
+export type BoundRetainedResult = RetainedResult & RetainedCandidateIdentity;
+
+interface RetainCandidateData {
+  diff: string;
+  writeSet: string[];
+  approvedDependencies?: string[];
+  root: string;
+  snapshot?: Bound;
+  baseline?: BaselineEntry[];
+  verification?: VerificationContract;
+  packageManifest?: FileBound;
+  lockfile?: FileBound;
+  dependencyTarget?: FileBound | DirBound;
+}
+
+type RetainInput = RetainCandidateData & Partial<RetainedCandidateIdentity>;
+
+const IDENTITY_KEYS = [
+  "stage",
+  "canonicalRoot",
+  "changeId",
+  "taskId",
+  "originRequestId",
+  "phase",
+  "launchIndex",
+] as const;
+
+function hasCompleteIdentity(
+  value: RetainedResult | RetainInput,
+): value is (RetainedResult | RetainInput) & RetainedCandidateIdentity {
+  return IDENTITY_KEYS.every((key) => value[key] !== undefined);
+}
+
+function hasAnyIdentity(value: RetainedResult | RetainInput): boolean {
+  return IDENTITY_KEYS.some((key) => value[key] !== undefined);
+}
+
+function cloneIdentity(identity: RetainedCandidateIdentity) {
+  return {
+    stage: identity.stage,
+    canonicalRoot: identity.canonicalRoot,
+    changeId: identity.changeId,
+    taskId: identity.taskId,
+    originRequestId: identity.originRequestId,
+    phase: identity.phase,
+    launchIndex: identity.launchIndex,
+  };
+}
+
+function cloneRetained(retained: RetainedResult): RetainedResult {
+  const clone: RetainedResult = {
+    ...retained,
+    diff: Buffer.from(retained.diff),
+    writeSet: [...retained.writeSet],
+    approvedDependencies: [...retained.approvedDependencies],
+    snapshot: structuredClone(retained.snapshot),
+    baseline: retained.baseline.map((entry) => ({ ...entry })),
+  };
+  if (retained.verification) {
+    clone.verification = {
+      ...retained.verification,
+      argv: [...retained.verification.argv],
+    };
+  }
+  if (retained.packageManifest) {
+    clone.packageManifest = { ...retained.packageManifest };
+  }
+  if (retained.lockfile) clone.lockfile = { ...retained.lockfile };
+  if (retained.dependencyTarget) {
+    clone.dependencyTarget = { ...retained.dependencyTarget };
+  }
+  return clone;
+}
+
 export class ResultStore {
   private readonly results = new Map<string, RetainedResult>();
+  private readonly sealedResults = new Map<string, RetainedResult>();
+  private readonly sealedCandidateFacts = new Map<
+    string,
+    RetainedCandidateFacts
+  >();
 
-  retain(input: {
-    diff: string;
-    writeSet: string[];
-    root: string;
-    snapshot?: Bound;
-    baseline?: BaselineEntry[];
-    verification?: VerificationContract;
-    packageManifest?: FileBound;
-    lockfile?: FileBound;
-    dependencyTarget?: FileBound | DirBound;
-  }): string {
+  retain(input: RetainInput): string {
+    if (hasAnyIdentity(input) && !hasCompleteIdentity(input)) {
+      throw new Error("retained candidate identity is incomplete");
+    }
     const id = randomUUID();
-    this.results.set(id, {
+    const retained: RetainedResult = {
       id,
       diff: Buffer.from(input.diff, "utf8"),
-      writeSet: [...new Set(input.writeSet)],
+      ...(hasCompleteIdentity(input) ? cloneIdentity(input) : {}),
+      writeSet: [...input.writeSet],
+      approvedDependencies: [...(input.approvedDependencies ?? [])],
       root: input.root,
-      snapshot: input.snapshot ?? snapshotFiles(input.root, input.writeSet),
+      snapshot: structuredClone(
+        input.snapshot ?? snapshotFiles(input.root, input.writeSet),
+      ),
       baseline: (input.baseline ?? []).map((entry) => ({ ...entry })),
       ...(input.verification === undefined
         ? {}
@@ -58,18 +161,153 @@ export class ResultStore {
       ...(input.dependencyTarget === undefined
         ? {}
         : { dependencyTarget: { ...input.dependencyTarget } }),
-    });
+    };
+    this.results.set(id, retained);
+    this.sealedResults.set(id, cloneRetained(retained));
+    if (hasCompleteIdentity(retained)) {
+      this.sealedCandidateFacts.set(id, this.cloneFacts(retained));
+    }
     return id;
   }
 
   get(id: string): RetainedResult | undefined {
-    return this.results.get(id);
+    const retained = this.results.get(id);
+    return retained ? cloneRetained(retained) : undefined;
+  }
+
+  hasCandidateIdentity(id: string): boolean {
+    const retained = this.results.get(id);
+    if (!retained) return false;
+    this.assertIntegrity(id, retained);
+    return hasAnyIdentity(retained);
+  }
+
+  bindIdentity(
+    id: string,
+    identity: RetainedCandidateIdentity,
+  ): BoundRetainedResult {
+    const retained = this.results.get(id);
+    if (!retained) throw new Error("retained result not found");
+    this.assertIntegrity(id, retained);
+    if (hasAnyIdentity(retained)) {
+      if (
+        !hasCompleteIdentity(retained) ||
+        !this.matchesIdentity(retained, identity)
+      ) {
+        throw new Error("retained candidate identity mismatch");
+      }
+      return cloneRetained(retained) as BoundRetainedResult;
+    }
+    if (retained.root !== identity.root) {
+      throw new Error("retained candidate identity mismatch");
+    }
+    Object.assign(retained, cloneIdentity(identity));
+    this.sealedResults.set(id, cloneRetained(retained));
+    return cloneRetained(retained) as BoundRetainedResult;
   }
+
+  resolveIdentity(
+    id: string,
+    expected: RetainedCandidateFacts,
+  ): BoundRetainedResult {
+    const retained = this.results.get(id);
+    if (!retained) throw new Error("retained result not found");
+    this.assertIntegrity(id, retained);
+    if (
+      !hasCompleteIdentity(retained) ||
+      !this.matchesIdentity(retained, expected) ||
+      !isDeepStrictEqual(retained.writeSet, expected.writeSet) ||
+      !isDeepStrictEqual(
+        retained.approvedDependencies,
+        expected.approvedDependencies,
+      )
+    ) {
+      throw new Error("retained candidate identity mismatch");
+    }
+    const sealed = this.sealedCandidateFacts.get(id);
+    if (sealed) {
+      if (
+        !this.matchesIdentity(retained, sealed) ||
+        !isDeepStrictEqual(retained.writeSet, sealed.writeSet) ||
+        !isDeepStrictEqual(
+          retained.approvedDependencies,
+          sealed.approvedDependencies,
+        ) ||
+        !isDeepStrictEqual(retained.snapshot, sealed.snapshot)
+      ) {
+        throw new Error("retained candidate identity mismatch");
+      }
+    } else {
+      if (!isDeepStrictEqual(retained.snapshot, expected.snapshot)) {
+        throw new Error("retained candidate identity mismatch");
+      }
+      this.sealedCandidateFacts.set(id, this.cloneFacts(retained));
+    }
+    return cloneRetained(retained) as BoundRetainedResult;
+  }
+
+  resolveForApply(id: string): RetainedResult {
+    const retained = this.results.get(id);
+    if (!retained) throw new Error("retained result not found");
+    this.assertIntegrity(id, retained);
+    return cloneRetained(retained);
+  }
+
+  private assertIntegrity(id: string, retained: RetainedResult): void {
+    const sealed = this.sealedResults.get(id);
+    if (sealed && isDeepStrictEqual(retained, sealed)) return;
+    const identityChanged =
+      sealed !== undefined &&
+      (IDENTITY_KEYS.some((key) => retained[key] !== sealed[key]) ||
+        retained.root !== sealed.root ||
+        !isDeepStrictEqual(retained.writeSet, sealed.writeSet) ||
+        !isDeepStrictEqual(
+          retained.approvedDependencies,
+          sealed.approvedDependencies,
+        ) ||
+        !isDeepStrictEqual(retained.snapshot, sealed.snapshot));
+    throw new Error(
+      identityChanged
+        ? "retained candidate identity mismatch"
+        : "retained candidate integrity mismatch",
+    );
+  }
+
+  private cloneFacts(retained: BoundRetainedResult): RetainedCandidateFacts {
+    return {
+      ...cloneIdentity(retained),
+      root: retained.root,
+      writeSet: [...retained.writeSet],
+      approvedDependencies: [...retained.approvedDependencies],
+      snapshot: structuredClone(retained.snapshot),
+    };
+  }
+
+  private matchesIdentity(
+    retained: BoundRetainedResult,
+    expected: RetainedCandidateIdentity,
+  ): boolean {
+    return (
+      retained.stage === expected.stage &&
+      retained.canonicalRoot === expected.canonicalRoot &&
+      retained.root === expected.root &&
+      retained.changeId === expected.changeId &&
+      retained.taskId === expected.taskId &&
+      retained.originRequestId === expected.originRequestId &&
+      retained.phase === expected.phase &&
+      retained.launchIndex === expected.launchIndex
+    );
+  }
+
   discard(id: string): boolean {
+    this.sealedResults.delete(id);
+    this.sealedCandidateFacts.delete(id);
     return this.results.delete(id);
   }
   clear(): void {
     this.results.clear();
+    this.sealedResults.clear();
+    this.sealedCandidateFacts.clear();
   }
   get size(): number {
     return this.results.size;