# 030 — Account switch: sign-in, sign-out, remote sign-out (A06)

Created: 2026-11-06
Updated: 2026-11-06

Standa (S3, S4): sign-in is a clean switch to the account; the local data is backed up and comes back at sign-out;
both transitions 100% reliable, ending with the skin, every section and every widget reloaded **without restarting
Kodi**.

## 1. Folders

`DATA/account/`: `switch.json` (journal), `staging/` (downloaded account: `bootstrap.json` pages, `secrets.json`,
`schema.json`, `foryou.json`), `local_backup/` (`library_user.db`, `files/…`, `settings.json`), `base/` (020 §3).
All JSON written as `tmp + os.replace`. `staging/secrets.json` and `local_backup/settings.json` hold secrets: file mode
0600, never logged, deleted at `done`.

## 2. Backup set (the account class of WEB `02-data-inventory.md`)

- `library.db` user tables: `titles`, `movie_state`, `episode_state`, `play_log`, `feedback`, `sync_*`, the
  `flags` that are account-derived (`shared.tv.applied`), and `meta` keys `foryou:*`. Copied with `ATTACH` + `CREATE
  TABLE … AS SELECT` into `local_backup/library_user.db` in one read transaction. `pending_marks` is drained before
  (`jobs.process_marks` until empty, max 10 s) — otherwise the switch waits and says so.
- Files: every account-class document of 020 §3, `ai_usage.db`.
- Settings: every id of the account, secret and onboarding sets (from the schema) with its current value.
- Not backed up: shared caches, derived data, device settings, skin settings (S7).

## 3. Sign-in stages

| Stage | Does | On failure / crash |
|---|---|---|
| `login:stage` | pair done; download schema, bootstrap (all pages), secrets, Pro tebe snapshot into `staging/`; verify counts and versions | nothing local changed → delete staging, `POST api/sync/logout` (frees the device on the web), clear the token, tell the user why (the device stays signed out with its data untouched) |
| `login:backup` | write `local_backup/` (§2); fsync; record checksums in the journal | redo the stage from scratch |
| `login:apply` | one `store.tx()`: delete user tables' rows, insert the account's; `meta foryou:*` replaced; cursor = bootstrap `rev`; then files (`os.replace`), then settings (values from staging; secrets via `secrets.apply`); `base/` written | redo (idempotent: the same staging overwrites the same targets) |
| `login:refresh` | 040/A06.3 list: clear derived files (rows of user rows, `row_snapshots`, `skin_cache` user files, `channel_icons`, `provider_flags.json`), `refresh.changed(ALL_ROWS)`, `journal.request_all()`, `accounts.sync_status`, `appearance.publish()`, MyTV shared flag, Pro tebe snapshot from staging (or local build), Home window properties of the account item; `ReloadSkin()` only if A06.3 proves a section needs it | redo |
| `login:done` | delete staging, start the worker, notification "Přihlášeno jako …" | — |

The UI shows Kodi's progress dialog (`DialogProgressBG` from the plugin process that runs the switch, or the guide's
own status line) with the stage names; the GUI stays responsive (no work on the GUI thread).

## 4. Sign-out stages

| Stage | Does |
|---|---|
| `logout:flush` | stop the worker; push the outbox (≤ 10 s); if ops remain: S20 question (remote sign-out: no question, T13) |
| `logout:clear` | one `store.tx()` deletes the account's user rows; account files, account/secret/onboarding settings cleared |
| `logout:restore` | `local_backup/` → tables (one transaction), files, settings (verify checksums from the journal) |
| `logout:refresh` | as `login:refresh`, Pro tebe = the local snapshot from the backup (or a local build) |
| `logout:done` | `POST api/sync/logout` (if the token still works), clear token settings, delete `local_backup/` and `base/`, notification |

## 5. Remote sign-out (T13)

The worker sees `logout: true` (or 401). It pushes the outbox (not on 401), then waits while `Player.HasMedia` (checked
every 2 s via `monitor.waitForAbort`) — a film is never interrupted — then runs §4 from `logout:clear` and confirms.

## 6. Resume at start

`service.py`: before `start_rest()` and before the onboarding check, `wcs.account.switch.resume_if_needed()` (cheap:
one `os.path.exists(switch.json)`). An unfinished journal is finished in a background thread while Home shows a
"Dokončuji přihlášení/odhlášení…" notification; rows are built after it ends (the journal publishes a Home property
the row builder waits for — never longer than the switch takes; signed-out devices never wait).

## 7. What must be true after a switch (A06.3 checklist)

Pro tebe, Pokračovat, Moje filmy, Moje seriály, MyTV (channels, next), MyCinema, Vinyl (rows of the account's Vinyl
user), AI (history row), Milionář hra (topics row), TMDb rows, genre page, search history, Recently played, settings
dialog values, key statuses, the menu item 1108 label — all show the new side; nothing of the other side is visible
anywhere (screens + `rowfiles` contents checked).

## Result

2026-11-06: journaled sign-in (stage → backup → apply → refresh) and sign-out (flush → restore → refresh), local
backup via ATTACH of `library.db` user tables + JSON files + settings, reload without restarting Kodi, remote sign-out
waits for the end of playback (T13), interrupted sign-out resumes (K7). Verified: simulator kills inside both switches;
live Mac Kodi: sign-in ~20 s for Standa's account (backup 0.9, prepare 1.3, apply 14.1 of which library.db rows 10.9,
secrets 2.6, refresh 0.7), sign-out by the web during playback waited and finished within 5 s of the stop; the local
data after the sign-out equal to the backup taken before (all user tables and settings; only TMDb caches and widget
revisions differ).
