@abelxiaoxing/cadence 1.3.0 → 1.4.0

package/src/isolation-backend.ts

@@ -15,6 +15,7 @@ export interface IsolationRunInput {
   mounts?: IsolationMount[];
   environment?: Record<string, string>;
   signal?: AbortSignal;
+  outputWitness?: string;
 }
 
 export type IsolationRunResult =
@@ -24,6 +25,11 @@ export type IsolationRunResult =
       exitCode: number;
       stdout: string;
       stderr: string;
+      outputWitnessMatched?: boolean;
+      logs: {
+        stdout: { bytes: number; truncated: boolean };
+        stderr: { bytes: number; truncated: boolean };
+      };
     }
   | {
       ok: false;
@@ -31,14 +37,13 @@ export type IsolationRunResult =
       code:
         | "isolation-backend-unavailable"
         | "isolation-backend-launch-failed"
-        | "isolation-execution-timeout"
-        | "isolation-output-limit-exceeded";
+        | "isolation-execution-timeout";
     }
   | { ok: false; state: "cancelled"; code: "cancelled" };
 
 export const ISOLATION_RUN_LIMITS = Object.freeze({
   timeoutMs: 10 * 60_000,
-  maxOutputBytes: 1024 * 1024,
+  maxOutputBytes: 256 * 1024,
   terminateGraceMs: 1_000,
 });
 
@@ -64,6 +69,59 @@ function validEnvironmentName(name: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(name);
 }
 
