Codex Work Packages

Codex Work Packages

Purpose

This page defines operational work packages for Codex sessions building OSAI.

How to Use Codex on OSAI

Use one package per commit or pull request. Never skip tests. Keep boot logs when a task touches boot, kernel, drivers, networking, or platform code. Update documentation when code changes alter architecture, commands, APIs, or benchmark methodology.

Each package must end with a review of logical correctness, API usage, data flow, project integration, docs impact, and build/test results.

Package 001: Build Skeleton

Goal: Create the initial source tree and host build commands.

Allowed files: Makefile, scripts/, boot/, kernel/, userspace/, tests/, docs/README.md.

Implementation steps: create directory skeleton, add host bootstrap script, add placeholder build/image/qemu/test targets.

Commands to run: make all, make image, make test.

Definition of done: commands run and artifacts stay under ignored build output directories.

Tests: host script validates QEMU, LLVM, LLD, Python, Git, image tools, and OVMF availability.

Expected commit message: Add OSAI build skeleton

Package 002: UEFI Hello Loader

Goal: Build a UEFI loader that prints deterministic startup output.

Allowed files: boot/uefi/, scripts/build-image.sh, scripts/run-qemu-x86_64.sh.

Implementation steps: compile PE/COFF EFI app, build FAT EFI image, launch QEMU serial stdio.

Commands to run: make image, make qemu.

Definition of done: serial output includes OSAI loader starting.

Tests: missing firmware or image reports a useful error.

Expected commit message: Add UEFI hello loader

Package 003: Loader and Kernel Handoff

Goal: Load kernel.elf and jump to kernel entry with boot info.

Allowed files: boot/uefi/, kernel/core/, kernel/include/osai/, scripts/.

Implementation steps: validate ELF64, gather memory map, gather ACPI RSDP, exit boot services, pass versioned boot info.

Commands to run: make image, make qemu.

Definition of done: kernel entry logs through serial.

Tests: missing or invalid kernel reports a useful boot error.

Expected commit message: Add kernel handoff from UEFI loader

Package 004: Physical Memory Manager

Goal: Initialize early physical page allocation.

Allowed files: kernel/mm/, kernel/core/, kernel/include/osai/, tests/.

Implementation steps: parse UEFI memory map, reserve kernel/boot/ACPI/MMIO/framebuffer regions, implement allocate/free page.

Commands to run: make test, make qemu.

Definition of done: memory totals print and 1024 allocate/free test passes.

Tests: reserved regions are never allocated.

Expected commit message: Add early physical memory manager

Package 005: Exceptions and Diagnostics

Goal: Add exception handling and panic diagnostics.

Allowed files: kernel/arch/x86_64/, kernel/core/, kernel/irq/, tests/.

Implementation steps: install GDT/IDT, handle CPU exceptions, print page-fault address/error code.

Commands to run: make test, make qemu.

Definition of done: invalid opcode, breakpoint, and page fault tests report correctly.

Tests: fatal unknown exception panics cleanly.

Expected commit message: Add x86_64 exception diagnostics

Package 006: SMP Registry and Core Lease

Goal: Bring up multiple CPUs and prepare no-migration core leasing.

Allowed files: kernel/arch/x86_64/smp.c, kernel/core/, kernel/sched/, tests/.

Implementation steps: register CPUs, log APIC IDs, implement core lease create/release.

Commands to run: make qemu.

Definition of done: QEMU with four CPUs brings all cores online and CPU 1 can be leased to a fixed loop.

Tests: leased loop never migrates.

Expected commit message: Add SMP registry and core leases

Package 007: Minimal User Init

Goal: Run /init in user mode from an initramfs or boot image.

Allowed files: kernel/user/, userspace/init/, runtime/, scripts/.

Implementation steps: load ELF, enter user mode, add minimal syscalls for log, exit, time, map, unmap, and cell info.

Commands to run: make image, make qemu.

Definition of done: /init logs and exits cleanly.

Tests: bad syscall returns an error without crashing the kernel.

Expected commit message: Add minimal user init

Package 008: VirtIO Networking Smoke Test

Goal: Implement enough VirtIO net to reply to ICMP in QEMU.

Allowed files: kernel/dev/virtio/, kernel/net/, scripts/, tests/qemu/.

Implementation steps: implement RX/TX queues, Ethernet, ARP, IPv4 checksum, ICMP echo reply.

Commands to run: make qemu, ping host-forwarded target where configured.

Definition of done: QEMU guest replies to ICMP and logs packet counters.

Tests: malformed frames are dropped safely.

Expected commit message: Add VirtIO net ICMP smoke test

Package 009: AI Cell Manifest MVP

Goal: Add the first AI Cell manifest parser and lifecycle state machine.

Allowed files: kernel/cap/, kernel/sched/, userspace/osctl/, runtime/include/osai/, tests/.

Implementation steps: parse manifest, validate resources, create cell, lease cores, report telemetry.

Commands to run: make test, make qemu.

Definition of done: valid manifest starts and invalid manifest is rejected.

Tests: resource conflicts fail safely.

Expected commit message: Add AI Cell manifest MVP

Package 010: Shared Model Arena MVP

Goal: Map one read-only model arena into multiple AI Cells.

Allowed files: kernel/mm/, ai/runtime/, runtime/, tests/.

Implementation steps: create model identity, map read-only shared weights, allocate private KV/cache arenas, prefault hot pages.

Commands to run: make test, make qemu.

Definition of done: two cells share weights while KV/cache remains private.

Tests: write to shared weights fails safely.

Expected commit message: Add shared model arena MVP