Implementation Plan

Implementation Plan

Purpose

This page converts the original repository implementation plan into a wiki roadmap for building OSAI from design stage to developer preview.

Contents

• Rules
• Original Plan Coverage
• Phase 0: Repo and Build Foundation
• Phase 1: QEMU Boot
• Phase 2: Kernel Core
• Phase 3: Memory Management
• Phase 4: Interrupts and Timers
• Phase 5: VirtIO Storage and Network
• Phase 6: AI Cell Runtime
• Phase 7: Low-Latency Networking
• Phase 8: CPU AI Runtime
• Phase 9: Intel Desktop
• Phase 10: Intel Xeon
• Phase 11: ARM/NVIDIA
• Phase 12: Release Hardening

Rules

• One deliverable per commit or pull request.
• Kernel code is freestanding C99 plus minimal architecture assembly.
• No libc assumptions inside the kernel.
• No heap allocation before kernel heap initialization.
• No dynamic allocation in scheduler, networking, AI Cell, or memory hot paths after service warmup.
• No migration unless a service explicitly opts into it.
• No hidden background work on leased AI cores.
• No post-READY page faults on hot AI cores by default.
• Every architecture feature needs a generic fallback.
• Every hot-path structure documents cache-line ownership.

Original Plan Coverage

The original repository implementation plan was migrated into the wiki with this coverage:

