Snapshots

Each tier is built on the one below it, and each has a key that is a pure function of named inputs. A run restores the highest tier whose key still matches and recomputes everything above it. That is why “why did this boot cold” is always answerable: the keys differ in exactly one place.

S0 · runtime

The Certus guest image: kernel, init, the in-sandbox agents. Nothing of any customer. Rebuilt on a Certus release, never by your run.

S1 · toolchain

Language runtimes and system packages from the pinned toolchain lock. No code from your repository runs here. Invalidated by a change to the lock.

S2 · dependencies

Your own dependency install, hashed at the merge base. Install hooks run here, so this is the first tier scoped to your tenant. Invalidated by any lockfile or manifest edit.

S3 · world

The booted world at the merge base: services running, migrations applied, fixtures seeded, build caches warm — and neither checkout present. Invalidated by a recipe edit, a new merge base, or a fixture change.

S4 · side delta

One per side: the changed files, the incremental build, and anything whose identity depends on that commit. BASE gets one too, with an empty delta.

S5 · run state

The writable disk, the live database layer, leases, logs in flight. It has no key because it is never looked up and never cached. Creating it is the run.

Between S1 and S2 is the tenant line. S0 and S1 are shared across every customer because nothing in them can be influenced by repository code. S2 upward is yours alone — S2 executes install hooks from your repository and its contents disclose your dependency graph, including internal package names.

Between S4 and S5 is the secret seal. No process that has ever held a leased credential appears in any cached tier. S0 through S4 are cached and therefore hold no secret, in memory or on disk; S5 is the only tier that may, and S5 is never captured.

Every cached artifact is content-addressed and verified by hash before it is loaded. A restore that does not verify is discarded and recomputed rather than trusted.

The Substrate view shows, per side, which tier was restored, whether it hit, and how long the restore took. A hit high on the ladder is a fast boot. A miss at S3 means the world was rebuilt: migrations re-applied, fixtures re-seeded, services restarted.

S5 always misses, and that is not a problem — it is the run's own state, created fresh every time. A warm database is never reused between runs under any load.

• Keep .certus/env.yaml stable. The recipe hash is part of the S3 key, so any edit — including a comment — rebuilds the world.
• Batch lockfile changes. Every dependency edit invalidates S2 and everything above it, and costs an install plus a full boot.
• Rebase onto a shared merge base. Consecutive pull requests off one merge base share S3, which is where the time actually is.
• Leave fixture sets alone unless you mean to change them. The fixture digest is in the S3 key.
• Expect S4 to miss across pull requests and hit within one. Re-proofs, a second frontier and retries all reuse it.

A cold boot on a repository that is usually warm

Compare this run's tier keys with the last warm one. Exactly one input changed: the toolchain lock, a dependency lockfile, the recipe, the fixture set, or the merge base.

S3 misses every time

Something in the S3 key is moving on every run — usually a recipe that is generated rather than committed, or a merge base that advances constantly.

BLOCKED with a snapshot restore failure

A cached artifact did not verify or would not restore. Certus recomputes once and stops if that fails too. Re-run; if it persists it is a Certus fault, not yours.

A restore that is slower than the boot it replaced

Report it. A tier whose restore costs more than recomputing it is a tier that should not exist.