Golden test vectors

Golden vectors are known-input to known-digest fixtures. They pin the manifest encoding and the content-addressed digest domain for AWC. Every binary that re-derives a digest from a described input must reproduce the recorded digest exactly. The vectors anchor the content-addressing scheme against drift across implementations and releases.

Purpose

The vectors are a regression guard. A new release runs them to prove that it still emits the same bytes for the same described input. A binary that disagrees with a vector has a format bug.

Digest domain

Every vector pins the same domain-separated digest. The digest is taken over a canonical encoding of an object, tagged by its object kind. The object kinds are BLOB, FILE, TREE, and SNAPSHOT. The canonical encoding is defined in on-disk format.

The canonical digest string is sha256: followed by 64 lowercase hexadecimal characters.

Release artifacts

The golden vectors are checked into the test suite and published as a release artifact. They are versioned independently from the service release version. The fixture is small. Read it from the repository for the exact bytes and digests.

Stability contract

A change to a vector is a format change. Three rules follow.

• The vectors must be checked by all binaries.
• The format specification and the vectors must be versioned independently from service release versions.
• Every binary must share the same golden digests.

Do not edit a recorded digest to quiet a failing test. A failing golden test means the encoding changed. Bump the format version and add a new vector set instead.