Schcom v0: a compositor that actually composites

Clients connect over a Unix socket, are handed a shared buffer, draw into
it and commit; Schcom composites and presents. Both of the hard blockers
its README listed -- unix domain sockets and raw input events -- have been
done for a while, so nothing was in the way.

The model is Wayland's, on purpose. A surface is not a window: it is a
rectangle of pixels with no policy attached, because placement belongs to
SchWM and the moment this program starts deciding where windows go the
split has failed. Nothing is shown until COMMIT, so a client halfway
through drawing is never presented. The compositor tells clients when to
draw rather than letting them render frames nobody sees.

Wayland is MIT-licensed and supporting it later is intended, so the
divergences are the ones that are cheap to undo: a buffer handle is a
System V shm id rather than an fd over SCM_RIGHTS, and the message
carries a handle_kind field so switching is a new value rather than a
protocol break. Every message carries its own length, so an unknown
message is skipped instead of desynchronising the stream -- which is what
lets a v0 compositor survive a v1 client.

The compositor owns the shm segment, not the client: it has to survive a
client crashing mid-frame, and it must not be something a client can
resize underneath it. A dropped connection takes its surfaces and their
segments with it.

Composites into a back buffer and copies once, because compositing
straight into the framebuffer shows every intermediate state -- the
flicker would be the whole desktop being repainted under the user's eyes.

projects/ gets build glue for the first time: `make projects` builds
against the sysroot's libc and stages into sysroot/bin. It is not a
dependency of anything above it, and `make` never descends there.

Verified by `make schcom-test`, which boots SchOS, runs the compositor and
a client, screendumps the framebuffer and asserts the pixels on the host.
That last part is the point -- the compositor reporting that it
composited something proves nothing, and a screenshot nobody inspects
proves less. It checks the client's colour mid-surface, the compositor's
background, and the white border exactly at the requested origin, so
"arrived" and "arrived at the wrong offset" cannot pass for each other.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

projects/schcom/README.md

@@ -12,31 +12,75 @@ and Schcom exposes a protocol for it rather than implementing policy itself.
 
 ## Status
 
-Not started. Scoped only.
+**v0 runs.** A client connects, is given a shared buffer, draws into it and
+commits; the result is composited and presented. Verified end to end by
+`make schcom-test`, which boots SchOS, runs the compositor and a client, then
+screendumps the framebuffer and asserts the pixels **from the host** — the
+compositor's own report that it composited something proves nothing.
 
-## What it needs from the kernel first
+What exists:
+
+- framebuffer output through `/dev/fb0` and the fbdev ioctls, double-buffered
+- a versioned protocol over a Unix socket, with a handshake that must come first
+- shared-memory buffers, one per surface, owned by the compositor
+- surface / attach / **commit** semantics: nothing is shown mid-draw
+- input from `/dev/input/eventN`, routed to the topmost surface
+- clients that die are cleaned up, including their shm segments
+
+What does not exist yet: damage tracking beyond "repaint everything", multiple
+outputs, subsurfaces, and any focus model beyond "topmost". Those are additions
+rather than rewrites, which is the reason for committing to the surface/commit
+model now instead of growing into it later.
+
+## Building
+
+Not part of the OS build. Needs `make ports` first, for the sysroot's libc:
+
+```sh
+make projects        # builds and stages into sysroot/bin
+make                 # rebuilds the image so the binaries are on it
+make schcom-test     # boots it and checks the pixels
+```
+
+## What it needs from the kernel
 
 | Need | State |
 |---|---|
 | Shared memory (`shmget`/`shmat`/`shmdt`) | done |
 | `mmap` of `/dev/fb0` | done |
 | Framebuffer geometry via the fbdev ioctls | done |
-| **Unix domain sockets**, with `SCM_RIGHTS` | **missing** — `socket()` is a `NO_LINUX` stub |
-| **Raw input events** — key down/up with modifiers | **missing** — input only arrives cooked, through the tty line discipline |
-| Mode setting and double buffering | **missing** — needs the virtio-gpu driver |
+| Unix domain sockets | done |
+| Raw input events — key down/up with modifiers | done |
+| `SCM_RIGHTS` | done, and **not yet used** — see below |
+| Mode setting and double buffering | partial — virtio-gpu binds, no modeset API yet |
 
-The two marked missing are hard blockers, not inconveniences. A client and
-the compositor have to pass a buffer handle between them, and a pipe cannot
-carry one. And a compositor that reads the tty gets line-buffered text
-delivered to a single foreground process, which is not input in any sense it
-can use.
+## Design notes
 
-## Design notes, so far
-
-- **Buffers are shared memory, not pipes.** A pipe means copying every frame;
-  at 800×600×32 that is 1.9 MB per frame per client. shm exists for this.
+- **Buffers are shared memory, not pipes.** A pipe means copying every frame; at
+  800×600×32 that is 1.9 MB per frame per client.
+- **The compositor owns the segment, not the client.** It has to survive a
+  client crashing mid-frame, and it must not be something a client can resize
+  underneath the compositor.
 - **One protocol, versioned from the start.** SchWM and SchDE are separate
-  programs, so the protocol is a real compatibility surface from day one, not
-  after the fact.
+  programs, so this is a real compatibility surface on day one. Every message
+  carries its own length, so an unknown message is skipped rather than
+  desynchronising the stream — that is what lets a v0 compositor survive a v1
+  client.
 - **Policy belongs to SchWM.** If Schcom starts deciding where windows go, the
-  split has already failed.
+  split has already failed. `CREATE_SURFACE` carries x/y today only because
+  there is no SchWM yet to ask.
+
+## On Wayland
+
+The protocol is deliberately Wayland-shaped — surfaces rather than windows,
+buffers attached and made visible only on commit, and the compositor telling
+clients when to draw. Wayland is **MIT-licensed**, so it can be linked against
+without any conflict with Apache-2.0 (see `docs/architecture/licensing.md`), and
+supporting it later is intended.
+
+The one place v0 knowingly diverges: a buffer handle is a System V shared memory
+id passed as an integer, where Wayland passes a file descriptor over
+`SCM_RIGHTS`. The kernel supports `SCM_RIGHTS` already; an integer simply needs
+no ancillary-data handling on either side. `struct schcom_surface` carries a
+`handle_kind` field precisely so that switching is a new value rather than a
+protocol break.