1 files changed, 149 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-10-15-updates-design.md b/docs/superpowers/specs/2026-10-15-updates-design.md
new file mode 100644
index 0000000..e6a3458
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-15-updates-design.md
@@ -0,0 +1,149 @@
+# Updates module
+
+A drawer tile and page that answer one question per row: what do I do next
+to bring this machine up to date. It replaces two places that showed the same
+facts less clearly: the conky updates card, a copy of `nvtable`'s table where
+installed-behind and repo-behind share a row and are told apart by colour,
+and the homepage ChangeLog widget, which shows the latest upstream -current
+entry rather than what this machine is missing.
+
+## Sources and what they mean
+
+Four versions per tracked package:
+
+- **U, upstream**: `~/.config/nvchecker/new_ver.json`.
+- **R, recipe**: `VERSION=` in `<pkg>.info` under the three repos of
+  `~/Programming/GIT/slackbuilds-superrepo` (`sbo-slackbuilds`,
+  `my-slackbuilds`, `Slackware-Pentesting-Suite`), falling back to the
+  SlackBuilds.org clone at `/var/lib/sbopkg/SBo-git`. A recipe from that clone
+  is tagged `SBo`: it is not the user's SlackBuild, and a bump of it happens
+  through a slackrepo `.hint` file on the build VM, which is not visible from
+  here.
+- **B, built**: `PACKAGES.TXT` of the user's binary repo, the directory named
+  by the `danix` entry of `MIRRORPLUS` in `/etc/slackpkg/slackpkgplus.conf`.
+- **I, installed**: `/var/log/packages`, then appimage-updater's
+  `installed.json`, then `flatpak list --app`, in that order, as `nvtable`
+  does.
+
+nvtable's two alias tables (stanza name to installed name, stanza name to
+SlackBuild directory) are ported into the script as dicts.
+
+For Slackware itself, the mirror is the `file://` line active in
+`/etc/slackpkg/mirrors`. Its `PACKAGES.TXT` and `ChangeLog.txt` are compared
+against `/var/log/packages`. `/var/lib/slackpkg/ChangeLog.txt` is not used:
+`slackpkg update` replaces it without installing anything, so a diff against
+it reads "nothing pending" after an update that was never applied.
+
+## Sections
+
+In page order. A package appears in exactly one section, the first that
+matches, so a row shows the next step and nothing after it.
+
+1. **Slackware**, three groups, all from the mirror:
+   - *Upgrade*: an installed package whose name is on the mirror with a
+     different version or build.
+   - *New*: the ChangeLog's newest line for the package says `Added.`, it is
+     on the mirror, and it is not installed. These are slackpkg's
+     `install-new` semantics.
+   - *Removed*: the ChangeLog's newest line for the package says `Removed.`,
+     it is installed, and it is not on the mirror. The row carries the date of
+     that ChangeLog entry.
+
+   Installed packages whose build tag matches a pattern in
+   `/etc/slackpkg/blacklist` (`_SBo`, `_danix`, `alien` and the rest) are
+   skipped in all three, as slackpkg skips them; so are blacklisted names.
+2. **Upgrade here**: B newer than I. The package is built and sitting in the
+   repo.
+3. **Awaiting build**: R is the user's (not `SBo`), R equals U, and B is older
+   than U. The SlackBuild is bumped and only needs building.
+4. **Upstream newer**: U newer than both R and B. The SlackBuild or its hint
+   needs bumping, then a build. `SBo` rows land here until the build appears
+   in B.
+5. **App updates**: I comes from AppImage or flatpak and is older than U.
+
+"Newer" and "older" are version order, never equality: an installed 2.1.278
+against an SBo recipe of 2.1.267 is not an upgrade. A tracked package that is
+not installed and whose recipe is current is not shown.
+
+## `updatesctl`
+
+`desktop/modules/updates/updatesctl`, `/usr/bin/python3`, standard library
+only. It prints one JSON document:
+
+    {
+      "checked": <mtime of new_ver.json, epoch seconds>,
+      "slackware": {"upgrade": [...], "new": [...], "removed": [...]},
+      "upgrade": [...], "build": [...], "upstream": [...], "apps": [...],
+      "errors": {"mirror": "unreachable", ...}
+    }
+
+Rows are `{name, repo, from, to}`; Slackware rows are `{name, from, to}`,
+`{name, version}` and `{name, date}`. `repo` is the label nvtable shows
+(`personal`, `my-sbo`, `pentesting`, `SBo`, `AppImage`, `flatpak`).
+
+**Version order** is a small `vercmp`: split on non-alphanumerics, compare
+numeric chunks as numbers and alphabetic chunks as strings, numbers before
+letters. It replaces nvtable's normalised equality, including its rule that
+an installed version extending upstream at a component boundary (a kernel
+suffix, a git hash) counts as equal; that rule is kept as a prefix check
+before ordering.
+
+**NFS reads** (`PACKAGES.TXT` of the repo and of the mirror, the mirror's
+`ChangeLog.txt`) go through `subprocess.run(["cat", path], timeout=5)`. The
+mount is `hard`, so a read during a NAS outage blocks; the timeout kills the
+child, the script carries on, and that source is reported in `errors` while
+the sections that do not need it still fill.
+
+**`--refresh`** runs `nvchecker -c ~/.config/nvchecker/nvchecker.toml`
+synchronously first, then prints as above. That config already names the
+GitHub keyfile. nvtake is not run: this model never reads `old_ver.json`.
+
+## Module
+
+`desktop/modules/updates/UpdatesModule.qml`, name `updates`.
+
+- **Icon**: ``, `linux-slackware`, present in Inconsolata Nerd Font.
+- **Tile line**: `3 to install · 2 to build`, counting Slackware (all three
+  groups) plus Upgrade here as "to install", and Awaiting build as "to build".
+  `up to date` when both are zero. `checking…` before the first result.
+- **Active** (accent) when there is anything to install.
+- **Freshness**: when the tile is created, which is when the drawer opens, the
+  module runs `updatesctl`. If `checked` is more than 30 minutes old it then
+  runs `updatesctl --refresh` and the page shows `checking…` until it
+  returns. Nothing runs while the drawer is closed, the same gating as KDE
+  Connect.
+- **Page**: the five sections in order, each with a heading and a count, each
+  hidden when empty. Rows read `name   repo   from → to`. A footer reads
+  `checked 12 min ago` and holds a refresh button that runs `--refresh`.
+  An entry in `errors` shows as one dim line under the section it empties,
+  e.g. `mirror unreachable`. Read-only: no install or build buttons.
+
+## Retiring conky's card
+
+Once the user trusts the tile, `bin/updates-sample.sh` and
+`widgets/updates.lua` are deleted from `conky-theme-udt`, with the card's
+slot, as a separate commit in that repo. `nvtable` stays in
+`danix-nvchecker` for the shell; this repo does not depend on it.
+
+## Testing
+
+`desktop/modules/updates/test_updatesctl.py`, run with `/usr/bin/python3`:
+
+- `vercmp`: 1.14.10 > 1.14.9, 2.1.278 > 2.1.267, 2026_10_02 > 2026_09_12,
+  a kernel suffix equal to its base.
+- Section assignment on fixture directories built in a temp dir, one row per
+  case: built and newer goes to Upgrade here, bumped and unbuilt to Awaiting
+  build, unbumped to Upstream newer, an SBo recipe behind upstream to
+  Upstream newer, an installed version ahead of SBo to nothing, an AppImage
+  behind to App updates.
+- Slackware: a mirror with one changed build, one `Added.` package and one
+  `Removed.` package, plus a blacklisted `_SBo` build that must not appear.
+- An NFS path that times out: a fifo with no writer, read with a short
+  timeout, must report `unreachable` without hanging the test.
+
+The tests must be shown to fail on a broken input before they are trusted.
+
+## Not in scope
+
+Installing, building, or bumping from the page. Showing upstream lag of the
+NFS mirror itself. Reading slackrepo hint files from the build VM.