@kungfu-tech/buildchain 2.11.14-alpha.1 → 2.11.14-alpha.2

package/dist/site/public-surface-audit.json

@@ -412,6 +412,7 @@
           "buildchain-ref",
           "buildchain-repository",
           "checkout-cache-fallback",
+          "checkout-cache-fetch-attempts",
           "checkout-cache-mirror-url-template",
           "checkout-cache-mode",
           "checkout-cache-reference-repository-template",
@@ -442,7 +443,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 48
+        "inputCount": 49
       },
       {
         "id": ".bump-minor-version",
@@ -2538,8 +2539,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "3c0729f5351eb82fe26625fa5aabf30903f45f68af2431e02860f85ada468ac9",
-    "workflowRegistryDigest": "4041321df08640a802a87ff0fbe8584d95dc416945b43778727adb820cab9097",
-    "pageRegistryDigest": "172c596669f7793af188430bde105d1e940c4927ba6446dc9f7ecf0456f1a4e1"
+    "workflowRegistryDigest": "7052aa984ab49647ce2c9f96669caa32f92da57d8b2e506ac172089bedd793cf",
+    "pageRegistryDigest": "784424e0ecb730449947fc0a3aba0bfcff77c34d097d63d71a9d60d5db1383df"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-10T11:01:58.300Z",
-  "publishedAt": "2026-07-10T11:01:58.300Z",
+  "generatedAt": "2026-07-10T13:03:42.866Z",
+  "publishedAt": "2026-07-10T13:03:42.866Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "5a95cdcb4e1114635046a0765aec1ea1ecc60dcd",
+  "sourceRevision": "d0be2b26d092ef5fa411d30888ea0ee3fa044c85",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.1",
+    "version": "2.11.14-alpha.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-10T11:01:58.300Z",
-  "publishedAt": "2026-07-10T11:01:58.300Z",
+  "generatedAt": "2026-07-10T13:03:42.866Z",
+  "publishedAt": "2026-07-10T13:03:42.866Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "5a95cdcb4e1114635046a0765aec1ea1ecc60dcd",
+  "sourceRevision": "d0be2b26d092ef5fa411d30888ea0ee3fa044c85",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.1",
+    "version": "2.11.14-alpha.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -197,7 +197,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:16c8e4994276142e6b57a61a18a88998727dce5911cb2da96d3900c049fb76dc"
+      "digest": "sha256:60c39693878258d275e9d47983b306faed35d6416297c14570429de73284604c"
     },
     {
       "id": "reusable-build-surface",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:5f56d66ad2798bc46acde3f8091c2e5ccee80412c1b26b70c8197ff9c7f6a406"
+      "digest": "sha256:4f3699841c5a189d199db045d526b11f76ad0dff1464d6a63ca98ceadf1bb215"
     },
     {
       "id": "publish-transaction",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:f2eae65a8b678203da26e223bda9cffd7939852deea406f7328ce9e617da3c6f"
+      "digest": "sha256:59858b6e02e42377b8a1f3d6d33ba50c5ffba476f7e1443fd61e03919046eff2"
     },
     {
       "id": "release-flow",
@@ -253,7 +253,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4c88b27af8aeb3f72fc8b979529b68d5fbc910dce70fe4219192c09aeb404e5c"
+      "digest": "sha256:f1e92ba87417dc9aac4f8cf080565f7f2c114b5007bb68b90f33692c73fdad88"
     }
   ],
   "facts": [

package/dist/site/workflow-registry.json

@@ -26,6 +26,7 @@
         "buildchain-ref",
         "buildchain-repository",
         "checkout-cache-fallback",
+        "checkout-cache-fetch-attempts",
         "checkout-cache-mirror-url-template",
         "checkout-cache-mode",
         "checkout-cache-reference-repository-template",
@@ -56,7 +57,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 48,
+      "inputCount": 49,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"

package/docs/lifecycle-protocol.md

@@ -293,7 +293,10 @@ checked-out release material. Any code or undeclared file change still fails the
 release tree gate.
 
 The action input `verification-command` remains supported. When it is provided,
-it overrides `lifecycle.verify` for that invocation.
+it overrides `lifecycle.verify` for that invocation. The override inherits
+`[lifecycle.env]` and `lifecycle.verify.env`; when the configured stage declares
+`shell`, it also inherits that shell. If the stage has no explicit shell,
+Buildchain preserves the platform-default shell for compatibility.
 
 ## Migration Preflight
 

package/docs/publication-artifacts.md

@@ -150,6 +150,15 @@ The build-only workflow:
 
 It does not publish npm packages, deploy web pages, or create GitHub Releases.
 
+The paper release preset additionally hydrates every prior published package
+registry from the npm registry before generating the current manifest. npm
+package integrity authenticates each downloaded source; Buildchain verifies the
+registry self-digest, merges immutable records, and fails if a cumulative
+registry drops an accepted version or changes immutable route/artifact facts.
+The synthesized package therefore carries complete history even on a clean
+runner. Its cumulative registry and file SHA-256 values are bound into the paper
+release build summary and release passport evidence.
+
 ## Paper Release Preset
 
 Paper repositories that publish a versioned npm package should use the

package/docs/release-governance.md

@@ -318,8 +318,14 @@ After each merge, the next PR is re-evaluated before it can move the protected
 dev branch. This prevents one merge from silently making the next candidate
 stale or conflicting.
 
-The required check should be the `check` job. Repositories can keep that job
-name stable while changing the actual verification command declaratively in
+The canonical consumer required check context is `check / check`, matching the
+reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
+emits the repository-local context `check`, so Buildchain self-promotion,
+release-line bootstrap, and dogfood patrol wrappers pass `check` explicitly.
+Release governance preserves the exact context emitted by the repository and
+records branch-protection policy before/after facts; it does not rewrite one
+context shape into the other. Consumer repositories can keep their context
+stable while changing the actual verification command declaratively in
 `buildchain.toml`:
 
 ```toml
@@ -359,7 +365,7 @@ jobs:
       statuses: read
     with:
       target-branch: dev/v2/v2.6
-      required-status-checks: check
+      required-status-checks: check / check
       ready-label: ready
       block-labels: blocked,do-not-merge
       max-merges: 1

package/docs/reusable-build-surface.md

@@ -233,6 +233,7 @@ jobs:
       checkout-cache-reference-repository-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE }}
       checkout-cache-fallback: github
       checkout-cache-timeout-seconds: 60
+      checkout-cache-fetch-attempts: 3
 ```
 
 `checkout-cache-mode` accepts:
@@ -255,7 +256,10 @@ Do not read cache URLs or reference paths from PR-controlled files such as
 `.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org
 variables. Buildchain does not pass GitHub credentials to cache mirrors or
 reference repositories. If it must fall back to GitHub, the workflow token is
-used only for the GitHub fetch path.
+used only for the GitHub fetch path. Retryable timeout and transient network
+failures use the bounded `checkout-cache-fetch-attempts` budget; permanent
+failures stop immediately. Diagnostics record the configured budget and actual
+GitHub fetch attempts before exact HEAD/tree verification.
 
 Each platform diagnostics artifact includes `source-checkout.json` and embeds a
 compact `sourceCheckout` summary in `diagnostics.json`: mode, transport,
@@ -592,7 +596,7 @@ jobs:
       runner-preset: github-hosted
       trusted-publishing: true
       github-release: true
-      required-status-check: check
+      required-status-check: check / check
       required-artifact-count: 3
       publish-dist-tag: alpha
       publish-package-set-order: platforms-first-main-last

package/docs/web-surface-deployments.md

@@ -351,6 +351,16 @@ The CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:
 - `web-surface-artifact-hash`
 - `web-surface-manifest-json`
 
+The reusable workflow resolves that same effective channel before running the
+caller build or verify command. Both steps receive
+`BUILDCHAIN_WEB_SURFACE_CHANNEL` (`preview`, `staging`, or `production`) and
+`BUILDCHAIN_PREVIEW_ALIAS` for previews. Compatibility aliases
+`BUILDCHAIN_SURFACE_CHANNEL` and `BUILDCHAIN_WEB_SURFACE_ALIAS` are also
+provided. Callers should consume these variables instead of reconstructing the
+release-intent state machine from raw GitHub events.
+An unapproved manual canary resolves to `staging`; a trusted manual dispatch
+with `production-approved=true` resolves to `production` through the same path.
+
 ## Explicit Apply
 
 `deploy-apply` and `cleanup-apply` are explicit execution modes for the
@@ -452,7 +462,11 @@ HTTP check is visible from the consumer run.
 
 It can also execute a previously saved deploy plan. In that mode Buildchain
 recomputes the local artifact hash before running AWS commands and fails closed
-if the artifact no longer matches the saved plan:
+if the artifact no longer matches the saved plan. Before any adapter operation,
+it also checks channel-aware JSON manifests in the artifact: top-level
+`canonicalHost` and declared `pages[].host` facts must belong to the plan's
+surface hosts. A production plan therefore rejects staging/preview host facts
+before AWS apply:
 
 ```bash
 node scripts/web-surface.mjs \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.14-alpha.1",
+  "version": "2.11.14-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-contract.js

@@ -96,6 +96,10 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "platforms-json",
         "release-candidate",
         "artifact-transfer-mode",
+        "checkout-cache-mode",
+        "checkout-cache-fallback",
+        "checkout-cache-timeout-seconds",
+        "checkout-cache-fetch-attempts",
         "buildchain-contract-lock-path",
         "buildchain-contract-drift-issue-mode",
       ],
