Walk 01
note add -> shell -> notes timeline -> causal event -> SlFS snapshot/export
A note begins as operator text, becomes a typed timeline payload, updates a replayable notes view, and can be exported to SlFS.
slos:/$ note add map the write path before changing it
Note #7 added.
slos:/$ note tag last manual
Tagged note #7 with manual
slos:/$ tl show notes
#2386 notes NOTE_ADD map the write path before changing it
#2387 notes NOTE_TAG manual
slos:/$ why 2387
[2387] notes: tag note #7 manual
caused by [2386] notes: map the write path before changing it
What the reader learns
Timeline note procedure
Application state is an event stream; snapshots and exports are conveniences over replayable history.
Ordered stages
Prompt
The shell parses note add and dispatches to the notes command handler.
Application
notes_add() appends a typed event to the notes timeline.
Timeline
timeline_emit() uses the previous notes head as the parent edge.
Causal event
causal_emit_payload() allocates an ID, tick, subsystem tag, and payload.
Persistence
Notes snapshots and exports use SlFS files when the operator asks for durable copies.
Source files
kernel/apps/notes.c |
kernel/graph/timeline.c |
kernel/graph/causal.c |
kernel/fs/blockfs.c |
Walk 02
exec browser -> ELF loader -> ring-3 task -> syscalls -> rendered text
The browser program shows the ordinary user-program path: lookup, ELF validation, argv stack, scheduler entry, SlFS file reads, and console writes.
slos:/$ diskmkdir /docs
slos:/$ diskwrite /docs/boot.html "<h1>Boot notes</h1><p>Rendered by browser.</p>"
slos:/$ exec browser file:/docs/boot.html -find browser
[elf] loaded 'browser' (entry 0x40000000, pid 42)
SlOS Browser ELF: file:/docs/boot.html (32 bytes)
Matches:
Rendered by browser.
Ran 'browser' (pid 42)
slos:/$ events 5
ID TICK TYPE DESCRIPTION
2410 12004 elf exec: browser at 0x40000000
2411 12005 syscall syscall 73 pid=42
2412 12006 syscall syscall 48 pid=42
2413 12007 syscall syscall 1 pid=42
2414 12008 syscall syscall 0 pid=42
What the reader learns
ELF loading procedure
Ring-3 programs are loaded objects that use syscall wrappers for all services.
Ordered stages
Prompt
cmd_exec() resolves the embedded browser program or a disk ELF path.
Loader
elf_load_args() validates ELF32, maps loadable segments, and builds argc/argv.
Task
The new ring-3 task becomes schedulable with a user entry frame.
Syscalls
programs/browser.c reads SlFS or built-in about pages and writes rendered text.
Event
exec and syscall records make the user-program path inspectable.
Source files
kernel/apps/cmd_system.c |
kernel/core/elf.c |
programs/browser.c |
include/syscall.h |
kernel/core/syscall_dev.c |
Walk 03
HTTP request -> VirtIO net -> IPv4/TCP -> httpd -> causal explorer API
A request enters through QEMU forwarding, crosses the SlOS TCP stack, reaches a ring-3 server, and returns dashboard or causal graph data.
slos:/$ httpd
[httpd] Listening on port 80 — dashboard at http://<ip>/
host$ curl http://localhost:8080/api/sysinfo
{"version":"SlOS 0.1.0","uptime_ticks":22690,"total_events":2519}
slos:/$ tcptrace
Recent TCP causal events:
[2516] T+22690 conn 1: CLOSED → SYN_RCVD (port 80)
[2517] T+22691 conn 1: SYN_RCVD → ESTABLISHED (port 80) [←2516]
[2518] T+22692 conn 1: send 42 bytes [←2517]
[2519] T+22693 conn 1: ESTABLISHED → CLOSE_WAIT (port 80) [←2518]
What the reader learns
Network procedure
Device queues carry frames; IP classifies packets; TCP supplies a byte stream; httpd serves the application response.
Ordered stages
Host request
QEMU forwards localhost:8080 to port 80 in the guest.
Device
virtio_net.c receives or transmits Ethernet frames through virtqueues.
Stack
net.c handles Ethernet, ARP, IPv4, and TCP handoff.
Transport
tcp.c advances connection state and buffers the HTTP byte stream.
Program
programs/httpd.c handles GET paths and writes HTTP/1.0 responses.
Source files
programs/httpd.c |
kernel/net/tcp.c |
kernel/net/net.c |
kernel/drivers/virtio_net.c |
kernel/apps/cmd_net.c |
Walk 04
diskwrite -> SlFS inode/block allocation -> VirtIO block sector write
A disk write walks from shell text to an inode update, data blocks, cache state, and a VirtIO block request.
slos:/$ diskmkdir /log
slos:/$ diskwrite /log/run.txt sector path recorded
slos:/$ diskstat /log/run.txt
/log/run.txt: inode=7 type=file size=21 bytes blocks=1 ctime=T+123 mtime=T+123 flags=rw
slos:/$ diskcat /log/run.txt
sector path recorded
slos:/$ fsck
fsck: clean
What the reader learns
Persistent file procedure
Persistent files are block-device transactions with names, metadata, allocation, and verification commands around them.
Ordered stages
Prompt
cmd_diskwrite() normalizes the path and creates the file if needed.
Filesystem
blockfs_write_file() updates inode metadata and block allocation.
Sector
File bytes are copied into 512-byte sectors.
Device
virtio_blk.c builds a request descriptor chain and waits for completion.
Check
diskcat, diskstat, diskcache, and fsck inspect the persisted result.
Source files
kernel/apps/cmd_files.c |
kernel/fs/blockfs.c |
kernel/drivers/virtio_blk.c |
kernel/drivers/virtio.c |
include/blockfs.h |
Walk 05
send -> actor lookup -> mailbox -> receive edge -> mesh/federation option
Actor delivery starts with a name, writes a bounded mailbox entry, and records send and receive events; remote routes extend that shape over mesh and federation.
slos:/$ actors
ID NAME PID MSGS IN/OUT
2 shell 0 0 3/0
slos:/$ send shell local loop
Sent to shell: local loop
slos:/$ recv shell
[type=1 from=2 t=30211] local loop
slos:/$ trace 2732
2732 actor recv name=shell type=1
caused by 2731 actor send to=shell
What the reader learns
Actor routing procedure
Communication is explicit: actor names, route records, mailbox slots, causal IDs, and optional remote peer transport.
Ordered stages
Prompt
cmd_send() joins message words and calls actor_send().
Lookup
actor.c resolves a local actor or route target.
Mailbox
The bounded mailbox stores sender, type, length, timestamp, and payload.
Receive
actor_recv() emits a receive event connected to the send event.
Remote
Federation can package the same actor message for Noise-protected mesh transport.
Source files
kernel/graph/actor.c |
kernel/graph/federation.c |
kernel/graph/mesh.c |
kernel/core/noise.c |
kernel/apps/cmd_graph.c |
Walk 06
doom -> ELF user process -> framebuffer syscalls -> VGA mode 13h
DOOM exercises the loader, user runtime, framebuffer, palette, keyboard, timing, and file services as one visible integration path.
slos:/$ doom
[elf] loaded 'doom' (entry 0x40000000, pid 52)
<screen enters 320x200 256-colour graphics mode>
<doomgeneric reads /doom2.wad and draws frames>
slos:/$ events 6
2810 elf exec: doom at 0x40000000
2811 syscall FB_INIT pid=52
2812 syscall FB_PALETTE pid=52
2813 syscall FB_BLIT pid=52
2814 syscall POLL_KEY pid=52
2815 syscall SLEEP pid=52
What the reader learns
Graphics showcase procedure
A graphical user program is still syscall traffic with device-facing consequences.
Ordered stages
Launch
cmd_doom() finds and starts the DOOM ELF when support is built.
Program
doom_entry.c enters doomgeneric with the WAD path.
Syscalls
doomgeneric_slos.c issues framebuffer, palette, input, and sleep calls.
Device
arch/x86/vga13h.c switches mode and blits the 320x200 indexed buffer.
Record
Frame and input calls appear as ordinary causal syscall events.
Source files
kernel/apps/cmd_apps.c |
kernel/core/elf.c |
doom/platform/doom_entry.c |
doom/platform/doomgeneric_slos.c |
kernel/core/syscall_dev.c |
arch/x86/vga13h.c |
Walk 07
why -a across a reboot -> cjournal read-through -> parent chain survives
When an event has aged out of the hot ring, the archived journal still supplies lookup and trace records from SlFS.
slos:/$ journal spill-through last
journal spill-through: event #3912 archived (spilled 1)
slos:/$ events 10
#3912 is no longer in the hot ring
slos:/$ why 3912
(event 3912 beyond recent history)
slos:/$ why -a 3912
Journal trace for event #3912:
#3912 T+39012 hash=0xabc123 hashv=4 source=journal transport=syscall hash_cmd="journal hash 3912" shell shell command complete
caused by:
#3911 T+39011 hash=0xdef456 hashv=4 source=journal transport=syscall hash_cmd="journal hash 3911" syscall syscall syscall 1 pid=37
slos:/$ trace -a 3912
Journal trace for event #3912:
#3912 T+39012 hash=0xabc123 hashv=4 source=journal transport=syscall hash_cmd="journal hash 3912" shell shell command complete
What the reader learns
Durable explanation procedure
Recent causality is fast; durable causality is searchable, reboot-resistant, and proof-bearing.
Ordered stages
Prompt
why first tries the recent ring through eventinfo().
Miss
An old ID may not be resident after ring churn or reboot.
Archive
why -a delegates to journal trace through the kernel command proxy.
Journal
cjournal reads persisted segment records and follows parent IDs.
Event
The explanation remains an ordered parent chain, now sourced from journal.
Source files
programs/shell.c |
kernel/graph/cjournal.c |
include/cjournal.h |
kernel/graph/causal.c |
Walk 08
open /causal -> graph JSON -> SVG render -> state scrub API
The web explorer is a live page served by SlOS httpd. It fetches graph data, renders SVG, and calls replay when the scrubber moves.
slos:/$ httpd
[httpd] Listening on port 80 — dashboard at http://<ip>/
host$ xdg-open http://localhost:8080/causal
browser: GET /causal
browser: GET /api/causal/graph
browser: render SVG nodes and parent edges
browser: click #4120 to focus causes and effects
browser: GET /api/causal/state?tick=100
What the reader learns
Web causal explorer procedure
A browser view can be a precise system instrument when every endpoint is backed by kernel data.
Ordered stages
HTTP
programs/httpd.c routes GET /causal to a self-contained HTML page.
Graph
The page fetches /api/causal/graph for nodes and edges.
Render
Browser JavaScript lays out the DAG and draws an SVG.
Focus
Clicking a node highlights ancestors and descendants in the edge list.
Scrub
Moving the range input fetches /api/causal/state?tick=N.
Source files
programs/httpd.c |
kernel/graph/causal.c |
kernel/graph/replay.c |
kernel/net/tcp.c |
Walk 09
scrub to a past tick -> replay reconstruction -> diff from now
scrub asks the replay engine for derived state at a tick, then compares that frame to another tick when requested.
slos:/$ scrub 100
SlOS Causal Time-Travel tick 100 / 999
[====------------------------------------]
Reconstructed state (replay of 100 events):
tasks: alive 3 created 4 exited 1
io: syscalls 18 fs 2 net tx/rx 0/0 actor msgs 1
Active tasks (3):
[pid 1] shell
Recent events (4): #97 #98 #99 #100
slos:/$ scrub diff 100 999
Causal diff: tick 100 -> tick 999
events +899 syscalls +12 fs +3
net tx +0 net rx +0 actor +12
tasks alive: 3 -> 7
slos:/$ scrub json 100
{"tick":100,"total_events":100,"tasks":{"alive":3,"created":4,"exited":1},"io":{"syscalls":18,"fs":2,"net_tx":0,"net_rx":0,"actor_msgs":1},"active_tasks":[{"pid":1,"name":"shell"}],"recent_events":[97,98,99,100]}
What the reader learns
Replay scrub procedure
Time-travel is deterministic reconstruction over causal events, not a mutable global undo stack.
Ordered stages
Prompt
programs/scrub.c parses a tick, diff, event, whatif, or json mode.
Syscall
The program requests replay state through the replay syscall path.
Replay
kernel/graph/replay.c walks events up to the target tick.
Snapshot
integrity.c snapshots can speed state reconstruction while preserving verifiability.
Output
scrub renders plain text, JSON, or an interactive TUI frame.
Source files
programs/scrub.c |
kernel/graph/replay.c |
kernel/graph/integrity.c |
kernel/core/syscall_graph.c |
include/replay.h |
Walk 10
lens save -> /lens.db on SlFS -> reboot -> lens run
A lens stores a named causal query so repeated field checks survive reboot and avoid manual command reconstruction.
slos:/$ lens save syscall cq -a type=syscall limit=10
lens: saved 'syscall' = cq -a type=syscall limit=10
slos:/$ lens list
Saved causal lenses
syscall cq -a type=syscall limit=10
slos:/$ reboot
...
slos:/$ lens run syscall
CQ results (archived journal):
slos:/$ diskcat /lens.db
syscall cq -a type=syscall limit=10
What the reader learns
Saved query procedure
Operator knowledge can become a small durable tool without changing the kernel command table.
Ordered stages
Prompt
cmd_lens() accepts save, list, rm, run, or a bare lens name.
Persist
lens_save_db() writes the lens table to /lens.db on SlFS.
Reboot
The saved file remains on disk.img because make clean does not delete it.
Load
lens_ensure_loaded() reads /lens.db before listing or running.
Dispatch
lens_run() tokenizes the saved query and dispatches it through the shell command table.
Source files
programs/shell.c |
kernel/fs/blockfs.c |
kernel/graph/cjournal.c |
Makefile |