# Binary Distribution

Buildchain's binary distribution is the first high-pressure proof case for the
Release Passport protocol. It is not the boundary of the product.

## Asset Rules

GitHub Release assets use platform-specific archives:

- `buildchain-x86_64-unknown-linux-gnu.tar.gz`
- `buildchain-aarch64-apple-darwin.tar.gz`
- `buildchain-x86_64-pc-windows-msvc.zip`

The release lane does not upload loose top-level `buildchain` or
`buildchain.exe` assets. Linux and macOS both name the executable `buildchain`
inside their archives, so top-level loose assets would collide when matrix
artifacts are merged.

`Binary Distribution` is evidence-only. It never receives `contents: write`
and never calls `gh release upload`; `upload-release=true` is rejected before
the matrix starts. A completed promotion explicitly dispatches the workflow at
the exact public tag because tags created by `GITHUB_TOKEN` do not recursively
start ordinary `push` workflows.

After all three runners qualify, the workflow seals a
`binary-distribution` controller receipt over the exact source/runtime SHA,
release bundle, and Release Passport. `Binary Release Assets` observes the
successful evidence run, rechecks that its source SHA still equals the exact
tag, derives the governed alpha/release branch, and asks the credential-free
publication authority to assemble a short-lived capability. Only the nested
publisher owns `contents: write`, and it runs behind the protected
`buildchain-release-assets` Environment.

GitHub Release metadata remains deterministic and tag-derived. Exact alpha tags such
as `v2.6.2-alpha.0` are created or updated with `prerelease=true` and
`make_latest=false`; exact stable tags such as `v2.6.1` are created or updated
with `prerelease=false` and `make_latest=true`. The sealed publisher uses
`scripts/ensure-github-release.mjs` before asset upload instead of relying on
GitHub's default latest-release heuristic.

Each archive is accompanied by:

- a platform manifest from the standalone binary builder;
- platform observability event logs and summaries;
- `checksums.txt`;
- Release Passport evidence files;
- `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
the KFD-3 surface `distribution:buildchain-standalone`. Its declaration assigns
registration to Shifu, names `binary:build` as the reproducible task, and lists
the artifact kind, platform, and path glob for all three archives. Shifu should
discover the registry through `buildchain layout --json`, not by copying the
registry path.

The repository-owned task is:

```bash
pnpm binary:build
```

The release workflow still builds each target on its declared runner. The local
task is the stable task identity used by the KFD declaration and local smoke
checks; it does not replace the three-platform release matrix.

## Runner Policy

Production binary builds use GitHub-hosted runners:

- `ubuntu-24.04`
- `macos-latest`
- `windows-2022`

Self-hosted runners are compatibility fixtures. They can prove that consumers
with private runner fleets can still use the protocol, but Buildchain's public
binary distribution should stay reproducible on GitHub-hosted runners.

## Evidence Bundle

`buildchain-release-bundle.tar.gz` groups release assets and passport evidence
under one archive:

```text
buildchain-release-bundle/
  release-assets/
  release-passport/
  buildchain-release-bundle.index.json
```

`buildchain-release-bundle.json` records the bundle digest and every included
file digest. Consumers can download the bundle when they want one artifact for
offline review, mirroring, or site ingestion.

Publication fails closed unless the bundle contains all three archives,
`checksums.txt`, and `buildchain.release.json`; its archive digest, controller
receipt, live control-plane audit, runner provenance, source/runtime SHA, and
exact target tag must all match the sealed admission.

## Local Smoke

```bash
pnpm binary:build -- --version v0.0.0-local
node bin/buildchain.mjs collect github-release \
  --tag v0.0.0-local \
  --assets-dir dist/binary \
  --output-dir .buildchain/release-passport
node scripts/create-release-bundle.mjs \
  --assets-dir dist/binary \
  --passport-dir .buildchain/release-passport \
  --output-dir .buildchain/release-passport \
  --tag v0.0.0-local
```