Operating manual

SlOS is a native x86-64/AArch64 operating system whose operating record is a causal DAG. This manual describes how to boot it, ask what happened, query durable history, scrub time, and inspect the source plates.

Read the application guide for C/Hew editing, ledger and queue examples, installed reports and saved-project recovery. Building SlOS describes the native platform. Older graphical transcripts and source plates retain their i386 scope.

First run Application guide Building SlOS Personal local Hew experiment Causality laboratory Subsystems Kernel visual atlas Source plates Showcase Distributed computing Durable debugger

Machine identity

SlOS is a personal, unreleased hobby OS. Its native x86-64 and AArch64/QEMU virt targets run private ELF64 user programs through an LP64 SDK, with VirtIO block/network devices and persistent SlFS. x86-32 is retired. Follow /start for prerequisites and disposable make dev operation.

The kernel scheduler is preemptive. Kernel actors and mesh messaging are separate from the cooperative runtime subset in Slepp’s local Hew-on-SlOS offshoot; /hew records its source-to-ELF proofs and limits, not an official Hew target.

The distinguishing device is the causal graph. Scheduler actions, syscalls, filesystem work, network packets, actor messages, mesh traffic, and application changes are recorded as events with Lamport time and parent event IDs.

Recent and durable history

The hot graph is a bounded in-memory ring for immediate inspection. The persistent causal journal, cjournal, spills history to SlFS segments with event hashes, Merkle roots, and epoch proofs.

Use read-through commands when an event has aged out of the ring: events -a, cq -a, why -a, trace -a, and journal subcommands consult archived history instead of only live memory.

Time-travel operation

Replay reconstructs state by scanning causal events up to a chosen tick. The scrub program is the operator surface: a TUI for moving through ticks, focusing on events, comparing ticks, and exporting JSON.

Counterfactual analysis is explicit. whatif and scrub whatif drop an event in analysis and report the downstream effects that would disappear.

Web causal explorer

The user-space httpd program serves a live dashboard and a /causal explorer. The explorer draws an SVG causal DAG, lets the reader focus events, and mirrors the time-travel state used by scrub.

The API surface is small and inspectable: /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot.

Remote workstation

telnetd listens on guest port 23, forwarded by the default QEMU run to localhost:2323. noiseshd listens on port 5200 and uses an ephemeral X25519 exchange followed by ChaCha20-Poly1305 frames. It is a from-scratch confidential channel, not OpenSSH, and it does not yet authenticate the server.

The remote shell is more than line input. Per-task I/O hooks redirect console output and input, console cursor/clear/colour emit ANSI, SYS_TERM_GETKEY decodes arrows and Ctrl combinations from the byte stream, and telnet NAWS supplies terminal size for editor and pager sessions.

Use /home/... for persistent work and /tmp or relative paths for RAM scratch. Long-lived service commands such as httpd detach from the session, so a service started remotely can survive exit or a dropped connection.

Timelines and graph-native applications

Timelines are named chains of causal events. Notes, mail, the editor, process timeline viewing, and scheduled commands treat application state as replayable history rather than opaque mutable files.

Use tl list/show/rewind/forward/at/mark/tail as the shared manual controls, then operate note, mail, edit, proc, schedule, and scheduled for application-specific views.

Per-core and graphical operation

Native x86-64 and AArch64/QEMU virt default to SMP=1 CPUS=4. Explicitly AP-pinned kernel work is preemptive; user programs, allocation, filesystems, networking and general services remain on CPU 0. Native automatic offload and user migration are not implemented. SMP=0 CPUS=1 selects UP debugging.

The historical i386 wm demonstration turns a 1024x768 framebuffer into tiled CPU, causal-tail, task and memory panels. It is not evidence that the old desktop or DOOM has been ported to the native targets. Current CPU snapshots and concurrency checks are described on /development.

Application workbench and saved projects

The native workbench opens a private developer VM with the editor and develop client. Write C or multi-file Hew in the guest, compile through a trusted Linux worker and run the checked ELF64 in SlOS. diagnostics revisits checked feedback; edit opens its source line; status distinguishes source edits from the installed program.

A failed build leaves the last good application available. rollback changes program selection without discarding current edits or application data outside the project. The ledger and supervised job queue demonstrate that separation; the queue can start through the installed service manager at boot.

For an ordinary handoff, save, run fsck and halt. Interrupted originals are not silently resumed. Read-only rescue, recovery on a new v2 copy and checked project import provide an explicit path to a fresh session with new credentials. Unsaved buffers and unrelated application data are not included.

