@kungfu-tech/buildchain 3.0.9-alpha.0 → 3.0.9-alpha.10

package/scripts/aws-macos-jit-source-rebind.mjs

@@ -28,7 +28,169 @@ function priorOwnershipPlan(plan) {
   };
 }
 
-function campaignRunsWithNoWork(plan) {
+function assertRunMatchesPolicy(policy, run, jobs, jobCount, artifactCount) {
+  if (policy === "unused") {
+    if (jobCount !== 0 || artifactCount !== 0) {
+      throw new Error(
+        `macOS campaign run ${run.id} already has jobs or artifacts`,
+      );
+    }
+    return;
+  }
+  if (policy === "preflight-failure") {
+    const jobList = jobs.jobs || [];
+    const failedJobs = jobList.filter((job) => job.conclusion === "failure");
+    const nonFailedJobs = jobList.filter((job) => job.conclusion !== "failure");
+    const hasJitLabel = jobList.some((job) =>
+      (job.labels || []).some((label) =>
+        String(label.name || label).startsWith(MACOS_JIT_RUNNER_LABEL_PREFIX),
+      ),
+    );
+    if (
+      run.status !== "completed" ||
+      run.conclusion !== "failure" ||
+      jobCount === 0 ||
+      artifactCount === 0 ||
+      jobList.some((job) => job.status !== "completed") ||
+      failedJobs.length !== 1 ||
+      !String(failedJobs[0].name || "").endsWith(" / Trust gate") ||
+      nonFailedJobs.some((job) => job.conclusion !== "skipped") ||
+      hasJitLabel
+    ) {
+      throw new Error(
+        `macOS campaign run ${run.id} is not an exact preflight Trust gate failure`,
+      );
+    }
+    return;
+  }
+  if (
+    run.status !== "completed" ||
+    run.conclusion !== "failure" ||
+    jobCount === 0 ||
+    artifactCount === 0 ||
+    (jobs.jobs || []).some((job) => job.status !== "completed")
+  ) {
+    throw new Error(
+      `macOS campaign run ${run.id} is not a terminal failed run with retained evidence`,
+    );
+  }
+}
+
+function assertExactStartupFailure(run, jobCount, artifactCount) {
+  if (
+    run.status !== "completed" ||
+    run.conclusion !== "startup_failure" ||
+    jobCount !== 0 ||
+    artifactCount !== 0
+  ) {
+    throw new Error(
+      `macOS campaign run ${run.id} is not an exact startup failure`,
+    );
+  }
+}
+
+function assertExactSuccessfulRun(run, jobs, jobCount, artifactCount) {
+  if (
+    run.status !== "completed" ||
+    run.conclusion !== "success" ||
+    jobCount === 0 ||
+    artifactCount === 0 ||
+    (jobs.jobs || []).some((job) => job.status !== "completed")
+  ) {
+    throw new Error(
+      `macOS campaign run ${run.id} is not a terminal successful run with retained evidence`,
+    );
+  }
+}
+
+function classifyCampaignRun(plan, run) {
+  const startupFailure = plan.github.startupFailureRuns.find(
+    ({ runId }) => runId === String(run.id),
+  );
+  const historicalTerminalFailure =
+    plan.github.historicalTerminalFailureRuns.find(
+      ({ runId }) => runId === String(run.id),
+    );
+  const historicalPreflightFailure =
+    plan.github.historicalPreflightFailureRuns.find(
+      ({ runId }) => runId === String(run.id),
+    );
+  const preflightFailure = plan.github.preflightFailureRunIds.includes(
+    String(run.id),
+  );
+  const successfulRun = plan.github.successfulRunIds.includes(String(run.id));
+  return {
+    startupFailure,
+    historicalTerminalFailure,
+    historicalPreflightFailure,
+    successfulRun,
+    expectedSourceSha:
+      startupFailure?.sourceSha ||
+      historicalTerminalFailure?.sourceSha ||
+      historicalPreflightFailure?.sourceSha ||
+      plan.previousSource.sha,
+    classification: startupFailure
+      ? "startup-failure"
+      : historicalTerminalFailure
+        ? "historical-terminal-failure"
+        : historicalPreflightFailure
+          ? "historical-preflight-failure"
+          : successfulRun
+            ? "successful-run"
+            : preflightFailure
+              ? "preflight-failure"
+              : plan.github.priorRunPolicy,
+  };
+}
+
+function exactReceiptInventory(receipts, classification, withSource = false) {
+  return receipts
+    .filter((receipt) => receipt.classification === classification)
+    .map((receipt) =>
+      withSource
+        ? { runId: receipt.runId, sourceSha: receipt.sourceSha }
+        : receipt.runId,
+    )
+    .sort(
+      (left, right) =>
+        Number(withSource ? left.runId : left) -
+        Number(withSource ? right.runId : right),
+    );
+}
+
+function assertExactReceiptInventories(plan, receipts) {
+  if (plan.github.priorRunPolicy === "unused") return;
+  const inventories = [
+    ["terminal-failure", plan.github.terminalFailureRunIds, false],
+    ["preflight-failure", plan.github.preflightFailureRunIds, false],
+    ["successful-run", plan.github.successfulRunIds, false],
+    ["startup-failure", plan.github.startupFailureRuns, true],
+    [
+      "historical-terminal-failure",
+      plan.github.historicalTerminalFailureRuns,
+      true,
+    ],
+    [
+      "historical-preflight-failure",
+      plan.github.historicalPreflightFailureRuns,
+      true,
+    ],
+  ];
+  for (const [classification, expected, withSource] of inventories) {
+    const observed = exactReceiptInventory(
+      receipts,
+      classification,
+      withSource,
+    );
+    if (JSON.stringify(observed) !== JSON.stringify(expected)) {
+      throw new Error(
+        `macOS campaign ${classification} inventory does not match the confirmed runs`,
+      );
+    }
+  }
+}
+
+function campaignRunReceipts(plan) {
   const branch = sourceRefName(plan.source.ref);
   const response = ghJson(
     [
@@ -46,7 +208,8 @@ function campaignRunsWithNoWork(plan) {
   }
   const receipts = [];
   for (const run of matching) {
-    if (run.head_sha !== plan.previousSource.sha) {
+    const classification = classifyCampaignRun(plan, run);
+    if (run.head_sha !== classification.expectedSourceSha) {
       throw new Error(
         `macOS campaign run ${run.id} is bound to an unexpected source`,
       );
@@ -68,19 +231,41 @@ function campaignRunsWithNoWork(plan) {
     const artifactCount = Number(
       artifacts.total_count || (artifacts.artifacts || []).length || 0,
     );
-    if (jobCount !== 0 || artifactCount !== 0) {
-      throw new Error(
-        `macOS campaign run ${run.id} already has jobs or artifacts`,
+    if (classification.startupFailure) {
+      assertExactStartupFailure(run, jobCount, artifactCount);
+    } else if (classification.successfulRun) {
+      assertExactSuccessfulRun(run, jobs, jobCount, artifactCount);
+    } else {
+      assertRunMatchesPolicy(
+        classification.historicalTerminalFailure
+          ? "terminal-failure"
+          : classification.historicalPreflightFailure
+            ? "preflight-failure"
+            : plan.github.priorRunPolicy,
+        run,
+        jobs,
+        jobCount,
+        artifactCount,
       );
     }
     receipts.push({
       runId: String(run.id),
+      sourceSha: String(run.head_sha || ""),
+      classification: classification.classification,
       status: String(run.status || "unknown"),
       conclusion: String(run.conclusion || ""),
       jobCount,
       artifactCount,
+      artifacts: (artifacts.artifacts || []).map((artifact) => ({
+        id: String(artifact.id),
+        name: String(artifact.name || ""),
+        sizeInBytes: Number(artifact.size_in_bytes || 0),
+        digest: String(artifact.digest || ""),
+        expired: artifact.expired === true,
+      })),
     });
   }
+  assertExactReceiptInventories(plan, receipts);
   return receipts;
 }
 
@@ -286,8 +471,22 @@ function assertZeroCampaignResidue(plan, profile) {
   if (matchingRunners.length !== 0) {
     throw new Error("macOS campaign already has a registered JIT runner");
   }
-  const evidenceObjectCounts = {};
-  for (const sourceSha of [plan.previousSource.sha, plan.source.sha]) {
+  const evidenceObjects = {};
+  const historicalTerminalSources =
+    plan.github.historicalTerminalFailureRuns.map(({ sourceSha }) => sourceSha);
+  const historicalPreflightSources =
+    plan.github.historicalPreflightFailureRuns.map(
+      ({ sourceSha }) => sourceSha,
+    );
+  const evidenceSources = [
+    ...new Set([
+      plan.previousSource.sha,
+      ...historicalTerminalSources,
+      ...historicalPreflightSources,
+      plan.source.sha,
+    ]),
+  ];
+  for (const sourceSha of evidenceSources) {
     const evidence = awsJson(
       plan,
       profile,
@@ -299,27 +498,44 @@ function assertZeroCampaignResidue(plan, profile) {
         "--prefix",
         `macos/${sourceSha}/`,
         "--max-keys",
-        "1",
+        "1000",
         "--output",
         "json",
       ],
       `macOS campaign evidence inventory for ${sourceSha}`,
     );
+    if (evidence.IsTruncated === true) {
+      throw new Error(
+        `macOS campaign source ${sourceSha} evidence inventory is incomplete`,
+      );
+    }
+    const objects = (evidence.Contents || []).map((object) => ({
+      key: String(object.Key || ""),
+      size: Number(object.Size || 0),
+      etag: String(object.ETag || ""),
+    }));
     const count = Number(
       evidence.KeyCount || (evidence.Contents || []).length || 0,
     );
-    if (count !== 0) {
+    const terminalEvidenceSource =
+      (sourceSha === plan.previousSource.sha &&
+        plan.github.priorRunPolicy === "terminal-failure") ||
+      historicalTerminalSources.includes(sourceSha);
+    if (
+      (!terminalEvidenceSource && count !== 0) ||
+      (terminalEvidenceSource && count === 0)
+    ) {
       throw new Error(
-        `macOS campaign source ${sourceSha} already has bootstrap evidence`,
+        `macOS campaign source ${sourceSha} bootstrap evidence does not match the rebind policy`,
       );
     }
-    evidenceObjectCounts[sourceSha] = count;
+    evidenceObjects[sourceSha] = objects;
   }
   return {
-    priorRuns: campaignRunsWithNoWork(plan),
+    priorRuns: campaignRunReceipts(plan),
     jitParameterCount: parameters.length,
     runnerCount: matchingRunners.length,
-    evidenceObjectCounts,
+    evidenceObjects,
   };
 }
 
@@ -480,7 +696,12 @@ export function executeMacosJitSourceRebind(plan, { profile = "" } = {}) {
     schemaVersion: 1,
     contract: AWS_MACOS_JIT_CONTROLLER_CONTRACT,
     kind: "campaign-source-rebind-result",
-    status: "rebound-zero-allocation",
+    status:
+      plan.github.priorRunPolicy === "terminal-failure"
+        ? "rebound-after-terminal-failure-zero-allocation"
+        : plan.github.priorRunPolicy === "preflight-failure"
+          ? "rebound-after-preflight-failure-zero-allocation"
+          : "rebound-zero-allocation",
     repository: plan.repository,
     campaign: plan.campaign,
     previousSource: plan.previousSource,

package/scripts/aws-macos-jit.mjs

@@ -25,6 +25,17 @@ function writeJson(file, value) {
   return resolved;
 }
 
+export function writeMacosJitQualificationEnvironment(
+  githubEnv = process.env.GITHUB_ENV,
+) {
+  if (!githubEnv) return false;
+  fs.appendFileSync(
+    path.resolve(githubEnv),
+    "BUILDCHAIN_SIGNING_REQUESTS_ENABLED=false\n",
+  );
+  return true;
+}
+
 export function main() {
   const mode = process.argv[2] || "plan";
   if (mode === "plan") {
@@ -64,6 +75,7 @@ export function main() {
         ".buildchain/aws-macos-jit.json",
       result,
     );
+    writeMacosJitQualificationEnvironment();
     process.stdout.write(`${output}\n`);
     return result;
   }

package/scripts/buildchain-channel-router.mjs

@@ -105,8 +105,24 @@ export function resolveBuildchainChannel({
     if (channel !== "auto" && explicitRef.kind !== "override" && channel !== explicitRef.kind) {
       throw new Error(`buildchain-channel=${channel} conflicts with buildchain-ref=${explicitRef.ref}`);
     }
-    if (channel !== "auto" && explicitRef.kind === "override") {
-      throw new Error("train, authority, and exact-SHA buildchain-ref overrides require buildchain-channel=auto");
+    if (explicitRef.kind === "override") {
+      const lane = resolveBuildchainChannel({
+        requestedChannel: channel,
+        requestedRef: "",
+        publishChannel,
+        eventName,
+        gitRef,
+        releasePrerelease,
+        routerRef: `v${major}`,
+        packageVersion,
+      });
+      return {
+        ...lane,
+        major,
+        buildchainRef: explicitRef.ref,
+        selectionSource: "explicit-buildchain-ref+channel-evidence",
+        reason: `trusted runtime override ${explicitRef.ref} bound to ${lane.channel}`,
+      };
     }
     return {
       channel: explicitRef.kind,

package/scripts/buildchain-cli-help.mjs

@@ -129,11 +129,18 @@ export const BUILDCHAIN_USAGE = `Usage:
                              [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>]
                              [--check-response-timeout-minutes <n>]
                              [--max-entries-to-build <n>] [--apply]
-  buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe>
+  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|cancel-queued|observe>
                              --repository <owner/repo> --branch <dev/vN/vN.M>
                              [--execute] [--output <file>] [--json]
-  buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration>
+  buildchain dev authority <migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe>
+                             --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--execute] [--output <file>] [--json]
+  buildchain dev proof <source|verify-source|classify|native|verify-native|classify-native|verify-native-reuse|replay|integration|verify-integration>
                              [--output <file>] [--json]
+  buildchain dev two-phase --repository <owner/repo> --branch <dev/vN/vN.M>
+                             --pull-request <n> --expected-head <sha>
+                             --warrant-result <file> [--native-proof <file>]
+                             [--native-command <command>]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
                  [--path <jsonl>] [--json]

package/scripts/buildchain-contract-lock.mjs

@@ -69,6 +69,10 @@ export function checkBuildchainContractLock({
   runtimeSha = env("BUILDCHAIN_RUNTIME_SHA"),
   runtimeClass = env("BUILDCHAIN_RUNTIME_CLASS"),
   compatibilityPolicy = env("BUILDCHAIN_CONTRACT_COMPATIBILITY_POLICY"),
+  workflowShellRef = env("BUILDCHAIN_WORKFLOW_SHELL_REF"),
+  expectedChannel = env("BUILDCHAIN_EXPECTED_CHANNEL"),
+  expectedMajor = env("BUILDCHAIN_EXPECTED_MAJOR"),
+  allowOpaqueRuntime = boolEnv("BUILDCHAIN_ALLOW_OPAQUE_RUNTIME"),
   issueMode = env("BUILDCHAIN_CONTRACT_DRIFT_ISSUE_MODE", "compatible-and-breaking"),
   issueBodyPath = env("BUILDCHAIN_CONTRACT_DRIFT_ISSUE_BODY", ".buildchain/contract-drift/issue-body.md"),
   repository = env("GITHUB_REPOSITORY"),
@@ -84,6 +88,10 @@ export function checkBuildchainContractLock({
     runtimeSha,
     runtimeClass,
     compatibilityPolicy,
+    workflowShellRef,
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
   });
   const shouldIssue = issueModeAllows(issueMode, evaluation);
   if (shouldIssue) {
@@ -104,6 +112,8 @@ export function checkBuildchainContractLock({
     `- Compatible: \`${evaluation.compatible ? "true" : "false"}\``,
     `- Runtime ref: \`${runtimeRef || "(unknown)"}\``,
     `- Runtime SHA: \`${runtimeSha || "(unknown)"}\``,
+    `- Workflow shell ref: \`${workflowShellRef || "(unknown)"}\``,
+    evaluation.channelBinding ? `- Bound channel: \`${evaluation.channelBinding.channel || "(unknown)"}\`` : "",
     `- Contract digest: \`${current.contractDigest}\``,
     `- Compatibility digest: \`${current.compatibilityDigest}\``,
     `- Compatibility proof registry: \`${current.compatibilityProofRegistryRoot || "(legacy)"}\``,
@@ -128,7 +138,7 @@ export function checkBuildchainContractLock({
     "current-buildchain-sha": runtimeSha || "",
   });
   if (!evaluation.ok) {
-    throw new Error(`Buildchain contract drift is not compatible: ${(evaluation.reasons || []).join("; ")}`);
+    throw new Error(`Buildchain contract lock rejected: ${(evaluation.reasons || []).join("; ")}`);
   }
   return { evaluation, current, shouldIssue };
 }

package/scripts/check-internal-architecture.mjs

@@ -131,6 +131,7 @@ function repositoryJavaScriptFiles(root) {
     .filter((file) => [".js", ".mjs", ".cjs"].includes(path.extname(file)))
     .filter((file) => !file.startsWith("tests/"))
     .filter((file) => !/(?:^|\/)tests?\//u.test(file))
+    .filter((file) => !file.startsWith(".buildchain/"))
     .filter((file) => !/^actions\/[^/]+\/dist\//u.test(file))
     .sort();
 }

package/scripts/check-inventory.mjs

@@ -53,6 +53,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",
@@ -75,6 +79,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",
@@ -86,10 +92,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",
@@ -215,7 +226,7 @@ const selfDogfoodAlphaEvaluation = evaluateBuildchainContractLock({
   }),
   runtimeRef: `v${selfDogfoodMajor}-alpha`,
   runtimeSha: "current-development-contract",
-  runtimeClass: "alpha",
+  runtimeClass: "alpha", workflowShellRef: `v${selfDogfoodMajor}-alpha`,
 });
 if (
   !canAdmitSelfDogfoodLockEvaluation({
@@ -304,7 +315,7 @@ if (!promotionOverrideAuthorization.includes("promotion runtime override is only
 }
 for (const requiredSnippet of [
   "buildchain-channel:",
-  "uses: ./.github/workflows/.build.yml",
+  "uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3-alpha", "uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n",
   "needs.resolve-channel.outputs.buildchain-ref",
   "needs.resolve-channel.outputs.contract-lock-path",
 ]) {
@@ -992,7 +1003,7 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: write",
-  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@769b221bad7a6b9104afad4c2628d9dca396ab0f\n",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@cc6c32845ab5779009aeb48cc34efe65e229fe30\n",
   "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')",

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