PD-286 / C9 — Livrable agent app-pvproof-assembler-multi¶

Agent : agent-developer (Claude) Module : app-pvproof-assembler-multi Projet : ProbatioVault-app (React Native + Expo SDK 54 + TypeScript) Référence plan : PD-286-plan.md §1.2 C9, §3 (INV-286-08), §5 (TC-NOM-03 / TC-NR-02) Référence contract : PD-286-code-contracts.yaml module app-pvproof-assembler-multi

1. Synthèse¶

Extension de l'assembler .pvproof (PD-85) avec le shape multi-volumes (PD-286) — strictement additif :

• conteneur .pvproof inchangé (forbidden : modification du format) — la classe PvproofAssembler n'a pas changé d'API publique ;
• pvproof.json interne reçoit deux clés additionnelles uniquement sur un export multi-volumes : volumes_count et assembled_from[] ;
• sur un export single-volume legacy (INV-286-05), pvproof.json reste byte-identical à PD-85 (clés volumes_count / assembled_from absentes, pas null) ;
• assembled_from[] est strictement projeté sur {volumeIndex, integrityHash, estimatedBytes} — signedUrl (donnée temporaire) et manifest (taille excessive) sont absents ;
• assertion runtime fail-closed à la sérialisation : assembled_from.length === volumes_count (INV-286-08) + contiguïté + ordre ascendant (INV-286-06).

L'orchestrator (C7) consommera l'API buildPvproofMetadata(...) puis assembler.addPvproofMetadata(metadata) — le pipeline d'assemblage du conteneur (entrées ZIP, finalize, hash) reste identique à PD-85.

2. Fichiers livrés¶

Aucun fichier hors périmètre n'a été modifié. Périmètre contract :

src/export/pvproof-assembler.ts
src/export/__tests__/pvproof-assembler.test.ts

3. Conformité au code contract¶

3.1 Interfaces (contract interfaces)¶

3.2 Invariants (contract invariants)¶

3.3 Forbidden (contract forbidden)¶

3.4 Fichiers (contract files)¶

4. Couverture des critères et tests du plan¶

4.1 Critères d'acceptation couverts¶

4.2 Tests couverts¶

4.3 Tests additionnels (qualité)¶

• Single-volume legacy (3 cas) — returns legacy shape when volumes is omitted, ... when volumes is an empty array, derives exportDate from clock when omitted. Protègent INV-286-05 contre régression future qui ajouterait volumes_count: null.
• Sort déterministe (1 cas) — sorts assembled_from by volumeIndex ascending avec input shuffle [2, 0, 1]. Garantit le déterminisme inter-runtime.
• Forbidden fields (1 cas) — strips signedUrl and manifest from assembled_from entries injecte des clés interdites en entrée et vérifie leur absence en sortie (assertion sur Object.keys).
• Validations strictes (10 cas fail-closed) — cardinalité, hors-plage, négatif, doublon, regex hash (lowercase strict, longueur, charset), bornes estimatedBytes (zéro, non-entier).
• Assertion runtime (4 cas) — assertMultiVolumeMetadataConsistent accepté ; rejette cardinalité ≠ volumes_count, ordre non ascendant, gap dans la séquence.
• Type guard (2 cas) — isMultiVolumeMetadata retourne true / false selon shape.
• Intégration class (4 cas) — addPvproofMetadata accepte legacy, accepte multi cohérent, throw sur multi incohérent, produit un seul fichier en sortie.
• Total — 36/36 tests passent (4 PD-85 préservés + 32 PD-286).

5. Décisions architecturales¶

Format architectural_decisions du code contract — max 1-2 décisions, focalisées sur des choix non triviaux.

