@kungfu-tech/buildchain 3.0.9-alpha.2 → 3.0.9-alpha.4

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

@@ -28,7 +28,29 @@ function priorOwnershipPlan(plan) {
   };
 }
 
-function campaignRunsWithNoWork(plan) {
+function assertRunMatchesPolicy(plan, run, jobs, jobCount, artifactCount) {
+  if (plan.github.priorRunPolicy === "unused") {
+    if (jobCount !== 0 || artifactCount !== 0) {
+      throw new Error(
+        `macOS campaign run ${run.id} already has jobs or artifacts`,
+      );
+    }
+    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 campaignRunReceipts(plan) {
   const branch = sourceRefName(plan.source.ref);
   const response = ghJson(
     [
@@ -68,19 +90,35 @@ 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`,
-      );
-    }
+    assertRunMatchesPolicy(plan, run, jobs, jobCount, artifactCount);
     receipts.push({
       runId: String(run.id),
       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,
+      })),
     });
   }
+  if (plan.github.priorRunPolicy === "terminal-failure") {
+    const observed = receipts
+      .map((receipt) => receipt.runId)
+      .sort((left, right) => Number(left) - Number(right));
+    if (
+      JSON.stringify(observed) !==
+      JSON.stringify(plan.github.terminalFailureRunIds)
+    ) {
+      throw new Error(
+        "macOS campaign terminal failed run inventory does not match the confirmed run ids",
+      );
+    }
+  }
   return receipts;
 }
 
@@ -286,7 +324,7 @@ function assertZeroCampaignResidue(plan, profile) {
   if (matchingRunners.length !== 0) {
     throw new Error("macOS campaign already has a registered JIT runner");
   }
-  const evidenceObjectCounts = {};
+  const evidenceObjects = {};
   for (const sourceSha of [plan.previousSource.sha, plan.source.sha]) {
     const evidence = awsJson(
       plan,
@@ -299,27 +337,43 @@ 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 previousTerminalEvidence =
+      sourceSha === plan.previousSource.sha &&
+      plan.github.priorRunPolicy === "terminal-failure";
+    if (
+      (!previousTerminalEvidence && count !== 0) ||
+      (previousTerminalEvidence && 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 +534,10 @@ 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"
+        : "rebound-zero-allocation",
     repository: plan.repository,
     campaign: plan.campaign,
     previousSource: plan.previousSource,

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",

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/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-site-bundle.mjs

@@ -368,6 +368,7 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "release-train": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 132 },
+  "next-development-transition": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 133 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
@@ -733,6 +734,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-train.md",
+      "docs/next-development-transition.md",
       "docs/stable-candidate-patrol.md",
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",

package/scripts/init-repo.mjs

@@ -3,21 +3,35 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
-import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
+import {
+  detectPackageManager,
+  assertPackageManager,
+} from "../packages/core/package-manager.js";
 import {
   PUBLICATION_REHEARSAL_WORKFLOW_PATH,
   appendPublicationRehearsalToml,
   mergePublicationRehearsalAgentInstructions,
   publicationRehearsalWorkflow,
 } from "../packages/core/publication-rehearsal-projection.js";
-
-const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
-const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
-const DEFAULT_PUBLICATION_LATEX_DIGEST = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8";
-const DEFAULT_PUBLICATION_LATEX_COMMAND = "latexmk -pdf -outdir=_build paper/main.tex";
+import {
+  appendNextDevelopmentToml,
+  mergeNextDevelopmentAgentInstructions,
+  nextDevelopmentWorkflowHeader,
+} from "../packages/core/next-development-projection.js";
+
+const BUILDCHAIN_WORKFLOW_REF =
+  "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
+const DEFAULT_PUBLICATION_LATEX_IMAGE =
+  "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
+const DEFAULT_PUBLICATION_LATEX_DIGEST =
+  "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8";
+const DEFAULT_PUBLICATION_LATEX_COMMAND =
+  "latexmk -pdf -outdir=_build paper/main.tex";
 
 function posixPath(value) {
-  return String(value || "").split(path.sep).join("/");
+  return String(value || "")
+    .split(path.sep)
+    .join("/");
 }
 
 function repoName(cwd) {
@@ -282,34 +296,42 @@ command = "make check"
 }
 
 function infraContractDesiredJson(cwd) {
-  return `${JSON.stringify({
-    service: repoName(cwd),
-    environment: "staging",
-    resources: [
-      {
-        kind: "static-site",
-        name: repoName(cwd),
-        desiredState: {
-          hostname: "staging.example.com",
-          accessControl: "managed-network",
-          owner: "platform",
+  return `${JSON.stringify(
+    {
+      service: repoName(cwd),
+      environment: "staging",
+      resources: [
+        {
+          kind: "static-site",
+          name: repoName(cwd),
+          desiredState: {
+            hostname: "staging.example.com",
+            accessControl: "managed-network",
+            owner: "platform",
+          },
         },
-      },
-    ],
-  }, null, 2)}\n`;
+      ],
+    },
+    null,
+    2,
+  )}\n`;
 }
 
 function infraContractOutputsJson(cwd) {
-  return `${JSON.stringify({
-    service: repoName(cwd),
-    environment: "staging",
-    observedMode: "manual-observed",
-    outputs: {
-      hostname: "staging.example.com",
-      distributionId: "observed-distribution-id",
-      bucket: "observed-bucket-name",
+  return `${JSON.stringify(
+    {
+      service: repoName(cwd),
+      environment: "staging",
+      observedMode: "manual-observed",
+      outputs: {
+        hostname: "staging.example.com",
+        distributionId: "observed-distribution-id",
+        bucket: "observed-bucket-name",
+      },
     },
-  }, null, 2)}\n`;
+    null,
+    2,
+  )}\n`;
 }
 
 function workflowArtifactPaths(type) {
@@ -333,7 +355,7 @@ function workflowArtifactPaths(type) {
 }
 
 function publicationWorkflowYaml() {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -365,7 +387,7 @@ jobs:
 }
 
 function workflowYaml({ type, runnerPreset, artifactName }) {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -400,7 +422,9 @@ jobs:
 
 function writeIfAllowed(filePath, content, { force }) {
   if (fs.existsSync(filePath) && !force) {
-    throw new Error(`${posixPath(filePath)} already exists; pass --force to overwrite`);
+    throw new Error(
+      `${posixPath(filePath)} already exists; pass --force to overwrite`,
+    );
   }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
@@ -408,7 +432,9 @@ function writeIfAllowed(filePath, content, { force }) {
 }
 
 function writeManagedAgentEntry(filePath, current) {
-  const content = mergePublicationRehearsalAgentInstructions(current);
+  const content = mergeNextDevelopmentAgentInstructions(
+    mergePublicationRehearsalAgentInstructions(current),
+  );
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
   return filePath;
@@ -424,27 +450,33 @@ export function initBuildchainRepo({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const manager = detectOrDefaultPackageManager(resolvedCwd, packageManager);
-  const toml = appendPublicationRehearsalToml((() => {
-    if (type === "package") {
-      return packageToml(resolvedCwd, manager);
-    }
-    if (type === "native") {
-      return nativeToml(resolvedCwd);
-    }
-    if (type === "web-surface") {
-      return webSurfaceToml(resolvedCwd);
-    }
-    if (type === "infra-contract") {
-      return infraContractToml(resolvedCwd);
-    }
-    if (type === "publication-artifact") {
-      return publicationArtifactToml(resolvedCwd);
-    }
-    if (type === "anchored-package") {
-      return anchoredPackageToml(resolvedCwd, manager);
-    }
-    throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
-  })());
+  const toml = appendNextDevelopmentToml(
+    appendPublicationRehearsalToml(
+      (() => {
+        if (type === "package") {
+          return packageToml(resolvedCwd, manager);
+        }
+        if (type === "native") {
+          return nativeToml(resolvedCwd);
+        }
+        if (type === "web-surface") {
+          return webSurfaceToml(resolvedCwd);
+        }
+        if (type === "infra-contract") {
+          return infraContractToml(resolvedCwd);
+        }
+        if (type === "publication-artifact") {
+          return publicationArtifactToml(resolvedCwd);
+        }
+        if (type === "anchored-package") {
+          return anchoredPackageToml(resolvedCwd, manager);
+        }
+        throw new Error(
+          "init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package",
+        );
+      })(),
+    ),
+  );
 
   const agentsPath = path.join(resolvedCwd, "AGENTS.md");
   const currentAgents = fs.existsSync(agentsPath)
@@ -452,7 +484,9 @@ export function initBuildchainRepo({
     : "";
 
   const written = [
-    writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
+    writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, {
+      force,
+    }),
     writeIfAllowed(
       path.join(resolvedCwd, ".github", "workflows", "build.yml"),
       type === "publication-artifact"
@@ -472,14 +506,31 @@ export function initBuildchainRepo({
     writeManagedAgentEntry(agentsPath, currentAgents),
   ];
 
-  if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {
-    written.push(writeIfAllowed(path.join(resolvedCwd, "release.json"), "{\n  \"upstream\": \"\",\n  \"version\": \"0.0.0\"\n}\n", { force }));
+  if (
+    type === "anchored-package" &&
+    !fs.existsSync(path.join(resolvedCwd, "release.json"))
+  ) {
+    written.push(
+      writeIfAllowed(
+        path.join(resolvedCwd, "release.json"),
+        '{\n  "upstream": "",\n  "version": "0.0.0"\n}\n',
+        { force },
+      ),
+    );
   }
 
   if (type === "infra-contract") {
     written.push(
-      writeIfAllowed(path.join(resolvedCwd, "infra", "desired.json"), infraContractDesiredJson(resolvedCwd), { force }),
-      writeIfAllowed(path.join(resolvedCwd, "infra", "outputs.json"), infraContractOutputsJson(resolvedCwd), { force }),
+      writeIfAllowed(
+        path.join(resolvedCwd, "infra", "desired.json"),
+        infraContractDesiredJson(resolvedCwd),
+        { force },
+      ),
+      writeIfAllowed(
+        path.join(resolvedCwd, "infra", "outputs.json"),
+        infraContractOutputsJson(resolvedCwd),
+        { force },
+      ),
     );
   }
 
@@ -489,7 +540,9 @@ export function initBuildchainRepo({
     cwd: resolvedCwd,
     packageManager: manager,
     workflowRef: BUILDCHAIN_WORKFLOW_REF,
-    written: written.map((filePath) => posixPath(path.relative(resolvedCwd, filePath))),
+    written: written.map((filePath) =>
+      posixPath(path.relative(resolvedCwd, filePath)),
+    ),
   };
 }
 
@@ -501,7 +554,11 @@ function readArg(name, fallback = "") {
   return process.argv[index + 1] || "";
 }
 
-if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (
+  !process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
   try {
     const result = initBuildchainRepo({
       cwd: readArg("cwd", process.cwd()),