Systems & runtime

System programming

A governed-effects surface, not a Go or Rust standard-library clone: rehearse then commit; an LLM cannot act by construction.

1 Strong · 7 Solid · 3 Partial · 1 Emerging

Measured against: Go/Rust std · libuv · Folders: base/system(opens in a new tab) · base/platform(opens in a new tab) · For programmers: this area's reference

**an agent writes into a twin of the file system; the disk does not move.** drawn on 2026-10-01 by the site's script tools/areas-figurative.ring, run inside the library at commit 0e72e2e2c · the source(opens in a new tab)

Rethought from first principles

What Softanza kept from what works, and what it rethought, as the library wrote it down in its design documents and narrations.

The Softanza wayOnly the engine touches the real system; everything above it is a view or a rehearsal, and reality changes only when a governed plan crosses the one door.

Kept from the best practice

Direct action stays available: the real file, folder and process classes still act at once. Rehearsal is the recommended path for consequential change, not a forced one. source(opens in a new tab)
Child processes are managed the usual way: spawn, stream the output, wait, read the exit code, stop. Closing a handle stops a running child, so nothing leaks. source(opens in a new tab)
Building for another machine reuses Zig's cross-compiler: a deployment target's operating system and processor are simply the build triple. source(opens in a new tab)

Rethought

Rehearse, plan, commit. Changes are tried in an in-memory twin that holds no reference to reality; an update plan is the only way they reach the real system. source(opens in a new tab)
Imagining a change and enacting it are separate powers. A language-model actor holds no power to act, so it can propose a plan but never commit one. source(opens in a new tab)
System code is written in a named scope: development, deployment or runtime. Code for a phone is checked against the phone, and a forbidden act is refused at write time. source(opens in a new tab)
The twin also stands in for a machine you do not have: a microcontroller's pins are rehearsed on a laptop, then lowered to firmware source for the real device. source(opens in a new tab)

Deliberately not a Go/Rust-std system library: a clean but intentional subset of OS primitives, plus a layer none of them have -- an in-memory rehearsal twin over files, env and spawns, a single narrated/scoped/audited stzUpdatePlan that is the only bridge to reality, and a capability-actor lattice where an inference-only (LLM) actor's effect set is empty by construction. It omits by design what a governed-effects surface doesn't need: signals, broad IPC, the raw syscall zoo.

What a crafter does with it, and what stands out

A rehearsal twin over files, env and spawns that touches nothing
stzUpdatePlan: the sole crossing to reality, through three gates (reject, scope, governance)
An inference-only (LLM) actor's effect set is empty by construction -- agents that cannot hurt you
Deploy(:Production) gated by MayCommit; Git and LocalRepo backends proven byte-for-byte

What is owed

Signal handling (SIGINT/SIGTERM/SIGCHLD and Windows console-control)
The full async reactor surface
Complete the process face (ExePath, IsAlive, process table); live-verify ssh/docker/device deploy backends
Richer IPC and the lower OS surface (permissions, symlinks, users/groups); wire the engine sandbox flag

The Softanza way, run

What Softanza does differently in this area, shown by code taken from its narrations and guards, and run for this page.

File changes are rehearsed in an in-memory twin and come out as a plain-language plan; nothing on disk changes until the plan is committed.

Softanza

oVfs = new stzVirtualFileSystem()
oVfs.CreateFolder("config")
oVfs.CreateFile("config/greenhouse.ini", "pump_threshold=40")
oVfs.MoveFile("old_settings.txt", "config/legacy.ini")
oPlan = oVfs.GenerateUpdatePlan()
? oPlan.Narration()

Output

Update plan (3 of 3 operations to commit):
  * 1. create folder 'config'
  * 2. create file 'config/greenhouse.ini' (17 bytes)
  * 3. move 'old_settings.txt' -> 'config/legacy.ini'

run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/doc/narrations/stz-system-dev-to-deploy-narration.md(opens in a new tab)

The articles of this area (8)

The lanes, one by one

Lanes and their notes are quoted as they were read at the source, on Read from the source on 2026-09-16, from a read-only main worktree.

Safe-world governance (actor, twin, commit)

Strong

A capability lattice, a rehearsal twin that touches nothing, stzUpdatePlan as the sole crossing with three gates; an LLM actor's effect set is empty.stzSystemActor, stzVirtualSystem, stzUpdatePlan; marker-file guard (queued spawn does not run until commit)

Process / subprocess management

Solid

Managed children: Spawn, streaming ReadOutput/ReadError, Wait, ExitCode, Kill, no-leak Close; SystemCall double-exec bug fixed (one spawn).system.zig, stzProcess, stzSystemCall

Environment & working directory

Solid

Get/set/unset/list env, cwd, hostname, username, cpu-count engine-backed; on Windows SetEnvironmentVariableW so later child spawns inherit.stzEnvironment

Filesystem operations

Solid

Read/write/append/copy/delete/stat and dir create/delete/list/walk/count screened by pathIsUsable; omits permissions, ownership, symlinks, fifos.file.zig, stzVirtualFileSystem

OS / platform detection & machine info

Solid

OS/arch/endianness, cpu-count, machine and process memory, declared profiles for non-host targets; facts are engine, opinions are Haro; not a deep sysinfo.base/platform

Time & clocks

Solid

Monotonic ns/us/ms, wall UTC, sleep, resolution; process uptime from a monotonic base instant at DLL load (the epoch-uptime bug fixed and guarded).time.zig

Deployment plane

Solid

define -> require -> feasibility -> plan -> execute -> ship; Deploy(:Production) gated by MayCommit; Git and LocalRepo backends proven byte-for-byte.stzDeployment, stzDeploymentSite, SOFTANZA_DELIVERY_PLANE.md

Build & emulation

Solid

stzBuilder + build.zig wasm produce a bundle; stzEmulator rehearses Deploy(:Emulated); stzPlatform refuses to deploy what wasn't built.stzBuilder, stzEmulator, stzWebBundle, stzPlatform

Threading / async (reactor)

Partial

reactor.zig is a libuv-backed loop, but only its first slice (version + selftest) ships in this group; no thread-spawn API.reactor.zig

Low-level OS surface

Partial

Path helpers and common file/dir ops; permissions, ownership, symlinks, fifos, mmap, users/groups, ptrace, raw syscalls deliberately omitted.stz_config_sandbox (designed, not wired)

IPC

Partial

Only the managed child's stdout/stderr/stdin pipes; no named pipes, shared memory or socketpair.

Signals

Emerging

None: grep finds no stz_signal* in the engine and no Haro signal class; no SIGINT/SIGTERM/SIGCHLD handling, no graceful shutdown.