Understanding PangeaOS: Design Philosophy & Architecture Report

1. The Core Problem: Speed vs. Safety in Operating Systems

Every modern computer runs many pieces of software at the same time: a network driver talking to your Wi-Fi card, a storage driver reading files from your disk, system services managing data, and applications. The job of the operating system is to coordinate all of these programs so they can work together smoothly without interfering with one another.

To keep programs from accidentally overwriting each other's data, mainstream operating systems like Linux, Windows, and macOS build thick virtual walls between every running program. They give each program its own private map of memory (called a virtual address space). Furthermore, they run ordinary programs in a restricted processor mode (User Mode, or Ring 3) while keeping the core operating system in a privileged processor mode (Kernel Mode, or Ring 0).

Why Those Walls Slow the Computer Down

Putting every program in its own separate world is great for safety, but it creates a constant performance bottleneck whenever programs need to cooperate:

1. Crossing the Border Takes Time: Every time a program wants to send a message to another program or ask the operating system for help, the processor has to stop what it is doing, save its current state, switch from User Mode to Kernel Mode, and validate the request.
2. Swapping Out the Memory Map: When the processor switches from Program A to Program B, it must load a completely different memory address map. Doing this forces the processor to throw away cached memory lookups, which slows down the next several thousand instructions while the cache warms back up.

The Single-Space Idea—and Why It Used to Be Dangerous

For decades, computer scientists have asked: What if we removed those walls? What if the operating system kernel, device drivers, and services all lived inside one shared memory address space (known as a Single Address Space Operating System, or SASOS) and ran at the same processor level (Ring 0)?

When everything lives in one shared space, switching from one task to another requires no map swapping and no mode transitions. Communication becomes as fast as calling a normal function inside a single program.

However, early attempts at building single-space operating systems ran into two serious problems:

• No Protection Between Neighbors: If every program shares the same room and has full hardware privileges, a single bug or stray pointer in a device driver can accidentally overwrite the core operating system's memory.
• Halting the Whole Machine on Any Error: Because early single-space systems could not tell whether a bug had damaged shared memory, their only safe response to an unexpected error was to call panic!() and freeze the entire computer. That meant a single bad network packet or a minor bug in a background service would bring down the whole system.

---

2. How PangeaOS Solves Both Problems

PangeaOS v1.2.4b is an experimental operating system written in Rust that keeps the speed of a single shared address space while solving both of the historical safety problems:

1. Compartments Without Context-Switch Delays: Instead of swapping out the entire memory map when switching between programs, PangeaOS divides the single 64-bit address space into separate zones and locks each zone with a hardware keycard built into modern x86-64 processors.
2. Local Quarantine Instead of Global Panics: PangeaOS refuses to shut down the whole computer when a single service fails. Whether a service crashes, tries to touch memory it does not own, gets stuck in an infinite loop, or asks for too much memory, PangeaOS isolates and resets only that one broken service while every other service continues running.

---

3. The Seven Layers of Protection in PangeaOS

Because PangeaOS does not rely on the traditional wall between User Mode and Kernel Mode, it uses seven cooperating layers of defense. Think of these layers like the safety systems in a modern building: badge scanners at the door, locks on individual offices, smoke detectors, and emergency exits.

Layer 1: Writing the OS in Safe Rust

