PD-103 — Agent Developer — Module M6 capture-orchestrator¶

Date : 2026-04-03 Agent : Agent Developer (Claude) Story : PD-103 — Capture probatoire d'écran et scellement automatique Module : M6 capture-orchestrator Spec version : v3

1. Résumé¶

Module M6 implémenté : orchestrateur séquentiel coordonnant les modules M1 (state-machine), M2 (crypto-pipeline), M3 (ocr-service), M4 (upload-service), M5 (useCaptureStore) et M7 (purge-manager).

Le flux complet suit la séquence contractuelle : purgeStale → capture → hash → encrypt → OCR → upload → purge locale

2. Fichiers créés¶

3. Fichiers existants non modifiés¶

Aucun fichier existant n'a été modifié. L'orchestrateur consomme les APIs publiques des modules M1–M5 et M7 sans altération.

4. API publique¶

CaptureOrchestrator¶

class CaptureOrchestrator {
  constructor(deps: CaptureOrchestratorDeps, config?: CaptureOrchestratorConfig)

  // Flux nominal : capture → hash → encrypt → OCR → upload → UPLOADED
  async execute(
    imageBytes: Uint8Array,
    metadata: CaptureMetadata,
    jwtToken: string,
    ocrEnabled?: boolean,
    signal?: AbortSignal,
    onProgress?: (progress: CaptureUploadProgress) => void,
  ): Promise<CaptureOrchestratorResult>

  // Reprise différée : UPLOAD_DEFERRED → UPLOADING → UPLOADED
  async resumeDeferred(
    captureId: CaptureId,
    jwtToken: string,
    signal?: AbortSignal,
    onProgress?: (progress: CaptureUploadProgress) => void,
  ): Promise<CaptureOrchestratorResult>

  // Annulation explicite (CAPTURED ou UPLOADING → CANCELLED)
  async cancel(jwtToken?: string): Promise<CaptureOrchestratorResult | null>

  // Watchdog TTL : expire les captures différées au-delà du TTL
  async expireDeferredCaptures(): Promise<CaptureId[]>
}

CaptureOrchestratorDeps¶

interface CaptureOrchestratorDeps {
  readonly kekProvider: KekProvider;      // M2 — wrapping DEK
  readonly ocrService: OcrService;        // M3 — OCR local
  readonly uploadService?: CaptureUploadService;  // M4 — upload S3 + POST
  readonly purgeManager?: CapturePurgeManager;    // M7 — purge artefacts
}

CaptureOrchestratorConfig¶

interface CaptureOrchestratorConfig {
  readonly apiBaseUrl?: string;    // URL API backend
  readonly maxRetries?: number;    // 0..5, défaut 3
  readonly backoffBaseMs?: number; // 1000..10000, défaut 1000
}

5. Couverture des invariants¶

6. Matrice de couverture tests (TC-* → fichiers)¶

Tests additionnels (NON-CONTRACTUAL)¶

7. Résultats des tests¶

PASS src/__tests__/capture/orchestrator.test.ts
  CaptureOrchestrator
    TC-NOM-01: Flux nominal complet
      ✓ devrait executer le flux capture → hash → encrypt → upload → UPLOADED (3 ms)
      ✓ devrait calculer le hash SHA3-256 localement avant upload (INV-103-03) (1 ms)
    TC-NOM-02: OCR desactive
      ✓ devrait atteindre UPLOADED sans champs OCR
    TC-NOM-03: OCR en erreur
      ✓ devrait continuer sans OCR si extraction echoue (1 ms)
    TC-NOM-04: purgeStale au demarrage
      ✓ devrait appeler purgeStale() avant toute operation
    TC-NOM-05: Upload deferred sur echec reseau
      ✓ devrait transitionner vers UPLOAD_DEFERRED apres epuisement des retries (1 ms)
    TC-NOM-06: Reprise differee
      ✓ devrait reprendre un upload differe avec succes (1 ms)
    TC-NOM-14: Annulation explicite en UPLOADING
      ✓ devrait annuler l'upload et transitionner vers CANCELLED (12 ms)
    TC-NOM-17: Purge locale immediate apres UPLOADED
      ✓ devrait supprimer l'artefact local apres ACK backend (1 ms)
    TC-ERR-01: Retries epuises
      ✓ devrait transitionner vers UPLOAD_DEFERRED apres echec upload (1 ms)
    TC-ERR-02: Annulation utilisateur pre-upload
      ✓ devrait annuler depuis CAPTURED via cancel()
    TC-ERR-05: Image vide provoque erreur hash
      ✓ devrait rejeter avec CANCELLED si image_bytes est vide (1 ms)
    TC-INV-02: Garde CAPTURED → UPLOADING
      ✓ devrait reussir la transition si hash et chiffrement sont valides
    TC-ERR-11: TTL differe expire
      ✓ devrait expirer les captures differees au-dela du TTL
    NON-CONTRACTUAL: cancel sans capture active
      ✓ devrait retourner null si aucune capture active
    NON-CONTRACTUAL: capture_id lowercase (INV-103-31)
      ✓ devrait normaliser capture_id en lowercase
    NON-CONTRACTUAL: reprise capture inexistante
      ✓ devrait retourner CANCELLED si capture differee non trouvee

Test Suites: 1 passed, 1 total
Tests:       17 passed, 17 total

Non-régression¶

Tous les tests existants des modules M1, M3, M5, M7 passent toujours (199 tests au total, 0 échec).

8. Décisions architecturales¶

architectural_decisions:
  - decision: "Injection de dépendances via interface CaptureOrchestratorDeps"
    rationale: "Permet de mocker chaque module (M2, M3, M4, M7) indépendamment pour les tests unitaires, conformément au pattern existant (KekProvider, OcrEngine)."
    alternatives_considered:
      - "Instanciation directe des modules dans le constructeur"
      - "Singleton global"
    trade_offs: "Légère verbosité à l'instanciation, mais testabilité maximale et découplage strict."

  - decision: "Persistance du ciphertext en base64 via expo-file-system"
    rationale: "Hermes ne supporte pas Blob/File natif. Base64 est le seul encodage supporté par FileSystem.writeAsStringAsync. Le ciphertext est déjà chiffré (AES-256-GCM), pas de risque de fuite en clair."
    alternatives_considered:
      - "Stockage binaire via react-native-fs"
      - "Stockage en AsyncStorage (limité en taille)"
    trade_offs: "Overhead base64 (~33% taille) acceptable car le ciphertext est temporaire et purgé après UPLOADED."

9. Hypothèses¶

10. Limites et dette technique¶

1. Base64 dans filesystem — Le stockage du ciphertext en base64 sur le filesystem local introduit un overhead de ~33%. Pour des images > 100 MB, cela pourrait impacter le stockage temporaire. Acceptable car la purge est immédiate post-UPLOADED et le TTL différé est borné à 24h.

2. btoa/atob en Hermes — Les fonctions btoa/atob sont utilisées pour la conversion base64 du ciphertext local. Si le runtime Hermes cible ne les supporte pas, un fallback via bytesToBase64 de src/crypto/utils.ts sera nécessaire.

3. Pas de retry sur la reprise différée — resumeDeferred() tente un seul cycle upload. Si l'upload échoue à nouveau, la capture reste en UPLOAD_DEFERRED. Le watchdog TTL gérera l'expiration. Un mécanisme de retry automatique au niveau de l'app (via AppState ou NetInfo) est la responsabilité de M8 (capture-ui).

4. Annulation best-effort — L'abort S3 (cancelUpload) est best-effort. Si l'appel échoue, les lifecycle rules S3 (M15) et le GC orphelins (M12) nettoieront les objets résiduels.