lardon3d/docs/architecture/task_system.md

# Système de tâches (Task System)

## Extraction précise v1A

`features.extract.sift` et `features.extract.rootsift`, version 1, possèdent
chacun leur lifecycle durable. Une tâche correspond à une image, est persistée
avant enqueue et reprend avec le même `task_id`. `detectAndCompute` n'est pas
interruptible : pause/cancel sont coopératifs à ses frontières et un crash
recommence uniquement cette image. ORB READY n'est jamais recalculé par SIFT.

## Objectif et responsabilités

Le module `task` gère le cycle de vie complet des tâches de traitement dans
Lardon3D. Il définit les états, la progression, la pause coopérative,
l'annulation et les callbacks associés à chaque tâche.

Chaque tâche représente une unité de travail atomique : estimation des
coûts, exécution sous réservation et publication d'un résultat validé.

## Fichiers

- `include/lardon3d/task.h` — types publics et API
- `src/task.c` — implémentation

## Types principaux

Les états réels sont `TASK_PENDING`, `TASK_RUNNING`, `TASK_PAUSED`,
`TASK_CANCELLED`, `TASK_FAILED` et `TASK_COMPLETED`. Une rupture de séquence est
une opération de réadmission, pas un état supplémentaire.

## API publique

| Fonction | Description |
|---|---|
| `lardon3d_task_create()` | Alloue une tâche et copie son estimation |
| `lardon3d_task_destroy()` | Annule, attend puis libère la tâche |
| `lardon3d_task_start()` | Exécute sous réservation active |
| `lardon3d_task_pause()` / `resume()` | Contrôle la pause coopérative |
| `lardon3d_task_request_cancel()` | Demande l'annulation coopérative |
| `lardon3d_task_checkpoint()` | Frontière coopérative en mémoire |
| `lardon3d_task_sequence_break()` | Libère puis renouvelle la réservation |
| `lardon3d_task_snapshot()` | Copie l'état d'observation runtime |

### API durable

| Fonction | Description |
|---|---|
| `lardon3d_task_durable_snapshot()` | Copie les champs durables sous mutex |
| `lardon3d_task_restore()` | Reconstruit une tâche sans état d'exécution vivant |
| `lardon3d_task_create_typed()` | Crée une tâche persistable avec kind/version immuables |
| `lardon3d_task_restore_typed()` | Restaure une tâche typée et transfère l'ownership du userdata |
| `lardon3d_task_checkpoint_save()` | Publie atomiquement un snapshot v1 |
| `lardon3d_task_checkpoint_load()` | Lit et valide un checkpoint borné |
| `lardon3d_task_checkpoint_stage()` / `promote_staged()` | Publie d'abord `<path>.next`, puis promeut sous le verrou par tâche |

Après `rename`, un échec du `fsync` du répertoire retourne
`LARDON3D_TASK_CHECKPOINT_PUBLISHED_NOT_DURABLE` : la publication est visible,
mais sa durabilité après crash n'est pas confirmée.

### Publication et reprise projet

Le protocole générique par tâche emploie le chemin canonique
`.lardon3d/checkpoints/<task_id>.chk`, sa représentation staged `.chk.next` et
le verrou consultatif `.chk.lock`. Le verrou sérialise un writer et la reprise
sur le slot staged fixe ; il est détenu pour la séquence entière et sa fermeture
par le noyau après crash ne constitue pas un état durable.

L'ordre de publication est strictement : codec durable de `.next`, commit
SQLite du résumé de tâche et de la référence checkpoint, puis promotion de
`.next` vers le fichier canonique et durabilité du répertoire. DB et système de
fichiers ne forment pas une transaction unique : si la promotion échoue ou sa
durabilité est incertaine après le commit SQLite, `.next` reste la
représentation de récupération possible.

La reprise acquiert d'abord `.lock`, puis recharge la ligne SQLite : la page de
découverte peut être devenue périmée pendant l'attente. Elle valide le codec et
la version du canonique et compare seulement les champs effectivement stockés
dans le résumé DB — `task_id`, nom, états saved/recovery, progression et
compteur de séquences. Les timestamps et l'estimation complète ne sont pas
dupliqués par la DB et ne participent donc pas à ce test. Un canonique valide
dont ce résumé correspond est prioritaire ; une `.next` absente, périmée ou
corrompue est alors ignorée. Sinon, une `.next` valide qui correspond au même
résumé est promue sous le même verrou puis reprise. Un ancien projet v22 qui ne
possède que `.chk` reste ainsi récupérable. Toute autre absence, version non
supportée, corruption ou divergence interdit la reprise de cette tâche sans
affecter les autres entrées de l'inventaire.

## Invariants

1. **Estimation durable immuable** : l'estimation stockée dans la Task courante
   ne change jamais. Compute Governor v2 utilise une enveloppe privée de
   capacités, distincte de ce snapshot et non persistée comme identité. Le
   contrat choisi pour une séquence est lui aussi immutable jusqu'à sa
   libération ; seule une séquence suivante peut être adaptée.
2. **Transitions d'état validées** : le cycle nominal est
   `PENDING → RUNNING → COMPLETED/FAILED/CANCELLED`, avec pause coopérative.
3. **Pause et annulation coopératives** : le callback appelle périodiquement
   `lardon3d_task_checkpoint()`. Aucun autre thread ne force son arrêt.
4. **Progression bornée** : la progression ne peut jamais dépasser la valeur
   maximale définie par l'estimation.
5. **Reprise réadmise** : une tâche restaurée non terminale repasse par la file,
   le scheduler et le Resource Governor avec une nouvelle réservation.
6. **Snapshot court** : seuls les champs durables sont copiés sous le mutex ;
   la sérialisation et les I/O ont lieu après déverrouillage.

## Interactions

- **task_queue** : la file gère l'ordre d'exécution et invoque les callbacks.
- **resource_governor** : l'estimation est utilisée pour la réservation avant
  exécution.
- **scheduler** : ses responsabilités restent représentées par le runtime et
  l'unique Queue existants ; aucun second scheduler n'est introduit.

### Frontière Compute Governor v2

**COMPUTE_GOVERNOR_V2 — PASS / FROZEN.** Chaque kind de production
reste propriétaire d'une Task et passe par l'unique Queue à un worker, puis par
l'unique Resource Governor, même lorsque CPU, lot, mémoire, I/O et GPU sont
tous fixes. Une dimension fixe n'autorise jamais à contourner l'admission.

Le code conserve une `Lardon3DResourceEstimate` canonique immutable pour la
durabilité. Derrière les types opaques, chaque Task possède désormais une
enveloppe privée bornée : par défaut une capacité fixe exactement égale à cette
estimation ; seuls les kinds possédant des alternatives réelles en ajoutent.
Queue et `sequence_break()` demandent au Governor de choisir et réserver une
capacité depuis un seul snapshot courant. L'exécution reçoit ce contrat
immutable et ne le renégocie pas en cours de séquence. Cette couture n'étend ni
le descriptor public du Task Kind Registry, ni le checkpoint, ni le payload
Project DB et n'ajoute aucune dimension d'identité scientifique.

Le Governor possède aussi la politique CPU hôte privée. Depuis le masque
permis et la topologie package/core, il dérive un compute-pool par coeurs
physiques complets ; un caller déjà précontraint fournit directement son pool.
Sans topologie exploitable, le budget portable subsiste avec affinité inactive.
Seul le worker lourd de Queue applique et vérifie son propre masque (`pid=0`)
avant les callbacks, donc le creator/main/TUI reste libre. Le Governor ne mute
jamais un TID auxiliaire énuméré : un `PIDFD_THREAD` ne stabilise pas le numéro
TID consommé par `sched_setaffinity(tid)`. Le démarrage établit plutôt
`MESA_SHADER_CACHE_DISABLE=true` avant tout pthread applicatif et toute
initialisation Vulkan. Une absence prend ce défaut sûr ; `true`/`1` explicites
sont conservés, tandis qu'une valeur explicite fausse ou malformée est respectée
mais entraîne un refus de démarrage. Cette politique opérationnelle, sans état
Task durable ni identité scientifique, supprime les helpers de cache Mesa
observés qui élargissaient leur masque. Il n'existe plus de sweep post-init,
latch de Task ou retry de recontrainte auxiliaire ; les diagnostics indiquent
l'état et la raison de la politique sans prétendre une activité auxiliaire.
Le nombre du pool borne toute admission CPU. Cette couture
n'ajoute ni scheduler, ni worker, ni champ durable ou ABI publique.