Installed Hew tools and services

The local Hew userland includes text, filesystem, data, system, network and causal commands, alongside base stream tools. Installed programs resolve through the selected bundle and have their own help. Familiar names describe bounded practical subsets rather than full GNU/POSIX behaviour; C rescue builtins remain separate.

The report workspace accepts canonical expense TSV inputs, publishes immutable reports and preserves working data outside versioned installations. Bundle update and rollback select checked code without erasing that data.

The distributed renderer assigns actual guest computation across x86-64 and AArch64 workers. Its durable debugger follows result, assignment, process and configuration records across boots. Remote reports, checked local state and missing evidence remain distinct.

Actors, mesh, and proofs

Actors are named message endpoints with local mailboxes and routes that can cross the mesh. Mesh and federation commands expose peer identity, routing, remote actor delivery, and causal graph exchange.

Proof commands make the archive auditable: prove, cproof, verify proof-health, journal json selfcheck, journal verify, journal proof-health, and cq -a epoch-proof inspect hash chains and epoch roots.

Build and boot

make doctor
make first-user-check
make dev
make dev DEV_DISK=my-slos.img
make check

Causal inspection commands

slos:/$ events 10
slos:/$ why last
slos:/$ trace -a last
slos:/$ cq -a subsystem=sched limit=8 -l
slos:/$ journal proof-health --json-ish
slos:/$ cwatch tail --once
slos:/$ cpu
slos:/$ scrub event last
slos:/$ httpd

Remote terminal access

Use telnet for the plain path and the bundled Python client for the encrypted path. The encrypted shell is confidential but not server-authenticated yet.

# Separate persistent/forwarded workflow; make dev has no host forwards
# Start with make DOOM=0 SMP=0 run-nographic
# host terminal, with legacy run defaults
telnet localhost 2323
# or encrypted from the SlOS repo
python3 scripts/noise-shell-client.py localhost 5200

# SlOS shell
termsize
edit /home/day/hello.sl
run /home/day/hello.sl
httpd
exit

# host terminal
curl http://localhost:8080/

Command reference

The commands below operate on live state, archived events, and guest applications. The source map identifies their implementations.

Installed Hew programs have their own CLI and may take precedence over a same-named kernel command. Use kcmd to select the kernel history forms below, and --help for the installed program's interface. The command toolbox explains that distinction.

Native application workbench

`exec /develop.elf init PROJECT [hew]`	Create a C or Hew workspace without overwriting existing source.
`exec editor PATH; exec editor PATH +LINE`	Edit source, or open a positive one-based line. Ctrl-S saves; Ctrl-Q protects unsaved changes.
`exec /develop.elf build PROJECT`	Submit the declared sources to the trusted worker and install only a checked native result. Compiler errors retain the last good program.
`exec /develop.elf run PROJECT -- ARGUMENT`	Run the selected application and wait for its real exit status.
`exec /develop.elf status PROJECT; exec /develop.elf diagnostics PROJECT`	Inspect saved build choices, current edits and checked compiler feedback without contacting the worker.
`exec /develop.elf edit PROJECT`	Open the first safe manifest source-and-line location in retained diagnostics.
`exec /develop.elf rollback PROJECT`	Verify and select the previous program without reverting current source edits.
`exec /develop.elf run-saved PROJECT`	In an already readable guest, verify only the installed selection while preserving pending evidence. Not filesystem repair or unsafe resume.

Installed application examples

`report accept ID PATH; report run ID; report status ID`	Accept an immutable expense-input snapshot, generate a checked report and inspect its state in the installed workspace.
`bundle versions; bundle rollback`	Inspect installed versions or verify and select a predecessor while retaining working data.
`exec service status; exec service logs`	Inspect the installed boot service and its bounded lifecycle log.
`exec service stop; exec service start`	Stop before a project update, then launch its verified selected program.
`why job ID; why service; why inspect RECEIPT_ID`	With the debugger bundle installed, inspect durable application evidence. Use kcmd why for the separate kernel history command.

Causal graph

`events [N]`	List recent events from the live causal ring.
`why <id\|last>`	Explain an event by showing its causal chain. why --md exports the chain as Markdown.
`trace <id>; trace -a <id\|first\|last>`	Walk parent events backward through the DAG; -a reads through the durable journal.
`graph [N]`	Draw a compact ASCII DAG of recent events.
`blast <id>`	Walk downstream effects caused by an event.
`cpath <a> <b>`	Find a causal path from event a to event b; cpath common finds a nearest common ancestor.
`cdot <id\|last> [effects]`	Emit Graphviz DOT for causes or downstream effects.
`cwatch \| cwatch tail [--once]`	Live-tail the causal graph from the current head until any key is pressed; --once prints a bounded sample for automation.

