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

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.3",
+    "version": "2.12.7-alpha.5",
     "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:18b1cdc05272152120fdb52eb98be1d146702664ca8eba29ae92591ae55d5d2a"
+      "auditDigest": "sha256:4dc810c734e3b597297932839d3919219b93c69a985fc1b8ecc91a08299b940e"
     },
     {
       "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:197c71556a66a7435fc08d4e90d24c494dea43d00a57f3f6afb91ab7c13e62ff"
+      "auditDigest": "sha256:10c3132362feab7e8e3f612eedc2e62b9b90ff0ed2fcf8445ce75caef55c26d5"
     },
     {
       "contractVersion": 1,
@@ -269,7 +269,7 @@
         "semver GitHub Releases are created or updated only after transaction completion, with prerelease/latest metadata derived from the public release tag"
       ],
       "breakingDigest": "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874",
-      "auditDigest": "sha256:61edd187a303c33eeef28ccca138e46d7494645b16e6df72719b6d632b0d8e80"
+      "auditDigest": "sha256:0a6b261a43f59477497d99f840e83b11a2cfa6545a3d89c9952f47d7ebed33dc"
     },
     {
       "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:1b444a6dd4d4ea1b7f55ab74e6e53b4e042c9a872d6dee247acf63f7bbab9f23"
+      "auditDigest": "sha256:653df5708fa73f074129b3bf1e047f7f204f42e4521e2b0d7521618f01f9f345"
     },
     {
       "contractVersion": 1,
@@ -549,7 +549,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:cd51cdc232d3c96ebfc9176ff99dc6ddaae1c93822d7f50be055973355b20dc4"
+      "auditDigest": "sha256:69ff5a1b9407cae5c97cd8328bd1937a19ce8ac3c25e6262717a27164592eb9e"
     },
     {
       "contractVersion": 1,
@@ -1001,7 +1001,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
-      "auditDigest": "sha256:18b1cdc05272152120fdb52eb98be1d146702664ca8eba29ae92591ae55d5d2a"
+      "auditDigest": "sha256:4dc810c734e3b597297932839d3919219b93c69a985fc1b8ecc91a08299b940e"
     },
     {
       "contractVersion": 1,
@@ -1520,7 +1520,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:5f1868478b7ccd9fb79aea76bc771289d2ca6bd2dccd1abf57575426f1eae5fb",
-      "auditDigest": "sha256:2b8db410486b9f572536be9fc68b8819c373ba31bdf8a7379c2770ce5168eb6c"
+      "auditDigest": "sha256:f478f291726cd47d998c37d454d9fc3e97f1d4a45dc60fe756d8c239fa1245bd"
     },
     {
       "contractVersion": 1,
@@ -2155,7 +2155,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:0eb318df455ef9cb737a7c2515a2411b685d34ed0bde7b5f5b173a7a42513114",
-      "auditDigest": "sha256:4dfb8623c947f6b8ab339a11e31de132401997c6bb5ea0cfe70e45e3b4aa9429"
+      "auditDigest": "sha256:f5f11c5c5d27884e0b93ce99b7dc5d2e58d956a004a0001707a21f0939f3226e"
     },
     {
       "contractVersion": 1,
@@ -2525,7 +2525,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:46238f8fc3c20924decc57ecad142a462fc4739c6bc21409d5cd2457fc1c3cdd",
-      "auditDigest": "sha256:197c71556a66a7435fc08d4e90d24c494dea43d00a57f3f6afb91ab7c13e62ff"
+      "auditDigest": "sha256:10c3132362feab7e8e3f612eedc2e62b9b90ff0ed2fcf8445ce75caef55c26d5"
     },
     {
       "contractVersion": 1,
@@ -2654,5 +2654,5 @@
     }
   ],
   "compatibilityDigest": "sha256:af162b86ab4506e9b5f1d3c59b41f3fd57fbad79ff4d749a7f12ff16460517f8",
