@abelxiaoxing/cadence 1.3.0 → 1.4.1

package/src/activity-contracts.ts

@@ -0,0 +1,82 @@
+export type PacketActivityState =
+  | "queued"
+  | "preparing"
+  | "connecting"
+  | "waiting-first-response"
+  | "running"
+  | "retrying"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed-out";
+
+export type PacketFailureReason =
+  | "subagent failed"
+  | "subagent cancelled"
+  | "phase timed out";
+
+export interface PacketActivityEvent {
+  state: PacketActivityState;
+  requestId: string;
+  role: string;
+  phase: string;
+  objective: string;
+  sequence: number;
+  attempt?: number;
+  maxAttempts?: number;
+  code?: string;
+  wait?: string;
+  failureReason?: PacketFailureReason;
+}
+
+export type PacketActivityObserver = (
+  event: PacketActivityEvent,
+) => void | Promise<void>;
+
+export const WORKFLOW_ACTIVITY_STATES = [
+  "queued",
+  "preparing",
+  "connecting",
+  "waiting-first-response",
+  "running",
+  "validating",
+  "retrying",
+  "verifying",
+  "paused",
+  "approval-needed",
+  "applying",
+  "recovering",
+  "operation-cancelled",
+  "discarded",
+  "rejected",
+  "completed",
+] as const;
+
+export type WorkflowActivityState = (typeof WORKFLOW_ACTIVITY_STATES)[number];
+export type ActivityState = PacketActivityState | WorkflowActivityState;
+export type TerminalActivityState =
+  | Exclude<
+      PacketActivityState,
+      | "queued"
+      | "preparing"
+      | "connecting"
+      | "waiting-first-response"
+      | "running"
+      | "retrying"
+    >
+  | WorkflowActivityState;
+
+export interface WorkflowActivityUpdate {
+  state: WorkflowActivityState;
+  stage?: "abel-design" | "abel-implement";
+  runId?: string;
+  change?: string;
+  taskId?: string;
+  phase?: string;
+  objective?: string;
+  code?: string;
+  attempt?: number;
+  maxAttempts?: number;
+  wait?: string;
+  legalCommands?: string[];
+}

package/src/apply-transaction.ts

