onboard: the wasm seed bootstrap

1 files changed, 12 insertions, 6 deletions

diff --git a/ONBOARD.md b/ONBOARD.md
index 0f1c95c..3a0b171 100644
--- a/ONBOARD.md
+++ b/ONBOARD.md
@@ -43,12 +43,18 @@ build/bin/zy < examples/hello.zc
 ```
 
 watch the output of `make`: the default memory map is generated
-(`build/core/map/`), zc0 compiles the genome sources (stage 0), a core built
-around that image compiles the compiler again (stage 1) and again (stage 2), the
-two self-compiled images are compared, and the first becomes
-`build/core/genome.bin`. then `zy`, `zym` and `zclsp` are built around it.
-
-you should be able to say: why the bootstrap needs three stages, what `mkgenome`
+(`build/core/map/`), then `src/boot/boot.sh` checks the pinned seed
+(`seed/zc.wasm`, the microcore with a compiler genome inside, built for WASI) against
+the sha256 in `seed/MANIFEST` and runs it under wasmtime or node: the seed compiles the
+compiler sources (g1), g1 compiles them again (g2), and g1 and g2 must agree (else g2
+compiles them to g3 and g2 and g3 must). the result becomes `build/core/genome.bin`;
+then `zy`, `zym` and `zclsp` are built around it. no c compiler takes part in
+compiling the compiler, and the seed is proven by the fixpoint rather than trusted.
+`make seed` rebuilds the seed and its manifest from the current genome (needs clang
+with wasm32 and wasm-ld; wasm-opt when found); `make genome-c` is the old bootstrap
+through zc0 and the c core, kept for comparison.
+
+you should be able to say: why the bootstrap needs a second (sometimes third) stage, what `mkgenome`
 protects against (a compiler's error report taken for an image), and how a core
 finds its image (`src/core/genome.h`, `--embed-dir`).