PD-56 — Plan d'implémentation¶

1. Découpage en composants¶

2bis. Diagramme de dépendances agents¶

graph LR
    subgraph "Wave 1 — Fondations"
        A1[C1: ProofAvailabilityState enum]
        A7[C7: MerkleProofResult DTO]
        A8[C8: MerkleProofException]
        A10[C10: Migration DDL]
        A9[C9: ETA Calculator]
    end

    subgraph "Wave 2 — Services intermédiaires"
        A2[C2: MerkleLeaf extension]
        A4[C4: EventResolver]
        A5[C5: StateMachine]
        A6[C6: ProofAuditService]
    end

    subgraph "Wave 3 — Orchestrateur"
        A3[C3: MerkleProofService]
    end

    subgraph "Wave 4 — Validation"
        A11[C11: Tests]
        A12[C12: Script off-chain]
    end

    A1 --> A2
    A1 --> A5
    A10 --> A2
    A7 --> A3
    A8 --> A3
    A4 --> A3
    A5 --> A3
    A6 --> A3
    A9 --> A3
    A2 --> A3
    A3 --> A11
    A3 --> A12

4 waves d'exécution. Wave 1 : 5 agents en parallèle. Wave 2 : 4 agents (C4/C6 indépendants, C2/C5 dépendent de C1). Wave 3 : 1 agent (intégration). Wave 4 : 2 agents (tests + script off-chain).

2. Flux techniques¶

F-01 — Preuve disponible (available)¶

