Skip to content

Engineering

How AriCodeOS is built

A written plan, recorded decisions, automated tests on every change and audits with evidence. Failures are not hidden: they are reproduced, studied and fixed with a test.

Principles

Ten rules that must not be broken

  • Small kernel
  • Secure by default
  • Isolated drivers
  • Legacy compatibility outside the kernel
  • Explicit APIs
  • No legacy without justification
  • Test before integrating
  • Every privilege must be explainable
  • Every unsafe must be justifiable
  • Every important optimisation must be measurable

Compare, then reuse or improve

What “from scratch” means here

Not writing every line: studying the established implementations and their failures, measuring ours against them for compatibility and for how fast the system runs, and keeping the winner (ADR 0063). Adopted code must carry a permissive licence; GPL and proprietary code are not accepted.

Adopted

RustCrypto and the dalek crates for SHA-2, AES-GCM, ChaCha20-Poly1305, Ed25519 and X25519; rustls and rustls-webpki for TLS and X.509; wasmi for WebAssembly.

Kept and improved

The kernel, its drivers and services; the SSH server, with ML-KEM and key re-exchange; TCP, with its transmission rebuilt; ECDSA and RSA verification, HMAC, HKDF and the kernel generator, which measured faster.

15–35×
WebAssembly inside AriCodeOS with wasmi (ADR 0071)
0.12 → 1.15 MB/s
SSH output on the reference laptop, after rebuilding TCP
31 → 10 ms
Echo of a key over SSH, in QEMU (ADR 0069)
−37 %
SSH send cost per byte (ADR 0068)

Decisions

85 architecture decisions

