PangeaOS Implementation Blueprint v1.2.3

Target Specification: PangeaOS Architecture Specification v1.2.3.
Core Invariants: Universal Ring-0 (CPL=0) execution, Single Address Space Operating System (SASOS), shared virtual address layout, zero per-domain CR3 switching, and zero transitions to CPL=3.
Purpose: Decompose fault localization and DoS resilience into immediately implementable crate hierarchies, root configuration files, public API signatures, milestones M0–M8, and mechanical verification gates.

---

1. Implementation Priority Order & Acyclic Layer Hierarchy

The highest priority is neither raw benchmark speed nor S-KARL alone, but guaranteeing that localized faults never escalate into full-system halts and that localized recovery never violates the trusted computing base (TCB) boundary:

1. Trusted Interrupt Entry (Two-Stack IST Pivot) & Domain Attribution
2. Watchdog, Forced Timer Preemption & Resource Quotas
3. Domain Quarantine & SMP Revocation Protocol
4. PFN Database, K13 PT Update Gate & TLB/IOTLB Shootdown
5. SFI / Positive-Allowlist Instruction Verifier & Final Binary Audit
6. IPC (Class S → Class B), DMA Isolation & Regeneration Control
7. Advanced Hardening Extensions (CET, S-KARL, Cache Partitioning)

Reversing this order—enabling advanced hardware features before establishing bounded queues, preemption, and trusted exception entries—cannot prevent service-originated Denial-of-Service (DoS).

1.1 Acyclic Layer Dependency Hierarchy (Layer 0 → Layer 5)

To enforce zero circular dependencies via cargo-deny, lower layers must never depend on upper-layer crates:

[Layer 5: Boot & Verification Harness]
  pangea-boot, test-kernel, xtask (ircheck, bincheck, sfi-verify, release-manifest)
       │
[Layer 4: Subsystems — Scheduler, IPC, Allocators & Watchdog]
  pangea-sched, pangea-watchdog, ring-ipc, pangea-ring, alloc-slab, alloc-buddy
       │
[Layer 3: Core Kernel Engines — Fault Containment, MMU, IOMMU & Domain Verifier]
  fault-core, domain-verify, pangea-mmu, hal-iommu, hal-apic, cmee
       │
[Layer 2: Low-Level State & Hardware Gates]
  pangea-irq, gate-asm, percpu, pangea-pfndb, hal-core, pangea-measure
       │
[Layer 1: Cryptographic & Audit Primitives]
  csprng, cap-core, audit-log, bincheck-core
       │
[Layer 0: Freestanding Leaf Types (Zero Internal Dependencies)]
  pangea-memmap, cpu-features

---

2. Workspace Structure & Complete Root Configuration Files