@@ -104,6 +108,7 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "publish source locks are verified before heavy build jobs",
         "release-candidate builds do not publish registry artifacts",
         "contract drift is checked before heavy build jobs for stable floating refs",
+        "retryable GitHub fallback fetches use a bounded attempt budget before exact source SHA and tree verification",
       ],
     }),
     surface(root, {
@@ -115,7 +120,7 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       requiredOutputs: ["promoted-sha", "built-source-sha", "release-candidate-artifact"],
       breakingDefaults: {
         promoteOnlyReleaseCandidate: true,
-        requiredStatusCheck: "check",
+        requiredStatusCheck: "check / check",
       },
       optionalInputs: [
         "buildchain-ref",
@@ -177,6 +182,8 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "contract drift is checked before caller build, web-surface render, deploy planning, and apply side effects",
         "compatible contract drift continues and produces a consumer issue or summary",
         "breaking contract drift fails closed before rendering, deployment, or release publication",
+        "effective channel and preview alias are injected before caller build and verify commands",
+        "channel-aware artifact host facts are checked against the deploy plan before adapter side effects",
       ],
     }),
     surface(root, {
@@ -189,6 +196,7 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       breakingDefaults: {
         requireGovernance: false,
         releasePassport: true,
+        requiredStatusCheck: "check / check",
       },
       optionalInputs: [
         "publish-transaction",

package/packages/core/publication-artifact.js

@@ -477,7 +477,54 @@ function publicationArchiveRecord({ collected, manifestPath, passportPath, regis
   };
 }
 
-function updatePublicationArchiveRegistry({ cwd, collected, manifestPath, passportPath, registryOutput, generatedAt }) {
+function immutablePublicationRecord(record = {}) {
+  const { publishedAt: _publishedAt, latestObservedAt: _latestObservedAt, recordSha256: _recordSha256, ...immutable } = record;
+  return immutable;
+}
+
+function readVerifiedPublicationRegistry(registryPath) {
+  const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+  if (registry.contract !== PUBLICATION_ARTIFACT_REGISTRY_CONTRACT) {
+    throw new Error(`publication archive registry has unsupported contract: ${registry.contract || "(missing)"}`);
+  }
+  const expectedDigest = sha256Json({ ...registry, registrySha256: undefined });
+  if (registry.registrySha256 !== expectedDigest) {
+    throw new Error(`publication archive registry digest mismatch for ${registryPath}: expected ${expectedDigest}, got ${registry.registrySha256 || "(missing)"}`);
+  }
+  if (!Array.isArray(registry.versions)) throw new Error(`publication archive registry versions must be an array: ${registryPath}`);
+  return registry;
+}
+
+function mergePublicationRegistryVersions({ registries = [], publicationId }) {
+  const versions = new Map();
+  for (const registry of registries) {
+    if (registry.publication?.id !== publicationId) {
+      throw new Error(`publication archive registry id mismatch: expected ${publicationId}, got ${registry.publication?.id || "(missing)"}`);
+    }
+    if (registry.historyPolicy === "cumulative-authenticated-hydration") {
+      const declaredVersions = new Set(registry.versions.map((record) => String(record?.version || "")));
+      const missingVersions = [...versions.keys()].filter((version) => !declaredVersions.has(version));
+      if (missingVersions.length > 0) throw new Error(`cumulative publication archive registry dropped accepted versions: ${missingVersions.join(", ")}`);
+    }
+    for (const record of registry.versions) {
+      const version = String(record?.version || "").trim();
+      if (!version) throw new Error("publication archive registry record is missing version");
+      const existing = versions.get(version);
+      if (!existing) {
+        versions.set(version, record);
+        continue;
+      }
+      if (existing.immutableDigest !== record.immutableDigest || stableJson(immutablePublicationRecord(existing)) !== stableJson(immutablePublicationRecord(record))) {
+        throw new Error(`publication archive version ${version} changed across accepted registries: ${existing.immutableDigest || "(missing)"} != ${record.immutableDigest || "(missing)"}`);
+      }
+      const latestObservedAt = [existing.latestObservedAt, record.latestObservedAt].filter(Boolean).sort().at(-1);
+      versions.set(version, latestObservedAt ? { ...existing, latestObservedAt } : existing);
+    }
+  }
+  return [...versions.values()];
+}
+
+function updatePublicationArchiveRegistry({ cwd, collected, manifestPath, passportPath, registryOutput, registryInputs = [], generatedAt }) {
   const archive = collected.manifest.publication.archive;
   if (!archive) {
     return undefined;
@@ -503,17 +550,16 @@ function updatePublicationArchiveRegistry({ cwd, collected, manifestPath, passpo
       siteConsumers: collected.manifest.publication.siteConsumers,
     },
     appendOnly: true,
+    historyPolicy: "cumulative-authenticated-hydration",
     sameVersionRepublish: "fail-on-digest-change",
     immutablePathPolicy: archive.immutablePathPolicy,
     versions: [],
   };
-  if (fs.existsSync(registryPath)) {
-    registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
-    if (registry.contract !== PUBLICATION_ARTIFACT_REGISTRY_CONTRACT) {
-      throw new Error(`publication archive registry has unsupported contract: ${registry.contract || "(missing)"}`);
-    }
-  }
-  const versions = Array.isArray(registry.versions) ? registry.versions : [];
+  const inputPaths = [...registryInputs.map((entry) => path.resolve(cwd, entry)), ...(fs.existsSync(registryPath) ? [registryPath] : [])];
+  const versions = mergePublicationRegistryVersions({
+    registries: inputPaths.map(readVerifiedPublicationRegistry),
+    publicationId: archive.id,
+  });
   const existingIndex = versions.findIndex((entry) => entry.version === record.version);
   if (existingIndex !== -1) {
     const existing = versions[existingIndex];
@@ -559,6 +605,7 @@ export function writePublicationArtifact({
   output = "",
   passportOutput = "",
   registryOutput = "",
+  registryInputs = [],
   sourceSha = "",
   sourceBundle = true,
   sourceBundlePath = "",
@@ -586,6 +633,7 @@ export function writePublicationArtifact({
     manifestPath: path.resolve(cwd, manifestOutput),
     passportPath: path.resolve(cwd, passportPath),
     registryOutput,
+    registryInputs,
     generatedAt,
   });
   return {

package/packages/core/publication-package.js

@@ -106,6 +106,7 @@ export function collectPublicationPackageFacts({
       manifestPath: publication.manifestPath,
       passportPath: ".buildchain/publication/publication-artifact-passport.json",
       registryPath: publication.archive?.registryPath || "",
+      registryHydrationPath: publication.archive ? ".buildchain/publication/registry-hydration.json" : "",
       sourceBundlePath: publication.sourceBundlePath,
       artifactPaths: [publication.primaryArtifact, ...publication.artifactPaths].filter(Boolean),
       metadataPaths: publication.metadataPaths,
@@ -131,6 +132,7 @@ export function preparePublicationNpmPackage({
     facts.publication.manifestPath,
     facts.publication.passportPath,
     facts.publication.registryPath,
+    facts.publication.registryHydrationPath,
     facts.publication.sourceBundlePath,
     ...facts.publication.artifactPaths,
     ...facts.publication.metadataPaths,
@@ -197,6 +199,9 @@ export function preparePublicationNpmPackage({
       publicationManifest: facts.publication.manifestPath,
       publicationPassport: facts.publication.passportPath,
       publicationRegistry: facts.publication.registryPath || undefined,
+      publicationRegistryHydration: files.some((file) => file.path === facts.publication.registryHydrationPath)
+        ? facts.publication.registryHydrationPath
+        : undefined,
       primaryArtifact: facts.publication.primaryArtifact,
       sourceBundle: facts.publication.sourceBundlePath,
       siteConsumers: facts.publication.siteConsumers,

package/scripts/locked-source-checkout.mjs

@@ -213,6 +213,31 @@ function fetchSha({ targetPath, remoteName, remoteUrl, sha, fetchRef, timeoutMs,
   }
 }
 
+export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onRetry = () => {}, shouldRetry = () => true }) {
+  const limit = Math.max(1, Math.floor(Number(attempts) || 1));
+  let lastError;
+  for (let attempt = 1; attempt <= limit; attempt += 1) {
+    onAttempt({ attempt, limit });
+    try {
+      return { value: fetch({ attempt, limit }), attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      if (attempt >= limit || !shouldRetry(error)) {
+        error.fetchAttempts = attempt;
+        throw error;
+      }
+      onRetry({ attempt, limit, error });
+    }
+  }
+  throw lastError;
+}
+
+function retryableGitFetchError(error) {
+  const code = String(error?.code || "").toUpperCase();
+  if (["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "EPIPE"].includes(code)) return true;
+  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(String(error?.message || error || ""));
+}
+
 function githubRemoteUrl({ repository, serverUrl = "https://github.com" }) {
   const base = String(serverUrl || "https://github.com").replace(/\/+$/, "");
   return `${base}/${repository}.git`;
@@ -252,6 +277,7 @@ export function lockedSourceCheckout({
   referenceRepositoryTemplate = readEnv("BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE"),
   fallback = readEnv("BUILDCHAIN_CHECKOUT_CACHE_FALLBACK", "github"),
   timeoutSeconds = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_TIMEOUT_SECONDS", "60") || 60),
+  fetchAttempts = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_FETCH_ATTEMPTS", "3") || 3),
   diagnosticsPath = readEnv("BUILDCHAIN_SOURCE_CHECKOUT_DIAGNOSTICS_PATH", ".buildchain/diagnostics/source-checkout.json"),
   githubToken = readEnv("GITHUB_TOKEN"),
   githubServerUrl = readEnv("GITHUB_SERVER_URL", "https://github.com"),
@@ -265,6 +291,7 @@ export function lockedSourceCheckout({
   const treeSha = sourceTreeSha ? assertSha(sourceTreeSha, "sourceTreeSha") : "";
   const repoParts = splitRepository(repository);
   const timeoutMs = Math.max(1, Number(timeoutSeconds || 60)) * 1000;
+  const normalizedFetchAttempts = Math.max(1, Math.floor(Number(fetchAttempts) || 3));
   const targetPath = ensureCheckoutTarget(checkoutPath, workspace);
   git(["init"], { cwd: targetPath, timeoutMs });
   const renderedMirrorUrl = renderTemplate(mirrorUrlTemplate, { ...repoParts, sha });
@@ -285,6 +312,7 @@ export function lockedSourceCheckout({
       mode: normalizedMode,
       fallback: normalizedFallback,
       timeoutSeconds: Math.max(1, Number(timeoutSeconds || 60)),
+      fetchAttempts: normalizedFetchAttempts,
       mirror: sanitizeIdentity(renderedMirrorUrl),
       referenceRepository: sanitizeIdentity(renderedReferenceRepository),
     },
@@ -294,6 +322,7 @@ export function lockedSourceCheckout({
       transport: "github",
       fallbackUsed: normalizedMode === "off",
       fallbackReason: normalizedMode === "off" ? "cache disabled" : "",
+      githubFetchAttempts: 0,
     },
     verification: {
       head: "",
@@ -352,15 +381,20 @@ export function lockedSourceCheckout({
     if (!evidence.cache.fallbackReason && checkoutError) {
       evidence.cache.fallbackReason = checkoutError.message;
     }
-    fetchSha({
-      targetPath,
-      remoteName: "origin",
-      remoteUrl,
-      sha,
-      fetchRef,
-      timeoutMs,
-      env: githubAuthEnv(githubToken),
-    });
+    try {
+      const fetchResult = runBoundedFetch({
+        attempts: normalizedFetchAttempts,
+        fetch: () => fetchSha({ targetPath, remoteName: "origin", remoteUrl, sha, fetchRef, timeoutMs, env: githubAuthEnv(githubToken) }),
+        onAttempt: ({ attempt }) => { evidence.cache.githubFetchAttempts = attempt; },
+        onRetry: ({ attempt, limit, error }) => console.log(`buildchain: GitHub source fetch failed, retry ${attempt + 1}/${limit}: ${error.message}`),
+        shouldRetry: retryableGitFetchError,
+      });
+      evidence.cache.githubFetchAttempts = fetchResult.attempts;
+    } catch (error) {
+      evidence.durationMs = Date.now() - startedAt;
+      writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);
+      throw error;
+    }
     checkoutFetchedCommit(targetPath, sha, timeoutMs);
   }
   evidence.verification = verifyCheckout({ targetPath, sourceSha: sha, sourceTreeSha: treeSha });

package/scripts/publication-artifact.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
 import { writePublicationArtifact } from "../packages/core/publication-artifact.js";
 
 function readFlag(args, name, fallback = "") {
@@ -11,16 +13,32 @@ function readBooleanFlag(args, name) {
   return args.includes(`--${name}`);
 }
 
+function readRegistryInputs(args, cwd) {
+  const inputs = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--registry-input" && args[index + 1]) inputs.push(args[index + 1]);
+  }
+  const inputDir = readFlag(args, "registry-input-dir", "");
+  if (inputDir) {
+    const resolved = path.resolve(cwd, inputDir);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) throw new Error(`publication registry input directory is missing: ${inputDir}`);
+    inputs.push(...fs.readdirSync(resolved).filter((entry) => entry.endsWith(".json")).sort().map((entry) => path.join(resolved, entry)));
+  }
+  return inputs;
+}
+
 export function runPublicationArtifactCli(args = process.argv.slice(2)) {
   const [mode = "manifest"] = args;
   if (!["manifest", "collect"].includes(mode)) {
-    throw new Error("usage: buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--passport-output <file>] [--registry-output <file>] [--source-bundle <file>] [--no-source-bundle] [--json]");
+    throw new Error("usage: buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--passport-output <file>] [--registry-output <file>] [--registry-input <file>] [--registry-input-dir <dir>] [--source-bundle <file>] [--no-source-bundle] [--json]");
   }
+  const cwd = readFlag(args, "cwd", process.cwd());
   const result = writePublicationArtifact({
-    cwd: readFlag(args, "cwd", process.cwd()),
+    cwd,
     output: readFlag(args, "output", ""),
     passportOutput: readFlag(args, "passport-output", ""),
     registryOutput: readFlag(args, "registry-output", ""),
+    registryInputs: readRegistryInputs(args, cwd),
     sourceSha: readFlag(args, "source-sha", ""),
     sourceBundlePath: readFlag(args, "source-bundle", ""),
     sourceBundle: !readBooleanFlag(args, "no-source-bundle"),