-  "contractDigest": "sha256:3abf1d4b7f940f16739b375c8286aa4e293fa81708d774d6554fb6b4f1309e59"
+  "contractDigest": "sha256:9d102ee81f219a5ec4d6dc421e22e3b2b857e706a2ccfbe367636acf59ec9c9f"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-14T16:58:46.295Z",
-  "publishedAt": "2026-07-14T16:58:46.295Z",
+  "generatedAt": "2026-07-14T23:35:00.122Z",
+  "publishedAt": "2026-07-14T23:35:00.122Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a80e367748620f3c1cb16a08d81c854131ed6d89",
+  "sourceRevision": "0729934d3442d37667544dd469c43e14ea1cd2f2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.3",
+    "version": "2.12.7-alpha.5",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -1031,7 +1031,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:b299d74aa98276a4f5b7ca498d1bd56ef72efa621f565aa236b434b2e4a07715",
+      "digest": "sha256:24429efd2c39cfcbf3ed2c0f7265cadc44b28fa3e1dab1f115f2b8a7a3d7c028",
       "headings": [
         {
           "level": 1,
@@ -1064,7 +1064,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2\n    permissions:\n      checks: write\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      publication-admission-json: ${{ needs.authority.outputs.admission-json }}\n      publication-runner-provenance-json: ${{ needs.authority.outputs.runner-provenance-json }}\n      publication-control-plane-audit-json: ${{ needs.authority.outputs.control-plane-audit-json }}\n      publication-expected-json: ${{ needs.authority.outputs.expected-json }}\n      toolchain-type: config\n      verify-command: make check\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe publication job does not accept a long-lived promotion token. The caller\nmust first produce a fresh sealed admission, runner provenance, external\ncontrol-plane audit, and exact expected bindings. The credential-free verifier\njob checks those receipts; only then can the publication job use its short-lived\n`github.token` and caller-bound OIDC trusted publisher identity. npm binds that\nidentity to the consumer workflow filename; an npm Environment restriction is\noptional and must be represented explicitly when configured. The workflow fails\nbefore the publication build when the target branch protection cannot be read.\n\nThe preset:\n\n- resolves the same floating Buildchain runtime and contract lock as the build\n  workflow;\n- verifies that the declared promotion authority can read the protected target\n  channel before starting the publication build;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- publishes the package through npm Trusted Publishing;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2\n    permissions:\n      checks: write\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      publication-admission-json: ${{ needs.authority.outputs.admission-json }}\n      publication-runner-provenance-json: ${{ needs.authority.outputs.runner-provenance-json }}\n      publication-control-plane-audit-json: ${{ needs.authority.outputs.control-plane-audit-json }}\n      publication-expected-json: ${{ needs.authority.outputs.expected-json }}\n      toolchain-type: config\n      verify-command: make check\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe publication job does not accept a long-lived promotion token. The caller\nmust first produce a fresh sealed admission, runner provenance, external\ncontrol-plane audit, and exact expected bindings. The credential-free verifier\njob checks those receipts; only then can the publication job use its short-lived\n`github.token` and caller-bound OIDC trusted publisher identity. npm binds that\nidentity to the consumer workflow filename; an npm Environment restriction is\noptional and must be represented explicitly when configured. The workflow fails\nbefore the publication build when the target branch protection cannot be read.\n\nThe preset:\n\n- resolves the same floating Buildchain runtime and contract lock as the build\n  workflow;\n- verifies that the declared promotion authority can read the protected target\n  channel before starting the publication build;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- publishes the package through npm Trusted Publishing;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n  every file declared by `publication.primary_artifact` and\n  `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publication-authority",
@@ -1078,7 +1078,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/publication-authority.md",
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71",
+      "digest": "sha256:06ba05f9d8a2685a0896334b6013a97c45b7d71163cf6898e5a6274baf7f0296",
       "headings": [
         {
           "level": 1,
@@ -1111,7 +1111,7 @@
           "anchor": "publication-lanes"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-14\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-14\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nBuildchain's own `workflow_run` promotion lane may assemble those inputs only\nfor `kungfu-systems/buildchain`. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and creates an explicit Buildchain-owned no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. The self-assembly mode rejects other\nrepositories, unknown refs, non-exact source SHAs, and any caller other than\n`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external\nconsumer workflows still require their own explicit admission inputs.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v2/v2.12 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-15\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-15\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nBuildchain's own `workflow_run` promotion lane may assemble those inputs only\nfor `kungfu-systems/buildchain`. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and creates an explicit Buildchain-owned no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. The self-assembly mode rejects other\nrepositories, unknown refs, non-exact source SHAs, and any caller other than\n`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external\nconsumer workflows still require their own explicit admission inputs.\n\nBefore authority verification, the reusable promotion controller runs the same\nrelease transaction selector in read-only mode. That plan supplies one exact\npublication version and tag to the admission verifier, the publish-gate source\nlock, and the real promotion action. The verifier rejects a capability for a\ndifferent version, and the promotion action rechecks the planned version before\nany publish transaction side effect. Release-candidate fixture versions are\nartifact evidence only; they never name Buildchain's own source-lock or\npublication capability.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v2/v2.12 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
     },
     {
       "id": "manual:publish-transaction",
@@ -1711,7 +1711,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/shifu-gate-profiles.md",
-      "digest": "sha256:01550c79827ef6905ff5d9f6db3308139b63f40378c212df892cde09b6e0bbd7",
+      "digest": "sha256:919c163a414df5ed562148e4da9e0e3a94718488e7477eb120073e2ee35b5288",
       "headings": [
         {
           "level": 1,
@@ -1749,7 +1749,7 @@
           "anchor": "validation-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nBefore invoking the project-owned command, the workflow adds the runner\naccount's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This\nkeeps user-scoped tools such as `uv` available to strict Shifu cache profiles\nwithout assuming an administrator-managed system installation. The consumer or\nrunner owner remains responsible for provisioning the declared tools.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
     },
     {
       "id": "manual:site-bundle-contract",
@@ -2474,7 +2474,7 @@
       "path": "docs/publication-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71"
+      "digest": "sha256:06ba05f9d8a2685a0896334b6013a97c45b7d71163cf6898e5a6274baf7f0296"
     },
     {
       "id": "release-candidate",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "e348bc83923857ba1a3a850370b5023fbde79ba49edff09bca8f8ba61e9fd638",
+    "sha256": "7bafa611c991c1b808267f22e6708bed2cf00b655ebd6bee60c50dd27fcefa37",
     "summary": {
       "cliCommandCount": 79,
       "workflowCount": 46,
@@ -225,7 +225,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "e348bc83923857ba1a3a850370b5023fbde79ba49edff09bca8f8ba61e9fd638",
+      "sha256": "7bafa611c991c1b808267f22e6708bed2cf00b655ebd6bee60c50dd27fcefa37",
       "summary": {
         "cliCommandCount": 79,
         "workflowCount": 46,
@@ -2642,7 +2642,7 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 22,
+          "inputCount": 23,
           "inputs": [
             "admission-json",
             "auto-admission",
@@ -2661,6 +2661,7 @@
             "package-name",
             "product",
             "publication-target",
+            "publication-version",
             "publisher-workflow-path",
             "runner-provenance-json",
             "source-sha",
@@ -3671,16 +3672,18 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 52,
+          "inputCount": 54,
           "inputs": [
             "allow-repository",
             "branch-protection-bypass-apps",
             "branch-protection-bypass-teams",
             "branch-protection-bypass-users",
             "dry-run",
+            "expected-publication-version",
             "generated-ref-update-token",
             "generated-status-check-token",
             "github-release",
+            "github-release-artifact-paths",
             "github-release-notes",
             "github-release-title",
             "promote-only-release-candidate",

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.3",
+    "version": "2.12.7-alpha.5",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/manual-registry.json

@@ -65,7 +65,7 @@
       "title": "Sealed publication authority",
       "path": "docs/publication-authority.md",
       "plane": "verify",
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71",
+      "digest": "sha256:06ba05f9d8a2685a0896334b6013a97c45b7d71163cf6898e5a6274baf7f0296",
       "capabilityGroup": "release-passport-trust",
       "audience": [
         "release-operator",

package/dist/site/node-api-registry.json

@@ -86,7 +86,7 @@
       "specifier": "@kungfu-tech/buildchain/controller-evidence",
       "export": "./controller-evidence",
       "target": "./packages/core/controller-evidence.js",
-      "digest": "sha256:477c219ae49b3829dc6c607226b487e82cb6a9db277699e78af463d84002a268",
+      "digest": "sha256:3c9cf557ee0e2e4376335bb7d0e61b6e8c9a1d8699962dd8a1e7adc529e13f89",
       "summary": "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs.",
       "capabilityGroup": "reusable-build",
       "audience": [

package/dist/site/page-registry.json

@@ -965,7 +965,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:b299d74aa98276a4f5b7ca498d1bd56ef72efa621f565aa236b434b2e4a07715",
+      "digest": "sha256:24429efd2c39cfcbf3ed2c0f7265cadc44b28fa3e1dab1f115f2b8a7a3d7c028",
       "headings": [
         {
           "level": 1,
@@ -998,7 +998,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2\n    permissions:\n      checks: write\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      publication-admission-json: ${{ needs.authority.outputs.admission-json }}\n      publication-runner-provenance-json: ${{ needs.authority.outputs.runner-provenance-json }}\n      publication-control-plane-audit-json: ${{ needs.authority.outputs.control-plane-audit-json }}\n      publication-expected-json: ${{ needs.authority.outputs.expected-json }}\n      toolchain-type: config\n      verify-command: make check\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe publication job does not accept a long-lived promotion token. The caller\nmust first produce a fresh sealed admission, runner provenance, external\ncontrol-plane audit, and exact expected bindings. The credential-free verifier\njob checks those receipts; only then can the publication job use its short-lived\n`github.token` and caller-bound OIDC trusted publisher identity. npm binds that\nidentity to the consumer workflow filename; an npm Environment restriction is\noptional and must be represented explicitly when configured. The workflow fails\nbefore the publication build when the target branch protection cannot be read.\n\nThe preset:\n\n- resolves the same floating Buildchain runtime and contract lock as the build\n  workflow;\n- verifies that the declared promotion authority can read the protected target\n  channel before starting the publication build;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- publishes the package through npm Trusted Publishing;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2\n    permissions:\n      checks: write\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      publication-admission-json: ${{ needs.authority.outputs.admission-json }}\n      publication-runner-provenance-json: ${{ needs.authority.outputs.runner-provenance-json }}\n      publication-control-plane-audit-json: ${{ needs.authority.outputs.control-plane-audit-json }}\n      publication-expected-json: ${{ needs.authority.outputs.expected-json }}\n      toolchain-type: config\n      verify-command: make check\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe publication job does not accept a long-lived promotion token. The caller\nmust first produce a fresh sealed admission, runner provenance, external\ncontrol-plane audit, and exact expected bindings. The credential-free verifier\njob checks those receipts; only then can the publication job use its short-lived\n`github.token` and caller-bound OIDC trusted publisher identity. npm binds that\nidentity to the consumer workflow filename; an npm Environment restriction is\noptional and must be represented explicitly when configured. The workflow fails\nbefore the publication build when the target branch protection cannot be read.\n\nThe preset:\n\n- resolves the same floating Buildchain runtime and contract lock as the build\n  workflow;\n- verifies that the declared promotion authority can read the protected target\n  channel before starting the publication build;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- publishes the package through npm Trusted Publishing;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n  every file declared by `publication.primary_artifact` and\n  `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publication-authority",
@@ -1012,7 +1012,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/publication-authority.md",
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71",
+      "digest": "sha256:06ba05f9d8a2685a0896334b6013a97c45b7d71163cf6898e5a6274baf7f0296",
       "headings": [
         {
           "level": 1,
@@ -1045,7 +1045,7 @@
           "anchor": "publication-lanes"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-14\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-14\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nBuildchain's own `workflow_run` promotion lane may assemble those inputs only\nfor `kungfu-systems/buildchain`. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and creates an explicit Buildchain-owned no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. The self-assembly mode rejects other\nrepositories, unknown refs, non-exact source SHAs, and any caller other than\n`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external\nconsumer workflows still require their own explicit admission inputs.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v2/v2.12 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-15\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-15\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nBuildchain's own `workflow_run` promotion lane may assemble those inputs only\nfor `kungfu-systems/buildchain`. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and creates an explicit Buildchain-owned no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. The self-assembly mode rejects other\nrepositories, unknown refs, non-exact source SHAs, and any caller other than\n`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external\nconsumer workflows still require their own explicit admission inputs.\n\nBefore authority verification, the reusable promotion controller runs the same\nrelease transaction selector in read-only mode. That plan supplies one exact\npublication version and tag to the admission verifier, the publish-gate source\nlock, and the real promotion action. The verifier rejects a capability for a\ndifferent version, and the promotion action rechecks the planned version before\nany publish transaction side effect. Release-candidate fixture versions are\nartifact evidence only; they never name Buildchain's own source-lock or\npublication capability.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v2/v2.12 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
     },
     {
       "id": "manual:publish-transaction",
@@ -1645,7 +1645,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/shifu-gate-profiles.md",
-      "digest": "sha256:01550c79827ef6905ff5d9f6db3308139b63f40378c212df892cde09b6e0bbd7",
+      "digest": "sha256:919c163a414df5ed562148e4da9e0e3a94718488e7477eb120073e2ee35b5288",
       "headings": [
         {
           "level": 1,
@@ -1683,7 +1683,7 @@
           "anchor": "validation-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nBefore invoking the project-owned command, the workflow adds the runner\naccount's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This\nkeeps user-scoped tools such as `uv` available to strict Shifu cache profiles\nwithout assuming an administrator-managed system installation. The consumer or\nrunner owner remains responsible for provisioning the declared tools.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
     },
     {
       "id": "manual:site-bundle-contract",

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

@@ -625,13 +625,14 @@
           "package-name",
           "product",
           "publication-target",
+          "publication-version",
           "publisher-workflow-path",
           "runner-provenance-json",
           "source-sha",
           "target-ref",
           "used-nonces-json"
         ],
-        "inputCount": 22,
+        "inputCount": 23,
         "secrets": [],
         "secretCount": 0,
         "outputs": [
@@ -1754,9 +1755,11 @@
           "branch-protection-bypass-teams",
           "branch-protection-bypass-users",
           "dry-run",
+          "expected-publication-version",
           "generated-ref-update-token",
           "generated-status-check-token",
           "github-release",
+          "github-release-artifact-paths",
           "github-release-notes",
           "github-release-title",
           "promote-only-release-candidate",
@@ -1802,7 +1805,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 52
+        "inputCount": 54
       },
       {
         "id": "report-buildchain-issue",
@@ -3328,8 +3331,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "a6daf4822365bf576425777230246046ebca67b3f8dcfea61fc7a61773776185",
-    "workflowRegistryDigest": "0a42ae651ae4e0121393641c792aa99d357cb582752278728bdffb92269314bd",
-    "pageRegistryDigest": "69cad87fc8b656d7876aa6e9861b5d0d4d02ba681e21bccb266c66290f1e17e3"
+    "workflowRegistryDigest": "2b36c3c532082a835a2054ce565b4b5ca39ef1c09b8188a080d5dc4a5909218b",
+    "pageRegistryDigest": "dc526c6f9aefa92aa566a9664374eb4f177f4b3ae5b9480eb94abbbf3a257a30"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-14T16:58:46.295Z",
-  "publishedAt": "2026-07-14T16:58:46.295Z",
+  "generatedAt": "2026-07-14T23:35:00.122Z",
+  "publishedAt": "2026-07-14T23:35:00.122Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a80e367748620f3c1cb16a08d81c854131ed6d89",
+  "sourceRevision": "0729934d3442d37667544dd469c43e14ea1cd2f2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.3",
+    "version": "2.12.7-alpha.5",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-14T16:58:46.295Z",
-  "publishedAt": "2026-07-14T16:58:46.295Z",
+  "generatedAt": "2026-07-14T23:35:00.122Z",
+  "publishedAt": "2026-07-14T23:35:00.122Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a80e367748620f3c1cb16a08d81c854131ed6d89",
+  "sourceRevision": "0729934d3442d37667544dd469c43e14ea1cd2f2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.3",
+    "version": "2.12.7-alpha.5",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -85,7 +85,7 @@
       "path": "docs/publication-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71"
+      "digest": "sha256:06ba05f9d8a2685a0896334b6013a97c45b7d71163cf6898e5a6274baf7f0296"
     },
     {
       "id": "release-candidate",

package/dist/site/workflow-registry.json

@@ -231,13 +231,14 @@
         "package-name",
         "product",
         "publication-target",
+        "publication-version",
         "publisher-workflow-path",
         "runner-provenance-json",
         "source-sha",
         "target-ref",
         "used-nonces-json"
       ],
-      "inputCount": 22,
+      "inputCount": 23,
       "secrets": [],
       "secretCount": 0,
       "outputs": [
@@ -1487,9 +1488,11 @@
         "branch-protection-bypass-teams",
         "branch-protection-bypass-users",
         "dry-run",
+        "expected-publication-version",
         "generated-ref-update-token",
         "generated-status-check-token",
         "github-release",
+        "github-release-artifact-paths",
         "github-release-notes",
         "github-release-title",
         "promote-only-release-candidate",
@@ -1535,7 +1538,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 52,
+      "inputCount": 54,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/publication-artifacts.md

@@ -228,12 +228,19 @@ The preset:
   before any publish side effect;
 - publishes the package through npm Trusted Publishing;
 - writes Buildchain release/passport evidence; and
-- creates or updates the exact-version GitHub Release by default.
+- creates or updates the exact-version GitHub Release by default, uploading
+  every file declared by `publication.primary_artifact` and
+  `publication.artifact_paths` alongside the release evidence.
 
 Consumers can opt out of the GitHub Release with `github-release: false`, but
 the default is on so downstream release propagation can observe
 `release.published` without hand-written `gh release` steps.
 
+Declared publication artifacts are resolved from the generated publication
+manifest rather than repeated in consumer workflow YAML. Publication fails
+before upload if a declared artifact is missing or if its basename would
+collide with another GitHub Release asset.
+
 For npm Trusted Publishing, register the consumer workflow file that calls this
 preset, for example `.github/workflows/paper-release.yml`, against the declared
 package in npm. The trusted publisher is the consumer repository and workflow

package/docs/publication-authority.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-14
+last_reviewed: 2026-07-15
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-14
+  generated_at: 2026-07-15
   limits: Live provider configuration must be re-audited; no credential values are represented.
 ---
 
@@ -121,6 +121,15 @@ repositories, unknown refs, non-exact source SHAs, and any caller other than
 `.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external
 consumer workflows still require their own explicit admission inputs.
 
+Before authority verification, the reusable promotion controller runs the same
+release transaction selector in read-only mode. That plan supplies one exact
+publication version and tag to the admission verifier, the publish-gate source
+lock, and the real promotion action. The verifier rejects a capability for a
+different version, and the promotion action rechecks the planned version before
+any publish transaction side effect. Release-candidate fixture versions are
+artifact evidence only; they never name Buildchain's own source-lock or
+publication capability.
+
 Evidence publication is a separate authority class and never grants product
 publication.
 

package/docs/shifu-gate-profiles.md

@@ -78,6 +78,12 @@ Every matrix job checks out the exact source SHA planned by Buildchain, invokes
 then invokes `shifu gate receipt validate`. Buildchain uploads the original
 receipt and validation result even when the run fails.
 
+Before invoking the project-owned command, the workflow adds the runner
+account's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This
+keeps user-scoped tools such as `uv` available to strict Shifu cache profiles
+without assuming an administrator-managed system installation. The consumer or
+runner owner remains responsible for provisioning the declared tools.
+
 The fixed `Gate profile / aggregate` job fails closed for missing receipts,
 invalid or stale Shifu validation, dirty or mismatched source SHA, registry or
 plan drift, missing required results, required failures/skips, or gate action

package/package.json

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

package/packages/core/controller-evidence.js

@@ -303,7 +303,7 @@ function normalizeEvidence(entries = []) {
 function receiptStatus(plan, stages) {
   if (stages.some((stage) => stage.status === "failed")) return "failed";
   if (stages.length > 0 && stages.every((stage) => stage.status === "skipped")) return "skipped";
-  if (stages.some((stage) => stage.status === "cancelled" || stage.status === "missing")) return "partial";
+  if (stages.some((stage) => stage.status === "cancelled" || (stage.required && stage.status === "missing"))) return "partial";
   const required = new Set(plan.expected.stages.filter((stage) => stage.required).map((stage) => stage.id));
   if (stages.filter((stage) => required.has(stage.id)).every((stage) => stage.status === "passed")) return "passed";
   return "partial";

package/scripts/assemble-self-publication-admission.mjs

@@ -137,6 +137,7 @@ async function main() {
     isolation: "github-hosted-single-job",
   });
   const packageJson = JSON.parse(fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8"));
+  const publicationVersion = required("BUILDCHAIN_PUBLICATION_VERSION");
   const issuedAt = new Date();
   const admission = createPublicationAdmission({
     registryDigest: registry.registryDigest,
@@ -154,7 +155,7 @@ async function main() {
     environment: process.env.BUILDCHAIN_PUBLICATION_ENVIRONMENT || "none",
     product: process.env.BUILDCHAIN_PUBLICATION_PRODUCT || "Buildchain",
     target: process.env.BUILDCHAIN_PUBLICATION_TARGET || `npm:${packageJson.name}`,
-    version: process.env.BUILDCHAIN_PUBLICATION_VERSION || packageJson.version,
+    version: publicationVersion,
     channel: required("BUILDCHAIN_PUBLICATION_CHANNEL"),
     artifactDigest: artifactSet.manifestSetDigest,
     nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}`,

package/scripts/check-inventory.mjs

@@ -840,6 +840,9 @@ for (const requiredSnippet of [
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
   "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
+  "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
+  "publication-version: ${{ needs.publication-plan.outputs.version }}",
+  "name: Plan exact publication version",
   "DRY_RUN: ${{ inputs.dry-run }}",
   "if (dryRun) {",
   "Enforce Buildchain stable release canary gate",

package/scripts/workflow-friction-report.mjs

@@ -202,6 +202,8 @@ export async function classifyWorkflowFriction({
   buildWorkflowName = DEFAULT_BUILD_WORKFLOW_NAME,
   releaseCandidateOutcome = env("BUILDCHAIN_RC_RESOLVE_OUTCOME"),
   releaseCandidateDiagnosis = env("BUILDCHAIN_RC_DIAGNOSIS"),
+  promotionOutcome = env("BUILDCHAIN_PROMOTION_OUTCOME"),
+  promotionDiagnosis = env("BUILDCHAIN_PROMOTION_DIAGNOSIS"),
   runUrl = env("BUILDCHAIN_WORKFLOW_RUN_URL"),
   outputDir = ".buildchain/workflow-friction",
   fetchImpl = globalThis.fetch,
@@ -256,14 +258,23 @@ export async function classifyWorkflowFriction({
   if (releaseCandidateOutcome === "failure") {
     diagnosisParts.push("Promotion reached the post-Verify workflow before required PR-stage RC evidence could be resolved.");
   }
-  if (releaseCandidateDiagnosis) {
+  if (releaseCandidateOutcome === "failure" && releaseCandidateDiagnosis) {
     diagnosisParts.push(releaseCandidateDiagnosis);
   }
+  if (promotionOutcome === "failure") {
+    diagnosisParts.push(
+      promotionDiagnosis
+        ? `Promotion failed: ${promotionDiagnosis}`
+        : "Promotion failed after PR-stage release-candidate evidence resolved successfully.",
+    );
+  }
   diagnosisParts.push(...workflowRunDiagnostics);
   const diagnosis = diagnosisParts.join(" ") || "Buildchain ref promotion failed after Verify succeeded; inspect the classified evidence and keep the fix in Buildchain.";
   const nextAction = frictionClass === "late-fail-fast"
     ? "Move the missing/stale RC evidence check earlier or make the promotion workflow consume the exact PR-stage RC passport before any publish side effect."
-    : "Deduplicate the PR/build path or tighten Buildchain workflow gates so the next channel promotion reaches publish exactly once.";
+    : ["duplicate-channel-pr", "duplicate-heavy-build"].includes(frictionClass)
+      ? "Deduplicate the PR/build path or tighten Buildchain workflow gates so the next channel promotion reaches publish exactly once."
+      : "Fix the concrete promotion failure above, then rerun through the protected channel workflow; do not treat successful RC resolution as the failure diagnosis.";
   fs.mkdirSync(outputDir, { recursive: true });
   const bodyFile = path.join(outputDir, "issue-body.md");
   const body = buildWorkflowFrictionBody({