Field manual / subsystem chapters

Subsystem chapters.

Read SlOS as a set of instruments: source path, role, command, watch point, and causal record. Paths on this page follow the arch, kernel, programs, include, and lib layout.

Causal graphcjournalscrub/causalSlFSremote shell

slos:/$ status
  ╔══════════════════════════════════╗
  ║       SlOS System Status         ║
  ╚══════════════════════════════════╝
  Version:   <kernel version>
  Tasks:     <task count>
  Events:    <causal event count>
slos:/$ journal recent 5
Journal recent: <n> events
  #<id> T+<tick> hash=0x<hash> source=journal ...

Reading method

Trace one path at a time.

Choose a command, observe its output, then follow the source files that explain the transition. The useful reading order is prompt, syscall or command handler, subsystem, causal event, and durable record.

Route map

19 subsystems to inspect.

Chapter	Subsystem	Concept
01	Boot and CPU tables	Machine entry and protected-mode structure
02	Memory manager	Frames, pages, per-task isolation, and the heap
03	Scheduler and tasks	Preemption, context frames, and userspace concurrency
04	Syscall gate	Controlled entry from user code to kernel services
05	Causal graph core	Every important action becomes an event with parents
06	Durable causal journal	Searchable history on SlFS, beyond the hot ring
07	Causal query tooling	Filter, prove, save, and aggregate causal records
08	Replay and time-travel	Reconstruct past state rather than trust a snapshot of now
09	Counterfactual analysis	Ask which effects depend on an event
10	Web causal explorer	A live SVG DAG and time-travel scrubber served by SlOS
11	SlFS and storage	Block devices, directory state, and persistent files
12	Networking and TCP	Frames, address resolution, transport state, and services
13	Remote terminal and shells	A remote workstation over telnet or a from-scratch encrypted channel
14	Timelines and graph-native apps	Application state as named event chains
15	Actors, mesh, and federation	Named endpoints and routed messages
16	User programs and scripting	ELF loading, runtime wrappers, slosh automation, games, and recovery tools
17	Trust and non-repudiation	Signed causal history another machine can verify
18	Multi-core task dispatch	Every core online; opt-in kernel tasks can auto-offload to idle APs
19	High-resolution graphics	A 1024x768x32 framebuffer, additive over VGA text

Chapter 01

Boot and CPU tables

Role	Multiboot enters arch/x86/boot.asm, the first stack is established, and kernel_main() initializes CPU tables, interrupts, memory, devices, filesystems, user programs, and shell services in dependency order.
Watch points	Read the GDT, IDT, TSS, PIC, and PIT setup before studying any higher service. Timer interrupts are the first regular source of scheduling pressure.
Source paths	`arch/x86/boot.asm` `arch/x86/interrupt.asm` `kernel/core/main.c` `kernel/core/x86.c` `kernel/core/interrupt.c`

Learning target

Machine entry and protected-mode structure

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

make
make run-nographic
status
irqstat
events 5

Chapter 02

Memory manager

Role	The PMM tracks physical frames. Paging identity-maps the low 128 MB as supervisor-only (no PTE_USER), and each ring-3 task gets its own page directory with private user mappings for its ELF image, 64 KB stack, and heap — so kernel memory and other tasks' pages are unreachable from user mode by hardware. The kernel heap supplies bounded dynamic allocation.
Watch points	Read-only code is mapped without write permission (a self-modifying write faults); writable data stays executable (32-bit paging has no NX bit, so this is code write-protection, not full W^X). faultdemo probes each boundary and the task is terminated cleanly on the fault while the shell survives.
Source paths	`kernel/core/memory.c` `kernel/core/elf.c` `kernel/core/task.c` `programs/faultdemo.c` `include/memory.h`

Learning target

Frames, pages, per-task isolation, and the heap

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

free
memmap
heap
faultdemo
faultdemo write

Chapter 03

Scheduler and tasks

