testsAndMisc/docs/superpowers/contracts/syncyomi-library-recovery-2026-08-09.json
Krzysztof kuhy Rudnicki cef72fbab0 syncyomi_guard: refuse a collapsed payload as the new good copy
TachiyomiSY 1.13.2 can report a restore as SUCCESS while writing almost
nothing, then sync that near-empty library up and replace the only good
copy. On 2026-08-09 a 14 MB payload holding 2182 manga became a 267 KB
stub, and the real library survived only as stale pages in the SQLite
write-ahead log.

The upstream bug is Kotlin in an APK and cannot be fixed here, so this
targets the fixable half: decode the payload, count what is actually in
it, and refuse to treat a collapse as normal drift. A pure is-it-zero
check would have caught this incident but not the harder case upstream
describes, where a restore keeps some entries and drops the rest, so the
threshold is proportional. Categories get their own rule because all
2182 manga survived the round trip and all 18 categories did not.

Adds the setup script and a runbook covering the WAL-page salvage used
to recover the library on the day.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YQLwdquDCNmWtvgi3Lk72J
2026-08-10 15:33:18 +02:00

19 lines
1.6 KiB
JSON

{
"title": "syncyomi_guard: refuse to let a collapsed sync payload overwrite the only good copy",
"objective": "TachiyomiSY 1.13.2 can report a backup restore as SUCCESS while having written almost nothing, then push that near-empty library to the SyncYomi server and replace the last good copy (observed 2026-08-09: a 14 MB payload holding 2182 manga became a 267 KB stub). The upstream bug lives in the APK and cannot be fixed here, so this package targets the fixable half: detect a payload collapse and refuse to accept it as normal.",
"acceptance_criteria": [
"Decodes the SyncYomi payload and reports counts of manga, categories and sources",
"Flags a collapse when a payload loses more than a tenth of its entries, not merely when it hits zero",
"Treats categories under their own rule, since the 2026-08-09 incident kept all 2182 manga but lost all 18 categories",
"Distinguishes normal drift from collapse so routine syncs are not blocked",
"100% branch coverage across every module in python_pkg/syncyomi_guard",
"Runbook documents the manual recovery path used on 2026-08-09 (WAL-page salvage)"
],
"out_of_scope": [
"Fixing the upstream TachiyomiSY restore bug (jobobby04/TachiyomiSY#1634, #1638) — that is Kotlin in an APK",
"Automatically restoring a collapsed library; the guard refuses the overwrite, a human does the recovery",
"Changing SyncYomi server deployment or the existing setup_syncyomi.sh"
],
"verifier": "python -m pytest python_pkg/syncyomi_guard --cov=python_pkg.syncyomi_guard (60 passed, 100% branch coverage on __init__, __main__, payload, store, verdict)"
}