docs: four directories, and a rule for when a thing leaves the roadmap

docs/ was ten files where a plan, a description, a guide and a bug report all
sat next to each other. It is now architecture/ (what SchOS is), plan/ (what it
will be), guides/ (how to work on it) and history/ (why it is like this), with
an index that states the one rule holding it together: when something is
finished it moves from plan/ to architecture/ and is rewritten as a description
of the thing rather than a record of building it.

A ticked checkbox says the work happened. It does not say what the work
*produced*, and six months later the checkbox is all that is left. The network
stack proved the point: finished, verified end to end, and for a month the only
description of it anywhere was a checkbox four levels of indentation deep.

So roadmap.md went from 534 lines to 181 -- nothing deleted, the done work
graduated. Seven subsystems that were finished and undescribed now have
descriptions: boot, kernel, syscalls, filesystem, networking, graphics, usb,
init. Every one ends with "What it does not do", which is the section that pays;
a document listing only strengths is marketing, and the reader who needs it most
is the one about to trip over a limitation nobody wrote down.

schfs.md still opened with "phases 1 through 3 1/2 are done, phase 4 is next"
long after all five had landed. It is a description now, with the phase record
and the hard-won bugs moved to history/.

Three corrections found on the way, all load-bearing:

  * projects/schcom/README.md claimed SCM_RIGHTS was done. There is no
    sendmsg/recvmsg in the kernel at all, and an entire GUI plan rested on it.
  * The root README said "No TCP/IP" months after the stack landed.
  * history/kernel.md sec.7 was marked "in progress" on a problem that process
    groups solved.

Also adds plan/1.0.md, which draws a finish line so the open list stops being
infinite, and marks schwm/ and schde/ superseded: in Wayland the compositor is
the window manager, so that split dissolves rather than being abandoned.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2

docs/architecture/syscalls.md

