@abelxiaoxing/cadence 1.3.0 → 1.4.1

package/src/evidence-draft.ts

@@ -0,0 +1,122 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { AGENTS_IMPACTS, RELATIVE_PATH_PATTERN } from "./contracts.ts";
+
+// The authoring boundary is smaller than the sealed EvidenceResult. Only
+// code-owned identity and explicitly advisory fields may be omitted.
+const advisoryStrings = () => Type.Optional(Type.Array(Type.String()));
+const relativePath = () =>
+  Type.String({
+    pattern: RELATIVE_PATH_PATTERN,
+    minLength: 1,
+    maxLength: 512,
+    description:
+      "Canonical workspace-relative path or module slug; no absolute paths, ./, .., backslashes, or trailing slash.",
+  });
+const pathSet = (minItems = 0) =>
+  Type.Array(relativePath(), { uniqueItems: true, minItems });
+
+export function evidenceDraftSchema(requestId: string, role: string) {
+  const identity = {
+    id: Type.Optional(
+      Type.Literal(requestId, {
+        description:
+          "Omit: bound by the submit tool. If supplied, must match this request.",
+      }),
+    ),
+    role: Type.Optional(Type.Literal(role)),
+    kind: Type.Optional(Type.Literal("evidence")),
+  };
+  return role === "design-explorer"
+    ? Type.Object(
+        {
+          ...identity,
+          packet_id: Type.Optional(Type.Literal(requestId)),
+          module_name: relativePath(),
+          scope: pathSet(1),
+          files_read: pathSet(),
+          evidence: Type.Array(
+            Type.Object(
+              {
+                claim: Type.String({ minLength: 1 }),
+                path: relativePath(),
+                line_start: Type.Integer({ minimum: 1 }),
+                line_end: Type.Integer({
+                  minimum: 1,
+                  description:
+                    "Inclusive end line, greater than or equal to line_start.",
+                }),
+              },
+              { additionalProperties: false },
+            ),
+          ),
+          existing_structures: advisoryStrings(),
+          existing_conventions: advisoryStrings(),
+          constraints_discovered: Type.Array(Type.String()),
+          open_questions: Type.Array(Type.String()),
+          dependencies: advisoryStrings(),
+          write_set_hints: Type.Optional(pathSet()),
+          validation_hints: advisoryStrings(),
+          agents_impact_hints: advisoryStrings(),
+          risks: Type.Array(Type.String()),
+          success_criteria_hints: advisoryStrings(),
+        },
+        { additionalProperties: false },
+      )
+    : Type.Object(
+        {
+          ...identity,
+          conclusions: Type.Array(Type.String()),
+          citations: Type.Array(
+            Type.Object(
+              { path: relativePath(), lines: Type.String() },
+              { additionalProperties: false },
+            ),
+          ),
+          constraints: Type.Array(Type.String()),
+          dependencies: advisoryStrings(),
+          risks: Type.Array(Type.String()),
+          blockingQuestions: Type.Array(Type.String()),
+          hints: Type.Optional(
+            Type.Object(
+              {
+                writeSet: pathSet(),
+                verification: Type.String(),
+                agentsImpact: StringEnum(AGENTS_IMPACTS),
+              },
+              { additionalProperties: false },
+            ),
+          ),
+        },
+        { additionalProperties: false },
+      );
+}
+
+export function completeEvidenceDraft(
+  value: unknown,
+  requestId: string,
+  role: string,
+): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const draft = value as Record<string, unknown>;
+  const defaults: Record<string, unknown> = {
+    id: requestId,
+    role,
+    kind: "evidence",
+    dependencies: [],
+    ...(role === "design-explorer"
+      ? {
+          packet_id: requestId,
+          existing_structures: [],
+          existing_conventions: [],
+          write_set_hints: [],
+          validation_hints: [],
+          agents_impact_hints: [],
+          success_criteria_hints: [],
+        }
+      : { hints: { writeSet: [], verification: "", agentsImpact: "none" } }),
+  };
+  // Defaults mean "no advisory information supplied", never verified facts or
+  // authority. Explicit wrong values (including null/undefined) survive validation.
+  return { ...defaults, ...draft };
+}