Le comportement de production normal ORB est `AUTO` Governor-owned. Les modes
CPU/Vulkan explicites sont réservés au debug, benchmark et à la
reproductibilité. Une Task normale nouvelle persiste une classe `MIXED`
sémantiquement honnête ; cette signature reconstruit AUTO, tandis que toute
signature CPU ORB ancienne ou courante reconstruit un CPU fixe et que Vulkan
reste fixe. Création et reprise n'initialisent pas Vulkan sur le caller ; le
premier begin appartient au worker Queue contraint. Le choix matériel ne
devient ni payload ni identité. Seule une reprise AUTO établit la disponibilité
Vulkan partagée ; les reprises fixes et historiques sont sans effet global,
donc leur ordre ne dégrade pas AUTO. Une panne backend est publiée avant tout
fallback ou sortie précoce ; une inéligibilité de paire reste locale et ne
possède aucun handle à terminer. Le Governor conserve une télémétrie fixe et
bornée par kind/backend (dernière durée, travail durable, débit, backend
sélectionné/réel, contrat, pression et raison) et aucune grande histoire
persistante. L'adaptation générique utilise deux observations de référence et
deux du palier d'essai. Le lot ORB Vulkan, plus bruité, exige huit séquences
pures consécutives pour chacune de ces fenêtres avant toute décision ; une
observation Matcher mesure la cadence de bout en bout depuis la réadmission
réussie jusqu'au checkpoint générique durable, et non le seul callback de
calcul. Le temps de calcul seul reste diagnostique. Ainsi le Governor apprend
le coût de séquence amorti par le lot et un checkpoint échoué ne l'entraîne pas.
Une
admission adaptative encore permise sous pression installe
CPU1, lot minimum et inflight minimum avant sa réservation. Inflight ORB normal
reste fixé à 1; helpers reste 0. Les callbacks atomiques n'annoncent
un item que si extraction et publication propre sont durables ; READY,
`ALREADY_PRESENT` et `PUBLISHED_NOT_DURABLE` sont des observations zéro qui
n'avancent pas la rampe.
L'A/B forcé ABBA a mesuré seulement +2,077617 % à depth 2
(54,661652238 contre 55,797311953 paires/s), sous le deadband 5 %, avec digest identique,
quatre séquences de fallback local par exécution et zéro panne/discard. Depth 2 est donc
**REJECTED_WITH_MEASURED_REASON** pour AUTO normal. Compute Governor v2 reste
en cours jusqu'aux réconciliations restantes.

Pour Matcher Vulkan, le lease privé de capacité matérialise le contrat de la
séquence seulement après son admission. Il alloue un ou deux payloads de
640 Kio sans requête pending, les conserve jusqu'au nettoyage complet de la
séquence, puis rend depth 2 à depth 1 avant `sequence_break()`. Une allocation
depth 2 échouée ne modifie pas le contrat scientifique et conduit à la paire CPU
complète; elle ne laisse ni réservation suivante sous-facturée, ni résultat
Vulkan partiel.

Cette boucle est maintenant `observe → choose → execute → measure → adapt next`.
Les CPU réductibles progressent uniquement par `1/2/4/8/12`, bornés par le
compute-pool ; CPU et lot ne sont jamais essayés ensemble. Les observations
hôte privées comprennent utilisation du pool, mémoire/PSI/swap actif, GPU busy
et RSS observé, sans confondre RSS et réservation. Le dernier diagnostic peut
être tiré par numéro de série ou formaté dans un buffer borné ; le runtime ne
l'imprime pas directement dans le TUI. Le contrat déjà installé demeure
immutable même si une nouvelle observation arrive pendant son exécution.
Un agrégat privé de taille fixe complète ce dernier diagnostic : il compte les
admissions et séquences effectivement enregistrées et somme leurs métriques en
saturant, afin qu'un poller lent ne transforme pas des changements coalescés en
fausse histoire exhaustive. Il vit uniquement avec le Governor courant.
Pour la matrice forcée du runner, cet agrégat sépare les fallbacks par
inéligibilité locale, panne backend et raison autre/inconnue, à la fois par
séquence diagnostique et par item exact. Le compte d'items avance une seule fois
après la publication durable du fallback CPU complet; le travail d'une
séquence sélectionnée CPU reste à zéro. Ce commit opérationnel immédiat survit à
l'échec ou l'annulation d'une paire suivante, mais ne crée ni séquence réussie,
ni débit durable, ni adaptation. Un high-water mark non persisté le rend
idempotent pendant la vie de la Task. La Task n'expose alors qu'une capacité
Vulkan aux batch/depth demandés : absence de GPU/backend/mémoire ne peut donc
pas devenir une admission CPU. Une panne backend tardive laisse la publication
CPU complète déjà durable mais fait échouer la Task de benchmark après
checkpoint; seul le compte d'items localement inéligibles, égal entre cohortes
comparées même lorsque leur batch diffère, reste admissible pour l'évidence.
Les anciens logs batch 2/4, à quatre contre trois séquences locales pour les
mêmes items/digest, sont préliminaires et ne déterminent aucun débit utile. La
matrice item-valide suivante mesure batch 2/4/8/12 à
54,180767704/66,094373197/74,784998723/76,755814095 paires/s. Les deux premiers
gains de palier dépassent le deadband, celui de 8 à 12 vaut seulement
+2,635308425 % : AUTO normal s'arrête à batch 8 et batch 12 reste un contrôle
privé sûr rejeté pour la politique normale.
Le run sans override `short-auto-batch8-governor-v2.stdout.jsonl` valide ensuite
la Task réelle : `1 → 2 → 4 → 8`, 4113/4113 résultats, 76,072 paires/s, digest
identique, six items locaux et aucune panne/discard. La cadence de séquence
inclut réadmission et checkpoint durable; inflight reste 1 et helpers 0.
Le run S21 final crée ensuite la Task normale 2831 en mode AUTO, sans option
backend/lot/inflight. Ses 21 630 admissions sont toutes Vulkan; la Task publie
172 741/172 741 résultats, termine `COMPLETE` à 100 %, avec zéro doublon et
curseur complet. La seule admission YELLOW produit un contrat batch 1, puis
les admissions GREEN suivantes remontent de façon bornée jusqu'à batch 8. Le
contrat actif n'est jamais muté sous le callback : chaque changement appartient
à la séquence suivante.