Each decision that shapes the system is recorded as an ADR with its context, the alternatives considered and the consequences.

  • ADR 0001 · Rust no_std as the kernel language (versus AriCode)
  • ADR 0002 · UEFI-only boot
  • ADR 0003 · Pragmatic microkernel
  • ADR 0004 · Capability-based security
  • ADR 0005 · User-space drivers
  • ADR 0006 · The uefi crate in AriBoot
  • ADR 0007 · Test behaviour via the command line, not features
  • ADR 0008 · Stable Rust only; interrupt stubs in generated assembly
  • ADR 0009 · Linear physical map built by the loader
  • ADR 0010 · Kernel objects by handle with generation and rights
  • ADR 0011 · Service lifecycle and queryable status
  • ADR 0012 · Deadlines, correlation and retries in IPC calls
  • ADR 0013 · User-space keyboards as console input
  • ADR 0014 · AriFS persistence: checksums, journal and flush
  • ADR 0015 · Asynchronous launches and observable limits
  • ADR 0016 · Per-resource permissions: read-only shared files
  • ADR 0017 · Out-of-tree applications installed in AriFS
  • ADR 0018 · Transactional package installation and update
  • ADR 0019 · aricode-wasm v1 profile and validation
  • ADR 0020 · Receiving from several endpoints (ipc_receive_any)
  • ADR 0021 · Standard UEFI memory types in AriBoot
  • ADR 0022 · MSI in addition to MSI-X for user drivers
  • ADR 0023 · USB storage as a block service inside usbd
  • ADR 0024 · Shared network core and Realtek r8169 driver
  • ADR 0025 · SSH server with session shells launched by init
  • ADR 0026 · HTTPS with a TLS 1.3 client and X.509 verification
  • ADR 0027 · System updates over the network
  • ADR 0028 · Failure protocol, strict mode and fault events
  • ADR 0029 · Update sources and the signed update index
  • ADR 0030 · Peer-gone notification on IPC endpoints
  • ADR 0031 · User-space EHCI driver with USB 2.0 hubs
  • ADR 0032 · Boot self-tests only on request
  • ADR 0033 · An absolute budget for every HTTP fetch
  • ADR 0034 · TCP secrets: initial sequence numbers and ephemeral ports
  • ADR 0035 · TCP listener protection: backlog cap, SYN|ACK budget and reset
  • ADR 0036 · File descriptors follow their client
  • ADR 0037 · Sockets follow their client
  • ADR 0038 · DMA buffer lifetime
  • ADR 0039 · The entropy source is visible
  • ADR 0040 · Parallel test runner and CI container
  • ADR 0041 · Agents work from outside the trusted base (proposed)
  • ADR 0042 · Official drivers, protocol stability and licensing (proposed)
  • ADR 0043 · Kernel seed carried across boots
  • ADR 0044 · One wait for IPC, IRQ and deadline
  • ADR 0045 · Development update channel
  • ADR 0046 · The compositor flushes damage at a frame cadence
  • ADR 0047 · A session console for programs launched from an SSH shell
  • ADR 0048 · HTTP redirects, and a public update source
  • ADR 0049 · Zero-fill pages on first touch, and running out of memory
  • ADR 0050 · The file service’s authority, closed on every path
  • ADR 0051 · Addresses a PCI device reports are checked before use
  • ADR 0052 · Compositor sessions: a window belongs to the client that made it
  • ADR 0053 · Applications never get the raw input services
  • ADR 0054 · Distrusted certificate keys, refused anywhere in a chain
  • ADR 0055 · WASM fuel counts work
  • ADR 0057 · Handle values are not reused early, and console input belongs to its reader
  • ADR 0058 · The subject common name is never a host name
  • ADR 0060 · Damaged update state fails closed
  • ADR 0061 · An interrupt line masks only its own source; MSI-X only where it is still in place
  • ADR 0062 · No wildcard over a public suffix
  • ADR 0063 · Compare, then reuse or improve
  • ADR 0064 · System image downloads go through UPDATE
  • ADR 0065 · SIMD in user programs
  • ADR 0066 · Adopted cryptography, measured against ours
  • ADR 0067 · TLS and X.509 through rustls and rustls-webpki
  • ADR 0068 · SSH server kept, with ML-KEM, key re-exchange and a faster send path
  • ADR 0069 · sshd waits once for the client and the shell
  • ADR 0070 · TCP kept, its transmission rebuilt after comparing it with smoltcp
  • ADR 0071 · WebAssembly through wasmi, profile v2
  • ADR 0072 · AriFS v2, copy-on-write replace and a larger partition
  • ADR 0073 · Signed driver packages and three trust levels
  • ADR 0074 · A base system and an optional desktop profile
  • ADR 0075 · The PS/2 keyboard and touchpad in the desktop
  • ADR 0076 · Text beyond ASCII: the Spanish keyboard as Linux types it
  • ADR 0077 · The close box of a window
  • ADR 0078 · A desktop worth the name
  • ADR 0079 · The panel’s own size when the firmware does not offer it
  • ADR 0080 · One path from programs to the hardware
  • ADR 0081 · Windows with two buffers
  • ADR 0082 · Threads in a process
  • ADR 0083 · The GPU engine on the HD 4000
  • ADR 0084 · Memory for big programs
  • ADR 0085 · Resizing windows by their edges and corners
  • ADR 0086 · Compute on the HD 4000, without a compiler
  • ADR 0087 · Plug and play on the xHCI root ports

Measured, not guessed

Optimisations chosen by the numbers

Figures from QEMU with TCG on the development machine, p50. They compare builds with each other; they do not predict real hardware.

10 ms → 46 µs
IPC call to the file service (ADR 0020)
712 → 141 µs
4 KiB read, after sector batching
5.7 → 2.6 ms
4 KiB atomic replace, one flush fewer
99 ns
Empty system call round trip

Process

Branches, tests and audits

Git flow

main, develop and feature, fix and hotfix branches. Small commits with descriptive messages; the whole QEMU suite must pass before anything reaches main.

Audits

Important milestones are audited and the findings recorded with evidence. Hotfix versions (0.1.1, 0.3.1, 0.4.1, 0.5.1, 0.8.1) carry the fixes.

Failure protocol

Record, reproduce, study from several angles, confirm with evidence, fix with a test, audit, close. In strict mode a component halts at its first unexpected failure instead of looping.

Incident 0001 — transaction errors on the laptop’s USB stick — was investigated with three independent studies, strict-mode dumps and measurements on the host before any fix was accepted.