# TypePHP OS roadmap

This directory is a long-running experiment. Every milestone must remain
bootable in QEMU and must not change ordinary TypePHP, PHPX, or PHP Nano
behavior.

## Architecture rules

- The project is an ordinary `tpc --nano` consumer. tpc has no kernel option,
  and PHP Nano has no kernel source profile.
- PHP and Composer remain build-time tools; the kernel never links `libphp`.
- Keep copied php-src C/H files unchanged and compile the complete Nano source
  manifest. TypePHP OS owns the required libc/POSIX and C++ ABI boundary.
- Missing ABI operations must be linkable panic stubs. Replace each stub with
  a real kernel service before exposing the corresponding PHP capability.
- Cross-project changes must use generally useful portability contracts such
  as `PHP_NANO_NO_LIBC`, `PHPX_NO_EXCEPTION`, and `PHPX_NO_RTTI`; product-specific
  conditionals are not allowed in PHP Nano or PHPX.
- Ordinary kernel sources live under `kernel/`; the TypePHP entry files are at
  that directory's top level and the native implementation is under
  `kernel/core/`. Same-ABI source files and flags belong in `project.yml`.
  Startup sources live under `boot/` and are built by Make; compatible objects
  may be linked through tpc's generic `objects` facility. Architecture
  packaging and ELF/binary conversion happen after tpc emits the 64-bit ELF.
- Every completed milestone must pass the serial-output QEMU smoke test and
  leave the 64-bit payload with no undefined symbols.

## Milestones

1. **Boot and scalar AOT — complete.** Multiboot v1 bootstrap, x86_64 long
   mode, VGA/COM1 output, TypePHP scalars, functions, and control flow.
2. **Memory and Zend containers — complete.** Physical arena, TypePHP OS ABI
   layer, original `zend_alloc`, `zend_gc`, `zend_string`, `zend_hash`, zval
   destruction, and generated TypePHP arrays/strings through PHPX.
3. **Zend object model — complete for the current demo.** Original object
   store, class entries, inheritance, interfaces, handlers, PHP exception
   classes, generated user classes, construction, properties, and destruction.
4. **Time service — complete.** CMOS wall clock, monotonic host hook, built-in
   date formatting, and the standard extension's `sleep()` path.
5. **Filesystem — fourth slice complete.** ATA PIO, a persistent FAT16 image,
   TypePHP-owned cluster/directory/file logic, file descriptors, POSIX
   directory/stat operations, and PHP's local file stream API. DOS 8.3 path
   lookup, file reads, directory enumeration, file/directory mutation, and
   same-parent rename traverse nested cluster chains. Directories grow by
   allocating and linking additional clusters. A fixed 128-sector LRU
   read/write-through cache now avoids repeated ATA PIO reads while preserving
   synchronous persistence. A general VFS page cache, cross-directory rename,
   replacement semantics, and long filenames are next.
6. **Single-task userspace — third slice complete.** Disk-backed ELF64
   validation/loading from FAT16,
   GDT/TSS, Ring-3 entry, synchronous
   `int 0x80` system calls, COM1 standard I/O, saved parent context, shared
   syscall definitions, complete `argv[]`
   delivery, and independent freestanding C shell/command programs. The first
   Linux-compatible file syscalls cover `openat`, `read`, `write`, `lseek`,
   `close`, `mkdir`, `rmdir`, and `unlink`; `cat`, `write`, `touch`, and the
   directory commands exercise persistent FAT16 changes. The `mv` command
   exposes same-parent rename through a private syscall until full Linux
   rename semantics are implemented. The resident shell
   and every command are independent files under `/BIN` rather than byte arrays embedded in
   the kernel, and command discovery no longer uses a compiled-in whitelist.
   Each process now has its own CR3 and recyclable 4 KiB physical pages. ELF
   segments retain `RX`/`RW` permissions, stacks have an unmapped guard, and
   NX plus supervisor write protection are enabled. Linux-compatible `brk`,
   anonymous private `mmap`, `mprotect`, and `munmap` provide the first real
   userspace memory-management ABI. Ring-3 CPU exceptions terminate a
   short-lived command and restore the saved shell; `fault.elf`, `vmfault.elf`,
   and `wrfault.elf` cover invalid-opcode, isolation, and write-protection
   recovery, while page accounting checks reclamation. The
   programs use standard C `main(argc, argv)` behind a shared crt0 and receive
   a Linux-style initial stack; syscall evolution follows the glibc migration
   rules in `user/README.md`.
7. **Native Class memory.** Exercise Wren GC through Zend MM and verify tracing
   of PHPX fields under sustained allocation.
8. **Kernel services.** Interrupt-driven timer and keyboard, higher-level VM
   region management, Zend-chunk reclamation, and a capability-oriented native
   API.
9. **Packaging and CI.** Automate the two-stage ELF32/ELF64 build and QEMU boot
   smoke test in GitHub Actions.

Later architectures may provide different bootstraps and host ABI adapters.
Generated TypePHP code and PHPX values remain 64-bit on every target.