VectraOS Design

Control plane

Every service exposes a 9P-shaped node tree: walk, stat, readdir, read, write, watch, create and remove. Namespaces are per process and have no global root; a sealed namespace is the sandbox.

Typed interfaces declared in Swift, with zero-allocation stubs
Each service directory describes itself with .help and .schema
Requests travel on channels, batched: one channel_call carries many operations

Data plane

A client opens …/ring on a service and receives a VMO and a counter. That exchange is the only way a ring comes to exist, and a ring is never the only way to reach a service.

One SPSC ring format for input, audio, frames, packets, blocks and tensors
Doorbells are counters, rung only when the other side is asleep: ring_kicks = 0 under load
Large payloads travel by reference into a shared data VMO

The one ring

One layout, every bulk path

Cursors are free-running 64-bit counters, each alone on a 128-byte line, so neither 64- nor 128-byte cache lines share them. The producer writes a slot and store-releases its cursor; the consumer load-acquires it, reads, and releases its own. One implementation in Swift, one C23 header for C-side drivers, both tested against the same model checker.

architecture §3 · ring layout

0     producer cursor  u64, release
128   consumer cursor  u64, release
256   header           magic, version, slot size,
                       slot count (power of 2),
                       format descriptor, flags
384+  slots[count]     wire format or raw bytes

Layers

The system map

The kernel

croi, a rewrite of Zircon in Embedded Swift, cut down to the setup-engine role. Handles and rights, VMOs and VMARs, jobs, processes and threads, EDF scheduling contexts with admission control and deadline donation, channels, ports, counters, futexes, timers, interrupts and MSIs, the IOMMU, the pager and trace. It boots through UEFI and ACPI only, and it has no ARC: everything is owned.

Services and drivers

Ordinary user processes in tier 0 Embedded Swift: namespaces, launch, the device manager, Taisce, the Radharc compositor, the plumber, the network stack, 9gate and the accelerator service. Drivers get their DMA memory as capabilities.

Taisce

The one file system. Typed attributes, declared indices, queries with ranges and ordering, and live queries that report additions, removals and changes. On disk: copy-on-write B+trees, checksums on every pointer, and an intent log.

The desktop

Radharc, a retained layer tree with late latching. Each workspace is tile or space, switchable live; both arrangements persist as Taisce attributes, so switching back loses nothing.

The swarm

9gate is the only thing that speaks 9P2000.L. It exports a subtree to the network, which Linux v9fs and 9front mount unchanged, and imports remote servers as nodes. Between VectraOS peers it adds attributes, queries, leases and ring bridging, over Noise IK.

Compute and Wasm

Accelerators are nodes under /dev/accel. A host compiler lowers models to TOSA in one artifact; a first-party executor runs it on the CPU, Adreno or the Hexagon CDSP. Wasm apps are ordinary processes whose WASI imports map onto nodes and rings.

The names

Why the Irish

The larger parts of VectraOS and the projects it grew from carry Irish names. Commands and paths keep short Plan 9 names (fs, /net), and the repository writes the names without the fada (croi, todhchai). Pronunciations are rough English approximations.

Name	Say it	Means	What it is
croí	kree	heart	The kernel: a rewrite of Zircon in Embedded Swift, at the heart of the system
Taisce	TASH-keh	store, hoard, treasure	The file system, which keeps what's yours with typed attributes and answers live queries
Radharc	RYE-ark	sight, view	The compositor: everything you see on the screen passes through it
todhchaí	TOW-khee	the future	The earlier project that gave VectraOS its performance contracts, Taisce, Radharc and the SDK

Normative

The twenty-nine principles

A change that breaks one needs a dated entry in the decision log explaining why.

#	Principle
A. One way
01	One mechanism per job. Adding a mechanism means removing or refusing another.
02	The base system fits in one head. Every component publishes its line count, and a check enforces the total.
03	Every layer must pay rent: measurably faster, safer or simpler for the programs above it.
B. The data plane and the control plane
04	The kernel is a setup engine. Bulk data never passes through it.
05	Nodes are for control and discovery; rings are for bulk. A ring is never the only way to reach a service.
06	One ring format.
07	One wire format: little-endian, aligned, decoded in place. No JSON, protobuf or FlatBuffers on the device.
08	One buffer currency: a VMO, a format descriptor and a timeline fence.
C. Time and threads
09	One wait for everything: a port.
10	Time is an absolute deadline plus a leeway.
11	Threads declare intent, never priority; realtime is admission-tested.
12	Batch by default. Hot interfaces take arrays with counts.
D. Contracts
13	Performance numbers block releases. A budget with no check running is not a budget.
14	The tool that measures is the tool that explains. Budgets are read from trace events.
15	A budget is never loosened in the change that would fail it.
16	v1 promises are permanent, so v1 promises little.
17	Errors are values: typed throws in Swift, status codes at the C ABI.
E. Data you can see and query
18	Files carry typed attributes, and the file system answers live queries.
19	The system shows what it is doing.
F. The developer's joy
20	The platform is a library the app calls, not a framework that calls the app.
21	A minimal windowed app takes at most 12 API calls.
22	APIs grow out of real programs.
23	Debugging and hot reload are OS services.
24	Apps are single files; installing one means copying it.
25	One front door: `vx` builds, boots, tests, benches, traces and runs CI.
G. Ownership and authority
26	Capabilities, not ambient authority. A process's namespace is its sandbox.
27	Local first. Nothing leaves the machine, or the user's own swarm, unless a policy says so.
28	The device runs only our code. Heavy toolchains stay on the host; required firmware blobs are listed with their provenance.
29	Swift first, C23 where necessary. Each C file names its reason.

Provenance

Three projects, one system

VectraOS joins three earlier projects. Where two solved the same problem, one solution wins and the other goes.

Source	What it gives VectraOS
croi	The kernel, the UEFI loader and the arch code, already Embedded Swift and C23
todhchai	Performance contracts, the Node protocol and typed IPC, Taisce, the Radharc compositor and the SDK
NeoVectra	The "one mechanism per job" rule, the ring and doorbell data plane, the swarm design and the Q8B hardware notes
AbyssBSD	Hardware reference only: the Q8B's and the Orange Pi 6 Plus's ACPI facts, consoles, Ethernet, GPU power-up order and NPU notes

The blueprint

Read it in full

The design lives in the repository, next to the code it governs.

Doc	Contents
Vision	What we are building, and what we take from the Scalable Edge Architecture paper
Principles	The twenty-nine rules every change follows
Architecture	How the layers fit: kernel, the ring, the Node protocol, the swarm, Taisce, the desktop, compute, Wasm
Performance	The budgets and how they are enforced
Provenance	Which code comes from which repository, and why
Decisions	The dated decision log, one file per decision
Roadmap	The milestones and their exit criteria
Syscall audit	V1's audit: which calls stay, which go, and what replaces them
Trace format	The trace record the budgets are read from
Kernel	The kernel's rules, roadmap, design notes per subsystem, and its divergences from Zircon

The kernel is a setup engine.