bde961c6f2
PAF becomes saf/device (history kept), STATE.md dissolves into saf/state.md with the dated era archived, the substrate SAF moves up from souveraine, and every agreement points at saf/INDEX.md and nowhere else. one map, nothing to remember
102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
## The principal split still owed
|
|
|
|
This is the process-order graph that exists; it is not yet the final security
|
|
boundary. All of its units are currently user units and therefore inherit the
|
|
human graphical session's UID. The target moves sessiond's lock lifecycle to
|
|
the dedicated `souveraine-session` principal described in
|
|
[session authority](../authority/01-session.md), while the user manager keeps
|
|
only the presentation and application lifetimes that belong there.
|
|
|
|
The compositor must offer that principal a narrow way to hold
|
|
ext-session-lock and render the fallback without granting it Casey's home or
|
|
general session bus. The lock authority must be ready before the user home is
|
|
decrypted and remain ready after the Personal key is evicted. Changing unit
|
|
placement without proving the Wayland connection, PAM path, handoff, crash
|
|
retake, and key-eviction order would only move the black screen to a new UID.
|
|
|
|
## 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.
|