docs: the tree moved and the documentation did not

The site and several documents still described the system as it was before
virtual terminals, the new schinit, the hybrid work and descriptor passing.

docs/architecture/init.md described the wrong program. It documented a single
schinit that parses manifests and supervises jobs, which has not been true since
PID 1 was split: PID 1 forks a supervisor, spawns jobs on its behalf and reaps;
the job table lives in /proc/schinit; a heartbeat runs both ways; and
proc_reincarnate() re-execs PID 1 in place rather than panicking. Rewritten
around what exists, keeping the reasoning that is still load-bearing -- the five
failures of the sibling-init scheme, the escalation ladder, and the three bugs in
the reincarnation path that each had to happen before they were obvious.

docs/plan/init.md is deleted, which is the tree's own rule for finished work and
had not been applied. Fourteen source comments referenced it by part number, so
they are repointed at the architecture doc by section name rather than left
dangling -- a deleted document nobody notices is worse than a stale one.

docs/architecture/devices.md gained the section it has been missing since
/dev/pci existed: what a driver needs from a kernel, why mmap is checked against
the caller's claims, why DMA is a call and not a mapping, and why the write back
after an interrupt is not optional. Also that a released device does not come
back by itself, which is true and was nowhere.

docs/architecture/networking.md gained a descriptor-passing section, and
docs/architecture/README.md's stack diagram gained the two layers and the third
seam it was missing. "Two seams hold the whole thing together" has not been true
since /dev/pci.

docs/plan/README.md said the hybrid work was deliberately last, on the argument
that an interface with no consumer is wrong in ways nobody can see. The argument
was right; the conclusion was not, and the document now says why it changed --
the alternative to a driver compatibility layer is writing a driver for every
device that exists, and the original objection is answered rather than ignored
because SchOS's own drivers are the consumers.

The site: a Hybrid section with the eviction transcript, cards for virtual
terminals, schinit and drivers outside the kernel, and the numbers remeasured
rather than estimated -- 46,961 lines, 207 syscalls. The boot log in app.js is
from a boot taken today, and the lines are trimmed to what the console can show
without clipping, each still a verbatim prefix of real output.

Two small rendering fixes found by looking at the pages rather than assuming:
.console pre's min-height is now scoped to the hero, so a static transcript sizes
to its content instead of reserving eight lines it does not have; and the docs
reader's contents panel strips inline marks from headings, so a heading written
`proc_reincarnate()` no longer carries its backticks into the sidebar.

Every intra-doc link checked; none broken.

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

cmd/schinit/main.c

@@ -7,7 +7,7 @@
 // now lives in schinitd (PID 2), and what is left here is deliberately, almost
 // aggressively small.
 //
-// The reason is docs/plan/init.md, and it is worth restating because the
+// The reason is docs/architecture/init.md, and it is worth restating because the
 // smallness looks like an accident otherwise:
 //
 //   **PID 1 is the one program on the machine with no supervisor.** Nothing
@@ -211,7 +211,8 @@ bootstrap(void)
 
 // Publish what PID 1 is holding.
 //
-// docs/plan/init.md part 2: the state lives outside whichever process is
+// docs/architecture/init.md, "State outside the process": it lives outside
+// whichever process is
 // supervising, so a restarted supervisor can read the world back instead of
 // rebuilding it. It is written by PID 1 because PID 1 is the process that
 // cannot lose it.
@@ -613,7 +614,7 @@ main(int argc, char *argv[])
         // The heartbeat. A supervisor that has stopped answering is stuck,
         // and a stuck supervisor is indistinguishable from a working one by
         // any means except asking it something -- which is the whole reason
