Printable field manual
Read this page straight through or print it as the desk reference. It is arranged for a live SlOS session: command, observation, event, proof, source.
Reading order
| Order | Route | Use |
|---|---|---|
| 1 | Index | Establish the voice of the machine: a small x86-32 OS with a causal DAG, durable history, timelines, actors, and a restrained manual surface. |
| 2 | Manual | Read the structured reference before operating: identity, history, time travel, web explorer, apps, commands, and source map. |
| 3 | Causality laboratory | Study event records, Lamport time, parent edges, replay, journal proofs, and federation. |
| 4 | Subsystem chapters | Read each subsystem with its role, source files, and command that makes it visible. |
| 5 | Source plates | Inspect verified excerpts from causal.c, cjournal.c, replay.c, httpd.c, scrub.c, and timeline.c. |
| 6 | Glossary and source atlas | Pair terms with implementation files before changing vocabulary or explaining internals. |
| 7 | Execution walks | Follow prompt-to-device and prompt-to-graph paths with transcripts. |
| 8 | Operator labs | Run QEMU exercises and compare expected observations with live output, including remote-shell operation. |
| 9 | Showcase | Watch recorded sessions and map each clip to commands and source. |
| 10 | Showcase notes | Use chapter notes as prompts for live reproduction. |
| 11 | Reading room | Place the design beside logical clocks, event sourcing, provenance, actors, and time-travel debugging. |
| 12 | Field manual | Print this continuous route and use it beside the running kernel. |
Section 1
SlOS is operated as a causal machine. Build it, boot it, issue one command, and then ask the kernel what changed and why.
The recent causal ring is the first instrument. The persistent cjournal is the durable instrument. cwatch is the live stream; scrub and /causal are visual causal instruments; wm is the framebuffer desktop for live per-core and system panels. For day-to-day work, telnetd and noiseshd let the operator use the machine from another terminal.
Section 2
Use make for the default x86 build. Use make run for graphical QEMU, make run-nographic for serial operation, and make iso to create a GRUB ISO when the host has the required tools.
QEMU supplies VirtIO block and network devices. The x86 run target forwards host port 8080 to SlOS port 80, so the httpd dashboard and /causal explorer are reachable from the host after httpd starts.
Section 3
An event has an ID, node hash, Lamport time, wall tick, type, subsystem, description, optional payload, schema data, and up to four parents. Parent IDs turn logs into a DAG.
Use events, why, trace, graph, blast, cpath, and cdot for the hot graph. Use events -a, cq -a, why -a, and trace -a when the answer must read through durable journal segments.
Section 4
cjournal persists causal events to SlFS segments. The journal records segment indexes, event hashes, Merkle roots, and proof material so archived history can be queried and checked.
Use journal recent, find, type, subsystem, stats, filter, verify, json, selfcheck, proof-health, and epoch-proof. Use cq selectors for typed query work: type=, subsystem=, desc~, since=, until=, id=, segment=, and limit=.
Section 5
Replay reconstructs state by scanning events forward to a tick. scrub makes this operator-visible: scrub for a TUI, scrub <tick> for a single frame, scrub event for focus, scrub diff for deltas, and scrub json for machine-readable state.
whatif is counterfactual rather than restorative. It asks which downstream effects would be eliminated if one event were dropped from analysis.
Section 6
Under the default QEMU run, telnetd is reachable from the host at localhost:2323 and noiseshd at localhost:5200. On real hardware or bridged networking, use guest ports 23 and 5200. The encrypted path uses the host script scripts/noise-shell-client.py.
The terminal path is honest: telnet plus a small unauthenticated encrypted channel, not OpenSSH. The useful part is the redirection layer: ANSI output, cooked-key input, telnet NAWS sizing, a remote full-screen editor, coherent file commands, and detached services that survive disconnect.
Section 7
Timelines provide common controls for graph-native applications: tl list, show, rewind, forward, at, mark, and tail. Notes, mail, editor, process views, and scheduled commands build on this model.
Actors, mesh, and federation expose named message endpoints, routes, encrypted peer channels, and remote graph or actor delivery. Use actors, send, recv, routes, mesh, federation, ping, netstat, and arp as field instruments.
Section 8
smp offload <n> creates unpinned ap_offloadable kernel tasks; the BSP may retarget them to idle APs. This is cooperative kernel-task offload, not preemptive migration or arbitrary user-task load balancing.
Use cpu for a per-core table, cwatch tail to see scheduler offload events appear in the graph, and wm when the best view is the 1024x768 framebuffer desktop.
Section 9
httpd serves both a dashboard and the /causal explorer. /causal draws a live SVG DAG and lets the reader focus events and scrub state. The companion endpoints are /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot.
Treat the web view as another manual plate: it is useful because every visible field has a source path in programs/httpd.c and a corresponding shell command.
Command card
events 10 | List recent causal events. |
events -a find switch 8 | Search durable journal text. |
why --md last | Export a Markdown causal chain. |
trace -a last | Read-through ancestry from the journal. |
cq -a subsystem=sched limit=20 -l | Archive query with selectors and long output. |
journal proof-health --json-ish | Check journal proof health. |
cpath selftest; cdot last effects | Inspect causal paths and DOT output. |
ctop 128; cwatch tail; lens save demo events 5; lens run demo | Monitor activity, live-tail the graph, and reuse named causal queries. |
cpu; smp offload 6; events | tail -n 5 | Watch cooperative AP offload and its scheduler events. |
wm | Open the tiled framebuffer desktop; Tab focuses panels, q/Esc exits. |
ps | grep shell; help | grep Network | Use sequential shell pipelines; intermediate output is capped at 4096 bytes. |
telnet localhost 2323; python3 scripts/noise-shell-client.py localhost 5200 | Enter SlOS remotely: telnet is plain; noiseshd is X25519 plus ChaCha20-Poly1305 but not server-authenticated. |
termsize; edit /home/day.sl; run /home/day.sl; exit | Exercise terminal sizing, remote full-screen editor input, persistent files, slosh execution, and session close. |
mkdir /home/day; write /home/day/file persistent; write /tmp/scratch.txt volatile; cat /home/day/file | Remember the overlay rule: /home persists to SlFS, /tmp and relative paths are RAM scratch. |
chatd start; chatd status | Run the multi-user TCP chat service on host-forwarded port 6667. |
scrub event last; scrub diff 100 99999; scrub json | Inspect time-travel state. |
tl show notes; note search term; mail unread; schedule 100 events 5 | Operate timeline applications. |
httpd | Serve the web explorer, then open http://localhost:8080/causal from the host. |
Field rule: do not trust a term until you can name its command, archived query, proof surface, and source file.