fix: recover cache metadata sidecars

[leehack]

Summary

• Recover missing, malformed, or unsupported-version model cache metadata sidecars when the completed deterministic cache file is still present.
• Treat metadata byte-count mismatches and stored/caller SHA-256 mismatches as cache misses by deleting stale cache artifacts so reuse policies redownload safely and cache-only fails.
• Document metadata invariants and recovery behavior in the public download/cache docs and changelog.

Closes #134

Production-readiness scope

• Users can keep using package-managed native model downloads when only metadata.json is damaged or from an unsupported schema version; the deterministic completed model file is reused without network access.
• Supported paths: native/file-backed DefaultModelDownloadManager stable cache entries for HTTP(S)/Hugging Face-derived remote model sources.
• Unsupported/stale paths: missing completed files, source/file/path mismatches, byte-count mismatches, and checksum mismatches are treated as cache misses instead of returning stale entries.
• Existing APIs remain compatible; behavior is an internal cache-hardening change.

Test Plan

• dart format --output=none --set-exit-if-changed lib/src/core/models/download/model_download_manager_base.dart lib/src/platform/io/model_download_manager_io.dart test/unit/platform/io/model_download_manager_io_test.dart
• dart test -p vm test/unit/platform/io/model_download_manager_io_test.dart
• dart analyze
• dart test -p vm -j 1 --exclude-tags local-only

Review Notes

• Local diff reviewed for issue feat(models): harden cache metadata versioning and recovery policy #134 acceptance criteria: metadata recovery cases, stale-metadata cache-miss behavior, and signed URL redaction guarantees.

[Copilot]

Pull request overview

This PR hardens the native/file-backed model download cache by making cache metadata (metadata.json) recoverable when the completed deterministic model file is still present, and by treating byte-length / SHA-256 mismatches as cache misses (cleaning up stale artifacts) so re-download policies behave safely. It also documents the metadata invariants/recovery behavior and adds targeted unit tests for the new recovery paths.

Changes:

• Recover missing/malformed/unsupported-version metadata.json sidecars from an existing completed cache file (including cacheOnly).
• Treat recorded byte-length mismatches and stored/caller SHA-256 mismatches as cache misses by deleting stale cache artifacts.
• Add unit tests and update public docs/changelog to describe metadata invariants and recovery behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/src/platform/io/model_download_manager_io.dart	Adds metadata recovery path and shared verification helpers for completed cache files.
test/unit/platform/io/model_download_manager_io_test.dart	Adds tests covering metadata recovery and mismatch-driven re-download behavior.
lib/src/core/models/download/model_download_manager_base.dart	Documents recovery/miss policy expectations for implementations.
website/docs/guides/model-lifecycle.md	Documents cache metadata invariants and recovery behavior for users.
website/docs/changelog/recent-releases.md	Adds release note entry for metadata recovery hardening.
CHANGELOG.md	Adds corresponding changelog entry for metadata recovery and mismatch handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 57.97101% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.23%. Comparing base (b982ce4) to head (31cebb1).

Files with missing lines	Patch %	Lines
lib/src/platform/io/model_download_manager_io.dart	57.97%	29 Missing ⚠️

❌ Your patch status has failed because the patch coverage (57.97%) is below the target coverage (70.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #140      +/-   ##
==========================================
- Coverage   78.38%   78.23%   -0.15%     
==========================================
  Files          75       75              
  Lines        9646     9696      +50     
==========================================
+ Hits         7561     7586      +25     
- Misses       2085     2110      +25     

Flag	Coverage Δ
unittests	78.23% <57.97%> (-0.15%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.