# Process Model The process model defines how capOS represents isolated user programs, how they receive authority, how they enter and leave the scheduler, and how a parent can observe a child. ## Current Behavior A `Process` currently owns a user address space, a per-process capability table, a ring scratch area, a mapped capability ring, an optional read-only CapSet page, private thread/kernel-stack ledgers, and one or more `Thread` records. Process IDs are assigned by an atomic counter. The scheduler names current execution, run queues, direct IPC handoff, and blocking waiters with generation-checked `ThreadRef` values. Each thread owns its kernel stack, saved CPU context, FS base, and `cap_enter` blocking state, while address space, capability table, ring, CapSet, and resource accounting stay process-owned. ELF images are loaded into fresh user address spaces. PT_LOAD segments are mapped with page permissions derived from ELF flags, the user stack is fixed at `USER_STACK_BASE` (`0x100_0000` as of WASI Phase W.2 sub-slice 1; see `capos-config/src/process_layout.rs` for the canonical layout) with a linker-enforced image limit below it, and PT_TLS data is mapped into a per-process TLS area below the ring page. The process starts from a synthetic `CpuContext` that returns to Ring 3 with `iretq`. `ProcessSpawner` lets a holder spawn packaged boot binaries, grant selected caps to the child, and receive result caps. Every successful spawn returns a non-transferable `ProcessHandle`; child-local endpoint kernel grants also return parent-side client facets so a supervisor can wire imports without sharing endpoint owner authority. `ProcessHandle.wait` either completes immediately for an already-exited child or registers one waiter. Child-local `ThreadControl` grants give runtimes ownership of their current FS base and current-thread exit. Child-local `ThreadSpawner` grants let a process create additional in-process threads and receive process-local `ThreadHandle` result caps for join, detach-on-release, and exit-code observation. ## Design Process construction separates image loading from capability-table assembly. Default boot maps only init in the kernel and gives it a bootstrap CapSet. Spawned children use the same image loading and `Process` creation helpers, but their grants are supplied by the calling process through `ProcessSpawner`. Init resolves service-sourced manifest imports against previously recorded exports before asking ProcessSpawner to create each child. Each process starts with three machine arguments: - `RDI` - fixed ring virtual address (`RING_VADDR`). - `RSI` - process ID. - `RDX` - fixed CapSet virtual address, or zero if no CapSet is mapped. Exit releases authority before the `Process` storage is dropped. The scheduler switches to the kernel page table before address-space teardown, cancels endpoint state for the exiting pid, completes any pending process waiter, and defers the final process drop until execution is on another kernel stack. Future process lifecycle work should keep authority transfer explicit: parents should not gain ambient access to child internals, and child grants should come from named caps plus interface checks. The 7.1.0 in-process threading contract is documented in [In-Process Threading](threading.md). It defines `ThreadSpawner` and `ThreadHandle` as process-local authorities, preserves `ProcessHandle` as the parent-facing whole-process lifecycle handle, and keeps process exit as the operation that releases shared capability authority. ## Invariants - A process cannot access a resource unless its local `CapTable` holds a cap. - Bootstrap CapSet metadata is immutable from userspace. - A stale `CapId` generation must not name a reused cap-table slot. - `ProcessSpawner` raw grants require a copy-transferable cap or an endpoint owner cap; client-endpoint grants require an endpoint owner or `ProcessSpawner` endpoint result source and never add receive or return authority. - `ProcessSpawner` kernel-source Endpoint, FrameAllocator, VirtualMemory, ThreadControl, ThreadSpawner, and EntropySource grants are fresh child-local caps and cannot be badged. QEMU-only PersistentStore grants mount a Store cap through the child-local kernel-source path for focused persistence proofs. Endpoint kernel grants are exportable only through returned parent client facets, not through a shared owner cap in init. - `ProcessHandle` caps are non-transferable. - `ThreadHandle` caps are process-local, non-transferable, and observe only one thread in the same process. - At most one waiter may be registered on a `ProcessHandle`. - Process exit releases cap-table authority before the kernel stack frame is freed. ## Code Map - `kernel/src/process.rs` - `Process`, bootstrap CPU context, ring/CapSet mapping, exit capability cleanup. - `kernel/src/spawn.rs` - ELF mapping, stack mapping, TLS mapping, process construction helpers. - `kernel/src/sched.rs` - process table, process handles, wait completion, exit path. - `docs/architecture/threading.md` - frozen 7.1.0 contract for process-owned versus thread-owned state, creation, FS-base, and join/exit behavior. - `kernel/src/cap/process_spawner.rs` - `ProcessSpawnerCap`, `ProcessHandleCap`, spawn grant validation, child-local kernel grants, child CapSet construction. - `capos-lib/src/cap_table.rs` - `CapId` generation and cap-table operations. - `capos-config/src/capset.rs` - fixed CapSet page ABI. - `schema/capos.capnp` - `ProcessSpawner`, `ProcessHandle`, and `CapGrant`. - `init/src/main.rs` - BootPackage manifest validation, generic spawn loop, child waits, and hostile spawn checks. ## Validation - `make run-smoke` validates init-owned default service startup, `ProcessSpawner`, `ProcessHandle.wait`, child grants, exit cleanup, and clean halt. - `make run-spawn` validates the narrower ProcessSpawner graph for endpoint, IPC, VirtualMemory, FrameAllocator cleanup, and hostile spawn failures. - `cargo test-lib` covers `CapTable` generation, stale-slot, and transfer primitives. - `cargo test-config` covers CapSet and manifest metadata used to build process grants. - `cargo build --features qemu` verifies the kernel and QEMU-only paths compile. ## Open Work - Add lifecycle operations such as kill and post-spawn grants only after their authority semantics are explicit. - Implement restart policy outside the kernel-side static boot graph.