PD-103 — Agent Developer — Module capture-purge (M7)¶

1. Identification¶

2. Responsabilite du module¶

Le module capture-purge (M7) gere la purge des artefacts temporaires sensibles du flux de capture probatoire :

1. purgeStale() au demarrage de chaque flux capture (INV-103-07, CA-103-12)
2. Suppression locale post-UPLOADED immediatement apres ACK backend (INV-103-38, CA-103-27, §5.3)
3. Watchdog TTL differe detection des captures UPLOAD_DEFERRED expirees (INV-103-38, §5.3)
4. Purge sur annulation nettoyage local sur CANCELLED (INV-103-29)

3. Implementation¶

3.1 Classe CapturePurgeManager¶

Gestionnaire singleton instancie par l'orchestrateur (M6). Suit le pattern etabli par src/export/temp-file-manager.ts (PD-283).

API publique :

3.2 Registre persistant (crash recovery)¶

• Cle AsyncStorage : @probatiovault_capture_registry
• Repertoire dedie : {documentDirectory}/ProbatioVault/capture-temp/
• Persistance a chaque mutation du registre (best-effort)
• Chargement au purgeStale() pour recoverer apres crash
• Scan d'orphelins sur disque pour fichiers non enregistres

3.3 Strategie de purge¶

3.4 Design decisions¶

Le module ne mute PAS la FSM directement. checkDeferredTtl() est un check pur : il retourne les captures expirees et laisse l'orchestrateur (M6) gerer la transition UPLOAD_DEFERRED -> CANCELLED puis appeler purgeCancelled(). Cette separation respecte le principe de responsabilite unique.

4. Mapping invariants¶

5. Matrice de couverture tests¶

Total : 21 tests, 21 passed.

6. Couverture¶

Lignes non couvertes : constructeur CapturePurgeError (error class rarement instanciee directement), catch interne _persistRegistry et _scanOrphans (branches d'erreur best-effort).

7. Qualite¶

8. Hypotheses¶

9. Architectural decisions¶

architectural_decisions:
  - decision: "Registre AsyncStorage plutot que fichier JSON"
    rationale: "Pattern prouve par TempFileManager (PD-283), survit aux crashes, simple a tester"
    alternatives_considered:
      - "Fichier JSON dans capture-temp/"
      - "SQLite local"
    trade_offs: "AsyncStorage est limité en taille (~6MB) mais largement suffisant pour un registre de metadata"

  - decision: "checkDeferredTtl retourne les IDs sans muter la FSM"
    rationale: "Separation des responsabilites : M7 gere le filesystem, M1 gere les transitions d'etat"
    alternatives_considered:
      - "M7 appelle directement FSM.transition()"
    trade_offs: "Necessite coordination par l'orchestrateur (M6) mais evite couplage M7-M1"

10. Dependances¶

11. Points de vigilance¶

1. Watchdog TTL en background iOS — checkDeferredTtl() ne s'executera pas si l'app est tuee par iOS. Mitigation : purgeStale() au prochain lancement detecte et purge les artefacts expires (point 9 du plan).

2. Best-effort purge — Si un fichier est verrouille par un autre processus, la suppression echoue silencieusement. Le registre est quand meme nettoye pour eviter les boucles infinies.

3. Pas de mutex — Les operations registerArtifact / purgeStale ne sont pas protegees par un mutex. En pratique, l'orchestrateur (M6) serialise les appels. Si un usage concurrent est necessaire, ajouter un Map<string, Promise> mutex par captureId (pattern PD-86).