-        // this exists. See docs/plan/init.md part 3.
+        // this exists. See docs/architecture/init.md, "The heartbeat".
         if (sock >= 0) {
             int now = uptime();
             if (now - last_ping >= SCHINIT_PING_SECS * 100) {

cmd/schinitd/main.c

@@ -4,7 +4,7 @@
 //
 // Everything that used to make PID 1 complicated lives here: reading
 // /etc/schinit, parsing manifests, deciding what runs, respawn policy and
-// throttling. docs/plan/init.md calls this "where the bugs will be", which is
+// throttling. docs/architecture/init.md calls this "where the bugs will be", which is
 // exactly why it is a separate program -- a bug here is a restart, not a panic.
 //
 // The one rule that makes the split worth having:
@@ -16,7 +16,7 @@
 //
 // A supervisor that forked its own children could not be restarted without
 // either losing them to reparenting or racing the new copy to adopt them --
-// the split-brain failure docs/plan/init.md rejects the two-init scheme for.
+// the split-brain failure docs/architecture/init.md rejects the two-init scheme for.
 
 #include "types.h"
 #include "user.h"
@@ -482,7 +482,7 @@ note_exit(unsigned int cookie, int pid, int status)
 
 // Read /proc/schinit and claim the jobs PID 1 is already holding.
 //
-// This is the half of docs/plan/init.md part 2 that makes the other half worth
+// This is the half of "State outside the process" that makes the other half worth
 // anything. PID 1 publishes the table; without this, a restarted supervisor
 // reads its manifests, sees nothing running *as far as it knows*, and starts
 // everything a second time. The console shell then exists twice, both reading
@@ -644,7 +644,7 @@ main(void)
         //
         // There is nothing this program can do about it -- PID 1 cannot be
         // killed and cannot be replaced from here -- so it says so, loudly,
-        // once. docs/plan/init.md is explicit that this is the limit: a hang
+        // once. docs/architecture/init.md is explicit that this is the limit: a hang
         // in PID 1 is only caught by noticing, and if both ends are wedged at
         // once nothing catches it. There is no hardware watchdog.
         //

docs/README.md

@@ -75,8 +75,9 @@ good chance it is in there.
 | [devices.md](architecture/devices.md) | The device model, driver binding, the class vtables. |
 | [usb.md](architecture/usb.md) | xHCI, the USB core, and the class drivers. |
 | [graphics.md](architecture/graphics.md) | Framebuffer, text rendering, console, and the crash screen. |
+| [terminals.md](architecture/terminals.md) | The six virtual terminals, and how one is switched to. |
 | [networking.md](architecture/networking.md) | Drivers, lwIP, sockets — Unix and INET. |
-| [init.md](architecture/init.md) | `schinit`, PID 1, and the job manifests. |
+| [init.md](architecture/init.md) | `schinit`, PID 1 as a role, and the job manifests. |
 
 ## plan/ — what SchOS will be
 
@@ -85,7 +86,6 @@ good chance it is in there.
 | [README](plan/README.md) | The three current decisions and the order they happen in. |
 | [1.0.md](plan/1.0.md) | **The finish line.** What 1.0 contains, and what is explicitly deferred past it. |
 | [foundations.md](plan/foundations.md) | The kernel work everything else is blocked on. |
-| [init.md](plan/init.md) | PID 1 becomes a role rather than a process. |
 | [wayland.md](plan/wayland.md) | The GUI stack, and what gets deleted to make room. |
 | [hybrid.md](plan/hybrid.md) | Moving drivers out of the kernel. |
 | [schapi.md](plan/schapi.md) | The long-term API layering, and the compatibility promise. |
@@ -112,6 +112,7 @@ good chance it is in there.
 |---|---|
 | [README](history/README.md) | What belongs in here and what does not. |
 | [kernel.md](history/kernel.md) | Bugs whose cause was nowhere near their symptom. |
+| [schfs.md](history/schfs.md) | The filesystem's own, from the same period as its design. |
 | [moving-to-linux.md](history/moving-to-linux.md) | The Windows-to-Fedora move, kept for the parts that recur. |
 
 ---

docs/Website/README.md

@@ -1,7 +1,7 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 # The website
 
-Three files and a folder of marks. No build step, no dependencies, no
+Five files and a folder of marks. No build step, no dependencies, no
 framework — open `index.html` and it works, including from a `file://` URL.
 
 ```

docs/Website/app.js

@@ -22,12 +22,13 @@
    */
   var LINES = [
     { t: "[    0.000]", k: "SchIFT",     s: " 64-bit, 2 cpus" },
-    { t: "[    0.004]", k: "cpu0",       s: ": lapic timer 999949260 Hz, tsc 3792 MHz" },
+    { t: "[    0.004]", k: "cpu0",       s: ": lapic timer 999941980 Hz, tsc 3792 MHz" },
-    { t: "[    0.061]", k: "virtio-gpu", s: ": 1280x800, 4000 KB framebuffer, irq 11" },
+    { t: "[    0.049]", k: "virtio-gpu", s: ": 1280x800, 4000 KB framebuffer" },
     { t: "[    0.088]", k: "e1000",      s: ": 52:54:00:12:34:56, link up, irq 11" },
-    { t: "[    0.143]", k: "schfs0",     s: ": mounted, generation 41" },
+    { t: "[    0.143]", k: "schfs",      s: ": mounted 'schos', generation 2" },
     { t: "[    0.169]", k: "net",        s: ": eth0 10.0.2.15/255.255.255.0" },
-    { t: "[    0.204]", k: "schinit",    s: ": 4 jobs", g: true },
+    { t: "[    0.204]", k: "schinit",    s: ": ready (pid 1)" },
+    { t: "[    0.212]", k: "schinitd",   s: ": 2 job(s) loaded, generation 1", g: true },
     { t: "",            k: "",           s: "# " }
   ];
 

docs/Website/docs.js

@@ -6,7 +6,7 @@
  * read without leaving the page and without a build step. No dependency: the
  * parser below handles exactly what docs/ actually uses -- headings, fenced
  * code, tables, lists, quotes, and inline marks. Pulling in a 40 KB Markdown
- * library to render 29 files would outweigh every other asset here combined.
+ * library to render 30 files would outweigh every other asset here combined.
  *
  * Everything is escaped before any tag is emitted. The only HTML that reaches
  * the page is HTML this file wrote.
@@ -46,7 +46,6 @@
       ["plan/README.md",              "What plan/ is for"],
       ["plan/roadmap.md",             "Roadmap"],
       ["plan/foundations.md",         "Foundations"],
-      ["plan/init.md",                "schinit"],
       ["plan/wayland.md",             "Wayland"],
       ["plan/hybrid.md",              "Hybrid kernel"],
       ["plan/schapi.md",              "SchAPI"]
@@ -268,6 +267,18 @@
     });
   }
 
+  /* A heading's own Markdown, as text. The contents panel is a list of
+     destinations, not a place to render code and emphasis -- a heading written
+     `proc_reincarnate()` should read as proc_reincarnate() there rather than
+     carrying its backticks across. Marks are stripped, not escaped: the result
+     goes through textContent. */
+  function plain(s) {
+    return s.replace(/`([^`]+)`/g, "$1")
+            .replace(/\*\*([^*]+)\*\*/g, "$1")
+            .replace(/\*([^*]+)\*/g, "$1")
+            .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
+  }
+
   function buildToc(headings) {
     tocEl.innerHTML = "";
     var real = headings.filter(function (h) { return h.level >= 2; });
@@ -283,7 +294,7 @@
       li.className = "lvl" + h.level;
       var a = document.createElement("a");
       a.href = "#" + h.id;
-      a.textContent = h.text;
+      a.textContent = plain(h.text);
       li.appendChild(a);
       ul.appendChild(li);
     });

docs/Website/index.html

@@ -23,6 +23,7 @@
       <a href="#origin">Origin</a>
       <a href="#stack">The stack</a>
       <a href="#what">What it has</a>
+      <a href="#hybrid">Hybrid</a>
       <a href="#numbers">Numbers</a>
       <a href="docs.html">Docs</a>
     </nav>
@@ -95,7 +96,7 @@
         </p>
       </div>
       <div class="step">
-        <span class="when">Now</span>
+        <span class="when">Then</span>
         <h3>Hardware, not emulation</h3>
         <p>
           A UEFI loader, xHCI and USB storage, an e1000 with a real TCP/IP stack,
@@ -103,6 +104,16 @@
           names its consumer.
         </p>
       </div>
+      <div class="step">
+        <span class="when">Now</span>
+        <h3>Drivers that are not in the kernel</h3>
+        <p>
+          A process can be handed a PCI device — its registers, its memory, its
+          interrupts — and drive it. The GPU driver already runs that way. Nobody
+          writes a driver for every device that exists; the answer is to stop
+          requiring that they live inside.
+        </p>
+      </div>
     </div>
   </div>
 </section>
@@ -110,20 +121,23 @@
 <section id="stack" class="reveal">
   <div class="wrap">
     <p class="eyebrow">Architecture</p>
-    <h2>Two seams hold the whole thing together</h2>
+    <h2>Three seams hold the whole thing together</h2>
     <p class="lede">
       Above the syscall table, software is ordinary and portable. Below the device
       model, a driver never names its consumer and a consumer never names a driver.
-      Everything else is arrangement.
+      And at <code>/dev/pci</code>, a driver stops needing to be in the kernel at
+      all. Everything else is arrangement.
     </p>
 
     <div class="stack">
-      <div class="layer"><span class="name">userland</span><span class="what">toybox, mksh, musl, and the first-party programs in <code>cmd/</code></span></div>
+      <div class="layer"><span class="name">userland</span><span class="what">toybox, mksh, zsh, musl, and the first-party programs in <code>cmd/</code></span></div>
-      <div class="layer"><span class="name">schinit</span><span class="what">PID 1 — job manifests and supervision</span></div>
+      <div class="layer"><span class="name">userspace drivers</span><span class="what"><code>vgpud</code> — a driver that is an ordinary process</span></div>
+      <div class="layer"><span class="name">schinit</span><span class="what">PID 1 — job manifests, supervision, reincarnation</span></div>
       <div class="layer seam"><span class="name">syscall table</span><span class="what">Linux numbering, one <code>.inc</code> file — the ABI seam</span></div>
-      <div class="layer"><span class="name">kernel services</span><span class="what">VFS, sockets, signals, mmap, poll, procfs</span></div>
+      <div class="layer"><span class="name">kernel services</span><span class="what">VFS, sockets and <code>SCM_RIGHTS</code>, signals, mmap, poll, procfs</span></div>
-      <div class="layer"><span class="name">subsystems</span><span class="what">SchFS, lwIP, text and graphics, the buffer cache</span></div>
+      <div class="layer"><span class="name">subsystems</span><span class="what">SchFS, lwIP, virtual terminals, graphics, the buffer cache</span></div>
       <div class="layer seam"><span class="name">device model</span><span class="what">class vtables and bus binding — the driver seam</span></div>
+      <div class="layer seam"><span class="name">/dev/pci</span><span class="what">registers, DMA and interrupts to a process — the eviction seam</span></div>
       <div class="layer"><span class="name">drivers</span><span class="what">xHCI, e1000, virtio-gpu, VBE, IDE, PS/2</span></div>
       <div class="layer"><span class="name">SchIFT core</span><span class="what">scheduler, paging, traps, IRQ, SMP, DMA</span></div>
       <div class="layer"><span class="name">boot</span><span class="what">the UEFI loader in <code>boot/uefi</code></span></div>
@@ -190,6 +204,26 @@
           kernel can mount, through the same device model as everything else.
         </p>
       </div>
+      <div class="card">
+        <span class="tag runs">runs</span>
+        <h3>Virtual terminals</h3>
+        <p>
+          Six of them, each with its own cell grid, scrollback and foreground
+          job — switched with <code>AltGr+F1</code>…<code>F6</code>, which is the
+          one chord a Linux host does not take for itself. The console draws to
+          whichever framebuffer is present, from the kernel's first line.
+        </p>
+      </div>
+      <div class="card">
+        <span class="tag runs">runs</span>
+        <h3>schinit</h3>
+        <p>
+          PID 1 does almost nothing: it forks a supervisor, spawns jobs on its
+          behalf, and reaps. The supervisor holds the manifests and the respawn
+          policy, and if it dies PID 1 replaces it and hands back the children it
+          was already watching. PID 1 can re-exec itself without dropping them.
+        </p>
+      </div>
       <div class="card">
         <span class="tag runs">runs</span>
         <h3>A real userland</h3>
@@ -200,12 +234,23 @@
           answer was to give the kernel what it was looking for.
         </p>
       </div>
+      <div class="card">
+        <span class="tag runs">runs</span>
+        <h3>Drivers outside the kernel</h3>
+        <p>
+          <code>/dev/pci</code> hands a process a device: its registers by
+          <code>mmap</code>, physically contiguous memory it can point the device
+          at, and interrupts as something to <code>read()</code>. The virtio-gpu
+          driver already lives out there. <a href="#hybrid">How that works →</a>
+        </p>
+      </div>
       <div class="card">
         <span class="tag partial">in progress</span>
         <h3>Schcom</h3>
         <p>
-          The compositor that will own the display. v0 runs. The desktop above it
+          The compositor that will own the display. v0 runs, and descriptor
-          is the next large piece of work, and it is deliberately Wayland-shaped.
+          passing — the one thing a Wayland client cannot do without — now
+          exists. What a buffer still needs is a shareable memory object.
         </p>
       </div>
       <div class="card">
@@ -221,15 +266,93 @@
   </div>
 </section>
 
+<section id="hybrid" class="reveal">
+  <div class="wrap">
+    <p class="eyebrow">Hybrid</p>
+    <h2>A driver can leave the kernel</h2>
+    <p class="lede">
+      Nobody writes a driver for every device that exists — not a project this
+      size, and not any project. So the interesting question is not how to write
+      more of them, but what a driver actually needs from a kernel, and whether it
+      can have that from outside.
+    </p>
+
+    <div class="origin-grid">
+      <div class="step">
+        <span class="when">It needs</span>
+        <h3>Its registers</h3>
+        <p>
+          <code>mmap</code> on <code>/dev/pci</code>, where the offset is the
+          physical address of a BAR. The kernel refuses any offset that is not
+          inside a BAR of a device this process was given, which is what stops it
+          being <code>/dev/mem</code> with extra steps.
+        </p>
+      </div>
+      <div class="step">
+        <span class="when">It needs</span>
+        <h3>Memory the device can reach</h3>
+        <p>
+          Physically contiguous, and the process is told the physical address —
+          which is the whole reason it cannot do this for itself. The arena is
+          reserved at boot, before the general allocator gets anything.
+        </p>
+      </div>
+      <div class="step">
+        <span class="when">It needs</span>
+        <h3>To be told when to look</h3>
+        <p>
+          Interrupts arrive by <code>read()</code>, so they compose with
+          <code>poll</code>. The kernel masks the line and leaves it masked until
+          the driver writes back — because a PCI interrupt is level-triggered, and
+          nobody but the driver knows how to clear it at the device.
+        </p>
+      </div>
+      <div class="step">
+        <span class="when">It needs</span>
+        <h3>A descriptor to arrive</h3>
+        <p>
+          <code>sendmsg</code> with <code>SCM_RIGHTS</code>. Handing a process the
+          device it is allowed to touch and handing a compositor a buffer turned
+          out to be the same act, which is why one primitive answered both.
+        </p>
+      </div>
+    </div>
+
+    <div class="console transcript" aria-label="Evicting the GPU driver to userspace">
+      <div class="console-bar">
+        <i class="dot live"></i> tty1
+        <span>vgpud</span>
+      </div>
+<pre><span class="t">$ </span>vgpud
+<span class="k">vgpud</span>: virtio-gpu at 00:03.0, currently held by virtio-gpu
+<span class="k">virtio-gpu</span>: released to userspace; screen is the VBE framebuffer
+<span class="k">vgpud</span>: claimed
+<span class="k">vgpud</span>: display is 1280x800
+<span class="k">vgpud</span>: scanout is ours, framebuffer at physical 0x3eceb000
+<span class="g">vgpud</span>: <span class="g">drew a test pattern from userspace</span>
+</pre>
+    </div>
+
+    <p class="seam-note">
+      <b>No syscall in that transcript knows it is talking about a GPU.</b> The
+      kernel handed over a PCI device; the process decided what it was. That is
+      the property that makes the interface general — and the reason SchOS's own
+      drivers are being moved out through it first, rather than shaping it around
+      something foreign and hoping it fits.
+    </p>
+  </div>
+</section>
+
 <section id="numbers" class="reveal">
   <div class="wrap">
     <p class="eyebrow">Numbers</p>
     <h2>The size of it</h2>
     <div class="figures">
-      <div class="figure"><b>43,701</b><span>lines in <code>kernel/</code> and <code>include/</code></span></div>
+      <div class="figure"><b>46,961</b><span>lines in <code>kernel/</code> and <code>include/</code></span></div>
-      <div class="figure"><b>205</b><span>syscalls, Linux numbering</span></div>
+      <div class="figure"><b>207</b><span>syscalls, Linux numbering</span></div>
       <div class="figure"><b>128</b><span>uberblock ring slots</span></div>
       <div class="figure"><b>0</b><span>patches carried against fastfetch</span></div>
+      <div class="figure"><b>1</b><span>driver already running outside the kernel</span></div>
     </div>
   </div>
 </section>

docs/Website/style.css

@@ -203,8 +203,12 @@ header.top {
   line-height: 1.85;
   color: var(--fg);
   overflow-x: auto;
-  min-height: 16.5rem;
 }
+/* The hero's console reserves its height so the typing animation does not
+   push the page around as it fills. A static transcript sizes to its own
+   content instead, which is why this is not on .console pre. */
+.hero .console pre { min-height: 16.5rem; }
+.console.transcript { margin-top: 3rem; }
 .console .t { color: var(--dim); }
 .console .k { color: var(--accent); }
 .console .g { color: var(--ok); }

docs/architecture/README.md

@@ -29,7 +29,9 @@ each with its own screen, line discipline and foreground process group. See
 
 ```
       ┌─────────────────────────────────────────────────┐
-      │  toybox   mksh   musl        first-party cmd/   │   userland
+      │  toybox   mksh   zsh   musl    first-party cmd/ │   userland
+      ├─────────────────────────────────────────────────┤
+      │  vgpud — a driver that is an ordinary process   │
       ├─────────────────────────────────────────────────┤
       │  schinit — PID 1, job manifests, supervision    │
       ├─────────────────────────────────────────────────┤
@@ -37,11 +39,13 @@ each with its own screen, line discipline and foreground process group. See
       ╞═════════════════════════════════════════════════╡
       │  VFS │ sockets │ signals │ mmap │ poll │ procfs │
       ├──────┴─────────┴─────────┴──────┴──────┴────────┤
-      │  SchFS  │  lwIP  │  text/gfx  │  buffer cache   │
+      │  SchFS  │  lwIP  │  vt/gfx  │  buffer cache     │
-      ├─────────┴────────┴────────────┴─────────────────┤
+      ├─────────┴────────┴──────────┴───────────────────┤
-      │  device model — class vtables, bus binding      │
+      │  device model — class vtables, bus binding      │   ← the driver seam
       ├─────────────────────────────────────────────────┤
-      │  drivers: xHCI  e1000  virtio-gpu  VBE  IDE  PS/2│
+      │  /dev/pci — MMIO, DMA and IRQs to a process     │   ← the eviction seam
+      ├─────────────────────────────────────────────────┤
+      │ drivers: xHCI  e1000  virtio-gpu  VBE  IDE  PS/2│
       ├─────────────────────────────────────────────────┤
       │  scheduler │ paging │ traps │ IRQ │ SMP │ DMA   │   SchIFT core
       └─────────────────────────────────────────────────┘
@@ -49,10 +53,13 @@ each with its own screen, line discipline and foreground process group. See
                    UEFI loader (boot/uefi)
 ```
 
-The two seams that matter are the syscall table and the device model. Above the
+Three seams matter. Above the **syscall table**, software is ordinary and
-first, software is ordinary and portable — musl and toybox are unmodified.
+portable — musl and toybox are unmodified. Below the **device model**, a driver
-Below the second, a driver never names its consumer and a consumer never names a
+never names its consumer and a consumer never names a driver. And at
-driver.
+**`/dev/pci`**, a driver stops having to be in the kernel at all: a process is
+handed a device's registers, DMA memory and interrupts, and the in-kernel driver
+that held it releases it cleanly. `vgpud` is the virtio-gpu driver living out
+there today. See [../plan/hybrid.md](../plan/hybrid.md).
 
 ---
 
@@ -83,8 +90,9 @@ Read in this order if you are new:
 | [devices.md](devices.md) | Buses, classes, binding, and the vtables consumers talk to. |
 | [usb.md](usb.md) | xHCI, the USB core, and the three class drivers. |
 | [graphics.md](graphics.md) | Framebuffer, text rendering, the console, and PSOGM. |
+| [terminals.md](terminals.md) | The six virtual terminals, and the chord that switches them. |
 | [networking.md](networking.md) | NIC drivers, lwIP, and both socket families. |
-| [init.md](init.md) | `schinit` and the job manifests. |
+| [init.md](init.md) | `schinit`, PID 1 as a role, and the job manifests. |
 
 ---
 

docs/architecture/devices.md

@@ -57,6 +57,75 @@ can read beats a list assembled by side effects.
 
 ---
 
+## Drivers that are not in the kernel
+
+`/dev/pci` (major 9) hands a PCI device to a process. It is deliberately about
+*PCI devices* and not about any driver model, and its first users are SchOS's
+own drivers, evicted one at a time — which is the ordering that keeps it a
+general mechanism rather than a hole shaped like something foreign.
+
+What a driver needs from a kernel, and all it needs:
+
+| | |
+|---|---|
+| find its device, and read what the bus says | `PCIIOC_INFO`, `PCIIOC_CFG` |
+| be given it, exclusively | `PCIIOC_CLAIM` |
+| reach its registers | `mmap`, where the offset is a BAR's physical address |
+| memory it can hand to the device | `PCIIOC_DMA` |
+| be told when the device wants attention | `PCIIOC_IRQ`, then `read()` |
+
+Three of those are worth expanding on, because each encodes a decision:
+
+**`mmap` is checked against the caller's claims.** An offset that is not inside
+a BAR of a device this process holds is refused. That is the whole difference
+between this and `/dev/mem` with extra steps.
+
+**DMA is a call, not a mapping.** The process is told the *physical* address,
+which is precisely what it cannot work out for itself, and the memory comes from
+an arena reserved at boot before the general allocator gets anything.
+
+**Interrupts arrive by `read()`**, the way Linux's uio does it and for the same
+reason: a descriptor composes with `poll`, and a driver that stops reading falls
+behind rather than losing events. The kernel masks the line when the interrupt
+arrives and leaves it masked until the driver `write()`s back. **That write is
+not optional.** A PCI interrupt is level-triggered — it stays asserted until the
+cause is cleared *at the device*, which is a different register on every chip and
+therefore something only the driver can do. Signal EOI on a line that is still
+asserted and it re-fires immediately, for ever. That is not hypothetical: it
+happened here at 72,000 interrupts a second, and what it looked like from
+userspace was a clock running seven times slow. See §13 of
+[../history/kernel.md](../history/kernel.md).
+
+### Handing a device over
+
+`struct pci_driver` has a `release` hook. A driver that does not define one keeps
+its device — always safe, and for anything on the path to a shell also correct.
+A driver that does define one has to give back everything, not just the device:
+the first eviction found this the hard way, because releasing the GPU while
+keeping its 4 MB framebuffer meant the incoming driver was told there was no DMA
+memory left.
+
+`cmd/vgpud` is the virtio-gpu driver as an ordinary process. It does the whole
+virtio 1.0 bring-up from outside — reset, feature negotiation, a virtqueue in DMA
+memory, `SET_SCANOUT`, transfer and flush — and while it owns the GPU the kernel
+console falls back to the VBE framebuffer.
+
+**No syscall on that path knows it is talking about a GPU.** The kernel hands
+over a PCI device; the process decides what it is.
+
+### What this is not
+
+**It is not a security boundary.** There is no IOMMU, so a process holding a DMA
+buffer can point the device at any physical address. This isolates a driver
+against its own *bugs* and not against its own *intent* — a crashed driver that
+restarts instead of taking the machine down is the entire benefit, and it is
+worth having on those terms. [../plan/hybrid.md](../plan/hybrid.md) says so at
+length.
+
+**One device per process.** A driver drives one thing; if you need two, run two.
+
+---
+
 ## Linux drivers
 
 **Decided 2026-08-08.** Linux drivers are not shipped with SchOS and never
@@ -96,9 +165,14 @@ existing mechanisms for keeping that true mechanically rather than by intention.
   `in_use` flag is the hook a hot-unplug path would need, and nothing sets it
   for that purpose.
 - **`NDEVICE` is 32**, compile-time, like every other table in the kernel.
-- **Drivers are fixed at link time.** There is no module loader, and nothing can
+- **In-kernel drivers are fixed at link time.** There is no module loader, and
-  be installed after the build — the class vtable is the attachment point a
+  nothing can be added to the kernel after the build. A driver *outside* the
-  loader would use, and it is the only part that exists.
+  kernel is an ordinary program and can be started whenever — but it reaches its
+  device through `/dev/pci` and publishes nothing to the class vtables, so the
+  console cannot be handed to one yet.
+- **A released device does not come back by itself.** `PCIIOC_RELEASE`, or the
+  process exiting, leaves the interrupt line masked and the in-kernel driver
+  unbound. Something has to start a replacement; nothing watches for one.
 - **Only two class vtables are defined**: `display_ops` and `netdev_ops`.
   Storage and input devices appear in the list with `ops = 0` and are reached
   through their own subsystems instead.

docs/architecture/init.md

@@ -1,7 +1,166 @@
-# `schinit` — PID 1
+# `schinit` — PID 1 as a role
 
-Shaped after launchd rather than sysvinit. The reason is not the configuration
+Shaped after launchd rather than sysvinit, and it breaks one Unix rule on
-format.
+purpose.
+
+---
+
+## The rule that was changed
+
+Unix's rule is *PID 1 is special and must never die*. Every init since 1975 has
+honoured it by being careful.
+
+> **SchOS's rule instead: PID 1 is a role. The kernel guarantees the role is
+> filled. The role's state lives outside whichever process currently holds it.**
+
+"Must never die" is not a mechanism — it is a hope, and the thing it hopes about
+is the one program on the machine with no supervisor. What replaced it is four
+pieces: a split by role, state in `/proc`, a heartbeat, and a kernel that
+re-execs PID 1 in place instead of panicking.
+
+### The arrangement it is not
+
+The obvious design — init 1 starts init 2; if init 1 dies, init 2 revives it —
+was tried on paper and rejected. The failures are worth keeping, because they are
+the traps any redundant-supervisor scheme falls into:
+
+- **It defends against an attack that already fails.** Userspace cannot kill
+  PID 1 here: `init_ignores()` drops `SIGKILL` to `initproc`.
+- **Init 2 is the same binary.** If init 1 died of its own bug, init 2 reaches
+  the same line and dies the same way — *faster*, having just watched the input
+  that caused it.
+- **The chain has no bound.** Init 2 makes init 3 by symmetry. With a cap, the
+  cap is the real design and the chain is decoration.
+- **Two supervisors is split brain.** Both hold the job table, both see a pid
+  exit, both restart it. Now the console shell exists twice, both reading
+  `/dev/console`. That is worse than no redundancy: it corrupts the state it was
+  added to protect.
+- **It only detects death.** The common way an init breaks is *hanging*, and
+  `wait()` never returns for a process that is merely stuck. The scheme is armed
+  against the rare failure and blind to the likely one.
+
+---
+
+## The split
+
+| | |
+|---|---|
+| **`schinit`** (PID 1) | Reaps children, holds the job table in memory, supervises exactly one child. No manifest parsing, no filesystem walking after boot, no allocation. About 520 lines. Its entire job is to be too boring to fail. |
+| **`schinitd`** (PID 2) | Manifests, respawn policy, backoff, socket sections, and the eventual `schinitctl`. This is where the bugs will be, and it is restartable. |
+
+The detail that makes this work, and that two copies of one program cannot have:
+
+> **Jobs are forked by PID 1, not by `schinitd`.** `schinitd` decides and asks;
+> PID 1 acts. Every job on the machine is a child of PID 1 at all times, so
+> `schinitd` crashing orphans nothing, reparents nothing and restarts nothing. It
+> comes back, reads the state, and finds the world exactly as it left it.
+
+So there are still two processes with one watching the other — but their roles
+are *different*, which is what stops the second being a second copy of the first
+one's bug.
+
+### The protocol
+
+`include/schinit.h`. **Every message is exactly one struct**, and PID 1 reads
+`sizeof(struct)` or nothing: no length prefix to get wrong, no partial-message
+state machine, and no allocation in the process that must not fail. The socket is
+a `socketpair` inherited as fd 3.
+
+| To PID 1 | | To the supervisor | |
+|---|---|---|---|
+| `HELLO` | version handshake | `WELCOME` | PID 1's version, echoed |
+| `SPAWN` | start this job | `SPAWNED` | the pid, or negative |
+| `PONG` | answer to a ping | `EXITED` | a child was reaped |
+| | | `PING` | answer within the deadline |
+
+---
+
+## State outside the process
+
+`/proc/schinit` is the serialised job table: a generation, the supervisor's pid,
+then one line per running job — cookie, pid, start tick, label.
+
+It is **written by PID 1**, because PID 1 is the process that cannot lose it, and
+written whenever the table changes rather than generated on read — a procfs
+generator runs in the kernel, and the kernel has no business walking this
+program's memory.
+
+procfs rather than a file on disk for four reasons: it survives a read-only root,
+it survives a full disk, it costs no I/O, and it is already the pattern this
+kernel uses for exactly this kind of question.
+
+A resurrected supervisor reads it back and adopts what is already running instead
+of starting it again. The side benefit is that the job table is no longer
+invisible: `cat /proc/schinit` is the observation.
+
+---
+
+## The heartbeat
+
+PID 1 pings the supervisor every 2 seconds and expects an answer within 10. This
+is the failure the sibling-init scheme cannot see: a supervisor that is *stuck*
+rather than dead never causes a `wait()` to return.
+
+Silence from `schinitd` means PID 1 replaces it — **without waiting for the
+corpse**, because `kill()` on a wedged process never completes and PID 1 waiting
+for it would be the hang it was trying to detect.
+
+Silence from PID 1 is what the kernel change exists for.
+
+---
+
+## `proc_reincarnate()`
+
+`exit()` on `initproc` used to `panic("init exiting")`. Now the kernel tears down
+the address space, keeps the `struct proc`, keeps **pid 1**, and re-execs
+`/bin/schinit` in place with a generation counter passed in.
+
+No init 2, no init 3, and no reparenting problem — **because pid 1 never stops
+being pid 1**. Every orphan the kernel already reparented to `initproc` is still
+correctly parented, `initproc` is still the pointer it always was, the children
+survive, and the state is in `/proc/schinit`.
+
+Three details in that path are not obvious and each was a bug first:
+
+- **`exec()` returns 0 on success.** It does not fail to return, so the code
+  after it is the *success* path, not an error path to panic in.
+- **`killed` has to be cleared first**, or the new image exits before its first
+  instruction — five generations in microseconds.
+- **`exec` preserves descriptors**, so the new PID 1 inherits the old
+  supervisor's socket and never sees the hangup that tells it the supervisor is
+  gone. It has to be closed deliberately.
+
+### The escalation ladder
+
+| Generation | What happens |
+|---|---|
+| 1 | Normal boot. |
+| 2–3 | Re-exec in place. Log it, keep the jobs, carry on. |
+| 4 | Re-exec, but ignore `/etc/schinit` entirely and start only a console shell. **A manifest that kills init must not kill it forever.** |
+| 5 | Stop. `panic()`. |
+
+The last row is the honest one. A machine that cannot hold PID 1 up five times is
+not a machine that should keep trying, and PSOGM renders a stop code, a call
+chain and a QR code of the whole report — a far better end than a silent loop.
+
+### Both paths are tested by doing them, not by reasoning
+
+Two `sysrq` keys exist for this:
+
+| | |
+|---|---|
+| `sysrq i` | Kills PID 1. Signals cannot — `init_ignores()` drops them — so this sets `killed` directly, which is the kernel deciding rather than userspace asking. |
+| `sysrq w` | Wedges `schinitd` on purpose, so the heartbeat timeout is exercised. There is no way back from it; reboot afterwards. |
+
+```
+init: pid 1 exited with status 9 -- reincarnating, generation 2
+schinit: reclaimed 2 running job(s) from /proc/schinit
+schinit: SchOS process 1, generation 2 (reincarnated)
+schinitd: adopting os.schos.console-shell
+schinitd: adopting os.schos.tty2-shell
+```
+
+The shell being typed into keeps its pid across the death and rebirth of PID 1.
 
 ---
 
@@ -14,16 +173,15 @@ That inverts the dependency graph. A job stops needing to declare what must be
 running before it, because the thing it depends on answers on first use — and
 runlevels stop being a concept at all.
 
-SchOS has the two pieces that makes possible: `AF_UNIX` sockets and a real
+SchOS has the two pieces that make it possible: `AF_UNIX` sockets and a real
-`/proc`. **This milestone is the supervisor; demand launching is the next one.**
+`/proc`. Socket sections are parsed and remembered but not yet held, so this is
-Socket sections are parsed and remembered but not yet held.
+still the reason for the shape rather than a feature of it.
 
-## Constraints on the program itself
+## Constraints on the programs themselves
 
-`cmd/schinit/main.c` links against `lib/`, which is raw syscall stubs. **There is
+Both link against `lib/`, which is raw syscall stubs. **There is no libc here** —
-no libc here** — no `malloc`, no `printf`, no `strlen`. Everything is static
+no `malloc`, no `printf`, no `strlen`. Everything is static storage and
-storage and hand-rolled, which is also why the limits are constants rather than
+hand-rolled, which is also why the limits are constants rather than growable:
-growable:
 
 | | |
 |---|---|
@@ -57,9 +215,9 @@ entirely.
 
 ## Job manifests
 
-Every `*.job` file in `/etc/schinit` is loaded at boot, found with `getdents64`
+Held by `schinitd`, not by PID 1. Every `*.job` file in `/etc/schinit` is loaded
-rather than a hardcoded list — so dropping a file in the directory is all it
+at boot, found with `getdents64` rather than a hardcoded list — so dropping a
-takes to add a job.
+file in the directory is all it takes to add a job.
 
 Sectioned `key = value`, `#` starts a comment, keys are case-insensitive
 (a manifest may say `KeepAlive`, `keepalive` or `KEEPALIVE`; keys are for humans
@@ -89,14 +247,14 @@ the rest of the system through a shared controlling terminal.
 That is exactly what makes `ControllingTerminal` necessary, and the interaction
 is the least obvious thing in the program:
 
-> A fresh session has no controlling terminal, and the console only delivers
+> A fresh session has no controlling terminal, and a terminal only delivers input
-> input to the foreground process group it is tracking. Without
+> to the foreground process group it is tracking. Without
 > `ControllingTerminal = yes`, the shell comes up, echoes every keystroke through
 > the line discipline, and executes none of them — which looks like a hung shell
 > and is really a terminal that is not listening to it.
 
-It is **off by default**. A daemon has no business seizing the console, and
+It is **off by default**. A daemon has no business seizing a terminal, and
-launchd's model is that the console is something a job asks for.
+launchd's model is that the terminal is something a job asks for.
 
 `exec.c` enables the Linux ABI automatically for musl binaries, so a job must
 not call `enable_linux_abi()` itself — it would renumber the syscalls the child
@@ -104,36 +262,24 @@ still has to make.
 
 ## Supervision
 
-One loop around `wait()`.
+PID 1 loops on `wait()` and reports every reaped pid to the supervisor.
 
 **It reaps whatever exited, including processes reparented here when their own
-parent died.** Those are not jobs, `job_by_pid` returns 0 for them, and that is
+parent died.** Those are not jobs, and that is the whole handling they need.
-the whole handling they need.
 
-A `KeepAlive` job is restarted, subject to `ThrottleInterval` — a job that exits
+A `KeepAlive` job is restarted by the supervisor asking PID 1 to spawn it again,
-immediately and forever would otherwise spin the machine. launchd defaults to
+subject to `ThrottleInterval` — a job that exits immediately and forever would
-10 seconds; 1 is enough here, where the common case is a shell someone just
+otherwise spin the machine. launchd defaults to 10 seconds; 1 is enough here,
-exited on purpose and expects back.
+where the common case is a shell someone just exited on purpose and expects back.
-
-When `wait()` returns -1 there is nothing left to wait for, which should not
-happen while any job is alive. It sleeps rather than spinning, so a mistake
-there costs an idle machine and not a hot CPU.
 
 ## The fallback
 
-With no manifests found, schinit says so and starts `/bin/sh` on the console
+With no manifests found, the supervisor says so and starts `/bin/sh` on the
-anyway.
+console anyway.
 
 > An unbootable-looking machine because a manifest was missing would be a poor
 > trade for purity.
 
-## PID 1 cannot be killed
-
-Enforced in the kernel, not here. `init_ignores()` discards any signal whose
-disposition is the default action when the target is PID 1, **including
-`SIGKILL`** — see [kernel.md](kernel.md#signals) for why Ctrl-C is the input that
-finds that window. A handler init did install is still delivered.
-
 ---
 
 ## What it does not do
@@ -141,15 +287,18 @@ finds that window. A handler init did install is still delivered.
 - **Socket activation is not implemented.** The manifest key is parsed and the
   path remembered; nothing holds the socket, so demand launching — the entire
   reason for copying launchd — does not happen yet.
-- **No `schinitctl`.** Jobs cannot be started, stopped, reloaded or inspected at
+- **No `schinitctl`.** Jobs cannot be started, stopped or reloaded at runtime.
-  runtime. The only interface is rebooting with a different manifest.
+  They can now be *inspected*, through `/proc/schinit`, which is half of it.
-- **The job table is invisible.** Nothing reports what is loaded, what is
-  running, or how many times something has respawned.
 - **No dependency ordering of any kind**, deliberately — demand launching is
   meant to make it unnecessary, and until that exists there is nothing in its
   place either.
 - **No log capture.** `StandardOut` is a path, so a job's output goes wherever
   the manifest says and nothing aggregates it.
-- **A crash in schinit is fatal to the machine**, because `exit()` panics on
+- **`/proc/schinit` records running jobs, not the whole table.** A job that is
-  initproc. Fixing that is [../plan/init.md](../plan/init.md).
+  loaded and stopped is not in it, so a resurrected supervisor learns what is
+  alive and re-reads the manifests for everything else.
+- **A new compatibility surface exists between PID 1 and PID 2** that did not
+  before, and the tree's own [../plan/schapi.md](../plan/schapi.md) §3 spends a
+  section warning about exactly those. `SCHINIT_PROTO` is versioned in the
+  handshake, which is the least that can be done about it.
 - **32 jobs, 16 arguments, 4 KB manifests**, all compile-time.

docs/guides/layout.md

@@ -12,13 +12,17 @@ deliberately kept out of `clean`).
 
 ```
 schos/
-├─ boot/          Stage 1 MBR + stage 2 loader (splash, F8 menu, kernel load)
+├─ boot/          uefi/ the PE/COFF loader (splash, F8 menu, kernel load),
+│                 common/ the UI it shares. UEFI only -- there is no BIOS path.
 ├─ kernel/        The kernel, by subsystem: arch/ core/ dev/ fs/ proc/ sys/
 ├─ include/       Headers shared by kernel, userland, and tools/mkfs
 ├─ lib/           First-party userland runtime: _start glue, syscall stubs,
 │                 the initcode blob embedded in the kernel, user.ld
 ├─ cmd/           First-party programs — one directory per program:
 │                 cmd/<name>/main.c  →  sysroot/bin/<name>
+│                 schinit and schinitd are PID 1 and its supervisor; vgpud is
+│                 the virtio-gpu driver, which runs out here rather than in
+│                 the kernel; socktest/shmtest/nettest/pcitest are suites.
 ├─ ports/         Third-party software — one directory per port.
 │                 Contains ONLY a Makefile and optional patches/.
 ├─ projects/      Things that run ON SchOS rather than things that ARE it:

docs/guides/testing.md

@@ -62,7 +62,7 @@ a subsystem nothing exercises looks identical whether it works or not.
 |---|---|
 | `-Tty` | Pipes, `isatty`, `SIGPIPE`, Ctrl-C. **None can be checked from a screenshot**, and all were once broken in ways that looked like broken *commands*. |
 | `-Usb` | Attaches an xHCI controller with a keyboard, mouse and mass-storage device. Nothing on the default machine has a USB port, so without it a broken driver looks exactly like a working one. |
-| `-Sock` | Unix sockets. A socket layer that accepted every call and dropped every byte would look identical from outside. `socktest` has one process write and another read. |
+| `-Sock` | Unix sockets. A socket layer that accepted every call and dropped every byte would look identical from outside. `socktest` has one process write and another read — including the `SCM_RIGHTS` checks, where the descriptor passed is always a pipe end, because a pipe announces its own lifetime and that is what makes "was the kernel's reference released" a value rather than a belief. |
 | `-Evdev` | Raw input. Needs the QEMU monitor, because a key has to be *pressed* — characters typed at the serial port never touch the keyboard controller. |
 | `-Ps` | Process enumeration. `/proc`'s whole reason for existing is one directory per process, and nothing else in the suite touches it. |
 | `-Net` | TCP/IP. A listener runs **on the host** and the guest connects out. |

docs/plan/1.0.md

@@ -237,14 +237,32 @@ memory object, `AF_UNIX` in the filesystem namespace.
 
 Nothing above needs these; everything below stops without them.
 
-### Gate 2 — Init as a role
+- [x] ~~**Item 1 — `sendmsg`/`recvmsg` with `SCM_RIGHTS`.**~~ Built and tested;
+      fourteen checks in `cmd/socktest`, each moving data through the passed
+      descriptor rather than inspecting it. Described in
+      [../architecture/networking.md](../architecture/networking.md#descriptor-passing).
+      This was also mechanism 1 of [hybrid.md](hybrid.md) — one primitive for
+      both, which is the whole reason those are one plan.
+- [ ] **Item 2 — a shareable memory object** (`memfd_create`, and
+      `mmap(MAP_SHARED)` on it genuinely working between two processes). This is
+      what a Wayland buffer still cannot cross on.
+- [ ] **Item 3 — `AF_UNIX` sockets in the filesystem namespace.**
 
-[init.md](init.md), milestones I0–I3.
+### Gate 2 — Init as a role — **done**
+
+Milestones I0–I3, all built. PID 1 forks a supervisor and spawns jobs on its
+behalf; the job table lives in `/proc/schinit`; a heartbeat runs both ways; and
+`proc_reincarnate()` re-execs PID 1 in place rather than panicking. Both failure
+paths are exercised by `sysrq` keys rather than reasoned about.
 
 Before the desktop rather than after, because a compositor being brought up for
 the first time crashes constantly, and something that restarts it and says why is
 worth far more during that work than at the end of it.
 
+The description is now [../architecture/init.md](../architecture/init.md); the
+plan document it replaced has been deleted, per
+[the rule](../README.md#the-rule-that-keeps-this-from-rotting).
+
 ### Gate 3 — The desktop
 
 [wayland.md](wayland.md), W1–W3, and the terminal.
@@ -261,7 +279,7 @@ attention. Nothing here is cancelled.
 
 | | Why it waits |
 |---|---|
-| **The hybrid kernel** ([hybrid.md](hybrid.md)) | An architecture improvement, not a completeness requirement. It is also the work that most wants a demanding consumer first, and 1.0's compositor is exactly that consumer. |
+| **The rest of the hybrid kernel** ([hybrid.md](hybrid.md)) | Still not a completeness requirement — but the mechanisms and the first eviction happened early, because the alternative to a driver compatibility layer is writing a driver for every device that exists, and that is not a plan. What is deferred is the foreign driver host, not the interface it needs. |
 | **Dynamic linking, Mesa, SDL3** | Everything at 1.0 is statically linked. This is the single biggest post-1.0 unlock and it is a whole project. |
 | **A page cache** | `memfd` covers the desktop's needs. General writable `MAP_SHARED` of a file is a real project with no 1.0 consumer. |
 | **`.sip` and the installer** | 1.0 installs by writing a USB stick. That is how most systems start and it is honest. |

docs/plan/README.md

@@ -19,14 +19,14 @@ Taken together, because they turn out to need the same foundation.
 | | |
 |---|---|
 | **[wayland.md](wayland.md)** | The GUI stack becomes Wayland. SchWM and SchDE are deleted; Schcom survives and changes its wire format. |
-| **[hybrid.md](hybrid.md)** | The kernel becomes hybrid — drivers move out into userspace processes, starting with the GPU. |
+| **[hybrid.md](hybrid.md)** | The kernel becomes hybrid — drivers move out into userspace processes, starting with the GPU. **Partly built**: all four mechanisms exist and the GPU driver already runs outside the kernel. |
-| **[init.md](init.md)** | PID 1 stops being a process and becomes a role the kernel guarantees is filled. |
+| ~~init.md~~ | **Built.** PID 1 is now a role the kernel refills; the description moved to [../architecture/init.md](../architecture/init.md). |
 
 And the one they all wait on:
 
 | | |
 |---|---|
-| **[foundations.md](foundations.md)** | Descriptor passing, shared memory, sockets in the filesystem. The critical path. |
+| **[foundations.md](foundations.md)** | Descriptor passing, shared memory, sockets in the filesystem. The critical path. **Item 1 is built** — `sendmsg`/`recvmsg` with `SCM_RIGHTS`. |
 
 And the one that says which parts of the above are actually being worked on:
 
@@ -61,30 +61,49 @@ shared memory are the substrate for handing a buffer to a compositor *and* for
 handing a device to a driver process. **Doing it once for both is the entire
 reason these are one plan rather than three.**
 
-### 2. `init.md` — before the desktop, not after
+### 2. `init.md` — before the desktop, not after — **done**
 
 A compositor being brought up for the first time crashes constantly, and
 something that restarts it and says why is worth far more during that work than
-at the end of it.
+at the end of it. Built; see [../architecture/init.md](../architecture/init.md).
 
-### 3. `wayland.md` — with the GPU driver still in the kernel
+### 3. `hybrid.md` — **moved up, and the reason is worth recording**
 
-W1–W3 and a terminal. W4 and W5 are post-1.0.
+This document used to put the hybrid work *after 1.0*, deliberately last, on this
+argument:
 
-### 4. `hybrid.md` — **after 1.0**
+> designing a userspace driver interface with no driver consuming it produces an
+> interface that is wrong in ways nobody can see
 
-Deliberately last: **designing a userspace driver interface with no driver
+The argument was sound and the conclusion drawn from it was wrong. What forced
-consuming it produces an interface that is wrong in ways nobody can see.** The
+the change was the driver situation: SchOS cannot write a driver for every device
-compositor is the demanding consumer that makes the interface judgeable, so it
+that exists, no project can, and the only route to the hardware support an
-has to exist first.
+established OS has is a compatibility layer with the foreign drivers kept
+*outside* the kernel. That layer is this plan's mechanisms. It is not optional and
+it is not late work.
+
+The original argument still holds, and it is answered rather than ignored:
+**SchOS's own drivers are the consumers.** `vgpud` is a real driver, with real
+requirements, and building the interface against it is what keeps it a general
+mechanism rather than a hole shaped like something foreign. The compositor is
+still a demanding consumer — it is no longer the *only* one available.
+
+Four mechanisms, all built. One eviction done, one to go, then the foreign
+driver host.
+
+### 4. `wayland.md` — with the GPU driver either side of the seam
+
+W1–W3 and a terminal. W4 and W5 are post-1.0. Item 1 of `foundations.md` —
+descriptor passing — was the thing it could not start without, and it now
+exists.
 
 ---
 
 ## In one sentence
 
 > Fix what is broken, build the descriptor-passing and shared-memory substrate,
-> make init survivable, put a terminal on the screen — and only then use the
+> make init survivable, move the drivers out through an interface SchOS's own
-> compositor as the pressure that shapes the userspace driver interface.
+> drivers have to live with first — and put a terminal on the screen.
 
 ---
 
@@ -96,6 +115,9 @@ Stated here so it is not mistaken for covered:
   hostile driver.
 - **No page cache**, so `foundations.md` delivers a `memfd` and not a general
   answer to shared file mappings. The general answer is still owed.
+- **No garbage collector for descriptors in flight**, so an `AF_UNIX` socket
+  passed over itself and never received leaks. Bounded at thirty-two sockets, and
+  nothing on this plan does it.
 - **No dynamic linking**, so no Mesa, no accelerated clients, and no third party
   shipping a `.so` for anything.
 - **A new compatibility surface** between PID 1 and PID 2, created by a plan

docs/plan/init.md

@@ -1,212 +0,0 @@
-# PID 1 becomes a role
-
-What `schinit` is today is [../architecture/init.md](../architecture/init.md).
-This is what it becomes, and it is the one item on this plan that deliberately
-breaks a Unix rule.
-
----
-
-## The law being changed
-
-Unix's rule is *PID 1 is special and must never die*. Every init since 1975 has
-honoured it by being careful.
-
-> **SchOS's rule instead: PID 1 is a role. The kernel guarantees the role is
-> filled. The role's state lives outside whichever process currently holds it.**
-
-That is a real change and it is worth making, because "must never die" is not a
-mechanism — it is a hope, and the thing it hopes about is the one program on the
-machine with no supervisor.
-
----
-
-## The proposal this replaces
-
-The original sketch was: init 1 starts init 2; if init 1 is killed, init 2 starts
-init 3 and revives init 1.
-
-The instinct is right — init needs something watching it — and one half of the
-idea survives below. The specific arrangement has five problems, and four of them
-are structural rather than fixable. They are recorded because each one is a trap
-that any redundant-supervisor design falls into:
-
-**It defends against the attack that already fails.** Userspace cannot kill PID 1
-on this kernel. `init_ignores()` (`kernel/proc/proc.c:620`) drops `SIGKILL` to
-`initproc`. The threat is already handled.
-
-**Init 2 is the same binary as init 1.** If init 1 died of its own bug — a null
-dereference parsing a manifest, an exec of a truncated binary — init 2 reaches
-the same line and dies the same way, and *faster*, because it just watched the
-input that caused it.
-
-**The chain has no bound.** Init 2 makes init 3, which by symmetry watches init 2
-and makes init 4. Without a cap it is a fork bomb whose author is the supervisor;
-with a cap, the cap is the real design and the chain is decoration.
-
-**Two supervisors is split brain.** Both hold the job table. Both see a job's pid
-exit. Both restart it. Now the console shell exists twice, both reading
-`/dev/console`, and every keystroke goes to whichever woke first. This is the
-standard failure of redundant supervisors, and it is worse than no redundancy
-because it corrupts the state it was added to protect.
-
-**It only detects death.** The common way an init breaks is not dying — it is
-**hanging**: deadlocked, spinning, or blocked forever on a disk that stopped
-answering. `wait()` never returns for a process that is merely stuck, so init 2
-watches a wedged init 1 forever and reports everything normal. The scheme is
-armed against the rare failure and blind to the likely one.
-
----
-
-## What gets built instead
-
-Four parts. The first three are userspace; the fourth is the kernel change.
-
-### Part 1 — split by role, not by copy
-
-**`schinit` (PID 1)** becomes small enough to be obviously correct and then stops
-changing: reap children, hold the job table in memory, supervise exactly one
-child. No manifest parsing. No filesystem walking after boot. No allocation. Its
-entire job is to be too boring to fail.
-
-**`schinitd` (PID 2)** gets everything else — manifests, socket activation,
-respawn policy, backoff, and the eventual `schinitctl`. It is where the bugs will
-be, and it is restartable.
-
-The detail that makes this work, and that the two-copy scheme cannot have:
-
-> **Jobs are forked by PID 1, not by `schinitd`.** `schinitd` decides and asks;
-> PID 1 acts. So every job on the machine is a child of PID 1 at all times, and
-> `schinitd` crashing orphans nothing, reparents nothing and restarts nothing. It
-> comes back, reads the state, and finds the world exactly as it left it.
-
-This keeps the good half of the original idea — two processes, one watching the
-other — with the roles made *different*, so the second is not a second copy of
-the first one's bug.
-
-### Part 2 — state outside the process
-
-**`/proc/schinit`**: the serialised job table, written by PID 1 whenever it
-changes, readable by anyone. A resurrected supervisor reads it back and knows
-what is running without having started it.
-
-procfs rather than a file on disk, for four reasons: it survives a read-only
-root, it survives a full disk, it costs no I/O, and it is already the pattern
-this kernel uses for exactly this kind of question.
-
-The side benefit closes an item the architecture doc lists as missing — the job
-table is currently invisible. `cat /proc/schinit` is the observation.
-
-### Part 3 — a heartbeat, in both directions
-
-The failure the original scheme cannot see.
-
-PID 1 and `schinitd` hold a `socketpair`; each must be heard from within a
-deadline. Silence from `schinitd` means PID 1 kills and restarts it. Silence from
-PID 1 is the case part 4 exists for.
-
-**A hang is now as detectable as a death**, which is the whole point.
-
-### Part 4 — `proc_reincarnate()`
-
-The kernel change, and the actual law change.
-
-Today `exit()` on `initproc` calls `panic("init exiting")`
-(`kernel/proc/proc.c:277`). Instead: tear down the address space, keep the
-`struct proc`, keep **pid 1**, and re-exec `/sbin/schinit` in place with a
-generation counter passed in.
-
-No init 2, no init 3, no reparenting problem — **because pid 1 never stops being
-pid 1**. Every orphan the kernel already reparented to `initproc` is still
-correctly parented, `initproc` is still the pointer it always was, the children
-survive, and the state is in `/proc/schinit`.
-
-This is strictly better than resurrection-by-sibling for every case, and it is
-the smaller change.
-
-#### The escalation ladder
-
-What makes it safe to have at all:
-
-| Generation | What happens |
-|---|---|
-| 1 | Normal boot. |
-| 2–3 | Re-exec in place. Log it, keep the jobs, carry on. |
-| 4 | Re-exec, but ignore `/etc/schinit` and start only a console shell. **A manifest that kills init must not kill it forever.** |
-| 5 | Stop. `panic()` with stop code `INIT_RESURRECTION_FAILED`. |
-
-The last row is the honest one. A machine that cannot hold PID 1 up five times is
-not a machine that should keep trying, and PSOGM already renders a stop code, a
-call chain and a QR code of the whole report — which is a far better end than a
-silent loop. The crash screen is the correct place for this to arrive.
-
----
-
-## Milestones
-
-**All four milestones are built.** `sysrq w` wedges the supervisor and PID 1
-replaces it; `sysrq i` kills PID 1 and the kernel refills the role:
-
-```
-init: pid 1 exited with status 9 -- reincarnating, generation 2
-schinit: reclaimed 2 running job(s) from /proc/schinit
-schinit: SchOS process 1, generation 2 (reincarnated)
-schinitd: adopting os.schos.console-shell
-schinitd: adopting os.schos.tty2-shell
-```
-
-The shell being typed into keeps its pid across the death and rebirth of PID 1.
-
-**I0 and I1 first.** `schinit` is 520 lines with no parser and no
-allocation; `schinitd` holds the manifests. `kill 3` produces:
-
-```
-schinitd: 2 job(s) loaded, generation 1
-schinitd: adopting os.schos.console-shell
-schinitd: adopting os.schos.tty2-shell
-schinitd: ready
-```
-
-— and `/proc/schinit` is byte-identical across the restart, same pids, same
-cookies, same start times. The shell the user was typing into never noticed.
-
-The first attempt at I1 got this wrong in the instructive way: PID 1 published
-the table and `schinitd` never read it, so the restarted supervisor started
-everything a *second* time. Two console shells on one terminal, which is the
-split-brain this plan rejects the two-init scheme for, reached by a different
-road. Publishing state is only half of it; the other half is coming back and
-believing it.
-
-
-| | |
-|---|---|
-| **I0** ✅ | Split the program. PID 1 supervises one child; `schinitd` does everything else. Jobs still forked by PID 1. |
-| **I1** ✅ | `/proc/schinit`, written and read back. Kill `schinitd` by hand and watch it return without disturbing a single job. |
-| **I2** ✅ | The heartbeat both ways, with a `sysrq` key that wedges `schinitd` on purpose so the timeout path is exercised rather than assumed. |
-| **I3** ✅ | `proc_reincarnate()` and the ladder, with a `sysrq` key that kills PID 1 on purpose. |
-
----
-
-## What it costs
-
-**PID 1 and PID 2 must agree on a protocol**, which is a compatibility surface
-where there was none — created by a plan whose own [schapi.md](schapi.md) §3
-warns about exactly that. Keep it tiny, version it in its first message, and keep
-it entirely internal. It is not SchAPI and nothing else may speak it.
-
-**`proc_reincarnate()` is a genuinely dangerous function.** It runs in the
-context of a process that is dying, and it must not take a lock that process may
-already hold. It belongs in `proc.c` next to `exit()`, written with the care of
-the panic path, and tested by a `sysrq` key rather than by reasoning.
-
----
-
-## What it will still not do
-
-- **It does not make init correct**, only survivable. A `schinitd` that starts
-  the wrong jobs starts them again after every restart.
-- **It does not protect the jobs from each other.** A job that fills the disk or
-  exhausts the process table still takes the machine down, and the supervisor
-  surviving does not help.
-- **A hang in PID 1 itself is only caught by `schinitd` noticing**, and if both
-  are wedged simultaneously nothing catches it. There is no hardware watchdog.
-- **Five generations is a guess**, not a measured number.

docs/plan/roadmap.md

@@ -25,9 +25,10 @@ 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*
+  whatever the loader asked for. This was to be done *with*
-  [hybrid.md](hybrid.md)'s GPU eviction rather than before it — moving the driver
+  [hybrid.md](hybrid.md)'s GPU eviction, and that eviction has now happened —
-  out is what makes a modeset API affordable to design properly.
+  `cmd/vgpud` drives virtio-gpu from userspace. The modeset API is the next thing
+  it makes affordable, and is milestone H3 over there rather than here.
 - **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
@@ -43,7 +44,7 @@ belongs to the GUI.
 
 ## 3. Networking
 
-Three things the stack owed on the day it landed, all still owed:
+Two things the stack owed on the day it landed, both 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
@@ -52,8 +53,11 @@ Three things the stack owed on the day it landed, all still owed:
   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.
 
-`setsockopt` returning 0 for everything is in
+Two that were on this list are now done and described in
-[foundations.md](foundations.md) instead, because the Wayland work needs it.
+[../architecture/networking.md](../architecture/networking.md): `setsockopt`
+honours six options and refuses the rest, and `sendmsg`/`recvmsg` carry
+`SCM_RIGHTS`. A third is closer than it was — toybox's `ping` needed `recvmsg`
+*and* `IP_RECVTTL`, and only the second is still missing.
 
 ## 4. The interactive crash screen
 
@@ -159,11 +163,13 @@ Not phases, and each one improves everything above it:
   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
+- **The `ls -lR` hang** — **not reproducible**, and kept here because the absence
-  shell session eventually makes a *later*, unrelated directory hang; the same
+  of a result is a result. Instrumented and hunted at length; see Gate 0 of
-  command succeeds on a fresh boot. Not inode or file table exhaustion — both
+  [1.0.md](1.0.md). Two real defects were found on the way and fixed, neither
-  fail cleanly and neither fired. Next step: instrument `itable`/`ftable`
+  proven to be the cause.
-  occupancy across a long session and watch what climbs.
+- **No garbage collector for descriptors in flight.** An `AF_UNIX` socket passed
+  over itself and never received leaks the pair. Bounded at thirty-two sockets,
+  and nothing in the tree does it — but a third-party program could.
 
 ---
 

include/proc.h

@@ -250,7 +250,7 @@ struct proc {
   // more than one terminal to choose between.
   int ctty;
   // Never scheduled again. Set by sysrq 'w' to produce a hang on purpose --
-  // see proc_wedge() and docs/plan/init.md part 3.
+  // see proc_wedge() and docs/architecture/init.md, "The heartbeat".
   int wedged;
 
   // Real/effective/saved user and group ids. Nothing enforces permissions with

include/schinit.h

@@ -2,7 +2,7 @@
 //
 // The protocol between PID 1 and the supervisor.
 //
-// docs/plan/init.md §"What it costs" warns about this file specifically: two
+// docs/architecture/init.md warns about this file specifically: two
 // processes that must agree is a compatibility surface where there was none,
 // and docs/plan/schapi.md §3 is about how those go wrong. So the rules are
 // written here rather than assumed.
@@ -52,7 +52,8 @@
 
 // The heartbeat.
 //
-// docs/plan/init.md part 3, and the failure the two-init scheme could not see:
+// docs/architecture/init.md, "The heartbeat" -- the failure the two-init scheme
+// could not see:
 // **the common way an init breaks is not dying, it is hanging.** wait() never
 // returns for a process that is merely stuck, so a supervisor watching a
 // wedged PID 1 -- or PID 1 watching a wedged supervisor -- reports everything

kernel/dev/procfs.c

@@ -496,7 +496,7 @@ proc_sysrq_cmd(char cmd)
     // Setting `killed` directly is the kernel deciding, not userspace asking:
     // init exits at its next trap return and proc_reincarnate() takes over.
     //
-    // docs/plan/init.md asks for this to be "tested by a sysrq key rather than
+    // docs/architecture/init.md asks for this to be "tested by doing it rather than
     // by reasoning", which is the only honest way to know the path works.
     proc_kill_init();
     cprintf("sysrq: pid 1 asked to exit -- it should come back\n");
@@ -560,7 +560,8 @@ procwrite(struct inode *ip, uint64 off, char *src, int n)
 // /proc/schinit -- the job table
 // ---------------------------------------------------------------------------
 //
-// docs/plan/init.md part 2. PID 1 writes this whenever the table changes and
+// docs/architecture/init.md, "State outside the process". PID 1 writes this
+// whenever the table changes and
 // anyone may read it; a supervisor that has just been restarted reads it back
 // and knows what is running without having started any of it.
 //

kernel/proc/proc.c

@@ -269,7 +269,7 @@ fork(void)
 // passes W_EXITCODE(n, 0).
 // PID 1 is a role, and the kernel guarantees the role is filled.
 //
-// This is the rule change docs/plan/init.md exists for. Unix's rule is "PID 1
+// This is the rule change docs/architecture/init.md exists for. Unix's rule is "PID 1
 // is special and must never die", honoured since 1975 by being careful --
 // which is not a mechanism, it is a hope, and the thing it hopes about is the
 // one program on the machine with no supervisor.
@@ -514,7 +514,7 @@ waitpid(int pid, int *status, int options)
 
 // Stop a process running, by name, and never start it again.
 //
-// This exists for one reason: docs/plan/init.md part 3 says the heartbeat's
+// This exists for one reason: docs/architecture/init.md says the heartbeat's
 // timeout path should be "exercised rather than assumed", and a hang is the
 // one failure that cannot be produced by killing something. A wedged process
 // is still alive, still has its descriptors open, and still shows up in every