Skip to content

Checkpointed Stage Promotion

Promotion process — instantiates Self-Hosted Bootstrap Construction

Advances the build one stage at a time — snapshotting each stage, promoting only when readiness and invariants both check out, and rolling back to the last good snapshot when they don't.

A ladder is only safe to climb if you can stand still and step back. Checkpointed Stage Promotion is the workflow that actually moves the build up a rung: it captures a restorable snapshot of each completed stage, checks the stage against explicit readiness criteria and a set of invariants that must survive the transition, and only then promotes it to become the base for the next stage — rolling back to the last good snapshot if either check fails. Its defining move is coupling a snapshot to a gate: because every promoted stage is checkpointed, a failed promotion is never catastrophic, and the decision to advance is a deliberate, evidence-backed act rather than the mere fact that the next build happened to start. Where the runbook says what each rung must achieve, this process is where a rung earns — or is denied — the right to carry the ones above it.

Example

A container platform bootstraps its base images in stages: scratch → a minimal busybox layer → a hardened base → the full runtime image, each built using the layer below it. The promotion pipeline snapshots every layer as an immutable, content-addressed image before anything downstream depends on it. Promotion from the hardened base to the full runtime is gated twice: a readiness check (the base's smoke tests and package set are complete) and an invariant set that must hold across the transition — no new critical CVEs introduced, image size under the agreed ceiling, and the same non-root user and locale carried forward.

One promotion attempt fails the invariant check: the new runtime layer quietly reintroduces a root default that the hardened base had removed. Because the base was snapshotted, the pipeline rolls straight back to it, and the bad runtime never becomes anyone's foundation. The fix lands, the promotion is retried, the invariants pass, and only then does the runtime image become the published base others build on.

How it works

What distinguishes this process is that it treats advancement itself as the guarded operation. Three things fire at every rung: a checkpoint snapshot captured before the stage is trusted, a readiness gate confirming the stage has met its contract, and an invariant check confirming that specific properties held before promotion still hold after it. Promotion is the atomic outcome of passing both gates; failing either triggers the rollback policy, which restores the last good snapshot rather than trying to repair in place. The stage-by-stage cadence is deliberate — it keeps every failure bounded to a single rung with a known-good state one step below it.

Tuning parameters

  • Snapshot granularity — checkpoint every stage or only major ones. Frequent snapshots make rollback precise and cheap but cost storage and time; sparse ones save space but lose more work on a revert.
  • Gate strictness — how much must pass before promotion. Strict gates catch more bad promotions but slow the climb and tempt people to weaken the criteria under deadline pressure.
  • Invariant scope — which properties must survive every transition (security posture, size, interface stability). A broader set catches more regressions but raises the chance a promotion is blocked on something minor.
  • Rollback depth — revert one rung, or unwind several. Single-step rollback is fast and usually enough; deep rollback recovers from a defect that turns out to predate the last stage but discards more progress.

When it helps, and when it misleads

Its strength is that it makes an inherently risky, self-referential climb recoverable: every rung has a known-good state beneath it, so a bad stage is caught and reverted before anything is built on top of it, and "we've advanced" always means "we passed the gate," never just "the next build ran."

Its failure mode is gate erosion under schedule pressure — readiness criteria quietly softened, invariants waived "just this once" — so that promotions keep happening while the checks that gave them meaning hollow out. Snapshots can also breed false confidence: a checkpoint is only a safe fallback if the state it captured was actually good, and a defect that predates the snapshot rolls back to the same defect. The classic misuse is promoting first and back-filling the readiness evidence afterward, so the gate ratifies a decision already made. The discipline is to keep the gate criteria versioned and externally reviewed, and to pair each snapshot with an independent check that the captured state truly met its contract.

How it implements the components

Checkpointed Stage Promotion fills the archetype's guarded-advancement components — snapshot, gate, and recover:

  • bootstrap_checkpoint_snapshot — it captures a restorable snapshot of each stage before anything depends on it.
  • readiness_criteria — it checks each stage against explicit conditions before allowing promotion.
  • stage_transition_invariant_set — it verifies that the properties required to survive a transition still hold after promotion.
  • fallback_or_rollback_policy — on a failed gate it restores the last good snapshot rather than repairing in place.

It does not define what each rung's capability should be (that's Capability-Ladder Runbook), prove a promoted stage is free of a hidden compromise (that's Diverse Double-Compilation Check), or handle recovery when no good snapshot remains (that's Emergency External-Seed Recovery).