Phase 49

Architectural Declaration

m3OS gains an explicit, enforceable architecture contract for what belongs in ring 0, what is transitional, and what must move to userspace over time. The phase also turns the giant syscall surface into a structure that can be unwound safely in later phases.

Complete

Learning goal

Understand the difference between a documented architecture and an architecture that constrains implementation choices.

Why this phase matters

How it works in m3OS

Phase 49 makes the kernel/userspace boundary explicit and enforceable. Before this phase, m3OS described itself as a microkernel but lacked a formal contract for what belongs in ring 0, what is transitional, and what must eventually move to userspace. This phase closes that gap by decomposing the syscall surface, classifying every kernel subsystem by long-term ownership, and adopting a userspace-first rule for new policy-heavy code.

How it builds on earlier phases

This phase builds on Security Foundation and turns that foundation into Architectural Declaration.

Implementation outline

Inventory the current kernel, syscall, and service boundaries against the documented microkernel ideal.
Create a keep/move/transition matrix and link it from the architecture and roadmap docs.
Split syscall.rs into subsystem-oriented modules or an equivalent staged decomposition.
Tag major modules and service paths by long-term ownership.
Document the userspace-first rule for future policy-heavy work.
Update roadmap dependencies and contributor-facing docs to reflect the declared architecture.
Validate that the refactor still builds cleanly and that the docs match the code layout.

Task progress snapshot

43 of 43 tracked tasks are complete.

Documentation targets

Documentation deliverables have not been listed yet.

Deferred follow-on work

Full service extraction for storage, networking, and display
Broad POSIX/libc boundary redesign
Strong automated architecture-lint enforcement beyond documentation and review rules

Source materials

Important code

Code spotlight cards

Create syscall module directory structure. Why it matters: The monolithic syscall handler mixed all subsystem concerns in one file, making ownership boundaries invisible. Focus on `syscall_handler` and `mod.rs` in `kernel/src/arch/x86_64/syscall/mod.rs` while you trace the snippet.

/// Linux syscall number → handler dispatch (Phase 12, T011–T026).
///
/// Numbers that happen to match our Phase 11 ABI are handled identically.
/// The custom debug-print syscall is moved from 12 → 0x1000 to free up
/// Linux brk = 12.
///
/// # Syscall audit (T011) — Linux numbers that musl requires
///
/// | Linux # | Name        | Implementation        |
/// |---------|-------------|----------------------|
/// |       0 | read        | ramdisk / stdin stub  |
/// |       1 | write       | stdout → serial       |
/// |       2 | open        | ramdisk lookup        |
/// |       3 | close       | fd-table release      |
/// |       5 | fstat       | minimal stat struct   |
/// |       8 | lseek       | per-fd offset update  |
/// |       9 | mmap        | anonymous only        |
/// |      11 | munmap      | stub (no-op)          |
/// |      12 | brk         | frame-backed heap     |
/// |      16 | ioctl       | TIOCGWINSZ only       |
/// |      19 | readv       | loop over read        |
/// |      20 | writev      | loop over write       |
/// |      39 | getpid      | ✓ same as Phase 11    |
/// |      57 | fork        | ✓ same as Phase 11    |

View on GitHub

Filesystem syscall module. Why it matters: Filesystem operations are the largest group of syscalls and the primary extraction target for later phases. Focus on `sys_open` and `sys_read` in `kernel/src/arch/x86_64/syscall/fs.rs` while you trace the snippet.

View on GitHub

Memory management syscall module. Why it matters: Memory syscalls are kernel mechanisms that stay permanently in ring 0. Focus on `sys_mmap` and `sys_munmap` in `kernel/src/arch/x86_64/syscall/mm.rs` while you trace the snippet.

        9 => super::sys_linux_mmap(arg0, arg1, arg2),
        // mprotect
        10 => super::sys_mprotect(arg0, arg1, arg2),
        // munmap
        11 => super::sys_linux_munmap(arg0, arg1),
        // brk
        12 => super::sys_linux_brk(arg0),
        // framebuffer_mmap
        0x1006 => super::sys_framebuffer_mmap(),
        _ => return None,
    };
    Some(result)

View on GitHub

Key files

kernel/Cargo.toml — When the phase lands, bump kernel/Cargo.toml and any release/version references to 0.49.0.
kernel/src/arch/x86_64/syscall/mod.rs — Thin syscall dispatcher routing to subsystem modules
kernel/src/arch/x86_64/syscall/fs.rs — Filesystem syscall implementations
kernel/src/arch/x86_64/syscall/mm.rs — Memory management syscall implementations
kernel/src/arch/x86_64/syscall/process.rs — Process lifecycle syscall implementations
kernel/src/arch/x86_64/syscall/net.rs — Network syscall implementations
kernel/src/arch/x86_64/syscall/signal.rs — Signal syscall implementations
kernel/src/arch/x86_64/syscall/io.rs — I/O multiplexing syscall implementations
kernel/src/arch/x86_64/syscall/time.rs — Time syscall implementations
kernel/src/arch/x86_64/syscall/misc.rs — Miscellaneous syscall implementations
docs/appendix/architecture-and-syscalls.md — Architecture contract with keep/move/transition matrix

How real OSes differ

Monolithic kernels like Linux do not need this phase because their answer is already "the kernel owns it."
Mature microkernels usually enforced the boundary earlier and more aggressively than m3OS has so far.
m3OS is taking the slower but more teachable route: declare the target explicitly, then migrate toward it without pretending the gap does not exist.

Success criteria

A documented keep/move/transition matrix exists for the major kernel and service subsystems.
The syscall surface is decomposed enough that subsystem ownership is obvious in the source tree.
New high-level policy is explicitly documented as userspace-first unless justified otherwise.
The main architecture docs clearly distinguish current implementation reality from target architecture.
`cargo xtask check` still passes after the structural refactor.

Related phases

Keep exploring the roadmap

Security Foundation

m3OS closes the trust-floor gaps that currently block any honest claim of "safe enough for serious headless use." When this phase lands, identity transitions, password storage, entropy, and default remote-exposure behavior all match the project's intended multi-user and network-facing story.

IPC Completion

m3OS gains the missing IPC and bulk-data pieces required for serious userspace services: safe capability transfer, practical large-payload transport, ring-3-safe service registration, and clear failure semantics for the canonical server loop.