Home/Tutorials/09-verification

Lesson 09 — Verification & the SHA-256 Gate

Series: index · prev: 08 · next: 10 — The .ledger class

SLeeLa's toolchain builds fail-closed: the compiler will not build unless every toolchain source matches a trusted SHA-256 manifest. This protects the interpreter, so you can trust that the thing running your Wrappers is the thing that was reviewed.

The manifest

security/sha256-manifest.json records a digest for each toolchain source the build compiles (the core, front end, Nordshrift driver, subject libraries, and the shared ledger core). It is generated by:

python3 tools/generate-sha256-manifest.py --root . --output security/sha256-manifest.json

Building with the gate

The verified build needs the manifest path in the environment:

cd impl
export SLEELA_SHA256_MANIFEST="$PWD/../security/sha256-manifest.json"
make build/nordshrift

If a toolchain file has changed without the manifest being updated, the build stops with a clear message, e.g.:

verification: SHA-256 mismatch: impl/nordshrift/nordshrift.cpp
  expected: <digest-in-manifest>
  actual:   <digest-on-disk>
verification: FAILED (1 item(s))

That's the gate doing its job. The fix is not to bypass it — it is to review the change and regenerate the manifest so it records the new, trusted bytes:

python3 tools/generate-sha256-manifest.py --root . --output security/sha256-manifest.json

What is and isn't covered

  • Covered: the toolchain sources and trusted inputs (including SHEET.sheet, which the compiler reads to resolve conducted methods — tampering with it would silently change program meaning).
  • Not covered: your own .sleela programs. The gate protects the interpreter, not the arbitrary programs it runs. Per-file integrity of your artifacts is the .ledger's job — next lesson.

Why it belongs in a tutorial

Reproducible, fail-closed builds are part of "SLeeLa at her source best": the same inputs always yield the same trusted toolchain, and any drift is caught before code runs rather than after.

Next: Lesson 10 — The .ledger class