[2JIHAN]

Summary

The four review notes from #141, as agreed there. Each is its own commit.

1. A lost conversation says which one it was. conversationEntries was right to discard a scan that did not end on SQLITE_DONE, but it returned the same [] as a conversation with no usage and said nothing, so a store that could not be read stayed invisible for as long as it stayed that way. The read is now a value with four cases, because three of them produce no rows and only one of those three is a fact about the user's spend. A file with no gen_metadata is deliberately not a loss — this directory can hold databases that are not conversation stores, and a missing table is permanent, so naming it would print the same line every two minutes forever. SQLITE_ERROR from prepare is that case; BUSY or I/O there is a real loss.

The regression test walks the branch rather than approximating it. A lock cannot be used — immutable=1 disables locking, so the fallback reads straight through anything a test could hold — so the fixture spans several 512-byte pages and has the last page's b-tree type byte damaged, which steps rows and then returns SQLITE_CORRUPT. It asserts the trigger condition first, that rows really do arrive and the scan really does not reach DONE, so it cannot keep passing if the failure moves to the open.

2. Discarded token counters are reported. tokenCount clamped anything above the ceiling to 0, which is the right value, but left the record looking like a turn that used no input. It now returns nil for a value that cannot be a count, which the absent case does not — cache_write_tokens is declared and never written, so "the writer set nothing" is a legitimate zero. Counting is per row and reporting per store: tokenCount runs four times a record and the live store here holds 5,572 of them.

3. The cache keys on each store's (mtime, size). It expired after 30 seconds while LocalUsageCache keys per-file blobs, which has both of a timer's failings — for up to half a minute it served a store that had just changed from a parse taken before the change, and the moment it lapsed it reopened all 160 stores to find that none had moved. Measured on the live store: cold scan 0.185s, second scan 0.013s with all 160 blobs reused.

The signature is the newest of the .db and its -wal plus their two lengths. -shm is excluded on purpose and it is the subtle part: a read-only WAL connection writes read marks into it, so a key that included it would be invalidated by this reader's own read, on every scan — a cache that never hits, which is worse than the expiry it replaces.

Three things had to move for a blob to be sound: the window filter left the row loop (a cutoff baked into a cached unit is wrong as soon as the window moves); a read that did not finish no longer writes a blob, carrying the previous rows forward under their old signature so the next scan retries; and a database with no gen_metadata does cache its empty, because that is permanent. The monthKey guard went with the expiry — enrichmentScanStart only ever advances, and the guard was keyed on the wrong quantity anyway: at 00:30 on the 1st the month key says April while the scan window starts in March, so it threw away exactly the blobs the new week total needed.

4. sqlite3_close_v2. Nothing leaks today because the finalize is registered after the close and defer runs last-in-first-out, but that is a fact about where two lines sit, not about the call — and the function has since grown early returns between them. The error path in openReadOnly is the site where v1 could already have been wrong: there is no statement to order against there at all.

Plus the two follow-ups the protocol asks for. docs/reference/defect-log.md gains the three classes these notes produced — a blob cache removing the retry that a discarded partial read depends on, why the file our own read touches cannot be in the invalidation key, and failure folded into [] being indistinguishable from no usage. And AntigravityProto.tokenCeiling now cross-references LocalUsageReader.maxParsedTokenValue.

One question, on that last point. #145 landed while #141 was open, and the two ceilings differ on both axes: 1e9 vs 1e15, and this one discards the counter where that one clamps to the ceiling. Neither divergence is accidental — nothing here adds two parsed values before Entry.total, so a tighter ceiling costs nothing, and clamping keeps a number that then dominates today's total, the burn tier and the companion, where discarding loses one counter and leaves the record intact. But defect-log.md asks for one defence point per class, so I have written the difference down rather than reconciled it. Happy to converge them either way if you would rather — it is a small change in either direction.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• Other:

Checklist

• swift build and swift test pass locally — 577 tests, scripts/test-gate.sh reports 89.52%
• PR title and description are written in English
• UI changes are described above (before/after — images optional) — nothing under Sources/PokeTokenBar/UI/ changed, so the UI section is omitted
• No copyrighted assets, secrets, or private tooling references are committed (see CONTRIBUTING)
• Tests were added or updated for this change

[chattymin]

Thank you so much for your contribution! You implemented exactly what we had discussed earlier, so everything looks perfect without any additional back-and-forth. We really appreciate your interest and effort, and we look forward to seeing more contributions from you in the future!