@abelxiaoxing/cadence 1.4.0 → 1.5.0

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/execution-profile.ts

@@ -0,0 +1,38 @@
+export interface ExecutionProfile {
+  mode: "isolated" | "local-trusted";
+  timeoutMs: number;
+  bwrapPath: string;
+  inheritEnvironment: string[];
+}
+
+/** Operator configuration only. Unknown modes never silently disable isolation. */
+export function executionProfile(
+  env: NodeJS.ProcessEnv = process.env,
+): ExecutionProfile {
+  const mode = env.ABEL_EXECUTION_MODE ?? "isolated";
+  if (mode !== "isolated" && mode !== "local-trusted")
+    throw new Error("execution-mode-invalid");
+  const timeoutMs = Number(env.ABEL_VERIFICATION_TIMEOUT_MS ?? 600_000);
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    timeoutMs > 86_400_000
+  )
+    throw new Error("verification-timeout-invalid");
+  const inheritEnvironment = (env.ABEL_VERIFICATION_ENV ?? "")
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+  if (
+    inheritEnvironment.some((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name))
+  )
+    throw new Error("verification-environment-names-invalid");
+  if (mode === "isolated" && inheritEnvironment.length)
+    throw new Error("verification-environment-requires-trusted-mode");
+  return {
+    mode,
+    timeoutMs,
+    bwrapPath: env.ABEL_BWRAP_PATH ?? "/usr/bin/bwrap",
+    inheritEnvironment,
+  };
+}

package/src/implement-graph.ts

@@ -348,6 +348,9 @@ export function assessImplementGraphReadiness(
             taskId: task.taskId,
             phase,
             verificationId,
+            field: `phases.${phase}.verificationInputs`,
+            expectedPaths: [...requiredPaths].sort(),
+            actualPaths: [...boundPaths].sort(),
           }),
         );
       }

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;
+}