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

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

@@ -7604,7 +7604,7 @@
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "2e7804e1fa8ef08bbe59fcf58908e47daef4dc145675fc9a989862671e40f993",
     "workflowRegistryDigest": "1ab8b8d32f2ceb8dffad69d1f877f6ad6b37355dbe62c6ef5c0e6b9f4f197acb",
-    "pageRegistryDigest": "5604707e51d06fa0b1739abb00d8d2db53fb3dda7d49d34ef558d63772f1fb84"
+    "pageRegistryDigest": "ce8922a853a4784781b708b0572cb3035ec08058847900b1eff2580130ba6d28"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-06T03:18:26.054Z",
-  "publishedAt": "2026-08-06T03:18:26.054Z",
+  "generatedAt": "2026-08-06T04:18:30.646Z",
+  "publishedAt": "2026-08-06T04:18:30.646Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2e685b037b979732297210d74b480d5e061a7aa4",
+  "sourceRevision": "0adfa4b1f1784f8d43ac056991822a32cf5e8e7f",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.6-alpha.3",
+    "version": "3.0.6-alpha.4",
     "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-08-06T03:18:26.054Z",
-  "publishedAt": "2026-08-06T03:18:26.054Z",
+  "generatedAt": "2026-08-06T04:18:30.646Z",
+  "publishedAt": "2026-08-06T04:18:30.646Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2e685b037b979732297210d74b480d5e061a7aa4",
+  "sourceRevision": "0adfa4b1f1784f8d43ac056991822a32cf5e8e7f",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.6-alpha.3",
+    "version": "3.0.6-alpha.4",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -237,7 +237,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3fbfe0227cf929f0ddc2050605d071643cee0b302a4c31920b4f9047c923ae8c"
+      "digest": "sha256:18da0179c3dbfee4fa393d46111122ef16b9da1130092b6d88d820e4277e87c2"
     },
     {
       "id": "build-facts",

package/docs/node-api-reference.md

@@ -447,7 +447,7 @@ Target: `./packages/core/index.js`. Public symbols: 562.
 | `readReleaseTransaction` | function: function readReleaseTransaction(filePath) | filePath | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { readReleaseTransaction } from "@kungfu-tech/buildchain";` | `packages/core/publish-transaction.js:367` |
 | `recordReleaseActivationPhase` | function: function recordReleaseActivationPhase(transaction, phaseId, { receiptRoots = [], failure = "" } = {}) | transaction, phaseId, { receiptRoots = [], failure = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { recordReleaseActivationPhase } from "@kungfu-tech/buildchain";` | `packages/core/release-activation-transaction.js:217` |
 | `recordReleasePropagationStage` | function: function recordReleasePropagationStage({ work, expectedWorkRoot, receipt } = {}) | { work, expectedWorkRoot, receipt } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { recordReleasePropagationStage } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-transitions.js:45` |
-| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain";` | `packages/core/release-candidate-recovery.js:376` |
+| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain";` | `packages/core/release-candidate-recovery.js:396` |
 | `redactBuildchainLogAttributes` | function: function redactBuildchainLogAttributes(attributes = {}) | attributes = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { redactBuildchainLogAttributes } from "@kungfu-tech/buildchain";` | `packages/core/logging.js:33` |
 | `redactDiagnosticsValue` | function: function redactDiagnosticsValue(key, value, pattern = DEFAULT_SECRET_KEY_PATTERN) | key, value, pattern = DEFAULT_SECRET_KEY_PATTERN | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { redactDiagnosticsValue } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:953` |
 | `redactIssueText` | function: function redactIssueText(value) | value | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { redactIssueText } from "@kungfu-tech/buildchain";` | `packages/core/issue-reporting.js:51` |
@@ -571,7 +571,7 @@ Target: `./packages/core/index.js`. Public symbols: 562.
 | `verifyPublicationQualificationReceipt` | function: function verifyPublicationQualificationReceipt({ receipt, capability, gateAggregate, expected = {}, usedNonces = [], now = new Date(), } = {}) | { receipt, capability, gateAggregate, expected = {}, usedNonces = [], now = new Date(), } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyPublicationQualificationReceipt } from "@kungfu-tech/buildchain";` | `packages/core/publication-authority.js:1096` |
 | `verifyPublicationReproducibility` | function: function verifyPublicationReproducibility({ cwd = process.cwd(), sourceSha = "", output = DEFAULT_OUTPUT, promote = false, keepWorkspaces = false, pullToolchain = true, packageName = "", allowUnpinnedToolchain = false, overlayPaths = [DEFAULT_REGISTRY_INPUT_DIR, DEFAULT_REGISTRY_HYDRATION], } = {}) | { cwd = process.cwd(), sourceSha = "", output = DEFAULT_OUTPUT, promote = false, keepWorkspaces = false, pullToolchain = true, packageName = "", allowUnpinnedToolchain = false, overlayPaths = [DEFAULT_REGISTRY_INPUT_DIR, DEFAULT_REGISTRY_HYDRATION], } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain";` | `packages/core/publication-reproducibility.js:869` |
 | `verifyPublicationSealedBundle` | function: function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) | { bundleRoot, manifest } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyPublicationSealedBundle } from "@kungfu-tech/buildchain";` | `packages/core/publication-sealed-bundle.js:124` |
-| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain";` | `packages/core/release-candidate-recovery.js:256` |
+| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain";` | `packages/core/release-candidate-recovery.js:273` |
 | `verifyReleasePassport` | function: async function verifyReleasePassport({ passportLocation, artifactEvidenceLocation = "", publishEvidenceLocation = "", impactLocation = "", agentIndexLocation = "", productMechanismLocation = "", kfdAgentHubEvidenceLocation = "", kfdSupportEvidenceLocation = "", checkedAt = nowIso(), } = {}) | { passportLocation, artifactEvidenceLocation = "", publishEvidenceLocation = "", impactLocation = "", agentIndexLocation = "", productMechanismLocation = "", kfdAgentHubEvidenceLocation = "", kfdSupportEvidenceLocation = "", checkedAt = nowIso(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleasePassport } from "@kungfu-tech/buildchain";` | `packages/core/release-passport.js:2743` |
 | `verifyReleasePropagationWork` | function: function verifyReleasePropagationWork(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyReleasePropagationWork } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work.js:486` |
 | `WEB_SURFACE_PRODUCTION_DECISION_CONTRACT` | constant: const WEB_SURFACE_PRODUCTION_DECISION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { WEB_SURFACE_PRODUCTION_DECISION_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/web-surface-publication-candidate.js:7` |
@@ -1062,7 +1062,7 @@ Target: `./packages/core/index.js`. Public symbols: 562.
 | `readReleaseTransaction` | function: function readReleaseTransaction(filePath) | filePath | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { readReleaseTransaction } from "@kungfu-tech/buildchain/core";` | `packages/core/publish-transaction.js:367` |
 | `recordReleaseActivationPhase` | function: function recordReleaseActivationPhase(transaction, phaseId, { receiptRoots = [], failure = "" } = {}) | transaction, phaseId, { receiptRoots = [], failure = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { recordReleaseActivationPhase } from "@kungfu-tech/buildchain/core";` | `packages/core/release-activation-transaction.js:217` |
 | `recordReleasePropagationStage` | function: function recordReleasePropagationStage({ work, expectedWorkRoot, receipt } = {}) | { work, expectedWorkRoot, receipt } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { recordReleasePropagationStage } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-transitions.js:45` |
-| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain/core";` | `packages/core/release-candidate-recovery.js:376` |
+| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain/core";` | `packages/core/release-candidate-recovery.js:396` |
 | `redactBuildchainLogAttributes` | function: function redactBuildchainLogAttributes(attributes = {}) | attributes = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { redactBuildchainLogAttributes } from "@kungfu-tech/buildchain/core";` | `packages/core/logging.js:33` |
 | `redactDiagnosticsValue` | function: function redactDiagnosticsValue(key, value, pattern = DEFAULT_SECRET_KEY_PATTERN) | key, value, pattern = DEFAULT_SECRET_KEY_PATTERN | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { redactDiagnosticsValue } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:953` |
 | `redactIssueText` | function: function redactIssueText(value) | value | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { redactIssueText } from "@kungfu-tech/buildchain/core";` | `packages/core/issue-reporting.js:51` |
@@ -1186,7 +1186,7 @@ Target: `./packages/core/index.js`. Public symbols: 562.
 | `verifyPublicationQualificationReceipt` | function: function verifyPublicationQualificationReceipt({ receipt, capability, gateAggregate, expected = {}, usedNonces = [], now = new Date(), } = {}) | { receipt, capability, gateAggregate, expected = {}, usedNonces = [], now = new Date(), } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyPublicationQualificationReceipt } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-authority.js:1096` |
 | `verifyPublicationReproducibility` | function: function verifyPublicationReproducibility({ cwd = process.cwd(), sourceSha = "", output = DEFAULT_OUTPUT, promote = false, keepWorkspaces = false, pullToolchain = true, packageName = "", allowUnpinnedToolchain = false, overlayPaths = [DEFAULT_REGISTRY_INPUT_DIR, DEFAULT_REGISTRY_HYDRATION], } = {}) | { cwd = process.cwd(), sourceSha = "", output = DEFAULT_OUTPUT, promote = false, keepWorkspaces = false, pullToolchain = true, packageName = "", allowUnpinnedToolchain = false, overlayPaths = [DEFAULT_REGISTRY_INPUT_DIR, DEFAULT_REGISTRY_HYDRATION], } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-reproducibility.js:869` |
 | `verifyPublicationSealedBundle` | function: function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) | { bundleRoot, manifest } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyPublicationSealedBundle } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-sealed-bundle.js:124` |
-| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain/core";` | `packages/core/release-candidate-recovery.js:256` |
+| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain/core";` | `packages/core/release-candidate-recovery.js:273` |
 | `verifyReleasePassport` | function: async function verifyReleasePassport({ passportLocation, artifactEvidenceLocation = "", publishEvidenceLocation = "", impactLocation = "", agentIndexLocation = "", productMechanismLocation = "", kfdAgentHubEvidenceLocation = "", kfdSupportEvidenceLocation = "", checkedAt = nowIso(), } = {}) | { passportLocation, artifactEvidenceLocation = "", publishEvidenceLocation = "", impactLocation = "", agentIndexLocation = "", productMechanismLocation = "", kfdAgentHubEvidenceLocation = "", kfdSupportEvidenceLocation = "", checkedAt = nowIso(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleasePassport } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport.js:2743` |
 | `verifyReleasePropagationWork` | function: function verifyReleasePropagationWork(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyReleasePropagationWork } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work.js:486` |
 | `WEB_SURFACE_PRODUCTION_DECISION_CONTRACT` | constant: const WEB_SURFACE_PRODUCTION_DECISION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { WEB_SURFACE_PRODUCTION_DECISION_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/web-surface-publication-candidate.js:7` |
@@ -1910,10 +1910,10 @@ Target: `./packages/core/release-candidate-recovery.js`. Public symbols: 4.
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:376` |
+| `recoveryFailure` | function: function recoveryFailure(error) | error | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { recoveryFailure } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:396` |
 | `RELEASE_CANDIDATE_RECOVERY_CONTRACT` | constant: const RELEASE_CANDIDATE_RECOVERY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_CANDIDATE_RECOVERY_CONTRACT } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:11` |
 | `ReleaseCandidateRecoveryError` | class: class ReleaseCandidateRecoveryError | none | ReleaseCandidateRecoveryError | Construction and method errors follow the linked source implementation. | class-dependent | `import { ReleaseCandidateRecoveryError } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:18` |
-| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], productPayloadManifests = [], artifacts = [], currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:256` |
+| `verifyReleaseCandidateRecovery` | function: function verifyReleaseCandidateRecovery({ candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {}) | { candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile, expectedWorkflowName, channel, targetRef, targetSha, targetTree, expectedSourceTree = "", expectedCandidateRoot = "", expectedRuntimeSha, expectedTransactionId = "", existingTransaction = undefined, run, workflow, pullRequest, ancestry, passport, buildSummary, controllerReceipts = [], platformManifests = [], platformManifestEvidence = [], productPayloadManifests = [], artifacts = [], publicationVersion = "", currentToolingSha, recoveryRunId = "", createdAt = new Date().toISOString(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyReleaseCandidateRecovery } from "@kungfu-tech/buildchain/release-candidate-recovery";` | `packages/core/release-candidate-recovery.js:273` |
 
 ## `@kungfu-tech/buildchain/stable-candidate-ledger`
 

package/package.json

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

package/packages/core/release-candidate-recovery.js

@@ -93,13 +93,14 @@ function normalizedRef(value) {
   return String(value || "").replace(/^refs\/heads\//, "").trim();
 }
 
-function isBuildchainDiagnosticsEnvelope(file) {
-  return String(file?.path || "").replace(/\\/g, "/").startsWith(".buildchain/");
+function sameArtifactFile(left, right) {
+  return Boolean(left && right && left.size === right.size && left.sha256 === right.sha256);
 }
 
-function validatePlatformPayloads(passport, artifacts, platformManifests) {
+function validatePlatformPayloads(passport, artifacts, platformManifests, platformManifestEvidence) {
   const byName = new Map(artifacts.map((artifact) => [artifact.name, artifact]));
   const manifestsByArtifact = new Map((platformManifests || []).map((manifest) => [manifest.artifactName, manifest]));
+  const evidenceByArtifact = new Map((platformManifestEvidence || []).map((evidence) => [evidence.artifactName, evidence]));
   if (manifestsByArtifact.size !== (passport.platformMatrix || []).length) {
     fail("platform-matrix-mismatch", "platform manifest count differs from the Passport platform matrix", "Restore every exact platform manifest from the candidate run.");
   }
@@ -122,10 +123,26 @@ function validatePlatformPayloads(passport, artifacts, platformManifests) {
       size: Number(file.size ?? file.bytes),
       sha256: `sha256:${String(file.sha256 || "").replace(/^sha256:/, "")}`,
     })).sort((left, right) => left.path.localeCompare(right.path));
-    const productPayloadFiles = payload.files.filter((file) => !isBuildchainDiagnosticsEnvelope(file));
-    const manifestProductFiles = manifestFiles.filter((file) => !isBuildchainDiagnosticsEnvelope(file));
-    if (JSON.stringify(productPayloadFiles) !== JSON.stringify(manifestProductFiles)) {
-      fail("artifact-manifest-mismatch", `platform payload bytes differ from the uploaded platform manifest: ${platform.artifactName}`, "Do not publish; preserve the mismatched manifest and payload evidence.");
+    const platformId = required(platform.platformId, `${platform.artifactName}.platformId`);
+    const buildchainEvidencePrefix = `.buildchain/artifacts/${platformId}/`;
+    const manifestByPath = new Map(manifestFiles.map((file) => [file.path, file]));
+    const evidenceFiles = new Map((evidenceByArtifact.get(platform.artifactName)?.files || []).map((file) => [file.path, file]));
+    const payloadPaths = new Set(payload.files.map((file) => file.path));
+    for (const manifestFile of manifestFiles) {
+      if (!payloadPaths.has(manifestFile.path)) {
+        fail("artifact-manifest-mismatch", `platform payload omits a manifest-declared file: ${platform.artifactName}/${manifestFile.path}`, "Do not publish; preserve the mismatched manifest and payload evidence.");
+      }
+    }
+    for (const payloadFile of payload.files) {
+      const manifestFile = manifestByPath.get(payloadFile.path);
+      if (sameArtifactFile(payloadFile, manifestFile)) continue;
+      const evidencePath = payloadFile.path.startsWith(buildchainEvidencePrefix)
+        ? payloadFile.path.slice(buildchainEvidencePrefix.length)
+        : "";
+      const evidenceFile = evidencePath ? evidenceFiles.get(evidencePath) : undefined;
+      if (!sameArtifactFile(payloadFile, evidenceFile)) {
+        fail("artifact-manifest-mismatch", `platform payload contains unbound bytes or evidence drift: ${platform.artifactName}/${payloadFile.path}`, "Do not publish; preserve the platform payload, manifest, and independently uploaded evidence.");
+      }
     }
     if (passportFiles.length > 0 && JSON.stringify(manifestFiles) !== JSON.stringify(passportFiles)) {
       fail("artifact-manifest-mismatch", `platform manifest differs from Passport inventory: ${platform.artifactName}`, "Do not publish; preserve the mismatched manifest and Passport evidence.");
@@ -236,17 +253,17 @@ function validateCandidateIdentity({
   return { sha, tree, runtimeSha, toolingSha };
 }
 
-function validateRecoveryTransaction({ existingTransaction, expectedTransactionId, repository, passport, sha, targetRef, candidateRoot }) {
+function validateRecoveryTransaction({ existingTransaction, expectedTransactionId, repository, version, passport, sha, targetRef, candidateRoot }) {
   const actualTransactionId = String(existingTransaction?.id || "");
   if (expectedTransactionId && !actualTransactionId) fail("transaction-identity-conflict", `expected transaction ${expectedTransactionId} does not exist`, "Remove the stale transaction identity only if no durable transaction was ever sealed; otherwise preserve evidence and enter repair_required.");
   if (expectedTransactionId && expectedTransactionId !== actualTransactionId) fail("transaction-identity-conflict", `existing transaction ${actualTransactionId} conflicts with expected ${expectedTransactionId}`, "Enter repair_required and inspect the durable transaction before any retry.");
   if (existingTransaction) {
-    const expectedIdentity = releaseTransactionId({ repository, version: passport.target.version, sourceSha: sha, targetRef: normalizedRef(targetRef) });
+    const expectedIdentity = releaseTransactionId({ repository, version, sourceSha: sha, targetRef: normalizedRef(targetRef) });
     assertEqual(existingTransaction.id, expectedIdentity, "transaction-identity-conflict", "durable transaction identity", "Enter repair_required; the durable transaction does not belong to this exact publication target.");
     assertEqual(existingTransaction.repository, repository, "transaction-identity-conflict", "durable transaction repository", "Enter repair_required; never cross repository transaction boundaries.");
     assertEqual(normalizedRef(existingTransaction.target_ref), normalizedRef(targetRef), "transaction-identity-conflict", "durable transaction target ref", "Enter repair_required; never retarget a sealed transaction.");
     assertEqual(existingTransaction.source_sha, sha, "transaction-identity-conflict", "durable transaction source SHA", "Resume with the transaction's exact promotion SHA or enter repair_required.");
-    assertEqual(existingTransaction.version, passport.target.version, "transaction-identity-conflict", "durable transaction version", "Enter repair_required; never change a sealed publication version.");
+    assertEqual(existingTransaction.version, version, "transaction-identity-conflict", "durable transaction version", "Enter repair_required; never change a sealed publication version.");
     assertEqual(existingTransaction.channel, passport.target.channel, "transaction-identity-conflict", "durable transaction channel", "Enter repair_required; never move a transaction between channels.");
   }
   if (existingTransaction?.candidateRoot && existingTransaction.candidateRoot !== candidateRoot) fail("transaction-identity-conflict", "existing transaction is sealed to a different candidate root", "Enter repair_required; never reuse the conflicting transaction.");
@@ -276,8 +293,10 @@ export function verifyReleaseCandidateRecovery({
   buildSummary,
   controllerReceipts = [],
   platformManifests = [],
+  platformManifestEvidence = [],
   productPayloadManifests = [],
   artifacts = [],
+  publicationVersion = "",
   currentToolingSha,
   recoveryRunId = "",
   createdAt = new Date().toISOString(),
@@ -296,7 +315,7 @@ export function verifyReleaseCandidateRecovery({
   if (new Set(recoveredArtifacts.map((artifact) => artifact.name)).size !== recoveredArtifacts.length) {
     fail("artifact-count-mismatch", "candidate artifact names are not unique", "Inspect the candidate run and remove ambiguity by creating a new candidate.");
   }
-  validatePlatformPayloads(passport, recoveredArtifacts, platformManifests);
+  validatePlatformPayloads(passport, recoveredArtifacts, platformManifests, platformManifestEvidence);
 
   const references = new Map((passport.controllerReceipts || []).map((reference) => [reference.controllerId, reference]));
   for (const receipt of controllerReceipts) {
@@ -331,8 +350,9 @@ export function verifyReleaseCandidateRecovery({
     runtimeSha,
   });
 
+  const version = required(publicationVersion || passport.target?.version, "publicationVersion");
   const actualTransactionId = validateRecoveryTransaction({
-    existingTransaction, expectedTransactionId, repository, passport, sha, targetRef, candidateRoot,
+    existingTransaction, expectedTransactionId, repository, version, passport, sha, targetRef, candidateRoot,
   });
 
   const receipt = {
@@ -351,7 +371,7 @@ export function verifyReleaseCandidateRecovery({
       mergeSha: String(pullRequest.mergeSha || ""),
       tree: passport.source.treeHash,
     },
-    target: { channel: passport.target.channel, ref: normalizedRef(targetRef), sha, tree },
+    target: { channel: passport.target.channel, ref: normalizedRef(targetRef), sha, tree, version },
     recovered: {
       candidateRoot,
       buildSummaryRoot: `sha256:${passport.diagnostics.buildSummaryHash}`,

package/scripts/check-inventory.mjs

@@ -992,7 +992,7 @@ for (const requiredSnippet of [
   "resume-buildchain-runtime-sha:",
   "github-release: true",
   "release-passport-buildchain-self-kfd: true",
-  "artifact-patterns: ${{ inputs['resume-candidate-run-id'] != '' && 'buildchain-package-*' || '' }}",
+  'artifact-patterns: "buildchain-package-*"',
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

package/scripts/resume-from-candidate-run.mjs

@@ -148,7 +148,11 @@ function candidateArtifactNames({ passport, selected, artifacts, artifactPattern
     if (!reference.artifact) throw new Error(`Passport controller receipt ${reference.controllerId} has no artifact identity`);
     names.add(reference.artifact);
   }
-  for (const platform of passport.platformMatrix || []) names.add(platform.artifactName);
+  for (const platform of passport.platformMatrix || []) {
+    names.add(platform.artifactName);
+    const diagnosticsArtifactName = `${selected.prefix}-diagnostics-${platform.platformId}-${selected.sourceSha}`;
+    if (artifacts.some((artifact) => artifact.name === diagnosticsArtifactName)) names.add(diagnosticsArtifactName);
+  }
   const manifestPattern = new RegExp(`^${selected.prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-manifest-.+-${selected.sourceSha}$`);
   for (const artifact of artifacts) {
     if (manifestPattern.test(String(artifact.name || ""))) names.add(artifact.name);
@@ -162,18 +166,42 @@ function candidateArtifactNames({ passport, selected, artifacts, artifactPattern
 
 function normalizePlatformManifests(downloads, passport) {
   const manifests = [];
+  const evidenceByArtifact = new Map();
+  function addEvidence(artifactName, files) {
+    if (!artifactName) return;
+    const evidenceFiles = evidenceByArtifact.get(artifactName) || new Map();
+    for (const file of files) {
+      const existing = evidenceFiles.get(file.path);
+      if (existing && (existing.size !== file.size || existing.sha256 !== file.sha256)) {
+        throw new Error(`platform evidence disagrees for ${artifactName}/${file.path}`);
+      }
+      evidenceFiles.set(file.path, file);
+    }
+    evidenceByArtifact.set(artifactName, evidenceFiles);
+  }
   for (const download of downloads) {
-    if (!String(download.artifact.name).includes("-manifest-")) continue;
-    for (const file of download.files.filter((entry) => path.basename(entry.path) === "manifest.json")) {
+    if (String(download.artifact.name).includes("-manifest-")) for (const file of download.files.filter((entry) => path.basename(entry.path) === "manifest.json")) {
       const manifest = JSON.parse(fs.readFileSync(file.absolutePath, "utf8"));
       if (!manifest.artifactName) {
         const platformId = String(manifest.platform?.id || manifest.platformId || "");
         manifest.artifactName = (passport.platformMatrix || []).find((entry) => entry.platformId === platformId)?.artifactName || "";
       }
       manifests.push(manifest);
+      addEvidence(manifest.artifactName, download.record.files);
+    }
+    if (String(download.artifact.name).includes("-diagnostics-")) {
+      const diagnosticsFiles = download.files.filter((entry) => path.basename(entry.path) === "diagnostics.json");
+      if (diagnosticsFiles.length === 1) {
+        const diagnostics = JSON.parse(fs.readFileSync(diagnosticsFiles[0].absolutePath, "utf8"));
+        addEvidence(String(diagnostics.links?.artifactName || ""), download.record.files);
+      }
     }
   }
-  return manifests;
+  const evidence = [...evidenceByArtifact].map(([artifactName, files]) => ({
+    artifactName,
+    files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
+  }));
+  return { manifests, evidence };
 }
 
 function normalizeControllerReceipts(downloads, passport) {
@@ -258,9 +286,6 @@ async function recoverCandidateEvidence({
   for (const artifact of [selected.passport, selected.summary]) initialDownloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   const passport = readOnlyJson(initialDownloads[0].files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "release-candidate-passport.json");
   const buildSummary = readOnlyJson(initialDownloads[1].files.filter((file) => path.basename(file.path) === "build-summary.json"), "build-summary.json");
-  const candidateVersion = String(passport.target?.version || "").trim();
-  if (!candidateVersion) throw new Error("Release Candidate Passport has no exact target version");
-  const existingTransaction = await readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version: candidateVersion });
   const requiredNames = candidateArtifactNames({ passport, selected, artifacts, artifactPatterns });
   const chosen = artifacts.filter((artifact) => requiredNames.has(artifact.name));
   if (chosen.length !== requiredNames.size) {
@@ -272,7 +297,7 @@ async function recoverCandidateEvidence({
   for (const artifact of chosen.filter((entry) => ![selected.passport.id, selected.summary.id].includes(entry.id))) downloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   return {
     run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-    passport, buildSummary, candidateVersion, existingTransaction, chosen, downloads,
+    passport, buildSummary, chosen, downloads,
   };
 }
 
@@ -311,7 +336,7 @@ export async function resumeFromCandidateRun({
   try {
     const {
       run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-      passport, buildSummary, candidateVersion, existingTransaction, chosen, downloads,
+      passport, buildSummary, chosen, downloads,
     } = await recoverCandidateEvidence({
       repoInfo, runId, artifactName, artifactPatterns, requiredArtifactCount,
       outputDir, apiUrl, token, fetchImpl, archiveDir,
@@ -323,9 +348,20 @@ export async function resumeFromCandidateRun({
     const targetRefState = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/ref/heads/${targetRef.replace(/^refs\/heads\//, "")}` });
     if (targetRefState.object?.sha !== targetSha) throw new Error(`target ref ${targetRef} no longer points at ${targetSha}`);
     const compare = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${pullRequest.merge_commit_sha}...${targetSha}` });
-    const platformManifests = normalizePlatformManifests(downloads, passport);
+    const platformManifestEvidence = normalizePlatformManifests(downloads, passport);
     const controllerReceipts = normalizeControllerReceipts(downloads, passport);
     const productPayloadManifests = normalizeProductPayloadManifests(downloads);
+    const sealed = createSealedBundle({
+      downloads,
+      bundleRoot,
+      repository: repoInfo.fullName,
+      passport,
+      runtimeSha,
+      publishPackageMain,
+      releasePatterns,
+    });
+    const candidateVersion = sealed.manifest.npm.version;
+    const existingTransaction = await readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version: candidateVersion });
     const recovery = verifyReleaseCandidateRecovery({
       candidateRepository: repoInfo.fullName,
       targetRepository,
@@ -369,21 +405,14 @@ export async function resumeFromCandidateRun({
       passport,
       buildSummary,
       controllerReceipts,
-      platformManifests,
+      platformManifests: platformManifestEvidence.manifests,
+      platformManifestEvidence: platformManifestEvidence.evidence,
       productPayloadManifests,
       artifacts: downloads.map((download) => download.record),
+      publicationVersion: candidateVersion,
       currentToolingSha: runtimeSha,
       recoveryRunId,
     });
-    const sealed = createSealedBundle({
-      downloads,
-      bundleRoot,
-      repository: repoInfo.fullName,
-      passport,
-      runtimeSha,
-      publishPackageMain,
-      releasePatterns,
-    });
     const recoveryReceiptPath = path.join(resolvedOutput, "recovery-receipt.json");
     const sealedManifestPath = path.join(resolvedOutput, "sealed-bundle.json");
     const requiredArtifactsPath = path.join(resolvedOutput, "publish-required-artifacts.json");