Skip to content

Latest commit

 

History

History
495 lines (456 loc) · 29.1 KB

source.md

File metadata and controls

495 lines (456 loc) · 29.1 KB

Source contract: sibling repos, toolchain kernel-build plan, codec and utility tools

Moved verbatim from CLAUDE.md (2026-09-29 compaction); CLAUDE.md keeps the rules and hazards and indexes this file.

Source Contract

The system spans this repository plus one sibling checkout per external source: the toolchain (miniGCC, ld, cvm), the interpreters (lua, micropython, cpython), the UI and audio libraries (nuklear, nuked-opl3), the browser (FreeDom) and the reference-only raycastlib. Every one of them carries an addons/<name>.yaml (see Addon doctrine); DOOM, Quake 2 and doomedit live in-repo or nested and carry one too. The build must be reproducible from those upstreams alone, so:

  • make sources clones the missing ones and make sources-update pulls them. Neither ever modifies a directory that already exists, so a checkout with local work is never clobbered.
  • Every location is overridable (MINIGCC_DIR, LD_DIR, CVM_REPO_DIR, CVM_DIR, LUA_DIR, MICROPYTHON_DIR, NUKLEAR_DIR, NUKED_OPL3_DIR, FREEDOM_DIR, RAYCASTLIB_DIR) and so is every origin (*_URL, plus MICROPYTHON_REF/LUA_REF where a release is pinned). Nothing in the build assumes an absolute path.
  • Everything on the ramdisk is regenerated from source: minigcc.o, ld.o and cvm.o from the sibling checkouts, and the demo programs from this repository's own C sources in progs/, driven through miniGCC and ld. The prebuilt objects in progs/ are a convenience for a first boot, never an input the build depends on.
  • Ramdisk content is owned here. Reaching into another project's test fixtures for files to ship would break the moment that project reorganizes them, which is exactly what happened when the image was built from ld/tests/*.s.
  • ramdisk.bin lists the Makefile among its prerequisites: the file list lives there, so editing it must invalidate the image even when no individual file changed. minifs.bin carries the same rule for the same reason.
  • tools/mkramdisk.py deflate-compresses every payload (zlib stream, decoded by the kernel's miniz) and stores raw only when compression does not pay, with raw_size/stored_size/data_offset/flags per entry. ramdisk_setup_from inflates every entry once at boot into the working area, so the on-disk/embedded image drops to ~28% of the raw size (kernel image 957 KB -> 569 KB) while reads, writes and resizes see plain bytes and lose no performance. A payload that fails to inflate aborts setup rather than publishing a torn file.
  • progs/bin/ ships the command-path utilities: cp, freedom, lzss and unlzss, compiled from this repository's own sources in progs/src/ through the miniGCC-to-ld chain, with the sources on the ramdisk too so the OS can rebuild the utilities from scratch without leaving the machine. The ramdisk tree is organized by kind: objects/ (ET_REL toolchain), bin/ (Linux ELFs + command path), cvm/ (CVM modules), src/ (C sources), asm/ (miniGCC assembly), docs/.

The four repositories and the self-hosting bootstrap

MiniOS is one of four projects that together make the system: this repository holds the kernel, the boot path and the ramdisk, and the toolchain it carries lives next door.

Repository Role
miniOS this repository: kernel, two-stage boot path, ramdisk, shell, editor
miniGCC C compiler: C to x86-64 AT&T assembly
ld assembler and linker: assembly to a Linux ELF or a CVM module
cvm the CVM / cvm2 bytecode interpreter

To build the whole system from source, clone the other three next to this one:

make sources          # clone the missing repositories from GitHub
make toolchain        # build minigcc, ld and cvm2 from those sources
make                  # rebuild every ramdisk object and os.img

make sources never touches a directory that already exists, so a checkout with local work is left alone. make sources-update pulls the latest commit of each before rebuilding, and make sources-status shows which revision each one is sitting on.

The update contract (make update)

make sources answers "where do the sources come from"; make update answers "bring me the newest ones". The updater lives in tools/update_sources.py and drives every checkout the build consumes, not just the toolchain trio:

make update                 # every checkout: toolchain, browser, interpreters, libraries
make update freedom         # only the browser
make update freedom ld      # only those two
make update-status          # the revision each checkout sits on, no network
make update-list            # the managed checkouts, their mode and their path
make update-rollback        # restore the revisions the last update replaced

The fleet is: minigcc, ld, cvm (the toolchain), freedom (the browser), micropython, cpython, lua (the interpreters), nuklear, nuked-opl3 (the UI and audio libraries), raycastlib, quake2 and pokemon (the reference sources). Each one keeps its mode:

Mode Checkouts What "update" means
track minigcc, ld, cvm, freedom, nuklear, nuked-opl3 fast-forward to the upstream tip
pinned micropython (v1.28.0), cpython (v3.12.11), lua (v5.4.7) held at the release tag; the tag is re-verified and restored when it drifted
reference raycastlib, quake2, pokemon tracked like track, but never required: a missing checkout is reported, not fetched

Freedom is the one checkout that carries a commit of its own: the platform seam (gui/platform.h, the local commit that lets the same browser link against Wayland or MiniOS) that freedom-gui depends on. Upstream keeps rewriting gui/browser_ui.c, so the two meet in a conflict that is resolved by hand inside the FreeDom repository: the seam wins for the host-specific parts, upstream's features enter through the seam's API, and browser_ui.c keeps zero host references.

The safety rules are the contract, not a side effect:

  • Local work is never discarded. A dirty worktree is reported as skipped and left exactly as it is; nothing is ever reset, stashed or force-updated. The Quake 2 upstream carries the MiniOS bug fixes as local edits for exactly that reason.
  • History is never rewritten. A checkout that carries local commits is merged with the upstream tip, so a local commit and the upstream work coexist. A merge that conflicts is aborted, the conflicted files are named, and the checkout is left clean; the port is then done by hand in the sibling repository. UPDATE_STRATEGY=rebase replays the local commits instead, UPDATE_STRATEGY=ff reports a divergence and touches nothing.
  • Every update records the pre-update revision in build/sources-snapshot.json, so make update-rollback puts the fleet back exactly where it was (git reset --keep, which refuses to discard local changes).
  • A shallow checkout is deepened by a bounded number of steps until the fast-forward becomes provable; the depth never grows without a budget.

Each checkout reports one line: the state (updated, current, pinned, repinned, skipped, diverged, conflict, absent, not-a-clone, would-update, failed), the path, and a short detail. The command exits nonzero when a checkout failed or conflicted, so a scripted update never reports success over a broken fleet.

Expected layout: the directory holding this repository can have any name:

src/
├── miniOS/     (this repository)
├── miniGCC/
├── ld/
└── cvm/            with cvm/cvm2 inside

The defaults are MINIGCC_DIR=../miniGCC, LD_DIR=../ld, CVM_REPO_DIR=../cvm and CVM_DIR=$(CVM_REPO_DIR)/cvm2. Point the build somewhere else with MINIGCC_DIR=, LD_DIR=, CVM_REPO_DIR= or CVM_DIR=; change where make sources clones from with MINIGCC_URL=, LD_URL= or CVM_URL=.

Nothing on the ramdisk is a binary you have to take on trust: objects/minigcc.o, objects/ld.o and objects/cvm.o are compiled from the sibling checkouts, and the demo programs (fib, w1, ldhello) are compiled from this repository's own C sources in progs/src/ through the full miniGCC-to-ld chain. The objects under progs/objects/ are build products, not tracked files, so a fresh clone runs make sources first.

The compiler on the ramdisk is self-hosted, in three generations: the host-built generation 1 compiles the miniGCC source, ld links that into the generation 2 compiler, and the generation 2 compiler compiles the source again into the generation 3 assembly that ld links into bin/minigcc.elf, the compiler that ships on the ramdisk. No GNU as/ld is involved anywhere after generation 1. make selfhost verifies the bootstrap fixed point on the host (g3.s == g4.s: the generation 3 binary reproduces its own output of its own source). Inside the OS the self-hosted compiler drives the same edit/compile/link/run loop as objects/minigcc.o.

Repository layout (file to role)

File Role
headers/arch/x86/boot/bootdefs.h every constant shared by the boot path
arch/x86/boot/stage1.S 512-byte boot sector: loads stage 2 over LBA
arch/x86/boot/stage2.S loads the kernel above 1 MB, enters long mode
kernel.c / headers/kernel.h kernel: console, heap, ramdisk, loaders, shell
kernel/shell.c / headers/shell.h shell prompt, command resolution, builtins
kernel/editor.c / headers/editor.h line editor (nano-like: status, goto, search, range listing)
kernel/syscalls.c Linux ABI syscall dispatcher, user pointer validation
kernel/syscalls_proc.c / headers/syscalls_proc.h process syscalls: clone, seccomp, nice, yield, getpid/tid, exit, wait4, kill
kernel/redirect.c shell I/O redirection (>, >>)
kernel/sched.c process management, timer ISR, desktop tick
kernel/vga_fb.c VESA framebuffer desktop, windowed terminal, mouse, WM
net/rtl8139.c / headers/net/rtl8139.h rtl8139 NIC driver: port I/O, PCI, TX/RX, TSC clock
net/net.c / headers/net.h protocol stack: ARP/IP/ICMP/UDP/DNS/TCP, sockets
net/tls.c / net/tls_crypto.c / net/tls_x509.c kernel TLS 1.2 client, crypto, X.509
vma.c / headers/vma.h VMA red-black tree for mmap tracking
fs/ramdisk.c ramdisk filesystem driver
fs/minifs.c MiniFS filesystem driver
fs/kfile.c unified file API (ramdisk + MiniFS)
fs/vfs.c VFS dispatch layer
fs/zip.c ZIP archive read/write (miniz)
drivers/ide.c IDE PIO disk driver
drivers/pcspk.c PC speaker driver (tone, volume)
drivers/sb16.c Sound Blaster 16 DMA driver
drivers/rtc.c CMOS RTC clock driver
tls_roots_src/ + tools/mkroots.sh the 8 embedded CA roots and their generator
tools/tls_test.py / tls_test.c host TLS suite: vectors + full handshakes
kernel/cvm_host.c CVM interpreter + JIT integration in MiniOS
progs/lua/lua_main.c Lua 5.4 entry point (REPL, -e, -l, script modes)
progs/lua/minios.c Lua bindings for MiniOS kernel services
progs/lisp/lisp.c self-contained Lisp interpreter + MiniOS primitives (ring-3 static ELF)
progs/lisp/minigcc.lisp subset C compiler in Lisp (v0.3: multi-function, params, calls, usage/version CLI, ld-ready asm)
progs/src/test.lisp in-OS Lisp suite: language, primitives, toolchain roundtrip
progs/wl/wl_mini.h Wayland-mini wire contract (header-only, ADR-0024)
progs/wl/wlcomp.c ring-3 Wayland-mini compositor (max 8 surfaces)
tools/test_lisp.py host Lisp suite: 49 vectors, zero-warning build
tools/lisp_scoped.sh scoped Lisp gate: rebuild plus 13 targeted mutants
progs/topogpt3/topogpt3.c TopoGPT3 C inference engine (1,999 lines)
progs/topogpt3/topogpt3.fp16 TopoGPT3 float16 model weights (48,930,967 bytes)
progs/topogpt3/vocab.bin GPT-2 BPE vocabulary (50,257 tokens, 421,349 bytes)
progs/ ramdisk contents organized by kind: objects/, bin/, cvm/, src/, asm/, docs/
tools/mkramdisk.py packs progs/ into the ramdisk image
tools/test_bdd.sh / tools/test_http_server.py behavioural suite and its HTTP fixture
progs/src/test_all.sh one-boot comprehensive non-interactive test (103 PASS markers)
mcp/minios_mcp.py MCP bridge: boots the OS and exposes its console as tools
mcp/test_minios_mcp.py unit + QEMU BDD suite for the bridge
mcp/mutate_mcp.sh mutation testing for the bridge
skills/minios/SKILL.md agent skill: the edit/compile/link/run workflow over the bridge
tools/mutate.sh mutation testing

Toolchain kernel-build contract (sibling repos miniGCC/ld/cvm)

The end state is that the kernel itself builds through the hosted chain (minigcc.o + ld.o on the ramdisk), with cvm in lockstep: any asm miniGCC emits, ld assembles/links into both ELF and CVM, and cvm2 runs every bytecode ld generates. The three repos move as one; a gap lands in all three specs together. Feature demand is survey-verified, not assumed: tools/kernel_feature_survey.py scans this tree for function pointers, asm constraints, wide calls, unions, long long, bitfields, privileged mnemonics and section attributes, and every SDD claim about a gap must reproduce through it first.

  • miniGCC landed: D/S extended-asm constraints (fixed homes %rdi/%rsi, scratch pool excludes pinned registers, overflow is fail-closed too many register asm operands, =& earlyclobber accepted; template %N stays full-width, narrow outputs go through literal %%dil/%%di/%%edi stores). Proven by tests/t_asm_ds.c (+neg_asm_ds.c) in test_all.sh, 42/42 green, 5 scoped mutants dead. Still open, in survey order: function pointers (kernel tables vfs_ops_t/syscall dispatch; landed: (*name)(params) declarators for locals/globals/params/members/arrays, call *%r10 codegen, fail-closed arithmetic/callability, proven by tests/t_fnptr.c (+4 neg_fnptr*.c) with 13 scoped mutants dead), >6-arg stack spill (ksyscall takes 7; landed: any fixed count through registers plus ordered stack spill with static parity padding, proven by tests/t_args7.c plus the tools/test_call_align.py probe, pad-inversion mutant dead), unsigned/signed/long long plus user typedef and struct-member capture (lexer folding with multi-declarator reseeds in statements, typedefs and for-init; struct unsigned capture with long-as-8; scalar/chained/fnptr alias records; proven by tests/t_unsigned.c + t_struct_ul.c + t_longlong.c + neg_typedef_arrcont.c with 12 scoped mutants dead, 2 documented equivalents); unions/bitfields are deferred with survey proof (only ring-3 host-built programs use them). Standing gate found while proving A7: miniGCC models plain int as 8 bytes (sizeof(int) == 8, 64-bit wrap) but the kernel needs LP64 (minifs.h superblock unsigned int fields are 4 bytes on disk), so an LP64 follow-up (A8) gates B1; integer </> also stay signed-only (u64 >= 2^63 compares wrong). Reusable probes live in tools/ by contract: tools/kernel_feature_survey.py (survey-verified feature demand, the single source every SDD gap claim must reproduce through) and tools/test_call_align.py (6/7/8-arg direct plus 7-arg indirect stack alignment reporting).
  • ld open: call */jmp * encodings, privileged EA forms (in/out/lidt/lgdt/mov-cr, today documented future work), kernel object/link mode per its own spec.
  • cvm open: indirect-call opcode + ld -f cvm lowering + parity matrix.
  • Method per milestone: SDD spec, TDD failing test, scoped suite + scoped mutants on touched files only; full mutate.sh + test_bdd.sh run once at the very end because they take hours.

Compression tools (lzss / unlzss)

progs/src/lzss.c is a single source that builds two command-path binaries: the linker emits the same program as bin/lzss and bin/unlzss, and the program selects its mode from argv[0] (any invocation path containing unlzss decodes; -d forces decode explicitly).

  • The codec is Okumura LZSS (window LZSS_N 2048, lookahead LZSS_F 17, threshold LZSS_P 1, MSB-first bit stream) so in-OS output interops with a host reference implementation; the window is pre-filled with 0x20 exactly as the reference.
  • The on-disk format is fail-closed: 4-byte magic LZS1, then the original size as a little-endian u32, then the bit stream. unlzss rejects a bad magic, a truncated stream and any declared size larger than the expansion bound derived from the input length (LZSS_EXPAND_NUM/ LZSS_EXPAND_DEN), so a hostile header can never drive an oversized allocation, and a stream that would write past the declared size aborts before touching the output file.
  • The codec works whole-file in memory (bounded, one malloc per side, sized from the input file and the derived expansion bound), compresses only when the result is reported with exact byte counts, and every I/O shortfall is a diagnostic plus a nonzero exit code, never a partial silent write. Past the first input MB the encoder prints one lzss: <bytes>... heartbeat per MB (the match search is O(window) per byte, so a multi-MB file takes a while and must never look wedged); small-file output is a single result line. Proven on DOOM1.WAD (4196020 -> 2349321 bytes, unlzss back byte-identical by hash).

Compression tools (lz4 / unlz4)

progs/src/lz4.c builds bin/lz4 and bin/unlz4 from a single source, with the same argv[0] dispatch as lzss (any invocation path containing unlz4 decodes; -d forces decode). The codec itself lives in the kernel (lz4_kernel.c, the same one MiniFS uses), so the tools are thin syscall front-ends over two MiniOS syscalls, 216 lz4_compress and 255 lz4_decompress, which mirror minifs_compress/minifs_decompress byte for byte. A call passes a user pointer validated to lie inside the user window; a violating pointer returns -EFAULT.

  • The on-disk block is the MiniFS block format, so lz4 output interops with the filesystem's own LZ4 blocks: a 4-byte little-endian original size, then the raw LZ4 stream. lz4_compress refuses to write (returns 0) unless the compressed stream is strictly shorter than the input, and lz4_decompress refuses a header whose declared size exceeds the output capacity or a stream that fails to decode to exactly that size.
  • The front-ends work whole-file in memory (one malloc per side, the output side sized from LZ4_COMPRESSBOUND or the declared size), report exact byte counts, and every I/O shortfall or implausible declared size is a diagnostic plus a nonzero exit code, never a partial silent write.
  • The ld stub set grows the lz4_compress/lz4_decompress entries (216, 217) beside the other MiniOS syscalls, so the toolchain and the ramdisk binary rebuild together.
  • The kernel lz4_kernel.c decompressor handles the literal-only tail of a stream correctly (a valid LZ4 block may end with a final literal sequence and no trailing match), so its own compressor round-trips and its output interops with a host reference decoder.

Zip builtins (unzip / zip)

The shell's unzip and zip builtins read and write ZIP archives through the miniz zip library, compiled into the kernel as a pristine upstream amalgamation (3.0.2) in third_party/miniz/ with the allocator redirected to the kernel heap and stdio/time stripped (MINIZ_NO_STDIO, MINIZ_NO_TIME). miniz_impl.c applies every knob through macros, the same pattern as the stb wrapper; the amalgamated header forward-declares the writer's internal state, so the heap writer's output buffer is exposed through two accessors (mz_zip_writer_mem_ptr/mz_zip_writer_mem_size) defined where the full struct is visible.

  • Usage: zip <out.zip> <file...> stores each file (under its sanitized relative name) with the default compression level; unzip <archive.zip> [dir] extracts into dir (default the cwd), creating missing directories, and unzip -l <archive.zip> lists the entries. Both builtins work whole-file in memory over the unified file API (ramdisk first, MiniFS fallback), matching the compression tools contract: the archive is fully validated before any entry is published, output is written only after the whole archive was read, and every failure path reports a diagnostic and releases. The ld stub set is untouched: the builtins are shell features, not toolchain programs.
  • Entry names are hostile data. Each is normalized to forward slashes, stripped of leading / and ./ repetitions, and rejected when a component is ./.. or empty (zip_sanitize_name), so a crafted archive can never write outside the directory the user named — an absolute name degrades to a relative one, a traversal name is skipped. The BDD fixture etc/hostile.zip (generated by tools/gen_zip_fixtures.py, one entry ../escape.txt beside a plain file, a directory marker and an absolute name) proves escape.txt is never created.
  • etc/host.zip is a second generated fixture: a host-produced archive with a nested directory, proving the extractor interops with a reference ZIP writer and not just its own output. Both fixtures are regenerated from source at build time (fixed timestamps, reproducible) like the desktop icons.
  • Fail-closed surface: a non-zip input is unzip: <f>: not a zip archive, a missing file is unzip: <f>: cannot read, an entry whose declared size does not match what the extractor produced aborts that entry, and a destination that is an existing file is refused. The mutation suite kills a traversal bypass (the hostile fixture), a bad-magic accept and a skipped finalize.

JSON tool (json)

bin/json is a self-contained JSON validator, pretty-printer and query tool built from progs/src/json.c through the miniGCC-to-ld chain; like DOOM and MicroPython it ships on MiniFS (bare-name command at the MiniFS root), not on the size-budgeted ramdisk. It is written in the miniGCC subset, which has no structs, so the parsed value is a flat node table of parallel arrays (js_type/js_num/js_str/js_key/ js_first/js_count/js_next); object members keep their key in js_key and their value in the node itself.

  • Usage: json <file> validates and pretty-prints; json <file> <path> prints the value at a dotted path (.a.b, .a.3, bare .a). A missing path is json: <path>: not found with exit 1, never a crash.
  • The parser is fail-closed: truncated input, a trailing non-whitespace token, an unbalanced }/] and an unknown escape all report json: <file>: invalid JSON with exit 1. String escapes (\n \t \r \b \f \" \\ \/, and \u mapped to ?) decode into a bounded string pool, and the pretty-printer re-escapes them so its output is itself valid JSON.
  • The node table, string pool and query segment are all size-bounded by named constants (JS_MAX_NODES, JS_POOL); an input that would exceed a bound is a diagnostic plus exit 1, never a silent overflow.
  • cJSON (single-file, struct-based) was tried as a portable engine and does not compile under miniGCC (structs, ->, double, CJSON_PUBLIC), which is why this hand-rolled flat-table parser exists.

Encryption tool (aes / unaes)

progs/src/aes.c builds bin/aes and bin/un aes from a single source with the same argv[0] dispatch as the other command pairs (a path containing unaes decrypts; -d forces decrypt). Like DOOM, MicroPython and json it ships on MiniFS (bare-name commands at the MiniFS root) instead of the size-budgeted ramdisk.

  • The cipher is AES-256 (NIST FIPS-197) written in the miniGCC subset: no structs, flat int arrays masked to bytes at every step, and an S-box generated procedurally from the GF(2^8) multiplicative inverse plus the FIPS-197 affine transform, so the file carries no magic tables. Round expansion follows FIPS-197 for Nk=8/Nr=14, including the extra SubWord pass every Nk/2 words.
  • The mode is CTR (NIST SP 800-38A): no padding, encrypt and decrypt share one code path, and the big-endian counter increments over the full block. Usage: aes [-d] <key-hex64> <nonce-hex32> <src> <dst>; a nonce must never repeat under the same key. CTR gives confidentiality only, not authentication - a flipped ciphertext byte flips the matching plaintext byte, so integrity needs a MAC layered above this tool.
  • The container is fail-closed: 4-byte magic AES1, then the original size as a little-endian u32, then the raw keystream XOR. Decoding refuses a bad magic, a truncated header, and any body whose length does not equal the declared size exactly; key and nonce hex are length- and alphabet- validated before anything runs.
  • Host verification lives in tests/host_aes.sh: the NIST F.5.5 CTR-AES256 known answer, byte-for-byte ciphertext equality against OpenSSL across a multi-block stream, reverse-direction interop (OpenSSL ciphertext decoded by unaes), dispatch modes, empty input, and the fail-closed set. Five one-line mutants of the codec (ShiftRows drop, polynomial, affine constant, AES-256 extra SubWord, size-mismatch check) all die against it.

System monitor (mtop)

progs/src/mtop.c builds bin/mtop.elf plus the bare-name copy bin/mtop (the topogpt3 idiom, so plain mtop resolves through the command path) through the miniGCC-to-ld chain from the same conservative subset as json/cp (int/long/char only, no structs, output through write so layout never depends on puts newline behavior, raw syscall inline asm only with 3 or fewer arguments, which is all miniGCC supports: register pinning such as register long r10 __asm__("r10") is rejected, so every MINFO call carries at most a selector plus two out-words). Usage mtop [frames] [interval_ms] (0 runs until quit, -1 draws one snapshot, interval clamped to 100..5000 ms); quit keys are q/Q/ ESC plus Ctrl+C/Ctrl+D through a nonblocking SYS_GETC_RAW (236) poll, so while it runs the monitor owns the keyboard focus like the fullscreen games do. Panels speak plain language (RAM ocupada X de Y, CPU en uso Z%, no syscall jargon); etc/alias carries the matching mtop=bin/mtop entry.

  • Figures come from the MINFO syscall (251, MINIOS_SYS_MINFO): 0 = heap used/free KB, 1 = ramdisk used/cap KB, 2 = MiniFS free/total blocks, 3 = cpu total/idle 100 Hz ticks, 4 = cpu count/uptime seconds, 5 = clear the caller's terminal view, 6 = sleep milliseconds. CPU busy percent is (dt-didle)*100/dt between two reads of selector 3; idle ticks come from a per-CPU counter bumped in the timer ISR when it finds no process on that CPU. Every value is range-checked before display, so a foreign kernel answering 251 with other semantics degrades to plain unavailable instead of showing garbage.
  • Selector 6 exists because a polling refresh loop never lets the CPU idle and would pin its own meter at 100%: the caller parks on a wait queue (sleep_on, futex discipline) woken by a 100 Hz audio-tick listener, in chunks of at most 50 ms so key checks stay responsive. Registration happens at boot next to the other tick listeners; without it sel 6 fails closed with -EIO. Number 251 shadows Linux ioprio_set: documented DEVIATION (no port traps ioprio, trapped calls fail closed on selector validation), listed in tools/check_abi_numbers.py, ABI bumped to v11 with the manifest regenerated at build time.
  • Frames after the first clear the screen through selector 5, which calls the new term_clear (framebuffer logical-line ring plus in-progress line reset, viewport snapped live, repaint; parked twin snapshots are unaffected until they refocus): a true redraw where the terminal is live, ANSI clear on the serial console as fallback. The clear builtin was a silent no-op on the desktop (it only wiped the legacy text buffer), so it takes the same path plus the ANSI sequence, which the framebuffer terminal swallows without garbage.
  • DISK throughput is measured live by reading a ramdisk probe opened once and rewound every frame: the ld fopen stub keeps a 5-slot table that fclose never releases (sibling-ld bug, tracked here), so open-per-frame dies on the 5th frame. NET is a TCP socket create/close plus a localhost DNS round trip, probed on frame 1 and every 10th frame and cached between (an unanswered DNS costs seconds).
  • Each sampled panel keeps a 32-deep history drawn as an auto-scaled sparkline ( .:-=+*#%@) beside a [####--] bar scaled to the observed maximum; UPTIME and CMOS clock (SYS_RTC 212) head every frame.
  • Degradation is total: on a host without MiniOS syscalls (or before the network is up) every failed probe prints n/a with its cause and the program still renders and exits 0, so the same binary smoke-tests on Linux (mtop -1) and live under QEMU (run bin/mtop.elf 3 200, BDD-pinned output shape).