utils/DOCS-app-errors.md
Krzysztof kuhy Rudnicki 073cc24468
Some checks are pending
app_errors tests / test (push) Waiting to run
data_transfer_flutter tests / test (push) Waiting to run
dependency freshness / dependencies on newest stable (push) Waiting to run
file length / file-length (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
sync_settings_ui tests / test (push) Waiting to run
app_errors: ingest kartka too
kartka now reports through crdt_sync_flutter 0.9.1, so the shared ingest
reads /kartka (old entry shape included) and kartka's own ingest retires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:23:59 +01:00

3.4 KiB

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. Headless runs and APP_ERRORS_OFF=1 write nothing, so a game's own test gates file no tickets.
    • 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 moved over on 2026-11-17: the shared ingest reads /kartka too (it parses kartka's older entry shape: sourceId, per-entry build), the board's error_sources is [] and kartka-errors.timer is retired. Ticket ids stayed the same: all 134 stored kartka signatures recompute identically.
  • 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.