getMerkleProof(eventId)
  │
  ├─ 1. Valider format eventId (UUID v4 regex) → sinon ERR-56-01
  ├─ 2. EventResolverService.resolve(eventId) → eventHash
  │     └─ Lookup anchor_batch_events.event_id → event_hash (PD-55)
  │     └─ Si introuvable → ERR-56-01
  ├─ 3. MerkleLeaf.findOne({ leafHash: eventHash }) + join MerkleTree
  │     └─ Si leaf introuvable → flux pending (F-02/F-05)
  ├─ 4. Lire proofAvailabilityState
  │     └─ Si CORRUPTED → ERR-56-03 (pas de transition, pas d'alerte)
  ├─ 5. Validation structurelle (merklePath format, bornes §5.1/§5.2)
  │     └─ Si invalide → F-06 (corruption structurelle)
  ├─ 6. Auto-vérification : MerkleProofVerifier.verifyProof(eventHash, merklePath, merkleRoot)
  │     └─ Si mismatch → F-04 (corruption crypto)
  ├─ 7. Vérifier finalized_at IS NOT NULL (via AnchorBatch lié)
  │     └─ Si NULL → flux pending (F-02/F-05)
  ├─ 8. Retourner MerkleProofResult available (AUCUNE écriture — l'état proof_availability est déduit du contexte, pas persisté en nominal)
  └─ 9. Construire MerkleProofResult { status:'available', ... }

F-02 — Preuve en attente (pending)¶

  ... (après étape 3 ou 7, leaf absent ou finalized_at IS NULL)
  │
  ├─ Lookup AnchorBatch candidat (le plus récent contenant eventId — NOTE: le filtre sur batch FAILED est un point ouvert §10.2 Q2, le plan sélectionne tout batch contenant l'eventId sans filtrage de statut)
  ├─ Si window_end IS NOT NULL → estimatedAvailableAt = window_end (UTC Z)
  │   └─ Retour { status:'pending', estimatedAvailableAt }
  └─ Si window_end IS NULL → ERR-56-05

F-04 — Mismatch cryptographique¶

  ... (étape 6 : computedRoot != merkleRoot)
  │
  ├─ ProofAvailabilityStateMachine.transitionTo(CORRUPTED, eventHash)
  │   └─ UPDATE merkle_leaves SET proof_availability_state = 'CORRUPTED'
  │      WHERE leaf_hash = :eventHash AND proof_availability_state != 'CORRUPTED'
  │   └─ Si rows affected > 0 → première détection
  ├─ Si première détection → MerkleProofAuditService.emitSecurityAlert(eventId, 'ERR-56-04')
  └─ Retourner ERR-56-04

F-06 — Corruption structurelle¶

  ... (étape 5 : structure invalide)
  │
  ├─ Même logique que F-04 mais code ERR-56-03
  └─ ProofAvailabilityStateMachine.transitionTo(CORRUPTED) + alerte si première détection

Diagramme de séquence enrichi¶

sequenceDiagram
    participant PES as ProofEnvelopeService
    participant MPS as MerkleProofService
    participant ERS as EventResolverService
    participant DB_ABE as vault_blockchain.anchor_batch_events
    participant DB_ML as vault_merkle.merkle_leaves
    participant DB_MT as vault_merkle.merkle_trees
    participant DB_AB as vault_blockchain.anchor_batches
    participant MPV as MerkleProofVerifier
    participant SM as ProofAvailabilityStateMachine
    participant AUD as MerkleProofAuditService

    PES->>MPS: getMerkleProof(eventId: UUID)
    MPS->>MPS: validateEventIdFormat(eventId)
    alt eventId invalide
        MPS-->>PES: ERR-56-01
    end

    MPS->>ERS: resolve(eventId)
    ERS->>DB_ABE: SELECT event_hash FROM anchor_batch_events WHERE event_id = $1
    alt inexistant
        DB_ABE-->>ERS: null
        ERS-->>MPS: null
        MPS-->>PES: ERR-56-01
    else trouvé
        DB_ABE-->>ERS: eventHash
        ERS-->>MPS: eventHash
    end

    MPS->>DB_ML: SELECT * FROM merkle_leaves WHERE leaf_hash = $1
    alt leaf introuvable
        MPS->>DB_AB: SELECT window_end FROM anchor_batches JOIN anchor_batch_events ON ... WHERE event_id = $1
        alt window_end IS NULL
            MPS-->>PES: ERR-56-05
        else window_end calculable
            MPS-->>PES: {status:'pending', estimatedAvailableAt}
        end
    else leaf trouvé
        DB_ML-->>MPS: {leafHash, leafIndex, inclusionProof, proofAvailabilityState, treeId}
        alt state = CORRUPTED
            MPS-->>PES: ERR-56-03 (sans alerte)
        end

        MPS->>DB_MT: SELECT merkle_root, leaf_count FROM merkle_trees WHERE tree_id = $1
        DB_MT-->>MPS: {merkleRoot, leafCount}

        MPS->>MPS: validateStructure(inclusionProof, leafCount)
        alt structure invalide
            MPS->>SM: transitionTo(CORRUPTED)
            SM->>DB_ML: UPDATE proof_availability_state = 'CORRUPTED'
            SM-->>MPS: {firstDetection: true}
            MPS->>AUD: emitSecurityAlert(CRITICAL, ERR-56-03)
            MPS-->>PES: ERR-56-03
        end

        MPS->>MPV: verifyProof(eventHash, inclusionProof, merkleRoot, 'SHA-256')
        MPV-->>MPS: {valid, computedRoot}

        alt computedRoot != merkleRoot
            MPS->>SM: transitionTo(CORRUPTED)
            SM-->>MPS: {firstDetection: true/false}
            opt firstDetection
                MPS->>AUD: emitSecurityAlert(CRITICAL, ERR-56-04)
            end
            MPS-->>PES: ERR-56-04
        end

        MPS->>DB_AB: SELECT finalized_at, window_end FROM anchor_batches WHERE tree_id = $1
        alt finalized_at IS NULL
            alt window_end IS NULL
                MPS-->>PES: ERR-56-05
            else
                MPS-->>PES: {status:'pending', estimatedAvailableAt: window_end}
            end
        else finalized_at IS NOT NULL
            Note over MPS: Pas d'écriture — état déduit, non persisté en nominal
            MPS-->>PES: {status:'available', eventHash, merkleRoot, merklePath, treeId, treeSize, leafIndex, hashAlgorithm:'SHA-256', hashAlgorithmVersion:'1.0'}
        end
    end

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Propagation : toutes les exceptions sont des MerkleProofException (extends Error) avec un code contractuel. Pas de catch silencieux (cf. anti-catch-absorb). L'appelant (ProofEnvelopeService) reçoit l'exception telle quelle.

7. Impacts sécurité¶

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

1. Résolution eventId → eventHash (critique) : l'entity AnchorBatchEvent (PD-55) expose eventId (UUID) mais pas de colonne eventHash visible. Si la colonne n'existe pas, la résolution passera par une jointure vers la table source métier de l'événement probatoire. À valider en Go/No-Go avant implémentation.

2. Convention de tri dans computeRootFromProof() : le code PD-237 mentionne sorted(a,b) dans un commentaire mais aussi un mécanisme basé sur l'index de feuille. Vérifier la cohérence exacte avec la spec PD-56 §5.3 (tri lexicographique pur hashPair(sorted(a,b))).

3. Migration DDL : utiliser varchar avec CHECK constraint plutôt qu'un type ENUM PostgreSQL natif, conformément au REX PD-282. Séquence migration : (1) ALTER TABLE ADD COLUMN proof_availability_state VARCHAR DEFAULT 'PENDING' (2) commitTransaction() (3) CREATE INDEX (4) ALTER TABLE ADD CONSTRAINT CHECK. La migration DOIT appeler commitTransaction() AVANT toute clause WHERE utilisant la nouvelle valeur (REX PD-282, PD-279). Default 'PENDING' est non-volatile → pas de table rewrite (PostgreSQL 11+).

4. Anti-flood multi-instance : Conformément à INV-56-09, SECURITY_ALERT DOIT être émis une seule fois par eventId. Utiliser SELECT ... FOR UPDATE dans une transaction pour garantir l'unicité même en multi-instance. Pattern : BEGIN → SELECT leaf FOR UPDATE → CHECK state != 'CORRUPTED' → UPDATE state = 'CORRUPTED' → EMIT SECURITY_ALERT → COMMIT. Si state = 'CORRUPTED' déjà, retourner ERR-56-03 SANS alerte.

5. Performance P95 ≤ 10 ms : le flux nominal nécessite 2-3 queries SQL séquentielles (event lookup, leaf lookup, tree/batch lookup). Avec les index existants (idx_merkle_leaves_hash, idx_anchor_batch_event_event_id), c'est réaliste. Optimisation possible : jointure unique leaf+tree en une query.

6. proofAvailabilityState initial : la migration met default 'PENDING' sur les leaves existantes. C'est correct car les leaves existantes n'ont pas encore été vérifiées par PD-56. La première invocation de getMerkleProof() déterminera l'état réel.

7. Cas treeSize=1 avec merklePath=[] : cas valide contractuel (§5.1). Le MerkleProofVerifier.verifyProof() avec proof=[] doit retourner valid: true si leaf == root. À vérifier dans l'implémentation existante.

9bis. Contraintes techniques¶

Dépendances inter-PD¶

10. Hors périmètre¶

• Exposition REST endpoint (pas de route HTTP — service interne uniquement).
• Construction d'arbre Merkle (PD-54).
• Ancrage blockchain (PD-55).
• Persistance Merkle structurelle initiale (PD-237) — PD-56 consomme et met à jour l'état uniquement.
• Mécanismes de transport d'observabilité (outbox, bus, retry).
• Auto-résolution de CORRUPTED (résolution manuelle uniquement).
• Rate-limiting (pas d'endpoint REST).
• Intégration ProofEnvelopeService (consommateur PD-56, pas producteur).

11. Mécanismes cross-module¶

Aucune modification d'autres modules. PD-56 est un service interne consommé par ProofEnvelopeService. Il lit les données de : - vault_merkle.merkle_leaves et vault_merkle.merkle_trees (PD-237) — lecture + mise à jour proof_availability_state - vault_blockchain.anchor_batch_events et vault_blockchain.anchor_batches (PD-55) — lecture seule

Pas de guard cross-route, pas de middleware, pas d'intercepteur sur d'autres modules.

12. Périmètre de test¶

Tous les niveaux de test sont couverts, avec réserve sur l'opposabilité perf (benchmark officiel).