Role	Task records carry pid, priority, sleep/block state, parentage, user or kernel mode, and saved context. The PIT timer preempts at 100 Hz, so ring-3 programs run concurrently with the shell. SYS_SPAWN backgrounds a program (also via a trailing &) and stateless job control — jobs, wait, fg, renice — tracks it.
Watch points	A new task begins on a fabricated stack; an old task resumes by restoring saved callee registers and ESP. A backgrounded httpd serves real HTTP clients while the shell stays interactive — the make multitask-check and httpd-check gates prove it.
Source paths	`kernel/core/task.c` `kernel/core/syscall.c` `arch/x86/context.asm` `programs/shell.c` `programs/worker.c` `include/task.h`

Learning target

Preemption, context frames, and userspace concurrency

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

ps
spawn httpd
worker 5 &
jobs
renice 1 6

Chapter 04

Syscall gate

Role	INT 0x80 carries a syscall number and register arguments into C dispatch. User programs reach files, devices, graph queries, TCP, timelines, replay, and process control through this gate.
Watch points	Compare include/syscall.h with lib/slos.h wrappers. Note which calls emit causal records and which proxy shell or graph commands.
Source paths	`kernel/core/syscall.c` `kernel/core/syscall_dev.c` `kernel/core/syscall_graph.c` `kernel/core/syscall_net.c` `include/syscall.h` `lib/slos.h`

Learning target

Controlled entry from user code to kernel services

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

ringdemo
strace hello
events 10
why <syscall-event-id>

Chapter 05

Causal graph core

Role	The causal graph assigns IDs, Lamport time, type, subsystem, description, hashes, and parent edges. Shell commands expose recent roots, traces, effects, paths, DOT output, and activity views.
Watch points	Use the hot ring for immediate study, then switch to journal-backed commands when an event has aged out or crossed a reboot boundary.
Source paths	`kernel/graph/causal.c` `kernel/apps/cmd_graph.c` `programs/shell.c` `include/causal.h`

Learning target

Every important action becomes an event with parents

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

events 10
why last
trace <event-id>
blast <event-id>
cpath <ancestor-id> <event-id>
cdot <event-id>
ctop 128

Chapter 06

Durable causal journal

Role	cjournal persists causal records to SlFS segments with indexes, retention controls, JSON/long forms, archived trace/effects/parents, and read-through used by why -a and trace -a.
Watch points	Observe the source field in query output: hot rows come from ring; archived rows come from journal. Verify aged events with journal lookup, journal trace, and events -a.
Source paths	`kernel/graph/cjournal.c` `include/cjournal.h` `programs/shell.c` `kernel/fs/blockfs.c`

Learning target

Searchable history on SlFS, beyond the hot ring

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

journal recent 10
events -a 10
events -a find syscall
why -a last
trace -a last

Chapter 07

Causal query tooling

Role	The shell query layer supplies cq for hot and archived records, ctop for subsystem activity, cwatch for live causal tailing, why --md for Markdown export, lens for saved SlFS-backed queries, and shell filters for pipeline aggregation.
Watch points	Prefer cq -a for durable history. Use cwatch or cwatch tail when you want a live append-only graph stream; press any key to stop. Pipelines are sequential, not POSIX-concurrent: each stage captures at most 4096 bytes before feeding the next.
Source paths	`programs/shell.c` `kernel/graph/cjournal.c` `kernel/graph/search.c` `kernel/graph/integrity.c`

Learning target

Filter, prove, save, and aggregate causal records

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

cq -a type=syscall limit=10
cq -a id=last epoch-proof --json-ish
why --md last
cwatch tail
lens save syscalls cq -a type=syscall limit=10
lens run syscalls
events | tail -n 5
ps | grep shell
journal type sched 50 | tally

Chapter 08

Replay and time-travel

