PD-284 — Agent Developer — Module seal-event-processor¶

1. Module livré¶

2. Architecture¶

2.1 Vue d'ensemble¶

Le SealEventProcessor est le point d'entrée unique pour traiter les événements SSE bruts avant application au store Zustand (C5). Il implémente le pipeline de traitement décrit au §2.3 du plan :

Événement SSE brut
  │
  ├─ seal_id ≠ actif → ignorer + telemetry
  ├─ event_id déjà vu (cache FIFO 100) → ignorer silencieusement
  ├─ Validation Zod payload → ignorer + toast 5s + telemetry
  ├─ sequence_number gap → fenêtre grâce 200ms → resync GET
  ├─ Transition non autorisée → ignorer + toast 5s + telemetry
  └─ OK → callback onEventApplied → store update

2.2 Composants internes¶

EventDeduplicationCache¶

Ring buffer FIFO de taille N=100 pour les event_id. Politique d'éviction : les event_id les plus anciens sont éjectés en premier (FIFO strict, pas LRU — invariant contract).

• checkAndAdd(eventId) : retourne true si doublon, false sinon (et ajoute)
• Recherche linéaire O(N=100) — acceptable pour la taille du cache
• Écriture en index modulo circulaire

SealEventProcessor¶

Classe principale avec lifecycle management :

• Construction : reçoit activeSealId, initialState, callbacks, et optionnellement un config partiel
• processRawEvent(rawPayload) : point d'entrée principal, retourne un ProcessEventResult discriminé
• resyncFromServer(state, sequence) : recalibrage après GET /status en cas de gap
• dispose() : nettoyage des timers et ressources

3. Invariants respectés¶

Interdits respectés (forbidden)¶

4. Schemas Zod¶

Chaque état SSE (§5.12) a un schema dédié qui étend le schema de base :

Tous les champs utilisent les regex de validation de SEAL_VALIDATION_PATTERNS (§5.6).

5. Gestion des erreurs¶

6. Fenêtre de grâce — Comportement détaillé¶

1. Événement reçu avec sequence_number > lastApplied + 1 : l'événement est bufferisé dans pendingEvents
2. Si aucun timer actif : démarrage du timer graceWindowMs (défaut 200ms, configurable §5.8)
3. Si l'événement manquant arrive avant expiration : flush de tous les événements en ordre
4. Si le timer expire avec gap toujours présent :
5. Log logSequenceGap()
6. Appel callbacks.onResyncRequired(sealId)
7. Vidage de pendingEvents (le resync recalibrera l'état complet)

Le timer utilise performance.now() (pas Date.now()) conformément à l'interdit du code contract.

7. Resync serveur¶

Après un GET /seals/{id}/status de resynchronisation, l'orchestrateur (C7) appelle resyncFromServer(serverState, serverSequence) :

• Recale l'état interne du processor
• Remet à zéro le compteur de séquence
• Vide les événements bufferisés (la réponse GET fait foi)
• Annule tout timer de grâce actif

8. Matrice de couverture des tests¶

9. Décisions architecturales¶

architectural_decisions:
  - decision: "Ring buffer tableau fixe pour cache FIFO event_id"
    rationale: "Array pré-alloué avec index modulo — O(1) écriture, O(N) lookup. N=100 rend le lookup négligeable vs overhead Map/Set."
    alternatives_considered:
      - "Set avec delete du plus ancien (nécessite tracking ordre — overhead)"
      - "Map avec compteur (surconsommation mémoire pour 100 entrées)"
    trade_offs: "Lookup linéaire O(100) acceptable pour la taille. Pas de hashmap overhead."

  - decision: "ProcessEventResult union discriminée plutôt qu'exceptions"
    rationale: "Le traitement d'événements SSE ne doit jamais crasher. Retourner un résultat typé permet au caller de réagir sans try/catch."
    alternatives_considered:
      - "Throw + catch par le caller (risque de crash si oubli)"
      - "Callback pour chaque cas (API verbeuse)"
    trade_offs: "Le caller doit inspecter le résultat mais ne risque pas de crash non géré."

10. Hypothèses¶

11. Dépendances non implémentées (stubs inter-PD)¶

Aucun stub inter-PD dans ce module. Toutes les dépendances sont intra-PD-284 : - C1 (types/seal.ts) : implémenté - C2 (state-machine.ts) : implémenté - C13 (telemetry.ts) : implémenté - zod : dépendance npm installée

12. Fichiers modifiés¶