feat(video-validation): add lightweight semantic pre-validator contract

[zedarvates]

Summary

Implements the provider-agnostic semantic gate tracked in #41, without bundling ViCLIP weights or adding a hard dependency:

• VideoTextScorer protocol for ViCLIP-like backends;
• SemanticPrevalidator with PASS / ESCALATE / UNCERTAIN;
• fail-safe handling for missing clips, empty specs, provider failures, invalid and non-finite scores;
• content-hash semantic-score cache keyed by shot spec + clip bytes;
• external defect signals reuse the cached semantic score and recompute only the verdict, avoiding redundant video encoding/GPU work;
• force_refresh=True explicitly bypasses the semantic cache;
• external defect signals force escalation even when semantic similarity is high;
• tests cover thresholds, cache hits, force refresh, provider errors, non-finite scores and defect escalation.

Safety/quality boundary

A semantic PASS is not a final render approval. Structural, identity, temporal and safety validators can still reject/escalate the clip. This module only decides whether a heavy semantic VLM call can potentially be skipped.

Validation status

StoryCore has no general Python PR workflow; its only GitHub workflow is scoped to apps/storycore-harbour/**. Keep this PR draft until targeted local/self-hosted tests are run. No hosted workflow is added here.

Targeted command:

pytest -q tests/test_semantic_prevalidator.py

Next step

Add an optional ViCLIP-L/14 provider in an environment where the model/runtime is available, then benchmark heavy-VLM calls avoided vs false-PASS rate on the fixed StoryCore clip set.

Tracks #41.

[zedarvates]

Diagnostic SonarQube Cloud — 2026-08-30

The previous bot comment reporting “The last analysis has failed” is stale relative to the exact current PR head 49f2140c39f64614ce241bfce814400053e72293.

GitHub check SonarCloud Code Analysis for this exact head completed successfully:

• conclusion: success
• Quality Gate: passed
• new issues: 0
• accepted issues: 0
• security hotspots: 0
• annotations: 0

No functional code or Sonar configuration change is required from this incident. Keep the PR draft until its separate targeted/self-hosted validation gate is completed. No merge is authorized by this note.

[zedarvates]

Targeted semantic-prevalidator gate — passed

A dedicated public GitHub Actions gate now validates this PR without using the personal/self-hosted runner.

Evidence:

• workflow: Semantic Prevalidator CI
• run: 33540324378
• Python: 3.12
• targeted compile: passed
• python -m pytest -q tests/test_semantic_prevalidator.py: passed
• no secrets and contents: read only

During setup, actions/checkout@v4 exposed an unrelated repository-structure problem: GemReward-Service-Repo is treated as a submodule path but has no matching URL in .gitmodules, causing checkout cleanup to exit 128. The retained workflow avoids that unrelated failure by materializing the exact PR commit without git-submodule cleanup.

The one-shot proof workflow used during diagnosis has been removed. Keep PR #42 draft; this records the targeted Python validation only and does not authorize merge.

[sonarqubecloud]

Quality Gate passed

Issues
0 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

[zedarvates]

Validation ciblée exécutée sur le head exact 1a01b01dd0f4c4c7fafd1440fe3eb86fc48bf109.

Preuves :

• GitHub Actions Semantic Prevalidator CI run 33540403086: python -m pytest -q tests/test_semantic_prevalidator.py → 10 passed in 0.06s.
• Exécution locale indépendante, reconstruite à partir des fichiers exacts de la PR sans accès réseau : python3 -m pytest -q tests/test_semantic_prevalidator.py → 10 passed in 0.09s.
• Compilation ciblée également verte dans le run CI (python -m compileall -q src/video_validation tests/test_semantic_prevalidator.py).

Aucun défaut fonctionnel n'a été révélé par le test ciblé ; aucune correction de code n'est donc justifiée. La frontière reste inchangée : un PASS sémantique n'est pas une approbation finale du rendu et n'écrase pas les validateurs structurels, identité, temporels ou sécurité.