Role	The replay engine walks causal history to reconstruct task, syscall, filesystem, network, and actor counts at a tick. The scrub program presents that reconstruction as a TUI and one-shot command set.
Watch points	A reconstructed frame is a derived view. Compare scrub <tick>, scrub json <tick>, scrub diff, replay, and rewind before treating any current counter as permanent truth.
Source paths	`kernel/graph/replay.c` `include/replay.h` `programs/scrub.c` `kernel/graph/integrity.c` `kernel/apps/cmd_graph.c`

Learning target

Reconstruct past state rather than trust a snapshot of now

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

scrub 100
scrub event last
scrub diff 100 999
scrub json 999
rewind 100
replay 100

Chapter 09

Counterfactual analysis

Role	whatif walks downstream effects from an event and reports the impact of removing or changing that cause. scrub whatif exposes the same idea from the time-travel inspector.
Watch points	Use counterfactuals on specific event IDs, not vague subsystems. The useful answer is the set of affected descendants and the verdict on system impact.
Source paths	`kernel/graph/whatif.c` `programs/scrub.c` `kernel/graph/causal.c`

Learning target

Ask which effects depend on an event

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

whatif summary <event-id>
scrub whatif last
blast <event-id>

Chapter 10

Web causal explorer

Role	The ring-3 httpd program serves /causal, /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot over the SlOS TCP stack.
Watch points	The page is not a screenshot. It fetches graph JSON, renders SVG nodes and edges, focuses ancestors/effects on click, and calls /api/causal/state?tick=N when the scrubber moves.
Source paths	`programs/httpd.c` `kernel/net/tcp.c` `kernel/net/net.c` `kernel/graph/replay.c` `kernel/graph/causal.c`

Learning target

A live SVG DAG and time-travel scrubber served by SlOS

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

httpd
# host side
curl http://localhost:8080/api/causal/graph
curl 'http://localhost:8080/api/causal/state?tick=100'
curl http://localhost:8080/api/causal/dot

Chapter 11

SlFS and storage

Role	VirtIO block I/O supplies synchronous sector reads and writes. SlFS provides directories, files, metadata, block allocation, cache, fsck, and persistence for journals, lenses, snapshots, exports, and user files. The shell now presents a coherent overlay namespace: /tmp and relative paths are RAM scratch; other absolute paths such as /home/... persist to SlFS, with reads checking RAM first and SlFS second.
Watch points	Distinguish scratch from persistent intent rather than treating the namespace as two unrelated filesystems. Follow write /home/x through cmd_files.c to blockfs, and write tmp.txt or /tmp/x through the RAM filesystem.
Source paths	`kernel/drivers/virtio.c` `kernel/drivers/virtio_blk.c` `kernel/fs/blockfs.c` `kernel/fs/fs.c` `kernel/apps/cmd_files.c` `include/fs_route.h` `include/blockfs.h`

Learning target

Block devices, directory state, and persistent files

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

mkdir /home/field
write /home/field/log.txt storage event
cat /home/field/log.txt
write /tmp/scratch.txt volatile
pwd
fsck

Chapter 12

Networking and TCP

Role	VirtIO net moves Ethernet frames. ARP, IPv4, UDP, DHCP, ICMP, TCP, wget, httpd, telnetd, chatd, netstat, and tcptrace expose the stack from packet to service. chatd is an IRC-lite multi-user TCP service on port 6667 with /nick, join/leave announcements, and broadcast across up to eight clients.
Watch points	Check byte order at every boundary. TCP state transitions are the best compact evidence that the packet path is coherent. chatd is deliberately small: fixed eight-client table, CR/LF line buffering, and task-per-session workers rather than a general async server.
Source paths	`kernel/drivers/virtio_net.c` `kernel/net/net.c` `kernel/net/dhcp.c` `kernel/net/tcp.c` `kernel/net/wget.c` `programs/httpd.c`

Learning target

Frames, address resolution, transport state, and services

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

