vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: fix upgrade-block bullets for the store-first sweep

Browse source 
`ensure_hive_user` no longer short-circuits on the token file it
already has, and a hive's per-hive store token now wins over the file
whenever it's present. Both upgrade-guide bullets described the old
file-first order and needed rewording to match.

Refs #4427
This commit is contained in:
atlas 2026-09-29 20:28:36 +02:00 • committed by mara
commit d98d407bf1
1 changed files with 23 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/integrations/matrix.md
View file

@ -217,18 +217,29 @@ Nothing to do, and no window where the hive is without an account.
stays in the store, unread, until an operator deletes it. Delete it or
leave it; the accounts it authenticates as keep their own standing either
way, since an access token lives on the device that minted it.
- **The hive re-mints, per hive, on the next boot.** `ensure_hive_user` runs
from the startup sweep. It short-circuits on the token file it already has
— so the first boot after the upgrade keeps running on the shared token
until that file goes — and on a hive with no such file it reads the new
per-hive store path, finds nothing on a store that has never held one, and
falls through to the register-or-appservice-login ladder against
`@hive-<hive>:`. That ladder needs only the `as_token`, which is per hive
and on local disk, so it works with or without a reachable store.
- **To move a hive onto its own account now**, delete its sender-token file
(`hivectl matrix sync-admin` re-provisions, or the next sweep does) — the
ladder then registers `@hive-<hive>:` and persists that account's token.
Only then does the hive stop presenting the shared one.
- **The hive re-mints, per hive, on the next sweep.** `ensure_hive_user`
reads the new per-hive store path **first, on every sweep**, not just when
the file is missing (`sender_source`'s decision). If a per-hive token is
already there — `swarm-controller` mints one for every hive — the sweep
takes it and overwrites the file, so the shared token stops being served
as soon as one exists in the store, no boot required. If the store has
nothing yet, the file is left untouched (still the shared token, right
after the upgrade), so nothing breaks mid-sweep. Only when neither the
store nor the file holds anything does the sweep fall through to the
register-or-appservice-login ladder against `@hive-<hive>:`, using only
the `as_token`, which is per hive and on local disk, so that step works
with or without a reachable store.
- **To move a hive onto its own account now**, clear both copies: the
sender-token file, and the store's `swarm/hives/<hive>/matrix/sender-token`
if `swarm-controller` or `swarm-matrix-ctl` has already published one for
it (otherwise the next sweep just re-adopts that value instead of minting
a new one). With both empty, the next sweep — or `hivectl matrix
sync-admin` — runs the ladder, registers `@hive-<hive>:`, and persists
that account's token to the file. The ladder never writes the store — on
a swarm that runs `swarm-controller`, its own mint pass will reach the
same account on its next tick and write a token there too, on the same
pinned device, which replaces whichever token was minted last. Only once
both copies agree does the hive stop presenting the shared one.
- **The rooms the shared account created don't follow the new account, and
this is the one step that needs a decision.** Membership is per account.
`ensure_hive_space` takes the stored room id first, so the sweep hands the