From 2dc15a4849fe365558b57176d164c11f6495fbcc Mon Sep 17 00:00:00 2001 From: Eduard Tolosa Date: Tue, 26 May 2026 21:33:10 -0500 Subject: [PATCH] docs: document the single-instance daemon contract Add a "Single instance" note to ARCHITECTURE explaining the two layers that keep exactly one daemon on the bus: the extension skips spawning when the name is owned, and the daemon requests it with DoNotQueue (exits if taken, never steals/orphans). Co-Authored-By: Claude Opus 4.7 --- ARCHITECTURE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 45d6f64..965a80c 100755 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -71,6 +71,17 @@ The extension listens for `notify::g-name-owner` on the D-Bus proxy. When the daemon's `dev.edu4rdshl.Strata` name becomes owned, the panel triggers its initial fetch. No polling, no fixed delays. +### Single instance + +Exactly one daemon should serve the bus name. Two layers enforce it: the +extension skips spawning when `GetNameOwner` shows the name is already owned +(so a daemon started out-of-band, e.g. via a systemd user service, is reused), +and the daemon itself requests the name with `DoNotQueue` -- if the name is +already taken it errors out and exits rather than queueing or stealing it. +It deliberately does not use `ReplaceExisting`: taking the name from a running +instance would orphan that instance (zbus does not terminate a replaced owner), +so the late starter bows out instead. + ## Ingest path ```