PD-286 — Livrable agent-developer : module export-manifest-multi (C3)¶

Story : Export probatoire multi-volumes (PD-286) Module : export-manifest-multi (C3, Wave 2) Project : ProbatioVault-backend Statut : implémenté + testé (41 tests unitaires PASS, 332/332 tests export PASS, 0 régression PD-85)

1. Périmètre couvert¶

Extension de ExportManifestBuilder (PD-85) avec une méthode buildPartial() pour produire un manifest partiel par volume, et création de ManifestRootBuilderService qui calcule le manifestRootHash du manifest racine multi-volumes. Conforme au code contract export-manifest-multi (CC-286-C3) et au plan §1.1 / §2.2 / §3 (mapping INV-286-07 + manifestRootHash).

Fichiers produits (3 fichiers, dans le périmètre autorisé)¶

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

Note d'intégration (handoff C5) : ManifestRootBuilderService n'est PAS encore enregistré dans export.module.ts. C'est de la responsabilité de l'agent C5 (export-controller-multi) qui orchestre l'injection des services C1/C3 dans ExportService, exactement comme ExportPartitionerService (C1) attend aussi son enregistrement par C5.

2. Choix de conception¶

2.1 ExportManifestBuilder.buildPartial() — extension chirurgicale¶

Pourquoi pas un nouveau service ? Le manifest partiel d'un volume est, structurellement, un ManifestDto qui ne contient qu'un sous-ensemble des preuves. Le typage du DTO ExportVolumeDto.manifest (C2) est déjà ManifestDto ; introduire un type différent casserait le contrat C2 sans rien apporter. Le calcul du hash réutilise IntegrityHashComputer (PD-85) — c'est exactement la propriété attendue par INV-286-07 (« réutilise IntegrityHashComputer » dans le code contract).

Refacto interne : extraction de buildManifest(args) privé, partagé par build() (PD-85, single-volume legacy) et buildPartial() (PD-286, multi-volumes). Aucune duplication de logique de canonicalisation ou de hashing — la cohérence cross-runtime backend ↔ app dépend de cette unicité de chemin.

Paramètre exportedAt explicite : la signature build(proofs, exportId, userId, role) (PD-85) reste rétrocompatible — on ajoute un 5e argument optionnel. buildPartial() REQUIERT un exportedAt car tous les volumes d'un même export doivent partager le même timestamp pour que les manifests partiels divergent uniquement par le contenu réel (proofs). Si chaque volume reçoit new Date() indépendamment, les hashes deviennent non reproductibles. Le caller (C5 ExportService) fixe la valeur une seule fois en début de partition.

Contenu du manifest partiel : strictement les mêmes champs que la PD-85 (version, exportId, exportedAt, exportedBy, proofCount, proofs, integrityHash). Les métadonnées de volume (volumeIndex, totalVolumes) sont délibérément absentes — elles vivent au niveau ExportVolumeDto / ManifestRootDto (C2). Cette séparation permet à l'app de recalculer le hash partiel sans connaître l'index du volume, ce qui simplifie la vérification client (C8 volume-verifier) et évite de coupler le hash partiel à la position du volume dans la séquence.

2.2 ManifestRootBuilderService — calcul du manifestRootHash¶

Formule (mapping plan §3, ligne « manifestRootHash ») :

manifestRootHash = SHA3-256(JCS_RFC8785({
  exportId,
  totalVolumes,
  volumes: [{ volumeIndex, integrityHash, estimatedBytes }, ...]
}))

Réutilise la même chaîne JsonCanonicalizeService + createHash('sha3-256') que PD-85 / IntegrityHashComputer. Aucune lib npm tierce (canonicalize, json-canonicalize) — cf. forbidden contract.

Tri par volumeIndex ASC : RFC 8785 trie les CLÉS d'objet mais pas les ÉLÉMENTS d'array. Le service trie donc défensivement le tableau volumes par volumeIndex ASC sur une copie défensive (forbidden : mutation des entrées). Conséquence : l'ordre des volumes en entrée n'a aucune importance — résout le piège review « ordre de tri volumes[] » documenté en plan §9.2.

Validations défensives alignées sur §5.1 spec et INV-286-06 :

Le mapping vers HTTP 5xx (§6.2 plan) reste de la responsabilité du caller C5 — le service domain-level ne dépend pas de NestJS HTTP.