pangeaos/
├── rust-toolchain.toml
├── Cargo.toml
├── pangea-x86_64.json
├── linker.ld
├── crates/
│   ├── pangea-boot/       # UEFI entry, Secure Boot, bounded ExitBootServices retry
│   ├── pangea-memmap/     # UEFI memory classification, reserved region tracking
│   ├── cpu-features/      # CPUID/MSR/microcode capability profile verification
│   ├── pangea-measure/    # Signature, hash, Measured Boot & rollback policy
│   ├── csprng/            # ChaCha20 CSPRNG, reseeding & domain-separated key derivation
│   ├── cap-core/          # Capability ID, generation, owner & rights ledger table
│   ├── domain-verify/     # SFI, positive opcode allowlist, CFG & memory access verifier
│   ├── bincheck-core/     # no_std post-link and post-relocation binary verifier core
│   ├── gate-asm/          # Non-generic fixed assembly gates (PKRU/PKRS, PT, context, IRQ)
│   ├── pangea-irq/        # IDT, IST bootstrap stacks, Two-Stack exception entry protocol
│   ├── fault-core/        # FaultClass state machine, attribution & quarantine policy
│   ├── pangea-watchdog/   # APIC timer budget, NMI watchdog & lockup recovery
│   ├── pangea-sched/      # Ring-0 coroutine/task scheduler & CPU budget enforcement
│   ├── percpu/            # Trusted K0 Per-CPU state & recovery continuation records
│   ├── pangea-mmu/        # Shared VA, W^X, K13 PT Update Gate & TLB shootdown
│   ├── pangea-pfndb/      # PFN state machine, owner, generation & DMA pin tracking
│   ├── alloc-buddy/       # Bounded page allocation, domain quota & virtual guard mapping
│   ├── alloc-slab/        # Out-of-band metadata, quarantine ring & remote free
│   ├── hal-core/          # PCI configuration, device lifecycle & bounded MMIO access
│   ├── hal-iommu/         # Intel VT-d / AMD-Vi, IOTLB/IR invalidation & fault containment
│   ├── hal-apic/          # xAPIC/x2APIC, IPI synchronization & timer routing
│   ├── pangea-ring/       # Bounded IPC rings & snapshot-then-validate counter logic
│   ├── ring-ipc/          # Class S (brokered copy) & Class B (re-keyed zero-copy) IPC
│   ├── cmee/              # Software zeroization workflow & state transition enforcement
│   ├── audit-log/         # Fixed-size per-CPU ring logs & token-bucket rate limiter
│   └── test-kernel/       # Unit, property, fuzz & hardware fault-injection harness
├── xtask/
│   ├── ircheck/
│   ├── bincheck/
│   ├── sfi-verify/
│   ├── release-manifest/
│   └── unsafe-allow.toml
└── labs/
    ├── attacks/            # DoS, UAF, IPC, DMA & privilege opcode regression suites
    ├── fault-injection/    # #PF/#GP/#UD/panic localized recovery test suites
    └── hw-verify/          # CPU profile, IOMMU, APIC, TLB & NMI hardware test evidence

Note: This directory tree defines the target engineering structure; it does not imply all crates are already implemented.

2.1 rust-toolchain.toml

[toolchain]
channel = "nightly-2026-10-01"
components = ["rust-src", "llvm-tools-preview", "clippy", "rustfmt", "miri"]
targets = ["x86_64-unknown-none"]

2.2 Root Cargo.toml

[workspace]
resolver = "2"
members = [
    "crates/pangea-memmap", "crates/cpu-features", "crates/csprng",
    "crates/cap-core", "crates/audit-log", "crates/bincheck-core",
    "crates/pangea-measure", "crates/hal-core", "crates/pangea-pfndb",
    "crates/percpu", "crates/gate-asm", "crates/pangea-irq",
    "crates/cmee", "crates/hal-apic", "crates/hal-iommu",
    "crates/pangea-mmu", "crates/domain-verify", "crates/fault-core",
    "crates/alloc-buddy", "crates/alloc-slab", "crates/pangea-ring",
    "crates/ring-ipc", "crates/pangea-watchdog", "crates/pangea-sched",
    "crates/pangea-boot", "crates/test-kernel", "xtask",
]

[workspace.lints.rust]
unsafe_code = "deny"
missing_docs = "warn"

[workspace.lints.clippy]
all = "deny"
unwrap_used = "deny"
expect_used = "deny"
panic = "deny"

[profile.dev]
panic = "abort"
overflow-checks = true

[profile.release]
panic = "abort"
opt-level = 2
lto = "fat"
codegen-units = 1
overflow-checks = true
debug = false
strip = "none"

2.3 Custom Target Specification pangea-x86_64.json

