@kungfu-tech/buildchain 2.14.2 → 2.14.3-alpha.0

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.14.2",
+    "version": "2.14.3-alpha.0",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -50,7 +50,7 @@
         "retryable GitHub fallback fetches use a bounded attempt budget before exact source SHA and tree verification"
       ],
       "breakingDigest": "sha256:a6a35370d6b0d0f46e1b2712dcc01961fe53c2febde95409a27a485c10a36650",
-      "auditDigest": "sha256:07f01d270d7f5712be067697f652b5843a07748696c0d2b8b2020639108c669d"
+      "auditDigest": "sha256:46fa80913e6174f34b96c323ed913410b9fea0f3632a0ce9c7d4f3e0b23b7072"
     },
     {
       "contractVersion": 1,
@@ -159,7 +159,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:6dbae32ce3d7aab3be6957065105af574794581847b7637314dad45f5349c919",
-      "auditDigest": "sha256:0a5691beb2469a71e22b0b7ecd3d32af539fa14dd6af6e14bf47d692a1788070"
+      "auditDigest": "sha256:1f65ef71c7cbafdcd7628a7d41929d153fa3bf9fcbc167d514a358dd49518e98"
     },
     {
       "contractVersion": 1,
@@ -527,7 +527,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:e0fd0a6e19835663980faec6d4d132424d9ee65c27fcd3437bf30634740032bb"
+      "auditDigest": "sha256:14f679ffb745bf4f9edc9fabaef962c0de61aaa054d111fe691d5734714e6a8e"
     },
     {
       "contractVersion": 1,
@@ -549,7 +549,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:dca785dc9f657536f84a9b40c3fb00d5a191bbd6cbce2fb1cb59cd0369150817"
+      "auditDigest": "sha256:03d6f62196eb47edcfc8b4b68abefc0a10912b276d407e75e83be443a112ba16"
     },
     {
       "contractVersion": 1,
@@ -600,7 +600,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:373723a73d188194d389dee04c394d3b79cb0c016a370f2f5d0f60979a02ed48",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "buildchain-ref": {
             "classification": "included",
@@ -747,7 +747,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:367be236280f2597ffefc49680feb106b4cf9e8f5fb9420713351f075a168c4a",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN": {
             "classification": "redacted",
@@ -1006,7 +1006,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
-      "auditDigest": "sha256:07f01d270d7f5712be067697f652b5843a07748696c0d2b8b2020639108c669d"
+      "auditDigest": "sha256:46fa80913e6174f34b96c323ed913410b9fea0f3632a0ce9c7d4f3e0b23b7072"
     },
     {
       "contractVersion": 1,
@@ -1113,7 +1113,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:2e113607af3cb0a17b4da64b8758652a4bee4a162656ce7256a8e06de3d4cf2f",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN": {
             "classification": "redacted",
@@ -1443,7 +1443,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:29569f4b754595792a16742d1c4c63838b54601674a2cb6c96261a72c962dece",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -1614,7 +1614,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:7e6283c8fbeab7a680bae57c9ab9c8eb94aab7400d3ee01c5b9dfdd03f149edb",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "artifact-path": {
             "classification": "digest-only",
@@ -1850,7 +1850,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:6b132790b9798e8a5dfbe095701d8e024c160a08bc7c4bd477ee79feef7a9cfd",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -2031,7 +2031,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:0613ea545fe2d630f34e665c8e6fe99df3f5333d75051a7176e9cf991e494f59",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -2305,7 +2305,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:2507d132710f66d3ae6ffdb18f5e66172707b8e0f9ad9e888f7422fdacc99133",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "BUILDCHAIN_ISSUE_APP_ID": {
             "classification": "redacted",
@@ -2580,7 +2580,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:46238f8fc3c20924decc57ecad142a462fc4739c6bc21409d5cd2457fc1c3cdd",
-      "auditDigest": "sha256:0a5691beb2469a71e22b0b7ecd3d32af539fa14dd6af6e14bf47d692a1788070"
+      "auditDigest": "sha256:1f65ef71c7cbafdcd7628a7d41929d153fa3bf9fcbc167d514a358dd49518e98"
     },
     {
       "contractVersion": 1,
@@ -2624,21 +2624,24 @@
         "buildchain-repository",
         "downstream-base-ref",
         "downstream-branch",
+        "downstream-prepare-command",
         "downstream-repository",
         "downstream-target",
+        "downstream-verify-command",
         "dry-run",
         "graph-json",
         "lock-path",
         "pr-body",
         "pr-title",
         "propagation-token",
+        "refresh-managed-readme-badges",
         "source-node",
         "upstream-release-json"
       ],
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
-        "digest": "sha256:9b9f9a2320c4349903d72ee46e329211b5538ed5ebebaa93559df4eafb835997",
-        "registryDigest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b",
+        "digest": "sha256:ede9eba43b87cf19330d5f8203a1585bf066aa9affc9cac0f43230ac76b8580d",
+        "registryDigest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd",
         "inputClassifications": {
           "buildchain-ref": {
             "classification": "included",
@@ -2656,6 +2659,10 @@
             "classification": "included",
             "source": "workflow-call-input"
           },
+          "downstream-prepare-command": {
+            "classification": "digest-only",
+            "source": "workflow-call-input"
+          },
           "downstream-repository": {
             "classification": "included",
             "source": "workflow-call-input"
@@ -2664,6 +2671,10 @@
             "classification": "included",
             "source": "workflow-call-input"
           },
+          "downstream-verify-command": {
+            "classification": "digest-only",
+            "source": "workflow-call-input"
+          },
           "dry-run": {
             "classification": "included",
             "source": "workflow-call-input"
@@ -2688,6 +2699,10 @@
             "classification": "redacted",
             "source": "workflow-call-secret"
           },
+          "refresh-managed-readme-badges": {
+            "classification": "included",
+            "source": "workflow-call-input"
+          },
           "source-node": {
             "classification": "included",
             "source": "workflow-call-input"
@@ -2705,9 +2720,9 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:d7a1f15990ce8bd13149474888232c7d4451dd2a49bebf4d4ce1336695da430e",
-      "auditDigest": "sha256:2750630ae675352b601dd6cb6a987df14bf11029fcf02aa54638b4fcdcb7590e"
+      "auditDigest": "sha256:43fd4da155c701d4c5078373c1f47b50bebc6a46556b8db5e3c4d502c113fa95"
     }
   ],
   "compatibilityDigest": "sha256:af162b86ab4506e9b5f1d3c59b41f3fd57fbad79ff4d749a7f12ff16460517f8",
-  "contractDigest": "sha256:90466f4b69982ad1aba65d22596baa4cd0112454f44b1f7c33ab3de017029a06"
+  "contractDigest": "sha256:394a6bfc690c07ee0adc8da9c357b09ad6710a5358015b767f2990dfbdf06573"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-18T01:00:00.995Z",
-  "publishedAt": "2026-07-18T01:00:00.995Z",
+  "generatedAt": "2026-07-18T22:57:23.219Z",
+  "publishedAt": "2026-07-18T22:57:23.219Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "ae16e640bf2f21c8f981ffa8b3523c8aae9200b2",
+  "sourceRevision": "8b0423396f09f29e2ea05c38896228751767ab21",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.2",
+    "version": "2.14.3-alpha.0",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -1490,7 +1490,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-passport.md",
-      "digest": "sha256:2421e3e9f2dd892971bea5deb605492dfec38f3a83e539229442b55380bebe25",
+      "digest": "sha256:0029014ffab7d7228a12d8b92326b78cf6757a41f481b661c5997e2cef06d3cc",
       "headings": [
         {
           "level": 1,
@@ -1538,7 +1538,7 @@
           "anchor": "binary-distribution"
         }
       ],
-      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\nRelease-candidate and final passports may also include compact\n`controllerReceipts[]` references. These bind a real reusable-workflow receipt\nto its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they\ndo not infer execution evidence from a green job. See\n[`controller-evidence.md`](controller-evidence.md).\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: public release tag, internal transaction tag, line, channel,\n  source SHA, target ref, release SHA, release material SHA, publish tooling\n  SHA, and durable release-state ref. Anchored/manual package releases use the\n  published package version for the public tag while preserving the internal\n  exact transaction tag for Buildchain recovery.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `buildFacts`: module/product build facts that bind Git source digests,\n  version sources, lifecycle invocations, platforms, outputs, product\n  artifacts, and verification results to the release.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest. Registry artifacts retain\n  optional built/reused action, content and current-release coordinates,\n  platform/contract/parent metadata, and fail-closed verification evidence.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/product.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport. `buildFacts[]`\nrecords first-class module/product build facts, while\n`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,\nids, and digests for quick audit traversal. See\n[`build-facts.md`](build-facts.md) for the fact collection and verification\ncontract.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nBuildchain also performs a reverse audit before that witness is used. The\ngenerated `dist/site/public-surface-audit.json` enumerates real CLI commands\nfrom `bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself KFD witnesses include that audit result and classify the collaboration\ninterface as closed-world only when the reverse audit passes. If a public\ncommand, workflow input, action input, or site page is exposed without a\nregistry entry, `pnpm run check` fails before release promotion can produce a\npassport.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`.buildchain/contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nFor npm subjects, Buildchain treats the registry as the package digest source:\n`npm:<name>@<version>` resolves `dist.integrity` and matches it against\n`packageSet.main.digest`, `packageSet.platforms[].digest`, and publish evidence.\nUse `--npm-registry <url>` when the package comes from a non-default registry.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
+      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\nRelease-candidate and final passports may also include compact\n`controllerReceipts[]` references. These bind a real reusable-workflow receipt\nto its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they\ndo not infer execution evidence from a green job. See\n[`controller-evidence.md`](controller-evidence.md).\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nIndependent verifiers can pin two package-owned, standalone files without\nscraping this implementation:\n\n- `dist/site/schemas/release-passport-v1.schema.json` is the self-contained\n  JSON Schema for the Buildchain-owned envelope;\n- `dist/site/release-passport-check-manifest.json` names the normative checker,\n  required and conditional sibling evidence, local-resolution rules,\n  Buildchain aggregation fields, canonical KFD subsection schema authorities,\n  and forward-compatibility policy.\n\nThe same files are exported as\n`@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json` and\n`@kungfu-tech/buildchain/site/release-passport-check-manifest.json`. The schema\nchecks the envelope shape. `buildchain verify release-passport` remains the\nnormative semantic checker: it resolves sibling evidence relative to the\npassport and fails closed on missing evidence, digest drift, or inconsistent\nrelease facts. Buildchain owns envelope aggregation; KFD retains schema and\ncompatibility authority for the `kfd-1`, `kfd-2`, and `kfd-3` subsections.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: public release tag, internal transaction tag, line, channel,\n  source SHA, target ref, release SHA, release material SHA, publish tooling\n  SHA, and durable release-state ref. Anchored/manual package releases use the\n  published package version for the public tag while preserving the internal\n  exact transaction tag for Buildchain recovery.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `buildFacts`: module/product build facts that bind Git source digests,\n  version sources, lifecycle invocations, platforms, outputs, product\n  artifacts, and verification results to the release.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest. Registry artifacts retain\n  optional built/reused action, content and current-release coordinates,\n  platform/contract/parent metadata, and fail-closed verification evidence.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/product.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport. `buildFacts[]`\nrecords first-class module/product build facts, while\n`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,\nids, and digests for quick audit traversal. See\n[`build-facts.md`](build-facts.md) for the fact collection and verification\ncontract.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nBuildchain also performs a reverse audit before that witness is used. The\ngenerated `dist/site/public-surface-audit.json` enumerates real CLI commands\nfrom `bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself KFD witnesses include that audit result and classify the collaboration\ninterface as closed-world only when the reverse audit passes. If a public\ncommand, workflow input, action input, or site page is exposed without a\nregistry entry, `pnpm run check` fails before release promotion can produce a\npassport.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`.buildchain/contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nFor npm subjects, Buildchain treats the registry as the package digest source:\n`npm:<name>@<version>` resolves `dist.integrity` and matches it against\n`packageSet.main.digest`, `packageSet.platforms[].digest`, and publish evidence.\nUse `--npm-registry <url>` when the package comes from a non-default registry.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
     },
     {
       "id": "manual:release-propagation",
@@ -1552,7 +1552,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/release-propagation.md",
-      "digest": "sha256:d5877075eb41a3d41e531549da113756d29d6f34c91e3b68b8ce650753d5ca1d",
+      "digest": "sha256:fc2b743e3d76c4f90cdd8c6560cf9d619ad25d74c15c074be96db7bcb6cc2a29",
       "headings": [
         {
           "level": 1,
@@ -1585,7 +1585,7 @@
           "anchor": "kfd-to-site-libkungfu-dev"
         }
       ],
-      "markdown": "# Release Propagation\n\nRelease propagation lets a finalized upstream release open a downstream update\nPR using the upstream release passport as the audit source. It is for product\nchains such as:\n\n```text\nkfd -> site-libkungfu-dev\nA -> B -> C\n```\n\nThe downstream repository receives an exact lock, not a floating dist-tag. A\nsite or app can then consume the upstream package, site bundle, or release\npassport as its single source of truth without hand-copying release facts.\n\n## Contract\n\nThe propagation graph is declarative JSON:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-release-propagation-graph\",\n  \"nodes\": [\n    {\n      \"id\": \"kfd\",\n      \"repository\": \"kungfu-systems/kfd\",\n      \"package\": \"@kungfu-tech/kfd\"\n    },\n    {\n      \"id\": \"site-libkungfu-dev\",\n      \"repository\": \"kungfu-systems/site-libkungfu-dev\",\n      \"lockPath\": \"buildchain.upstreams/kfd.release.json\",\n      \"baseRef\": \"dev/v2/v2.7\"\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"kfd-to-site\",\n      \"from\": \"kfd\",\n      \"to\": \"site-libkungfu-dev\",\n      \"channelPolicy\": \"preserve\"\n    }\n  ]\n}\n```\n\n`channelPolicy: \"preserve\"` is the default and maps:\n\n```text\nalpha   -> alpha\nrelease -> release\n```\n\nCross-channel mapping is allowed only when an edge declares\n`channelPolicy: \"explicit\"` and a `channelMap`. Buildchain rejects cycles so a\nchain can fan out or continue as `A -> B -> C`, but cannot loop back into an\nalready visited release line.\n\n## Upstream Release Envelope\n\nThe upstream release envelope is the post-finalization fact set:\n\n```json\n{\n  \"repository\": \"kungfu-systems/kfd\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v1.4.0-alpha.3\",\n  \"sourceSha\": \"1111111111111111111111111111111111111111\",\n  \"package\": {\n    \"name\": \"@kungfu-tech/kfd\",\n    \"version\": \"1.4.0-alpha.3\",\n    \"integrity\": \"sha512-...\"\n  },\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json\",\n    \"sha256\": \"2222222222222222222222222222222222222222222222222222222222222222\"\n  },\n  \"siteBundle\": {\n    \"manifestSha256\": \"3333333333333333333333333333333333333333333333333333333333333333\"\n  }\n}\n```\n\nThe package version and integrity must be exact. Downstream build logic should\ninstall that version directly, not resolve `alpha` or `latest` again.\n\nPublication repositories can propagate immutable publication archive evidence\nwithout npm package facts. The upstream envelope then includes\n`publicationArtifact`:\n\n```json\n{\n  \"repository\": \"kungfu-systems/paper-observer-declared-timelines\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v0.1.0-alpha.1\",\n  \"sourceSha\": \"4444444444444444444444444444444444444444\",\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json\",\n    \"sha256\": \"5555555555555555555555555555555555555555555555555555555555555555\"\n  },\n  \"publicationArtifact\": {\n    \"id\": \"observer-declared-timelines\",\n    \"kind\": \"paper\",\n    \"version\": \"0.1.0-alpha.1\",\n    \"canonicalUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/\",\n    \"latestUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\",\n    \"latestEvidenceUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\",\n    \"immutableVersionUrl\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/\",\n    \"registry\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-registry.json\",\n      \"sha256\": \"6666666666666666666666666666666666666666666666666666666666666666\"\n    },\n    \"manifest\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact.json\",\n      \"sha256\": \"7777777777777777777777777777777777777777777777777777777777777777\"\n    },\n    \"passport\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact-passport.json\",\n      \"sha256\": \"8888888888888888888888888888888888888888888888888888888888888888\"\n    },\n    \"primaryArtifact\": {\n      \"path\": \"_build/main.pdf\",\n      \"url\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/main.pdf\",\n      \"sha256\": \"9999999999999999999999999999999999999999999999999999999999999999\"\n    }\n  }\n}\n```\n\nThis lets a site repository render the latest reader page and historical\nversion index from release facts while keeping old PDFs, source bundles,\nmanifests, and passports immutable.\n\n## CLI\n\nGenerate a propagation plan:\n\n```bash\nbuildchain release-propagation plan \\\n  --graph buildchain.release-propagation.json \\\n  --upstream-release .buildchain/upstream-release.json \\\n  --output .buildchain/release-propagation-plan.json \\\n  --json\n```\n\nWrite the downstream lock:\n\n```bash\nbuildchain release-propagation write-lock \\\n  --plan .buildchain/release-propagation-plan.json \\\n  --target site-libkungfu-dev \\\n  --cwd downstream-checkout \\\n  --json\n```\n\nThe written lock has contract\n`kungfu-buildchain-release-propagation-lock` and records:\n\n- upstream repository, channel, exact tag, source SHA;\n- optional npm package name, exact version, and sha512 integrity;\n- optional publication artifact canonical/latest/immutable URLs, registry,\n  manifest, passport, source bundle, and primary artifact digests;\n- release passport URL and SHA-256;\n- optional site bundle manifest SHA-256;\n- downstream repository, channel, base ref, lock path;\n- edge id and channel policy.\n\n## Reusable Workflow\n\nUpstream repositories can call\n`.github/workflows/release-propagation.yml@v2` after release finalization:\n\n```yaml\njobs:\n  propagate-site:\n    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v2\n    with:\n      buildchain-ref: v2\n      graph-json: ${{ needs.release.outputs.propagation-graph-json }}\n      upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}\n      downstream-target: site-libkungfu-dev\n      downstream-repository: kungfu-systems/site-libkungfu-dev\n      downstream-base-ref: dev/v2/v2.7\n      dry-run: false\n    secrets:\n      propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n```\n\nThe downstream branch name may be reused across upstream releases. Before\nreplacing an existing managed branch, the workflow reads its exact remote SHA\nand pushes with an explicit `--force-with-lease=<ref>:<sha>`. A surviving branch\nfrom a merged PR is therefore reconciled without manual deletion, while a\nconcurrent writer makes the lease fail closed. The controller receipt includes a\n`propagation-branch-reconciliation` evidence file recording the branch, observed\nremote SHA, pushed SHA, lease mode, and the deterministically created or updated\nopen PR.\n\nThe workflow checks out the Buildchain runtime selected by\n`buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes\nthat runtime for the propagation plan and lock write, then checks out the\ndownstream repository, writes the exact lock, and opens or updates a PR. It does\nnot publish the downstream release directly. The downstream repository keeps its\nnormal Buildchain governance: the PR updates source-of-truth facts, then\ndownstream alpha or release publication runs through its own protected channel.\nThe workflow stages the declared lock path before checking the index, so the\nfirst propagation creates a PR even when the lock did not previously exist; a\nbyte-identical rerun is an explicit successful no-op.\nFor unreleased runtime validation, keep the caller's reusable workflow reference\non `@v2` and pass a temporary train ref through `buildchain-ref`.\n\n## kfd to site-libkungfu-dev\n\nFor `kfd -> site-libkungfu-dev`, the graph should preserve channels:\n\n- a `kfd` alpha release produces a downstream alpha lock and downstream alpha\n  publication consumes the exact `@kungfu-tech/kfd@...-alpha.N` package;\n- a `kfd` stable release produces a downstream release lock and downstream\n  stable publication consumes the exact stable package.\n\nThis keeps the site synchronized to the package truth without allowing the site\nto drift onto a floating npm dist-tag."
+      "markdown": "# Release Propagation\n\nRelease propagation lets a finalized upstream release open a downstream update\nPR using the upstream release passport as the audit source. It is for product\nchains such as:\n\n```text\nkfd -> site-libkungfu-dev\nA -> B -> C\n```\n\nThe downstream repository receives an exact lock, not a floating dist-tag. A\nsite or app can then consume the upstream package, site bundle, or release\npassport as its single source of truth without hand-copying release facts.\n\n## Contract\n\nThe propagation graph is declarative JSON:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-release-propagation-graph\",\n  \"nodes\": [\n    {\n      \"id\": \"kfd\",\n      \"repository\": \"kungfu-systems/kfd\",\n      \"package\": \"@kungfu-tech/kfd\"\n    },\n    {\n      \"id\": \"site-libkungfu-dev\",\n      \"repository\": \"kungfu-systems/site-libkungfu-dev\",\n      \"lockPath\": \"buildchain.upstreams/kfd.release.json\",\n      \"baseRef\": \"dev/v2/v2.7\"\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"kfd-to-site\",\n      \"from\": \"kfd\",\n      \"to\": \"site-libkungfu-dev\",\n      \"channelPolicy\": \"preserve\"\n    }\n  ]\n}\n```\n\n`channelPolicy: \"preserve\"` is the default and maps:\n\n```text\nalpha   -> alpha\nrelease -> release\n```\n\nCross-channel mapping is allowed only when an edge declares\n`channelPolicy: \"explicit\"` and a `channelMap`. Buildchain rejects cycles so a\nchain can fan out or continue as `A -> B -> C`, but cannot loop back into an\nalready visited release line.\n\n## Upstream Release Envelope\n\nThe upstream release envelope is the post-finalization fact set:\n\n```json\n{\n  \"repository\": \"kungfu-systems/kfd\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v1.4.0-alpha.3\",\n  \"sourceSha\": \"1111111111111111111111111111111111111111\",\n  \"package\": {\n    \"name\": \"@kungfu-tech/kfd\",\n    \"version\": \"1.4.0-alpha.3\",\n    \"integrity\": \"sha512-...\"\n  },\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json\",\n    \"sha256\": \"2222222222222222222222222222222222222222222222222222222222222222\"\n  },\n  \"siteBundle\": {\n    \"manifestSha256\": \"3333333333333333333333333333333333333333333333333333333333333333\"\n  }\n}\n```\n\nThe package version and integrity must be exact. Downstream build logic should\ninstall that version directly, not resolve `alpha` or `latest` again.\n\nPublication repositories can propagate immutable publication archive evidence\nwithout npm package facts. The upstream envelope then includes\n`publicationArtifact`:\n\n```json\n{\n  \"repository\": \"kungfu-systems/paper-observer-declared-timelines\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v0.1.0-alpha.1\",\n  \"sourceSha\": \"4444444444444444444444444444444444444444\",\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json\",\n    \"sha256\": \"5555555555555555555555555555555555555555555555555555555555555555\"\n  },\n  \"publicationArtifact\": {\n    \"id\": \"observer-declared-timelines\",\n    \"kind\": \"paper\",\n    \"version\": \"0.1.0-alpha.1\",\n    \"canonicalUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/\",\n    \"latestUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\",\n    \"latestEvidenceUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\",\n    \"immutableVersionUrl\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/\",\n    \"registry\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-registry.json\",\n      \"sha256\": \"6666666666666666666666666666666666666666666666666666666666666666\"\n    },\n    \"manifest\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact.json\",\n      \"sha256\": \"7777777777777777777777777777777777777777777777777777777777777777\"\n    },\n    \"passport\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact-passport.json\",\n      \"sha256\": \"8888888888888888888888888888888888888888888888888888888888888888\"\n    },\n    \"primaryArtifact\": {\n      \"path\": \"_build/main.pdf\",\n      \"url\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/main.pdf\",\n      \"sha256\": \"9999999999999999999999999999999999999999999999999999999999999999\"\n    }\n  }\n}\n```\n\nThis lets a site repository render the latest reader page and historical\nversion index from release facts while keeping old PDFs, source bundles,\nmanifests, and passports immutable.\n\n## CLI\n\nGenerate a propagation plan:\n\n```bash\nbuildchain release-propagation plan \\\n  --graph buildchain.release-propagation.json \\\n  --upstream-release .buildchain/upstream-release.json \\\n  --output .buildchain/release-propagation-plan.json \\\n  --json\n```\n\nWrite the downstream lock:\n\n```bash\nbuildchain release-propagation write-lock \\\n  --plan .buildchain/release-propagation-plan.json \\\n  --target site-libkungfu-dev \\\n  --cwd downstream-checkout \\\n  --json\n```\n\nThe written lock has contract\n`kungfu-buildchain-release-propagation-lock` and records:\n\n- upstream repository, channel, exact tag, source SHA;\n- optional npm package name, exact version, and sha512 integrity;\n- optional publication artifact canonical/latest/immutable URLs, registry,\n  manifest, passport, source bundle, and primary artifact digests;\n- release passport URL and SHA-256;\n- optional site bundle manifest SHA-256;\n- downstream repository, channel, base ref, lock path;\n- edge id and channel policy.\n\n## Reusable Workflow\n\nUpstream repositories can call\n`.github/workflows/release-propagation.yml@v2` after release finalization:\n\n```yaml\njobs:\n  propagate-site:\n    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v2\n    with:\n      buildchain-ref: v2\n      graph-json: ${{ needs.release.outputs.propagation-graph-json }}\n      upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}\n      downstream-target: site-libkungfu-dev\n      downstream-repository: kungfu-systems/site-libkungfu-dev\n      downstream-base-ref: dev/v2/v2.7\n      downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts\n      downstream-verify-command: pnpm run check\n      dry-run: false\n    secrets:\n      propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n```\n\nThe downstream branch name may be reused across upstream releases. Before\nreplacing an existing managed branch, the workflow reads its exact remote SHA\nand pushes with an explicit `--force-with-lease=<ref>:<sha>`. A surviving branch\nfrom a merged PR is therefore reconciled without manual deletion, while a\nconcurrent writer makes the lease fail closed. The controller receipt includes a\n`propagation-branch-reconciliation` evidence file recording the branch, observed\nremote SHA, pushed SHA, lease mode, and the deterministically created or updated\nopen PR.\n\nThe workflow checks out the Buildchain runtime selected by\n`buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes\nthat runtime for the propagation plan and lock write, then checks out the\ndownstream repository and writes the exact lock. A consumer that must pin the\nexact upstream package or regenerate deterministic files declares\n`downstream-prepare-command`. The command receives\n`BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and\n`BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an\nexisting `<!-- buildchain:badges:start -->` README block by default. Consumers\ncan disable that step with `refresh-managed-readme-badges: false`.\n\n`downstream-verify-command` runs against the final tree before any commit or\npush, so consumers can use the same check as their PR workflow. Preparation,\nbadge refresh, and verification failures all fail closed. The workflow stages\nthe complete deterministic result, signs the propagation commit with DCO, and\nthen opens or updates the PR. It does not publish the downstream release\ndirectly. The downstream repository keeps its normal Buildchain governance: the\nPR updates source-of-truth facts, then downstream alpha or release publication\nruns through its own protected channel. A byte-identical rerun is an explicit\nsuccessful no-op.\nFor unreleased runtime validation, keep the caller's reusable workflow reference\non `@v2` and pass a temporary train ref through `buildchain-ref`.\n\n## kfd to site-libkungfu-dev\n\nFor `kfd -> site-libkungfu-dev`, the graph should preserve channels:\n\n- a `kfd` alpha release produces a downstream alpha lock and downstream alpha\n  publication consumes the exact `@kungfu-tech/kfd@...-alpha.N` package;\n- a `kfd` stable release produces a downstream release lock and downstream\n  stable publication consumes the exact stable package.\n\nThis keeps the site synchronized to the package truth without allowing the site\nto drift onto a floating npm dist-tag."
     },
     {
       "id": "manual:reusable-build-surface",
@@ -2504,7 +2504,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:2421e3e9f2dd892971bea5deb605492dfec38f3a83e539229442b55380bebe25"
+      "digest": "sha256:0029014ffab7d7228a12d8b92326b78cf6757a41f481b661c5997e2cef06d3cc"
     },
     {
       "id": "controller-evidence",
@@ -2536,7 +2536,7 @@
       "path": "docs/release-propagation.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:d5877075eb41a3d41e531549da113756d29d6f34c91e3b68b8ce650753d5ca1d"
+      "digest": "sha256:fc2b743e3d76c4f90cdd8c6560cf9d619ad25d74c15c074be96db7bcb6cc2a29"
     },
     {
       "id": "readme-badges",
@@ -2724,7 +2724,9 @@
     "releasePassport": {
       "entrypoint": "buildchain.release.json",
       "bundle": "buildchain-release-bundle.tar.gz",
-      "contract": "kungfu-buildchain-release-passport"
+      "contract": "kungfu-buildchain-release-passport",
+      "schema": "schemas/release-passport-v1.schema.json",
+      "checkManifest": "release-passport-check-manifest.json"
     },
     "releasePropagation": {
       "graphContract": "kungfu-buildchain-release-propagation-graph",

package/dist/site/capability-registry.json

@@ -50,7 +50,7 @@
         "manualCount": 4,
         "pageCount": 4,
         "cliCommandCount": 21,
-        "nodeApiCount": 6,
+        "nodeApiCount": 7,
         "workflowCount": 2,
         "actionCount": 1
       },

package/dist/site/controller-registry.json

@@ -1683,6 +1683,10 @@
           "classification": "included",
           "source": "workflow-call-input"
         },
+        "downstream-prepare-command": {
+          "classification": "digest-only",
+          "source": "workflow-call-input"
+        },
         "downstream-repository": {
           "classification": "included",
           "source": "workflow-call-input"
@@ -1691,6 +1695,10 @@
           "classification": "included",
           "source": "workflow-call-input"
         },
+        "downstream-verify-command": {
+          "classification": "digest-only",
+          "source": "workflow-call-input"
+        },
         "dry-run": {
           "classification": "included",
           "source": "workflow-call-input"
@@ -1715,6 +1723,10 @@
           "classification": "redacted",
           "source": "workflow-call-secret"
         },
+        "refresh-managed-readme-badges": {
+          "classification": "included",
+          "source": "workflow-call-input"
+        },
         "source-node": {
           "classification": "included",
           "source": "workflow-call-input"
@@ -1758,8 +1770,8 @@
           "controller-receipt"
         ]
       },
-      "digest": "sha256:9b9f9a2320c4349903d72ee46e329211b5538ed5ebebaa93559df4eafb835997"
+      "digest": "sha256:ede9eba43b87cf19330d5f8203a1585bf066aa9affc9cac0f43230ac76b8580d"
     }
   ],