dhcp status
ifconfig
arp
netstat
tcptrace
chatd start
chatd status
# host side: nc localhost 6667
wget 10.0.2.15 /api/sysinfo

Chapter 13

Remote terminal and shells

Role	telnetd listens on guest port 23 (QEMU hostfwd localhost:2323) and noiseshd listens on 5200. Each accepted connection spawns a shell task with per-task I/O hooks, so console writes go back over TCP and shell/editor input comes from that session. The Noise shell performs an ephemeral X25519 exchange and then frames the byte stream with ChaCha20-Poly1305; it is confidential against passive listeners but currently unauthenticated, not OpenSSH.
Watch points	Terminal redirection is the enabling layer: console clear, cursor, and colour emit ANSI through io_write; SYS_TERM_GETKEY decodes arrows, Ctrl-S/Ctrl-Q/Ctrl-C/Ctrl-L, and other cooked keys; SYS_CON_GETSIZE reads the session size populated by telnet NAWS. Long-lived daemons such as httpd, telnetd, and noiseshd detach from session I/O so they survive disconnect, while foreground editors remain session-owned.
Source paths	`docs/remote-access.md` `kernel/apps/telnetd.c` `kernel/core/syscall.c` `kernel/drivers/console.c` `programs/editor.c` `scripts/noise-shell-client.py` `kernel/core/task.c`

Learning target

A remote workstation over telnet or a from-scratch encrypted channel

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

# host side, default QEMU forwarding
telnet localhost 2323
# or encrypted, from the SlOS repo
python3 scripts/noise-shell-client.py localhost 5200

# SlOS shell
termsize
edit /home/field/day.sl
run /home/field/day.sl
httpd
exit
# host side
curl http://localhost:8080/

Chapter 14

Timelines and graph-native apps

Role	Timelines give notes, mail, the editor, process views, and scheduled commands ordered event streams with rewind, forward, at, show, and replay operations.
Watch points	The previous timeline head becomes the parent of the next event. Current app state is a replayed view of ordered payloads.
Source paths	`kernel/graph/timeline.c` `kernel/apps/notes.c` `kernel/apps/mail.c` `kernel/apps/sched_app.c` `include/timeline.h`

Learning target

Application state as named event chains

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

note add timeline state is replayable
tl show notes
tl rewind notes 5
tl forward notes 5
mail
edit
scheduled

Chapter 15

Actors, mesh, and federation

Role	Actors are named mailboxes. Routes, Noise-based mesh identity, and federation let selected messages and causal graph material move beyond the local actor table.
Watch points	Trace actor registration, local delivery, dead-letter behaviour, remote proxy selection, peer identity, and federated causal edges.
Source paths	`kernel/graph/actor.c` `kernel/graph/mesh.c` `kernel/graph/federation.c` `kernel/core/noise.c` `kernel/apps/cmd_graph.c`

Learning target

Named endpoints and routed messages

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

actors
send shell local loop
recv shell
mesh
routes
federation
why remote_parent shell

Chapter 16

User programs and scripting

Role	The program registry and ELF loader start shell, httpd, wget, browser, scrub, rogue, DOOM, and other ring-3 programs. The in-kernel slosh interpreter now has functions (func/end), $1..$9 positional parameters, return, bounded recursion, for loops, and shell-command passthrough, so scripts can drive ls, cat, wget, and other shell surfaces. Kernel commands also expose the surgeon crash shell for recovery exercises.
Watch points	Separate kernel built-ins from user ELFs and scripts. slosh variables are global except saved positional parameters, recursion is bounded, and unknown slosh commands dispatch through shell_exec after expansion.
Source paths	`kernel/core/elf.c` `kernel/apps/script.c` `docs/scripting.md` `programs/shell.c` `programs/browser.c` `programs/rogue.c` `programs/scrub.c` `kernel/apps/cmd_apps.c` `include/doom.h`

Learning target

ELF loading, runtime wrappers, slosh automation, games, and recovery tools

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

