@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/dev-delivery/commands/dev-delivery-proof.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { classifyDevDeliveryDelta, createIntegrationDeliveryProof, createNativeProofReuseDecision, createNativeQualificationProof, createProjectCutReplayPlan, createProjectCutReplayProof, createSourceQualificationProof, verifyIntegrationDeliveryProof, verifyNativeProofReuseDecision, verifyNativeQualificationProof, verifyProjectCutReplayProof, verifySourceQualificationProof } from "../dev-delivery-warrant.js";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function jsonFile(file, label) {
+  if (!file) throw new Error(`${label} is required`);
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function jsonList(value, label, { required = false } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value || "[]");
+  } catch (cause) {
+    throw new Error(`${label} must be a JSON array: ${cause.message}`);
+  }
+  if (!Array.isArray(parsed) || (required && parsed.length === 0)) {
+    throw new Error(`${label} must be ${required ? "a non-empty" : "a"} JSON array`);
+  }
+  return parsed;
+}
+
+function boolean(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  return ["1", "true", "yes", "on"].includes(String(value).trim().toLowerCase());
+}
+
+export function devDeliveryProofCliOptions(args = [], environment = process.env) {
+  const [command = "", ...rest] = args;
+  return {
+    command,
+    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
+    protectedBase: flag(rest, "branch", environment.BUILDCHAIN_DEV_DELIVERY_BRANCH || environment.GITHUB_BASE_REF),
+    sourceIdentityRoot: flag(rest, "source-identity-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_IDENTITY_ROOT),
+    sourceHead: flag(rest, "source-head", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_HEAD),
+    sourcePatchRoot: flag(rest, "source-patch-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PATCH_ROOT),
+    planRoot: flag(rest, "plan-root", environment.BUILDCHAIN_DEV_DELIVERY_PLAN_ROOT),
+    closureRoot: flag(rest, "closure-root", environment.BUILDCHAIN_DEV_DELIVERY_CLOSURE_ROOT),
+    dependencyRoot: flag(rest, "dependency-root", environment.BUILDCHAIN_DEV_DELIVERY_DEPENDENCY_ROOT),
+    toolchainRoot: flag(rest, "toolchain-root", environment.BUILDCHAIN_DEV_DELIVERY_TOOLCHAIN_ROOT),
+    environmentRoot: flag(rest, "environment-root", environment.BUILDCHAIN_DEV_DELIVERY_ENVIRONMENT_ROOT),
+    affectedPaths: flag(rest, "affected-paths-json", environment.BUILDCHAIN_DEV_DELIVERY_AFFECTED_PATHS || "[]"),
+    shardEvidenceRoots: flag(rest, "shard-evidence-roots-json", environment.BUILDCHAIN_DEV_DELIVERY_SHARD_EVIDENCE_ROOTS || "[]"),
+    qualifiedAt: flag(rest, "qualified-at", environment.BUILDCHAIN_DEV_DELIVERY_QUALIFIED_AT),
+    qualifiedBase: flag(rest, "qualified-base", environment.BUILDCHAIN_DEV_DELIVERY_QUALIFIED_BASE),
+    nativeExecutionReceiptPath: flag(rest, "native-execution-receipt", environment.BUILDCHAIN_DEV_DELIVERY_NATIVE_EXECUTION_RECEIPT),
+    sourceProofPath: flag(rest, "source-proof", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PROOF),
+    sourceProofRoot: flag(rest, "source-proof-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PROOF_ROOT),
+    warrantResultPath: flag(rest, "warrant-result", environment.BUILDCHAIN_DEV_DELIVERY_WARRANT_RESULT),
+    currentBase: flag(rest, "current-base", environment.BUILDCHAIN_DEV_DELIVERY_CURRENT_BASE),
+    previousBase: flag(rest, "previous-base", environment.BUILDCHAIN_DEV_DELIVERY_PREVIOUS_BASE),
+    replayTree: flag(rest, "replay-tree", environment.BUILDCHAIN_DEV_DELIVERY_REPLAY_TREE),
+    qualificationReceiptPath: flag(rest, "qualification-receipt", environment.BUILDCHAIN_DEV_DELIVERY_QUALIFICATION_RECEIPT),
+    mergeGroupHead: flag(rest, "merge-group-head", environment.BUILDCHAIN_DEV_DELIVERY_MERGE_GROUP_HEAD),
+    mergeGroupTree: flag(rest, "merge-group-tree", environment.BUILDCHAIN_DEV_DELIVERY_MERGE_GROUP_TREE),
+    requiredContextRoots: flag(rest, "required-context-roots-json", environment.BUILDCHAIN_DEV_DELIVERY_REQUIRED_CONTEXT_ROOTS || "[]"),
+    verifiedAt: flag(rest, "verified-at", environment.BUILDCHAIN_DEV_DELIVERY_VERIFIED_AT),
+    pullRequestNumber: flag(rest, "pull-request", environment.BUILDCHAIN_DEV_DELIVERY_PR_NUMBER),
+    changedPaths: flag(rest, "changed-paths-json", environment.BUILDCHAIN_DEV_DELIVERY_CHANGED_PATHS || "[]"),
+    graphKnown: boolean(flag(rest, "graph-known", environment.BUILDCHAIN_DEV_DELIVERY_GRAPH_KNOWN), false),
+    attributionComplete: boolean(flag(rest, "attribution-complete", environment.BUILDCHAIN_DEV_DELIVERY_ATTRIBUTION_COMPLETE), false),
+    renames: flag(rest, "renames-json", environment.BUILDCHAIN_DEV_DELIVERY_RENAMES || "[]"),
+    outputPath: flag(rest, "output", environment.BUILDCHAIN_DEV_DELIVERY_PROOF_OUTPUT || ".buildchain/dev-delivery/proof.json"),
+    json: hasFlag(rest, "json"),
+  };
+}
+
+function sourceProof(options) {
+  return createSourceQualificationProof({
+    repository: options.repository,
+    protectedBase: options.protectedBase,
+    sourceIdentityRoot: options.sourceIdentityRoot,
+    sourceHead: options.sourceHead,
+    sourcePatchRoot: options.sourcePatchRoot,
+    planRoot: options.planRoot,
+    closureRoot: options.closureRoot,
+    dependencyRoot: options.dependencyRoot,
+    toolchainRoot: options.toolchainRoot,
+    affectedPaths: jsonList(options.affectedPaths, "affected paths"),
+    shardEvidenceRoots: jsonList(options.shardEvidenceRoots, "shard evidence roots", { required: true }),
+    qualifiedAt: options.qualifiedAt,
+  });
+}
+
+function activeWarrant(options) {
+  const result = jsonFile(options.warrantResultPath, "Warrant result");
+  const warrant = result.warrant || result.observation?.activeWarrant;
+  if (result.schema !== "kungfu.buildchain.dev-delivery-command-result/v1" || !warrant) {
+    throw new Error("Warrant result does not contain an active Buildchain Delivery Warrant");
+  }
+  return warrant;
+}
+
+export function runDevDeliveryProofCommand(options) {
+  if (options.command === "source") return sourceProof(options);
+  if (options.command === "verify-source") {
+    return verifySourceQualificationProof(jsonFile(options.sourceProofPath, "source proof"));
+  }
+  if (options.command === "classify") {
+    return classifyDevDeliveryDelta({
+      proof: jsonFile(options.sourceProofPath, "source proof"),
+      current: {
+        sourceIdentityRoot: options.sourceIdentityRoot,
+        sourcePatchRoot: options.sourcePatchRoot,
+        planRoot: options.planRoot,
+        closureRoot: options.closureRoot,
+        dependencyRoot: options.dependencyRoot,
+        toolchainRoot: options.toolchainRoot,
+        graphKnown: options.graphKnown,
+        changedPaths: jsonList(options.changedPaths, "changed paths"),
+      },
+    });
+  }
+  if (options.command === "native") {
+    return createNativeQualificationProof({
+      repository: options.repository,
+      protectedBase: options.protectedBase,
+      sourceIdentityRoot: options.sourceIdentityRoot,
+      sourcePatchRoot: options.sourcePatchRoot,
+      planRoot: options.planRoot,
+      closureRoot: options.closureRoot,
+      dependencyRoot: options.dependencyRoot,
+      toolchainRoot: options.toolchainRoot,
+      environmentRoot: options.environmentRoot,
+      sourceHead: options.sourceHead,
+      qualifiedBase: options.qualifiedBase,
+      nativeExecutionReceipt: jsonFile(options.nativeExecutionReceiptPath, "native execution receipt"),
+      affectedPaths: jsonList(options.affectedPaths, "affected paths"),
+      shardEvidenceRoots: jsonList(options.shardEvidenceRoots, "shard evidence roots", { required: true }),
+      qualifiedAt: options.qualifiedAt,
+    });
+  }
+  if (options.command === "verify-native") {
+    return verifyNativeQualificationProof(jsonFile(options.sourceProofPath, "native proof"));
+  }
+  if (options.command === "classify-native") {
+    return createNativeProofReuseDecision({
+      proof: jsonFile(options.sourceProofPath, "native proof"),
+      current: {
+        sourceIdentityRoot: options.sourceIdentityRoot,
+        sourcePatchRoot: options.sourcePatchRoot,
+        planRoot: options.planRoot,
+        closureRoot: options.closureRoot,
+        dependencyRoot: options.dependencyRoot,
+        toolchainRoot: options.toolchainRoot,
+        environmentRoot: options.environmentRoot,
+        currentBase: options.currentBase,
+        graphKnown: options.graphKnown,
+        attributionComplete: options.attributionComplete,
+        changedPaths: jsonList(options.changedPaths, "changed paths"),
+        renames: jsonList(options.renames, "renames"),
+      },
+    });
+  }
+  if (options.command === "verify-native-reuse") {
+    return verifyNativeProofReuseDecision(jsonFile(options.qualificationReceiptPath, "native reuse decision"), {
+      proof: jsonFile(options.sourceProofPath, "native proof"),
+      current: {
+        sourceIdentityRoot: options.sourceIdentityRoot,
+        sourcePatchRoot: options.sourcePatchRoot,
+        planRoot: options.planRoot,
+        closureRoot: options.closureRoot,
+        dependencyRoot: options.dependencyRoot,
+        toolchainRoot: options.toolchainRoot,
+        environmentRoot: options.environmentRoot,
+        currentBase: options.currentBase,
+        graphKnown: options.graphKnown,
+        attributionComplete: options.attributionComplete,
+        changedPaths: jsonList(options.changedPaths, "changed paths"),
+        renames: jsonList(options.renames, "renames"),
+      },
+    });
+  }
+  if (options.command === "replay") {
+    return createProjectCutReplayPlan({
+      repository: options.repository,
+      protectedBase: options.protectedBase,
+      pullRequestNumber: options.pullRequestNumber,
+      sourceHead: options.sourceHead,
+      previousBase: options.previousBase,
+      currentBase: options.currentBase,
+      sourcePatchRoot: options.sourcePatchRoot,
+      replayTree: options.replayTree,
+    });
+  }
+  if (options.command === "replay-proof") {
+    return createProjectCutReplayProof({
+      repository: options.repository,
+      protectedBase: options.protectedBase,
+      pullRequestNumber: options.pullRequestNumber,
+      sourceHead: options.sourceHead,
+      sourcePatchRoot: options.sourcePatchRoot,
+      currentBase: options.currentBase,
+      replayTree: options.replayTree,
+      qualificationReceipt: jsonFile(options.qualificationReceiptPath, "Project Cut qualification receipt"),
+      requiredContextRoots: jsonList(options.requiredContextRoots, "required context roots", { required: true }),
+      verifiedAt: options.verifiedAt,
+    });
+  }
+  if (options.command === "verify-replay") {
+    return verifyProjectCutReplayProof(jsonFile(options.sourceProofPath, "Project Cut replay proof"));
+  }
+  if (options.command === "integration") {
+    const sourceProofRoot = options.sourceProofRoot || jsonFile(options.sourceProofPath, "source proof").proofRoot;
+    return createIntegrationDeliveryProof({
+      repository: options.repository,
+      protectedBase: options.protectedBase,
+      sourceProofRoot,
+      currentBase: options.currentBase,
+      replayTree: options.replayTree,
+      mergeGroupHead: options.mergeGroupHead,
+      mergeGroupTree: options.mergeGroupTree,
+      warrant: activeWarrant(options),
+      requiredContextRoots: jsonList(options.requiredContextRoots, "required context roots", { required: true }),
+      verifiedAt: options.verifiedAt,
+    });
+  }
+  if (options.command === "verify-integration") {
+    return verifyIntegrationDeliveryProof(jsonFile(options.sourceProofPath, "integration proof"));
+  }
+  throw new Error("unsupported dev delivery proof command");
+}
+
+function usage() {
+  return "Usage:\n  buildchain dev proof <source|verify-source|classify|native|verify-native|classify-native|verify-native-reuse|replay|replay-proof|verify-replay|integration|verify-integration> [options] [--output FILE] [--json]\n";
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || hasFlag(args, "help")) {
+    process.stdout.write(usage());
+    return;
+  }
+  const options = devDeliveryProofCliOptions(args);
+  const result = runDevDeliveryProofCommand(options);
+  fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
+  fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(`Buildchain dev delivery proof ${options.command}: ${result.proofRoot || result.reason}\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(`buildchain dev proof: ${error.message}`);
+    process.exit(1);
+  });
+}

package/packages/core/dev-delivery/commands/dev-delivery-provider-heartbeat.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { heartbeatDeliveryAttempt, verifyDeliveryHeartbeat } from "../native/heartbeat.js";
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function readJson(file, label) {
+  if (!file) throw new Error(`${label} is required`);
+  return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  fs.writeFileSync(path.resolve(file), `${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || "";
+  if (!new Set(["run", "verify"]).has(command)) {
+    process.stdout.write(
+      "Usage: dev-delivery-provider-heartbeat.mjs <run|verify> --admission FILE --repository owner/repo --branch dev/vN/vN.M --workflow-run-id N --workflow-run-attempt N --output FILE\n",
+    );
+    return;
+  }
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  const common = {
+    repository: flag(args, "repository", process.env.GITHUB_REPOSITORY),
+    branch: flag(args, "branch", process.env.GITHUB_BASE_REF),
+    admission: readJson(flag(args, "admission"), "admission"),
+    workflowRunId: Number(process.env.GITHUB_RUN_ID),
+    workflowRunAttempt: Number(process.env.GITHUB_RUN_ATTEMPT),
+    token,
+    apiUrl: process.env.GITHUB_API_URL || "https://api.github.com",
+    now: new Date().toISOString(),
+    admissionJobName: flag(
+      args,
+      "admission-job-name",
+      "Reserve exact delivery candidate",
+    ),
+    heartbeatJobName: flag(
+      args,
+      "heartbeat-job-name",
+      "Credentialed independent Warrant heartbeat",
+    ),
+    finalizerJobName: flag(
+      args,
+      "finalizer-job-name",
+      "Credentialed provider finalizer",
+    ),
+  };
+  const result =
+    command === "run"
+      ? await heartbeatDeliveryAttempt({
+          ...common,
+          leaseSeconds: Number(flag(args, "lease-seconds", "3600")),
+          heartbeatSeconds: Number(flag(args, "heartbeat-seconds", "30")),
+        })
+      : await verifyDeliveryHeartbeat({
+          ...common,
+          receipt: readJson(flag(args, "receipt"), "heartbeat receipt"),
+          jobsReadback: readJson(flag(args, "jobs-readback"), "jobs readback"),
+        });
+  writeJson(flag(args, "output"), result);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(`dev delivery provider heartbeat: ${error.message}`);
+    process.exit(1);
+  });
+}

package/packages/core/dev-delivery/commands/dev-delivery-request.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+set -euo pipefail
+
+usage() {
+  echo "usage: buildchain dev deliver <pull-request-url-or-number> [--execute] [--json]" >&2
+  exit 2
+}
+
+pull_request="${1:-}"
+shift || true
+if [ -z "$pull_request" ] || [[ "$pull_request" == --* ]]; then usage; fi
+execute=false
+json=false
+for argument in "$@"; do
+  case "$argument" in
+    --execute) execute=true ;;
+    --json) json=true ;;
+    *) usage ;;
+  esac
+done
+
+source_root="${BUILDCHAIN_WORK_SOURCE_ROOT:-}"
+[[ "$source_root" =~ ^sha256:[0-9a-f]{64}$ ]] || {
+  echo "buildchain dev deliver: BUILDCHAIN_WORK_SOURCE_ROOT is required" >&2
+  exit 1
+}
+command -v gh >/dev/null || { echo "buildchain dev deliver: gh is required" >&2; exit 1; }
+command -v jq >/dev/null || { echo "buildchain dev deliver: jq is required" >&2; exit 1; }
+
+case "$pull_request" in
+  https://github.com/*/pull/*)
+    coordinate="${pull_request#https://github.com/}"
+    repository="${coordinate%/pull/*}"
+    number="${coordinate#*/pull/}"
+    number="${number%%/*}"
+    ;;
+  *#*) repository="${pull_request%#*}"; number="${pull_request##*#}" ;;
+  *) repository="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"; number="$pull_request" ;;
+esac
+[[ "$repository" =~ ^[^/]+/[^/]+$ && "$number" =~ ^[1-9][0-9]*$ ]] || usage
+
+pr="$(gh pr view "$number" --repo "$repository" --json number,state,isDraft,baseRefName,headRefName,headRefOid,headRepository,statusCheckRollup)"
+jq -e --arg repository "$repository" '
+  .state == "OPEN" and (.isDraft | not) and .headRepository.nameWithOwner == $repository
+' >/dev/null <<<"$pr" || {
+  echo "buildchain dev deliver: PR must be open, non-draft, and from the same repository" >&2
+  exit 1
+}
+base="$(jq -r .baseRefName <<<"$pr")"
+source_head="$(jq -r .headRefOid <<<"$pr")"
+runtime_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+runtime_sha="$(git -C "$runtime_root" rev-parse 'HEAD^{commit}')"
+workflow_ref="$base"
+if [ "$repository" = kungfu-systems/buildchain ]; then
+  [ "$runtime_sha" = "$source_head" ] || {
+    echo "buildchain dev deliver: source-owned workflow and runtime must match the exact PR head" >&2
+    exit 1
+  }
+  workflow_ref="$(jq -er '.headRefName | select(type == "string" and length > 0)' <<<"$pr")"
+fi
+
+run_id="$(jq -r '[.statusCheckRollup[] | select(.workflowName == "Verify" and .conclusion == "SUCCESS") | .detailsUrl | capture("/runs/(?<id>[0-9]+)").id] | unique | last // empty' <<<"$pr")"
+[ -n "$run_id" ] || { echo "buildchain dev deliver: no successful Verify run covers the PR head" >&2; exit 1; }
+run="$(gh api "repos/$repository/actions/runs/$run_id")"
+jq -e --arg head "$source_head" --argjson number "$number" '
+  .conclusion == "success" and .event == "pull_request" and .head_sha == $head and
+  ((.path | sub("@.*$"; "")) == ".github/workflows/self-build-verify.yml") and
+  any(.pull_requests[]; .number == $number)
+' >/dev/null <<<"$run" || { echo "buildchain dev deliver: Verify run does not exactly cover the PR head" >&2; exit 1; }
+qualified_base="$(jq -r --argjson number "$number" '.pull_requests[] | select(.number == $number) | .base.sha' <<<"$run" | head -n 1)"
+
+for revision in "$source_head" "$qualified_base"; do
+  git cat-file -e "$revision^{commit}" 2>/dev/null || git fetch --no-tags origin "$revision"
+done
+affected_paths="$(git diff --name-only --no-renames "$qualified_base...$source_head" | jq -Rsc 'split("\n") | map(select(length > 0)) | sort')"
+[ "$(jq length <<<"$affected_paths")" -gt 0 ] || { echo "buildchain dev deliver: PR has no source changes" >&2; exit 1; }
+
+paths_at_head() {
+  while IFS= read -r item; do
+    if git cat-file -e "$source_head:$item" 2>/dev/null; then printf '%s\n' "$item"; fi
+  done | jq -Rsc 'split("\n") | map(select(length > 0)) | sort'
+}
+existing_paths="$(jq -r '.[]' <<<"$affected_paths" | paths_at_head)"
+policy_paths="$(printf '%s\n' .github/workflows/self-build-verify.yml .github/workflows/self-ops-dev-delivery.yml buildchain.toml .buildchain/buildchain.toml | paths_at_head)"
+[ "$(jq length <<<"$policy_paths")" -gt 0 ] || policy_paths="$(jq '.[0:1]' <<<"$existing_paths")"
+[ "$(jq length <<<"$existing_paths")" -gt 0 ] || existing_paths="$policy_paths"
+dependency_paths="$(printf '%s\n' package.json pnpm-lock.yaml package-lock.json yarn.lock Cargo.toml Cargo.lock go.mod go.sum | paths_at_head)"
+[ "$(jq length <<<"$dependency_paths")" -gt 0 ] || dependency_paths="$policy_paths"
+required_contexts="$(jq '[.statusCheckRollup[] | select(.conclusion == "SUCCESS") | .name] | unique | sort' <<<"$pr")"
+[ "$(jq length <<<"$required_contexts")" -gt 0 ] || { echo "buildchain dev deliver: exact PR head has no successful checks" >&2; exit 1; }
+
+predicates="$(node "$runtime_root/packages/core/dev-delivery/commands/dev-delivery-source-proof-reuse.mjs" predicates \
+  --cwd "$PWD" --repository "$repository" --branch "$base" --qualified-base "$qualified_base" \
+  --source-head "$source_head" --runtime-ref "$runtime_sha" --runtime-sha "$runtime_sha" \
+  --contract-digest "$runtime_sha" --node-version "${BUILDCHAIN_NODE_VERSION:-24}" \
+  --policy-paths-json "$policy_paths" --closure-paths-json "$existing_paths" \
+  --dependency-paths-json "$dependency_paths" --required-contexts-json "$required_contexts")"
+
+# Observe current ownership before submitting a new delivery request.
+github_token="${GITHUB_TOKEN:-${GH_TOKEN:-$(gh auth token 2>/dev/null || true)}}"
+if [ -n "$github_token" ]; then
+  observation="$(GITHUB_TOKEN="$github_token" node "$runtime_root/packages/core/dev-delivery/commands/dev-delivery-warrant.mjs" observe --repository "$repository" --branch "$base" --json 2>/dev/null || true)"
+  active_pr="$(jq -r '.observation.activeWarrant.pullRequestNumber // empty' <<<"${observation:-}" 2>/dev/null || true)"
+  active_head="$(jq -r '.observation.activeWarrant.sourceHead // empty' <<<"${observation:-}" 2>/dev/null || true)"
+  if [ -n "$active_pr" ] && ! jq -e '.observation.activeWarrant.phase | IN("ready", "provisional", "qualified")' <<<"$observation" >/dev/null; then
+    echo "Active Warrant must declare its current phase; historical recovery is unsupported." >&2
+    exit 1
+  fi
+  if [ "$execute" = true ] && [ -n "$active_pr" ] && { [ "$active_pr" != "$number" ] || [ "$active_head" != "$source_head" ]; }; then
+    active_pr_state="$(gh pr view "$active_pr" --repo "$repository" --json state,headRefOid 2>/dev/null || true)"
+    observed_state="$(jq -r '.state // empty' <<<"${active_pr_state:-}" 2>/dev/null || true)"
+    observed_head="$(jq -r '.headRefOid // empty' <<<"${active_pr_state:-}" 2>/dev/null || true)"
+    stale_outcome=""
+    if [ "$observed_state" = CLOSED ]; then
+      stale_outcome="cancelled"
+    elif [ "$active_pr" = "$number" ] && [ -n "$observed_head" ] && [ "$observed_head" != "$active_head" ]; then
+      stale_outcome="dequeued"
+    fi
+    if [ -n "$stale_outcome" ]; then
+      stale_fact="$(jq -cn --arg repository "$repository" --arg base "$base" --argjson pr "$active_pr" --arg recorded "$active_head" \
+        --arg observed "${observed_head:-$active_head}" --arg state "$observed_state" '{repository:$repository,protectedBase:$base,pullRequestNumber:$pr,recordedHead:$recorded,observedHead:$observed,observedState:$state}')"
+      stale_evidence_root="$(node --input-type=module -e 'const {pathToFileURL}=await import("node:url");const {devDeliveryContentRoot:root}=await import(pathToFileURL(process.argv[1]).href);process.stdout.write(root(JSON.parse(process.argv[2])))' "$runtime_root/packages/core/dev-delivery/dev-delivery-warrant.js" "$stale_fact")"
+      GITHUB_TOKEN="$github_token" node "$runtime_root/packages/core/dev-delivery/commands/dev-delivery-warrant.mjs" settle \
+        --repository "$repository" --branch "$base" --pull-request "$active_pr" --expected-source-head "$active_head" \
+        --fencing-token "$(jq -er '.observation.activeWarrant.fencingToken' <<<"$observation")" --lease-generation "$(jq -er '.observation.activeWarrant.generation' <<<"$observation")" \
+        --outcome "$stale_outcome" \
+        --evidence-root "$stale_evidence_root" \
+        --reason "Buildchain observed a terminal PR or changed PR head before a new minimal delivery request." --execute >/dev/null
+      observation="$(GITHUB_TOKEN="$github_token" node "$runtime_root/packages/core/dev-delivery/commands/dev-delivery-warrant.mjs" observe --repository "$repository" --branch "$base" --json)"
+    fi
+  fi
+
+fi
+workflow="self-ops-dev-delivery.yml"
+payload="$(jq --arg ref "$workflow_ref" --arg base "$base" --arg runtime "$runtime_sha" --arg number "$number" \
+  --arg head "$source_head" --arg roots "$(jq -cn --arg root "$source_root" '{sourceRoot:$root}')" \
+  --arg run "$run_id" '. as $proof | {ref:$ref,inputs:{
+    "buildchain-ref":$runtime,"target-branch":$base,"expected-pr-number":$number,
+    "expected-head-sha":$head,"native-roots-json":$roots,"source-workflow-run-id":$run,
+    "source-identity-root":$proof.sourceIdentityRoot,
+    "source-patch-root":$proof.sourcePatchRoot,"plan-root":$proof.planRoot,
+    "closure-root":$proof.closureRoot,"dependency-root":$proof.dependencyRoot,
+    "toolchain-root":$proof.toolchainRoot,"environment-root":"",
+    "affected-paths-json":"[]","shard-evidence-roots-json":"[]",
+    "release-blocker-priority-json":"","native-proof-json":"","native-command":"",
+    "native-command-root":"","native-heartbeat-seconds":"30","delivery-class":"non-native-fast",
+    "delivery-priority":"ordinary"}}' <<<"$predicates")"
+
+if [ "$execute" = true ]; then
+  gh api --method POST "repos/$repository/actions/workflows/$workflow/dispatches" --input - <<<"$payload" >/dev/null
+fi
+mode=plan
+[ "$execute" = true ] && mode=execute
+if [ "$json" = true ]; then
+  jq -n --arg mode "$mode" --arg repository "$repository" \
+    --arg workflow "$workflow" --argjson number "$number" --arg head "$source_head" \
+    '{ok:true,mode:$mode,repository:$repository,workflowId:$workflow,pullRequestNumber:$number,sourceHead:$head}'
+else
+  echo "Buildchain dev delivery: $mode PR #$number"
+fi