Le runner d'évidence réel crée les nouvelles Tasks Matcher normales par l'API
AUTO. Son contrôle `synchronous` est un flag de contexte compilé seulement dans
le target benchmark/test : il ne modifie ni Task durable, ni envelope, ni
contrat installé, ni callback de production. Puisque ce flag n'est pas
checkpointé, le runner refuse expressément de l'appliquer à une reprise Matcher
pendante. Le chemin rolling/recovery normal reste inchangé.

Dans ce même target seulement, `--matcher-inflight 1|2` reconstruit avant la
création d'une Task neuve une enveloppe AUTO Vulkan à profondeur fixe et batch
2 par défaut. `--matcher-batch 2|4|8|12`, valable seulement avec inflight et
rolling AUTO, fixe aussi le lot. Ces contrôles ne remplacent pas le Governor : l'admission, la mémoire
par slot, l'UMA et la réservation de séquence restent identiques. Le contrôle
est refusé pour les modes explicites, pour synchronous depth 2 et pour une Task
pendante. Une garde de processus restaure les tokens privés sur toute sortie;
aucun token, champ de contexte, payload ou comportement correspondant n'est
compilé dans `lardon3d`.

## Statut

**IMPLEMENTED** — cycle de vie, pause/annulation coopératives, séquences
adaptatives et fondation de checkpoints persistants isolés.

**IMPLEMENTED** — une registry statique peut reconstruire explicitement le
callback et le userdata d'un kind connu. Le destructeur du userdata est détenu
par la tâche restaurée et exécuté après arrêt de son exécution.

**IMPLEMENTED** — `import.images` utilise la pause, l'annulation, les ruptures
de séquence et les checkpoints génériques ; une tâche restaurée conserve son ID
lors de sa soumission explicite à la file.

**IMPLEMENTED** — resoumission automatique sélective des tâches production à
l'ouverture du projet.

**NOT_YET_WIRED** — autosave générique et dépendances entre tâches.

**IMPLEMENTED** — `visual_index.update` traite jusqu'à seize Feature Sets par
séquence, checkpoint après commit de segment et repasse par le Governor.

**IMPLEMENTED** — `candidate_pair.generate` traite jusqu'à soixante-quatre
Feature Sets par séquence, interroge le Visual Index, persiste les paires
candidates avec idempotence, checkpoint après chaque lot et repasse par le
Governor via `sequence_break`. La reprise est idempotente avec le curseur
`after_feature_set_id` rechargé depuis la DB.

**PASS / FROZEN — Compute Governor v2.** `matcher.run` traite une
Candidate Pair atomique à la fois, par lots opérationnels bornés jusqu'à 12.
Le code courant consomme honnêtement CPU, lot et GPU du contrat choisi. Feature,
SIFT et RootSIFT appliquent l'admission OpenCV `1..12`; RAW et Photo Quality
restent CPU1. Pour ORB normal, le Governor choisit GPU-first ou CPU complet pour la prochaine
séquence, sans mutation pendant son exécution. Ces dimensions ne changent ni
identité scientifique ni publication. Le callback persiste le curseur
`after_candidate_pair_id`, checkpoint après publication de chaque lot et
effectue une rupture de séquence avant le suivant. Une paire repassée après un
crash est réutilisée par son Match Result. La soumission Vulkan rolling est
privée et request-bound; le contrat normal de séquence fige inflight 1. Deux slots
maximum restent disponibles à la couture privée de sûreté/benchmark et portent
chacun command/fence/buffers/query et un handle exact tandis
que device/pipeline/layout/cache restent partagés. Le propriétaire soumet
jusqu'à la profondeur admise, finit le plus ancien et publie toujours le
préfixe canonique contigu; toute sortie, annulation ou exception nettoie les
handles encore privés. Les buffers du second slot ne sont mappés que pendant
une séquence depth 2 admise et sont libérés avant la rupture suivante. Helpers
reste 0 et le contrôle synchrone force depth 1.

