@kungfu-tech/buildchain 3.0.2-alpha.4 → 3.0.2-alpha.6

package/dist/site/workflow-registry.json

@@ -111,6 +111,9 @@
         "expected-artifacts-json",
         "fail-fast",
         "gate-profile-aggregate-json",
+        "github-artifact-attestation-platform-id",
+        "github-artifact-attestation-signer-sha",
+        "github-artifact-attestation-subject-path",
         "install-command",
         "kfd-agent-hub",
         "lifecycle-timeout-minutes",
@@ -144,7 +147,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 69,
+      "inputCount": 72,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -355,6 +358,9 @@
         "buildchain-repository",
         "channel",
         "dry-run",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-retention-days",
         "github-governance-receipt-json",
         "github-release",
         "github-release-notes",
@@ -428,7 +434,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 85,
+      "inputCount": 88,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -451,6 +457,10 @@
         "controller-receipt-digest",
         "controller-receipt-json",
         "controller-receipt-status",
+        "github-artifact-attestation-evidence-root",
+        "github-artifact-attestation-id",
+        "github-artifact-attestation-publication-receipt-digest",
+        "github-artifact-attestation-url",
         "promoted-sha",
         "publication-capability-digest",
         "publication-commit-evidence-digest",
@@ -459,7 +469,7 @@
         "publication-commit-url",
         "release-candidate-artifact"
       ],
-      "outputCount": 15,
+      "outputCount": 19,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
@@ -935,6 +945,9 @@
         "expected-artifacts-json",
         "fail-fast",
         "gate-profile-aggregate-json",
+        "github-artifact-attestation-platform-id",
+        "github-artifact-attestation-signer-sha",
+        "github-artifact-attestation-subject-path",
         "install-command",
         "kfd-agent-hub",
         "lifecycle-timeout-minutes",
@@ -968,7 +981,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 72,
+      "inputCount": 75,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1225,22 +1238,27 @@
         "dev-workflow-path",
         "dry-run",
         "max-age-seconds",
+        "settlement-authorized",
         "source-branch",
         "target-branch"
       ],
-      "inputCount": 9,
+      "inputCount": 10,
       "secrets": [
         "promotion-token"
       ],
       "secretCount": 1,
       "outputs": [
+        "active-candidate-pr",
+        "controller-state",
         "eligible",
+        "next-candidate-sha",
         "promotion-pr",
         "result-path",
         "selected-sha",
+        "settlement-action",
         "source-lock-ref"
       ],
-      "outputCount": 5,
+      "outputCount": 9,
       "surface": "repository-patrol",
       "capabilityGroup": "governance-versioning",
       "status": "active"
@@ -1296,6 +1314,40 @@
       "capabilityGroup": "governance-versioning",
       "status": "active"
     },
+    {
+      "id": "github-artifact-attestation",
+      "path": ".github/workflows/github-artifact-attestation.yml",
+      "reusable": true,
+      "inputs": [
+        "buildchain-ref",
+        "environment",
+        "evidence-artifact-name",
+        "evidence-run-id",
+        "platform-manifest-artifact-name",
+        "platform-manifest-relative-path",
+        "policy-json",
+        "release-passport-artifact-name",
+        "release-passport-relative-path",
+        "retention-days",
+        "source-sha",
+        "subject-artifact-name",
+        "subject-relative-path"
+      ],
+      "inputCount": 13,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [
+        "attestation-id",
+        "attestation-url",
+        "bundle-digest",
+        "evidence-artifact-name",
+        "evidence-root"
+      ],
+      "outputCount": 5,
+      "surface": "release-passport",
+      "capabilityGroup": "release-passport-trust",
+      "status": "active"
+    },
     {
       "id": "github-governance-audit",
       "path": ".github/workflows/github-governance-audit.yml",
@@ -1632,6 +1684,9 @@
         "buildchain-stable-contract-lock-path",
         "channel",
         "dry-run",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-retention-days",
         "github-governance-receipt-json",
         "github-release",
         "github-release-notes",
@@ -1694,7 +1749,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 77,
+      "inputCount": 80,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1718,6 +1773,10 @@
         "controller-receipt-digest",
         "controller-receipt-json",
         "controller-receipt-status",
+        "github-artifact-attestation-evidence-root",
+        "github-artifact-attestation-id",
+        "github-artifact-attestation-publication-receipt-digest",
+        "github-artifact-attestation-url",
         "promoted-sha",
         "promotion-contract-lock-digest",
         "promotion-contract-lock-path",
@@ -1737,7 +1796,7 @@
         "publication-commit-url",
         "release-candidate-artifact"
       ],
