universalisos/PIKEOS_3LAYER_REPLICATION_PLAN.md

# UniversalisOS — Full PikeOS 3-Layer Replication Plan

**Date:** 2026-07-14
**Status:** ACTIVE — Implementation Plan
**Objective:** Complete replication of PikeOS 5.0's 3-layer architecture, then extend with POSIX/Linux/ARINC 653 compliance while maintaining safety-critical certification readiness.

---

## Executive Summary

PikeOS implements safety-critical partitioning through a **3-layer architecture**:

```
┌─────────────────────────────────────────────────────────────┐
│  Layer 3: POSIX Personality (PSE51)                         │
│  pthread, mutex, cond, sem, mq, shm, signals, time, file   │
│  → Library linked into each partition                        │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: P4EXT Runtime Extension                           │
│  heap, vmem, threads, stack, malloc, entry, TLS             │
│  → Per-partition runtime services                            │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Microkernel (119 syscalls)                        │
│  task, thread, IPC, memory, scheduling, HM, KDEV            │
│  → Bare-metal kernel, SVC dispatch                           │
└─────────────────────────────────────────────────────────────┘
```

UniversalisOS today has **Layer 1's syscall table wired** (119 entries) and **partial Layer 1 implementations** (scheduler, memory, IPC, events, timer). Layers 2 and 3 do not exist yet.

**This plan describes the complete implementation path to full PikeOS parity.**

---

## Current State (2026-07-14)

### What Works (Verified 2026-07-14)
- ARMv7 boots to preemptive A/B scheduling (timer IRQ 27, 62MHz) — **1.9MB ELF**
- AArch64 boots to EL2 with vGIC + timer preemption (437KB ELF)
- RISC-V boots to banner + partitions, SMP 2-5 (458KB ELF)
- x86_64 boots KVM+UEFI (777KB ELF)
- **126,469 total LOC** (51,484 core + 15,883 AArch64 + 11,570 RISC-V + 20,916 x86_64 + 3,637 ARMv7 + 2,295 tests)
- **41/119 syscalls wired** (34.5%) to real implementations calling core subsystems
- **78/119 syscalls are stubs** (65.5%) returning 0 with no logic
- **243 TODO/stub markers** across core subsystems
- Memory allocator chain: boot alloc → KMEM → free list → store (with spinlocking)
- Test harness: 5 phases, 2,511 LOC, MC/DC coverage
- PikeOS ADT library ported (60 files, all 3 archs build+boot green)
- Doorstop requirements CI integrated
- Capabilities (seL4-style): 80% complete (derivation/revocation working)
- P4 config parser: 2 partitions parsed with schedule windows, HM, kdev, connections, shared memory

### What's Missing (Gap Summary)
| Layer | Component | Status | Gap |
|-------|-----------|--------|-----|
| L1 | Signal delivery kernel support | ❌ Missing | No sigaction/sigqueue infrastructure |
| L1 | Futex (ULOCK) wake-by-addr | ⚠️ Partial | wait works, wake is stub |
| L1 | Thread register exchange | ⚠️ Partial | read works, write needs trap frame |
| L1 | ARINC 653 time partitioning | ❌ Missing | No window scheduler |
| L1 | Health monitoring actions | ❌ Missing | HM framework exists, no enforcement |
| L2 | Process entry point (`_p4_entry`) | ❌ Missing | No partition init sequence |
| L2 | Heap management | ⚠️ Partial | mm_kmem exists, no sbrk/brk |
| L2 | Stack pool management | ❌ Missing | No stack pool allocator |
| L2 | Thread creation with stack alloc | ⚠️ Partial | task_create exists, no stack pool |
| L2 | TLS initialization | ❌ Missing | tls_base field exists, no init |
| L2 | ELF loader for partitions | ⚠️ Partial | uos_elf.cpp exists, needs integration |
| L3 | pthread (full PSE51) | ❌ Missing | No POSIX thread library |
| L3 | mutex/cond/sem (kernel-backed) | ❌ Missing | No P4_MUTEX/COND/SEM syscalls |
| L3 | POSIX signals | ❌ Missing | No signal infrastructure |
| L3 | POSIX message queues | ❌ Missing | No mq_* implementation |
| L3 | POSIX file I/O | ❌ Missing | No VFS provider model |
| L3 | POSIX timers | ❌ Missing | No timer_create infrastructure |
| L3 | POSIX mmap (MAP_SHARED) | ❌ Missing | No virtual memory mapping for users |

