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

.github/workflows/music-plan-contract.yml

@@ -0,0 +1,72 @@
+name: MusicPlan Contract
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "schemas/music-plan-v1.schema.json"
+      - "src/music_plan.py"
+      - "src/music_provider.py"
+      - "scripts/music_plan_mutation_probe.py"
+      - "scripts/music_plan_holdout_evaluator.py"
+      - "tests/test_music_plan.py"
+      - "tests/fixtures/music_plan/**"
+      - "docs/music-planning-layer-v1.md"
+      - ".github/workflows/music-plan-contract.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install focused validation dependencies
+        run: python -m pip install 'pytest>=8,<10' 'jsonschema>=4.23,<5'
+      - name: Compile model-free contracts
+        run: python -m py_compile src/music_plan.py src/music_provider.py scripts/music_plan_mutation_probe.py scripts/music_plan_holdout_evaluator.py
+      - name: Run MusicPlan contract tests
+        run: python -m pytest -q tests/test_music_plan.py
+      - name: Run controlled negative mutation probe
+        run: python -m scripts.music_plan_mutation_probe
+      - name: Verify private holdout evaluator protocol
+        run: |
+          python - <<'PY'
+          import json
+          import subprocess
+          import sys
+          from pathlib import Path
+
+          plan = json.loads(Path('tests/fixtures/music_plan/full.json').read_text(encoding='utf-8'))
+          request = {"id": "public-protocol-smoke", "input": {"plan": plan, "expected_valid": True}}
+          r = subprocess.run(
+              [sys.executable, '-m', 'scripts.music_plan_holdout_evaluator'],
+              input=json.dumps(request), text=True, capture_output=True, check=True,
+          )
+          response = json.loads(r.stdout)
+          assert response == {"passed": True}, response
+          print('holdout evaluator protocol OK')
+          PY
+      - name: Verify Draft 2020-12 schema and reference fixtures
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          from jsonschema import Draft202012Validator
+
+          schema_path = Path('schemas/music-plan-v1.schema.json')
+          schema = json.loads(schema_path.read_text(encoding='utf-8'))
+          Draft202012Validator.check_schema(schema)
+          validator = Draft202012Validator(schema)
+          for path in sorted(Path('tests/fixtures/music_plan').glob('*.json')):
+              data = json.loads(path.read_text(encoding='utf-8'))
+              validator.validate(data)
+              print(f'OK {path}')
+          PY

.github/workflows/repository-checkout-ci.yml

@@ -0,0 +1,19 @@
+name: Repository Checkout CI
+
+on:
+  pull_request:
+    paths:
+      - 'GemReward-Service-Repo'
+      - '.gitmodules'
+      - '.github/workflows/repository-checkout-ci.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  checkout:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4

.github/workflows/semantic-prevalidator-ci.yml

@@ -0,0 +1,36 @@
+name: Semantic Prevalidator CI
+
+on:
+  pull_request:
+    paths:
+      - 'src/video_validation/**'
+      - 'tests/test_semantic_prevalidator.py'
+      - '.github/workflows/semantic-prevalidator-ci.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  semantic-prevalidator:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Materialize exact PR commit without git submodule cleanup
+        env:
+          REPOSITORY: ${{ github.repository }}
+          SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          set -euo pipefail
+          curl --fail --location --silent --show-error \
+            "https://codeload.github.com/${REPOSITORY}/tar.gz/${SHA}" \
+            | tar -xz --strip-components=1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install targeted test dependency
+        run: python -m pip install --disable-pip-version-check pytest
+      - name: Compile targeted module
+        run: python -m compileall -q src/video_validation tests/test_semantic_prevalidator.py
+      - name: Run semantic prevalidator tests
+        run: python -m pytest -q tests/test_semantic_prevalidator.py

FUTURE_ROADMAP.md

@@ -90,4 +90,32 @@ A dynamic-residency optimization graduates only if it improves at least one usef
 
 ---
 **Maintained by:** StoryCore-Engine Team  
