SlOS operating manual / reference edition
SlOS is a bare-metal x86-32 operating system whose operating record is a causal DAG. This manual describes how to boot it, ask what happened, query durable history, scrub time, and inspect the source plates.
Chapter 1
SlOS defaults to a freestanding x86-32 Multiboot build, with additional x86-64 and ARM64 Makefile targets; the x86 path runs in QEMU with VirtIO block and network devices and supplies its own C runtime inside the kernel and user programs.
The distinguishing device is the causal graph. Scheduler actions, syscalls, filesystem work, network packets, actor messages, mesh traffic, and application changes are recorded as events with Lamport time and parent event IDs.
Chapter 2
The hot graph is a bounded in-memory ring for immediate inspection. The persistent causal journal, cjournal, spills history to SlFS segments with event hashes, Merkle roots, and epoch proofs.
Use read-through commands when an event has aged out of the ring: events -a, cq -a, why -a, trace -a, and journal subcommands consult archived history instead of only live memory.
Chapter 3
Replay reconstructs state by scanning causal events up to a chosen tick. The scrub program is the operator surface: a TUI for moving through ticks, focusing on events, comparing ticks, and exporting JSON.
Counterfactual analysis is explicit. whatif and scrub whatif drop an event in analysis and report the downstream effects that would disappear.
Chapter 4
The user-space httpd program serves a live dashboard and a /causal explorer. The explorer draws an SVG causal DAG, lets the reader focus events, and mirrors the time-travel state used by scrub.
The API surface is small and inspectable: /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot.
Chapter 5
telnetd listens on guest port 23, forwarded by the default QEMU run to localhost:2323. noiseshd listens on port 5200 and uses an ephemeral X25519 exchange followed by ChaCha20-Poly1305 frames. It is a from-scratch confidential channel, not OpenSSH, and it does not yet authenticate the server.
The remote shell is more than line input. Per-task I/O hooks redirect console output and input, console cursor/clear/colour emit ANSI, SYS_TERM_GETKEY decodes arrows and Ctrl combinations from the byte stream, and telnet NAWS supplies terminal size for editor and pager sessions.
Use /home/... for persistent work and /tmp or relative paths for RAM scratch. Long-lived service commands such as httpd detach from the session, so a service started remotely can survive exit or a dropped connection.
Chapter 6
Timelines are named chains of causal events. Notes, mail, the editor, process timeline viewing, and scheduled commands treat application state as replayable history rather than opaque mutable files.
Use tl list/show/rewind/forward/at/mark/tail as the shared manual controls, then operate note, mail, edit, proc, schedule, and scheduled for application-specific views.
Chapter 7
Four-core boots now have a narrow automatic work lane: smp offload <n> creates unpinned ap_offloadable kernel tasks, and the BSP may retarget them to idle application processors. The lane is cooperative and kernel-task-only; arbitrary user tasks and long-running kernel loops stay on the BSP.
The cpu command prints a per-core scheduler snapshot, and wm turns the 1024x768 framebuffer into a tiled desktop with live CPU, causal-tail, task, and memory/system panels. cwatch or cwatch tail streams new causal events until a key is pressed.
Chapter 8
Actors are named message endpoints with local mailboxes and routes that can cross the mesh. Mesh and federation commands expose peer identity, routing, remote actor delivery, and causal graph exchange.
Proof commands make the archive auditable: prove, cproof, verify proof-health, journal json selfcheck, journal verify, journal proof-health, and cq -a epoch-proof inspect hash chains and epoch roots.
Boot card
make
make run
make run-nographic
make isoOperator card
slos:/$ events 10
slos:/$ why last
slos:/$ trace -a last
slos:/$ cq -a subsystem=sched limit=8 -l
slos:/$ journal proof-health --json-ish
slos:/$ cwatch tail --once
slos:/$ cpu
slos:/$ scrub event last
slos:/$ httpdRemote card
Use telnet for the plain path and the bundled Python client for the encrypted path. The encrypted shell is confidential but not server-authenticated yet.
# host terminal, with make run defaults
telnet localhost 2323
# or encrypted from the SlOS repo
python3 scripts/noise-shell-client.py localhost 5200
# SlOS shell
termsize
edit /home/day/hello.sl
run /home/day/hello.sl
httpd
exit
# host terminal
curl http://localhost:8080/Chapter 9
Commands are listed as operator surfaces, not as implementation promises. The source paths in the next section show where each surface is implemented.
events [N] | List recent events from the live causal ring. |
why <id|last> | Explain an event by showing its causal chain. why --md exports the chain as Markdown. |
trace <id>; trace -a <id|first|last> | Walk parent events backward through the DAG; -a reads through the durable journal. |
graph [N] | Draw a compact ASCII DAG of recent events. |
blast <id> | Walk downstream effects caused by an event. |
cpath <a> <b> | Find a causal path from event a to event b; cpath common finds a nearest common ancestor. |
cdot <id|last> [effects] | Emit Graphviz DOT for causes or downstream effects. |
cwatch | cwatch tail [--once] | Live-tail the causal graph from the current head until any key is pressed; --once prints a bounded sample for automation. |
triage | One-screen incident verdict (HEALTHY/DEGRADED/CRITICAL) plus one next action, composing entropy, blame, critical-path, journal, and contract checks. |
cbisect <metric> <N> | git-bisect over replayable history: binary-search the tick timeline for the earliest tick a cumulative metric (events/tasks/net/fs/actors/syscalls) reached N, reconstructing state per probe via replay. |
cdb break ...; cdb run|bt|step|print | A stateful debugger for causation: predicate breakpoints, a persistent cursor, bt walks causes and step walks effects across shell calls. |
cprof [window] | Profile causal flow across cause-to-effect subsystem boundaries, marking cross-subsystem crossings. |
attest <id|last>; attest verify <id> | Emit a self-contained Ed25519-signed receipt for one outcome, and re-verify its signature against the node key. |
capsule <id|last> | Write a portable causal incident bundle (event slice, hash, and proof) to SlFS at /capsule/<id>.txt. |
why -r <id|last> | Walk the cause chain, tagging each hop with its origin node (local or imported). |
journal recent|find|type|subsystem|stats|filter|verify|json selfcheck|proof-health | Operate the persistent causal journal on SlFS. |
events -a [N] | Browse archived events after they spill from the live ring. |
cq type=T subsystem=S desc~TEXT since=T until=T id=N limit=N -l --json-ish | Query the live causal ring with selectors and long or json-ish output. |
cq -a ... | Run the same style of query against archived journal history. |
cq -a id=N epoch-proof --json-ish | Fetch an epoch proof for one archived event. |
lens save <name> <command...>; lens list; lens run <name> | Persist named causal queries to SlFS. |
grep|head|tail|wc [file] | Read from a file or, with no file argument, from pipeline stdin. |
cmd1 | cmd2 [| cmd3] | Sequential shell pipelines. Each stage completes into a 4096-byte buffer before the next stage reads it; this is not a concurrent POSIX pipe. |
tally [-f N] <file> | Aggregate pipeline output by whole line or field, for example journal type sched 50 | tally. |
replay | Reconstruct recorded state from causal events. |
rewind | Move reconstructed state back through event history. |
scrub | Open the full-screen causal time-travel inspector. |
scrub <tick> | Print reconstructed state at a tick. |
scrub event <id|last> | Focus one event, its parents, and its effects. |
scrub diff <a> <b> | Show state deltas between two ticks. |
scrub json [tick] | Emit reconstructed state as JSON. |
whatif summary <id>; scrub whatif <id|last> | Drop one event in analysis and report eliminated downstream effects. |
telnet localhost 2323 | Host-side entry to telnetd through the default QEMU host forward; on real or bridged networking use guest port 23. |
python3 scripts/noise-shell-client.py localhost 5200 | Host-side client for noiseshd. The channel is X25519 plus ChaCha20-Poly1305, currently without server authentication. |
exit; logout | Close the current remote shell session cleanly. Multiple sessions may be open concurrently. |
termsize | Report the terminal size SlOS is using; telnet NAWS can update it, otherwise the safe default is 80x25. |
edit /home/day.txt | Open the full-screen editor through terminal redirection. Arrow keys and Ctrl-S/Ctrl-Q are decoded from the stream. |
cat|more|less|head|tail|wc|grep|cp|mv|rm|mkdir|touch|write|cd|pwd | Operate one coherent namespace: /tmp and relative paths are RAM scratch; other absolute paths such as /home/... persist to SlFS. |
run /home/script.sl; slosh | Run slosh scripts or the REPL. Functions, $1..$9 parameters, return, recursion, for loops, and shell-command passthrough are available. |
smp; cpus | Show CPU inventory and APIC status. |
cpu | Print active state, current task/PID, context-switch count, and idle/busy state for each CPU. |
smp runon <cpu> | Create an AP-pinned kernel demo task and wake that CPU by IPI. |
smp offload <n> | Create n unpinned AP-offloadable kernel tasks; the BSP scheduler assigns eligible queued work to idle APs. |
wm | Open the 1024x768 framebuffer tiled desktop: CPU monitor, causal tail, task list, memory/system bars; Tab focuses, q/Esc exits. |
chatd [start|stop|status] | Run the IRC-lite TCP chat server on port 6667, up to eight clients, with /nick and join/leave broadcast. |
httpd | Serve the live dashboard, /causal explorer, and causal API endpoints. |
tl list|show|rewind|forward|at|mark|tail | Navigate named application event timelines. |
note; mail; edit; proc; schedule; scheduled | Operate graph-native notes, mail, editor, process timelines, and future commands. |
actors; send; recv; routes; watch | Inspect and use actor mailboxes and routing. |
mesh; federation; routes; ping; netstat; arp | Inspect peer transport, remote delivery, and network state. |
prove; cproof; verify proof-health; journal proof-health | Inspect causal proofs and journal proof health. |
causal; learn; ctop | Read the built-in glossary, run the guided causality tour, and monitor causal activity. |
doom; rogue; browser; wget; crash | Run representative programs and Kernel Surgeon demonstrations. |
Desktop plate
wm, cpu, and cwatch expose the same
operating facts at different scales: framebuffer dashboard, table snapshot,
and live graph tail.
slos:/$ wm
# tiled 1024x768 framebuffer desktop
# Tab cycles focus; q/Esc returns to the shell
slos:/$ cpu
CPU ACTIVE CURRENT SWITCHES STATE
0 yes shell 1842 busy
1 yes idle/1 17 idle
slos:/$ cwatch tail --once
#8842 SCHED sched offload pid=47 to=cpu1HTTP plate
Run httpd inside SlOS and open the forwarded QEMU port. The dashboard links
to /causal; API routes provide state, recent events, graph JSON, and DOT.
GET /causal
GET /api/causal/state
GET /api/causal/recent
GET /api/causal/graph
GET /api/causal/dotField rule: use live commands for immediacy, archived commands for durability, proof commands for integrity, and scrub or /causal when the question is visual.
Appendix A
| Area | Files | Read for |
|---|---|---|
| Causal graph | include/causal.h; kernel/graph/causal.c | Event record, Lamport clock, parent edges, hot ring, and read-through cache. |
| Persistent journal | include/cjournal.h; kernel/graph/cjournal.c | SlFS segment files, indexes, hashes, Merkle roots, and epoch proofs. |
| Replay and what-if | include/replay.h; kernel/graph/replay.c; kernel/graph/whatif.c; programs/scrub.c | State reconstruction, scrub TUI, diffs, JSON, and counterfactual impact. |
| Query and command surface | programs/shell.c; kernel/apps/shell.c; kernel/apps/cmd_graph.c | Shell commands including cq, journal, cwatch, cpath, cdot, lens, pipelines, tally, learn, and ctop. |
| Remote terminal | docs/remote-access.md; kernel/apps/telnetd.c; kernel/core/syscall.c; kernel/drivers/console.c; programs/editor.c; scripts/noise-shell-client.py | telnetd/noiseshd, terminal redirection, cooked-key input, console sizing, ANSI output, remote editor, and host encrypted-shell client. |
| Files and slosh | kernel/apps/cmd_files.c; include/fs_route.h; kernel/apps/script.c; docs/scripting.md | Overlay namespace, persistent /home paths, RAM scratch, file commands, slosh functions, recursion, for loops, and shell passthrough. |
| SMP and window manager | kernel/core/task.c; kernel/core/smp.c; kernel/apps/cmd_apps.c; include/gfx.h | Opt-in AP offload, per-CPU snapshots, and the 1024x768 wm dashboard. |
| Web explorer | programs/httpd.c | HTTP dashboard, /causal page, and /api/causal endpoints. |
| Timelines and apps | kernel/graph/timeline.c; kernel/apps/notes.c; kernel/apps/mail.c; programs/editor.c; kernel/apps/sched_app.c | Event-backed applications and timeline navigation. |
| Mesh and proofs | kernel/graph/actor.c; kernel/graph/mesh.c; kernel/graph/federation.c; kernel/graph/prove.c | Named actors, encrypted peer channels, remote delivery, and verification. |