PD-286 — Livrable agent agent-developer-app-export-api-client¶

Story : PD-286 (Export probatoire multi-volumes) Module : app-export-api-client (projet ProbatioVault-app) Agent : agent-developer (B — Claude) Wave : 2 (Backend services / parallèle, dépend uniquement du contrat) Date : 2026-04-25

1. Synthèse exécutive¶

Implémentation de l'extension ExportApiClient côté ProbatioVault-app pour supporter le second contrat de réponse multi-volumes (PD-286) tout en préservant la rétrocompatibilité du contrat single-volume legacy (PD-283 / INV-286-05).

Le module est la frontière API côté app : il valide strictement le payload reçu via Zod avant tout téléchargement de volume. La validation Zod est la seule source de vérité pour la conformité du contrat (aucune validation manuelle ad hoc).

2. Périmètre livré¶

Aucun fichier hors périmètre du contrat n'a été modifié. Les fichiers src/export/types.ts, orchestrator.ts, pvproof-assembler.ts, etc., sont intacts (la migration de l'orchestrateur vers callExportApiV2 est la responsabilité de l'agent C7 app-export-orchestrator-multi).

3. Conformité au code contract¶

3.1 Interfaces livrées¶

3.2 Invariants — couverture¶

3.3 Interdictions — respect¶

4. Décisions architecturales¶

Décision 1 — Coexistence legacy + V2 (additive, pas de refactor)¶

• Décision : ajouter callExportApiV2 plutôt que muter callExportApi.
• Rationale : la fonction legacy callExportApi (PD-283) reste utilisée par les tests d'intégration et l'orchestrateur actuel. Une mutation aurait nécessité de changer la signature de retour, cassant tous les consommateurs en cascade. La voie additive permet à l'agent C7 (orchestrator) de migrer indépendamment et donne une période de cohabitation pour les tests d'intégration.
• Alternatives considérées :
• Refactor callExportApi en wrapper de V2 : risque de régression sur les tests PD-283, gain marginal.
• Discriminated union z.union([…]) : Zod renvoie alors le message d'erreur du dernier schéma essayé, ce qui masque la cause réelle (ex : un défaut de continuité volumeIndex afficherait manifest required). Inacceptable pour le mapping d'erreur précis demandé par la spec §6.
• Trade-offs : duplication ~30 lignes du flux HTTP entre callExportApi et callExportApiV2. Volontairement accepté pour préserver la stabilité du contrat legacy. Le facteur commun pourra être extrait quand l'orchestrateur aura migré.

Décision 2 — Branded types via z.brand au lieu d'un type alias nu¶

• Décision : volumeIndex et totalVolumes sont des branded numbers (number & {__brand: "VolumeIndex"}).
• Rationale : cf. learning 2026-03-04 sur les UUID. Les deux valeurs sont des entiers sémantiquement distincts (un index ∈ [0, N-1] vs un total ≥ 1). Sans branding, TypeScript n'empêche pas un appelant d'inverser les paramètres f(volumeIndex, totalVolumes). Le branding force as VolumeIndex au site d'appel et évite la classe d'erreurs "j'ai swappé deux paramètres".
• Alternatives considérées :
• Type alias type VolumeIndex = number : aucune protection à la compilation, équivalent à string en termes de risque.
• Wrapper class class VolumeIndex { value: number } : surcoût runtime, casse la sérialisation JSON directe.
• Trade-offs : cast explicite requis dans le superRefine (v.volumeIndex as unknown as number) pour les comparaisons numériques. Acceptable et localisé dans le schéma lui-même.

5. Mapping tests → invariants / critères¶

Synthèse couverture :

• 14 tests legacy (PD-283) — non-régression : 14/14 PASS
• 37 tests nouveaux (PD-286) — multi-volumes : 37/37 PASS
• Total fichier : 51/51 PASS (jest)
• Test suite schemas-validation.test.ts (PD-283) : 19/19 PASS (non-régression)

6. Mapping erreurs¶

callExportApiV2 mappe les défauts de contrat Zod vers ExportError :

Note d'agent — pour C7/C8 : si une distinction sémantique fine est requise (par ex. séparer INVALID_VOLUME_CONTINUITY de ARTIFACT_CORRUPT dans la télémétrie), un code d'erreur supplémentaire devra être ajouté à ExportErrorCode dans src/export/types.ts. Ce fichier est hors périmètre de cet agent ; je signale le besoin sans l'implémenter.

7. Vérifications effectuées¶

Le repo a des erreurs TypeScript préexistantes dans des modules sans rapport (auth, biometric, navigation, hooks). Aucune n'est liée à PD-286 ni à src/export/. Conformément à l'Art. VI, je signale ce gap mais le périmètre agent est strictement limité aux fichiers du contract.

8. Hypothèses & limites¶

9. Points laissés à C7 (orchestrator) et C8 (verifier)¶

10. Annexe — diff résumé¶

src/export/schemas.ts                     |  +152 (constantes + 9 schémas + 2 types branded + 1 type union + 1 fonction discriminante)
src/export/api-client.ts                  |  +127 (1 type union + 2 fonctions privées + 1 fonction publique callExportApiV2)
src/export/__tests__/api-client.test.ts   |  +259 (37 nouveaux cas, 5 describe blocks PD-286)

Aucun export public legacy n'a été supprimé ou renommé. Le module est strictement additif vis-à-vis de PD-283.