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/plan/roadmap.md

@@ -0,0 +1,179 @@
+# Roadmap — everything else still open
+
+The three current decisions have their own documents; see
+[README.md](README.md). This file holds what is left: work that is scoped,
+agreed and unstarted, with nothing in it that is finished.
+
+**Finished work is not here.** It moved to
+[../architecture/](../architecture/) and was rewritten as a description of what
+it produced — see [the rule](../README.md#the-rule-that-keeps-this-from-rotting).
+What used to be phases 1 through 4 of this file, several hundred lines of ticked
+boxes, is now `usb`, `networking.md`, `graphics.md` and `devices.md` over there.
+
+---
+
+## 1. Storage and the boot path
+
+**Make a USB disk mountable and bootable.** The xHCI stack, the bulk-only
+transport, the SCSI layer and the block device all work — a superblock reads back
+through `bread()`. What is missing is that **the root device is compiled in
+rather than selectable**, so nothing can be told to mount it.
+
+This is also the first piece of the installer, and it is the single change that
+would most enlarge what SchOS can boot from.
+
+## 2. Graphics
+
+- **A `/dev/dri`-style device with mode setting**, so resolution stops being
+  whatever the loader asked for. Worth doing *with*
+  [hybrid.md](hybrid.md)'s GPU eviction rather than before it — moving the driver
+  out is what makes a modeset API affordable to design properly.
+- **Double buffering and vblank.** `display_ops` specifies both and no driver
+  implements either. Schcom needs both to not tear.
+- **Port the console onto the text layer and delete the cell grid.** The layer
+  exists, the rasteriser exists, and the console still indexes `font_data[256][16]`.
+- **Load a font from disk** and point the console at it.
+- **CFF/Type 2 charstrings**, so OTF fonts work. A separate `font_ops` provider
+  and a bytecode interpreter, *not* an extension of the `glyf` path.
+- **Text layout** — advance widths, kerning — as a library in `lib/`, so the
+  terminal and the file manager are not each solving it.
+
+The console keeps its fixed grid until the first item above; proportional text
+belongs to the GUI.
+
+## 3. Networking
+
+Three things the stack owed on the day it landed, all still owed:
+
+- **`accept()` does not report the peer's address**, and there is no
+  `getsockname`/`getpeername`. Nothing has needed them yet; a server that wants
+  to log who connected will.
+- **No routing table.** With two interfaces up, the first is the default route
+  and the second is reachable only by an address on its own subnet. That is a
+  rule rather than an accident, and it is not routing.
+- **Receive is polled.** The network thread looks at the NIC every timer tick
+  when the link is idle, so an arriving frame waits up to 10 ms. Waking that
+  thread from the e1000 interrupt is the real fix, and was deliberately not the
+  first version: a receive path woken by an interrupt is much harder to debug
+  than one that is asked.
+
+`setsockopt` returning 0 for everything is in
+[foundations.md](foundations.md) instead, because the Wayland work needs it.
+
+## 4. The interactive crash screen
+
+PSOGM renders and stops. The idea is *a small OS inside the crash*, and the
+framing decides the design:
+
+> At panic time the kernel is the only thing running, which is exactly why it can
+> offer what a live system cannot: walk the stack, read another process's memory,
+> dump page tables, inspect the process table — with no scheduler and no locking
+> to respect, because nothing else can race you.
+
+What makes it a *system* rather than a print statement is that it keeps the base
+machine's drivers. Concretely, the ones that work with interrupts off: the
+framebuffer (`gfx_draw_pixel` is a plain memory write), the PS/2 keyboard
+(pollable via ports 0x60/0x64), and the serial port. **Those three are a complete
+console.**
+
+Everything else — IDE, USB, the timer, anything that sleeps or takes a
+sleeplock — is off limits, because the lock it needs may be precisely the one
+held by the CPU that just died.
+
+So the shape is a **polled event loop over preallocated state**: no `kalloc`, no
+`sleep`/`wakeup`, no `acquire` on anything a live path might hold, one static
+command buffer, and that driver set. **That restriction is not a limitation to
+work around later; it is the invariant that makes the mode trustworthy when
+everything else is not.** Anything wanting more should be answered by rebooting
+into a recovery environment.
+
+A useful precedent to read but not copy: DDB, the BSD in-kernel debugger, is
+exactly this, and its hard-won rule is the same one — *a debugger that can
+deadlock is worse than no debugger.*
+
+## 5. The installer and `.sip`
+
+Scoped in [`projects/schinst/README.md`](../../projects/schinst/README.md),
+which holds the detail. In short:
+
+- [ ] `.sip` format specification, **written down before any code**
+- [ ] `tools/mksip` — capture a directory tree into a package
+- [ ] The apply path
+- [ ] An installation environment that boots from the ISO, partitions, applies
+      the `.sip`, and installs the loader
+
+`.sip` is modelled on WIM, and the thing worth copying from WIM is that it is
+**file-based, not block-based**: one file holds a whole filesystem, applies to a
+partition of any size, and several images can share their common files.
+
+**Most of this already exists.** `tools/mkschfs.c` and `tools/mkfs.c` both do
+content dedup with an `(st_dev, st_ino)` fast path, and SchFS's B-tree is content
+addressed. `mksip` should share that code rather than reimplement it — that is
+the reason the dedup was factored the way it was.
+
+Open questions, all wanting a decision before code:
+
+- **Compression.** Something with a small decompressor is worth more than
+  something with a good ratio, because the decompressor runs in the installation
+  environment.
+- **Multiple images per `.sip`** — WIM's real trick, install/recovery/boot
+  sharing one blob store. Worth the complexity now, or not?
+- **Can the kernel mount a `.sip` read-only directly?** It is close to a
+  filesystem already, and if it can, the installation environment's root can
+  simply *be* the `.sip`.
+
+The GUI for this is a Wayland client; see [wayland.md](wayland.md).
+
+## 6. SchFS beyond SchOS
+
+In the order they should happen.
+
+**~~An on-disk format version~~, and an upgrade path.** The version policy is
+done — see [../architecture/schfs.md](../architecture/schfs.md). What remains is
+the **upgrade step**, and it cannot be written until there are two formats to
+convert between; the first bump is when that becomes real work rather than
+speculation.
+
+The format is now pinned, which is what the other two items were waiting on.
+
+**A Linux implementation, FUSE first.** Three reasons in order of weight: it can
+be tested with `fsx` and `xfstests`, which are far harsher than anything written
+alongside the code; it carries no licence entanglement, since libfuse is LGPL and
+used across a process boundary; and it can reuse the read/write logic already in
+`tools/mkschfs` and `tools/schfs_fsck` rather than being written twice and having
+the two disagree.
+
+A kernel module is a different project, comes only after FUSE passes `xfstests`,
+and carries the licence problem [../licensing.md](../licensing.md) describes.
+
+**The missing features**, listed honestly before adding any: no journal replay
+across an unclean shutdown beyond what copy-on-write gives for free, no
+snapshots, no sparse-file support, and no online `fsck`. **Snapshots are the one
+where the existing design already pays for most of the cost** — the B-tree is
+copy-on-write, which is most of the machinery; nothing takes or names a snapshot.
+
+## 7. The kernel's own gaps
+
+Not phases, and each one improves everything above it:
+
+- **A slab or pool allocator.** `kalloc` hands out one page at a time, and every
+  subsystem written since has invented its own fixed-size table to work around
+  that. This is the single change that would most improve the rest of the kernel.
+- **A page cache**, which is what a general writable `MAP_SHARED` needs.
+  [foundations.md](foundations.md) delivers a `memfd` instead, which is narrower
+  and sufficient for the GUI.
+- **Symlinks in procfs**, so `/proc/<pid>/exe` can be one and `ps -o comm` stops
+  printing `[init]`. Belongs with the rest of the VFS work rather than on its own.
+- **The `ls -lR` hang.** Heavy directory listing across many commands in one long
+  shell session eventually makes a *later*, unrelated directory hang; the same
+  command succeeds on a fresh boot. Not inode or file table exhaustion — both
+  fail cleanly and neither fired. Next step: instrument `itable`/`ftable`
+  occupancy across a long session and watch what climbs.
+
+---
+
+## Kept out of scope on purpose
+
+- Anything that needs pushing or publishing. This work stays local.
+- TrueType hinting.
+- XWayland.