perf(core): run visual participants (actor, scene) in parallel within a shared decode stream

[Mahnoor-Zaffar]

Summary

Runs the actor and scene visual participants in parallel over a single shared decode stream: one decode pass, per-participant bounded queues, and sentinel-based shutdown. Actor remains in-order; backpressure stalls decode when a participant falls behind. Also fixes a deadlock where a participant failing mid-stream would hang the pipeline — the participant error now propagates instead.

Internal-only; no public API or storage changes.

Motivation

Refs grayhatdevelopers#96. Video decoding is the common cost shared by the visual participants (scene, actor). Previously each participant ran its own pass over the decoded frames, so N participants meant N decode passes. This change decodes once and feeds both participants concurrently, cutting redundant decode work and letting the slower participant overlap with the faster one.

What changed

• src/vidxp/capabilities/visual.py — parallel participant scheduling over a shared decode stream:
  • one decode loop produces frames into per-participant bounded queues;
  • scene and actor consumers run concurrently in their own workers;
  • sentinel shutdown terminates consumers cleanly when decode completes or is cancelled;
  • actor remains in-order while scene may lag;
  • backpressure: if a participant falls behind its queue limit, decode stalls so memory stays bounded;
  • mid-stream participant failures are surfaced as errors instead of deadlocking the pipeline (they are joined and re-raised, not swallowed).
• tests/test_visual_threading.py — 7 unit tests covering concurrent processing, cancellation, decode failures, participant failures, ordering, and backpressure/shutdown.

Design details

• One decode pass: frames advance once per video; participants subscribe to the shared stream rather than re-decoding.
• Bounded queues: each participant has a finite queue depth, so a slow consumer cannot grow memory unboundedly; when the queue is full, the decode loop pauses (backpressure).
• Deterministic shutdown: a sentinel object marks end-of-stream; consumers drain remaining frames then exit. Cancellation and error paths use the same sentinel protocol so no worker leaks.
• Failure propagation: a failing participant's exception is collected during join and raised from the indexing run — reproducing the previously-hanging mid-stream failure now raises the participant error.

Validation

• uv run --no-sync python -m pytest -q tests/test_visual_threading.py — 7 passed.
• uv run --no-sync python -m pytest -q tests/test_runner.py tests/test_manifest.py tests/test_generation_manifest.py — passed (reported 27 in the fork PR).
• uv run --no-sync ruff check src/vidxp/capabilities/visual.py tests/test_visual_threading.py — clean.
• Reproduced the mid-stream participant failure that previously deadlocked; it now raises the participant error.
• Rebased onto the original repository's main (c17a884); the working tree is clean and the visual-area tests pass on the rebased base.

Notes

Internal-only performance/reliability change. No public API, storage schema, CLI, or MCP surface changes.