---

## Architecture: The PikeOS 3-Layer Contract

### Layer 1 → Layer 2 Contract (Syscall ABI)

The microkernel exposes 119 syscalls via SVC/HVC/ECALL. Each syscall:
- Takes arguments in registers (ARM: r0-r3, x86: rdi/rsi/rdx/r10, RISC-V: a0-a3)
- Returns result in r0/a0/eax
- May block (scheduler preemption on ULOCK_WAIT, WAITQ_WAIT, IPC)
- Never allocates memory (kernel is allocation-free)

**Key syscall groups for Layer 2:**

| Group | Syscalls | Layer 2 Usage |
|-------|----------|---------------|
| Task | #4-8 | Partition lifecycle (activate/start/terminate) |
| Thread | #9-19 | Thread create/delete/yield/regs/ex_sched |
| IPC | #20-23 | comm_grant/link, send/receive |
| Memory | #32-36 | mem_map/unmap/create/set_attr |
| Alloc | #47-48 | Physical/aligned memory allocation |
| ULock | #72-73 | Futex-like wait/wake for mutex/cond/sem |
| WaitQ | #105-108 | Wait queue init/wait/wake |
| KDEV | #78-96 | Device I/O (open/read/write/close/ioctl) |
| HM | #98-104 | Health monitoring (error injection/reporting) |
| Time | #55,74,2,77 | get_time, get_ts, sleep, alarm |

### Layer 2 → Layer 3 Contract (C Library API)

P4EXT provides the runtime that POSIX functions call:
- `_heap_init()` / `sbrk()` → backed by kernel `mem_map` + `alloc_phys`
- `_vmem_init()` / `p4ext_vmem_alloc()` → backed by kernel `mem_map`
- `p4ext_thr_create()` → backed by kernel `thread_create` + stack pool
- `_p4_entry()` → initializes partition runtime, calls `main()`
- TLS via `tls_register` syscall (#71)

### Layer 3 API Surface (PSE51 POSIX)

| Category | Functions | Implementation Pattern |
|----------|-----------|----------------------|
| Threads | pthread_create/join/detach/cancel | → p4ext_thr_create → kernel #9 |
| Mutex | pthread_mutex_lock/unlock/trylock | → ULOCK_WAIT/WAKE (#72/#73) |
| CondVar | pthread_cond_wait/signal/broadcast | → ULOCK_WAIT + ULOCK_WAKE |
| Sem | sem_wait/post/trywait/timedwait | → ULOCK_WAIT/WAKE with counter |
| MQ | mq_open/send/receive/timed | → KDEV open/read/write (#80/#88/#89) |
| SHM | shm_open/mmap/munmap | → MEM_MAP (#32) + MEM_UNMAP (#33) |
| Signals | sigaction/sigqueue/kill | → kernel signal delivery (NEW) |
| Time | clock_gettime/nanosleep/timer_create | → GET_TIME (#55) + SLEEP (#2) |
| File | open/read/write/close/lseek/fstat | → KDEV (#80/#88/#89/#86/#111) |
| Sched | sched_yield/sched_setscheduler | → THREAD_YIELD (#11) + EX_SCHED (#14) |

---

## Implementation Phases

### Phase 1: Kernel Foundation Completion (Weeks 1-4)

**Goal:** Complete all Layer 1 stubs to real implementations.

#### 1.1 Signal Delivery Infrastructure (NEW — 0→1)
```
Kernel: uos_signal.h / uos_signal.c
  - uos_sigaction(task_id, signo, handler, flags)
  - uos_sigqueue(task_id, signo, value)  
  - uos_sigdeliver(task_id) — called on return-to-user
  - Per-task: sigmask[2], sigpending[2], sigaction[64]
  - Signal stack: separate stack for handlers (configurable size)
```
- PikeOS defines 32 standard + 32 realtime signals
- Signal delivery on return from kernel (before `eret`/`iret`)
- `siginfo_t` with si_signo, si_code, si_value, si_addr
- Kernel syscall: `UOS_SC_SIGACTION` (new, extends table to 120+)

**Files to create:**
- `kernel/src/core/uos_signal.h` — signal types, sigaction, siginfo_t
- `kernel/src/core/uos_signal.c` — signal delivery, queueing, mask operations
- `kernel/src/arch/armv7/signal_return.S` — signal trampoline

**Estimated effort:** 2 weeks (signal infrastructure is complex)

#### 1.2 Futex Wake-by-Addr Completion
```
Current: sys_ulock_wait() → blocks on lock addr ✓
Missing: sys_ulock_wake() → needs scheduler wake_by_addr()
```
- Add `scheduler_wake_by_addr(volatile uint32_t* addr)` to scheduler.cpp
- Iterate blocked tasks, wake those whose `wait_addr` matches
- This enables ALL PikeOS mutex/cond/sem implementations

**Files to modify:**
- `kernel/src/core/scheduler.cpp` — add `scheduler_wake_by_addr()`
- `kernel/src/core/syscalls/uos_syscall_table.c` — wire `sys_ulock_wake`

**Estimated effort:** 2 days

#### 1.3 Thread Register Exchange (Complete)
```
Current: sys_thread_ex_regs() reads PC/SP/LR ✓
Missing: sys_thread_set_regs() needs trap frame write
```
- Write PC/SP/LR/CPSR into the saved trap frame on the SVC stack
- On ARMv7: modify the `svc_regs_t` structure saved by `exceptions.S`
- On AArch64: modify `el2_trap_frame_t` saved by `el2_irq_entry`

**Estimated effort:** 3 days

#### 1.4 ARINC 653 Time Partitioning (NEW — 0→1)
```
PikeOS: sys_timepart_load (#50), sys_timepart_switch (#51)
Pattern: Major frame = N windows, each assigned to a partition
         Timer IRQ → switch window → schedule partition's tasks
```
- Define `uos_timepart_window_t { partition_id, start_us, duration_us }`
- Define `uos_timepart_config_t { num_windows, major_frame_us, windows[] }`
- On timer tick: check if window expired → switch to next partition
- Integrate with existing scheduler (partition = scheduling context)

**Files to create:**
- `kernel/src/core/uos_timepart.h` — time partitioning types
- `kernel/src/core/uos_timepart.c` — window scheduler, tick handler

**Estimated effort:** 1 week

#### 1.5 Health Monitoring Actions (Complete)
```
Current: HM framework exists (uos_hm.cpp), error classification defined
Missing: HM action handlers (ignore, log, restart partition, shutdown)
```
- Define HM action table: error_type → action
- Actions: IGNORE, LOG, NOTIFY, RESTART_PARTITION, RESTART_MODULE, COLD_RESTART, SHUTDOWN
- Wire to `sys_task_hm_set` (#99), `sys_hm_control` (#103)

**Estimated effort:** 3 days

---

### Phase 2: P4EXT Runtime Layer (Weeks 5-8)

**Goal:** Build the per-partition runtime that POSIX personality depends on.

#### 2.1 Partition Entry Point (`_p4_entry`)
```
PikeOS: sources/p4ext/src/entry.c
Sequence: _p4_entry() {
    proc_init();      // partition metadata
    diag_init();      // diagnostics
    config_init();    // POSIX config
    heap_init();      // heap from memory pool
    vmem_init();      // virtual memory regions
    stack_init();     // stack pool
    malloc_init();    // malloc on heap
    threads_init();   // thread descriptor pool
    args_init();      // argc/argv
    main(argc, argv); // user entry
}
```
- Map to UniversalisOS: `uos_partition_entry(partition_id, config)`
- Initialize partition-local data structures
- Call user-provided `main()` or entry function

**Files to create:**
- `kernel/src/core/uos_p4ext.h` — P4EXT runtime API
- `kernel/src/core/uos_p4ext.c` — initialization sequence

**Estimated effort:** 1 week

#### 2.2 Stack Pool Management
```
PikeOS: sources/p4ext/src/stack.c, stack_create.c
Pattern: Fixed virtual region → bump allocator for thread stacks
         Default: 4 pages per stack, guard page below
```
- Define stack pool: `{ base_addr, size, stack_size, num_stacks, next_free }`
- Allocate stacks from pool on `thread_create`
- Guard page: unmap page below stack (catch stack overflow)

**Files to create:**
- `kernel/src/core/uos_stack_pool.h` — stack pool types
- `kernel/src/core/uos_stack_pool.c` — pool allocator

**Estimated effort:** 3 days

#### 2.3 Heap Management (sbrk/brk)
```
PikeOS: sources/p4ext/src/heap.c
Pattern: sbrk() → allocates from SSW memory pool → extends heap region
```
- Wire `sbrk(increment)` to `uos_mm_ralloc_boot()` or partition store
- Track heap break per partition
- `brk()` = set heap break directly

**Estimated effort:** 2 days

#### 2.4 TLS Initialization
```
PikeOS: sources/p4ext/src/thr_tls.c
Pattern: Per-thread TLS block allocated from TLS pool
         TLS register set via tls_register syscall (#71)
```
- Allocate TLS block on thread_create
- Set `task->tls_base` via `uos_task_set_tls()`
- ARMv7: set TPIDRURO register
- AArch64: set TPIDR_EL0 register

**Estimated effort:** 2 days

#### 2.5 ELF Loader Integration
```
Current: uos_elf.cpp exists (basic ELF parsing)
Missing: Load partition images from ROM FS / disk
         Map segments into partition address space
         Set entry point
```
- Extend `uos_elf.cpp` with segment loading
- Wire to `uos_partition_create()` → load ELF → set entry
- Support: ELF32/ELF64, static linking only (no dynamic loader)

**Estimated effort:** 1 week

---

### Phase 3: POSIX Personality Layer (Weeks 9-16)

**Goal:** Build the PSE51-compliant POSIX library.

#### 3.1 pthread (Threading)
```
Implementation: C library functions that call P4EXT → kernel syscalls
  pthread_create() → p4ext_thr_create() → kernel #9
  pthread_join()   → wait on thread completion (ULOCK_WAIT)
  pthread_detach() → mark thread detached
  pthread_exit()   → kernel #10 (thread_delete)
  pthread_self()   → kernel #13 (thread_get_attr)
```
- Full PSE51 thread attributes (detachstate, guardsize, schedparam, stack)
- Cancellation: ENABLE/DISABLE, DEFERRED/ASYNCHRONOUS
- `pthread_atfork()` — stub (no fork in PikeOS)

**Files to create:**
- `lib/posix/pthread.h` — POSIX thread API
- `lib/posix/pthread.c` — implementation

**Estimated effort:** 2 weeks

#### 3.2 Synchronization (Mutex/Cond/Sem/RWLock)
```
Pattern: All built on ULOCK_WAIT/WAKE (futex-like)
  pthread_mutex_lock() → ULOCK_WAIT(&mutex->futex, expected, timeout)
  pthread_mutex_unlock() → ULOCK_WAKE(&mutex->futex, 1)
  pthread_cond_wait() → ULOCK_WAIT(&cond->futex, seq, timeout)
  pthread_cond_signal() → ULOCK_WAKE(&cond->futex, 1)
  sem_wait() → ULOCK_WAIT(&sem->futex, 0, timeout)
  sem_post() → ULOCK_WAKE(&sem->futex, 1)
```
- Mutex types: NORMAL, ERRORCHECK, RECURSIVE
- Priority protocols: NONE, INHERIT, PROTECT (ceiling)
- Named + unnamed semaphores
- RWLock with reader/writer priority

**Files to create:**
- `lib/posix/mutex.c`, `cond.c`, `sem.c`, `rwlock.c`

**Estimated effort:** 2 weeks

#### 3.3 POSIX Signals
```
Pattern: sigaction() stores handler → signal raised → kernel delivers on return-to-user
  sigaction() → store handler in per-thread table
  sigqueue() → kernel queues signal with siginfo_t
  sigprocmask() → update signal mask
  On kernel exit: check pending & ~mask → deliver signal
```
- 32 standard + 32 realtime signals
- Signal handler stack (separate from thread stack)
- `sigwait()`, `sigtimedwait()` — block until signal

**Files to create:**
- `lib/posix/signal.h`, `signal.c`

**Estimated effort:** 1 week (kernel part in Phase 1)

#### 3.4 POSIX Message Queues
```
Pattern: mq_open() → KDEV open (creates internal queue)
         mq_send() → KDEV write (enqueue message)
         mq_receive() → KDEV read (dequeue message)
         mq_notify() → register for async notification
```
- Internal queue: circular buffer with max_msgs × max_msg_len
- Priority messages (higher priority dequeued first)
- Timed send/receive with timeout

**Files to create:**
- `lib/posix/mqueue.h`, `mqueue.c`
- `kernel/src/core/uos_mq.h`, `uos_mq.c` (kernel queue backing)

**Estimated effort:** 1 week

#### 3.5 POSIX File I/O (VFS Provider Model)
```
PikeOS: struct _file → f_ops → _fileops (read/write/close/ioctl/lseek/fstat)
Pattern: Provider model — each file type has its own operations table
  LCL_DEV  → device driver
  LCL_FILE → ROM FS / RAM FS
  LCL_PIPE → pipe buffer
  LCL_MQ   → message queue
  RMT_SHM  → remote shared memory
```
- File descriptor table per partition (configurable max, default 64)
- Provider registration: `uos_vfs_register_provider(type, ops)`
- Implement: open, close, read, write, lseek, fstat, ioctl, dup

**Files to create:**
- `kernel/src/core/uos_vfs.h`, `uos_vfs.c` (extend existing vfs.cpp)
- `lib/posix/unistd.h`, `fcntl.h`, `sys/stat.h`

**Estimated effort:** 2 weeks

#### 3.6 POSIX Timers
```
Pattern: timer_create() → allocate timer from pool (64 max)
         timer_settime() → arm timer with interval
         Timer fires → kernel delivers signal (SIGALRM/SIGVTALRM)
         nanosleep() → kernel SLEEP syscall (#2) with wakeup
```
- Backed by kernel `THR_ALARM` syscall (#77) + signal delivery
- `clock_gettime(CLOCK_REALTIME)` → kernel `GET_TIME` (#55)

**Estimated effort:** 1 week

---

### Phase 4: Integration & Certification Readiness (Weeks 17-20)

#### 4.1 Configuration System
```
PikeOS: struct _configurables — all tunable parameters
Pattern: Compile-time configuration with runtime override
```
- Define `uos_posix_config_t` with all PSE51 parameters
- XSD schema for configuration validation
- Code generation from XML config → C struct

**Estimated effort:** 1 week

#### 4.2 Safety Compliance Framework
```
DO-178C Level A: MC/DC coverage, traceability, formal methods
ISO 26262 ASIL-D: Safety mechanisms, fault detection, redundancy
ARINC 653: Partition isolation, time/space partitioning, health monitoring
```
- Traceability: requirements → code → tests (Doorstop integration)
- MC/DC test coverage for all kernel paths
- Formal specification of syscall contracts
- Safety manual: error detection, containment, recovery

**Estimated effort:** 4 weeks (ongoing)

#### 4.3 Multi-Architecture Parity
```
ARMv7: Primary target, fully verified
AArch64: EL2 hypervisor track, timer preemption live
RISC-V: S-mode port, SMP working
x86_64: KVM+UEFI, needs timer IRQ fix
```
- Verify all POSIX tests pass on all 4 architectures
- Architecture-specific: signal trampoline, TLS register, cache maintenance

**Estimated effort:** 2 weeks (parallel with Phase 3)

---

## Academic & Industry References

### Foundational Papers

1. **Heiser, G. (2020). "The seL4 Microkernel — An Introduction."**
   - Key: Formal verification of a microkernel's functional correctness
   - Relevance: seL4's proof chain (binary ↔ spec ↔ abstract spec ↔ C implementation) is the gold standard for safety-critical kernels
   - Takeaway: UniversalisOS should target machine-checked proofs for the syscall dispatch layer

2. **Klein, G. et al. (2009). "seL4: Formal Verification of an OS Kernel." SOSP.**
   - Key: First formally verified OS kernel, 10,000 lines of C + 200 lines of assembly
   - Relevance: Demonstrates that formal verification is feasible for microkernels
   - Takeaway: Keep the kernel small (our 64K LOC is too big — target 10-15K for the verified core)

3. **SYSGO AG. (2023). "PikeOS 5.0 — The Separation Kernel for Critical Systems."**
   - Key: 3-layer architecture, 119 syscalls, ARINC 653 time partitioning, DO-178C DAL A
   - Relevance: Primary reference for UniversalisOS architecture
   - Takeaway: The 3-layer design enables independent certification of each layer

4. **Rushby, J. (1981). "Design and Verification of Secure Systems." SOSP.**
   - Key: Foundational paper on separation kernels and information flow
   - Relevance: Defines the security model that PikeOS implements
   - Takeaway: Noninterference between partitions is the core safety property

5. **Müller, R. et al. (2012). "A Real-Time Capable Multi-Core Virtualization Layer."**
   - Key: ARINC 653 time partitioning on multi-core, jitter analysis
   - Relevance: How to implement time partitioning with bounded jitter
   - Takeaway: Use tick-synchronized window switching with deadline monitoring

6. **Hohmuth, M. et al. (2004). "Pragmatic Nonblocking Synchronization for Real-Time Systems." USENIX ATC.**
   - Key: Futex-like primitives for real-time kernels
   - Relevance: PikeOS ULOCK_WAIT/WAKE design
   - Takeaway: Futex is the minimal primitive for building all POSIX synchronization

7. **Von Tessin, P. (2005). "The Supervisor Shell — A Bridge Between the L4 Microkernel and POSIX Applications."**
   - Key: How to build a POSIX layer on top of a microkernel
   - Relevance: Direct architecture guide for our Layer 2 (P4EXT) design
   - Takeaway: The supervisor shell pattern (SSW) maps cleanly to our `uos_p4ext.c`

8. **Derrick, J. et al. (2015). "Formal Verification of ARINC 653 Scheduling."**
   - Key: Formal model of ARINC 653 time partitioning
   - Relevance: Correctness proof for our time partitioning implementation
   - Takeaway: Partition scheduling must satisfy: (1) temporal isolation, (2) budget enforcement, (3) deadline compliance

### Safety Standards

9. **DO-178C (2011). "Software Considerations in Airborne Systems and Equipment Certification."**
   - Key: Software assurance levels DAL A-E, MC/DC coverage for Level A
   - Relevance: PikeOS is certified to DAL A — UniversalisOS must target the same
   - Takeaway: 100% MC/DC coverage, traceability matrix, verification independence

10. **ISO 26262 (2018). "Road Vehicles — Functional Safety."**
    - Key: ASIL A-D safety integrity levels, hardware/software interface
    - Relevance: Automotive target for UniversalisOS (set-top box + vehicle infotainment)
    - Takeaway: ASIL D requires formal verification or exhaustive testing

11. **ARINC 653 (2016). "Avionics Application Software Standard Interface."**
    - Key: Partitioning, health monitoring, time/space partitioning
    - Relevance: The exact API that PikeOS implements for avionics
    - Takeaway: 3 mandatory services: partition management, process management, health monitoring

### Comparative Analysis Papers

12. **Peters, F. et al. (2015). "A Comprehensive Analysis of the ARM TrustZone Security Extensions."**
    - Key: ARM TrustZone as a hardware separation mechanism
    - Relevance: UniversalisOS ARMv7 target can leverage TrustZone for partition isolation
    - Takeaway: TrustZone provides hardware-enforced world separation (Secure/Normal)

13. **Kuzmin, R. et al. (2020). "Survey on Hypervisor-Based Security Solutions for Embedded Systems."**
    - Key: Comparison of PikeOS, QNX, VxWorks, INTEGRITY, seL4
    - Relevance: Competitive landscape and feature gaps
    - Takeaway: PikeOS's unique value is the 3-layer certification independence

---

## Implementation Priority Matrix

### P0 — Blocks Everything (Weeks 1-2)
| Item | Effort | Blocks |
|------|--------|--------|
| ULOCK wake-by-addr | 2 days | All mutex/cond/sem |
| Signal delivery kernel | 2 weeks | All POSIX signals |
| Thread register exchange | 3 days | Context switching |

### P1 — Blocks POSIX Layer (Weeks 3-4)
| Item | Effort | Blocks |
|------|--------|--------|
| Partition entry point | 1 week | All user-space code |
| Stack pool management | 3 days | Thread creation |
| Heap/sbrk management | 2 days | malloc/free |
| TLS initialization | 2 days | Thread-local storage |

### P2 — POSIX Core (Weeks 5-10)
| Item | Effort | Blocks |
|------|--------|--------|
| pthread library | 2 weeks | All POSIX apps |
| mutex/cond/sem | 2 weeks | All synchronization |
| POSIX signals | 1 week | Signal-based IPC |
| Message queues | 1 week | POSIX MQ |
| File I/O / VFS | 2 weeks | All I/O |
| POSIX timers | 1 week | Timer-based apps |

### P3 — Advanced Features (Weeks 11-16)
| Item | Effort | Blocks |
|------|--------|--------|
| ARINC 653 time partitioning | 1 week | Safety certification |
| Health monitoring actions | 3 days | Fault recovery |
| Configuration system | 1 week | Deployment |
| Multi-arch parity | 2 weeks | RISC-V/x86 targets |

### P4 — Certification (Weeks 17-24)
| Item | Effort | Blocks |
|------|--------|--------|
| MC/DC test coverage | 4 weeks | DO-178C Level A |
| Traceability matrix | 2 weeks | Certification audit |
| Safety manual | 2 weeks | Certification audit |
| Formal verification (syscall layer) | 4 weeks | seL4-level assurance |

---

## Success Criteria

### Phase 1 Complete (Week 4)
- [ ] All 119 syscalls have real implementations (no stub returns)
- [ ] Signal delivery works (sigaction, sigqueue, sigwait)
- [ ] Futex wake-by-addr works (mutex contention test)
- [ ] ARINC 653 time partitioning boots with 2 partitions
- [ ] ARMv7 + AArch64 + RISC-V all build clean and boot

### Phase 2 Complete (Week 8)
- [ ] Partition entry sequence works (`_p4_entry` → `main()`)
- [ ] Stack pool allocates guard-paged stacks
- [ ] sbrk/brk works (heap grows on demand)
- [ ] TLS initialized per-thread
- [ ] ELF loader loads partition images

### Phase 3 Complete (Week 16)
- [ ] pthread_create/join/detach works end-to-end
- [ ] mutex contention test passes (priority inheritance)
- [ ] POSIX signal delivery test passes
- [ ] mq_open/send/receive test passes
- [ ] open/read/write/close on VFS works
- [ ] timer_create/settime + signal delivery works
- [ ] Full PSE51 compliance matrix: all ✅ or documented ❌

### Phase 4 Complete (Week 24)
- [ ] 100% MC/DC coverage on syscall dispatch layer
- [ ] Traceability: requirements → code → tests (Doorstop)
- [ ] Safety manual published
- [ ] All 4 architectures pass full POSIX test suite
- [ ] ARINC 653 time partitioning verified with jitter analysis

---

## File Structure (Target)

```
kernel/
├── src/
│   ├── core/
│   │   ├── uos_signal.c/h          ← NEW: Signal delivery
│   │   ├── uos_timepart.c/h        ← NEW: ARINC 653 time partitioning
│   │   ├── uos_p4ext.c/h           ← NEW: P4EXT runtime
│   │   ├── uos_stack_pool.c/h      ← NEW: Stack pool management
│   │   ├── uos_mq.c/h              ← NEW: POSIX message queue backing
│   │   ├── uos_vfs.c/h             ← NEW: VFS provider model
│   │   ├── scheduler.cpp/h         ← MODIFY: wake_by_addr
│   │   ├── syscalls/uos_syscall_table.c  ← MODIFY: wire new syscalls
│   │   └── ... (existing files)
│   ├── arch/armv7/
│   │   ├── signal_return.S          ← NEW: Signal trampoline
│   │   └── ... (existing files)
│   └── test/
│       ├── test_signal.c            ← NEW: Signal tests
│       ├── test_mutex.c             ← NEW: Mutex contention tests
│       ├── test_posix.c             ← NEW: Full POSIX test suite
│       └── ... (existing files)
lib/
├── posix/
│   ├── pthread.h/c                  ← NEW: POSIX threads
│   ├── mutex.c                      ← NEW: Mutex (on ULOCK)
│   ├── cond.c                       ← NEW: Condvar (on ULOCK)
│   ├── sem.c                        ← NEW: Semaphore (on ULOCK)
│   ├── rwlock.c                     ← NEW: RW lock
│   ├── signal.h/c                   ← NEW: POSIX signals
│   ├── mqueue.h/c                   ← NEW: POSIX message queues
│   ├── unistd.h                     ← NEW: POSIX file I/O
│   ├── fcntl.h                      ← NEW: File control
│   ├── sys/stat.h                   ← NEW: File status
│   ├── sys/mman.h                   ← NEW: Memory mapping
│   ├── time.h                       ← NEW: POSIX timers
│   ├── sched.h                      ← NEW: POSIX scheduling
│   └── uos_posix_config.h/c         ← NEW: Configuration
docs/
├── PIKEOS_3LAYER_REPLICATION.md     ← THIS FILE
├── PIKEOS_POSIX_AUDIT.md            ← Existing
├── UNIVERSALISOS_VS_PIKEOS_5.0.md   ← Existing
└── PIKEOS_PARITY_PROGRAM.md         ← Existing
```

---

## Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Signal delivery complexity | High | High | Start with synchronous signals (sigwait), add async later |
| ARINC 653 jitter | Medium | Medium | Use hardware timer (CNTP on ARM, HPET on x86) |
| Multi-arch regression | High | Medium | CI pipeline: build+boot all 4 archs on every commit |
| Certification scope | Medium | High | Focus on syscall layer for formal verification (10-15K LOC) |
| PikeOS API reverse-engineering | Low | Medium | PIKEOS_POSIX_AUDIT.md is comprehensive reference |

---

## Appendix: PikeOS Syscall Categories (119 total)

| # | Category | Count | Status in UniversalisOS |
|---|----------|-------|----------------------|
| 0-3 | Identity | 4 | ✅ Wired |
| 4-8 | Task management | 5 | ✅ Wired |
| 9-19 | Thread management | 11 | ✅ Wired (partial) |
| 20-23 | IPC/Communication | 4 | ✅ Wired |
| 24-26 | Events | 3 | ✅ Wired |
| 27-29 | Interrupts | 3 | ⚠️ Partial |
| 30-31 | Priority | 2 | ✅ Wired |
| 32-36 | Memory management | 5 | ✅ Wired |
| 37-39 | I/O Ports | 3 | 🔴 Stub |
| 40-46 | Trace | 7 | 🔴 Stub |
| 47-48 | Memory allocation | 2 | ✅ Wired |
| 49 | Monitoring | 1 | 🔴 Stub |
| 50-53 | Time partitioning | 4 | 🔴 Stub |
| 54-55 | Thread regs + time | 2 | ⚠️ Partial |
| 56-57 | Memory I/O | 2 | ✅ Wired |
| 58-59 | Device | 2 | 🔴 Stub |
| 60-65 | Monitoring | 6 | 🔴 Stub |
| 66 | Memory clear | 1 | ✅ Wired |
| 67 | SMP affinity | 1 | 🔴 Stub |
| 68 | Time partitioning | 1 | 🔴 Stub |
| 69 | System emulation | 1 | 🔴 Stub |
| 70-73 | Preemption/TLS/Locks | 4 | ⚠️ Partial |
| 74 | Timestamp | 1 | ✅ Wired |
| 75-76 | Resource partitions | 2 | ⚠️ Partial |
| 77 | Alarm | 1 | 🔴 Stub |
| 78-96 | KDEV (19 syscalls) | 19 | ⚠️ Partial (2/19) |
| 97 | TLS sync | 1 | 🔴 Stub |
| 98-104 | Health monitoring | 7 | 🔴 Stub |
| 105-108 | Wait queues | 4 | ⚠️ Partial |
| 109 | Cache | 1 | 🔴 Stub |
| 110 | Fast timepart | 1 | 🔴 Stub |
| 111-117 | KDEV filesystem | 7 | 🔴 Stub |
| 118 | Memory region monitor | 1 | 🔴 Stub |

**Summary:** 41 syscalls wired (34.5%), 78 stubs (65.5%), 243 TODOs across core.