PangeaOS Implementation Blueprint: How the 26 Rust Crates Are Built

1. Why PangeaOS Is Split Into 26 Small Modules ("Crates")

If you write an entire operating system as one giant block of code, it quickly becomes impossible to verify which parts of the kernel are allowed to touch raw hardware and which parts must follow safe rules. Worse, if a low-level error handler accidentally calls a high-level function that allocates memory or waits on a lock, a simple error can turn into an unrecoverable deadlock.

To prevent this, PangeaOS v1.2.4b divides its source code into 26 small, focused Rust packages (called "crates"), arranged in six strict layers (Layer 0 at the bottom to Layer 5 at the top).

Two Golden Rules of Our Code Structure

1. One-Way Dependencies Only: A crate in a lower layer is never allowed to import or call a crate in a higher layer. This guarantees there are zero circular dependencies in the kernel.
2. Strict Separation of Safe Code and Hardware Code: Out of our 26 crates, 16 crates are pure safe Rust—they carry the #![forbid(unsafe_code)] attribute at the top of the file, meaning the Rust compiler will refuse to build if anyone tries to add a raw pointer or unsafe block inside them. Only 10 designated hardware crates are permitted to use unsafe Rust to talk to the CPU and devices, and our build tool (cargo xtask audit) checks this rule on every build.

2. Visual Map of the 6 Layers

Here is how the 26 crates are stacked from the lowest hardware definitions (Layer 0) up to the boot image and automated test runner (Layer 5):

[Layer 5: Boot Image & Automated Test Runner]
  pangea-boot (UEFI boot & 14 live self-tests), test-kernel (12 stress tests), xtask (build verifier)
       │
[Layer 4: High-Level Subsystems — Scheduler, Messaging, Memory Allocators & Watchdog]
  pangea-sched, pangea-watchdog, ring-ipc, pangea-ring, alloc-slab, alloc-buddy
       │
[Layer 3: Core Kernel Engines — Fault Policy, Address Map Manager, Device Isolation & Verifier]
  fault-core, domain-verify, pangea-mmu, hal-iommu, hal-apic, cmee
       │
[Layer 2: Low-Level Hardware Tables, Per-CPU Records & Security Gates]
  pangea-irq, gate-asm, percpu, pangea-pfndb, hal-core, pangea-measure
       │
[Layer 1: Foundational Building Blocks — Random Numbers, Permissions, Logs & Code Scanner]
  csprng, cap-core, audit-log, bincheck-core
       │
[Layer 0: Basic Hardware & Memory Definitions (Zero Internal Dependencies)]
  pangea-memmap, cpu-features

3. What Each Crate Does (Explained Layer by Layer)

Layer 0: Basic Hardware & Memory Definitions

These two crates sit at the very bottom and do not depend on any other crate in the project:

• pangea-memmap (Safe Rust): Reads the list of physical RAM regions provided by the computer's UEFI firmware at startup. It also enforces a 2-Megabyte "No-Man's-Land" (Virtual NULL Guard) at address 0 so that if any program accidentally tries to read or write a null pointer (0x0), the processor catches it immediately.
• cpu-features (Hardware Crate): Asks the processor what security features it supports (using the CPUID instruction), turns on hardware Write Protection (CR0.WP) and Memory Protection Keys (CR4.PKE), reads and writes the hardware keycard register (PKRU), and sets the per-CPU state pointer (IA32_GS_BASE).

Layer 1: Foundational Building Blocks (100% Safe Rust)

Every crate in Layer 1 is pure, safe logic with zero hardware dependencies:

• csprng: A cryptographic random number generator based on the ChaCha20 algorithm. PangeaOS uses it to generate secret keys that scramble memory allocator pointers and randomize where pages are placed, making memory layout impossible for an attacker to guess.
• cap-core: Manages Capability Handles—unforgeable permission tickets that a service must present when asking to read, write, or perform DMA on a resource. Each ticket includes a generation number. When a service crashes and restarts, its generation number goes up by 1, automatically canceling all tickets from its previous run.
• audit-log: A fixed-size circular log buffer with a built-in rate limiter (token bucket). Even if a broken service triggers thousands of errors per second, audit-log records the first few and counts the rest without overflowing memory or freezing the console.
• bincheck-core: The machine-code scanner. It decodes compiled x86-64 program bytes instruction by instruction, rejecting any binary that contains privileged instructions (like cli or wrpkru) or memory accesses outside the service's assigned 1-Terabyte workspace.

Layer 2: Low-Level Hardware Tables, Per-CPU Records & Gates

