Shell support matrix#

The simulated shell in crates/computer is a bounded reimplementation, not a POSIX shell. This page is the published surface: if a flag is not listed here it is not supported, and invoking it fails with a non-zero status rather than being ignored. crates/computer/tests/shell_conformance.rs runs every row below, so the table cannot drift away from the code.

Two words are used throughout:

• modelled — real semantics computed from simulation state (the VFS, the process table, the environment, the tick). The answer changes when the world changes.
• fixed — a plausible constant read from Computer::hardware. The world does not simulate the underlying fact (cores, RAM, disk capacity, a NIC), so the value is stable per computer, identical on every call and every replay, and never sampled from the host. Change it by editing Computer::hardware before the episode runs.

Exit codes#

Every command returns a truthful status in CommandResult::exit_code. Classify by the code; do not regex-match stderr.

This vocabulary is deliberately narrower than GNU coreutils, which spends 2 on per-tool operational errors. Here 2 always means you asked for something this world does not implement — the one distinction a porting consumer actually needs.

The error contract#

Every diagnostic this shell prints follows one shape, and every command that prints one exits non-zero. The wording is GNU coreutils' own, because that is what scripts and people match against:

The reason half is strerror's wording, mapped from the VFS's own errors:

An unknown or unimplemented flag is always status 2 and always names itself. crates/computer/tests/shell_conformance.rs runs every command in the table below with an invented long flag and an invented short flag and asserts both are refused by name; a flag that is accepted and then ignored is the one bug this suite exists to prevent. Where a flag is accepted but does nothing, the table says so explicitly and gives the reason — xargs -P (commands run sequentially so a replay is identical), ls -1 (output is already one entry per line), md5sum -b/-t (the VFS has no text/binary distinction), tee -i (this world delivers no signals). 127 is reserved for a command that does not exist; nothing else uses it.

Nested shells (sh -c, bash script, executable scripts) and git propagate their inner status rather than collapsing it to 1, and a nested shell's stderr reaches the caller even when it exits 0, so a script never loses what it printed. CommandResult is serialised whole by terminal.v1 execute, so the code reaches API consumers. The desktop terminal window renders only stdout + stderr; GUI-driven agents read the code from the machine's terminal state value instead.

Grammar#

Word splitting#

An unquoted expansion is split on whitespace and a quoted one is not, as in bash, so X='a b'; cmd $X passes two arguments and cmd "$X" passes one. An unquoted expansion that comes out empty contributes no argument at all, which is the difference between cmd $EMPTY and cmd "$EMPTY". A * that arrives from a variable stays literal; only a * written in the source globs, so data never becomes a pattern.

Standard input inside a compound#

< f on a compound, and a pipe into one, give its body a single shared stream. read takes one line from it and leaves the rest — that is what makes while read line; do …; done < f advance and then stop. Any other command is handed the stream only if it would actually read it (cat, tr, tee, xargs, and grep/sed/awk/cut/ head/tail/wc/sort/uniq/nl/rev/fold/expand/unexpand/paste/shuf/ split/strings/base64/md5sum/sha1sum/sha256sum/xxd/od/hexdump when no operand names an existing file), and it consumes the whole of it. A loop body that ignores stdin therefore cannot swallow the lines the loop is reading.

Limits#

A deterministic simulator must never hang, so every bound is a status, not a wait. All four are per execute call and are refused with status 2:

The step budget usually trips first, because every iteration of a loop runs at least one command. A nested shell (sh -c, a script, a command substitution) starts a fresh budget, so the worst case is bounded by depth × budget — finite, and identical on every replay.

Commands#

find#

Every predicate below really filters; an unknown one is refused by name with status 2 rather than ignored, because a search that silently returns the wrong set is worse than one that says it cannot.

-print is appended only when nothing in the expression already has an effect, so find . -prune still prints and find . -quit does not.

Refused by name rather than half-done: -L / -H / -follow and -xtype (only -P, not following links, is honest here), -ok / -okdir (there is no terminal to prompt at), -type b|c|p|s (this world has no device, FIFO or socket nodes), -perm +MODE (withdrawn by GNU itself), symbolic X in -perm, relative words in -newermt, and any -printf conversion or escape not listed above.

Two deliberate differences from GNU: a directory's entries are visited in sorted order rather than readdir order, because a deterministic simulator must give the same answer twice; and -exec hands its argument vector to a nested shell run, which starts a fresh nesting budget, so find refuses an -exec that is already 32 levels deep.

Archives#

tar, gzip and zip write and read real container bytes, verified in both directions against GNU tar, gzip, unzip and Python's tarfile: an archive made in the simulation unpacks on a host, and a host archive unpacks in the simulation. That is why these are commands rather than a convenience format — a world where tar -czf produced something only this world could read would be a trap.

