@abelxiaoxing/cadence 1.1.1 → 1.2.0

package/src/control-contracts.ts

@@ -11,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,52 +23,37 @@ const SHA256 = /^[a-f0-9]{64}$/u;
 interface ControlBase {
   command: ControlCommandName;
   stage: ControlStage;
-}
-
-interface NamedControlBase extends ControlBase {
   change: string;
 }
 
-export interface NamedStartControlCommand extends NamedControlBase {
+export interface StartControlCommand extends ControlBase {
   command: "start";
   operationId: string;
-  provisionalKey?: string;
 }
 
-export interface ProvisionalDesignStartControlCommand 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;
 }
@@ -125,11 +110,10 @@ export function validateControlCommand(
     return { ok: false, code: "invalid-control-command" };
   }
 
-  const common = ["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,
@@ -137,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)
       ) {
@@ -149,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" &&
@@ -195,7 +161,7 @@ export function validateControlCommand(
       if (
         !hasExactKeys(
           value,
-          [...named, "operationId"],
+          [...common, "operationId"],
           ["deliveryRevision", "receiptHash"],
         ) ||
         !validChange(value.change) ||

package/src/design-control.ts

@@ -32,9 +32,10 @@ import type { ResolvedStateRoot } from "./state-root.ts";
 
 const CHANGE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/u;
 const IDENTIFIER = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
-const SHA256 = /^[a-f0-9]{64}$/u;
 const ARTIFACT_SEGMENT = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/iu;
 const MAX_DESIGN_FILE_BYTES = 16 * 1024 * 1024;
+const MAX_DESIGN_REQUIREMENT_BYTES = 64 * 1024;
+const MAX_DESIGN_CONTRACT_BYTES = 256 * 1024;
 
 export interface DesignOpenSpecInspection {
   change: string;
@@ -45,21 +46,47 @@ export interface DesignOpenSpecInspection {
 }
 
 export type DesignControlRequest =
+  | {
+      operation: "start";
+      operationId: string;
+      requirement: string;
+    }
+  | {
+      operation: "start";
+      operationId: string;
+      change: string;
+    }
+  | {
+      operation: "status";
+      runId: string;
+    }
+  | {
+      operation: "bind-change";
+      runId: string;
+      operationId: string;
+      change: string;
+    }
   | {
       operation: "record-decision";
       runId: string;
       operationId: string;
       decisionId: string;
       category: "behavior" | "technical";
-      contractHash: string;
+      contract: string;
       refs: string[];
     }
   | {
       operation: "approve-gate";
       runId: string;
       operationId: string;
-      gate: "gate-a" | "gate-b";
-      contractHash: string;
+      gate: "gate-a";
+      contract: string;
+    }
+  | {
+      operation: "approve-gate";
+      runId: string;
+      operationId: string;
+      gate: "gate-b";
     }
   | {
       operation: "compile-plan";
@@ -121,6 +148,25 @@ function exactKeys(
   );
 }
 
+function normalizedTransientText(value: string): string {
+  return value.replace(/\r\n?/gu, "\n").trim();
+}
+
+function transientHash(domain: string, value: string): string {
+  return createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(normalizedTransientText(value))
+    .digest("hex");
+}
+
+function lifecycleOperationId(kind: string, runId: string): string {
+  return `design-${kind}-${createHash("sha256")
+    .update(runId)
+    .digest("hex")
+    .slice(0, 32)}`;
+}
+
 export function validateDesignControlRequest(
   value: unknown,
 ):
@@ -128,6 +174,37 @@ export function validateDesignControlRequest(
   | { ok: false; code: "invalid-design-control-request" } {
   if (!isRecord(value))
     return { ok: false, code: "invalid-design-control-request" };
+  if (value.operation === "start") {
+    const operationValid =
+      typeof value.operationId === "string" &&
+      IDENTIFIER.test(value.operationId);
+    if (!operationValid)
+      return { ok: false, code: "invalid-design-control-request" };
+    if (
+      exactKeys(value, ["operation", "operationId", "requirement"]) &&
+      typeof value.requirement === "string" &&
+      value.requirement.trim().length > 0 &&
+      Buffer.byteLength(value.requirement, "utf8") <=
+        MAX_DESIGN_REQUIREMENT_BYTES
+    ) {
+      return {
+        ok: true,
+        value: structuredClone(value) as DesignControlRequest,
+      };
+    }
+    return exactKeys(value, ["operation", "operationId", "change"]) &&
+      typeof value.change === "string" &&
+      CHANGE_NAME.test(value.change)
+      ? { ok: true, value: structuredClone(value) as DesignControlRequest }
+      : { ok: false, code: "invalid-design-control-request" };
+  }
+  if (value.operation === "status") {
+    return exactKeys(value, ["operation", "runId"]) &&
+      typeof value.runId === "string" &&
+      IDENTIFIER.test(value.runId)
+      ? { ok: true, value: structuredClone(value) as DesignControlRequest }
+      : { ok: false, code: "invalid-design-control-request" };
+  }
   const commonValid =
     typeof value.runId === "string" &&
     IDENTIFIER.test(value.runId) &&
@@ -135,6 +212,13 @@ export function validateDesignControlRequest(
     IDENTIFIER.test(value.operationId);
   if (!commonValid)
     return { ok: false, code: "invalid-design-control-request" };
+  if (value.operation === "bind-change") {
+    return exactKeys(value, ["operation", "runId", "operationId", "change"]) &&
+      typeof value.change === "string" &&
+      CHANGE_NAME.test(value.change)
+      ? { ok: true, value: structuredClone(value) as DesignControlRequest }
+      : { ok: false, code: "invalid-design-control-request" };
+  }
   if (value.operation === "write-artifact") {
     return exactKeys(value, [
       "operation",
@@ -163,16 +247,22 @@ export function validateDesignControlRequest(
       : { ok: false, code: "invalid-design-control-request" };
   }
   if (value.operation === "approve-gate") {
-    return exactKeys(value, [
-      "operation",
-      "runId",
-      "operationId",
-      "gate",
-      "contractHash",
-    ]) &&
-      (value.gate === "gate-a" || value.gate === "gate-b") &&
-      typeof value.contractHash === "string" &&
-      SHA256.test(value.contractHash)
+    if (value.gate === "gate-b") {
+      return exactKeys(value, ["operation", "runId", "operationId", "gate"])
+        ? { ok: true, value: structuredClone(value) as DesignControlRequest }
+        : { ok: false, code: "invalid-design-control-request" };
+    }
+    return value.gate === "gate-a" &&
+      exactKeys(value, [
+        "operation",
+        "runId",
+        "operationId",
+        "gate",
+        "contract",
+      ]) &&
+      typeof value.contract === "string" &&
+      value.contract.trim().length > 0 &&
+      Buffer.byteLength(value.contract, "utf8") <= MAX_DESIGN_CONTRACT_BYTES
       ? { ok: true, value: structuredClone(value) as DesignControlRequest }
       : { ok: false, code: "invalid-design-control-request" };
   }
@@ -185,14 +275,15 @@ export function validateDesignControlRequest(
     "operationId",
     "decisionId",
     "category",
-    "contractHash",
+    "contract",
     "refs",
   ]) &&
     typeof value.decisionId === "string" &&
     IDENTIFIER.test(value.decisionId) &&
     (value.category === "behavior" || value.category === "technical") &&
-    typeof value.contractHash === "string" &&
-    SHA256.test(value.contractHash) &&
+    typeof value.contract === "string" &&
+    value.contract.trim().length > 0 &&
+    Buffer.byteLength(value.contract, "utf8") <= MAX_DESIGN_CONTRACT_BYTES &&
     Array.isArray(value.refs) &&
     value.refs.every((ref) => typeof ref === "string")
     ? { ok: true, value: structuredClone(value) as DesignControlRequest }
@@ -407,6 +498,12 @@ export class DesignController {
     if (!validation.ok) throw new Error(validation.code);
     const request = validation.value;
     switch (request.operation) {
+      case "start":
+        return this.#start(request);
+      case "status":
+        return this.#statusOutcome(request.runId);
+      case "bind-change":
+        return this.#bindChange(request);
       case "record-decision":
         return this.#journal.recordDecision(request);
       case "approve-gate":
@@ -422,6 +519,116 @@ export class DesignController {
     }
   }
 
+  #statusOutcome(runId: string): Record<string, unknown> {
+    const run = this.#runs.status(runId);
+    if (run.stage !== "abel-design") throw new Error("design-run-invalid");
+    const terminal = ["completed", "discarded", "rejected"].includes(run.state);
+    const design = this.#journal.status(runId);
+    const latestDecisionSequence = design.decisions.reduce(
+      (latest, decision) => Math.max(latest, decision.sequence),
+      0,
+    );
+    const planReadyForGateB =
+      design.gates.gateA.current &&
+      design.plan !== null &&
+      design.plan.sequence >
+        Math.max(
+          design.gates.gateA.approvedSequence ?? 0,
+          latestDecisionSequence,
+        );
+    const canApproveGate =
+      !design.gates.gateA.current ||
+      (planReadyForGateB && !design.gates.gateB.current);
+    const legalActions = terminal
+      ? ["status"]
+      : [
+          "status",
+          "record-decision",
+          ...(canApproveGate ? ["approve-gate"] : []),
+          ...(design.gates.gateA.current && !design.change
+            ? ["bind-change"]
+            : []),
+          ...(design.gates.gateA.current && design.change
+            ? ["write-artifact", "delete-artifact", "compile-plan"]
+            : []),
+          ...(design.change &&
+          design.plan &&
+          design.gates.gateA.current &&
+          design.gates.gateB.current
+            ? ["finalize-delivery"]
+            : []),
+          "finish",
+        ];
+    return {
+      runId: run.runId,
+      stage: run.stage,
+      ...(run.change ? { change: run.change } : {}),
+      state: run.state,
+      completed: run.state === "completed",
+      ...(run.pauseCode ? { pause: { code: run.pauseCode } } : {}),
+      legalActions,
+      design,
+    };
+  }
+
+  #start(request: Extract<DesignControlRequest, { operation: "start" }>) {
+    const fromRequirement = "requirement" in request;
+    const run = this.#runs.startRun({
+      stage: "abel-design",
+      ...(fromRequirement
+        ? {
+            provisionalKey: transientHash(
+              "abel-design-requirement-v1",
+              request.requirement,
+            ),
+          }
+        : { change: request.change }),
+      operationId: request.operationId,
+    });
+    if (run.state === "created") {
+      this.#runs.transition({
+        runId: run.runId,
+        to: "paused",
+        operationId: lifecycleOperationId(
+          fromRequirement ? "await-gate-a" : "await-evidence",
+          run.runId,
+        ),
+        code: fromRequirement
+          ? "design-awaiting-gate-a"
+          : "design-awaiting-evidence",
+      });
+    }
+    return this.#statusOutcome(run.runId);
+  }
+
+  #bindChange(
+    request: Extract<DesignControlRequest, { operation: "bind-change" }>,
+  ) {
+    const run = this.#runs.status(request.runId);
+    if (run.change && run.change !== request.change) {
+      throw new Error("design-operation-conflict");
+    }
+    if (!run.change) {
+      const design = this.#journal.status(request.runId);
+      if (!design.gates.gateA.current)
+        throw new Error("design-gate-a-required");
+    }
+    const bound = this.#runs.bindChange({
+      runId: request.runId,
+      change: request.change,
+      operationId: request.operationId,
+    });
+    if (bound.state === "paused") {
+      this.#runs.transition({
+        runId: request.runId,
+        to: "paused",
+        operationId: lifecycleOperationId("bound", request.runId),
+        code: "design-awaiting-evidence",
+      });
+    }
+    return this.#statusOutcome(request.runId);
+  }
+
   #artifactRun(runId: string): { change: string; gateACurrent: boolean } {
     const status = this.#journal.status(runId);
     if (!status.change) throw new Error("design-change-required");