-      "outputCount": 27,
+      "outputCount": 31,
       "surface": "release-governance",
       "capabilityGroup": "reusable-build",
       "status": "active"
@@ -1932,6 +1991,28 @@
   ],
   "actionSource": "actions/*/action.yml reverse input enumeration",
   "actions": [
+    {
+      "id": "github-artifact-attestation",
+      "path": "actions/github-artifact-attestation/action.yml",
+      "inputs": [
+        "attestation-id",
+        "attestation-url",
+        "bundle-path",
+        "expected-buildchain-ref",
+        "expected-caller-repository",
+        "expected-source-sha",
+        "mode",
+        "output-dir",
+        "platform-manifest-path",
+        "policy-json",
+        "preparation-json",
+        "release-passport-path",
+        "subject-path"
+      ],
+      "inputCount": 13,
+      "capabilityGroup": "release-passport-trust",
+      "status": "active"
+    },
     {
       "id": "macos-credential-island",
       "path": "actions/macos-credential-island/action.yml",
@@ -2006,6 +2087,7 @@
         "release-passport",
         "release-passport-build-summary-path",
         "release-passport-buildchain-self-kfd",
+        "release-passport-github-artifact-attestation-policy-jsons",
         "release-passport-impact-json",
         "release-passport-invariant-passport-command",
         "release-passport-invariant-passport-jsons",
@@ -2032,7 +2114,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 66,
+      "inputCount": 67,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/MAP.md

@@ -27,7 +27,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability group | Primary facts | Primary manuals |
 | --- | --- | --- |
 | Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
-| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
+| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
 | Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
@@ -42,6 +42,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
 | Product invariant Passport release gate | `buildchain.release.json#invariantPassports`, `dist/site/buildchain-contract.json` | [`release-passport.md`](release-passport.md) |
+| GitHub keyless Linux artifact attestation | `buildchain.release.json#githubArtifactAttestations`, `dist/site/workflow-registry.json`, `dist/site/artifact-schemas.json` | [`github-artifact-attestation.md`](github-artifact-attestation.md) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
 | KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Declarative KFD Agent Hub adapter conformance and Passport evidence | `.buildchain/kfd/agent-hub.json`, `.buildchain/artifacts/kfd-agent-hub/evidence.json`, `buildchain.release.json#kfdAgentHub` | [`kfd-agent-hub.md`](kfd-agent-hub.md) |
@@ -85,6 +86,7 @@ replace them.
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I keylessly attest Linux release artifacts with GitHub and bind them to a Release Passport? | [`github-artifact-attestation.md`](github-artifact-attestation.md) | verify/use | preview |
 | How do I seal exact artifact, identity, lifecycle, and KFD assessment roots for KFX admission? | [`artifact-verification-envelope.md`](artifact-verification-envelope.md) | verify/use | preview |
 | How is product publication authority sealed to an exact workflow, runner, control plane, nonce, and artifact? | [`publication-authority.md`](publication-authority.md) | verify | preview |
 | How are GitHub ownership, independent review, effective protection, and plan capability audited fail-closed? | [`github-governance-authority.md`](github-governance-authority.md) | verify | preview |

package/docs/binary-distribution.md

@@ -47,6 +47,13 @@ Each archive is accompanied by:
 - `buildchain-release-bundle.tar.gz`;
 - `buildchain-release-bundle.json`.
 
+Linux archives may also be accompanied by a GitHub/Sigstore bundle and
+`buildchain.github-artifact-attestation-evidence/v1`. These prove the exact
+GitHub signer workflow and source digest while preserving the original compiler
+runner in the platform manifest. The GitHub-hosted signer does not rebuild or
+execute consumer source. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 ## KFD-3 Distribution Declaration
 
 Buildchain self-describes this release lane in `dist/site/kfd-claims.json` as

package/docs/cli.md

@@ -74,6 +74,7 @@ import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
 import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain/badges";
 import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
+import { verifyGitHubArtifactAttestationEvidence } from "@kungfu-tech/buildchain/github-artifact-attestation";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
@@ -92,6 +93,14 @@ floating-ref contract world for a runtime such as `@v3`.
 
 ## Commands
 
+`buildchain create github-artifact-attestation-policy` seals the expected
+artifact, caller source, original Linux build, immutable Buildchain signer, and
+GitHub permission set before the Release Passport is collected.
+`buildchain verify github-artifact-attestation` invokes `gh attestation verify`
+with the exact signer/source policy and then verifies the retained bundle,
+predicate, platform manifest, Passport, and Buildchain evidence locally. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 `buildchain layout` is the stable machine question for repository layout. Tools
 such as Shifu should call it instead of copying `.buildchain/` path constants:
 

package/docs/dev-alpha-candidate-patrol.md

@@ -8,20 +8,21 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-07-26
+last_reviewed: 2026-07-27
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-26
+  generated_at: 2026-07-27
   visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.
   invisible_context_boundary: No credentials, private logs, or private configuration were used.
 ---
 
 # Dev to Alpha Candidate Patrol
 
-Buildchain provides a reusable observation and PR controller for repositories
-that promote a development branch into a protected Alpha branch. It does not
-publish Alpha. The controller reads the exact heads of both branches, walks the
+Buildchain provides a reusable observation and single-flight PR controller for
+repositories that promote a development branch into a protected Alpha branch.
+It does not publish Alpha. The read-only observer reads the exact heads of both
+branches, walks the
 bounded development history from newest to oldest (stopping early at the Alpha
 head), and selects the newest commit that satisfies all of these conditions:
 
@@ -45,19 +46,56 @@ The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records th
 source and target branches and SHAs, comparison distance, workflow paths, run
 identities and attempts, completion times, URLs, policy, and a canonical decision
 root. Missing, stale, failed, duplicate, or source-mismatched evidence fails
-closed.
+closed as an auditable `blocked` or `stale` observation and cannot enter
+settlement.
+
+The companion state is
+`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:
+
+- `observed`: no exact candidate is currently settleable;
+- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha
+  candidate PR is active;
+- `active`: exactly one managed candidate PR is open;
+- `retained-next`: an active PR remains authoritative and the newest different
+  qualified SHA is retained as `nextCandidate`;
+- `stale`: the available exact-SHA evidence pair is outside policy age; or
+- `blocked`: qualification or reconciliation failed closed.
+
+When a newer qualified SHA replaces an earlier `nextCandidate`, the state also
+records that earlier SHA as `supersededCandidate`. Every state carries exact
+repository, source/target refs and SHAs, workflow-run evidence through the
+candidate decision, and canonical decision/state roots.
 
 ## Reusable workflow
 
 Call `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository
-workflow. Start with `dry-run: true`. Once the repository has proven that its
-two workflow names and branch topology produce exact same-SHA evidence, it may
-set `create-pull-request: true` and `dry-run: false`.
+workflow. Start with `dry-run: true`. The reusable workflow always runs an
+`observe` job with only Actions/content/pull-request read permissions. Once the
+repository has proven that its two workflow names and branch topology produce
+exact same-SHA evidence, it may set `settlement-authorized: true` and
+`dry-run: false`. The older `create-pull-request` input remains a compatibility
+alias for settlement authorization.
+
+The separately permissioned `settle` job re-runs the exact observation before
+any write. With no active managed candidate, it creates one branch named from
+the target branch and the first 12 characters of the full source SHA. An
+existing branch must point to the same full SHA or the run fails. With one
+active managed candidate, it only updates the machine-readable state marker in
+that PR body so repeated events and rapid dev progress cannot create another
+candidate PR or another heavy candidate build. Foreign human-authored Alpha PRs
+are ignored. More than one open Buildchain-managed candidate fails closed.
+
+The PR body is the bounded durable controller state: it preserves the active
+candidate and newest retained `nextCandidate` without introducing an always-on
+service. Once the active PR settles or is abandoned, the next execution
+recomputes current exact-SHA qualification and creates only the newest still
+fresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.
 
-Candidate mode creates one branch named from the target branch and the first 12
-characters of the full source SHA. An existing branch must point to the same
-full SHA or the run fails. The controller then creates or reuses one open pull
-request from that immutable branch to the protected Alpha branch.
+Consumers should invoke this workflow after relevant qualification workflow
+completion and from an offset periodic fallback. GitHub may delay scheduled
+runs, so the event path supplies low latency while the fallback supplies
+recovery. Workflow concurrency plus the server-side open-PR reconciliation
+makes duplicate or delayed events idempotent.
 
 The workflow never moves the Alpha ref directly, merges or auto-merges the pull
 request, publishes npm, creates a Git tag or GitHub Release, or changes branch

package/docs/github-artifact-attestation.md

@@ -0,0 +1,219 @@
+---
+status: draft
+period: 2026-07
+theme: buildchain-linux-artifact-provenance
+doc_type: protocol
+source_level: code-and-official-docs
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-24
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-24
+  visible_context: Buildchain source, tests, GitHub Actions documentation, and actions/attest documentation
+  invisible_context: Model internals and provider-side implementation details are not visible
+---
+
+# GitHub-native Linux Artifact Attestation
+
+Buildchain can bind a Linux release artifact to its original compiler run, exact
+source revision, platform manifest, Release Passport, and an immutable
+Buildchain attester workflow. GitHub's OIDC identity and artifact attestation
+service provide the keyless signature; Buildchain provides the release contract
+and fail-closed local verification.
+
+This capability proves provenance and integrity. It does not prove that source
+code is safe, that a compiler was uncompromised, or that a self-hosted build
+runner had no privileged observer.
+
+## Trust Boundary
+
+The original Linux runner remains the compiler identity. The reusable attester
+runs on `ubuntu-24.04` only after the artifact, platform manifest, and Release
+Passport have been sealed and uploaded. It downloads those files as data and
+never checks out or executes consumer source.
+
+The attester checks out only
+`actions/github-artifact-attestation` from an exact Buildchain commit. It
+rejects a floating Buildchain ref, a different caller repository, a different
+source SHA, a different workflow run, a non-Linux platform manifest, or a
+subject digest absent from the Release Passport.
+
+The protected Environment defaults to `buildchain-artifact-attestation`.
+Consumer repositories should require review or restrict deployment branches on
+that Environment when their release policy requires an independent gate.
+
+## Non-circular Passport Binding
+
+The Release Passport first records
+`githubArtifactAttestations[]`, an immutable expected-attestation policy:
+
+- artifact name, relative path, byte size, and SHA-256;
+- caller repository, source commit, and source tree;
+- original Linux platform and platform-manifest digest; the initial v3 contract
+  requires the runner receipt root to equal that exact manifest digest;
+- Buildchain signer workflow path and exact signer-bootstrap commit;
+- exact Buildchain runtime commit used to build and release the artifact;
+- exact GitHub permission set.
+
+The GitHub attestation predicate then records the completed Release Passport
+file digest. The returned attestation id, URL, Sigstore bundle digest, and
+predicate root are written to a separate
+`buildchain.github-artifact-attestation-evidence/v1` document. Keeping dynamic
+provider evidence outside the Passport avoids a self-referential hash while
+still binding both directions.
+
+## GitHub Permissions and Runtime Pins
+
+Both caller and reusable workflow grant only:
+
+```yaml
+permissions:
+  actions: read
+  artifact-metadata: write
+  attestations: write
+  contents: read
+  id-token: write
+```
+
+The reusable workflow pins `actions/checkout`, `actions/download-artifact`,
+`actions/upload-artifact`, and `actions/attest` by full commit SHA. The workflow
+itself must also be called at its exact signer-bootstrap commit. The signer
+commit and the later Buildchain runtime commit are separately bound so the
+first v3 integration never relies on a mutable or self-referential workflow ref.
+
+## Prepare the Release Passport
+
+Create one input document for each Linux artifact and seal it as a policy:
+
+```bash
+buildchain create github-artifact-attestation-policy \
+  --input-json .buildchain/github-artifact-attestation/policy-input.json \
+  --output .buildchain/github-artifact-attestation/policy.json
+```
+
+The input object contains `subject`, `caller`, `signer`, and `build` objects.
+The CLI computes no trusted values implicitly: the caller supplies the already
+measured subject size/digest, source commit/tree, platform-manifest digest,
+runner receipt root, and exact Buildchain workflow commit.
+
+Pass the policy into Release Passport collection:
+
+```bash
+buildchain collect github-release \
+  --github-artifact-attestation-policy-json \
+    .buildchain/github-artifact-attestation/policy.json \
+  --output-dir .buildchain/release-passport \
+  # ...the existing release inputs
+```
+
+The build, Passport, and attestation jobs must stay in the same workflow run.
+The release-candidate build declares both the subject and the already-merged
+signer bootstrap commit. The Buildchain runtime remains the exact runtime ref
+used by the build workflow and may be a later commit:
+
+```yaml
+with:
+  github-artifact-attestation-subject-path: dist/kungfu-linux-x64.tar.gz
+  github-artifact-attestation-signer-sha: <exact-signer-bootstrap-sha>
+  github-artifact-attestation-platform-id: linux-x64
+```
+
+For release promotion, prefer the integrated v3 route. The policy must already
+be present in the downloaded release-candidate payload:
+
+```yaml
+permissions:
+  actions: write
+  artifact-metadata: write
+  attestations: write
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@<exact-buildchain-v3-runtime-sha>
+    with:
+      buildchain-ref: <exact-buildchain-v3-runtime-sha>
+      github-release: true
+      release-passport: true
+      github-artifact-attestation-policy-json: .buildchain/release-candidate/payload/<artifact>/policy.json
+      github-artifact-attestation-environment: buildchain-artifact-attestation
+```
+
+Promotion binds the policy into the Passport, stages only digest-matching data,
+calls the exact v3 signer, verifies the provider identity a second time, and
+publishes immutable bundle, predicate, verification, evidence, and receipt
+assets beside the release artifact. A same-name Release asset with different
+bytes is rejected instead of overwritten.
+
+Low-level callers may call the reusable attester directly after their Passport
+job. Both the reusable workflow ref and `buildchain-ref` use the same exact
+40-hex signer-bootstrap commit and fail closed if the provider identity differs:
+
+```yaml
+jobs:
+  attest-linux:
+    needs: [build-linux, release-passport]
+    permissions:
+      actions: read
+      artifact-metadata: write
+      attestations: write
+      contents: read
+      id-token: write
+    uses: kungfu-systems/buildchain/.github/workflows/github-artifact-attestation.yml@<exact-signer-bootstrap-sha>
+    with:
+      buildchain-ref: <exact-signer-bootstrap-sha>
+      evidence-run-id: ${{ github.run_id }}
+      source-sha: ${{ github.sha }}
+      subject-artifact-name: linux-release
+      subject-relative-path: libnode-linux-x64.tar.gz
+      platform-manifest-artifact-name: linux-platform-manifest
+      platform-manifest-relative-path: manifest.json
+      release-passport-artifact-name: release-passport
+      release-passport-relative-path: buildchain.release.json
+      policy-json: ${{ needs.release-passport.outputs.github-attestation-policy-json }}
+      evidence-artifact-name: linux-attestation-evidence
+```
+
+## Verify Online and Offline
+
+The Buildchain verifier reconstructs exact `gh attestation verify` arguments
+from the policy, including repository, signer workflow, signer digest, source
+digest, predicate type, and self-hosted-runner denial. It then verifies the
+local artifact, platform manifest, Release Passport, retained Sigstore bundle,
+custom predicate, and Buildchain evidence root:
+
+The reusable workflow runs that same exact signer/source verification
+immediately after `actions/attest` and before it finalizes or uploads evidence.
+Passing a different `buildchain-ref` than the commit used to invoke the reusable
+workflow therefore fails in the signer job, not only during later consumption.
+The policy additionally retains the distinct Buildchain runtime SHA that
+created the build and release evidence.
+
+```bash
+buildchain verify github-artifact-attestation \
+  --artifact libnode-linux-x64.tar.gz \
+  --platform-manifest manifest.json \
+  --release-passport buildchain.release.json \
+  --bundle attestation.sigstore.json \
+  --evidence github-artifact-attestation.evidence.json
+```
+
+Verification fails if a single artifact byte changes, the source commit or
+repository differs, the signer workflow or Buildchain commit differs, the
+Passport was replaced, the platform manifest drifts, the bundle omits the
+expected statement, or GitHub reports a self-hosted signer.
+
+## Qualification Policy
+
+New protocol work qualifies on the Buildchain v3 alpha line first. The v2
+development branch is not a supported landing target. Production
+adoption waits for the exact v3 implementation commit to pass the repository
+suite and a real GitHub OIDC/Sigstore qualification run, including the negative
+cases above. A successful local fixture is necessary but not sufficient.

package/docs/release-passport.md

@@ -8,6 +8,14 @@ promotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and
 machine-readable evidence. A project can keep its existing build system and use
 Buildchain to make the release record auditable.
 
+Linux release artifacts can additionally carry a GitHub keyless attestation
+policy in `githubArtifactAttestations[]`. The policy binds the exact subject,
+consumer source, original Linux build evidence, immutable Buildchain signer
+workflow, and minimum permissions before the provider attestation exists. The
+completed provider bundle and attestation identifier remain separate evidence,
+avoiding a Passport hash cycle. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 Release-candidate and final passports may also include compact
 `controllerReceipts[]` references. These bind a real reusable-workflow receipt
 to its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they
@@ -91,6 +99,10 @@ Additive passport sections:
   semantic Passport root, exact clean source revision, complete platform
   coverage, verdict, and residual risk. Buildchain owns release admission, not
   the meaning of the product invariants.
+- `githubArtifactAttestations`: expected GitHub keyless attestation identities
+  for Linux release artifacts, including subject, caller source, original build
+  evidence, exact Buildchain signer workflow digest, and least-privilege
+  permissions. Dynamic provider evidence is stored beside the Passport.
 
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:
@@ -144,6 +156,7 @@ buildchain collect github-release \
   --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --invariant-passport-json product/release/qualification/invariant-passport.json \
+  --github-artifact-attestation-policy-json .buildchain/github-artifact-attestation/policy.json \
   --output-dir .buildchain/release-passport
 ```
 

package/docs/reusable-build-surface.md

@@ -5,6 +5,12 @@ Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
 
+For Linux release artifacts, the build workflow can hand the sealed artifact,
+platform manifest, and Release Passport to the separate GitHub-hosted keyless
+attester. The compiler runner remains the recorded build identity; the attester
+only signs and verifies immutable data. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 ## Automatic Channel Router
 
 The preferred consumer surface is one reusable workflow call. After v2.12