---
name: schfs-phase2-mount
description: "SchFS phase 2 is done — the kernel mounts real images read-only; run `make schfs-check` after touching kernel/fs/schfs"
metadata: 
  node_type: memory
  type: project
  originSessionId: a665e14b-86bd-4b41-a228-51377f3e9225
  modified: 2026-08-03T12:37:43.088Z
---

**Phase 2 done (2026-08-02):** the kernel mounts a SchFS volume read-only at
boot and it is verified end to end. Phase 1 notes: [[schfs-btree-phase1]].

Layout — everything but `kmount.c` compiles into *both* the kernel and the host
tools, so writer and reader cannot drift:

- `kernel/fs/schfs/vol.c` uberblock ring, `obj.c` read side, `objw.c` write side
  (host only until phase 3), `kmount.c` buffer-cache bdev + boot mount.
- `tools/mkschfs.c` builds images, `tools/schfs_fsck.c` verifies/lists/extracts.

**Run `make schfs-check`** (B-tree + round-trip) after any change under
`kernel/fs/schfs`. `tools/mutate.sh` injects six bugs and fails if any survives.

Boot-testing: `make ramroot` first (root from RAM leaves device 1 free), then
`make qemu-schfs`, then `cat /proc/schfs`. Unattended:
`tools\bootcheck.ps1 -SchFS` drives the shell over serial and asserts on the
transcript — see [[schunix-verify-by-driving-shell]].

**Traps that cost real time, all fixed:**

- The root's object id must be *reserved*; starting `next_objectid` at it made
  the first directory become the root, so it contained itself.
- Range callbacks get pointers into the cursor's block buffer, which any nested
  lookup overwrites. Directory iteration copies each entry out first.
- A 4096-byte block will not fit on the 4096-byte kernel stack (KSTACKSIZE).
  The kstack canary catches it as "kstack overflow".
- Extents only merge if the whole run is allocated before any tree write.

Full write-up, including why the design doc's phase list changed, is in
`docs/architecture/schfs.md` §8-9.

**Superseded on 2026-08-03 by [[schfs-phase3-writes]]** — writes are done, and
free space is *derived from the tree at mount*, not tracked as tree keys as
planned here. The VFS work is still outstanding, and also unblocks per-pid
`/proc` for ps/top ([[schunix-devfs-procfs]]).