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

First run

Native 64-bit prerequisites and a QEMU user shell with a disposable disk.

Development

Current source state, isolated builds, validation and limitations.

Local Hew

Slepp’s personal source-to-ELF experiment, not official Hew support.

Manual

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

Causality

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

Source plates

Dated illustrative source excerpts with a current file atlas.

Showcase

Recorded sessions mapped to commands and subsystems.

Glossary

TermExplanationWhere it appearsSource files
preemptive scheduler The kernel can switch tasks on timer interrupts rather than waiting for each task to yield. Native QEMU targets default to four CPUs with preemptive AP-pinned kernel work. User programs and general services remain on CPU 0; Hew’s cooperative process worker is a separate scheduling boundary.
  • kernel/core/task.c
  • kernel/core/native_smp.c
  • include/spinlock.h
Hew-on-SlOS (local) Slepp’s personal modern-Hew runtime port, not an official Hew project or upstream target. /hew documents host-compiled x86-64/AArch64 objects linked with the restricted freestanding runtime and generic LP64 SDK as ELF64. Owned values, cooperative actors/tasks, files, streams and TCP are exercised in real guests. This is not full Rust-runtime/stdlib parity; the older C SDK/mailbox example remains separate.
  • docs/HEW.md
  • lib/slos.h
dev VM A fresh disposable native 64-bit QEMU session started with make dev. DOOM=0, default native SMP, serial and no host forwards. Successful disposable sessions remove their image; failures retain it. DEV_DISK=my-slos.img explicitly requests persistence; SLOS_QEMU_HOSTFWD adds opt-in rules.
  • scripts/dev-vm.py
  • docs/manuals/OPERATOR.md
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
external pipeline Up to four installed user-program stages execute concurrently through bounded streams. The native shell supports binary first-stage < file and final > / >> output, feeding stdin while draining stdout. It closes unused endpoints and collects child statuses. All-builtin rescue composition remains buffered; mixed builtin/external composition is rejected. This is not a full POSIX shell.
  • programs/shell.c
  • docs/USER_IO.md
  • docs/shell.md
SMP auto-offload (historical) The retired i386 scheduler could retarget explicitly eligible kernel tasks to idle APs for cooperative execution. This is not native SMP. Current x86-64/AArch64 QEMU targets default to four CPUs with preemptive AP-pinned kernel work; users and general services stay on CPU 0. Native automatic offload and migration are not implemented.
  • docs/smp.md
  • kernel/core/native_smp.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 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.

Source reading order

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.