architectural_decisions:
  - decision: |
      Externaliser la construction de la métadonnée dans une fonction pure
      `buildPvproofMetadata(input)` plutôt qu'un constructeur de la classe.
    rationale: |
      Le shape multi-volumes nécessite 5 validations indépendantes (cardinalité,
      hors-plage, doublon, regex hash, bornes estimatedBytes) et un tri
      déterministe. Mettre cette logique dans le constructeur de
      `PvproofAssembler` aurait fait grossir la classe (déjà 100 lignes pour
      le streaming ZIP) et empêché les tests unitaires sans instancier le
      pipeline ZIP. La fonction pure rend le code 100% testable sans mock
      `fflate` et permet à l'orchestrator (C7) d'appeler le builder une fois
      au démarrage de la phase ASSEMBLING, séparant clairement validation
      logique et écriture conteneur.
    alternatives_considered:
      - "Constructeur enrichi `new PvproofAssembler({ volumes, totalVolumes })` — rejeté : couple validation à l'instanciation, casse la classe PD-85"
      - "Méthode statique `PvproofAssembler.buildMetadata(...)` — rejeté : n'apporte pas de bénéfice par rapport à une fonction libre, ajoute du couplage"
    trade_offs:
      - "+ Validation testable indépendamment du pipeline ZIP (mock `fflate` non requis)"
      - "+ L'orchestrator peut valider la métadonnée AVANT d'instancier l'assembler"
      - "+ Class `PvproofAssembler` PD-85 préservée à l'identique"
      - "- 1 fonction de plus dans le namespace exporté (mineur)"

  - decision: |
      Double validation : `buildPvproofMetadata` valide à la construction et
      `assertMultiVolumeMetadataConsistent` ré-asserte à la sérialisation
      via `addPvproofMetadata`.
    rationale: |
      Le contract exige une « assertion runtime à la finalisation » (INV-286-08).
      Une métadonnée pourrait être produite hors `buildPvproofMetadata` (test
      qui forge un objet manuellement, refactor futur, sérialisation/désérialisation
      qui passe par JSON). L'assertion à la sérialisation garantit le fail-closed
      même si le builder est by-passé. Coût : O(N) supplémentaire à la
      finalisation, négligeable pour N ≤ ~14 volumes (10 GB / 768 MB).
    alternatives_considered:
      - "Validation unique au build — rejeté : INV-286-08 demande explicitement une assertion à la finalisation"
      - "Validation unique au runtime — rejeté : laisse passer des erreurs build-time qui pourraient être catchées tôt par TypeScript / tests d'orchestrator"
    trade_offs:
      - "+ Dernier rempart fail-closed même en cas de bypass du builder"
      - "+ Cohérent avec l'esprit `defense in depth` du contract"
      - "- Légère duplication entre `buildPvproofMetadata` (validation complète) et `assertMultiVolumeMetadataConsistent` (ré-assertion structurelle uniquement)"
      - "- O(N) à la finalisation, négligeable en pratique"

6. Hypothèses confirmées et points de vigilance¶

6.1 Hypothèses du plan validées¶

• H-PD286-PLAN-04 (compatibilité format .pvproof) : confirmé par préservation de tous les tests pvproof-assembler-class.test.ts (PD-85, 8/8 passent). L'ajout de volumes_count / assembled_from[] dans pvproof.json est purement additif — un consommateur PD-85 strict qui parse pvproof.json ignorera ces clés inconnues (JSON tolère les clés additionnelles). La validation byte-identical par un parser PD-85 réel relève des tests d'intégration C11 (TC-NR-02).

6.2 Points de vigilance pour l'orchestrator (C7)¶

L'orchestrator app DOIT respecter les invariants suivants pour ne pas dégrader la garantie INV-286-08 :

1. Construire la métadonnée AVANT de commencer le pipeline d'écriture — appeler buildPvproofMetadata({...}) une fois après réception de la réponse API multi-volumes. Si le builder throw, transitionner vers state FAILED AVANT toute écriture ZIP. Ne pas attendre finalize() pour découvrir une incohérence.
2. Appeler addPvproofMetadata(metadata) plutôt que addPvproofJson(rawObject) dans la branche multi-volumes. La forme typée garantit l'assertion runtime (INV-286-08).
3. Conserver la branche legacy : sur un export single-volume, l'orchestrator existant (PD-85) appelle addPvproofJson(rawObject) directement. Cette branche reste valide et ne doit PAS être migrée vers addPvproofMetadata (INV-286-05 — pvproof.json byte-identical).
4. Ne JAMAIS muter la métadonnée entre construction et addPvproofMetadata — les types readonly aident, mais le runtime ne l'empêche pas (Object.freeze non appliqué pour ne pas pénaliser le tooling JSON).

6.3 Dette technique laissée en l'état¶

7. Vérification locale¶

Note : npx tsc --noEmit global remonte des erreurs préexistantes dans d'autres modules (src/__tests__/AppNavigator.test.tsx, src/services/biometricKeychain.qwen.test.ts, src/crypto/aes-gcm.ts, etc.). Aucune n'est imputable à C9 — toutes préexistent à mon travail et sortent du périmètre du contract app-pvproof-assembler-multi.

8. Hors périmètre (signalé, non modifié)¶

• Intégration dans l'orchestrator (C7) : remplacement de assembler.addPvproofJson(pvproofMeta) par assembler.addPvproofMetadata(buildPvproofMetadata({...volumes})) dans la branche multi-volumes — responsabilité de l'agent app-export-orchestrator-multi (C7).
• Vérification d'intégrité par volume : volume-verifier.verify() est appelé par C7 AVANT appendVolume/addFileFromDisk ; pas dans le scope de C9.
• Hashing final du .pvproof : hashFileStreaming(outputPath) reste appelé par l'orchestrator post-finalize() (PD-85 inchangé).
• Test E2E .pvproof consommé par parser PD-85 : couvert par C11 (suite tests d'intégration TC-NR-02).
• Bumping pvproof_format_version : conditionnel à TC-NR-02, story de suivi si nécessaire.