souveraine/saf/surface/02-session-start.md

Session start

The graphical session is one dependency graph. A green system graphical.target proves only that greetd may run; it does not prove that the user authority or a drawing shell exists.

The order

souveraine-session-viewtop is the session leader. It starts viewtop, waits for the compositor's Wayland socket, and imports that socket and the Souveraine desktop identity into the user systemd manager. Only then can the rest begin:

1. souveraine-session-pre.target pulls in systemd's graphical-session-pre.target. souveraine-sessiond belongs here because it needs Wayland in order to take ext-session-lock, and it must hold that lock before a drawing surface appears.
2. The leader waits for $XDG_RUNTIME_DIR/souveraine/sessiond.sock. A Type=simple service is considered started before it serves; the socket is the readiness fact until sessiond becomes Type=notify.
3. souveraine-session.target pulls in graphical-session.target, which starts souveraine-shell.service and the other surfaces that belong to the session.
4. When viewtop exits, the leader stops the two Souveraine targets. Their bindings let systemd stop everything whose lifetime is the graphical session.

The two Souveraine targets are necessary because the stock graphical-session targets carry RefuseManualStart=yes. A session leader cannot start those stock units directly. It starts its own targets; their dependencies may pull the stock targets into the transaction in the way systemd permits.

This graph raises session authority; it does not replace it. systemd owns process lifetime and dependency order. Sessiond owns session policy once its socket is ready.

Package boundary

souveraine-viewtop owns the compositor and the session edge on both x86_64 and aarch64:

• /usr/bin/viewtop
• /usr/bin/souveraine-session-viewtop
• /usr/lib/systemd/user/souveraine-session-pre.target
• /usr/lib/systemd/user/souveraine-session.target
• /usr/lib/systemd/user/souveraine-shell.service

The package depends on souveraine for sessiond and on the virtual quickshell package for qs. Both architecture artifacts carry and verify the same start contract. Architecture changes the compositor binary, not the meaning of a Souveraine session.

Versioned QML and face assets remain a separate surface-package boundary. The session unit names what launches them; it must not own a mutable ~/.config/quickshell tree or turn a development compose into an installed artifact.

No shadow starts

A unit under ~/.config/systemd/user or /etc/systemd/user outranks the package copy under /usr/lib/systemd/user. Such a file may prove a repair, but it is a splint: once the package carries the same unit, the higher-priority copy must move out of systemd's search path. Otherwise pacman can update the owned unit forever while the machine keeps booting the old answer.

The same distinction holds across delivery:

• source says what could ship;
• a green package job says what was built and signed;
• pacman -Qo and file identity say what is installed;
• a fresh session start says the dependency graph actually raised the glass.

Do not collapse those into "fixed."

The failure this closes

On 2026-08-17 blueline reached system graphical.target with greetd and viewtop alive, but user souveraine-session.target, sessiond, and QuickShell were all dead. The installed r117 leader had directly requested the refused stock targets. Viewtop failed closed with no lock surface and the panel was black. Starting the Souveraine wrapper target recovered sessiond, loaded QuickShell, transferred the lock surface, and showed the session without a reboot.

That recovery proved the dependency shape. It did not become durable until the leader, both targets, the shell unit, their runtime dependencies, and artifact content checks travelled together through the signed package path.