{
  "llvm-target": "x86_64-unknown-none-elf",
  "data-layout": "e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-i128:128-f80:128-n8:16:32:64-S128",
  "arch": "x86_64",
  "target-endian": "little",
  "target-pointer-width": "64",
  "target-c-int-width": "32",
  "os": "none",
  "executables": true,
  "linker-flavor": "ld.lld",
  "linker": "rust-lld",
  "panic-strategy": "abort",
  "disable-redzone": true,
  "relocation-model": "pie",
  "code-model": "kernel",
  "features": "+soft-float,-sse,-sse2,+xsave,+xsaveopt,+shstk,+ibt",
  "pre-link-args": {
    "ld.lld": [
      "-Tlinker.ld",
      "--build-id=none",
      "--emit-relocs",
      "-z", "noexecstack",
      "-z", "relro",
      "-z", "now",
      "-z", "max-page-size=4096"
    ]
  }
}

2.4 Linker Script linker.ld (Page-Aligned Isolation of .text.gate_asm & .text.isr_entry)

ENTRY(pangea_kernel_main)
KERNEL_VMA_BASE = 0xFFFFFFFF80000000;

SECTIONS
{
    . = KERNEL_VMA_BASE;

    .text ALIGN(4096) : {
        __text_start = .;
        *(.text .text.*)
        . = ALIGN(4096);
        __text_end = .;
    }

    .text.gate_asm ALIGN(4096) : {
        __gate_asm_start = .;
        KEEP(*(.text.gate_asm))
        . = ALIGN(4096);
        __gate_asm_end = .;
    }

    .text.isr_entry ALIGN(4096) : {
        __isr_entry_start = .;
        KEEP(*(.text.isr_entry))
        . = ALIGN(4096);
        __isr_entry_end = .;
    }

    .rodata ALIGN(4096) : {
        __rodata_start = .;
        *(.rodata .rodata.*)
        . = ALIGN(4096);
        __rodata_end = .;
    }

    .data ALIGN(4096) : {
        __data_start = .;
        *(.data .data.*)
        . = ALIGN(4096);
        __data_end = .;
    }

    .bss ALIGN(4096) : {
        __bss_start = .;
        *(.bss .bss.* COMMON)
        . = ALIGN(4096);
        __bss_end = .;
    }

    /DISCARD/ : {
        *(.eh_frame .eh_frame_hdr .comment .note.*)
    }
}

2.5 TCB unsafe Allowlist xtask/unsafe-allow.toml

# Enforced by BC-UNSAFE-ALLOW. All crates omitted from this manifest must declare #![forbid(unsafe_code)].
allowed_crates = [
    { name = "cpu-features", reason = "CPUID and RDMSR hardware capability discovery" },
    { name = "percpu",       reason = "GS-relative access to K0 TrustedPerCpuState" },
    { name = "gate-asm",     reason = "Audited single-instance PKRU/PT/Context assembly gates" },
    { name = "pangea-irq",   reason = "Two-Stack Supervisor IST entry stubs and IDT load" },
    { name = "pangea-mmu",   reason = "Page table walk and TLB shootdown INVLPG/INVPCID" },
    { name = "hal-core",     reason = "Bounded PCI configuration and MMIO register access" },
    { name = "hal-apic",     reason = "x2APIC MSR programming and IPI delivery" },
    { name = "hal-iommu",    reason = "VT-d / AMD-Vi DMAR/IVRS register and IOTLB control" },
    { name = "cmee",         reason = "Volatile memory zeroization inside K15 gate" },
    { name = "pangea-boot",  reason = "UEFI efi_main entry and ExitBootServices handoff" },
]

---

3. Fault Policy Implementation & Cross-Crate API Contracts

3.0 Protection Key Assignment & Access Policy

Protection Key	Designated Purpose	Domain Access Policy
K0	Domain 0 private mutable state, Per-CPU records, Capability ledger, scheduler state	Trusted Domain 0 paths only (RW); AD=1 for all domains
K1–K12	Domain 1–12 private data, heap, and execution stacks	Owning domain RW; all other domains AD=1
K13	Page-table hierarchy pages and PT management metadata	Normally AD=1 or WD=1; writable exclusively inside the single PT Update Gate
K14	IPC control words and ring metadata	Domains Read-Only (RO); updated exclusively via the IPC Gate
K15	CMEE temporary mapping and quarantine zeroization region	Normally AD=1; enabled temporarily only inside the CMEE gate

