Appendix G

Glossary and source atlas.

Each term is paired with current SlOS source paths. Use it as a vocabulary check before reading code, writing notes, or operating the machine.

Manual Causality Source plates Showcase

Route

Manual

Structured reference for boot, commands, durable history, time travel, and web operation.

Route

Causality

Event records, Lamport time, parent edges, replay, journal proofs, and federation.

Route

Source plates

Verified excerpts from current SlOS source files.

Route

Showcase

Recorded sessions mapped to commands and subsystems.

Field terms

Terms in operating order.

TermExplanationWhere it appearsSource files
actor mailbox A bounded queue attached to a named actor endpoint. actors lists endpoints; send and recv move typed messages locally or through federation routes.
  • include/actor.h
  • kernel/graph/actor.c
  • kernel/apps/cmd_graph.c
archived query (cq -a) A causal query that reads persistent journal segments instead of only the live event ring. cq -a accepts selectors such as type=, subsystem=, desc~, since=, until=, id=, segment=, and limit=.
  • programs/shell.c
  • include/cjournal.h
  • kernel/graph/cjournal.c
BlockFS / SlFS The persistent filesystem stored on the VirtIO block device. Journal segments, timeline files, lenses, notes snapshots, and ordinary persistent files live on SlFS.
  • include/blockfs.h
  • kernel/fs/blockfs.c
  • kernel/drivers/virtio_blk.c
causal DAG A directed graph of events connected by parent-to-child cause edges. events, graph, trace, why, blast, cpath, and cdot expose the DAG to the operator.
  • include/causal.h
  • kernel/graph/causal.c
  • kernel/apps/cmd_graph.c
  • programs/shell.c
causal event One recorded fact: ID, node identity, Lamport time, wall tick, type, subsystem, description, payload, schema, and parent IDs. Emitted by scheduler, syscall, filesystem, network, actor, mesh, and timeline code.
  • include/causal.h
  • kernel/graph/causal.c
cjournal The persistent causal journal that spills events to SlFS segments. journal commands inspect recent archives, find text, filter types or subsystems, verify hashes, and report proof health.
  • include/cjournal.h
  • kernel/graph/cjournal.c
  • programs/shell.c
chatd An IRC-lite multi-user TCP server running inside SlOS on port 6667. chatd start/status/stop controls the service; host clients can connect through the forwarded port, use /nick, and broadcast lines to up to eight clients.
  • kernel/net/tcp.c
  • docs/TCP.md
  • docs/JOURNAL.md
cpath A command for answering whether one event is causally upstream of another and by what chain. cpath <a> <b> searches parent edges; cpath common reports a nearest common ancestor.
  • kernel/apps/cmd_graph.c
  • programs/shell.c
ctop A causal activity monitor that buckets recent events by subsystem. ctop [N] shows where event traffic is concentrated right now.
  • programs/shell.c
cdot A Graphviz DOT exporter for a focused causal subgraph. cdot <id|last> shows causes; cdot <id|last> effects shows downstream impact.
  • kernel/apps/cmd_graph.c
  • programs/shell.c
triage (operator verdict) A one-screen incident verdict that composes entropy, blame, critical-path, journal, and contract signals. triage prints HEALTHY, DEGRADED, or CRITICAL plus one next-action command.
  • kernel/graph/triage.c
  • programs/shell.c
cbisect (causal bisect) git-bisect over replayable history: a binary search of the tick timeline for when a cumulative metric crossed a threshold. cbisect <metric> <N> reconstructs state per probe via replay.
  • kernel/graph/cbisect.c
  • kernel/graph/replay.c
cdb (causal debugger) A gdb-style debugger over the recorded causal DAG: predicate breakpoints, a persistent cursor, and cause/effect navigation. cdb break, run, bt, step, print, and reset operate one session across shell calls.
  • kernel/graph/cdb.c
  • kernel/apps/cmd_graph.c
cprof (causal flow profile) A profile of cause-to-effect flow across subsystem boundaries, marking cross-subsystem crossings. cprof [window] ranks parent-to-child type boundaries by edge volume.
  • kernel/graph/cprof.c
cwatch A live tail of the causal event graph. cwatch or cwatch tail prints recent context, then streams new events until any key is pressed; --once gives a bounded sample.
  • docs/causal-toolkit.md
  • docs/JOURNAL.md
  • programs/shell.c
