Expand description
Host-side helpers that drive a saturnus_core::Machine in emulated time,
shared by the saturnus CLI and the Kermit test host: key scripts
(script), the scripted session with its idle wait (session),
the per-model boot and Kermit server start (autostart), ROM loading
(rom) and its download from hpcalc.org (fetch), the screen as
text or PNG (screen), the native hosts’ files (files) and the machine thread that drives the front-end protocol’s
state machine (saturnus_host::protocol) for the desktop app and the
CLI’s control API (runner) with its auto-saves’ writer thread
(save_writer), and the HTTP servers on 127.0.0.1 of
the control API and the desktop app’s MCP endpoint, under one set of
rules (loopback).
Unlike the core crate this one does file I/O, so it is not meant for
wasm32.
Modules§
- autostart
- Scripted boot and Kermit server start-up, shared by the CLI’s
--autostartand the Kermit test host (saturnus-kermit). - fetch
- Downloading a known ROM image from hpcalc.org on the user’s machine,
for
saturnus rom fetchand the desktop app (kb: iterations/iteration-20b-rom-download). Saturnus never hosts or proxies an image; the hosts ask the user first. - files
- The native hosts’ files: ROMs and states read with a size cap, and
states and settings written whole (a temporary file renamed over the
old one). The page never names a file; the desktop app chooses them in
dialogs and the CLI takes them on its command line, and keeps the
auto-saved states in its data folder (
StateDir). - loopback
- HTTP servers on 127.0.0.1 under one set of rules (kb:
docs/control-api-security): the CLI’s control API (
saturnus run --serve) and the desktop app’s MCP endpoint. A per-user bearer token (token), the bounded HTTP/1.1 ofhttp, and the checks and connection budgets every request passes (guard). Binding is to the IPv4 loopback address only (bind); a busy port names its listener (bind_error). - rom
- Loading ROM images with a size check. ROMs are never bundled (kb:
docs/clean-room-rule);
saturnus rom fetchdownloads them. - runner
- The machine thread of the native hosts: a thin driver around the
protocol’s state machine (
saturnus_host::protocol::Engine, shared with the Web Worker), which owns the emulator, paces it and answers the front end’s protocol (web/protocol.md). Commands arrive on a channel, events leave through aSink, replies through each command’s own channel; the thread blocks until the engine’s next deadline or the next command. Two hosts use it: the Tauri app (its window) andsaturnus run(the HTTP control API, with the serial bridge as aHook). - save_
writer - The auto-saves of a native host, written off the machine thread
(decision log, 2026-10-31). The 49G’s state is about 2.6 MB and
StateDir::savewrites it whole and fsynced; on the machine thread a key pressed meanwhile waited for the write. - screen
- Screen dumps: the text form shared with the oracle diff script, and a 1-bit PNG, to a file or in memory.
- script
- Key scripts: a small line-based format that drives the keyboard in
emulated time. See
README.md(“Key scripts”) for the format. - session
- Drives a
Machinein emulated time: fixed runs, key script actions and the “wait until idle” heuristic.