docs: the SchFS suite is red, and Gate 0 says why

Two failures found by running `make schfs-check` rather than by reading it, both
predating the current work -- confirmed by stashing the session's changes and
re-running to byte-identical output.

  * AddressSanitizer: 2121728 bytes leaked in 518 allocations, every one from
    md_palloc in tools/schfs_objtest.c, the test's own page allocator. The
    target exits non-zero, so the whole suite fails whatever the assertions say.
    The cost is not the memory -- it is that a real leak in the filesystem would
    now arrive as noise inside 2 MB of expected noise.

  * UndefinedBehaviorSanitizer: 31 misaligned accesses across obj.c, objw.c,
    attr.c and space.c, one root cause. Records are read by casting a pointer
    into a tree leaf, and a record's offset within a leaf is not a multiple of
    8. This works on x86, which is why it has never shown as a bug, and it is
    undefined in C: a compiler entitled to assume 8-byte alignment may emit an
    instruction that requires it, and the failure would then look like
    filesystem corruption rather than codegen.

Recorded as Gate 0 items rather than as nice-to-haves for one reason: a suite
that is red for known reasons stops being read, and then it is red for unknown
reasons too. guides/testing.md now says so up front, so nobody reads the [ok]
lines and ignores the exit code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
This commit is contained in:
Nexoniarz 2026-09-12 17:30:01 +02:00
commit 3e2f3cd1ec
2 changed files with 56 additions and 0 deletions

View file

@ -121,6 +121,22 @@ linked into the kernel binary for a `ramroot` build.
---
## The suite is currently red
`make schfs-check` **exits non-zero at baseline**, and has for some time. Two
separate causes, both in the harness rather than the filesystem, both itemised
in [../plan/1.0.md](../plan/1.0.md):
- AddressSanitizer reports 2121728 bytes leaked in 518 allocations, all from the
test's own page allocator, which never frees.
- UndefinedBehaviorSanitizer reports 31 misaligned reads, from casting pointers
into tree leaves where records are not 8-aligned.
Worth knowing before you run it, and worth fixing rather than living with: the
assertions still pass, so it is tempting to read the `[ok]` lines and ignore the
exit code — which is exactly how a suite stops being a check and becomes a
decoration.
## What is not tested
- **No automated test runs on real hardware.** Everything above is QEMU.