@kungfu-tech/buildchain 4.0.1-alpha.4 → 4.0.1-alpha.6

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -20,6 +20,7 @@ import {
   candidateFromDecision,
   selectLatestQualifiedSource,
 } from "../packages/core/dev-alpha-candidate-selection.js";
+import { readGitHubNextDevelopmentVersionReservation } from "../packages/core/next-development-candidate-reservation.js";
 
 export { reconcileActiveReleaseTrain, selectLatestQualifiedSource };
 
@@ -617,6 +618,7 @@ export async function runDevAlphaCandidatePatrol(
     comparison,
     workflowEvidence,
     skippedNewerCommitCount,
+    versionReservation,
     qualificationError,
   } = await resolvePatrolSourceInputs({
     client,
@@ -646,6 +648,7 @@ export async function runDevAlphaCandidatePatrol(
           observedSourceHeadSha,
           skippedNewerCommitCount,
           ...(targetBaseline ? { targetBaseline } : {}),
+          ...(versionReservation ? { versionReservation } : {}),
         },
         workflowEvidence,
         requiredWorkflowPaths,
@@ -992,6 +995,20 @@ export function createGitHubChannelCandidateClient({
         targetBranch,
         parseCandidate: managedCandidateFromPullRequest,
       }),
+    async readNextDevelopmentVersionReservation({
+      reservationSha,
+      candidateSha,
+      targetVersion,
+    }) {
+      return readGitHubNextDevelopmentVersionReservation({
+        api,
+        owner,
+        repo,
+        reservationSha,
+        candidateSha,
+        targetVersion,
+      });
+    },
     async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
       const runs = [];
       for (let page = 1; page <= 10; page += 1) {
@@ -1015,7 +1032,11 @@ export function createGitHubChannelCandidateClient({
         for (const commit of rows) {
           const commitSha = text(commit.sha);
           if (commitSha === targetSha) return commits;
-          commits.push(commitSha);
+          commits.push({
+            sha: commitSha,
+            message: text(commit.commit?.message),
+            parents: (commit.parents || []).map((parent) => text(parent.sha)),
+          });
         }
         if (rows.length < 100) return commits;
       }

package/scripts/dev-delivery-source-proof-replay.mjs

@@ -0,0 +1,153 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SHA = /^[0-9a-f]{40}$/u;
+
+function exactSha(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${label} must be an exact 40-hex Git SHA`);
+  return normalized;
+}
+
+function git(args, { cwd, encoding = "utf8" }) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.status !== 0)
+    throw new Error(
+      `git ${args.join(" ")} failed: ${String(result.stderr || "").trim()}`,
+    );
+  return encoding === null ? result.stdout : String(result.stdout || "").trim();
+}
+
+function patchRoot(base, head, cwd) {
+  const patch = git(
+    [
+      "diff",
+      "--binary",
+      "--full-index",
+      "--no-ext-diff",
+      `${base}..${head}`,
+    ],
+    { cwd, encoding: null },
+  );
+  return `sha256:${crypto.createHash("sha256").update(patch).digest("hex")}`;
+}
+
+function linearRange(base, head, cwd) {
+  try {
+    git(["merge-base", "--is-ancestor", base, head], { cwd });
+  } catch {
+    return null;
+  }
+  const commits = git(
+    ["rev-list", "--reverse", "--topo-order", `${base}..${head}`],
+    { cwd },
+  )
+    .split(/\s+/u)
+    .filter(Boolean);
+  if (commits.length === 0) return null;
+  let expectedParent = base;
+  const trees = [];
+  const patchRoots = [];
+  for (const rangeCommit of commits) {
+    const [observedCommit, ...parents] = git(
+      ["rev-list", "--parents", "-n", "1", rangeCommit],
+      { cwd },
+    ).split(/\s+/u);
+    if (
+      observedCommit !== rangeCommit ||
+      parents.length !== 1 ||
+      parents[0] !== expectedParent
+    ) {
+      return null;
+    }
+    trees.push(
+      exactSha(
+        git(["rev-parse", `${rangeCommit}^{tree}`], { cwd }),
+        "replayedCommitTree",
+      ),
+    );
+    patchRoots.push(patchRoot(expectedParent, rangeCommit, cwd));
+    expectedParent = rangeCommit;
+  }
+  return { commits, trees, patchRoots };
+}
+
+export function exactMergeGroupBinding(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const mergeGroupHead = exactSha(input.mergeGroupHead, "mergeGroupHead");
+  const expectedTree = exactSha(input.mergeGroupTree, "mergeGroupTree");
+  const qualifiedBase = exactSha(input.qualifiedBase, "qualifiedBase");
+  const currentBase = exactSha(input.currentBase, "currentBase");
+  const sourceHead = exactSha(input.sourceHead, "sourceHead");
+  const sourcePatchRoot = String(input.sourcePatchRoot || "").trim();
+  const actualTree = exactSha(
+    git(["rev-parse", `${mergeGroupHead}^{tree}`], { cwd }),
+    "mergeGroupTree",
+  );
+  if (actualTree !== expectedTree)
+    return { ok: false, reason: "merge-group-tree-mismatch" };
+  try {
+    git(["merge-base", "--is-ancestor", qualifiedBase, currentBase], { cwd });
+  } catch {
+    return {
+      ok: false,
+      reason: "current-base-not-descendant-of-qualified-base",
+    };
+  }
+  if (!/^sha256:[0-9a-f]{64}$/u.test(sourcePatchRoot))
+    throw new Error("sourcePatchRoot must be an exact SHA-256 root");
+  if (patchRoot(currentBase, mergeGroupHead, cwd) !== sourcePatchRoot)
+    return { ok: false, reason: "merge-group-source-patch-mismatch" };
+
+  const [commit, ...parents] = git(
+    ["rev-list", "--parents", "-n", "1", mergeGroupHead],
+    { cwd },
+  ).split(/\s+/u);
+  if (commit !== mergeGroupHead)
+    return { ok: false, reason: "merge-group-parent-mismatch" };
+  if (
+    parents.length === 2 &&
+    parents[0] === currentBase &&
+    parents[1] === sourceHead
+  ) {
+    return {
+      ok: true,
+      mergeGroupHead,
+      mergeGroupTree: actualTree,
+      parents,
+      compositionMode: "two-parent-merge",
+      replayedCommitTrees: [],
+      replayedCommitPatchRoots: [],
+    };
+  }
+
+  const sourceRange = linearRange(qualifiedBase, sourceHead, cwd);
+  const mergeGroupRange = linearRange(currentBase, mergeGroupHead, cwd);
+  if (
+    !sourceRange ||
+    !mergeGroupRange ||
+    sourceRange.commits.length !== mergeGroupRange.commits.length ||
+    sourceRange.patchRoots.some(
+      (root, index) => root !== mergeGroupRange.patchRoots[index],
+    )
+  ) {
+    return { ok: false, reason: "merge-group-parent-mismatch" };
+  }
+  return {
+    ok: true,
+    mergeGroupHead,
+    mergeGroupTree: actualTree,
+    parents,
+    compositionMode: "linear-replay",
+    replayedCommitTrees: mergeGroupRange.trees,
+    replayedCommitPatchRoots: mergeGroupRange.patchRoots,
+  };
+}

package/scripts/dev-delivery-source-proof-reuse.mjs

@@ -11,6 +11,7 @@ import {
   verifySourceQualificationProof,
 } from "../packages/core/dev-delivery-warrant.js";
 import { validateControllerReceipt } from "../packages/core/controller-evidence.js";
+import { exactMergeGroupBinding } from "./dev-delivery-source-proof-replay.mjs";
 
 const REUSE_DECISION_SCHEMA =
   "kungfu.buildchain.source-qualification-reuse-decision/v1";
@@ -113,98 +114,6 @@ function gitPathRoot(ref, paths, label, cwd) {
   });
 }
 
-function exactMergeGroupBinding(input = {}) {
-  const cwd = path.resolve(input.cwd || process.cwd());
-  const mergeGroupHead = exactSha(input.mergeGroupHead, "mergeGroupHead");
-  const expectedTree = exactSha(input.mergeGroupTree, "mergeGroupTree");
-  const currentBase = exactSha(input.currentBase, "currentBase");
-  const sourceHead = exactSha(input.sourceHead, "sourceHead");
-  const actualTree = exactSha(
-    git(["rev-parse", `${mergeGroupHead}^{tree}`], { cwd }),
-    "mergeGroupTree",
-  );
-  if (actualTree !== expectedTree)
-    return { ok: false, reason: "merge-group-tree-mismatch" };
-  const [commit, ...parents] = git(
-    ["rev-list", "--parents", "-n", "1", mergeGroupHead],
-    { cwd },
-  ).split(/\s+/u);
-  if (commit !== mergeGroupHead) {
-    return { ok: false, reason: "merge-group-parent-mismatch" };
-  }
-  if (
-    parents.length === 2 &&
-    parents[0] === currentBase &&
-    parents[1] === sourceHead
-  ) {
-    return {
-      ok: true,
-      mergeGroupHead,
-      mergeGroupTree: actualTree,
-      parents,
-      compositionMode: "two-parent-merge",
-      replayedCommitTrees: [],
-    };
-  }
-
-  const linearRange = (head) => {
-    try {
-      git(["merge-base", "--is-ancestor", currentBase, head], { cwd });
-    } catch {
-      return null;
-    }
-    const commits = git(
-      ["rev-list", "--reverse", "--topo-order", `${currentBase}..${head}`],
-      { cwd },
-    )
-      .split(/\s+/u)
-      .filter(Boolean);
-    if (commits.length === 0) return null;
-    let expectedParent = currentBase;
-    const trees = [];
-    for (const rangeCommit of commits) {
-      const [observedCommit, ...rangeParents] = git(
-        ["rev-list", "--parents", "-n", "1", rangeCommit],
-        { cwd },
-      ).split(/\s+/u);
-      if (
-        observedCommit !== rangeCommit ||
-        rangeParents.length !== 1 ||
-        rangeParents[0] !== expectedParent
-      ) {
-        return null;
-      }
-      trees.push(
-        exactSha(
-          git(["rev-parse", `${rangeCommit}^{tree}`], { cwd }),
-          "replayedCommitTree",
-        ),
-      );
-      expectedParent = rangeCommit;
-    }
-    return trees;
-  };
-
-  const sourceTrees = linearRange(sourceHead);
-  const mergeGroupTrees = linearRange(mergeGroupHead);
-  if (
-    !sourceTrees ||
-    !mergeGroupTrees ||
-    sourceTrees.length !== mergeGroupTrees.length ||
-    sourceTrees.some((tree, index) => tree !== mergeGroupTrees[index])
-  ) {
-    return { ok: false, reason: "merge-group-parent-mismatch" };
-  }
-  return {
-    ok: true,
-    mergeGroupHead,
-    mergeGroupTree: actualTree,
-    parents,
-    compositionMode: "linear-replay",
-    replayedCommitTrees: mergeGroupTrees,
-  };
-}
-
 export function sourceQualificationPredicates(input = {}) {
   const cwd = path.resolve(input.cwd || process.cwd());
   const repository = required(input.repository, "repository");
@@ -397,7 +306,8 @@ export function materializeReuseLifecycleEvidence({
       decisionRoot: decision.decisionRoot,
       sourceWorkflowRunId: decision.sourceWorkflowRunId,
       sourceHead: decision.sourceHead,
-      qualifiedBase: decision.currentBase,
+      qualifiedBase: decision.qualifiedBase,
+      currentBase: decision.currentBase,
       mergeGroupHead: decision.mergeGroupHead,
       mergeGroupTree: decision.mergeGroupTree,
     },
@@ -446,7 +356,7 @@ export function verifySourceQualificationReuse(input = {}) {
   const verification = verifySourceQualificationProof(proof, {
     repository: required(input.repository, "repository"),
     protectedBase: required(input.protectedBase, "protectedBase"),
-    qualifiedBase: exactSha(input.currentBase, "currentBase"),
+    qualifiedBase: exactSha(proof.qualifiedBase, "qualifiedBase"),
     sourceHead: exactSha(input.sourceHead, "sourceHead"),
     sourceWorkflowRunId: Number(input.sourceWorkflowRunId),
     controllerReceiptRoot: receipt.digest,
@@ -462,7 +372,7 @@ export function verifySourceQualificationReuse(input = {}) {
   }
   const current = sourceQualificationPredicates({
     ...input,
-    qualifiedBase: input.currentBase,
+    qualifiedBase: proof.qualifiedBase,
   });
   const classification = classifyDevDeliveryDelta({
     proof,
@@ -476,7 +386,11 @@ export function verifySourceQualificationReuse(input = {}) {
       reason: classification.reason,
     });
   }
-  const mergeGroup = exactMergeGroupBinding(input);
+  const mergeGroup = exactMergeGroupBinding({
+    ...input,
+    qualifiedBase: proof.qualifiedBase,
+    sourcePatchRoot: proof.sourcePatchRoot,
+  });
   if (!mergeGroup.ok) {
     return rootedDecision({
       schema: REUSE_DECISION_SCHEMA,
@@ -493,12 +407,14 @@ export function verifySourceQualificationReuse(input = {}) {
     sourceProofRoot: proof.proofRoot,
     sourceWorkflowRunId: proof.sourceWorkflowRunId,
     sourceHead: proof.sourceHead,
-    currentBase: proof.qualifiedBase,
+    qualifiedBase: proof.qualifiedBase,
+    currentBase: exactSha(input.currentBase, "currentBase"),
     mergeGroupHead: mergeGroup.mergeGroupHead,
     mergeGroupTree: mergeGroup.mergeGroupTree,
     mergeGroupParents: mergeGroup.parents,
     mergeGroupCompositionMode: mergeGroup.compositionMode,
     mergeGroupReplayTrees: mergeGroup.replayedCommitTrees,
+    mergeGroupReplayPatchRoots: mergeGroup.replayedCommitPatchRoots,
     predicateRoots: {
       sourceIdentityRoot: proof.sourceIdentityRoot,
       sourcePatchRoot: proof.sourcePatchRoot,

package/scripts/generate-next-development-guidance.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { nextDevelopmentManual } from "../packages/core/next-development-projection.js";
+
+export const NEXT_DEVELOPMENT_MANUAL_PATH =
+  "docs/next-development-transition.md";
+
+export function generateNextDevelopmentGuidance({
+  cwd = process.cwd(),
+  check = false,
+} = {}) {
+  const target = path.resolve(cwd, NEXT_DEVELOPMENT_MANUAL_PATH);
+  const expected = nextDevelopmentManual();
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (check) {
+    if (current !== expected) {
+      throw new Error(
+        `${NEXT_DEVELOPMENT_MANUAL_PATH} drifted from its contract source`,
+      );
+    }
+    return { ok: true, changed: false, path: NEXT_DEVELOPMENT_MANUAL_PATH };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (current !== expected) fs.writeFileSync(target, expected);
+  return {
+    ok: true,
+    changed: current !== expected,
+    path: NEXT_DEVELOPMENT_MANUAL_PATH,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = generateNextDevelopmentGuidance({
+      check: process.argv.includes("--check"),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`next-development guidance: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-release-candidate-passport.mjs

@@ -5,11 +5,160 @@ import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { createReleaseCandidatePassport, validateReleaseCandidatePassport } from "../packages/core/release-candidate.js";
 import { scanV4FloatingConsumerPolicy, v4ConsumerPolicyScannerRoot } from "../packages/core/v4-floating-consumer-policy.js";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { V4_STAGE_CAPSULE_CONTRACT, V4_STAGE_CAPSULE_IDENTITY_CONTRACT, v4StageCapsuleIdentityRoot, v4StageCapsuleRoot, validateV4StageCapsule } from "../packages/core/v4-stage-capsule.js";
+import { v4RuntimeResumeDocumentRoot } from "../packages/core/v4-runtime-ref-resume-authority.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
 const env = (name, fallback = "") => process.env[name] || fallback;
 const readJsonFile = (filePath) => JSON.parse(fs.readFileSync(filePath, "utf8"));
 
+export function createReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  coordinates,
+}) {
+  if (!passport.consumerPolicy?.receiptRoot) return undefined;
+  if (
+    coordinates.repository !== passport.repository ||
+    String(coordinates.runId) !== String(passport.workflow.runId) ||
+    String(coordinates.runAttempt) !== String(passport.workflow.runAttempt) ||
+    coordinates.sourceSha !== passport.source.headSha
+  ) {
+    throw new Error(
+      "Stage Capsule coordinate set does not bind the candidate run",
+    );
+  }
+  const coordinateByPlatform = new Map(
+    coordinates.artifacts.map((entry) => [entry.platformId, entry]),
+  );
+  const qualificationRoot = passport.controllerReceipts?.[0]?.receiptDigest;
+  const entries = passport.platformMatrix
+    .map((platform) => {
+      const coordinate = coordinateByPlatform.get(platform.platformId);
+      if (!coordinate || coordinate.name !== platform.artifactName) {
+        throw new Error(
+          `Stage Capsule coordinate missing for ${platform.platformId}`,
+        );
+      }
+      const manifest = readJsonFile(platform.manifestPath);
+      const identity = {
+        schema: V4_STAGE_CAPSULE_IDENTITY_CONTRACT,
+        sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+        platform: platform.platformId,
+        platformRoot: v4ContentRoot("candidate-identity", manifest.platform),
+        stage: "verify",
+        toolchainRoots: [],
+        runtimeRoot: v4ContentRoot("candidate-identity", {
+          sha: passport.buildchain.sha,
+        }),
+        policyRoot: passport.consumerPolicy.receiptRoot,
+        declaredInputs: [
+          {
+            name: "release-candidate",
+            root: `sha256:${passport.candidateHash}`,
+          },
+        ],
+        transformationRoot: v4ContentRoot("candidate-identity", {
+          lifecycle: manifest.lifecycle,
+          summary: platform.summary,
+        }),
+        outputManifestRoot: v4ContentRoot(
+          "stage-capsule-artifact-manifest",
+          { artifact: coordinate, manifest },
+        ),
+        qualificationRoot,
+        observationRoots: [
+          {
+            name: "provider-coordinate",
+            root: v4ContentRoot("provider-readback-sample", coordinate),
+          },
+        ],
+      };
+      const capsule = {
+        schema: V4_STAGE_CAPSULE_CONTRACT,
+        writerAuthority: "typescript-v3",
+        rustAuthority: "validation-only",
+        identity,
+        identityRoot: v4StageCapsuleIdentityRoot(identity),
+        retentionPromise: {
+          class: "github-artifact",
+          retainUntil: coordinate.expiresAt,
+        },
+        capsuleRoot: `sha256:${"0".repeat(64)}`,
+      };
+      capsule.capsuleRoot = v4StageCapsuleRoot(capsule);
+      validateV4StageCapsule(capsule);
+      return {
+        platform: platform.platformId,
+        artifactName: coordinate.name,
+        artifactDigest: coordinate.digest,
+        artifact: coordinate,
+        capsule,
+      };
+    })
+    .sort((left, right) => left.platform.localeCompare(right.platform));
+  const body = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-release-candidate-stage-capsules/v1",
+    status: "sealed",
+    repository: passport.repository,
+    buildAttempt: {
+      id: `github-run:${passport.workflow.runId}:attempt:${passport.workflow.runAttempt}`,
+      runtimeSha: passport.buildchain.sha,
+    },
+    source: {
+      sha: passport.source.headSha,
+      treeSha: passport.source.treeHash,
+    },
+    consumerPolicyReceiptRoot: passport.consumerPolicy.receiptRoot,
+    capsules: entries,
+  };
+  return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
+}
+
+function writeReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  outputPath,
+}) {
+  const coordinatesPath = path.resolve(
+    env(
+      "BUILDCHAIN_ARTIFACT_COORDINATES_PATH",
+      ".buildchain/artifacts/artifact-coordinates.json",
+    ),
+  );
+  if (!fs.existsSync(coordinatesPath)) {
+    if (passport.consumerPolicy?.receiptRoot) {
+      throw new Error(
+        "v4 release candidate Stage Capsules require exact artifact coordinates",
+      );
+    }
+    return { path: "", root: "" };
+  }
+  const stageCapsules = createReleaseCandidateStageCapsules({
+    passport,
+    buildSummary,
+    coordinates: readJsonFile(coordinatesPath),
+  });
+  if (!stageCapsules) return { path: "", root: "" };
+  const stageCapsulesPath = path.join(
+    path.dirname(outputPath),
+    "release-candidate-stage-capsules.json",
+  );
+  fs.writeFileSync(
+    stageCapsulesPath,
+    `${JSON.stringify(stageCapsules, null, 2)}\n`,
+  );
+  return {
+    path: path
+      .relative(process.cwd(), stageCapsulesPath)
+      .split(path.sep)
+      .join("/"),
+    root: stageCapsules.root,
+  };
+}
+
 export function resolveLegacyConsumerPolicyReceipt(options = {}) {
   if (options.json) return { receipt: JSON.parse(options.json), receiptRoot: options.receiptRoot };
   if (options.repository !== "kungfu-systems/buildchain" || options.targetChannel !== "alpha" || options.workflowShellRef !== "v4-alpha" || options.runtimeOverride !== true) return undefined;
@@ -80,6 +229,7 @@ export function generateReleaseCandidatePassportCli() {
   if (!validation.ok) throw new Error(`release candidate passport invalid: ${validation.errors.join("; ")}`);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, `${JSON.stringify(passport, null, 2)}\n`);
+  const stageCapsules = writeReleaseCandidateStageCapsules({ passport, buildSummary, outputPath });
   writeGitHubOutputs({
     "release-candidate-passport-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
     "release-candidate-passport-json": JSON.stringify({
@@ -94,6 +244,8 @@ export function generateReleaseCandidatePassportCli() {
       consumerPolicy: passport.consumerPolicy,
       controllerReceipts: passport.controllerReceipts || [],
     }),
+    "release-candidate-stage-capsules-path": stageCapsules.path,
+    "release-candidate-stage-capsules-root": stageCapsules.root,
   });
   return passport;
 }