Manual section W

Execution walks.

These plates follow SlOS commands from prompt to syscall, subsystem, event, device, journal, or browser view. Each stage names the next handoff.

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

Timeline note procedure

Application state is an event stream; snapshots and exports are conveniences over replayable history.

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.

kernel/apps/notes.c
kernel/graph/timeline.c
kernel/graph/causal.c
kernel/fs/blockfs.c

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

ELF loading procedure

Ring-3 programs are loaded objects that use syscall wrappers for all services.

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.

kernel/apps/cmd_system.c
kernel/core/elf.c
programs/browser.c
include/syscall.h
kernel/core/syscall_dev.c

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]

Network procedure

Device queues carry frames; IP classifies packets; TCP supplies a byte stream; httpd serves the application response.

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.

programs/httpd.c
kernel/net/tcp.c
kernel/net/net.c
kernel/drivers/virtio_net.c
kernel/apps/cmd_net.c

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

Persistent file procedure

Persistent files are block-device transactions with names, metadata, allocation, and verification commands around them.

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.

kernel/apps/cmd_files.c
kernel/fs/blockfs.c
kernel/drivers/virtio_blk.c
kernel/drivers/virtio.c
include/blockfs.h

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

Actor routing procedure

Communication is explicit: actor names, route records, mailbox slots, causal IDs, and optional remote peer transport.

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.

kernel/graph/actor.c
kernel/graph/federation.c
kernel/graph/mesh.c
kernel/core/noise.c
kernel/apps/cmd_graph.c

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

Graphics showcase procedure

A graphical user program is still syscall traffic with device-facing consequences.

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.

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

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

Durable explanation procedure

Recent causality is fast; durable causality is searchable, reboot-resistant, and proof-bearing.

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.

programs/shell.c
kernel/graph/cjournal.c
include/cjournal.h
kernel/graph/causal.c

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

Web causal explorer procedure

A browser view can be a precise system instrument when every endpoint is backed by kernel data.

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.

programs/httpd.c
kernel/graph/causal.c
kernel/graph/replay.c
kernel/net/tcp.c

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]}

Replay scrub procedure

Time-travel is deterministic reconstruction over causal events, not a mutable global undo stack.

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.

programs/scrub.c
kernel/graph/replay.c
kernel/graph/integrity.c
kernel/core/syscall_graph.c
include/replay.h

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

Saved query procedure

Operator knowledge can become a small durable tool without changing the kernel command table.

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.

programs/shell.c
kernel/fs/blockfs.c
kernel/graph/cjournal.c
Makefile

Continue with guided trails, subsystems, causality, source, showcase, manual, and glossary.