@kungfu-tech/buildchain 3.0.2-alpha.3 → 3.0.2-alpha.5

package/packages/core/release-passport.js

@@ -21,6 +21,9 @@ import {
 import { createSurfaceTimestampPolicy } from "./surface-manifest.js";
 import { validatePublishEvidence as validateTransactionPublishEvidence } from "./publish-transaction.js";
 import { normalizeControllerReceiptReferences } from "./controller-evidence.js";
+import {
+  normalizeGitHubArtifactAttestationPolicy,
+} from "./github-artifact-attestation.js";
 
 export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
 export const ARTIFACT_EVIDENCE_CONTRACT = "kungfu-buildchain-artifact-evidence";
@@ -1166,6 +1169,7 @@ export function createReleasePassport({
   kfdAgentHubEvidencePath = "",
   controllerReceipts = [],
   controllerReceiptReferences = [],
+  githubArtifactAttestations = [],
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: normalizedTag, sourceSha, workflow });
@@ -1231,6 +1235,8 @@ export function createReleasePassport({
       : [],
     requirePassed: true,
   });
+  const normalizedGitHubArtifactAttestations = (githubArtifactAttestations || [])
+    .map(normalizeGitHubArtifactAttestationPolicy);
   const publishArtifacts = normalizedPublishEvidence?.artifacts || [];
   const normalizedPublishSummary = normalizePublishSummary({
     packageSet: normalizedPackageSet,
@@ -1360,6 +1366,9 @@ export function createReleasePassport({
     ...(normalizedKfdAgentHub ? { kfdAgentHub: normalizedKfdAgentHub } : {}),
     ...(invariantPassports ? { invariantPassports } : {}),
     ...(normalizedControllerReceipts.length > 0 ? { controllerReceipts: normalizedControllerReceipts } : {}),
+    ...(normalizedGitHubArtifactAttestations.length > 0
+      ? { githubArtifactAttestations: normalizedGitHubArtifactAttestations }
+      : {}),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [
@@ -1450,6 +1459,7 @@ export function collectGitHubReleasePassport({
   invariantPassportCommand = "",
   kfdAgentHubEvidenceJson = "",
   controllerReceiptReferences = [],
+  githubArtifactAttestationPolicyJsons = [],
   basePassportJson = "",
   requireBaseKfd = false,
   releaseJsonExtra = "",
@@ -1526,6 +1536,13 @@ export function collectGitHubReleasePassport({
     undefined,
     { cwd, label: "kfdAgentHubEvidenceJson" },
   );
+  const githubArtifactAttestationPolicies = (githubArtifactAttestationPolicyJsons || [])
+    .filter(Boolean)
+    .map((policyJson) => parseJsonInput(policyJson, undefined, {
+      cwd,
+      label: "githubArtifactAttestationPolicyJsons entry",
+    }))
+    .map(normalizeGitHubArtifactAttestationPolicy);
   const kfd3ArtifactWitnesses = [
     ...kfd3ArtifactWitnessMetas.map((meta) => meta.value),
     ...(kfd3ArtifactCommandMeta.value ? [kfd3ArtifactCommandMeta.value] : []),
@@ -1623,6 +1640,7 @@ export function collectGitHubReleasePassport({
       : undefined,
     kfdAgentHubEvidencePath: kfdAgentHubEvidenceMeta.value ? "kfd-agent-hub-evidence.json" : "",
     controllerReceiptReferences,
+    githubArtifactAttestations: githubArtifactAttestationPolicies,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
@@ -1972,6 +1990,39 @@ export function createReleaseCheckReport({
     issues.push(issue("error", "kfdSupport.section", "KFD support evidence is present without a release-passport projection"));
   }
 
+  for (const [index, value] of (passport?.githubArtifactAttestations || []).entries()) {
+    try {
+      const policy = normalizeGitHubArtifactAttestationPolicy(value);
+      if (policy.caller.sourceSha !== String(passport?.release?.sourceSha || "").toLowerCase()) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].caller.sourceSha`,
+          "attestation policy source SHA must match passport.release.sourceSha",
+        ));
+      }
+      const artifact = (passport?.artifacts || []).find((entry) => entry.name === policy.subject.name);
+      if (!artifact) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].subject.name`,
+          `attestation subject ${policy.subject.name} is absent from the Release Passport artifacts`,
+        ));
+      } else if (artifact.sha256 !== policy.subject.digest.sha256) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].subject.digest`,
+          `attestation subject ${policy.subject.name} digest differs from the Release Passport artifact`,
+        ));
+      }
+    } catch (error) {
+      issues.push(issue(
+        "error",
+        `githubArtifactAttestations[${index}]`,
+        error.message,
+      ));
+    }
+  }
+
   const tag = passport?.release?.tag || "";
   if (!tag) {
     issues.push(issue("error", "release.tag", "release.tag is required"));

package/scripts/check-inventory.mjs

@@ -68,6 +68,7 @@ const requiredPaths = [
   "docs/product-mechanism.md",
   "docs/readme-badges.md",
   "docs/release-passport.md",
+  "docs/github-artifact-attestation.md",
   "docs/shifu-gate-profiles.md",
   "docs/auditable-demo.md",
   "docs/release-propagation.md",
@@ -358,6 +359,9 @@ if (rootPackage.exports?.["./kfd-gate"] !== "./packages/core/kfd-gate.js") {
 if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-passport.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-passport");
 }
+if (rootPackage.exports?.["./github-artifact-attestation"] !== "./packages/core/github-artifact-attestation.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/github-artifact-attestation");
+}
 if (rootPackage.exports?.["./release-passport-contract"] !== "./packages/core/release-passport-contract.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-passport-contract");
 }

package/scripts/create-github-artifact-attestation-policy.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import {
+  GITHUB_ARTIFACT_ATTESTATION_WORKFLOW,
+  createGitHubArtifactAttestationPolicy,
+  githubArtifactAttestationSha256File,
+} from "../packages/core/github-artifact-attestation.js";
+
+function env(name, fallback = "") {
+  return String(process.env[name] || fallback).trim();
+}
+
+function required(name) {
+  const value = env(name);
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+const cwd = path.resolve(env("BUILDCHAIN_SOURCE_CWD", "."));
+const subjectRelativePath = required("BUILDCHAIN_GITHUB_ATTESTATION_SUBJECT_PATH").replace(/\\/g, "/");
+const subjectPath = path.resolve(cwd, subjectRelativePath);
+const manifestPath = path.resolve(required("BUILDCHAIN_GITHUB_ATTESTATION_PLATFORM_MANIFEST"));
+const outputPath = path.resolve(required("BUILDCHAIN_GITHUB_ATTESTATION_POLICY_OUTPUT"));
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+const manifestEntry = (manifest.files || []).find((entry) => (
+  String(entry.path || "").replace(/\\/g, "/") === subjectRelativePath
+));
+if (!manifestEntry) throw new Error(`platform manifest does not contain ${subjectRelativePath}`);
+const digest = githubArtifactAttestationSha256File(subjectPath);
+const size = fs.statSync(subjectPath).size;
+if (`sha256:${String(manifestEntry.sha256 || "").toLowerCase()}` !== digest || Number(manifestEntry.size) !== size) {
+  throw new Error("subject bytes do not match the final platform manifest");
+}
+const manifestDigest = githubArtifactAttestationSha256File(manifestPath);
+const runtimeSha = required("BUILDCHAIN_RUNTIME_SHA").toLowerCase();
+const signerSha = required("BUILDCHAIN_GITHUB_ATTESTATION_SIGNER_SHA").toLowerCase();
+const policy = createGitHubArtifactAttestationPolicy({
+  subject: { name: path.basename(subjectPath), path: subjectRelativePath, size, digest },
+  caller: {
+    repository: required("BUILDCHAIN_SOURCE_REPOSITORY"),
+    sourceSha: required("BUILDCHAIN_SOURCE_SHA").toLowerCase(),
+    sourceTreeSha: required("BUILDCHAIN_SOURCE_TREE_SHA").toLowerCase(),
+  },
+  signer: {
+    repository: "kungfu-systems/buildchain",
+    workflowPath: GITHUB_ARTIFACT_ATTESTATION_WORKFLOW,
+    workflowDigest: signerSha,
+  },
+  build: {
+    platform: required("BUILDCHAIN_PLATFORM_ID"),
+    platformManifestDigest: manifestDigest,
+    runnerReceiptRoot: manifestDigest,
+    buildchainRuntimeSha: runtimeSha,
+  },
+});
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, `${JSON.stringify(policy, null, 2)}\n`);
+process.stdout.write(`github-artifact-attestation-policy=${outputPath}\n`);

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

@@ -16,13 +16,18 @@ function bool(value, fallback = false) {
 
 function repository(value) {
   const normalized = text(value);
-  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) throw new Error(`repository must be owner/repo, got ${value || "<empty>"}`);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized))
+    throw new Error(`repository must be owner/repo, got ${value || "<empty>"}`);
   return normalized;
 }
 
 function branch(value, name) {
   const normalized = text(value).replace(/^refs\/heads\//, "");
-  if (!normalized || normalized.startsWith("-") || /[\s~^:?*[\\]/.test(normalized)) {
+  if (
+    !normalized ||
+    normalized.startsWith("-") ||
+    /[\s~^:?*[\\]/.test(normalized)
+  ) {
     throw new Error(`${name} is not a valid branch name`);
   }
   return normalized;
@@ -43,24 +48,69 @@ function integer(value, fallback) {
 
 export function normalizeDevAlphaPatrolOptions(options = {}) {
   return {
-    repository: repository(options.repository ?? process.env.BUILDCHAIN_CHANNEL_PATROL_REPOSITORY ?? process.env.GITHUB_REPOSITORY),
-    sourceBranch: branch(options.sourceBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH ?? "dev/v4/v4.0", "sourceBranch"),
-    targetBranch: branch(options.targetBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH ?? "alpha/v4/v4.0", "targetBranch"),
-    devWorkflowPath: workflowPath(options.devWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DEV_WORKFLOW ?? ".github/workflows/dev-verify-patrol.yml", "devWorkflowPath"),
-    alphaWorkflowPath: workflowPath(options.alphaWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_ALPHA_WORKFLOW ?? ".github/workflows/alpha-promotion-preflight.yml", "alphaWorkflowPath"),
-    maxAgeSeconds: integer(options.maxAgeSeconds ?? process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS, 7 * 24 * 60 * 60),
-    createPullRequest: bool(options.createPullRequest ?? process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR, false),
-    dryRun: bool(options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN, true),
-    now: text(options.now ?? process.env.BUILDCHAIN_CHANNEL_PATROL_NOW) || new Date().toISOString(),
-    outputPath: text(options.outputPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_OUTPUT_PATH) || ".buildchain/patrol/dev-alpha-candidate.json",
+    repository: repository(
+      options.repository ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_REPOSITORY ??
+        process.env.GITHUB_REPOSITORY,
+    ),
+    sourceBranch: branch(
+      options.sourceBranch ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH ??
+        "dev/v4/v4.0",
+      "sourceBranch",
+    ),
+    targetBranch: branch(
+      options.targetBranch ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH ??
+        "alpha/v4/v4.0",
+      "targetBranch",
+    ),
+    devWorkflowPath: workflowPath(
+      options.devWorkflowPath ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_DEV_WORKFLOW ??
+        ".github/workflows/dev-verify-patrol.yml",
+      "devWorkflowPath",
+    ),
+    alphaWorkflowPath: workflowPath(
+      options.alphaWorkflowPath ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_ALPHA_WORKFLOW ??
+        ".github/workflows/alpha-promotion-preflight.yml",
+      "alphaWorkflowPath",
+    ),
+    maxAgeSeconds: integer(
+      options.maxAgeSeconds ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS,
+      7 * 24 * 60 * 60,
+    ),
+    createPullRequest: bool(
+      options.createPullRequest ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR,
+      false,
+    ),
+    dryRun: bool(
+      options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN,
+      true,
+    ),
+    now:
+      text(options.now ?? process.env.BUILDCHAIN_CHANNEL_PATROL_NOW) ||
+      new Date().toISOString(),
+    outputPath:
+      text(
+        options.outputPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_OUTPUT_PATH,
+      ) || ".buildchain/patrol/dev-alpha-candidate.json",
   };
 }
 
 function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
   const matching = runs
-    .filter((run) => run.path === workflowPathValue && run.head_sha === sourceSha)
+    .filter(
+      (run) => run.path === workflowPathValue && run.head_sha === sourceSha,
+    )
     .sort((left, right) => Number(right.id) - Number(left.id));
-  if (matching.length === 0) throw new Error(`missing completed same-SHA workflow run: ${workflowPathValue}`);
+  if (matching.length === 0)
+    throw new Error(
+      `missing completed same-SHA workflow run: ${workflowPathValue}`,
+    );
   const run = matching[0];
   return {
     workflowPath: workflowPathValue,
@@ -75,25 +125,122 @@ function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
   };
 }
 
-export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput) {
+function workflowEvidenceIsFreshAndSuccessful(run, { now, maxAgeSeconds }) {
+  const completedAt = Date.parse(run.updated_at);
+  const ageSeconds = (Date.parse(now) - completedAt) / 1000;
+  return (
+    run.status === "completed" &&
+    run.conclusion === "success" &&
+    Number.isFinite(ageSeconds) &&
+    ageSeconds >= 0 &&
+    ageSeconds <= maxAgeSeconds
+  );
+}
+
+function latestRunsBySha(runs, workflowPathValue) {
+  const latest = new Map();
+  for (const run of runs.filter((row) => row.path === workflowPathValue)) {
+    const current = latest.get(run.head_sha);
+    if (!current || Number(run.id) > Number(current.id))
+      latest.set(run.head_sha, run);
+  }
+  return latest;
+}
+
+export function selectLatestQualifiedSource({
+  sourceHistory,
+  workflowRunsByPath,
+  requiredWorkflowPaths,
+  now,
+  maxAgeSeconds,
+}) {
+  const latestByPath = new Map(
+    requiredWorkflowPaths.map((workflow) => [
+      workflow,
+      latestRunsBySha(workflowRunsByPath.get(workflow) || [], workflow),
+    ]),
+  );
+  for (let index = 0; index < sourceHistory.length; index += 1) {
+    const sourceSha = sourceHistory[index];
+    const rows = requiredWorkflowPaths.map((workflow) =>
+      latestByPath.get(workflow).get(sourceSha),
+    );
+    if (
+      rows.every((run) =>
+        workflowEvidenceIsFreshAndSuccessful(run || {}, { now, maxAgeSeconds }),
+      )
+    ) {
+      return {
+        sourceSha,
+        skippedNewerCommitCount: index,
+        workflowEvidence: requiredWorkflowPaths.map((workflow) =>
+          latestWorkflowEvidence(
+            workflowRunsByPath.get(workflow) || [],
+            workflow,
+            sourceSha,
+          ),
+        ),
+      };
+    }
+  }
+  throw new Error(
+    "no source commit ahead of target has fresh completed successful same-SHA workflow evidence",
+  );
+}
+
+export async function runDevAlphaCandidatePatrol(
+  optionsInput = {},
+  clientInput,
+) {
   const options = normalizeDevAlphaPatrolOptions(optionsInput);
-  if (options.sourceBranch === options.targetBranch) throw new Error("source and target branches must differ");
-  const client = clientInput || createGitHubChannelCandidateClient({
-    repository: options.repository,
-    token: process.env.GITHUB_TOKEN,
-  });
-  const [sourceSha, targetSha] = await Promise.all([
+  if (options.sourceBranch === options.targetBranch)
+    throw new Error("source and target branches must differ");
+  const client =
+    clientInput ||
+    createGitHubChannelCandidateClient({
+      repository: options.repository,
+      token: process.env.GITHUB_TOKEN,
+    });
+  const [observedSourceHeadSha, targetSha] = await Promise.all([
     client.resolveBranch(options.sourceBranch),
     client.resolveBranch(options.targetBranch),
   ]);
-  const comparison = await client.compare(targetSha, sourceSha);
-  const requiredWorkflowPaths = [options.devWorkflowPath, options.alphaWorkflowPath];
+  const headComparison = await client.compare(targetSha, observedSourceHeadSha);
+  const requiredWorkflowPaths = [
+    options.devWorkflowPath,
+    options.alphaWorkflowPath,
+  ];
+  let sourceSha = observedSourceHeadSha;
+  let comparison = headComparison;
   let workflowEvidence = [];
-  if (comparison.status === "ahead" && Number(comparison.ahead_by) > 0) {
-    const runs = await client.listCompletedRuns(sourceSha);
-    workflowEvidence = requiredWorkflowPaths.map((workflow) =>
-      latestWorkflowEvidence(runs, workflow, sourceSha),
-    );
+  let skippedNewerCommitCount = 0;
+  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),
+      ),
+    ]);
+    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);
   }
   const decision = decideChannelCandidate({
     repository: options.repository,
@@ -102,6 +249,11 @@ export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput)
     sourceSha,
     targetSha,
     comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
+    selection: {
+      mode: "latest-qualified-source-ancestor",
+      observedSourceHeadSha,
+      skippedNewerCommitCount,
+    },
     workflowEvidence,
     requiredWorkflowPaths,
     maxAgeSeconds: options.maxAgeSeconds,
@@ -118,11 +270,14 @@ export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput)
         "Buildchain exact-source channel candidate.",
         "",
         `- Source branch: \`${options.sourceBranch}\``,
+        `- Observed source HEAD: \`${observedSourceHeadSha}\``,
         `- Source SHA: \`${sourceSha}\``,
+        `- Skipped newer unqualified commits: \`${skippedNewerCommitCount}\``,
         `- Target branch/head: \`${options.targetBranch}\` / \`${targetSha}\``,
         `- Decision root: \`${decision.decisionRoot}\``,
         ...decision.workflowEvidence.map(
-          (row) => `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
+          (row) =>
+            `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
         ),
         "",
         "The source-lock branch must continue to point at the exact source SHA. This patrol never merges the PR, publishes a package, creates a tag, or creates a release.",
@@ -142,7 +297,11 @@ function encodeRef(value) {
   return value.split("/").map(encodeURIComponent).join("/");
 }
 
-export function createGitHubChannelCandidateClient({ repository: repositoryInput, token, fetchImpl = globalThis.fetch }) {
+export function createGitHubChannelCandidateClient({
+  repository: repositoryInput,
+  token,
+  fetchImpl = globalThis.fetch,
+}) {
   const [owner, repo] = repository(repositoryInput).split("/");
   const headers = {
     accept: "application/vnd.github+json",
@@ -150,34 +309,74 @@ export function createGitHubChannelCandidateClient({ repository: repositoryInput
     "user-agent": "buildchain-dev-alpha-candidate-patrol",
     "x-github-api-version": "2022-11-28",
   };
-  async function api(requestPath, { method = "GET", body, allow404 = false } = {}) {
+  async function api(
+    requestPath,
+    { method = "GET", body, allow404 = false } = {},
+  ) {
     const response = await fetchImpl(`https://api.github.com${requestPath}`, {
       method,
-      headers: Object.fromEntries(Object.entries(headers).filter(([, value]) => value)),
+      headers: Object.fromEntries(
+        Object.entries(headers).filter(([, value]) => value),
+      ),
       body: body === undefined ? undefined : JSON.stringify(body),
     });
     const raw = await response.text();
     const payload = raw ? JSON.parse(raw) : undefined;
     if (allow404 && response.status === 404) return undefined;
-    if (!response.ok) throw new Error(`GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`);
+    if (!response.ok)
+      throw new Error(
+        `GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`,
+      );
     return payload;
   }
   return {
     async resolveBranch(ref) {
-      const payload = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`);
+      const payload = await api(
+        `/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`,
+      );
       return text(payload.object?.sha);
     },
     async compare(baseSha, headSha) {
       return api(`/repos/${owner}/${repo}/compare/${baseSha}...${headSha}`);
     },
-    async listCompletedRuns(headSha) {
-      const payload = await api(`/repos/${owner}/${repo}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=completed&per_page=100`);
-      return payload.workflow_runs || [];
+    async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
+      const runs = [];
+      for (let page = 1; page <= 10; page += 1) {
+        const payload = await api(
+          `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflowPathValue)}/runs?branch=${encodeURIComponent(sourceBranch)}&status=completed&per_page=100&page=${page}`,
+        );
+        const rows = payload.workflow_runs || [];
+        runs.push(...rows);
+        if (rows.length < 100) return runs;
+      }
+      throw new Error(
+        `${workflowPathValue} completed workflow history exceeds 1000 runs`,
+      );
+    },
+    async listBranchHistory(sourceBranch, targetSha) {
+      const commits = [];
+      for (let page = 1; page <= 10; page += 1) {
+        const rows = await api(
+          `/repos/${owner}/${repo}/commits?sha=${encodeURIComponent(sourceBranch)}&per_page=100&page=${page}`,
+        );
+        for (const commit of rows) {
+          const commitSha = text(commit.sha);
+          if (commitSha === targetSha) return commits;
+          commits.push(commitSha);
+        }
+        if (rows.length < 100) return commits;
+      }
+      return commits;
     },
     async ensureImmutableBranch(ref, sourceSha) {
-      const current = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`, { allow404: true });
+      const current = await api(
+        `/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`,
+        { allow404: true },
+      );
       if (current && current.object?.sha !== sourceSha) {
-        throw new Error(`source-lock branch ${ref} points to ${current.object?.sha}, not ${sourceSha}`);
+        throw new Error(
+          `source-lock branch ${ref} points to ${current.object?.sha}, not ${sourceSha}`,
+        );
       }
       if (current) return current;
       return api(`/repos/${owner}/${repo}/git/refs`, {
@@ -186,11 +385,16 @@ export function createGitHubChannelCandidateClient({ repository: repositoryInput
       });
     },
     async ensurePullRequest({ head, base, title, body }) {
-      const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);
-      return open[0] || api(`/repos/${owner}/${repo}/pulls`, {
-        method: "POST",
-        body: { head, base, title, body },
-      });
+      const open = await api(
+        `/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`,
+      );
+      return (
+        open[0] ||
+        api(`/repos/${owner}/${repo}/pulls`, {
+          method: "POST",
+          body: { head, base, title, body },
+        })
+      );
     },
   };
 }
@@ -214,7 +418,8 @@ async function main() {
   fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
   fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
   const summary = markdown(result);
-  if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+  if (process.env.GITHUB_STEP_SUMMARY)
+    fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
   else process.stdout.write(summary);
   if (process.env.GITHUB_OUTPUT) {
     const outputs = {
@@ -224,7 +429,12 @@ async function main() {
       "source-lock-ref": result.decision.sourceLockRef || "",
       "promotion-pr": result.pullRequest?.html_url || "",
     };
-    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${Object.entries(outputs).map(([key, value]) => `${key}=${value}`).join("\n")}\n`);
+    fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `${Object.entries(outputs)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("\n")}\n`,
+    );
   }
 }
 

package/scripts/generate-site-bundle.mjs

@@ -328,6 +328,7 @@ const manualMetaById = new Map(Object.entries({
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
+  "github-artifact-attestation": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 108 },
   "publication-authority": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 105 },
   "github-governance-authority": { capabilityGroup: "governance-versioning", audience: ["maintainer", "release-operator", "agent"], maturity: "preview", order: 106 },
   "controller-evidence": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator", "agent"], maturity: "draft", order: 205 },
@@ -405,6 +406,7 @@ function cliCommandMeta(id) {
     "collect-github-release": { group: "release-passport-trust", purpose: "Collect GitHub Release assets into a release passport." },
     create: { group: "release-passport-trust", purpose: "Create canonical sealed publication evidence documents." },
     "create-publication-admission": { group: "release-passport-trust", purpose: "Create a canonical short-lived publication admission envelope from exact consumer bindings." },
+    "create-github-artifact-attestation-policy": { group: "release-passport-trust", purpose: "Create an exact source, signer, Linux build, and Release Passport attestation policy." },
     "create-runner-provenance": { group: "release-passport-trust", purpose: "Create runner provenance evidence with an explicit qualification floor." },
     diagnostics: { group: "observability-diagnostics", purpose: "Inspect diagnostics command families." },
     "diagnostics-summary": { group: "observability-diagnostics", purpose: "Summarize diagnostics artifacts into JSON and cross-platform lifecycle timing tables." },
@@ -494,6 +496,7 @@ function cliCommandMeta(id) {
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
     "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
+    "verify-github-artifact-attestation": { group: "release-passport-trust", purpose: "Verify GitHub keyless attestation identity plus local artifact, manifest, Passport, predicate, bundle, and evidence bindings." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
     "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
     "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
@@ -532,6 +535,7 @@ function nodeApiMeta(exportName) {
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./anchored-version-material": { group: "reusable-build", summary: "Anchored/manual derived version material preflight, exact-tree binding, and digest evidence APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
+    "./github-artifact-attestation": { group: "release-passport-trust", summary: "GitHub keyless artifact attestation policy, predicate, provider evidence, and fail-closed verification APIs." },
     "./kfd-agent-hub": { group: "kfd-trust", summary: "Declarative Agent Hub adapter inspection, fixed-suite execution, exact KFD cut locking, and agent explanation APIs." },
     "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
@@ -606,6 +610,7 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
 }
 
 function workflowCapabilityGroup(entry) {
+  if (entry.id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
@@ -615,6 +620,7 @@ function workflowCapabilityGroup(entry) {
 }
 
 function actionCapabilityGroup(id) {
+  if (id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (id === "promote-buildchain-ref") return capabilityGroup("release-passport-trust");
   if (id === "run-lifecycle" || id === "validate-config") return capabilityGroup("reusable-build");
   if (id === "report-buildchain-issue") return capabilityGroup("observability-diagnostics");
@@ -898,6 +904,7 @@ function buildSiteBundle() {
         ["dev-pr-auto-merge", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
+        ["github-artifact-attestation", "release-passport"],
         ["buildchain-patrol", "repository-patrol"],
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
@@ -991,6 +998,7 @@ function buildSiteBundle() {
         "publish evidence JSON",
         "buildchain.release.json",
         "release passport assets",
+        "GitHub artifact attestation Sigstore bundle and Buildchain evidence JSON",
       ],
       owner: "promote-buildchain-ref",
     },
@@ -1023,6 +1031,10 @@ function buildSiteBundle() {
       "llms.txt",
       "buildchain-release-bundle.json",
       "buildchain-release-bundle.tar.gz",
+      "github-artifact-attestation.policy.json",
+      "github-artifact-attestation.predicate.json",
+      "github-artifact-attestation.evidence.json",
+      "attestation.sigstore.json",
     ],
     site: [
       "buildchain-site.json",