01 / Causal graph
Every significant action has parents.
Scheduler switches, syscalls, filesystem operations, packets, actor messages, mesh events, shell commands, and application events enter a typed DAG with Lamport time and parent edges.
SlOS operating manual / current field edition
A kernel that keeps the chain of cause.
SlOS is a bare-metal x86-32 operating system organized around a causal graph. Each meaningful operation records what happened, when it happened, and which prior events gave it cause. The record is no longer only live memory: SlOS now persists, queries, verifies, replays, and serves that history over HTTP.
General description
A small workstation manual for an inspectable machine.
SlOS brings up its own tables, interrupts, paging, heap, scheduler, syscalls, filesystems, VirtIO drivers, TCP/IP, HTTP service, actors, encrypted mesh, and graph-native applications. Its distinguishing instrument is the causal graph: a single directed history spanning kernel, userspace, storage, network, and application state.
Flagship visual / wm
A tiled desktop built from kernel instruments.
The wm command switches to the 1024x768x32 framebuffer and presents
a keyboard-driven desktop: live per-CPU status, causal event tail, task list,
and memory/system bars. It is still deliberately simple -- fixed tiled panels,
Tab focus, and q/Esc exit -- but it makes the causal
machine visible at a glance.
slos:/$ wm
SlOS WM: 1024x768 tiled desktop
Tab: focus next q/Esc: exit
+ CPU monitor: CPU0..CPU3 active/current task/switches
+ Causal tail: live recent events
+ Task list: PID, state, priority, name
+ System: uptime, heap, frames, event ring bars02 / Durable history
The graph survives reboot.
cjournal spills aged events from the hot ring into SlFS segment files with per-event hashes, Merkle sidecars, epoch roots, and searchable indexes.
03 / Replay
State can be reconstructed at a tick.
rewind, replay, scrub, and whatif read the same event material. The Causal Inspector focuses the DAG, diffs two ticks, and reports counterfactual blast radius.
04 / Window manager
The framebuffer now has a live desktop.
wm is a keyboard-driven tiled desktop on the 1024x768 framebuffer: CPU monitor, causal tail, task list, and memory/system panels in one inspectable screen.
05 / SMP
Idle APs can take opt-in kernel work.
The BSP can auto-offload queued ap_offloadable kernel tasks to idle application processors. It is cooperative and kernel-task-only, not arbitrary load balancing.
06 / Web explorer + federation
The machine serves its own causality.
The userspace httpd exposes /causal, an interactive SVG DAG with a time-travel scrubber. Actors, Noise-encrypted mesh, and federation carry the same causal vocabulary between peers.
07 / Trust
History you can prove to another machine.
A per-node Ed25519 key signs verified epoch roots. Over the encrypted mesh, peers exchange signing keys and signed roots; the receiver checks the signature against the peer key, so shared causal history is attributable to that node.
08 / Remote workstation
Connect from another host and work.
telnetd and a Noise-encrypted shell expose SlOS over TCP. A terminal-redirection layer carries the full-screen editor and ANSI apps over the wire, sized to your terminal via NAWS. Paths under /home persist, slosh has functions and recursion, and services you start survive disconnect.
Remote workstation
Connect from another host and actually work.
telnetd and a Noise-encrypted shell (noiseshd,
X25519 + ChaCha20-Poly1305) expose SlOS over TCP. A terminal-redirection
layer carries the full-screen edit editor and ANSI apps over the
connection, sized to your terminal through telnet NAWS. Paths under
/home persist to SlFS across reboot; slosh has grown
functions, recursion, and shell-command passthrough; and a service you start
in a session keeps running after you disconnect. It is telnet and a
from-scratch encrypted channel -- not OpenSSH -- and the machine is still a
single trust domain, but you can edit, run, and serve from your own keyboard.
host:$ telnet localhost 2323 # or the guest IP on port 23
slos:/$ uname
SlOS 0.1.0 (Slepp Operating System) i686 x86
slos:/$ edit /home/proj/hello.sl # full-screen editor, over the wire
slos:/$ run /home/proj/hello.sl
hello from a real SlOS day
slos:/$ httpd # start a background service
[httpd] Started (pid 35) -- http://localhost:8080/
slos:/$ exit # ...the server keeps running
host:$ curl http://localhost:8080/ # reachable after you disconnectFlagship instrument
The Web Causal Explorer is served by the operating system itself.
Start httpd inside SlOS and open /causal. The page renders
the live causal DAG as an in-browser SVG, laid out by causal depth and coloured
by event type. A slider reconstructs past system state at any tick. Clicking a
node highlights causes in blue and effects in yellow.
slos:/$ httpd
[httpd] Started (pid 18) — http://10.0.2.15/ (host: http://localhost:8080/)
[httpd] Listening on port 80 — dashboard at http://<ip>/
host:$ curl http://10.0.2.15/api/causal/state?tick=18400
{"tick":18400,"total_events":4218,"tasks":{"alive":9,"created":31,"exited":22},"io":{"syscalls":701,"fs":211,"net_tx":44,"net_rx":88,"actor_msgs":37},"active_tasks":[{"pid":31,"name":"shell"}],"recent_events":[4215,4216,4217,4218]}
host:$ curl http://10.0.2.15/api/causal/graph
{"nodes":[{"id":4219,"tick":18401,"type":"shell","subsystem":"shell","desc":"command: note add field report","remote":false}],"edges":[{"from":4219,"to":4220}]}
Open http://10.0.2.15/causal
live SVG DAG + time-travel scrubber + click-to-focusSMP and live causality
Offload decisions become evidence.
smp offload <n> creates unpinned, AP-safe kernel tasks.
The BSP scheduler may retarget them to idle CPUs 1-3 and records the decision
as causal scheduler events. This is opt-in cooperative offload, not AP timer
preemption or user-task migration.
slos:/$ smp offload 6
created 6 AP-offloadable kernel tasks
[ap] task ran on CPU 1
[ap] task ran on CPU 2
[ap] task ran on CPU 3
slos:/$ cpu
CPU ACTIVE CURRENT SWITCHES STATE
0 yes shell 1842 busy
1 yes ap-demo 17 busy
2 yes idle/2 14 idle
3 yes idle/3 13 idle
slos:/$ cwatch tail
#8842 SCHED sched offload pid=47 to=cpu1Learning routes
Begin from an observable command.
Each route starts with an operator surface, then names the source files that make the result possible. Causality is the preferred first route for this edition.
| Causality laboratory | Live ring, archived journal, CQ selectors, proofs, scrub, whatif, and the web DAG explorer. |
| Guided concept trails | Routes through boot, commands, causal graph inspection, replay, networking, and applications. |
| Subsystem chapters | Source paths, commands, dependencies, and operator watch points for each kernel area. |
| Source atlas | Files and listings for graph, journal, replay, shell, httpd, userspace, and drivers. |
| Showcase plates | Boot, persistence, productivity, mesh, distributed DOOM, and graph-native applications. |
| Field manual | Continuous manual reading order for printing or long-form study. |
| Reading room | Research lineage: logical clocks, event sourcing, provenance, replay, actors, and limits. |
| Glossary | Operating-system and causal-graph terms mapped to SlOS commands and source files. |
System measurements
Current field notes
| Target | i686 bare metal; QEMU or hardware via Multiboot |
| Build | make, make run, make run-nographic |
| Hot causal ring | 16,384 live events |
| Event types | SCHED, MEM, FS, NET, SYSCALL, SHELL, ACTOR, MESH, IO, USER |
| Journal storage | SlFS /causal segments, 512 events each |
| Integrity | per-event hashes, Merkle sidecars, epoch proofs |
| Web surface | /causal and /api/causal/{state,recent,graph,dot} |
| SMP lane | 4 CPUs; cooperative auto-offload for ap_offloadable kernel tasks |
| Framebuffer UI | wm tiled desktop at 1024x768x32 |
| TCP services | httpd, telnetd :23, Noise-encrypted shell :5200, chatd :6667 |
| Remote workstation | full-screen editor over the wire, NAWS terminal sizing, daemon survival |
| Scripting | slosh: functions, recursion, for-loops, shell-command passthrough |
| Filesystem | coherent namespace; /home persists across reboot, /tmp is scratch |
| Applications | timelines, notes, mail, editor, scheduler, wm, DOOM |
System plate A
Causal map
shell command
->
syscall event
->
fs / net / actor event
hot ring
->
cjournal segment
->
proof + read-through query
event DAG
->
replay at tick
->
scrub / web explorer
System plate B
Field commands
events 10
why last
why --md last
why -a <event-id>
trace <event-id>
blast <event-id>
cpath <ancestor-id> <descendant-id>
cpath common <a> <b>
cdot last effects
journal stats
journal proof-health
cq -a type=fs desc~notes limit=5 -l
ctop 128
cwatch tail
cpu
smp offload 6
ps | grep shell
events | tail -n 5
chatd start
lens save fsnotes cq -a type=fs desc~notes limit=8
scrub event last
scrub whatif lastLive and archived query
Ask why, even after eviction.
slos:/$ events 6
ID TICK TYPE DESCRIPTION
4219 18401 shell command: note add field report
4220 18401 fs write /notes.db
4221 18402 user notes event appended
4222 18402 syscall write pid=31
slos:/$ why --md last
# Why event 4222
- **[4222]** syscall: write pid=31
- **[4221]** notes: notes event appended
- **[4220]** fs: write /notes.db
slos:/$ why -a 1042
Journal trace for #1042
#1042 T+9112 shell command: wget /index.html
#1040 T+9109 tcp rx ack
#1036 T+9098 net packet rxDurable journal
Search and verify history.
slos:/$ journal stats
Journal stats: 12288 persisted events by type
sched 4180
fs 2107
net 903
syscall 3721
slos:/$ cq -a type=fs desc~notes limit=3 -l
Event #3182
Tick: T+14211
Type: fs
Source: journal
Segment: 00000006
slos:/$ journal proof-health
journal proof-health: PASS segments=24 hash=24/24 root=24/24Time travel
Reconstruct a previous machine.
slos:/$ scrub 18400
SlOS Causal Time-Travel tick 18400 / 18402
[=======================================-]
Reconstructed state (replay of 4218 events):
tasks: alive 9 created 31 exited 22
io: syscalls 701 fs 211 net tx/rx 44/88 actor msgs 37
Active tasks (9):
[pid 31] shell
Recent events (8): #4215 #4216 #4217 #4218 #4219 #4220 #4221 #4222
slos:/$ scrub event last
Event #4222 focus
type=SYSCALL subsystem=syscall tick=T+18402
origin: node=0x0 (local)
desc: write pid=31
Caused by (parents):
#4221 notes: notes event appended
#4220 fs: write /notes.db
Led to (effects):
(no downstream effects)
slos:/$ scrub whatif last
whatif: drop #4222 (syscall) -> 0 events eliminated, verdict: NO IMPACTtypedef struct {
uint32_t id;
uint32_t node_hash;
causal_time_t time;
causal_type_t type;
char subsystem[16];
char desc[CAUSAL_DESC_LEN];
uint8_t payload[CAUSAL_PAYLOAD_LEN];
uint32_t payload_len;
uint8_t payload_hash[32];
bool payload_hash_valid;
uint16_t schema_id;
uint8_t schema_version;
uint32_t parents[CAUSAL_MAX_PARENTS];
uint8_t num_parents;
uint16_t child_count;
} causal_event_t;#define CJOURNAL_MAX_FILES 32
#define CJOURNAL_EVENTS_PER_FILE 512
#define CJOURNAL_DIR "/causal"
#define CJOURNAL_SPILL_THRESHOLD 12288
typedef struct __attribute__((packed)) {
uint32_t id;
uint32_t node_hash;
uint64_t lamport;
uint32_t wall_ticks;
uint8_t type;
char subsystem[16];
char desc[80];
uint32_t parents[4];
uint8_t num_parents;
uint16_t child_count;
uint32_t payload_len;
uint8_t payload_hash[32];
uint16_t schema_id;
uint8_t schema_version;
} cjournal_event_t;
Operator quick start
Build and enter the machine.
git clone https://github.com/slepp/slos.git
cd slos
make
make run-nographicThe short claim
A live diagram from inside the guest.
A bare-metal OS that serves a live, navigable, time-travelling picture of its own causality over HTTP. The page is not a simulation of the manual. It is a userspace program asking the kernel for its graph.