@@ -0,0 +1,131 @@
+# Syscalls, and the Linux personality
+
+Two things happen at this boundary. SchOS has its own syscall numbering, and it
+also answers Linux's — which is why musl, toybox and mksh run unmodified.
+
+---
+
+## One table, everything generated
+
+**Syscalls are declared in exactly one place:**
+[`kernel/sys/table.inc`](../../kernel/sys/table.inc). One line each.
+
+```c
+SYSCALL(nr, linux_nr, name)     // implemented as sys_<name>()
+SYSCALL_ALIAS(linux_nr, name)   // a second Linux number for the same handler
+```
+
+Three things are generated from it by macro expansion, and none is
+hand-maintained:
+
+| Generated | Where |
+|---|---|
+| The `SYS_*` constants | `include/syscall.h` |
+| The dispatch table | `kernel/sys/syscall.c` |
+| The Linux translation map | `kernel/sys/linux_abi.c` |
+
+Adding a syscall is therefore two edits: a line here, and a body written with
+`SYSCALL_DEFINE(<name>)` in one of the `kernel/sys/sys_*.c` files.
+
+**This replaced a two-place scheme and the reason is worth keeping.** The Linux
+number used to live in a second hand-written table. Adding a syscall meant three
+edits across two files, and forgetting the second one left the call *unreachable
+from every musl-linked program* while looking perfectly registered in the first.
+A syscall can no longer be half-registered.
+
+## How a Linux binary runs
+
+The translation is a flat array indexed by Linux syscall number, whose value is
+the native `SYS_*` number — or 0, meaning not implemented, which dispatches to
+`-ENOSYS`.
+
+It is enabled **per process**, and selected automatically by `exec()`:
+
+```c
+// musl binaries have entry >= 0x100000; SchOS-native ones are linked at 0x4000
+if (elf.entry >= LINUX_ABI_ENTRY_THRESHOLD)
+    myproc()->syscall_map = linux_syscall_map;
+```
+
+A link address is a crude discriminator and it is honest about being one. It
+works because the two classes of binary in this system are linked by two
+different linker scripts at two very different addresses.
+
+There is also `enable_linux_abi()` as an explicit call, which is why
+`cmd/schinit/main.c` carries a warning not to use it: doing so mid-process would
+renumber the syscalls the caller still has to make.
+
+### Native vs. Linux numbering
+
+Some calls have no Linux equivalent and are marked `NO_LINUX`: `sleep`,
+`uptime`, `reboot`, `shutdown`, `getmouse`, `vga_sync`, `schfs_index`,
+`schfs_query`. These are reachable only from first-party programs linked
+against `lib/`.
+
+They all land on the same scratch index in the translation array and overwrite
+each other there, which is harmless — no real Linux syscall uses that number, so
+the slot is never dispatched.
+
+### Where the two disagree on a name
+
+`shutdown` is the one collision. SchOS has a native `shutdown()` that powers the
+machine off, and Linux number 48 is the socket call. Two syscalls cannot share a
+`sys_` function name, so Linux 48 maps to `sockshutdown`.
+
+## What is implemented
+
+Roughly 190 native numbers covering:
+
+| Area | |
+|---|---|
+| Process | fork, exec, exit, wait/waitpid/wait4/waitid, clone, kill, sessions, process groups |
+| Identity | the full real/effective/saved set for both uid and gid, groups, umask |
+| Memory | mmap, munmap, mprotect, brk/sbrk, madvise, System V shared memory |
+| Filesystem | the ordinary set, the whole `*at()` family, statfs, xattr, mount/umount2 |
+| I/O | read/write, readv/writev, pread/pwrite, sendfile, poll/select/ppoll/pselect6, epoll, ioctl, fcntl |
+| Sockets | socket, bind, listen, accept, connect, sendto, recvfrom, socketpair, setsockopt, getsockopt |
+| Signals | rt_sigaction, rt_sigreturn, rt_sigsuspend, rt_sigpending, rt_sigtimedwait, sigaltstack |
+| Time | gettimeofday, clock_gettime, clock_getres, nanosleep, clock_nanosleep, alarm, timers |
+| Notification | eventfd2, timerfd_create/settime/gettime, signalfd4 |
+
+### Argument fetching
+
+`fetchint`, `fetchaddr`, `fetchstr` and `argptr` validate a user pointer through
+the page tables and nothing else. They previously rejected any address
+`>= proc->sz`, on the assumption that every valid user pointer lives in the
+heap — which is wrong for stack addresses and for every `mmap`'d buffer, i.e.
+for most pointers real programs pass.
+
+`uva2ka()` translates a user virtual address and **returns the in-page offset**,
+which it did not originally do. Every caller that read or wrote through a
+non-page-aligned pointer — `TIOCGPGRP`, `TCGETS`, `getcwd`, signal masks,
+`times()`, `sysinfo()` — was touching the wrong address whenever the pointer was
+not page-aligned, i.e. almost always.
+
+**`uva2ka()` guarantees only the page containing that address.** A structure
+copied in bulk through one translation runs off the end of the mapped page when
+the pointer lands near a boundary — and `P2V` is a flat offset, so "the next
+page" in kernel space has nothing to do with the user's next page. That bug
+corrupted unrelated kernel memory and crashed every freshly `exec`'d shell. Copy
+field by field, each through its own translation, or use `copyin`/`copyout`.
+
+---
+
+## What it does not do
+
+- **No `sendmsg`/`recvmsg`**, and therefore no ancillary data and no
+  `SCM_RIGHTS`.
+- **No `memfd_create`.**
+- **No `getsockname` or `getpeername`**, and `accept()` does not report an
+  AF_INET peer's address.
+- **`setsockopt` handles six options** and answers `ENOPROTOOPT` for everything
+  else. `SO_RCVTIMEO`/`SO_SNDTIMEO` are among the refused.
+- **`clone` does not share an address space**, so it is `fork` with extra steps.
+- **`sched_setaffinity` is accepted and ignored.**
+- **`getrusage` does not distinguish `RUSAGE_CHILDREN`** from `RUSAGE_SELF`, and
+  fills in only the calling process's own tick count.
+- **The ABI is chosen by link address.** It works, and it is a heuristic rather
+  than a fact about the binary.
+- **`/proc/<pid>/exe` is a regular file, not a symlink**, so `readlink()` on it
+  fails and `ps -o comm` prints `[init]` rather than `init`. Default `ps` and
+  `top` output is unaffected.