lardon3d/AGENTS.md

Guide des agents Lardon3D

Validation obligatoire

Avant livraison, exécuter réellement :

CC=clang meson setup build --wipe
meson compile -C build -j8
meson test -C build --print-errorlogs
git diff --check

Pour les changements sensibles à la mémoire ou aux durées de vie, ajouter un build ASan/UBSan séparé. Pour toute concurrence, exécuter aussi TSan lorsque disponible. Ne jamais annoncer une vérification non exécutée.

Git et périmètre

• Ne jamais utiliser git add -A.
• Ne jamais ajouter ou modifier scan3d/, notamment scan3d/tri_photos.py.
• Ne faire ni commit ni push depuis le sandbox.
• Préserver les changements existants hors ticket.
• Fournir à la fin la liste exacte des fichiers appartenant au ticket.

Architecture à préserver

• La TUI orchestre les entrées et ncurses ; le métier et le layout restent séparés. Le layout dessine uniquement et ne modifie aucun état.
• ncurses appartient exclusivement au thread principal.
• Toute tâche possède une estimation immuable et une réservation valide avant son exécution. Aucun callback ne démarre sans réservation active.
• Le Resource Governor décide des budgets, slots et lots. Le scheduler applique le FIFO et exécute le contrat ; il ne réinterprète jamais les ressources.
• Les API à durée de vie complexe restent opaques, avec propriété et nettoyage explicites.

Principes non négociables

• La stabilité du système hôte et la réactivité de la TUI passent avant le débit.
• Aucun traitement lourd monolithique : utiliser des séquences adaptatives.
• Budgets, files et buffers doivent être bornés.
• La RAM d'un iGPU partagé appartient au budget RAM système.
• La zram est un filet de sécurité, jamais un budget de travail.
• Publier uniquement des sorties atomiques validées ; effectuer un rollback ciblé sans toucher aux données antérieures.
• Préserver des frontières permettant la reprise après interruption.
• Le viewer reste séparé, lecteur de snapshots validés et non bloquant.

Contraintes de code

• C17, Clang, Meson et ncursesw.
• Aucune variable globale d'état.
• Nettoyer explicitement chaque allocation, descripteur, mutex, condition et thread.
• Ne pas utiliser system() ni popen() dans le code de production.
• Ne laisser aucun TODO, code mort ou dépendance inutile dans un ticket fini.
• Préférer l'évolution minimale aux réécritures de modules validés.

État actuel

• Moteur de tâches FIFO, un worker, pause et annulation coopératives.
• Gouverneur thread-safe avec estimations, budgets et réservations opaques.
• Scheduler relié au gouverneur ; réservation obligatoire avant callback.
• Aucun DAG, aucune priorité, aucun pool de workers.
• L'import asynchrone utilise encore son worker dédié et n'est pas migré vers le scheduler générique.
• Le viewer Vulkan n'est pas commencé.

Prochains tickets recommandés

1. Sélectionner une tâche admissible sans blocage par la tête de file.
2. Introduire le DAG et les dépendances.
3. Persister les tâches et checkpoints de reprise.
4. Orchestrer et mesurer les séquences adaptatives.
5. Ajouter les pools bornés CPU, IO et GPU.
6. Migrer l'import vers le scheduler générique.
7. Ajouter la publication live validée, puis le viewer Vulkan séparé.