feat(video-routing): route real shot specs across direct/parallel/sequential

[zedarvates]

Summary

Implements the deterministic multi-subject routing core tracked in #40 and connects it to StoryCore-style shot specifications without coupling the project to any video model.

Routing core

• DIRECT, PARALLEL, and SEQUENTIAL generation strategies;
• deterministic inputs for subject count, interaction/contact, occlusion, identity criticality, camera motion, temporal dependency, and compute budget;
• strong contact/interaction/occlusion routes to staged sequential generation;
• independent identity-critical subjects can route to parallel generation/composition;
• simple or severely compute-constrained scenes retain the direct baseline;
• route decisions include confidence, reasons, and intermediate-validation requirements.

Shot-spec adapter

• accepts dicts or existing dataclass-like StoryCore shot objects;
• subject count can come from subject_count, characters_present, subjects, an explicit subject list, or routing metadata;
• reads optional metadata.multi_subject_routing without changing the current core Shot dataclass;
• deterministically maps common camera-movement text (pan/tracking/orbit/handheld/etc.) to bounded intensity;
• orchestration can provide explicit overrides when scene context knows interaction/occlusion information;
• unknown subject count, invalid scores, or non-boolean contact metadata fail closed rather than silently defaulting to a cheap strategy.

Tests

Covers DIRECT/PARALLEL/SEQUENTIAL boundaries, camera-motion normalization, metadata overrides, fail-closed subject counting, score validation, and ambiguous contact metadata.

Boundary

This PR chooses generation topology only. It does not render/composite media and cannot bypass semantic, structural or temporal validators. Parallel and sequential paths explicitly require intermediate validation.

Validation status

StoryCore currently has no general Python PR workflow; its GitHub Action is path-limited to apps/storycore-harbour/**. Keep this PR draft until the targeted Python tests are run locally/self-hosted. No new hosted GitHub workflow is added here.

Next step

Run:
pytest -q tests/test_multi_subject_router.py tests/test_shot_spec_router_adapter.py

Then benchmark three fixed multi-subject fixtures against the DIRECT baseline using reproducible manifests.

Tracks #40.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud