Module payload_digest 

Mirror of the rule deciding what a box commits to about its own extracted tree.

A signed release commits to the archive’s SHA-256, which proves every payload byte — but only while the archive still exists. An application that installs a box once and runs it for months has thrown that archive away. So a box also carries a list: one record per payload entry, naming it and hashing its content. The release signs the SHA-256 of that list, and the list travels inside the payload.

The list is what makes verification a closed question. A verifier walks the list, never the directory, so anything the list does not name is never visited: the __pycache__ Python writes on first import, the model cache a caller fills after extraction, the file an application writes into its own working directory. Those are invisible by construction rather than by an exclusion list.

Records are sorted by their own bytes rather than by their paths compared as strings. The two are the same ordering — a path cannot contain NUL, and NUL sorts below every byte a path can hold — but only one of them is unambiguous across languages. Comparing strings would ask each implementation to agree on what a string is, and above the Basic Multilingual Plane JavaScript orders by UTF-16 code unit while Python orders by code point. Rust would order by UTF-8 bytes and quietly agree with neither, which is precisely why the format does not ask.

tests/contract.rs proves this mirror against fixtures/payload-digest-contract.json.

Structs

PayloadDigest

What a release carries to commit to its extracted tree.

PayloadDigestEntry

One payload entry as the digest sees it.

Enums

PayloadDigestKind

What a payload entry is, as the digest sees it. Directories are not represented: neither the entry collector nor the archive writer produces one, so an empty directory is already lost between build and install.

Constants

MAX_PAYLOAD_DIGEST_BYTES

The largest list a verifier will read before refusing.

PAYLOAD_DIGEST_FILE

Where the list lives inside the payload.

PAYLOAD_DIGEST_FORMAT

The format a release names, and the first line of the stream it names it for.

Functions

parse_payload_digest_stream

Reads a list back into entries, refusing anything a serialiser could not have produced.

payload_digest

Serialises the entries and returns what a release carries about them.

payload_digest_stream

Serialises payload entries into the canonical bytes a release commits to.