# Reproducible builds

Prove that a build is byte-for-byte reproducible by comparing the snapshot ID of
its output directory, and archive every release artifact under a verifiable,
content-addressed ID.

## The problem

A reproducible build is supposed to produce identical output from identical
inputs — but "identical" is hard to demonstrate. Two builds on two machines emit
trees full of files; diffing them by hand is tedious, and a single embedded
timestamp or non-deterministic archive order silently breaks bit-for-bit
equality. When a security review or a supply-chain audit asks "is the binary we
shipped the one this commit produces?", most teams cannot answer with proof,
only with hope. And the artifacts themselves get scattered across CI caches and
release buckets with no durable, tamper-evident identifier.

## Why snapdir

The snapshot ID is the BLAKE3 hash of the build output's
[manifest](../concepts/manifests.md). Two builds are byte-for-byte reproducible
**if and only if** their output directories produce the same ID — a single
string you can compare, log, and assert on in CI.

- **One-line reproducibility check.** Compare the ID of a rebuild against the ID
  of the reference build. Equal IDs are a cryptographic proof of bit-for-bit
  equality; a difference points you straight at a changed file.
- **Verifiable archive.** Push the release tree to a store and the ID *is* the
  receipt. Anyone can later [verify](../concepts/integrity.md) the archived
  snapshot against that ID.
- **Deterministic by construction.** The manifest is sorted by path with no
  embedded mtimes, so it does not depend on walk order or the clock — only on
  content.

## Walkthrough

Build twice — on a clean rebuild, or on a second machine — and compare the output
IDs. `snapdir id` only hashes the tree; it writes nothing:

```sh
snapdir id ./dist          # reference build
# ... rebuild from the same commit into ./dist-rebuild ...
snapdir id ./dist-rebuild  # must print the identical ID
```

Wire that assertion into the pipeline so a non-reproducible build fails loudly:

```sh
ref=$(snapdir id ./dist)
got=$(snapdir id ./dist-rebuild)
[ "$ref" = "$got" ] || { echo "build not reproducible: $ref != $got"; exit 1; }
```

When the build is verified reproducible, archive it. `push` stores the manifest
and objects under content-addressed keys and prints the ID to record in your
release notes:

```sh
release_id=$(snapdir push --store s3://releases/builds ./dist)
echo "release $release_id"
```

For an after-the-fact audit, re-verify the archived snapshot end-to-end against
its store — every object is re-hashed against the manifest:

```sh
snapdir verify --store s3://releases/builds --id "$release_id"
```

## Outcome

Reproducibility becomes a checkable assertion rather than an aspiration: a single
ID comparison proves two builds are identical, and CI can gate releases on it.
Every shipped artifact is archived under a content-addressed ID that doubles as
an audit receipt, re-verifiable at any time. To reconstruct exactly what was
released and when, query the snapshot history with
[`snapdir revisions`](../guide/history.md).