Sortie immutable : Object.freeze sur le résultat et chaque volume référencé. Empêche toute mutation aval (defense in depth contre forbidden « mutation de l'objet manifest reçu »).

Defense in depth post-hash : vérification de la regex /^[0-9a-f]{64}$/ sur le hash retourné par node:crypto avant exposition. Inutile en pratique (Node renvoie toujours du hex lowercase), mais détecte une régression future si la lib changeait son format de sortie.

2.3 Aucun champ manifestRootHash dans son propre input¶

Forbidden « Inclusion du champ integrityHash dans l'input du hash (boucle infinie sémantique) — toujours exclure avant canonicalisation » : appliqué symétriquement au manifestRootHash. L'objet canonicalisé contient exactement {exportId, totalVolumes, volumes: [...]}, jamais manifestRootHash. Le test vector regression (cf. §3.5) le prouve par construction : la valeur de référence est calculée sans ce champ.

3. Couverture des tests¶

41 tests unitaires PASS pour manifest-root-builder.service.spec.ts. Tous les tests export* du backend continuent de passer (332/332).

3.1 Calcul nominal (7 tests)¶

• Single-volume (totalVolumes: 1) → hash hex 64 chars.
• Multi-volume (3 volumes, tailles différentes) → hash valide.
• Déterminisme : même input → même hash (2 appels successifs).
• Indépendance d'ordre : [v2, v0, v1] produit le même hash que [v0, v1, v2], et le résultat sortant est trié ASC.
• Vector regression : recalcule indépendamment SHA3-256(JsonCanonicalizeService.canonicalize({...})) et vérifie l'égalité. Détecte toute dérive future de l'algo (ex : passage à SHA-256, lib JCS différente, oubli d'un champ).
• Anti-collision basique : 3 inputs qui diffèrent par un seul champ produisent 3 hashes distincts.
• Anti-régression algorithme : compare explicitement result.manifestRootHash à sha256 ET sha3_256 du même canonical, prouve qu'on utilise SHA3-256.

3.2 Forbidden — defensive cloning (2 tests)¶

• inputVolumes n'est pas mutée par build() (snapshot avant/après).
• Résultat retourné Object.isFrozen (incluant volumes et chaque référence).

3.3 Validations (32 tests)¶

• exportId : 7 cas invalides (vide, uppercase, v3, mauvaise variant, mauvaise longueur, dashes mal placés, non-UUID).
• totalVolumes : 4 cas invalides (0, -1, fractionnel, NaN).
• volumes cardinalité & continuité (INV-286-06) : 6 cas (length mismatch, index négatif, index ≥ totalVolumes, fractionnel, doublon, trou).
• integrityHash (INV-286-07 case-sensitive) : 7 cas invalides + 1 cas valide.
• estimatedBytes (INV-286-01/02) : 5 cas invalides (0, négatif, fractionnel, NaN, > MAX_TOTAL) + 2 cas bornes valides (1 et MAX_TOTAL_EXPORT_BYTES).

3.4 Mapping aux Test-IDs contractuels¶

Les tests unitaires de C3 ne portent pas de Test-ID contractuel TC-* car le contrat de test PD-286-tests.md couvre explicitement l'orchestration (TC-NOM-04 sur app-side, TC-NOM-05 sur audit, etc.). Les tests unitaires C3 verrouillent les invariants techniques sous-jacents :

4. Conformité aux invariants¶

5. Architectural decisions (code contract YAML)¶

architectural_decisions:
  - decision: "Étendre ExportManifestBuilder (PD-85) avec buildPartial() plutôt que créer un service séparé"
    rationale: "Le manifest partiel est structurellement un ManifestDto avec un sous-ensemble de proofs ; séparer aurait dupliqué la chaîne JCS+SHA3-256 et risqué la divergence cross-runtime backend↔app."
    alternatives_considered:
      - "Service ExportPartialManifestBuilder distinct"
      - "Méthode statique sans service (helper pur)"
    trade_offs:
      - "Avantage : un seul chemin de calcul, garantie de byte-stable identique entre PD-85 legacy et PD-286 partiel"
      - "Inconvénient : la classe ExportManifestBuilder porte deux entrées publiques — accepté car la sémantique reste claire"

  - decision: "exportedAt en paramètre explicite (vs new Date() inline)"
    rationale: "En multi-volumes, tous les manifests partiels doivent partager le même timestamp pour que les hashes ne divergent que par le contenu réel des proofs. Génération inline produirait des timestamps différents par volume."
    alternatives_considered:
      - "Stocker exportedAt en champ de classe (stateful)"
      - "Passer un objet args complet à build()"
    trade_offs:
      - "Avantage : service stateless, déterminisme total, signature explicite"
      - "Inconvénient : caller doit penser à fixer exportedAt en début de partition — documenté dans la JSDoc"

  - decision: "Tri volumes par volumeIndex ASC dans ManifestRootBuilderService.build()"
    rationale: "RFC 8785 ne trie pas les arrays. Sans tri sémantique, deux callers passant des volumes dans un ordre différent obtiendraient des hashes différents — ambiguïté review §9.2 du plan."
    alternatives_considered:
      - "Exiger l'ordre déjà trié et throw si désordonné"
      - "Pas de tri (responsabilité du caller)"
    trade_offs:
      - "Avantage : robuste à l'ordre d'entrée, plus simple côté caller"
      - "Inconvénient : un peu plus de coût CPU (négligeable, N ≤ ~14 volumes max attendus)"

6. Hypothèses techniques retenues¶

7. Vérification PD-85 (non-régression)¶

La signature de ExportManifestBuilder.build(proofs, exportId, userId, role) reste rétrocompatible (paramètre exportedAt ajouté en optionnel à la fin). Aucun appel existant n'est cassé. Le test TC-NR-04 (déterminisme PD-85) continue de passer sans modification.

8. Traçabilité tests / fichiers¶

TC-INV-286-06 (continuité volumeIndex)        → manifest-root-builder.service.spec.ts (validation volumes cardinality & continuity)
TC-INV-286-07 (integrityHash case-sensitive)  → manifest-root-builder.service.spec.ts (validation integrityHash)
INV-286-01/02 (bornes estimatedBytes)         → manifest-root-builder.service.spec.ts (validation estimatedBytes)
SHA3-256 strict (CC forbidden)                → manifest-root-builder.service.spec.ts (uses SHA3-256 not SHA-256)
JCS RFC 8785 (cohérence cross-runtime)        → manifest-root-builder.service.spec.ts (vector regression)
Forbidden — mutation des entrées              → manifest-root-builder.service.spec.ts (forbidden — defensive cloning)

9. Hors périmètre (refusés)¶

• ❌ Modification d'export.module.ts pour enregistrer ManifestRootBuilderService — appartient à C5 (export-controller-multi), comme c'est déjà le cas pour ExportPartitionerService (C1). Documenté en §1 (handoff).
• ❌ Tests pour ExportManifestBuilder.buildPartial() dans un nouveau fichier — non listé dans le périmètre files du code contract (C3). La validation byte-stable du chemin partagé buildManifest() est garantie par le test vector regression côté ManifestRootBuilderService (qui utilise la même chaîne JsonCanonicalizeService + createHash('sha3-256') que IntegrityHashComputer) ET par les tests PD-85 existants qui passent toujours.
• ❌ Suite roundtrip CI backend↔app pour H-PLAN-01 — responsabilité C8 (app-volume-verifier) + C10 (app-export-api-client).

10. Prochain pas¶

L'agent C5 (export-controller-multi) doit, dans ExportService.export() multi-volumes :

1. Fixer un exportedAt = new Date().toISOString() une seule fois, en début de partition.
2. Pour chaque VolumePlanEntry issu de C1 : charger les LegalCompositeProof[] correspondant à proofIds, puis appeler :

const partialManifest = manifestBuilder.buildPartial({
  proofs: volumeProofs,
  exportId,
  userId,
  role,
  exportedAt,
});
// partialManifest.integrityHash = SHA3-256(JCS(manifest_partial \ integrityHash))

1. Construire les VolumeReference[] à partir des VolumePlanEntry + partialManifest.integrityHash, puis :

const root = manifestRootBuilder.build({
  exportId,
  totalVolumes: plan.totalVolumes,
  volumes: plan.volumes.map((v, i) => ({
    volumeIndex: v.volumeIndex,
    integrityHash: partialManifests[i].integrityHash,
    estimatedBytes: v.estimatedBytes,
  })),
});
// root.manifestRootHash → exposé sur ComplaintFileResponseDto.manifestRootHash

1. Enregistrer ManifestRootBuilderService dans export.module.ts providers.
2. Câbler ExportVolumeDto.manifest = partialManifest et ExportVolumeDto.integrityHash = partialManifest.integrityHash (le hash est dupliqué : une fois dans le manifest partiel pour vérification fonctionnelle app, une fois au niveau ExportVolumeDto pour validation contrat — c'est la double-validation expected par INV-286-07).