@abelxiaoxing/cadence 1.1.0 → 1.2.0

package/src/candidate-patch.ts

@@ -0,0 +1,250 @@
+import { lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+
+import { isValidRelativePath } from "./contracts.ts";
+import { observeSafePath } from "./safe-path.ts";
+
+export type CandidatePatchOperation =
+  | {
+      kind: "replace";
+      path: string;
+      oldText: string;
+      newText: string;
+    }
+  | { kind: "rewrite"; path: string; content: string }
+  | {
+      kind: "create";
+      path: string;
+      content: string;
+      mode: "regular" | "executable";
+    }
+  | { kind: "delete"; path: string };
+
+interface CandidateFileState {
+  path: string;
+  base: string | null;
+  current: string | null;
+  mode: "100644" | "100755";
+}
+
+function exactKeys(value: object, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  return (
+    actual.length === expected.length &&
+    [...expected].sort().every((key, index) => actual[index] === key)
+  );
+}
+
+function safeText(value: unknown, maxBytes: number): value is string {
+  if (typeof value !== "string" || value.includes("\0")) return false;
+  const encoded = Buffer.from(value, "utf8");
+  return encoded.byteLength <= maxBytes && encoded.toString("utf8") === value;
+}
+
+function renderFileDiff(state: CandidateFileState): string {
+  if (state.base === state.current) return "";
+  if (state.base === null && state.current === "") {
+    throw new Error("candidate-empty-file-create-unsupported");
+  }
+  if (state.current === null && state.base === "") {
+    throw new Error("candidate-empty-file-delete-unsupported");
+  }
+  const output: string[] = [`diff --git a/${state.path} b/${state.path}`];
+  if (state.base === null) output.push(`new file mode ${state.mode}`);
+  if (state.current === null) output.push(`deleted file mode ${state.mode}`);
+  const generated = generateUnifiedPatch(
+    state.path,
+    state.base ?? "",
+    state.current ?? "",
+    3,
+  );
+  const generatedHeaders = `--- ${state.path}\n+++ ${state.path}\n`;
+  if (!generated.startsWith(generatedHeaders)) {
+    throw new Error("candidate-patch-diff-invalid");
+  }
+  output.push(state.base === null ? "--- /dev/null" : `--- a/${state.path}`);
+  output.push(state.current === null ? "+++ /dev/null" : `+++ b/${state.path}`);
+  return `${output.join("\n")}\n${generated.slice(generatedHeaders.length)}`;
+}
+
+function occurrenceCount(value: string, search: string): number {
+  let count = 0;
+  let offset = 0;
+  for (;;) {
+    const found = value.indexOf(search, offset);
+    if (found < 0) return count;
+    count += 1;
+    if (count > 1) return count;
+    offset = found + 1;
+  }
+}
+
+export function compileCandidatePatch(input: {
+  root: string;
+  writePaths: readonly string[];
+  deletePaths: readonly string[];
+  operations: readonly CandidatePatchOperation[];
+  maxBytes: number;
+}): string {
+  if (
+    !path.isAbsolute(input.root) ||
+    !Number.isSafeInteger(input.maxBytes) ||
+    input.maxBytes < 1 ||
+    !Array.isArray(input.operations) ||
+    input.operations.length < 1 ||
+    input.operations.length > 128
+  ) {
+    throw new Error("candidate-patch-invalid");
+  }
+  const writePaths = new Set(input.writePaths);
+  const deletePaths = new Set(input.deletePaths);
+  const states = new Map<string, CandidateFileState>();
+
+  const requirePath = (relative: unknown): string => {
+    if (
+      !isValidRelativePath(relative) ||
+      relative === "." ||
+      relative.trim() !== relative ||
+      /[\r\n\t]/u.test(relative)
+    ) {
+      throw new Error("candidate-patch-path-invalid");
+    }
+    return relative;
+  };
+  const load = (relative: string): CandidateFileState => {
+    const existing = states.get(relative);
+    if (existing) return existing;
+    const observation = observeSafePath(input.root, relative);
+    if (observation.kind === "directory" || observation.kind === "unsafe") {
+      throw new Error("candidate-patch-path-unsafe");
+    }
+    let base: string | null = null;
+    let mode: CandidateFileState["mode"] = "100644";
+    if (observation.kind === "file") {
+      const target = path.join(input.root, relative);
+      const stat = lstatSync(target);
+      if (stat.size > input.maxBytes) {
+        throw new Error("candidate-patch-source-too-large");
+      }
+      const bytes = readFileSync(target);
+      try {
+        base = new TextDecoder("utf-8", {
+          fatal: true,
+          ignoreBOM: true,
+        }).decode(bytes);
+      } catch {
+        throw new Error("candidate-patch-source-invalid");
+      }
+      if (base.includes("\0")) {
+        throw new Error("candidate-patch-source-invalid");
+      }
+      mode = stat.mode & 0o111 ? "100755" : "100644";
+    }
+    const state = { path: relative, base, current: base, mode };
+    states.set(relative, state);
+    return state;
+  };
+
+  for (const operation of input.operations) {
+    if (
+      !operation ||
+      typeof operation !== "object" ||
+      Array.isArray(operation)
+    ) {
+      throw new Error("candidate-patch-operation-invalid");
+    }
+    switch (operation.kind) {
+      case "replace": {
+        if (
+          !exactKeys(operation, ["kind", "path", "oldText", "newText"]) ||
+          !safeText(operation.oldText, input.maxBytes) ||
+          operation.oldText.length === 0 ||
+          !safeText(operation.newText, input.maxBytes)
+        ) {
+          throw new Error("candidate-patch-replace-invalid");
+        }
+        const relative = requirePath(operation.path);
+        if (!writePaths.has(relative)) {
+          throw new Error("candidate-patch-replace-invalid");
+        }
+        const state = load(relative);
+        if (
+          state.current === null ||
+          occurrenceCount(state.current, operation.oldText) !== 1
+        ) {
+          throw new Error("candidate-patch-replace-invalid");
+        }
+        state.current = state.current.replace(
+          operation.oldText,
+          operation.newText,
+        );
+        break;
+      }
+      case "rewrite": {
+        if (
+          !exactKeys(operation, ["kind", "path", "content"]) ||
+          !safeText(operation.content, input.maxBytes)
+        ) {
+          throw new Error("candidate-patch-rewrite-invalid");
+        }
+        const relative = requirePath(operation.path);
+        if (!writePaths.has(relative)) {
+          throw new Error("candidate-patch-rewrite-invalid");
+        }
+        const state = load(relative);
+        if (state.current === null) {
+          throw new Error("candidate-patch-rewrite-invalid");
+        }
+        state.current = operation.content;
+        break;
+      }
+      case "create": {
+        if (
+          !exactKeys(operation, ["kind", "path", "content", "mode"]) ||
+          !safeText(operation.content, input.maxBytes) ||
+          operation.content.length === 0 ||
+          (operation.mode !== "regular" && operation.mode !== "executable")
+        ) {
+          throw new Error("candidate-patch-create-invalid");
+        }
+        const relative = requirePath(operation.path);
+        if (!writePaths.has(relative)) {
+          throw new Error("candidate-patch-create-invalid");
+        }
+        const state = load(relative);
+        if (state.base !== null || state.current !== null) {
+          throw new Error("candidate-patch-create-invalid");
+        }
+        state.current = operation.content;
+        state.mode = operation.mode === "executable" ? "100755" : "100644";
+        break;
+      }
+      case "delete": {
+        if (!exactKeys(operation, ["kind", "path"])) {
+          throw new Error("candidate-patch-delete-invalid");
+        }
+        const relative = requirePath(operation.path);
+        if (!deletePaths.has(relative)) {
+          throw new Error("candidate-patch-delete-invalid");
+        }
+        const state = load(relative);
+        if (state.base === null || state.current === null) {
+          throw new Error("candidate-patch-delete-invalid");
+        }
+        state.current = null;
+        break;
+      }
+      default:
+        throw new Error("candidate-patch-operation-invalid");
+    }
+  }
+
+  const diff = [...states.values()]
+    .filter((state) => state.base !== state.current)
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map(renderFileDiff)
+    .join("");
+  if (diff.length === 0) throw new Error("candidate-patch-empty");
+  return diff;
+}

package/src/child-session.ts

@@ -200,14 +200,8 @@ function structuralSubmitCount(message: AssistantMessage | undefined) {
   ).length;
 }
 