For PKRU, bits 2k and 2k+1 represent AD and WD for key k. Masks are generated exclusively from a tested const fn (fault-core::pkru_for_domain); unrelated hand-written masks in multiple crates are forbidden. Domain code is validated against a positive instruction allowlist, not merely a blacklist.

3.1 fault-core Responsibilities & Prohibitions

• Responsibilities: Finite state machine for FaultClass, FaultOrigin, and RecoveryAction; reading Domain ID and generation from K0 Per-CPU state; centralized action table; static CI enforcement (BC-NO-LOCAL-GLOBAL-HALT) proving local faults never call global_halt(); rate-limited fixed-size event recording.
• Prohibitions: Never use arbitrary fields on an exception frame to authenticate a domain's identity; never allocate dynamic memory or acquire blocking locks during fault logging; never invoke normal domain callbacks from a fault handler.

3.2 Deterministic Fault Action Table

Detected Condition	Mandatory Kernel Processing
Malformed user request or invalid IPC value	RejectRequest; update caller violation strike count only.
Domain CPU budget overrun	PreemptDomain on first occurrence; QuarantineDomain on repeated overrun.
Domain panic! or local #PF/#GP/#UD/#CP	QuarantineDomain via trusted entry stack and non-local scheduler continuation.
Domain memory quota exceeded	RejectAllocation; global allocator panic is strictly prohibited.
IPC ring full	BackpressureOrDrop.
Device interrupt storm or IOMMU fault storm	DisableBME → invalidate IOTLB/IR → isolate device.
Domain restart limit exceeded	PermanentlyDisableDomain.
Domain 0 or trusted gate integrity violation	GlobalFailStop.
Unconfirmed TLB or IOTLB invalidation completion	Pin physical frames in Quarantine and isolate affected subject; enter Policy F3 if containment cannot be proven.

3.3 Core Cross-Crate Public Interface Contracts

• gate-asm (Single-Instance Non-Generic Assembly Gates): Exports only non-generic extern "C" symbols placed in .text.gate_asm:
  • pub unsafe extern "C" fn gate_enter_domain(dom_id: u16, dom_gen: u32, dom_pkru: u32, dom_rsp: u64, dom_rip: u64) -> u64;
  • pub unsafe extern "C" fn gate_abort_to_scheduler(reason_code: u64) -> !;
  • pub unsafe extern "C" fn gate_pt_update_write_pte(pte_va: *mut u64, new_pte: u64);
  • pub unsafe extern "C" fn gate_cmee_zeroize_page_4k(page_va: *mut u8);
• pangea-mmu (PT Update Gate & TLB Shootdown):
  • pub fn map_domain_page(pfn_db: &mut PfnDatabase, dom_id: u16, va: u64, pfn: usize, perms: PagePermissions) -> Result<(), MmuError>;
  • pub fn rekey_page_with_shootdown(pfn_db: &mut PfnDatabase, va: u64, new_key: u8, target_cpus: u64) -> Result<(), ShootdownTimeoutError>;
• domain-verify / bincheck-core (Three-Class Verification Pipeline):
  • pub fn verify_domain_image(elf_bytes: &[u8], assigned_domain_id: u16, cpu_profile: &VerifiedCpuProfile) -> Result<VerifiedDomainManifest, VerifyError>;
  • pub fn verify_relocated_memory_image(code_slice: &[u8], manifest: &VerifiedDomainManifest) -> Result<(), VerifyError>;

---

4. Implementation Milestones (M0–M8)

