DOCS-app-errors: the shared error pipeline

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-17 21:49:15 +01:00
parent 10e4656b04
commit a22b412463
2 changed files with 66 additions and 0 deletions

59
DOCS-app-errors.md Normal file
View File

@ -0,0 +1,59 @@
# App errors and slow waits become board tickets
kuhy's rule (2026-11-17): every error, and every wait the user sees over 1 s, in
any of his apps is reported automatically. The board then turns each one into a
ticket that fixes itself. This doc covers the apps' half and the PC ingest. The
board's half is todoImplementer `DOCS-errors.md`, with the contract in
`contracts/app-error.schema.json`. The design is kartka's pipeline
(`~/src/kartka`, `docs/DOCS-error-reports.md`), made shared.
## Pipeline
1. **Apps report.** Each report is one *entry* (see `app_errors/README.md`):
- Flutter, `crdt_sync_flutter` 0.9.0: `installAppErrors` hooks
`FlutterError.onError` and `PlatformDispatcher.onError`. `WaitWatch` turns
a spinner shown over 1 s into `perf.slow`. The device deduplicates (30 s,
20 a minute) and redacts each report, and queues it in
`SharedPreferences`. It uploads to RTDB `/<app>/errors/<device>/<id>` with
the build (versionCode).
- Python/Tk, `gatelock` 0.15.0: `gatelock.error_report.install` hooks
`sys.excepthook`, `threading.excepthook` and Tk callback errors.
`watch_stalls(root, rep)` reports a frozen Tk loop over 1 s.
`rep.wait(...)` and `rep.begin(...)` time a wait.
- Godot, `godot_dev_tools` 0.2.0, `addons/app_errors`: an `OS.add_logger`
logger catches script errors and `push_error`. A frame over 1 s, or
`report_wait` over 1 s, becomes `perf.slow`.
- PC apps (Tk and Godot) append to the local spool
`~/.local/state/app-errors-spool/<app>.jsonl`. They need no RTDB, because
the ingest runs on the same PC.
2. **The PC ingests.** `app-errors-ingest.timer` runs `app-errors ingest` every
5 min. It reads RTDB through an already seeded crdt-sync session
(`firebase_backup`) and reads the spool. It merges reports by signature
(Dart signatures are kartka-identical), deletes what it read, and writes
`~/.local/state/app-errors/<app>.json` as a contract `report`.
3. **The board files tickets.** It scans that folder every 60 s and makes one
ticket per `app:signature` (todoImplementer `DOCS-errors.md`).
`app-errors resolve <app> <signature>` sets `open: false`. A later report opens
the error again only when it is a regression: a newer build when both sides
know the build, else a report made after the resolve. The board never calls
`resolve` on its own, because folder sources have no resolve hook. It tracks
shipped fixes by `fixed_build`.
## Choices made (no questions asked, per the brief)
- kartka keeps its own ingest for now. The shared ingest skips `/kartka`, and
the board's `kartka` adapter still reads kartka's `state.json`. Two readers
would race on deletes. To move kartka over, switch the board's default
source off (`error_sources`) and retire `kartka-errors.timer`. Its ticket
ids stay the same, because the signatures match.
- Tk and Godot use the local spool instead of RTDB: they only run on the PC.
- The Godot reporter is its own addon folder, mounted in every build. It is
not part of `dev_tools`, which only loads for `--dev` runs.
- Reporting is silent: no text, dialog or notification in any app.
## Install and check
`scripts/deploy.sh` runs `app_errors/install.sh`. That installs the venv and
`~/.local/bin/app-errors`, enables the timer, and checks that the timer is
active and the venv imports the live checkout.

View File

@ -77,6 +77,13 @@ watcher + pacman hooks). Not a package — installed by running
Consumed by `steam-backlog-enforcer` (expects a `guard-lib/install.sh`
sibling clone) and referenced by `screen-locker`.
## app_errors/
The PC ingest of the shared app error and slow-wait reporting: RTDB and local
spool reports in, todoImplementer board tickets out, on a systemd `--user`
timer. The reporters live in `crdt_sync_flutter`, `gatelock` and
`godot_dev_tools/addons/app_errors`. See [`DOCS-app-errors.md`](DOCS-app-errors.md).
## gatelock/
Python lock-window + HMAC log-integrity backend (package: `gatelock`, not