<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="dark light">
<meta name="description" content="zshrs — the most powerful shell ever created. No-fork architecture, AOP intercept, worker thread pool, bytecode caching, fusevm compiled execution.">
<title>zshrs — Documentation</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;600;700;900&family=Share+Tech+Mono&display=swap" rel="stylesheet">
<link rel="stylesheet" href="hud-static.css">
<link rel="stylesheet" href="tutorial.css">
<style>
.tutorial-main { max-width: 68rem; }
.arch-table { width: 100%; border-collapse: collapse; margin: 0.6rem 0 1rem; font-size: 12px; }
.arch-table th {
background: var(--bg-secondary); color: var(--cyan);
font-family: 'Orbitron', sans-serif; font-size: 10px; font-weight: 700;
letter-spacing: 1px; text-transform: uppercase; text-align: left;
padding: 6px 10px; border: 1px solid var(--border);
}
.arch-table td { padding: 6px 10px; border: 1px solid var(--border); color: var(--text-dim); vertical-align: top; }
.arch-table td code { color: var(--accent-light); background: var(--bg); padding: 1px 4px; font-size: 11px; }
.arch-table tr:hover td { background: var(--bg-hover); }
.motto { font-family: 'Orbitron', sans-serif; font-size: 16px; color: var(--accent); letter-spacing: 3px; margin: 0.5rem 0 1.5rem; }
.section-num { color: var(--cyan); font-family: 'Share Tech Mono', monospace; margin-right: 0.5rem; }
.code-block {
margin: 0.5rem 0; padding: 0.7rem 1rem; border-left: 2px solid var(--cyan);
background: var(--bg); font-family: 'Share Tech Mono', ui-monospace, monospace;
font-size: 12px; color: var(--text); white-space: pre-wrap; word-break: break-word;
line-height: 1.6;
}
.code-block .comment { color: var(--text-muted); }
.code-block .keyword { color: var(--cyan); }
.code-block .string { color: var(--green); }
.code-block .var { color: var(--accent-light); }
.diagram {
margin: 0.8rem 0; padding: 1rem; border: 1px solid var(--border);
background: var(--bg-secondary); font-family: 'Share Tech Mono', monospace;
font-size: 12px; color: var(--cyan); white-space: pre; overflow-x: auto; line-height: 1.5;
}
.cat-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr)); gap: 0.6rem; margin: 0.7rem 0; }
.cat-card {
border: 1px solid var(--border); border-left: 2px solid var(--cyan);
padding: 0.6rem 0.8rem; background: color-mix(in srgb, var(--bg-card) 92%, transparent); border-radius: 2px;
}
.cat-card h4 {
font-family: 'Orbitron', sans-serif; font-size: 11px; font-weight: 700;
letter-spacing: 1.5px; text-transform: uppercase; color: var(--cyan); margin: 0 0 0.35rem;
}
.cat-card p { margin: 0; font-size: 11.5px; color: var(--text-dim); line-height: 1.5; }
.cat-card code { font-size: 11px; color: var(--accent-light); }
.highlight { color: var(--accent); font-weight: 700; }
.stat { font-family: 'Orbitron', sans-serif; font-size: 28px; font-weight: 900; color: var(--cyan); }
.stat-label { font-size: 11px; color: var(--text-muted); letter-spacing: 1px; text-transform: uppercase; }
.stat-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr)); gap: 1rem; margin: 1rem 0; text-align: center; }
.docs-build-line {
margin: 0.35rem 0 0;
font-family: 'Share Tech Mono', ui-monospace, monospace;
font-size: 11px;
color: var(--text-dim);
letter-spacing: 0.03em;
max-width: 42rem;
opacity: 0.75;
}
.hub-scheme-strip {
border-bottom: 1px dashed var(--border);
background: color-mix(in srgb, var(--bg-secondary) 85%, transparent);
padding: 0.55rem 1.5rem 0.65rem;
position: relative;
}
.hub-scheme-strip-inner {
max-width: 68rem;
margin: 0 auto;
display: flex;
align-items: center;
gap: 0.85rem;
}
.hub-scheme-strip .hud-scheme-label {
flex: 0 0 auto;
font-family: 'Orbitron', sans-serif;
font-size: 9px;
font-weight: 700;
letter-spacing: 2px;
text-transform: uppercase;
color: var(--accent);
text-align: left;
}
.hub-scheme-strip .scheme-grid {
flex: 1 1 auto;
display: grid;
grid-template-columns: repeat(5, minmax(0, 1fr));
gap: 6px;
}
@media (max-width: 720px) {
.hub-scheme-strip-inner { flex-direction: column; align-items: stretch; }
.hub-scheme-strip .scheme-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}
</style>
</head>
<body>
<div class="app tutorial-app" id="docsApp">
<div class="crt-scanline" id="crtH" aria-hidden="true"></div>
<div class="crt-scanline-v" id="crtV" aria-hidden="true"></div>
<header class="tutorial-header">
<div class="tutorial-header-inner">
<div>
<h1 class="tutorial-brand">// ZSHRS — COMPILED SHELL</h1>
<nav class="tutorial-crumbs" aria-label="Breadcrumb">
<span class="current">Docs</span>
<span class="sep">/</span>
<a href="https://github.com/MenkeTechnologies/zshrs" target="_blank" rel="noopener noreferrer">GitHub</a>
<span class="sep">/</span>
<a href="https://crates.io/crates/zshrs" target="_blank" rel="noopener noreferrer">crates.io</a>
<span class="sep">/</span>
<a href="https://docs.rs/zshrs" target="_blank" rel="noopener noreferrer">docs.rs</a>
</nav>
<p class="docs-build-line">zshrs v0.10.9 · Anti-fork architecture · 23 coreutils builtins · VM-executed parallel · Bytecode caching · JIT · <a href="reference.html" style="color: var(--cyan);">Full reference</a> · <a href="daemon-report.html" style="color: var(--cyan);">Daemon impl map</a></p>
</div>
<div class="tutorial-toolbar">
<button type="button" class="btn btn-secondary" id="btnTheme" title="Toggle light/dark">Theme</button>
<button type="button" class="btn btn-secondary active" id="btnCrt" title="CRT scanline overlay">CRT</button>
<button type="button" class="btn btn-secondary active" id="btnNeon" title="Neon border pulse">Neon</button>
<a class="btn btn-secondary" href="reference.html">Reference</a>
<a class="btn btn-secondary" href="daemon-report.html" title="DAEMON.md → daemon/*.rs implementation map with file:line citations">Daemon Map</a>
<a class="btn btn-secondary" href="https://github.com/MenkeTechnologies/zshrs" target="_blank" rel="noopener noreferrer">GitHub</a>
<a class="btn btn-secondary" href="https://github.com/MenkeTechnologies/zshrs/issues" target="_blank" rel="noopener noreferrer">Issues</a>
</div>
</div>
</header>
<div class="hub-scheme-strip">
<div class="hub-scheme-strip-inner">
<span class="hud-scheme-label">// Color scheme</span>
<div class="scheme-grid" id="hudSchemeGrid"></div>
</div>
</div>
<main class="tutorial-main">
<h2 class="tutorial-title"><span class="step-hash">>_</span>ZSHRS REFERENCE</h2>
<p class="tutorial-subtitle">The most powerful shell ever created. No-fork architecture, AOP intercept, worker thread pool, bytecode caching, fusevm compiled execution.</p>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<p class="motto">SHELL SCRIPTS AT MACHINE CODE SPEED.</p>
<p class="motto" style="font-size: 12px; color: var(--cyan); margin-top: -1rem;">NO FORK. NO INTERPRETER. JUST BYTECODES.</p>
<div class="stat-grid">
<div><div class="stat">0</div><div class="stat-label">forks in hot path</div></div>
<div><div class="stat">100%</div><div class="stat-label">bytecode compiled</div></div>
<div><div class="stat">18</div><div class="stat-label">worker threads</div></div>
<div><div class="stat">180+</div><div class="stat-label">builtins</div></div>
<div><div class="stat">23</div><div class="stat-label">coreutils builtins</div></div>
<div><div class="stat">100x</div><div class="stat-label">warm start speedup</div></div>
<div><div class="stat">2000x</div><div class="stat-label">fork avoidance speedup</div></div>
<div><div class="stat">1st</div><div class="stat-label">compiled Unix shell</div></div>
</div>
<p style="font-size: 14px; line-height: 1.8; color: var(--text);">
For the first time in the history of computing — since the dawn of Unix at Bell Labs
in 1970 — a shell compiles to executable bytecodes and runs them on a virtual machine
with fused superinstructions. <span class="highlight">Every interactive command line, every shell script,
every function invocation, every <code>source</code>’d file</span> compiles to fusevm bytecodes
and executes at near-machine-code speed. No tree-walking interpreter. No fork. No parsing at
runtime if bytecodes are cached.</p>
<p style="font-size: 14px; line-height: 1.8; color: var(--text);">
Compiled bytecodes are cached as <code>rkyv</code> zero-copy archives mmap'd directly into
memory. Function invocations deserialize cached bytecodes
in microseconds — skipping the lexer, parser, and compiler entirely. <code>source</code>’d
scripts and interpreted scripts follow the same path: compile once, cache, execute from bytecode
forever. This has <span class="highlight">never been achieved in a Unix shell</span>.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x00a]</span> INVENTIONS — THE LIST</h2>
<p>This is a legacy, not a battle. Every item below originated in
zshrs and is offered as <strong>prior art for the shell-design
commons</strong> under the MIT grant. Future shells (bash, fish,
nushell, elvish, oil, xonsh, murex, projects that don’t exist
yet) should inherit any of it. Ports must credit zshrs as the
invention source in their docs — see
<a href="https://github.com/MenkeTechnologies/zshrs/blob/main/CREATORS.md"><code>CREATORS.md</code></a>
for the suggested wording. The protected invariants in
<a href="https://github.com/MenkeTechnologies/zshrs/blob/main/MAINTAINERS.md"><code>MAINTAINERS.md</code></a>
guard upstream identity, not the ideas.</p>
<div class="cat-grid">
<div class="cat-card">
<h4>Compiled Unix shell</h4>
<p>First Unix shell to compile every command (interactive,
script, function, sourced file) to bytecode and execute on
a purpose-built VM. Every shell since Bell Labs 1970 has
been an interpreter.</p>
</div>
<div class="cat-card">
<h4>fusevm bytecode VM</h4>
<p>NaN-boxed register VM with fused superinstructions and a
Cranelift JIT for hot blocks. Shared substrate with stryke
so a shell and a scripting language ride the same value
representation.</p>
</div>
<div class="cat-card">
<h4>Persistent worker thread pool</h4>
<p>18 (configurable [2-18]) tokio threads owned by the shell.
<code>$(cmd)</code>, <code><(cmd)</code>, <code>&</code>,
globbing, completion, autoloading all dispatch to the pool
instead of <code>fork(2)</code>. Zero forks in the hot path.</p>
</div>
<div class="cat-card">
<h4>90/10 daemon / shell split</h4>
<p>Singleton <code>zshrs-daemon</code> owns every mutation
(canonical state, fsnotify, schedule, jobs, locks, cache,
history). Thin shell clients are stateless and forkable.
No shared writer, no second process tree, no auto-spawn.</p>
</div>
<div class="cat-card">
<h4>Recorder-owns-rebuild (AOP intercept)</h4>
<p><code>zshrs-recorder</code> AOP-intercepts every state-mutating
dispatcher at runtime — alias / function / export / fpath
edit / hash -d / zstyle / bindkey / compdef / zmodload /
setopt / trap / sched / source / assignment — and ships
<code>(kind, name, value, file, line, fn_chain)</code> to the daemon.
Replaces the static-walker approach every other shell uses for
completion / fpath scanning.</p>
</div>
<div class="cat-card">
<h4>rkyv canonical-state shards</h4>
<p>Daemon's in-memory canonical state persists as
content-addressed rkyv archives under
<code>~/.zshrs/images/</code>. Cold-start shells mmap the
shard and skip every dotfile in <code>/etc</code> + <code>~</code>.
~10ms cold-start vs >100ms re-source.</p>
</div>
<div class="cat-card">
<h4>Single <code>~/.zshrs/</code> directory rule</h4>
<p>Every config + log + sqlite + rkyv shard + socket lives
under one root. <code>$ZSHRS_HOME</code> overrides for
sandboxes / hermetic harnesses. <code>rm -rf ~/.zshrs/</code>
is the one-verb total reset.</p>
</div>
<div class="cat-card">
<h4>Three log files, one per binary</h4>
<p><code>zshrs.log</code> (shell) + <code>zshrs-daemon.log</code> +
<code>zshrs-recorder.log</code> — never interleaved. One
<code>paths::is_zshrs_log_file</code> matcher feeds rotation,
tail, clear, snapshot bundling.</p>
</div>
<div class="cat-card">
<h4>Three TOML configs, all auto-seeded</h4>
<p><code>zshrs.toml</code> + <code>zshrs-daemon.toml</code> +
<code>zshrs-recorder.toml</code> with documented defaults.
Every binary seeds the dir on first run; idempotent across
all four. Auto-migrates legacy <code>daemon.toml</code> →
<code>zshrs-daemon.toml</code>.</p>
</div>
<div class="cat-card">
<h4><code>z*</code> builtin family</h4>
<p>One namespace, twenty-three builtins, one daemon route.
<code>zcache</code>, <code>zls</code>, <code>zid</code>, <code>zping</code>,
<code>ztag</code>, <code>zsend</code>, <code>znotify</code>,
<code>zsubscribe</code>, <code>zjob</code>, <code>zsync</code>,
<code>zask</code>, <code>zhistory</code>, <code>zsource</code>,
<code>zcomplete</code>, <code>zsuggest</code>, <code>zlog</code>,
<code>zwhere</code>, <code>zd</code>, <code>zlock</code>,
<code>zpublish</code>.</p>
</div>
<div class="cat-card">
<h4>Cross-shell pub/sub + named locks</h4>
<p><code>zsubscribe</code> / <code>zpublish</code> /
<code>zlock</code> as builtins routed through the singleton
daemon. Replaces <code>flock</code> + <code>socat</code> + named
pipes glued by hand. Locks are token-issued; release requires
the original token (lost shell can’t accidentally release
someone else’s lock).</p>
</div>
<div class="cat-card">
<h4>Session-persistent supervised jobs</h4>
<p><code>zjob submit</code> spawns under the daemon — survives
shell exit, output captured to disk, status persisted in
catalog.db, history survives daemon restarts. Replaces
<code>nohup</code> + <code>screen</code> + <code>pueue</code> +
<code>disown</code>.</p>
</div>
<div class="cat-card">
<h4>Bidirectional ptmx <code>zjob attach</code></h4>
<p><code>--pty</code> submit allocates a pseudo-terminal pair;
child runs with slave on 0/1/2.
<code>zjob attach</code> switches client termios to raw mode,
pumps stdin via <code>job_input</code> (base64), drains daemon
broadcast back to user’s tty, propagates SIGWINCH via
<code>job_resize</code>. Ctrl-] detaches; job keeps running.
Solves bg-jobs-blocked-on-stdin.</p>
</div>
<div class="cat-card">
<h4>Auto-derived OpenAPI 3.1</h4>
<p><code>GET /openapi</code> serves a spec-compliant OpenAPI
doc generated on every request from the daemon’s op
registry (<code>OP_NAMES</code>). 108 paths today (4 meta + 101
ops + 3 stream routes). bearerAuth declared only when
<code>[http.tokens]</code> is populated. Loopback bind requires
no token; non-loopback bind refuses without one.</p>
</div>
<div class="cat-card">
<h4>Daemon HTTP listener default-on (loopback)</h4>
<p>Seeded <code>zshrs-daemon.toml</code> ships
<code>[http] listen = "127.0.0.1:7733"</code> so
<code>zd health</code> works out of the box. Same trust model as
the Unix socket on a single-user box; flips to required-auth
the moment the bind goes non-loopback.</p>
</div>
<div class="cat-card">
<h4><code>zd</code> — HTTP bin AND in-process builtin</h4>
<p>Same arg surface, two transports.
<code>zd</code> the binary uses ureq against the HTTP listener
(works from bash / fish / CI / curl). <code>zd</code> the builtin
inside zshrs uses the local Unix socket via the daemon
<code>Client</code> — 5.5× faster (0.48ms vs 2.64ms,
no fork).</p>
</div>
<div class="cat-card">
<h4><code>zd doctor</code></h4>
<p>One-command health sweep: cache-root perms, file-perms drift,
pidlock liveness, socket presence, catalog integrity (sqlite
<code>PRAGMA integrity_check</code>), shards-present count,
fsnotify-alive, supervised-job count, legacy-litter scan
(<code>~/.zcompdump*</code>, <code>~/*.zwc</code>). Pretty
ASCII table; non-zero exit on any FAIL.</p>
</div>
<div class="cat-card">
<h4>Flat history + sibling FTS5 sqlite</h4>
<p><code>~/.zshrs/zshrs_history</code> (flat zsh-extended-history
text, <code>cat</code>-able and <code>grep</code>-able) +
<code>~/.zshrs/zshrs_history.db</code> (FTS5 index for fast
search / dedup / frequency). The writer keeps both in lockstep;
on open, the text mirror is rehydrated from the index if
stale. Auto-migrates the legacy
<code>~/Library/Application Support/zshrs/history.db</code>.</p>
</div>
<div class="cat-card">
<h4>Recorder sources the full 8-file login chain</h4>
<p><code>zshrs-recorder</code> by default mirrors a real
<code>zsh -l -i</code>: <code>/etc/zshenv</code>,
<code>${ZDOTDIR:-$HOME}/.zshenv</code>, <code>/etc/zprofile</code>,
<code>~/.zprofile</code>, <code>/etc/zshrc</code>,
<code>~/.zshrc</code>, <code>/etc/zlogin</code>,
<code>~/.zlogin</code>. Missing files skipped silently.
<code>$ZDOTDIR</code> re-resolved per file.</p>
</div>
<div class="cat-card">
<h4><code>zsync up --all</code></h4>
<p>Single command snapshots every overlay table
(alias / galias / salias / setopt / params /
env / path / manpath / fpath / named_dir / compdef /
zstyle) and pushes into the daemon’s canonical state.
Shell-side <code>overlay_snapshot::enumerate_all_overlays</code>
registered via fn-pointer trampoline so the daemon crate
stays decoupled from <code>ShellExecutor</code>.</p>
</div>
<div class="cat-card">
<h4>23 anti-fork coreutils builtins</h4>
<p><code>cat</code>, <code>head</code>, <code>tail</code>,
<code>wc</code>, <code>sort</code>, <code>find</code>,
<code>uniq</code>, <code>cut</code>, <code>tr</code>,
<code>seq</code>, <code>rev</code>, <code>tee</code>,
<code>sleep</code>, <code>date</code>, <code>mktemp</code>,
<code>hostname</code>, <code>uname</code>, <code>whoami</code>,
<code>id</code>, <code>basename</code>, <code>dirname</code>,
<code>touch</code>, <code>realpath</code>. All in-process; one
<code>cat</code> in a pipeline doesn’t fork.</p>
</div>
<div class="cat-card">
<h4>Parallel-as-syntactic-primitive</h4>
<p>fish-style parallel iterators (<code>par_for</code>,
<code>par_map</code>, <code>par_filter</code>, <code>par_reduce</code>)
ship as VM opcodes, not library calls. Glob walks parallelize
at depth ≥ 32 by default. Worker pool is the substrate.</p>
</div>
<div class="cat-card">
<h4>The <code>--no-fork</code> philosophy as a measurement</h4>
<p>Every accepted commit is graded by “does this remove
a fork?” not “does this add a feature?”
Optimization layers (zinit turbo, p10k instant prompt, zwc,
zcompile, BG_NICE, lazy autoload) are evidence that zsh
can’t solve the problem in userspace; zshrs accepts the
architecture cost to solve it for real.</p>
</div>
</div>
<p style="font-size: 12px; color: var(--text-muted); margin-top: 0.8rem;">
Full enumeration + suggested attribution wording in
<a href="https://github.com/MenkeTechnologies/zshrs/blob/main/CREATORS.md"><code>CREATORS.md</code></a>.
Op-by-op detail in <a href="daemon-report.html"><code>daemon-report.html</code></a>.
Port-coverage report in <a href="report.html"><code>report.html</code></a>.
</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x00]</span> THE COMPILATION PIPELINE</h2>
<p>Every path through zshrs ends at the same place: fusevm bytecode execution.</p>
<div class="diagram">
┌─────────────────────────────────────────────────────────────────┐
│ THREE EXECUTION PATHS │
│ │
│ ┌─────────────┐ Interactive command line │
│ │ REPL Input │──► Parser ──► ShellCompiler ──► fusevm::Op │
│ └─────────────┘ │ │
│ ▼ │
│ ┌─────────────┐ Shell script / source file VM::run() │
│ │ Script File │──► Parser ──► ShellCompiler ──► │ │
│ └─────────────┘ │ │ │
│ └──► rkyv image ──────────┘ │
│ (cached on first compile) │
│ │
│ ┌─────────────┐ Autoload function (compinit) │
│ │ rkyv image │──► mmap zero-copy archive ──► fusevm::Chunk ──►│
│ │ shard │ (no lexer, no parser, VM::run() │
│ └─────────────┘ no compiler — microseconds) │
└─────────────────────────────────────────────────────────────────┘
</div>
<table class="arch-table">
<tr><th>Path</th><th>Lex</th><th>Parse</th><th>Compile</th><th>Execute</th><th>Cache</th></tr>
<tr><td>Interactive command</td><td>Yes</td><td>Yes</td><td>Yes</td><td>fusevm</td><td>No (ephemeral)</td></tr>
<tr><td>Script file (first run)</td><td>Yes</td><td>Yes</td><td>Yes</td><td>fusevm</td><td>Yes → rkyv</td></tr>
<tr><td>Script file (cached)</td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td>fusevm</td><td>Hit → deserialize</td></tr>
<tr><td>Autoload function (cached)</td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td>fusevm</td><td>Hit → deserialize</td></tr>
<tr><td>Plugin source (cached)</td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td><span class="highlight">No</span></td><td>fusevm</td><td>Delta replay → µs</td></tr>
</table>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x01]</span> ARCHITECTURE</h2>
<div class="diagram">
zshrs Architecture
┌─────────────────────────────────────────────────────┐
│ REPL / ZLE │
│ reedline + syntax highlighting + autosuggestions │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ ShellExecutor (19K lines) │
│ parser ─► compiler ─► fusevm bytecode dispatch │
│ 180+ builtins │ AOP intercept │ trap/signal │
└──────┬─────────┬─────────┬─────────┬────────────────┘
│ │ │ │
┌──────▼───┐ ┌───▼────┐ ┌─▼──────┐ ┌▼──────────────┐
│ Worker │ │ rkyv │ │ fusevm │ │ compsys │
│ Pool │ │ images │ │ VM │ │ completion │
│ [2-18] │ │ + │ │ │ │ engine │
│ threads │ │catalog │ │ Op enum│ │ │
│ │ │ .db │ │ fused │ │ MenuState │
│ glob │ │(query) │ │ super- │ │ MenuKeymap │
│ rehash │ │bytecode│ │ instr │ │ FTS5 mirror │
│ compinit │ │mmap'd │ │ JIT ► │ │ │
│ history │ │ shards │ │Cranelft│ │ │
└──────────┘ └────────┘ └────────┘ └───────────────┘
</div>
<h3>Source-tree layout: ported / extensions / recorder split</h3>
<p>The runtime crate is physically split so port code and original code can never be confused. Bots, contributors, and humans all read <a href="https://github.com/MenkeTechnologies/zshrs/blob/main/docs/PORT.md" style="color:var(--cyan);"><code>docs/PORT.md</code></a> before writing a single line of code; <code>tests/port_purity.rs</code> mechanically enforces the rules in CI.</p>
<ul>
<li><strong><code>src/ported/</code> — 105 files, FROZEN.</strong> Strict 1:1 port. Every <code>.rs</code> mirrors a real <code>src/zsh/Src/<x>.c</code> file (same stem, same relative subpath). Every top-level <code>fn</code> carries a <code>/// Port of <cname>() from Src/<file>.c:NNNN</code> doc-comment. New file creation is banned; new fn names that don't exist in upstream zsh C source are banned. The freeze closes both drift vectors: bots invent helper names ("shell_quote", "find_in_path") and bots create fresh files to drop helpers in. Both blocked.</li>
<li><strong><code>src/extensions/</code> — 37 files.</strong> The non-port directory. Features zsh C demonstrably does <em>not</em> have: AOT (<code>aot.rs</code>, <code>compile_zsh.rs</code>), autoload/plugin/script caches, fish-style autosuggest/abbrev/highlight, persistent worker pool, arith JIT, AST s-exp dump, ZWC byte-code helpers, recorder hooks, daemon presence, structured logging, ZLE keymaps/widgets, ext builtins, regex module, config, overlay snapshot + canonical apply, subscript/fds/hist extensions. <code>port_purity</code> exempts this directory from the 1:1 file-existence rule on the basis that no C ancestor exists.</li>
<li><strong><code>src/recorder/</code> — 1 file, feature-gated.</strong> Every symbol <code>#[cfg(feature = "recorder")]</code>; deleted by rustc when the feature is off. Compiled into the separate <code>zshrs-recorder</code> binary, never the default <code>zshrs</code> build.</li>
<li><strong><code>src/zsh/</code> — vendored upstream.</strong> Read-only reference. The C spec; never modified.</li>
</ul>
<p>Lexer + parser ports live in <code>src/ported/lex.rs</code> and <code>src/ported/parse.rs</code> (no separate <code>parse/</code> crate). Workspace siblings: <code>daemon/</code> (41 files, <code>zshrs-daemon</code>), <code>compsys/</code> (27 files, completion-system rkyv mmap + zstyle), <code>fish/</code> (157 files, fish-style reader/highlighter/abbreviations), <code>bins/</code> (3 entry points: <code>zshrs</code>, <code>zshrs-recorder</code> with <code>required-features = ["recorder"]</code>, <code>zd</code> with <code>required-features = ["zd"]</code>). 413 <code>.rs</code> files total · 371,790 Rust LOC (<code>git ls-files '*.rs' | xargs wc -l</code>, 2026-05-12).</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x01]</span> ANTI-FORK ARCHITECTURE</h2>
<p>Every fork is a full process copy. On macOS, <code>fork()</code> costs 2-5ms
including exec + ld.so + libc init. zsh forks for <em>every</em>
<code>$(...)</code>, <code><(...)</code>, <code>cat</code>, <code>grep</code>, subshell, and completion.
zshrs forks for <em>none</em> of them.</p>
<table class="arch-table">
<tr><th>Operation</th><th>zsh</th><th>zshrs</th><th>Speedup</th></tr>
<tr><td><code>cat file</code></td><td>fork + exec /bin/cat</td><td><span class="highlight">Builtin</span> — zero fork</td><td>2000-5000x</td></tr>
<tr><td><code>head</code>/<code>tail</code>/<code>wc</code></td><td>fork + exec</td><td><span class="highlight">Builtin</span> — zero fork</td><td>2000-5000x</td></tr>
<tr><td><code>sort</code>/<code>find</code>/<code>uniq</code></td><td>fork + exec</td><td><span class="highlight">Builtin</span> — zero fork</td><td>2000-5000x</td></tr>
<tr><td><code>date</code>/<code>hostname</code>/<code>uname</code></td><td>fork + exec</td><td><span class="highlight">Direct syscall</span></td><td>3000-8000x</td></tr>
<tr><td><code>sleep</code>/<code>mktemp</code>/<code>touch</code></td><td>fork + exec</td><td><span class="highlight">Builtin</span> — zero fork</td><td>2000-5000x</td></tr>
<tr><td><code>xattr</code> operations</td><td>fork + exec xattr</td><td><span class="highlight">Direct syscall</span></td><td>2000-5000x</td></tr>
<tr><td><code>pmap</code>/<code>pgrep</code>/<code>peach</code></td><td>fork N times to sh -c</td><td><span class="highlight">VM execution</span> — zero fork</td><td>Nx</td></tr>
<tr><td><code>$(cmd)</code></td><td>fork + pipe + exec</td><td>In-process stdout capture via <code>dup2</code></td><td>—</td></tr>
<tr><td><code><(cmd)</code> / <code>>(cmd)</code></td><td>fork + FIFO</td><td>Worker pool thread + FIFO</td><td>—</td></tr>
<tr><td>Glob <code>**/*.rs</code></td><td>Single-threaded <code>opendir</code></td><td>Parallel <code>walkdir</code> per-subdir on pool</td><td>—</td></tr>
<tr><td><code>rehash</code></td><td>Serial <code>readdir</code> per PATH dir</td><td>Parallel scan across pool</td><td>—</td></tr>
<tr><td>Autoload function</td><td>Read file + parse every time</td><td>Zero-copy mmap of rkyv-archived bytecode (µs)</td><td>100x</td></tr>
</table>
<h3>Coreutils Builtins (23 commands, zero fork)</h3>
<div class="code-block">cat head tail wc sort find uniq cut tr seq rev tee
basename dirname touch realpath sleep whoami id hostname
uname date mktemp</div>
<p>Every invocation of these commands is <span class="highlight">2000-5000x faster</span> than forking to the external binary.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x02]</span> WORKER THREAD POOL</h2>
<p>Persistent pool of warm threads. Bounded crossbeam channel with backpressure.
Panic recovery keeps workers alive. Task cancellation on Ctrl-C. Instant shutdown on exit.</p>
<div class="code-block"><span class="comment"># ~/.zshrs/zshrs.toml (seeded on first run; idempotent)</span>
[log]
<span class="var">level</span> = <span class="string">"info"</span> <span class="comment"># env $ZSHRS_LOG overrides; "trace" prints startup diagnostics</span>
[shell]
<span class="var">skip_configs</span> = <span class="string">"auto"</span> <span class="comment"># when daemon up + canonical shard recorded, skip /etc/zsh{env,rc} + ~/.{zshenv,zprofile,zshrc,zlogin}</span>
[worker_pool]
<span class="var">size</span> = <span class="string">8</span> <span class="comment"># 0 = auto (num_cpus clamped [2, 18])</span>
[completion]
<span class="var">bytecode_cache</span> = <span class="keyword">true</span> <span class="comment"># compile autoload functions to fusevm bytecodes</span>
[history]
<span class="var">async_writes</span> = <span class="keyword">true</span> <span class="comment"># daemon-side writes via IPC; prompt never blocks</span>
[glob]
<span class="var">parallel_threshold</span> = <span class="string">32</span> <span class="comment"># min files before parallel metadata prefetch</span>
<span class="var">recursive_parallel</span> = <span class="keyword">true</span> <span class="comment"># fan out **/ across worker pool</span></div>
<p>Tasks shipped to the pool:</p>
<div class="cat-grid">
<div class="cat-card"><h4>compinit</h4><p>Background fpath scan + bytecode compilation of 16K+ functions</p></div>
<div class="cat-card"><h4>Process Sub</h4><p><code><(cmd)</code> and <code>>(cmd)</code> on pool threads instead of fork</p></div>
<div class="cat-card"><h4>Parallel Glob</h4><p><code>**/</code> recursive walk split per-subdir across pool</p></div>
<div class="cat-card"><h4>Metadata Prefetch</h4><p>Glob qualifiers: one parallel <code>stat</code> batch, zero syscalls after</p></div>
<div class="cat-card"><h4>PATH Rehash</h4><p>Parallel <code>readdir</code> across every PATH directory</p></div>
<div class="cat-card"><h4>History Writes</h4><p>Daemon-side writes via IPC — prompt never waits, zero client SQLite handle</p></div>
</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x03]</span> AOP INTERCEPT</h2>
<p>The first shell ever with aspect-oriented programming. Hook <span class="highlight">before</span>,
<span class="highlight">after</span>, or <span class="highlight">around</span> any command or function
— at machine code speed, no fork. One primitive that replaces <code>defer</code>,
<code>profile</code>, <code>memo</code>, <code>retry</code>, and <code>timeout</code>.</p>
<div class="code-block"><span class="comment"># Before — log every git command</span>
<span class="keyword">intercept</span> before git { echo "[$(date)] git <span class="var">$INTERCEPT_ARGS</span>" >> ~/git.log }
<span class="comment"># After — show timing for completion functions</span>
<span class="keyword">intercept</span> after '_*' { echo "<span class="var">$INTERCEPT_NAME</span> took <span class="var">${INTERCEPT_MS}</span>ms" }
<span class="comment"># Around — memoize expensive function</span>
<span class="keyword">intercept</span> around expensive_func {
local cache=/tmp/cache_<span class="var">${INTERCEPT_ARGS// /_}</span>
if [[ -f <span class="var">$cache</span> ]]; then cat <span class="var">$cache</span>
else <span class="keyword">intercept_proceed</span> | tee <span class="var">$cache</span>; fi
}
<span class="comment"># Around — retry with backoff</span>
<span class="keyword">intercept</span> around flaky_api {
repeat 3; do <span class="keyword">intercept_proceed</span>; [[ $? == 0 ]] && break; sleep 1; done
}
<span class="comment"># Fat binary — stryke code at machine code speed</span>
<span class="keyword">intercept</span> after 'make *' { <span class="string">@pmaps { notify "done: $_" } @(slack email)</span> }</div>
<p>Variables available in advice:</p>
<table class="arch-table">
<tr><th>Variable</th><th>Available</th><th>Description</th></tr>
<tr><td><code>$INTERCEPT_NAME</code></td><td>all</td><td>Command name</td></tr>
<tr><td><code>$INTERCEPT_ARGS</code></td><td>all</td><td>Arguments as space-separated string</td></tr>
<tr><td><code>$INTERCEPT_CMD</code></td><td>all</td><td>Full command string</td></tr>
<tr><td><code>$INTERCEPT_MS</code></td><td>after</td><td>Execution time in milliseconds (nanosecond source)</td></tr>
<tr><td><code>$INTERCEPT_US</code></td><td>after</td><td>Execution time in microseconds</td></tr>
<tr><td><code>$?</code></td><td>after</td><td>Exit status</td></tr>
</table>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x04]</span> RKYV ZERO-COPY CACHE LAYER</h2>
<p>Cached bytecode lives in <code>rkyv</code> archives mmap'd by clients — zero-copy
deserialization, no allocator pressure on hot paths. The daemon owns all writes; clients
only mmap. The single queryable mirror is <code>catalog.db</code> (SQLite) for
<code>dbview</code> introspection — never touched on the hot path.</p>
<div class="cat-grid">
<div class="cat-card">
<h4>images/{hash}-{slug}.rkyv</h4>
<p>Per-source-root rkyv shards. Compiled bytecode for autoloads, plugins, sourced
scripts. Daemon writes; clients mmap zero-copy. Validates with rkyv's bytecheck on first
access; format-versioned for migration safety.</p>
</div>
<div class="cat-card">
<h4>index.rkyv</h4>
<p>Top-level shard index: source-root path → shard hash + mtime. Daemon rewrites
on changes; clients mmap to resolve which shard to load.</p>
</div>
<div class="cat-card">
<h4>catalog.db (SQLite mirror)</h4>
<p>Daemon-hydrated FTS5-indexed mirror of all rkyv contents. Used ONLY by
<code>dbview</code> and <code>zcache</code> introspection — never read on the
hot path. Clients have ZERO SQLite handles. The daemon's own FTS5 history
(<code>history.db</code>) sits next to it; the shell's user-facing history is
<code>zshrs_history</code> (flat zsh-extended-history-format text) plus a sibling
FTS5 index <code>zshrs_history.db</code>, both in <code>$ZSHRS_HOME</code>.</p>
</div>
</div>
<p>Browse caches without SQL:</p>
<div class="code-block"><span class="keyword">dbview</span> <span class="comment"># list all tables + row counts (hits catalog.db)</span>
<span class="keyword">dbview</span> autoloads <span class="comment"># dump autoloads: name, body size, ast size</span>
<span class="keyword">dbview</span> autoloads _git <span class="comment"># single row: source, body, ast status, preview</span>
<span class="keyword">dbview</span> comps git <span class="comment"># search comps for "git"</span>
<span class="keyword">dbview</span> executables rustc <span class="comment"># search PATH cache</span>
<span class="keyword">dbview</span> history docker <span class="comment"># search history</span>
<span class="keyword">zcache</span> rebuild <span class="comment"># force daemon to recompile every shard</span>
<span class="keyword">zcache</span> verify <span class="comment"># bytecheck every rkyv archive</span></div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x04b]</span> FILE LAYOUT & BINARIES</h2>
<p>One directory holds every zshrs file: <code>$ZSHRS_HOME</code> (defaults to
<code>~/.zshrs/</code>). All four binaries — <code>zshrs</code>, <code>zshrs-daemon</code>,
<code>zshrs-recorder</code>, <code>zd</code> — seed the directory and three default configs
on first run via <code>CachePaths::ensure_default_configs</code>. Idempotent — never
overwrites user edits. Auto-migrates legacy <code>daemon.toml</code> →
<code>zshrs-daemon.toml</code> and the legacy macOS history at
<code>~/Library/Application Support/zshrs/history.db</code> →
<code>~/.zshrs/zshrs_history.db</code>.</p>
<div class="diagram">
~/.zshrs/
├── zshrs.toml # shell config [log] [daemon] [shell.skip_configs]
├── zshrs-daemon.toml # daemon config [log] [http] [http.tokens]
├── zshrs-recorder.toml # recorder config [log]
├── zshrs.log # shell tracing
├── zshrs-daemon.log # daemon tracing
├── zshrs-recorder.log # recorder tracing
├── zshrs_history # flat zsh-extended-history-format text
├── zshrs_history.db # FTS5 index sibling
├── catalog.db # daemon canonical-state mirror (FTS5)
├── history.db # daemon's own FTS5 history
├── cache.db # daemon KV cache
├── plugins.db
├── images/ # rkyv canonical shards (per source root)
├── replay/ # non-deterministic .zshrc fragments
├── artifacts/ # content-addressed artifact cache
├── snapshots/ # tag-based canonical-state snapshots
├── jobs/ # supervisor stdout/stderr captures
├── daemon.sock # Unix domain socket
├── daemon.pid # singleton flock
└── index.rkyv # shard registry
</div>
<h3>Three log files (one per binary)</h3>
<table class="arch-table">
<tr><th>File</th><th>Owner</th><th>Level source</th></tr>
<tr><td><code>zshrs.log</code></td><td>shell</td><td><code>[log] level</code> in <code>zshrs.toml</code> (env <code>$ZSHRS_LOG</code> wins)</td></tr>
<tr><td><code>zshrs-daemon.log</code></td><td>daemon</td><td><code>[log] level</code> in <code>zshrs-daemon.toml</code></td></tr>
<tr><td><code>zshrs-recorder.log</code></td><td>recorder</td><td><code>[log] level</code> in <code>zshrs-recorder.toml</code></td></tr>
</table>
<p>Helper <code>paths::is_zshrs_log_file</code> matches all three for rotation, tail, and
clear. Default daemon startup emits 7 INFO lines; with <code>level = "trace"</code> an
additional ~5 startup diagnostics print (resolved env, pidlock, db sizes, ticker spawn,
schedule spawn, http listener address).</p>
<h3><code>[shell] skip_configs = "auto"</code></h3>
<p>When the daemon is up AND has a recorded zshrs canonical shard, the shell SKIPS
sourcing <code>/etc/zshenv</code> + <code>~/.{zshenv,zprofile,zshrc,zlogin}</code> entirely
and rebuilds executor state from the rkyv shard. <code>canonical_apply</code> wires
alias/galias/salias/env/params/setopt/path/fpath/named_dirs/autoload_functions/zstyle/bindkey/compdef/zle widgets.
Inline functions are deferred until the recorder ships bytecode in the shard.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x04c]</span> RECORDER (<code>zshrs-recorder</code>)</h2>
<p>Separate binary — <em>not</em> a flag on <code>zshrs</code>. Sources the full zsh login
chain in order, skipping any missing file silently:</p>
<div class="code-block">1. /etc/zshenv
2. ${ZDOTDIR:-$HOME}/.zshenv
3. /etc/zprofile
4. ${ZDOTDIR:-$HOME}/.zprofile
5. /etc/zshrc
6. ${ZDOTDIR:-$HOME}/.zshrc
7. /etc/zlogin
8. ${ZDOTDIR:-$HOME}/.zlogin</div>
<p><code>-f PATH</code> overrides the chain to source one file. End-of-run ships a
<code>recorder_ingest</code> IPC bundle to the daemon, which folds it into the canonical
shard for the matching source root.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x04d]</span> <code>zd</code> — TWO SURFACES</h2>
<table class="arch-table">
<tr><th>Surface</th><th>Transport</th><th>Latency</th><th>Use case</th></tr>
<tr><td><code>zd</code> binary</td><td>HTTP via <code>ureq</code> to <code>[http].listen</code></td><td>2.64 ms (fork+exec)</td><td>bash, fish, CI, anything outside zshrs</td></tr>
<tr><td><code>zd</code> builtin (in-process)</td><td>local Unix socket via <code>Client</code></td><td>0.48 ms (5.5× faster)</td><td>inside zshrs — same arg surface</td></tr>
</table>
<p>Default HTTP listener: <code>127.0.0.1:7733</code>, seeded into
<code>zshrs-daemon.toml</code> on first run so <code>zd health</code> works out of the
box. Default token comes from <code>$DAEMON_TOKEN</code>. Loopback bind requires no
token; non-loopback bind refuses to start until <code>[http.tokens]</code> is populated.
<code>GET /openapi</code> (alias <code>/openapi.json</code>) returns an OpenAPI 3.1
document auto-derived from <code>OP_NAMES</code> — 108 paths today (4 meta + 101 ops
+ 3 streams), with <code>ErrPayload</code> in components and <code>bearerAuth</code>
declared only when tokens are configured.</p>
<h3><code>zd</code> subcommands</h3>
<div class="code-block"><span class="keyword">zd health</span> <span class="comment"># liveness probe</span>
<span class="keyword">zd ops</span> <span class="comment"># enumerate every op</span>
<span class="keyword">zd metrics</span> <span class="comment"># Prometheus exposition</span>
<span class="keyword">zd ping</span> [echo...]
<span class="keyword">zd info</span>
<span class="keyword">zd call</span> OP [JSON_BODY] <span class="comment"># raw op invocation</span>
<span class="keyword">zd doctor</span> [--json] <span class="comment"># pretty health table: perms, db integrity, shards,</span>
<span class="comment"># fsnotify, pidlock, jobs, legacy litter; exit 1 on any fail</span>
<span class="keyword">zd config</span> get KEY <span class="comment"># runtime knob plumbing</span>
<span class="keyword">zd config</span> set KEY VALUE
<span class="keyword">zd config</span> list
<span class="keyword">zd snapshot</span> save TAG [--notes N] <span class="comment"># canonical-state freeze</span>
<span class="keyword">zd snapshot</span> list
<span class="keyword">zd snapshot</span> load TAG
<span class="keyword">zd snapshot</span> diff A B
<span class="keyword">zd cache</span> <put|get|del|list|stats>
<span class="keyword">zd job</span> <submit|list|status|output|kill|cancel|wait>
<span class="keyword">zd lock</span> <try|acquire|release|list>
<span class="keyword">zd publish</span> TOPIC [DATA] [--json '...']
<span class="keyword">zd events</span> / <span class="keyword">zd watch</span> / <span class="keyword">zd defs</span>
<span class="keyword">zd artifact</span> <put|get|list|gc>
<span class="keyword">zd schedule</span> <add|add-once|list|remove>
<span class="keyword">zd export</span> TARGET FORMAT [--json] <span class="comment"># raw export — NO json envelope by default</span>
<span class="keyword">zd view</span> TARGET [FORMAT]</div>
<p><code>zd export aliases pdf > out.pdf</code> produces a real PDF — payload is
streamed direct for <code>sh / csv / json / yaml / text / pdf</code>. <code>--json</code>
opt-in restores the JSON envelope.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x04e]</span> NEW <code>z*</code> BUILTINS</h2>
<table class="arch-table">
<tr><th>Builtin</th><th>Description</th></tr>
<tr><td><code>zlock try NAME</code></td><td>Cross-process named lock — non-blocking try</td></tr>
<tr><td><code>zlock acquire NAME [--timeout S]</code></td><td>Poll-wait acquire with optional timeout</td></tr>
<tr><td><code>zlock release NAME TOKEN</code></td><td>Release by token</td></tr>
<tr><td><code>zlock list</code></td><td>List all held locks</td></tr>
<tr><td><code>zpublish TOPIC</code> / <code>TOPIC DATA</code> / <code>TOPIC --json '{...}'</code></td><td>Producer side of the pub/sub bus (consumer is <code>zsubscribe</code>)</td></tr>
<tr><td><code>zwhere SUBSYS NAME</code></td><td>Query daemon canonical state for "where did this alias / function / zstyle come from" with <code>file:line</code> attribution</td></tr>
</table>
<p>Full builtin family: <code>zcache</code>, <code>zls</code>, <code>zid</code>,
<code>zping</code>, <code>ztag</code>, <code>zuntag</code>, <code>zsend</code>,
<code>znotify</code>, <code>zsubscribe</code>, <code>zunsubscribe</code>,
<code>zjob</code>, <code>zsync</code>, <code>zask</code>, <code>zhistory</code>,
<code>zsource</code>, <code>zcomplete</code>, <code>zsuggest</code>,
<code>zcmd-result</code>, <code>zlog</code>, <code>zwhere</code>, <code>zd</code>,
<code>zlock</code>, <code>zpublish</code>.</p>
<h3><code>zjob</code> — bidirectional ptmx attach</h3>
<div class="code-block"><span class="keyword">zjob submit</span> [--pty] [--cwd DIR] [--tag T...] [--env K=V...] -- CMD ARGS...
<span class="keyword">zjob list</span> [--state running|exited|killed|failed] [--tag T] [--limit N]
<span class="keyword">zjob status</span> <id>
<span class="keyword">zjob output</span> <id> [--follow] [--stderr] [--lines N]
<span class="keyword">zjob attach</span> <id> <span class="comment"># read-only file-tail for non-pty;</span>
<span class="comment"># bidirectional raw-mode pump for --pty</span>
<span class="keyword">zjob kill</span> <id> [--signal NAME]
<span class="keyword">zjob cancel</span> <id> [--grace SECS]
<span class="keyword">zjob wait</span> <id> [--timeout SECS]</div>
<p>With <code>--pty</code> the daemon calls <code>nix::pty::openpty()</code> and the
child runs with the slave on 0/1/2 via <code>pre_exec</code> <code>dup2</code>; the
master fd lives in <code>JobMeta</code>. Two new IPC ops drive it:</p>
<ul>
<li><code>job_input {id, bytes_b64}</code> — base64-decode, write to master</li>
<li><code>job_resize {id, rows, cols}</code> — <code>TIOCSWINSZ</code> for SIGWINCH propagation</li>
</ul>
<p>On <code>zjob attach</code> against a pty job: <code>termios cfmakeraw</code> on
stdin, a stdin reader thread batches keystrokes and fires <code>job_input</code>, output
is broadcast as <code>job:N.stdout</code> events with <code>bytes_b64</code> payload
(decoded back to the user's tty), and <code>SIGWINCH</code> is forwarded as
<code>job_resize</code>. <code>Ctrl-]</code> is the detach key. Termios is restored on
exit via a Drop guard. Use case: background jobs that block on stdin (deploy scripts
asking y/n, REPLs in background) — submit with <code>--pty</code>, attach later, type,
detach, attach again.</p>
<h3><code>zsync up --all</code></h3>
<p>Now wired (was a stub). The shell-side enumerator
(<code>src/extensions/overlay_snapshot.rs</code>) snapshots every overlay table and ships
<code>push_canonical</code> per subsystem. Covers
alias/galias/salias, setopt, params (vars+arrays+assoc unioned), env, path, manpath,
fpath, named_dir, compdef, zstyle. Skipped: <code>function</code> (needs source-text
round-trip), <code>bindkey</code> (lives in <code>ZleManager</code>),
<code>zmodload</code> (no canonical "currently loaded" list).</p>
<div class="code-block"><span class="keyword">zsync up</span> --all <span class="comment"># promote every overlay subsystem</span>
<span class="keyword">zsync up</span> <subsystem> KEY VALUE
<span class="keyword">zsync up</span> <subsystem> --json '<obj>'
<span class="keyword">zsync pull</span> <subsystem>
<span class="keyword">zsync diff</span> <subsystem> --overlay '<obj>'
<span class="keyword">zsync watch</span> <subsystem>...</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x05]</span> BYTECODE CACHING</h2>
<p>Every autoload function in fpath gets compiled to fusevm bytecodes during <code>compinit</code>.
Compiled chunks are serialized via <code>rkyv</code> into per-source-root shards and written
by the daemon. Subsequent loads mmap the archive zero-copy, validate via <code>bytecheck</code>,
and dispatch directly — no lex, no parse, no compile, no allocator hit.</p>
<div class="diagram">
First call to _git (daemon path):
fpath/_git (source text)
│
▼
ShellParser::parse_script() ~1ms
│
▼
ShellCompiler::compile() ~0.5ms
│
▼
fusevm::Chunk (bytecodes)
│
├──► VM::run() native dispatch
│
└──► rkyv::to_bytes() ~0.1ms (zero-copy archive)
│
▼
images/{hash}-fpath.rkyv (daemon writes)
Every subsequent call (client path, ZERO daemon RTT):
images/{hash}-fpath.rkyv mmap (kernel page cache)
│
▼
rkyv::access::<ArchivedChunk> ~0 µs (zero-copy access)
│
▼
fusevm::Chunk (no lexer, no parser, no compiler, no alloc)
│
▼
VM::run() native bytecode dispatch
</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x06]</span> FUSEVM BYTECODE TARGET</h2>
<p><span class="highlight">100% lowered.</span> Every shell construct compiles to <code>fusevm</code>
bytecodes — a language-agnostic VM with fused superinstructions and Cranelift JIT.
The same VM that powers stryke (which beats LuaJIT on benchmarks). No tree-walking
interpreter remains. Hot bytecodes compile to native x86-64 machine code.</p>
<div class="diagram">
stryke source ───► stryke compiler ──┐
├──► fusevm::Op ──► VM::run() ──► JIT ──► native
zshrs source ───► shell compiler ──┘ │
├── Linear JIT: straight-line code
├── Block JIT: loops, conditionals
└── Cranelift codegen → x86-64
</div>
<p>Shell constructs already lowered to fusevm bytecodes:</p>
<div class="cat-grid">
<div class="cat-card"><h4>Arithmetic</h4><p><code>$(( ))</code> — full precedence, ternary, assignment, hex/octal, bitwise</p></div>
<div class="cat-card"><h4>Loops</h4><p><code>for</code>, <code>for(())</code>, <code>while</code>, <code>until</code>, <code>repeat</code></p></div>
<div class="cat-card"><h4>Conditionals</h4><p><code>if/elif/else</code>, <code>case</code>, <code>[[ ]]</code> with all file tests and comparisons</p></div>
<div class="cat-card"><h4>Commands</h4><p><code>Exec</code>, <code>ExecBg</code>, pipelines, redirects, here-docs, here-strings</p></div>
<div class="cat-card"><h4>Functions</h4><p>Definition, <code>Call</code>/<code>Return</code>, <code>PushFrame</code>/<code>PopFrame</code></p></div>
<div class="cat-card"><h4>Fused Ops</h4><p><code>AccumSumLoop</code>, <code>SlotIncLtIntJumpBack</code>, <code>PreIncSlotVoid</code> — single-dispatch loop execution</p></div>
</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x07]</span> EXCLUSIVE BUILTINS</h2>
<h3>Parallel Primitives (VM-executed, zero fork)</h3>
<table class="arch-table">
<tr><th>Builtin</th><th>Description</th></tr>
<tr><td><code>async</code> / <code>await</code></td><td>Ship work to pool, collect result</td></tr>
<tr><td><code>pmap</code></td><td>Parallel map with ordered output — compiles to bytecode, runs on VM, zero forks</td></tr>
<tr><td><code>pgrep</code></td><td>Parallel filter — compiles to bytecode, runs on VM, zero forks</td></tr>
<tr><td><code>peach</code></td><td>Parallel for-each, unordered — compiles to bytecode, runs on VM, zero forks</td></tr>
<tr><td><code>barrier</code></td><td>Run all commands in parallel, wait for all</td></tr>
</table>
<h3>AOP / Debugging</h3>
<table class="arch-table">
<tr><th>Builtin</th><th>Description</th></tr>
<tr><td><code>intercept</code></td><td>AOP before/after/around advice on any command. Glob pattern matching. Nanosecond timing.</td></tr>
<tr><td><code>intercept_proceed</code></td><td>Call original command from around advice.</td></tr>
<tr><td><code>doctor</code></td><td>Full diagnostic: worker pool metrics, cache stats, bytecode coverage, startup health.</td></tr>
<tr><td><code>dbview</code></td><td>Browse the daemon's catalog.db mirror without SQL. Tables: autoloads, comps, executables, history, plugins. Hot path uses rkyv mmap directly.</td></tr>
<tr><td><code>profile</code></td><td>In-process command profiling. Nanosecond accuracy. No fork overhead in measurement.</td></tr>
</table>
<h3>Coreutils (Anti-Fork)</h3>
<table class="arch-table">
<tr><th>Builtin</th><th>Description</th><th>Speedup vs fork</th></tr>
<tr><td><code>cat</code></td><td>Concatenate files — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>head</code> / <code>tail</code></td><td>First/last N lines — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>wc</code></td><td>Line/word/char count — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>sort</code> / <code>uniq</code></td><td>Sort and dedupe — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>find</code></td><td>Walk directories — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>cut</code> / <code>tr</code> / <code>rev</code></td><td>Text manipulation — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>seq</code> / <code>tee</code></td><td>Number sequences, copy stdin — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>date</code></td><td>Current date/time — direct strftime</td><td>3000-8000x</td></tr>
<tr><td><code>sleep</code></td><td>Delay — std::thread::sleep</td><td>2000-5000x</td></tr>
<tr><td><code>mktemp</code></td><td>Create temp file/dir — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>hostname</code> / <code>uname</code></td><td>System info — direct syscall</td><td>3000-8000x</td></tr>
<tr><td><code>id</code> / <code>whoami</code></td><td>User info — direct syscall</td><td>3000-8000x</td></tr>
<tr><td><code>touch</code> / <code>realpath</code></td><td>File ops — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>basename</code> / <code>dirname</code></td><td>Path manipulation — no fork</td><td>2000-5000x</td></tr>
<tr><td><code>zgetattr</code> / <code>zsetattr</code></td><td>xattr ops — direct syscall</td><td>2000-5000x</td></tr>
</table>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x07b]</span> SHELL LANGUAGE FEATURES</h2>
<p>Every shell construct compiles to fusevm bytecode — no tree-walker
dispatch lives in zshrs. The categories below are summaries; the
<a href="reference.html">full reference</a> documents each entry with a runnable
code example.</p>
<div class="cat-grid">
<div class="cat-card">
<h4>Control Flow</h4>
<p><code>if</code>, <code>while</code>, <code>until</code>, <code>for</code>, <code>for ((;;))</code>,
<code>case</code>, <code>select</code>, <code>coproc</code>, <code>break</code>, <code>continue</code>,
<code>return</code>, <code>;</code>/<code>&&</code>/<code>||</code>/<code>&</code>.</p>
</div>
<div class="cat-card">
<h4>Indexed Arrays</h4>
<p><code>arr=(a b c)</code>, <code>arr+=(d)</code>, <code>${arr[1]}</code> (1-based),
<code>${arr[-1]}</code>, <code>${arr[@]}</code> (argv splice), <code>${#arr[@]}</code>.</p>
</div>
<div class="cat-card">
<h4>Associative Arrays</h4>
<p><code>typeset -A m</code>, <code>m[key]=val</code>, <code>${m[key]}</code>,
<code>${(k)m}</code> (keys), <code>${(v)m}</code> (values).</p>
</div>
<div class="cat-card">
<h4>Parameter Expansion</h4>
<p><code>${var:-x}</code>, <code>${var:=x}</code>, <code>${var:?msg}</code>,
<code>${var:+x}</code>, <code>${#var}</code>, <code>${var:o:l}</code>, <code>${var#pat}</code>,
<code>${var/pat/repl}</code>, <code>${var:u}</code>/<code>:l</code>.</p>
</div>
<div class="cat-card">
<h4>Zsh Flags</h4>
<p><code>(L)</code>/<code>(U)</code> case, <code>(j: :)</code> join,
<code>(s. .)</code> split, <code>(f)</code> newline-split, <code>(o)</code>/<code>(O)</code> sort,
<code>(P)</code> indirect, <code>(@)</code> force-array, <code>(k)</code>/<code>(v)</code>,
<code>(#)</code>. Stack: <code>(jL)</code>, <code>(s:,:U)</code>.</p>
</div>
<div class="cat-card">
<h4>Redirects & Pipelines</h4>
<p><code>></code> <code>>></code> <code><</code> <code><<EOF</code> <code><<<</code>
<code>2>&1</code> <code>&></code> <code>&>></code> <code>|</code>
<code>|&</code> <code>!</code> <code><(cmd)</code> <code>>(cmd)</code>.</p>
</div>
<div class="cat-card">
<h4>Background & Async</h4>
<p><code>cmd &</code> (fork + setsid), <code>$!</code>, <code>wait</code>,
<code>jobs</code>/<code>fg</code>/<code>bg</code>; <code>async</code>/<code>await</code>
(worker pool, no fork).</p>
</div>
<div class="cat-card">
<h4>Coprocesses</h4>
<p><code>coproc { body }</code> creates two pipes, forks, registers
<code>$COPROC=[read_fd, write_fd]</code>. Read from <code>/dev/fd/${COPROC[1]}</code>,
write to <code>/dev/fd/${COPROC[2]}</code>.</p>
</div>
<div class="cat-card">
<h4>Eval & Indirect Dispatch</h4>
<p><code>eval 'echo $x'</code> defers expansion correctly (single-quoted specials honored).
<code>cmd=ls; $cmd</code> routes through host intercepts.</p>
</div>
<div class="cat-card">
<h4>Arithmetic</h4>
<p><code>$((expr))</code>, <code>(( cond ))</code>, <code>let</code>; full integer expression
grammar compiled inline (no runtime parser).</p>
</div>
<div class="cat-card">
<h4>Glob & Brace</h4>
<p><code>*.rs</code>, <code>**/*.rs</code> (parallel walk), <code>{a,b,c}</code>,
<code>{1..10}</code>, glob qualifiers <code>*(.x)</code> <code>*(N)</code>.</p>
</div>
<div class="cat-card">
<h4>Tilde & Cmd-Sub</h4>
<p><code>~</code>, <code>~user</code>, <code>~+</code>/<code>~-</code>; <code>$(cmd)</code>
(in-process pipe-capture), backticks.</p>
</div>
</div>
<p style="margin-top: 1rem; font-size: 12px; color: var(--text-muted);">
For the complete catalog — every supported builtin, keyword, parameter-expansion form,
ZshFlag, AOP primitive, parallel primitive, and anti-fork coreutils replacement with a code
example for each — see the <a href="reference.html" style="color: var(--cyan); font-weight: 700;">FULL REFERENCE</a>.</p>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x08]</span> INSTALL</h2>
<div class="code-block"><span class="comment"># Lean build — pure shell, all features, no stryke</span>
cargo install --path zsh
<span class="comment"># Fat build — shell + stryke runtime (@ prefix, AOP stryke advice)</span>
cargo install strykelang
<span class="comment"># From source</span>
git clone https://github.com/MenkeTechnologies/strykelang
cd strykelang
cargo build --release -p zsh <span class="comment"># target/release/zshrs</span></div>
<div class="code-block"><span class="comment"># Set as default shell</span>
sudo sh -c 'echo /Users/$(whoami)/.cargo/bin/zshrs >> /etc/shells'
chsh -s /Users/$(whoami)/.cargo/bin/zshrs
<span class="comment"># Tab completion for zshrs itself</span>
cp completions/_zshrs /usr/local/share/zsh/site-functions/</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0x09]</span> DIAGNOSTICS</h2>
<div class="code-block"><span class="comment"># Full health check</span>
zshrs --doctor
<span class="comment"># In-session diagnostics</span>
doctor
<span class="comment"># Browse cache</span>
dbview
dbview autoloads _git
<span class="comment"># Profile a command</span>
profile 'compinit'
profile -s 'for i in {1..1000}; do echo $i > /dev/null; done'
<span class="comment"># Show intercepts</span>
intercept list</div>
</section>
<!-- ════════════════════════════════════════════════════════════ -->
<section class="tutorial-section">
<h2><span class="section-num">[0xFF]</span> THE PHILOSOPHY</h2>
<p>Shells haven't fundamentally improved since the 1990s. bash is a GNU rewrite of
the Bourne shell from 1979. zsh added features but kept the fork-based C architecture.
fish focused on UX and abandoned POSIX. nushell reinvented the data model but lost compatibility.</p>
<p>zshrs takes a different approach: keep everything that makes zsh powerful —
glob qualifiers, parameter expansion flags, the completion system, ZLE, zstyle, modules —
and replace the runtime with modern systems engineering. Rust instead of C. Thread pool
instead of fork. <code>rkyv</code> mmap'd zero-copy archives instead of flat files. Bytecode VM
instead of tree-walker. AOP instead of monkey-patching.</p>
<p>The result is the first shell that gets <em>faster</em> as you add more plugins,
because the plugin cache means each plugin is only parsed once. The first shell where
<code>**/*.rs</code> scales with your CPU count. The first shell where you can
intercept any command with nanosecond-accurate timing and zero overhead.</p>
<p>The result is the first shell where every command — interactive or scripted —
compiles to bytecodes and executes on a VM with fused superinstructions. The first
shell where autoload functions load from pre-compiled bytecodes in microseconds. The first
shell where <code>source ~/.zshrc</code> can skip the lexer, parser, and compiler entirely
because the bytecodes are mmap'd zero-copy from <code>rkyv</code> archives the daemon
already validated.</p>
<p>Since the Bourne shell at Bell Labs in 1970, through csh, ksh, bash, zsh, and fish —
every Unix shell has been an interpreter. zshrs is the first to be a compiler. Shell scripts
at machine code speed. Achieved in alpha.</p>
<p class="motto">THE FIRST COMPILED UNIX SHELL. THE MOST POWERFUL SHELL EVER CREATED.</p>
</section>
</main>
<footer style="border-top: 1px solid var(--border); padding: 1rem 1.5rem; text-align: center; color: var(--text-muted); font-size: 11px;">
© 2026 MenkeTechnologies · MIT License ·
<a href="https://github.com/MenkeTechnologies/strykelang" style="color: var(--cyan);">GitHub</a>
</footer>
</div>
<script src="hud-theme.js"></script>
</body>
</html>