• percpu: Holds the kernel's private record for each CPU core (TrustedPerCpuState). It stores which service domain is currently running, the kernel's private rescue stack pointer, a 64-bit security canary word ("PANGEAK0"), and the saved bookmark (SchedulerContinuation) needed to jump back to the scheduler if the running service crashes.
• gate-asm: Contains the assembly language security doors (gate_enter_domain_live, gate_restore_continuation, gate_abort_to_scheduler, and gate_pt_update_write_pte) that safely switch hardware keycards (PKRU) and stacks when entering or leaving a service domain.
• pangea-irq: Sets up the processor's 64-bit Global Descriptor Table (GDT), the 104-byte Task State Segment (TSS) holding four emergency rescue stacks (IST 1 to IST 4), and the 256-entry Interrupt Descriptor Table (IDT). When a crash or interrupt happens, its assembly stub switches to the rescue stack and calls the Rust handler.
• pangea-pfndb (Safe Rust): The Physical Frame Number Database. It keeps a strict ledger for every 4-Kilobyte physical RAM page (Free, Allocated, DmaPinned, Quarantine, Erased) and refuses to let a page be reused until all CPU cores and hardware devices confirm they have forgotten the old mapping.
• hal-core: Drives the serial output port (COM1) so you can see boot messages in your terminal, controls the QEMU exit port, and verifies hardware ACPI tables (APIC, DMAR, IVRS, MCFG) by checking their sizes and checksums.
• pangea-measure (Safe Rust): Checks cryptographic hashes and version numbers before restarting a quarantined service from a clean image. If a service crashes more times than allowed, pangea-measure disables that service permanently and switches PangeaOS into Restricted Mode so all other services can keep running.

Layer 3: Core Kernel Engines

• fault-core (Safe Rust): The central rulebook that decides how to respond to each error class (L0–L3 vs. F1–F3), tracks CPU and memory budgets (DomainQuota), and computes the exact 32-bit hardware keycard masks (0xCBFF_FFFC for the kernel, 0xC3FF_FFFC for updating page tables).
• domain-verify (Safe Rust): Combines golden hash checks on gate-asm with two rounds of bincheck-core scanning (once after linking, and once after address relocation) before issuing a VerifiedDomainCertificate.
• pangea-mmu: Encodes page-table entries so that no page is ever both writable and executable at the same time (W^X), unlocks Key K13 only inside the page-table update gate, and tracks cross-core cache flushes (TlbShootdownTracker).
• hal-iommu: Keeps PCIe hardware devices in a default-deny state (BME=0) until their memory pages are pinned and flushed, and immediately isolates any device that causes an interrupt or DMA fault storm.
• hal-apic: Configures the processor's internal stopwatch timer (Local APIC Timer) to fire every 1 millisecond for preemptive scheduling.
• cmee: Wipes quarantined 4-Kilobyte RAM frames with zeros after cache flushes complete, and issues an unforgeable ErasedFrameProof token required before the page allocator will reuse the frame.

Layer 4: High-Level Subsystems (100% Safe Rust)

• pangea-watchdog & pangea-sched: The task scheduler and watchdog monitor. They share CPU time fairly among ready services, pause any service that exceeds its 1-millisecond slice, recover from hard lockups via the NMI watchdog, enforce exponential wait times between restarts, and protect the kernel's 16-Megabyte emergency memory reserve.
• pangea-ring & ring-ipc: The inter-service messaging system. It snapshots message counters into private registers once (preventing "Bait-and-Switch" double-fetch bugs) and supports both Class S (safe copied messages) and Class B (zero-copy buffer handoffs using protection key re-tagging).
• alloc-buddy & alloc-slab: Hardened memory allocators. alloc-buddy places an unmapped 4 KB guard page before and after every allocated page so buffer overflows hit an immediate wall. alloc-slab stores management pointers outside the data buffer, scrambles them with a ChaCha20 secret key, and fills freed memory with 0xDF poison bytes to catch Use-After-Free and Double-Free bugs.

Layer 5: Boot Image & Automated Verification

• test-kernel (Safe Rust): Runs 12 automated stress and attack scenarios (infinite loops, forbidden instructions, corrupted message counters, memory floods, crash storms, device fault storms, and cache-flush timeouts) to prove that PangeaOS contains every single one.
• pangea-boot & xtask: Compiles the UEFI boot image (BOOTX64.EFI), runs static source and binary audits (cargo xtask audit), and boots PangeaOS inside QEMU (cargo xtask qemu) to execute all 14 live self-tests.

4. Summary of Milestones (M0–M8) & Live Hardware Phases (H0–H4)