write /home/fib.sl func countdown
  echo $1
  if $1 != 1
    expr n $1 - 1
    countdown $n
  end
end
countdown 3
run /home/fib.sl
exec browser about:slos
scrub help
rogue
doom
crash int3

Chapter 17

Trust and non-repudiation

Role	A persistent per-node Ed25519 key signs each verified journal epoch root into a sidecar. Over the Noise-encrypted mesh a node distributes its public signing key and shares a signed segment root; a peer independently recomputes that root from imported events and verifies the signature, so cross-node causal history is non-repudiable. Refused roots raise per-peer rate-limited integrity events.
Watch points	verify-sig recomputes the Merkle root from durable events before checking the signature, so tampering at any layer is caught. On-node verification proves self-consistency; authenticity needs the peer's distributed key — exactly what the cluster gate checks. Primitives (SHA-512, Ed25519, ChaCha20-Poly1305, BLAKE2s, Curve25519) are cross-validated against PyNaCl and OpenSSL.
Source paths	`kernel/core/noise.c` `kernel/graph/cjournal.c` `kernel/graph/federation.c` `kernel/graph/mesh.c` `include/federation.h`

Learning target

Signed causal history another machine can verify

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

journal sign 1
journal verify-sig 1
journal trust-health
federation identity
federation share-root 1

Chapter 18

Multi-core task dispatch

Role	Booted with make run-smp (-smp 4), SlOS enumerates CPUs from the ACPI MADT, moves the bootstrap processor from the legacy PIC to its Local APIC timer plus the IOAPIC, and brings every application processor online. The proven lane now includes explicit AP-pinned dispatch with smp runon <cpu> and BSP-driven auto-offload: smp offload <n> creates unpinned ap_offloadable kernel tasks, and the scheduler retargets eligible queued work to idle CPUs 1/2/3 before sending IPI vector 0xFE.
Watch points	Honest status: this is cooperative AP scheduling for opt-in kernel tasks, not preemptive migration or general load balancing. AP LAPIC timers remain masked; AP tasks must yield, block, or exit; ring-3/user tasks, shell, boot, idle, and long-running kernel loops stay on the BSP. Use cpu for the per-core table, and events/why/cprof/cwatch to see BSP-side offload causal records such as offload pid=<pid> to=cpu<N>. make smp-check still gates four-core bring-up and shell responsiveness.
Source paths	`kernel/core/smp.c` `include/smp.h` `include/spinlock.h` `kernel/core/interrupt.c` `kernel/core/task.c`

Learning target

Every core online; opt-in kernel tasks can auto-offload to idle APs

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

smp
cpus
cpu
smp spinlock-test
smp runon 1
smp offload 6
events | tail -n 5
why last

Chapter 19

High-resolution graphics

Role	Beyond the 80x25 text console and DOOM's 320x200 mode, the gfx command switches to a 1024x768x32 linear framebuffer using QEMU std-VGA's Bochs VBE registers and the PCI-BAR framebuffer. gfxdash renders an interactive system dashboard; wm builds a keyboard-driven tiled desktop with live CPU, causal-tail, task-list, and memory/system panels.
Watch points	It is purely additive: the high-res path keeps its own state, so the default text console and DOOM are untouched, and the whole thing is x86-only. wm is not a compositing desktop and has no mouse path yet; it redraws fixed tiled panels, cycles focus with Tab, and exits with q/Esc. Headless selftests use framebuffer readback to validate pixels without relying on a host display.
Source paths	`arch/x86/vga13h.c` `include/gfx.h` `kernel/apps/cmd_apps.c` `kernel/drivers/fbcon.c` `include/fb.h`

Learning target

A 1024x768x32 framebuffer, additive over VGA text

Ask which structure changes, which event records the change, and whether the record is recent only or durable.

gfx
gfxdash
wm
showcase

Cross-link this page with guided trails, execution walks, causality, source, showcase, manual, and glossary.