nexoniarz/SchOS
nexoniarz/SchOS
Watch
1
0
Fork
You've already forked SchOS
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

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

Browse source 
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
This commit is contained in:
Nexoniarz 2026-09-12 17:13:35 +02:00
commit 57aff40228
59 changed files with 3981 additions and 1124 deletions
Download patch file Download diff file Expand all files Collapse all files

178
docs/plan/init.md Normal file
View file

@ -0,0 +1,178 @@
# 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
| | |
|---|---|
| **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.