Software integrity¶

Understand why StageX treats reproducibility and full-source bootstrapping as one end-to-end software integrity claim.

One integrity claim¶

StageX treats reproducibility and full-source bootstrapping as closely related parts of the same end-to-end supply chain property. A package is not considered reproducible in StageX just because the final build can be repeated bit for bit. Artifacts must be reproducible, and the in-tree toolchain used to build them must be full-source bootstrapped and deterministic; otherwise part of the stack still depends on a binary whose own origin cannot be reproduced.

Why reproducibility is not enough¶

A build is reproducible when the same source, toolchain, dependencies, and build settings produce the same bytes. If two machines build the same input and get the same digest, they have evidence that the published artifact came from that input.

That evidence is useful, but it is incomplete if the compiler or base toolchain was itself a prebuilt binary. The final application can be reproducible while still depending on an unreproducible part of the stack. The final digest matches, but the ancestry of the compiler remains opaque.

StageX closes that gap by requiring both:

The artifact must build deterministically from declared inputs.
The in-tree toolchain and package stack must be full-source bootstrapped.

Full-source bootstrapping¶

Full-source bootstrapping means building the toolchain from source all the way down to a small auditable seed. StageX starts from hex0, a 181-byte hand-written i386 ELF program. From there, each stage builds tools that are used to build the next stage.

The simplified chain is:

hex0 seed
  -> stage0 tools
  -> 32-bit userland
  -> cross-compilers
  -> native 64-bit toolchain
  -> StageX packages and pallets

No prebuilt compiler binary is inserted into the StageX userland chain.

Deterministic, hermetic, reproducible¶

StageX uses three related properties:

Hermetic: The build uses declared inputs and does not download new material during compilation.
Deterministic: The same inputs produce the same output on the same machine.
Reproducible: Different machines can produce the same output from the same inputs.

StageX requires all three, plus full-source bootstrapping for the in-tree stack.

How StageX supports this¶

StageX builds use:

Digest-pinned toolchain images.
Fixed build environment values such as locale, timezone, and SOURCE_DATE_EPOCH.
RUN --network=none for compile steps.
Lockfiles or explicit source hashes for dependencies.
OCI image output with normalized timestamps.
Independent rebuilds by more than one maintainer before signing.
A bootstrapped userland chain that traces back to the hex0 seed.

What this does and does not prove¶

Reproducibility and bootstrapping do not prove that upstream source code is correct, secure, or free of malicious logic. They prove a narrower but important claim: the artifact matches the declared source and build process, and the in-tree toolchain used to build it is itself traceable to source.

That removes both the build server and opaque prebuilt toolchains as places where code can be changed without leaving evidence.