The field guide.

01 / ARCHITECTURE

Follow a request

A Kingdom is one operating-system instance. Court runs in user mode (Ring 3). Submitting a command crosses into the Crown’s privileged code through a narrow experimental service interface. The Crown derives the caller from trusted execution state and checks the requested operation.

An application cannot gain Court’s launch permission by copying its request. Its own instance receives only the operations and finite resources approved for its catalog entry. These experimental grants are not a permanent capability ABI.

02 / INTERACTION

Read Court’s instruments

kingdom reports kernel and CPU status. apps lists the compiled catalog; app inspect hello explains an entry’s limits. tasks shows the protected application’s state, while warriors shows the earlier kernel-task demonstration. They describe different execution contexts.

Commands are lowercase and bounded to 64 printable ASCII bytes. help lists available commands; clear changes the display without restarting the app. Court remains an unauthenticated development interface.

03 / HANDS-ON

Run the development VM

This tour is for developers who already have the source checkout. There is no public release image. The reference host is Ubuntu 24.04 under WSL2 with Rust 1.90.0, Python 3.11+, QEMU x86 and OVMF firmware.

Prepare the checkout

From its root in WSL, use the project’s setup instructions in docs/development.md. With the prerequisites installed:

bash scripts/bootstrap-rust.sh
source scripts/env.sh
cargo fetch --locked
python3 scripts/doctor.py --output build/environment.json

Start Court

In WSL Bash:

python3 scripts/play.py --workshop

Or from the repository root in Windows PowerShell:

.\play.cmd --workshop

The launcher gives a single virtual CPU 256 MiB of RAM and connects this terminal to the guest’s COM1 serial port. Wait for court>. Ctrl-C stops the disposable VM. No host disks or network are attached.

04 / FIELD EXERCISE

Who owns those frames?

A virtual address names a location within an address space. A physical frame is a 4 KiB unit of memory. The page table connects the two; an ownership record says who may eventually release that frame.

1. Use service to check the finite boot service. Wait until its attempts finish and the application slot is free.
2. Type memory, then app run counter. Use tasks twice. Look for one generation with increasing progress.
3. Check memory again. Enter task stop N, substituting the observed generation. Check the frame count once more.

In the qualified workshop, allocated frames go from 17 to 27 and back to 17. The application owned ten frames. Fourteen remain with live Court and three with retained infrastructure. Asking for the old generation to stop a second time should be denied.

Knowledge check: Why must the kernel remove an old mapping before reusing its physical frame for a different application?

05 / GLOSSARY

Names with engineering meaning

Kingdom

An operating-system instance that hosts applications and services.

Crown

The authority-enforcing side of the system. It checks requests independently of the shell.

Court / Court Chamber

Court is the command shell; a Chamber is a session endpoint. Holding Court will mean an authenticated Earl actively participating. Today’s console has no authenticated Earl.

Warrior

An execution context; the initial Warriors demonstrate cooperative kernel tasks with guarded stacks.

Guildhall

The provisional catalog of approved demonstration applications. Installation and authority to run are separate.

Earl / Realm

A future authenticated principal and the home of that Earl’s personal belongings. Ownership and recovery semantics remain open.

Royal Decree

A proposed exceptional grant of bounded authority. No general decree mechanism exists.

Roads / Parley

Vocabulary for future network paths and external or inter-Kingdom communication. No native protocol is selected.