@@ -20,10 +20,12 @@ import {
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
-
 import type { ArtifactStore } from "./artifact-store.ts";
+import { compareCanonicalStrings } from "./canonical.ts";
 import { isValidRelativePath } from "./contracts.ts";
 import { observeSafePath } from "./safe-path.ts";
+import { configureSqlite, ensureSqliteSchema } from "./sqlite-schema.ts";
+import { APPLY_SCHEMA } from "./storage-schema.ts";
 import type {
   WorkspaceEntry,
   WorkspaceRevision,
@@ -548,7 +550,11 @@ export async function verifyCumulativeRevision(
   );
   chmodSync(temporary, 0o700);
   try {
-    input.workspaceStore.materialize(revision.revisionId, temporary);
+    await input.workspaceStore.materializeAsync(
+      revision.revisionId,
+      temporary,
+      input.signal,
+    );
     if (input.signal?.aborted) {
       return {
         ok: false,
@@ -629,16 +635,8 @@ export class ApplyTransaction {
       throw new Error("transaction-database-path-invalid");
     }
     this.#database = new DatabaseSync(databasePath);
-    this.#database.exec(
-      "PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL;",
-    );
-    this.#database.exec(`
-      CREATE TABLE IF NOT EXISTS apply_transaction_journal (
-        transaction_id TEXT PRIMARY KEY,
-        journal_json TEXT NOT NULL,
-        journal_hash TEXT NOT NULL
-      ) STRICT;
-    `);
+    configureSqlite(this.#database);
+    ensureSqliteSchema(this.#database, APPLY_SCHEMA);
     chmodSync(databasePath, 0o600);
   }
 
@@ -986,7 +984,7 @@ export class ApplyTransaction {
     const deepestFirst = [...journal.createdDirectories].sort(
       (left, right) =>
         right.split("/").length - left.split("/").length ||
-        right.localeCompare(left),
+        compareCanonicalStrings(right, left),
     );
     for (const relative of deepestFirst) {
       const observation = observeSafePath(journal.consumerRoot, relative);
@@ -1244,7 +1242,11 @@ export class ApplyTransaction {
           path.join(this.root, "post-apply-verification-"),
         );
         try {
-          this.#workspaces.materialize(journal.finalRevisionId, isolatedRoot);
+          await this.#workspaces.materializeAsync(
+            journal.finalRevisionId,
+            isolatedRoot,
+            signal,
+          );
           const execution = Promise.resolve(
             this.#hooks.postApply({
               transactionId,

package/src/artifact-store.ts

@@ -3,6 +3,7 @@ import {
   chmodSync,
   closeSync,
   constants,
+  copyFileSync,
   fsyncSync,
   lstatSync,
   mkdirSync,
@@ -160,6 +161,22 @@ export class ArtifactStore {
     return Buffer.from(bytes);
   }
 
+  /** Clone when supported; always use a distinct inode and verify the copied bytes. */
+  copyVerified(hash: string, destination: string): number {
+    const source = this.#blobPath(hash);
+    const stat = lstatSync(source, { throwIfNoEntry: false });
+    if (!stat?.isFile() || stat.isSymbolicLink())
+      throw new Error("artifact-unavailable");
+    copyFileSync(
+      source,
+      destination,
+      constants.COPYFILE_EXCL | constants.COPYFILE_FICLONE,
+    );
+    const bytes = readFileSync(destination);
+    if (digest(bytes) !== hash) throw new Error("artifact-integrity-invalid");
+    return bytes.byteLength;
+  }
+
   referenceCount(hash: string): number {
     requireHash(hash);
     const referencePath = this.#referencePath(hash);

package/src/candidate-artifact.ts

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { diffWritePaths } from "./contracts.ts";
+import {
+  type BeginCandidateInput,
+  TASK_LEDGER_LIMITS,
+  type TaskLedger,
+} from "./task-ledger.ts";
+import type { DurableCandidateProposal } from "./workflow-policy.ts";
+
+type ArtifactProposal = Extract<
+  DurableCandidateProposal,
+  { kind: "candidate" | "sealed-candidate" }
+>;
+interface CandidateArtifactInput {
+  ledger: TaskLedger;
+  identity: BeginCandidateInput;
+  proposal: ArtifactProposal;
+}
+
+const sha256 = (bytes: Uint8Array) =>
+  createHash("sha256").update(bytes).digest("hex");
+
+/** Inspect the same sealed bytes for normal phases and repairs. Callers own recovery policy. */
+export function inspectCandidateArtifact({
+  ledger,
+  identity,
+  proposal,
+  approvedPaths,
+}: CandidateArtifactInput & { approvedPaths: readonly string[] }):
+  | { ok: true; bytes: Buffer; paths: string[] }
+  | {
+      ok: false;
+      code: "candidate-diff-invalid" | "write-set-mismatch";
+      stage: string;
+    } {
+  const invalid = (stage: string) => ({
+    ok: false as const,
+    code: "candidate-diff-invalid" as const,
+    stage,
+  });
+  ledger.beginCandidate(identity);
+  let bytes: Buffer;
+  if (proposal.kind === "sealed-candidate") {
+    if (
+      proposal.candidateId !== identity.candidateId ||
+      !/^[a-f0-9]{64}$/u.test(proposal.artifactHash) ||
+      !Number.isSafeInteger(proposal.bytes) ||
+      proposal.bytes < 1 ||
+      !Array.isArray(proposal.paths)
+    )
+      return invalid("candidate-seal");
+    bytes = Buffer.from(ledger.readSealedCandidate(identity.candidateId));
+    if (
+      bytes.length !== proposal.bytes ||
+      sha256(bytes) !== proposal.artifactHash
+    ) {
+      throw new Error("candidate-seal-integrity-invalid");
+    }
+  } else {
+    if (
+      !(proposal.bytes instanceof Uint8Array) ||
+      proposal.bytes.length === 0
+    ) {
+      return invalid("candidate-submit");
+    }
+    bytes = Buffer.from(proposal.bytes);
+  }
+  let paths: string[];
+  try {
+    paths = diffWritePaths(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    ).paths;
+  } catch {
+    return invalid("candidate-diff");
+  }
+  if (paths.some((relative) => !approvedPaths.includes(relative))) {
+    return {
+      ok: false,
+      code: "write-set-mismatch",
+      stage: "candidate-boundary",
+    };
+  }
+  if (
+    proposal.kind === "sealed-candidate" &&
+    JSON.stringify([...proposal.paths].sort()) !==
+      JSON.stringify([...paths].sort())
+  ) {
+    return invalid("candidate-seal");
+  }
+  return { ok: true, bytes, paths };
+}
+
+/** Seal after isolated patch/dependency checks, before any phase verification. */
+export function sealCandidateArtifact({
+  ledger,
+  identity,
+  proposal,
+  bytes,
+}: CandidateArtifactInput & { bytes: Buffer }):
+  | { ok: true; artifactHash: string }
+  | { ok: false; kind: "paused" | "retryable"; code: string; stage: string } {
+  if (proposal.kind === "sealed-candidate")
+    return { ok: true, artifactHash: proposal.artifactHash };
+  let sequence = 0;
+  for (
+    let offset = 0;
+    offset < bytes.length;
+    offset += TASK_LEDGER_LIMITS.maxSegmentBytes
+  ) {
+    const segment = bytes.subarray(
+      offset,
+      Math.min(offset + TASK_LEDGER_LIMITS.maxSegmentBytes, bytes.length),
+    );
+    const accepted = ledger.appendCandidateSegment({
+      ...identity,
+      sequence,
+      bytes: segment,
+      segmentHash: sha256(segment),
+    });
+    if (!accepted.ok)
+      return {
+        ok: false,
+        kind: "paused",
+        code: accepted.code,
+        stage: "candidate-segment",
+      };
+    sequence++;
+  }
+  const sealed = ledger.sealCandidate({
+    ...identity,
+    segmentCount: sequence,
+    totalBytes: bytes.length,
+    candidateHash: sha256(bytes),
+  });
+  return sealed.ok
+    ? { ok: true, artifactHash: sealed.artifactHash }
+    : {
+        ok: false,
+        kind: "retryable",
+        code: sealed.code,
+        stage: "candidate-seal",
+      };
+}

package/src/candidate-patch.ts

@@ -1,6 +1,7 @@
 import { lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+import { compareCanonicalStrings } from "./canonical.ts";
 
 import { isValidRelativePath } from "./contracts.ts";
 import { observeSafePath } from "./safe-path.ts";
@@ -146,7 +147,7 @@ export function compileCandidatePatch(input: {
     return state;
   };
 
-  for (const operation of input.operations) {
+  for (const [operationIndex, operation] of input.operations.entries()) {
     if (
       !operation ||
       typeof operation !== "object" ||
@@ -165,20 +166,40 @@ export function compileCandidatePatch(input: {
           throw new Error("candidate-patch-replace-invalid");
         }
         const relative = requirePath(operation.path);
+        const reject = (reason: string, hint: string): never => {
+          throw new Error(
+            JSON.stringify({
+              code: "candidate-patch-replace-invalid",
+              operationIndex,
+              ...(relative.length <= 512 && !/[\p{Cc}\p{Cf}]/u.test(relative)
+                ? { path: relative }
+                : {}),
+              reason,
+              hint,
+            }),
+          );
+        };
         if (!writePaths.has(relative)) {
-          throw new Error("candidate-patch-replace-invalid");
+          reject(
+            "path-not-authorized",
+            "Use only approved write paths; request context instead of widening authority.",
+          );
         }
         const state = load(relative);
-        if (
-          state.current === null ||
-          occurrenceCount(state.current, operation.oldText) !== 1
-        ) {
-          throw new Error("candidate-patch-replace-invalid");
+        const current =
+          state.current ??
+          reject(
+            "file-not-found",
+            "Use create for a new approved file, or correct the path.",
+          );
+        const occurrences = occurrenceCount(current, operation.oldText);
+        if (occurrences !== 1) {
+          reject(
+            occurrences === 0 ? "old-text-not-found" : "old-text-ambiguous",
+            "Read the approved file and supply exact unique oldText, including enough surrounding context. Operations are applied in order.",
+          );
         }
-        state.current = state.current.replace(
-          operation.oldText,
-          operation.newText,
-        );
+        state.current = current.replace(operation.oldText, operation.newText);
         break;
       }
       case "rewrite": {
@@ -242,7 +263,7 @@ export function compileCandidatePatch(input: {
 
   const diff = [...states.values()]
     .filter((state) => state.base !== state.current)
-    .sort((left, right) => left.path.localeCompare(right.path))
+    .sort((left, right) => compareCanonicalStrings(left.path, right.path))
     .map(renderFileDiff)
     .join("");
   if (diff.length === 0) throw new Error("candidate-patch-empty");

package/src/candidate-workspace.ts

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import { lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { observeSafePath } from "./safe-path.ts";
+
+export function runGitApply(
+  root: string,
+  diff: Uint8Array,
+  checkOnly: boolean,
+  signal: AbortSignal,
+): Promise<"ok" | "failed" | "cancelled"> {
+  if (signal.aborted) return Promise.resolve("cancelled");
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value: "ok" | "failed" | "cancelled") => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", abort);
+      resolve(value);
+    };
+    const child = spawn(
+      "git",
+      [
+        "apply",
+        ...(checkOnly ? ["--check"] : []),
+        "--recount",
+        "--whitespace=nowarn",
+        "-",
+      ],
+      { cwd: root, shell: false, stdio: ["pipe", "ignore", "ignore"] },
+    );
+    const abort = () => {
+      child.kill("SIGTERM");
+      settle("cancelled");
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    child.once("error", () => settle(signal.aborted ? "cancelled" : "failed"));
+    child.once("close", (code) =>
+      settle(signal.aborted ? "cancelled" : code === 0 ? "ok" : "failed"),
+    );
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(Buffer.from(diff));
+  });
+}
+export function revisionChanges(
+  root: string,
+  paths: readonly string[],
+): Record<
+  string,
+  { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
+> {
+  const changes: Record<
+    string,
+    { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
+  > = {};
+  for (const relative of [...new Set(paths)].sort()) {
+    const observation = observeSafePath(root, relative);
+    if (observation.kind === "absent") {
+      changes[relative] = { kind: "absent" };
+      continue;
+    }
+    if (observation.kind !== "file") {
+      throw new Error("workflow-candidate-path-unsafe");
+    }
+    const target = path.join(root, ...relative.split("/"));
+    const stat = lstatSync(target);
+    changes[relative] = {
+      kind: "file",
+      bytes: readFileSync(target),
+      mode: stat.mode & 0o777,
+    };
+  }
+  return changes;
+}

package/src/canonical.ts

@@ -0,0 +1,16 @@
+/** Canonical identity ordering is UTF-16 code-unit order, never host collation. */
+export function compareCanonicalStrings(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => compareCanonicalStrings(left, right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}

package/src/change-contract-schema.ts

@@ -0,0 +1,191 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import {
+  isValidRelativePath,
+  VERIFICATION_LIMITS,
+  validateVerificationContract,
+} from "./contracts.ts";
+import type { DesignPlanDiagnostic } from "./design-diagnostics.ts";
+
+const text = Type.String({ minLength: 1, maxLength: 8192, pattern: "\\S" });
+const id = Type.String({ pattern: "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$" });
+const object = <T extends Parameters<typeof Type.Object>[0]>(properties: T) =>
+  Type.Object(properties, { additionalProperties: false });
+const managers = Type.Union([
+  Type.Literal("bun"),
+  Type.Literal("npm"),
+  Type.Literal("pnpm"),
+  Type.Literal("yarn"),
+]);
+const packageRunner = {
+  kind: Type.Literal("package-script"),
+  packageManager: managers,
+  script: text,
+  command: text,
+};
+const executable = Type.Union([
+  object(packageRunner),
+  object({ kind: Type.Literal("local-binary"), executable: text }),
+  object({
+    kind: Type.Literal("npx"),
+    executable: text,
+    noInstall: Type.Literal(true),
+  }),
+]);
+const classification = Type.Union([
+  Type.Literal("expected-red"),
+  Type.Literal("expected-green"),
+  Type.Literal("expected-refactor"),
+]);
+const base = {
+  id,
+  classification,
+  expectedFailure: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
+  executionBindings: Type.Optional(
+    Type.Record(Type.String(), Type.Union([Type.String(), Type.Null()])),
+  ),
+};
+const args = Type.Array(Type.String(), { maxItems: 128 });
+export const ATOMIC_VERIFICATION_SCHEMAS = {
+  vitest: object({
+    ...base,
+    kind: Type.Literal("vitest"),
+    runner: executable,
+    testFiles: Type.Array(text, {
+      minItems: VERIFICATION_LIMITS.minTestFiles,
+      maxItems: VERIFICATION_LIMITS.maxTestFiles,
+      uniqueItems: true,
+    }),
+    args,
+    minTests: Type.Integer({ minimum: 1 }),
+  }),
+  "package-script": object({ ...base, ...packageRunner, args }),
+  "static-check": object({
+    ...base,
+    kind: Type.Literal("static-check"),
+    runner: Type.Union([
+      executable,
+      object({ kind: Type.Literal("node"), script: text }),
+    ]),
+    args,
+  }),
+};
+const atomic = Type.Union(Object.values(ATOMIC_VERIFICATION_SCHEMAS));
+const steps = object({
+  kind: Type.Literal("steps"),
+  id,
+  classification,
+  steps: Type.Array(atomic, {
+    minItems: VERIFICATION_LIMITS.minSteps,
+    maxItems: VERIFICATION_LIMITS.maxSteps,
+  }),
+});
+export const VERIFICATION_SCHEMA = Type.Union([atomic, steps]);
+export const CHANGE_CONTRACT_SCHEMA = object({
+  goal: text,
+  acceptance: Type.Array(
+    object({ id, statement: text, verification: VERIFICATION_SCHEMA }),
+    { minItems: 1, maxItems: 256 },
+  ),
+  constraints: Type.Array(object({ id, statement: text }), { maxItems: 256 }),
+  policy: object({
+    writeRoots: Type.Array(text, {
+      minItems: 1,
+      maxItems: 256,
+      uniqueItems: true,
+    }),
+    dependencies: Type.Array(text, { maxItems: 256, uniqueItems: true }),
+    verificationModes: Type.Array(
+      Type.Union([
+        Type.Literal("behavior"),
+        Type.Literal("mechanical"),
+        Type.Literal("refactor"),
+      ]),
+      { minItems: 1, maxItems: 256, uniqueItems: true },
+    ),
+  }),
+});
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+const schemaFields = new Set([
+  "goal",
+  "acceptance",
+  "id",
+  "statement",
+  "verification",
+  "constraints",
+  "policy",
+  "writeRoots",
+  "dependencies",
+  "verificationModes",
+  "classification",
+  "expectedFailure",
+  "executionBindings",
+  "kind",
+  "runner",
+  "packageManager",
+  "script",
+  "command",
+  "executable",
+  "noInstall",
+  "testFiles",
+  "args",
+  "minTests",
+  "steps",
+]);
+function diagnosticField(pointer: string): string {
+  const fields = ["contract"];
+  for (const part of pointer.split("/").slice(1)) {
+    if (!schemaFields.has(part) && !/^(0|[1-9][0-9]{0,5})$/u.test(part)) break;
+    fields.push(part);
+    // Binding keys are author data, even when they happen to look like schema fields.
+    if (part === "executionBindings") break;
+  }
+  return fields.join(".");
+}
+
+/** Shared shape, bounded field-only diagnostics; never return submitted values or parser messages. */
+export function changeContractDiagnostics(
+  value: unknown,
+): DesignPlanDiagnostic[] {
+  const diagnostics: DesignPlanDiagnostic[] = Value.Errors(
+    CHANGE_CONTRACT_SCHEMA,
+    value,
+  )
+    .slice(0, 32)
+    .map((error) => ({
+      code: "change-contract-field-invalid",
+      field: diagnosticField(error.instancePath),
+      category: error.keyword,
+    }));
+  if (!record(value)) return diagnostics;
+  if (Array.isArray(value.acceptance))
+    value.acceptance.slice(0, 256).forEach((item, index) => {
+      if (!record(item)) return;
+      const verification = item.verification;
+      if (!validateVerificationContract(verification).ok) {
+        const field = `contract.acceptance.${index}.verification`;
+        if (
+          record(verification) &&
+          verification.classification === "expected-red" &&
+          typeof verification.expectedFailure !== "string"
+        )
+          diagnostics.push({
+            code: "change-contract-field-invalid",
+            field: `${field}.expectedFailure`,
+          });
+        else diagnostics.push({ code: "change-contract-field-invalid", field });
+      }
+    });
+  if (record(value.policy) && Array.isArray(value.policy.writeRoots))
+    value.policy.writeRoots.slice(0, 256).forEach((root, index) => {
+      if (root !== "." && !isValidRelativePath(root))
+        diagnostics.push({
+          code: "change-contract-field-invalid",
+          field: `contract.policy.writeRoots.${index}`,
+        });
+    });
+  return diagnostics.slice(0, 32);
+}