• M0 — Build Reproducibility & Test Foundation: Fix Rust nightly, pangea-x86_64.json, linker.ld, and crate dependencies. Enable cargo fmt, clippy lints, overflow checks, and unsafe-allow.toml in CI. Implement Layer 0–1 pure Rust crates (pangea-memmap, cap-core, fault-core, pangea-pfndb, pangea-ring, audit-log) and pass host unit tests. Establish QEMU COM1 serial logging. Pass Gate: Identical SHA-256 artifacts across two consecutive builds, test execution logs, and separation of release and dev signing keys.
• M1 — Trusted Exception Entry & Attribution: Implement TrustedPerCpuState and SchedulerContinuation in percpu bound to MSR_GS_BASE. Implement IDT, Supervisor IST bootstrap stacks (IST 1..4, U/S=0), k0_priv_rsp pivot, cld (DF=0), 16-byte stack alignment, and reentrancy guards in pangea-irq. Switch to PKRU_KERNEL_DEFAULT before touching K0 memory. Pass Gate: Local #PF/#GP/#UD/#CP and domain panics halt only the faulting test domain and return to the scheduler via gate_abort_to_scheduler; trusted stack corruption tests trigger GlobalFailStop.
• M2 — CPU Budgets, Watchdog & DoS Prevention: Implement APIC timer preemption (1 ms [T] initial target), per-domain CPU budgets, and the NMI watchdog in hal-apic and pangea-watchdog. Reject CLI/STI/POPFQ/IRETQ/HLT in bincheck-core. Integrate domain quotas, bounded work queues, and fixed-size token-bucket audit logs. Pass Gate: Infinite loops, log floods, IPC floods, and allocation floods allow other domains to make forward progress without global halts.
• M3 — Two-Stage Domain Verification Pipeline: Implement exact instruction-boundary decoding, CFG verification, 1TB-arena SFI memory bounds verification ((addr >> 40) == d), and indirect branch validation in bincheck-core and domain-verify. Execute verification both post-link and post-S-KARL relocation; fail-closed on any unknown opcode or unresolved CFG edge. Pass Gate: 100% detection across the adversarial binary test suite with documented false-positive metrics on valid binaries.
• M4 — Capability Ledger, Non-Generic Gates & PKRU State: Implement non-generic single-instance gate-asm functions. Generate absolute PKRU masks via const fn and validate Domain ID, generation, rights, and buffer bounds at runtime against cap-core. Prove no XRSTOR path can restore PKRU bit 9. Pass Gate: Unauthorized transitions, stale capabilities, WRPKRU gadgets, and generic gate duplication are rejected.
• M5 — PFN Database, PT Update Gate & SMP Reclamation: Implement the pangea-pfndb state machine, K13 PT Update Gate in pangea-mmu, cross-core TLB shootdown, and frame quarantine. Wait for all-core ACKs during quarantine and pin frames without reuse on timeout (F3). Pass Gate: Fault injection tests for double-free, UAF, cross-core re-key races, and TLB ACK timeouts.
• M6 — Dual-Class IPC & Device DoS Containment: Implement Class S (brokered copy) IPC first in ring-ipc with checked_pending snapshot validation, generation checks, and per-sender rate limits, followed by Class B (re-keyed zero-copy) IPC. Implement default-deny IOMMU (BME=0 until IOVA map and IOTLB invalidation complete) and fault storm quarantine in hal-iommu. Pass Gate: Malformed rings, DMA floods, and interrupt storms isolate only the offending subject.
• M7 — Safe Domain Regeneration & Restricted Mode: Implement clean-image signature re-verification, generation bumps, restart budgets, and exponential backoff in pangea-measure and pangea-sched. Transition repeating offenders to PermanentlyDisabled and enter Restricted Mode where only dependent requests return Err(ServiceUnavailable). Pass Gate: Independent domains continue operating across repeated panics, failed devices, and disabled services.
• M8 — Final Audit & Release Qualification: Execute all mandatory DoS regressions, SFI verification suites, and physical hardware tests (CPU profile, IOMMU, NMI watchdog) alongside two-builder reproducible build verification. Pass Gate: Zero full-system halts on known localized faults; deterministic fail-stop on core TCB invariant violations.

