Skip to content

Bootstrap Dependency Manifest

Dependency register — instantiates Self-Hosted Bootstrap Construction

Declares the full build-dependency graph, names the trusted seed at its root, and marks the single edge where the bootstrap cycle is deliberately cut.

Before anyone builds anything, someone has to write down what needs what. Bootstrap Dependency Manifest is the declared, version-controlled record of the whole construction: every stage and its build inputs, traced all the way back to the one small artifact the project agrees to trust without building it. Its defining move is making the circularity legible — it shows exactly where the graph would eat its own tail (the compiler that needs a compiler, the build system that needs itself to build), names the trusted seed that sits below that loop, and marks the single edge where the cycle is cut. It builds nothing and enforces nothing; it is the map every other mechanism reads. A manifest that merely lists packages without exposing the cut point is just an inventory — this one exists to answer "where does the regress stop, and why is stopping there safe?"

Example

A team bootstrapping a Linux userland from as little as possible starts by writing the manifest. Working in the spirit of the bootstrappable-builds effort, they trace the graph downward: the shell needs a C compiler, the C compiler needs a C compiler, make needs a shell — and the whole tangle bottoms out at a few hundred bytes of hand-auditable machine code (a hex0-style seed) that a human can read in an afternoon. The manifest records all of it: nodes for each stage, edges for each build input, the seed pinned at the root by hash, and one edge flagged in red — "this is the cut; below it we trust the seed by inspection, above it everything is derived."

The payoff shows up the first time someone proposes adding a convenience dependency midway up the ladder. Because the manifest is explicit, the new edge is visible immediately as what it is: a second, undeclared entry point that quietly widens the trusted base. The proposal gets rewritten to build that tool from existing rungs instead. The manifest didn't make that decision, but it made the decision possible by showing the shape no one could otherwise hold in their head.

How it works

What distinguishes the manifest is that it is declarative and static — a described structure, not an executed one. It fixes three things and nothing else: the dependency graph (what derives from what), the seed at the root (the artifact trusted without derivation, identified by hash), and the cut edge (the exact point where recursion is halted). Everything downstream — the climb, the checks, the handoff — treats the manifest as ground truth and is measured against it. Keeping it purely descriptive is the point: the moment it starts doing work, it stops being a trustworthy map of what the work actually depends on.

Tuning parameters

  • Graph granularity — nodes per package, per binary, or per source file. Finer granularity catches subtler hidden dependencies but is far more expensive to keep honest.
  • Seed minimality — how far down the root is pushed. A smaller seed shrinks the trusted base and the audit burden, but pushing lower usually costs many more derived rungs to climb back up.
  • Cut-edge count — whether the manifest permits one designated cut or several. More cut points make bring-up easier but enlarge the surface that must be trusted by inspection.
  • Provenance depth — how much origin metadata (hashes, source, signer) each node carries. Deeper provenance strengthens later verification but grows the manifest and its upkeep.

When it helps, and when it misleads

Its strength is turning an implicit tangle into an inspectable object: hidden dependencies, second entry points, and an ever-creeping trusted base all become visible as edges someone has to justify. It is the shared reference that lets the pin-and-replace procedure, the clean rebuild, and the double-compilation check each know what "correct" even means.

Its central failure mode is drift — a manifest is only as true as its last reconciliation with reality, and an unenforced one silently rots into fiction while everyone still cites it. The classic misuse is writing it after the build already works, reverse-engineered from whatever happened to be installed, so it launders the accidental trusted base into a documented one rather than constraining it. The discipline that guards against this is to treat the manifest as executable intent and hold it to a from-scratch Clean-Environment Rebuild: if the system won't rebuild from exactly what the manifest declares, the manifest is wrong, not the build.[1]

How it implements the components

Bootstrap Dependency Manifest fills the archetype's declared-structure components — the map, not the motion:

  • bootstrap_dependency_graph — its primary content: the nodes and build edges of the whole construction, the object the graph component names.
  • trusted_minimal_seed — it designates and pins the root artifact trusted without derivation, identified by hash.
  • bootstrap_cycle_break_rule — it marks the single edge where recursion is halted and records why stopping there is acceptable.

It does not climb the graph (that's Capability-Ladder Runbook), enact the cut by swapping in self-built tools (that's Bootstrap Toolchain Pin-and-Replace), or enforce that reality matches the declaration (that's Clean-Environment Rebuild).

Notes

The manifest is deliberately inert — it describes the cut but never performs it. That separation is load-bearing: it lets the trusted base be argued about as a declared fact, independent of whichever procedure happens to build the system this week. When a manifest starts to include steps or conditionals, it has quietly become a runbook and lost the one property that made it worth trusting.

References

[1] The Bootstrappable Builds effort (and seed toolchains such as stage0) is the real-world discipline of shrinking the trusted binary seed toward something a human can audit and deriving everything else — the concrete practice a manifest like this exists to record. ↩