Codex Work Packages

Codex Work Packages

Purpose

This page defines directly actionable Codex work packages for building XAI OS one focused commit at a time.

How to Use Codex on XAI OS

• Complete one work package per commit or pull request.
• Read the related wiki pages before editing code.
• Run the commands listed in the package.
• Preserve boot logs for boot, kernel, driver, and networking work.
• Update docs when architecture, commands, APIs, or benchmark methodology change.
• Do not skip tests; if a test cannot run, record why.
• End each package with a review of logical correctness, API usage, data flow, integration, docs impact, and build/test results.

Standard Package Fields

Every package includes ID, title, goal, allowed files, implementation requirements, commands to run, tests, expected output or boot log, definition of done, expected commit message, and forbidden shortcuts.

WP-000: Repository Hygiene

• Goal: keep the main repository ready for source implementation.
• Allowed files: .gitignore, README.md, CONTRIBUTING.md, SECURITY.md, LICENSE.
• Implementation requirements: no generated artifacts, no secrets, README links point to existing wiki pages.
• Commands to run: git status, and the repository secret-scan command from SECURITY.md.
• Tests: README link sanity.
• Expected output or boot log: clean status except intended docs.
• Definition of done: repo is clean and implementation-ready.
• Expected commit message: Maintain repository hygiene
• Forbidden shortcuts: reintroducing long wiki content into README.

WP-001: macOS Host Bootstrap

• Goal: verify host tools for QEMU on macOS.
• Allowed files: scripts/macos-bootstrap.sh, Makefile.
• Implementation requirements: check QEMU, LLVM/Clang, LLD, Python, Git, image tools, OVMF.
• Commands to run: scripts/macos-bootstrap.sh, make test.
• Tests: missing-tool simulation where practical.
• Expected output or boot log: actionable tool status report.
• Definition of done: bootstrap exits non-zero with clear messages when tools are missing.
• Expected commit message: Add macOS host bootstrap checks
• Forbidden shortcuts: hardcoded local absolute tool paths.

WP-002: QEMU Run Scripts

• Goal: add reproducible QEMU commands.
• Allowed files: scripts/run-qemu-x86_64.sh, scripts/run-qemu-aarch64.sh, Makefile.
• Implementation requirements: serial stdio, Q35 x86-64 target, documented memory/SMP defaults.
• Commands to run: make qemu.
• Tests: QEMU starts and reports missing image clearly.
• Expected output or boot log: QEMU invocation printed or executed.
• Definition of done: run scripts are deterministic.
• Expected commit message: Add QEMU run scripts
• Forbidden shortcuts: relying on GUI-only QEMU output.

WP-003: UEFI Loader Skeleton

• Goal: build a minimal UEFI loader.
• Allowed files: boot/uefi/, scripts/build-image.sh, Makefile.
• Implementation requirements: PE/COFF output, serial/console log, no kernel assumptions.
• Commands to run: make image, make qemu.
• Tests: loader prints XAIOS loader starting.
• Expected output or boot log: deterministic loader startup line.
• Definition of done: QEMU reaches loader.
• Expected commit message: Add UEFI loader skeleton
• Forbidden shortcuts: GRUB or BIOS boot.

WP-004: ELF64 Kernel Loading

• Goal: load and validate kernel.elf.
• Allowed files: boot/uefi/, kernel/core/, kernel/include/xaios/.
• Implementation requirements: validate ELF64 headers, load segments, gather boot info.
• Commands to run: make image, make qemu.
• Tests: missing and invalid kernel paths.
• Expected output or boot log: loader reports kernel load and handoff.
• Definition of done: kernel entry is reached.
• Expected commit message: Load ELF64 kernel from UEFI
• Forbidden shortcuts: hardcoded kernel physical addresses.

WP-005: Kernel Entry and Serial Logging

• Goal: implement freestanding kernel entry and early logging.
• Allowed files: kernel/core/, kernel/include/xaios/.
• Implementation requirements: no libc, no heap, serial log, panic path.
• Commands to run: make qemu, make test.
• Tests: panic smoke test.
• Expected output or boot log: XAIOS kernel starting.
• Definition of done: kernel logs and panics cleanly.
• Expected commit message: Add kernel entry and serial logging
• Forbidden shortcuts: using host runtime functions.

WP-006: Physical Memory Manager

• Goal: allocate and free physical pages safely.
• Allowed files: kernel/mm/, kernel/core/, tests/.
• Implementation requirements: parse UEFI map, reserve kernel/boot/ACPI/MMIO/framebuffer.
• Commands to run: make test, make qemu.
• Tests: 1024 allocate/free pages, reserved-region exclusion.
• Expected output or boot log: memory totals and PMM test pass.
• Definition of done: allocator never returns reserved pages.
• Expected commit message: Add physical memory manager
• Forbidden shortcuts: treating all RAM as free.

WP-007: Virtual Memory Manager