---

5. bincheck Rules

Raw byte-sequence scanning is used only as an auxiliary check and never substitutes for instruction-boundary decoding and CFG verification:

Rule ID	Target Scope	Pass Condition
BC-INSN-DECODE	Executable sections	100% of executable bytes decode cleanly along valid instruction boundaries; embedded data is placed in separate non-executable sections.
BC-PRIVILEGED	Domain code	Zero occurrences of CR/MSR writes, port I/O, descriptor table loads, or interrupt control instructions.
BC-PKRU-RESTORE	Domain code / XSTATE gates	Zero occurrences of WRPKRU; zero restoration of PKRU (bit 9) via XRSTOR/XRSTORS.
BC-SFI-MEM	Memory loads/stores	Every memory access is proven within verified sandbox bounds (1TB domain window) or targets an authenticated gate.
BC-CFI-CFG	Branches & calls	All indirect branch targets belong to the verified CFG target set; arbitrary indirect branches are prohibited.
BC-GATE-HASH	gate-asm	Matches manifest golden hash and invokes only authorized targets.
BC-POST-RELOC	Post-relocation image	Re-executes all verification checks above on the final S-KARL relocated memory image.
BC-UNSAFE-ALLOW	Workspace crates	Every unsafe usage resides in unsafe-allow.toml with a documented review record.
BC-NO-LOCAL-GLOBAL-HALT	Fault paths	Prohibits any control-flow path from L0/L1/L2 handlers to global_halt(); only F1/F2/F3 paths are permitted.

---

6. Mandatory DoS Regression Test Cases

• CPU: Tight loop, branch-heavy loop, pause loop, budget boundary overrun, and NMI watchdog recovery.
• Interrupt: Domain CLI/STI rejection, DF=1 entry clearing, nested NMI, IST guard-page touch, and reentrant panic.
• Memory: Over-quota allocation rejection, double-free detection, stale generation access, and TLB shootdown timeout pinning.
• IPC: Capacity overflow (tail - head > capacity), u32 counter wrap-around, double-fetch attempt, queue saturation, stale descriptor rejection, and peer restart storm.
• Device: MSI storm, IOMMU fault storm, BME disable failure, absent/timed-out PCIe FLR, and IOTLB invalidation timeout.
• Recovery: Interrupt during panic, new IPC arrival during quarantine, recovery reentrancy, and audit log ring saturation.
• Fatal Path: Domain 0 invariant violation, gate-asm hash mismatch, and trusted entry stack corruption.

Every test run records the triggering event, expected fault class, actual kernel action, proof of continued OS operation, and whether physical frames were reused.

---

7. strict-release Qualification Criteria

Before permitting a strict-release build, all of the following conditions must be satisfied:

• Ring-0 / SASOS invariants hold across source, linker, and physical hardware inspections.
• 100% of native domain code passes the SFI, positive opcode allowlist, and CFG verifiers.
• Zero unapproved paths connect localized faults to global_halt().
• CPU budgets, NMI watchdog, bounded queues, and per-domain quotas are active.
• Zero unsafe frame frees or reuses occur upon TLB or IOTLB invalidation timeouts.
• DoS regression suites confirm localized faults remain contained while core TCB integrity faults trigger fail-stop.
• No unimplemented security feature is described as "completed" or "guaranteed."

---

8. Engineering Precautions

This blueprint does not describe an already-completed implementation. SFI verification, NMI entry handling, SMP reclamation, and IOMMU invalidation are subtle and must never be claimed safe on the basis of code review alone. Implementation begins with a minimal, verifiable core—Class S brokered IPC, a restricted positive instruction allowlist, and fixed resource quotas—before advancing to Class B zero-copy IPC and hardware performance optimizations.