# 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](../authority/01-session.md); 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.