Operator toolkit

`triage`	One-screen incident verdict (HEALTHY/DEGRADED/CRITICAL) plus one next action, composing entropy, blame, critical-path, journal, and contract checks.
`cbisect <metric> <N>`	git-bisect over replayable history: binary-search the tick timeline for the earliest tick a cumulative metric (events/tasks/net/fs/actors/syscalls) reached N, reconstructing state per probe via replay.
`cdb break ...; cdb run\|bt\|step\|print`	A stateful debugger for causation: predicate breakpoints, a persistent cursor, bt walks causes and step walks effects across shell calls.
`cprof [window]`	Profile causal flow across cause-to-effect subsystem boundaries, marking cross-subsystem crossings.
`attest <id\|last>; attest verify <id>`	Emit a self-contained Ed25519-signed receipt for one outcome, and re-verify its signature against the node key.
`capsule <id\|last>`	Write a portable causal incident bundle (event slice, hash, and proof) to SlFS at /capsule/<id>.txt.
`why -r <id\|last>`	Walk the cause chain, tagging each hop with its origin node (local or imported).

Durable journal and query

`journal recent\|find\|type\|subsystem\|stats\|filter\|verify\|json selfcheck\|proof-health`	Operate the persistent causal journal on SlFS.
`events -a [N]`	Browse archived events after they spill from the live ring.
`cq type=T subsystem=S desc~TEXT since=T until=T id=N limit=N -l --json-ish`	Query the live causal ring with selectors and long or json-ish output.
`cq -a ...`	Run the same style of query against archived journal history.
`cq -a id=N epoch-proof --json-ish`	Fetch an epoch proof for one archived event.
`lens save <name> <command...>; lens list; lens run <name>`	Persist named causal queries to SlFS.
`grep\|head\|tail\|wc [file]`	Read from a file or, with no file argument, from pipeline stdin.
`cmd1 \| cmd2 [\| cmd3 \| cmd4]`	Native all-external pipelines run concurrently through bounded streams, with first-stage < file and final > / >> output. All-builtin rescue composition remains buffered; mixed builtin/external composition is rejected.
`tally [-f N] <file>`	Aggregate pipeline output by whole line or field, for example journal type sched 50 \| tally.

Time travel

`replay`	Reconstruct recorded state from causal events.
`rewind`	Move reconstructed state back through event history.
`scrub`	Open the full-screen causal time-travel inspector.
`scrub <tick>`	Print reconstructed state at a tick.
`scrub event <id\|last>`	Focus one event, its parents, and its effects.
`scrub diff <a> <b>`	Show state deltas between two ticks.
`scrub json [tick]`	Emit reconstructed state as JSON.
`whatif summary <id>; scrub whatif <id\|last>`	Drop one event in analysis and report eliminated downstream effects.

Remote workstation, files, and slosh

`telnet localhost 2323`	Host-side entry to telnetd through the default QEMU host forward; on real or bridged networking use guest port 23.
`python3 scripts/noise-shell-client.py localhost 5200`	Host-side client for noiseshd. The channel is X25519 plus ChaCha20-Poly1305, currently without server authentication.
`exit; logout`	Close the current remote shell session cleanly. Multiple sessions may be open concurrently.
`termsize`	Report the terminal size SlOS is using; telnet NAWS can update it, otherwise the safe default is 80x25.
`edit /home/day.txt`	Open the full-screen editor through terminal redirection. Arrow keys and Ctrl-S/Ctrl-Q are decoded from the stream.
`cat\|more\|less\|head\|tail\|wc\|grep\|cp\|mv\|rm\|mkdir\|touch\|write\|cd\|pwd`	Operate one coherent namespace: /tmp and relative paths are RAM scratch; other absolute paths such as /home/... persist to SlFS.
`run /home/script.sl; slosh`	Run slosh scripts or the REPL. Functions, $1..$9 parameters, return, recursion, for loops, and shell-command passthrough are available.

SMP, desktop, and TCP services