+/** Retains independent head/tail copies; discarded chunks never stay referenced. */
+class BoundedLog {
+  bytes = 0;
+  #head = Buffer.alloc(0);
+  #tail = Buffer.alloc(0);
+  readonly limit: number;
+  readonly #witness?: Buffer;
+  #witnessTail = Buffer.alloc(0);
+  witnessMatched = false;
+  constructor(limit: number, witness?: string) {
+    this.limit = limit;
+    if (witness) this.#witness = Buffer.from(witness);
+  }
+  append(chunk: Buffer | string): void {
+    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    this.bytes += input.byteLength;
+    if (this.#witness && !this.witnessMatched) {
+      const searchable = Buffer.concat([this.#witnessTail, input]);
+      this.witnessMatched = searchable.includes(this.#witness);
+      this.#witnessTail = this.witnessMatched
+        ? Buffer.alloc(0)
+        : Buffer.from(
+            searchable.subarray(
+              Math.max(0, searchable.length - this.#witness.length + 1),
+            ),
+          );
+    }
+    const headLimit = Math.ceil(this.limit / 2);
+    const take = Math.min(input.length, headLimit - this.#head.length);
+    if (take > 0)
+      this.#head = Buffer.concat([this.#head, input.subarray(0, take)]);
+    const rest = input.subarray(take);
+    const tailLimit = this.limit - headLimit;
+    if (rest.length && tailLimit) {
+      this.#tail =
+        rest.length >= tailLimit
+          ? Buffer.from(rest.subarray(-tailLimit))
+          : Buffer.concat([
+              this.#tail.subarray(
+                Math.max(0, this.#tail.length + rest.length - tailLimit),
+              ),
+              rest,
+            ]);
+    }
+  }
+  text(): string {
+    return Buffer.concat([this.#head, this.#tail]).toString("utf8");
+  }
+  metadata() {
+    return { bytes: this.bytes, truncated: this.bytes > this.limit };
+  }
+}
+
 /** Linux isolation capability. Lack of Bubblewrap is a pause, never a fallback. */
 export class BubblewrapIsolationBackend {
   readonly #bwrapPath: string;
@@ -103,6 +161,13 @@ export class BubblewrapIsolationBackend {
   }
 
   async run(input: IsolationRunInput): Promise<IsolationRunResult> {
+    if (
+      input.outputWitness !== undefined &&
+      (typeof input.outputWitness !== "string" ||
+        input.outputWitness.length < 1 ||
+        input.outputWitness.length > 512)
+    )
+      throw new Error("isolation-output-witness-invalid");
     if (!(await this.available())) {
       return {
         ok: false,
@@ -165,9 +230,8 @@ export class BubblewrapIsolationBackend {
 
     return new Promise((resolve) => {
       let settled = false;
-      const stdout: Buffer[] = [];
-      const stderr: Buffer[] = [];
-      let capturedBytes = 0;
+      const stdout = new BoundedLog(this.#maxOutputBytes, input.outputWitness);
+      const stderr = new BoundedLog(this.#maxOutputBytes, input.outputWitness);
       let child: ReturnType<typeof spawn>;
       let executionTimer: ReturnType<typeof setTimeout> | undefined;
       let killTimer: ReturnType<typeof setTimeout> | undefined;
@@ -207,21 +271,11 @@ export class BubblewrapIsolationBackend {
         });
         return;
       }
-      const capture = (destination: Buffer[], chunk: Buffer | string): void => {
-        if (settled || terminationResult) return;
-        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        const remaining = this.#maxOutputBytes - capturedBytes;
-        if (remaining > 0) destination.push(bytes.subarray(0, remaining));
-        if (bytes.byteLength > remaining) {
-          capturedBytes = this.#maxOutputBytes;
-          terminate({
-            ok: false,
-            state: "paused",
-            code: "isolation-output-limit-exceeded",
-          });
-          return;
-        }
-        capturedBytes += bytes.byteLength;
+      const capture = (
+        destination: BoundedLog,
+        chunk: Buffer | string,
+      ): void => {
+        if (!settled && !terminationResult) destination.append(chunk);
       };
       child.stdout?.on("data", (chunk: Buffer | string) => {
         capture(stdout, chunk);
@@ -244,8 +298,15 @@ export class BubblewrapIsolationBackend {
             ok: true,
             state: "completed",
             exitCode: code ?? 1,
-            stdout: Buffer.concat(stdout).toString("utf8"),
-            stderr: Buffer.concat(stderr).toString("utf8"),
+            stdout: stdout.text(),
+            stderr: stderr.text(),
+            logs: { stdout: stdout.metadata(), stderr: stderr.metadata() },
+            ...(input.outputWitness
+              ? {
+                  outputWitnessMatched:
+                    stdout.witnessMatched || stderr.witnessMatched,
+                }
+              : {}),
           },
         );
       });

package/src/package-delivery.ts

@@ -0,0 +1,486 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { isValidRelativePath } from "./contracts.ts";
+import {
+  assessDeliveryTraceability,
+  compileImplementPlan,
+  DeliveryValidationError,
+  type GateApprovalProof,
+  parseGateAReceipt,
+  parseImplementPlan,
+  parseReadyReceipt,
+} from "./delivery-compiler.ts";
+import { canonicalJson, hashCanonicalValue } from "./implement-graph.ts";
+import {
+  inspectOpenSpecDelivery,
+  type OpenSpecCliOptions,
+  type OpenSpecDeliveryInspection,
+} from "./openspec-cli.ts";
+import { observeSafePath } from "./safe-path.ts";
+import type {
+  WorkflowAvailableDelivery,
+  WorkflowDeliverySource,
+} from "./workflow-engine.ts";
+
+function sha256(value: Uint8Array | string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export interface PackageDeliverySourceOptions {
+  inspectOpenSpec?: (
+    consumerRoot: string,
+    change: string,
+    options?: OpenSpecCliOptions,
+  ) => Promise<OpenSpecDeliveryInspection>;
+  verifyGateProof?: (input: {
+    change: string;
+    gate: "gate-a" | "gate-b";
+    proof: GateApprovalProof;
+  }) => boolean;
+  verifyFinalizedDelivery?: (input: {
+    change: string;
+    deliveryRevision: number;
+    receiptHash: string;
+    gateA: GateApprovalProof;
+    gateB: GateApprovalProof;
+    planCanonicalHash: string;
+  }) => boolean;
+}
+
+export interface PackageWorkflowDeliverySource extends WorkflowDeliverySource {
+  discoverLatest(input: {
+    stage: "abel-implement";
+    change: string;
+  }): Promise<WorkflowAvailableDelivery | undefined>;
+}
+
+function proofVerified(verify: () => boolean): boolean {
+  try {
+    return verify() === true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizedTrackingArtifact(
+  bytes: Uint8Array,
+  taskIds: readonly string[],
+): Buffer | undefined {
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return undefined;
+  }
+  const identities = taskIds.map((taskId) => ({
+    taskId,
+    pattern: new RegExp(
+      `(?:^|[^A-Za-z0-9._:-])${taskId.replace(
+        /[.*+?^${}()|[\]\\]/gu,
+        "\\$&",
+      )}(?![A-Za-z0-9._:-])`,
+      "u",
+    ),
+    matches: 0,
+  }));
+  const normalized = text
+    .split(/(?<=\n)/u)
+    .map((segment) => {
+      const line = segment.endsWith("\n") ? segment.slice(0, -1) : segment;
+      if (!/^\s*-\s+\[[ xX]\]/u.test(line)) return segment;
+      const matching = identities.filter(({ pattern }) => pattern.test(line));
+      if (matching.length !== 1) return segment;
+      matching[0].matches += 1;
+      return segment.replace(/^(\s*-\s+)\[[xX]\]/u, "$1[ ]");
+    })
+    .join("");
+  if (identities.some(({ matches }) => matches !== 1)) return undefined;
+  return Buffer.from(normalized, "utf8");
+}
+
+function readPackageDeliveryFile(
+  root: string,
+  relative: string,
+  maximumBytes = PACKAGE_DELIVERY_MAX_BYTES,
+): Buffer {
+  const observation = observeSafePath(root, relative);
+  if (observation.kind !== "file") {
+    throw new Error("delivery-file-unavailable");
+  }
+  const target = path.join(root, ...relative.split("/"));
+  const stat = lstatSync(target);
+  if (stat.size < 1 || stat.size > maximumBytes) {
+    throw new Error("delivery-file-size-invalid");
+  }
+  return readFileSync(target);
+}
+
+export function packageDeliverySource(
+  consumerRoot: string,
+  options: PackageDeliverySourceOptions = {},
+): PackageWorkflowDeliverySource {
+  const inspect = options.inspectOpenSpec ?? inspectOpenSpecDelivery;
+  const verifyGateProof = options.verifyGateProof;
+  const verifyFinalizedDelivery = options.verifyFinalizedDelivery;
+  return {
+    async discoverLatest(input) {
+      if (
+        input.stage !== "abel-implement" ||
+        !verifyGateProof ||
+        !verifyFinalizedDelivery
+      ) {
+        return undefined;
+      }
+      try {
+        const changeRoot = `openspec/changes/${input.change}`;
+        const receiptBytes = readPackageDeliveryFile(
+          consumerRoot,
+          `${changeRoot}/ready.yaml`,
+          4 * 1024 * 1024,
+        );
+        const receipt = parseReadyReceipt(receiptBytes, {
+          allowLegacyOrder: true,
+        });
+        if (receipt.change !== input.change) return undefined;
+        const gateABytes = readPackageDeliveryFile(
+          consumerRoot,
+          `${changeRoot}/${receipt.approvals.gateA.path}`,
+          4 * 1024 * 1024,
+        );
+        if (sha256(gateABytes) !== receipt.approvals.gateA.rawSha256) {
+          return undefined;
+        }
+        const gateA = parseGateAReceipt(gateABytes, { allowLegacyOrder: true });
+        if (
+          gateA.change !== receipt.change ||
+          gateA.schema !== receipt.schema ||
+          !proofVerified(() =>
+            verifyGateProof({
+              change: input.change,
+              gate: "gate-a",
+              proof: gateA.approval,
+            }),
+          ) ||
+          !proofVerified(() =>
+            verifyGateProof({
+              change: input.change,
+              gate: "gate-b",
+              proof: receipt.approvals.gateB,
+            }),
+          )
+        ) {
+          return undefined;
+        }
+        const receiptHash = sha256(receiptBytes);
+        if (
+          !proofVerified(() =>
+            verifyFinalizedDelivery({
+              change: input.change,
+              deliveryRevision: receipt.deliveryRevision,
+              receiptHash,
+              gateA: gateA.approval,
+              gateB: receipt.approvals.gateB,
+              planCanonicalHash: receipt.plan.canonicalHash,
+            }),
+          )
+        ) {
+          return undefined;
+        }
+        return {
+          deliveryRevision: receipt.deliveryRevision,
+          receiptHash,
+        };
+      } catch {
+        return undefined;
+      }
+    },
+    async load(input) {
+      if (input.stage !== "abel-implement") {
+        throw new DeliveryValidationError(["delivery-stage-invalid"]);
+      }
+      const changeRoot = `openspec/changes/${input.change}`;
+      const receiptRelative = `${changeRoot}/ready.yaml`;
+      const planRelative = `${changeRoot}/implement-plan.json`;
+      let receiptBytes: Buffer;
+      try {
+        receiptBytes = readPackageDeliveryFile(
+          consumerRoot,
+          receiptRelative,
+          4 * 1024 * 1024,
+        );
+      } catch {
+        throw new DeliveryValidationError(["delivery-receipt-unavailable"]);
+      }
+      let receipt: ReturnType<typeof parseReadyReceipt>;
+      try {
+        receipt = parseReadyReceipt(receiptBytes, { allowLegacyOrder: true });
+      } catch {
+        throw new DeliveryValidationError([
+          "delivery-receipt-invalid",
+          "delivery-recompile-required",
+        ]);
+      }
+      const diagnostics = new Set<string>();
+      if (receipt.change !== input.change) {
+        diagnostics.add("delivery-change-mismatch");
+      }
+      const receiptHash = sha256(receiptBytes);
+      if (
+        (input.deliveryRevision !== undefined &&
+          input.deliveryRevision !== receipt.deliveryRevision) ||
+        (input.receiptHash !== undefined && input.receiptHash !== receiptHash)
+      ) {
+        diagnostics.add("delivery-revision-mismatch");
+      }
+
+      let inspection: OpenSpecDeliveryInspection | undefined;
+      try {
+        inspection = await inspect(consumerRoot, input.change, {
+          signal: input.signal,
+        });
+      } catch {
+        diagnostics.add("delivery-openspec-unavailable");
+      }
+      input.signal?.throwIfAborted();
+      if (inspection) {
+        if (!inspection.strictValid) {
+          diagnostics.add("delivery-openspec-strict-invalid");
+        }
+        if (!inspection.planningComplete) {
+          diagnostics.add("delivery-openspec-incomplete");
+        }
+        if (inspection.schema !== receipt.schema) {
+          diagnostics.add("delivery-schema-mismatch");
+        }
+      }
+
+      let gateABytes: Buffer | undefined;
+      let gateA: ReturnType<typeof parseGateAReceipt> | undefined;
+      try {
+        gateABytes = readPackageDeliveryFile(
+          consumerRoot,
+          `${changeRoot}/${receipt.approvals.gateA.path}`,
+          4 * 1024 * 1024,
+        );
+        if (sha256(gateABytes) !== receipt.approvals.gateA.rawSha256) {
+          diagnostics.add("delivery-gate-a-hash-mismatch");
+        }
+        gateA = parseGateAReceipt(gateABytes, { allowLegacyOrder: true });
+        if (
+          gateA.change !== receipt.change ||
+          gateA.schema !== receipt.schema
+        ) {
+          diagnostics.add("delivery-gate-a-binding-mismatch");
+        }
+      } catch {
+        diagnostics.add("delivery-gate-a-invalid");
+      }
+
+      const artifactBytes = new Map<string, Buffer>();
+      const artifactHashes = new Map(
+        receipt.artifacts.map((artifact) => [
+          artifact.path,
+          artifact.rawSha256,
+        ]),
+      );
+      for (const artifact of receipt.artifacts) {
+        try {
+          const bytes = readPackageDeliveryFile(
+            consumerRoot,
+            `${changeRoot}/${artifact.path}`,
+          );
+          artifactBytes.set(artifact.path, bytes);
+          if (
+            artifact.path !== receipt.traceability.taskPath &&
+            sha256(bytes) !== artifact.rawSha256
+          ) {
+            diagnostics.add(`delivery-artifact-hash-mismatch:${artifact.path}`);
+          }
+        } catch {
+          diagnostics.add(`delivery-artifact-unavailable:${artifact.path}`);
+        }
+      }
+      if (inspection) {
+        const covered = new Set(receipt.artifacts.map((entry) => entry.path));
+        const expected = new Set(inspection.artifactPaths);
+        for (const relative of expected) {
+          if (!isValidRelativePath(relative) || !covered.has(relative)) {
+            diagnostics.add(`delivery-artifact-unbound:${relative}`);
+          }
+        }
+        for (const relative of covered) {
+          if (!expected.has(relative)) {
+            diagnostics.add(`delivery-artifact-not-in-openspec:${relative}`);
+          }
+        }
+      }
+      if (gateA) {
+        if (!verifyGateProof) {
+          diagnostics.add("delivery-gate-proof-verifier-unavailable");
+        } else if (
+          !proofVerified(() =>
+            verifyGateProof({
+              change: input.change,
+              gate: "gate-a",
+              proof: gateA.approval,
+            }),
+          )
+        ) {
+          diagnostics.add("delivery-gate-a-proof-invalid");
+        }
+        for (const artifact of gateA.artifacts) {
+          if (artifactHashes.get(artifact.path) !== artifact.rawSha256) {
+            diagnostics.add(
+              `delivery-gate-a-artifact-mismatch:${artifact.path}`,
+            );
+          }
+        }
+      }
+      if (
+        verifyGateProof &&
+        !proofVerified(() =>
+          verifyGateProof({
+            change: input.change,
+            gate: "gate-b",
+            proof: receipt.approvals.gateB,
+          }),
+        )
+      ) {
+        diagnostics.add("delivery-gate-b-proof-invalid");
+      }
+      if (gateA) {
+        if (!verifyFinalizedDelivery) {
+          diagnostics.add("delivery-finalization-verifier-unavailable");
+        } else if (
+          !proofVerified(() =>
+            verifyFinalizedDelivery({
+              change: input.change,
+              deliveryRevision: receipt.deliveryRevision,
+              receiptHash,
+              gateA: gateA.approval,
+              gateB: receipt.approvals.gateB,
+              planCanonicalHash: receipt.plan.canonicalHash,
+            }),
+          )
+        ) {
+          diagnostics.add("delivery-finalization-proof-invalid");
+        }
+      }
+
+      let plan: ReturnType<typeof parseImplementPlan> | undefined;
+      let planBytes: Buffer | undefined;
+      try {
+        planBytes = readPackageDeliveryFile(consumerRoot, planRelative);
+        plan = parseImplementPlan(planBytes, { allowLegacyOrder: true });
+      } catch {
+        diagnostics.add("delivery-plan-invalid");
+      }
+      if (plan && planBytes) {
+        if (plan.changeId !== input.change) {
+          diagnostics.add("delivery-plan-change-mismatch");
+        }
+        let compiled: ReturnType<typeof compileImplementPlan> | undefined;
+        try {
+          compiled = compileImplementPlan(plan, { consumerRoot });
+        } catch {
+          diagnostics.add("delivery-verification-closure-invalid");
+        }
+        if (
+          receipt.plan.path !== "implement-plan.json" ||
+          receipt.plan.rawSha256 !== sha256(planBytes) ||
+          receipt.plan.canonicalHash !== hashCanonicalValue(plan)
+        ) {
+          diagnostics.add("delivery-plan-binding-invalid");
+        }
+        if (
+          compiled &&
+          canonicalJson(compiled.closure) !==
+            canonicalJson(receipt.verificationClosure)
+        ) {
+          diagnostics.add("delivery-verification-closure-mismatch");
+        }
+      }
+
+      if (plan) {
+        const tasksBytes = artifactBytes.get(receipt.traceability.taskPath);
+        const expectedTasksHash = artifactHashes.get(
+          receipt.traceability.taskPath,
+        );
+        if (
+          tasksBytes &&
+          expectedTasksHash &&
+          sha256(tasksBytes) !== expectedTasksHash
+        ) {
+          const normalized = normalizedTrackingArtifact(
+            tasksBytes,
+            plan.tracking.taskIds,
+          );
+          if (!normalized || sha256(normalized) !== expectedTasksHash) {
+            diagnostics.add(
+              `delivery-artifact-hash-mismatch:${receipt.traceability.taskPath}`,
+            );
+          }
+        }
+        const specs = [...artifactBytes]
+          .filter(
+            ([relative]) =>
+              relative.startsWith("specs/") && relative.endsWith("/spec.md"),
+          )
+          .flatMap(([relative, bytes]) => {
+            try {
+              return [
+                {
+                  path: relative,
+                  text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+                },
+              ];
+            } catch {
+              diagnostics.add(`delivery-artifact-encoding-invalid:${relative}`);
+              return [];
+            }
+          });
+        if (!tasksBytes || specs.length === 0) {
+          diagnostics.add("delivery-traceability-input-unavailable");
+        } else {
+          try {
+            const traceability = assessDeliveryTraceability({
+              tasksMarkdown: new TextDecoder("utf-8", { fatal: true }).decode(
+                tasksBytes,
+              ),
+              specs,
+              plan,
+            });
+            if (!traceability.ok) {
+              for (const diagnostic of traceability.diagnostics) {
+                diagnostics.add(diagnostic);
+              }
+            } else if (
+              canonicalJson(traceability.value) !==
+              canonicalJson(receipt.traceability)
+            ) {
+              diagnostics.add("delivery-traceability-binding-mismatch");
+            }
+          } catch {
+            diagnostics.add("delivery-traceability-invalid");
+          }
+        }
+      }
+      if (!plan || !gateA || diagnostics.size > 0) {
+        throw new DeliveryValidationError([...diagnostics]);
+      }
+      return {
+        gate: "gate-b",
+        revision: receipt.deliveryRevision,
+        receiptHash,
+        plan,
+        approvalProofs: {
+          gateA: structuredClone(gateA.approval),
+          gateB: structuredClone(receipt.approvals.gateB),
+        },
+      };
+    },
+  };
+}
+
+const PACKAGE_DELIVERY_MAX_BYTES = 16 * 1024 * 1024;