package/packages/core/dev-delivery/commands/dev-delivery-source-proof-reuse.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import { sourceQualificationPredicates } from "../source-proof/predicates.js";
+import { sealSourceQualificationProof } from "../source-proof/seal.js";
+import { verifySourceQualificationReuse, rootedDecision, REUSE_DECISION_SCHEMA } from "../source-proof/reuse.js";
+import { materializeReuseLifecycleEvidence } from "../source-proof/evidence.js";
+import { writeJson } from "../source-proof/io.js";
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function writeOutputs(values) {
+  const output = process.env.GITHUB_OUTPUT;
+  if (!output) return;
+  fs.appendFileSync(
+    output,
+    Object.entries(values)
+      .map(([key, value]) => `${key}=${String(value)}\n`)
+      .join(""),
+  );
+}
+
+function cliInput(args) {
+  return {
+    cwd: flag(args, "cwd", process.cwd()),
+    repository: flag(args, "repository", process.env.GITHUB_REPOSITORY),
+    protectedBase: flag(args, "branch", process.env.GITHUB_BASE_REF),
+    qualifiedBase: flag(args, "qualified-base"),
+    currentBase: flag(args, "current-base"),
+    sourceHead: flag(args, "source-head"),
+    sourceWorkflowRunId: flag(
+      args,
+      "source-workflow-run-id",
+      process.env.GITHUB_RUN_ID,
+    ),
+    runtimeRef: flag(args, "runtime-ref"),
+    runtimeSha: flag(args, "runtime-sha"),
+    contractDigest: flag(args, "contract-digest"),
+    nodeVersion: flag(args, "node-version", "24"),
+    workingDirectory: flag(args, "working-directory", "."),
+    policyPaths: flag(args, "policy-paths-json"),
+    closurePaths: flag(args, "closure-paths-json"),
+    dependencyPaths: flag(args, "dependency-paths-json"),
+    requiredContexts: flag(args, "required-contexts-json"),
+    controllerReceiptPath: flag(args, "controller-receipt"),
+    sourceProofPath: flag(args, "source-proof"),
+    mergeGroupHead: flag(args, "merge-group-head"),
+    mergeGroupTree: flag(args, "merge-group-tree"),
+    qualifiedAt: flag(args, "qualified-at"),
+    verifiedAt: flag(args, "verified-at"),
+    outputPath: flag(args, "output"),
+    manifestPath: flag(args, "manifest-output"),
+    summaryPath: flag(args, "summary-output"),
+  };
+}
+
+export function sourceProofReuseCli(args = process.argv.slice(2)) {
+  const [command = "", ...rest] = args;
+  const input = cliInput(rest);
+  if (command === "predicates") return sourceQualificationPredicates(input);
+  if (command === "seal") {
+    const proof = sealSourceQualificationProof(input);
+    writeJson(input.outputPath, proof);
+    writeOutputs({ "proof-root": proof.proofRoot, "proof-reused": "false" });
+    return proof;
+  }
+  if (command === "verify") {
+    let decision;
+    try {
+      decision = verifySourceQualificationReuse(input);
+    } catch (error) {
+      decision = rootedDecision({
+        schema: REUSE_DECISION_SCHEMA,
+        reusable: false,
+        action: "rerun-full-source-qualification",
+        reason: "unverifiable-proof",
+        diagnostic: String(error.message || error),
+      });
+    }
+    writeJson(input.outputPath, decision);
+    if (decision.reusable && input.manifestPath && input.summaryPath) {
+      materializeReuseLifecycleEvidence({
+        decision,
+        sourceProofPath: input.sourceProofPath,
+        decisionPath: input.outputPath,
+        manifestPath: input.manifestPath,
+        summaryPath: input.summaryPath,
+        workspace: input.cwd,
+        repository: input.repository,
+        sourceRef: process.env.GITHUB_REF,
+        runId: process.env.GITHUB_RUN_ID,
+        runAttempt: process.env.GITHUB_RUN_ATTEMPT,
+        platformId: process.env.RUNNER_OS || process.platform,
+        platformName:
+          process.env.RUNNER_NAME || process.env.RUNNER_OS || process.platform,
+        runnerOs: process.env.RUNNER_OS || process.platform,
+        runnerArch: process.env.RUNNER_ARCH || process.arch,
+      });
+    }
+    writeOutputs({
+      reuse: String(decision.reusable),
+      "proof-root": decision.sourceProofRoot || "",
+      reason: decision.reason,
+      "decision-root": decision.decisionRoot,
+    });
+    return decision;
+  }
+  throw new Error(
+    "usage: dev-delivery-source-proof-reuse.mjs <predicates|seal|verify> [options]",
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = sourceProofReuseCli();
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    console.error(
+      `::error::${String(error.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}