• Goal: build kernel page-table management.
• Allowed files: kernel/mm/, kernel/arch/aarch64/, kernel/include/xaios/.
• Implementation requirements: RX text, RO rodata, RW data, MMIO metadata, NX where supported.
• Commands to run: make test, make qemu.
• Tests: translation checks for text, rodata, data, and MMIO; read-only and NX fault smoke tests after exception diagnostics exist.
• Expected output or boot log: VMM test pass.
• Definition of done: early kernel address-space permissions are represented and the QEMU boot path remains stable after MMU enable.
• Expected commit message: Add virtual memory manager
• Forbidden shortcuts: identity-map everything permanently.

WP-008: Exceptions and Panic Path

• Goal: diagnose CPU exceptions.
• Allowed files: kernel/arch/aarch64/, kernel/irq/, kernel/core/.
• Implementation requirements: EL1 vector table, trap handlers, page-fault address/error code.
• Commands to run: make qemu.
• Tests: controlled page fault smoke build.
• Expected output or boot log: controlled fault diagnostics.
• Definition of done: fatal exception panics cleanly.
• Expected commit message: Add exception diagnostics
• Forbidden shortcuts: swallowing faults.

WP-009: Timers

• Goal: provide monotonic time without a hot-core tick scheduler.
• Allowed files: kernel/arch/aarch64/timer.c, kernel/arch/aarch64/gic.c, kernel/include/xaios/.
• Implementation requirements: detect generic counter frequency, monotonic abstraction, GIC distributor discovery, no periodic hot-core scheduler tick.
• Commands to run: make test, make qemu.
• Tests: time increases and remains monotonic.
• Expected output or boot log: timer source and monotonic samples.
• Definition of done: time API works in QEMU.
• Expected commit message: Add monotonic timer support
• Forbidden shortcuts: global periodic scheduler tick.

WP-010: SMP and Per-Core State

• Goal: bring up multiple CPUs and per-core registry.
• Allowed files: kernel/arch/aarch64/smp.c, kernel/core/, kernel/sched/.
• Implementation requirements: PSCI CPU_ON, MPIDR logging, CPU roles, idle reserved non-boot CPUs.
• Commands to run: make qemu.
• Tests: QEMU four-CPU boot.
• Expected output or boot log: all CPUs online with IDs.
• Definition of done: per-core state is addressable.
• Expected commit message: Add SMP and per-core state
• Forbidden shortcuts: generic load balancing.

WP-011: Minimal Service Supervisor

• Goal: run minimal userspace init and service lifecycle skeleton.
• Allowed files: kernel/user/, userspace/init/, userspace/services/, runtime/.
• Implementation requirements: service states first; later EL0 loader, log/exit syscalls.
• Commands to run: make image, make qemu.
• Tests: /init lifecycle logs; invalid control command returns error.
• Expected output or boot log: init lifecycle log.
• Definition of done: control-plane lifecycle can start, stop, and reject invalid commands.
• Expected commit message: Add minimal service supervisor
• Forbidden shortcuts: broad POSIX scope.

WP-012: VirtIO Block

• Goal: read blocks from QEMU disk image.
• Allowed files: kernel/dev/virtio/, kernel/dev/pci/, kernel/fs/.
• Implementation requirements: VirtIO-MMIO feature negotiation, queue setup, safe read path.
• Commands to run: make image, make qemu.
• Tests: read known block and handle read error.
• Expected output or boot log: virtio-blk device and test block log.
• Definition of done: block read path works in QEMU.
• Expected commit message: Add VirtIO block read path
• Forbidden shortcuts: assuming disk geometry.

WP-013: VirtIO Net

• Goal: exchange a test packet in QEMU.
• Allowed files: kernel/dev/virtio/, kernel/net/.
• Implementation requirements: VirtIO-MMIO RX/TX queues, Ethernet, ARP smoke, checked packet lengths.
• Commands to run: make qemu.
• Tests: ARP request/reply exchange with QEMU user networking; malformed frame drop later.
• Expected output or boot log: packet counters and ARP reply success.
• Definition of done: QEMU guest exchanges packets.
• Expected commit message: Add VirtIO net smoke path
• Forbidden shortcuts: unchecked packet lengths.

WP-014: AI Cell Metadata Model

• Goal: define AI Cell identity, manifest, and lifecycle states.
• Allowed files: kernel/runtime/, kernel/include/xaios/, kernel/sched/, userspace/osctl/.
• Implementation requirements: states, resource fields, validation errors.
• Commands to run: make test.
• Tests: parse valid/invalid manifests.
• Expected output or boot log: lifecycle state transitions.
• Definition of done: metadata model rejects incomplete cells.
• Expected commit message: Add AI Cell metadata model
• Forbidden shortcuts: implicit default privileges.

WP-015: Core Lease API

