fix(models): recover from undecodable revision markers

[rudycelekli]

Summary

An undecodable local revision marker raises before the existing validated legacy-reference or curated-pin fallback can run.

Changes

• Treat Unicode decoding errors like unreadable marker files and retain the existing fallback order and repository validation.
• Add focused regressions and update the relevant documentation and changelog.

Type

• 🐛 Bug fix

Testing

• Hosted CI audit at 2026-10-06T12:35:20.584679+00:00: no failing latest checks; required CLA passes. All latest reported checks completed successfully. No upstream merge performed.

• Native temporary marker/reference files cover invalid bytes and BOM bytes, both with and without a valid legacy reference. The model-dependent NLLB route test was deselected.

• Regression against unchanged main production source: 6 failed, 5 passed, 1 deselected. After the fix: 11 passed, 1 deselected; 24 with changelog gate.

• Python 3.13 with HF_HUB_OFFLINE=1 and an empty Hugging Face cache. No model download or inference calls.

• Diff check and Python compilation pass.

• Full backend/Electron suites were not run locally; focused tests alone do not establish hosted security or platform gates. Hosted results are reported separately below.

Checklist

• I've tested this locally
• Every commit author has signed the CLA — registered signature and required CLA status verified
• I've updated relevant documentation
• No local machine paths, logs, or personal env details in this PR
• Maintained version files are in sync — no version bump
• Runtime regression fixture still loads green on smoke-matrix CI — not run locally

Closes #2634

installed_revision now skips marker files that raise ASCII decoding errors, so a valid legacy reference or curated revision pin can still support model repair. Regression tests cover invalid and BOM bytes, with and without a valid legacy reference. Full backend, Electron, hosted security, and platform validation remains unverified.

[github-actions]

All contributors on this pull request have signed the VoiceStudio CLA. Thank you!

[greptile-apps]

[Medium risk] Handles corrupted model revision markers gracefully.

The reviewed change appears safe to merge.

Summary

The PR lets model-revision lookup continue past undecodable local markers and adds focused regression coverage and troubleshooting guidance.

_{Reviews (1) · Last reviewed commit: "docs: link revision-decode regression re..."}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: debpalash/VoiceStudio/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2550cd13-3e20-4e7b-af22-209013917110

📥 Commits

Reviewing files that changed from the base of the PR and between 286f46b and 686ef92.

📒 Files selected for processing (4)

• CHANGELOG.md
• backend/services/hf_revisions.py
• docs/install/troubleshooting.md
• tests/test_hf_revisions.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

installed_revision now skips revision markers that cannot be decoded and continues to the legacy Hugging Face reference or curated revision fallback. A parametrized test covers both fallback outcomes. The changelog and troubleshooting guide document the behavior.

Changes

Revision Marker Repair

Layer / File(s)	Summary
Decode errors and revision fallback backend/services/hf_revisions.py, tests/test_hf_revisions.py, docs/install/troubleshooting.md, CHANGELOG.md	installed_revision catches UnicodeError when reading a marker. Tests verify use of a valid legacy refs/main revision or the curated revision. The troubleshooting guide and changelog describe the fallback.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: debpalash

Merge Risk: ⚪ Minimal · up to 686ef

Undecodable revision markers no longer block repair from using a valid legacy reference or the curated pin. No concrete merge-blocking risk is evident; normal project checks remain.

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #2634 requires undecodable revision markers to leave the validated fallback path available. installed_revision now catches UnicodeError and continues to the legacy reference or curated pin; …
Out of Scope Changes check	✅ Passed	All changes support issue #2634: the fallback fix, regression tests, troubleshooting guidance, and changelog entry. The diff shows no unrelated changes.
Cross-Platform Default Parity	✅ Passed	The default behavior changes in installed_revision at backend/services/hf_revisions.py:97-99. It now catches UnicodeError from the same explicit ASCII Path.read_text call on every platform, th…
I18n Completeness (21 Locales)	✅ Passed	The pull request changes only CHANGELOG.md, backend/services/hf_revisions.py, docs/install/troubleshooting.md, and tests/test_hf_revisions.py. It changes no Electron UI code, so it adds or changes no …
Local-First Guarantee	✅ Passed	The PR adds no cloud, account, or API-key requirement. The only production change catches Unicode decoding errors while reading local revision-marker files, then checks the existing local legacy refer…
Backward Compatibility	✅ Passed	The PR changes only revision-marker error handling, documentation, changelog, and tests. installed_revision still prefers a valid recorded revision or legacy refs/main revision, then uses the exis…
Title check	✅ Passed	The title follows the required conventional-commit format with a scope, describes the fix, and the description references issue #2634.
Description check	✅ Passed	The description includes the required Summary, Changes, Type, Testing, and Checklist sections. It explains the fix, regression coverage, test results, and validation limits.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[rudycelekli]

recheck

[debpalash]

Thanks for the report and the work on this, @rudycelekli. The problem in #2634 is fixed on main by 1f28c054 (merged in #2673), so I'm closing this pull request as already fixed. It will ship in v0.5.7. Reporter credit stays in the changelog.