package/src/implement-graph.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonical.ts";
 import {
   type ImplementationPhase,
   type ImplementGraphBoundary,
@@ -16,21 +17,6 @@ import {
   validateVerificationAdapterCapability,
 } from "./verification-capability.ts";
 
-export function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
-  }
-  if (value && typeof value === "object") {
-    const entries = Object.entries(value as Record<string, unknown>)
-      .filter(([, entry]) => entry !== undefined)
-      .sort(([left], [right]) => left.localeCompare(right));
-    return `{${entries
-      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}
-
 export function hashCanonicalValue(value: unknown): string {
   return createHash("sha256").update(canonicalJson(value)).digest("hex");
 }
@@ -92,7 +78,14 @@ function taskPhases(
   task: ImplementTaskBoundary,
 ): Array<[ImplementationPhase, ImplementTaskBoundary["phases"]["red"]]> {
   return [
-    ["red", task.phases.red],
+    ...(!task.verificationMode || task.verificationMode === "behavior"
+      ? [
+          ["red", task.phases.red] as [
+            ImplementationPhase,
+            ImplementTaskBoundary["phases"]["red"],
+          ],
+        ]
+      : []),
     ["green", task.phases.green],
     ...(task.phases.refactor
       ? ([["refactor", task.phases.refactor]] as Array<
@@ -355,6 +348,9 @@ export function assessImplementGraphReadiness(
             taskId: task.taskId,
             phase,
             verificationId,
+            field: `phases.${phase}.verificationInputs`,
+            expectedPaths: [...requiredPaths].sort(),
+            actualPaths: [...boundPaths].sort(),
           }),
         );
       }
@@ -576,3 +572,5 @@ export function assessImplementGraphReadiness(
 
   return { closure, phases, outputs: outputReadiness };
 }
+
+export { canonicalJson } from "./canonical.ts";

package/src/implement-plan.ts

@@ -0,0 +1,70 @@
+import type { ChangeContract } from "./change-contract.ts";
+import type {
+  AgentsImpact,
+  ImplementGraphOutput,
+  ImplementTaskBoundary,
+  PhaseBoundary,
+  StructuredVerificationContract,
+} from "./contracts.ts";
+
+/** Complete execution contracts. No authoring references or defaults cross this boundary. */
+export interface PlanTaskDraft extends Omit<ImplementTaskBoundary, "phases"> {
+  phases: {
+    red: PhaseBoundary;
+    green: PhaseBoundary;
+    refactor?: PhaseBoundary;
+  };
+  affectedVerification: StructuredVerificationContract;
+  repairVerification: StructuredVerificationContract;
+}
+
+export interface PlanVerification {
+  baseline: {
+    target: "task-red-contracts";
+    affected: "task-affected-contracts";
+    fullSuite: StructuredVerificationContract;
+    failureIdentity: "normalized";
+  };
+  change: {
+    affected: "task-affected-contracts";
+    fullSuite: StructuredVerificationContract;
+    postApply: StructuredVerificationContract;
+  };
+  artifactCorrection: {
+    maxAttempts: number;
+  };
+  repair: {
+    maxAttempts: number;
+    inBoundaryOnly: true;
+    approvalOnBoundaryExpansion: true;
+    attribution: ["pre-existing", "introduced", "unresolved", "environment"];
+  };
+  agentsCheckpoint: {
+    required: boolean;
+    verification: StructuredVerificationContract | null;
+    operations: PlanAgentsCheckpointOperation[];
+  };
+}
+
+export interface PlanAgentsCheckpointOperation {
+  target: string;
+  impact: Exclude<AgentsImpact, "none">;
+  taskIds: string[];
+  managedBlock: string | null;
+}
+
+export interface PlanTracking {
+  path: "tasks.md";
+  format: "markdown-checkbox";
+  taskIds: string[];
+  completionOwner: "parent";
+}
+
+export interface ImplementPlan {
+  changeContract?: ChangeContract;
+  changeId: string;
+  tasks: PlanTaskDraft[];
+  outputs: ImplementGraphOutput[];
+  verification: PlanVerification;
+  tracking: PlanTracking;
+}