cpu command A per-core scheduler snapshot. cpu shows active state, current task and PID, switch count, and idle/busy state for each CPU; SMP offloads also appear as causal scheduler events.
  • docs/smp.md
  • kernel/core/task.c
attest (signed receipt) A self-contained, Ed25519-signed receipt that proves one outcome happened and is independently verifiable. attest <id|last> emits the receipt; attest verify <id> re-checks the signature against the node key.
  • kernel/graph/attest.c
  • kernel/graph/cjournal.c
  • kernel/core/noise.c
capsule (incident bundle) A portable bundle of one event with its nearby causes, effects, hash, and proof, written to SlFS. capsule <id|last> prints the bundle and saves /capsule/<id>.txt.
  • kernel/graph/capsule.c
  • kernel/fs/blockfs.c
why -r (origin-tagged walk) A cause walk that tags each hop with its origin node, marking imported remote boundaries. why -r <id|last> annotates the chain as origin=local or origin=node:<hash>; honest that federation imports events individually.
  • kernel/apps/cmd_graph.c
  • programs/shell.c
durable journal Archived causal history stored beyond the bounded hot ring. events -a, cq -a, why -a, trace -a, and journal commands read through it.
  • include/cjournal.h
  • kernel/graph/cjournal.c
  • kernel/graph/causal.c
epoch proof Proof material for a journal epoch or segment, used to check archived event integrity. cq -a id=N epoch-proof, cq -a segment=N epoch-proof, cproof, verify, and journal proof-health expose it.
  • include/cjournal.h
  • kernel/graph/cjournal.c
  • kernel/graph/prove.c
  • programs/shell.c
GDT Global Descriptor Table: the x86 table of code, data, user, and TSS descriptors. Installed during CPU setup before interrupts and user entry are used.
  • include/x86.h
  • kernel/core/x86.c
  • arch/x86/boot.asm
IDT Interrupt Descriptor Table: exception, IRQ, and INT 0x80 syscall dispatch. Interrupt assembly stubs build register frames for kernel handlers.
  • include/interrupt.h
  • kernel/core/interrupt.c
  • arch/x86/interrupt.asm
Lamport time A logical counter that advances with local events and can merge remote causal time. Each causal event carries Lamport time alongside wall ticks and TSC fragments.
  • include/causal.h
  • kernel/graph/causal.c
  • kernel/graph/federation.c
lens A saved, named causal query or causal command. lens save, list, run, and rm persist reusable views to SlFS.
  • programs/shell.c
Merkle event hash A hash commitment for event data that feeds journal roots and proof checks. journal verify, cproof, cq hash, and proof-health use event hashes and segment roots.
  • include/causal.h
  • kernel/graph/causal.c
  • kernel/graph/cjournal.c
  • kernel/graph/integrity.c
Noise-encrypted shell The noiseshd remote shell on TCP port 5200: an ephemeral X25519 exchange followed by ChaCha20-Poly1305 frames carrying the same shell byte stream as telnet. Use scripts/noise-shell-client.py from the host. It is confidential against passive observers but currently unauthenticated and not OpenSSH.
  • docs/remote-access.md
  • kernel/apps/telnetd.c
  • scripts/noise-shell-client.py
  • kernel/core/noise.c
terminal redirection / cooked-key input Per-task I/O hooks redirect console output and input for a remote shell task. Console cursor, clear, and colour become ANSI; SYS_TERM_GETKEY decodes stream bytes into editor keys. Full-screen editor sessions over telnet use arrows, Ctrl-S, Ctrl-Q, Ctrl-C, Ctrl-L, and ANSI drawing through the session instead of the VGA keyboard path.
  • kernel/apps/telnetd.c
  • kernel/core/syscall.c
  • kernel/drivers/console.c
  • programs/editor.c
NAWS Telnet Negotiate About Window Size, option 31, used by SlOS to learn the remote terminal rows and columns. telnetd asks for NAWS; SYS_CON_GETSIZE returns the per-task size to editor and pager code. Clients that do not provide it fall back to 80x25.
  • docs/remote-access.md
  • kernel/apps/telnetd.c
  • kernel/core/syscall.c
daemon survival (detach) Long-lived services clear inherited session I/O hooks so they continue after the remote shell disconnects. Start httpd, telnetd, noiseshd, or chatd from a remote shell; the listener/service task is detached from that session, while foreground interactive programs remain tied to it.
  • docs/remote-access.md
  • kernel/core/syscall.c
  • kernel/apps/telnetd.c
  • kernel/core/task.c