The majority of PangeaOS (16 out of its 26 software modules) is written in safe Rust with a strict rule (#![forbid(unsafe_code)]) that forbids raw pointer manipulation. Rust's compiler checks memory ownership before the program is even compiled, eliminating common bugs like reading freed memory or freeing the same memory twice. Low-level hardware code that requires unsafe Rust is isolated inside 10 small, heavily audited modules.

Layer 2: Pre-Launch Machine Code Inspection (bincheck-core & domain-verify)

Safe source code is not enough on its own, because the processor ultimately executes compiled machine instructions. Since all programs in PangeaOS run at the processor's highest privilege level (Ring 0), a program could try to cheat by containing special processor instructions that turn off interrupts or unlock other programs' memory keys.

To make sure this never happens, PangeaOS inspects the compiled machine code of every service before it is allowed to run:

• Checking Every Instruction Against an Allowlist: The scanner reads the program's machine code from start to finish, making sure every single instruction is on an approved list of normal math, logic, and memory operations. Any instruction that modifies processor control registers, disables interrupts (cli), or changes memory keys (wrpkru) is blocked before boot.
• Keeping Each Service Inside Its 1-Terabyte Sandbox: PangeaOS supports up to 12 isolated service compartments (called Domains 1 through 12). Each domain is given its own 1-Terabyte slice of the address space. The pre-launch scanner verifies that memory reads and writes inside Domain 3 only target addresses inside Domain 3's 1-Terabyte window.

Layer 3: Hardware Memory Keycards (MPK / PKRU, Keys K0 to K15)

In addition to checking code before launch, PangeaOS uses a live hardware security feature on modern x86-64 CPUs called Memory Protection Keys (MPK). Every 4-Kilobyte page of memory is tagged with one of 16 hardware keys (K0 through K15):

• Key K0 (Core Kernel): Protects the central operating system (Domain 0), including the task scheduler, security records, and capability table.
• Keys K1 through K12 (Isolated Services): Each of the 12 service domains gets its own private key. Domain 1 uses K1, Domain 2 uses K2, and so on.
• Key K13 (Address Map Vault): Protects the memory pages that store the address map (page tables) itself. Even when the core kernel is running, K13 is kept locked as Read-Only so a stray pointer cannot corrupt the address map.
• Key K14 (Message Mailbox): Protects the counters used when services send messages to each other. Services can read these counters, but only the kernel's message broker can change them.
• Key K15 (Quarantine & Shredder): Protects memory pages that are being wiped clean after a service finishes using them.

While Service Domain 3 is running, the CPU's internal keycard register (PKRU) only unlocks K3 for reading and writing, and K14 for reading. All other keys—including the core kernel's K0 and every other service's key—are locked by the processor hardware. If Domain 3 tries to touch Domain 4's memory, the CPU immediately stops the instruction and triggers a hardware fault.

Layer 4: Harmonizing Code Execution and Data Keys on x86-64

There is an important technical detail in how x86-64 processors handle Memory Protection Keys: the hardware keycard register (PKRU) only checks pages that are marked with a specific page-table flag (U/S=1). However, x86-64 processors also have a security feature called SMEP that prevents the CPU from executing program instructions from pages marked with U/S=1 while running in Ring 0.

PangeaOS makes these two hardware features work together seamlessly:

• All program code pages (which are read-only and never modified at runtime) and emergency interrupt stacks are marked as Supervisor pages (U/S=0). This allows the CPU to execute instructions in Ring 0 without triggering SMEP faults.
• All data pages, heaps, and service stacks are marked as non-executable (NX=1) and tagged with U/S=1 plus their protection key (K0 through K15). This ensures that the hardware keycard (PKRU) strictly polices every single data read and write, while the processor refuses to execute data as code.

Layer 5: Guarded Security Doors (gate-asm)

If a service domain is not allowed to change its own hardware keycard (PKRU), how does it ask the core kernel for help? It must pass through a Security Gate (gate-asm). A security gate is a small, fixed sequence of assembly instructions at a known address. When Domain 3 calls a gate, the gate verifies that Domain 3 is really the active domain, checks that its permission token (Capability Handle) has not expired, and confirms that any data buffer it passed lies completely inside Domain 3's 1-Terabyte workspace. Only after those checks pass does the gate unlock K0 to perform the requested work, locking K0 again before returning to Domain 3.

Layer 6: Controlling Hardware Devices (hal-iommu & hal-core)

Network cards and disk controllers can write directly to computer memory using Direct Memory Access (DMA), bypassing the CPU altogether. To prevent a faulty or malicious plug-in card from overwriting kernel memory, PangeaOS starts every PCIe hardware device with its DMA switch turned off (Default-Deny). A device is only allowed to turn on DMA after the system's IOMMU (Input-Output Memory Management Unit) has locked the device into its own approved memory pages. Additionally, when PangeaOS reads hardware configuration tables (ACPI) from the motherboard at boot, it uses a strict verifier that checks table sizes and checksums and refuses to run executable firmware scripts (AML bytecode).

Layer 7: Stopwatches, Quotas, and Emergency Reserves (pangea-watchdog & pangea-sched)

To stop a broken service from hogging the computer:

• 1-Millisecond Preemptive Timer: A hardware timer interrupts the running service every 1 millisecond. If a service is stuck in an infinite loop, the scheduler pauses it on the first overrun so other services can run, and quarantines it if it keeps overrunning.
• Non-Maskable Interrupt (NMI) Watchdog: If a service manages to stall normal timer interrupts, a high-priority NMI signal detects that the heartbeat counter has stopped and quarantines just the stalled service.
• Memory Quotas & 16 MiB Kernel Reserve: Every service has a hard cap on how much memory it can allocate. Even if several services try to allocate memory at once, PangeaOS keeps 16 Megabytes of RAM permanently reserved for the core kernel (Domain 0) so recovery operations never run out of memory.

---

4. How PangeaOS Classifies Errors: Local vs. Fatal

Instead of treating every unexpected event as a reason to crash the computer, PangeaOS sorts every anomaly into one of seven categories:

Category	Plain Description & Example	What PangeaOS Does	Does the Computer Stop?
L0: Bad Request	A service passes an invalid buffer size, an out-of-range queue number, or an expired permission token.	Rejects the request with an error value, adds 1 strike to the caller's record, and continues running.	No
L1: Service Crash	A service hits a CPU fault (such as dividing by zero, executing an invalid instruction, or touching locked memory) or calls panic!.	The CPU jumps to the emergency rescue stack, locks out the crashed service, revokes its tokens, and returns control to the scheduler.	No
L2: Over Budget	A service runs past its 1 ms time limit, asks for more memory than its quota allows, or fills up a message queue.	Pauses the service (or quarantines it on repeat offenses) and rejects excess memory/message requests without affecting other services.	No
L3: Device or Restart Storm	A hardware device floods the CPU with interrupts, or a crashed service fails repeatedly even after being restarted.	Turns off the faulty device's DMA access, or marks the repeatedly failing service as permanently disabled (Restricted Mode).	No
F1: Core Kernel Damaged	An unexpected fault happens inside the core kernel (Domain 0) itself, or a security canary is corrupted.	Because the core referee itself is damaged, PangeaOS safely halts all CPU cores (Global Fail-Stop).	Yes
F2: Physical Hardware Failure	The processor reports an uncorrectable physical memory or silicon error (Machine Check Exception).	Halts the system immediately so corrupted data is never written or trusted.	Yes
F3: Unconfirmed Cleanup	When reclaiming memory, a CPU core or device fails to confirm that it cleared its address cache within the time limit.	Permanently locks the affected memory pages in quarantine so they are never reused by another program.	Only if isolation cannot be kept

---

5. Step-by-Step: How PangeaOS Survives a Live Hardware Crash (v1.2.4b)

One of the hardest problems in a Ring-0 operating system is surviving a real hardware exception—such as when a service executes an illegal instruction or touches a locked memory page.

Why is this tricky? Because when a service is running, its hardware keycard (PKRU) has the core kernel's memory (K0) locked, and its stack pointer (RSP) might be pointing to broken memory. If the CPU tried to run the crash handler using the crashed service's stack and keycard, the crash handler itself would immediately fault!

In version 1.2.4b, PangeaOS wires the following four-step rescue sequence directly into the x86-64 processor hardware and tests it live on QEMU:

1. Step 1 — Hardware Jump to an Always-Unlocked Emergency Stack (IST 1): At boot, PangeaOS loads its own 64-bit Global Descriptor Table (GDT), Task State Segment (TSS), and 256-entry Interrupt Descriptor Table (IDT). Inside the TSS, we configure four dedicated emergency stacks (IST 1 through IST 4). The instant a service triggers a hardware fault, the processor hardware automatically switches the stack pointer to IST 1, which is always unlocked.
2. Step 2 — Unlocking the Kernel's Master Keycard: The assembly entry stub saves the crashed program's registers onto IST 1 and immediately writes the kernel's default keycard mask (0xCBFF_FFFC) into the PKRU register. Now the kernel has full access to its own K0 memory again.
3. Step 3 — Pivoting to the Kernel's Private Stack (k0_priv_rsp): To make sure IST 1 is immediately free in case another interrupt arrives, the stub checks a 64-bit security canary word ("PANGEAK0"), copies the saved crash frame onto the kernel's private exception stack (k0_priv_rsp), and switches RSP to that private stack before calling our Rust crash handler (pangea_rust_isr_entry_bridge).
4. Step 4 — Jumping Back to the Scheduler (gate_restore_continuation): Every time the scheduler starts a service via invoke_domain_live, it saves a "bookmark" of the scheduler's own registers and return address (SchedulerContinuation) inside protected K0 memory. When the Rust crash handler sees that Domain 5 crashed, it records the crash details, marks Domain 5 as quarantined, and jumps directly back to that saved bookmark. To the scheduler, it looks as if Domain 5 simply returned an error code—and the operating system continues running!

---

6. Honest Engineering Trade-Offs

No operating system design is magic; every architecture involves trade-offs:

• What PangeaOS Gains: Ultra-fast transitions between components without flushing address caches; fine-grained data compartments using hardware keys; and guaranteed survival against service crashes, infinite loops, memory floods, and double-fetch bugs.
• What PangeaOS Requires in Return: Because all services run in Ring 0, the pre-launch code verifier (bincheck-core), the assembly gates (gate-asm), and the two-stack exception stub (pangea-irq) are critical parts of the Trusted Computing Base (TCB). Every program binary must be verified before execution, and shared memory reclamation requires strict synchronization across CPU cores and the IOMMU.