package/src/design-journal.ts

@@ -11,6 +11,7 @@ const SHA256 = /^[a-f0-9]{64}$/u;
 const IDENTIFIER = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
 const ZERO_HASH = "0".repeat(64);
 const MAX_PLAN_BYTES = 16 * 1024 * 1024;
+const MAX_CONTRACT_BYTES = 256 * 1024;
 
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS design_facts (
@@ -144,6 +145,7 @@ export interface DesignGateProjection {
     | "behavior-decision-changed"
     | "technical-decision-changed"
     | "plan-recompiled"
+    | "gate-a-reapproved"
     | "gate-a-stale"
     | "plan-missing";
 }
@@ -223,6 +225,21 @@ function sha256(value: Uint8Array | string): string {
   return createHash("sha256").update(value).digest("hex");
 }
 
+function contractHash(domain: string, value: string): string {
+  if (
+    typeof value !== "string" ||
+    value.trim().length === 0 ||
+    Buffer.byteLength(value, "utf8") > MAX_CONTRACT_BYTES
+  ) {
+    throw new Error("design-transient-input-invalid");
+  }
+  return createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(value.replace(/\r\n?/gu, "\n").trim())
+    .digest("hex");
+}
+
 function requireIdentifier(value: string, label: string): void {
   if (!IDENTIFIER.test(value)) throw new Error(`invalid-${label}`);
 }
@@ -877,11 +894,14 @@ export class DesignJournal {
     operationId: string;
     decisionId: string;
     category: DecisionCategory;
-    contractHash: string;
+    contract: string;
     refs: string[];
   }): Record<string, unknown> {
     requireIdentifier(input.decisionId, "design-decision-id");
-    requireHash(input.contractHash, "design-decision-hash");
+    const decisionContractHash = contractHash(
+      "abel-design-decision-v1",
+      input.contract,
+    );
     if (input.category !== "behavior" && input.category !== "technical") {
       throw new Error("design-decision-category-invalid");
     }
@@ -890,7 +910,7 @@ export class DesignJournal {
       operation: "record-decision",
       decisionId: input.decisionId,
       category: input.category,
-      contractHash: input.contractHash,
+      contractHash: decisionContractHash,
       refs,
     };
     return this.#transaction(() => {
@@ -909,7 +929,7 @@ export class DesignJournal {
       let decision: DesignDecisionProjection;
       if (
         prior &&
-        prior.contractHash === input.contractHash &&
+        prior.contractHash === decisionContractHash &&
         canonicalJson(prior.refs) === canonicalJson(refs)
       ) {
         decision = prior;
@@ -919,7 +939,7 @@ export class DesignJournal {
           decisionId: input.decisionId,
           category: input.category,
           revision,
-          contractHash: input.contractHash,
+          contractHash: decisionContractHash,
           refs,
         };
         const fact = this.#appendFact(
@@ -980,12 +1000,20 @@ export class DesignJournal {
     return undefined;
   }
 
-  approveGate(input: {
-    runId: string;
-    operationId: string;
-    gate: DesignGate;
-    contractHash: string;
-  }): {
+  approveGate(
+    input:
+      | {
+          runId: string;
+          operationId: string;
+          gate: "gate-a";
+          contract: string;
+        }
+      | {
+          runId: string;
+          operationId: string;
+          gate: "gate-b";
+        },
+  ): {
     operation: "approve-gate";
     runId: string;
     gate: DesignGate;
@@ -994,14 +1022,17 @@ export class DesignJournal {
     if (input.gate !== "gate-a" && input.gate !== "gate-b") {
       throw new Error("design-gate-invalid");
     }
-    requireHash(input.contractHash, "design-decision-hash");
-    const request = {
-      operation: "approve-gate",
-      gate: input.gate,
-      contractHash: input.contractHash,
-    };
+    const gateAContractHash =
+      input.gate === "gate-a"
+        ? contractHash("abel-design-gate-a-v1", input.contract)
+        : undefined;
     return this.#transaction(() => {
       this.#run(input.runId, true);
+      const request = {
+        operation: "approve-gate",
+        gate: input.gate,
+        ...(gateAContractHash ? { contractHash: gateAContractHash } : {}),
+      };
       const replay = this.#operationReplay(
         input.runId,
         input.operationId,
@@ -1012,15 +1043,26 @@ export class DesignJournal {
         return structuredClone(replay) as ReturnType<
           DesignJournal["approveGate"]
         >;
+      let approvedContractHash = gateAContractHash;
       if (input.gate === "gate-b") {
         const current = this.#gateStatus(input.runId);
         if (!current.gateA.current) throw new Error("design-gate-a-required");
         const plan = this.#currentPlanProjection(input.runId);
         if (!plan) throw new Error("design-plan-required");
-        if (plan.canonicalHash !== input.contractHash) {
-          throw new Error("design-gate-b-plan-mismatch");
+        const latestDecisionSequence = this.#facts(input.runId)
+          .filter((fact) => fact.kind === "decision")
+          .at(-1)?.sequence;
+        if (
+          plan.sequence <= (current.gateA.approvedSequence ?? 0) ||
+          (latestDecisionSequence !== undefined &&
+            plan.sequence <= latestDecisionSequence)
+        ) {
+          throw new Error("design-plan-stale");
         }
+        approvedContractHash = plan.canonicalHash;
       }
+      if (!approvedContractHash)
+        throw new Error("design-transient-input-invalid");
       const existing = this.#latestApproval(input.runId, input.gate);
       const currentGate = this.#gateStatus(input.runId)[
         input.gate === "gate-a" ? "gateA" : "gateB"
@@ -1029,7 +1071,7 @@ export class DesignJournal {
       if (
         existing &&
         currentGate.current &&
-        existing.proof.contractHash === input.contractHash
+        existing.proof.contractHash === approvedContractHash
       ) {
         proof = existing.proof;
       } else {
@@ -1037,7 +1079,7 @@ export class DesignJournal {
         const payload = {
           gate: input.gate,
           revision,
-          contractHash: input.contractHash,
+          contractHash: approvedContractHash,
         };
         const fact = this.#appendFact(
           input.runId,
@@ -1047,7 +1089,7 @@ export class DesignJournal {
         );
         proof = {
           revision,
-          contractHash: input.contractHash,
+          contractHash: approvedContractHash,
           recordHash: fact.record_hash,
         };
       }
@@ -1506,6 +1548,11 @@ export class DesignJournal {
         latestTechnical > gateBApproval.sequence
       ) {
         staleReason = "technical-decision-changed";
+      } else if (
+        gateAApproval !== undefined &&
+        gateAApproval.sequence > gateBApproval.sequence
+      ) {
+        staleReason = "gate-a-reapproved";
       } else if (plan && plan.sequence > gateBApproval.sequence) {
         staleReason = "plan-recompiled";
       } else if (!plan) {