@kungfu-tech/buildchain 3.0.6-alpha.1 → 3.0.6-alpha.3

package/scripts/auditable-demo.mjs

@@ -7,10 +7,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import {
-  validateRenditionSet,
-  validateTerminalCapture,
-} from "./auditable-demo-renditions.mjs";
+import { readRendererManifest, validateRendererCompositionInputs, validateRenditionSet, validateTerminalCapture } from "./auditable-demo-renditions.mjs";
 
 const UTF8 = new TextDecoder("utf-8", { fatal: true });
 const IMAGE_PATTERN = /^[a-z0-9][a-z0-9./_-]*@sha256:[0-9a-f]{64}$/;
@@ -130,7 +127,7 @@ function writeChecksums(root, checksumName = "checksums.sha256") {
   return sha256(Buffer.from(bytes));
 }
 
-function verifyChecksums(root, checksumName = "checksums.sha256") {
+function verifyChecksums(root, checksumName = "checksums.sha256", options = {}) {
   const bytes = readRegular(path.join(root, checksumName), checksumName);
   const text = decodeUtf8(bytes, checksumName);
   invariant(text.endsWith("\n"), `${checksumName} must end with a newline`);
@@ -143,8 +140,11 @@ function verifyChecksums(root, checksumName = "checksums.sha256") {
     const target = resolveInside(root, member, "checksum member");
     invariant(!declared.has(member), `duplicate checksum member: ${member}`);
     declared.add(member);
+    const maximumBytes = options.allowLongFormRendererManifest && member === "manifest.json"
+      ? 32 * 1024 * 1024
+      : MAX_BUNDLE_MEMBER_BYTES;
     invariant(
-      sha256(readRegular(target, member, MAX_BUNDLE_MEMBER_BYTES)).slice(7) === match[1],
+      sha256(readRegular(target, member, maximumBytes)).slice(7) === match[1],
       `checksum mismatch: ${member}`,
     );
   }
@@ -190,7 +190,7 @@ function validateScene(value) {
   exactKeys(
     value,
     ["schema", "id", "width", "height", "fps", "durationMs", "title"],
-    ["durationClass", "commandLabel", "background", "accent"],
+    ["durationClass", "compositionMode", "commandLabel", "background", "accent"],
     "scene",
   );
   invariant(value.schema === "build-images.demo-scene/v1", "unsupported scene schema");
@@ -199,6 +199,11 @@ function validateScene(value) {
   integer(value.height, 360, 1080, "scene.height");
   const durationClass = value.durationClass ?? "standard";
   invariant(durationClass === "standard" || durationClass === "long-form", "scene.durationClass is invalid");
+  const compositionMode = value.compositionMode ?? "presentation-framed";
+  invariant(
+    compositionMode === "presentation-framed" || compositionMode === "terminal-fill",
+    "scene.compositionMode is invalid",
+  );
   const maximumDurationMs = durationClass === "long-form" ? LONG_FORM_MAX_DURATION_MS : STANDARD_MAX_DURATION_MS;
   const maximumFps = durationClass === "long-form" ? LONG_FORM_MAX_FPS : 30;
   integer(value.fps, 1, maximumFps, "scene.fps");
@@ -216,6 +221,7 @@ function validateScene(value) {
     height: value.height,
     fps: value.fps,
     ...(value.durationClass === undefined ? {} : { durationClass }),
+    compositionMode,
     durationMs: value.durationMs,
     title: value.title,
     commandLabel: value.commandLabel ?? "",
@@ -674,8 +680,7 @@ function inspectRendererMedia(values) {
   const rendererImage = required(values, "--renderer-image");
   invariant(IMAGE_PATTERN.test(rendererImage), "renderer image must use an immutable sha256 coordinate");
   invariant(!fs.existsSync(output), "media inspection output must not already exist");
-  const manifest = readJson(path.join(renderOutput, "manifest.json"), "renderer manifest");
-  invariant(manifest.schema === "build-images.auditable-demo-render/v1", "unexpected renderer manifest schema");
+  const { manifest } = readRendererManifest(path.join(renderOutput, "manifest.json"), RENDITION_VALIDATION_HELPERS);
   invariant(manifest.renderer?.image === rendererImage, "renderer manifest image coordinate mismatch");
   const members = Object.keys(manifest.outputs || {})
     .filter((name) => name !== "media-probe.json")
@@ -739,7 +744,7 @@ function qualifyMediaFixture(values) {
         sha256(readRegular(path.join(renderOutput, name), `fixture ${name}`)),
       ]),
     ),
-    rendererManifestRoot: sha256(readRegular(path.join(renderOutput, "manifest.json"), "renderer manifest")),
+    rendererManifestRoot: sha256(readRendererManifest(path.join(renderOutput, "manifest.json"), RENDITION_VALIDATION_HELPERS).bytes),
     qualification: verified.qualification,
   };
   writeJson(output, { ...body, evidenceRoot: semanticRoot(body) });
@@ -979,9 +984,8 @@ function verifyRendererOutput(renderOutput, expectedImage, expectedInputs, optio
     "public-projection.json",
     "scene.json",
   ];
-  verifyChecksums(renderOutput);
-  const manifest = readJson(path.join(renderOutput, "manifest.json"), "renderer manifest");
-  invariant(manifest.schema === "build-images.auditable-demo-render/v1", "unexpected renderer manifest schema");
+  verifyChecksums(renderOutput, "checksums.sha256", { allowLongFormRendererManifest: true });
+  const { manifest } = readRendererManifest(path.join(renderOutput, "manifest.json"), RENDITION_VALIDATION_HELPERS);
   invariant(manifest.renderer?.image === expectedImage, "renderer manifest image coordinate mismatch");
   const outputNames = Object.keys(manifest.outputs || {}).sort();
   invariant(outputNames.includes("media-probe.json"), "renderer manifest must declare media-probe.json");
@@ -999,21 +1003,11 @@ function verifyRendererOutput(renderOutput, expectedImage, expectedInputs, optio
     const observed = manifest.inputs?.[key]?.root;
     invariant(observed === sha256(readRegular(filePath, `${key} input`)), `renderer ${key} input root mismatch`);
   }
-  if (expectedInputs.renditionSet) {
-    invariant(
-      manifest.derivation?.policy === "independent-native-frame-sets/v1",
-      "renderer did not use independent native frame sets",
-    );
-    invariant(
-      Array.isArray(manifest.inputs?.renditions)
-        && manifest.inputs.renditions.length === 2
-        && manifest.inputs.renditions[0]?.role === "primary"
-        && manifest.inputs.renditions[1]?.role === "responsive"
-        && manifest.inputs.renditions[0]?.terminalCapture?.root
-          !== manifest.inputs.renditions[1]?.terminalCapture?.root,
-      "renderer native rendition inputs are not independently bound",
-    );
-  }
+  const composition = validateRendererCompositionInputs(
+    manifest,
+    expectedInputs,
+    RENDITION_VALIDATION_HELPERS,
+  );
   const probe = readJson(path.join(renderOutput, "media-probe.json"), "media probe");
   invariant(probe.schema === "build-images.demo-media-probe/v1" && probe.passed === true, "renderer media probe failed");
   const qualification = qualifyRendererOutput(
@@ -1024,7 +1018,7 @@ function verifyRendererOutput(renderOutput, expectedImage, expectedInputs, optio
     options.inspectMedia || inspectMediaFile,
     options.inspectionRoot || "",
   );
-  return { manifest, probe, qualification };
+  return { manifest, probe, qualification, composition };
 }
 
 function renditionInputRoots(root, renditions) {
@@ -1254,7 +1248,7 @@ function finalizeMedia(values) {
     sourceSha,
     qualifiedGateRoot: gateRoot,
     rendererImage,
-    rendererManifestRoot: sha256(readRegular(path.join(renderOutput, "manifest.json"), "renderer manifest")),
+    rendererManifestRoot: sha256(readRendererManifest(path.join(renderOutput, "manifest.json"), RENDITION_VALIDATION_HELPERS).bytes),
   };
   const mediaReceipt = selectedProfile.mode === "archive"
     ? { schema: "buildchain.auditable-demo-media/v1", ...commonReceipt }

package/scripts/build-contract-core.mjs

@@ -3,7 +3,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { macosJitRunnerLabel } from "./aws-macos-jit-core.mjs";
 import { windowsJitRunnerLabel } from "./aws-windows-jit-core.mjs";
-
 export const RUNNER_PRESETS = Object.freeze({
   "github-hosted": [
     { id: "linux-x64", name: "Linux x64", platform: "linux", runner: '["ubuntu-24.04"]', capabilities: ["node"] },
@@ -768,6 +767,55 @@ function platformIsLinux(platform) {
   );
 }
 
+function platformUsesGitHubHostedRunner(platform, index) {
+  if (platform?.githubHosted !== undefined) {
+    if (typeof platform.githubHosted !== "boolean") {
+      throw new Error(
+        `platforms-json[${index}].githubHosted must be a boolean`,
+      );
+    }
+    return platform.githubHosted;
+  }
+  if (String(platform?.provider || "").trim()) {
+    return false;
+  }
+  const runnerLabels = parseJsonArray(
+    String(platform?.runner || "[]"),
+    `platforms-json[${index}].runner`,
+  ).map((label) => String(label || "").toLowerCase());
+  if (runnerLabels.includes("self-hosted") || runnerLabels.length !== 1) {
+    return false;
+  }
+  return /^(ubuntu-(latest|20\.04|22\.04|24\.04|24\.04-arm)|windows-(latest|2019|2022|2025|11-arm)|macos-(latest|13|14|15|26)(-intel)?)$/.test(
+    runnerLabels[0],
+  );
+}
+
+function bindRunnerHosting(platforms) {
+  return platforms.map((platform, index) => ({
+    ...platform,
+    githubHosted: platformUsesGitHubHostedRunner(platform, index),
+  }));
+}
+
+function runnerHostingSummary(platforms) {
+  const githubHostedPlatforms = platforms.filter(
+    (platform) => platform.githubHosted,
+  );
+  const relayPlatforms = platforms.filter((platform) => !platform.githubHosted);
+  return {
+    githubHostedPlatforms,
+    githubHostedPlatformsJson: JSON.stringify(githubHostedPlatforms),
+    githubHostedPlatformIdsJson: JSON.stringify(
+      githubHostedPlatforms.map((platform) => platform.id),
+    ),
+    githubHostedPlatformCount: githubHostedPlatforms.length,
+    relayPlatforms,
+    relayPlatformsJson: JSON.stringify(relayPlatforms),
+    relayPlatformCount: relayPlatforms.length,
+  };
+}
+
 function normalizePlatform(platform, index) {
   const id = String(platform?.id || "").trim();
   const name = String(platform?.name || id).trim();
@@ -793,7 +841,9 @@ function normalizePlatform(platform, index) {
   if (platform?.platform !== undefined) normalized.platform = String(platform.platform || "").trim();
   if (platform?.provider !== undefined) normalized.provider = String(platform.provider || "").trim();
   if (platform?.project !== undefined) normalized.project = String(platform.project || "").trim();
+  if (platform?.githubHosted !== undefined) normalized.githubHosted = platform.githubHosted;
   normalized.capabilities = capabilities.sort();
+  if (platform?.environment !== undefined) normalized.environment = platform.environment;
   if (platform?.required === false) normalized.required = false;
   return normalized;
 }
@@ -813,8 +863,10 @@ export function resolveRunnerMatrix({
     linuxContainerImage,
   });
   if (customPlatformsJson) {
-    const platforms = parseJsonArray(customPlatformsJson, "platforms-json").map(
-      normalizePlatform,
+    const platforms = bindRunnerHosting(
+      parseJsonArray(customPlatformsJson, "platforms-json").map(
+        normalizePlatform,
+      ),
     );
     if (platforms.length === 0) {
       throw new Error("platforms-json must include at least one platform");
@@ -838,6 +890,7 @@ export function resolveRunnerMatrix({
       containerPlatformsJson: JSON.stringify(containerPlatforms),
       containerPlatformCount: containerPlatforms.length,
       linuxContainer,
+      ...runnerHostingSummary(platforms),
     };
   }
 
@@ -875,6 +928,7 @@ export function resolveRunnerMatrix({
       runner: JSON.stringify(["self-hosted", "macOS", "ARM64", runnerLabel]),
     }));
   }
+  resolvedPlatforms = bindRunnerHosting(resolvedPlatforms);
   const containerPlatforms = linuxContainer.enabled
     ? resolvedPlatforms.filter(platformIsLinux)
     : [];
@@ -894,6 +948,7 @@ export function resolveRunnerMatrix({
     containerPlatformsJson: JSON.stringify(containerPlatforms),
     containerPlatformCount: containerPlatforms.length,
     linuxContainer,
+    ...runnerHostingSummary(resolvedPlatforms),
   };
 }
 

package/scripts/buildchain-cli-help.mjs

@@ -108,10 +108,18 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain inspect release --passport <file-or-url> [--json]
   buildchain inspect artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--json]
   buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
+  buildchain dev pr-admit --repository <owner/repo> --branch <dev/vN/vN.M>
+                             --pull-request <n> --expected-head <sha>
+                             [--execute] [--output <file>] [--json]
   buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M>
                              [--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>
+                             --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--execute] [--output <file>] [--json]
+  buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration>
+                             [--output <file>] [--json]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
                  [--path <jsonl>] [--json]

package/scripts/buildchain-patrol.mjs

@@ -194,6 +194,15 @@ export async function runBuildchainPatrol(optionsInput = {}, clientInput) {
   }
 
   result.summary.plannedCount = result.planned.length;
+  const admissionActions = result.actions.flatMap((action) => action.result?.actions || []);
+  result.runKind = "cadence-patrol";
+  result.outcome = result.summary.evaluatedCount === 0
+    ? "no-op-no-candidates"
+    : admissionActions.length === 0
+      ? "no-op-all-skipped"
+      : "actions-present";
+  result.noOp = admissionActions.length === 0;
+  result.qualification = false;
   result.ok = result.inspections.every((inspection) => inspection.ok !== false);
   return result;
 }

package/scripts/check-inventory.mjs

@@ -74,6 +74,7 @@ const requiredPaths = [
   "docs/shifu-gate-profiles.md",
   "docs/auditable-demo.md",
   "contracts/auditable-demo-scenario-v1.schema.json",
+  "contracts/release-candidate-recovery-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",
@@ -117,6 +118,7 @@ const requiredPaths = [
   "scripts/publication-commit-evidence.mjs",
   "scripts/publication-reproducibility.mjs",
   "scripts/release-candidate-resolver.mjs",
+  "scripts/resume-from-candidate-run.mjs",
   "scripts/buildchain-patrol.mjs",
   "scripts/observed-evidence.mjs",
   "scripts/workflow-friction-report.mjs",
@@ -134,9 +136,11 @@ const requiredPaths = [
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/buildchain-candidate-recovery-dogfood-failure.yml",
   ".github/workflows/release-line-bootstrap.yml",
   ".github/workflows/release-governance-reconcile.yml",
   ".github/workflows/dev-pr-auto-merge.yml",
+  ".github/workflows/buildchain-dev-delivery.yml",
   ".github/workflows/buildchain-patrol.yml",
   ".github/workflows/patrol-daily.yml",
   ".github/workflows/patrol-weekly.yml",
@@ -983,10 +987,12 @@ for (const requiredSnippet of [
   "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')",
-  "target-sha: ${{ github.event.workflow_run.head_sha || inputs.sha || github.sha }}",
+  "resume-candidate-run-id:",
+  "resume-expected-source-tree:",
+  "resume-buildchain-runtime-sha:",
   "github-release: true",
   "release-passport-buildchain-self-kfd: true",
-  "publish-required-artifacts-json: \"[]\"",
+  "artifact-patterns: ${{ inputs['resume-candidate-run-id'] != '' && 'buildchain-package-*' || '' }}",
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {
@@ -1040,6 +1046,11 @@ for (const requiredSnippet of [
   "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
   "Consumer has no binary-distribution.yml; standalone binary dispatch is not applicable.",
   "gh workflow view binary-distribution.yml",
+  "resume-candidate-run-id:",
+  "node .buildchain/runtime/scripts/resume-from-candidate-run.mjs",
+  "publish-sealed-bundle-root: ${{ steps.rc.outputs.publish-sealed-bundle-root }}",
+  "BUILDCHAIN_EXPECTED_TRANSACTION_ID: ${{ inputs.resume-transaction-id }}",
+  "if: ${{ inputs.resume-candidate-run-id == '' }}",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
     throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);

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

@@ -5,6 +5,10 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { decideChannelCandidate } from "../packages/core/channel-candidate.js";
+import {
+  resolveManagedPromotionBaseline,
+  resolvePatrolSourceInputs,
+} from "../packages/core/channel-promotion-baseline.js";
 
 export const DEV_ALPHA_CANDIDATE_STATE_SCHEMA =
   "kungfu-buildchain-dev-alpha-candidate-state/v1";
@@ -301,8 +305,7 @@ export function normalizeDevAlphaPatrolOptions(options = {}) {
       false,
     ),
     mergeMethod: autoMergeMethod(
-      options.mergeMethod ??
-        process.env.BUILDCHAIN_CHANNEL_PATROL_MERGE_METHOD,
+      options.mergeMethod ?? process.env.BUILDCHAIN_CHANNEL_PATROL_MERGE_METHOD,
     ),
     dryRun: bool(
       options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN,
@@ -321,7 +324,10 @@ export function normalizeDevAlphaPatrolOptions(options = {}) {
 function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
   const matching = runs
     .filter(
-      (run) => run.path === workflowPathValue && run.head_sha === sourceSha,
+      (run) =>
+        run.conclusion !== "cancelled" &&
+        run.path === workflowPathValue &&
+        run.head_sha === sourceSha,
     )
     .sort((left, right) => Number(right.id) - Number(left.id));
   if (matching.length === 0)
@@ -356,7 +362,9 @@ function workflowEvidenceIsFreshAndSuccessful(run, { now, maxAgeSeconds }) {
 
 function latestRunsBySha(runs, workflowPathValue) {
   const latest = new Map();
-  for (const run of runs.filter((row) => row.path === workflowPathValue)) {
+  for (const run of runs.filter(
+    (row) => row.path === workflowPathValue && row.conclusion !== "cancelled",
+  )) {
     const current = latest.get(run.head_sha);
     if (!current || Number(run.id) > Number(current.id))
       latest.set(run.head_sha, run);
@@ -620,52 +628,26 @@ export async function runDevAlphaCandidatePatrol(
       repository: options.repository,
       token: process.env.GITHUB_TOKEN,
     });
-  const [observedSourceHeadSha, targetSha] = await Promise.all([
-    client.resolveBranch(options.sourceBranch),
-    client.resolveBranch(options.targetBranch),
-  ]);
-  const headComparison = await client.compare(targetSha, observedSourceHeadSha);
   const requiredWorkflowPaths = [
     options.devWorkflowPath,
     options.alphaWorkflowPath,
   ];
-  let sourceSha = observedSourceHeadSha;
-  let comparison = headComparison;
-  let workflowEvidence = [];
-  let skippedNewerCommitCount = 0;
-  let qualificationError;
-  if (
-    headComparison.status === "ahead" &&
-    Number(headComparison.ahead_by) > 0
-  ) {
-    const [sourceHistory, ...workflowRunSets] = await Promise.all([
-      client.listBranchHistory(options.sourceBranch, targetSha),
-      ...requiredWorkflowPaths.map((workflow) =>
-        client.listCompletedWorkflowRuns(workflow, options.sourceBranch),
-      ),
-    ]);
-    try {
-      const selected = selectLatestQualifiedSource({
-        sourceHistory,
-        workflowRunsByPath: new Map(
-          requiredWorkflowPaths.map((workflow, index) => [
-            workflow,
-            workflowRunSets[index],
-          ]),
-        ),
-        requiredWorkflowPaths,
-        now: options.now,
-        maxAgeSeconds: options.maxAgeSeconds,
-      });
-      sourceSha = selected.sourceSha;
-      skippedNewerCommitCount = selected.skippedNewerCommitCount;
-      workflowEvidence = selected.workflowEvidence;
-      if (sourceSha !== observedSourceHeadSha)
-        comparison = await client.compare(targetSha, sourceSha);
-    } catch (error) {
-      qualificationError = error;
-    }
-  }
+  const {
+    observedSourceHeadSha,
+    targetSha,
+    headComparison,
+    targetBaseline,
+    sourceSha,
+    comparison,
+    workflowEvidence,
+    skippedNewerCommitCount,
+    qualificationError,
+  } = await resolvePatrolSourceInputs({
+    client,
+    options,
+    requiredWorkflowPaths,
+    selectQualifiedSource: selectLatestQualifiedSource,
+  });
   const decision = qualificationError
     ? blockedCandidateDecision({
         options,
@@ -682,9 +664,12 @@ export async function runDevAlphaCandidatePatrol(
         targetSha,
         comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
         selection: {
-          mode: "latest-qualified-source-ancestor",
+          mode: targetBaseline
+            ? "latest-qualified-source-after-managed-promotion"
+            : "latest-qualified-source-ancestor",
           observedSourceHeadSha,
           skippedNewerCommitCount,
+          ...(targetBaseline ? { targetBaseline } : {}),
         },
         workflowEvidence,
         requiredWorkflowPaths,
@@ -927,7 +912,12 @@ export async function runDevAlphaCandidatePatrol(
       }
     }
   }
-  const autoMerge = await armCandidateAutoMerge(options, controllerState, pullRequest, client);
+  const autoMerge = await armCandidateAutoMerge(
+    options,
+    controllerState,
+    pullRequest,
+    client,
+  );
   return {
     schema: "kungfu-buildchain-dev-alpha-candidate-patrol/v1",
     dryRun: options.dryRun,
@@ -1015,6 +1005,13 @@ export function createGitHubChannelCandidateClient({
     async compare(baseSha, headSha) {
       return api(`/repos/${owner}/${repo}/compare/${baseSha}...${headSha}`);
     },
+    resolveManagedPromotionBaseline: (targetSha, targetBranch) =>
+      resolveManagedPromotionBaseline({
+        api: (requestPath) => api(`/repos/${owner}/${repo}${requestPath}`),
+        targetSha,
+        targetBranch,
+        parseCandidate: managedCandidateFromPullRequest,
+      }),
     async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
       const runs = [];
       for (let page = 1; page <= 10; page += 1) {