-**Last Updated:** August 22, 2026
+**Last Updated:** August 22, 2026
+
+## 6. Scientific transfer: structural drawing and physical consistency (2026-09-10)
+
+**Planned.** This work follows existing resource admission and render stability
+gates; it does not enable a new generation workflow.
+
+- [ ] Define a versioned storyboard input carrying strokes, contours, junctions, perspective constraints, coordinate frames, stable identities and provenance.
+- [ ] Reuse Human Skills practice outputs and CogniARC structural critique; distinguish practiced trajectories from fitted reference curves.
+- [ ] Compare unchanged, random-correction and targeted-correction storyboards on held-out compositions with equal action/render budgets.
+- [ ] Measure junction/outline preservation, proportions, camera consistency and identity drift separately from visual style.
+- [ ] Test bounded brush-style controls after structural quality passes, using [Procedural Brush Synthesis](https://users.cg.tuwien.ac.at/zsolnai/gfx/procedural-brush-synthesis-paper/) and [DiffVG](https://people.csail.mit.edu/tzumao/diffvg/) as individually sourced methods.
+- [ ] Add offline physical-consistency fixtures for motion and contact only after numerical reference validation; compare persistent/constant-velocity predictions before introducing a learned predictor.
+
+**First implementation:** a tiny synthetic storyboard fixture and validator for
+strokes, frames and identities, reusing existing project schemas where possible.
+No external assets, model weights or generation services are required for that
+contract experiment.
+
+**Acceptance:** reproducible improvement on reserved compositions, intact
+identities and camera/geometry constraints, recorded failures and measured
+resource use on stated hardware. Reference curve fitting alone is not evidence
+of learned drawing skill; a physically plausible-looking clip is not a physics
+validation.
+
+Physical prerequisite:
+[CogniARC's initial particle-neighbour reference and limits](https://github.com/zedarvates/cogniarc/blob/a4aac4a5f42e546c4a4ad777c508e4a1b0f0f136/experiments/particle_graph/README.md).
+That implementation is separate from StoryCore and is not a calibrated water
+simulator or a generation integration.

addons/official/storycore_asset_creator/COMFYUI_CLIENT.md

@@ -0,0 +1,107 @@
+# Suivi des tâches ComfyUI
+
+Le client Python existant reste le point d'accès HTTP de l'Asset Creator.
+Cette correction n'ajoute aucun service externe, modèle ou abonnement.
+
+## Deux défauts reproduits
+
+Sur le commit `5b6c83bd26f60f7eb5e4da53f958f2d3b06edb4a`, avec des réponses
+simulées et les sockets interdites :
+
+- Une entrée d'historique contenant `status_str="error"`, `completed=false`
+  et des sorties partielles était renvoyée comme un résultat réussi.
+- L'appel HTTP à `/history/{prompt_id}` ne recevait aucun `timeout`.
+  La lecture du client montre la même omission pour les autres appels,
+  sauf `/system_stats`.
+
+## Comportement du client
+
+| Situation | Résultat |
+|---|---|
+| `status.status_str == "success"` et `status.completed is True` | Retourne le dictionnaire `outputs`, même vide. |
+| `status.status_str == "error"` | Lève `RuntimeError`, même avec des fichiers intermédiaires. |
+| Ancien champ `error` au premier niveau | Lève `RuntimeError`. |
+| Historique absent, statut inconnu ou incomplet | Continue le suivi jusqu'à son expiration. |
+| Budget de suivi écoulé | `ComfyUIWaitTimeout`, avec `reason="wait_deadline"`. |
+| `requests.exceptions.Timeout` pendant un GET de suivi | `ComfyUIWaitTimeout`, avec `reason="http_timeout"` et cause conservée. |
+| Autre erreur HTTP ou réseau | Exception Requests transmise à l'appelant. |
+
+`ComfyUIWaitTimeout` hérite de `TimeoutError` et expose `prompt_id`.
+Le client ne supprime pas la tâche, ne l'annule pas et ne la soumet pas à
+nouveau quand le suivi expire. Une expiration ne prouve pas que la tâche a
+échoué ou qu'elle tourne encore ; son état doit être relu sur le serveur.
+
+## Deux délais distincts
+
+- `request_timeout=30.0` : délai Requests appliqué à tous les appels HTTP.
+  Le contrôle de disponibilité garde un plafond de 5 secondes.
+- `wait_for_result(..., timeout=300.0, poll_interval=2.0)` : budget du suivi
+  et intervalle entre lectures. Le budget utilise une horloge monotone.
+  Avant chaque GET, le délai HTTP est limité au budget restant ; les pauses
+  sont également limitées. Le budget est revérifié au retour des GET et
+  après le callback avant de dormir.
+
+Ces trois paramètres doivent être finis et strictement positifs.
+`get_history` et `get_queue_status` acceptent aussi un `timeout` nommé pour
+réduire leur délai HTTP, sans dépasser celui du client.
+
+Le délai Requests concerne la connexion et l'inactivité de lecture. Il
+ne garantit **pas** une durée totale stricte : plusieurs adresses réseau,
+une réponse qui arrive lentement ou un callback bloquant peuvent dépasser
+le budget. Aucun thread n'est abandonné pour simuler une telle garantie.
+Voir la [documentation officielle Requests sur les délais](https://requests.readthedocs.io/en/latest/user/advanced/#timeouts).
+
+## Reprendre le suivi
+
+```python
+from addons.official.storycore_asset_creator.src.comfyui_client import (
+    ComfyUIClient,
+    ComfyUIWaitTimeout,
+)
+
+client = ComfyUIClient.from_project_config(request_timeout=30.0)
+# prompt_id est l'identifiant déjà renvoyé par queue_workflow et sauvegardé.
+try:
+    outputs = client.wait_for_result(prompt_id, timeout=300.0)
+except ComfyUIWaitTimeout as error:
+    prompt_id_a_reprendre = error.prompt_id
+    # Plus tard : client.wait_for_result(prompt_id_a_reprendre, timeout=300.0)
+```
+
+L'appelant doit sauvegarder l'identifiant dès l'acceptation. Cette correction
+ne crée pas de stockage persistant de tâches et ne raccorde pas encore la
+reprise à une interface MCP, CLI ou Blender.
+
+Si le POST `/prompt` expire avant de renvoyer un identifiant, l'acceptation
+reste incertaine. Le client laisse remonter l'exception Requests et n'ajoute
+aucune relance automatique. Il faut vérifier la file du serveur avant de
+décider d'une nouvelle soumission.
+
+Les réponses des téléchargements sont fermées même en cas d'erreur.
+Un téléchargement interrompu peut toujours laisser un fichier partiel :
+la correction ne rend pas l'écriture atomique.
+
+## Contrat et vérification
+
+Contrat lu dans ComfyUI au commit
+[`387f98aa2822f684b8597959a52a467d88cc4806`](https://github.com/Comfy-Org/ComfyUI/commit/387f98aa2822f684b8597959a52a467d88cc4806) :
+[`execution.py`](https://github.com/Comfy-Org/ComfyUI/blob/387f98aa2822f684b8597959a52a467d88cc4806/execution.py#L1316-L1340)
+décrit le statut enregistré ;
+[`main.py`](https://github.com/Comfy-Org/ComfyUI/blob/387f98aa2822f684b8597959a52a467d88cc4806/main.py#L367-L372)
+le renseigne à la fin du traitement. Le client ne déduit pas la réussite
+de la seule présence d'un fichier.
+
+Depuis la racine du dépôt, avec `requests` installé :
+
+```bash
+python -m unittest discover -s tests/asset_creator -p test_comfyui_client.py -v
+```
+
+Les 18 tests utilisent des réponses HTTP simulées et une horloge contrôlée.
+La création de sockets y est interdite. Ils couvrent les statuts terminaux,
+les sorties partielles, les délais, la reprise et les ressources HTTP.
+Vérification locale effectuée avec Python 3.12.14 et Requests 2.34.2.
+
+Il ne s'agit pas d'un test sur un serveur ComfyUI, Blender ou un GPU.
+Les recettes Trellis2 locales, leurs extensions et le format API réellement
+soumis restent à vérifier dans l'environnement d'exécution.

addons/official/storycore_asset_creator/README.md

@@ -51,6 +51,12 @@ Le port ComfyUI **n'est jamais supposé** — il varie selon l'édition install
 3. Variables d'environnement       ← STORYCORE_COMFYUI_HOST / STORYCORE_COMFYUI_PORT
 ```
 
+### Délais et reprise du suivi
+
+Le client distingue le délai HTTP du budget d'attente de la génération.
+Une expiration du suivi conserve l'identifiant du prompt ; elle ne l'annule
+pas. Voir [le contrat du client et les tests](COMFYUI_CLIENT.md).
+
 ### Override via variables d'environnement
 
 ```bash
@@ -91,12 +97,37 @@ workflows/
   trellis2_lowvram.json    ← workflow Low VRAM (recommandé)
   trellis2_standard.json   ← workflow qualité standard
   trellis2_lowpoly.json    ← workflow low poly
-  trellis2_trunk_only.json ← workflow tronc seul (inclus)
+  trellis2_trunk_only.json ← workflow tronc seul (à fournir)
 ```
 
 > Les workflows `PixelArtistry_Trellis2_*.json` de votre dossier `Downloads/3s/`  
 > doivent être copiés ici et renommés selon la convention ci-dessus.
 
+Ces quatre fichiers ne sont pas inclus dans l'arbre du dépôt examiné pour cette
+correction. Un nom de preset déclaré ne garantit pas qu'une recette est installée.
+
+Le pipeline prépare désormais la recette **avant tout appel client et tout upload**.
+Une image source absente, un preset inconnu, un fichier JSON absent ou illisible,
+une structure d'éditeur incompatible ou un nœud d'image non modifiable provoquent
+une erreur locale. Un preset inconnu ne sélectionne plus silencieusement `lowvram`.
+Le template préparé est conservé en mémoire ; après upload, seul son nom d'image
+est remplacé par celui renvoyé par ComfyUI, sans relecture de la recette sur disque.
+
+**Portée de cette validation :** le chargeur manipule encore les champs d'éditeur
+`nodes` / `widgets_values`. Cette correction ne convertit pas le template au format
+API de `/prompt` et ne prouve pas que le graphe est exécutable. La conversion, la
+disponibilité des nœuds/modèles, les délais HTTP et un essai réel restent à vérifier
+à partir des workflows effectivement utilisés dans Asset Factory / ComfyUI.
+
+Tests locaux sur recettes synthétiques, depuis la racine du dépôt :
+
+```bash
+python -m unittest discover -s tests/asset_creator -v
+```
+
+Ils ne nécessitent ni Blender, ni serveur ComfyUI, ni GPU. Voir leur
+[portée précise](../../../tests/asset_creator/README.md).
+
 ### 3. Installation de l'addon
 
 ```
@@ -181,7 +212,7 @@ storycore_asset_creator/
     ├── trellis2_lowvram.json      ← Workflow ComfyUI (à copier)
     ├── trellis2_standard.json     ← Workflow ComfyUI (à copier)
     ├── trellis2_lowpoly.json      ← Workflow ComfyUI (à copier)
-    └── trellis2_trunk_only.json   ← Workflow tronc seul (placeholder inclus)
+    └── trellis2_trunk_only.json   ← Workflow tronc seul (à copier)
 ```
 
 ---