@abelxiaoxing/cadence 1.2.0 → 1.2.2

package/agents/implementation-worker.md

@@ -20,8 +20,15 @@ Your output is one complete structured patch delivered through `abel_submit_resu
 - every operation path is within the declared phase boundary; paths that do
   not need a change may remain untouched;
 - preserve the expected parent-owned verification contract without claiming a result;
-- use a typed `context-request` for bounded context, task splitting, or an
-  approval-boundary blocker instead of submitting a partial patch.
+- use a typed `context-request` for bounded context or task splitting instead
+  of submitting a partial patch; classify every ref as a requested path with
+  `read | write` access, a source citation with path and line, or a
+  contract-diagnostic ref;
+- report only the missing context and structural facts: never select
+  `approval-needed`, `boundary-review-needed`, a Gate, or a workflow stage;
+- an `AGENTS.md` path is never a Worker write path;
+- report an AGENTS read need separately, and leave every sealed AGENTS contract
+  and managed-block update to the parent control plane.
 
 If the submit tool rejects malformed operations, use its concrete error to correct the submission once in this same disposable session; a second rejected structural submission ends the session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",

package/src/control-contracts.ts

@@ -74,6 +74,64 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+const CONTROL_TOOL_FIELDS = new Set([
+  "command",
+  "stage",
+  "change",
+  "operationId",
+  "deliveryRevision",
+  "receiptHash",
+  "routeId",
+]);
+
+const COMMAND_FIELDS: Readonly<
+  Record<ControlCommandName, ReadonlySet<string>>
+> = Object.freeze({
+  start: new Set(["command", "stage", "change", "operationId"]),
+  status: new Set(["command", "stage", "change"]),
+  resume: new Set([
+    "command",
+    "stage",
+    "change",
+    "operationId",
+    "deliveryRevision",
+    "receiptHash",
+  ]),
+  rebind: new Set(["command", "stage", "change", "operationId", "routeId"]),
+  cancel: new Set(["command", "stage", "change", "operationId"]),
+  discard: new Set(["command", "stage", "change", "operationId"]),
+});
+
+/**
+ * Adapts Pi/provider strict-schema padding to the closed command union.
+ * Known fields belonging to a different command are projected away, while
+ * unknown fields and fields owned by the selected command remain available to
+ * the strict validator and therefore cannot bypass its exact-key/type checks.
+ */
+export function canonicalizeControlCommandToolInput(value: unknown): unknown {
+  if (
+    !isRecord(value) ||
+    !(CONTROL_COMMANDS as readonly unknown[]).includes(value.command)
+  ) {
+    return value;
+  }
+  const command = value.command as ControlCommandName;
+  const allowed = COMMAND_FIELDS[command];
+  const canonical = Object.create(null) as Record<string, unknown>;
+  for (const [key, entry] of Object.entries(value)) {
+    if (CONTROL_TOOL_FIELDS.has(key) && !allowed.has(key)) continue;
+    if (
+      command === "resume" &&
+      (key === "deliveryRevision" || key === "receiptHash") &&
+      (entry === null || entry === undefined)
+    ) {
+      continue;
+    }
+    canonical[key] = entry;
+  }
+  return canonical;
+}
+
 function hasExactKeys(
   value: Record<string, unknown>,
   required: readonly string[],

package/src/index.ts

@@ -37,7 +37,10 @@ import {
   type StructuredVerificationContract,
   verificationSteps,
 } from "./contracts.ts";
-import { validateControlCommand } from "./control-contracts.ts";
+import {
+  canonicalizeControlCommandToolInput,
+  validateControlCommand,
+} from "./control-contracts.ts";
 import {
   assessDeliveryTraceability,
   compileImplementPlan,
@@ -1522,19 +1525,46 @@ export function openPackageWorkflowControlEngine(
       if (!phase) {
         return { kind: "paused", code: "task-phase-unavailable" };
       }
+      const taskPhases = Object.values(input.task.phases);
+      const executionBoundary = input.artifactCorrection
+        ? {
+            read: [
+              ...new Set(
+                taskPhases.flatMap((boundary) => [
+                  ...boundary.read,
+                  ...boundary.write,
+                  ...boundary.delete,
+                ]),
+              ),
+            ].sort(),
+            write: [
+              ...new Set(taskPhases.flatMap((boundary) => boundary.write)),
+            ].sort(),
+            delete: [
+              ...new Set(taskPhases.flatMap((boundary) => boundary.delete)),
+            ].sort(),
+          }
+        : {
+            read: [...phase.read],
+            write: [...phase.write],
+            delete: [...phase.delete],
+          };
       const phaseContract = {
         candidateId: input.candidateArtifact.identity.candidateId,
         taskId: input.taskId,
         phase: input.phase,
-        readSet: [...phase.read],
-        writeSet: [...phase.write],
-        deleteSet: [...phase.delete],
+        readSet: executionBoundary.read,
+        writeSet: executionBoundary.write,
+        deleteSet: executionBoundary.delete,
         verification: structuredClone(phase.verification),
         agentsImpact: input.task.agents.impact,
         agentsTarget: input.task.agents.target ?? null,
         agentsManagedOnly: true,
         agentsWriteAllowed: false,
         impactClosure: structuredClone(input.task.impactClosure),
+        ...(input.artifactCorrection
+          ? { artifactCorrection: structuredClone(input.artifactCorrection) }
+          : {}),
         ...(input.repair
           ? {
               repair: {
@@ -1567,7 +1597,11 @@ export function openPackageWorkflowControlEngine(
           path.resolve(input.workspaceRoot, root),
         ),
         allowedPaths: [
-          ...new Set([...phase.read, ...phase.write, ...phase.delete]),
+          ...new Set([
+            ...executionBoundary.read,
+            ...executionBoundary.write,
+            ...executionBoundary.delete,
+          ]),
         ],
         timeoutMs: LIMITS.phaseTimeoutMs,
         signal: input.signal,
@@ -1597,11 +1631,28 @@ export function openPackageWorkflowControlEngine(
       }
       const result = child.result;
       if (result.kind === "context-request") {
-        return classifyCandidateContextRequest(result, [
-          ...phase.read,
-          ...phase.write,
-          ...phase.delete,
-        ]);
+        return classifyCandidateContextRequest(result, {
+          phase: input.phase,
+          readPaths: phase.read,
+          writePaths: phase.write,
+          deletePaths: phase.delete,
+          taskPaths: [
+            ...new Set(
+              Object.values(input.task.phases).flatMap((boundary) => [
+                ...boundary.read,
+                ...boundary.write,
+                ...boundary.delete,
+              ]),
+            ),
+          ],
+          redWritePaths: input.task.phases.red.write,
+          agents: {
+            impact: input.task.agents.impact,
+            ...(input.task.agents.target
+              ? { target: input.task.agents.target }
+              : {}),
+          },
+        });
       }
       if (result.kind !== "sealed-candidate") {
         return { kind: "retryable", code: "candidate-diff-invalid" };
@@ -1841,7 +1892,7 @@ export function registerWorkflowControl(
       receiptHash: { type: "string" },
       routeId: { type: "string" },
     },
-    required: ["command", "stage"],
+    required: ["command", "stage", "change"],
     additionalProperties: false,
   } as const;
   const PACKET_PARAMETERS = {
@@ -1872,6 +1923,12 @@ export function registerWorkflowControl(
           ? "Private stage-bound Abel workflow control. Accepts durable Implement change commands."
           : "Private stage-bound Abel packet control. Accepts bounded Design and Diagnose packet operations.",
       executionMode: "parallel",
+      ...(kind === "command"
+        ? {
+            prepareArguments: (args: unknown) =>
+              canonicalizeControlCommandToolInput(args) as never,
+          }
+        : {}),
       parameters:
         kind === "command" ? CONTROL_COMMAND_PARAMETERS : PACKET_PARAMETERS,
       async execute(
@@ -2004,7 +2061,9 @@ export function registerWorkflowControl(
             ...(usage === undefined ? {} : { usage }),
           };
         }
-        const validation = validateControlCommand(params);
+        const validation = validateControlCommand(
+          canonicalizeControlCommandToolInput(params),
+        );
         if (!validation.ok) {
           const error = new Error(validation.code);
           error.name = "ControlCommandError";

package/src/run-store.ts

@@ -917,7 +917,23 @@ export class RunStore {
     code?: string;
     lease?: OperationLease;
   }): RunProjection {
+    return this.transitionAtomically(input, () => {});
+  }
+
+  transitionAtomically(
+    input: {
+      runId: string;
+      to: RunState;
+      operationId: string;
+      code?: string;
+      lease?: OperationLease;
+    },
+    write: (database: DatabaseSync) => void,
+  ): RunProjection {
     requireIdentifier(input.operationId, "operation-id");
+    if (typeof write !== "function") {
+      throw new Error("state-transition-write-invalid");
+    }
     return this.#transaction(() => {
       if (input.lease) {
         if (input.lease.runId !== input.runId) throw new Error("lease-fenced");
@@ -935,6 +951,7 @@ export class RunStore {
         to: input.to,
         ...(input.code ? { code: input.code } : {}),
       });
+      write(this.#database);
       this.#recordOperation(
         input.runId,
         input.operationId,

package/src/submit-tool.ts

@@ -9,6 +9,7 @@ import {
   type CandidateFailure,
   type DiffResult,
   type EvidenceResult,
+  isAgentsPath,
   isValidRelativePath,
   type SubmitFinalCategory,
   type SubmitSchemaState,
@@ -144,15 +145,57 @@ function candidateArtifactSchema(candidateId: string) {
         code: Type.Union([
           Type.Literal("approved-context-needed"),
           Type.Literal("task-split-needed"),
-          Type.Literal("boundary-review-needed"),
         ]),
-        refs: Type.Array(Type.String(), { maxItems: 32 }),
+        refs: Type.Array(
+          Type.Union([
+            Type.String(),
+            Type.Object(
+              {
+                kind: Type.Literal("requested-path"),
+                path: Type.String(),
+                access: Type.Union([
+                  Type.Literal("read"),
+                  Type.Literal("write"),
+                ]),
+              },
+              { additionalProperties: false },
+            ),
+            Type.Object(
+              {
+                kind: Type.Literal("source-citation"),
+                path: Type.String(),
+                line: Type.Integer({ minimum: 1 }),
+              },
+              { additionalProperties: false },
+            ),
+            Type.Object(
+              {
+                kind: Type.Literal("contract-diagnostic"),
+                ref: Type.String(),
+              },
+              { additionalProperties: false },
+            ),
+          ]),
+          { minItems: 1, maxItems: 32 },
+        ),
       },
       { additionalProperties: false },
     ),
   ]);
 }
 
+export type CandidateContextRequestCode =
+  | "approved-context-needed"
+  | "task-split-needed"
+  | "boundary-review-needed";
+
+export type CandidateContextRef =
+  | { kind: "requested-path"; path: string; access: "read" | "write" }
+  | { kind: "source-citation"; path: string; line: number }
+  | { kind: "contract-diagnostic"; ref: string };
+
+export type CandidateContextRefInput = string | CandidateContextRef;
+
 export type CandidateArtifactSubmissionResult =
   | {
       kind: "sealed-candidate";
@@ -166,11 +209,8 @@ export type CandidateArtifactSubmissionResult =
   | {
       kind: "context-request";
       candidateId: string;
-      code:
-        | "approved-context-needed"
-        | "task-split-needed"
-        | "boundary-review-needed";
-      refs: string[];
+      code: CandidateContextRequestCode;
+      refs: CandidateContextRef[];
     };
 
 export type CandidateContextRequest = Extract<
@@ -178,18 +218,114 @@ export type CandidateContextRequest = Extract<
   { kind: "context-request" }
 >;
 
+export interface CandidateContextBoundary {
+  phase: "red" | "green" | "refactor";
+  readPaths: readonly string[];
+  writePaths: readonly string[];
+  deletePaths?: readonly string[];
+  taskPaths: readonly string[];
+  redWritePaths: readonly string[];
+  agents: {
+    impact: "none" | "update-existing" | "create-index" | "remove-index";
+    target?: string;
+  };
+}
+
 export interface ClassifiedCandidateContextRequest {
-  kind: "paused" | "approval-needed";
+  kind: "paused" | "retryable" | "approval-needed";
   code:
     | "approved-context-needed"
     | "task-split-needed"
-    | "boundary-review-needed";
+    | "boundary-review-needed"
+    | "red-artifact-constraint"
+    | "agents-context-needed"
+    | "agents-write-parent-owned"
+    | "agents-contract-insufficient";
   contextRequest: {
-    code: CandidateContextRequest["code"];
-    refs: string[];
+    code: CandidateContextRequestCode;
+    refs: CandidateContextRef[];
   };
 }
 
+const LEGACY_CITATION = /^(.*):(\d+)$/u;
+const LEGACY_DIAGNOSTIC =
+  /^(?:phase-contract|task-contract|sealed-contract|workflow-contract)\.[a-z0-9._-]+$/iu;
+
+function validDiagnosticRef(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= 512 &&
+    value.trim() === value &&
+    !/[\r\n\0]/u.test(value)
+  );
+}
+
+function normalizeCandidateContextRef(
+  input: CandidateContextRefInput,
+): CandidateContextRef {
+  if (typeof input === "string") {
+    const citation = LEGACY_CITATION.exec(input);
+    if (citation && isValidRelativePath(citation[1])) {
+      const line = Number(citation[2]);
+      if (Number.isSafeInteger(line) && line >= 1) {
+        return { kind: "source-citation", path: citation[1], line };
+      }
+    }
+    if (LEGACY_DIAGNOSTIC.test(input)) {
+      return { kind: "contract-diagnostic", ref: input };
+    }
+    if (!isValidRelativePath(input)) {
+      throw new Error("context request refs are invalid");
+    }
+    return { kind: "requested-path", path: input, access: "read" };
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("context request refs are invalid");
+  }
+  if (
+    input.kind === "requested-path" &&
+    Object.keys(input).length === 3 &&
+    isValidRelativePath(input.path) &&
+    (input.access === "read" || input.access === "write")
+  ) {
+    return { ...input };
+  }
+  if (
+    input.kind === "source-citation" &&
+    Object.keys(input).length === 3 &&
+    isValidRelativePath(input.path) &&
+    Number.isSafeInteger(input.line) &&
+    input.line >= 1
+  ) {
+    return { ...input };
+  }
+  if (
+    input.kind === "contract-diagnostic" &&
+    Object.keys(input).length === 2 &&
+    validDiagnosticRef(input.ref)
+  ) {
+    return { ...input };
+  }
+  throw new Error("context request refs are invalid");
+}
+
+export function normalizeCandidateContextRefs(
+  value: unknown,
+): CandidateContextRef[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 32) {
+    throw new Error("context request refs are invalid");
+  }
+  const refs = value.map((entry) =>
+    normalizeCandidateContextRef(entry as CandidateContextRefInput),
+  );
+  const identities = refs.map((ref) => JSON.stringify(ref));
+  if (new Set(identities).size !== refs.length) {
+    throw new Error("context request refs are invalid");
+  }
+  return refs;
+}
+
 function contextRefWithinBoundary(relative: string, approved: string): boolean {
   return (
     approved === "." ||
@@ -198,23 +334,108 @@ function contextRefWithinBoundary(relative: string, approved: string): boolean {
   );
 }
 
+function normalizedBoundary(
+  boundary: readonly string[] | CandidateContextBoundary,
+): CandidateContextBoundary {
+  if (!Array.isArray(boundary)) return boundary as CandidateContextBoundary;
+  return {
+    phase: "green",
+    readPaths: boundary,
+    writePaths: [],
+    deletePaths: [],
+    taskPaths: boundary,
+    redWritePaths: [],
+    agents: { impact: "none" },
+  };
+}
+
+function pathWithinAny(relative: string, approved: readonly string[]): boolean {
+  return approved.some((path) => contextRefWithinBoundary(relative, path));
+}
+
 export function classifyCandidateContextRequest(
-  request: CandidateContextRequest,
-  approvedPaths: readonly string[],
+  request: {
+    kind: "context-request";
+    candidateId: string;
+    code: CandidateContextRequestCode;
+    refs: readonly CandidateContextRefInput[];
+  },
+  inputBoundary: readonly string[] | CandidateContextBoundary,
 ): ClassifiedCandidateContextRequest {
-  const refs = [...request.refs];
-  const inBoundary =
-    refs.length > 0 &&
-    refs.every((relative) =>
-      approvedPaths.some((approved) =>
-        contextRefWithinBoundary(relative, approved),
+  const refs = normalizeCandidateContextRefs(request.refs);
+  const boundary = normalizedBoundary(inputBoundary);
+  const phasePaths = [
+    ...boundary.readPaths,
+    ...boundary.writePaths,
+    ...(boundary.deletePaths ?? []),
+  ];
+  const requested = refs.filter(
+    (ref): ref is Extract<CandidateContextRef, { kind: "requested-path" }> =>
+      ref.kind === "requested-path",
+  );
+  const ordinaryRequested = requested.filter((ref) => !isAgentsPath(ref.path));
+  const outsideOrdinary = ordinaryRequested.filter(
+    (ref) =>
+      !pathWithinAny(
+        ref.path,
+        ref.access === "write"
+          ? [...boundary.writePaths, ...(boundary.deletePaths ?? [])]
+          : phasePaths,
       ),
+  );
+  const agentsRequested = requested.filter((ref) => isAgentsPath(ref.path));
+  const agentsWrites = agentsRequested.filter((ref) => ref.access === "write");
+  const citedRedArtifacts = refs.filter(
+    (ref): ref is Extract<CandidateContextRef, { kind: "source-citation" }> =>
+      ref.kind === "source-citation" &&
+      pathWithinAny(ref.path, boundary.redWritePaths) &&
+      !pathWithinAny(ref.path, [
+        ...boundary.writePaths,
+        ...(boundary.deletePaths ?? []),
+      ]),
+  );
+  const requestedRedArtifacts = outsideOrdinary.filter(
+    (ref) =>
+      pathWithinAny(ref.path, boundary.redWritePaths) &&
+      pathWithinAny(ref.path, boundary.taskPaths),
+  );
+  const redArtifactConstraint =
+    boundary.phase === "green" &&
+    (citedRedArtifacts.length > 0 || requestedRedArtifacts.length > 0) &&
+    outsideOrdinary.every((ref) => requestedRedArtifacts.includes(ref)) &&
+    agentsRequested.every((ref) => ref.access === "read");
+
+  let classification: Pick<ClassifiedCandidateContextRequest, "kind" | "code">;
+  if (outsideOrdinary.length > 0 && !redArtifactConstraint) {
+    classification = {
+      kind: "approval-needed",
+      code: "boundary-review-needed",
+    };
+  } else if (agentsWrites.length > 0) {
+    const targetMismatch = agentsWrites.some(
+      (ref) =>
+        boundary.agents.impact === "none" ||
+        boundary.agents.target === undefined ||
+        ref.path !== boundary.agents.target,
     );
-  const approvalNeeded =
-    !inBoundary || request.code === "boundary-review-needed";
+    classification = targetMismatch
+      ? { kind: "approval-needed", code: "agents-contract-insufficient" }
+      : { kind: "paused", code: "agents-write-parent-owned" };
+  } else if (redArtifactConstraint) {
+    classification = { kind: "retryable", code: "red-artifact-constraint" };
+  } else if (agentsRequested.length > 0) {
+    classification = { kind: "paused", code: "agents-context-needed" };
+  } else {
+    classification = {
+      kind: "paused",
+      code:
+        request.code === "task-split-needed"
+          ? "task-split-needed"
+          : "approved-context-needed",
+    };
+  }
   return {
-    kind: approvalNeeded ? "approval-needed" : "paused",
-    code: inBoundary ? request.code : "boundary-review-needed",
+    ...classification,
     contextRequest: {
       code: request.code,
       refs,
@@ -391,18 +612,17 @@ export function createCandidateArtifactTool(
           terminate: true,
         };
       }
-      const refs = value.refs as string[];
-      if (
-        refs.some((relative) => !isValidRelativePath(relative)) ||
-        new Set(refs).size !== refs.length
-      ) {
+      let refs: CandidateContextRef[];
+      try {
+        refs = normalizeCandidateContextRefs(value.refs);
+      } catch (error) {
         schema = "invalid";
         failure = {
           kind: "artifact",
           code: "invalid-structural-result",
           stage: "structural-submit",
         };
-        throw new Error("context request refs are invalid");
+        throw error;
       }
       result = {
         kind: "context-request",
@@ -411,7 +631,7 @@ export function createCandidateArtifactTool(
           CandidateArtifactSubmissionResult,
           { kind: "context-request" }
         >["code"],
-        refs: [...refs],
+        refs,
       };
       return {
         content: [