Original section	New wiki location
Product Objective	[[Project Purpose
Performance Targets	[[Performance Targets
Hardware Rollout Order	[[QEMU on macOS
Core Architecture	Architecture, [[AI Cells
Repository Structure Codex Must Create	[[Build System
Codex Rules	this page, [[Codex Work Packages
Phase 0: Build and Host Bootstrap	Phase 0 below, [[Build System
Phase 1: UEFI Loader and First QEMU Boot	Phase 1 below, [[QEMU on macOS
Phase 2: Kernel Entry, Logging, Panic, and PMM	Phase 2 below
Phase 3: Virtual Memory, Kernel Heap, and Hugepage Metadata	Phase 3 below, [[Memory System
Phase 4: Exceptions, Interrupts, and Timers	Phase 4 below
Phase 5: SMP and Per-Core State	Phase 6 below, [[Scheduler and Core Isolation
Phase 6: User Mode, ELF Loader, and Minimal Syscalls	Phase 5 below
Phase 7: Device Discovery, PCI, VirtIO, and Storage	Phase 5 below, [[Driver Model
Phase 8: Control-Plane Networking and SSH	Phase 5 and Phase 7 below, Networking, [[Security Model
Phase 9: Service Manager and AI Cell Manifests	Phase 6 below, [[AI Cells
Phase 10: AI Memory Architecture	Phase 8 below, [[Memory System
Phase 11: CPU AI Runtime MVP	Phase 8 below, [[CPU AI Runtime
Phase 12: Low-Latency netq Networking	Phase 7 below, Networking
Phase 13: Source-Code Agent Runtime	[[App Agents
Phase 14: Intel Desktop Port	Phase 9 below, [[Intel Desktop Port
Phase 15: Intel Xeon Port	Phase 10 below, [[Intel Xeon Port
Phase 16: ARM/NVIDIA N1X-Class Port	Phase 11 below, [[ARM NVIDIA Port
Phase 17: Persistent Storage and System Image	[[Filesystem and Storage
Phase 18: Security and Agent Safety	[[Security Model
Phase 19: Benchmarks	[[Testing and Benchmarking
100% Completion Criteria	Phase 12 below, Roadmap
First Ten Codex Tasks	[[Codex Work Packages
Implementation Biases	this page, [[Build System
Final Rule	this page and [[Codex Work Packages

Phase 0: Repo and Build Foundation

Create the source tree, Makefile or build system, image scripts, QEMU scripts, test scripts, format scripts, and host bootstrap checks.

Acceptance:

• make all succeeds;
• make image succeeds;
• make test succeeds;
• make qemu starts QEMU even before a real kernel exists.

Phase 1: QEMU Boot

Build a UEFI PE/COFF loader, load kernel.elf, gather the memory map and ACPI RSDP, exit boot services, and jump to kernel_entry.

Acceptance:

• serial log shows loader start;
• kernel.elf is loaded;
• kernel entry is reached;
• missing kernel produces a useful boot error.

Phase 2: Kernel Core

Implement kernel entry, early logging, panic, assertions, and physical memory manager.

Acceptance:

• kernel entry log appears;
• memory totals print;
• page allocate/free test passes;
• panic path prints file, line, and message.

Phase 3: Memory Management

Implement page tables, virtual memory, kernel heap, arena allocator, and hugepage metadata.

Acceptance:

• map/unmap tests pass;
• heap tests pass;
• read-only mapping faults safely;
• hugepage support is logged.

Phase 4: Interrupts and Timers

Install GDT/IDT, exception handlers, APIC/x2APIC detection, page-fault diagnostics, and monotonic time.

Acceptance:

• invalid opcode, page fault, and breakpoint tests report correctly;
• monotonic time increases;
• no tick scheduler is introduced for future hot cores.

Phase 5: VirtIO Storage and Network

Implement ACPI table walking, PCI discovery, VirtIO feature negotiation, VirtIO block reads, GPT parsing, VirtIO net RX/TX, Ethernet, ARP, IPv4, ICMP, UDP, and a minimal TCP control path.

Acceptance:

• VirtIO block and net are discovered;
• /init or equivalent payload loads from disk image;
• ICMP echo replies work in QEMU;
• block and network errors fail safely.

Phase 6: AI Cell Runtime

Implement service manifests, core leases, pinned workers, cell lifecycle, resource accounting, and telemetry counters.

Acceptance:

• AI Cell starts and stops;
• worker core does not migrate;
• post-warmup page faults are counted;
• invalid resource requests are rejected.

Phase 7: Low-Latency Networking

Build the per-core TCP/UDP path, queue ownership, flow-to-core pinning, adaptive polling, interrupt fallback, and copy-small/zero-copy-large policy.

Acceptance:

• p50/p95/p99/p999 latency is measured;
• packet processing stays on the owning core;
• hot inference cores are not disturbed by unrelated traffic.

Phase 8: CPU AI Runtime

Add model loader, shared read-only weights, private KV/cache arenas, tokenizer/runtime boundaries, scalar kernels, and architecture-specific CPU paths behind feature detection.

Acceptance:

• one model mapping can be shared by multiple AI Cells;
• KV/cache state is private;
• scalar fallback works;
• hot model arenas are prefaulted.

Phase 9: Intel Desktop

Port to modern Intel Desktop CPUs with P-core/E-core placement, NVMe, PCIe NIC support, thermal telemetry, and tuned baseline comparisons.

Acceptance:

• hot workers stay on P-cores;
• background services stay on E-cores where available;
• performance counters compare against tuned Linux/BSD.

Phase 10: Intel Xeon

Add NUMA policy, server NICs, multi-queue NVMe, IOMMU, MSI-X routing, memory-bandwidth admission control, and many-cell scheduling.

Acceptance:

• AI Cells remain NUMA-local by default;
• NIC/NVMe queues are NUMA-local where possible;
• many agents run under measured resource contracts.

Phase 11: ARM/NVIDIA

Port to ARM/NVIDIA N1X-compatible systems with AArch64 boot, GIC, SMMU, UEFI/SBSA where available, and cluster-aware core policy.

Acceptance:

• system boots on target hardware or emulator;
• hot workers remain in intended clusters;
• memory and latency counters are platform-specific.

Phase 12: Release Hardening

Add signed updates, rollback, installer notes, CI smoke boots, benchmark reports, example app-agent service, and developer-preview documentation.

Acceptance:

• external developer can boot OSAI;
• run a sample CPU-only app agent;
• measure latency, bandwidth, jitter, migration, context switches, and page faults;
• compare against a documented tuned baseline.