Offload RealVideoProcessor result cache disk I/O to threads

[groupthinking]

Move RealVideoProcessor cache read/write (disk + JSON) off the event loop via worker threads and make cache writes atomic.

[linear-code]

GRV-243

[github-actions]

👋 Thanks for opening this issue! It has been automatically labeled for triage.

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• perf: RealVideoProcessor blocks the event loop on result-cache disk I/O #1227

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[groupthinking]

Took this on. Findings, in order of what a maintainer needs to know.

1. This issue as literally written is already fixed

Both stated requirements shipped in merged PR #1228:

This issue asks for	Status on main
_load_from_cache off the loop	Done — asyncio.to_thread(self._read_cache_file, …) (L139)
_save_to_cache off the loop	Done — asyncio.to_thread(self._write_cache_file, …) (L166)
Atomic cache writes	Done — tempfile.mkstemp in the cache dir + os.replace + unlink-on-failure

Verified by reading the shipped source on main, not by trusting the PR description. What landed is stronger than this issue asks: _read_cache_file fstats the open descriptor, so a concurrent republish can't cause a stat/read mismatch.

Why the duplicate exists: #1228 closed its parent #1227 as COMPLETED at 2026-08-02T14:34:27Z. This issue was filed 16 seconds later at 14:34:43Z. That's an automation race, not a second genuine report. CodeRabbit flagged the same thing.

2. But there is a real remaining gap — same defect class, third call site

I didn't want to close this off a read of the two methods the issue names, so I scanned every blocking-I/O primitive in the file grouped by its enclosing def. That turned up one call site #1228 missed.

get_processing_status (L473) is async def, but counted cache entries inline:

cached_files = len(list(self.cache_dir.glob("*_processed.json"))) if self.cache_dir.exists() else 0

Two blocking syscall sequences on the loop thread — stat(), then an eager opendir/readdir walk of the whole cache directory.

It's live on an HTTP endpoint. real_api_endpoints.py:324 awaits it. Every status request stalled all concurrently-served requests for the length of the walk, scaling with the number of cached videos.

Worth noting why it survived #1228: TestGetProcessingStatus had three tests asserting the count is correct (cached_videos == 2), but nothing asserted where the scan runs. The blocking behavior was entirely unlocked, so nothing failed when it was left inline.

3. Fixed in #1237

Mirrors the convention #1228 established here — a blocking @staticmethod awaited via asyncio.to_thread — plus two tests that assert the offload from independent angles (thread identity; loop responsiveness while the scan is in flight). Neither names asyncio.to_thread, so they stay honest if the mechanism changes.

RED 2 failed/3 passed → GREEN 5/5; 326 passed across all five related test files; revert the fix and only the two new tests fail. Three negative controls all discriminate — including one that keeps the helper but calls it inline, which proves the tests assert offloading rather than rewarding the extraction. Zero new CI lint violations.

Recommendation

Keep this open until #1237 merges, then close. Closing it now as a duplicate of #1227 would discard a real, endpoint-reachable instance of the same defect.