coherent filesystem (overlay namespace) One shell namespace routes /tmp and relative paths to RAM scratch, while other absolute paths such as /home/... persist to SlFS. cat, more/less, head, tail, wc, grep, cp, mv, rm, mkdir, touch, write, cd, and pwd use RAM-first reads with SlFS fallback, so editor and shell commands see the same path.
  • docs/remote-access.md
  • kernel/apps/cmd_files.c
  • include/fs_route.h
  • kernel/fs/blockfs.c
slosh functions Reusable slosh blocks declared with func name ... end. Arguments are exposed as $1..$9, return exits early, and saved positional parameters make bounded recursion possible. Scripts can combine functions, for loops, variables, expr, if/while, and shell-command passthrough to drive ls, cat, wget, and other shell tools.
  • docs/scripting.md
  • kernel/apps/script.c
mesh federation Encrypted peer transport plus remote actor and causal event delivery. mesh inspects peers; federation reports replication and remote delivery status.
  • include/mesh.h
  • kernel/graph/mesh.c
  • include/federation.h
  • kernel/graph/federation.c
  • kernel/core/noise.c
read-through A lookup mode that falls back from the live ring to the durable journal. trace -a, why -a, cq -a, events -a, and causal hydration resolve aged-out events.
  • kernel/graph/causal.c
  • kernel/graph/cjournal.c
  • programs/shell.c
sequential pipeline Shell cmd1 | cmd2 composition implemented by running each stage to completion and capturing stdout for the next stage. grep, head, tail, and wc read from pipeline stdin; intermediate buffers are capped at 4096 bytes, so this is not concurrent POSIX pipe streaming.
  • programs/shell.c
  • docs/shell.md
  • docs/JOURNAL.md
SMP auto-offload BSP-driven dispatch of explicitly ap_offloadable kernel tasks to idle application processors. smp offload <n> creates eligible unpinned tasks; cpu and causal commands show placement. It is cooperative, kernel-task-only, and not general load balancing.
  • docs/smp.md
  • kernel/core/task.c
replay Reconstruction of state by scanning events forward to a selected tick. replay and rewind commands use the replay engine; scrub and httpd expose reconstructed state.
  • include/replay.h
  • kernel/graph/replay.c
  • programs/scrub.c
  • programs/httpd.c
ring 3 x86 user privilege level used by SlOS user-space ELF programs. User programs call kernel services through INT 0x80 syscalls.
  • include/syscall.h
  • kernel/core/syscall.c
  • kernel/core/elf.c
  • lib/slos.h
scrub / time-travel The causal inspector for moving through reconstructed ticks and focusing events. scrub, scrub <tick>, scrub event, scrub diff, scrub json, and scrub whatif are user-space surfaces.
  • programs/scrub.c
  • include/replay.h
  • kernel/graph/replay.c
syscall A controlled entry from user space to kernel services through INT 0x80. Syscall handling records causal context before domain-specific syscall handlers run.
  • include/syscall.h
  • kernel/core/syscall.c
  • kernel/core/syscall_graph.c
  • kernel/core/syscall_net.c
  • kernel/core/syscall_dev.c
tally A frequency aggregator for command and pipeline output. Use journal type sched 50 | tally or tally -f N to count repeated lines or fields.
  • programs/shell.c
timeline cursor The current position in a named application event chain. tl rewind, forward, at, mark, and tail navigate notes, mail, editor, process, and scheduler timelines.
  • include/timeline.h
  • kernel/graph/timeline.c
  • kernel/apps/notes.c
  • kernel/apps/mail.c
  • kernel/apps/sched_app.c
VirtIO The paravirtual PCI device interface used for block and network devices in QEMU. PCI finds devices; VirtIO queues carry block sectors and Ethernet frames.
  • include/virtio.h
  • kernel/drivers/pci.c
  • kernel/drivers/virtio.c
  • kernel/drivers/virtio_blk.c
  • kernel/drivers/virtio_net.c
web causal explorer The httpd-served /causal view: live SVG DAG, click-to-focus, and time-travel state mirror. The explorer consumes /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot.
  • programs/httpd.c
  • programs/scrub.c
  • kernel/graph/replay.c
