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

package/scripts/buildchain-cli-help.mjs

@@ -8,6 +8,11 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain architecture qualify --authority-revision <git-revision>
                                       [--candidate-revision <git-revision>]
                                       [--cwd <dir>] [--json]
+  buildchain adopter-delivery run --input <json-or-path> [--output <path>]
+  buildchain adopter-delivery verify --input <json-or-path>
+                                      --readback <json-or-path> [--output <path>]
+  buildchain adopter-delivery bootstrap --input <json-or-path> [--output <path>]
+  buildchain adopter-delivery archive --input <json-or-path> [--output <path>]
   buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
                                  [--github-output <file>] [--json]
   buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
@@ -44,6 +49,23 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain release-tail init --declaration <json-or-path> [--state <path>]
   buildchain release-tail <status|verify> [--state <path>] [--output <path>]
   buildchain release-tail compat --hooks-json <json-or-path> [--output <path>]
+  buildchain release-tail rehearse --capsule <absolute-path>
+                                      --candidate-root <absolute-path>
+                                      --mode <simulate|replay>
+                                      --state <absolute-path>
+                                      --evidence <absolute-path>
+  buildchain tail-reseal plan --request <request.json> [--output <plan.json>]
+  buildchain tail-reseal admit --request <request.json> [--output <admission.json>]
+  buildchain tail-reseal verify-platform --request <request.json> --platform <id>
+                                      [--artifact-root <dir>] [--mode retained|resealed]
+                                      [--provider-readback-root <sha256:...>]
+                                      [--output <readback.json>]
+  buildchain tail-reseal seal --request <request.json> --plan <plan.json>
+                                      --readbacks <dir> --passport <passport.json>
+                                      --protected-readback-root <sha256:...>
+                                      [--output <receipt.json>]
+  buildchain next-development materialize --input <request.json> [--cwd <dir>]
+                                      [--write] [--output <path>] [--json]
   buildchain github-governance <plan|apply|rollback|protection-policy-plan|ruleset-policy-plan> ...
   buildchain release <inspect|recover|finalize|abort> ...
   buildchain transaction inspect ...
@@ -154,6 +176,14 @@ export const BUILDCHAIN_USAGE = `Usage:
                              [--module-fact <file>]... [--artifact <path>]...
                              [--output <file>] [--json]
   buildchain facts verify [--cwd <dir>] --fact <file> [--json]
+  buildchain facts compatibility project [--cwd <dir>] [--registry <json-or-path>]
+                                      [--output <file>] [--json]
+  buildchain facts compatibility verify [--cwd <dir>] [--registry <json-or-path>] [--json]
+  buildchain facts compatibility query --query <json-or-path>
+                                      [--registry <json-or-path>] [--cwd <dir>] [--json]
+  buildchain facts compatibility query-template --fact-root <sha256:...>
+                                      [--query-id <id>] [--registry <json-or-path>]
+                                      [--cwd <dir>] [--json]
   buildchain kfd ...
   buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
                      [--declaration <path>] [--output-dir <path>]

package/scripts/check-ci-lane-change-budget.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { evaluateCiLaneChangeBudget } from "../packages/core/ci-lane-change-budget.js";
+
+const root = process.cwd();
+const workflowRoot = path.join(root, ".github", "workflows");
+const policyPath = path.join(
+  root,
+  "architecture",
+  "ci-lane-change-budget.json",
+);
+
+const workflows = fs
+  .readdirSync(workflowRoot, { withFileTypes: true })
+  .filter((entry) => entry.isFile() && /\.(?:yaml|yml)$/u.test(entry.name))
+  .map((entry) => {
+    const workflowPath = path.posix.join(".github/workflows", entry.name);
+    return {
+      path: workflowPath,
+      text: fs.readFileSync(path.join(workflowRoot, entry.name), "utf8"),
+    };
+  })
+  .sort((left, right) => left.path.localeCompare(right.path));
+
+const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+const baselineRevision = String(policy.baseline?.gitRevision || "").trim();
+if (!/^[0-9a-f]{40}$/u.test(baselineRevision)) {
+  throw new Error("baseline.gitRevision must be an exact Git commit");
+}
+const embeddedBaselineLanes = policy.baseline?.lanes;
+if (
+  !Array.isArray(embeddedBaselineLanes) ||
+  embeddedBaselineLanes.length === 0
+) {
+  throw new Error("baseline.lanes must contain the exact offline lane set");
+}
+const embeddedLaneSetRoot = `sha256:${crypto
+  .createHash("sha256")
+  .update(`${JSON.stringify(embeddedBaselineLanes)}\n`)
+  .digest("hex")}`;
+if (embeddedLaneSetRoot !== policy.baseline?.laneSetRoot) {
+  throw new Error("baseline laneSetRoot does not match baseline.lanes");
+}
+
+let baselineWorkflows = null;
+try {
+  execFileSync("git", ["cat-file", "-e", `${baselineRevision}^{commit}`], {
+    cwd: root,
+    stdio: "ignore",
+  });
+  const baselinePaths = execFileSync(
+    "git",
+    [
+      "ls-tree",
+      "-r",
+      "--name-only",
+      baselineRevision,
+      "--",
+      ".github/workflows",
+    ],
+    { cwd: root, encoding: "utf8" },
+  )
+    .split(/\r?\n/u)
+    .filter((value) => /\.(?:yaml|yml)$/u.test(value))
+    .sort();
+  baselineWorkflows = baselinePaths.map((workflowPath) => ({
+    path: workflowPath,
+    text: execFileSync("git", ["show", `${baselineRevision}:${workflowPath}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  }));
+} catch {
+  // Shallow and exported source cuts may not contain the pinned commit object.
+  // The content-rooted embedded lane set remains the exact offline authority.
+}
+
+const embeddedEvaluation = evaluateCiLaneChangeBudget({
+  policy,
+  workflows,
+});
+const evaluation = baselineWorkflows
+  ? evaluateCiLaneChangeBudget({ policy, workflows, baselineWorkflows })
+  : embeddedEvaluation;
+if (
+  baselineWorkflows &&
+  (evaluation.baselineLaneCount !== embeddedEvaluation.baselineLaneCount ||
+    JSON.stringify(evaluation.newLanes) !==
+      JSON.stringify(embeddedEvaluation.newLanes))
+) {
+  throw new Error(
+    "embedded baseline lanes do not match the pinned baseline revision",
+  );
+}
+process.stdout.write(`${JSON.stringify(evaluation, null, 2)}\n`);
+if (!evaluation.ok) process.exitCode = 1;

