@kungfu-tech/buildchain 3.0.7-alpha.0 → 3.0.7

package/scripts/engineering-housekeeper-workflow.mjs

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  GitHubHousekeeperClient,
+  applyGitHubHousekeeperPlan,
+  collectGitHubHousekeeperInventory,
+} from "../packages/core/engineering-housekeeper-github.js";
+
+const VALID_MODES = new Set(["report", "apply"]);
+const VALID_SCOPES = new Set(["branches", "pull-requests"]);
+const DEFAULT_OUTPUT_DIRECTORY = ".buildchain/engineering-housekeeper";
+
+function requiredString(value, field) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${field} is required`);
+  return normalized;
+}
+
+function boolOption(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new Error(`boolean input must be true or false, got: ${value}`);
+}
+
+function positiveInteger(value, fallback, field) {
+  const selected =
+    value === undefined || value === "" ? fallback : Number(value);
+  if (!Number.isInteger(selected) || selected < 1) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+  return selected;
+}
+
+function splitPatterns(value, fallback) {
+  const normalized = String(value || "").trim();
+  if (!normalized) return [...fallback];
+  return [
+    ...new Set(
+      normalized
+        .split(/[\n,]+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+function normalizeRepository(value) {
+  const repository = requiredString(value, "repository");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
+    throw new Error(`repository must be owner/repo, got: ${repository}`);
+  }
+  return repository;
+}
+
+function normalizeMode(value) {
+  const mode = String(value || "report")
+    .trim()
+    .toLowerCase();
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(`mode must be report or apply, got: ${value || "<empty>"}`);
+  }
+  return mode;
+}
+
+export function normalizeHousekeeperWorkflowOptions(options = {}) {
+  const mode = normalizeMode(options.mode ?? process.env.HOUSEKEEPER_MODE);
+  const applyEnabled = boolOption(
+    options.applyEnabled ?? process.env.HOUSEKEEPER_APPLY_ENABLED,
+    false,
+  );
+  if (mode === "apply" && !applyEnabled) {
+    throw new Error("apply mode requires apply-enabled=true");
+  }
+  if (mode === "report" && applyEnabled) {
+    throw new Error("apply-enabled=true is only valid when mode=apply");
+  }
+  return {
+    mode,
+    applyEnabled,
+    repository: normalizeRepository(
+      options.repository ||
+        process.env.HOUSEKEEPER_REPOSITORY ||
+        process.env.GITHUB_REPOSITORY,
+    ),
+    targetBranch: requiredString(
+      options.targetBranch || process.env.HOUSEKEEPER_TARGET_BRANCH,
+      "target-branch",
+    ).replace(/^refs\/heads\//, ""),
+    staleDays: positiveInteger(
+      options.staleDays ?? process.env.HOUSEKEEPER_STALE_DAYS,
+      30,
+      "stale-days",
+    ),
+    maxActions: positiveInteger(
+      options.maxActions ?? process.env.HOUSEKEEPER_MAX_ACTIONS,
+      20,
+      "max-actions",
+    ),
+    protectedPatterns: splitPatterns(
+      options.protectedPatterns ?? process.env.HOUSEKEEPER_PROTECTED_PATTERNS,
+      ["dev/**", "alpha/**", "release/**", "publish-gate/**"],
+    ),
+    retainedPatterns: splitPatterns(
+      options.retainedPatterns ?? process.env.HOUSEKEEPER_RETAINED_PATTERNS,
+      ["train/**", "authority/**"],
+    ),
+    stalePullRequestLabel: String(
+      options.stalePullRequestLabel ??
+        process.env.HOUSEKEEPER_STALE_PR_LABEL ??
+        "",
+    ).trim(),
+    observedAt: String(
+      options.observedAt ||
+        process.env.HOUSEKEEPER_OBSERVED_AT ||
+        new Date().toISOString(),
+    ),
+    appliedAt: String(
+      options.appliedAt ||
+        process.env.HOUSEKEEPER_APPLIED_AT ||
+        new Date().toISOString(),
+    ),
+    outputDirectory: path.resolve(
+      String(
+        options.outputDirectory ||
+          process.env.HOUSEKEEPER_OUTPUT_DIRECTORY ||
+          DEFAULT_OUTPUT_DIRECTORY,
+      ),
+    ),
+  };
+}
+
+function workflowPolicy(options) {
+  return {
+    protectedPatterns: options.protectedPatterns,
+    retainedPatterns: options.retainedPatterns,
+    pullRequests: {
+      reportStale: true,
+      label: options.stalePullRequestLabel,
+      autoClose: false,
+    },
+  };
+}
+
+function actionIdentity(action) {
+  return action.name
+    ? `${action.kind}:${action.name}`
+    : `${action.kind}:#${action.number}`;
+}
+
+function decisionFor(entry) {
+  if (entry.kind === "branch") return entry.decision;
+  return entry.actions.length > 0 ? entry.actions.join(",") : "report-only";
+}
+
+export function renderHousekeeperWorkflowReport(
+  plan,
+  receipt,
+  { mode, scope = "all" } = {},
+) {
+  const lines = [
+    "## Engineering Housekeeper",
+    "",
+    `Mode: \`${mode || "report"}\``,
+    `Scope: \`${scope}\``,
+    `Repository: \`${plan.repository}\``,
+    `Target ref: \`${plan.target.name}@${plan.target.headOid}\``,
+    `Observed at: \`${plan.observedAt}\``,
+    `Plan root: \`${plan.planRoot}\``,
+    `Receipt root: \`${receipt.receiptRoot}\``,
+    "",
+    "### Decisions",
+    "",
+    "| Subject | Observed ref | Decision | Reason codes |",
+    "| --- | --- | --- | --- |",
+  ];
+  for (const entry of plan.inventory) {
+    const subject =
+      entry.kind === "branch" ? entry.name : `PR #${entry.number}`;
+    lines.push(
+      `| \`${subject}\` | \`${entry.headOid}\` | ${decisionFor(entry)} | \`${entry.reasonCodes.join(",")}\` |`,
+    );
+  }
+  if (plan.inventory.length === 0)
+    lines.push("| - | - | retain | `inventory.empty` |");
+  lines.push(
+    "",
+    "### Outcomes",
+    "",
+    "| Action | Outcome | Details |",
+    "| --- | --- | --- |",
+  );
+  for (const outcome of receipt.outcomes) {
+    const details =
+      outcome.reasonCodes?.join(",") || outcome.providerError?.operation || "-";
+    lines.push(
+      `| \`${outcome.action}\` | ${outcome.status} | \`${details}\` |`,
+    );
+  }
+  if (receipt.outcomes.length === 0)
+    lines.push("| - | no-op | `no-actions-in-scope` |");
+  return `${lines.join("\n")}\n`;
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeText(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value);
+}
+
+function writeOutputs(outputs, outputFile = process.env.GITHUB_OUTPUT) {
+  if (!outputFile) return;
+  const lines = Object.entries(outputs).map(
+    ([key, value]) => `${key}=${String(value).replace(/\n/g, "%0A")}`,
+  );
+  fs.appendFileSync(outputFile, `${lines.join("\n")}\n`);
+}
+
+function appendSummary(
+  markdown,
+  summaryFile = process.env.GITHUB_STEP_SUMMARY,
+) {
+  if (summaryFile) fs.appendFileSync(summaryFile, markdown);
+  else process.stdout.write(markdown);
+}
+
+export async function createHousekeeperWorkflowPlan(
+  optionsInput = {},
+  clientInput,
+) {
+  const options = normalizeHousekeeperWorkflowOptions(optionsInput);
+  const client =
+    clientInput ||
+    new GitHubHousekeeperClient({
+      token: requiredString(process.env.GITHUB_TOKEN, "GitHub token"),
+    });
+  const plan = await collectGitHubHousekeeperInventory({
+    client,
+    repository: options.repository,
+    targetBranch: options.targetBranch,
+    observedAt: options.observedAt,
+    staleDays: options.staleDays,
+    policy: workflowPolicy(options),
+  });
+  const receipt = await applyGitHubHousekeeperPlan({
+    client,
+    plan,
+    dryRun: true,
+    appliedAt: options.appliedAt,
+    staleDays: options.staleDays,
+    maxActions: options.maxActions,
+  });
+  return { options, plan, receipt };
+}
+
+export function selectHousekeeperActions(plan, scope, maxActions) {
+  if (!VALID_SCOPES.has(scope))
+    throw new Error(`scope must be branches or pull-requests, got: ${scope}`);
+  return plan.actions
+    .slice(0, positiveInteger(maxActions, 20, "max-actions"))
+    .filter((action) =>
+      scope === "branches"
+        ? action.kind === "delete-branch"
+        : action.kind.endsWith("-pull-request"),
+    );
+}
+
+export async function applyHousekeeperWorkflowScope({
+  options: optionsInput = {},
+  plan,
+  scope,
+  client: clientInput,
+}) {
+  const options = normalizeHousekeeperWorkflowOptions(optionsInput);
+  if (options.mode !== "apply" || !options.applyEnabled) {
+    throw new Error("scope apply requires mode=apply and apply-enabled=true");
+  }
+  if (
+    plan.repository !== options.repository ||
+    plan.target.name !== options.targetBranch
+  ) {
+    throw new Error(
+      "plan repository or target branch does not match current workflow inputs",
+    );
+  }
+  const client =
+    clientInput ||
+    new GitHubHousekeeperClient({
+      token: requiredString(process.env.GITHUB_TOKEN, "GitHub token"),
+    });
+  const scopedPlan = {
+    ...plan,
+    actions: selectHousekeeperActions(plan, scope, options.maxActions),
+  };
+  const receipt = await applyGitHubHousekeeperPlan({
+    client,
+    plan: scopedPlan,
+    dryRun: false,
+    appliedAt: options.appliedAt,
+    staleDays: options.staleDays,
+    maxActions: Math.max(1, scopedPlan.actions.length),
+  });
+  return { options, plan, scopedPlan, receipt };
+}
+
+async function planCommand() {
+  const result = await createHousekeeperWorkflowPlan();
+  const planPath = path.join(result.options.outputDirectory, "plan.json");
+  const reportPath = path.join(result.options.outputDirectory, "report.md");
+  const receiptPath = path.join(
+    result.options.outputDirectory,
+    "report-receipt.json",
+  );
+  const report = renderHousekeeperWorkflowReport(result.plan, result.receipt, {
+    mode: result.options.mode,
+  });
+  writeJson(planPath, result.plan);
+  writeJson(receiptPath, result.receipt);
+  writeText(reportPath, report);
+  appendSummary(report);
+  writeOutputs({
+    "plan-path": planPath,
+    "report-path": reportPath,
+    "report-receipt-path": receiptPath,
+    "plan-root": result.plan.planRoot,
+    "report-receipt-root": result.receipt.receiptRoot,
+    "action-count": result.plan.actions.length,
+    "branch-action-count": result.plan.actions.filter(
+      (action) => action.kind === "delete-branch",
+    ).length,
+    "pull-request-action-count": result.plan.actions.filter((action) =>
+      action.kind.endsWith("-pull-request"),
+    ).length,
+    outcome:
+      result.plan.actions.length === 0
+        ? "no-actions"
+        : `${result.options.mode}-ready`,
+  });
+}
+
+async function applyCommand(scope) {
+  const planPath = path.resolve(
+    requiredString(process.env.HOUSEKEEPER_PLAN_PATH, "HOUSEKEEPER_PLAN_PATH"),
+  );
+  const plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+  const result = await applyHousekeeperWorkflowScope({ plan, scope });
+  const receiptPath = path.join(
+    result.options.outputDirectory,
+    `${scope}-receipt.json`,
+  );
+  const reportPath = path.join(
+    result.options.outputDirectory,
+    `${scope}-report.md`,
+  );
+  const report = renderHousekeeperWorkflowReport(result.plan, result.receipt, {
+    mode: result.options.mode,
+    scope,
+  });
+  writeJson(receiptPath, result.receipt);
+  writeText(reportPath, report);
+  appendSummary(report);
+  writeOutputs({
+    "receipt-path": receiptPath,
+    "report-path": reportPath,
+    "receipt-root": result.receipt.receiptRoot,
+    "outcome-count": result.receipt.outcomes.length,
+    "selected-action-count": result.scopedPlan.actions.length,
+    outcome: result.scopedPlan.actions.length === 0 ? "no-actions" : "applied",
+  });
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command === "plan") return planCommand();
+  if (command === "apply")
+    return applyCommand(requiredString(process.argv[3], "scope"));
+  throw new Error(
+    "usage: engineering-housekeeper-workflow.mjs plan | apply <branches|pull-requests>",
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/scripts/generate-site-bundle.mjs

@@ -332,11 +332,16 @@ function capabilityGroup(id) {
   return id;
 }
 
-function publicSurfaceLifecycle({ owner, maturity, nonDuplicationRationale }) {
+function publicSurfaceLifecycle({
+  owner,
+  maturity,
+  nonDuplicationRationale,
+  introducedVersion = "pre-3.0.2-alpha.4",
+}) {
   return {
     owner,
     maturity,
-    introducedVersion: "pre-3.0.2-alpha.4",
+    introducedVersion,
     compatibilityPromise: "preserved-through-the-v3-major-line",
     deprecationReplacement: "",
     sunsetCondition: "explicit-breaking-change-review-in-a-future-major-line",
@@ -369,6 +374,7 @@ const manualMetaById = new Map(Object.entries({
   "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 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
+  "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
   "runtime-train-validation": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer"], maturity: "stable", order: 220 },
@@ -521,7 +527,7 @@ function workflowCapabilityGroup(entry) {
   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");
-  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
+  if (entry.id.includes("patrol") || entry.id.includes("housekeeper") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
   if (entry.status === "repository-internal" || entry.status === "compatibility-fixture") return capabilityGroup("api-cli-reference");
   return capabilityGroup("api-cli-reference");
 }
@@ -732,6 +738,7 @@ function buildSiteBundle() {
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
       "docs/observed-evidence-patrol.md",
+      "docs/engineering-housekeeper.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
       "docs/controller-evidence.md",
@@ -791,6 +798,10 @@ function buildSiteBundle() {
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
+        ["engineering-housekeeper", "repository-patrol"],
+        ["engineering-housekeeper-daily", "repository-patrol"],
+        ["engineering-housekeeper-weekly", "repository-patrol"],
+        ["engineering-housekeeper-monthly", "repository-patrol"],
         ["stable-candidate-patrol", "repository-patrol"],
         ["dev-qualification-patrol", "repository-patrol"],
         ["dev-alpha-candidate-patrol", "repository-patrol"],
@@ -808,8 +819,13 @@ function buildSiteBundle() {
         ["candidate-lab", "repository-internal"],
         ["build-surface-fixture", "repository-internal"],
         ["buildchain-stable-candidate-qualification", "repository-internal"],
+        ["engineering-housekeeper", "preview"],
+        ["engineering-housekeeper-daily", "preview"],
+        ["engineering-housekeeper-weekly", "preview"],
+        ["engineering-housekeeper-monthly", "preview"],
         ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
+      const engineeringHousekeeper = entry.id.startsWith("engineering-housekeeper");
       return {
         ...entry,
         surface: surfaceById.get(entry.id) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
@@ -821,7 +837,10 @@ function buildSiteBundle() {
         ...publicSurfaceLifecycle({
           owner: "buildchain-workflows",
           maturity: statusById.get(entry.id) || "active",
-          nonDuplicationRationale: "Existing workflow identity retained for caller compatibility and repository orchestration.",
+          introducedVersion: engineeringHousekeeper ? packageJson.version : undefined,
+          nonDuplicationRationale: engineeringHousekeeper
+            ? "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+            : "Existing workflow identity retained for caller compatibility and repository orchestration.",
         }),
       };
     }),

package/scripts/inspect-artifact-signing-requests.mjs

@@ -82,6 +82,10 @@ export function inspectArtifactSigningRequests({
       if (seen.has(key))
         throw new Error(`duplicate artifact signing request: ${key}`);
       seen.add(key);
+      const {
+        entitlementsProfile = "none",
+        entitlementsPaths = [],
+      } = request.signature;
       const item = {
         id: request.artifact.id,
         slug: safeId(request.artifact.id),
@@ -104,6 +108,8 @@ export function inspectArtifactSigningRequests({
         sourceSha: request.source.sha,
         sourceTreeSha: request.source.treeSha,
         transportFormat: request.artifact.transport?.format || "",
+        entitlementsProfile,
+        entitlementsPaths: entitlementsPaths.join(","),
       };
       if (request.signature.profile === "detached-signature-v1")
         matrices.detached.push(item);

package/scripts/materialize-self-release-candidate-version.mjs

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import {
   getVersionStrategy,
   loadConfiguredAnchorManifest,
+  discoverConfiguredDerivedVersionMaterial,
 } from "../packages/core/buildchain-config.js";
 import {
   alignMajorBootstrapReleaseImpact,
@@ -64,6 +65,10 @@ export function materializeSelfReleaseCandidateVersion({
     throw new Error("self-release candidate requires declared version state");
   }
   const discoveredPaths = discovered.files.map((file) => file.path);
+  const derivedPaths = discoverConfiguredDerivedVersionMaterial(
+    cwd,
+    discovered.config,
+  ).map((file) => file.path);
   const versionStrategy = getVersionStrategy(discovered.config);
   const anchorManifest = loadConfiguredAnchorManifest(cwd, discovered.config);
   const lifecycleEnv = versionVerificationEnv(versionStrategy, anchorManifest, {
@@ -88,6 +93,7 @@ export function materializeSelfReleaseCandidateVersion({
     allowedPaths: versionVerificationAllowedPathsForPromotion(
       resolvedChannel,
       discoveredPaths,
+      derivedPaths,
     ),
     env: lifecycleEnv,
     runLifecycleVerify: false,

package/scripts/publication-commit-evidence.mjs

@@ -7,6 +7,12 @@ import { pathToFileURL } from "node:url";
 
 const SCHEMA = "kungfu-buildchain-publication-commit-evidence/v1";
 const INSTALLER_BUNDLE_SCHEMA = "kungfu.installer-publication-bundle/v1";
+const RELEASE_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const RELEASE_REDIRECT_HOSTS = new Set([
+  "github.com",
+  "release-assets.githubusercontent.com",
+  "objects.githubusercontent.com",
+]);
 
 function requiredString(value, label) {
   if (typeof value !== "string" || value.trim() === "") {
@@ -104,7 +110,7 @@ function validateInstallerBundle(evidence, expected) {
   }
   if (
     exactSha(bundle.sourceCommit, "installerBundle.sourceCommit") !==
-      expected.sourceSha ||
+      expected.candidateSourceSha ||
     !["alpha", "stable"].includes(bundle.channel)
   ) {
     throw new Error("installer bundle release identity mismatch");
@@ -228,6 +234,7 @@ function validateInstallerBundle(evidence, expected) {
   return {
     schema: bundle.schema,
     bundleRoot,
+    sourceCommit: bundle.sourceCommit,
     manifestDigest: bundle.manifestDigest,
     channel: bundle.channel,
     channelPayloadRoot: bundle.channelPayloadRoot,
@@ -238,10 +245,9 @@ function validateInstallerBundle(evidence, expected) {
     assets: bundle.assets,
   };
 }
-
 export function validatePublicationCommitEvidence(
   evidence,
-  { version, sourceSha, releaseSha, releaseTag } = {},
+  { version, sourceSha, candidateSourceSha, releaseSha, releaseTag } = {},
 ) {
   if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
     throw new Error("publication commit evidence must be an object");
@@ -264,6 +270,17 @@ export function validatePublicationCommitEvidence(
       throw new Error(`publication commit evidence ${field} mismatch`);
     }
   }
+  expected.candidateSourceSha = exactSha(
+    candidateSourceSha ?? identity.candidateSourceSha ?? expected.sourceSha,
+    "expected candidateSourceSha",
+  );
+  if (
+    identity.candidateSourceSha !== undefined &&
+    exactSha(identity.candidateSourceSha, "identity.candidateSourceSha") !==
+      expected.candidateSourceSha
+  ) {
+    throw new Error("publication commit evidence candidateSourceSha mismatch");
+  }
   const publicUrl = publicHttps(evidence.publication?.url, "publication.url");
   const payloadRoot = sha256Root(
     evidence.publication?.payloadRoot,
@@ -313,15 +330,47 @@ export async function verifyInstallerBundleReadback(
   if (typeof fetchImpl !== "function") {
     throw new Error("installer bundle read-back requires fetch");
   }
-  const manifestResponse = await fetchImpl(result.publicUrl, {
-    redirect: "manual",
-    cache: "no-store",
-  });
-  if (manifestResponse.status !== 200) {
-    throw new Error(
-      `installer bundle manifest read-back failed: HTTP ${manifestResponse.status}`,
-    );
-  }
+  const fetchReleaseReadback = async (url, label) => {
+    let current = url;
+    for (let hop = 0; hop <= 3; hop += 1) {
+      const response = await fetchImpl(current, {
+        redirect: "manual",
+        cache: "no-store",
+      });
+      if (response.status === 200) return response;
+      if (!RELEASE_REDIRECT_STATUSES.has(response.status)) {
+        throw new Error(`${label} failed: HTTP ${response.status}`);
+      }
+      if (hop === 3) {
+        throw new Error(`${label} exceeded the bounded redirect limit`);
+      }
+      const location = response.headers?.get?.("location");
+      if (!location) {
+        throw new Error(`${label} redirect omitted Location`);
+      }
+      const redirect = new URL(location, current);
+      if (
+        redirect.protocol !== "https:" ||
+        redirect.username ||
+        redirect.password ||
+        !RELEASE_REDIRECT_HOSTS.has(redirect.hostname) ||
+        (redirect.hostname === "github.com" &&
+          !redirect.pathname.startsWith(
+            "/kungfu-systems/kungfu/releases/download/",
+          ))
+      ) {
+        throw new Error(
+          `${label} redirected outside trusted GitHub release storage`,
+        );
+      }
+      current = redirect.href;
+    }
+    throw new Error(`${label} failed without a terminal response`);
+  };
+  const manifestResponse = await fetchReleaseReadback(
+    result.publicUrl,
+    "installer bundle manifest read-back",
+  );
   const manifestBytes = Buffer.from(await manifestResponse.arrayBuffer());
   if (digest(manifestBytes) !== bundle.manifestDigest) {
     throw new Error("installer bundle manifest digest mismatch");
@@ -336,7 +385,7 @@ export async function verifyInstallerBundleReadback(
     semanticRoot(unsigned) !== bundle.bundleRoot ||
     manifest.package?.name !== "@kungfu-tech/site" ||
     typeof manifest.package?.version !== "string" ||
-    manifest.identity?.sourceCommit !== result.identity.sourceSha ||
+    manifest.identity?.sourceCommit !== result.identity.candidateSourceSha ||
     manifest.identity?.releaseSha !== result.identity.releaseSha ||
     manifest.identity?.releaseTag !== result.identity.releaseTag ||
     manifest.identity?.version !== result.identity.version ||
@@ -365,15 +414,10 @@ export async function verifyInstallerBundleReadback(
   for (const asset of bundle.assets) {
     let observation = byUrl.get(asset.releaseUrl);
     if (!observation) {
-      const response = await fetchImpl(asset.releaseUrl, {
-        redirect: "manual",
-        cache: "no-store",
-      });
-      if (response.status !== 200) {
-        throw new Error(
-          `installer bundle asset read-back failed: HTTP ${response.status}`,
-        );
-      }
+      const response = await fetchReleaseReadback(
+        asset.releaseUrl,
+        "installer bundle asset read-back",
+      );
       const bytes = Buffer.from(await response.arrayBuffer());
       observation = {
         releaseUrl: asset.releaseUrl,
@@ -394,7 +438,7 @@ export async function verifyInstallerBundleReadback(
     schema: "kungfu-buildchain-installer-publication-bundle-seal/v1",
     bundleRoot: bundle.bundleRoot,
     manifestDigest: bundle.manifestDigest,
-    sourceCommit: result.identity.sourceSha,
+    sourceCommit: result.identity.candidateSourceSha,
     releaseTag: result.identity.releaseTag,
     releasePassport: bundle.releasePassport,
     observations,
@@ -409,6 +453,8 @@ async function main(args) {
     if (value === "--evidence") options.evidence = args[++index];
     else if (value === "--version") options.version = args[++index];
     else if (value === "--source-sha") options.sourceSha = args[++index];
+    else if (value === "--candidate-source-sha")
+      options.candidateSourceSha = args[++index];
     else if (value === "--release-sha") options.releaseSha = args[++index];
     else if (value === "--release-tag") options.releaseTag = args[++index];
     else throw new Error(`unknown argument: ${value}`);