There is one compressor under all of it, cw-zlib, the same one Python's zlib and Node's zlib use here: a real DEFLATE encoder at the level asked for, and an inflate covering stored, fixed-Huffman and dynamic-Huffman blocks. So tar -czf, gzip and a method-8 .zip member all really compress, and real-world .gz and .zip files really decompress. GNU gzip's own encoder is not reproduced byte for byte — the bytes are zlib's — but every reader accepts them.

Anything the format cannot carry faithfully is refused by name: a member whose path does not fit ustar's prefix/name split, a link target over 100 bytes, a hard-link or device typeflag, a zip compression method other than 0 or 8, and any member whose path would escape the extraction directory.

awk#

awk (crates/computer/src/awk.rs) is the POSIX language, not a field-printing shortcut: a lexer, a recursive-descent parser and an interpreter with the whole value model. gawk, mawk and nawk are the same command.

Values. A scalar is uninitialised, a number, a string, or a string from input. The last is the rule that makes real scripts work: a field or a getline result that reads entirely as a number compares numerically, so $1 == 10 is true for a line containing 10.0, while "10" == 10 compares the string constant as a string. An uninitialised value equals both 0 and "". Numbers print as integers when they are integral and through CONVFMT (OFMT for print) when they are not.

Records and fields. RS is a single character, a multi-character regular expression, or "" for paragraph mode (a blank line separates records and a newline always separates fields). FS is a single character taken literally, a regular expression when longer, " " for the default blank-run split, and "" to split into characters; -Ft means a tab, as in every awk. Assigning $n past NF pads the record, assigning NF truncates it, and either rebuilds $0 with OFS.

Determinism. for (k in a) walks the subscripts in sorted order. POSIX leaves the order unspecified; this world fixes it so a replay is identical. rand() is a 48-bit LCG seeded from the world; srand() with no argument seeds from the simulated tick, not a host clock, and returns the previous seed.

Streams. print > "file" and print >> "file" buffer and write through the VFS. print | "cmd" buffers its text and runs cmd when the pipe is closed — by close("cmd"), fflush(), system(), or the end of the program — and the command's output is spliced into awk's own at that moment. There is no second process to schedule, so this is the honest ordering; it makes print | "sort" behave exactly as expected. "cmd" | getline runs the command once and reads its output as records. getline < "file" returns 1, 0 at end of file, and -1 when the file cannot be opened — it never aborts the program.

