chitti
CLAUDE.md9 starsChanged 4 months agoApache-2.0View on GitHub
Chitti is an agentic operating system: the agent is the driver. The fundamental unit of execution is an AI agent, not a compiled binary. There is no exec(binary) → trap into syscalls; instead spawn(agent) → plan over capabilities → a deterministic executor runs the primitives. A tiny language model runs on the CPU, on bare metal, and every effect it wants flows through a capability-checked, audited, grammar-constrained ABI. No POSIX. No libc. No ELF loader. No re-implementing Unix. We are…
- Installs packages
- Commits and pushes
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 31
Provenance/taint gating: Every context token is tagged (user_typed / system_trusted / untrusted_ingested / skill_installed).
- Very specific: line 168
Before them a 16x16 PNG needed more than a 4 KiB arena.
- Very specific: line 292
After any change, verify both — make verify runs exactly this:
- Distinctive: line 662
The geometry registers do not report the mode in effect: Before the guest first enables SVGA mode they hold the device's defaults (QEMU …
- Very specific: line 691
RUN.md, which names no display device.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ChittiOS — guide for agents & humans working in this repo
Chitti is an agentic operating system: the agent is the driver. The
fundamental unit of execution is an AI agent, not a compiled binary. There is no
exec(binary) → trap into syscalls; instead spawn(agent) → plan over
capabilities → a deterministic executor runs the primitives. A tiny language
model runs on the CPU, on bare metal, and every effect it wants flows through a
capability-checked, audited, grammar-constrained ABI.
No POSIX. No libc. No ELF loader. No re-implementing Unix. We are not
building "Linux but in Rust." Why reinvent the wheel? The interesting question is
what an OS looks like when an agent — not a shell script or a C program — is the
thing you run. So the OS gives an agent first-class primitives: a shell agent
(chat REPL), sessions (save/resume/fork), sub-agents (isolated,
capability-attenuated delegation), tools (MCP-shaped, Synapse-backed),
skills (signed, permissioned, progressively-disclosed packages), a todo-list
TUI, and a real windowed console with mouse + keyboard. The classic OS
plumbing that must exist (scheduler, MMU, capabilities, IPC, block/FS, drivers)
exists to serve that, not to run /bin/sh.
The load-bearing invariants — never break these
- The determinism boundary. Model output is an untrusted plan. It never
causes a side effect directly — it is parsed, grammar-validated, capability-
checked, and only then executed by deterministic native code (
Synapse). Above the boundary: stochastic (the agent/model). Below: deterministic. - All effects route through Synapse. Tools are a validation/presentation layer over Synapse primitives; they never touch hardware or memory directly.
- Delegation only ever narrows authority. A sub-agent's capability set is a strict subset of its parent's. Spawning can attenuate, never widen.
- Provenance/taint gating. Every context token is tagged
(
user_typed/system_trusted/untrusted_ingested/skill_installed). A destructive primitive justified by untrusted-ingested content is refused or requires explicit human confirmation — prompt-injection-as-privilege- escalation defense enforced at the OS boundary. - A skill is bounded by its install-time grant, forever. Even if a skill's text says "delete everything," it can only act within the capabilities the human approved at install.
Capabilities are unforgeable (opaque per-task indices, no ambient authority).
Effective authority is always intersection(requested, granting-context).
STANDING RULE — ring 0 is for drivers; agents and their commands run in ring 3
Only the kernel proper and the drivers execute in ring 0 / EL1. Every agent, and every agent- or app-facing command, performs its effects in ring 3 / EL0 as a userspace tenant. This is the execution-model half of invariant #1: "all effects route through Synapse" is a claim about authority, and this rule is the claim about privilege — an agent should not be able to corrupt kernel memory by getting a tool wrong, only to be refused by a gate.
How to make a call from a migrated caller — one function, always:
crate::synapse::tenant::invoke_in_userspace(task, raw, justification) // -> Option<Invocation>It runs the call in ring 3 under task's own identity, through all four gates, and
returns the structured Invocation.
Three rules that are not style preferences — each is a bug that already happened:
- Never parse the tenant's reply text to decide what happened. A tenant's reply is
prose rendered by
synapse::abi::render, whose vocabulary (denied:capability:X) differs from the tool router's (denied: no capability for X). Classifying from the text made refusals read as successes andsecurity::redteamreported five injected attacks as permitted where it had reported zero. There is exactly one authority for what an outcome was, and it is theInvocation, not a string. - The justification is computed above the boundary and passed in. The ABI defaults
to
UntrustedIngested, so a caller moved into ring 3 without one keeps its identity and capabilities but silently becomes maximally tainted — every destructive call it used to make legitimately starts being refused. Moving code across the ring boundary must not change what it is allowed to do, or the migration is a policy change wearing a refactor's clothes. Pass what the in-kernel path passed (Justification::trusted()where it called plainsynapse::execute). The tenant still cannot choose it — the kernel sets it before entering ring 3. - No in-kernel fallback when userspace fails. Retrying the call in ring 0 would make confinement depend on whether the loader happened to work. Report "the userspace call never reached the gates" as its own failure — never folded into a refusal or a grammar rejection, because "the gates said no" and "userspace could not run it" are different facts and a caller that cannot tell them apart retries the wrong one.
synapse::executor::execute / execute_with_justification are for the kernel and
drivers only. Calling them from anything agent-shaped is the bug this rule exists to
prevent, and it is invisible — the call still works, it just keeps kernel privilege. The
legitimate callers are exactly:
synapse::abi::dispatch— the kernel side of the tenant trap. This is the ring-3 path; it must call the executor directly or nothing could.tools::dispatch::run_synapse— the in-kernel arm, taken only whenruns_in_userspace(session)is false, i.e. for the orchestrator.synapse::bench— measuring the gate chain, kernel-internal by definition.#[test_case]tests of the gate chain itself (lib.rs'sphase*tests,cap,redteam). A test of the executor should call the executor.
Anything else is a bypass. Four existed at once and every one was found by grepping for
the call rather than by review, because a bypass looks exactly like ordinary code and
works: agent/wasm_rt.rs (app UI ops), service/server.rs (content-agent asset read),
service/package_ui.rs (the running app-UI pump), persona/agent.rs (a persona agent's
plan/act loop). All four are migrated.
This is enforced, not remembered: cargo xtask ring-check scans kernel/src and
fails on any direct executor call outside the allowlist in xtask/src/rings.rs, printing
file:line. Run it after adding a Synapse call site; to add a legitimate caller, add the
file to ALLOWED with a reason (a test asserts every entry has one). The scanner skips
comments — the rule is documented in prose that names the function, and a check that
counted those would be deleted for crying wolf — and a host test plants a fake bypass to
prove the walk is not vacuously green.
The one documented exception is the orchestrator (the shell agent), which stays in ring 0: it is the shell, holds root authority, and drives the kernel it would be confined relative to — so there is no isolation to gain. Revisit that deliberately if ever, not by accident.
Where "run it in ring 3" is not the right question. Ring 3 has no device access by
construction — that is the property being bought. So a command that touches hardware
(/voice on the sound device and ONNX models, /model DMA-loading a GGUF, /ping on an
ICMP socket, /lspci, /disks, /display, /battery, /install) cannot itself execute
there without mapping device memory into a tenant, which destroys the isolation. The
correct shape is always driver in ring 0, effect requested from ring 3 through a
Synapse primitive — so "migrate X" for such a command means designing a primitive,
not moving code. That is a real design act: each primitive is a new gated, audited
authority surface, it moves the primitive count the design paper states, and it adds an
entry to the security::redteam census.
The other half of ring 3 is the parsers, and they are the cheap case: a decoder needs no
authority at all. It reads a byte buffer, writes a pixel buffer, exits — zero Synapse
calls, so no new primitive, no gate change, nothing in the primitive count or the
redteam census. That is the exact opposite of /http or MCP, and it is why the largest
attacker-reachable code in the OS is also the easiest thing to confine. /open decodes
PNG and JPEG in ring 3 (userspace/imgdec/, driven by synapse::tenant::ImageTenant):
a malformed file becomes a status word from a tenant the kernel discards, where in ring 0
it is a parser bug away from a wild write. /decoder ring3|kernel switches back for an
A/B, and the in-kernel decoder stays until the differential has run on both arches.
Five things that path pins down, each of which cost a debugging cycle:
- The tenant mounts the kernel's own source (
#[path] = "../../../kernel/src/image/…", thepdf-wasm/h264diffpattern), so there is one decoder and porting it cannot regress it. What the differential test then compares is the boundary — layout, entry offset, stack ABI, arena, pixel gather — which is the thing that can actually be wrong. - x86-64 SysV guarantees
rsp % 16 == 8at function entry, because acallpushed a return address. A tenant arrives byiretq, which pushes nothing, so a 16-aligned initial rsp leaves every compiler frame 8 bytes off and the firstmovapsspill raises#GP. Corrupt inputs returned before spilling a vector register, so rejection worked and success did not. AAPCS64 is the opposite rule (SP always 16-aligned), so the initial SP is arch-specific. - The tenant is reused, and a reused address space keeps its
.bss— so it resets its own bump cursor at_start. Without that line the second decode starts with a full arena and reports out-of-memory, and nothing in the loader points at the cause. Reuse is not a micro-optimisation: building a space, mapping ~1000 arena pages and tearing it down was the entire measured overhead of ring 3, not the execution. - How much heap an image needs is a number inside the file. So the loader does not size
the arena — it starts small, and the tenant reports
STATUS_OUT_OF_MEMORY(distinct from "corrupt", or a good photo reads as a broken one) and the loader maps more and re-enters. The alternative is parsing the header in ring 0, which is the thing being undone. Symmetrically there is no output buffer: the tenant leaves the pixels in its arena and reports where, and every number it reports is bounds-checked against the frames the loader owns rather than trusted. The tenant also parses the header itself and reports the arena it expects to need (HEAP_WANT), so an oversized image costs one retry instead of a doubling search — six full attempts, each doing real work before running out, is what made a large photo effectively undecodable. - A bump allocator's size is the sum of everything it ever allocated, unless it reclaims.
Freeing the top allocation (roll the cursor back) and growing the top block in place are
four lines each, and together they turn that sum back into a high-water mark: a
Vecgrown by doubling stops stranding every intermediate size, and per-row scratch stops accumulating. Before them a 16x16 PNG needed more than a 4 KiB arena; after them it fits in one page, which is whata_16x16_png_decodes_inside_a_single_page_of_arenapins. The other half of that fix is inimage/png.rsitself — it unfilters in place rather than building a second whole-image buffer plus aVecper scanline, which is also one allocation per row of heap churn removed from the kernel path (performance trap #3). - No in-kernel fallback, per the rule above: a decode that cannot be sandboxed is an error, not a quiet retry in ring 0.
The next decoders need a chunked, stateful tenant, and that is a design act rather than a
port. H.264, AAC and ONNX are all on the list, and the blocker they share is not the mount:
it is that Ctrl+C and upkeep() are standing rules and a tenant has no device access by
construction. A whole-file AAC decode takes seconds — the in-kernel one pumps upkeep() every
32 frames for exactly that reason — so doing it in one crossing would freeze the clock, mouse
and net stack and ignore Ctrl+C. The shape that works is the tenant decoding a bounded number
of frames per entry while the kernel pumps and polls between entries, which means a command
word in the startup block, decoder state that survives an entry, and an arena that is not
reset per call (the opposite of the image tenant's one line). H.264 has that plus a second
problem: tenants are pinned to the boot CPU (no TLB shootdown), while 1080p30 was reached
partly by loaning the decoder to an SMP worker — so a naive port trades a measured 30 fps for
~12. ONNX is last for the reason it always was: weights live in DMA frames and its ops fan out
across the fleet. Note what is not a blocker — the H.264 decoder core is pure (video/mt.rs
is the only SMP dependency and it covers YUV→RGB and letterbox scale, i.e. presentation, not
parsing), so the natural split is bitstream→YUV in ring 3, YUV→RGB in ring 0.
wasm was measured and rejected for this: tools/pngbench (a permanent host tool, the
*diff pattern) put wasmi at 47-67x native on a 1.3 MP PNG — and "small images via
wasm" does not rescue it, because an attacker sends a large one. Ring 3 costs a page-table
switch and a trap. wasm stays right for pdf, which is already there.
/open x.pdf renders real pages, and wasm is the sandbox there because ring 3 is not
available. The rasterizer is hayro over
vello_cpu — tools/pdfrender-wasm/ from crates.io, compiled to
assets/wasm/pdfrender.wasm (4 MiB, checked in, include_bytes!) and driven by
shell/pdf.rs + the pure pdfview.rs. It would rather be a tenant like imgdec, but its
tree is std-bound in three places that are not features (moxcms, pxfm,
pic-scale), so the confinement comes from wasm instead of a page table: zero imports,
a memory-page limiter, a per-call fuel bound. Five things that path pins down:
- The build profile is worth 8.5x.
opt-level = "s"renders a dense LaTeX page in ~7.0 s under wasmi,3in ~0.82 s — and the3module is smaller (4.1 vs 5.4 MiB), so there is no trade to make: the size profile drops the inlining vello_cpu's per-pixel pipelines are built around.tools/pdfbenchis the permanent harness (native and wasm, same crate, seconds on the host — thepngbenchpattern). - Then wasm SIMD was worth another 2.2x, and it takes both halves. The guest is built
with
-Ctarget-feature=+simd128(pinned intools/pdfrender-wasm/.cargo/config.toml, not an env var, so a rebuild cannot silently lose it) and the kernel runs wasmi 1.1 with thesimdfeature. Separated on one real document: the 0.40 -> 1.1 interpreter alone is 1.43x, SIMD on top is another 1.53x, and on a blend-heavy page — vello_cpu's per-pixel pipelines are exactly what vectorizes — it reaches 5.8x (6850 -> 1181 ms). Both halves are required: wasmi 0.40 rejects a simd128 module at validation, and a scalar module gains nothing from the feature. The interpreter tax fell from 30-90x (340x on the worst page) to 3-30x. SIMD also lowered fuel use 3x — a vector op does several scalars' work and is charged once — so a fuel budget does not survive a change in how the guest is compiled. - The WASI stubs were all declared
() -> i32— the wrong arity for every one of the five. wasmi resolves an import by name andFuncType, so no real WASI module could ever have instantiated, and the symptom was again"wasm instantiate failed (missing imports/limits?)". Nothing noticed because the only module on that surface (pdfrender.wasm) has no import section at all and no test instantiated a WASI importer.register_wasi_importsnow implements the ten functions Javy needs, with fd 0/1 backed by host-side buffers. - Fuel metering costs 3.7%, measured with it off. It stays on: that is the only bound on a runaway guest, and 3.7% is not a price worth arguing about.
- In-kernel is ~3x slower than the host on heavy pages and equal on light ones, which is not the allocator: re-rendering a page with the guest's arena already grown is only 6% faster than the cold render. It scales with the working set (a heavy page holds 56 MiB of glyph and image caches), so the suspect is guest TLB pressure under stage-2 translation, and the lever would be huge pages for the kernel heap — unmeasured, so stated as a hypothesis. Release and debug kernels time the same here, so the harness's debug boots are fine to measure on. Real figures (aarch64 HVF): 445 ms for page 1 of a 117-page book, 565 ms for a paper's first page, ~3.1-3.9 s for its two attention-matrix figure pages.
- SMP for wasmi does not exist and cannot exist inside a call. wasmi is a
single-threaded interpreter and none of the wasm
threadsproposal is implemented, so there is no way to split one render across cores; vello_cpu's ownmultithreadingfeature needs rayon and is off. What is available is loaning a wholeSessionto an SMP worker the way the video player loans its decoder (smp::async_submit) — which buys a live UI during a render and a next-page render-ahead, not a faster render.Session: Sendis asserted at compile time (a_session_is_send_so_it_can_be_loaned_to_an_smp_worker) so that groundwork cannot rot; the render-ahead path itself is not built. - The
ResourceLimitercapped function tables at a hardcoded 256, and a renderer built on trait objects declares 693. The failure iswasm instantiate failed (missing imports?)— the one message that does not mention tables. It is nowLimits::with_table_elems, defaulted to the old 256 so every existing agent module keeps exactly its old bound. - Pixels and documents do not go through the string ABI. A page is megabytes;
base64-through-JSON would cost that 4/3 twice plus a guest decode.
Session::put_bytes/get_bytes/get_u32smove bytes directly, and every number the guest reports is bounds-checked against live linear memory — the image tenant's rule, because a guest is the untrusted side even when it is our own code. - An oversized render is refused, not attempted. Under
panic = "abort"an allocation failure is a trap that kills the instance, so the parsed document would be lost with it; the guest checksMAX_PIXELSfirst and answersERR_TOO_LARGE, and the host clamps to the same number (pdfview::cap_permille) so it rarely has to ask. - One instance holds one document, and it stays parsed. The
Sessionis retained, so paging a 35-page paper parses it once and the render cache keeps glyphs warm; the rendered page is cached by(page, scale), so scrolling, panning and tab switches are a memcpy and only a page or zoom change pays the renderer. Zoom re-renders rather than scaling the bitmap — that is the whole point of "proper preview" — and the view only ever moves a 1:1 window over the result (pdfview::compose).
Note also a viewer-shaped trap that is not about PDF at all: media_key hands a painter
typed bytes while media_nav hands the finals of an escape sequence, and both are
u8. A viewer that read A..D as arrows in the typed path scrolled the page whenever a
capital letter was typed — with the tab focused, /cat /samples/README.md arrived as
/cat /samles/REME.md. Arrows belong only to the nav path.
Still in ring 0 for want of a primitive, not by choice: the http tool (binds to
Shell{command:"http"}, and net_http_get/net_http_post do not express its
-X/-H/-d/--stream surface), MCP tools/call (a stateful JSON-RPC/SSE session),
downloads (fetch and store write), browser navigation and the web tools (the JS engine
plus the net stack), and agent memory (its own store, though this one is expressible as
mem_fs_* and is the cheapest next migration).
STANDING RULE — dual-architecture, no divergence
The kernel is one codebase for two architectures: x86_64 and aarch64, and
functionality must not diverge between them. Every change must build and work for
both arches. Never gate behaviour behind target_arch unless it is genuinely
arch-specific (a driver, an instruction) — and then provide the equivalent for the
other arch behind the same API, never a stub that drops a feature. If a
capability exists on one arch, it exists on the other.
After any change, verify both — make verify runs exactly this:
cargo xtask build -arch x86_64andcargo xtask test -arch x86_64cargo xtask build -arch aarch64andcargo xtask test -arch aarch64(and boot it viacargo xtask run -arch aarch64when the change is boot-visible)
The unit suite runs on BOTH arches, and keeping both green is the gate. It was
x86-only for a long time, which meant ~2400 test cases gated every x86 change and
nothing gated aarch64 beyond "it compiles" — a divergence in the coverage that
enforces this very rule. Turning it on immediately found a real one: aarch64's
switch_to did not save/restore DAIF, the direct counterpart of x86's
pushfq/popfq of RFLAGS.IF, so a preemptive switch out of the IRQ handler handed
the incoming task a masked interrupt state that nothing ever cleared. aarch64
preemption worked exactly once per boot, and the interactive shell hid it by
yielding constantly. Expect more of these: a test that has only ever run on one
arch is evidence about that arch alone.
STANDING RULE — every feature/fix ships with tests
Two layers, and new work adds to both where they apply:
Unit tests (
cargo xtask test [-arch …], both arches under QEMU, no model/hardware) for the pure logic — parsers, decoders, codecs, format/build functions, capability math. The pattern that keeps us safe: pull the fiddly logic out of the hardware/IO path into a pure function and test it with cases (e.g.mouse::decode_ps2_packet,xhci::parse_report_layout,net::httpparse_url/dechunk_partial,shell::parse_tool_call,ws::{base64,sha1,encode_frame},channelring/EOF,synapse::uidraw-op raster + ownership,service::http::parse_request,crypto::verify_p256, the executor scope gate,registry_client::parse_index). If logic broke before, it gets a test.framebuffer/is#[cfg(not(test))], so a test written inside the compositor never runs — it is not even compiled. (The gate is inlib.rs: a-Z build-std+cargo testinteraction gives two non-unified copies ofcore/allocotherwise.) A#[cfg(test)] modin there is therefore silent dead code, not coverage — which is how an analog-clock trig reduction wrong in two of four quadrants shipped, with tests sitting next to it that asserted the right things and were never built. So geometry, wrapping and colour math must live outside the compositor to be testable, the wayclock::face(dial geometry),editor_wrap(soft wrap),textsel(selection),panes_layout(pane geometry) anddisplayalready do. When you touch drawing code, check whether the logic you are changing is in a module that can be tested at all before adding a test to it.- End-to-end tests (
tests/e2e/,make e2e/make e2e-full) for anything that only exists on the running OS — a shell command, a network/TLS/WebSocket exchange, a model or voice flow. The harness boots the real kernel under QEMU and drives the shell over serial. Adding a shell command or a networked/model/voice feature means adding an e2e scenario (os/agents/netgroups always run;model/voiceare--slow, gated on assets). Theagentsgroup covers install/consent, service lifecycle, the network + HTTP/Doc service agents (the host reaches guest listeners via an opt-in slirpCHITTI_HOSTFWDport), registry search/install, and UI surfaces. A fix for something the harness could have caught gets a scenario too. Runmake e2ebefore shipping boot-visible or networked changes.
CI (.github/workflows/ci.yml) runs the unit job on every push/PR as a
matrix, one leg per arch (unit (x86_64), unit (aarch64)), each building its
arch and running its unit suite, with fail-fast: false so a dual-arch divergence
never hides which side broke. The e2e suite is not run in CI — boot it
locally with make e2e before shipping boot-visible or networked changes.
It is fork-PR-safe — pull_request (never pull_request_target),
contents: read, no secrets, GitHub-hosted runners only. Keep it that way.
STANDING RULE — performance: know the three traps before optimizing
Hard-won findings (commits f2bd8f7, 06a62b4) that apply to any new
compute- or I/O-heavy feature. Measure first, always — every one of these was
found by profiling, and the obvious suspect was wrong every time.
+strict-alignsilently scalarizes NEON. The aarch64 target builds with+strict-align(required for the pre-MMU boot window and device MMIO). Under it, LLVM lowers any unaligned vector load/store — thevld1q_*intrinsics and auto-vectorized plain loops — into a 16×ldrb+orr+ stack-spill byte-assembly: ~25 instructions per load, ~100× slower. The binary still containsfmla, so it looks fine until you disassemble the loads. Hot SIMD loops must do their memory access via inline asm (ldr q/ldp q/stp q— correct at runtime: Normal cacheable RAM,SCTLR_EL1.A=0), the same pattern as the MMIO single-ldr/strrule. Reusable kernels live incortex/tensor.rs:dot_f32,axpy_f32,scale_f32, theldq_s8/u8/f32load helpers, and the Q8_0/Q4_0/Q4_K SDOT matvecs. Prefer composing these over writing new intrinsics code; if you must write a new SIMD loop, verify withobjdump -d(countldrbin the hot function — the Q4_K kernel disassembles to 0 ldrb / 32 sdot) and/onnx benchin the booted kernel (dot_f32 ≥ 10 GMAC/s under HVF; ~1 GMAC/s means the disease is back)./benchprints the SDOT-vs-exact rel-RMS error per fast kernel (check_q4_0_sdot,check_q4_k_sdot).- Batch block I/O or die waiting. One
read_block= one polled virtio round trip (~0.5 ms). Anything reading more than a few KiB must useread_blocks(all drivers implement multi-sector requests;Partitionforwards). FATread_filecoalesces contiguous cluster runs — loading the 131 MB parakeet model went from ~2.5 min to ~2 s. New filesystem or loader code must follow the same pattern (and cache FAT-chain sectors). - The kernel allocator punishes churn. First-fit linked list: cloning
multi-MB tensors per node, or cloning a whole env per loop iteration, is
real time. Borrow instead of clone on hot paths; move values into maps
instead of cloning them. Heap pressure counters exist
(
mm::heap::alloc_stats()— allocs + free-list scan steps).
Layout matters as much as SIMD: iterate state row-wise/contiguous (the
DeltaNet delta rule went from stride-512B scalar walks to contiguous AXPYs —
that alone nearly doubled tokens/sec). Per-op wall-time accounting for the
ONNX executor prints one onnx: op time: ktrace line per run; /perf gives
prefill/decode tok/s; tools/onnxdiff/ runs the kernel's own ONNX interpreter
natively on the host (seconds per iteration, layer-by-layer diff vs
onnxruntime) — use it for any voice-model numeric or perf work before touching
QEMU.
Current figures (aarch64 HVF, 0.8B Q8, /perf 512): prefill ~105 tok/s, decode
~23 tok/s (same box, same run: prefill was ~60 tok/s before the window-wide
cores below), /voice stt ~2 s, /voice say ~14 s for 3.5 s of audio.
Prefill's parallel axis is not the position, and getting that wrong is what
kept pp pinned near tg. The projections were weight-stationary matmuls
across the whole fleet while the attention and DeltaNet cores ran a position at
a time on the BSP — so seven cores idled through the part that was left, and a
2x-of-decode prefill looked like a matmul problem when it was an Amdahl one.
Both cores are now window-wide (attn_core_batched, delta_core_batched, with
decode entering them as a one-position window so the two paths cannot drift):
attention fans out over positions (every (position, head) is independent
once the batched K/V are in the cache), the recurrence over heads (sequential
in position, but each head owns its own state slice). Three things that bite
here: the conv1d's window/ring index is ck + p, not ck - 1 + p — the
per-position form shifted the ring before convolving and that -1 follows you
into the rewrite, where it reads every tap one position too old and still decodes
fluent text (conv_tap, pinned by conv_window_matches_the_per_position_ring);
parallelism that exists is not parallelism worth taking — fanning a decode
step's 0.8M-MAC DeltaNet layer across the fleet measured slower than inline
(35 -> 20 tok/s), hence fanout_chunk; and /perf [n_prompt [n_decode]] now
prints a proj / attn / delta / elementwise split, because "prefill is slow"
is three different diagnoses and they scale differently. Measure with a real
prompt length: at 64 tokens prefill is one chunk and tells you nothing.
aarch64 SMP
row-split is live (arch/aarch64/smp.rs): PSCI CPU_ON bring-up, WFE-parked
workers, a static-partition job barrier splitting the SDOT matvecs + generic
parallel_for (video YUV→RGB) across all online cores. x86 has an equivalent
fleet (smp.rs): APs park in hlt with interrupts enabled and are woken by an
all-excluding-self IPI (a pause spin would cost a core of power per idle AP —
real heat and battery on a laptop), with the same static-partition barrier, the
same claim/done straggler protocol, and its own boot wake self-test. Callers reach
both through arch::parallel_for / arch::online_cpus — never
arch::aarch64::smp::* directly. That direct cfg(aarch64) call was how x86 came
to run every ONNX op, video row conversion and matvec on one core while aarch64
used the whole machine; a new parallel loop must use the neutral facade or the
divergence comes straight back. The barrier is bounded, never trust a worker wake: workers
enable the counter event stream (CNTKCTL_EL1) so WFE self-wakes, a
claim/done protocol recomputes a straggler's range on the BSP, and a boot-time
wake self-test (smp: wake self-test ok|FAILED ktrace) degrades to single-core
up front on hypervisors that park a trapped WFE until an interrupt —
VirtualBox-ARM does exactly that and used to hang the first prefill matvec
forever. Slow beats stuck; any new cross-core wait needs the same bound.
The PSCI gate fails open: bring-up skips PSCI only when a valid FDT
explicitly lacks an arm,psci-* node (Apple Silicon via m1n1 — hvc there
halts the guest). Boots with no FDT in x0 (QEMU/VBox -kernel ELF, the
UEFI stub) keep PSCI — gating those on FDT contents once silently turned SMP
off on QEMU (fdt::present distinguishes "no FDT" from "FDT says no PSCI";
the smp: N cores online ktrace is the first thing to check when inference
is inexplicably slow). QEMU vCPU count comes from CHITTI_SMP (default 8).
Also NB: make's RELEASE defaults to 1 — a dev kernel's unoptimized
NEON is many times slower and reads as an inference bug.
The interrupt mask is per-task state, and on aarch64 it was not. x86's
switch_to has always done pushfq/popfq and seeded INITIAL_RFLAGS with IF
set; aarch64's saved x19-x30 and d8-d15 and left DAIF as a global CPU
property. IRQs are masked on exception entry, so when sched::on_timer_tick
forced a switch from inside the IRQ handler, the incoming task resumed through
switch_to's ret rather than an eret and inherited the handler's masked DAIF,
with nothing to ever clear it — aarch64 preemption worked exactly once per
boot, and from then on the machine ran with interrupts disabled: a spinning task
could never be descheduled, and every later sched::block_on tripped its own
lock-discipline assert (which reads interrupts-enabled as "no Locked is held").
The interactive shell hid it completely by yielding constantly. DAIF is now in the
switch frame, and a fresh task's value is derived, not hardcoded the way x86's
is (context::initial_daif): unmasked where gic::init_bsp succeeded and
start_preemption committed, masked where the kernel is correctly cooperative
(Apple-Silicon HVF exposes no ICC_* to a bare-metal EL1 guest), because
unmasking on a machine with no usable CPU interface is its own hazard. One
ordering constraint falls out: a task spawned before start_preemption() keeps
a masked DAIF for life — true today on both paths, and worth not breaking.
Found the day the aarch64 unit suite first ran, which is the argument for it.
STANDING RULE — real hardware, nothing hardcoded to an emulator
Drivers must target real, standards-based hardware, not QEMU or VirtualBox quirks. Do not hardcode addresses, resolutions, device layouts, or behaviour to a specific emulator/hypervisor. Discover hardware the way real firmware does (ACPI/PCIe ECAM, UEFI GOP, fw_cfg, HID report descriptors, PrimeCell IDs, EDID/ mode tables) and degrade gracefully when a facility is absent. A feature that only works under QEMU is not done.
On Apple Silicon a probe of undiscovered hardware is not a failed probe, it is
the machine going down — and a guard at the call site does not survive a new
caller. Reading a compiled-in address costs nothing on a PC or a VM (an absent PCI
function answers all-ones), so probe-and-see is the normal shape and looks
harmless. There is no PCI to enumerate on a bare m1n1 boot unless chitti.wifi
brought APCIE up, and QEMU virt's virtio-mmio window at 0x0a00_0000 is inside a
Device-typed GiB with nothing behind it: the read takes an external abort, and what
the human sees is a reboot — the SoC watchdog resets a few seconds later — with
no syndrome, because nothing survived to print one. main.rs has always known
this, running the whole net/sound/clipboard bring-up block only in its
non-Apple arm. What that could not do is stop another caller from reaching the
same probes, which is exactly what adding a runtime re-probe to sound::ensure_up
then did: /open <audio> reset a Mac mini, and dropping chitti.wifi changed
nothing because the radio was never involved. The guard now lives inside
sound::autodetect, as data — sound::probe_order(apple) returns the backends
that machine may probe and Backend::probes_undiscovered_hardware classifies each
one, so a backend added without being classified fails a test rather than a
laptop. The generalisable rule: when a path is unsafe on a platform, the
refusal belongs in the function that does the unsafe thing, not in the one
caller that happened to know.
The display mode comes from the display, via EDID — never a constant, never
"the biggest mode advertised". The kernel itself holds no resolution at all:
width/height/pitch/pixel-format arrive from the firmware (Limine's
Framebuffer on x86, the stub's boot-info page on aarch64, m1n1's prepared
framebuffer on Apple Silicon) and the font scale is derived from the height
(pick_scale), so every layout is a ratio of whatever the panel turned out to be.
That means the only place a resolution is decided is the loader, and on real
hardware the chain is monitor EDID → loader picks the mode → kernel adopts the
framebuffer geometry.
kernel/src/edid.rs parses the EDID base block
(header + checksum validated, then the first detailed timing descriptor) into the
panel's native resolution; the aarch64 stub/ mounts that same file with
#[path] so the two can't disagree, and its pure bit-packing is unit-tested
(cargo xtask test) rather than only on hardware. The selection order is
EDID-preferred → keep the firmware's current mode → largest advertised mode,
and the middle step is the load-bearing one: with no EDID, the mode the firmware
is already in is the resolution the platform was configured for (VirtualBox's
VBoxInternal2/EfiGraphicsResolution, UTM's display setting), so overriding it
throws away the user's choice. Both arches had this wrong in different ways —
kernel/limine.conf pinned resolution: 2560x1440, and the stub always jumped
to the largest GOP mode — which is why a VirtualBox guest came up at a fixed QHD
surface regardless of its settings. On x86 the fix is simply not to set
resolution: (Limine then queries EDID itself, falling back to 1024x768 with
none); CHITTI_RESOLUTION=WxH cargo xtask image appends an explicit override for
a headless VM. Only fall back to the largest mode when there is no EDID and the
firmware's mode is below 1024x768 — a default nobody chose, which is the real
"UEFI came up at 800x600" case the largest-mode heuristic was written for.
A hypervisor's resolution knob cannot be trusted, so there is a channel that
does not need one. VBoxInternal2/EfiGraphicsResolution is stored by
VirtualBox-ARM and then ignored — the guest boots at the host panel's size
whatever it says — which left no way to ask for a framebuffer that fits the VM
window (VirtualBox draws the guest 1:1, so a 2560x1440 guest in a 1440-wide
window has half of itself off-screen; that is a clipped console, not a driver
bug). So the loader reads a preference off the ESP: \chitti-display.cfg,
resolution=<W>x<H>, parsed by edid::parse_boot_cfg and applied with GOP
set_mode before the kernel starts, outranking even the display's EDID-native
mode because it is the one size a human typed on purpose. CHITTI_RESOLUTION=WxH
now writes it at image-assembly time on aarch64 exactly as it appends
resolution: to limine.conf on x86, and make vbox VBOX_RES= goes through it.
Three rules it must keep: empty means unset (a wrapper passes the variable
through unconditionally), the depth component of Limine's WxHxBPP is dropped
(a GOP mode is chosen by dimensions, so writing it out would be ignored silently),
and a request is a ceiling — best_mode_for never exceeds it, since the reason
for asking is usually that something bigger does not fit. The stub logs the
firmware's entire mode list and says so when the requested size was not on offer;
without that, "the resolution I asked for did not happen" has two
indistinguishable causes (never offered vs. set_mode failed), and on a machine
that will not boot right that distinction is the whole diagnosis. Verified by
booting --uefi under AAVMF, which offers only 640x480/800x600/1024x768: a pinned
1024x768 reaches framebuffer TUI up (1024x768), a pinned 1280x720 correctly
lands on 800x600 (1024x768 is taller than 720) and says why, and an unset build
writes no file and behaves exactly as before. /display boot still only records
a preference — the kernel would have to write FAT to mirror it to the ESP — and
says so rather than implying a reboot will apply it.
Resolution is a setting, and there are exactly two kinds of it — /display
(kernel/src/display.rs, pure + unit-tested; persisted to
/configs/core/display.json; also exposed to the settings agent as the
display shell tool, which may apply it directly since it is reversible):
- The logical desktop (
/display set <WxH>|native) — applies instantly on both arches.width/heightonScreenare the logical desktop andorigin_x/origin_yplace it inside the physical framebuffer, so a smaller resolution is a centred, letterboxed viewport that still renders 1:1 — glyphs are rasterised at physical pixels, nothing is scaled, text stays sharp. The entire translation is one function,Screen::fb_offset, which every framebuffer write goes through (there are only five such sites —put_pixel, the row blit, the cursor read-back, the pane scroll's row copy, andread_rgb32_row(the/screenshotread-back, added deliberately: it is the read mirror ofblit_rgb32_row); keep it that way). NB the physical accessors —fill_physand its read mirrorread_phys_rgb32_row— bypass it on purpose, since a letterbox bar and a whole-panel capture are outside the desktop by definition. At native both origins are 0 and it is the identity, so the default path is byte-identical to before. Noterebuilt/relayoutmust feedbuildthefb_w/fb_hphysical size, neverwidth/height, or the viewport shrinks on every rebuild; andpick_scaletakes the logical height so a smaller desktop gets proportionally sized text. - The font scale (
/display scale <1-4>|auto) — cells are8*scalex16*scalepx, so this is what answers "everything is too small on a high-resolution screen"; a smaller desktop only letterboxes. The automatic value isdisplay::auto_font_scale(height), thresholds not a division: the old(h + 550) / 1100needed 1650 px to reach scale 2, so a 2560x1440 panel rendered at scale 1 — 8x16 px cells, 320 columns — which is what actually made a 2K display look broken, independently of which mode the loader picked. - The panel's own mode (
/display boot <WxH>|auto) — only the loader can set this, so it costs a reboot. This is recorded but NOT yet applied: the preference lives on the ext4 store and the loader can only read the ESP, so mirroring it there (a FAT write viablock::esp, then the stub reading it and the x86limine.confresolution:line being rewritten) is the missing bridge. Until then/display bootsays so explicitly and points at the platform knobs that do work (VBOX_RES,CHITTI_RESOLUTION) — do not let it claim otherwise.
Display settings are stored per monitor, the way monitors.xml does it. The
stub copies the chosen output's EDID base block into the boot-info page
(length at 384, block at 388) — the firmware's buffer is gone by the time the
kernel runs, so it is handed over or lost, the same handoff Linux's EFI stub makes.
edid::identity unpacks the display's own vendor/product/serial (the manufacturer
code is three five-bit letters packed big-endian in bytes 8..10 — reading it as
a u16 gives nonsense) and edid::monitor_name reads the 0xFC descriptor, so
/display can name the output it is talking about. display::profile_key keys the
settings on that identity, falling back to fb-<W>x<H> where no EDID is published
(hypervisors, and the x86/Limine path, which passes none) so two
differently-sized monitors still get separate profiles. display.json is
therefore a displays: { key: {logical, font_scale} } map plus a global
boot_mode; the older flat shape is adopted for the display in use and migrated on
the next save rather than discarded. A save rewrites only the current
display's entry.
KMS — real kernel mode setting (kernel/src/kms/) follows Linux's DRM split:
kms/mod.rs is the device-independent core (Mode/Connector/Scanout, the
DisplayDriver trait, mode-set orchestration, damage accumulation, polled
hot-plug), and each device is a backend. virtio-gpu is implemented and verified
(kms/virtio_gpu.rs): GET_DISPLAY_INFO → RESOURCE_CREATE_2D →
RESOURCE_ATTACH_BACKING (the device scans out of our DMA pages, so the
compositor draws with no copy) → SET_SCANOUT, then
TRANSFER_TO_HOST_2D + RESOURCE_FLUSH to present. Confirmed by screendumping the
virtio-gpu device itself: a 1280x800 console really becomes 1280x720, full
panel, scrollback intact.
Four things that path teaches:
- virtio-gpu does not scan out of guest memory continuously. Drawing alone
changes nothing on screen — it must be transferred and flushed. Damage is unioned
by
kms::damagefrom the coarse painters (fill_rect,blit_rgb32_row,draw_str,redraw) and flushed once perupkeep;put_pixeldeliberately does not report, because a redraw is millions of calls and a per-pixel union costs more than the flush it feeds. A flush per glyph is a queue round trip per glyph. - Damage is in physical coordinates, so the logical-viewport origin has to be added — a scanout is the whole framebuffer, not the desktop.
- A KMS-only machine has no framebuffer to re-init.
reinit_scanouttherefore initialises the console when none exists; without that, booting with only a virtio-gpu gives a blank screen (found by doing exactly that). - On aarch64
-kernelthere is no PCI (ECAM comes from the stub's ACPI), so virtio-gpu binds on the UEFI path and on x86, not on the plain-kerneldev loop. Matched by vendor+device id, never display class:virtio-gpu-pcireports class03:00like every other VGA device.
VMSVGA (kms/vmsvga.rs) works — the backend for VirtualBox and QEMU's
vmware-svga. Verified by screendump: 1024x768 -> 1280x720, clean. Getting there
needed three things that are each easy to get wrong:
- The FIFO, not just the mode registers. SVGA II ignores
WIDTH/HEIGHTuntil its command ring (BAR2) is configured andCONFIG_DONEis accepted: setMIN/MAX/NEXT_CMD/STOP, whereMINmust clear the extended register area (SVGA_FIFO_NUM_REGS * 4) whenSVGA_CAP_EXTENDED_FIFOis set, andMAX - MINmust leave at least 10 KiB or the device rejects the ring. Before that the registers read back whatever was written while the scanout keeps its geometry — the console rendered four times side by side.initrefuses to bind ifCONFIG_DONEreads back 0, because driving it in that state makes a mode set silently do nothing. flushis NOT a no-op. In VGA mode the device tracks framebuffer writes; once in SVGA mode it only repaints fromSVGA_CMD_UPDATEin the FIFO. So the driver queues an update rect per damage flush and pokesSVGA_REG_SYNC. Drawing without it leaves the screen frozen on the mode-set frame. (virtio-gpu needs the same thing for a different reason — see above — so both backends are damage-driven.)- The geometry registers do not report the mode in effect. Before the guest first
enables SVGA mode they hold the device's defaults (QEMU answers 640x480) while the
display is at whatever the firmware programmed through VGA. So the current mode is
seeded from the live framebuffer and only falls back to the registers; trusting
them made
preferred640x480 on a 1024x768 console, which is what a KMS-only boot would then have come up in.MAX_WIDTH/MAX_HEIGHTis a VRAM ceiling (an odd 2368x1770 on QEMU), never a mode to offer as native.
Two safety rules this driver had to learn the hard way, both after breaking a real VirtualBox display:
- Probing must not change the device.
CONFIG_DONEand the ring pointers alter how the device scans out, and at probe time the console is still drawing into the firmware's framebuffer — so writing them ininitmoved the scanout out from under a live console and left the display offset and clipped. They now happen lazily inensure_fifo, on the first actual mode set. Same rule the I2C/EC drivers follow: identification only ever reads. VMSVGA_ALLOW_MMIOis off.Regscan reach BAR0 as I/O ports or MMIO, but only the port path can be tested here (QEMU emulatesvmware-svgaon x86 only, where BAR0 is I/O). VirtualBox-ARM needs the MMIO path and its register layout is a guess; acting on that guess mis-programmed a real display. So it declines and keeps the firmware framebuffer — the KMS layer is optional, and getting these registers wrong costs the console, not just a feature. Verify the layout on the target before flipping the flag.
Bochs VBE (kms/bochs.rs) is the backend for QEMU's default adapter —
-vga std, PCI 1234:1111, Linux's drivers/gpu/drm/tiny/bochs.c. It matters more
than its simplicity suggests: virtio-gpu and VMSVGA both have to be asked for, while
this is what a plain qemu-system-x86_64 -M q35 gives you, including from our own
RUN.md, which names no display device. Without it that boot is Linux's nomodeset
position — mode fixed by firmware, /display able only to letterbox something
smaller. Verified by screendumping QEMU: 1280x800 -> 1920x1080 -> 2560x1440,
console clean and full-panel at each. Four things it pins down:
- EDID is at the base of the MMIO window, not
0x600.0x600is the QEXT region (Linux readsqext_sizefrom exactly there); the EDID occupies 0 up to the VGA register block at0x400. Written from memory as0x600it read a size word, failed the header check, and reported "this device publishes no EDID" on every configuration — includingedid=on,xres=…,yres=…, where QEMU certainly does publish one. A wrong offset that looks like an absent feature. Fetch these from the Linux source, never recall them. - That one offset also made
/display listlie. With no EDID the mode list is just "everything that fits in VRAM, largest first", and the list labelled its head(preferred)whenever any driver was bound — so a boot at the display's real 1280x800 read as the OS knowing you wanted 2560x1600 and ignoring it. The label now comes from the connector's ownpreferred(kms::preferred_mode), so it appears only when a display actually asked for something. ENABLEmust bracket the geometry writes — cleared first, set last. Geometry written to an enabled device leaves the scanout on the previous configuration while the registers read back the new one, which is how VMSVGA in this tree once drew the console four times side by side.modeset_sequencereturns the writes as data so the ordering is a unit test rather than a comment.VIRT_WIDTHis a stride in pixels, not bytes, and an oversized mode is refused rather than attempted — the device programs one happily and then scans out memory that is not there.
Its transport is chosen by reading the id register back through it rather than
by measuring the BAR: sizing a BAR means writing all-ones into it, and at probe time
the console is still drawing into the firmware's framebuffer. MMIO is preferred over
the 0x01CE/0x01CF ports because aarch64 has no ports at all. It claims only
1234:1111 — VirtualBox's 80ee:beef implements the same registers, but mis-driving
a real VirtualBox display is precisely what VMSVGA already did once, and that costs a
console rather than a feature.
Without a bound backend the whole module is inert and the compositor keeps the
loader's framebuffer — the position Linux is in with efifb/simpledrm
(nomodeset): mode fixed by firmware, /display set letterboxes instead, console
legibility via font size. Still absent: real-hardware GPU drivers (i915/AMD/AGX) —
see the note on why there is no display equivalent of xHCI/AHCI.
The identity map reaches 512 GiB, and QEMU virt puts its 64-bit PCIe window at
exactly that address. T0SZ=25 gives a 39-bit VA with a single-level L1 of 512
one-GiB blocks, so map_device_gib could not describe 0x8000000000 — and it
returned silently, leaving map_mmio to hand back an unmapped physical address.
A driver then wrote to it: ESR 0x96000044 (data abort, DFSC 0x4 — translation
fault at level 0), FAR 0x8000008014, immediately after "virtio-pci enabled".
Firmware only puts a BAR there when it has the room: TCG does, Apple's hypervisor
has a smaller guest physical space and does not, so the same image booted under
HVF and died under TCG — and it would die the same way on any machine that
assigns 64-bit BARs high. High windows are now aliased into spare L1 slots
(mmu::map_device_va, which map_mmio returns), not identity-mapped: reaching
past 512 GiB otherwise means a 48-bit VA and an L0 root, and ring-3 tenants switch
TTBR0 to roots sharing this table, so it would change every tenant address space
on a path that has already faulted real Apple cores over a live table edit. Nothing
needs high memory identity-mapped — map_mmio results are CPU register accesses,
while anything a device dereferences comes from alloc_dma off the heap.
Three copies of the virtio-pci capability walk mapped a fixed 16 KiB and then
added an unbounded offset (kms/virtio_gpu, drivers/virtio/transport,
arch/aarch64/virtio_pci — the last did not map at all, it added to the physical
BAR). offset is a byte offset within the BAR and the capability carries its own
length at cap+12; a fixed span is right only until a device puts a structure
past it, which QEMU's virtio-gpu does at 0x8014. On aarch64 whole-GiB mapping hid
it; on x86 map_mmio is page-granular, so it was a latent page fault there too.
Each fault had to be found by resolving the faulting PC against the kernel's symbol
table (nm + the load base), which is the fastest tool here by a wide margin —
three different call sites, identical syndrome.
The boot-info page is built even when there is no display, and that coupling was
a boot failure. The stub's GOP capture and the boot-info page used to be one
closure: no GOP handle, a refused open_protocol, or a blt-only mode returned
None for the whole page, and the comment said so as if it were harmless
("kernel falls back to ramfb/serial"). That was true when the page carried only a
framebuffer. It has since grown the kernel heap region, the model region, the RAM
and free extents, the ACPI RSDP and the wall clock — so "no boot-info" stopped
meaning "no picture" and started meaning "no memory map". detect then falls
back to FALLBACK_RAM_END and mm::init places its 1 GiB heap at 4 GiB, which is
unbacked on any machine with less than ~4 GiB: ESR 0x96000050, FAR 0x1_0000_0000,
a synchronous external abort on the first write in LinkedListAllocator::init.
Under HVF the syndrome carries ISV=0, so QEMU asserts in hvf_handle_exception
rather than reporting a guest fault — two failures that look nothing alike, one
cause. It made the released aarch64 image unbootable on QEMU virt (which reaches
no GOP handle) while VirtualBox, which offers a normal GOP, was fine. Display
acquisition is now its own step whose failure zeroes the framebuffer fields and
nothing else. The same coupling existed a second time on the kernel side —
bootinfo_regions returned None when the stub reported no heap, discarding the
RAM extents with it, which is what a 1 GiB guest hits (the stub cannot reserve a
1 GiB heap and says OUT_OF_RESOURCES). A zero heap base is now information, and
that machine gets the existing "not enough memory, raise -m" panic instead of a
hypervisor abort. Two rules fall out: a handoff structure must not be
all-or-nothing across independent fields, and ram_end comes from the
firmware's exact extents, never maxed with a size-derived estimate
(mm::ramlayout::ram_end, pure and tested — arch/aarch64/ is cfg'd out of the
test build, so logic placed there cannot be). Related: the stub's total_ram_bytes
spanned lowest-to-highest non-MMIO descriptor, which on QEMU virt starts near 0
while RAM starts at 1 GiB, so a 2 GiB machine reported 3 GiB; it sums DRAM
descriptors now, with the same filter ram_regions uses so the total and the
extents describe the same memory.
On m1n1, /memory is not "the RAM this machine has" — it is the window m1n1
says the kernel may use, and refusing to believe it cost real Apple hardware
every ring-3 tenant. mm::aarch64_frames declined to build a frame allocator on
Apple, reasoning that "m1n1 stays resident in RAM the device tree does not
describe". It is resident, and it does describe it: top_of_memory_alloc
shrinks cur_boot_args.mem_size as m1n1 allocates, and dt_set_memory writes
/memory last, deliberately (its own comment says so), so the boot
framebuffer, the ISP heap, the GPU initdata and m1n1's log buffer are already
outside the node by the time we read it. What is still inside is named in two
places, and Linux honours both: the FDT memory reservation block (m1n1's own
image, the device tree, one stack per secondary CPU, and the initrd — which on
this path is the GGUF, since cortex::model_module reads the model from
/chosen), and /reserved-memory, whose uat-handoff / uat-pagetables /
uat-ttbs nodes agx::hw itself resolves by phandle and the GPU firmware reads
while we run. fdt::mem_reservations and fdt::reserved_memory parse them
(pure, unit-tested on both arches) and aarch64_frames subtracts them. Three
things to keep: a reservation that does not fit the list is declined, not
capped — the post-carve verification cannot catch a dropped entry, since both
sides read the same list; the uat-* nodes are <0 0 0 0> in the checked-in
.dtb and filled in only on the live machine, so a parser tested against the
tree in this repo sees nothing at all and must treat a zero size as unfilled
rather than as a zero-length reservation; and the symptom of not having an
allocator was LoadError::NoAddressSpace on a path that mentions neither
memory nor m1n1 — /open reporting "the decode sandbox could not be started"
and every package-UI app failing ui_surface_request.
A machine can have more than one display, so the stub enumerates every graphics
output (locate_handle_buffer, not get_handle_for_protocol) and picks one via
edid::pick_output: the output carrying the firmware's console-out marker
(EFI_CONSOLE_OUT_DEVICE_GUID) first — that is where the firmware drew its own
boot messages, hence the display the user is watching — then any output with a
readable EDID (proof something is plugged in), then output 0 so a headless box
still gets a console. Taking handle 0 unconditionally, as this did, was a coin flip
between a laptop's built-in panel and its attached monitor: it would read one
display's EDID and set the mode on the other. Each output's console_out/edid is
logged, so "wrong screen" is diagnosable from the boot log alone.
The QEMU ramfb window is a separate path with the same "match the display, not
a constant" rule, and it was wrong in its own way: it scanned system_profiler
for the first Resolution: line and used the physical pixel count. On a
multi-monitor Mac that silently picked whichever display was listed first, and on
a HiDPI panel it handed the guest a framebuffer bigger than the desktop showing it
(a 2560x1600 panel whose desktop is 1440x900). xtask::parse_displays now parses
the per-display blocks (pure, cargo test -p xtask) and takes the main
display's desktop size — macOS's UI Looks like when present, else the physical
size halved for a Retina panel, since Apple's default scaled modes are an
unpublished per-panel table and the pixel count is never the right answer.
CHITTI_FB_DISPLAY=<name substring> picks another monitor; CHITTI_FB_RES=WxH
pins it. Every detected display is logged with * on the main one.
Concretely: display comes from the firmware (Limine GOP on x86, UEFI GOP via the
stub/ bootloader on aarch64, QEMU ramfb as a fallback); disks via virtio /
NVMe / AHCI over discovered PCIe; input via USB xHCI/HID (keyboard and mouse,
report-descriptor-driven), virtio-input, PL050/PS-2, and HID-over-I2C
(drivers/i2c_hid.rs on drivers/i2c.rs, the DesignWare/LPSS master) — the touchpad on
laptops from ~2016, which have no PS/2 aux port. An I2C device cannot be probed for:
its address comes from _CRS, so it is located by asking the namespace which device
claims PNP0C50 (aml::device_by_hid). Identification only ever reads, and
present() is a zero-length probe, because the same bus commonly carries the embedded
controller and the PD controller — a stray write there misconfigures real hardware. The
HID descriptor register comes from _DSM and is defaulted to 0x0020, but the
descriptor read is validated (length + version), so a wrong guess is detected rather
than silently producing garbage. Report decoding is shared with USB via
xhci::feed_pointer_report, so a touchpad and a mouse cannot drift apart; the wall clock from the
RTC / UEFI GetTime / the virtual counter — each behind a shared facade with a
per-arch implementation. The same kernel image must run on QEMU, VirtualBox, and
real UEFI hardware.
On x86, ACPI tables must be mapped before they can be read. Limine's HHDM
covers usable RAM, and the tables live in firmware-reserved regions outside
it — so both the raw physical address and its phys_to_virt translation are
unmapped, and touching either is a page fault that halts the boot, not a garbage
read a signature check can reject. (Cost two boot hangs to find: 0xf52e0, then
0xffff8000000f52e0.) acpi::map_table maps every table page explicitly on x86
and remaps to the header's declared length, since an XSDT can exceed a page.
aarch64 is deliberately untouched there: it has a flat identity map, and
init_uart reads SPCR before the frame allocator exists. Relatedly, Limine's RSDP
pointer is physical on newer protocol revisions and HHDM-virtual on older ones,
and the two cannot be told apart by trying both — classify by range (higher half =
already virtual), then signature-check.
FADT field offsets are named constants, and one of them was wrong. X_DSDT is
at 140; the code read it from 148, which is where X_PM1a_EVT_BLK's Generic
Address Structure starts. That does not fail loudly — it yields
space|width|offset|access|address_lo32 reinterpreted as a u64, a large
plausible number that sailed past the plausibility guard and made the DSDT
unfindable on every machine with a modern FADT. Consequence: on x86 the whole AML
layer silently did nothing — no _S5_ poweroff, no I2C touchpad, no battery — and
nothing reported an error, because "no DSDT" is a legitimate state. Every offset this
reads is now a named constant with a test that pins it (x_dsdt_is_at_offset_140_not_148
spells out the wrong read for the next person), and the pure decoders
(acpi::fadt_dsdt, acpi::fadt_pm1) take a slice so they are testable off-hardware.
A related trap in the same family: the PM1 event block is split down the middle —
status first, enable second — so PM1a_EN is at PM1a_EVT + PM1_EVT_LEN/2, not
a fixed +2; assuming +2 writes an enable mask into the middle of the status
register on any machine with an 8-byte block.
The power button works, and the FADT says which kind it is. drivers/pwrbtn.rs
arms the ACPI fixed-feature button (PM1 status bit 8) and shell::upkeep polls it
— one in per pump, which is cheaper than routing an SCI on a cooperative scheduler,
and a button press is a human-timescale event. It refuses to arm unless the FADT
described a fixed-feature button, ACPI mode is on (SCI_EN), and the event block is
long enough — each refusal ktraced, because "the power button does nothing" is
otherwise indistinguishable between those cases. Two rules keep it from powering a
machine off by accident: an all-ones status read is an unclaimed port, not every
event firing at once, and PM1 status bits are write-1-to-clear, so the ack writes
only the button bit rather than the whole word (which would acknowledge every other
pending event). The control-method (PNP0C0C GPE) button — what many laptops
use — is reported, not guessed at: FADT flags bit 4 says so, and GPE dispatch is
honestly unimplemented rather than silently polling a bit that will never change.
Uniquely for this hardware area, it is verifiable in a VM: QEMU's
system_powerdown sets exactly that status bit, and the power_button e2e scenario
presses it through the monitor (-serial mon:stdio, so Ctrl+A c reaches it — no extra
plumbing) and asserts a clean shutdown. /battery prints the button's state alongside
the battery's, and tests/e2e/run.py --only <names> exists so one scenario can be
iterated on without the 30-minute sweep.
Poweroff and the scheduler tick are real hardware now, not emulator stand-ins.
/poweroff performs an ACPI S5 transition (SLP_TYPa | SLP_EN to the FADT's
PM1a_CNT, with SLP_TYPa decoded from the DSDT's \_S5_ package by bytecode
scan; see the AML note below), keeping QEMU's isa-debug-exit write only as a
fallback; it used to write only that port, so on a physical machine /poweroff
did nothing and left the fans running. The tick prefers the local-APIC timer
calibrated against the HPET (arch/x86_64/hpet.rs), falling back to the
PIT/8259 — both of which a UEFI-only machine may omit entirely, in which case the
old code had no preemption at all and said nothing. Every wait added here is
bounded and the HPET gets a counter-liveness probe, because an unbounded spin on a
dead reference clock hung the boot before a single test ran.
AML (aml.rs) decodes, locates, and evaluates a fail-closed subset. ACPI
describes anything unenumerable as bytecode in the DSDT, so aml.rs is the byte layer:
PkgLength, NameString, data objects, then devices() / methods() walking
Scope/Device/Method (all three carry a PkgLength, so their extent is exact).
device_by_hid + device_name answer "what is this device's _CRS" — which is the
question a driver asks and a flat scan cannot answer. Three encodings cause all the
bugs, each pinned by a test: PkgLength is asymmetric (low six bits alone, low four
when more bytes follow), NameString has five forms, and OnesOp is all-bits-set,
not 0xFF. Containment is the other bug source — a parent's body contains its
children, and a Name inside a method body is a local; both are excluded from
device_name, and both were shipped wrong first and caught by tests.
On top of that sits an evaluator (eval_method, eval_device_method, and the
_with_fields variants): Return/If/Else/Store, Local0-7/Arg0-6, the
comparison and one-target arithmetic operators, and dynamic Package construction. Its
governing rule is that an unsupported opcode returns None, never a value — an
evaluator that guesses an integer is worse than the validated default it would replace,
which is why it was not half-built earlier. Note two ACPI traps it encodes: TRUE is
all-bits-set, so a caller comparing against 1 reads every true result as false, and a
method that falls off its end without Return yields None here rather than the spec's
zero — for these callers "unsupported control flow" is far likelier than a deliberate
zero. OperationRegion/Field (regions, fields, find_field) locate the named
bit-ranges a method actually reads; a reserved field entry still advances the bit
cursor (skipping it shifts every later field, which is how a battery reports a voltage
as a capacity), and an AccessField stops the walk rather than continuing with offsets
that would be wrong.
A real battery percentage is the composition of all of it. drivers/ec.rs is the
ACPI embedded controller — PNP0C09's _CRS (authoritative; the fixed 0x62/0x66
are only an x86 fallback) driven through bounded spins, with a 0xff status rejected as
an unclaimed port before any command is written and a stale output byte drained so a
read cannot return the previous transaction's value. drivers/battery.rs evaluates the
firmware's own _BST with a field resolver that reads EmbeddedControl/SystemMemory/
SystemIO bytes, takes last-full capacity from _BIX (index 3) or _BIF (index 2), and
reports remaining / last-full — last-full, not design, or a worn battery reads
permanently below 100%. Surfaced as the ${battery} status-bar variable
(ui_config.rs), cached for 5 s because one reading costs an AML evaluation plus a
handful of EC transactions; a variable that resolves to nothing takes its separator with
it, so a desktop's bar is byte-identical to before. Every layer fails closed and ktraces
which step gave up. None of this is verified on hardware — QEMU emulates no ACPI EC
and no battery — so the pure arithmetic (bit assembly, _BST/_BIF shapes, the
handshake against a simulated controller incl. slow/wedged/dead) is what the tests hold.
The touchpad's descriptor register now comes from _DSM too
(drivers::i2c_hid::descriptor_register) rather than the 0x0020 default — note the
_DSM UUID goes in ACPI's mixed-endian buffer order, or the table's own LEqual
fails and the method silently takes its unsupported branch.
A HID-over-I2C touchpad reads fine while powered down, which is the trap. The HID
descriptor is answerable from a device that has never been powered on — so descriptor
parsing appeared to work while no report would ever arrive. SET_POWER(ON) then RESET
through the command register (drivers::i2c_hid) is what makes reports flow, and the
command encoding is register-address-LE then argument then opcode: swapping the last two
sends SET_POWER as report-type 8 of opcode 0, which a device answers by doing nothing
rather than by NAKing, so the symptom is a dead touchpad and not an error. The sequence is
deliberately only reachable after HidDesc::parse validates, because those are the
first writes this driver makes and the same bus carries the embedded controller.
sleep()/resume() exist for the suspend path, where the device loses its state.
A battery percentage needs the AC adapter to be meaningful, and _BST will not tell
you. Once a pack is full, _BST reports neither charging nor discharging — so a
plugged-in machine and one running down produce byte-identical flags. ACPI0003's _PSR
is the missing half (= in the status bar), reported as None rather than guessed as
unplugged when no adapter device exists. Two more things a laptop needs: _STA bit 4 says
whether a bay actually contains a pack (a removed battery leaves its device in the
namespace), and a machine with two packs has two PNP0C0A devices — aml::devices_by_hid
returns all of them and the capacities are summed, because reporting the first pack
presents half the machine's charge as all of it. Flags union: one pack discharging means
the machine is.
The RTL8125 is not register-compatible with the 8168 it is dispatched with. The
2.5GbE parts move the interrupt mask and status to 0x38/0x3c and widen them to 32 bits,
and the transmit doorbell to 0x90 — and the 8168 offsets overlap those positions, so
driving an 8125 with them writes the doorbell into the interrupt mask. net::r8169
carries a per-chip RegMap (pure, unit-tested, including that every id the dispatcher
sends here lands in exactly one layout) rather than a comment saying to treat 8125 with
caution. Still unverified: QEMU models no r8169-family part at all.
Intel WiFi (drivers::wifi::iwl) is identification and firmware only, deliberately.
An Intel radio does nothing until an image is loaded, and the image is chosen by chip
family plus an API version that is a property of the file — Linux tries filenames
newest-first, and so does fw::firmware_candidates. An unrecognised Intel id is not
claimed: the wrong firmware fails a signature check inside the device with no error the
host can read, which is worse than the Ethernet dispatcher's silent non-receiving NIC.
The .ucode TLV parser refuses a pre-TLV image (leading word non-zero), a wrong magic and
any record claiming more than the file holds, and pads record lengths to 4 bytes — one
odd-length record misaligns every record after it. On top of that, csr is the register
map with its pure predicates (all-ones is a floating bus, not data; a prph address needs
its access-size bits or the following write vanishes), context is the gen2 context
info — from AX200 onward the host does not feed firmware section by section, it hands the
device a structure and the device's own loader fetches the image, so nearly all the risk
moves into one struct layout and every offset is pinned with offset_of! — and device is
the ordering: prepare the card (NIC_READY going clear is the ready signal; waiting
for it to set never completes), APM init, stop the DMA master before resetting so no
transfer is in flight against memory about to be reused, then grab MAC access — proceeding
without the grant is worse than failing, because reads return stale values and writes are
dropped, so bring-up appears to work and the device never starts. Every wait is bounded and
names itself. Bring-up is command-driven (/wifi up), never automatic at boot: the
same posture AGX and the Broadcom radio take, because an untested driver should not touch a
device just because the machine started. Firmware is fetched, never
committed (cargo xtask iwlwifi-assets into the gitignored assets/wifi/iwl/), which
is the same rule the Broadcom assets follow and the reason this needed no licensing
decision. What still does not exist: the receive path — so firmware's own alive
notification cannot be observed, which is why "handed over" is the strongest claim the load
makes — the command round-trip, and then 802.11 + WPA2. So the radio does not associate and
/wifi connect still cannot work; /wifi up reports how far bring-up got instead.
Interrupt-controller bases are discovered, and there are two sources, not one.
aarch64 finds the GICv3 from the device tree's arm,gic-v3 reg when there is an
FDT, and otherwise from the ACPI MADT (acpi::gic_from_rsdp: GICD type 0x0D
for the distributor; the redistributor from the GICC entry whose MPIDR matches
this core, else the first GICC's GicrBaseAddress, else the GICR discovery
range). Both windows get map_device_gib. This matters because the two cases are
different real platforms: QEMU virt boots via -kernel with an FDT, while
VirtualBox-ARM, UTM and real SBSA machines boot the UEFI stub with no FDT at
all — and requiring the FDT node left every one of those silently cooperative,
with no timer preemption, forever. An FDT that exists but lacks arm,gic-v3 is
Apple Silicon: stay cooperative and do not fall through to ACPI (there is
none, and probing a guessed base is an uncatchable data abort, not a trappable
UNDEF). The QEMU-virt addresses survive only as a last-resort default when an
FDT claims a GICv3 but carries no readable reg.
What exists today (subsystems, not phases)
- Agent layer — an orchestrator running a real tool-use loop
(
model → tool → result → repeat, budgeted); isolated sub-agents; a shared type contract inagent/types.rs. - Sessions (
session/) — serializable message history + todos + env + caps, saved/resumed/forked over the memory store (postcard). - Tools (
tools/) — MCP-shaped registry → Router → Synapse cap+taint gate; builtin toolset; provider registration. - The OS can explain its own extension mechanism.
build-agentis a bundled skill (skills/bundled.rs): its L0 description triggers on "new agent", "new tool", "extend", its L1 body is the whole loop (agents new|build|validate|install --path| test|reload, theexport functioncontract, theChittisurface, and what each failure message means), and its L2 asset is a complete workingtools.jsso an agent copies correct code instead of reconstructing the ABI from prose. Adding it found a small pre-existing wrongness worth knowing about: two bundled skills declaredAsset.bytesby hand and had drifted from their payloads (64 vs 77, 80 vs 84). Sizes are computed now, andbundled_skill_assets_are_declared_and_presentpins every declared asset to a real payload — which also guards the trap thatplace_trustedsilently drops an undeclared payload. - Skills (
skills/) — L0/L1/L2 progressive disclosure, signed install with consent + capability subsetting, installable skill-agents. Agents as installable apps: a package is markdown (SOUL.md persona +skills/*.mdprocedures) + a manifest (toolset = permissions,capabilities, optional ONNX assets) + a signature; installed via/agents install <name> [--yes](consent modal → grant only the approved subset →place_agent_homelands the SOUL/docs in/agent/<id>/). Per-agent filesystem sandbox: every non-orchestrator agent is confined to its own/agent/<id>/folder — the install grants a baselineFs @ /agent/<id>/**cap (skills::install:: with_home_sandbox) and nothing wider unless the manifest explicitly requests a broaderFsscope, which the consent screen flags as "FULL filesystem access". Enforcement is the executor's scope gate (Gate 2.5);list/searchare result-filtered by that same gate so a confined agent can't even enumerate paths outside its home. The shell agent (orchestrator) is the root and keepsScope::Any. A public registry (skills/registry_client.rs) fetches a signed index over HTTP(S) —/agents search <url> [q],/agents install <name> --registry <url>; registry packages authenticate with ECDSA P-256 (skills::crypto::verify_p256, RustCryptop256/sha2, baked publisher trust store) while local dev/boot packages use the keyed-MAC. - Channels (
channel/) — cap-gated byte-stream + datagram IPC between agents (the Linux pipe/socket analog; distinct fromipcu64 endpoints).Right::Channel{Read,Write}(ChannelId)are per-direction ends; a model-emitted channel handle is aCapslot in the caller's own table (executor resolves it — no ambient authority). Backends: heap ring (Pipe), datagram queue, or a live TCP socket (Tcp, viaadopt_tcp) so a service agent can hand an accepted connection to another agent (channel_grant). Synapse primitiveschannel_create/write/read/close/grant. - Service agents (
service/) — long-running native daemons (vs request/response reasoning agents):ServiceSpec {entry serve loop, autostart, caps},start/stop/task_for/supervise_tick(pumped fromshell::upkeep, bounded restarts). Their protocol/codec logic is native, deterministic code below the determinism boundary — the LLM never implements a protocol. Only agents that actually reason from a SOUL are installed agents — the built-in roster isdoc,ssh,chess,media,pdf,download,todo, plus the app packagesnotes,paint,slides,minesweeper,snake,synth— each a markdown SOUL plus a JSON manifest under the repo'sagents/folder, compiled into the image viainclude_str!, signed and installed into/agent/<id>/at boot byagent::system::install_all(same permissioned flow as any package, pre-trusted; a content agent's assets land in/agent/<id>/assets/).network/httpare not agents — pure mechanical plumbing (relay bytes, parse a protocol; no judgment, no SOUL), living entirely incrate::service. The web is a generic pipeline (service/pipeline.rs) of single-responsibility stages connected by datagram channels — all reusable infrastructure, none app-specific:network(service/network.rs) owns the socket and relays raw bytes;http(service/http.rs) parses the request + formats the response (no FS, no socket);server(service/server.rs) is a generic content runtime that serves whichever content agent the pipeline was started for — it runs that agent's model as a bounded ReAct loop (prompted with the agent's ownSOUL.md) which returns a JSON response object ({status, content_type/headers, file/body});server.rsparses that JSON and frames the reply. The body is either inlinebodyor an asset the agent names (file) / reads itself (amem_fs_read<tool_call>) — both go through the capability- and scope-gated reader confined to the agent's ownassets/, so the SOUL agent decides and reads the content while native code only parses + frames (determinism boundary intact). So a web server is justagents/<name>/{SOUL.md, manifest.json, assets/…}— the SOUL carries the routing/behaviour (model-planned per request, greedy), the assets carry the content, and no per-server Rust is written.docis exactly such an agent (data, not code)./agents start <name> [port]serves that agent over the pipeline;sshruns standalone (RFC 4253 version exchange; transport is a stub)./agents serviceslists running stages. Git + full SSH transport follow the same native-protocol shape. To add a built-in server agent: dropagents/<name>/{SOUL.md,manifest.json,assets/…}and register it inagent/system.rs(one line) — or publish it to the registry. - Apps — wasm-tool agent packages. An "app" is an installed agent whose
deterministic logic ships as
assets/tools.wasm(string ABI:export(args_ptr, args_len) -> i64 = (ptr<<32)|len,chitti_allocfor host writes; run byagent/wasm_rt.rsunder fuel + memory limits from the manifest — no host imports unless bound). The SOUL carries judgment; the wasm carries rules — chess (chess_legal/chess_try_movefromtools/chess-wasm), doc's HTTP router (route_request,tools/doc-wasm), pdf's document digest (pdf_digest,tools/pdf-wasm— xref tables+streams, ObjStm, FlateDecode reusing the kernel'simage/inflate.rs, text extraction; its page renderer is a separatestdmodule — see the ring-3 section), the full chess game (tools/chess-wasm— rules, board UI, and the agent-opponent flow; zero chess code in the kernel), and the app suitenotes/paint/slides/minesweeper/snake/synth(one shared module fromtools/apps-wasm). git is a wasm-tool agent too (git_commandfromtools/git-wasm,agents/git/): a real git over the store — loose objects (SHA-1 + zlib),init/status/add/commit/log/branch/checkout, smart-HTTPclone/push(.git/configrecordsorigin, so/git pushneeds no URL), a.gitignorematcher for untracked paths, and a working directory that starts at the shell's pwd (git clonemakes a folder named after the repo basename in the current dir, like the CLI). It needs host imports beyond the pure-string ABI, gated by its manifest capabilities:host_fs_*(write home-scoped unless the manifest grantsfsscopeany),host_sha1,host_inflate/host_deflate(stored-block zlib + consumed length),host_now_unix,host_user_home/host_home, andhost_http(only for agents whose manifest declares anetcap). Chat tool calls run on a fresh instance — design those digest-once (one call returns everything as JSON; the kernel caches) and pass binary inputs as base64 — but a running package-UI app keeps ONE persistent instance (service/package_ui.rs): guest statics ARE the game state (snake body, mine field, FEN), the guest bump heap resets per call cycle inchitti_alloc, and no guest static may hold a heap type. UI apps paint 256×192synapse::uisurfaces via the draw-op DSL (rect/line/pixel/text+board_set/board_markfor boards) with per-agentstorage_*(localStorage-shaped) state; the runtime pump (service/package_ui.rs) peeks the event queue natively and only drains through the auditedui_event_pollwhen events exist (an unpaced poll once flooded the audit log at ~1 kHz), forwards clicks/keys to the gueston_click/on_keyexports (an app consumes only keys it handles), and serves the model-ask protocol: any export may returnask:<prompt>→ one model turn over the agent's SOUL → the text back viaon_reply— the wasm builds the prompt and validates the reply, so the model only ever chooses (chess enumerates legal moves natively and the agent picks one). Manifests can claimcommand_hooks—/openroutes by extension to the owning agent's tool (media owns images/audio/video, pdf owns.pdf) and rebinds chat to that agent. Build a module withcargo build --release --target wasm32-unknown-unknownin itstools/<name>-wasm/crate and copy toagents/<name>/assets/tools.wasm(checked in;include_bytes!at boot). See the wasm-agent recipe gotchas: kerneljson_strunescapes\n;image/inflate.rsis raw RFC 1951 (strip the zlib header) and its#[test_case]tests need a shim under hostcargo test. - Agent tools in JavaScript, compiled on the machine. A package's
assets/tools.wasmneed not come from Rust:/agents new <name>scaffolds~/agents/<name>/{SOUL.md,manifest.json,tools.js}with two working tools, and/agents build <name>compilestools.jsinto that sameassets/tools.wasmon the running OS (~90 ms). The compiler is a wasm module in the image — Javy's QuickJS plugin (assets/wasm/javy-plugin.wasm, 1.3 MiB, Apache-2.0 + MIT) — driven byagent/js_rt.rs, withagent/jsmod.rswrapping the bytecode into a module. Lower-level:/js build <in.js> [-o out] [--tools a,b]and/js call <module.wasm> <tool> '<args json>'. There is deliberately no newToolBinding, nojsmanifest field and no second kind of agent — JavaScript is a source language, the artifact and the manifest are the ordinary ones, soeffect_of/origin_of/the primitive count/theredteamcensus are untouched. Seven things this path pins down:compile-srcreturns bytecode, not a module, sojsmod::emitwrites the wasm itself. It is a fixed template decoded fromjavy build -C dynamic: three types, three imports from the plugin's namespace, one function + one export per tool, and two passive data segments (bytecode, names). Each body reallocs andmemory.inits its inputs then callsinvoke;memory.inittakes a source offset, so one names segment serves every tool. The emitted module exports the same names a Rust module would, which is why nothing downstream changed.- A wrong LEB128 length still validates. So the tests execute the output
(
javascript_compiles_and_runs_on_this_machine) and validate it at 1/127/128/ 300/16384-byte bytecode lengths, rather than diffing against a golden blob. initialize-runtimereads a config JSON off fd 0. Feed it{}and rewind fd 0 before the tool's arguments, or it eats them and failsunknown field 'q', expected one of 'javy-stream-io',…— which reads like a bad argument.compile-src's result is a 3-word area[discriminant, ptr, len]. Read as two words you get a plausible pointer and QuickJS rejects it withinvalid version (0 expected=26).invokeresolves an ESM export verbatim — snake_case works. The Javy CLI's kebab→camel mapping is the CLI's convention, and this emitter bypasses the CLI.- The
ResourceLimitercapped instances at 1, and the JS path needs two in one store (engine + module). wasmi refuses the second withtried to instantiate too many instances, which reads like a problem with the module. NowLimits::with_instances, defaulted to 1 so every other guest is unchanged. - A syntax error costs the engine instance: the plugin panics inside its own
WASI shim rather than returning
compile-src's error arm, so the session is poisoned.build_moduletherefore starts a fresh session per build — a cached compiler would reject every good script after one bad one. Contract differences from a Rust tool, both stated because they surface as confusing bugs otherwise: exported functions take no arguments and their return value is dropped (args JSON in on fd 0, result JSON out on fd 1), and module top level re-runs per call, so JS globals do not persist — durable state goes through storage, and package-UI apps (whose guest statics are their state) stay Rust. A JS call costs 3-4 Mfuel before the script does anything, hencejs_rt's budgets rather thanDEFAULT_FUEL's 5 M. A JS tool reaches the same gated surface a Rust one does. The engine is our Javy plugin (tools/javy-plugin/,javy-plugin-api7.1.0, rebuilt bycargo xtask javy-plugin), which imports thechitti.host_*functions and exposes them as aChittiglobal —storageGet/Set/Remove/List,fsRead/Write/List/Exists,uiDraw,hud,http,notify,log,sha1,home,userHome,nowMs/nowUnix. Same imports, same gates, so the authority does not widen: only who can call it. Refusals throw into the script rather than returning empty, and "no value" returnsnull(localStorage's shape) becauseJSON.stringifydropsundefined, which would erase the distinction. Three more traps here: - Do not strip the plugin crate.
javy init-pluginvalidates through binaryen, which reads thetarget_featurescustom section to know which wasm features to permit; stripped, every bulk-memory instruction fails with[--enable-bulk-memory]— an error naming a flag, not the missing section. javy-plugin-api7.1.0 pairs with CLI v9.1.0. The published docs say 5.0.0; the truth is incrates/plugin/Cargo.tomlat the release tag, and a mismatch surfaces only atinit-plugin.- A JS exception arrives as a trap whose message is
wasm unreachable. The reason is the last thing the guest wrote to fd 2, soFds::last_stderrkeeps it and/js callleads with that instead ("storageSet: refused: this agent has no such capability bound"). Rebuilding the plugin changes its stamp, so everytools.wasmbuilt against the old one becomes stale — detected and reported as "rebuild it", not failed inside QuickJS. The whole loop runs on the machine (agent/local_pkg.rs):/agents new→ edit →/agents build→/agents validate→/agents install <name> --path(the same consent modal a registry package gets) →/agents test <name> --tool t --args '{…}'→/agents reload. Five things that path pins down: - A manifest's
toolsetdoes not create tools.registry::for_agentonly filters a compiled-in list, so a name with noToolDefis silently invisible and a freshly installed local agent could call none of its own tools.local_pkg::register_toolsregisters them at install viaregister_replace, deciding which names are the package's own from the module's exports — a toolset also lists borrowed tools likememory_add, and registering those would shadow the real ones. Reload deregisters the previous set first (remembered in the store, since the registry has no per-agent index), so a tool deleted from the script stops existing rather than lingering as a def over absent bytes. - A re-install grants
manifest ∩ recorded grant, never the manifest alone. The package lives in the store, which any agent with a broadFsscope can write, so re-reading its requests as authority would make editing a file an escalation.InstallRecord.granted_capabilitiesis the ceiling (invariant 5), anda_reinstall_cannot_widen_the_recorded_grantpins it. - Install records are written to the store and never read back, so
install::load_recordis new andlocal_pkg::reinstall_allruns at boot frommain.rs— without it a local agent's files survive a reboot while its role and tools quietly do not. NB the live-ISO store is memfs, so this only bites on an installed system. - Ids must survive a reboot because
/agent/<id>/holds the SOUL, assets and memory.next_agent_id()is an in-memory counter from 1 and the system roster bypasses it with fixed9000+ids, so local packages draw from a persisted counter atLOCAL_ID_BASE(20000) and a name always gets its id back. parse_manifestis forgiving because it must be (it also reads the compiled-in manifests at boot, where a hard failure would cost the machine an agent) — and that forgiveness hides real mistakes from a human editing a file: an unrecognisedkindsilently becomes a service, an unknown capabilitydomainis dropped whole, unknownrightsvanish, and an unrecognisedscopewidens to ANY, the worst reading of a typo.local_pkg::lintreports each, is shared by/agents validateand the install path, and blocks an install on errors./agents testprints the structuredToolOutcome— kind, provenance, origin — never a parse of the reply text.
Notifications (
notify.rs,/notify) — a bounded, coalescing, persisted ring: the channel by which the OS tells the human something happened while they were not looking. Three load-bearing properties. Repeats coalesce on adedup_key(a five-second job bumps a count instead of filling the ring and burying what mattered). Thesourceis stamped by the kernel from the live identity and never read from the poster's arguments — an agent that could name itselfkernelhas performed a transfer of authority wearing a label. And agents may post but not list, which removes the laundering channel (post, read back, untrusted content re-enters with its tag stripped) for one line of policy instead of a tagging path. Surfaced asStatusChip::Notifications+${notifications}— absent at zero unread, becausechip_textreturns""andui_config::expandswallows the following separator, so a quiet machine has a byte-identical status bar — plus a dropdown and aRightMode::Notificationsaction-pane tab, and a banner (notify/toast.rs+framebuffer/toast.rs).The banner reverses an earlier decision in this file, and the reasoning is worth keeping: a transient overlay was rejected on three grounds, and two of them were about a banner placed anywhere. Pinned top-right of the content rect they dissolve — nothing is typed there (the composer is at the bottom), and a banner that does not animate damages exactly twice (appear, lift) rather than once per pulse, which
Toast::needs_repaintis what enforces. The third — a transient overlay must save and restore the pixels beneath it on a single-buffered framebuffer — is real, and is solved the way the mouse cursor solves it:toast_savediscur_savedwith a different name. Anchoring to the content rect rather than the screen means all four/statusbaredges work with no match on which edge it is. A fullredrawinvalidates the saved pixels (toast_forget, called insideredrawrather than at its eight call sites, so a ninth cannot get it wrong)./notify on|mute|offis three states, not a switch, because "stop making noise at me" and "stop recording anything" are different requests and one switch answers one of them wrongly.mutekeeps the queue — which is most of its value — andoffrecords nothing at all, which is what "fully disable" means. Both persist toui.json(normalized through the parser, so a typo leaves notifications on: the safe reading of an unreadable setting is the one that still tells you things), and an empty listing underoffsays why it is empty, because "nothing is arriving" otherwise has two indistinguishable causes.The chime is a two- or three-note figure per severity, not a beep: a single tone carries no information, so success rises, error falls, and
Actionis a longer three-note figure.Infonever rings at all — a five-second scheduled job would be a metronome, and that is how an OS sound gets turned off for good. Every chime is under 400 ms, playing is best-effort, and a full audio queue drops it (the notification is already on screen; nothing waits on audio).The agent API is
host_notify(wasm) andChitti.notify(severity, title, body?)(JS). Same three rules as the tool: the source is stamped from the binding and cannot be chosen; it is write-only, so a posted notification cannot be read back (no laundering channel, for zero policy); and it shares thelog_countrate-limit budget, because the chime makes spam louder than usual.Severity::Actionis deliberately not reachable from a guest — it means "a human decision is waiting", which only the kernel's unattended-approval path is entitled to claim; a guest asking for it getsWarn.Ships with one real producer so it is not decorative —
service::supervise_tickexhausting a daemon's restart budget.Scheduled runs (
schedule/,/schedule) — a stored intent that acts later. Deliberately not five-field cron, because the wall clock here may be fiction: with no readable RTCclock::DEFAULT_UNIXputs the machine in January 2026 until/ntp. Soevery 5mis measured on the monotonic timebase and is correct on a lying clock, whileat 09:00 weekdays/on 1 03:00/in 30sare calendar and are held rather than fired whileclock::source()is untrusted — held, and reported as held by/schedule next, because "my schedule didn't run" otherwise has three indistinguishable causes on a box you cannot debug.MIN_EVERY_SECS = 5exists so an e2e test can watch a fire inside its budget.The authority model is the part to read before changing anything. A schedule is bounded by what its author could have done when it was stored, forever — the analogue of invariant 5. So: a stored human confirmation does not survive a change of action (
spec::reauthorise), or an injection turns a blessed nightly/disksinto a nightlyrm -rusing the human's own approval; provenance only ever joins worse, so editing cannot launder a tainted job; and human-vs-agent authorship is decided at the call site (shell::in_tool_call) rather than inferred from session taint, because a Telegram DM enters asUserTypedand inferring would hand a DM-authored schedule typed-human authority forever. A job authored while untrusted content was resident still runs — its inert calls are most of a daily digest — butblocks_destructive()holds for its life.No new Synapse primitive (the count stays 26): a schedule creates no effect at creation, so gating it would be
mem_fs_writein a costume. What it does add is one real gate —tools::dispatch::effect_ofclassifiesschedule addby the effect of the action being installed, soadd … command rm -rhits the destructive check while a human is still watching. Same shape as the documentedchannel sendmisclassification, found the same way.Where the work happens is the
msgchansplit, and each reason is specific.tick()runs onupkeepand only enqueues; the fire happens in the interactive loop's drain (inference is too heavy for the poll tick, andChatSession::turnbrings its own 1 MiB stack).with_busyguards the genuine tick→run→/http→upkeep→tick re-entry that would spin a non-reentrantLockedforever with interrupts off.ReadOutcome::ChannelWakebecameWakebecause without it a schedule does nothing while the prompt idles — which is most of the time, and the whole situation a scheduler exists for. Fires are at-most-once: the due time is advanced and persisted before the run, so a crash loses a run rather than repeating an irreversible one.An unattended run cannot answer a modal, so
execute_chat_tool_innerrefuses an approval-requiring call, recordsOutcome::NeedsApproval, and posts aSeverity::Actionnotification. "The OS tried to do the thing you scheduled, could not, and is asking you" is a completion of the agentic loop that neither half of this could provide alone.- Screenshot (
/screenshot,screenshot.rs) — capture to PNG in the store.image::png::encode_rgb8does per-row adaptive filtering overimage::deflate::zlib_compress(fixed-Huffman LZ77), which takes a 6.2 MB 1080p frame to tens of kilobytes;zlib_storedremains for the git object path, where "the bytes are literally in there" is worth more than a smaller.gituntil something has verified our output against libz. Every encoder test round-trips through our own inflater — an encoder verified against an independently written decoder in the same tree is a much stronger claim than one verified against its own inverse, and it immediately caught a cheap-reject probe reading one byte past the end. The capture reads throughread_phys_rgb32_row(the read mirror offill_phys, withblit_rgb32_row's native-XRGB fast path), lifts the mouse sprite first (it is composited into a single-buffered framebuffer, so a naive capture includes it and reads as an artefact in a bug report), and refuses aboveMAX_PIXELSrather than failing inside a first-fit allocator. A model-chosen capture from a non-root agent is narrowed to the surface that agent owns — the gate isin_tool_call(), notactive_agent_id()alone, because those are different questions and conflating them refused a human typing/screenshotwhile the chat happened to be homed to another agent. - Messaging channels (
msgchan/) — external inbox adapters (Telegram live; Discord/Slack/webhooks follow the same shape): a named instance + backend + access policy delivering inbound DMs into the shell agent and replies back out. Each channel turn runs on a fresh model context (channel_turnswaps KV/history out and back) so DMs can't stick to a console topic and console chat isn't polluted; transcripts still land in the session for audit. Distinct fromchannel/(cap-gated inter-agent pipes). - Cortex (
cortex/) — CPU transformer inference, architecture-dynamic like the ONNX interpreter:general.architecturein the GGUF names the hyperparameter key prefix and resolves to aFamily—QwenHybrid(Qwen3.5/3.6 DeltaNet+attention hybrid; finetunes like Ornith load via a key-shape sniff) orGemma4(sliding-window/global interleave with per-kind geometry — GQA ring-KV local layers, MQA global layers with V=K + p-RoPE freq factors — sandwich norms, GELU, √dim embed scale, logit softcap,layer_output_scale, suppress-token bias). Nothing numeric is compiled in. All mainstream GGML quants dequantize (legacy Q4_0/Q4_1/Q5_0/Q5_1/Q8_0, K-quants Q2_K–Q8_K, i-quants IQ2/IQ3/IQ4 viaiq_tables.rs— generated verbatim from ggml bytools/gen_iq_tables.py— plus F16/BF16 rows), so any unsloth file incl. UD-* dynamic mixes runs; plus PrismML's sub-2-bit packs (Q1_0binary type 41,Q2_0ternary type 42 — 128-elem blocks, one f16 scale; the Bonsai-27B builds). Fast SDOT matvecs for Q8_0/Q4_0/Q4_K/Q1_0/Q2_0 (the Q1_0 sign-expand and Q2_0 code unpack run fully in vector registers —vqtbl1qbroadcast /vzipinterleave, loads via theldq_*/ldp_*asm helpers), everything else through the generic dequant path (still SMP row-split). Batched (weight-stationary) prefill is decided per tensor, never per model (has_batched_kernel): Q8_0 ∣ Q1_0 ∣ Q2_0 always have a kernel, Q4_0 only with FEAT_I8MM, K-quants none — and a projection without one falls back to a matvec per position instead of disqualifying the whole file. The old per-model gate demanded one uniform quant type and read it fromtoken_embd.qt, which is the worst possible anchor: prefill never batchestoken_embd(a row lookup, plus one matvec for the final position on a tied output). Real GGUFs are almost never uniform —llama-quantizeupcasts selected tensors unless--pureis passed, so the file published as "Q4_0" arrives Q4_0+Q8_0+Q5_K+Q4_1 withtoken_embdat Q6_K, and that one tensor put a whole 4B on the per-token path. A fallback tensor costs far more than its share of bytes:ssm_outat Q5_K has no SDOT matvec either, so it goes through the generic dequant path — 11% of projection bytes was eating ~69% of prefill, ~18x less efficient per byte than i8mm. Hencextask/fetch-model.sh CHITTI_PURE=1|bf16, and/perf'sbatched weights: N%line. Measured on the 4B (/perf 512, 8 cores): per-token 3 pp / 1 tg → windowed at 89% batchable → pure file 23 pp / 6 tg. The shell chat loop feeds 64-token chunks throughModel::prefill(weight bytes + unpack amortized per chunk; UI pump + Ctrl+C between chunks), so a 27B's ~1.5k-token system prompt prefills in minutes, not hours. Chunk size is measured, not assumed — sizing it to the heap (128/256) was slower on a host sweep (4.06 s at 64, 4.17 s at 128, 4.22 s at 256): a bigger chunk only cuts weight traffic, and prefill is compute-bound while the wider activation tile costs cache locality. NB the paired BonsaidsparkGGUF is a drafter conditioned on the target's hidden-state taps — not a standalone model; the runnable Bonsai is the mainQ1_0/Q2_0file. Two tokenizer flavors behind one API (GPT-2 byte-BPE ∣ gemma4 raw-UTF-8 ▁-BPE with<0xXX>fallback), per-family chat format in the shell (ChatML ∣<start_of_turn>gemma turns, BOS peradd_bos). Select with-model qwen3.5-0.8b|2b|4b|9b|gemma-4-e4b|bonsai-27b| bonsai-27b-ternaryor any path (-model path/to/file.gguf— guest RAM derived from file size), or at runtime with/model load <file.gguf>(reads off any FAT/ext4 volume into DMA frames and re-homes chat on it; the status bar shows the GGUF's owngeneral.name). Zero-copy GGUF; grammar-constrained sampler; KV/recurrent cache (fixed W-slot rings on sliding layers).tools/cortexdiff/is the host-side harness (the onnxdiff pattern: mountskernel/src/cortexnatively; greedy decode in seconds;diff.pycross-checks tokenization + continuation against llama.cpp) — it generates therefcheck.rsfixtures (keyed bygeneral.name; the numpytools/ref*.pyare gone) and is the required bring-up tool for any new family/quant.cargo xtask ref-check [-arch aarch64] [-model …]runs the acceptance gate natively under HVF (minutes, vs TCG hours) and powers off via PSCI. - Synapse (
synapse/) — the capability ABI: primitive registry, GBNF-style grammar, deterministic executor, append-only audit log, taint gate. Primitives now span fs/console/spawn, channels (10–14), net listen/accept + http (15–18), and UI surfaces (19–22). The executor runs a scope gate (Gate 2.5): a granted narrow scope (an fs path glob, aNet{host,port}range) is enforced against the concrete target (scope_target+cap::scope_check) — deny-only-when-recorded, soScope::Anygrants and un-scoped tasks are unaffected.CapDomaingainedChannel/Net/Ui;synapse::uiowns the surface registry + bounded draw-op DSL (ownership-gated: an agent can only draw to its own surface). The audit log records every entry (append-only, structurally enforced + tested); its ktrace mirror coalesces identical consecutive entries into one line + a repeat count, so a polling loop can't drown the human-facing trace. NB: sessions that use net egress or UI input aren't replayable from a seed alone (the I/O is external) — the audit log records the effects; treat such a session as non-deterministic to replay. What the boundary costs is measured, not asserted (synapse::bench,/bench synapse): the gate chain is priced throughexecutor::gate_prefix, which runs the real predicates in the real order but executes no primitive and writes no audit entry, against a synthetic parked task whose table + scope ledger are granted explicitly and killed after — measuring against the shell agent would make a figure depend on what the session holds, and pricing a denied call would mean granting an agent a right to measure it.gate_prefixis a second copy of the gate order, sogate_prefix_agrees_with_executepins it to the real chain: a new gate that isn't added to both fails that test. Three benchmark traps, each of which printed a plausible wrong number first: a result-discarded pure call is deleted by the optimizer (the FNV row read 0 ns over 16.7M iterations — everything timed goes throughblack_box, and a zero-ms batch is flagged SUSPECT rather than printed as 0); cumulative prefixes must share one batch size after a warm-up, or the first batch pays to grow the heap and the curve comes out decreasing (making every marginal cost an artifact); andcycle_countis a constant-rate tick, not a CPU cycle (~24 MHzCNTVCT_EL0on Apple silicon), so the rate is printed beside every figure. A non-positive marginal cost prints "below noise floor" — a saturating subtraction is not evidence that a gate is free. The design write-up lives in a separate repository and is not part of this tree. The taint policy is enforced at EIGHT sites, not one, and/redteam(security::redteam) is the census. The Synapse executor gates destructive primitives; the tool router separately gates destructive shell commands,/http, MCPtools/call, agent-memory mutations, downloads, browser navigation, nestedrun_shell_command, and the web tools — so a new tool binding that forgets its check is a hole by omission, and the corpus carries one attack per site precisely so that shows up as a permitted attack instead of as silence. It runs through the realRouter, so the justification is computed byRouter::justificationoverSession::resident_max_taintexactly as in an agent turn; a laundering bug on the way to the gate would surface as aNOT TAINTEDrow. Three rules this harness must keep. It assumes the injection persuaded the model (the payload text is never read by a gate) — that is the worst case and it is what makes the numbers deterministic and model-independent; it measures the authorization boundary, not the planner. A permitted attack really executes under the baselines, so every target is a sandbox path or the loopback discard port, pinned bycorpus_targets_are_sandboxed_and_offline— this is why the destructive-shell attack isrmon a sandbox file and neverinstall, and why the victim runs as a throwaway agent identity (REDTEAM_AGENT): the memory-poison attack, if permitted, writes durable memory that re-enters the system prompt, so running it as the live orchestrator would poison the real shell agent as a side effect of measuring whether that was possible. And a non-policy error counts as permitted — a refused loopback connection is not a defence. The counterpart measurement is the utility suite: benign tasks over the same primitives, whose false-refusal rate (a destructive step refused when the untrusted content never named its target) is the number that decides whether the policy is usable, and it is reported next to the attack rate rather than separately, because a defence is only interesting if it is good on both axes. - Microkernel — tasks + context switch, cooperative + timer-preemptive scheduler, unforgeable capabilities, IPC, SMP, frame allocator + heap, MMU.
UI — a tmux-style split-pane framebuffer compositor in Geist Mono, living in
kernel/src/framebuffer/:mod.rsowns the data model (every type, constant and static — a child module sees its parent's private items, so aScreenfield is reachable from every painter with no visibility annotations) and one submodule owns each surface (paint/text/pane/layout/tabs/focus/status/menu/clock/modal/composer/views/surface/select/cursor/console/colors— the map is a table at the top ofmod.rs). Each is re-exported, so everycrate::framebuffer::…path is flat regardless of which file an item is in; put a new painter in the module it belongs to rather than growing one file back to the 8.7k lines this was. The shell (chat) pane is fixed in the primary band; the other band is a resizable grid of 1–8 action panes (/pane grid <cols> <rows>, or/pane max <2-9>for a balanced shape —panes_layout::grid_for_count). Every divider drags: the shell|band split (/pane split <10-90>) and each grid column/row gap, and a grid drag is per-gap — it re-splits only the two tracks it separates, so panes you weren't touching keep their exact pixel sizes. Either band can go fullscreen (Ctrl+F, or/pane full—LayoutCfg.fullscreen, which maximises the focused action pane, not pane 0). Shape,chat_pct, and the permille track weights persist to/configs/core/panes.jsonand reload at boot (legacynum_action_panesis still read as an action-pane count). The geometry is pure and unit-tested inkernel/src/panes_layout.rsin two steps —split_band(chat | band, one gap) thenlayout_grid(cols × rowscells from track weights) — withband_divider_pct/resize_tracksas their exact inverses, asserted by round-trip tests; weights are permille so a saved layout restores byte-identically andGridSpec::sanitizedrepairs a hand-edited file rather than producing a zero-size pane (MIN_TRACK_PXbounds every drag). Panes are addressed row-major (index = row * cols + col). Tabs move between action panes by drag-and-drop — press a tab label, drag past a ~4 px threshold (the target pane highlights), drop on a tab bar to insert there or on a body to append; a drop on the shell pane or outside the band cancels, so the shell can never acquire an action tab. The insert-index math ispanes_layout::insert_index(the same-pane removal shift must be applied before the clamp, or a drop-at-the-end lands second-to-last — a test pins every from/to slot pair). Withmax_panes == 2the band still collapses when its last tab closes, so the default boot UI is byte-identical to the classic two-pane look; withmax_panes > 2empty panes stay visible as drop targets. Note three traps this cost: a pane's frame carries its selection state, so focusing one must repaint the pane losing focus too, andfocus_action_columnmust repaint itself — it has already moved focus to the action side, so a followingfocus_set(true)sees no flip and draws nothing (which made clicking a pane change the selection invisibly). Opening a view must never move keyboard focus to the action pane (open_view_slot): the user typed that command at the composer and is still typing there, which is exactly whyaction_focusedleaves focus on the chat for every mode but the editor — settingfocus_actionon open sent the next command to the pane instead of the prompt, indistinguishable from the shell freezing. Focus moves only on an explicit act (click,/pane focus, Ctrl+Tab). And the per-view painters (/top, the audio/video/browser HUDs, the editor,surface_dims_px) resolve their target pane by which pane holds their tab (Screen::mode_dims), never the focused one — otherwise a/topon pane 3 paints into pane 1's rectangle as soon as you click elsewhere. The compositor pairs the chat pane + on-demand tabbed "action" panes: opening the ktrace stream, the/topdashboard, a vim-like editor, an image viewer (/open .png|.jpg), or the audio player (/open .wav|.mp3) each adds a tab on the focused action pane (already-open views focus their existing pane + tab instead of reopening); a tab bar in each pane header switches them (Ctrl+Tab / Shift+Tab / click), and every tab keeps its process alive when you switch away — the audio player keeps playing (pumped chunk-by-chunk fromui_tick, not a blocking loop), ktrace keeps streaming, the editor keeps its buffer. The editor is non-blocking: its state lives in a static andread_lineroutes bytes to it while its tab is focused. Both media tabs take key controls while the action pane is focused (Ctrl+Tab / click — same gating as pane scroll, so typing at the prompt is never intercepted): the image viewer does+/-zoom,r/lrotate, arrows pan,0reset (retaining the source, capped to ~4 MP, and re-rendering via the pureimage::render_view/rotate90); the audio player does space play/pause,←/→seek ±5 s,↑/↓±30 s,0/Home restart (state on theAudioPlayerstatic, seek just moves the PCM cursor, pause holds it while the device drains its queued chunk to silence). The image viewer decodes in-kernel —image/is a pure no_std PNG+DEFLATE and baseline-JPEG decoder set, unit-tested against real fixture files (plusrotate90/render_viewtransform tests) — then presents box-downscaled + letterboxed), a boot splash + status-bar Synapse-C brand mark, a live clock, a blinking caret, Enter submits a fully-typed command — the suggestion menu stays open while the typed token still matches an entry, so a command name typed in full kept its own entry highlighted and Enter "accepted" it, appended a space, and swallowed the keystroke; every later line was then one out of step, so a command silently did not run and it read as a frozen shell.suggest_would_ completegates the Enter path on whether accepting would change anything beyond the trailing separator (Tab is untouched — completing is its job). This is what made the command after/todos opennever execute, an e2e gap that sat unexplained for a while; thepane_gridscenario now asserts it. Path-taking commands (/ls /cat /open /mkdir /rm /cp /mv /touch /glob /grep—suggest::PATH_COMMANDS) additionally get path-argument autosuggest + completion: as you type the argument, the popup lists the parent directory's store/mount entries (suggest::path_itemsovervfs::readdir), dirs first with a trailing/, and Tab drills one level at a time. The same Enter gate is extended so a complete path argument submits the command rather than completing or drilling (the case that swallowed/ls /tmp_e2einto/ls /tmp_e2e/); Tab remains the drill key.The shell has a working directory, and every path-taking command resolves through ONE function —
shell::resolve_path. The shell agent starts in the ChittiOS user home (agent::home::USER_HOME,/home/chitti— the~); `/cd<dir>` moves it (bare `/cd` and `/cd ~` → home; `.` stays, `/` is the store root) and `/pwd` prints the live value (`shell::shell_cwd`/`set_shell_cwd`). `resolve_path(p)` implements the Linux rule once: `/abs` stays absolute, `~/x` → home, anything else → `<pwd>/<x>`, with `.`/`..`/`//` collapsed (`vpath::normalize`). It is applied at **every** fs-command call site (`ls`/`cat`/`glob`/`grep`/`touch`/`mkdir`/ `cp`/`mv`/`rm`/`open`/`edit`) and to the path-completion popup's readdir — a bare `/ls` lists the **pwd** (not the store root), `cat hello.txt` and `~/file` work, and completion keeps the typed form (`re<TAB>` → `rel.txt`, `~/h<TAB>` → `~/homedoc.md`, `/co<TAB>` stays absolute). **Never re-implement relative resolution at a call site** — route through `resolve_path`, and pass the shell's cwd to command-hook agents (e.g. the git agent gets `{"cwd":…}` so `git clone`'s default folder is the pwd, like the git CLI). mouse cursor + click, **mouse text selection in the chat pane** (drag-to-copy → clipboard, paste with Ctrl+V; absolute-indexed over scrollback via `textsel`, like the editor's drag-select), a **host clipboard bridge** (`clipboard`: an in-OS copy emits an **OSC 52** escape so a terminal-attached host copies it to the macOS/Linux clipboard; a host paste arrives as a **bracketed-paste** `ESC[200~…ESC[201~` block the line editor captures — works the same on QEMU and VBox over the serial console, no guest-additions driver; `/clip` shows/sets it), **key auto-repeat** (`keyrepeat`: software typematic in `xhci` — USB HID boot keyboards report only press edges — plus an accelerating streak amplifier: held Backspace/arrows erase/scroll 2/4/8 steps per repeat in the shell and editor), **syntax highlighting** (`highlight`: JSON/Markdown/Rust/Python/C/ JS/TOML/sh lexers colour the editor per-cell, `/cat` output, and the chat's streamed markdown — fence-tagged code blocks are lexed per language without breaking token streaming), ANSI-coloured agent output, a `/`-command shell, and an on-disk UI config (`/configs/core/ui.json`, `shortcuts.json`). **The status bar sits on any edge** — `/statusbar top|bottom|left|right`, the `status_pos` key in `ui.json`, and the settings agent's `statusbar` tool; applies instantly and persists. The geometry is one pure function, `panes_layout::status_split`, which carves the bar off its edge and returns the **content rect**; `Screen` stores that rect and *every* pane calculation works inside it (`build`, `paint_gutters`, `band_capacity`, and the `band_divider_pct` drag inverse) rather than `0..width`/`0..height`. Keep it that way — a layout site that reaches for the full desktop is correct only for `Bottom`, where the content origin is `(0, 0)` and the split is the identity, so the bug hides until someone moves the bar. `left`/`right` make it a **column**: text cannot run across 16 cells, so `status_segments` splits each template on the runs of 2+ spaces the author already used to group fields, `wrap_segment` wraps a long one onto extra rows (ellipsizing `${datetime} ${tz}` cut off the *time* — the part anyone reads), and the two stacks grow towards each other from the brand mark and the far edge, stopping when they would meet. The column width is a **fixed** `STATUS_V_COLS`, never fitted to the longest segment: the fields hold live values, so a fitted width would relayout every pane — reflowing scrollback — each time the clock ticked a digit. **System icons are Font Awesome 7 Free Solid** — not emoji, not hand-drawn rects for chrome. The face is `assets/fonts/FontAwesome7Free-Solid-900.otf` (SIL OFL / icons CC BY 4.0; see [THIRDPARTY-LICENSES.md](THIRDPARTY-LICENSES.md)), registered **first** in the TTF fallback chain at boot (`font_ttf::register_bundled_fallbacks`, name `FA_FALLBACK_NAME` = `"Font Awesome 7 Free Solid"`) so Private-Use-Area scalars resolve before Noto/emoji/CJK scans. Codepoints and helpers live in [`kernel/src/icons.rs`](kernel/src/icons.rs) (`icons::fa::*`, `is_icon`, `close_mark`, `for_agent`, `for_command` / `for_command_category`, `chess_piece`, `cursor_glyph`, status helpers); package-UI wasm guests cannot import the kernel crate, so they mirror the same literals in [`tools/apps-wasm/src/fa.rs`](tools/apps-wasm/src/fa.rs) and must stay in lockstep when a codepoint is added. **Where FA is used today:** status-bar `${kbd}` / `${mouse}` / `${net}` (active input is a body-size middle-dot, never a full FA circle — that ballooned at icon scale); OS mouse cursors (`arrow-pointer` / `hand-pointer` / `i-cursor` / `hourglass`, rasterized to fill+outline sprites with theme custom sprites still winning); pane and modal **close** (`xmark`, painted with `theme.accent` so `/theme` recolours it); action **tab labels** (ktrace/editor/top/todos/audio/image/video/browser + package-UI agent names via `for_agent`); `/help` and `/agents` browsers (category headers + command/agent rows); todos status marks; chess pieces on the board (`chess-pawn`…`chess-king` via `synapse::ui` text ops); settings / files / notes / activity package-UI chrome. **Sizing rules that bit us:** (1) size FA by **line height**, not `min(cw, ch)` — mono cells are tall and narrow, and width-first sizing made agent-list and close marks look like dots; (2) `blit_glyph` / `draw_str` give FA a **square cell of body line height** and advance by that width; (3) fontdue's `px` is an em size, not a max bitmap edge — solids often rasterize larger, so `build_ui_glyph` measures and **shrink-to-fits** with a little air so AA edges aren't clipped (status bar icons used to lose their tops). Only Free Solid is vendored (no Brands pack). The brand — logo, the terracotta `#cc785c` / warm-ink / cream palette (fully re-themable from `ui.json`), and typography — is specified in [DESIGN.md](DESIGN.md); honour it for any UI change. **Themes** (`theme.rs`, `/theme`) are presets layered over `ui.json` (still the single source of truth for the live look): bundled JSON in `assets/themes/*.json` (`dark`/`light`/`solarized-dark`/`nord`/`dracula`/`ubuntu`), installable to `/configs/themes/`, each carrying the chrome palette, `highlight` **syntax** colours, **cursor** fill/outline + optional sprite bitmaps (else FA default cursors), `font`+scale, a **wallpaper** (`""` ∣ `gradient:#a,#b` ∣ a store-image path, cover-scaled by `image::cover`, `/theme wallpaper` fetches a URL) and **opacity** (0–255). **NEW UI SURFACES MUST RESPECT THE THEME BACKGROUND:** with a translucent wallpaper (opacity < 255) the desktop must show behind *every* surface, so paint pane/region backgrounds through `Screen::paint_surface` and text-cell backgrounds through `fill_cell_bg` — **never a raw `fill_rect` of the bg colour** — and let glyphs blend via `blit_glyph`→`bg_at`. Both fast-path to `fill_rect` when there is no wallpaper / opacity == 255, so the default look is byte-identical (no regression). A theme switch recolours existing scrollback to the new `default_fg` (`Pane::recolor_default_fg`, called from `adopt`). The **only** exception is self-contained app content blitted as its own RGB buffer via `present_surface` — the browser, wasm-UI apps/games, the image/video viewers — which stays opaque. NB: the scheduler is cooperative, so **any long or blocking operation must pump the UI itself** — call `shell::upkeep()` (blink + status + mouse + `net::poll`) inside its loop, exactly as the per-token inference loops, the ONNX per-node loop, and the sliced FAT/ext4 readers do; loops that consume their own mouse events (modals, the editor) use `shell::status_tick()` instead. A tight compute loop that never yields freezes the clock, mouse, and net stack until it returns. Any new UI surface or blocking command must keep this upkeep running. The chat pane keeps a 2000-line scrollback (PgUp/PgDn; /clear wipes it); Shift+Tab / Ctrl+Tab / clicking switches pane focus.- AGX GPU (
agx/) — the Apple-Silicon GPU coprocessor is booted to RUNNING on a real M2 (t8112, viacargo xtask m1n1; the foundation for GPU compute offload ofcortex'smatvec_qw/batched_proj— the compute path itself is the next milestone, not done yet)./agx updrives the full bring-up: PMGRgfxpower-on + SGX liveness poke →cpu_start→ GFXHandoff PPL handshake (writeMAGIC_AP, wait the firmware'sMAGIC_FW— the shared- memory memory-manager handshake, done before the RTKit handshake per drm/asahi order) + UAT ctx-0 TTBRs under the handoff lock → RTKit HELLO v-negotiate → HELLO_ACK → EPMAP → START_EP →AP_PWR_STATE=ON→ service the crashlog BUFFER_REQUEST (mapped into the shared TTBR1 kernel range, not per-context TTBR0 — the firmware's boot context only sees TTBR1) → both IOP+AP power reach ON = RUNNING. The UAT is real ARMv8 16 KiB paging with the G14 geometry — bit 39 TTBR select (IAS=39), NOT bit 47 (agx/uat.rs, pure + unit-tested); getting that wrong makes the firmware's page-table walk miss our PTEs (the buffer is then unreachable and it stalls silently). The pure wire protocol (agx/proto.rs) + UAT encoder (agx/uat.rs) are arch-neutral, unit-tested undercargo xtask test(arch::aarch64is cfg-gated out of the x86 test build, so pure logic still belongs outside it if it is to be covered on both legs — but-arch aarch64does now compile and run tests placed inside it); the ASC-mailbox MMIO (agx/asc.rs, single-ldr x/str xFIFO +dsb/dmb), GFXHandoff (agx/handoff.rs, Dekker lock + cache-maintained shared mem), and discovery/PMGR/orchestration (agx/hw.rs) are aarch64-only. Gated onis_apple()+ achitti.agxbootarg (passchitti.usb chitti.agxtogether; bare boot only, never under the m1n1 hv — same rationale aschitti.usb); a clean no-op on QEMU/VBox/other SoC./agx statusdumps bases/endpoints/power; every wait is bounded + pumpsupkeep()/poll_interrupt()and answers Ctrl+C. Ported from m1n1src/{asc,rtkit,pmgr}.c+proxyclient/m1n1/{hw/uat.py,fw/agx/*}and drm/asahigpu.rs. Two hard-won fixes were decisive: UAT geometry = bit 39 (G14/t8112), and RTKit shared buffers belong in TTBR1 (shared across contexts), not TTBR0 (per-context, not active in the firmware's boot context). Next: app endpoints 0x20/0x21,initdata(perf/power tables + channel rings), the firmware command ring, then a GEMM microkernel intocortex. Commands compose —
|,|&,;,&&,||,>,>>(shell/pipeline.rsparser + runner,shell/status.rsexit status;/help pipeline). Available at the prompt and to agents throughrun_shell_command, which the system prompt advertises.An agent-reachable pipeline is only safe because
effect_ofreads every stage.tools::shell_cmd::stagesenumerates them and theRunShellCommandarm takes the worst — otherwisels / | rm /xclassifies by thelsand the destructive stage runs behind a harmless first token. Exactly the smuggling shapechannel sendandschedule addalready had to learn, and the reason this could not be turned on until the classification looked past the first token.security::redteamcarriespipeline-smuggled-rmfor it, and an unreadable line isEffect::BOTH, never assumed harmless. The agent entry point also setsenter_tool_callitself, because the runner callsdispatch_systemdirectly rather than throughrun_tool_command— without it the stages would run within_tool_callat zero, indistinguishable from a human at the console, which is a privilege escalation dressed as a refactor. Background jobs refuse a pipeline outright:tools::bgstores one(name, args)pair and would replay only the first stage.The parser lives ABOVE
dispatch_system, and that is the security property, not a filing decision. Scheduled fires, package-UI apps, sub-agents and theToolBinding::Shellexecutor all calldispatch_systemdirectly; parsing inside it would hand every one of them pipe syntax by accident and makeeffect_ofclassify a whole pipeline by its first stage. Above it,/passwdand/lockstay unreachable by construction — the rule the human-only section states — and a stage naming one is refused at the parse.has_operatoris the gate: a line with no unquoted operator takes exactly the path it took before.stdout/stderr needed no change to any command. There is no
serial_eprintln!here, but commands already printname> …status lines and unprefixed data lines, and a pipeline knows each stage's name — so"{name}> "is a precise classifier rather than a heuristic. That convention is now load-bearing: a command that emits data lines prefixedname>would have them silently swallowed as diagnostics. None do; if one ever must, give that command an explicit diagnostic macro rather than rewriting every call site.Four things that cost a debugging cycle each:
serial::CAPTUREhad to become a stack first, and that was a live bug on its own:bg::pumpcallsrun_tool_commandfrom insideupkeep()(which long-running commands call), so captures nest — and a singleOption<String>meant the inner call threw the outer buffer away and then took it, so an agent got""for a command that ran fine. Text goes to the innermost sink only; appending to all of them contaminates an outer command's result with an unrelated job's output.Teewrites through to the console (whatrun_tool_commandwants),Redirectdoes not (what a pipeline stage needs).>is not a separator, andhas_operatormissed it. It binds inside a stage rather than between stages, so checking only the pipeline separators made/head -n 3 f > outskip the composition path entirely —/headthen sawf > outas its argument and said "only one path at a time".- Colour codes must not leave a stage.
/catand/headsyntax-highlight and those escapes are in the capture verbatim, so a downstream/grepmatched against text with colour codes in it and failed for no visible reason. Data leaving a stage is stripped; data going to the console is not, so the last stage keeps its highlighting. - Piped input is offered, never injected. Commands take a path, not
stdin, so appending upstream output to the downstream argument would make
/ls | /grep foopass a directory listing as grep's path. A stage reads the pipe by naming-or omitting its path (head,tail,pbcopy,grep); any other stage ignores it and reports the byte count it ignored, because silently dropping the first stage's work looks exactly like nothing having happened.
Exit status is a cell handlers set on their error paths, 127 for an unknown command. The dangerous part is that an unconverted handler always reports success, so
status::REPORTS_STATUSenumerates the converted set, a test pins that every name in it is real, and&&/||after anything outside it warns once rather than implying a check that is not happening. Grow that list deliberately: add thefail()calls, then the name. Redirection writes through the samepath_on_mount→ VFS / else store split every other write command makes — routing a store path atvfs::writegetsNotMounted, which on a dev boot is every path.Host integration — a shared folder and a shared clipboard. Copying files and text between the host and the guest, over three channels with genuinely different reach. All new virtio devices go through one shared layer (
drivers/virtio/:layout.rsis the pure split-ring arithmetic,queue.rsthe DMA-backed queue,transport.rsone trait over virtio-mmio v1/v2 and modern virtio-pci) — because the aarch64-kerneldev loop has only mmio (no ACPI, so no ECAM, so PCI discovery finds nothing) while x86 has only PCI, and a device bound on one arch and not the other is exactly the divergence the dual-arch rule forbids. The ring math lives outsidearch/aarch64/specifically so the test build compiles it. Nothing existing was migrated onto it: rewriting seven working drivers would risk them all for no functional gain./hostis a real host folder (make run SHARE=<dir>,CHITTI_SHARE) over virtio-9p —drivers/virtio_9p.rsplusfs/ninep/(wire codec, then a client tested against an in-memory 9P server, which is where the fid leaks and chunking bugs actually surface)./ls /cat /cp /mkdir /rmall work on it, both directions, verified byte-exact on a real boot and by thehost_foldere2e scenario, which asserts on the host filesystem after the guest writes — an in-guest cache would satisfy anything weaker.It is the first filesystem here with no block device under it. The mount table is otherwise
disk+start_lba+sectorsand every VFS operation resolves a mount then callsprobe_disk_nth, soFsType::Hostis dispatched immediately before that in each of read/write/mkdir/unlink/stat/ readdir/exists; itsdiskisusize::MAXso a path that did reach the block layer fails loudly instead of quietly working on the boot disk. The session is taken out of its lock rather than held across I/O (a whole-file read is many round trips andLocked::withruns with interrupts disabled), and the device wait usespoll_interrupt()and neverupkeep()— the rule the block drivers document, since this runs from inside filesystem calls reachable from the UI pump.Traps the 9P tests pin, all silent when wrong:
sizecounts itself; a shortRwalkis a success reply (fewer qids than names means the last component does not exist — check only the message type and you hold the parent and report it as the child); readdir resumes from the last entry's own opaque cookie, not a byte count; a name too long for the 16-bit length is refused, never truncated, because a truncated name is a valid name for a different file; and the server may only ever lowermsize.The clipboard has two routes, and which one reaches the host depends on the host.
clipboard/keeps the existing OSC-52 over serial bridge (needs the console attached to a terminal) and adds the graphical-window one:clipboard/vdagent.rs(pure SPICE agent framing) overdrivers/virtio_serial.rs, i.e. what-chardev qemu-vdagent,clipboard=onconnects to. Confirmed by QEMU's own vdagent trace parsing our announcement and our grab (cap clipboard,cap clipboard-by-demand,grab_selection selection clipboard,grab_type type text).On a macOS host this does not reach the Mac pasteboard, and
/clipsays so rather than implying success. QEMU bridges its internal clipboard to a real one only through a display backend that registers a clipboard peer —gtkanddbusdo,cocoadoes not — so under the default-display cocoathe link is live and ends inside QEMU. Use OSC-52 over serial there, or VirtualBox.Two protocol decisions carry the risk. We announce no capability that adds a conditional field: four clipboard messages carry an optional 4-byte selection prefix and GRAB carries a second one for the grab serial, and QEMU decides whether they are present from our announcement — claim either without encoding it and every later field shifts by four bytes, so a grab for UTF-8 text reads as a grab for nothing.
CLIPBOARD_BY_DEMANDis required (QEMU'shave_clipboard()checks it; without it the clipboard is silently inert while the link looks healthy). And the two framings do not nest one to one — a chunk caps at 1024 bytes while a message may be megabytes and theVDAgentMessageheader is only in the first chunk, so treating a chunk as a message works until the first paste over ~1 KB.virtio-serial itself: queue numbering is not sequential per port (port 0 owns 0/1, the control pair is 2/3, port
i>=1owns2i+2/2i+3— the obvious "port 1 is 2/3" lands on the control channel), a port is unwritable until a four-step control handshake completes (a write before it is dropped in silence), and the port is found by name because QEMU picks the number. Queues must be configured beforeDRIVER_OKbut the port number is only learned after, so several ports are prepared up front.VirtualBox works: VMMDev + HGCM +
VBoxSharedClipboard(drivers/vbox/{mod,hgcm,clipboard}.rs,/vbox,/vbox up,/vbox diag). Verified on a real VirtualBox-ARM 7.2.12 guest — the host version it reports matchesVBoxManage --versionexactly, and the service assigns a client id. Shared folders are still not implemented. Probing only ever reads; the first writes are behind/vbox up, gated exactly as/wifi upis.Seven bugs stood between "the code looks right" and "the wire carries a message", and not one was findable without the VM. They are listed because every one is a class, not an instance:
- An undecoded PCI address reads all-ones — and so does a device
answering "unimplemented register". They are byte-identical from the
guest.
COMMANDhad memory decoding off (firmware leaves it off for a device no driver claimed), so nothing decoded and every write vanished; a probe built on the all-ones read called that "the device answered" for four iterations. Any probe that infers presence from all-ones is not a probe — read the COMMAND register and the BARs instead. - A
nomembarrier does not order the compiler.barrier()isasm!("dsb sy", options(nomem, …)), so the optimiser may hoist a flag load out of a poll loop and spin forever on a register copy. Every word the host writes is readread_volatile. Adsborders the CPU; only volatile orders the optimiser — and the failure looks exactly like a device that never answers. - The DONE flag is HGCM's contract, not
rc. The host writesVINF_HGCM_ASYNC_EXECUTEbefore the handler and then setsNO_WRITE_OUT, so gating onrcafter the doorbell reports a normal in-flight call as "never processed". VMMDevRequestHeader.versionisVMMDEV_REQUEST_HEADER_VERSION(0x10001), notVMMDEV_VERSION(0x10004) — which is the interface version and belongs inVBoxGuestInfo.interfaceVersion. On a mismatch the handlerreturns without writingrc: no error, nothing.- Every request declares a size its handler asserts exactly.
GetHostVersionis 24+16; declaring 24+12 is refused outright. Its first two fields areu16s, so reading threeu32s yieldsmajor | minor << 16— a plausible number, not an error. - Nothing ordered the request against the doorbell. Normal cacheable
stores can still be in flight when the Device store lands, so the host
reads a zeroed header and bails silently. Every virtio driver here
dsbs before its doorbell; this one did not. - aarch64 puts the heap at the top of RAM, so on a >4 GiB guest every
alloc_dmais out of reach of a register that takes a 32-bit address. The request page is.bss(loaded low, and VA == PA here).
Seeding
rcwith-1made this worse, because-1isVERR_GENERAL_FAILURE: "the host rejected this" and "the host never saw this" printed identically. The sentinel is now far outside the range VBox statuses use./vbox diagis the lesson institutionalised — the/wifi diagpattern of one boot telling you which of several indistinguishable causes you have, rather than one guess per iteration on hardware you cannot drive.Also: which window the register lives in is a property of the VM, not the arch (BAR0 is I/O space, BAR3 is MMIO with the same register offsets, and
VMMDev.cppcreates BAR3 only underif (pThis->fMmioReq)), so both are probed and an ARM guest without it is reported unreachable — a different fact from "no device".- An undecoded PCI address reads all-ones — and so does a device
answering "unimplemented register". They are byte-identical from the
guest.
- Storage — virtio/NVMe/AHCI block devices, GPT/MBR/FAT/ext4/exFAT
detection, ext4 (the default filesystem) + FAT + exFAT
(
block/exfat_rw: full read/write — format, create/replace/unlink/mkdir; names are ASCII-only on write, full UTF-16 on read; allocation tracks the FAT and the allocation bitmap, the exFAT analogue of "write every FAT copy"),/install(self-hosting install to a disk; detects an existing Chitti GPT and updates in place, preserving the data partition — destructive actions confirm via the permission modal), durable agent state on ext4. A fresh install carries the live store onto the new data partition rather than formatting it empty (install::plan_carry+format_data_with_carry): installing is something you do after setting a machine up, so an empty volume threw away the theme, the login password, the shell history, saved sessions and every config of the system you were installing from — which is what "/install overwrote my configs" turns out to mean. Two things make it work and are easy to get wrong.Ext4Storekeeps synapse keys as flat root-level files with/percent-encoded, so the seed must be written throughkey_encode— the ext4 writer has no directory support at all. And the migration must holdsynapse::fs::CredentialAccessfor the whole walk:listfilters the login record out andreadrefuses it, so the obvious implementation copies everything except the password and hands you a machine you cannot log into, silently./samples/**is deliberately left behind (boot re-seeds it), the carry is bounded byCARRY_BUDGETbecause every file is held in RAM at once, and anything dropped is named rather than counted. Every disk is enumerated, across controllers and ports:ahci::probe_nthindexes AHCI disks — each HBA on the bus × each port that is implemented and populated (Ahci::present_countcounts without allocating, so skipping past a disk doesn't bring a port up and leak its DMA;bringup_nththen takes the one the index names). Ports are sparse on real hardware — a drive on port 3 with 0-2 empty is normal — and only taking the first controller's first present port made every other disk invisible. Exercise the real-hardware storage paths in QEMU withCHITTI_DISK_IF=ahci|nvme|virtio-blk cargo xtask run -arch x86_64. Installing next to an existing OS. Plain/installstill writes a fresh GPT and erases the disk — that is the whole-disk path. Two non-destructive commands sit alongside it:/install plan(read-only; reports the partition table, free extents, and either a plan or why not) and/install alongside(x86; adds\EFI\BOOT\BOOTX64.EFIto the ESP already on the disk, renaming any existing loader toBOOTX64.CHBas a backup, touching no partition table and no partition). Planning isgpt::{free_extents, plan_alongside}— gaps computed with a high-water mark so an overlapping or contained entry can never make the inside of a live partition look free, and the existing ESP is shared, never reformatted, since a PC has one and rewriting it removes the Windows boot manager. The writer isblock::espover the pureblock::fat32layer, and the backup is a directory-entry rename so the displaced loader keeps its original cluster chain — preserved byte-for-byte, no copy, no half-written window; a pre-existing backup is never overwritten because that one is the true original. Write order is allocate → payload → FAT (to every copy, or chkdsk calls the volume corrupt and Windows may "repair" it back to the stale copy, undoing the install) → directory entry last. Verified by 6 tests against a real FAT32 volume on aRamDisk; one of them caught the install overwriting Windows' loader because the fixture had left its cluster marked free, which is the reminder that the FAT's allocation marks are the only thing protecting existing data. Still absent: no ChittiOS data partition is created byalongside, and NVRAM is untouched, so firmware boot order may need changing by hand. NVMe enumerates namespaces via the IDENTIFY CNS=2 active list, never "walk NSIDs until empty" — NSIDs are sparse on VirtualBox (port→NSID; an empty port 0 = inactive NSID 1, exactly what a VM looks like after its install medium is detached); thenvme: N active namespace(s)ktrace is the first check for "controller up but no disks". Relatedly, the aarch64 identity map types mixed RAM/MMIO GiB blocks at 2 MiB L2 granularity from the real RAM extents the stub passes in boot-info (mm/ramlayout.rs, pure + tested): VBox puts the model tail, GOP framebuffer and PCIe ECAM in one GiB block, and a whole-block Device retype alignment-faults NEON loads (scalar reads still work — "boots fine, dies in the matvec" is the signature). - Networking (
net/) — a full TCP/IP stack on smoltcp (vendored in-tree, 0BSD — see THIRDPARTY-LICENSES.md): DHCPv4, static IP, DNS, ICMP (/ping), TCP/UDP, plus loopback (127.0.0.0/8+ the namelocalhost) so an in-OS client can reach an in-OS listener. Loopback is a second smoltcp interface (Ethernet-mediumphy::Loopback,127.0.0.1/8) with its own socket set, polled alongside the NIC interface — NOT the same set: sharing one set lets the loopback interface's egress steal/drop the NIC sockets' segments. ATcpHandletags which set a socket lives in; a connect to a127/8address opens its socket in the loopback set via that interface's context. A vendored RFC-1122 guard in smoltcproute()keeps the NIC from ever emitting loopback traffic on the wire. NIC drivers behind oneNetDevicefacade — virtio-net over virtio-mmio (aarch64 QEMU) and over PCI, plus the PCI Ethernet families — discovered the same way on both arches. A PCI NIC is claimed by vendor+device ID, never by vendor alone (net/nic_ids.rs, pure + unit-tested): all Intel Ethernet reports8086/class02:00:00, but the families are register-incompatible — legacy e1000 (82540-82547) and e1000e (82571…I217/I218/I219, the NIC in most business laptops) keep the rings atRDBAL 0x2800/TDBAL 0x3800and sharenet/e1000.rs, while igb (82575-I350) and igc (I225/I226) moved them to0xC000/0xE000with advanced descriptors and neednet/igb.rs. Driving an I210 through the legacy path configures reserved space: it links and never receives a frame — and having claimed the one NIC slot, a second working card is never tried. Sonet::pci::probewalks every Ethernet function, skips the ones with no driver (logging each), and dispatches by table; unknown Intel IDs fall back to e1000e (the only open-ended family — Intel adds I219 IDs every PCH generation) with the ID ktraced as a guess. Realtek RTL8168/8111/8125 — the commonest consumer NIC — isnet/r8169.rs: descriptor-owned rings (DescOwnin the descriptor, no tail register; kick viaTxPoll), unverified on hardware (QEMU models no r8169-family part, onlyrtl8139, which is recognised but deliberately not implemented — no Windows-era machine has one). Test the dispatch against every family QEMU can emulate withCHITTI_NIC=e1000|e1000e|igb|rtl8139|virtio-net-pci cargo xtask run -arch x86_64(thenic_dispatche2e scenario asserts the chosen driver matches the emulated device). USB Ethernet exists now (net/usb_eth.rsover the xHCI bulk transport): CDC-ECM only, chosen because it is the one real standard of the three shapes and puts one frame per transfer with no framing header, so the transferred length is the frame length. ASIX and Realtek dongles are recognised and then refused with a log — they need per-chip register setup and packet headers, and treating their framed packets as raw would hand smoltcp garbage. CDC-ECM is matched by interface class, not an id list (it is a standard, so a list would guarantee gaps). Tried last inautodetect, after virtio and PCI, so a built-in NIC always wins. Bulk transport is inxhci.rs:configure_bulk+bulk_arm_in/bulk_take_in/bulk_send; note the delivered length isrequested - residual(a transfer event's low 24 bits are the untransferred count). Still missing for real machines: Broadcomtg3, Atheros/Killeralx, Aquantia. - WPA2-PSK and 802.11 frames (
drivers/wifi/wpa.rs,drivers/wifi/ieee80211.rs,net/sha1.rs) — the supplicant a SoftMAC radio needs, built entirely as pure, vector-pinned logic, because joining a Wi-Fi network is code where a bug is invisible: every step produces bytes as random-looking as the correct ones and the only feedback is that the access point stops answering, which is indistinguishable from a wrong password. So nothing here waits on a radio to be checkable. SHA-1 is deliberately absent from the TLS path (broken for signatures) and exists only because IEEE 802.11i mandates it — pinned to FIPS 180-2, RFC 2202 and the 802.11i Annex H PSK vectors; then PBKDF2→PMK, PRF-384→PTK (KCK/KEK/TK), the EAPOL-Key MIC, and AES-128 + RFC 3394 key unwrap for the group key. Four things are silent when wrong and each has a test: the MAC addresses and nonces concatenate smaller first (both sides do it, neither transmits the result, so a mistake is a self-consistent PTK the AP disagrees with — reported to the user as a wrong password); the PRF puts a NUL between label and data; the MIC is the first 16 bytes of HMAC-SHA-1 over the frame with its own MIC field zeroed; and PBKDF2 counts bits and must hash an over-long HMAC key first (every short vector passes without that branch).Handshakeis the four-way exchange as a pure state machine over frames —on_framein, reply out — so the failure paths are the tested ones: a replayed message 1 (which carries no MIC, so the replay counter is the only defence), a message 3 whose group key fails its integrity check, and the ordering that matters: the ANonce is checked before the MIC, because a changed ANonce fails the MIC too and checking the MIC first blames the passphrase.ieee80211parses beacons/RSN elements — attacker-controlled bytes from an unauthenticated sender, so every length is a claim and a lying one is refused, never clamped — and reports TKIP/SAE/802.1X/required-MFP as unsupported up front rather than as a timeout. Reachable and checkable by a user:/wifi psk <ssid> [passphrase]prints the derived key, andwpa_passphraseon any Linux box is an independent oracle for it (e2ewifi_pskasserts the published vectors on the running kernel). - Intel WiFi (
drivers/wifi/iwl/) — the part in most x86 laptops. Staged, and the stages are the point:fw(family from the PCI id, firmware filename search order,.ucodeTLV parse),csr(registers + pure predicates),context(the gen2 context info — the device's own loader fetches firmware out of host memory once it has that structure's address),proto(command out / notification in),device(the sequences and the queue)./wifi upresets the radio, hands over firmware, waits for the alive notification and checks its status word (firmware that comes up unusable still announces itself), reads the MAC out of the strap/OTP registers, and sends one read-only command (NVM_GET_INFO) — read-only on purpose, since a first command that configured something would misconfigure a real radio if any part of the untested transport is wrong. Traps pinned by tests: the MAC's first word is big-endian and the second contributes only its low two bytes reversed (to_le_bytes-and-concatenate gives a plausible wrong address);prphaddresses are 20 bits (the hardware supplies the0xA00000base, so truncation is correct); the transmit doorbell packs queue id and write index in one word; a command's first 20 bytes must come from a separate aligned staging buffer; and a receive buffer must be handed back (the free-list write index is a count, not a slot) or the driver works during bring-up and goes deaf under traffic. It cannot scan or associate, and that is deliberate: a scan request, MAC context and station key are large per-API-version structures, no emulator provides an Intel WiFi part, and code written from memory would look complete, send well-formed garbage to a real radio and report success — the failure would be somebody's laptop rather than a missing feature. Those need a machine with the part in it. Every layout here comes from Linux'sfw/api/*.h, fetched, never recalled — the one written from memory (NVM_GET_INFO's general section as fouru32s instead ofu32,u16,u8,u8) putn_hw_addrson the transmit chain mask: a small, plausible number that passes any sanity check, i.e. a confident wrong answer rather than an error. The groundwork for adding a command safely isfw::cmd_version(IWL_UCODE_TLV_CMD_VERSIONS, TLV 48), the table where the image states which request version it expects; a new command must consult it and refuse an unimplemented version, since silence in that table is not version 0. Also still absent: Realtek RTL8852 and Qualcomm/Killer WiFi, and Broadcom's SoftMAC parts. Shell surface:/network(info/dhcp/static/dns),/ping,/wifi(scan/connect via the password modal), a TCP listener (net::listen/try_accept, backed by a pool of Listen-state sockets in both the NIC and loopback sets, so one listener serves external/hostfwd andlocalhostclients alike; accept hands out an EstablishedTcpHandlea service agent adopts as a channel),/http(a curl-like HTTP/1.1 client innet/http.rs—-X/-H/-d/-v/--stream, all methods, live chunked/SSE streaming;http://andhttps://vianet/tls.rs/embedded-tls with real certificate verification (see the TLS-trust bullet); also the agent'shttptool;-O/-o <file>download the body to the Synapse store (/downloads/<name>, overwrite confirms via the modal, human-typed only) where/openreads it back — editor, image viewer, or audio player),/ws(a plaintext WebSocket client innet/ws.rs— RFC 6455 handshake with Sec-WebSocket-Accept verification, masked frames, ping/pong),/mcp(an MCP client inmcp.rs— Model Context Protocol over HTTP/JSON-RPC 2.0, Streamable-HTTP transport with SSE +Mcp-Session-Id:/mcp connect <name> <url>runs initialize→tools/list and registers each remote tool into the tool registry asmcp__<name>__<tool>, so the shell agent calls it like any builtin —tools/callforwarded on invoke, results taint-tracked as UntrustedIngested; agents declare MCP servers in their manifest (mcp_servers), shown + connected on the install consent screen)./model remote <http://host:port> [name]points the shell agent at a hosted OpenAI-compatible model (llama.cpp server / Ollama / vLLM), over http or https, viashell/remote.rs— same system prompt, tool calls, and approval gates; only generation moves off-box (config persisted at/configs/core/model.json; switching backends is human-only, never an agent tool). The stack is polled cooperatively from the shell idle loop. NB: aarch64 MMIO register access must be a singleldr/str(inline asm) — LLVM otherwise coalesces adjacent volatile accesses into a paired load HVF can't decode (hvf: isv). - TLS certificate trust (
net/x509.rs,net/rsa.rs,net/hashes.rs,net/ca_roots.rs) — HTTPS server certs are verified by default against an embedded Mozilla root store (121 roots,tools/gen_ca_roots.py→ca_roots.der+ spans; regenerate fromcacert.pem).ringcannot build bare-metal (C + asm; that's whyNoVerifyshipped originally), so the validator is pure RustCrypto:x509-certparses DER,p256/p384verify ECDSA, and [net::rsa] does RSA PKCS#1 v1.5 + PSS oncrypto-bigint(a fixedU4096modexp — norsa/num-bigint-dig/ring).x509::verifybuilds a chain leaf→intermediates→trusted root (each link's signature checked with the issuer key), checks each cert's validity window against the wall clock (refuses if the clock is unset — set/datetime), CA basic-constraints on issuers, and the leaf's SANs vs. the hostname (wildcards). The TLS 1.3CertificateVerify(RSA-PSS mandatory there — the bug that first failed css.tobyase.de) runs through the same code viax509::verify_data. AChittiVerifier(net/tls.rs) implements embedded-tls'sTlsVerifier(vendored crate given the few neededpubre-exports);/tls insecure onis thecurl -kescape hatch (human-only) for a self-signed/self-hosted box. Out of scope (documented, not silently skipped): CRL/OCSP revocation. Validated by KATs (rsa_testvec.rs,gen_rsa_testvec.sh) + a real embedded chain (ca_testvec.rs,gen_ca_testvec.sh: verifies, and tampered/expired/ wrong-host fail closed) + live/http https://…to real providers. Built-in audio on Apple Silicon works (
sound/apple/,/audio) — the Mac mini's own speaker plays. Five blocks in series, each silent when wrong: PMGR power domains → NCO (900 MHz reference → 3.072 MHz master clock) → MCA (I2S serialiser) → ADMAC (DMA through a T8110 DART in bypass) → TAS2764/SN012776 over the Apple/PASemi I2C master. Started on the first play (sound::try_apple_builtin, gated on the tree naming the amplifier, tried once);/audio probeis read-only,/audio upretries,/audio dumpreads every layer back,/audio gain <n>sets the analog level,/audio amp [reg]round-trips one register. Ported from m1n1'sproxyclient/experiments/speaker_amp.pyplushw/{nco,mca,admac,i2c}.pyandhw/codecs/'sSN012776Regs— but the working configuration is Linux's, not the script's, which is the single most expensive thing in this whole bring-up: the script drives a one-clock TDM pulse at 12.288 MHz, and this machine's amplifier wantsSND_SOC_DAIFMT_I2S | IB_IF— 64 bit-clocks per frame (two 32-bit slots), a square FSYNC, one-bit data delay,BCLK_POLclear,MCLK_CONFdivider 1, andTDM_CFG1 = 0x03on the amp. Given the wrong one it accepts the clock, latchestdm_clock_errorand shuts itself down.What made this take a dozen boots is that every failure is silence, and the layer that can see the problem is the last one. The lessons, in the order they cost time:
- Resolve what the tree states; never search by compatible and take the first
hit. Made three times in one driver: the wrong IOMMU (21
apple,t8110-dartnodes — the first is powered down, so reading its lock register took a synchronous external abort), the wrong DMA engine (2apple,admac), and the wrong I2C bus (5apple,i2c), where every register write was acknowledged by something else and discarded while reads returned that bus's world.fdt::{reg_by_phandle, parent_reg_of_compatible, parent_prop_cells_of_compatible}exist for this, and a block's power domain must be resolved the same way its registers are — a gated block does not read as all-ones, it does not decode at all. - A register field is not a register.
PORT_CLK_SEL's selector is bits 11:8, so1leavesSEL = 0and routes no clock to the port's pins. The serialiser still runs, the DMA still drains at real time, every controller register still reads back correct — only the amplifier can tell, and it says so by refusing to leave shutdown while latching no fault (an absent clock is not a clock error).mca::port_clk_selis a tested function for that reason;PORT_DATA_SELnext to it genuinely is a raw bitmask, which is why the distinction is written down. - Writing a register is a request; read it back.
power_upreturnsPWR_CTRLas it reads after the write,configureverifies one register, and/audio gainreports what stuck — "we powered the amplifier" and "we asked and it declined" are indistinguishable otherwise and produce identical silence.CHNL_0andDVCare only writable in shutdown, soset_gainbrackets its write; the part'sINT_LTCH0(0x49) latches the reason. - The part is booked and paged. macOS configures this amplifier minutes
before m1n1 boots and m1n1 leaves it alone, so it can be on any book — where
writes are acknowledged and land elsewhere.
select_and_resetdoes page 0 → book 0 →SW_RESET→ select again, after an SDZ pulse with delays. - A
SndDevice::playmust never callupkeep(). It runs insidesound::play_ch, which holds theSNDlock, andupkeeppumps the media player straight back into it: a non-reentrantLockedtaken twice on one core, i.e. a machine that stops with no output and no Ctrl+C. Blocking waits spin on their own hardware and are bounded (STALL_MS), and the descriptor ring is sized so a whole 200 ms pump chunk fits without waiting. - Diagnosis has to be built, not reasoned.
/audio dumpreading all four layers back — and printing what each should be — is what found the clock selector, after three rounds of plausible hypotheses. The pure parts (the NCO's LFSR divider table, MCA field packing, ADMAC descriptor encoding, I2C FIFO words, the gain field) are unit-tested on both arches; everything else needed the machine.
The amplifier's analog gain starts at its minimum and nothing raises it implicitly — loudness is
sound::apply_output_gain, where a mistake is quiet rather than destructive. Unimplemented and refused rather than guessed: capture (the mic is behind the always-on processor), the CS42L84 headphone jack, stereo, and the SIO DMA path.- Resolve what the tree states; never search by compatible and take the first
hit. Made three times in one driver: the wrong IOMMU (21
- Sound & voice (
sound/,onnx/) — virtio-snd PCM in/out (S16 mono, poll-driven, descriptor chains) over virtio-mmio (aarch64) and virtio-PCI (x86 QEMU), Intel HDA for VirtualBox (x86+ARM) and real hardware, plus AC'97 and Sound Blaster 16 (x86 legacy; viamm::alloc_dma_bounded, which asks the frame allocator for the 8237's real constraints — under 16 MiB and inside one 128 KiB block — instead of allocating normally and hoping, which never held and made the driver unreachable code);/voice(waveform modal, level-gated utterances) and/voice test(tone + mic check).audio/is the pure media-decoder layer behind the/open <file>.wav|.mp3|.aacplayer: a full RIFF/WAVE parser (PCM 8/16/24/32-bit + float32, any channel count downmixed), an MPEG Layer III decoder — a no_std Rust port of minimp3 (CC0; tables generated verbatim bytools/gen_mp3_tables.py), validated ±1 LSB against minimp3's own scalar decode (stereo MS/short-blocks, MPEG-2 LSF, bit reservoir) — and an AAC decoder (audio/aac/, a Symphonia-path port under MPL-2.0: LC + Main/LTP ICS, ADTS demux, HE-AAC SBR/PS) that also supplies the video player's audio track. Playback feeds the device in ~50 ms chunks — queue backpressure paces it — pumpingupkeep()and answering Ctrl+C between chunks.onnx/is a zero-copy no_std ONNX (protobuf) reader + op interpreter that runs the real voice models end-to-end: silero-vad v5 (VAD), parakeet-ctc int8 (STT —/voice stt <wav>transcribes), and KittenTTS (TTS —/voice say <text>speaks); bare/voiceis the full mic → VAD → STT → LLM → TTS conversation loop. Models load lazily from any disk volume (bundled in the images;cargo xtask voice-assetsdownloads them intoassets/voice/, gitignored). The ONNX ops parallelize across the SMP fleet (onnx::exec::par_range→smp::parallel_for: conv1d tiles, conv_transpose gather+dot, matmul rows/cols, strided broadcast,par_mapunary) and/voice sayis chunked —split_speechsynthesizes clause by clause into thespeech_pumpqueue (fed fromui_tickvia the non-blockingSndDevice::out_free_bytes), so audio starts in ~3 s and streams while the next clause synthesizes. For any numeric or perf work on this path, usetools/onnxdiff/(host-side layer-by-layer diff of the kernel's own interpreter against onnxruntime) — not QEMU round trips. NB: kitten's DynamicQuantizeLinear means outputs are only comparable by equidistance from onnxruntime, never bit-exact; any float reassociation flips int8 rounding. - Remote voice (
shell/voice_remote.rs) — hosted TTS/STT providers as an alternative to the local ONNX models, same posture as/model remote: human-configured key (/voice remote tts|stt <provider> <key> [voice] [model]), persisted at/configs/core/voice.json, never an agent tool. Providers: ElevenLabs, Cartesia, Inworld, Sarvam, and any OpenAI-compatible/v1/audio/{speech,transcriptions}(base viaurl@model). Each is a pure request-builder + response-decoder (unit-tested wire shapes); TTS audio comes back as WAV/MP3 bytes (audio::decode) or base64-in-JSON (Inworld/Sarvam), resampled to the device rate and fed into the same chunkedspeech_pump— so remote synthesis streams per clause too. STT uploads the utterance asmultipart/form-dataWAV.voice_say/voice_stt_fileprefer a configured remote endpoint, else fall back to the local model. TLS caveat: all providers are HTTPS and the in-kernel TLS client (net/tls.rs, embedded-tls TLS 1.3, no cert verification) doesn't interop with every server yet (RSA cert chains fail) — a provider that won't handshake reports a TLS error, not a wrong result. Video (
video/) — H.264/AVC baseline + Main/High-profile decoder + player for/open .mp4|.mov|.mkv|.webm|.ts|.m3u8(HLS VOD included), built in stages, each pure + unit-tested off-hardware and validated bit-exact against ffmpeg/PyAV via thetools/h264diff/host harness (mountsvideo/*.rsvia#[path]; the onnxdiff/cortexdiff pattern — the CAVLC VLC, deblock alpha/beta/tc0, and all CABAC tables are parsed/generated from the FFmpeg sources,tools/gen_cabac_tables.py, never hand-transcribed). CABAC / High profile (h264/cabac.rsengine + generatedh264/cabac_tables.rs+h264/decoder_cabac.rs): I/P/B slices, adaptive 8x8 transform + Intra_8x8, a POC-ordered multi-frame DPB with ref-list construction/reordering + sliding window/MMCO-1, explicit weighted P, implicit weighted bi-prediction, spatial + temporal direct — validated bit-exact on full real-world clips: 171/171 frames (sample-5s-720p: High, pyramid B, weightp) and 300/300 (Big Buck Bunny 720p: High, temporal direct, 16-ref). Hard-won availability rules: MV prediction may only use 4x4 cells whose motion for that list is final (per-listmvokstamps — an above-right cell of a later same-MB partition is unavailable, while a partition not using the list becomes available-with-ref -1 immediately, FFmpeg's LIST_NOT_USED fill); the ref-idx context reads refs-as-parsed (pre-MV); the B mb_type context tests the MB-level direct flag, not the per-4x4 one. Unsupported CABAC features (interlaced/MBAFF, FMO, scaling matrices, I_PCM-in-CABAC, long-term refs, poc type 1) are refused cleanly, never mis-decoded. Full baseline pipeline:mp4/mkvdemux → CAVLC residual (h264/cavlc.rs) → I + P macroblock decode (h264/decoder.rs: I_4x4/I_16x16/I_PCM, P_L0_16x16/16x8/8x16/8x8/Skip, multiple slices per frame with slice-aware neighbour availability) → intra (h264/intra.rs) + inter (h264/inter.rs: median MV prediction + 6-tap luma / bilinear chroma MC) → inverse transform (h264/transform.rs) → in-loop deblocking (h264/deblock.rs) → YUV→RGB → a video tab with a player HUD (framebuffer::draw_video_status: state, mm:ss, frame counter, scrubber, mute, shortcut hints — drawn after each frame blit) and transport controls (Ctrl+Tab focus, space pause, ←/→ seek, ↑/↓ ±10 frames, 0 restart,mmute, Ctrl+C stop), frame-paced by pts. The HUD sits in a reserved bottom strip (present_surface_reserve+video_hud_height) the per-frame blit never repaints, its text wrapped to the pane width and repainted in place — so it neither flickers nor overflows. Streaming decode:video::StreamDecoderholds the source + sample table and decodes on demand (seek_decode, rewinding to the latest keyframe on a backward seek) — a whole-clipVec<Frame>would be ~700 MB of RGB for a 1300-frame 480p clip (heap-hostile; trap #3). Baseline keeps one reference frame; CABAC keeps the DPB plus a bounded reorder cache (pictures pending their display slot, keyed by decode index — without it every backward hop of the B-pyramid display order re-decodes from the previous IDR, O(n²)). Display order comes from the container (ctts-adjustedSample.cts, stable-sorted). The "green frames" bug was NOT memory: a P-slice that ends with a trailingmb_skip_run(skips the final MBs, no coded MB after →more_rbsp_data()goes false mid-drain) left the last MB(s) at plane-init 0 → black luma / green chroma, which inter-prediction then propagated into a growing green region. Fix: keep draining inferred skips whileskip > 0even pastmore_rbsp_data()(decoder.rsMB loop). Lesson: render + eyeball vs PyAV, don't trust a single green-fraction metric (the first scan's threshold missed it). Audio:mp4::parse_audiodemuxes the AAC (mp4a/esds→ AudioSpecificConfig) track, and the AAC decoder inaudio/aac/(a Symphonia-path port, MPL-2.0 — see THIRDPARTY-LICENSES.md — plus ADTS demux and HE-AAC SBR/PS reconstruction) turns it into mono S16 PCM at open (open> audio ready: …); playback keeps the PCM cursor pts-locked to the video clock (pump_videosnaps drift > ~50 ms), andmmutes. Validated bit-exact against PyAV/ffmpeg — synthetic x264 clips (I/P, multi-slice, deblocked) and hundreds of consecutive frames of real-world mp4/mkv. In-kernel fixture tests hash an embedded I-only and an I+P clip against PyAV, andstream_decoder_seek_matches_sequentialproves random/backward seeks match a sequential decode frame-for-frame. Deblock gotchas (all three bit us): a chroma edge's QP isavg(qpc(QPp), qpc(QPq))notqpc(avg(QPp,QPq))(differs only across slices with differing QP); the luma normal filter'stc = tc0 + (ap<β) + (aq<β)can be nonzero even whentc0==0(don't force-skip); and the recycledFxworkspace must not leak the previous frame's motion into deblock —bs_inter2infers "list used" fromrefpoc != MIN, and a P slice never writes L1, somark_mb_decodedclearsrefpoc(not just refidx/mv) for unwritten cells. Bisect any deblock-vs-PyAV divergence withH264Dec::no_deblockagainst PyAVskip_loop_filter='ALL', and read FFmpeg's per-block list usage viaflags2=+export_mvs. Stage 1 (done):video/bits.rs(RBSP emulation-prevention unescape + a big-endianBitReaderwith H.264 Exp-Golombue/se/te),video/mp4.rs(ISO-BMFF box-tree demuxer →avcCSPS/PPS + thestsz/stsc/stco/stts/stsssample table assembled by the purebuild_samples), andvideo/h264.rs(Annex-B and AVCC NAL splitting + SPS/PPS parse → geometry/profile/entropy mode).video::probereports a stream (container, codec,W×H, frame count, CAVLC/CABAC) without decoding pixels;/open clip.mp4shows it. Scope: H.264 baseline (I/P slices, CAVLC, 4:2:0) plus Main/High CABAC (see above). Playback performance (all profiled first —sampleon the host harness,video: perf:ktrace in-kernel): in-kernel 1080p went 12 → ~30 fps, 4K ~8–10 fps, via three stacked levers: (1) NEON luma MC inthird_party/rust_h264/inter_pred.rs— the 6-tap interpolator was 40% of decode; all vector loads/stores are inline-asmldr/str d/q(ld8/st8/ ld16i/st16i— the+strict-alignrule; the asm loads beat thevld1intrinsics even host-side), and every hv quarter-pel case runs h-FIR once per row into an i16 block buffer instead of six FIRs per pixel (bit-exact: full-clip A/B byte-identity + PyAV); (2) decode-ahead — the pump loans theStreamDecoderto an SMP worker (smp::async_submit, the reserved last slot; dispatchers exclude it viafleet_workers+ zero its ranges) and holds the finished frame until its pts (VideoPlayer::ahead); every otherdectoucher joins first (video_job_join) — beware pipeline bubbles: the worker must be resubmitted on the same tick it's collected; (3) frame-drop (sample_is_nonref, pure + unit-tested): behind the clock, non-reference backlog samples are never fed to the decoder at all — but catch up in ≤2-frame steps; one giant hurry-jump decodes every backlog reference in one job and starves presentation (4K: 8 → 3 fps). Remaining: 4K ≥ 15 fps (needs parallel reconstruction — slice-parallel + independent non-ref B's; CABAC parse is the serial floor), and the multi-pane split + tab drag-drop. NB: the e2e stdlib muxer writes noctts, so its B-frame clips carry no display-reorder info — e2e CABAC clips use--bframes 0; the in-kernel fixture decodes an I/P/B clip in decode order and a media-key rule: a focused-but-stopped video tab must not eat keystrokes (media_keygates onvideo_loaded()). Host reference for the numeric stages: PyAV (self-contained ffmpeg) decodes the same clip to YUV for a frame-by-frame diff harness (tools/h264diff/, the onnxdiff/cortexdiff pattern — mountsvideo/*.rsvia#[path], runs on the host in seconds, no QEMU round-trips). The e2eopen_videoscenario muxes a real x264 baseline multi-slice clip into mp4 (stdlib muxer) and asserts the on-kernel probe + streaming decode ("N frame(s), ready in …") + transport controls; it auto-skips where x264 is absent.H.265/HEVC and VP9 both play. Main-profile 8-bit 4:2:0 HEVC and profile-0 VP9 are bit-exact against FFmpeg/libx265 and libvpx respectively;
/openstreams them. Tiles, PCM, 10-bit and VP9 segmentation still refuse with a named reason (VideoInfo::unsupported_reason) rather than a wrong H.264-shaped message — the player used to print "CABAC entropy coding (baseline/CAVLC only)" for every undecodable stream, which is true of H.264 and nonsense about HEVC (always CABAC) and VP9 (no CABAC). What landed:- The demuxers are codec-agnostic.
mp4::CodecConfigisAvc(AvcC) | Hevc(HvcC) | Vp9(VpcC); mp4 readsavc1/avc3,hvc1/hev1andvp09, mkv readsV_MPEG4/ISO/AVC,V_MPEGH/ISO/HEVCandV_VP9. Three traps, each of which silently produces a plausible wrong track:hvcC's fixed part is 22 bytes, notavcC's 5 (it carries the wholeprofile_tier_level), and reading it the short way lands the NAL arrays inside the constraint flags, where the lengths are large believable numbers; VP9 has noCodecPrivateand needs none (every frame header is self-describing), so requiring one rejects every WebM file; and VP9 samples carry no length prefix at all, soCodecConfig::length_size()is 0 there and a caller that assumes framing reads the frame header's first four bytes as a NAL length. - Fixed while generalising, both pre-existing and both invisible on a
video-only file: the mkv demuxer took blocks from every track (an mkv
with audio interleaved audio frames into the video sample list —
TrackTypeis now honoured and blocks are filtered by track number), and it read onlySimpleBlock, so a file usingBlockGroup/Blockdemuxed to zero frames. ABlockGrouphas no keyframe bit; the absence of aReferenceBlockis what marks one. - HEVC (
video/hevc.rs) — NAL split (Annex-B and HVCC), VPS/SPS/PPS,profile_tier_level, scaling lists, short-term RPS, and the slice segment header. Reusesvideo::bitsverbatim (HEVC's RBSP escaping and Exp-Golomb are AVC's) and nothing above it. Four things that are each a silent mis-decode: the NAL header is two bytes (nal_unit_typeis 6 bits at bit 1), so AVC'shdr & 0x1ftypes every unit wrong;SliceTypeis numbered backwards from AVC's (0 is B here, I there); the profile block is 88 bits and, whenmaxNumSubLayersMinus1 > 0, the unused sub-layer slots up to 8 are padded 2 bits each — omit that and every SPS field after it decodes to plausible nonsense; and the default scaling lists are not flat (H.265 Table 7-6 is a real matrix above 4x4), so a flat default decodes every scaling-list stream slightly soft rather than erroring. The slice header consumespred_weight_tableand reference-list modification even though the decoder does not use them yet, because their length is data-dependent and adata_byte_offsetthat is right only for simple streams decodes garbage instead of erroring. - VP9 (
video/vp9.rs) — superframe index, the boolean decoder, and the uncompressed frame header. A container sample is not a frame: almost every libvpx stream packs an invisible ALTREF with the frame that shows it, and treating the sample as one frame decodes the ALTREF and displays it. The bool decoder is libvpx's windowed form; a test proves it is arithmetically identical to the spec's bit-serialsplit = 1 + (((range - 1) * p) >> 8)for every reachable(range, prob), since the serial renormalise is too slow for the coefficient layer. Its first bit is a marker that must be 0, which is the only check that a compressed-header size was read correctly — get it wrong and a whole frame decodes as noise with no error. Also: the interpolation filter's 2-bit literal is not the enum order (literal 0 isEIGHTTAP_SMOOTH), ands(n)is magnitude-then-sign, not two's complement. tools/videodiff/is the host harness for all three codecs (theh264diff/onnxdiff pattern — mountskernel/src/video/*via#[path], so there is one implementation):probe,headers(per-frame/per-slice header dump — the bring-up view, since "the demuxer found no frames" and "the headers do not parse" are different failures with the same symptom), andyuv.diff.pycross-checks codec/geometry/frame-count against PyAV, which is the independent implementation our own tests structurally cannot be. Verified against real x265 and libvpx output in both container families, including tiled, multi-slice, 10-bit and 1024x576 clips: the HEVC B-pyramid comes out as POCs 0,4,2,1,3 with a CRA at the second keyframe, 4-slice frames at CTB addresses 0/20/40/60, and 2 WPP entry points for 3 CTB rows. NBh264diffalso had to be repaired — it had stopped compiling againstvideo/mt.rs's arch-neutralparallel_forfacade.- Tests: the parameter-set fixtures are real x265/libvpx bytes, not
hand-built bit patterns (a fixture built by the parser's author parses fine
by construction), plus whole embedded
hvc1mp4 andV_VP9WebM files, plus anopen_hevc_vp9e2e scenario that embeds those same two files base64 so it always runs instead of skipping when x265/vpxenc are absent.
VP9 decodes, and it is bit-exact against libvpx.
/openplays a VP9 file — profile 0 (8-bit 4:2:0), intra and inter, sub-8x8 partitions, all four transform types at all four sizes, multiple tile columns, and the in-loop deblocking filter. Verified frame-for-frame against PyAV/libvpx on nine clips including a 1280x720 real-world file, a 1024x576 four-tile clip, deeply-searched encodes that use every partition shape, and a non-frame-parallel stream that needs backward adaptation: zero differing samples in any plane.tools/videodiff vp9seq+cmpseqis that harness.The build is
kernel/src/video/vp9/:tables.rs(generated),idct_kernels.rs(transpiled),transform.rs,intra.rs,header.rs(compressed header),tokens.rs,tile.rs,inter.rs,loopfilter.rs,decoder.rs. Two of those files are machine-produced and must not be hand-edited:tools/gen_vp9_tables.pyparses ~9000 probability, scan, neighbour, filter and dequantiser values out of libvpx, andtools/gen_vp9_idct.pytranspiles the seven 1-D transform kernels (idct32alone is 328 statements). Regenerate, do not retype.Eleven bugs were found bringing this up, and every one of them was silent — worth reading before touching any of it:
- The table generator dropped the minus sign on
-PARTITION_NONE-style tree leaves, because-?\d+|[A-Za-z_]\w*cannot match a negated identifier. Every leaf became a node index, soread_treewalked1 -> 2 -> 1forever: a hang, not a crash. Guarded now by a tree-termination test. - The intra frame's partition probabilities are the constant
vp9_kf_partition_probs, not the frame context (libvpxset_partition_probs). This is the only probability set on the keyframe path that is not adaptive, and using the adaptive one desynchronises the whole tile while the mode grid still looks plausible — because keyframe Y and UV modes come from their own constant tables. A sensible-looking partition/mode dump over a completely wrong picture is the signature. ADST_DCTmeans ADST on the columns. libvpx's table istypedef struct { transform_1d cols, rows; }and itsADST_DCTentry is{ iadst, idct }— the first member is the column kernel. Swapping them is invisible onDCT_DCT, onADST_ADSTand on any DC-only block, so it survives every cheap test; it showed up as chroma (all-DC) bit-exact while luma was off by ~25 everywhere.- The residual covers the mode-info block, not the prediction block.
n4_w = (bw << 1) >> ssxwithbwin 8x8 MI units, so aBLOCK_4X4still carries a full 8x8 of luma — four 4x4 transforms. Sizing it fromnum_4x4_blocks_widereads one, leaving three quarters of the coefficients unread. Only content the encoder searches deeply enough to use sub-8x8 partitions trips it, so a fast encode of a clip was bit-exact while a slow encode of the same clip overran its tile. - The 4x4 directional intra predictors are hand-written special cases
(
intra_pred_no_4x4generates the generic form only for 8/16/32).d45at 4x4 continues the diagonal throughabove[7]where the generic one clamps toabove[bs-1]. Running the generic code at 4x4 gives a plausible diagonal that is wrong in its lower-right triangle. - Intra edge availability is per block, and the left edge is
tile-relative.
left_miis null at a tile's left column, which feeds the skip context, the transform-size context and the Y-mode probabilities — so it changes bit consumption, not just prediction. Invisible on single-tile content. Above-right is also only ever read for 4x4 transforms, and past a frame edge the last real sample repeats rather than the buffer's padding being read (which would decode differently on a seek than on linear play). - The output shift is per transform size (4/5/6/6), and the 32x32 row pass has no pre-shift. One constant makes large blocks come out at the wrong contrast.
- The bool decoder legitimately reads past the end. It pre-loads ~56 bits,
so every well-formed partition ends holding virtual zeros; libvpx adds
LOTS_OF_BITStocountthere and only errors when a decode runs far past. Flagging the first read past the last byte rejects every valid frame. num_4x4_w/num_4x4_hfor sub-8x8 inter blocks come from the partition, and having them the wrong way round makes aBLOCK_4X4read one motion vector instead of four.get_sub_block_mvuses a table (idx_n_column_to_subblock,{1,2},{1,3},{3,2},{3,3}), not a derivable rule. A plausible hand-derived version differs from it on exactly the cases a deep encode produces — it was worth 33 wrong pixels in one 10x6 region, which then propagated.
Also fixed while here, and both pre-existing: the mkv demuxer took blocks from every track (an mkv with audio interleaved audio frames into the video sample list) and read only
SimpleBlock, so aBlockGroupfile demuxed to zero frames.Backward probability adaptation is built too, which is what makes a stream encoded with frame-parallel decoding off decode at all: the probabilities the next frames start from are this frame's symbol counts merged into the context it was decoded against. Two things about it are not guessable.
mode_mv_merge_probsreturns the probability unchanged when there are no observations rather than falling back to 128 — which would throw away the forward update the header just transmitted. And motion vectors are counted from the reconstructed difference, not from the symbols as they were read:vp9_inc_mvrecomputes the joint and the magnitude class from the value, and counts the high-precision bit always, including where the bitstream coded none (its value is then the implicit 1). Counting per-symbol leaves the hp tallies short and desynchronises a frame several removes later — it was worth exactly three good frames and then noise.Still refused rather than guessed at: segmentation, reference scaling (a mid-stream resolution change) and profiles 1-3.
HEVC's pixel pipeline is being built stage by stage, and the pure stages are in.
/openstill refuses an HEVC file with a reason — nothing below is wired to a picture yet, and it will not be claimed as playing until whole frames match PyAV. What exists, each pure and unit-tested off-hardware:- The CABAC engine is H.264's, shared rather than copied
(
Cabac::new_hevc). The arithmetic,rangeTabLPSand the state transitions are byte-identical between the two standards; only the context initialisation differs. FFmpeg writes that derivation aspre = 2p - 127; pre ^= pre >> 31; clamp, which reads like an absolute value and is not — for negativex,x ^ (x >> 31)is-x - 1, and that off-by-one is exactly the specification's asymmetry between63 - p(valMPS 0) andp - 64(valMPS 1). "Cleaning it up" intoabs()is wrong on every context that starts with valMPS 0, each one state too confident, which no bitstream rejects. - 199 contexts and ~1200 constants are generated, never transcribed
(
tools/gen_hevc_tables.py->hevc/cabac_tables.rs,hevc/tables.rs). Two traps the generator had to learn:HEVC_CONTEXTSis the allocated size (199, sized for the range extensions) while only 179 are initialised, so the parse must accept3 x (<= n)and zero-pad as C does; and a zero-bin element occupies no context slot — the X-macro setsNAME_END = NAME_OFFSET + NUM_BINS - 1, so with 0 binsENDfalls belowOFFSETand the next element starts at the same index. Advancing by one there shifts every later element's contexts, which decodes one syntax element against another's probabilities: not a failure, a picture that is wrong in a way that looks like a different bug. The offsets are checked bypos == usedat generation time. - The inverse DCT is a matrix multiply, deliberately (
hevc/transform.rs). Every decoder in the wild writes it asTR_4insideTR_8insideTR_16insideTR_32— four nested macros of hand-placed constants. That factorisation is an optimisation, not the definition: the specification definesout[i] = sum_k M[k][i] * src[k]over one 32x32 basis, and because both passes sum in full precision before their single rounding step, the direct form is bit-exact with the butterfly rather than merely close. So the whole transform path contains no hand-written constant, driven from the generatedTRANSFORM; the 4x4 luma DST is the one exception and is cross-checked against FFmpeg's butterfly on every basis vector. - Intra prediction (
hevc/intra.rs) — reference substitution, the weak 3-tap and strong bilinear reference filters, and all 35 modes. Substitution propagates in the specification's scan order (up the left edge, around the corner, along the top), not from the nearest available sample: the obvious reading gives a different picture at every block touching a slice or picture boundary, and both look plausible. The corner is filtered from both edges at once — one wrong pixel there seeds every negative-angle projection through it. - Deblocking sample filters (
hevc/deblock.rs) — HEVC filters on an 8x8 grid, and each 8-sample edge is two independently decided halves whose strong/weak choice comes from lines 0 and 3 only and applies to all four. Deciding per line gives a smoother, plausible, wrong picture.tcis looked up atqp + 2 * (bS - 1), so dropping thebSterm still filters every edge that should be filtered, just uniformly — which reads as slightly soft intra edges and nothing else. - SAO (
hevc/sao.rs) — band and edge offset. The classifier must read unfiltered neighbours, so it cannot run in place: doing so makes columnx's category depend on columnx-1's offset, a directional bias that looks like a motion-compensation bug. Andedge_idxremaps the five relations to{1,2,0,3,4}so the flat case lands on the always-zero entry; indexing four offsets directly is off by one for two of the five categories. - Residual coding (
hevc/residual.rs) — the CABAC syntax layer: the last-significant-coefficient position, 4x4 coefficient groups walked backwards, greater1/greater2 flags, Golomb-Rice remainders withstat_coeffadaptation, and sign data hiding. Nearly every rule in it is a context selection rule, which is the mistake that does not fail — a bin decoded against the wrong model still yields a 0 or a 1, the stream stays in sync for a while, and the picture is wrong in a way that looks like a different bug. Two pieces of bookkeeping to hold on to:significant_coeff_flag_idxis filled in decreasing scan order (so entry 0 is the highest position, and reading those names the other way round inverts sign hiding's distance test), andgreater1_ctxis carried across coefficient groups rather than reset per group. The Rice code is validated by round-tripping against an encoder written separately from the specification's description, over every Rice parameter — and that needed a real arithmetic bypass encoder, because a bypass bin is not a raw bit. Withrangefixed at 510 the state obeysoffset_k = S_k - 510 * N_k(S_k= the first9 + kbits as an integer,N_k= the bins so far), which inverts toN_k = S_k / 510; the first version of that helper assumed bits passed straight through and would have tested the bit reader instead of the code. - Coding-unit derivations (
hevc/ctu.rs) — the MPM list, chroma mode resolution, scan-order selection, partition geometry andbS. The MPM ring is 32 wide over modes 2..=33, so mode 2's predecessor is 33 and mode 34 folds onto the same neighbours — not what "extend the angle by one step" suggests. The non-MPM path sorts the candidates before skipping, which is easy to omit because the MPM path does not need it, and omitting it still yields a legal mode. The chroma escape on a collision is mode 34, not the next table entry. AndbSmatches references by picture, not by list index — the same picture can sit at different indices in the two lists, so index-matching calls two identical predictions different — with both pairings tried when a block predicts twice from one picture. - Inter prediction (
hevc/inter.rs) — MV scaling, the merge candidate list, and motion compensation. MC works in a 14-bit intermediate: every fractional filter leaves its result there and the final shift happens once, in the uni- or bi-prediction combine, which is why bi-prediction is more accurate than averaging two rounded predictions. Five shifts have to agree (<< (14-B),>> (B-8),>> 6,>> (14-B),>> (15-B)) and a flat reference reconstructing exactly through every fractional position pins all of them at once. Merge pruning compares each position against a fixed short list of predecessors, not against everything found so far — B0 duplicating A1 is still kept — and B2 is dropped once four candidates exist, a rule about the count rather than about the list being full.mv_scale's+ 127 + (negative)is a round-half-away-from-zero; a plain shift biases every scaled vector towards negative infinity and drifts a whole GOP of B-frames.
Two tables in this work were recalled and wrong, which is the standing reason everything here is generated: the 4:2:2 chroma mode map (
tab_mode_idx) came out right for the first 14 entries and wrong for the remaining 21 — it is a gentle monotone curve either way, so nothing about it looks suspicious — and FFmpeg's context-initpre ^= pre >> 31reads as an absolute value but is-x - 1, which is the specification's63 - p/p - 64asymmetry.- AMVP (
hevc/inter.rs) — two predictor candidates per list. Each position is tried in listlxthen the other list, because a neighbour predicting the same picture through the opposite slot is still a valid predictor. AndisScaledFlaggates a whole second pass: when neither left neighbour exists, B is promoted into A's place and B is re-derived with scaling allowed. Missing that rearrangement yields the right number of predictors and the wrong ones, at every prediction unit on the left edge of a CTB row. Long-term and short-term references are never mixed — a long-term reference has no meaningful temporal distance, so the candidate is refused rather than scaled by a nonsense ratio. - POC, RPS, reference lists and the DPB (
hevc/dpb.rs) — nothing here touches a pixel, so every mistake is a whole frame that is right in isolation and wrong in sequence. Four rules carry the risk. The POC wrap test is asymmetric (<pairs with>=,>pairs with>), so a half-range difference wraps forwards and not backwards; writing both comparisons the same way misplaces exactly one picture per wrap. L0 is before-then-after and L1 after-then-before — that single swap is the whole structure of bidirectional prediction, and reversing it decodes fine with every B-frame's two predictions exchanged. A reference list is filled cyclically, so a slice activating more references than the RPS holds repeats the concatenation rather than getting a short list. Andused_by_curr_picdecides Curr vs Foll while position decides Before vs After, so a picture kept only for a later frame is in the RPS and in no list. Bumping releases the lowest pending POC, which is what turns decode order back into display order for a B-pyramid. CU/PU syntax elements (
hevc/syntax.rs) — everything above the residual coder: the split, skip, part-mode, CBF, intra-mode, merge, reference-index, MVD and QP-delta codes. The binarizations are pure functions over aBinsource, not over the CABAC engine, and that is what makes them testable — a context-coded bin cannot be forced from outside the arithmetic coder, so a test that had to code its way to a given branch would be testing the coder. With a canned bin source,part_modecan be checked for what actually matters: that its code is prefix-free and complete in each of the five configurations. Four traps it pins: an 8x8 inter CU codesNx2Nin two bins, not three (NxN there would be 4x4 inter prediction, which HEVC forbids), and consuming the third steals a bin from the next element; an 8x4 or 4x8 prediction unit skips its bi-prediction bin entirely for the same bandwidth reason; the MVD's four context-coded flags are interleaved x, y, x, y before either remainder, so decoding component-by-component reads a valid vector from the wrong bins whenever both components are non-zero; andcbf_luma's context index runs the opposite way from every other depth-indexed context here (1 at the top of the tree, 0 below).cu_qp_delta_abscannot express more than 131 — its suffix's own unary prefix is capped at 7 — and that ceiling has to be reported rather than absorbed: FFmpeg returns an error there, and the obvious alternative of returning the prefix is the plausible small delta5, so a corrupt stream would quietly shift the quantiser for the rest of the CU instead of being rejected. It returnsOption<u32>. (Found by a round-trip test that ran past the representable range, which is the only reason the cap was noticed at all.)- The walk (
hevc/decoder.rs) — the CTU quadtree, reconstruction, and the picture-level in-loop filters. It owns what a picture has and a block does not: the neighbour grids (motion, intra modes, skip, depth, QP, coefficient presence, each at the granularity the specification indexes it by), and availability, which for a quadtree is not "above or left" but a z-scan order comparison — a block above you can be one that has not been decoded.
HEVC intra is bit-exact against FFmpeg.
tools/videodiff hevcseqdecodes a realhvc1mp4 and the IDR frame matches PyAV with zero differing samples in all three planes — CABAC, the quadtree, MPM derivation, reference substitution and filtering, all 35 prediction modes, residual coding, dequant, both transforms, deblocking and SAO. Two bugs stood between "decodes" and "bit-exact", and both are the silent kind:- A leftover context-coded
decision()in the QP-delta path consumed one bin belonging to the residual right after it.cu_qp_delta_sign_flagis a bypass bin, present only when the magnitude is non-zero. The symptom was a picture that decoded, terminated its slice at exactly the right CTU, and had plausible intra modes throughout — while every coefficient block came from one bit too late. qPY_PREDis the average of the left and above neighbours inside the current CTB (H.265 §8.6.1), falling back to the previous CU's QP where either is absent — not the running QP. Using the running QP drifts toward the bottom-right of every picture, because the error compounds through each quantisation group's predictor and then again through intra prediction from the blocks it mis-quantised. It read as a gentle gradient error, maximum 34 of 255, with the top-left 32x32 already exact.
How to debug it, because the harness is most of the work.
tools/videodiff hevcseq <file>decodes with our decoder and writes raw I420; a PyAV venv (python3 -m venv /tmp/avenv && /tmp/avenv/bin/pip install av numpy) decodes the same file as the reference. PyAV ships libx265, so targeted clips can be generated to bisect the feature space — that is what found WPP, and it turns a guess into a measurement. Setdec.trace_onfor a per-CU/TU trace with the CABAC byte position, which distinguishes a syntax desync (bytes consumed far from the slice length) from a reconstruction error (bytes right, pixels wrong). Two traps in reading that trace:byte_posincludes up to 4 bytes of reservoir look-ahead and saturates at the slice end, so "61 of 61" is only accurate to +-4; and the CTU loop exits on the CTB count, soend_of_slice_segment_flagreturning 1 proves nothing about sync.HEVC Main plays, bit-exact against FFmpeg. Zero differing samples on the videodiff suite: multi-CTB all-intra, I+P, hierarchical B-pyramid, WPP, SAO, deblock, TMVP, sign-hide, mid-stream CRA with RASL leading pictures, and realish default-x265 GOPs (including 320x240). Two late silent bugs that made "almost every clip" match while a typical real encode did not:
ref_idx_l0andref_idx_l1share the L0 CABAC contexts in every production encoder/decoder (x265'sOFF_REF_NO_CTXis list-agnostic; FFmpeg hard-codesREF_IDX_L0_OFFSET). The specification's table has a separate L1 pair; using it desynchronises the first bi-predicted AMVP block that has more than one L1 reference — the hierarchical B-pyramid leaf case.- A mid-stream CRA must not empty the DPB. IDR/BLA set NoRaslOutputFlag and clear references; a continuous CRA keeps them so RASL leading pictures can still predict from the previous GOP. Clearing on every IRAP made three frames before each keyint CRA pure noise while everything else stayed exact.
Still refused rather than guessed: tiles, PCM, 10/12-bit. The rule stands — diff whole frames against PyAV before claiming anything works.
HLS plays —
/open http://…/master.m3u8(and a.m3u8or bare.tsin the store) fetches the playlist, downloads its MPEG-TS segments, and assembles them into one sample table the existingStreamDecoderopens, so H.264 and HEVC arrive over HLS with no change to either decoder.video/m3u8.rsis the playlist parser,video/ts.rsthe transport-stream demuxer,video/hls.rsthe loader — which takesfetchas a closure, so every unit test runs off-network and the shell path pumpsupkeep()and answers Ctrl+C between segments. Verified against a real libavformat-muxed VOD bytools/videodiff hls, frame-for-frame vs PyAV.Seven things this cost, and the first is the one worth reading:
- A segment boundary is the only place a media clock may legally restart,
and it must be judged there. Segments commonly restart their PTS, and
the step back from the end of the previous segment is smaller than a deep
B-frame reorder — so a generic "small backward step = reorder" rule maps
segment 1's pictures on top of segment 0's and the player interleaves
them. Every frame decodes, the count is right, and the sequence comes out
0, 8, 1, 9, 2, 10, …. Nothing but a frame-by-frame diff against PyAV finds that; the frame count, the geometry and the decode all look perfect.ts::Timeline::segment_boundarytakes the boundary explicitly, and#EXT-X-DISCONTINUITYoverrides it, because a splice may coincidentally continue the numbers. - PTS is not monotonic, so timestamps cannot be accumulated. With B-frames a picture's PTS is routinely earlier than its predecessor's in decode order. The step from the previous timestamp is therefore measured both ways modulo 2^33: a small forward step is the next picture (which makes the 33-bit wrap fall out for free), a small backward step is reorder, anything else is a discontinuity that resumes after the furthest sample so far. PTS and DTS run on separate timelines — that is what B-frames are.
corehas nof64::round.#EXTINF:9.009is exact decimal text, som3u8::parse_seconds_msscales the digits instead — simpler, exact, and it compiles.- A URL is not a path.
/openran its argument throughresolve_path, which prepends the cwd and collapseshttps://tohttps:/— so the fetch path was unreachable from the command that needs it most, HLS being fetched by definition. Relatedlypath_extensionnow strips a query string for URLs only:master.m3u8?token=…matched nocommand_hooksextension and fell through to the text editor. - Playing a URL is network egress, so it does not go through the hook
agent. The media agent's manifest grants
fs,uiandtodo— nonet— and routing a URL through itsvideo_playertool would hand it reach it was never granted, by way of a feature that reads as being about file formats./open <url>is therefore handled on the interactive path, which is unreachable fromdispatch_system(the/passwd//lockstructure: absent from the tool surface beats guarded inside it), andrun_media_toolrefuses a URL naming the missing capability. The browser agent keeps its own URL path, which is what it is for. - A byte-range playlist points every segment at one resource. Fetching per
segment downloads that whole file once per segment — quadratic.
load_vodholds the resource while consecutive segments draw ranges from it, and only for ranged segments. - Every failure names its segment. A VOD is hundreds of segments; a bare
ts: no PAT/PMTsays neither which one nor whether the download or the demux failed. - An access unit is only a picture if it carries a VCL NAL. A
parameter-set-only PES otherwise takes sample index 0 and never decodes, so
seek_decode(0)fails on a stream whose every later frame is fine.
/open <url>resolves the type from three signals, in this order, and the order is the whole design: the URL's own extension (what the human typed — no network needed to trust it), then the bytes, then the remoteContent-Type. The header is consulted last becauseapplication/octet-streamis what a great many servers say about everything and a server may simply be wrong, so a PNG served astext/plainstill reaches the image viewer (the_bytes_outrank_the_servers_claim). Routing adds no per-type branch: the body is staged in/downloads/under a name carrying the resolved extension and the existingresolve_open_hookchain takes it from there, exactly as for a local file. Streaming media (HLS and the video containers, by extension) skips staging and plays off the network — a VOD is hundreds of segments and a film is gigabytes. Staging never overwrites:/openis not a download command and you named no destination, so a colliding name takes-1,-2(/http -O, where you did ask, is what confirms and replaces). Handing every URL to the video player — the first cut — made/open https://…/logo.pngreport "unrecognised container (mp4/mov, mkv/webm, m3u8, ts supported)", blaming the video demuxer for a PNG.NB a trap found while testing that path, which is not about HLS: a focused media tab consumes the keys it handles and lets the rest through to the composer, so typing a command while an image tab has focus loses exactly its shortcuts —
/open http://10.0.2.2:8100/logo.pngarrives as/open http://1..2.2:81/ogo.png, having eaten0(reset) andl(rotate left), and then fails as a DNS error. Partial consumption is the wrong shape when the composer still receives the remainder; the video path already guards its half (media_keygates onvideo_loaded()), the image path does not.Refused with a reason rather than guessed at: encrypted playlists (
#EXT-X-KEYwith a cipher), live ones (no#EXT-X-ENDLIST), and fMP4 in every form —mp4.rshas nomoof/traf/trundemuxer, so only a non-fragmented mp4 segment plays. That is the largest remaining gap, since much of the modern web ships CMAF.The trap there is that a fragmented single file parses fine and yields zero samples: its
moovsample table is empty by design and every entry lives in amoof. That is exactly whatffmpeg -movflags frag_keyframe+empty_moovemits, i.e. the one input most likely to be tried — and left to fall through it surfaced several layers later as "video: no decodable frames found", naming neither fragmentation nor the missing demuxer.load_vodchecks for the empty table and both shapes now give the same diagnosis.- The demuxers are codec-agnostic.
Switchable engines, and the rule for adding another. Two subsystems run an alternative implementation alongside ours on the
/decoder ring3|kernelpattern — abenchsubcommand compares them:/heap firstfit|sizeclass(mm/heap.rs) and/html ours|tl(browser/html_tl.rsover the vendoredthird_party/tl). Note the defaults point opposite ways, and deliberately: size-class is the default because it moved page boot 3.8x, while our HTML parser stays the default becausetl's 6.75x is 6.75x of ~3 ms — its value is being a second implementation, not being faster. Five rules, each of which cost a debugging cycle or a wrong number:- A/B only what is like-for-like; share everything else. The
tladapter reusesextract_assets_rich,preprocess,set_attributeandfinalize_documentverbatim — the last two were extracted for it, and the third was found missing when the cross-engine test compared a title of"Untitled"against"". Otherwise the comparison measures the divergence rather than the engine. - A bench must never fall back; a page load must. An adapter returns
Noneon failure so a measurement cannot attribute our result to the challenger; the page path may fall back but must count it, so "X is selected" and "X actually did this" stay distinguishable. - Report agreement before speed.
/html benchprints whether both engines built the same tree, and restores the previous engine afterwards. A faster engine that produces something else has changed the page, not won. - A shared front end dilutes the ratio.
/html benchtimesextract_assets_rich+preprocessfor both engines because a page load really pays them, so on a small page the ratio collapses toward 1x — 1.9x on a 2 KiB fixture against 6-9x on real 700 KiB pages (tools/webbench). The command says so under 64 KiB. - A fixed iteration count is only sound when the thing timed is slow
relative to the counter. Flex placement is microseconds, so at 2,000
iterations four runs of the same benchmark reported 21.8x, 6.6x, 18.0x and
82.8x — the denominator was noise.
shell::time_untilextends a batch until it reaches a tick floor and the benches report per iteration, which is also what makes batches of different length comparable; a batch that never reaches the floor prints SUSPECT instead of a ratio.
Where the time actually goes, measured: on the shadcn page, JS is ~99% of page boot (686 ms of 695 ms; 2651 of 2654 before the allocator). HTML parsing and flex layout are rounding errors, which is why
tlis kept as an oracle rather than adopted, and why the next real lever is the JS engine.taffy was evaluated and removed. It agreed with
browser::flexto within 1 px on every shape — rows, columns, gaps,space-between, wrap,flex-grow— and cost ~20x per placement under first-fit and ~70x under the size-class heap: the gap widens with a better allocator, because both are allocation-dominated and ours more so (size-class made taffy 4.1x faster and ours 9.0x). That cost is a property of a per-call boundary that builds and drops a wholeTaffyTree, not a verdict on taffy, whose design is a persistent tree with dirty-subtree recompute — but there is no adoption case at this boundary, so the dependency is gone. The agreement is the finding worth keeping: two independently written implementations landing on the same pixels is evidencebrowser::flexis correct that our own unit tests structurally cannot provide. Re-vendor it as a#[cfg(test)]oracle if flex is ever reworked; do not put it back on the page-load path.Neither
tlnor ours implements implied end tags, so switching does not buy<p>a<p>bas siblings.- A/B only what is like-for-like; share everything else. The
- Agent chat protocol — the shell chat is an agentic ReAct loop on the
Qwen3.5 template: the prompt advertises a small CORE tool set plus
search_tools(progressive discovery over the registry — manifest toolset ∩tools::registry; never hardcode a tool list in a prompt),<tool_call>JSON in,<tool_response>back, thinking off by default (/think),/mode manual|auto|bypassgates agent tool calls through the modal, Ctrl+C/Esc cancels prefill and decode,/compactrebuilds the KV from a model-written summary. Agents are processes:/agentslists the scheduler tasks that carry agent identity,switchre-homes the chat,killrevokes a task's capability table. Every agent has/agent/<id>/{SOUL.md,skills/,memory/}; SOUL.md is prepended to its system prompt. The shell agent is the only default agent (boot demos removed).
STANDING RULE — one keyboard choke point; bytes are not columns
Every keyboard transport funnels through kernel/src/keymap/, and nothing else
decodes a scancode. Before it existed there were four independent decoders
(arch/x86_64/keyboard.rs set-1, arch/aarch64/pl050.rs set-2, xhci.rs HID
usages, arch/aarch64/virtio_input.rs evdev), each with its own modifier state,
its own copy of the arrow→CSI table, its own caps-lock rule (two had one, two did
not), and all four hard-coded to US. A driver's job now ends at "which
physical key was that, and which modifiers were down"; it builds a
KeyEvent { usage, mods, pressed, src } and calls keymap::feed_event.
Four facts forced that shape, and each is a constraint on any change here:
- x86 decodes inside IRQ1. So
feed_eventallocates nothing and only pushes a 4-byteCopystruct into a fixed ring;translate(which allocates — one press can emit several characters) runs on the drain side, inkeymap::next_byte. Do not move translation into a driver. arch::aarch64iscfg'd out of the x86 test build, from a differentcfgthanframebuffer/'s. So anything left inpl050.rs/virtio_input.rsis covered on one leg only —cargo xtask test -arch aarch64compiles and runs tests placed there,-arch x86_64cannot see them at all. That is why the set-2 and evdev cross-tables live inkeymap: a table both arches use should be pinned by both legs, not by whichever one happens to compile it.- Dead keys, Compose and the IME are stateful across keystrokes, and a machine
can have a USB keyboard and a virtio-input window at once (
console.rspolls both). Four states would mean´on one keyboard andeon the other fails to compose. Caps Lock lives inkeymap::Statefor the same reason. console::read_byte() -> Option<u8>does not change. The event type stops at the choke point; above it the OS still sees a byte stream, so the shell, editor, modals,poll_interruptand every e2e scenario are untouched.
HID usages are the canonical space because a layout maps a physical position
to a character, and set-1/set-2/evdev are positional too — the three cross-tables
are ~350 bytes of pure relabelling. An ASCII-based canonical space cannot express
"the key left of Y on an ISO board" (usage 0x64), which is where German puts
<>| and which no previous table decoded at all. Right Alt is its own modifier
bit: xhci read report[0] & 0x44, the OR of both Alts, into nothing, which is
precisely why AltGr never worked anywhere. Ctrl+Alt counts as AltGr too, as XKB
does, because many keyboards have no right Alt and a macOS host eats Option.
Layout data is in keymap/layouts.rs: a dense US_BASE plus per-layout sparse
overrides, four levels (Base/Shift/AltGr/ShiftAltGr), Out::None for an
undefined level (never a fallback to another level — that types a wrong
character rather than none). Nine layouts, ~11 KB of rodata, written out rather
than bit-packed on purpose: c('ö') in the wrong slot reads exactly like c('ö')
in the right one, so readability is the safety property. Two tests keep a
hand-written table honest — every layout can type all 26 letters and 10 digits,
and no layout lists a usage twice.
us_layout_reproduces_the_legacy_* are the migration gate. The four old
decoders' tables are copied verbatim into keymap's tests and every
scancode × modifier combination is asserted to produce the same byte. Two of those
drivers are invisible to the x86 leg, so this is the only place their behaviour is
pinned on both; do not delete these fixtures casually.
Scancodes cannot be injected over serial, so /keyboard test <layout> <keys>
exists to make the tables assertable from a running kernel — and it calls the real
keymap::translate, never a parallel path. A key is named by its US base
character with modifier prefixes (/keyboard test de altgr+q → @), plus named
keys for the ones with no character (iso is usage 0x64).
Bytes, chars and columns are three different numbers
kernel/src/textfit.rs holds the arithmetic, and the bug class it ends is worth
naming: String indices are bytes, terminal geometry is columns, and for
ASCII they are the same number — so the line editor, the composer and the modal
wrap all used buf.len() - cur as a column count and s.as_bytes().chunks(cols)
as a line break. The moment a non-ASCII character reaches them that is a panic
(buf.drain(cur - n..cur) on backspace; &line[start..start + max_cols] in the
composer), a caret in the wrong place, or mojibake. Use textfit::cols,
back_n_chars, visible_window, pad_trunc and wrap; never subtract byte
offsets to get a column count. wrap and pad_trunc moved out of
framebuffer/text.rs for the usual reason — a test written next to them would
never have been compiled, which is how wrap shipped silently deleting any word
whose byte-chunk boundary fell inside a character.
char_cols answers East-Asian width coarsely (0 for combining marks, 2 for
Wide/Fullwidth). The pane Cell grid is deliberately out of scope: it is
(char, Rgb) with one cell per character, so a wide glyph would need a lead cell
plus a continuation marker and then set_cell, the scroll row copy, the selection
maths and glyph_cell all change — inside the module where no test compiles. The
visible consequence, stated so nobody reports it as a bug: typed CJK is correct
in the composer (caret in the right place, backspace deletes one glyph) and renders
narrow once echoed into a pane, because font_ttf::build_ui_glyph scales a
non-ASCII glyph down into its cell. Cramped, not corrupt.
The IME ships what it can deliver honestly
kernel/src/ime.rs is a pure feed(char) -> ImeOut machine, fed after the
layout stage (so it composes over Dvorak and over AltGr output) and before
media_key (so a composing keystroke is never eaten by a focused app).
consumed: false is the regression guard: with Mode::Off it returns immediately
and the caller behaves exactly as before.
- romaji → kana is complete — hiragana and katakana, no dictionary, and every
glyph it can produce is inside the bundled CJK subset, so what you type renders.
The
nncase is the classic trap:nnis ん butnniis んに, so the secondncannot be resolved until the next character arrives. Converting it eagerly turns "konnichiwa" into こんいちわ. - Hangul is implemented, tested, and refused. Jamo→syllable is arithmetic
(
0xAC00 + (L*21 + V)*28 + T) plus the 2-set map and the compound merges. The bundled face has no Hangul glyphs, so it would compose perfectly and render tofu —set_mode_by_namerefuses with that reason andfont_ttf::fallback_coversis the gate, so bundling a Hangul subset later is a one-line change with tests already green. - Pinyin and kanji conversion are refused, naming the missing dictionary. A pinyin engine that knows 500 words is worse than none: the user types a word it lacks and gets silence or the wrong character, which is a mis-decode.
Two escape hatches are load-bearing, because an input method with no exit is a
trap: / and ~ are absent from the romaji table even though a real IME maps
them, and read_line bypasses the IME entirely on a line starting with / — so
/keyboard ime off is always typeable.
Also: the serial console now passes UTF-8 through rather than dotting out every byte ≥ 0x80. That filter was right while the OS could not hold non-ASCII text and became a lie the moment it could.
STANDING RULE — Ctrl+C interrupts every command and process
Any new command or long-running process must respond to Ctrl+C. A blocking
loop already has to pump shell::upkeep() (above); in the same loop it must
also poll for interrupt and bail when it fires — otherwise a stuck/streaming
command can only be escaped by killing the VM, which is not acceptable.
- A shell command / networked loop (
/http,/ping, DNS, TLS, a/ws-style stream, any future protocol client) callsshell::poll_interrupt()— true only on Ctrl+C (0x03), and it pushes any other byte back (console::unread) so it never swallows the next command's keystrokes. Return anErr("cancelled")/ break the loop on true. - An inference / decode loop calls
shell::poll_cancel()(Ctrl+C or bare Esc; a decode turn owns the console, so consuming input there is fine).
Both are cheap — call them once per loop iteration next to upkeep(). A command
that can block without an interrupt check is a bug; cover it with an e2e cancel
scenario (drive raw b"\x03" via guest.send_raw, assert it aborts fast and
the next command still runs) and a unit test on the pure poll logic
(poll_interrupt_ctrl_c_only_and_pushes_back, console::pushback_*).
There is exactly one documented exception: the login gate
(auth::prompt::gate). A gate you can Ctrl+C out of is not a gate. Ctrl+C and Esc
stay responsive there — they clear the typed field and repaint, so the key is
never dead — but neither returns from the loop. Do not "fix" it.
A kernel fault returns to the prompt instead of halting the machine
(fault_recovery.rs). sched::fault_current_task already contains a fault in any
task except task 0 — the shell — where the choice used to be a halt. The REPL now
arms a setjmp-style landmark at the top of its loop and the aarch64 sync
dispatcher, x86's #PF/#GP handlers and the Rust panic_handler jump back to
it. The point is the hardware loop: on a tethered Apple boot a halt costs the
framebuffer, the USB console, a model that took a minute to load and the state that
produced the bug, so a one-line bug used to cost a cold boot; and a halted AP is
also what a watchdog reset looks like from the outside. Six things this pins down:
- It never hides anything. The syndrome prints first, the recovery is counted, and the shell says it happened and suggests a reboot. A fault is still a bug.
- It refuses in three cases, and says which (
should_recover/refusal, both pure and tested): nothing armed (a fault during boot), aLockedis held — the abandoned frame never releases it and the next taker spins forever with interrupts off, which is worse than halting — or too many in a row. - "Are interrupts enabled" cannot answer the lock question here, which is why
mm::locks_heldexists (two relaxed RMWs insideLocked::with). That inference — the onesched::block_on's assert makes — needs interrupts to ever be on, andinitial_daifmasks them for every task on Apple Silicon, the machine this feature is for. - Restore the landmark's own IRQ mask, do not "enable interrupts". Unmasking on
Apple would let an interrupt reach a vector that dispatches into an absent GIC,
turning one fault into a fault loop.
LANDMARK_IRQ_ONrecords it at arm time. - The
longjmpmust load everything before it moves SP. The buffer sits on the faulting stack, below the landmark's SP; once SP is restored, an interrupt frame lands on top of it. Loadingd8-d15(or the x86 resume address) after the switch mirrors the save and is a race that surfaces as corrupt FP state much later. - Anything written between the save and the jump must live in memory, not in a
local — the oldest
setjmptrap, and it applies to the test that proves the asm works as much as toarm_hereitself.
Not covered, and stated rather than discovered: a fault inside an interrupt handler is abandoned without its EOI, so that source can stop delivering (a dead timer — impossible on the cooperative Apple path); and everything the abandoned frames owned is leaked.
The syndrome itself is now decoded rather than printed as three hex numbers
(mm::armv8::esr_class / esr_fault_status / esr_far_is_valid /
fault_pc_in_image, pure and tested on both arches because arch/aarch64/ is
cfg'd out of the x86 test build). Two of those matter specifically: a
translation fault and an alignment fault are one nibble apart in ESR and
mean completely different things (nothing mapped vs. a vector access to
Device-typed memory — the +strict-align and VirtualBox-mixed-GiB traps), and a
PIE kernel's ELR matches nothing in nm until the load base is subtracted, so
the handler prints the PC translated back to the link address plus the
llvm-addr2line command. That arithmetic-by-hand is the step CLAUDE.md already
records as the fastest tool here; the kernel knows its own load address and should
not make a human redo it.
STANDING RULE — human-only commands are absent from dispatch_system, not guarded inside it
/passwd and /lock (kernel/src/shell/auth.rs, [crate::auth]) are matched in
the interactive-only arm of the REPL, above the dispatch_system
fall-through, and must never move into dispatch_system. This is the security
property, not a filing decision:
run_shell_commandneeds no registry entry.tools/shell_cmd.rspasses any[A-Za-z0-9_-]+token straight todispatch_system, registeredToolDefor not — and it is inCORE_TOOLSand the orchestrator manifest. So the moment a human-only command gains adispatch_systemarm, every agent can call it, with no capability and no manifest change.- There is no
Right::Shelland noCapDomain::Shell. Shell commands are not capability-gated at all, so "don't grant the capability" was never available. dispatch_systemhas exactly one agent-reachable call site (run_tool_command), and everything funnels through it —run_shell_command,tools::bg::pump, theToolBinding::Shellexecutor, scheduledAction::Commandfires, Telegram-driven turns, package-UI apps and sub-agents. The last two callRouter::calldirectly and skiptool_in_chat_toolsetentirely, so a manifest toolset is not a boundary either. Being absent fromdispatch_systemcloses all of them at once, by construction.
The in_tool_call() refusals inside those handlers are defence in depth. Keep
them, and note that taint cannot answer this question: a Telegram DM enters
the session as Provenance::UserTyped, so UserTyped does not mean "a human at
this console". in_tool_call() is the only signal that does — and it is a depth
counter, not a flag, because bg::pump calls run_tool_command from inside
upkeep(), which long-running commands call, so a nested call's exit used to
clear the marker while the outer dispatch was still running (that bug also
affected /screenshot and /record). Pinned by
passwd_and_lock_are_unreachable_from_the_tool_surface and
in_tool_call_survives_a_nested_run_tool_command.
catalog::RESERVED_HUMAN_ONLY carries the names so /schedule add … command
passwd is refused at creation (a fire has no human at the keyboard, so it could
only ever fail — silently, at 3am) and no package manifest can claim one as a
command_hooks name.
STANDING RULE — key material comes from security::rng, never arch::hw_rand()
arch::hw_rand() returns 0 when RDRAND/RNDR is absent — which is every
QEMU and HVF default CPU model, i.e. every machine we develop and test on. A
caller that fills a buffer straight from it produces all zeros on exactly the
machines the tests run on, and real entropy only on hardware nobody tests against.
block::volcrypto::fill_random did precisely that, so every C4VE volume formatted
under QEMU had an all-zero salt and an all-zero master key — invisible, because an
all-zero key encrypts, decrypts, mounts and accepts its passphrase perfectly.
Use security::rng::fill_random / seed_rng (ChaCha20 over hardware words plus
cycle-counter jitter across yields). It cannot degrade to zeros: the diffuser folds
the cycle counter in unconditionally, which
entropy_survives_a_dead_hardware_rng pins with hw = 0 — the companion
"not all zeros" test alone passes under -cpu max even with the bug present.
net::tls::seed_rng is a re-export of the same function, so there is one
implementation. NB it yields, so it must not be called with a Locked held.
The login gate (kernel/src/auth/)
Single-user, fixed user chitti, independent of the volume passphrase. Boot gate,
/lock, idle auto-lock, and re-auth on resume from suspend. Pure logic in
auth/mod.rs; the blocking screen is auth/prompt.rs, #[cfg(not(test))] with a
deny-by-default stub.
The theme and the gate are applied together, as early as the store allows
(shell::boot_appearance_and_gate, called from all three main.rs arch entries
immediately after mount_persistent_store). ui.json, display.json,
panes.json and the credential record all live on the store, so nothing can be
themed or unlocked before it mounts — but everything after it can be, and used
not to be. Both started at the top of shell::run, which is the last thing boot
does, and the result was visible twice over: the whole boot log (drivers, network,
the agent roster, bundled skills, the sample corpus, schedules) was drawn in the
built-in palette at the default font scale and then recoloured and reflowed in one
jump, and the gate appeared only after the banner, the mount line and the
store-backend line had printed and the status bar was painted — so the machine
showed you its disk, its size, whether its store was durable, and a live battery
and clock, and only then asked who you were. Keep them there; run now prints
nothing before the console is unlocked, and the session resume (which prints the
previous session's id and message count) is well after it.
Seven things worth knowing before touching it:
- No record = no gate, anywhere. One state, one
fs::exists. That is also why the e2e harness needs no bypass flag: its guests run on a memfs store where nothing can ever have been enrolled, so every existing scenario is untouched. - The gate mirrors to serial and must keep doing so.
modal::inputrenders only to the framebuffer, so a modal-based gate is invisible to-serial mon:stdioand to the whole e2e harness — a machine that has silently stopped responding. It also returns""on Esc, which for an auth prompt is an empty password attempt, not a cancel. Hence its own loop. - It pumps
status_tick(), notupkeep(), and that is load-bearing. Besides the usual "a modal consumes its own clicks" reason, the shell task stays runnable throughout, so the scheduler never reaches the idle pump task — the only caller ofupkeep()— somsgchan::tick,schedule::tick,service::supervise_tickandtools::bg::pumpdo not fire behind the lock screen. A Telegram DM cannot drive an agent turn while the console is locked. Swapping inupkeep()looks like a harmless cleanup and silently opens that door. - The credential record is protected by two layers, and the second is the one
that enforces it. The Synapse executor denies
/configs/core/auth.jsonfor read and write/edit/delete (layered inside Gate 4 —GATE_COUNTstays 4, the paper's published contract), which is the correct statement of the policy. But/cat,/rm,/cp,/mv,/touch,/grepand/globareToolBinding::Shelltools that reachsynapse::fsdirectly and never enter the executor, so the refusal that actually holds is theCredentialAccessguard in the store facade.synapse::fs::listfilters the record out, which coversMEM_FS_LIST,MEM_FS_SEARCHandRouter::readable_paths(glob/grep/list_dir) in one place — and makesrm -rof an ancestor skip it by construction. - The idle timestamp already exists twice and covers everything.
console::read_bytestamps in the merged reader (serial, PS/2, xHCI/HID, virtio-keyboard, PL011) andmouse::activity_ms()is the pointer half. Do not add a third, and never callmouse::tick()to read it — that is a consuming poll that would steal the caller's clicks. The check is polled only inread_line's idle arm, because "idle" means idle at the prompt: it must not fire mid-/http, mid-inference or mid-video. - Resume auth goes at the end of
power::resume_devices(), after the i8042 is re-initialised and interrupts are unmasked — the controller comes back with its configuration byte reset, so a prompt placed earlier has no keyboard and the machine looks hung rather than locked. There rather than inrun_suspendso every resume path locks, including a future lid-close handler.
Honest limits, stated in the module doc and in /passwd's own output rather than
discovered: on an unencrypted disk the gate is bypassable offline in minutes
(mount elsewhere, delete the record) — it is a console lock, not
confidentiality, and /encrypt is what protects the data; on a memfs store it
does not persist; PBKDF2-HMAC-SHA256 is GPU-friendly (the kdf field exists so a
future argon2 is a migration); passwords are printable ASCII only, enforced at
enrolment because both input paths are; a reboot resets the backoff; and there is
no recovery path.
Build / run / test
Everything goes through cargo xtask. Arch is chosen explicitly, never
host-detected. See DEVELOPMENT.md for the full setup.
cargo xtask test [-arch x86_64|aarch64] # in-kernel unit suite under QEMU (default x86) — pure
# logic, no model. Keep BOTH arches green.
# x86: Limine ISO + isa-debug-exit. aarch64: a flat arm64
# `Image` (QEMU passes no DTB for an ELF, and no DTB means
# no GIC) + `gic-version=3` + TCG, verdict via a serial
# sentinel since `-M virt` has no isa-debug-exit.
cargo xtask ring-check # enforce the ring-3 rule: no direct synapse::executor
# calls outside the allowlist (xtask/src/rings.rs)
make e2e # end-to-end: boot the kernel, drive the shell over serial,
# exercise every OS command + the http/https/ws/wss/ping/
# hosted-model flows vs local servers (tests/e2e/, stdlib-only
# python; TLS scenarios need a TLS-1.3 python — Homebrew's)
# `make e2e E2E_JOBS=3` splits the sweep across 3 concurrent
# guest boots (~1 min vs ~13 min serial on a multicore Mac)
make e2e-full # + local inference (/infer,/perf,chat,/compact) and voice
# (/voice say) — slow; needs assets/model.gguf + assets/voice/
cargo xtask build -arch x86_64|aarch64 # cross-build the kernel
cargo xtask run -arch x86_64|aarch64 # boot in QEMU (aarch64 = native HVF on Apple Silicon)
cargo xtask image -arch x86_64|aarch64 # assemble a bootable image/ISO
cargo xtask sample-files [--refresh] # fetch the /samples corpus into assets/samples/
# (the build paths do this for you — see below)Every decoder needs a file, and a fresh boot has none — which made the media
stack (ring-3 PNG/JPEG, H.264+AAC, MP3/WAV/AAC, the PDF wasm, the editor's
highlighters) awkward to even try without /http -O first. So a ~15 MiB corpus is
embedded in the image and seeded into the store at boot — /samples/images/,
/samples/videos/, /samples/audios/, /samples/misc/, /samples/js/
(authored scripts for /js, from assets/samples-src/js/), plus a
/samples/README.md recording each file's source and licence — and
/open /samples/images/fruits.jpg works offline on the first boot
(kernel/src/samples.rs, SAMPLE_FILES in xtask/src/main.rs,
kernel::build.rs's directory walk).
Five rules it follows, each of which is a way this could have gone wrong:
- Opt-in, and default-on only for the dev flows.
CHITTI_SAMPLE_FILESgates it;make run|run-remote|run-uefi|image|vbox|m1n1|e2eset it (theSAMPLESknob), and a plaincargo xtask build/ CI /cargo xtask testembeds nothing, so those kernels are byte-identical to before. Empty reads as unset —makepasses the variable through unconditionally, the same trapCHITTI_RESOLUTIONhit. - Fetched, never committed (
assets/samples/is gitignored), so the tree redistributes nothing and no licensing decision was needed — the same rule the voice and WiFi assets follow. A failed download is a warning, not a failed build: the OS is fully functional without samples, and the alternative is a machine with no network being unable to build. - One definition, walked not duplicated. xtask owns the table (URL,
destination, provenance, and an
openableflag);kernel/build.rswalks the directory and generates theinclude_bytes!table. A second list in the kernel would be a second thing to drift. - Seeding never overwrites. On an installed system the store is ext4-backed
and durable, so re-writing every boot would silently revert a sample the user
edited;
samples::seed_planwrites only absent paths (and is unit-tested on exactly that). - A format with no decoder is labelled, not omitted.
sample.oggis there as the next decoder's input, marked unopenable, and the corpus test asserts every openable entry has an extension/openreally handles — so a.flaccannot creep in as a file that only ever errors. - A one-page fixture is not a document, and the PDF set says so. A synthetic
single page had made the renderer's limits look generous; the first real paper
needed twice the memory. So
/samples/misc/carries the shapes that actually differ:pdflatex-4-pages.pdf(24 KiB — the cheap multi-page case for e2e),pdflatex-image.pdf(an embedded colour JPEG, i.e. DCTDecode, which no vector-only document reaches) andgeotopo.pdf(117 pages with 19 JPEG figures — long-document navigation, ~0.5 s/page). - Freely redistributable is a stricter rule than "fetched, never committed".
A
CHITTI_SAMPLE_FILESbuild embeds these bytes in a kernel image and images get passed around, so it is not enough that the tree carries no copy. That is why the corpus holds no arXiv paper: the default arXiv licence lets arXiv distribute the PDF, not third parties. Fetch such a document on the running OS with/http -O <url>instead — which is also how the renderer's limits were measured (the Transformer paper, arXiv:1706.03762, whose two attention-matrix pages remain the heaviest thing measured here: 56 MiB of guest memory and ~6.9 s each at pane fit). Reproduce withtools/pdfbenchon any local copy.
Conventions
- The OS is named
ChittiOS— one word, no space. Use it everywhere: docs, boot banner, status bar, SOULs, served pages, commit messages. "Chitti" alone refers to the project/brand; the spaced two-word form is wrong — fix it on sight (and rebuild anytools/*-wasmmodule whose strings embed it). - No
unsafewithout an adjacent// SAFETY:comment justifying each invariant. - Every public module has a doc comment stating its responsibility.
- Deterministic by default: tests use fixed seeds + temperature 0; any RNG is seeded.
ktraceevery capability invocation and every inference call.- Commit per sub-milestone with a clear message; never leave the tree non-building.
- Match the surrounding code's style, comment density, and idioms.
Status
Active development — not stable. Interfaces, on-disk formats, and behaviour change without notice. This is a research OS; run it in a VM. See the caution in README.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