wm The graphical tiled window manager on the 1024x768x32 framebuffer. wm opens live panels for CPU state, causal tail, tasks, and memory/system bars; Tab changes focus and q/Esc exits.
  • docs/JOURNAL.md
  • include/gfx.h
  • kernel/apps/cmd_apps.c
whatif / counterfactual Analysis that drops an event and reports downstream effects that would be eliminated. whatif summary and scrub whatif expose the counterfactual path to the operator.
  • include/whatif.h
  • kernel/graph/whatif.c
  • programs/scrub.c
  • programs/shell.c

Source atlas

Important files by subsystem.

Boot, CPU, and syscalls

arch/x86/boot.asmMultiboot entry and early assembly setup.
kernel/core/x86.cGDT, IDT, and TSS construction.
kernel/core/interrupt.cPIC/PIT, exceptions, IRQs, and scheduler tick dispatch.
kernel/core/syscall.cINT 0x80 core dispatch, terminal cooked-key input, console sizing, and causal syscall context.

Causal core and consolidated graph modules

kernel/graph/causal.cHot event ring, Lamport clock, event hashes, and read-through cache.
kernel/graph/cjournal.cPersistent journal segments, indexes, roots, and proof health.
kernel/graph/replay.cState reconstruction from causal events.
kernel/graph/timeline.cNamed application event chains and timeline persistence.
kernel/graph/analysis.cConsolidated blame, entropy, and critical-path analysis.
kernel/graph/describe.cConsolidated annotate, narrate, enrich, and context descriptions.
kernel/graph/control.cConsolidated barrier and circuit-breaker control.
kernel/graph/search.cConsolidated causal search and event-pattern logic.
kernel/graph/ops.cConsolidated heal, supervise, reactive, and trigger operations.
kernel/graph/diagnostics.cConsolidated ghost and diagnose tooling.
kernel/graph/kv.cConsolidated key-value store and watcher logic.
kernel/graph/integrity.cSnapshot and Merkle integrity support.
kernel/graph/provenance.cProvenance and timeline diff support.

Shell and operator programs

programs/shell.cUser shell, command table, cq, journal proxying, lens, tally, ctop, learn, and causal glossary.
kernel/apps/shell.cKernel shell command dispatch for ring-0 operations.
kernel/apps/cmd_graph.cKernel graph commands including cpath and cdot.
kernel/apps/script.cslosh variables, expr, conditionals, while/for loops, functions, recursion, and shell passthrough.
kernel/apps/cmd_files.cCoherent overlay file commands spanning RAM scratch and SlFS persistence.
programs/editor.cFull-screen editor using terminal syscalls, cooked keys, and console sizing.
programs/scrub.cCausal Inspector time-travel TUI and one-shot modes.
programs/httpd.cDashboard, /causal explorer, and causal API endpoints.

Remote workstation

docs/remote-access.mdCanonical remote usage guide: telnet, noiseshd, terminal size, storage, and daemon survival.
kernel/apps/telnetd.ctelnetd on port 23, noiseshd on port 5200, per-task I/O hooks, NAWS, and encrypted shell framing.
kernel/core/syscall.cSYS_TERM_GETKEY cooked-key decode and SYS_CON_GETSIZE terminal sizing.
kernel/drivers/console.cANSI emission for clear, cursor, colour, and redirected console output.
scripts/noise-shell-client.pyHost-side client for the encrypted shell.

Storage, network, actors, and applications

kernel/fs/blockfs.cPersistent SlFS implementation.
kernel/net/tcp.cTCP state machine and causal network events.
kernel/graph/actor.cActor registry, mailboxes, and routing.
kernel/graph/mesh.cPeer discovery and encrypted mesh transport.
kernel/graph/federation.cRemote actor delivery and causal graph federation.
kernel/apps/notes.cTimeline-backed notes.
kernel/apps/mail.cTimeline-backed mail with actor delivery.
kernel/apps/sched_app.cTimeline-backed future command scheduler.

Reading order

A short route through the tree.

Start at kernel/core/main.c, then read kernel/graph/causal.c, kernel/graph/cjournal.c, kernel/graph/replay.c, programs/shell.c, kernel/apps/telnetd.c, kernel/core/syscall.c, programs/scrub.c, and programs/httpd.c. After that, follow one application path through kernel/graph/timeline.c into notes, mail, editor, or scheduled commands.