Function parameters. Parameters beyond the arguments are locals. Whether a parameter is a scalar or an array is decided from how the function body uses it (subscripted, walked with for … in, deleted, filled by split, or passed on to another function's array parameter), computed once as a fixpoint over the whole program; an array parameter is shared with the caller by reference.

Bounds. A program is stopped with status 2 after 2 000 000 evaluation steps or 256 nested function calls, so a runaway while(1) ends rather than hanging the world.

awk --version and sed --version print … (computerworld) POSIX profile, so a script that probes for a GNU-only feature by version string gets an honest answer rather than a number it can compare against.

sed#

sed (crates/computer/src/sed.rs) runs a real cycle: a pattern space, a hold space, an append queue, branch labels and a program counter. -i and -s process each file separately; otherwise every operand is one stream, so $ is the last line of the last file and line numbers run on.

Basic and extended regular expressions really differ. In a BRE, \(…\) groups, \{n,m\} repeats, \| alternates and \+/\? are GNU's extensions, while the bare characters are literals; * is a literal at the start of an expression and ^/$ anchor only at the edges. -E (or -r) swaps the two. \< and \> both become a word boundary, because the engine has no lookaround. A backreference inside a pattern is refused by name — the engine cannot backtrack — while \1–\9 in a replacement work, as do &, \&, and GNU's \U \L \u \l \E case operators.

a, i and c take both the POSIX a\ + text form and GNU's one-line a text. c on a range prints its text once, at the end of the range. w and s///w write through the VFS (with /dev/stdout writing to standard output), r and R read from it. q's code becomes the exit status and everything already printed still reaches the caller; Q quits without the final auto-print.

file#

file reads the stored bytes and reports only what this world can actually produce, so it never guesses:

A directory is directory and a symlink is symbolic link to TARGET unless -L follows it. -i maps the same table onto a MIME type.

git#

git is a synthetic, content-addressed Git: commits hold whole file trees, the index is a real staging area and the worktree is the machine's own files, so status, diff and a commit all say what the disk says. A revision is HEAD, HEAD~<n> (or HEAD^…), a branch name, or a commit hash (a unique prefix of at least four characters is enough).

A folder (or .) as a path stands for every file under it. Visual Studio Code's Source Control view runs exactly these commands: its + is git add, its − is git restore --staged, Unstage All Changes is git reset, and Discard Changes is git restore (an untracked file is moved to the trash instead).

sqlite3#

sqlite3 runs the pure cw-sql engine (crates/sql), which follows SQLite 3.45.1's dialect, messages and shell output. FILE is resolved against the working directory and read and written through the same permission checks as cat and a redirect; :memory: or no file is a scratch database. Every argument after FILE is run in order (SQL or a dot-command) and the first error ends the run; with no SQL arguments the shell reads its standard input instead, so echo 'select 1;' | sqlite3 f.db, a heredoc and < script.sql all work. There is no interactive prompt: each terminal line is one invocation.

Errors use the real shell's wording and go to stderr: Error: in prepare, … and Error: stepping, … (19) for arguments, Parse error near line N: … and Runtime error near line N: … for scripts, with a caret under syntax errors. The status is 1 when any statement failed. A database is written back only when its content changed, as one whole-file VFS write (so no reader ever sees half a save); a file that was only read is never created, and a transaction still open at exit is rolled back. 'now' and CURRENT_TIMESTAMP read the simulated clock, and random() is a seeded stream, so every replay agrees.

The engine implements tables with PRIMARY KEY, NOT NULL, UNIQUE, CHECK, DEFAULT, COLLATE and REFERENCES (enforced with PRAGMA foreign_keys = ON, including CASCADE, SET NULL and SET DEFAULT), AUTOINCREMENT, WITHOUT ROWID tables (stored, as SQLite stores them, as an index B-tree in primary key order), B-tree indexes the planner uses for equality, IN and range lookups and to avoid sorts (EXPLAIN QUERY PLAN shows the choice, including USING COVERING INDEX when the index holds every column the query reads and USING PRIMARY KEY for a WITHOUT ROWID table), views, triggers (BEFORE, AFTER and INSTEAD OF on INSERT, UPDATE [OF columns] and DELETE, FOR EACH ROW with WHEN, NEW and OLD, and RAISE(IGNORE | ABORT | FAIL | ROLLBACK, message); the newest fires first, recursive_triggers is off, foreign key actions fire the child's triggers, and a view with INSTEAD OF triggers takes writes), ALTER TABLE (rename, add, rename and drop column; renames rewrite triggers, indexes and the views that read the table, quoting the new name as the statement did), joins (inner, left, right, full, cross, USING, NATURAL), grouping, aggregates, compound selects, scalar, IN and EXISTS subqueries, recursive CTEs, upsert, RETURNING, transactions and savepoints. Refused by name rather than half-done: window functions, partial and expression indexes, generated columns, ATTACH, virtual tables, JSON operators and bytecode EXPLAIN. Foreign keys are checked immediately rather than deferred to the end of the statement.

Language runtimes#

python3 (crate cw-pyvm) and node (crate cw-jsvm) are interpreters written in Rust that run inside the simulation. They are commands like any other: they resolve through PATH and which, read stdin from a pipe or here-document, write to the pipe or redirection that follows them, and set $?. A script with a #!/usr/bin/env python3, #!/usr/bin/python3, #!/usr/bin/env node or #!/usr/bin/node line runs under that interpreter when executed by path after chmod +x.

Both see exactly what the rest of the shell sees and nothing of the host:

• Files are the computer's VFS, with the current user's permissions, relative to the shell's working directory. A program's os.chdir / process.chdir moves only the program, never the shell.
• Time is the simulated clock. time.time(), Date.now() and new Date() start at the world tick; timers, time.sleep, setTimeout and setInterval advance a virtual clock and never block the host. Executing code takes virtual time as well (one millisecond per 100 000 node instructions), so a busy-wait on Date.now() ends. The timezone is UTC.
• Randomness (random, secrets, Math.random, crypto.randomBytes, crypto.randomUUID) is drawn from the world's seeded entropy, so a replay prints the same numbers. random.seed(n) streams match CPython exactly.
• Resources are bounded: a program that exceeds its instruction budget (50 million steps for python3, 200 million for node) stops with a TimeoutError and status 124; the budget cannot be caught. Deep recursion is Python's RecursionError or Node's RangeError: Maximum call stack size exceeded, not a host crash.

Output reproduces the real tools, byte for byte where it is observable: print, repr and tracebacks for Python; console.log / util.inspect formatting, uncaught-error reports (source line, caret, stack with Node's internal frames, Node.js v24.21.0), unhandled rejections and exit codes for Node. Conformance corpora of whole programs with outputs recorded from CPython 3.12 and Node 24.21 live in crates/pyvm/tests/programs and crates/jsvm/tests/programs.

node implements the language through ES2023 (classes with private members, generators, async functions and async iterators, destructuring, spread, optional chaining, BigInt, tagged templates, Proxy/Reflect, typed arrays, DataView, WeakRef, labelled statements, getters and setters, ES modules with top-level await and dynamic import()), CommonJS require with Node's resolution (node_modules, index.js, package.json main, JSON files, require.cache), and a Node-shaped event loop (process.nextTick, microtasks, timers, immediates, process.on('exit'), 'uncaughtException' and 'unhandledRejection'). Built-in modules: fs (sync, callback and promise APIs), fs/promises, path, os, events, util, assert (assert/strict), readline (readline/promises), url, querystring, string_decoder, stream (a subset), buffer, crypto (hashes, HMAC, random), timers, timers/promises, perf_hooks, process, child_process, http, https, net, dns (dns/promises), zlib. Globals include Buffer, URL, URLSearchParams, TextEncoder, TextDecoder, AbortController, structuredClone, atob/btoa, queueMicrotask, a crypto object, and fetch with Headers, Request, Response, FormData, Blob, File and a minimal ReadableStream.

Network#

Both runtimes reach the simulated network exactly as the machine's other clients do (the browser, curl): every request goes through the world's DNS, routes, gateway policy and listeners, reaches the service's handler, and takes the simulated time the world charges for it. Nothing reaches the host.

• Python: urllib.request (urlopen, Request, openers and handlers, redirects, HTTPError/URLError, file: and data: URLs), urllib.parse, http.client (HTTPConnection, HTTPSConnection), http.HTTPStatus, ssl (contexts that carry settings), and socket (getaddrinfo, gethostbyname and friends against the world's DNS; create_connection, connect, sendall, recv, makefile).
• Node: http/https (request, get, Agent, IncomingMessage, createServer), global fetch (redirects, AbortSignal), net (Socket, connect, createServer) and dns (lookup, resolve4/resolve6/resolve, reverse, promises). Replies arrive as I/O completions at their simulated time.

A TCP connection to another machine is accepted or refused by the world (DNS, route, a listening service). Every simulated service speaks HTTP, so the bytes written on a socket are parsed as HTTP/1.x requests and each one is carried through the world's network; the answer comes back as HTTP/1.1 bytes (Content-Length, Connection honoured). Bytes that are not HTTP get 400 Bad Request and the connection closes, as a web server would. UDP datagrams to other machines are sent and lost (no UDP services exist). Servers a program creates (socket.bind/listen/accept, http.createServer, net.createServer) accept connections from that same program: other machines cannot reach a process that lives for one command.

TLS follows the browser's model: an https:// request goes to port 443 of the host and the world decides whether anything answers there; in the reference world the services listen on port 80, so https:// is refused (ECONNREFUSED, [Errno 111] Connection refused) exactly as the browser sees it. Errors carry the real vocabularies: socket.gaierror: [Errno -2] Name or service not known, getaddrinfo ENOTFOUND host, connect ECONNREFUSED 10.0.1.10:443, TypeError: fetch failed with the cause attached. A client timeout that the simulated latency exceeds raises TimeoutError: timed out / ETIMEDOUT.

Threads#

Python's threading runs on a deterministic green-thread scheduler inside the interpreter: Thread (with name, daemon, join(timeout), is_alive, ident, native_id), Lock, RLock, Condition, Event, Semaphore, BoundedSemaphore, Barrier, Timer, local, current_thread, main_thread, enumerate, active_count, excepthook/ExceptHookArgs, stack_size and get_ident; queue (Queue, LifoQueue, PriorityQueue, SimpleQueue, task_done/join, shutdown) and concurrent.futures (Future, Executor, ThreadPoolExecutor, map, as_completed, wait, FIRST_COMPLETED/FIRST_EXCEPTION/ALL_COMPLETED) are built on it.

Only one thread runs at a time, as under CPython's GIL, and the interpreter switches between threads after a fixed number of bytecode instructions. That quantum derives from the world seed (scaled by sys.setswitchinterval), so a race — a lost update, an interleaved log, the order two threads leave a semaphore — replays exactly the same way every time the world runs, and differently under a different seed. time.sleep in a thread advances only that thread on the simulated clock: three threads sleeping 50 ms each finish after 50 ms of simulated time, and waits end in deadline order. A thread that raises is reported as threading.excepthook does (Exception in thread NAME: and the traceback on standard error) and the program goes on; the interpreter waits for non-daemon threads to finish and abandons daemon ones. A wait nothing can satisfy is not a hang: the blocked thread gets RuntimeError: deadlock: every thread is waiting and none can make progress, which unwinds its frames (releasing what it held) and is reported like any other thread failure.

Node's worker_threads runs the same way: a worker is another JavaScript context — its own global object, module registry, microtask queue and timers — that the interpreter swaps in when it is that context's turn. Worker (workerData, eval, transferList, postMessage, terminate, threadId, and the online, message, error and exit events), parentPort, isMainThread, threadId, MessageChannel, MessagePort (postMessage, on('message'), start, close, ref/unref, onmessage), receiveMessageOnPort and markAsUntransferable are there, together with SharedArrayBuffer and the whole of Atomics (add, and, compareExchange, exchange, load, or, store, sub, xor, isLockFree, pause, wait, waitAsync, notify).

A message is structured-cloned on its way across, so the two sides share nothing — except a SharedArrayBuffer, whose bytes both contexts go on reading and writing, which is what Atomics works on. Only one context runs at a time, and it runs until it could make no more progress on its own, so the result of a race between two workers is the same in every run of a world. Starting a worker costs 10 ms of simulated time (a real thread spends about that long building its isolate), which is why a timer of a millisecond or two fires before a freshly started worker's first message arrives. What a worker writes reaches the terminal through its parent, as Node's pipe does, so it appears when the parent next comes round its loop and not in the middle of a line the parent is writing. Atomics.wait on any thread hands the turn to the other contexts and comes back when the cell changes or the timeout passes; a wait that nothing could ever end stops the program with Atomics.wait: every thread is waiting rather than hanging. A worker left waiting for a message that can no longer come ends with code 0 once nothing anywhere can move, where Node would keep the process alive for ever.

Not there: worker.resourceLimits, BroadcastChannel, moveMessagePortToContext, setEnvironmentData/getEnvironmentData, the argv/env/resourceLimits options (a worker shares its parent's process object), worker.stdin, and BigInt64Array/BigUint64Array for Atomics. An uncaught error in a worker still ends the program with status 1, but the frames printed with it are the main thread's, not the worker's.

Child processes#

subprocess (run, Popen with pipes, communicate, call, check_call, check_output, getoutput, getstatusoutput; shell=, cwd=, env=, input=, text=, timeout=), os.system and os.popen in Python, and child_process (spawn, exec, execFile, fork, spawnSync, execSync, execFileSync, with stdio pipes, input, cwd, env, encoding, exit codes) in Node run the machine's own shell commands — builtins, scripts, pipelines and nested python3/node — one nesting level below the program (the shell's 32-level cap applies). A child runs to completion when it starts: Popen with stdin=PIPE starts once its input is closed, and asynchronous Node children deliver their output and exit as I/O completions at the simulated time the child took. A child's virtual run time (its sleeps, timers and network waits) is charged to the parent's clock, which is what timeout= compares against; a timed-out child has still run to its end. Output a Python child writes to an inherited stream lands where CPython's would: after the parent's already-flushed output (standard output to a pipe is block-buffered, as in CPython), so print('a'); os.system('echo b') prints b first unless the parent flushed.

Compression#

cw-zlib is a port of zlib 1.3.1's deflate, so compressed bytes are the real library's, byte for byte, at every level, window size, memory level and strategy. Node ships Chromium's fork of zlib, whose string hashing differs, and CPython links the system zlib; the port reproduces both, so zlib.deflateSync in the simulated node and zlib.compress in the simulated python3 agree with the real programs (and with each other's decompressors). crates/zlib/tests/vectors.json holds the hashes of 434 outputs recorded from CPython 3.12 and Node 24.21 for that check.

• Python: zlib (compress, decompress, compressobj/decompressobj with flush modes, dictionaries, unused_data/unconsumed_tail, crc32, adler32), gzip (compress, decompress, open, GzipFile) and struct.
• Node: zlib — deflate/inflate/gzip/gunzip/unzip/deflateRaw/ inflateRaw and brotli, in sync, callback and stream forms, with crc32, constants and the option checks. Asynchronous results arrive as I/O completions after simulated work proportional to the bytes handled, so several jobs complete in the order their sizes imply.
• Brotli is the brotli crate (a port of Google's encoder and decoder); its compressed output is not promised to match the C library bit for bit, though it does for the recorded cases, and anything it produces or accepts is valid brotli.
• Python's bz2 and lzma are not implemented.

Consoles and reading from the terminal#

python3 and node with nothing to run start their console when standard input is the terminal (a pipe or a redirect still means "read a program"), and a program that reads a line — input(), sys.stdin, process.stdin, readline's question — stops until the next line is typed. Both print what CPython 3.12 and Node 24.21 print: the same banner, the same prompts (>>> and ... , > and | ), values echoed with repr() and util.inspect, Traceback (most recent call last): and Uncaught TypeError: …, Node's dot commands (.help, .break, .clear, .exit). At a terminal both streams are one screen, so an interactive run returns one stream with prompts, output and errors interleaved in the order they appear. The shell's prompt while a console is open is the console's, and the terminal's next line goes to it rather than to the shell; exit(), .exit or a Ctrl-D line (\u0004) ends it.

An interpreter cannot be kept alive between two actions of the world (its heap is not serializable, and a snapshot may be restored anywhere), so a waiting session is resumed by replay: the program is run again from the start with the new line appended to its input, and every host call the earlier lines made — files written, requests sent, the clock, the world's entropy — is answered from a journal recorded the first time instead of being made again. The interpreter is deterministic, so the replay reaches the same place; only what the new line produced is shown. Two consequences are worth knowing: a session is part of the machine's state and survives a snapshot, and a console line that runs for a long time is re-run (not re-executed against the world) on every later line.

In the Node console a binding a line makes (const x = 1, function f() {}, class C {}) is copied into the global object when the line finishes, which is how the next line sees it; a closure that later changes such a binding does not change what the next line reads. Top-level await is not transformed, so it yields a promise rather than its value.

Languages, regions and time zones#

Both runtimes format dates, numbers, currencies and lists in fourteen languages: en-US, en-GB, de, fr, es, it, pt-BR, ja, zh-CN, zh-TW, ko, ru, ar and hi. A locale that is not one of them falls back to its language (de-AT formats as de-DE, en-AU as en-GB, pt-PT as pt-BR) and an unknown language falls back to en-US.

• Node has ECMA-402: Intl.DateTimeFormat (component options and dateStyle/timeStyle, timeZone, hour12/hourCycle, formatToParts), Intl.NumberFormat (decimal, percent, currency and unit styles, grouping, fraction and significant digits, signDisplay, standard, compact and scientific notation, formatToParts), Intl.PluralRules (cardinal and ordinal), Intl.RelativeTimeFormat, Intl.ListFormat, Intl.DisplayNames (languages, regions, scripts and currencies of the covered set), Intl.Collator, Intl.Locale, Intl.getCanonicalLocales and Intl.supportedValuesOf; toLocaleString, toLocaleDateString, toLocaleTimeString and localeCompare go through them. Intl.Segmenter and Intl.DurationFormat are not implemented, the only calendar is gregory and the only numbering systems are the ones those locales use (latn, and arab where Arabic asks for it).
• Python has locale (setlocale, getlocale, localeconv, nl_langinfo, format_string, currency, str, atof, atoi, delocalize, normalize), and time.strftime/datetime.strftime follow LC_TIME: %a, %A, %b, %B, %p, %c, %x, %X and %r are the locale's, with glibc's -, _, 0 and ^ flags. A locale outside the fourteen raises locale.Error, as CPython does for one that is not installed.
• Time zones: zoneinfo.ZoneInfo and Intl's timeZone option know the 70-odd IANA zones in crates/tz (every offset in use, and the places a world's machines and services are plausibly in), with their transitions between 1970 and 2050, their abbreviations and their aliases (US/Eastern, Asia/Calcutta). A local time that happens twice or never resolves the way CPython's fold and V8 do. The machine's own clock stays UTC: a zone is something a program formats with, not somewhere the machine is.

The data is compiled in and generated by hand from the host's own libraries, so the simulated runtimes agree with the real ones: crates/jsvm/data/cldr.json (261 KiB, recorded from Node 24.21's ICU by crates/jsvm/tools/generate_cldr.js, parsed on the first Intl use and never otherwise), crates/pyvm/src/locale_data.rs (18 KiB, recorded from the host's glibc by crates/pyvm/tools/generate_locales.py; Arabic and Hindi are filled in from the CLDR file, since glibc had no data for them there) and crates/tz/src/data.rs (134 KiB of source for 6,219 transitions, from the host's IANA database by crates/tz/tools/generate.py). Together that is about 410 KiB of tables in the binary.

Debugging#

Both runtimes can run under a DAP-shaped debugger — breakpoints with conditions, hit counts and logpoints, stepping, exception filters, frames, scopes, variables, evaluation in a frame and changing a value — and both are wired to the machine's debug seam, so Visual Studio Code's Run and Debug view stops a python3 or node program on this machine. A session cannot hold a live interpreter between two actions of a world, so it keeps what it takes to be back at the stop and replays the program, answering the host calls the earlier runs made from a journal. See docs/debugging.md.

Event-loop timing#

Node's loop phases (timers, poll, check), process.nextTick and promise jobs run in Node's order, and when a callback is due follows from what the program costs in simulated time rather than from any fixed assumption:

• executing code costs 100,000 interpreter instructions per millisecond;
• preparing a function body the first time it runs costs a millisecond per kibibyte of its own source — V8 compiles it then, and Node reaches into the internals a body that size needs. Node's own builtins are in V8's startup snapshot and cost nothing; resolving and reading each module of the program costs 0.05 ms;
• simulated I/O (a network reply, a compression job, a child process) costs the time the world says it takes.

So setTimeout(f, 0) against setImmediate(g) from the main module — the case that depends on wall-clock jitter in real Node — comes out of the program: a short program reaches the first turn before the 1 ms timer is due and the immediate wins, while one that loads or computes for longer than a millisecond sees the timer fire first. A timer started inside a callback counts from the moment it is started, as Environment::GetNow does, so work done in a callback pushes back what was queued behind it. The rates are model constants (not measurements of any real machine); they are calibrated so that the orderings recorded from Node 24.21 in crates/jsvm/tests/programs come out the same way.

Known gaps shared by both: no native extensions. Strings that contain unpaired UTF-16 surrogates are carried as the replacement character.

Process table#

Every process on a machine is a real entry in crates/computer/src/process.rs, and ps, top, pgrep, pkill, kill, free and lsof all read that one table. There are four kinds of entry, and nothing else is ever in it:

An open window really is a process: launching an application adds one, closing the window ends it, and killing the process closes the window. pkill browser shuts the browser. A machine models one pseudo-terminal, pts/0, which is the one the shell runs on.

Columns#

ps -o takes these names, comma-separated, and --sort=[+-]NAME orders by any of them (- for descending). ps --json serializes the whole Process struct instead.

The JSON form#

ps --json prints the whole Process record for each selected process, which is the serialized Rust struct and therefore always in step with the table above:

[{"pid":2,"parent":1,"group":2,"owner":"ada","command":"browser https://wiki.internal/",
  "state":"Running","started":0,"ended":null,
  "fds":{"0":"Stdin","1":"Stdout","2":"Stderr"},"listeners":[],
  "signal_dispositions":{},"pending_signals":[],"wake_exit":null,
  "tty":"","rss_bytes":335544320,"cpu_us":0}]

Every field is always present. state is "Running", "Stopped", {"Sleeping":{"until":<tick>}}, {"Zombie":{"code":N}} or {"Exited":{"code":N}}; started/ended are world-clock ticks (microseconds), and ended is null while the process runs; parent is the PPID column and group the PGID; fds maps each open descriptor number to "Stdin"/"Stdout"/"Stderr", {"File":{…}}, {"Pipe":{…}} or {"Socket":{…}}, which is what lsof prints; listeners are the node:port pairs a service process owns; tty is empty rather than ? when the process is attached to none; and rss_bytes and cpu_us are the raw byte and microsecond values the rss and time columns format.

The three ready-made formats are the real ones: ps is pid,tty,time,args, ps -f is user,pid,ppid,c,start,tty,time,args (headed UID … STIME …), and ps aux is user,pid,pcpu,pmem,vsz,rss,tty,stat,start,time,args.

Memory is modelled; CPU time is not#

Memory is a published model, not a measurement: this world has no allocator. A process's RSS is the footprint of the program it runs, plus what it is actually holding — for a window, the bytes of the document it has open. Every number is fixed when the process starts, so ps reports the same figure on every replay, and the ordering is the ordering the real programs would have. The program table (crates/computer/src/process.rs) is:

and the application table (crates/environment/src/lib.rs) is:

So "the ten processes using the most memory" is a question with a real answer:

ps -e -o pid,rss,comm --sort=-rss | head -n 11

CPU time is not modelled and is not faked. Commands here run in zero simulated time — only sleep occupies the clock, and sleeping is not CPU — so TIME, %CPU and C are 00:00:00, 0.0 and 0, and top's %Cpu(s) line is idle. cpu_us is a real field on every process rather than a constant, so the day something charges it the column will say so; until then, use etime/etimes, which are real. top's PR and NI are fixed at 20 and 0 for the same reason, and nice is refused by name.

Clock#

date is derived from the simulated tick, never the host clock. Tick 0 is 09:00:00 UTC on Thursday 17 September 2026, the same origin the desktop clock and the GUI status bar use, so they never disagree. A tick is one microsecond. There is one timezone (UTC) and no way to set the clock from the shell; advance simulated time instead.

ls --json#

ls --json answers "what is every entry in this directory?" in one call, instead of a listing followed by an test -d per name. It prints a single JSON array, one object per entry, in the same order and under the same -a/-A/-d/-R/-t/-S rules as the text form:

ls -R --json prints one array per directory, separated by a blank line, and no dir: headings — each object's path already says where it is.

File metadata#

Every node carries an identity and a full set of attributes, all of them deterministic:

The filesystem behaves as if mounted noatime: a read does not move the access time, because reading takes a shared borrow of the VFS. touch -a, cp -p and a creation do. There is no group database, so membership is a convention: every user is in the group that carries their own name and in the shared group users. That is what makes the group permission bits sit genuinely between the owner's and everyone else's.

Permissions#

The mode is enforced, not decoration. read_as, write_as, list_as and every command built on them check the owner bits, then the group bits, then the other bits, and every directory on the path needs its execute bit. A file a user cannot read fails to read for that user with permission denied: PATH and status 1; sudo (default root) bypasses the check, as root does. The sticky bit on a directory (/tmp is 1777) stops one user removing or renaming another's files there. The desktop file managers go through the same calls, so a GUI cannot reach what the shell cannot.

umask is one mask for the filesystem rather than one per process — this world runs one shell per computer. It starts at 0022, so a new file is 0644 and a new directory 0755.

The trash#

Deleting from a desktop, and trash from the shell, both write a real FreeDesktop trash under ~/.local/share/Trash:

~/.local/share/Trash/files/todo.md          the file itself, moved
~/.local/share/Trash/info/todo.md.trashinfo [Trash Info]
                                            Path=/home/user/notes/todo.md
                                            DeletionDate=2026-09-17T09:00:00

Path= is percent-encoded and DeletionDate= comes from the world clock, so the record is byte-identical on every replay. A name already in the trash gets .2, .3 and so on, so nothing is overwritten.

The desktops' Move to Trash and Restore go through the same records, and the Trash folder in each file manager shows each entry's original path.

Stat fidelity#

%u/%g report hardware.uid/hardware.gid (1000/1000 by default), because there is no numeric user database; %U/%G report the stored owner and group names, which are real. Directory sizes are reported as one 4 KiB allocation unit rather than the stored child count. Device: is a constant, and so is stat -f's filesystem type (ext2/ext3) and name length (255); its block counts are hardware.disk_bytes against usage summed from the VFS, exactly as df computes them.

which and builtins#

Everything in the table above runs in-process; the VFS holds no real binaries. which first searches PATH in the VFS — so packages installed by apt/pip resolve to their real installed path — and otherwise reports a nominal /usr/bin/NAME for any command this shell implements. That keeps "is this available?" a truthful question. which exits 1 only when no operand resolves. A command the table marks refused by name (nice, jobs, vmstat and the rest) is deliberately not in that roster: which reports it missing, because it is, and running it explains why rather than printing command not found.

Fixed hardware facts#

Computer::hardware holds every constant the probing commands report:

Known gaps#

Deliberately not implemented, and refused rather than faked:

• trap — it would need a signal-delivery model the process table does not have, and a handler that never fires is worse than a command that says it is missing.
• eval — re-entrant parsing of text built at runtime, for very little gain in a world where nothing arrives from outside the simulation. sh -c covers the honest cases.
• select, export -f, arrays, declare/typeset, ${VAR/…/…} and ${VAR#…}. Functions are not exported, so a command substitution, sh -c or a script starts with an empty function table, as it would without export -f.
• ** in globs: a pattern matches one path component at a time.
• "$@" expands to one word joined by spaces rather than one word per parameter; use it unquoted to forward parameters that contain no spaces.
• Arithmetic beyond + - * / % and parentheses: no **, no comparisons, no ++.
• A regex backreference inside a pattern (sed 's/\(a\)\1/x/', grep '\(a\)\1'). The engine is a finite automaton with no backtracking, so it is refused by name rather than quietly matching something else. Backreferences in a sed replacement (\1–\9) work.
• awk's |& co-processes and gawk's extension library (gensub, asort, PROCINFO, RT, BEGINFILE/ENDFILE). A print | "cmd" pipe buffers its text and runs the command when the pipe closes, because this world has no second process to schedule; close() is therefore load-bearing where gawk would also accept a flush.
• tail -f: nothing in this world changes a file except a command in this same shell, so a follow would never wake. It is refused by name.
• Locale collation: sort and every comparison use C/byte order, and [a-z] in a bracket expression means the ASCII range.
• Real process scheduling: only sleep occupies simulated time, so no CPU accounting exists. ps reports TIME/%CPU/C as zero and nice, vmstat and job control are refused by name rather than faked. Memory is modelled, from a published table; see Process table above for exactly what is measured and what is not.
• A group database and an allocator. Group membership is the convention described under File metadata; block accounting assumes a 4 KiB unit.
• A terminal to prompt at, so -i on cp, mv and rm answers no: an existing destination is left alone and rm -i removes nothing. That is what a real prompt does when its input is at end of file, and it is the safe answer.
• Access times on read: the filesystem behaves as if mounted noatime.
• Binary bytes cannot travel through a pipe or a redirect: the shell's streams are UTF-8 strings, so printf '\211PNG' writes the UTF-8 encoding of U+0089, not the byte 0x89. Commands that read bytes (file, xxd, od, hexdump, cmp, strings, md5sum and friends) read them straight from the VFS and are exact.