@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/scripts/{v4-stage-capsule-resume-rehearsal.mjs → stage-capsule-resume-rehearsal.mjs}

@@ -4,8 +4,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { v4CanonicalBytes } from "../packages/core/v4-canonical-contracts.js";
-import { planV4StageCapsuleResume } from "../packages/core/v4-stage-capsule-resume-planner.js";
+import { domainCanonicalBytes } from "../packages/core/canonical-contracts.js";
+import { planStageCapsuleResume } from "../packages/core/stage-capsule-resume-planner.js";
 
 const repoRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -22,7 +22,7 @@ if (!platform) throw new Error("--platform is required");
 
 const declaration = JSON.parse(
   fs.readFileSync(
-    path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+    path.join(repoRoot, "architecture/platform-stage-checkpoints.json"),
     "utf8",
   ),
 );
@@ -38,13 +38,13 @@ const fixture = JSON.parse(
     "utf8",
   ),
 );
-const first = planV4StageCapsuleResume(fixture);
-const second = planV4StageCapsuleResume(structuredClone(fixture));
+const first = planStageCapsuleResume(fixture);
+const second = planStageCapsuleResume(structuredClone(fixture));
 if (first.planRoot !== second.planRoot)
   throw new Error("resume planner is not deterministic");
 
 process.stdout.write(
-  v4CanonicalBytes({
+  domainCanonicalBytes({
     schema: "buildchain-v4-stage-capsule-resume-rehearsal/v1",
     mode: "shadow-only",
     platform,

package/scripts/{v4-tail-reseal-macos-rehearsal.mjs → tail-reseal-macos-rehearsal.mjs}

@@ -6,8 +6,8 @@ import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
-import { verifyV4TailResealPlatform } from "./v4-tail-reseal.mjs";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
+import { verifyTailResealPlatform } from "./tail-reseal.mjs";
 
 function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
@@ -56,12 +56,12 @@ function writeCandidate(root, request, content) {
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   return {
-    artifactRoot: v4ContentRoot("tail-reseal-artifact-files", [file]),
+    artifactRoot: domainContentRoot("tail-reseal-artifact-files", [file]),
     manifestRoot: fileRoot(manifestPath),
   };
 }
 
-export function rehearseV4TailResealMacos({
+export function rehearseTailResealMacos({
   fixturePath = "contracts/fixtures/v4-tail-reseal-v1/valid.json",
   outputPath = "",
 } = {}) {
@@ -69,20 +69,20 @@ export function rehearseV4TailResealMacos({
     fs.readFileSync(path.resolve(fixturePath), "utf8"),
   );
   const workRoot = fs.mkdtempSync(
-    path.join(os.tmpdir(), "buildchain-v4-tail-macos-"),
+    path.join(os.tmpdir(), "buildchain-tail-macos-"),
   );
   try {
     const retainedRoots = writeCandidate(workRoot, request, "unsigned");
     const platform = request.platforms.find(({ id }) => id === "macos-arm64");
     Object.assign(platform, retainedRoots);
-    const retained = verifyV4TailResealPlatform({
+    const retained = verifyTailResealPlatform({
       request,
       platformId: "macos-arm64",
       artifactRoot: workRoot,
       mode: "retained",
     });
     writeCandidate(workRoot, request, "signed-and-notarized");
-    const resealed = verifyV4TailResealPlatform({
+    const resealed = verifyTailResealPlatform({
       request,
       platformId: "macos-arm64",
       artifactRoot: workRoot,
@@ -100,7 +100,7 @@ export function rehearseV4TailResealMacos({
     };
     const evidence = {
       ...payload,
-      evidenceRoot: v4ContentRoot("tail-reseal-admission", payload),
+      evidenceRoot: domainContentRoot("tail-reseal-admission", payload),
     };
     if (outputPath) {
       const output = path.resolve(outputPath);
@@ -118,7 +118,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    const evidence = rehearseV4TailResealMacos({
+    const evidence = rehearseTailResealMacos({
       fixturePath: flag(
         process.argv.slice(2),
         "fixture",

package/scripts/{v4-tail-reseal.mjs → tail-reseal.mjs}

@@ -6,13 +6,13 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
-  V4_TAIL_RESEAL_PLATFORMS,
-  normalizeV4TailResealRequest,
-  planV4TailReseal,
-} from "../packages/core/v4-tail-reseal.js";
-import { createV4TailResealReceipt } from "../packages/core/v4-tail-reseal-receipt.js";
-import { validateV4TailResealGitHubEvidence } from "../packages/core/v4-tail-reseal-github.js";
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+  TAIL_RESEAL_PLATFORMS,
+  normalizeTailResealRequest,
+  planTailReseal,
+} from "../packages/core/tail-reseal.js";
+import { createTailResealReceipt } from "../packages/core/tail-reseal-receipt.js";
+import { validateTailResealGitHubEvidence } from "../packages/core/tail-reseal-github.js";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
 
 function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
@@ -137,7 +137,7 @@ async function admitFromGitHub(request) {
       token,
     ),
   ]);
-  return validateV4TailResealGitHubEvidence({
+  return validateTailResealGitHubEvidence({
     request,
     sourceCommit,
     sourceRun,
@@ -183,14 +183,14 @@ function resolvePayload(root, relative, platformId) {
   return absolute;
 }
 
-export function verifyV4TailResealPlatform({
+export function verifyTailResealPlatform({
   request,
   platformId,
   artifactRoot,
   mode = "retained",
   providerReadbackRoot = null,
 } = {}) {
-  const normalized = normalizeV4TailResealRequest(request);
+  const normalized = normalizeTailResealRequest(request);
   const platform = normalized.platforms.find(({ id }) => id === platformId);
   if (!platform)
     throw new Error(`tail reseal request does not bind platform ${platformId}`);
@@ -243,7 +243,7 @@ export function verifyV4TailResealPlatform({
     );
   if (files.length === 0)
     throw new Error(`${platformId} manifest has no retained files`);
-  const observedArtifactRoot = v4ContentRoot(
+  const observedArtifactRoot = domainContentRoot(
     "tail-reseal-artifact-files",
     files,
   );
@@ -290,21 +290,21 @@ function collectReadbacks(directory) {
       throw new Error(`duplicate tail reseal readback for ${value.platformId}`);
     byPlatform.set(value.platformId, value);
   }
-  return V4_TAIL_RESEAL_PLATFORMS.map((platformId) => {
+  return TAIL_RESEAL_PLATFORMS.map((platformId) => {
     if (!byPlatform.has(platformId))
       throw new Error(`missing tail reseal readback for ${platformId}`);
     return byPlatform.get(platformId);
   });
 }
 
-export function runV4TailResealCli(args = process.argv.slice(2)) {
+export function runTailResealCli(args = process.argv.slice(2)) {
   const [command, ...options] = args;
   const requestPath = flag(options, "request");
   if (command === "plan") {
-    const request = normalizeV4TailResealRequest(
+    const request = normalizeTailResealRequest(
       readJson(required(requestPath, "--request"), "tail reseal request"),
     );
-    const plan = planV4TailReseal(request);
+    const plan = planTailReseal(request);
     const output = writeJson(
       flag(options, "output", ".buildchain/tail-reseal/plan.json"),
       plan,
@@ -331,7 +331,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
     return plan;
   }
   if (command === "admit") {
-    const request = normalizeV4TailResealRequest(
+    const request = normalizeTailResealRequest(
       readJson(required(requestPath, "--request"), "tail reseal request"),
     );
     return admitFromGitHub(request).then((admission) => {
@@ -347,7 +347,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
     });
   }
   if (command === "verify-platform") {
-    const readback = verifyV4TailResealPlatform({
+    const readback = verifyTailResealPlatform({
       request: readJson(required(requestPath, "--request")),
       platformId: required(flag(options, "platform"), "--platform"),
       artifactRoot: flag(options, "artifact-root", process.cwd()),
@@ -371,7 +371,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
   }
   if (command === "seal") {
     const request = readJson(required(requestPath, "--request"));
-    const receipt = createV4TailResealReceipt({
+    const receipt = createTailResealReceipt({
       request,
       plan: readJson(required(flag(options, "plan"), "--plan")),
       readbacks: collectReadbacks(
@@ -409,7 +409,7 @@ if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
-  runV4TailResealCli().catch((error) => {
+  runTailResealCli().catch((error) => {
     console.error(`tail-reseal: ${error.message}`);
     process.exitCode = 1;
   });

package/scripts/universal-facade-maintainability.mjs

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function loadUniversalFacadeMigration(root) {
+  const contract = JSON.parse(
+    fs.readFileSync(
+      path.join(root, "architecture/universal-workflow-bootstrap.json"),
+      "utf8",
+    ),
+  );
+  const retired = new Set(contract.retiredWorkflowSurfaces || []);
+  const paths = (contract.bootstrapGovernedWorkflows || []).filter(
+    (entry) =>
+      entry !== contract.bootstrap?.publicWorkflow && !retired.has(entry),
+  );
+  const sourceRevision = contract.migration?.facadeSourceRevision || "";
+  if (!/^[0-9a-f]{40}$/u.test(sourceRevision)) {
+    throw new Error(
+      "universal facade migration requires an exact facadeSourceRevision",
+    );
+  }
+  return {
+    paths: new Set(paths),
+    sourceRevision,
+    postMigration: new Set(contract.migration?.postMigrationWorkflows || []),
+  };
+}
+
+function verifyUniversalFacadeMigration(root) {
+  execFileSync(
+    process.execPath,
+    ["scripts/generate-universal-workflow-facades.mjs", "--check"],
+    { cwd: root, stdio: "pipe" },
+  );
+}
+
+function governUniversalFacadeWorkflowMetrics({
+  root,
+  current,
+  workflowMetricsAtRevision,
+}) {
+  const migration = loadUniversalFacadeMigration(root);
+  verifyUniversalFacadeMigration(root);
+  const frozen = workflowMetricsAtRevision(root, migration.sourceRevision);
+  const governed = { ...current, workflows: { ...current.workflows } };
+  for (const file of migration.postMigration) {
+    if (frozen[file] || !migration.paths.has(file))
+      throw new Error(`invalid post-migration workflow declaration ${file}`);
+    migration.paths.delete(file);
+  }
+  for (const file of migration.paths) {
+    if (!frozen[file])
+      throw new Error(`frozen universal facade source is missing ${file}`);
+    governed.workflows[file] = frozen[file];
+  }
+  return { governed, migration };
+}
+
+function isGeneratedFacadePublicTransition({
+  entry,
+  kind,
+  migration,
+  baseContract,
+  currentContract,
+}) {
+  if (kind !== "workflow" || !migration?.paths.has(entry.path) || !baseContract)
+    return false;
+  const { inputs: currentInputs, ...currentRest } = currentContract;
+  const { inputs: previousInputs, ...previousRest } = baseContract;
+  if (JSON.stringify(currentRest) !== JSON.stringify(previousRest))
+    return false;
+  const added = currentInputs.filter(
+    (input) => !previousInputs.includes(input),
+  );
+  const removed = previousInputs.filter(
+    (input) => !currentInputs.includes(input),
+  );
+  return (
+    removed.length === 0 &&
+    added.length === 1 &&
+    added[0] === "universal-request-json"
+  );
+}
+
+export {
+  governUniversalFacadeWorkflowMetrics,
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+  verifyUniversalFacadeMigration,
+};

package/scripts/universal-workflow-backflow.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  validateUniversalWorkflowRequest,
+  universalWorkflowRequestRoot,
+} from "../packages/core/universal-workflow-bootstrap.js";
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))
+        .map((key) => [key, canonical(value[key])]),
+    );
+  return value;
+}
+
+function contentRoot(domain, value) {
+  const hash = crypto.createHash("sha256");
+  hash.update(domain, "utf8");
+  hash.update(Buffer.from([0]));
+  hash.update(`${JSON.stringify(canonical(value))}\n`, "utf8");
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function validateTerminalReceipt(value, request) {
+  if (
+    value?.schema !==
+      "kungfu-buildchain-v4-universal-workflow-terminal-receipt/v1" ||
+    value.status !== "succeeded" ||
+    value.runtime?.repository !== request.candidate.repository ||
+    value.runtime?.sha !== request.candidate.expectedSha ||
+    value.requestRoot !== universalWorkflowRequestRoot(request) ||
+    !SHA.test(value.runtime?.sha || "") ||
+    !ROOT.test(value.receiptRoot || "")
+  )
+    fail(
+      "successful exact-candidate terminal receipt is required for backflow",
+    );
+  return value;
+}
+
+export function createUniversalBackflowPlan({
+  request: requestValue,
+  receipt,
+}) {
+  const request = validateUniversalWorkflowRequest(requestValue);
+  if (request.mode !== "train") fail("only Train delivery can create backflow");
+  if (request.capability.id !== "release-candidate-promote")
+    fail("only a release-candidate-promote delivery can create backflow");
+  if (request.payload?.inputs?.["dry-run"] !== false)
+    fail("only a non-dry-run release delivery can create backflow");
+  const terminal = validateTerminalReceipt(receipt, request);
+  const marker = `<!-- buildchain-universal-backflow:${request.candidate.expectedSha} -->`;
+  const binding = {
+    schema: "kungfu-buildchain-v4-universal-workflow-backflow/v1",
+    repository: request.candidate.repository,
+    pullRequest: request.candidate.reviewPullRequest,
+    baseRef: "dev/v4/v4.0",
+    trainSha: request.candidate.expectedSha,
+    consumerRepository: request.consumer.repository,
+    consumerSha: request.consumer.sourceSha,
+    requestRoot: terminal.requestRoot,
+    terminalReceiptRoot: terminal.receiptRoot,
+  };
+  const backflowRoot = contentRoot("universal-workflow-backflow", binding);
+  return {
+    ...binding,
+    marker,
+    backflowRoot,
+    body: [
+      marker,
+      "## Universal Train backflow",
+      "",
+      `- Train SHA: \`${binding.trainSha}\``,
+      `- Consumer: \`${binding.consumerRepository}@${binding.consumerSha}\``,
+      `- Request root: \`${binding.requestRoot}\``,
+      `- Terminal receipt root: \`${binding.terminalReceiptRoot}\``,
+      `- Backflow root: \`${backflowRoot}\``,
+      "",
+      "This receipt binds a successful consumer delivery to the protected Train-to-dev backflow PR; it does not designate the Train candidate as a Buildchain release.",
+    ].join("\n"),
+  };
+}
+
+function githubHeaders(token) {
+  return {
+    accept: "application/vnd.github+json",
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    "user-agent": "buildchain-universal-backflow",
+    "x-github-api-version": "2022-11-28",
+  };
+}
+
+async function githubJson({ path, method = "GET", token, body, fetchImpl }) {
+  const api = String(
+    process.env.GITHUB_API_URL || "https://api.github.com",
+  ).replace(/\/+$/u, "");
+  const response = await fetchImpl(`${api}${path}`, {
+    method,
+    headers: githubHeaders(token),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  const value = text ? JSON.parse(text) : {};
+  if (!response.ok)
+    fail(
+      `GitHub API ${method} ${path} failed with ${response.status}: ${value.message || text}`,
+    );
+  return value;
+}
+
+export async function upsertUniversalBackflow({
+  request,
+  receipt,
+  token,
+  fetchImpl = globalThis.fetch,
+}) {
+  const admitted = validateUniversalWorkflowRequest(request);
+  if (
+    admitted.mode !== "train" ||
+    admitted.capability.id !== "release-candidate-promote" ||
+    admitted.payload?.inputs?.["dry-run"] !== false
+  ) {
+    return {
+      schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
+      action: "skipped",
+      reason: "not-a-successful-non-dry-run-release-delivery",
+      backflowRoot: "",
+    };
+  }
+  if (!token) fail("GH_TOKEN is required for protected backflow");
+  if (typeof fetchImpl !== "function") fail("fetch is required for backflow");
+  const plan = createUniversalBackflowPlan({ request: admitted, receipt });
+  const encodedRepository = plan.repository;
+  const pull = await githubJson({
+    path: `/repos/${encodedRepository}/pulls/${plan.pullRequest}`,
+    token,
+    fetchImpl,
+  });
+  if (
+    pull.state !== "open" ||
+    pull.base?.ref !== plan.baseRef ||
+    pull.head?.repo?.full_name !== plan.repository ||
+    pull.head?.sha !== plan.trainSha
+  )
+    fail("backflow PR no longer binds the exact admitted Train candidate");
+  const comments = await githubJson({
+    path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments?per_page=100`,
+    token,
+    fetchImpl,
+  });
+  const existing = comments.find((comment) =>
+    String(comment.body || "").includes(plan.marker),
+  );
+  const comment = existing
+    ? await githubJson({
+        path: `/repos/${encodedRepository}/issues/comments/${existing.id}`,
+        method: "PATCH",
+        token,
+        body: { body: plan.body },
+        fetchImpl,
+      })
+    : await githubJson({
+        path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments`,
+        method: "POST",
+        token,
+        body: { body: plan.body },
+        fetchImpl,
+      });
+  return {
+    schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
+    action: existing ? "updated" : "created",
+    pullRequest: plan.pullRequest,
+    trainSha: plan.trainSha,
+    terminalReceiptRoot: plan.terminalReceiptRoot,
+    backflowRoot: plan.backflowRoot,
+    commentUrl: comment.html_url,
+  };
+}
+
+async function main() {
+  const request = JSON.parse(
+    process.env.BUILDCHAIN_UNIVERSAL_REQUEST_JSON ||
+      fail("request is required"),
+  );
+  const receipt = JSON.parse(
+    process.env.BUILDCHAIN_UNIVERSAL_TERMINAL_RECEIPT_JSON ||
+      fail("terminal receipt is required"),
+  );
+  const result = await upsertUniversalBackflow({
+    request,
+    receipt,
+    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+const isMain =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) await main();