souveraine-viewtop

The Souveraine compositor. Wayland session for the phone, built so the agent can compose over the screen rather than ask a shell for permission to touch it.

Names and boundaries

Sensorium is Souveraine's whole field of sensing and action across tools and surfaces.

Membrane is this compositor's name: the device-local touchpoint at the glass. It receives physical input, composes the visual scene, and withholds disclosure from sessiond facts.

sessiond decides session and lock truth. Membrane attests the display-side fact and applies that decision. It is one physical reach of the larger Sensorium, not the Sensorium and not a session authority.

The repository, package, binary, socket, and wire names remain viewtop until their compatibility migration is deliberately staged.

Why it exists

Doctrine §13: the agent owns the device more than the user does — call it 60/40. Operation, composition, and observation are the agent's; being the user, the credential, and the step-up are not. A verb the agent cannot reach is a defect unless a rule says otherwise.

A compositor whose shell answers to someone else's policy cannot honour that. Client windows have to become objects in a scene the agent can address — move, group, reveal, hide — not opaque rectangles a window manager owns.

Architecture

Crate	Owns
sessiond-client	Talks to souveraine-sessiond. Asks; never decides.
wire	Typed protocol between the compositor and the Flutter shell.
compositor	Smithay: Wayland protocol state, input routing, DRM/KMS.
shell-host	Hosts the Flutter engine; bridges scene state both ways.

sessiond stays the session authority. viewtop serves ext-session-lock-v1 so sessiond takes the lock through it exactly as it does against Hyprland today — viewtop gains the lock-surface role, never the decision. Per doctrine §4, nothing here caches state the protocol owns: locked arrives in SessionFacts and is stored verbatim. The verb vocabulary is not compiled in either; describe returns the table and callers plan from it, so this does not become a second place device capabilities are enumerated.

The lock gates the glass, not the agent. A locked device is one whose screen is unauthenticated, so the lock withholds disclosure to whoever is looking — and nothing else. Annie composes the whole scene while locked. The single unconditional refusal in the codebase is that unlock is never an agent verb (§13). See docs/LOCK-AUTHORITY.md.

Design decisions

Doc	Settles
docs/SHELL-BOUNDARY.md	The Flutter engine runs in-process, and what pays for that
docs/LOCK-AUTHORITY.md	sessiond decides locked, viewtop attests; the gate that replaced denial's secure_session_locked()

Building

Never build on the phone. The Pixel 3 is the daily driver; a build there costs a live system. a cross-compilation host builds everything.

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo build -p viewtop-compositor --features nested --bin viewtop

python3 scripts/make-aarch64-sysroot.py --out "$PWD/.aarch64-sysroot"
VIEWTOP_AARCH64_SYSROOT="$PWD/.aarch64-sysroot" \
  ./scripts/build-cross.sh --release

The Flutter engine is built separately from pinned revisions (Flutter 84fc5cbb, Skia e9ed4fc9, Dart d684a576) with the ten-patch DMSAA/external-texture series applied, retargeted to arm64.

Status

sessiond-client is real and tested against the live daemon's twelve-verb table. The Smithay Wayland frontend and both presentation backends are implemented. viewtop --nested runs the reversible winit test path; viewtop --kms opens the seat and DRM device through libseat and udev, brings up GBM/EGL/GLES, discovers outputs and libinput devices, and presents through DrmCompositor on the page-flip clock. CI constructs the arm64 sysroot from declared packages, builds the phone KMS binary, and verifies that its dynamic dependencies resolve inside that sysroot rather than the build host.

The unfinished seam is the Flutter shell. shell-host currently owns only disclosure classification; engine embedding, client surfaces as external textures, and the wire-to-compositor bridge remain open. The source and CI therefore prove an implemented, buildable compositor path, not a complete phone session or an end-to-end hardware touch result. Sessiond already owns the separate-process fallback described in SHELL-BOUNDARY.md; ViewTop will not grow a second one.

Licence

AGPL-3.0-or-later.