• Goal: assign fixed cores to AI Cells.
• Allowed files: kernel/sched/core_lease.c, kernel/core/, runtime/include/xaios/.
• Implementation requirements: create/release lease, conflict detection, no migration.
• Commands to run: make qemu.
• Tests: lease CPU 1 to fixed loop; conflict fails.
• Expected output or boot log: lease table and zero migration counter.
• Definition of done: leased loop never migrates.
• Expected commit message: Add core lease API
• Forbidden shortcuts: scheduler fallback migration.

WP-016: Memory Arena API

• Goal: create explicit memory arenas.
• Allowed files: kernel/mm/arena.c, runtime/include/xaios/mem.h, tests/.
• Implementation requirements: model, KV/cache, source index, build output, log arenas.
• Commands to run: make test.
• Tests: allocate, map, unmap, permission checks.
• Expected output or boot log: arena table.
• Definition of done: arenas enforce ownership.
• Expected commit message: Add memory arena API
• Forbidden shortcuts: untracked heap allocations on hot paths.

WP-017: Shared Model-Weight Mapping MVP

• Goal: map one read-only model object into multiple AI Cells.
• Allowed files: kernel/mm/model_map.c, ai/runtime/, tests/.
• Implementation requirements: shared read-only weights, private KV/cache, prefault.
• Commands to run: make test, make qemu.
• Tests: two cells share weights; write fault fails safely.
• Expected output or boot log: shared mapping identity and private KV arenas.
• Definition of done: no duplicate physical weight copy.
• Expected commit message: Add shared model-weight mapping MVP
• Forbidden shortcuts: silently copying weights per cell.

WP-018: Low-Latency UDP MVP

• Goal: build first latency-first UDP command path.
• Allowed files: kernel/net/udp.c, kernel/net/, bench/udp_latency/.
• Implementation requirements: owner core, queue counters, p50/p95/p99/p999 output.
• Commands to run: make qemu, UDP echo benchmark.
• Tests: UDP echo under idle and inference-stub load.
• Expected output or boot log: UDP latency JSON.
• Definition of done: benchmark artifact follows Benchmark Result Format.
• Expected commit message: Add low-latency UDP MVP
• Forbidden shortcuts: performance claims without baseline.

WP-019: Low-Latency TCP Design Skeleton

• Goal: define minimal TCP control path and future hot path.
• Allowed files: kernel/net/tcp_min.c, kernel/net/, runtime/include/xaios/net.h.
• Implementation requirements: connection state skeleton, owner core metadata, no generic socket buffer hot path.
• Commands to run: make test.
• Tests: state transitions and reset/error paths.
• Expected output or boot log: TCP state machine tests.
• Definition of done: skeleton is ready for QEMU control-plane smoke.
• Expected commit message: Add low-latency TCP skeleton
• Forbidden shortcuts: full TCP rewrite before requirements are tested.

WP-020: CPU AI Runtime Skeleton

• Goal: add CPU-only runtime boundary.
• Allowed files: ai/runtime/, ai/tokenizer/, ai/kernels/, runtime/include/xaios/.
• Implementation requirements: scalar fallback, feature dispatch stubs, shared model/private KV hooks.
• Commands to run: make test.
• Tests: deterministic decode stub.
• Expected output or boot log: runtime stub output.
• Definition of done: no CUDA/Metal/GPU dependency.
• Expected commit message: Add CPU-only AI runtime skeleton
• Forbidden shortcuts: vendor accelerator dependency.

WP-021: Source Index Service Skeleton

• Goal: index source files for embedded app agents.
• Allowed files: ai/source_index/, userspace/services/, tests/.
• Implementation requirements: file list, symbol placeholder, dependency metadata, memory arena accounting.
• Commands to run: make test.
• Tests: fixture repo indexing.
• Expected output or boot log: source index summary.
• Definition of done: index service runs outside inference cores.
• Expected commit message: Add source index service skeleton
• Forbidden shortcuts: indexing secrets or ignored files by default.

WP-022: Git Worktree Agent Skeleton

• Goal: isolate generated patches in Git worktrees.
• Allowed files: ai/git_agent/, userspace/services/, tests/integration/.
• Implementation requirements: worktree creation, status check, apply patch, run tests, block failed commit.
• Commands to run: make test.
• Tests: fixture patch success and failed-test rejection.
• Expected output or boot log: worktree audit log.
• Definition of done: no direct mutation of main worktree.
• Expected commit message: Add Git worktree agent skeleton
• Forbidden shortcuts: pushing without explicit permission.

WP-023: Benchmark Harness

• Goal: add benchmark runner and JSON validation.
• Allowed files: bench/, scripts/, tests/.
• Implementation requirements: emit Benchmark Result Format, include baseline metadata, counters, and workload.
• Commands to run: make test, benchmark JSON validator.
• Tests: sample result validates and missing fields fail.
• Expected output or boot log: valid benchmark JSON fixture.
• Definition of done: no benchmark claim can be made without artifact.
• Expected commit message: Add benchmark harness skeleton
• Forbidden shortcuts: human-only benchmark notes.

Related Pages

• Implementation Plan
• Build System
• Testing and Benchmarking
• Risk Register