package/scripts/check-inventory.mjs

@@ -54,6 +54,10 @@ const requiredPaths = [
   "packages/core/homebrew.js",
   "packages/core/artifact-verification-envelope.js",
   "packages/core/anchored-version-material.js",
+  "packages/core/next-development-transition.js",
+  "packages/core/next-development-controller.js",
+  "packages/core/next-development-candidate-reservation.js",
+  "packages/core/next-development-projection.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/publication-reproducibility.js",
@@ -76,6 +80,8 @@ const requiredPaths = [
   "docs/auditable-demo.md",
   "contracts/auditable-demo-scenario-v1.schema.json",
   "contracts/release-candidate-recovery-v1.schema.json",
+  "contracts/next-development-request-v1.schema.json",
+  "contracts/next-development-transition-v1.schema.json",
   "contracts/auditable-demo-media-profiles-v1.json",
   "contracts/evidence/auditable-demo-web-delivery-v1.json",
   "contracts/evidence/auditable-demo-responsive-web-delivery-v1.json",
@@ -87,10 +93,15 @@ const requiredPaths = [
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/public-projection.json",
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
+  "docs/next-development-transition.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
   "docs/versioning.md",
   "scripts/release-line-dry-run.mjs",
+  "scripts/next-development-transition.mjs",
+  "scripts/next-development-self-dogfood.mjs",
+  "scripts/next-development-self-dogfood-harness.mjs",
+  "scripts/generate-next-development-guidance.mjs",
   "scripts/reconcile-release-governance.mjs",
   "scripts/buildchain-channel-router.mjs",
   "scripts/generate-channel-build-workflow.mjs",
@@ -1010,16 +1021,16 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: write",
-  "uses: ./.github/workflows/.release-candidate-promote.yml",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4-alpha",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): release v')",
   "resume-candidate-run-id:",
   "resume-expected-source-tree:",
   "resume-buildchain-runtime-sha:",
-  "github-release: true",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4",
   "release-passport-buildchain-self-kfd: true",
-  "artifact-patterns: ${{ startsWith(github.event.workflow_run.head_branch || inputs['target-ref'], 'alpha/') && 'buildchain-package-*' || '' }}",
+  "buildchain-channel: alpha",
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

package/scripts/check-project-cut-merge-queue-admission.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import {
+  ProjectCutAdmissionError,
+  qualifyProjectCut,
+  releaseFamilyQueueLease,
+} from "./project-cut-merge-queue-admission.mjs";
+
+function parseArguments(argv) {
+  const options = {};
+  const names = new Map([
+    ["--base", "base"],
+    ["--head", "head"],
+    ["--initiative-id", "initiativeId"],
+    ["--assignment-id", "assignmentId"],
+    ["--delivery-class", "deliveryClass"],
+    ["--queue-attempt", "queueAttempt"],
+    ["--admission-proof-root", "admissionProofRoot"],
+    ["--release-family-marker", "releaseFamilyMarker"],
+    ["--expected-pr-head", "expectedPullRequestHead"],
+    ["--terminal-reason", "terminalReason"],
+    ["--evidence-root", "evidenceRoot"],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index];
+    const key = names.get(name);
+    if (!key) throw new Error(`unknown argument: ${name}`);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--"))
+      throw new Error(`${name} requires a value`);
+    if (Object.hasOwn(options, key))
+      throw new Error(`${name} was provided more than once`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function markerText(path) {
+  return path === "-"
+    ? fs.readFileSync(0, "utf8")
+    : fs.readFileSync(path, "utf8");
+}
+
+function repairReceipt(error) {
+  return {
+    schema: "project.cut.merge-queue-admission/v1",
+    ok: false,
+    decision: "repair-required",
+    retryable: false,
+    compositionChanged: false,
+    reasonCodes: [error.reasonCode],
+    error: error.message,
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  try {
+    const options = parseArguments(argv);
+    if (options.releaseFamilyMarker) {
+      console.log(
+        JSON.stringify(
+          releaseFamilyQueueLease(
+            markerText(options.releaseFamilyMarker),
+            options,
+          ),
+        ),
+      );
+      return 0;
+    }
+    if (!options.base || !options.head)
+      throw new Error("--base and --head are required");
+    console.log(
+      JSON.stringify(qualifyProjectCut({ cwd: process.cwd(), ...options })),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof ProjectCutAdmissionError) {
+      console.log(JSON.stringify(repairReceipt(error)));
+      return 1;
+    }
+    console.error(`project-cut admission error: ${error.message}`);
+    return 2;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exitCode = main();

package/scripts/check-v4-floating-consumer-policy-contract.mjs

@@ -52,8 +52,13 @@ function assertOrdered(relative, markers) {
 
 export function assertPromotionCertificationWiring(source) {
   for (const marker of [
-    ".buildchain/runtime/promotion-shell/scripts/v4-consumer-policy.mjs certify",
-    '--caller-root "${{ github.workspace }}"',
+    "path: .buildchain/runtime/candidate-policy-runtime",
+    "BUILDCHAIN_EXPECTED_RUNTIME_SHA: ${{ steps.v4-policy-caller.outputs.runtime-sha }}",
+    "policy_runtime=.buildchain/runtime",
+    'node "${policy_runtime}/scripts/v4-consumer-policy.mjs" certify',
+    "passport.consumerPolicy?.receipt?.caller?.sourceSha",
+    "path: .buildchain/runtime/policy-caller",
+    '--caller-root "${{ github.workspace }}/.buildchain/runtime/policy-caller"',
     '--stable-lock "${{ inputs.buildchain-stable-contract-lock-path }}"',
     '--alpha-lock "${{ inputs.buildchain-alpha-contract-lock-path }}"',
     "release-passport-v4-consumer-policy-certification-root: ${{ steps.v4-policy-certification.outputs.v4-consumer-policy-certification-root }}",
@@ -78,13 +83,22 @@ function assertPersistedSelectors() {
       );
       if (!match) continue;
       const selector = match[2];
+      const protectedBootstrap =
+        relative ===
+          ".github/workflows/buildchain-ref-promotion-recovery.yml" &&
+        match[1] === ".github/workflows/.release-candidate-promote.yml" &&
+        selector === "alpha/v4/v4.0";
       const isV4 =
         selector === "v4" ||
         selector === "v4-alpha" ||
         /^v4(?:[./-]|$)/u.test(selector) ||
         /^[0-9a-f]{40}$/iu.test(selector) ||
         selector.includes("${{");
-      if (isV4 && !["v4", "v4-alpha"].includes(selector)) {
+      if (
+        (isV4 || protectedBootstrap) &&
+        !["v4", "v4-alpha"].includes(selector) &&
+        !protectedBootstrap
+      ) {
         offenders.push(`${relative}:${node.line} @${selector}`);
       }
     }
@@ -112,7 +126,12 @@ export function checkV4FloatingConsumerPolicyContract() {
     "Enforce v4 floating consumer policy",
     "Validate consumer package manager contract",
   ]);
-  if (!read(".github/workflows/.build.yml").includes("BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: ${{ inputs.buildchain-expected-channel }}")) fail("channel builds must disambiguate dual-channel caller invocations");
+  if (
+    !read(".github/workflows/.build.yml").includes(
+      "BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: ${{ inputs.buildchain-expected-channel }}",
+    )
+  )
+    fail("channel builds must disambiguate dual-channel caller invocations");
   assertTrustGatedJobs(read(".github/workflows/.build.yml"), [
     "resolve-source",
     "resolve-contract",

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