**IMPLEMENTED** — `geometric_verifier.run` v1 traite un Match Result atomique à
la fois, par lots adaptatifs de 1, 2, 4 ou 8. Project DB v13 conserve sa
configuration scientifique et `after_match_result_id`. Chaque résultat est
publié avant le curseur ; pause, annulation, checkpoint et rupture de séquence
restent coopératifs aux frontières des parents et des lots.

**IMPLEMENTED** — `track_builder.run` v1 est une tâche durable de rebuild
complet. Le scope GVR est persistant et immuable ; la reprise rejoue depuis le
début avant publication et l'exact reuse Gate C absorbe un crash post-publication.
Pause et annulation sont observées avant/after l'unité Gate B non préemptible.

**PASS / FROZEN** — `acquisition_campaign.run` v1 est une
tâche durable reconstruite par la registry existante à partir de son Task ID et
de sa requête typée immuable Project DB v20. Elle matérialise un seul groupe
S3-E par séquence, vérifie pause/annulation aux frontières de groupe, retient
transactionnellement Capture et curseur avant progression/checkpoint, puis
appelle `sequence_break` avant le groupe suivant. Sa reprise passe par la Queue
et le Resource Governor existants ; aucune boucle d'exécution parallèle n'est
introduite.

**PASS / FROZEN** — le callback `photo_quality.triage` v1 réutilise ce
même Task/Queue/Resource Governor et une `sequence_break` entre groupes. Sa requête typée
est immuable ; le `next_group_id` canonique commence à 1, avance à `k+1` après le résultat
`k`, puis vaut `N+1` à terminaison. Résultat et curseur sont durables avant le checkpoint
générique, de sorte qu'une reprise ne devine ni ne réanalyse une identité déjà publiée. La
réservation charge le contexte retenu et 20 MiB de travail par groupe ; le
JPEG au-dessus de la limite opérationnelle de décodage 8192 pixels reste en attente
`UNAVAILABLE + SUSPECT` (ni erreur de décodage ni rejet) ; une entrée admise est réduite à
1024 pixels maximum avant analyse. Cette borne ne limite ni la campagne ni le dataset.

Le chemin de production de l'import ne possède plus de thread ni de drapeau
d'annulation privés. Son wrapper TUI ne fait qu'enqueue/cancel/observer la
tâche générique. Chaque callback traite un lot borné, checkpoint hors mutex de
tâche, puis effectue une rupture de séquence afin d'obtenir un nouveau contrat
et une nouvelle réservation.

Le callback terminal optionnel est notifié exactement une fois pour
`COMPLETED`, `FAILED` ou `CANCELLED`, jamais pour une pause ou une rupture de
séquence. L'état est fixé sous mutex, puis la réservation terminale est libérée
avant l'appel hors mutex. `join()` attend la fin du callback ; le userdata reste
donc valide pendant celui-ci et son destructeur n'est appelé qu'ensuite par la
destruction de la tâche.

Une tâche reconstruite mais refusée avant transfert à la queue est abandonnée
localement : son userdata est détruit, sans callback terminal ni écriture
durable d'une fausse annulation. Une annulation explicitement demandée conserve
le contrat de notification terminale.

La Project Database v7 peut enregistrer transactionnellement un résumé
`Lardon3DTaskDurableSnapshot` et la référence de son checkpoint. Elle ne stocke
ni estimation sérialisée complète, ni callback, ni réservation, et ne remplace
pas la validation du fichier checkpoint avant `task_restore()`.

`lardon3d_project_checkpoint_task()` est la frontière runtime : elle capture le
snapshot, stage le fichier hors mutex de tâche, met à jour la DB, puis promeut
le fichier canonique sous le verrou par tâche. L'API d'inventaire retourne des
snapshots dont le codec/version et le résumé DB ont été validés, mais ne peut
appeler `task_restore()` que via un descriptor connu ; aucun pointeur n'est
persistant.

## Limites

- Aucune priorité interne : l'ordre est uniquement FIFO.
- Pas encore de DAG pour ordonner des reprises interdépendantes.
- Aucune dépendance inter-tâches (pas de DAG).
- Pas encore de références d'artefacts métier validés.