`smp; cpus`	Show CPU inventory and APIC status.
`cpu`	Print active state, current task/PID, context-switch count, and idle/busy state for each CPU.
`smp test`	Exercise explicitly AP-pinned native kernel work alongside a BSP user process.
`Historical i386: smp runon <cpu>; smp offload <n>`	Earlier cooperative offload demonstrations, not the native automatic-offload API.
`Historical i386: wm`	The recorded 1024x768 tiled desktop; its presence in older media does not establish a native application port.
`chatd [start\|stop\|status]`	Run the IRC-lite TCP chat server on port 6667, up to eight clients, with /nick and join/leave broadcast.

Web, applications, actors

`httpd`	Serve the live dashboard, /causal explorer, and causal API endpoints.
`tl list\|show\|rewind\|forward\|at\|mark\|tail`	Navigate named application event timelines.
`note; mail; edit; proc; schedule; scheduled`	Operate graph-native notes, mail, editor, process timelines, and future commands.
`actors; send; recv; routes; watch`	Inspect and use actor mailboxes and routing.
`mesh; federation; routes; ping; netstat; arp`	Inspect peer transport, remote delivery, and network state.
`prove; cproof; verify proof-health; journal proof-health`	Inspect causal proofs and journal proof health.
`causal; learn; ctop`	Read the built-in glossary, run the guided causality tour, and monitor causal activity.
`doom; rogue; browser; wget; crash`	Run representative programs and Kernel Surgeon demonstrations.

CPU and task monitoring

wm, cpu, and cwatch expose the same operating facts at different scales: framebuffer dashboard, table snapshot, and live graph tail.

slos:/$ wm
# tiled 1024x768 framebuffer desktop
# Tab cycles focus; q/Esc returns to the shell

slos:/$ cpu
CPU ACTIVE CURRENT SWITCHES STATE
0   yes    shell   1842     busy
1   yes    idle/1  17       idle

slos:/$ cwatch tail --once
#8842 SCHED sched offload pid=47 to=cpu1

Causal explorer endpoints

Run httpd inside SlOS and open the forwarded QEMU port. The dashboard links to /causal; API routes provide state, recent events, graph JSON, and DOT.

GET /causal
GET /api/causal/state
GET /api/causal/recent
GET /api/causal/graph
GET /api/causal/dot

Source map

Area	Files	Read for
Causal graph	`include/causal.h; kernel/graph/causal.c`	Event record, Lamport clock, parent edges, hot ring, and read-through cache.
Persistent journal	`include/cjournal.h; kernel/graph/cjournal.c`	SlFS segment files, indexes, hashes, Merkle roots, and epoch proofs.
Replay and what-if	`include/replay.h; kernel/graph/replay.c; kernel/graph/whatif.c; programs/scrub.c`	State reconstruction, scrub TUI, diffs, JSON, and counterfactual impact.
Query and command surface	`programs/shell.c; kernel/apps/shell.c; kernel/apps/cmd_graph.c`	Shell commands including cq, journal, cwatch, cpath, cdot, lens, pipelines, tally, learn, and ctop.
Remote terminal	`docs/remote-access.md; kernel/apps/telnetd.c; kernel/core/syscall.c; kernel/drivers/console.c; programs/editor.c; scripts/noise-shell-client.py`	telnetd/noiseshd, terminal redirection, cooked-key input, console sizing, ANSI output, remote editor, and host encrypted-shell client.
Files and slosh	`kernel/apps/cmd_files.c; include/fs_route.h; kernel/apps/script.c; docs/scripting.md`	Overlay namespace, persistent /home paths, RAM scratch, file commands, slosh functions, recursion, for loops, and shell passthrough.
Native SMP	`kernel/core/task.c; kernel/core/native_smp.c; include/smp.h`	Preemptive AP-pinned kernel work, per-CPU state and BSP-owned user services.
Application workbench	`programs/develop.c; programs/editor.c; scripts/development-worker.py; scripts/development-console.py`	Guest editing, trusted host compilation, checked program selection, diagnostics and clean session handoff.
Saved-project recovery	`scripts/development-rescue.py; scripts/development-recover.py; scripts/development-import.py`	Original-preserving checked export and fresh-session continuation.
Web explorer	`programs/httpd.c`	HTTP dashboard, /causal page, and /api/causal endpoints.
Timelines and apps	`kernel/graph/timeline.c; kernel/apps/notes.c; kernel/apps/mail.c; programs/editor.c; kernel/apps/sched_app.c`	Event-backed applications and timeline navigation.
Mesh and proofs	`kernel/graph/actor.c; kernel/graph/mesh.c; kernel/graph/federation.c; kernel/graph/prove.c`	Named actors, encrypted peer channels, remote delivery, and verification.