✨ What kind of change does this PR introduce? (Bug fix, feature, docs update...)
Bug fix.
⤵️ What is the current behavior?
A failed JSON metadata write is reported but completes successfully. The repository can later persist the failed mutation, and a download replacement can delete the previous file even though its replacement metadata was not saved.
🆕 What is the new behavior (if this is a feature change)?
JSON mutations are serialized and committed to memory only after an atomic snapshot write succeeds. Failed JSON persistence operations now propagate errors instead of silently succeeding. This is an intentional failure-path behavior change; there are no public API or signature breaking changes. Failed writes leave the last committed metadata intact and do not prevent later operations. The proposed version remains 3.4.9, and maintainers may adjust it if necessary. Cache-hit timestamp updates use the current entry instead of rewriting a stale path. An existing file-deletion ordering issue remains: a failed metadata deletion after a file is removed leaves a stale record, and rollback means later writes can retain it. Replacement downloads now remove the old file only after the new file and its metadata have been saved.
💥 Does this PR introduce a breaking change?
No
🐛 Recommendations for testing
Flutter 3.47.4: formatting, analysis, and 147 tests passed. Web, Linux, and Android debug builds passed after the replacement-ordering change; verify iOS, macOS, and Windows in CI. Publish dry-run reports the existing ignored tracked-files warning.
📝 Links to relevant issues/docs
Related to the replacement persistence requirement for #508.
🤔 Checklist before submitting
- All projects build
- Follows style guide lines (code style guide)
- Relevant documentation was updated
- Rebased onto current main
- Version bumped and dated CHANGELOG entry added