-  "digest": "sha256:266928038838e26ba1350c70d78290723ddb2fd209b66ab1afab776d948a379b"
+  "digest": "sha256:2c6a3a4dce27e0d76baae1c9aeb4d3428866fe8b4c4022a8c582b054dace02fd"
 }

package/dist/site/kfd-claims.json

@@ -21,13 +21,13 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "3d9e43510266b900fe450253fbb8aac72953c7128a797154150eb301ef71ed6a",
+    "sha256": "056a3d5e87f0813bbddb47cf4f3c8db43458b23bcf9fbe4b3d0ca8b80c38bbdc",
     "summary": {
       "cliCommandCount": 83,
       "workflowCount": 48,
       "actionCount": 4,
       "sitePageCount": 50,
-      "docCommandRefCount": 257,
+      "docCommandRefCount": 258,
       "failureCount": 0
     },
     "auditBoundary": {
@@ -225,13 +225,13 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "3d9e43510266b900fe450253fbb8aac72953c7128a797154150eb301ef71ed6a",
+      "sha256": "056a3d5e87f0813bbddb47cf4f3c8db43458b23bcf9fbe4b3d0ca8b80c38bbdc",
       "summary": {
         "cliCommandCount": 83,
         "workflowCount": 48,
         "actionCount": 4,
         "sitePageCount": 50,
-        "docCommandRefCount": 257,
+        "docCommandRefCount": 258,
         "failureCount": 0
       },
       "auditBoundary": {
@@ -1303,6 +1303,18 @@
           "public": true,
           "packageExport": "./release-passport"
         },
+        {
+          "id": "export:./release-passport-contract",
+          "name": "@kungfu-tech/buildchain/release-passport-contract",
+          "kind": "package-export",
+          "sourcePath": "packages/core/release-passport-contract.js",
+          "evidencePath": "packages/core/release-passport-contract.js",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "packageExport": "./release-passport-contract"
+        },
         {
           "id": "export:./release-propagation",
           "name": "@kungfu-tech/buildchain/release-propagation",
@@ -3707,19 +3719,22 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 13,
+          "inputCount": 16,
           "inputs": [
             "buildchain-ref",
             "buildchain-repository",
             "downstream-base-ref",
             "downstream-branch",
+            "downstream-prepare-command",
             "downstream-repository",
             "downstream-target",
+            "downstream-verify-command",
             "dry-run",
             "graph-json",
             "lock-path",
             "pr-body",
             "pr-title",
+            "refresh-managed-readme-badges",
             "source-node",
             "upstream-release-json"
           ],
@@ -4702,6 +4717,6 @@
         }
       }
     ],
-    "publicSurfaceCount": 304
+    "publicSurfaceCount": 305
   }
 }