-function isSingleStructuralSubmit(message: AssistantMessage | undefined) {
-  const content = finalDeliveryContent(message);
-  return (
-    message?.role === "assistant" &&
-    content.length === 1 &&
-    content[0]?.type === "toolCall" &&
-    content[0].name === "abel_submit_result"
-  );
+function hasOneStructuralSubmit(message: AssistantMessage | undefined) {
+  return message?.role === "assistant" && structuralSubmitCount(message) === 1;
 }
 
 function safeChildError(failure: ChildFailure): string {
@@ -317,7 +311,7 @@ export async function runChildSession(input: {
   onStreamStart?: () => void;
   onStreamProgress?: () => void;
 }): Promise<ChildSessionResult> {
-  const segmentedCandidate = input.candidateArtifact !== undefined;
+  const candidateProtocol = input.candidateArtifact !== undefined;
   const submit = input.candidateArtifact
     ? createCandidateArtifactTool(input.candidateArtifact)
     : createSubmitTool({
@@ -402,14 +396,19 @@ export async function runChildSession(input: {
     const assistants =
       session?.messages.filter((m) => m.role === "assistant") ?? [];
     const last = assistants.at(-1);
+    const lastSubmit = assistants.findLast((message) =>
+      hasStructuralSubmit(message),
+    );
+    const structuralAttempts = assistants.reduce(
+      (count, message) => count + structuralSubmitCount(message),
+      0,
+    );
     let finalCategory: FinalCategory;
     if (!last) {
       finalCategory = "no-final-assistant";
-    } else if (isSingleStructuralSubmit(last)) {
+    } else if (hasOneStructuralSubmit(lastSubmit)) {
       finalCategory =
-        !segmentedCandidate && submit.getAttempts() > 1
-          ? "multiple-submit"
-          : "single-submit-only";
+        structuralAttempts > 1 ? "multiple-submit" : "single-submit-only";
     } else {
       const content = finalDeliveryContent(last);
       finalCategory =
@@ -504,13 +503,17 @@ export async function runChildSession(input: {
     if (childAgent) {
       const previousShouldStopAfterTurn = childAgent.shouldStopAfterTurn;
       childAgent.shouldStopAfterTurn = async (turn, signal) => {
-        if (
-          segmentedCandidate
-            ? submit.getResult() !== undefined
-            : hasStructuralSubmit(turn.message)
-        ) {
+        if (submit.getResult() !== undefined) {
           return true;
         }
+        const structuralAttempts =
+          session?.messages
+            .filter((message) => message.role === "assistant")
+            .reduce(
+              (count, message) => count + structuralSubmitCount(message),
+              0,
+            ) ?? 0;
+        if (structuralAttempts >= 2) return true;
         return (await previousShouldStopAfterTurn?.(turn, signal)) ?? false;
       };
     }
@@ -560,11 +563,11 @@ export async function runChildSession(input: {
     const result = submit.getResult();
     const attempts = submit.getAttempts();
     const classification = classifySession();
-    const segmentedComplete =
-      segmentedCandidate &&
+    const candidateComplete =
+      candidateProtocol &&
       result !== undefined &&
       (result.kind === "sealed-candidate" || result.kind === "context-request");
-    if (!result || (segmentedCandidate ? !segmentedComplete : attempts !== 1)) {
+    if (!result || (candidateProtocol && !candidateComplete)) {
       const failure = withSubmitDetails(
         submit.getFailure() ??
           input.failureOverride?.() ??
@@ -589,9 +592,9 @@ export async function runChildSession(input: {
     const assistants = session.messages.filter((m) => m.role === "assistant");
     const final = assistants.at(-1);
     if (
-      !(segmentedCandidate
-        ? segmentedComplete && structuralSubmitCount(final) === 1
-        : isSingleStructuralSubmit(final))
+      !(candidateProtocol
+        ? candidateComplete && structuralSubmitCount(final) === 1
+        : hasOneStructuralSubmit(final))
     ) {
       const failure = {
         kind: "artifact",

package/src/contracts.ts

@@ -10,7 +10,6 @@ export type {
 export {
   assertControlCommand,
   CONTROL_COMMANDS,
-  CONTROL_PROTOCOL_VERSION,
   CONTROL_STAGES,
   controlRunKey,
   validateControlCommand,
@@ -23,18 +22,11 @@ export const STAGES = [
 ] as const;
 export const ROLES = [
   "design-explorer",
-  "contract-reviewer",
   "implementation-worker",
   "diagnosis-worker",
 ] as const;
 export const OUTPUT_KINDS = ["evidence", "diff"] as const;
-export const PHASES = [
-  "evidence",
-  "red",
-  "green",
-  "refactor",
-  "review",
-] as const;
+export const PHASES = ["evidence", "red", "green", "refactor"] as const;
 
 export const AGENTS_IMPACTS = [
   "none",
@@ -146,8 +138,10 @@ export const APPROVAL_BOUNDARY_CODES = [
   "behavior-contract-insufficient",
   "architecture-contract-insufficient",
   "task-scope-insufficient",
+  "conflict-resource-authority-insufficient",
   "verification-contract-insufficient",
   "agents-contract-insufficient",
+  "irreversible-scope-insufficient",
 ] as const;
 export const VERIFICATION_ADAPTER_CODES = [
   "input-missing",
@@ -439,6 +433,7 @@ export type ImplementGraphReadinessDiagnostic =
 export interface PacketEnvelope {
   stage: "abel-design" | "abel-diagnose";
   role: "design-explorer" | "diagnosis-worker";
+  runId?: string;
   id: string;
   phase: string;
   objective: string;
@@ -1230,7 +1225,7 @@ export function validatePacketEnvelope(
     return { ok: false, reason: "missing request envelope" };
   }
   const packet = value as Record<string, unknown>;
-  const required = [
+  const baseRequired = [
     "stage",
     "role",
     "id",
@@ -1241,6 +1236,14 @@ export function validatePacketEnvelope(
     "declared",
     "output",
   ] as const;
+  const required =
+    packet.stage === "abel-design"
+      ? ([
+          ...baseRequired.slice(0, 2),
+          "runId",
+          ...baseRequired.slice(2),
+        ] as const)
+      : baseRequired;
   for (const field of required) {
     if (packet[field] === undefined) {
       return { ok: false, reason: `missing required field: ${field}` };
@@ -1262,6 +1265,12 @@ export function validatePacketEnvelope(
   ) {
     return { ok: false, reason: "packet role does not match stage" };
   }
+  if (
+    (packet.stage === "abel-design" && !validIdentifier(packet.runId)) ||
+    (packet.stage === "abel-diagnose" && packet.runId !== undefined)
+  ) {
+    return { ok: false, reason: "invalid Design run identity" };
+  }
   if (
     typeof packet.id !== "string" ||
     packet.id.length === 0 ||

package/src/control-contracts.ts

@@ -2,8 +2,6 @@
 // Mechanical graph, snapshot, task, and apply identities are intentionally not
 // part of this surface: the control plane derives them from approved delivery.
 
-export const CONTROL_PROTOCOL_VERSION = 2 as const;
-
 export const CONTROL_COMMANDS = [
   "start",
   "status",
@@ -13,7 +11,7 @@ export const CONTROL_COMMANDS = [
   "discard",
 ] as const;
 
-export const CONTROL_STAGES = ["abel-design", "abel-implement"] as const;
+export const CONTROL_STAGES = ["abel-implement"] as const;
 
 export type ControlCommandName = (typeof CONTROL_COMMANDS)[number];
 export type ControlStage = (typeof CONTROL_STAGES)[number];
@@ -23,55 +21,39 @@ const CHANGE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/u;
 const SHA256 = /^[a-f0-9]{64}$/u;
 
 interface ControlBase {
-  version: typeof CONTROL_PROTOCOL_VERSION;
   command: ControlCommandName;
   stage: ControlStage;
-}
-
-interface NamedControlBase extends ControlBase {
   change: string;
 }
 
-export interface NamedStartControlCommand extends NamedControlBase {
-  command: "start";
-  operationId: string;
-  provisionalKey?: string;
-}
-
-export interface ProvisionalDesignStartControlCommand extends ControlBase {
+export interface StartControlCommand extends ControlBase {
   command: "start";
-  stage: "abel-design";
-  provisionalKey: string;
   operationId: string;
 }
 
-export type StartControlCommand =
-  | NamedStartControlCommand
-  | ProvisionalDesignStartControlCommand;
-
-export interface StatusControlCommand extends NamedControlBase {
+export interface StatusControlCommand extends ControlBase {
   command: "status";
 }
 
-export interface ResumeControlCommand extends NamedControlBase {
+export interface ResumeControlCommand extends ControlBase {
   command: "resume";
   operationId: string;
   deliveryRevision?: number;
   receiptHash?: string;
 }
 
-export interface RebindControlCommand extends NamedControlBase {
+export interface RebindControlCommand extends ControlBase {
   command: "rebind";
   operationId: string;
   routeId: string;
 }
 
-export interface CancelControlCommand extends NamedControlBase {
+export interface CancelControlCommand extends ControlBase {
   command: "cancel";
   operationId: string;
 }
 
-export interface DiscardControlCommand extends NamedControlBase {
+export interface DiscardControlCommand extends ControlBase {
   command: "discard";
   operationId: string;
 }
@@ -86,10 +68,7 @@ export type ControlCommand =
 
 export type ControlCommandValidation =
   | { ok: true; value: ControlCommand }
-  | {
-      ok: false;
-      code: "invalid-control-command" | "unsupported-control-version";
-    };
+  | { ok: false; code: "invalid-control-command" };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -110,7 +89,6 @@ function hasExactKeys(
 
 function validCommon(value: Record<string, unknown>): boolean {
   return (
-    value.version === CONTROL_PROTOCOL_VERSION &&
     (CONTROL_COMMANDS as readonly unknown[]).includes(value.command) &&
     (CONTROL_STAGES as readonly unknown[]).includes(value.stage)
   );
@@ -128,21 +106,14 @@ export function validateControlCommand(
   value: unknown,
 ): ControlCommandValidation {
   if (!isRecord(value)) return { ok: false, code: "invalid-control-command" };
-  if (
-    Object.hasOwn(value, "version") &&
-    value.version !== CONTROL_PROTOCOL_VERSION
-  ) {
-    return { ok: false, code: "unsupported-control-version" };
-  }
   if (!validCommon(value)) {
     return { ok: false, code: "invalid-control-command" };
   }
 
-  const common = ["version", "command", "stage"] as const;
-  const named = [...common, "change"] as const;
+  const common = ["command", "stage", "change"] as const;
   switch (value.command) {
     case "status":
-      if (!hasExactKeys(value, named) || !validChange(value.change)) break;
+      if (!hasExactKeys(value, common) || !validChange(value.change)) break;
       return {
         ok: true,
         value: structuredClone(value) as unknown as StatusControlCommand,
@@ -150,7 +121,7 @@ export function validateControlCommand(
     case "cancel":
     case "discard":
       if (
-        hasExactKeys(value, [...named, "operationId"]) &&
+        hasExactKeys(value, [...common, "operationId"]) &&
         validChange(value.change) &&
         validOperationId(value.operationId)
       ) {
@@ -162,37 +133,19 @@ export function validateControlCommand(
       break;
     case "start":
       if (
-        hasExactKeys(value, [...named, "operationId"], ["provisionalKey"]) &&
+        hasExactKeys(value, [...common, "operationId"]) &&
         validChange(value.change) &&
-        validOperationId(value.operationId) &&
-        (value.provisionalKey === undefined ||
-          (value.stage === "abel-design" &&
-            typeof value.provisionalKey === "string" &&
-            SHA256.test(value.provisionalKey)))
-      ) {
-        return {
-          ok: true,
-          value: structuredClone(value) as unknown as NamedStartControlCommand,
-        };
-      }
-      if (
-        hasExactKeys(value, [...common, "provisionalKey", "operationId"]) &&
-        value.stage === "abel-design" &&
-        typeof value.provisionalKey === "string" &&
-        SHA256.test(value.provisionalKey) &&
         validOperationId(value.operationId)
       ) {
         return {
           ok: true,
-          value: structuredClone(
-            value,
-          ) as unknown as ProvisionalDesignStartControlCommand,
+          value: structuredClone(value) as unknown as StartControlCommand,
         };
       }
       break;
     case "rebind":
       if (
-        hasExactKeys(value, [...named, "operationId", "routeId"]) &&
+        hasExactKeys(value, [...common, "operationId", "routeId"]) &&
         validChange(value.change) &&
         validOperationId(value.operationId) &&
         typeof value.routeId === "string" &&
@@ -208,7 +161,7 @@ export function validateControlCommand(
       if (
         !hasExactKeys(
           value,
-          [...named, "operationId"],
+          [...common, "operationId"],
           ["deliveryRevision", "receiptHash"],
         ) ||
         !validChange(value.change) ||